bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-update-skill/references/detect-changes.md

@@ -1,45 +1,52 @@
 ---
 nextStepFile: 're-extract.md'
 noChangeReportFile: 'report.md'
-# Resolve `{hashContentHelper}` to the first existing path; HALT if neither
-# candidate exists — §1b and §Category D rely on the helper for deterministic
-# SHA-256 hashing (file-read + size + line-count) and provenance comparison
-# (UNCHANGED / MODIFIED_FILE / DELETED_FILE classification). Falling back to
-# prose-driven hashing would lose hash stability across runs.
+extractionPatternsData: 'skf-create-skill/references/extraction-patterns.md'
+# `{hashContentHelper}`: Category D's hash comparison. HALT if neither exists.
 hashContentProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
   - '{project-root}/src/shared/scripts/skf-hash-content.py'
-# Resolve `{buildChangeManifestHelper}` to the first existing path; HALT if
-# neither candidate exists. §3 uses `build` to aggregate Category A/B/C/D
-# results into the unified manifest; §2.2 uses `deletion-ratio` to compute
-# the major-version trigger. Falling back to prose-driven count rollups
-# would let the LLM drift on manifest shape across runs.
+# `{buildChangeManifestHelper}`: §3's `build` (and §1's for a docs-only
+# skill), §2.2's `deletion-ratio`, Category B's `baseline-gaps` and Category
+# C's `rename-candidates`. HALT if neither exists.
 buildChangeManifestProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-build-change-manifest.py'
   - '{project-root}/src/shared/scripts/skf-build-change-manifest.py'
-# Resolve `{provenanceGapDispatchHelper}` to the first existing path; HALT
-# if neither exists. §1c uses it to discover the latest drift report, parse
-# Out-of-Scope candidates, and classify them against brief.scope.amendments[]
-# in one call. Falling back to prose-driven markdown parsing would let
-# report-format drift produce silent skips of out-of-scope candidates.
+# `{provenanceGapDispatchHelper}`: §1c's drift-report candidates. HALT if
+# neither exists.
 provenanceGapDispatchProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
   - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
-# Resolve `{detectScriptsAssetsHelper}` to the first existing path; HALT if
-# neither candidate exists. §Category D uses `detect` to walk the current
-# source tree for scripts/assets (directory conventions, shebang signals,
-# `package.json` `bin` entry-points, asset filename patterns) so NEW_FILE
-# detection mirrors create-skill §4c exactly. Falling back to prose-driven
-# file walking would let the LLM drift on the heuristic list and miss new
-# scripts/assets at deeper directory depths — and on installed modules
-# (no `src/` tree) the LLM would otherwise guess a non-existent path.
+# `{detectScriptsAssetsHelper}`: Category D's script and asset walk, the
+# detector create-skill runs, over the whole source. HALT if neither exists.
 detectScriptsAssetsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
   - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
-# `{newFileDiffHelper}` derives NEW_FILE (inventory source_files not in the
-# provenance map, minus [MANUAL] paths) — the set-difference §Category D would
-# otherwise ask the model to compute by hand. Per-skill helper, always bundled.
+# `{newFileDiffHelper}`: Category D's NEW_FILE set difference, kept to the
+# skill brief's scope, bundled with this skill.
 newFileDiffHelper: 'scripts/skf-new-file-diff.py'
+# `{resolveAuthoritativeFilesHelper}`: §1b's mirror. HALT if neither exists.
+resolveAuthoritativeFilesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-authoritative-files.py'
+  - '{project-root}/src/shared/scripts/skf-resolve-authoritative-files.py'
+# `{classifyChangedFilesHelper}`: §2.1 Category A. HALT if neither exists.
+classifyChangedFilesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-classify-changed-files.py'
+  - '{project-root}/src/shared/scripts/skf-classify-changed-files.py'
+# `{extractPublicApiHelper}`: §2.1 Category B's recipe runner. If neither
+# exists, read the files by eye.
+extractPublicApiProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+# `{structuralDiffHelper}`: §2.1 Category B's diff. HALT if neither exists.
+structuralDiffProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-structural-diff.py'
+  - '{project-root}/src/shared/scripts/skf-structural-diff.py'
+# `{compareDocHashesHelper}`: §1's docs-only branch, the doc-hash comparison
+# audit-skill's doc-drift step runs. HALT if neither exists.
+compareDocHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -52,60 +59,51 @@ Compare current source code state against the provenance map to produce a comple
 
 ## Rules
 
-- Focus only on detecting and classifying changes — do not extract or merge
-- Use subprocess Pattern 4 (parallel) when available; if unavailable, compare sequentially
+- Focus only on detecting and classifying changes: extract only what Category B's diff reads (step 3 reuses it), and merge nothing
+- Run §2.1's categories in order, A, then B, then C: each reads the one before. Fan Category B's reading out in parallel batches (Pattern 4) only when its file list is long
 
 ## Steps
 
-### 0. Check for Test Report Input (Gap-Driven Mode)
+The helpers below and step 3 pass their JSON to each other through `{run_dir}`, the run folder SKILL.md On Activation created.
 
-**If `update_mode == "gap-driven"` (set in step 1 via `--from-test-report`):**
+**Halt procedure.** Every HALT in this step names its payload (`status`, `phase`, `path` when it has one, and `reason`), displays its message, and then runs, from `{project-root}`, the halt helper SKILL.md On Activation resolved. Nothing this step wrote is undone: it writes the skill brief only with a person's decision or a headless deferral (§1b, §1c), both of which stand, and the read-only modes write a copy in `{run_dir}` instead.
 
-Load the test report at `{test_report_path}` and extract findings:
+```bash
+uv run {runStateHelper} halt --run-dir "{run_dir}" \
+    [--tree "{source_tree}"] \
+    [--lock "{forge_data_folder}/{skill_name}/.skf-update.lock" --owner "{lock_owner}"] \
+    [--emit] <<'SKF_JSON'
+{"status": "<status>", "phase": "<phase>", "path": "<path; leave the key out when the halt names none>", "reason": "<reason>", "skill_name": "{skill_name}", "version": "<the metadata.json version>", "previous_version": "<the same>", "update_mode": "<normal or degraded>"}
+SKF_JSON
+```
 
-1. Read the **Gap Report** section — each gap entry has severity, category, and description
-2. Read the **Coverage Analysis** section — each per-export row has documented/missing/mismatch status
-3. Translate findings into change manifest format:
+Pass `--tree` when init.md §6b bound `{source_tree}`, `--lock` and `--owner` when init.md §1b bound `{lock_owner}` (the read-only modes take no lock), and `--emit` in `{headless_mode}`. It removes the private source tree, releases the run lock (never one another run holds) and, with `--emit`, prints the halt's `SKF_UPDATE_RESULT_JSON:` line through the shared emitter, which adds the decisions recorded so far, the `error` object and a warning for each step the helper could not finish (`source-tree-not-removed`, `run-lock-not-released`); it never stops on a result. Write each payload value as a JSON string: escape `"` and `\`, and write every path with `/`. Display the line it prints verbatim. When it exits 1 and its message names the payload, fix the payload once and run it again, which redoes nothing already done; when it still fails or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing. A HALT that names no payload (a helper the frontmatter says to HALT without, resolving to no path) takes `status: "blocked"`, `phase: "detect-changes:<the helper's file name>"` and `reason: "<the helper's file name> is missing; re-install SKF"`.
 
-| Gap Severity | Gap Type | Change Category |
-|-------------|----------|-----------------|
-| Critical | Missing export documentation | NEW_EXPORT (undocumented public API) — unless the remediation says the export is internal / out of scope; then DELETED_EXPORT (rescope), see rule R1 |
-| High | Signature mismatch | MODIFIED_EXPORT (signature needs update) |
-| Medium | Missing type/interface docs | NEW_EXPORT (undocumented type) |
-| Medium | Stale documentation | MODIFIED_EXPORT (docs reference removed export) |
-| Critical/Medium | Coverage gap whose remediation is **removal** (export is internal, `#[doc(hidden)]`, or explicitly out of scope) | DELETED_EXPORT (rescope) — see rule R1 |
-| Medium/High | Structural / coherence drift (output file only, no source change) | STRUCTURAL_FIX — see rule R2 |
-| Medium | Export documented in SKILL.md/references but **missing from the provenance-map** | NEW_EXPORT (provenance-completeness) — see rule R3 |
-| Low | Missing metadata/examples | metadata update — see rule R4 |
+The halt leaves `{run_dir}` in place, with the decisions the gates below recorded before it.
 
-**Translation rules (referenced by the table above):**
+**Warnings go to the run log.** Record each warning this step adds to `warnings[]` the moment it is raised: write its text to `{run_dir}/warning.txt` with a file write (a warning can hold quotes, `$` or backticks), then, from `{project-root}`, run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`. The halt line and the result line read warnings only from `{run_dir}/warnings.jsonl`.
+
+### 1. Scan Current Source State
 
-- **R1 — DELETED_EXPORT (rescope).** A coverage gap is a rescope only when its remediation text names removal (`rescope`, `remove from surface`, `out of scope`) or the export is upstream `#[doc(hidden)]` / internal. Default a bare "missing export documentation" gap to NEW_EXPORT (document it); choose rescope only on that explicit signal. **Interactive:** prompt per qualifying gap — "[D] Document the export / [R] Rescope (remove from the public surface)". **Headless:** default to **document** (NEW_EXPORT); choose rescope only when the remediation explicitly says removal *and* the export is internal/`#[doc(hidden)]`. A rescope is honest only if the reduction is expressed in the brief's scope: append a `scope.amendments[]` entry (`category: "scope-expansion"`, `action: "excluded"`) **and** add the export's source path to `brief.scope.exclude`, then route the entry to merge Priority 1 (removal) so step 4/6 remove it and recompute stats from the amended scope. Never close a coverage gap by editing `metadata.stats` to equal the documented count — that is denominator deflation and `skf-test-skill` will reject it.
-- **R2 — STRUCTURAL_FIX.** A coherence finding from `skf-scan-skill-md-structure.py` (e.g., `table_drift`, `unbalanced_fences`, a broken intra-skill anchor) that touches the generated output file only, with no source change and no provenance entry change. Carries `remediation` text describing the surgical markdown edit. Routes to merge Priority 8 (generated-markdown edit only); it never adds, modifies, or removes a provenance `entries[]` row.
-- **R3 — provenance-completeness.** An export documented in SKILL.md/`references/` but absent from the provenance-map. These are documented-and-known, so `unknown` is never correct: route to re-extract §0a source resolution **regardless of severity**, gated only on `source_root` being pinned and readable (see re-extract.md §0).
-- **R4 — metadata update.** A metadata-coherence patch that changes no export's source (e.g., reconcile a divergent `stats` count). Routes to merge Priority 8b and is applied by write.md §2 *before* the automatic stat recount (see merge.md §3 / write.md §2).
+**A docs-only skill** (`source_type: "docs-only"` in the brief or metadata.json) has no source tree for §2's categories to read: its drift is in the documents `doc_sources` records with their hashes. Compare them with the helper audit-skill's doc-drift step runs: resolve `{compareDocHashesHelper}` ← first existing path in `{compareDocHashesProbeOrder}` and, from `{project-root}`, run:
+
+```bash
+uv run {compareDocHashesHelper} compare-hashes "{skill_package}/metadata.json" > "{run_dir}/doc-hashes.json"
+```
 
-4. Build the change manifest from translated gaps — no file-level timestamp comparison needed since source hasn't changed. For each manifest entry, propagate these fields from the test report finding so step 3 can resolve the export against live source:
+It fetches each URL with a recorded hash and buckets it `changed`, `unchanged`, `fetch_failed` or `skipped_null_hash`, with `stats`: never fetch or hash a URL by hand. On exit 2, no JSON, or no candidate resolves, HALT with status `blocked` (halt procedure: `phase: "detect-changes:doc-hashes"`, `path: "{skill_package}/metadata.json"`, `reason: "<its error, or skf-detect-docs.py is missing; re-install SKF>"`). Add `doc-fetch-failed: {url} ({reason})` to `warnings[]` for each `fetch_failed` entry (a document that could not be read is not drift), `doc-not-hashed: {url}` for each `skipped_null_hash` entry, and `doc-drift-not-checked: metadata.json records no doc_sources` when `stats.total_tracked` is 0. Then skip §1b to §2.2 and §3's build, and have the helper write the change manifest from that output, never by hand:
 
-   - **`severity`** — the Gap Report severity (`Critical`, `High`, `Medium`, `Low`, `Info`). Step-03 §0 and step 6 §3 gate the null-citation fallback on severity: Critical/High gaps must produce AST provenance, Medium/Low/Info gaps may degrade to `unknown`.
-   - **`source_citation: {file, line}`** — populated only when the finding's `Source:` field is a `file:line` pair (e.g., a Gap Report row that cites `packages/utils/src/builder-utils.ts:33`). Step-03 §0 uses this field to perform a live spot-check against source rather than flagging the export as `unknown`. Omit when the `Source:` field is a region reference (e.g., `@storybook/addon-docs control primitives`) or missing.
-   - **`remediation_paths: [path, ...]`** — path-like tokens extracted from the finding's `Remediation:` text: any substring matching a recognized source file extension (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `.rs`, `.go`, `.java`, `.rb`, `.c`, `.h`, `.cpp`), or a directory/glob fragment under the project's source root. Include every matching path verbatim. Step-03 §0a uses this list as the source set for its Targeted Re-Extraction Branch when `source_citation` is absent and severity is Critical/High. Omit the field when the Remediation text names no paths — the entry then falls through to `unknown` or to §0a's halt, depending on severity.
-   - **`change_category`** — the Change Category resolved from the table above (`NEW_EXPORT`, `MODIFIED_EXPORT`, `DELETED_EXPORT`, `STRUCTURAL_FIX`, or `metadata update`). Step 3 §1a partitions on this field; merge.md §3 dispatches on it.
-   - **`remediation`** — the finding's full `Remediation:` text, verbatim. Required for `STRUCTURAL_FIX` (the surgical markdown edit), `metadata update` (the patch description), and `DELETED_EXPORT` rescope (the removal rationale recorded in the `scope.amendments[]` entry). For `NEW_EXPORT` / `MODIFIED_EXPORT` it is informational.
-   - **`provenance_completeness: true`** — set on a `NEW_EXPORT` entry whose gap is rule R3 (documented in SKILL.md/`references/` but absent from the provenance-map). Step 3 §0 routes these to §0a regardless of severity.
-5. Set `gap_count` from the total number of translated entries
-6. **Skip to section 5** (Display Change Summary) with the gap-derived manifest
+```bash
+uv run {buildChangeManifestHelper} build --doc-hashes "{run_dir}/doc-hashes.json" > "{run_dir}/change-manifest.json"
+```
 
-"**Gap-driven update mode.** Translating {gap_count} test report findings into change manifest — source drift detection skipped."
+It writes `{"mode": "docs-only", "no_changes", "changed_urls", "fetch_failed", "counts": {"docs_changed", "docs_fetch_failed"}}`. On exit 1 or no JSON: HALT with status `blocked` (halt procedure: `phase: "detect-changes:change-manifest"`, its stderr as `reason`). §4 then reports no change only when every hashed document matches (`changed_urls` is empty); otherwise §5 routes to step 3, whose §1 re-fetches the changed URLs, and step 5 records their new hashes from `{run_dir}/doc-hashes.json`.
 
-**If normal mode:** Continue with source drift detection below.
+`{source_root}` is the tree init.md §6b prepared at `{target_commit}` when `{source_tree_status}` is `ready` or `offline`, and otherwise the skill's local source. **If `{source_tree_status}` is `ready` or `offline` and `{source_root}` no longer exists**, HALT with status `blocked` per SKILL.md's source-tree rule (halt procedure: `phase: "detect-changes:source-tree-missing"`, `path: "{source_root}"`, `reason: "source tree {source_root} disappeared mid-run"`): reading a missing tree would report every file deleted. §2.1's helpers walk `{source_root}` themselves: build no file inventory here.
 
-### 1. Scan Current Source State
+**The brief this run reads.** Bind `{brief_path}` ← `{forge_data_folder}/{skill_name}/skill-brief.yaml`. When `detect_only_mode` or `dry_run_mode` is true and that file exists, copy it to `{run_dir}/skill-brief.yaml` and bind `{brief_path}` to the copy: §1b and §1c write each decision there, Category A reads the scope from there, and the brief itself stays as it was. Each amendment a read-only run writes to the copy is a proposed one: add `proposed-amendment: {action} {path} ({category}); not written: {--dry-run or --detect-only}` to `warnings[]` as you write it, and step 6 lists them with the change manifest.
 
-Read the source directory at `{source_root}` and build a current file inventory:
-- For each source file: record path, file size, last modified timestamp
-- Focus on file types relevant to the skill (from provenance map file patterns)
-- Exclude non-source files (node_modules, build artifacts, etc.)
+**The scope type this run reads.** Bind `{scope_type}` ← the `scope_type` metadata.json records (init.md §2), else the `scope.type` of `{brief_path}` when that file exists and names one: a skill whose metadata.json records no scope type updates under its brief's. Category B's runner takes it as `--scope-type` and writes it to `{run_dir}/extraction.json` as `scope.type`, where step 3's `records` and step 5's `apply` read it: under `public-api`, a normal-mode update neither documents nor adds to the provenance map a new export off the runner's public surface (re-extract.md §4, write.md §3).
 
 ### 1b. Discovered Authoritative Files Protocol (Mirror)
 
@@ -113,26 +111,30 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Skip this section entirely if:**
 
-- `update_mode == "gap-driven"` (source hasn't drifted — we're verifying test report findings, not discovering new files), OR
-- `metadata.json.source_type == "docs-only"` (no source tree to scan)
+- `metadata.json.source_type == "docs-only"` (no source tree to scan), OR
+- `{brief_path}` does not exist (a skill built without a brief, such as a quick skill): there is no scope or amendment to match a document against, and no brief to amend. Display `"Authoritative files mirror: skipped (no skill brief)."`
 
-**Procedure (identical heuristics to create-skill §2a):**
+**Procedure (the helper and buckets of create-skill §2a):**
 
-1. **Walk the source tree.** Match file basenames against the heuristic list case-insensitively:
-   - `llms.txt`, `llms-full.txt`
-   - `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `COPILOT.md`
-   - `.cursorrules`, `.windsurfrules`, `.clinerules`
+1. **Scan, classify and hash in one call.** Resolve `{resolveAuthoritativeFilesHelper}` ← first existing path in `{resolveAuthoritativeFilesProbeOrder}` and, from `{project-root}`, run:
 
-2. **Cross-reference with provenance map.** For each match:
-   - **Already in provenance map** (`entries[].source_file` or `file_entries[].source_file` contains this path): the file is already tracked. §2 will detect any drift in the normal flow. No action in §1b.
-   - **Not in provenance map:** continue to amendment check.
+   ```bash
+   uv run {resolveAuthoritativeFilesHelper} resolve \
+       --source-root "{source_root}" \
+       --brief "{brief_path}" \
+       [--provenance-map "{provenance_map_path}"]
+   ```
+
+   Pass `--provenance-map` whenever init.md §4 found one. It finds the files create-skill §2a looks for (`llms.txt`, `AGENTS.md`, `.cursorrules` and the like), sorts each into a bucket below, and hashes and previews each one a decision needs. Never walk, match or hash these files by hand. On exit 1 (a source root, brief or provenance map it cannot read), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:authoritative-files"`, `reason: "<its stderr>"`), showing its stderr.
 
-3. **Check brief amendments.** Load `brief.scope.amendments[]` from `{forge_data_folder}/{skill_name}/skill-brief.yaml`. For each candidate not in the provenance map:
-   - **`action: "promoted"` for this path exists:** the brief says this file should be in scope, but it's missing from the provenance map. This means the file was promoted by a prior run but its `file_entries[]` row is missing (e.g. provenance-map was regenerated from source without re-reading amendments). Add the path to `promoted_docs_new[]` (see step 6 below) with its content hash so §4 merge writes a new `file_entries[]` row. No user prompt — the decision was already made. Display: `"Honoring prior amendment: promoted {path} scheduled for file_entries write."`
-   - **`action: "skipped"` for this path exists:** user previously declined promotion. Honor the skip silently. No prompt, no action.
-   - **No amendment for this path:** continue to user prompt.
+2. **Apply each bucket:**
+   - **`already_tracked[]`:** the provenance map names the file (`entries[]` or `file_entries[]`), so §2 detects its drift. No action here.
+   - **`already_in_scope[]`:** the brief's scope already takes the file (a `scope.include` glob matches it, or its latest amendment promoted it), but the map has no row for it. Add the helper's `{path, heuristic, size_bytes, line_count, content_hash}` to `promoted_docs_new[]` (the list [P] Promote below fills), with no prompt, as create-skill §2a does. Display: `"In scope: {path} scheduled for file_entries write."`
+   - **`pre_decided[]` with `prior_action: "promoted"`:** a prior run promoted it, but its `file_entries[]` row is missing (e.g. provenance-map was regenerated from source without re-reading amendments). Add it to `promoted_docs_new[]` with the helper's hash, size and line count so §4 merge writes a new `file_entries[]` row. No user prompt: the decision was already made. Display: `"Honoring prior amendment: promoted {path} scheduled for file_entries write."`
+   - **`pre_decided[]` with `prior_action: "skipped"`:** a person declined promotion before. Honor the skip silently. No prompt, no action.
+   - **`unresolved[]`:** no one has decided the file yet (a `prior_action` of `deferred-headless` marks one a headless run met and left for a person, the legacy `skipped` amendment with reason `headless: no user to prompt` included): continue to the prompt.
 
-4. **Prompt.** For each unresolved candidate, present the same prompt as create-skill §2a:
+3. **Prompt.** For each `unresolved[]` candidate, present the same prompt as create-skill §2a, with the helper's `path`, `line_count`, `size_bytes`, `heuristic` and `preview` as it reported them (never recomputed):
 
    ```
    **New authoritative file discovered since skill creation**
@@ -152,36 +154,28 @@ Read the source directory at `{source_root}` and build a current file inventory:
    [U] Update  — halt this run and return to skf-brief-skill to refine scope
    ```
 
-5. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently add files to scope. **Also append one entry per candidate to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.promoted-doc-prompt", default_action: "S", taken_action: "S", reason: "headless: no user to prompt", evidence: {path: "<candidate.path>"}}`.
+   Steps 4 and 5 are the decision protocol for a scope candidate, which §1c follows too, with the differences it names. Every amendment they append goes to `brief.scope.amendments[]` with `path: candidate.path`, `heuristic: {basename}`, `date: {today ISO}` and `workflow: "skf-update-skill"`, and every brief write goes to `{brief_path}` (the run folder's copy in a read-only mode), preserving all other fields.
 
-6. **Apply decision:**
+4. **GATE [default: defer]**: in headless mode (`{headless_mode}` is true), promote nothing and decide nothing: whether a path belongs in scope needs a person. Leave every candidate out of this run and record it as deferred, so the next interactive run asks: append an amendment `action: "deferred-headless"`, `reason: "headless: no user to prompt; left for the next interactive run"`, except for a candidate whose `prior_action` is `deferred-headless`, which a headless run already recorded: write no second amendment for it. A non-interactive update run must never silently add files to scope, and never records a skip no person chose. **Also record one decision per candidate path**, from `{project-root}`:
 
-   - **[P] Promote:**
-     1. Append `candidate.path` to `brief.scope.include` as a literal glob.
-     2. Append a `brief.scope.amendments[]` entry: `action: "promoted"`, `path: candidate.path`, `reason: {user-provided or auto: "discovered post-creation — matched heuristic {basename}"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-update-skill"`.
-     3. **Write the amended brief back to disk immediately** at `{forge_data_folder}/{skill_name}/skill-brief.yaml`. Preserve all other fields.
-     4. **Hash the candidate** via `uv run {hashContentHelper} hash {candidate.path}` — emits `{content_hash, size_bytes, line_count}` as JSON. Combine with the existing context fields and append to the in-context `promoted_docs_new[]` list: `{path, heuristic, size_bytes, line_count, content_hash}`. This list is consumed by §4 merge Priority 7 to write new `file_entries[]` rows — promoted docs do NOT go through §3 code re-extraction, which would produce ghost entries on non-code files.
-     5. Display: `"Promoted {path} — brief amended, scheduled as new file_entries row for file_type doc."`
+   ```bash
+   uv run {emitEnvelopeHelper} record --workflow skf-update-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+   {"gate": "detect-changes.promoted-doc-prompt", "default_action": "S", "taken_action": "deferred-headless", "reason": "headless: no user to prompt; left for the next interactive run", "evidence": {"path": "<candidate.path>"}}
+   SKF_JSON
+   ```
 
-   - **[S] Skip:**
-     1. Do NOT modify `scope.include`.
-     2. Append a `brief.scope.amendments[]` entry: `action: "skipped"`, `path: candidate.path`, `reason: {user-provided or auto: "user declined promotion at update-skill §1b"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-update-skill"`.
-     3. **Write the amended brief back to disk** so neither update-skill nor create-skill will re-prompt in future runs.
-     4. Display: `"Skipped {path} — decision recorded in amendments."`
+5. **Apply decision:**
 
-   - **[U] Update:**
-     1. Halt the workflow immediately.
-     2. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."`
-     3. Exit with status `halted-for-brief-refinement`. Change manifest is discarded — no partial writes.
+   - **[P] Promote:** append `candidate.path` to `brief.scope.include` as a literal glob, append an amendment `action: "promoted"`, `reason: {user-provided or auto: "discovered post-creation: matched heuristic {basename}"}`, and **write the amended brief back to disk immediately**. Then append the candidate's `{path, heuristic, size_bytes, line_count, content_hash}`, as the helper reported them, to `promoted_docs_new[]`, which this section keeps as the JSON array `{run_dir}/promoted-docs.json` (each record as the helper printed it; `[]` when none): step 5's `apply` writes a new `file_entries[]` row for each (merge Priority 7). Promoted docs do NOT go through step 3's code re-extraction, which would produce ghost entries on non-code files. Display: `"Promoted {path}: brief amended, scheduled as new file_entries row for file_type doc."`
+   - **[S] Skip:** leave `scope.include` as it is, append an amendment `action: "skipped"`, `reason: {user-provided or auto: "user declined promotion at update-skill §1b"}`, and write the amended brief back to disk, so neither update-skill nor create-skill re-prompts in a later run. Display: `"Skipped {path}: decision recorded in amendments."`
+   - **[U] Update:** HALT with status `halted-for-brief-refinement` (halt procedure: `phase: "detect-changes:authoritative-files"`, `path: "{brief_path}"`, `reason: "the user chose to refine the brief's scope for {path}"`) and display `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."`: no partial writes.
 
-7. **Summary.** After all candidates are resolved (or none were found):
+6. **Summary.** After all candidates are resolved (or none were found):
 
-   - `"Authoritative files mirror: {N} candidates, {P} promoted, {S} skipped, {A} pre-decided from amendments, {T} already tracked in provenance."`
+   - `"Authoritative files mirror: {N} candidates, {P} promoted, {S} skipped, {D} deferred to an interactive run, {A} decided by the brief (in scope or amended), {T} already tracked in provenance."`, with N the helper's `summary.candidates_total`, A its `already_in_scope_count` plus `pre_decided_count` and T its `already_tracked_count`.
    - If N = 0: `"Authoritative files mirror: no candidates."`
 
-**Record for evidence report:** the update-skill evidence report appends `authoritative_files_mirror: {candidates: N, promoted: P, skipped: S, pre_decided: A, already_tracked: T, decisions: [{path, action, heuristic, reason}]}`.
-
-**Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, not in the change manifest. §2.0's `change_detection_excludes` set (built below) is what stops §2 Category A from re-classifying them as ADDED — it is the only coordination that survives across the parallel Category A subprocesses.
+**Record for evidence report:** append the record `authoritative_files_mirror: {candidates: N, promoted: P, skipped: S, deferred: D, pre_decided: A, already_tracked: T, decisions: [{path, action, heuristic, reason}]}` to `{run_dir}/evidence-records.jsonl` as one JSON line keyed `authoritative_files_mirror`: step 5 §4 reads it there, never from context.
 
 ### 1c. Major-Version Scope Reconciliation (Pre-Detection)
 
@@ -189,8 +183,8 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Skip this section entirely if:**
 
-- `update_mode == "gap-driven"` (test-report mode — source hasn't drifted), OR
 - `metadata.json.source_type == "docs-only"` (no source tree to scope), OR
+- `{brief_path}` does not exist (a skill built without a brief, such as a quick skill): there is no scope to expand and no brief to amend. Display `"Scope reconciliation: skipped (no skill brief)."`, OR
 - No audit drift report is available at the path computed in step 1 below.
 
 **Procedure:**
@@ -199,12 +193,14 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
    ```bash
    uv run {provenanceGapDispatchHelper} dispatch \
-       --skill-name {skill_name} \
-       --baseline-version {baseline_version} \
-       --forge-data-folder {forge_data_folder} \
-       --brief {forge_data_folder}/{skill_name}/skill-brief.yaml
+       --skill-name "{skill_name}" \
+       --baseline-version "{baseline_version}" \
+       --forge-data-folder "{forge_data_folder}" \
+       --brief "{brief_path}"
    ```
 
+   On exit 1 (a forge folder it cannot read, or a brief that exists but cannot be read), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:scope-reconciliation"`, `path: "{brief_path}"`, `reason: "<its stderr>"`).
+
    Output envelope:
 
    ```json
@@ -220,7 +216,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
                  | "pre-decided-demoted" | "unresolved",
          "prior_action": "promoted" | "skipped"
                        | "demoted-include" | "demoted-exclude"
-                       | null
+                       | "deferred-headless" | null
        }, ...
      ],
      "summary": {"pre_decided_count": N, "unresolved_count": N}
@@ -235,7 +231,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
      - `status: "already-in-scope"` → skip silently (`prior_action: "promoted"`).
      - `status: "pre-decided-skipped"` → honor silently (`prior_action: "skipped"`).
      - `status: "pre-decided-demoted"` → record as `pre_decided`; do not re-prompt (`prior_action` ∈ `demoted-include`, `demoted-exclude`).
-     - `status: "unresolved"` → continue to step 4 (user prompt).
+     - `status: "unresolved"` → continue to step 3 (user prompt). A `prior_action` of `deferred-headless` marks a path a headless run deferred (the legacy `skipped` amendment with reason `headless: no user to prompt` reads the same): a person decides it now.
 
    **Note:** the Out-of-Scope section is an optional audit-skill output and is often absent or empty — new-file detection is update-skill's job (§1b/§2.2), not audit-skill's — so the `no-report` / `no-candidates` paths above are the common case.
 
@@ -255,95 +251,125 @@ Read the source directory at `{source_root}` and build a current file inventory:
    [U] Update  — halt this run and return to skf-brief-skill to refine scope
    ```
 
-4. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `category: "scope-expansion"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently expand scope. **Also append one entry per candidate to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.scope-expansion", default_action: "S", taken_action: "S", reason: "headless: no user to prompt", evidence: {path: "<candidate.path>"}}`.
-
-5. **Apply decision:**
-
-   - **[P] Promote:**
-     1. Append `candidate.path` to `brief.scope.include` as a literal glob (preserve any wildcards from the drift report).
-     2. Append a `brief.scope.amendments[]` entry: `action: "promoted"`, `category: "scope-expansion"`, `path: candidate.path`, `reason: {user-provided or auto: "out-of-scope new public API — drift report {report basename}"}`, `evidence: {evidence string}`, `date: {today ISO}`, `workflow: "skf-update-skill"`.
-     3. **Write the amended brief back to disk immediately** at `{forge_data_folder}/{skill_name}/skill-brief.yaml`. Preserve all other fields.
-     4. Display: `"Promoted {path} — brief amended; §2 Category A will pick up matching files as ADDED."`
-     5. **No `promoted_docs_new[]` entry and no `change_detection_excludes` write** — promoted code globs flow through the standard §2 Category A → §3 extraction path, unlike §1b's promoted docs which bypass extraction.
+4. **GATE [default: defer]**: in headless mode (`{headless_mode}` is true), defer each candidate as §1b step 4 does, with this section's amendment fields (step 5) and the gate `detect-changes.scope-expansion` in its decision record: a non-interactive update run must never silently expand scope.
 
-   - **[S] Skip:**
-     1. Do NOT modify `scope.include` or `scope.exclude`.
-     2. Append a `brief.scope.amendments[]` entry: `action: "skipped"`, `category: "scope-expansion"`, `path: candidate.path`, `reason: {user-provided or auto: "user declined promotion at update-skill §1c"}`, `evidence: {evidence string}`, `date: {today ISO}`, `workflow: "skf-update-skill"`.
-     3. **Write the amended brief back to disk** so neither §1c nor a future run will re-prompt.
-     4. Display: `"Skipped {path} — decision recorded in amendments."`
+5. **Apply decision** as §1b step 5 does, with these differences:
 
-   - **[U] Update:**
-     1. Halt the workflow immediately.
-     2. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."`
-     3. Exit with status `halted-for-brief-refinement`. Change manifest is not yet built — no partial writes to provenance.
+   - **Amendment fields:** every amendment carries `category: "scope-expansion"` and the candidate's `evidence: {evidence string}` in place of `heuristic`. [P]'s auto reason is "out-of-scope new public API: drift report {report basename}", and [S]'s "user declined promotion at update-skill §1c".
+   - **Promotion target:** [P] appends the path to `scope.include` as the drift report gives it, wildcards kept, and adds no `promoted_docs_new[]` entry and no `--exclude`: §2 Category A lists the files a promoted code glob matches as ADDED, and step 3 extracts them, unlike §1b's documents. Display: `"Promoted {path}: brief amended; §2 Category A will pick up matching files as ADDED."`
+   - **[S]** leaves `scope.exclude` as it is too, and **[U]** halts with `phase: "detect-changes:scope-reconciliation"`.
 
 6. **Summary:** After all candidates are resolved (or none were found):
 
-   - `"Scope reconciliation: {N} candidates, {P} promoted, {S} skipped, {A} pre-decided from amendments."`
+   - `"Scope reconciliation: {N} candidates, {P} promoted, {S} skipped, {D} deferred to an interactive run, {A} pre-decided from amendments."`
    - If N = 0 (section absent or empty): `"Scope reconciliation: no out-of-scope observations in drift report."`
-   - If §1c was skipped entirely (no drift report): omit this line; §2.2 will still run.
+   - If §1c was skipped entirely (a docs-only skill, no skill brief or no drift report): omit this line; §2.2 will still run.
 
-**Record for evidence report:** the update-skill evidence report appends `scope_reconciliation_pre: {drift_report: path, candidates: N, promoted: P, skipped: S, pre_decided: A, decisions: [{path, action, evidence}]}` (omit when §1c was skipped).
+**Record for evidence report:** append the record `scope_reconciliation_pre: {drift_report: path, candidates: N, promoted: P, skipped: S, deferred: D, pre_decided: A, decisions: [{path, action, evidence}]}` to `{run_dir}/evidence-records.jsonl` as one JSON line keyed `scope_reconciliation_pre` (none when §1c was skipped).
 
 ### 2. Compare Against Provenance Map
 
-**If normal mode (provenance map available):**
+**In degraded mode (no provenance map),** run Category A without `--provenance-map`: its `full` mode lists every in-scope file as MODIFIED (with no brief, `--language` scopes the walk), so step 3 re-extracts every export. Run Category B's steps 1 and 2 only (re-extract.md §4's records come from them), and skip its step 3, Category C, Category D and §2.2: there is no map to compare against.
 
-#### 2.0 — Build Pre-filter Exclusion Set
+#### 2.0 Change-Detection Excludes
 
-Before launching parallel subprocesses, build a `change_detection_excludes` set in context that Category A subprocess workers must honor. Parallel subprocesses cannot see each other's in-memory state, so any coordination between §1b's decisions and §2's scan results must be pre-materialized into an explicit input the subprocesses receive.
+`promoted_docs_new[]` (§1b) holds documents that reach the provenance map as `file_entries[]` rows through step 4 Priority 7, never through code extraction. Category A leaves each of them out with `--exclude`: each is in scope and the map does not name it yet, so it would read as ADDED, and step 3 would send it to AST extraction, producing ghost entries. A path a `file_entries[]` row already names (a tracked document, script or asset) needs no exclude: Category A never lists one, and Category D compares its hash.
 
-The exclusion set includes:
+#### 2.1 Categories A, B and C, in Order
 
-- Every path in `promoted_docs_new[]` (populated by §1b). These files are tracked as `file_entries[]` via step 4 Priority 7, not through Category A code extraction. Without this exclusion, Category A would classify them as ADDED (because they're in source but not yet in the provenance map) and §3 re-extract would send them to AST extraction, producing ghost entries.
-- Every source path in `file_entries[].source_file` where `file_type == "doc"` in the existing provenance map. These are already-tracked authoritative docs; any drift in them is handled by Category D (script/asset file changes), not Category A.
+Category B reads the files Category A lists, and Category C pairs what A and B leave deleted and added. Category D (below) needs neither.
 
-Record the set size: "**Change-detection excludes:** {count} paths ({promoted_docs_new count} new promotions + {existing doc file_entries count} already tracked)."
+**Category A: file-level changes.** Resolve `{classifyChangedFilesHelper}` ← first existing path in `{classifyChangedFilesProbeOrder}` and, from `{project-root}`, run:
 
-#### 2.1 — Launch Category Subprocesses
+```bash
+uv run {classifyChangedFilesHelper} classify \
+    --source-root "{source_root}" \
+    [--provenance-map "{provenance_map_path}"] \
+    [--brief "{brief_path}"] \
+    [--language "{language}"] \
+    --tree-status "{source_tree_status}" \
+    --diff-status "{source_diff_status}" \
+    --changed-files "{source_changed_files}" \
+    [--exclude "<promoted document path>"] \
+    --lists-dir "{run_dir}" \
+    > "{run_dir}/category-a.json"
+```
 
-Launch subprocesses in parallel that compare source state against provenance map across these categories, returning change findings per category. **Every subprocess receives `change_detection_excludes` as an explicit input** and applies it to its file-path iteration loop.
+Pass `--provenance-map` whenever init.md §4 found one; `--brief` (as §1c left it) when that file exists (a skill built without a brief, such as a quick skill after its degraded update, has none); `--language` when metadata.json records one; one `--exclude` for each `promoted_docs_new[]` path; and the three init.md §6b values as bound (an empty or `null` value counts as not given). In a tree it takes the changed files from git's list at `{source_changed_files}`, never from file times or sizes, which a checkout rewrites. Add each of its `warnings[]` to `warnings[]`. It writes `{run_dir}/modified-files.json` (the files Category B diffs) and `{run_dir}/extract-files.json` (the modified and added files and each moved file's new path, which Category B and step 3 read): never retype or re-derive a list. On exit 1 (an input it cannot read, named on stderr), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-a"`, the helper's message as `reason`).
 
-**Category A — File-level changes:**
-- Files in provenance map but missing from source → DELETED
-- Files in source but not in provenance map AND not in `change_detection_excludes` → ADDED
-- Files in `change_detection_excludes`: skip entirely (routed to file_entries via §1b → step 4 Priority 7, never through Category A)
-- Files in both but with different timestamps/sizes → MODIFIED
-- Files with same content at different paths → MOVED
+**Category B: export-level changes.** Skip it when `{run_dir}/extract-files.json` lists no file.
 
-**Category B — Export-level changes (for MODIFIED files only):**
-- For each modified file, compare export list against provenance map exports
-- Exports in provenance but not in source → DELETED_EXPORT
-- Exports in source but not in provenance → NEW_EXPORT
-- Exports with changed signatures/types → MODIFIED_EXPORT
-- Exports at different line numbers but same content → MOVED_EXPORT
+1. **The recipe runner.** At Forge tier and above, resolve `{extractPublicApiHelper}` ← first existing path in `{extractPublicApiProbeOrder}` and, from `{project-root}`, run:
 
-**Category C — Rename detection:**
-- Cross-reference deleted files/exports with added files/exports
-- If content similarity > 80% (fixed bundled threshold — not configurable): classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
+   ```bash
+   uv run {extractPublicApiHelper} --mode full \
+       --source-root "{source_root}" \
+       --files-from "{run_dir}/extract-files.json" \
+       [--language "{language}"] \
+       [--scope-type "{scope_type}"] \
+       --head-cap 0 \
+       -o "{run_dir}/extraction.json"
+   ```
 
-**Subprocess return contract.** Hand each Category worker its exact output slice so it returns parse-ready JSON, not prose the parent must re-read. Each worker returns ONLY its own object — no prose, no commentary, no markdown fences (parent strips wrapping fences before parsing). The slice each worker fills is exactly the key §3's `build` helper consumes (the `category_a/b/c` shape below; Category D is helper-driven, not a worker):
+   Pass `--language` when metadata.json records it, and `--scope-type` when §1 bound `{scope_type}`. It takes no `--brief`: Category A applied the scope, and a tracked file the brief's scope leaves out (gap-driven.md §1's rule R1 excludes a rescoped export's file) keeps its exports. `--head-cap 0` keeps every match, since a dropped one would read as a deleted export. Step 3 reads this file and never runs the runner again. **Exit 1** (`incomplete`, its JSON written): run it once more; when still incomplete, step 2 below reads by eye each listed file with no export in `exports[]` or that an `errors[]` item lists in `unread`, and tells the user which files were read by eye. **Exit 2** (an input error, such as a file list it cannot read, or a failure it did not foresee, named in one stderr line with no JSON; `uv` failing to start it exits 2 too): HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, the stderr line that holds `error:` as `reason`). No by-eye read stands in for it: the skill is not written yet, and reading every file by eye would hide the error. **Exit 3 (`no-ast-grep`), no JSON on another exit, no candidate resolves, or Quick tier:** write `{"exports": []}` to `{run_dir}/extraction.json`, with `"scope": {"type": "{scope_type}"}` when §1 bound `{scope_type}`, so step 5's `apply` can warn that a `public-api` surface was not applied; step 2 reads every listed file by eye (at Quick tier, by text pattern). Tell the user which files were read by eye.
 
-```json
-// Category A worker returns ONLY:
-{"category_a": {"modified": [...], "added": [...], "deleted": [...]}}
-// Category B worker returns ONLY:
-{"category_b": {"modified_exports": [...], "new_exports": [...], "deleted_exports": [...], "moved_exports": [...]}}
-// Category C worker returns ONLY:
-{"category_c": {"renamed_files": [...], "renamed_exports": [...]}}
+   Then, at every tier (in degraded mode there is no map: skip it), list the map's entries the runner left out that their file still declares: the runner never reports a module, an alias that renames, a dunder such as `__version__` or another underscore name, and step 3's diff would read each as a deleted export. From `{project-root}`, run:
+
+   ```bash
+   uv run {buildChangeManifestHelper} baseline-gaps \
+       --provenance-map "{provenance_map_path}" \
+       --extraction "{run_dir}/extraction.json" \
+       --files "{run_dir}/modified-files.json" \
+       --source-root "{source_root}" \
+       -o "{run_dir}/baseline-gaps.json"
+   ```
+
+   It writes `{"gaps": [{name, file, line, entry, export_type}], "unchecked": [{name, file, export_type}]}`: in `gaps[]` each entry of a modified file that no export of `{run_dir}/extraction.json` holds and whose file still declares it, at the line that declares it, by the verifier's rule (audit-skill's extraction snapshot applies the same one), and in `unchecked[]` each such entry no rule can check (its file neither Python nor TS/JS, a file the rule will not read, such as a test file or one with a symlink on its path, or a dotted module name), which step 2 reads by eye. Never add a gap or drop one by eye. On exit 1 (an input it cannot read, or a `skf-verify-provenance-completeness.py` beside it that cannot be loaded), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, its stderr as `reason`): without it, every name the runner leaves out would read as deleted.
+
+2. **What the recipes do not record.** Workers, in parallel batches (Pattern 4) when the list is long, read the modified and added files and each return ONLY `{"exports": [...]}`, with no prose and no fences. For each function export the runner found whose `params` it left null (it could not read the signature): `export_name` and `source_file` as it wrote them, with `params` (each parameter as the source writes it, `name: type`, the form the provenance map's `params` hold) and `return_type` (null when there is none), read at its `source_line`. For each export it could not find (a name `entry_point_diff.extraction_gaps[]` lists, a name `{run_dir}/baseline-gaps.json` lists in `gaps[]`, a form Known Limitation #11 in `{extractionPatternsData}` lists, an export of a file `file_issues[]` names or that was read by eye): the same, plus `export_type`, `source_line`, `confidence: T1-low` and `extraction_method: source-read`. Record a baseline gap at its `file` and `line` (`source_line`), with, as `export_type`, its `export_type` while the declaration there still has that kind, else the kind it has now (a `variable` now declared by a `def` is a `function`, which step 3 reports as a changed kind), and the declaration's kind when the gap gives none; `params` and `return_type` as the declaration writes them, null when it has none (a module, an alias or a variable). For each `unchecked[]` entry, read its file by eye and record it the same way, at the line that declares it, only when the file still declares it. Record each name and file once: when a file read by eye whole (at Quick tier, or when the runner could not run or left the file unread) holds a name a gap or an `unchecked[]` entry lists, that read's record stands and the gap adds none. Write the union of their `exports` arrays to `{run_dir}/export-details.json`.
+
+3. **The diff.** Resolve `{structuralDiffHelper}` ← first existing path in `{structuralDiffProbeOrder}` and, from `{project-root}`, run:
+
+   ```bash
+   uv run {structuralDiffHelper} "{provenance_map_path}" "{run_dir}/extraction.json" \
+       --current-extra "{run_dir}/export-details.json" \
+       --files "{run_dir}/modified-files.json" \
+       -o "{run_dir}/category-b-diff.json"
+   ```
+
+   Exit 0 (no difference) and exit 1 (differences) both wrote the diff, which §3's helper maps onto Category B: never re-diff by eye. On exit 2, no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-b"`, the helper's `error` as `reason`).
+
+**Category C: rename detection.** The fixed rules pair Category A's `deleted` files with its `added` ones, and the diff's `removed[]` exports with its `added[]` ones and with the added files' exports, by script, never by eye. From `{project-root}`, run:
+
+```bash
+uv run {buildChangeManifestHelper} rename-candidates \
+    --category-a "{run_dir}/category-a.json" \
+    [--category-b-diff "{run_dir}/category-b-diff.json"] \
+    --provenance-map "{provenance_map_path}" \
+    [--extraction "{run_dir}/extraction.json"] \
+    [--export-details "{run_dir}/export-details.json"] \
+    --tier "{forge_tier}" \
+    --source-root "{source_root}" \
+    [--sizes-commit "{source_commit}"] \
+    -o "{run_dir}/category-c.json"
 ```
 
-The parent merges the three slices (plus Category D and the `degraded_mode`/`update_mode` flags) into the single category-JSON object §3 pipes to the `build` helper.
+Pass `--category-b-diff`, `--extraction` and `--export-details` when Category B wrote them, and `--sizes-commit` only when `{source_tree_status}` is `ready` or `offline`: in that tree the helper reads a deleted file's size at the pinned commit (`git cat-file -s`), while in a local source the file is gone and the size test is skipped. Skip Category C in degraded mode (there is no map). Content similarity above 80% (fixed, not configurable) is a rename: at Quick tier a file size within 20% and export names that overlap above 70% (export names above 80% alike), at Forge and above equal export signatures. The helper keeps a pair only when it is each side's best match, so a tie pairs nothing, and writes `category_c` (`renamed_files: [{old_path, new_path}]`, `renamed_exports: [{old_name, new_name, file, old_file?}]`, `old_file` only when it differs from `file`), the `evidence` of each pair and what it left `unpaired`. On exit 1, no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-c"`, its stderr as `reason`). Category A's `moved_files[]` (same-content moves) are not Category C's to pair, and §3's helper takes each pair out of the lists it was found in.
 
-**Category D — Script/asset file changes:**
+**CCC check (Forge+ and Deep, a local source only).** When `tools.ccc` is true and `{source_tree_status}` is neither `ready` nor `offline` (the tree init.md §6b prepared has no ccc index, and a search there could start indexing a folder step 7 deletes), you may pair what the rules left in `unpaired`: a deleted file with an added one that CCC ranks as the same code (`ccc_bridge.search` over the deleted file's export names; **Tool resolution:** `/ccc` skill search, ccc MCP or `ccc search`). This is the one judgment in Category C: add a pair only on CCC's evidence, name it in the report as a CCC pairing, and never undo a pair the rules made. Write only these pairs, with each path as `unpaired` gives it, to `{run_dir}/ccc-pairs.json` as `{"renamed_files": [{"old_path": "<deleted>", "new_path": "<added>"}]}`; the helpers below read `{run_dir}/category-c.json` themselves, so never copy its pairs.
 
-Run the bulk comparison once via:
+**Category D: script, asset and tracked-document file changes.**
+
+Run the bulk comparison once, keeping its output in the run folder (step 5's `apply` reads it):
 
 ```bash
-uv run {hashContentHelper} compare <source-root> \
-    --provenance-map <provenance-map-path>
+uv run {hashContentHelper} compare "{source_root}" \
+    --provenance-map "{provenance_map_path}" \
+    > "{run_dir}/category-d-compare.json"
 ```
 
+On exit 1, no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-d"`, its stderr as `reason`).
+
 The helper emits:
 
 ```json
@@ -357,43 +383,51 @@ The helper emits:
 }
 ```
 
-Translate the helper's output into the change manifest:
-- `MODIFIED_FILE` rows → add to manifest as MODIFIED_FILE
-- `DELETED_FILE` rows → add to manifest as DELETED_FILE
-- `UNCHANGED` rows → omit from the manifest (no action needed)
+A map with no `file_entries` field, or a null one (a skill with no script, asset or promoted document, or a map written before the field existed), tracks no file: the comparison lists no row and the set difference below subtracts nothing.
 
-The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. Pipe the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) into `{newFileDiffHelper}`, which subtracts the provenance map's `file_entries[].source_file` and sets aside user-authored `[MANUAL]` paths:
+The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. **When `{brief_path}` does not exist** (a skill built without a brief, such as a quick skill), skip it: with no scope to keep to, the walk would read every script and asset of the repository as new. Add `new-files-not-checked: no skill brief, so no new script or asset was looked for` to `warnings[]`, write no `{run_dir}/new-files.json`, and leave `--new-files` out of §3's `build` and step 5's `apply`. Otherwise pipe the detector create-skill step 3 §4c runs (resolved via `detectScriptsAssetsProbeOrder`), which walks the whole source, into `{newFileDiffHelper}`, which keeps what the brief takes and subtracts what the map tracks:
 
 ```bash
-uv run {detectScriptsAssetsHelper} detect <source-root> \
-    | uv run {newFileDiffHelper} {forge_version}/provenance-map.json
+uv run {detectScriptsAssetsHelper} detect "{source_root}" \
+    | uv run {newFileDiffHelper} "{provenance_map_path}" [--brief "{brief_path}"] \
+    > "{run_dir}/new-files.json"
 ```
 
-It emits `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "stats":{...}}`. Add each `new_files[]` entry to the manifest as NEW_FILE — `kind` (`script`/`asset`) selects the target array. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above.
+Pass `--brief` as Category A does, `{brief_path}` as §1c left it (in a read-only run, its copy in `{run_dir}`). On exit 2 (the detector's JSON, the map or the brief it cannot read, named in its JSON `error` on stderr, which also catches a detector that printed nothing), no JSON, or no candidate resolves: HALT with status `blocked` (halt procedure: `phase: "detect-changes:category-d"`, its `error` as `reason`).
 
-Aggregate all subprocess results into a unified change manifest.
+It writes `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "tracked_code":[...], "out_of_scope":[...], "intent_none":[...], "stats":{...}}`. §3's `build` reads both files, typing each compare row by its `file_entries[]` row's `file_type` and each new file by its `kind`: sort no row by hand. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above; `tracked_code[]` are code files the map's `entries[]` cite, which Categories A and B compare; `out_of_scope[]` are paths the brief's scope leaves out, by Category A's in-scope test; `intent_none[]` are paths of a kind whose `scripts_intent` or `assets_intent` is `none` (an absent or free-text intent detects). A path in these lists is no new file and no `stats` count, so step 6's report counts each of the three lists from this file, where it shows Category D: a brief scoped wrongly shows as many paths out of scope. A new file Category A lists too stays a new file: Category A lists every changed in-scope file, a genuine script included.
 
-**If degraded mode (no provenance map):**
-- All source files are treated as MODIFIED
-- All exports will be fully re-extracted in step 03
-- Skip export-level comparison
+**Write the category JSON** to `{run_dir}/categories.json`, where §2.2 and §3 read it beside the helper files: the two flags, `degraded_mode` and `update_mode: "normal"`. Category C stays in the files its steps wrote, which §2.2, §3 and step 5's `apply` take as `--category-c` and `--ccc-pairs`:
+
+```bash
+cat > "{run_dir}/categories.json" <<'SKF_JSON'
+{"degraded_mode": <bool>, "update_mode": "normal"}
+SKF_JSON
+```
 
 #### 2.2 — Major-Version Scope Reconciliation (Post-Detection)
 
 **Purpose:** §1c catches the major-version case when an audit drift report supplies explicit candidates. §2.2 is the safety net that fires when no audit was run (or audit emitted no out-of-scope section): it inspects the just-built Category A/B results for the deletion-ratio signature of a major-version restructure and gives the user an off-ramp before §3 commits the change manifest.
 
-**Trigger computation:** invoke the helper with the same Category A/B/C/D JSON used for §3, plus the provenance map:
+**Trigger computation:** skip §2.2 in degraded mode (there is no map). Otherwise invoke the helper with the files §3 reads, plus the provenance map:
 
 ```bash
-echo "{category JSON}" | uv run {buildChangeManifestHelper} deletion-ratio \
-    --provenance-map {forge_version}/provenance-map.json
+uv run {buildChangeManifestHelper} deletion-ratio \
+    --provenance-map "{provenance_map_path}" \
+    --category-a "{run_dir}/category-a.json" \
+    [--category-b-diff "{run_dir}/category-b-diff.json"] \
+    [--category-c "{run_dir}/category-c.json"] \
+    [--ccc-pairs "{run_dir}/ccc-pairs.json"] \
+    --input "{run_dir}/categories.json"
 ```
 
-The helper handles the three skip conditions internally — when the input has `update_mode: "gap-driven"`, `degraded_mode: true`, or the provenance has zero entries, it returns `skip_reason` set and `should_trigger: false`. `should_trigger` fires when the deletion ratio reaches the fixed bundled threshold of 50% (`ratio >= 0.50`, baked into the helper — not configurable). The output envelope:
+Pass `--category-b-diff`, `--category-c` and `--ccc-pairs` when Category B, Category C and the CCC check wrote them.
+
+The helper handles the two skip conditions internally: when the input has `degraded_mode: true`, or the provenance has zero entries, it returns `skip_reason` set and `should_trigger: false`. `should_trigger` fires when the deletion ratio reaches the fixed bundled threshold of 50% (`ratio >= 0.50`, baked into the helper, not configurable). The output envelope:
 
 ```json
 {
-  "skip_reason": "gap-driven" | "degraded-mode" | "zero-provenance-exports" | null,
+  "skip_reason": "degraded-mode" | "zero-provenance-exports" | null,
   "deleted_export_count": N,
   "total_provenance_exports": N,
   "deletion_ratio": 0.X,
@@ -424,37 +458,37 @@ The upstream surface appears to have been substantially replaced. The brief's
 [A] Audit    — halt and run skf-audit-skill to map the new surface, then re-run update-skill
 ```
 
-**Headless mode (`{headless_mode}` is true):** auto-select `[C] Continue`, log a WARN-level entry to the evidence report (`scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "headless-continue"}`), and surface the warning in step 7's report. A non-interactive run must not silently halt, but the user must be able to see the signal post-hoc. **Also append to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.deletion-ratio", default_action: "C", taken_action: "C", reason: "headless: deletion-ratio threshold exceeded but no user to halt", evidence: {deletion_ratio: <ratio>, deleted_export_count: <N>, total_provenance_exports: <T>}}`.
+**GATE [default: C]**: in headless mode (`{headless_mode}` is true), auto-select `[C] Continue`, append the record `scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "headless-continue"}` to `{run_dir}/evidence-records.jsonl` as one JSON line keyed `scope_reconciliation_post` (step 5 §4 lists it in the evidence report), and surface the warning in step 6's report. A non-interactive run must not silently halt, but the user must be able to see the signal post-hoc. **Also record the decision**, from `{project-root}`:
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-update-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
+{"gate": "detect-changes.deletion-ratio", "default_action": "C", "taken_action": "C", "reason": "headless: deletion-ratio threshold exceeded but no user to halt", "evidence": {"deletion_ratio": <ratio>, "deleted_export_count": <N>, "total_provenance_exports": <T>}}
+SKF_JSON
+```
 
 **Apply decision:**
 
-- **[C] Continue:** record `scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "continue"}` and proceed to §3.
-- **[B] Brief:** halt with status `halted-for-brief-refinement`. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."` Change manifest discarded — no partial writes.
-- **[A] Audit:** halt with status `halted-for-audit`. Display: `"Halting update-skill. Run skf-audit-skill against {skill_name} to map the new surface — its drift report will feed §1c on the next update-skill run."` Change manifest discarded.
+- **[C] Continue:** unless the headless branch above appended its record, append `scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "continue"}` to `{run_dir}/evidence-records.jsonl` the same way, and proceed to §3.
+- **[B] Brief:** HALT with status `halted-for-brief-refinement` (halt procedure: `phase: "detect-changes:deletion-ratio"`, `reason: "the user chose to refine the brief's scope: {deleted_export_count} of {total_provenance_exports} exports deleted"`). Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."` The change manifest is discarded: no partial writes.
+- **[A] Audit:** HALT with status `halted-for-audit` (halt procedure: `phase: "detect-changes:deletion-ratio"`, `reason: "the user chose to audit the new surface first"`). Display: `"Halting update-skill. Run skf-audit-skill against {skill_name} to map the new surface: its drift report will feed §1c on the next update-skill run."` The change manifest is discarded.
 
 ### 3. Build Change Manifest
 
-Hand the assembled Category A/B/C/D JSON to the helper:
+Hand the helper files and the category JSON to the helper, which takes Category A from the classify output, maps the diff onto Category B, and takes each Category C pair out of the lists it was found in:
 
 ```bash
-echo "{category JSON}" | uv run {buildChangeManifestHelper} build
+uv run {buildChangeManifestHelper} build \
+    [--category-a "{run_dir}/category-a.json"] \
+    [--category-b-diff "{run_dir}/category-b-diff.json"] \
+    [--category-c "{run_dir}/category-c.json"] \
+    [--ccc-pairs "{run_dir}/ccc-pairs.json"] \
+    [--file-compare "{run_dir}/category-d-compare.json" --provenance-map "{provenance_map_path}"] \
+    [--new-files "{run_dir}/new-files.json"] \
+    --input "{run_dir}/categories.json" \
+    > "{run_dir}/change-manifest.json"
 ```
 
-The category JSON shape is:
-
-```json
-{
-  "category_a": {"modified": [...], "added": [...], "deleted": [...]},
-  "category_b": {"modified_exports": [...], "new_exports": [...],
-                 "deleted_exports": [...], "moved_exports": [...]},
-  "category_c": {"renamed_files": [...], "renamed_exports": [...]},
-  "category_d": {"scripts_modified": [...], "scripts_added": [...],
-                 "scripts_deleted": [...], "assets_modified": [...],
-                 "assets_added": [...], "assets_deleted": [...]},
-  "degraded_mode": <bool>,
-  "update_mode": "normal" | "gap-driven"
-}
-```
+Pass each helper file its category wrote. On exit 1 or no JSON: HALT with status `blocked` (halt procedure: `phase: "detect-changes:change-manifest"`, its stderr as `reason`).
 
 The helper emits the unified manifest envelope:
 
@@ -467,21 +501,23 @@ The helper emits the unified manifest envelope:
     "exports_modified": N, "exports_new": N, "exports_deleted": N,
     "exports_renamed": N, "exports_moved": N,
     "scripts_modified": N, "scripts_added": N, "scripts_deleted": N,
-    "assets_modified": N, "assets_added": N, "assets_deleted": N
+    "assets_modified": N, "assets_added": N, "assets_deleted": N,
+    "docs_modified": N, "docs_deleted": N
   },
   "total_export_changes": N,
   "per_file": [
     {"file_path": "...", "status": "MODIFIED|ADDED|DELETED|MOVED",
-     "exports_affected": [{name, change_type, old_line, new_line}, ...]}
-  ]
+     "exports_affected": [{name, change_type, old_line, new_line, old_file?}, ...]}
+  ],
+  "category_d": {"scripts_modified": [...], ..., "docs_deleted": [...]}
 }
 ```
 
-`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field. Stash the envelope as the change manifest in workflow context.
+`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field, and a `MOVED_EXPORT` across files an `old_file`, the file it left, where `apply` finds its entry. `category_d` lists the paths behind the `scripts_*`, `assets_*` and `docs_*` counts: a `docs_*` path is a tracked document, which only Category D detects, so a change to one alone is a change. `{run_dir}/change-manifest.json` is the change manifest: step 3, step 6 and step 5's `apply` read it there, so it survives a compacted context.
 
 ### 4. Check for No-Change Shortcut
 
-**If zero changes detected across all categories:**
+**If zero changes detected across all categories** (`no_changes` is true in `{run_dir}/change-manifest.json`; for a docs-only skill, when every hashed document matched):
 
 "**No changes detected.** Source code matches provenance map exactly.
 
@@ -489,23 +525,17 @@ The skill `{skill_name}` is current — no update needed.
 
 **Skipping to report step...**"
 
-→ Skip steps 03-06, immediately load {noChangeReportFile} with "no changes" status.
+→ Skip steps 3-5, immediately load {noChangeReportFile} with "no changes" status. A `--detect-only` or `--dry-run` run takes this route too and stays read-only there: report.md §1 prints its line with no result file and never runs `{onCompleteCommand}`.
 
 ### 5. Display Change Summary and Route
 
-"**Change Detection Complete:**
+Display one line from the change manifest: "**Detected:** {modified} modified, {added} added, {deleted} deleted and {moved} moved or renamed files; {total_export_changes} exports affected." The report (step 6) shows the full counts.
 
-| Category | Count |
-|----------|-------|
-| Files modified | {count} |
-| Files added | {count} |
-| Files deleted | {count} |
-| Files moved/renamed | {count} |
-| Exports affected | {total_export_changes} |"
+For a docs-only skill, show instead the documents that changed (`changed_urls`) and the ones that could not be fetched.
 
 This step auto-proceeds — no user choices. Once the change manifest is fully built, load and fully read the next file, then execute it, per the branch that applies:
 
-- **`detect_only_mode == true`** → display "**Detect-only mode — skipping re-extract/merge/validate/write.** Loading report..." and load `{noChangeReportFile}` (report.md), which emits status `detect-only`. Do not load `{nextStepFile}`.
+- **`detect_only_mode == true`** → display "**Detect-only mode: skipping re-extract, merge and write.** Loading report..." and load `{noChangeReportFile}` (report.md), which emits status `detect-only`. Do not load `{nextStepFile}`.
 - **No changes detected** (section 4) → load `{noChangeReportFile}` (report.md), which emits status `no-changes`.
-- **Otherwise** → display "**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**" and load `{nextStepFile}` (re-extract.md) to begin re-extraction.
+- **Otherwise** → display "**Proceeding to re-extraction of {affected_file_count} changes...**" and load `{nextStepFile}` (re-extract.md) to begin re-extraction.