bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-analyze-source/references/step-shape-detect.md

@@ -1,14 +1,22 @@
+---
+shapeDetectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shape-detect.py'
+  - '{project-root}/src/shared/scripts/skf-shape-detect.py'
+---
+
 # Shape Detection Reference
 
 Reference document for invoking `skf-shape-detect.py` — the shared shape classification module. Loaded by `step-auto-scope.md` for auto-scope analysis.
 
 ## Invocation Contract
 
-**Script:** `src/shared/scripts/skf-shape-detect.py`
+**Resolve `{shapeDetectHelper}`** from `{shapeDetectProbeOrder}`; first existing path wins; HALT if neither resolves.
 
 **Command:**
 ```
-uv run python src/shared/scripts/skf-shape-detect.py --repo-url <url> --manifests <path1,path2,...>
+uv run {shapeDetectHelper} --repo-url <url> \
+  --manifests <path1,path2,...> \
+  --grammar-files <g1,g2,...> --tree-paths <d1/,d2/,file,...>
 ```
 
 **Arguments:**
@@ -16,9 +24,11 @@ uv run python src/shared/scripts/skf-shape-detect.py --repo-url <url> --manifest
 | Arg | Required | Description |
 |-----|----------|-------------|
 | `--repo-url` | Yes | Repository URL (context only — no cloning performed) |
-| `--manifests` | Yes | Comma-separated local file paths to manifest files |
+| `--manifests` | Yes | Comma-separated local file paths to manifest files (may be empty when a tree-level signal carries the classification) |
+| `--grammar-files` | No | Comma-separated repo-relative grammar files (`*.y`, `*.g4`, `*.pest`, `Grammar/python.gram`, ...) — a whole-language signal |
+| `--tree-paths` | No | Comma-separated repo-relative directory (trailing `/`) and structural file signals harvested from the clone (a `compiler/` dir, a lexer+parser+ast triad) |
 
-**Supported manifests:** `package.json`, `pyproject.toml`, `Cargo.toml`
+**Supported manifests:** `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`
 
 ## Output Schema
 
@@ -49,22 +59,19 @@ On exit code 2, error details are written to stderr as JSON: `{"error": "message
 | `library-API` | `full-library` | export_count ≤ 200 |
 | `library-API` | `public-api` | export_count > 200 (surface too large for full coverage) |
 | `reference-app` | `reference-app` | Direct mapping — apps, CLIs, demos |
-| `language-reference` | `full-library` | Language tools/parsers are library-shaped from a skill perspective |
-| `stack-compose` | `full-library` | Multi-skill decomposition when `package_count > 3` `[PENDING VALIDATION]` — see step-auto-scope.md §3a |
+| `language-reference` | `full-library` | Language tools/parsers are library-shaped from a skill perspective. **Corpora-dependent** for a *whole-language* reference (a `grammar_file:`/`tree_triad:` signal — a compiler/interpreter): its value is the language's prose (guide/Book + std/library docs), not compiler internals, so step-auto-scope.md §6b seeds companion corpora and §6/§7 record an honest DEGRADED caveat when none are found (mirrors the §3b facet-coverage guard). A parser *library* (`parser_producer:`/`parser_dep:`) is exempt — its code is the product. |
+| `stack-compose` | `full-library` | Decomposition candidate when `package_count > 3` — cohesion-checked in step-auto-scope.md §3b |
 | `unknown` | N/A | Triggers fallback to interactive mode |
 
 ## Decomposition Thresholds
 
-When auto-scope detects a repo exceeding complexity thresholds, it recommends multi-skill decomposition instead of producing a single unwieldy skill. The thresholds are evaluated in step-auto-scope.md §3a.
+When auto-scope detects a multi-package monorepo, it may recommend multi-skill decomposition instead of producing one unwieldy skill. The threshold is evaluated in step-auto-scope.md §3a.
 
 | Threshold | Value | Signal | Decomposition Path |
 |-----------|-------|--------|-------------------|
-| Large export surface | `export_count > 500` `[PENDING VALIDATION]` | Shape detection `export_count` | Group by top-level source directory modules |
-| Multi-package / monorepo | `package_count > 3` `[PENDING VALIDATION]` | Shape detection `package_count` | One skill per workspace package |
-
-Both thresholds are marked `[PENDING VALIDATION]` — no empirical data exists yet for real-world repos. Expected tuning: after running deepwiki against 5–10 real repos, adjust thresholds based on whether decomposition produces useful skill boundaries or noise.
+| Multi-package / monorepo | `package_count > 3` | Shape detection `package_count` | Cohesion check (§3b): merge to one skill or split per package |
 
-When both thresholds are met simultaneously, the monorepo path takes priority (package boundaries are explicit; export-count grouping is heuristic).
+`package_count > 3` makes a **monorepo** a decomposition candidate; step-auto-scope.md §3b then decides merge-vs-split. It is empirically validated (fires on real 15-, 38-, and 442-package workspaces). A *single* package with a large API surface is **not** decomposed — it produces one cohesive skill that `skf-create-skill`'s auto-shard splits into `references/` shards at the 400-line ceiling.
 
 When neither threshold is met, the single-scope flow proceeds unchanged.
 
@@ -72,7 +79,7 @@ When neither threshold is met, the single-scope flow proceeds unchanged.
 
 The five-shape heuristic ladder applies in order (first match wins):
 
-1. **language-reference** — parser/grammar/language-toolchain project. Signals: parser-related deps (pest, antlr4, tree-sitter, lark, etc.)
+1. **language-reference** — parser/grammar/language-toolchain project. Signals, strongest first: a hand-written-compiler tree structure (a dedicated `compiler/` directory with a lexer+parser+ast triad plus a codegen/VM/type-checker member — catches rustc, TypeScript, Go); a declared grammar file (`Grammar/python.gram`, a root `parse.y`, a `*.g4` — catches CPython, Ruby); the repo's own name being a known parser/grammar tool (pest, lalrpop, lark — the producer); or a parser-generator dependency (a DSL built on antlr4/lalrpop — the consumer). Delegating consumers (formatters, linters, bundlers that depend on a parser) and markup/DSL parsers (CSS, markdown, GraphQL) are excluded.
 2. **stack-compose** — multi-ecosystem composite project. Signals: manifests from 2+ distinct ecosystems
 3. **reference-app** — application, CLI, or demo project. Signals: npm `bin` field, Rust `[[bin]]`, framework deps (next, fastapi, axum, etc.)
 4. **library-API** — library exposing a programmatic API. Signals: `main`/`module`/`exports` fields, `[lib]` target, export count

package/src/skf-analyze-source/references/unit-detection-heuristics.md

@@ -77,7 +77,7 @@ Rules for identifying discrete skillable units within a project. A "skillable un
 - Scope type: inherits from the dominant constituent (typically `full-library` or `specific-modules`)
 
 **Detection heuristic (apply after initial classification, before user confirmation):**
-1. Among the qualifying units, find groups of ≥2 boundaries where EITHER:
+1. Among the qualifying units, find groups of ≥2 boundaries where either:
    - **Mutual hard dependency:** Every constituent imports from at least one other constituent in the group, AND no constituent's public API is self-contained (removing any one breaks the others)
    - **Shared integration surface:** Constituents share types/traits defined in one constituent but consumed by all others, AND the consuming constituents have no independent barrel (their value depends on the shared definitions)
 2. For each detected group, propose merging into a single composite unit:
@@ -88,7 +88,7 @@ Rules for identifying discrete skillable units within a project. A "skillable un
 
 ## Disqualification Rules
 
-Do NOT recommend as a skillable unit if:
+Do not recommend a boundary as a skillable unit when:
 
 1. **Too small**: Fewer than 3 source files or 100 lines of code
 2. **Generated code**: Auto-generated files (protobuf, GraphQL codegen, etc.)

package/src/skf-audit-skill/SKILL.md

@@ -7,11 +7,12 @@ description: Drift detection between skill and current source code. Use when the
 
 ## Overview
 
-Detects drift between an existing skill and its current source code, producing a severity-graded drift report with AST-backed findings and actionable remediation suggestions. Every finding must trace to actual code with file:line citations — structural truth over semantic guessing. Analysis depth adapts based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation. Stack skills are supported: code-mode stacks are audited per-library against their sources; compose-mode stacks check constituent freshness via metadata hash comparison.
+Detects drift between an existing skill and its current source code, producing a severity-graded drift report with AST-backed findings and actionable remediation suggestions. Analysis depth adapts based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation. Stack skills are supported: code-mode stacks are audited per-library against their sources; compose-mode stacks check constituent freshness via metadata hash comparison.
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root — stage files reference `knowledge/version-paths.md` and `knowledge/tool-resolution.md`, and the terminal step chains to `shared/health-check.md`.
 - `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
@@ -19,7 +20,7 @@ Detects drift between an existing skill and its current source code, producing a
 
 ## Role
 
-You are a skill auditor operating in Ferris Audit mode. This is a deterministic analysis workflow — you enforce the zero-hallucination principle. You bring AST analysis expertise and drift detection methodology, while the source code provides the ground truth.
+You are a skill auditor in Ferris Audit mode: a deterministic drift-detection workflow where the source code is the ground truth and every finding traces back to it.
 
 ## Workflow Rules
 
@@ -56,7 +57,7 @@ These rules apply to every step in this workflow:
 
 ## Exit Codes
 
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+Every hard halt in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
 
 | Code | Meaning              | Raised by                                                                                                          |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -68,13 +69,13 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every hard halt emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
 SKF_AUDIT_RESULT_JSON: {"status":"success|error","skill_name":"…","drift_score":"CLEAN|MINOR|SIGNIFICANT|CRITICAL|null","report_path":"…|null","next_workflow":"update-skill|null","audit_ref":"…|null","exit_code":0,"halt_reason":null}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `drift_score` is `null` when the workflow halted before severity classification ran. `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist, otherwise `null`. `halt_reason` is one of: `null` (success), `"input-missing"`, `"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"error"` on any halt. `drift_score` is `null` when the workflow halted before severity classification ran. `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist, otherwise `null`. `halt_reason` is one of: `null` (success), `"input-missing"`, `"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -106,6 +107,8 @@ SKF_AUDIT_RESULT_JSON: {"status":"success|error","skill_name":"…","drift_score
    - `{severityRulesPath}` ← `workflow.severity_rules_path` if non-empty, else `references/severity-rules.md`
    - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — report.md skips the hook invocation entirely)
 
-   Stash all three as workflow-context variables. Stage files reference `{driftReportTemplatePath}` / `{severityRulesPath}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies (custom drift-report layout, stricter severity thresholds) or wire in post-audit hooks (Slack notifier, ticket-tracker integration) without forking the skill.
+   Stash all three as workflow-context variables. Stage files reference `{driftReportTemplatePath}` / `{severityRulesPath}` / `{onCompleteCommand}` directly.
+
+   Also apply the array surfaces (not silent no-ops): run `workflow.activation_steps_prepend` now, treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts — the bundled default globs any `project-context.md`), then run `workflow.activation_steps_append` after activation.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-audit-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-audit-skill.
+# Team overrides:     _bmad/custom/skf-audit-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-audit-skill.user.toml (under {project-root})
 
 [workflow]
 

package/src/skf-audit-skill/references/init.md

@@ -1,13 +1,16 @@
 ---
 nextStepFile: 're-index.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-templateFile: 'assets/drift-report-template.md'
+templateFile: '{driftReportTemplatePath}'
 loadProvenanceProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-load-provenance.py'
   - '{project-root}/src/shared/scripts/skf-load-provenance.py'
 compareFileHashesProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-compare-file-hashes.py'
   - '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
+compareConstituentHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -52,9 +55,9 @@ Which skill would you like to audit? Please provide the skill name or path."
 
      - **[N] Audit symlink target ({symlink_target})** — recommended. The drift report describes the version the skill currently resolves to.
      - **[M] Audit manifest version ({active_version})** — only useful when investigating the older version specifically.
-     - **[X] Abort** — halt without producing a report. Run `[EX] Export Skill` to reconcile the manifest before re-running audit-skill."
+     - **[X] Abort** — halt without producing a report (exit 6, `halt_reason: "user-cancelled"`). Run `[EX] Export Skill` to reconcile the manifest before re-running audit-skill."
 
-     Default is **[N]**. Headless mode auto-selects **[N]** with a loud log line: `"headless: manifest active_version ({active_version}) is older than symlink target ({symlink_target}); auditing symlink target. Run export-skill to reconcile."` This mirrors §5b's upstream-drift handling — when the manifest and the working tree disagree, the working tree is the more honest signal under automation.
+     Default is **[N]**. Headless mode auto-selects **[N]** with a loud log line: `"headless: manifest active_version ({active_version}) is older than symlink target ({symlink_target}); auditing symlink target. Run export-skill to reconcile."` When the manifest and on-disk state disagree, the working tree is the more honest signal under automation.
 
    - When the symlink target's provenance is **older** than (or equal to) the manifest's `last_exported`, the symlink predates the export — this is the normal post-export shape, no gate needed. Resolve to the manifest's `active_version`.
    - When only one of the two versions has a provenance map, resolve to the version that has one (the other is inert — auditing it would degrade to text-diff). Log the choice.
@@ -70,13 +73,17 @@ Which skill would you like to audit? Please provide the skill name or path."
 - If missing → "Skill not found at `{resolved_skill_package}`. Check the path and try again."
 - If found → Continue
 
+**Headless default** (when `{headless_mode}`): the interactive prompt and its "check the path and try again" re-prompt cannot be answered under automation, so §1 halts deterministically instead of looping. This is the origin site for the exit-2 / exit-3 rows the Exit Codes table attributes to step 1 §1 — emit the `SKF_AUDIT_RESULT_JSON` error envelope on **stderr** (shape per SKILL.md → Result Contract; `status: "error"`, `drift_score: null`, `report_path: null`, `next_workflow: null`, `audit_ref: null`) at each halt:
+- **No `skill_name` supplied** (neither name nor path given): HALT with **exit 2**, `halt_reason: "input-missing"`, `skill_name: null`. Log: `"headless: no skill_name supplied; cannot resolve interactively. Re-run with skill_name set."`
+- **`SKILL.md` missing at `{resolved_skill_package}`**: HALT with **exit 3**, `halt_reason: "skill-not-found"`, `skill_name: {skill_name}`. Log: `"headless: skill not found at {resolved_skill_package}; no interactive retry. Check the exported skill name/path."`
+
 ### 2. Load Forge Tier
 
 Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 
 **If file missing:**
 - "Setup-forge has not been run. Cannot determine tool availability. Run `[SF] Setup Forge` first."
-- HALT workflow
+- HALT with **exit 3**, `halt_reason: "forge-tier-missing"`. When `{headless_mode}`, emit the error envelope on **stderr** (shape per SKILL.md → Result Contract) and log: `"headless: forge-tier.yaml missing at {sidecar_path}; run setup-forge. Aborting."`
 
 **If found:**
 - Extract tier level: Quick / Forge / Forge+ / Deep
@@ -118,24 +125,50 @@ Search for provenance map at `{forge_data_folder}/{skill_name}/{active_version}/
   - `{source_root}`, `{baseline_commit}`, `{baseline_ref}` — used by §5 Resolve Source Path and §5b Detect Upstream Drift.
   - `{reexport_map}` — `{<internal>: <public>}` mapping consumed by `structural-diff.md` §1 to collapse public-API renames before diffing.
 
-  If the script exits non-zero, surface the stderr as a HARD HALT — the map is structurally invalid and downstream steps cannot proceed.
+  If the script exits non-zero, surface the stderr as a hard halt — the map is structurally invalid and downstream steps cannot proceed.
 
 **If missing at both paths:**
 - "No provenance map found for `{skill_name}`. This skill may not have been created by create-skill."
 - "**Degraded mode available:** I can perform text-based comparison without provenance data. Findings will have T1-low confidence."
 - "**[D]egraded mode** — proceed with text-diff only"
 - "**[X]** — abort audit"
-- Wait for user selection. If D, set `degraded_mode: true` and `confidence_mode = "degraded — all findings T1-low"`, then skip the normalize call above (no map to normalize). If X, halt workflow.
+- Wait for user selection. If D, set `degraded_mode: true` and `confidence_mode = "degraded — all findings T1-low"`, then skip the normalize call above (no map to normalize). If X, halt workflow (exit 6, `halt_reason: "user-cancelled"`).
+
+**Headless default** (when `{headless_mode}`): consume the pre-supplied `degraded` input from the Invocation Contract. If `degraded=true`, auto-select **[D]** (set `degraded_mode: true`, `confidence_mode = "degraded — all findings T1-low"`, skip the normalize call) and log: `"headless: no provenance map for {skill_name}; proceeding in degraded mode (text-diff, T1-low) per pre-supplied degraded=true."` If `degraded` is unset or false, auto-select **[X] abort** (exit 6, `halt_reason: "user-cancelled"`) and log: `"headless: no provenance map for {skill_name} and degraded not pre-supplied; aborting. Re-run with degraded=true for text-diff."` Never silently emit a low-confidence report under automation without explicit opt-in — same stance as the [A]-abort default at §5b's dirty-worktree sub-gate.
 
 ### Stack Skill Detection
 
 `{is_stack_skill}` and `{legacy_stack_provenance}` are already resolved by the normalize call in §4 — no additional walk needed. Apply the post-detection logic:
 
 If `{is_stack_skill}` is true and `constituents` array is present (compose-mode stack):
-- For each constituent, compute the current metadata hash: read `{constituent.skill_path}/active/{constituent.skill_name}/metadata.json` and compute SHA-256
-- Compare against `constituent.metadata_hash`
-- Flag any mismatches as **constituent drift** with severity HIGH
-- Record constituent freshness results for the report
+
+Re-hashing each constituent's live `metadata.json` and comparing against the compile-time snapshot is deterministic work — and the model cannot compute a `sha256:{hexdigest}` natively (it must shell out on every run). Delegate the whole read/hash/compare pass to the shared helper, which hashes byte-symmetrically with how `constituents[].metadata_hash` was written at compose time (the `sha256:`-prefixed digest of the raw `metadata.json` bytes). This mirrors the two sibling drift checks — `structural-diff.md` §4b (`skf-compare-file-hashes.py`) and `step-doc-drift.md` §2 (`skf-detect-docs.py compare-hashes`).
+
+**Resolve `{compareConstituentHashesHelper}`** from `{compareConstituentHashesProbeOrder}`; first existing path wins.
+
+Run one deterministic comparison subprocess over the provenance map's `constituents[]`. Relative constituent `skill_path` values (e.g. `skills/{skill-dir}/`) are project-root-relative, so resolve them against `{project-root}`:
+
+```bash
+uv run {compareConstituentHashesHelper} compare-constituent-hashes {provenanceMap} --skills-root {project-root}
+```
+
+Parse the emitted JSON:
+
+```json
+{
+  "drifted":           [{"skill_name": "...", "skill_path": "...", "stored_hash": "sha256:...", "current_hash": "sha256:..."}],
+  "fresh":             [{"skill_name": "..."}],
+  "missing":           [{"skill_name": "...", "skill_path": "...", "stored_hash": "sha256:...", "reason": "metadata-not-found|incomplete-record"}],
+  "skipped_null_hash": [{"skill_name": "..."}],
+  "stats": {"total": N, "drifted": N, "fresh": N, "missing": N, "skipped_null_hash": N}
+}
+```
+
+- **Flag every entry in `drifted[]` as constituent drift with severity HIGH** — its live `metadata.json` differs from the compile-time snapshot recorded in the provenance map.
+- `fresh[]` are unchanged constituents. `missing[]` (each carrying a `reason`) are constituents whose `metadata.json` could not be located (`metadata-not-found`) or whose provenance record lacked `skill_name`/`skill_path` (`incomplete-record`) — surface these as a lower-severity note, not HIGH drift. `skipped_null_hash[]` had no compile-time baseline hash (recorded from a references/ cascade) — never reported as drift.
+- Record the constituent freshness results (the four buckets + `stats`) for the report — read the counts straight from `stats`, no manual recount.
+
+**If `uv`/the helper cannot execute** (e.g. claude.ai web): fall back to hashing by hand — for each constituent, read its `metadata.json` at `{constituent.skill_path}/active/{constituent.skill_name}/metadata.json` (resolve `skill_path` against `{project-root}` when relative, use as-is when absolute), SHA-256 the raw bytes, and compare against `constituent.metadata_hash` (a stored bare-hex form still matches after stripping any `sha256:` prefix from both sides). Flag mismatches as HIGH constituent drift.
 
 If `{legacy_stack_provenance}` is true: log a note that this stack uses v1 provenance format with reduced audit depth (library-level only, no per-export verification).
 
@@ -150,7 +183,7 @@ If `{legacy_stack_provenance}` is true: log a note that this stack uses v1 prove
 - Ask user: "Please provide the path to the current source code."
 - `baseline_commit` and `baseline_ref` are unavailable — §5b will short-circuit
 
-**Validate:** Confirm source directory exists and contains expected files.
+**Validate:** Confirm the source directory exists and is accessible. If it is missing or unreadable → HALT with **exit 3**, `halt_reason: "source-dir-missing"`. When `{headless_mode}`, emit the error envelope on **stderr** (shape per SKILL.md → Result Contract) and log: `"headless: source directory {source_root} from the provenance map no longer exists; aborting."`
 
 ### 5b. Detect Upstream Drift
 
@@ -221,7 +254,10 @@ When skipping, log the reason, then set the audit-ref context variables to basel
      - **[F]:** Run `git -C {source_root} checkout --force {chosen_ref}` instead of the plain checkout. Record `pre_checkout_force_discard: true` in workflow context for step 6 to surface as a loud warning. Skip the stash path.
      - **Other input:** help user, redisplay the sub-gate.
 
-     **Headless default** (when `{headless_mode}`): auto-select **[A] Abort** rather than silently mutating the working tree. Emit a loud log line: `"headless: dirty worktree detected at {source_root}; refusing to checkout {chosen_ref} or stash. Re-run interactively to choose [T]/[A]/[F]."` Stashing under automation could lose work if the operator never returns to pop; force-checkout under automation could destroy uncommitted work outright. Abort is the only safe non-interactive default.
+     **Headless default** (when `{headless_mode}`): consume the pre-supplied `dirty_worktree_choice` from the Invocation Contract — the operator's explicit answer is the consent that a silent working-tree mutation would otherwise lack.
+     - **`dirty_worktree_choice=T`**: run the `[T]` transient-stash path. Log: `"headless: dirty worktree at {source_root}; stashing before checkout per pre-supplied dirty_worktree_choice=T."`
+     - **`dirty_worktree_choice=F` with `force=true`**: run the `[F]` force-checkout path — `force=true` is the required consent to discard uncommitted changes irrecoverably. Log: `"headless: dirty worktree at {source_root}; force-discarding uncommitted changes per pre-supplied dirty_worktree_choice=F force=true."`
+     - **`dirty_worktree_choice=A`, unset, or `=F` without `force=true`**: auto-select **[A] Abort** (exit 6, `halt_reason: "user-cancelled"`). Abort is the safe default, and a force-discard without `force=true` consent is refused rather than executed. Log: `"headless: dirty worktree detected at {source_root}; refusing to checkout {chosen_ref} (dirty_worktree_choice={value or 'unset'}). Pass dirty_worktree_choice=T, or =F with force=true, to proceed non-interactively."` Stashing that is never popped could lose work; force-checkout without consent could destroy uncommitted work outright — so both require an explicit pre-supplied choice.
 
      If `git status --porcelain` is empty, skip the sub-gate and proceed directly to the checkout.
 
@@ -230,7 +266,10 @@ When skipping, log the reason, then set the audit-ref context variables to basel
    - **[X]:** HALT workflow — do not create drift report.
    - **Other input:** help user, redisplay gate.
 
-   **Headless default** (when `{headless_mode}`): auto-select **[S]** and emit a loud log line: `"headless: upstream drift detected ({baseline_ref} → {latest_tag or remote_head}); staying on baseline. Re-run interactively to audit against latest."` Do not check out in headless mode — silent ref changes under automation would mutate the user's working tree without consent.
+   **Headless default** (when `{headless_mode}`): consume the pre-supplied `upstream_drift_choice` from the Invocation Contract.
+   - **`upstream_drift_choice=S`, or unset**: auto-select **[S] Stay-on-baseline** (default). Set `audit_ref = baseline_ref`, `audit_ref_source = "baseline"`, `audit_commit = baseline_commit`. Log: `"headless: upstream drift detected ({baseline_ref} → {latest_tag or remote_head}); staying on baseline per upstream_drift_choice={value or 'default S'}. Pass upstream_drift_choice=C to audit against latest."` Defaulting to a checkout would mutate the working tree without consent, so `[S]` remains the default when no choice is supplied.
+   - **`upstream_drift_choice=C`**: run the `[C] Checkout-and-audit-against-latest` path above — the operator's pre-supplied choice is the explicit consent that a silent ref change would otherwise lack. The dirty-worktree sub-gate still applies and consults its own pre-supplied `dirty_worktree_choice`. Log: `"headless: upstream drift detected; checking out {latest_tag or remote_head} per pre-supplied upstream_drift_choice=C."`
+   - **`upstream_drift_choice=X`**: HALT the workflow (exit 6, `halt_reason: "user-cancelled"`) — do not create a drift report. Log: `"headless: upstream drift detected; aborting per pre-supplied upstream_drift_choice=X."`
 
 5. **Record for report:** store `audit_ref`, `audit_ref_source`, `audit_commit`, `latest_tag`, `remote_head`, and `baseline_commit` in context. Step-06 surfaces them in the Provenance section so readers can tell which comparison actually ran.
 
@@ -252,7 +291,7 @@ When skipping, log the reason, then set the audit-ref context variables to basel
 - **[D]:** Read the prior report's findings_list (parse the Structural/Semantic/Severity sections, or the appended findings tables) and stash as `prior_findings` in workflow context. Run the new audit normally. In step 6 (report.md), after the Remediation Suggestions section, emit a `## Diff Against Prior Report` subsection summarizing added / removed / changed findings vs `prior_findings`.
 - **[R]:** Load the prior report's frontmatter (`stepsCompleted`, `drift_score`, any intermediate state). Set `{outputFile}` to the prior report path (do NOT create a new one). Determine the next un-completed step from `stepsCompleted` and skip forward to it; downstream steps append to the existing report.
 
-  > **Note (resumability):** the existing template frontmatter captures `stepsCompleted` and `drift_score` but does not currently persist intermediate findings_list between stages. If [R] is selected and stepsCompleted indicates the prior run halted after structural-diff or semantic-diff, the appended sections in the report body (`## Structural Drift`, `## Semantic Drift`, `## Severity Classification`) serve as the implicit intermediate state — re-parse them on resume rather than re-running completed stages. **TODO:** if resumability proves unreliable in practice, extend the report frontmatter to carry an explicit `intermediate_findings` block (out of scope for this PR).
+  > **Note (resumability):** the template frontmatter captures `stepsCompleted` and `drift_score` but does not persist an intermediate findings_list between stages. If [R] is selected and stepsCompleted indicates the prior run halted after structural-diff or semantic-diff, the appended report-body sections (`## Structural Drift`, `## Semantic Drift`, `## Severity Classification`) serve as the implicit intermediate state — re-parse them on resume rather than re-running completed stages.
 
 - **Other input:** help user, redisplay the gate.
 
@@ -268,7 +307,9 @@ Create `{outputFile}` from `{templateFile}`:
 - Set `stepsCompleted: ['init']`
 - Fill Audit Summary skeleton with loaded baseline data
 
-### 7. Present Baseline Summary (User Gate)
+If the write fails (read-only mount, disk full, permissions denied) → HALT with **exit 4**, `halt_reason: "write-failed"`. When `{headless_mode}`, emit the error envelope on **stderr** (shape per SKILL.md → Result Contract).
+
+### 7. Present Baseline Summary and Confirm (User Gate)
 
 "**Audit Baseline Loaded**
 
@@ -290,22 +331,7 @@ Create `{outputFile}` from `{templateFile}`:
 
 **Ready to begin drift analysis?**"
 
-### 8. Present MENU OPTIONS
-
-Display: "**Select:** [C] Continue to Analysis"
-
-#### Menu Handling Logic:
-
-- IF C: Save baseline to {outputFile}, update frontmatter stepsCompleted, then load, read entire file, then execute {nextStepFile}
-- IF Any other: help user, then [Redisplay Menu Options](#8-present-menu-options)
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past baseline confirmation"
-- ONLY proceed to next step when user selects 'C'
-
-## CRITICAL STEP COMPLETION NOTE
+Halt and wait for the user's go-ahead. Only proceed once the drift report has been created with baseline data populated. On confirmation, save the baseline to `{outputFile}`, append `'init'` to the frontmatter `stepsCompleted`, then load, read the entire file, and execute `{nextStepFile}`. On any other input, help the user, then re-ask.
 
-ONLY WHEN C is selected and the drift report has been created with baseline data populated, will you then load and read fully `{nextStepFile}` to execute and begin source re-indexing.
+**GATE [default: proceed]** — if `{headless_mode}`, auto-proceed and log: "headless: auto-continue past baseline confirmation".
 

package/src/skf-audit-skill/references/re-index.md

@@ -14,7 +14,7 @@ Re-scan the source code using the current forge tier tools to build a fresh extr
 ## Rules
 
 - Focus only on extracting current source state — do not compare yet (that's Step 03)
-- Do not skip files or take shortcuts in extraction
+- Extract every file in the bounded scan list — a file skipped here makes step 3 flag its exports as false "removed" drift
 - Use subprocess Pattern 2 (per-file deep analysis) when available for AST extraction; if unavailable, extract in main thread file by file
 
 ## MANDATORY SEQUENCE
@@ -53,13 +53,10 @@ Audit-skill detects drift on files that were in scope during create-skill. The a
 
 **If a provenance map was loaded in step 1** (normal mode):
 
-1. Extract the unique set of file paths from the provenance map:
-   - `entries[].source_file` (one path per extracted export)
-   - `file_entries[].source_file` (one path per tracked script/asset, when present)
-2. Deduplicate the combined list. This is the **bounded scan list**.
-3. Verify each path under `{source_root}`. Files that existed at creation time but are now missing are **not** errors at this stage — keep them in the list so step 3 can classify them as DELETED. Handling missing files is step 3's job, not step 2's.
-4. Record `bounded_scan: true` and `bounded_scan_source: "provenance-map"` in context for the evidence report.
-5. Report:
+1. The **bounded scan list** is `{bounded_scan_files}` — the union of `entries[].source_file` and `file_entries[].source_file`, deduplicated, sorted, and forward-slash normalized by init.md §4's `skf-load-provenance.py normalize` call. Consume it directly; do **not** re-walk the provenance map to rebuild it. The union/dedup/sort has one correct answer per map and is already scripted — re-deriving it in-prompt risks diverging from step 3, which diffs against the same normalized projection.
+2. Verify each path under `{source_root}`. Files that existed at creation time but are now missing are **not** errors at this stage — keep them in the list so step 3 can classify them as DELETED. Handling missing files is step 3's job, not step 2's.
+3. Record `bounded_scan: true` and `bounded_scan_source: "provenance-map"` in context for the evidence report.
+4. Report:
 
    "**Bounded scan:** {count} files from provenance map ({provenance_date})."
 
@@ -76,7 +73,7 @@ Audit-skill detects drift on files that were in scope during create-skill. The a
 
 ### 3. Extract Current Exports
 
-**DO NOT BE LAZY — For EACH file in the bounded scan list from §2, launch a subprocess that:**
+**For each file in the bounded scan list from §2, launch a subprocess that:**
 1. Loads the source file
 2. Extracts all public exports using tier-appropriate method
 3. Records: export name, type, signature, file path, line number, confidence tier
@@ -86,7 +83,7 @@ Audit-skill detects drift on files that were in scope during create-skill. The a
 
 **If subprocess unavailable:** Perform extraction in main thread, processing each file sequentially.
 
-**Build extraction snapshot:**
+**Build extraction snapshot and persist it to `{forge_version}/extraction-snapshot.json`** — step 3 (`structural-diff.md`) reads this file directly, so it must be written to disk, not merely held in context:
 ```
 {
   "extraction_date": "{timestamp}",
@@ -108,15 +105,17 @@ Audit-skill detects drift on files that were in scope during create-skill. The a
 }
 ```
 
+Record the written path as `{extractionSnapshot}` in workflow context — step 3 passes it to the deterministic structural-diff helper.
+
 ### 4. Deep Tier Enhancement (Deep Only)
 
-**IF forge tier is Deep:**
+**If forge tier is Deep:**
 
 Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`.
 
 Find the collection entry matching the current skill: look for an entry where `skill_name` matches the current skill being audited AND `type` is `"extraction"`.
 
-Three collection states must be handled distinctly (same branching as step 4 §2 — keep them in sync):
+Three collection states must be handled distinctly — semantic-diff.md §2 branches the same way:
 
 **If a matching extraction collection is found and populated** (pre-query probe via `qmd ls {collection_name}` or equivalent returns one or more files):
 Query qmd_bridge against the `{skill_name}-extraction` collection for temporal context on each extracted export:
@@ -135,12 +134,12 @@ Continue without T2 enrichment — the unpopulated collection is a setup gap, no
 Log: "No QMD extraction collection found for {skill_name}. Temporal enrichment skipped. Re-run [CS] Create Skill to generate the collection."
 Continue without T2 enrichment — this is not an error.
 
-**IF forge tier is Quick, Forge, or Forge+:**
+**If forge tier is Quick, Forge, or Forge+:**
 Skip this section. Temporal context requires Deep tier.
 
 ### 4b. CCC Rename Detection (Forge+ and Deep with ccc)
 
-**IF `tools.ccc` is true in forge-tier.yaml:**
+**If `tools.ccc` is true in forge-tier.yaml:**
 
 For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
 
@@ -153,7 +152,7 @@ For each export in the skill baseline that was NOT found at its recorded file pa
 
 CCC failures: skip rename detection silently, proceed with standard structural diff.
 
-**IF `tools.ccc` is false:** Skip this section silently.
+**If `tools.ccc` is false:** Skip this section silently.
 
 ### 5. Validate Extraction Completeness
 
@@ -174,23 +173,5 @@ CCC failures: skip rename detection silently, proceed with standard structural d
 
 ### 6. Update Report and Auto-Proceed
 
-Update {outputFile} frontmatter:
-- Append `'re-index'` to `stepsCompleted`
-
-### 7. Present MENU OPTIONS
-
-Display: "**Proceeding to structural diff...**"
-
-#### Menu Handling Logic:
-
-- After extraction is complete and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed analysis step with no user choices
-- Proceed directly to next step after extraction
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the extraction snapshot is complete with all source files processed will you then load and read fully `{nextStepFile}` to execute and begin structural comparison.
+Update {outputFile} frontmatter — append `'re-index'` to `stepsCompleted`. Once the extraction snapshot is complete with all source files processed, load, read fully, and execute `{nextStepFile}` (structural diff).
 

package/src/skf-audit-skill/references/report.md

@@ -34,24 +34,7 @@ Update the ## Audit Summary section at the top of {outputFile} with final calcul
 
 ### 2. Generate Remediation Suggestions
 
-For EACH classified drift finding, generate a specific remediation suggestion:
-
-**CRITICAL findings remediation:**
-- Removed export → "Remove reference to `{export_name}` from SKILL.md section {section}. Export no longer exists at `{file}:{line}`."
-- Changed signature → "Update `{export_name}` signature in SKILL.md from `{old_signature}` to `{new_signature}`. See `{file}:{line}`."
-- Renamed export → "Replace `{old_name}` with `{new_name}` throughout SKILL.md. Renamed at `{file}:{line}`."
-
-**HIGH findings remediation:**
-- New public API (>3) → "Add documentation for {count} new exports to SKILL.md: {export_list}. Consider running update-skill workflow."
-- Deprecated API → "Mark `{export_name}` as deprecated in SKILL.md. Current replacement: `{replacement}` at `{file}:{line}`."
-
-**MEDIUM findings remediation:**
-- Moved function → "Update file reference for `{export_name}` from `{old_file}` to `{new_file}:{line}`."
-- New exports (1-3) → "Consider adding `{export_names}` to SKILL.md for completeness."
-- Changed convention → "Review convention documentation in SKILL.md for currency."
-
-**LOW findings remediation:**
-- Style changes → "Optional: Update style references in SKILL.md to reflect current conventions."
+For each classified drift finding, write one concrete remediation derived from the finding itself: **what** to change in the audited **SKILL.md** (or its `references/`) — not the source code — **where** (the section plus the source `{file}:{line}` the finding cites), and **why**. Set effort (`low`/`medium`/`high`) by how much of the skill doc the change touches. A reviewer should be able to act on each row without re-deriving the finding.
 
 Append to {outputFile}:
 
@@ -125,50 +108,20 @@ Append to {outputFile}:
 
 Update {outputFile} frontmatter:
 - Append `'report'` to `stepsCompleted`
-- Set `drift_score` to final calculated score
+- Set `drift_score` to the score from step 5's classification helper
 - Set `nextWorkflow` to `'update-skill'` if CRITICAL or HIGH findings, otherwise leave empty
 
-### 5. Present Final Report Summary
-
-"**Audit Complete: {skill_name}**
-
----
-
-**Overall Drift Score: {CLEAN / MINOR / SIGNIFICANT / CRITICAL}**
-
-| Severity | Count |
-|----------|-------|
-| CRITICAL | {count} |
-| HIGH | {count} |
-| MEDIUM | {count} |
-| LOW | {count} |
-| **Total** | {total} |
+If finalizing the report or writing the result JSON below fails (read-only mount, disk full, permissions denied) → HALT with **exit 4**, `halt_reason: "write-failed"`. When `{headless_mode}`, emit the error envelope on **stderr** (shape per SKILL.md → Result Contract) with `report_path: null`.
 
-**Report saved to:** `{outputFile}`
-
-{IF CRITICAL/HIGH findings:}
-**Action Required:** {count} priority items need remediation. Recommend running `[US] Update Skill` workflow.
-
-{IF MEDIUM/LOW only:}
-**Minor Drift:** Skill is functional but could benefit from updates. See report for details.
-
-{IF CLEAN:}
-**All Clear:** No drift detected. Skill accurately reflects current source code.
-
----
+### 5. Present Final Report Summary
 
-**Next Steps:**
-{IF findings exist:}
-1. **[US] Update Skill** — Automatically apply remediations from this drift report
-2. **Review report** — Manual review at `{outputFile}`
+Present a concise completion summary to the user conveying: the skill name, the **overall drift score** (CLEAN / MINOR / SIGNIFICANT / CRITICAL), the severity-count table (CRITICAL / HIGH / MEDIUM / LOW / Total), and the saved report path (`{outputFile}`). Close with the next-action recommendation matching the drift level:
 
-{IF CLEAN:}
-1. **No action needed** — Skill is current
-2. **[EX] Export Skill** — Skill is ready for distribution
-
----
+- **CRITICAL or HIGH findings** → action required: recommend running the `[US] Update Skill` workflow to apply the priority remediations; manual review at `{outputFile}` is the alternative.
+- **MEDIUM or LOW only** → minor drift: manual updates suffice, or run `[US] Update Skill` for automated remediation.
+- **CLEAN** → no action needed; the skill is current and ready for `[EX] Export Skill`.
 
-**Audit workflow complete.**"
+This summary reads as final but is **not** the terminal step — proceed to §6.
 
 ### Result Contract
 
@@ -182,7 +135,7 @@ SKF_AUDIT_RESULT_JSON: {"status":"success","skill_name":"{skill_name}","drift_sc
 
 Field rules: `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist (matches the frontmatter `nextWorkflow` set in §4), otherwise `null`. `audit_ref` carries the resolved value from step 1 §5b (`baseline_ref` when no upstream drift was detected, `latest_tag` or `remote_head` when the operator chose `[C] Checkout-and-audit-against-latest`).
 
-**HALT envelope mirror (headless only).** For every HARD HALT raised in this workflow (skill-not-found at init.md §1, forge-tier missing at §2, source-dir missing at §5, write-failed at §6, user-cancelled at any `[X]` selection), emit the same envelope shape on **stderr** with `status: "error"`, `drift_score: null` (or last known value if classification ran), `report_path: null` if the report write failed, `exit_code` matching the Exit Codes table, and `halt_reason` set to the failure class from the table (`"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`). This is the only signal a wrapping pipeline receives on failure — log it before exiting.
+**Hard-halt envelope (headless only).** Every hard halt emits this same envelope shape on **stderr** with `status: "error"` and the `exit_code` / `halt_reason` for its failure class (per SKILL.md → Exit Codes and Result Contract), produced at the halting site before exit — it is the only failure signal a wrapping pipeline receives, so log it before exiting. `drift_score` carries its last known value (`null` if classification never ran); `report_path` is `null` when the report write failed.
 
 **Post-audit hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it as:
 
@@ -194,5 +147,5 @@ where `{result_json_path}` is the per-run record path written above (`{forge_ver
 
 ### 6. Chain to Health Check
 
-ONLY WHEN the report has been written, presented, and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the user-facing summary reads as final.
+Only when the report has been written, presented, and the result contract saved do you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the user-facing summary reads as final.