feat: artifact update & audit — advisory revise + staleness/audit layer

CLAUDE.md

@@ -6,7 +6,7 @@ A Claude Code plugin that orchestrates the full SDLC lifecycle using company-con
 ## Architecture
 - `plugin.json` — Plugin manifest (entry point for Claude Code)
 - `SKILL.md` — Main skill definition (loaded when plugin activates)
-- `commands/` — 21 slash commands (`/sdlc`, `/sdlc-setup`, `/sdlc-status`, `/sdlc-next`, `/sdlc-gate`, `/sdlc-enhance`, `/sdlc-coach`, `/sdlc-review`, `/sdlc-intake`, `/sdlc-brief`, `/sdlc-spec`, `/sdlc-phase-report`, `/sdlc-audit`, `/sdlc-feature`, `/sdlc-experience`, `/sdlc-data`, `/sdlc-rules`, `/sdlc-channel`, `/sdlc-evals`, `/sdlc-harness`, `/sdlc-upgrade`)
+- `commands/` — 23 slash commands (`/sdlc`, `/sdlc-setup`, `/sdlc-status`, `/sdlc-next`, `/sdlc-gate`, `/sdlc-enhance`, `/sdlc-coach`, `/sdlc-review`, `/sdlc-intake`, `/sdlc-brief`, `/sdlc-spec`, `/sdlc-phase-report`, `/sdlc-audit`, `/sdlc-feature`, `/sdlc-experience`, `/sdlc-data`, `/sdlc-rules`, `/sdlc-channel`, `/sdlc-evals`, `/sdlc-harness`, `/sdlc-upgrade`, `/sdlc-revise`, `/sdlc-audit-artifacts`)
 - `agents/` — 13 agents (orchestrator, requirements-analyst, compliance-checker, section-evaluator, narrative-enhancer, gate-repair, multi-reviewer, discovery-analyst, feature-architect, visual-designer, conversation-designer, data-analyst, bizreq-analyst)
 - `channels/` — Cross-profile channel descriptor library (`_schema.yaml`, `ag-ui.yaml`, `voice.yaml`, `chat.yaml`) — the delivery-surface vocabulary the channel layer reads
 - `profiles/` — Company/stack YAML configs with compliance gates
@@ -59,6 +59,7 @@ When adding a new agent or command, document both modes in its file. `discovery-
 - **Finding memory & disposition tracking (Context Repair, Increment A)** — `/sdlc-review` now writes a machine-readable `## Gate Results` block (id/category/severity/target/disposition/detail) that `record_findings.py` parses into an append-only ledger `.sdlc/metrics/findings-log.jsonl`, so a finding survives the report being overwritten and its disposition is tracked across rounds. `findings_model.py` is the single source of truth for the severity↔gate mapping and the disposition state machine (FIXED/SPLIT/ACCEPTED_RISK/POSTPONED/OPEN) with honest counting — a mislabeled disposition (SPLIT without id+owner, an AI signing ACCEPTED_RISK) still counts as debt. The review stays **advisory** (the grader advises, never blocks); only the **FIXED-claim check** may block (`report --strict` exits 2) — a finding marked FIXED whose target file never changed is a factual false claim, not a judgment. The ledger is what later makes a recurring finding promotable into a permanent check (Phase C: "findings become new checks"). Runs standalone (`--repo`) or in-workflow (`--state`). See `docs/proposals/context-repair-loop.md`
 - **Multi-discipline channel layer** — an additive layer giving Data, Design, and Bizreq first-class seats and organizing a feature around its **customer channel of use**. `channels/` holds schema-guarded YAML descriptors (`ag-ui`, `voice`, `chat`) whose acceptance dimensions ride a spec's *existing* `## Acceptance Checks`; `validate_channel.py` guards the library and `check_channel.py` is an advisory (exit 0) DoR lint that never changes a ready/not-ready verdict. Six commands (`/sdlc-feature`, `/sdlc-experience`, `/sdlc-data`, `/sdlc-rules`, `/sdlc-channel`, `/sdlc-evals`, `/sdlc-harness`, `/sdlc-upgrade`) drive five interview-driven discipline agents (`feature-architect`, `visual-designer`, `conversation-designer`, `data-analyst`, `bizreq-analyst`) that also serve as `/sdlc-review` council lenses (7 viewpoints). A spec's optional `channel:` frontmatter field binds the surface; a phase-spanning `.sdlc/decision-log.md` (owner + 2-business-day clock, surfaced in `/sdlc-status` via `track_decisions.py`) and optional discipline sign-offs on the state sign-off record round it out. The protected core (`check_spec.py`, `check_gates.py`, `section-evaluator`, `harness/**`, `phase_model.py`, `phase-registry.yaml`, `/sdlc-coach`, `/sdlc-spec`) is byte-for-byte unchanged. See `references/channel-model.md` and `references/team-model.md`
 - **Close handoff-report generation** — Phase C Step 4 ("Hand over the record") is a two-pass draft: `generate_handoff_report.py` does the deterministic assembly first — phase report index, per-phase gate/sign-off table (from `state.yaml`), metrics history (reusing `scorecard.py`), spec backlog (reusing `track_specs.py`) — filling the existing `final-handoff-report.md` template and marking the judgment sections (outcomes vs the Phase 0 statement, debt log, open items, dashboard handover) with `[Fill: ...]` slots for the Explore agent to enrich. Honest by design (missing data reads "no data", never a fabricated zero) and refuses to clobber a human-edited report without `--force`. Runs standalone (`--repo`) or in-workflow (`--state`)
+- **Artifact update & audit** — an additive, advisory layer for *changing* a pre-Build artifact after the fact and auditing the trail. `artifact_model.py` owns the change-ledger entry shape and the staleness disposition state machine (`OPEN → REFRESHED | ACKNOWLEDGED | NOT_AFFECTED`) with honest counting (ACKNOWLEDGED needs an owner, NOT_AFFECTED a reason, or it still counts as debt); `artifact_lineage.py` harvests declared `upstream → downstream` edges (frozen-layer `source_artifacts`, id references, explicit markdown paths) with a labeled **coarse** phase-order fallback and cycle-safe traversal. `audit_artifacts.py` (`record` / `impact` / `report`, **exit 0 always**) records changes to an append-only `.sdlc/metrics/artifact-log.jsonl` — its **own** JSONL, never inside `gate_results`, so `/sdlc-audit` output is byte-identical with or without it — and flags a downstream as a *stale candidate* when an upstream changed after it last did. `/sdlc-revise <id|file#section>` is the PM-facing write path (discipline agent proposes, named human decides; records the why to the ledger **and** a linked `DL-NN` decision-log item; re-gates; shows impact to disposition). `/sdlc-audit-artifacts` is the read-only sibling to `/sdlc-audit` (freshness dashboard, `--impact`, `--history`). A `record --scan` step in `/sdlc-next` captures direct edits at advance time; `/sdlc-status` surfaces a stale rollup. The protected core (incl. `advance_phase.py`) is byte-for-byte unchanged. See `references/artifact-lifecycle.md`
 
 ## Testing
 ```bash
@@ -77,5 +78,8 @@ uv run scripts/scorecard.py report --state /tmp/test/.sdlc/state.yaml --window-d
 uv run scripts/generate_handoff_report.py --state /tmp/test/.sdlc/state.yaml
 uv run scripts/record_findings.py record --report /tmp/test/.sdlc/artifacts/02-design/review-report.md --repo /tmp/test
 uv run scripts/record_findings.py report --repo /tmp/test --strict
-uv run --project scripts --extra test python -m pytest scripts/tests/ -q
+uv run scripts/audit_artifacts.py record --scan --repo /tmp/test
+uv run scripts/audit_artifacts.py impact FR-012 --repo /tmp/test
+uv run scripts/audit_artifacts.py report --repo /tmp/test --json
+uv run --project scripts python -m pytest scripts/tests/ -q
 ```

README.md

@@ -109,7 +109,7 @@ For in-depth technical documentation, see the guides in [`docs/`](docs/):
 | [Phase Lifecycle](docs/phase-lifecycle.md) | All 9 phases in depth — workflows, artifacts, HITL gates, skills, agents, handoff protocol, project type adaptations |
 | [Gate System](docs/gate-system.md) | 7-gate validation — integrity, completeness, metrics, compliance, consistency, quality, exit criteria — severity levels, override protocol |
 | [Profiles](docs/profiles.md) | Schema reference (every field), built-in profiles, custom profile creation, compliance framework integration, evaluation criteria |
-| [Commands](docs/commands.md) | All 21 slash commands — internal flow, state changes, Python scripts called, error scenarios, examples |
+| [Commands](docs/commands.md) | All 23 slash commands — internal flow, state changes, Python scripts called, error scenarios, examples |
 | [Agents](docs/agents.md) | 13 custom agents + built-in subagent orchestration, phase-to-agent mapping, parallel execution rules, mandatory spawns |
 | [State Machine](docs/state-machine.md) | state.yaml format, transition rules, history tracking, session-handoff.json, the spec backlog |
 | [Templates & Artifacts](docs/templates-artifacts.md) | Template directory structure, per-phase artifact details, handoff document protocol, artifact lifecycle |
@@ -228,7 +228,7 @@ Gates have severity levels:
 claude-code-sdlc/
 ├── plugin.json              # Plugin manifest
 ├── SKILL.md                 # Main skill entry point
-├── commands/                # 21 slash commands (/sdlc, /sdlc-setup, /sdlc-status, /sdlc-next, /sdlc-gate, /sdlc-enhance, /sdlc-coach, /sdlc-review, /sdlc-intake, /sdlc-brief, /sdlc-spec, /sdlc-phase-report, /sdlc-audit, /sdlc-feature, /sdlc-experience, /sdlc-data, /sdlc-rules, /sdlc-channel, /sdlc-evals, /sdlc-harness, /sdlc-upgrade)
+├── commands/                # 23 slash commands (/sdlc, /sdlc-setup, /sdlc-status, /sdlc-next, /sdlc-gate, /sdlc-enhance, /sdlc-coach, /sdlc-review, /sdlc-intake, /sdlc-brief, /sdlc-spec, /sdlc-phase-report, /sdlc-audit, /sdlc-feature, /sdlc-experience, /sdlc-data, /sdlc-rules, /sdlc-channel, /sdlc-evals, /sdlc-harness, /sdlc-upgrade, /sdlc-revise, /sdlc-audit-artifacts)
 ├── agents/                  # 13 agents (orchestrator, requirements-analyst, compliance-checker, section-evaluator, narrative-enhancer, gate-repair, multi-reviewer, discovery-analyst, feature-architect, visual-designer, conversation-designer, data-analyst, bizreq-analyst)
 ├── profiles/                # Company/stack YAML profiles
 ├── channels/                # Channel descriptor library (ag-ui, voice, chat) + schema

commands/sdlc-audit-artifacts.md

@@ -0,0 +1,87 @@
+# /sdlc-audit-artifacts — Artifact Freshness, Impact & History
+
+Audit the **content** of your pre-Build artifacts: which ones have gone stale relative to the things
+they depend on, what a change would put at risk, and the full change trail of any one artifact.
+
+This is a **sibling** to `/sdlc-audit`, not a replacement. `/sdlc-audit` audits *gate effectiveness*
+(are the gates well-calibrated). This command audits *artifact staleness and change history*. They
+answer different questions and never overlap.
+
+Everything here is **advisory** — it surfaces candidates a human dispositions; it never blocks a
+gate, changes a verdict, or edits your artifacts, specs, or `state.yaml`.
+
+## Instructions
+
+1. **Resolve mode and repo root:**
+   - **Workflow mode** (default): look for `.sdlc/state.yaml`. Pass `--state .sdlc/state.yaml` to the
+     script. If not found, tell the user to run `/sdlc-setup` first.
+   - **Standalone mode** (`--repo <path>`, or no `.sdlc/` found): run against any repo containing a
+     `.sdlc/` directory. History and staleness are only as deep as the ledger in that repo.
+
+2. **Freshen the change-ledger** (so staleness reflects what is actually on disk):
+   ```bash
+   uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py record --scan --state .sdlc/state.yaml
+   ```
+   This appends **only** to the change-ledger (`.sdlc/metrics/artifact-log.jsonl`) — it hashes the
+   artifact tree and records any new or drifted files. It never touches your artifacts, specs, or
+   `state.yaml`. On the very first run it seeds a baseline ("history starts now") — it does not
+   invent a past. In standalone mode pass `--repo <path>` instead of `--state`.
+
+3. **Pick the lens** from the user's request:
+
+   - **Freshness dashboard (default)** — per artifact: when it last changed and by whom (from the
+     ledger), its sign-off status (from `state.yaml`), and **FRESH** or **STALE** vs. its declared
+     sources. Scope with `--phase <id>`, `--artifact <id|path>`, or `--since <YYYY-MM-DD>`:
+     ```bash
+     uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py report --state .sdlc/state.yaml
+     ```
+
+   - **`--impact <id|file>`** (forward) — *"I'm about to change FR-012 — what depends on it?"* Walks
+     the lineage graph and lists every downstream artifact and the path, **before** you commit:
+     ```bash
+     uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py impact FR-012 --state .sdlc/state.yaml
+     ```
+
+   - **`--history <id|file>`** (backward) — the full change trail of one artifact from the ledger:
+     every revision, when, who, why, and any linked `DL-NN`:
+     ```bash
+     uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py report --history FR-012 --state .sdlc/state.yaml
+     ```
+
+4. **Display results** with the honest confidence labels intact:
+   - Every downstream edge is tagged **declared** (a written-down link: a frozen layer's
+     `source_artifacts`, a spec's `source`, an `FR-012`/`BR-04` id reference, an explicit markdown
+     path) or **coarse** (a phase-order *guess*, used only where nothing was declared). Never present
+     a coarse inference as a declared link.
+   - A STALE artifact is a **candidate**, never "broken" — it may already account for the change.
+   - Report the honest counts: `N stale · X open · Y dispositioned`. "no data" reads as no data,
+     never a fabricated zero.
+
+5. **Offer to disposition open staleness** (optional). For each OPEN candidate the human wants to
+   resolve, record their judgement (this is the only write, and only to the ledger):
+   ```bash
+   uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py \
+     record --disposition ACKNOWLEDGED --downstream <file> --upstream <file> --owner "<name>" --state .sdlc/state.yaml
+   ```
+   - `REFRESHED` is **derived** — update the downstream artifact and the next scan clears it
+     automatically; you don't record it by hand.
+   - `ACKNOWLEDGED` needs an **owner** or it still counts as debt. `NOT_AFFECTED` needs a **reason**.
+     You cannot clear debt by typing a word — honest counting enforces this.
+
+## Arguments
+
+- No arguments: freshness dashboard for the whole project (workflow mode).
+- `--repo <path>`: standalone mode — audit any repo with a `.sdlc/` present.
+- `--impact <id|file>`: forward lineage — what a change here could make stale.
+- `--history <id|file>`: backward change trail for one artifact.
+- `--phase <id>` / `--artifact <id|path>` / `--since <YYYY-MM-DD>`: scope the dashboard.
+
+## Important
+
+- The user runs `/sdlc-audit-artifacts` — never `audit_artifacts.py` by hand. The command owns the
+  scan, the lens selection, and the disposition recording.
+- **Read-only with respect to your project.** The only thing this command ever writes is the
+  change-ledger (`.sdlc/metrics/artifact-log.jsonl`) — the audit trail itself. It never edits an
+  artifact, a spec, or `state.yaml`. To *change* an artifact, use `/sdlc-revise`.
+- **Advisory by construction** — `audit_artifacts.py` exits 0 always. Staleness is never a gate; a
+  candidate is a prompt for a human's judgement, not a verdict.

commands/sdlc-next.md

@@ -62,8 +62,19 @@ Run exit gate checks for the current phase and advance to the next phase if all
    7. If validation fails, fix issues and re-validate before proceeding
    8. See `references/frozen-layers.md` for format details and condensation strategy
 
-6. **Advance phase:** Perform the advance via `advance_phase.py` (it applies the state updates below
-   and records any discipline sign-offs captured in step 4 on the phase's existing sign-off record):
+6. **Advance phase:**
+
+   - **First, snapshot the artifact ledger (advisory, exit 0):** capture any direct edits to this
+     phase's artifacts before they freeze, so the change history and staleness stay current even for
+     edits made outside `/sdlc-revise`:
+     ```bash
+     uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/audit_artifacts.py record --scan --state .sdlc/state.yaml
+     ```
+     This appends only to `.sdlc/metrics/artifact-log.jsonl` (the audit trail) — it never modifies
+     artifacts or `state.yaml`, and never blocks the advance. If the script is absent, skip it.
+
+   Then perform the advance via `advance_phase.py` (it applies the state updates below and records any
+   discipline sign-offs captured in step 4 on the phase's existing sign-off record):
    ```bash
    uv run --project ${CLAUDE_PLUGIN_ROOT}/scripts ${CLAUDE_PLUGIN_ROOT}/scripts/advance_phase.py \
      --state .sdlc/state.yaml --confirmed \