git:20260902.12bea5f to git:20260911.1c2f8a7

58 added, 226 removed. Audit A to A.

- # Agent Artifacts System

- This document describes the automated actors and artifact management system in the `.agents/` directory.

- ## Overview

- The `.agents/` directory is the central repository for all agent-generated artifacts, session management, and governance documentation. It serves as the persistent knowledge base across agent sessions.

- ## Architecture

- ```mermaid

- flowchart TD

- subgraph Sessions["Session Management"]

- SL[sessions/]

- end

- subgraph Artifacts["Agent Outputs"]

- AN[analysis/]

- AR[architecture/]

- PL[planning/]

- CR[critique/]

- QA[qa/]

- RT[retrospective/]

- RM[roadmap/]

- SC[security/]

- end

- subgraph Governance["System Governance"]

- GV[governance/]

- SK[skills/]

- ST[steering/]

- SS[specs/]

- end

- subgraph Utilities["Support"]

- UT[utilities/]

- MT[metrics/]

- end

- Sessions --> Artifacts

- Governance --> Artifacts

- Artifacts --> Utilities

- style Sessions fill:#e1f5fe

- style Artifacts fill:#fff3e0

- style Governance fill:#e8f5e9

- style Utilities fill:#fce4ec

- ```

- ## Directory Catalog

- ### Session Management

- | Directory/File | Purpose | Automated Actor |

- |----------------|---------|-----------------|

- | `sessions/` | Historical JSON logs (creation discontinued) and per-issue handoffs | Per-issue handoffs: all agents |

- | `AGENT-SYSTEM.md` | System documentation | Architect/Orchestrator |

- ### Agent Output Directories

- | Directory | Primary Agent | Output Types |

- |-----------|---------------|--------------|

- | `analysis/` | analyst | Research findings, CVAs, impact assessments |

- | `architecture/` | architect | ADRs only (no review documents) |

- | `planning/` | milestone-planner | PRDs, milestones, task breakdowns |

- | `critique/` | critic | Plan reviews, ADR reviews, approval/rejection |

- | `qa/` | qa | Test strategies, test reports |

- | `retrospective/` | retrospective | Session retrospectives, skill extractions |

- | `roadmap/` | roadmap | Epics, prioritization, product roadmap |

- | `security/` | security | Threat models, security reviews |

- ### Governance

- | Directory | Purpose |

- |-----------|---------|

- | `governance/` | Naming conventions, consistency protocols |

- | `specs/` | EARS requirements, design docs, task specs |

- | `steering/` | Context-aware guidance files |

- | `skills/` | Learned skills and strategies |

- ---

- ## Automated Actors

- ### Session Log Validator

- **Role**: Validates a session log when one is staged; creation is discontinued

- (`.claude/rules/session-logs.md` MUST 1)

- | Attribute | Value |

- |-----------|-------|

- | **Script** | `scripts/validate_session_json.py`, wrapped by the `session-policy` pre-commit hook (`scripts/validation/git_hook_policy.py session`) |

- | **Trigger** | `session-policy` pre-commit hook (validate-if-present), manual |

- | **Input** | Staged session log, if any |

- | **Output** | Compliance report |

- **Validations** (run only when a session log is staged):

- | Check | Behavior | Description |

- |-------|----------|-------------|

- | No log staged | Pass | Gate returns 0 (`check_sessions` passes with no session paths) |

- | Schema valid | Blocks commit | A malformed staged log fails `session-policy` |

- | `endingCommit` reachable | Warns | Unreachable recorded SHA warns; it does not block |

- ---

- ### Consistency Validator

- **Role**: Cross-document consistency enforcement

- | Attribute | Value |

- |-----------|-------|

- | **Script** | `scripts/Validate-Consistency.ps1` |

- | **Trigger** | CI, manual |

- | **Input** | `.agents/` artifacts |

- | **Output** | Consistency report |

- **Validations**:

+ # .agents/

- - Naming convention compliance

- - Cross-reference integrity

- - Requirement coverage

+ Agent governance, planning, and history for the `rjmurillo/ai-agents` repository. Consumed by contributors, CI validators, and skills (`retrospective`, `memory`); never shipped to a plugin consumer.

- ---

+ ## Matters

- ### Planning Artifacts Validator

+ - Not a plugin root. Nothing under here reaches an installed `.claude/`, `src/claude/`, or `src/copilot-cli/` consumer.

+ - Most subtrees are history or write-only; read one only when the task names it (see Skip).

+ - `governance/PROJECT-CONSTRAINTS.md` is the index of record; read it before acting on anything governance-shaped.

+ - ADR `status` in YAML frontmatter is truth; `architecture/README.md` is generated from it, never hand-edited.

+ - Session log creation is discontinued; do not create a new `.agents/sessions/*.json` file.

+ - Markdownlint ignores `.agents/**` (`.markdownlint-cli2.yaml`), but the dash ban and `governance/DOCUMENTATION-LINK-REQUIREMENTS.md` (relative links, not bare paths) still bind.

+ - Rules that fire here by `paths:` scope: `session-logs.md`, `token-economy.md` (`.agents/**`), `governance.md` (`governance/**`), `retros.md` (`retrospective/**`), `secret-redaction.md` (`sessions/**`, `retrospective/**`), `tool-use-hook-bar.md` (`architecture/**`), `security.md`/`testing.md` (`security/**`, `security/benchmarks/**`).

- **Role**: Planning document consistency checker

+ ## Entry points

- | Attribute | Value |

- |-----------|-------|

- | **Script** | `build/scripts/Validate-PlanningArtifacts.ps1` |

- | **Trigger** | CI on `.agents/planning/**` |

- | **Input** | PRDs, task breakdowns |

- | **Output** | Validation report |

+ - `governance/PROJECT-CONSTRAINTS.md`: read at session start (root `AGENTS.md` Gates).

+ - `sessions/handoffs/<date>-<issue>-handoff.md`: read the latest at start, update at end.

+ - `architecture/ADR-NNN-*.md` (108 tracked): check `status` before citing a decision as active.

+ - `memory/episodes/*.json` (750 tracked): auto-extracted; read through the `memory` skill, never hand-edit.

- **Checks**:

+ ## Where to look

- - Effort estimate divergence

- - Orphan specialist conditions

- - Missing task coverage

+ | Path | Why |

+ |---|---|

+ | `governance/*.md` | Constraints, testing rigor, generator files, CI feedback subloop, naming; every normative line needs an evidence anchor |

+ | `architecture/ADR-NNN-*.md` (108) | Decision records; YAML `status` is truth, `README.md` is generated |

+ | `sessions/handoffs/` | Per-issue continuity: read latest at start, update at end |

+ | `specs/` | EARS requirements: `REQ-NNN`, `TASK-NNN`, `DESIGN-NNN`; `check_spec_id_uniqueness.py` and `traceability.py` gate it |

+ | `steering/claude-skills.md` | Skill schema authority |

+ | `memory/episodes/` (750) | Auto-extracted by pre-commit `extract-episodes`; never hand-edit |

+ | `security/` | Threat models (`TM-NNN`), reviews; `benchmarks/` is a test location, not docs |

+ | `schemas/` | JSON schemas: session-log, skill-output, pr-quality-gate-output, workflow, policy, evidence-entry |

+ | `hooks/` | Retired Phase 1 hook inventory; see Dangerous assumptions before trusting it |

- ---

+ ## Skip

- ## Data Flow

+ - `sessions/*.json`: session log creation discontinued; validate-if-present only.

+ - `archive/`: closed history; `retrospective/` writes go through the `retro`/`retrospective` skill only.

+ - `critique/`, `analysis/`, `qa/`, `planning/`, `plans/`, `projects/`, `audits/`, `audit/`, `checkpoints/`, `eval-results/`, `metrics/`, `pr-checks/`, `pr-consolidation/`, `incidents/`, `devops/`, `debt/`, `decisions/`, `benchmarks/`, `roadmap/`, `handoffs/`: write-only or historical; stale-script-ref and doc-interpreter gates exclude these roots, so treat contents as evidence, not instructions.

+ - `prototypes/`: A/B compression candidates (issue #1738), not the active agents in `.claude/agents/`.

+ - `.hook-state/`: gitignored runtime log directory, not tracked.

+ - `pr-batch-review-session-2025-12-20.md`: stray root file, historical.

- ```mermaid

- sequenceDiagram

- participant Agent

- participant Session as sessions/

- participant Output as artifacts/*

- participant Validation as Validators

+ ## Constraints

- Agent->>Session: Read latest per-issue handoff (session start)

- Agent->>Output: Write artifacts (analysis, plans, etc.)

- Agent->>Session: Update per-issue handoff (session end)

+ - Any `ADR-*.md` edit fires the `adr-review` skill (root `AGENTS.md`).

+ - `governance/**` changes need human approval, an ADR for a new rule or policy reversal, and consensus for cross-role rules (`governance.md`); no single agent may alter rules governing another unilaterally.

+ - Never amend a commit that already carries a recorded `endingCommit`; commit the SHA in a follow-up commit instead (`session-logs.md` MUST-2), and re-point it after any rebase (MUST-3).

+ - `validate-planning-artifacts.yml` fires on `planning/**`: estimate divergence, orphan conditions, task coverage.

+ - `sessions/**` and `retrospective/**` content must be secret-redacted before it is written (`secret-redaction.md`).

+ - Worktree Serena writes: behavior and the binding rule live in `.claude/rules/universal.md` MUST NOT 10; not restated here.

- Validation->>Session: Validate protocol compliance

- Validation->>Output: Validate consistency

- Validation-->>Agent: Compliance report

- ```

+ ## Dangerous assumptions

- ## Artifact Naming Conventions

+ - `hooks/hooks.yaml` looks like the live hook manifest. Its own `hooks/README.md` says otherwise: "a retired inventory. No generator or runtime reads it." The real sources of truth are `.claude/settings.json`, `.claude/hooks/`, and `templates/platforms/copilot-cli.yaml`.

+ - `governance/naming-conventions.md` documents a lowercase `prd-name.md` PRD pattern under `.agents/planning/`. Tracked PRDs mostly use `PRD-Name.md` (uppercase) under `specs/`, `plans/`, or `archive/planning/`; go by the tracked files, not the doc alone.

+ - `naming-conventions.md` defines no `TASK-EPIC-NNN-MM` pattern; the only other tracked occurrence is `.agents/archive/phase3-complete-handoff.md`, a retired PowerShell validator's pattern list. Live tasks are `TASK-NNN-<kebab-name>.md` under `specs/tasks/`.

- Source: `governance/naming-conventions.md`

+ ## Dependencies

- | Artifact Type | Pattern | Example |

- |---------------|---------|---------|

- | Session Log | `YYYY-MM-DD-session-NN-description.json` | `2025-12-18-session-24-docs.json` |

- | ADR | `ADR-NNN-kebab-title.md` | `ADR-001-database-selection.md` |

- | PRD | `PRD-feature-name.md` | `PRD-oauth-integration.md` |

- | Plan | `NNN-feature-plan.md` | `001-authentication-plan.md` |

- | Analysis | `NNN-topic-analysis.md` | `001-copilot-cli-analysis.md` |

- | Critique | `NNN-feature-critique.md` | `001-auth-plan-critique.md` |

- | Test Report | `NNN-feature-test-report.md` | `001-auth-test-report.md` |

- | Retrospective | `YYYY-MM-DD-topic.md` | `2025-12-18-session-failures.md` |

- | Threat Model | `TM-NNN-component.md` | `TM-001-auth-flow.md` |

- | Requirement | `REQ-NNN-title.md` | `REQ-001-user-login.md` |

- | Task | `TASK-EPIC-NNN-MM` | `TASK-001-03` |

+ - Feeds the `retrospective` skill, memory extraction, and the PreCompact hook, which all read existing session logs under `sessions/`.

+ - `architecture/README.md` is generated by `build/scripts/generate_adr_index.py` (via `build/scripts/build_all.py`); a hand-edit is overwritten on next regen.

+ - `governance/*.md` changes should cross-link from root `AGENTS.md`/`CLAUDE.md` when they change agent defaults (`governance.md` SHOULD-2).

- ## Traceability Chain

+ ## Architecture

- ```mermaid

- flowchart TD

- REQ[requirements/*.md<br>EARS format]

- DES[specs/design/*.md<br>Architecture]

- TSK[specs/tasks/*.md<br>Atomic tasks]

- IMP[Implementation]

+ - Two "hooks" trees exist and are unrelated: `.agents/hooks/` is a retired Phase 1 inventory; `.claude/hooks/` holds the canonical scripts Claude Code actually runs. Do not edit registrations in the former.

+ - `.agents/skills/` (steering learnings), `.agents/skillbook/` (policies/tensions/workflows JSON), and `.claude/skills/` (the actual skill catalog) are three distinct trees; don't conflate them.

- REQ -->|traces to| DES

- DES -->|traces to| TSK

- TSK -->|implemented by| IMP

+ ## Commands

- style REQ fill:#e1f5fe

- style DES fill:#fff3e0

- style TSK fill:#e8f5e9

- style IMP fill:#fce4ec

+ ```bash

+ uv run python scripts/validation/pre_pr.py

+ uv run python scripts/validation/check_adr_links.py

+ uv run python scripts/validation/check_spec_id_uniqueness.py

+ uv run python scripts/validate_session_json.py <path-to-log>

```

- ## Memory Integration

- Source: `skill-usage-mandatory` memory

- **Knowledge Sources**:

- | Source | Location | Purpose |

- |--------|----------|---------|

- | Serena memories | `.serena/memories/` | Technical patterns, skills |

- | Session logs (historical only) | `.agents/sessions/*.json` | Past decision history; creation discontinued |

- | Per-issue handoffs | `.agents/sessions/handoffs/` | Active cross-session continuity |

- | Skills | `.agents/skills/` | Learned strategies |

- **Agent Memory Protocol**:

- 1. Session start: Read the latest per-issue handoff, query Serena memories

- 2. During work: Reference prior decisions

- 3. Session end: Update the per-issue handoff, store learnings

- ## Security Considerations

- | Control | Description |

- |---------|-------------|

- | Path validation | Artifacts validated to stay within `.agents/` |

- | No credentials | No secrets stored in artifacts |

- | Review required | All artifact changes go through PR review |

- ## Error Handling

- | Scenario | Behavior |

- |----------|----------|

- | Missing session log | No error; session log creation is discontinued |

- | Naming convention violation | Consistency check fails |

- | Orphan artifact | Logged for manual review |

- ## Monitoring

- | Check | Workflow | Trigger |

- |-------|----------|---------|

- | Planning consistency | `validate-planning-artifacts.yml` | PR to `.agents/planning/**` |

- | Spec validation | `ai-spec-validation.yml` | PR to `.agents/specs/**` |

- ## Related Documentation

- - [AGENT-SYSTEM.md](AGENT-SYSTEM.md) - Full system documentation

- - [governance/naming-conventions.md](governance/naming-conventions.md) - Naming rules

- - [Root AGENTS.md](../AGENTS.md) - Agent usage instructions