bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -1,6 +1,21 @@
 ---
 nextStepFile: 'structural-diff.md'
+extractionPatternsData: 'skf-create-skill/references/extraction-patterns.md'
+tierDegradationRulesData: 'skf-create-skill/references/tier-degradation-rules.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+# This run's stage data folder: the scan list, the recipe runner's JSON and
+# the files of exports read by eye, which the snapshot is built from.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
+extractPublicApiProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+extractionSnapshotProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extraction-snapshot.py'
+  - '{project-root}/src/shared/scripts/skf-extraction-snapshot.py'
+# Every HALT after the [C] of upstream-checkout.md closes the private tree with it.
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -14,164 +29,137 @@ 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)
-- 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
+- Extract every file in the bounded scan list: a file skipped here makes step 3 flag its exports as false "removed" drift. The snapshot helper gives each file a status and says whether the snapshot is complete (§3), so never judge completeness by eye
+- At Forge, Forge+ and Deep the recipe runner extracts; read by eye only what it leaves (§3), using subprocess Pattern 2 (per-file deep analysis) when available to read those files; if unavailable, read them in the main thread file by file
 
 ## MANDATORY SEQUENCE
 
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. When `{source_tree}` is set (the [C] of `upstream-checkout.md`), first run `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` and go on whatever it prints. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "skill_name": "{skill_name}", "report_path": "{outputFile}"}`, adding `"path"` when the halt names one, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-audit-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Determine Extraction Strategy
 
+Label every export by the tool that produced it, never by the tier: an export an ast-grep rule matched is T1 with `extraction_method: ast-grep` and, as `ast_node_type`, the `kind` the matching pattern or recipe declares in `{extractionPatternsData}` (ast-grep's output does not report it); an export read by eye is T1-low with `extraction_method: source-read` and `ast_node_type: null`.
+
 Based on forge tier detected in Step 01:
 
 **Quick tier (no AST tools):**
 - Read source files via gh_bridge or direct file I/O
 - Extract export names by text pattern matching (function/class/type declarations)
-- Confidence label: T1-low
+- Label every export T1-low (read by eye, not matched by ast-grep) with `extraction_method: source-read` and `ast_node_type: null`
 
 **Forge tier (ast-grep available):**
-- Use ast_bridge to perform AST extraction per source file
-- Extract: export name, type (function/class/type/const), full signature, file path, line number
-- Confidence label: T1
+- The recipe runner extracts, as the **AST Extraction Protocol** in `{extractionPatternsData}` says: one `skf-extract-public-api.py --mode full` call over the bounded scan list from §2 (§3 gives the command) runs every recipe for the language in one process, reads only the files on the list, and keeps every match (`--head-cap 0`: a match past a cap would read as a removed export in step 3). While it can run, never run the recipes one at a time, batch them, or merge and dedupe their matches by hand
+- Each export it returns is T1 as it stands: its name (`$NAME`), type, file, line (`$NAME`'s line, as create-skill records it, not the match's first line, which a decorator or an `export` line can hold), `ast_node_type` and `signature`, the declaration on one line even when a formatter split its parameters over several
+- Read by eye only what the runner leaves (§3): the forms the recipes leave out (Known Limitation #11 in `{extractionPatternsData}`) when a file uses them, the names an entry point exports that no recipe found, and the files it could not parse or read. Label each export by the tool that produced it: T1 with `extraction_method: ast-grep` for a runner export, T1-low with `extraction_method: source-read` and `ast_node_type: null` for an export read by eye
+
+**Tier degradation handling (Forge/Forge+/Deep):** If the runner cannot run and ast-grep is unavailable, follow `{tierDegradationRulesData}` (AST Tool Unavailable, Per-File AST Failure) for the fallback and the user notification. A file ast-grep cannot parse falls back to reading that file only: its exports are T1-low with `extraction_method: source-read` and `ast_node_type: null`, and exports the runner matched in other files stay T1. Silent degradation is forbidden: the snapshot names each file's status, and the run names each file read after an ast-grep failure, and why (§3, §4); when ast-grep is unavailable for the whole run, every export is T1-low.
 
 **Forge+ tier (ast-grep + ccc available):**
-- Identical extraction to Forge tier: use ast_bridge for AST extraction per source file
-- Confidence label: T1
-- CCC rename detection available (see section 4b)
+- Identical extraction to Forge tier (the AST Extraction Protocol, above)
+- Label each export by tool, as at Forge tier
+- CCC rename detection runs in step 3 (`structural-diff.md` §1b), over the exports the diff reports removed
 
 **Deep tier (ast-grep + QMD available):**
-- Forge extraction (above) PLUS
-- Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
-- Confidence labels: T1 for structural, T2 for temporal context
+- Identical extraction to Forge tier, labeled by tool as at Forge tier
+- No QMD query at this step: step 4 (semantic diff) queries QMD itself
 
-**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`search`, `vector_search`) or `qmd` CLI. See `knowledge/tool-resolution.md`.
+**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge`, only when the runner cannot run (the protocol's **When the Runner Cannot Run**): the ast-grep MCP tool `find_code_by_rule` with a recipe and `output_format="json"`, or the protocol's CLI streaming template (`ast-grep scan -r {recipe_file} --json=stream`); `find_code` only as the fallback of Known Limitation #4. See `knowledge/tool-resolution.md`.
 
 ### 2. Build Bounded Scan List
 
-Audit-skill detects drift on files that were in scope during create-skill. The authoritative record of "what was in scope" is the provenance map loaded in step 1. Scan only those files — **audit-skill does NOT discover new files**. New-file detection is the responsibility of `skf-update-skill`, which maintains its own change manifest. To audit a project that has grown new files since creation, run update-skill first, then audit-skill.
+Audit-skill detects drift on files that were in scope during create-skill. The authoritative record of "what was in scope" is the provenance map loaded in step 1. Scan only those files: **audit-skill does NOT discover new files**. New-file detection is the responsibility of `skf-update-skill`, which maintains its own change manifest; public API a package's entry points export from files outside that list reaches the drift report through the runner's entry-point diff (§3), for update-skill's scope reconciliation. To audit a project that has grown new files since creation, run update-skill first, then audit-skill.
 
 **Why bounded:** without this constraint, files that were deliberately excluded by the original brief's scope patterns (test fixtures, vendored code, generated artifacts, demo code, unrelated modules) get scanned on every audit and their exports are flagged by step 3 structural diff as "added" — false-positive drift that obscures real structural changes.
 
-**If a provenance map was loaded in step 1** (normal mode):
+Every skill that reaches this step has a provenance map: step 1 stops a skill without one, and sends a compose-mode stack and a docs-only skill around this step.
 
-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:
+1. The **bounded scan list** is `{bounded_scan_files}`, the union of `entries[].source_file` and `file_entries[].source_file` that step 1 §4's `skf-load-provenance.py normalize` call returned. Do **not** re-walk the provenance map to rebuild it. Resolve `{extractionSnapshotHelper}` ← first existing path in `{extractionSnapshotProbeOrder}` (if none exists, HALT with **exit 3**, `halt_reason: "helper-missing"`, phase `re-index:scan-list`) and write the list where the runner reads it, from `{project-root}`:
 
-   "**Bounded scan:** {count} files from provenance map ({provenance_date})."
-
-**If degraded mode** (no provenance map was loaded — user confirmed `[D]egraded mode` at step 1 §4):
-
-1. Fall back to a source-tree scan: list all source files under `{source_root}` matching the project's primary language extensions (derive from `metadata.json.language` — e.g., `*.ts` / `*.tsx` for typescript, `*.py` for python, `*.rs` for rust, `*.go` for go).
-2. Apply generic exclusions: `**/tests/**`, `**/test/**`, `**/__tests__/**`, `*.test.*`, `*.spec.*`, `node_modules/**`, `dist/**`, `build/**`, `target/**`, `__pycache__/**`, `.venv/**`, `vendor/**`.
-3. Record `bounded_scan: false` and `bounded_scan_source: "source-tree-fallback"` in context.
-4. Report:
+   ```bash
+   mkdir -p "{auditDataFolder}"
+   uv run {extractionSnapshotHelper} scan-list "{provenanceMap}" -o "{auditDataFolder}/scan-files.json"
+   ```
 
-   "**Degraded mode scan:** {count} files from source tree (no provenance map — results may include files out of the original brief scope)."
+   It writes the same list as a JSON list of paths, the form the runner's `--files-from` reads: never retype it. If the folder or the file cannot be written (`status: "error"`), HALT with **exit 4**, `halt_reason: "write-failed"`, phase `re-index:scan-list`, `"path": "{auditDataFolder}"`.
+2. Files that existed at creation time but are now missing under `{source_root}` are **not** errors at this stage: keep them in the list. The snapshot marks them `missing`, and step 3 classifies their exports as DELETED.
+3. Report:
 
-**Count files to process** and proceed to section 3 with the resolved scan list.
+   "**Bounded scan:** {count} files from provenance map ({provenance_date})."
 
 ### 3. Extract Current Exports
 
-**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
-4. Returns structured findings to parent
-
-**If a file from the bounded scan list is missing on disk:** record `{file, exports: [], status: "missing"}` and continue — step 3 structural diff will classify exports previously at this path as DELETED.
+**1. The recipe runner** (Forge, Forge+ and Deep). Resolve `{extractPublicApiHelper}` ← first existing path in `{extractPublicApiProbeOrder}` and, from `{project-root}`, remove the JSON an earlier run left and run the runner over the scan list, so that a JSON at `-o` after the call is this call's:
 
-**If subprocess unavailable:** Perform extraction in main thread, processing each file sequentially.
-
-**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}",
-  "confidence_tier": "{tier}",
-  "source_root": "{source_path}",
-  "files_scanned": {count},
-  "bounded_scan": true|false,
-  "bounded_scan_source": "provenance-map|source-tree-fallback",
-  "exports": [
-    {
-      "name": "{export_name}",
-      "type": "function|class|type|const|interface",
-      "signature": "{full signature}",
-      "file": "{relative_path}",
-      "line": {line_number},
-      "confidence": "T1|T1-low|T2"
-    }
-  ]
-}
+```bash
+rm -f "{auditDataFolder}/extraction.json"
+uv run {extractPublicApiHelper} --mode full \
+    --source-root "{source_root}" \
+    --files-from "{auditDataFolder}/scan-files.json" \
+    --head-cap 0 \
+    [--timeout "{runner_timeout}"] \
+    -o "{auditDataFolder}/extraction.json"
 ```
 
-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:**
-
-Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`.
+The runner stops its ast-grep runs after 540 seconds and still writes its JSON (status `incomplete`), so give the command your shell tool's longest timeout; when that is under 10 minutes, pass `--timeout` as `{runner_timeout}`, a little under it (`100` under a two-minute limit). Never open the JSON: item 2's helper reads it and prints what this step acts on, its `status` included (never the exit code). At Quick tier no runner runs.
 
-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"`.
+**2. Build the snapshot.** Resolve `{extractionSnapshotHelper}` ← first existing path in `{extractionSnapshotProbeOrder}` (if none exists, HALT with **exit 3**, `halt_reason: "helper-missing"`, phase `re-index:snapshot`) and, from `{project-root}`, run:
 
-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:
-- When was this export first added?
-- Has it been modified recently?
-- What is its usage frequency across the codebase?
-- How does the current extraction compare to the previously compiled skill content?
-
-Append temporal metadata to each export in the snapshot.
-
-**If a matching extraction collection is found but empty** (pre-query probe reports `Files: 0 (updated never)` or an empty listing):
-Log: "QMD collection `{collection_name}` is registered but empty. Run `qmd update` to (re-)index `{collection.path}`, then re-audit. Temporal enrichment skipped for this run."
-Continue without T2 enrichment — the unpopulated collection is a setup gap, not an extraction failure. Step-04 will fall through to its direct-content fallback for semantic diff.
-
-**If no matching collection found in registry:**
-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.
+```bash
+uv run {extractionSnapshotHelper} build \
+    --source-root "{source_root}" \
+    --source-path "{source_path}" \
+    --tier "{tier}" \
+    --date "{timestamp}" \
+    --provenance-map "{provenanceMap}" \
+    [--extraction "{auditDataFolder}/extraction.json"] \
+    [--details "{auditDataFolder}/export-details-{n}.json"]... \
+    -o "{forge_version}/extraction-snapshot.json"
+```
 
-**If forge tier is Quick, Forge, or Forge+:**
-Skip this section. Temporal context requires Deep tier.
+Pass `--extraction` when the runner wrote its JSON, and one `--details` for each file item 3 wrote (none on the first build). The helper merges the runner's exports with the ones read by eye, gives every file on the list one status (`extracted`, `read-by-eye`, `hash-tracked` for a script, asset or doc only `file_entries[]` names, which step 3 compares by content hash, `missing`, `parse-failed` or `unread`) and prints one line. Act on its fields:
 
-### 4b. CCC Rename Detection (Forge+ and Deep with ccc)
+- **`runner_status` is `incomplete`** on the first build (an ast-grep run failed, or the time limit ran out): run item 1 once more, then this command again.
+- **`runner_status` is `no-ast-grep`, or null at Forge tier and above** (no JSON at `-o` after the call, or no runner candidate): the runner cannot run. Follow **When the Runner Cannot Run** in `{extractionPatternsData}` over the files in `to_read`, with this audit's parameters in place of create-skill's: the files in scope are those `to_read` lists, and their count is the Decision Tree's input (not create-skill's step 3 count). Keep every match, in every directory batch and every retry: pass `find_code_by_rule` a `max_results` that no recipe can reach (100000), and a Known Limitation #4 `find_code` retry the same, and drop the `| head -{HEAD_CAP}` from the CLI streaming template, in each batch, since a match past a cap reads as a removed export in step 3. Record each export as item 3 does, T1 with `ast-grep` for one the recipes match.
+- **`to_read` or `extraction_gaps` is not empty**, or a file uses the forms the recipes leave out: item 3 reads them, then run this command again with its details. When `complete` is still false, the files `to_read` lists could not be read: HALT with **exit 3**, `halt_reason: "source-unreadable"`, phase `re-index:snapshot`, naming them. Step 3 never reads an incomplete snapshot.
+- **`complete` is true** and nothing is left to read: go on to §4.
+- **`status: "error"`:** an `error` that starts `cannot write` is a failed write: HALT with **exit 4**, `halt_reason: "write-failed"`, phase `re-index:snapshot`, `"path": "{forge_version}/extraction-snapshot.json"`. Any other names a file this step wrote: fix it and run the command again.
+- **The command fails otherwise, or prints no JSON:** HALT with **exit 3**, `halt_reason: "helper-missing"`, phase `re-index:snapshot`, showing the first stderr line.
 
-**If `tools.ccc` is true in forge-tier.yaml:**
+**3. What the runner leaves.** Read by eye (T1-low, `extraction_method: source-read`, `ast_node_type: null`) only:
 
-For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
+- each file in `to_read`: a `parse-failed` one (its `issue`: a syntax error, where a recipe can miss an export; not UTF-8; unreadable), with the warning "**AST fallback:** ast-grep could not parse {file} ({issue}); its exports were read from source and labeled T1-low.", and an `unread` one (an incomplete run, or no runner: then every file, by text pattern matching at Quick tier);
+- each name in `extraction_gaps`, in its `file` (an entry point exports it, no recipe found it);
+- the forms the recipes leave out (Known Limitation #11 in `{extractionPatternsData}`) in a file that uses them.
 
-1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` — **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 5 "{export_name}"` (CLI) — to find candidate current locations. `ccc search` reads the index in the current working directory and has no project-selector flag (`--path` is a file-path glob filter *within* the index, and the result cap is `--limit`, not `--top`) — see `knowledge/ccc-bridge.md`.
-2. If CCC returns files containing the export name:
-   - Run ast-grep verification on each candidate file
-   - If verified at a new location: reclassify from "deleted" to "moved" with the new file:line reference
-   - This reduces false-positive structural drift findings where exports were relocated, not removed
-3. If CCC returns no results or verification fails: keep the "deleted" classification
+For each file to read, launch a subprocess (Pattern 2) that loads it and returns ONLY `{"files": [...], "exports": [...]}`, with no prose and no fences: `files` lists the file when the worker read the whole of it (also when it holds no export), and each export gives `name`, `type`, `signature` (the declaration on one line), `file` (relative to `{source_root}`, with forward slashes), `line` (`$NAME`'s line), `confidence: "T1-low"`, `extraction_method: "source-read"` and `ast_node_type: null`. Save each worker's JSON as it returned it, as `{auditDataFolder}/export-details-{n}.json` (`{n}` counting from 1), never merged by hand; without subprocesses, read the files in the main thread, one by one, and save one such file. A stack's export needs no library: the snapshot helper gives each one its file's `source_library` from the provenance map (the map `normalize` returns as `source_library_by_file`).
 
-CCC failures: skip rename detection silently, proceed with standard structural diff.
+**The snapshot.** The command writes `{forge_version}/extraction-snapshot.json`, which step 3 (`structural-diff.md`) reads directly: `exports[]` (for a stack, each with its file's `source_library`), `files[]` with each file's status, `files_by_status`, `counts` and `cap_hits` (§4) and `outside_scope` (step 6's Out-of-Scope New Public API table); `skf-extraction-snapshot.py --help` gives the full shape. Record the written path as `{extractionSnapshot}` in workflow context: step 3 passes it to the structural-diff helper.
 
-**If `tools.ccc` is false:** Skip this section silently.
+### 4. Validate Extraction Completeness
 
-### 5. Validate Extraction Completeness
+Take every value from the snapshot (`files_by_status`, `counts`, `cap_hits`) and the build's line (`ast_fallback_files`), never a recount:
 
 "**Extraction complete.**
 
 | Metric | Value |
 |--------|-------|
-| Scan mode | {bounded (provenance-map) / degraded (source-tree)} |
-| Files scanned | {count} |
-| Exports found | {total_exports} |
-| Functions | {function_count} |
-| Classes | {class_count} |
-| Types/Interfaces | {type_count} |
-| Constants | {const_count} |
-| Confidence | {T1/T1-low/T2} |
+| Files scanned | {files_scanned}: {extracted} extracted, {read-by-eye} read by eye, {hash-tracked} tracked by hash, {missing} missing |
+| Exports found | {counts.exports} |
+| By type | {each counts.by_type entry as `{type}` ×{count}} |
+| Labels | {t1_count} T1 (`ast-grep`), {t1_low_count} T1-low (`source-read`) |
+| AST fallback files | {count and names from `ast_fallback_files`, or none; n/a at Quick} |
+| Cap hits | {cap_hits, or none} |
 
 **Proceeding to structural comparison...**"
 
-### 6. Update Report and Auto-Proceed
+`ast_fallback_files` names the files read by eye after the runner could not parse or read them, not one read again for a gap or a Known Limitation #11 form (`all files (ast-grep unavailable)` when the runner could not run, none at Quick tier).
 
-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).
+### 5. Update Report and Auto-Proceed
 
+Update {outputFile} frontmatter: append `'re-index'` to `stepsCompleted` and set `ast_fallback_files` to the last build's `ast_fallback_files`. Once the snapshot helper reports `complete: true`, load, read fully, and execute `{nextStepFile}` (structural diff).

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

@@ -1,6 +1,17 @@
 ---
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 nextStepFile: 'health-check.md'
+# This run's stage data folder, where step 5 saved the findings and their
+# classification.
+auditDataFolder: '{forge_version}/.skf-audit/{timestamp}'
+# Resolve `{sourceTreeHelper}` to the first existing path. The Result
+# Contract removes the private tree the [C] of upstream-checkout.md read
+# the source in.
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
+# §2: this skill's renderer of the Out-of-Scope New Public API table, from the skill root.
+renderDriftTablesScript: 'scripts/render-drift-tables.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Drift report prose in {document_output_language}. -->
@@ -20,21 +31,38 @@ Finalize the drift report by completing the Audit Summary with calculated metric
 
 ## MANDATORY SEQUENCE
 
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. When `{source_tree}` is set (the [C] of `upstream-checkout.md`), first run `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` and go on whatever it prints. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "skill_name": "{skill_name}", "report_path": "{outputFile}", "drift_score": "<the saved classification's drift_score>"}`, adding `"path"` when the halt names one, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-audit-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Complete Audit Summary
 
 Update the ## Audit Summary section at the top of {outputFile} with final calculated values:
 
-- Fill in severity count table from Step 05 classification summary
-- Set overall drift score
-- Add total findings count
+- Fill in the severity count table from `{auditDataFolder}/severity.json`, the classification step 5 saved: `by_severity` for each level and `total_items` for **Total**
+- Set the overall drift score (its `drift_score`)
 - Include doc drift summary from `doc_drift_summary` context (set by step 5a):
-  - If `changed > 0`: "**Doc Drift:** {changed} of {total_tracked} tracked doc(s) have changed since compile. Consider re-running CS to update doc_sources."
+  - If `changed > 0`: "**Doc Drift:** {changed} of {total_tracked} tracked doc(s) have changed since compile." Then, for a docs-only skill (whose score these changes set): "Run `[US] Update Skill` to bring the skill up to them."; otherwise: "Consider re-running CS to update doc_sources."
   - If `fetch_failed > 0`: "{fetch_failed} doc URL(s) could not be reached during audit."
   - If `skipped_entirely`: no mention in summary (already noted in the doc drift section)
 
 ### 2. Generate Remediation Suggestions
 
-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.
+For each classified drift finding (`findings[]` of `{auditDataFolder}/severity.json`; one remediation may cover a rollup row of step 5's tables), 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.
+
+Rows of step 3's **Provenance label differences (not drift)** table are not findings: they get no remediation row and do not count toward the Workflow Recommendation.
+
+**Public API outside the skill's scope.** Step 2's snapshot lists in `outside_scope` the files the skill does not cover whose public API a package entry point exports: the recipe runner's entry-point diff found them, so nothing here is judged by eye. Render their subsection from the snapshot, never by hand. `{renderDriftTablesScript}` resolves relative to the skill root; from `{project-root}`, run:
+
+```bash
+uv run {renderDriftTablesScript} outside-scope "{forge_version}/extraction-snapshot.json"
+```
+
+Paste its output unchanged under Remediation Suggestions, where the template below shows it (nothing when it prints nothing: `outside_scope` is empty, as at Quick tier). update-skill's scope reconciliation (`skf-provenance-gap-dispatch.py`) reads that subsection from the newest drift report and asks whether to bring each path into scope. A compose-mode stack and a docs-only skill have no snapshot: skip the command. When the command exits non-zero, its JSON `error`, else its first stderr line, says what it could not read: write `Out-of-Scope New Public API not rendered: {error}` in place of its output and go on.
 
 Append to {outputFile}:
 
@@ -59,49 +87,61 @@ Append to {outputFile}:
 |---|---------|-------------|
 | 1 | {finding} | {specific action} |
 
+{what the outside-scope command printed, unchanged}
+
 ### Workflow Recommendation
 
 {IF any CRITICAL or HIGH findings:}
 **Recommended:** Run `[US] Update Skill` workflow to apply priority remediations automatically.
 
-{IF `audit_ref != baseline_ref` (source version bump detected in step 1 §5b):}
-**Version preservation (non-destructive).** `update-skill` preserves the prior version at `{skill_group}/{baseline_version}/` unchanged and writes the new skill to `{skill_group}/{audit_version}/` (see `skf-update-skill/references/merge.md` §6b, which creates the new version directory and leaves the previous one on disk). The `active` symlink at `{skill_group}/active` repoints to the new version (see `skf-update-skill/references/write.md` §5b). On the next export, the prior version's export-manifest entry transitions to `status: archived` — files retained for rollback (see `skf-export-skill/references/update-context.md`). Do **not** recommend `skf-drop-skill` + `skf-create-skill` for a version bump — that destroys the prior version's artifacts.
+{IF the frontmatter's `upstream_moved` is true:}
+**Upstream moved.** The skill is built from `{baseline_ref}` and upstream is now at `{upstream_ref}`{; this audit read `{upstream_ref}`, when `audit_ref_source` is `checkout-latest`; this audit read the baseline, otherwise}. Run `[US] Update Skill` with `--target-ref {upstream_ref}`, so the update compares the ref upstream moved to rather than the one the skill is pinned to.
+
+{IF the frontmatter's `audit_ref_source` is `checkout-latest` (the [C] of `upstream-checkout.md` audited a newer upstream ref than the baseline) or its `upstream_moved` is true:}
+**Version preservation (non-destructive).** `update-skill` keeps the audited version (`{audited_version}`) unchanged, writes the new version in a folder of its own beside it (see `skf-update-skill/references/merge.md` §6b, which leaves the previous version on disk) and repoints the skill's `active` link at it (see `skf-update-skill/references/write.md` §5b). On the next export, the prior version's export-manifest entry transitions to `status: archived`, its files kept for rollback (see `skf-export-skill/references/update-context.md`). Do **not** recommend `skf-drop-skill` + `skf-create-skill` for a version bump: that destroys the prior version's artifacts.
 
-**Surface new entry points for the brief gate.** If the audit observed new top-level modules, renamed package trees, or new public entry points (new `__init__.py`, `index.ts`, `lib.rs`, or equivalent) that were not in the brief's original scope, call them out here. `update-skill` step 2 §1b detects new candidate files via heuristic and prompts `[P]romote` / `[S]kip` / `[U]pdate-brief`; surfacing them in advance makes that gate faster to resolve, or lets the user refine scope via `skf-brief-skill` before running update-skill.
+{IF the Out-of-Scope New Public API table above has rows:}
+**New public API outside the scope.** update-skill's scope reconciliation (detect-changes §1c) offers each path to bring into the brief's scope; review them there, or refine the scope with `skf-brief-skill` before running update-skill.
 
 {IF only MEDIUM or LOW findings:}
 **Optional:** Minor drift detected. Manual updates sufficient, or run `[US] Update Skill` for automated remediation.
 
 {IF CLEAN:}
-**No action needed.** Skill is current with source code.
+**No drift against `{audit_ref}`.** The skill matches the source at `{audit_ref}` (`{audit_commit_short}`){; upstream has not moved past `{baseline_ref}`, when `upstream_moved` is false; upstream was not checked ({upstream_fetch}), when it is null; and when it is true, the Upstream moved recommendation above applies}.
 ```
 
 ### 3. Add Provenance Section
 
-Append to {outputFile}:
+Build the section from the frontmatter of {outputFile}, where step 1 §6, step 2 §5 and step 3 §6 recorded each value as it was known, not from values held in the conversation. Append to {outputFile}:
 
 ```markdown
 ## Provenance
 
 | Field | Value |
 |-------|-------|
-| **Audit Date** | {current_date} |
+| **Audit Date** | {date} |
 | **Audited By** | Ferris (Audit mode) |
-| **Forge Tier** | {tier} |
-| **Tools Used** | {tool_list based on tier} |
-| **Source Path** | {source_path} |
+| **Forge Tier** | {forge_tier} |
+| **Tools Used** | {tool_list based on forge_tier} |
+| **Source Path** | {source_path}{; read from the private tree `{source_tree}`, when set} |
 | **Skill Path** | {skill_path} |
-| **Provenance Map** | {provenance_map_path} |
-| **Provenance Age** | {days} days |
-| **Mode** | {normal / degraded} |
+| **Audited Version** | `{audited_version}` ({audited_version_reason}){; the export manifest names `{manifest_version}`, when set} |
+| **Provenance Map** | {provenance_map} |
+| **Provenance Age** | {provenance_age_days} days (generated {provenance_generated_at}) |
+| **AST fallback files** | {`ast_fallback_files`, or none; n/a at Quick} |
+| **Applied Transforms** | {each `applied_transforms` entry as `{transform}` ×{count}, or none} |
 | **Baseline Ref / Commit** | `{baseline_ref}` @ `{baseline_commit_short}` |
 | **Audit Ref / Commit** | `{audit_ref}` @ `{audit_commit_short}` ({audit_ref_source}) |
-| **Upstream Latest** | `{latest_tag or remote_head or "(not fetched)"}` |
+| **Upstream Latest** | `{latest_tag or remote_head or "(not fetched)"}` (fetch: {upstream_fetch}) |
+| **Upstream Moved** | {upstream_moved}{: to `{upstream_ref}`, when true} |
+| **Stage Data** | `{auditDataFolder}/`: the JSON this run saved and classified (the structural diff, the constituents' freshness or the documents' comparison, the findings and their classification) |
 
 **Confidence Legend:**
-- **T1:** AST extraction — high reliability, structural truth
-- **T1-low:** Text pattern matching — moderate reliability
-- **T2:** QMD temporal context — evidence-backed semantic analysis
+- **T1:** an ast-grep match (`extraction_method: ast-grep`) at any tier: high reliability, structural truth
+- **T1-low:** read by eye (`extraction_method: source-read`) at any tier: moderate reliability
+- **T1-low-fallback:** Deep-tier semantic diff read directly from the skill's docs and the current source because the QMD collection was empty: moderate reliability
+- **T2:** Deep-tier semantic diff: a claim the skill's QMD collection holds, checked against the current source line it cites: evidence-backed semantic analysis
+- **T3:** external documentation reference: variable reliability, secondary source
 ```
 
 ### 4. Update Report Frontmatter
@@ -109,43 +149,66 @@ Append to {outputFile}:
 Update {outputFile} frontmatter:
 - Append `'report'` to `stepsCompleted`
 - 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
+- Set `nextWorkflow` to `'update-skill'` when the saved classification's `by_severity.CRITICAL` or `by_severity.HIGH` is above 0, or when the frontmatter's `upstream_moved` is true, otherwise leave it empty
 
-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`.
+If finalizing the report fails (read-only mount, disk full, permissions denied) → HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:write`, `"path": "{outputFile}"`, and no `report_path` in the payload.
 
 ### 5. Present Final Report Summary
 
 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:
 
 - **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.
+- **The frontmatter's `upstream_moved` is true**, whatever the drift score → recommend `[US] Update Skill` with `--target-ref {upstream_ref}`, naming `{baseline_ref}` and `{upstream_ref}`: update-skill otherwise compares the ref the skill is pinned to, not the one upstream moved to. `{upstream_ref}` is the newer tag when upstream released one (`--target-ref {latest_tag}`), and for a skill built from the default branch it is `HEAD` (`--target-ref HEAD`).
 - **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`.
+- **CLEAN, and `upstream_moved` is not true** → no action needed: the skill matches `{audit_ref}` and is ready for `[EX] Export Skill`.
 
 This summary reads as final but is **not** the terminal step — proceed to §6.
 
 ### Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/audit-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the drift report path in `outputs`; include `drift_count` and `severity` (CLEAN/MINOR/SIGNIFICANT/CRITICAL) in `summary`.
+**Remove the private source tree first.** When `{source_tree}` is set (the [C] of `upstream-checkout.md` read the source there), no later step reads the source: resolve `{sourceTreeHelper}` ← first existing path in `{sourceTreeProbeOrder}` and, from `{project-root}`, run `uv run {sourceTreeHelper} close --tree "{source_tree}"`. Go on whatever it prints. On `left` or `refused`, a command that fails or prints no JSON, or no candidate, record `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "source_tree_not_removed: {source_tree}"` (a later SKF run removes it once it is seven days old). Then set `{source_tree}` to null.
+
+The shared emitter writes the result contract (per `shared/references/output-contract-schema.md`, which resolves relative to the SKF module root: `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development) and prints the `SKF_AUDIT_RESULT_JSON` envelope; this step stages their content, every value from the drift report's frontmatter and the classification step 5 saved. Write `{run_dir}/result-context.json`:
+
+```json
+{
+  "status": "success",
+  "skill_name": "{skill_name}",
+  "drift_score": "<drift_score>",
+  "report_path": "{outputFile}",
+  "next_workflow": <next_workflow>,
+  "audit_ref": "<audit_ref>",
+  "upstream_moved": <upstream_moved>,
+  "upstream_ref": <upstream_ref>,
+  "result_contract": {
+    "skill": "skf-audit-skill",
+    "status": "success",
+    "outputs": [{"type": "report", "path": "{outputFile}"}],
+    "summary": {"drift_count": <total_findings>, "severity": "<drift_score>", "next_workflow": <next_workflow>,
+                "audit_ref": "<audit_ref>", "upstream_moved": <upstream_moved>, "upstream_ref": <upstream_ref>}
+  }
+}
+```
 
-**Stdout envelope (headless only).** When `{headless_mode}` is true, emit a single-line JSON envelope to **stdout** immediately after the on-disk result contract is written, so chaining workflows can consume `drift_score`, `report_path`, and `next_workflow` from a captured stdout line without polling the filesystem. The shape matches the "Result Contract (Headless)" section in SKILL.md verbatim:
+When On Activation step 3 fell back to the bundled `customize.toml`, add `"customization_resolver_unavailable": "<the reason>"`, the one-line reason On Activation kept with each `"` and `\` escaped: the emitter turns it into a warning. `<drift_score>` and `<total_findings>` are the `drift_score` and `total_findings` of `{auditDataFolder}/severity.json`: `drift_count` (the saved classification's `total_findings`: one per finding, never a label difference) and `severity` (its `drift_score`: CLEAN/MINOR/SIGNIFICANT/CRITICAL). `<next_workflow>` is `"update-skill"` exactly when §4 set the frontmatter's `nextWorkflow` (CRITICAL or HIGH findings, or `upstream_moved` true), else JSON `null`. `audit_ref`, `upstream_moved` and `upstream_ref` are the frontmatter's, resolved at step 1 §5b and, when upstream moved, by `upstream-checkout.md` (`audit_ref` is `baseline_ref` when the audit stayed on the baseline, `upstream_ref` when the operator chose `[C]`): `<upstream_moved>` is JSON `true` when upstream moved, `false` when the check found it unchanged and `null` when the check was skipped or failed, and `<upstream_ref>` is the ref upstream moved to, as a JSON string, when `upstream_moved` is true, else `null`. Then run, in every mode:
 
-```
-SKF_AUDIT_RESULT_JSON: {"status":"success","skill_name":"{skill_name}","drift_score":"{CLEAN|MINOR|SIGNIFICANT|CRITICAL}","report_path":"{outputFile}","next_workflow":"{update-skill|null}","audit_ref":"{audit_ref}","exit_code":0,"halt_reason":null}
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-audit-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
-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`).
+It writes `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and its `audit-skill-result-latest.json` copy (stable path for pipeline consumers: a copy, not a symlink), stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both, and prints the `SKF_AUDIT_RESULT_JSON:` line on stdout. When `{headless_mode}` is true, display the line verbatim: chaining workflows read `drift_score`, `report_path`, `next_workflow`, `upstream_moved` and `upstream_ref` from it without polling the filesystem. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HALT with **exit 4**, `halt_reason: "write-failed"`, phase `report:result-contract`: the run's result contract could not be written.
 
-**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.
+**Hard-halt envelope (headless only).** Every hard halt prints its envelope through the emitter on **stderr** with `status: "error"` and the `exit_code` / `halt_reason` for its failure class, as each step's **Halt envelope** paragraph shows: it is the only failure signal a wrapping pipeline receives. `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:
+**Post-audit hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it from `{project-root}` as:
 
 ```bash
 {onCompleteCommand} --result-path={result_json_path}
 ```
 
-where `{result_json_path}` is the per-run record path written above (`{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json`). Log success/failure to `workflow_warnings[]` — never fail the workflow on a hook error. The hook runs after the result contract is finalized so notifiers, ticket-tracker integrations, or downstream pipelines see a complete record. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+where `{result_json_path}` is the envelope's `result_path`, the per-run record the emitter wrote (skip the hook when it is null). When the hook fails, tell the user it failed and why, and go on: never fail the workflow on a hook error. The hook runs after the result contract is finalized so notifiers, ticket-tracker integrations, or downstream pipelines see a complete record. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
 ### 6. Chain to Health Check
 
-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.
+Only when the report has been written, presented, and the result contract saved, delete the run folder, whose decisions, warnings and payloads the run no longer needs: `rm -rf "{run_dir}"`. 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.