bmad-module-skill-forge 1.0.0 → 1.1.0

package/src/skf-brief-skill/assets/skill-brief-schema.md

@@ -67,14 +67,23 @@ scope:
   #   - "code/core/src/manager-api/**"
   #   - "code/core/src/preview-api/**"
   notes: "Optional notes about scope decisions"
-  # Optional: amendment log for scope decisions made during create-skill §2a
+  # Optional: amendment log for scope decisions made during create-skill §2a,
+  # update-skill §1b (auth-doc), and update-skill §1c (scope-expansion).
   # amendments:
   #   - path: "apps/docs/public/llms.txt"
-  #     action: "promoted"          # "promoted" | "skipped"
+  #     action: "promoted"          # "promoted" | "skipped" | "demoted-include" | "demoted-exclude"
+  #     category: "auth-doc"        # "auth-doc" (default for legacy entries) | "scope-expansion"
   #     reason: "authoritative AI docs — only source for canonical install command"
-  #     heuristic: "llms.txt"
+  #     heuristic: "llms.txt"        # required for auth-doc; absent for scope-expansion
   #     date: "2026-04-11"
   #     workflow: "skf-create-skill"
+  #   - path: "python/cocoindex/_internal/api.py"
+  #     action: "promoted"
+  #     category: "scope-expansion"
+  #     reason: "out-of-scope new public API — drift report drift-report-20260424-212355.md"
+  #     evidence: "~70 new exports flagged out-of-scope by audit"
+  #     date: "2026-04-25"
+  #     workflow: "skf-update-skill"
   # Additional fields when scope.type is "component-library":
   # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
   # ui_variants:                           # Optional — design system variants
@@ -87,37 +96,46 @@ scope:
 
 ### Scope Amendments (Optional)
 
-`scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Its primary writer is `skf-create-skill` §2a (Discovered Authoritative Files Protocol), which appends entries when extraction discovers authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) that the original scope patterns excluded.
+`scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Two writer paths exist today:
+
+- **Auth-doc promotions** (`category: "auth-doc"`) — `skf-create-skill` §2a and its mirror `skf-update-skill` §1b append entries when extraction discovers authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) that the original scope patterns excluded.
+- **Scope-expansion promotions** (`category: "scope-expansion"`) — `skf-update-skill` §1c appends entries when an audit drift report flags out-of-scope new public API paths (typically a major-version restructure where the brief's `scope.include` no longer reflects the real surface).
 
 **Entry fields:**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `path` | string | yes | Relative path from source root to the file being amended. Matches the literal path added to `scope.include` (for `promoted` actions). |
-| `action` | string | yes | One of: `promoted` (file added to scope with a literal `scope.include` entry), `skipped` (user declined promotion; file remains out of scope, decision recorded to prevent re-prompting). |
-| `reason` | string | yes | Human-readable sentence explaining the decision. Either user-provided at prompt time or auto-generated ("authoritative AI docs — matched heuristic {basename}"). |
-| `heuristic` | string | yes | The basename heuristic that matched (`llms.txt`, `AGENTS.md`, etc.) so future audits can verify the file still matches its original classification. |
+| `path` | string | yes | Relative path (or glob, for `category: "scope-expansion"`) from source root to the file or tree being amended. For `promoted` actions this matches the literal entry added to `scope.include`. |
+| `action` | string | yes | One of: `promoted` (path added to `scope.include`), `skipped` (user declined promotion; decision recorded to prevent re-prompting), `demoted-include` (path removed from `scope.include` — only valid with `category: "scope-expansion"`), `demoted-exclude` (path removed from `scope.exclude` — only valid with `category: "scope-expansion"`). |
+| `category` | string | no | One of: `auth-doc` (default for entries without this field — the historical sole use case), `scope-expansion`. Distinguishes which workflow path wrote the entry and which writer-rules apply on re-runs. |
+| `reason` | string | yes | Human-readable sentence explaining the decision. Either user-provided at prompt time or auto-generated. |
+| `heuristic` | string | conditional | Required for `category: "auth-doc"` — the basename that matched (`llms.txt`, `AGENTS.md`, etc.). Omit for `category: "scope-expansion"`. |
+| `evidence` | string | conditional | Required for `category: "scope-expansion"` — short rationale from the source signal (e.g., a drift-report finding's evidence one-liner). Omit for `category: "auth-doc"`. |
 | `date` | string | yes | ISO date (`YYYY-MM-DD`) when the amendment was recorded. |
-| `workflow` | string | yes | Workflow name that wrote the amendment (`skf-create-skill`, `skf-update-skill`). Identifies which workflow's §2a-equivalent made the decision. |
+| `workflow` | string | yes | Workflow name that wrote the amendment (`skf-create-skill`, `skf-update-skill`). Identifies which workflow made the decision. |
+
+**Promotion write-through:** When `action: "promoted"`, the workflow also appends the literal path to `scope.include`. This is a belt-and-suspenders design: future runs read `scope.include` during scope filtering and include the file in the filtered list automatically, so the §2a/§1b/§1c discovery loop finds no candidate and does not re-prompt. The `amendments[]` entry is the human-readable audit trail of *why* the path was added.
 
-**Promotion write-through:** When `action: "promoted"`, the workflow also appends the literal path to `scope.include`. This is a belt-and-suspenders design: future `skf-create-skill` runs read `scope.include` during §2 and include the file in the filtered list automatically, so §2a finds no candidate and does not re-prompt. The `amendments[]` entry is the human-readable audit trail of *why* the path was added.
+**Skip recording:** When `action: "skipped"`, the workflow does NOT modify `scope.include` or `scope.exclude`. The amendment entry alone is enough to prevent re-prompting, because the discovery loop checks `amendments[]` before prompting.
 
-**Skip recording:** When `action: "skipped"`, the workflow does NOT modify `scope.include` or `scope.exclude`. The amendment entry alone is enough to prevent re-prompting, because §2a checks `amendments[]` before prompting.
+**Demotion (scope-expansion only):** `demoted-include` removes a previously-promoted path from `scope.include` — used when a prior `[P]` decision is reversed. `demoted-exclude` removes a path from `scope.exclude` — used when a previously excluded path needs to be re-evaluated. Both write the structural change and append the amendment so future runs see the rationale. Demotion is not valid for `category: "auth-doc"`: auth-doc skips already prevent re-prompting without scope mutation.
 
-**Backward compatibility:** `scope.amendments` is optional. Briefs without this field validate unchanged. Treat missing as an empty list.
+**Backward compatibility:** `scope.amendments` is optional. Briefs without this field validate unchanged. Treat missing as an empty list. Existing entries without `category` are equivalent to `category: "auth-doc"` — readers must default the field when absent.
 
 **Who reads `amendments[]`:**
 
-- `skf-create-skill` §2a consults it to avoid re-prompting on decided files.
-- `skf-update-skill` §1b (mirror of §2a) consults it for the same reason.
-- `skf-audit-skill` may optionally report on stale promotions (promoted files that no longer exist in source) as a future enhancement — not currently implemented.
+- `skf-create-skill` §2a consults it to avoid re-prompting on decided auth-doc files.
+- `skf-update-skill` §1b (mirror of §2a) consults it for the same auth-doc reason.
+- `skf-update-skill` §1c consults it to avoid re-prompting on decided scope-expansion candidates and to honor prior `demoted-*` decisions.
+- `skf-audit-skill` may optionally report on stale promotions (promoted paths that no longer exist in source) as a future enhancement — not currently implemented.
 - Humans reading the brief see the audit trail of non-obvious scope decisions.
 
 **Who writes `amendments[]`:**
 
-- `skf-create-skill` §2a (Discovered Authoritative Files Protocol)
-- `skf-update-skill` §1b (mirror of §2a applied during change detection)
-- Manual edits by the brief author are permitted but should include all required fields above.
+- `skf-create-skill` §2a (Discovered Authoritative Files Protocol) — `category: "auth-doc"`
+- `skf-update-skill` §1b (mirror of §2a applied during change detection) — `category: "auth-doc"`
+- `skf-update-skill` §1c (Major-Version Scope Reconciliation) — `category: "scope-expansion"`
+- Manual edits by the brief author are permitted but should include all required fields above (and `category` when the entry is not an auth-doc decision).
 
 ## YAML Template
 

package/src/skf-drop-skill/steps-c/step-02-execute.md

@@ -95,7 +95,7 @@ For each entry in `target_context_files`:
 
 5. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step-04 section 4d:
 
-   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the current entry's `skill_root` if different. **Override guard:** If `snippet_skill_root_override` is set in config.yaml AND the extracted prefix equals the override value, skip the rewrite — leave the root path untouched. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
+   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in config.yaml — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
 
 6. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
 

package/src/skf-export-skill/assets/managed-section-format.md

@@ -71,7 +71,7 @@ All other IDEs use AGENTS.md as the context file, each with its own skill direct
 **`snippet_skill_root_override` (optional):** Authoring repos where all skills live under one shared on-disk directory (e.g. `skills/`) that does not match any per-IDE skill root may set `snippet_skill_root_override: skills/` in `config.yaml`. When set:
 
 - `export-skill/step-03` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
-- `export-skill/step-04` §4d (and its equivalents in `drop-skill/step-02` and `rename-skill/step-02`) skip the prefix rewrite for any snippet whose current prefix already equals the override — the managed section will reference the on-disk location instead of a per-IDE directory that does not exist
+- `export-skill/step-04` §4d (and its equivalents in `drop-skill/step-02` and `rename-skill/step-02`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
 
 Consuming projects (the common case) omit the field and keep the default IDE-mapping behavior. The override is a narrow escape hatch for repos that author skills into `{skills_output_folder}` and never duplicate them into `.claude/skills/`-style directories.
 

package/src/skf-export-skill/steps-c/step-04-update-context.md

@@ -166,11 +166,11 @@ For each snippet being included in the managed section:
 
 1. Read the `root:` value from the snippet's first line — it has the form `root: {prefix}{skill-name}/`
 2. Extract the current prefix by stripping the trailing `{skill-name}/` from the root value
-3. **Override guard:** If `snippet_skill_root_override` is set in config.yaml AND the extracted prefix equals the override value, skip the rewrite for this snippet — leave the root path untouched. This is the authoring-repo escape hatch: when the override is set, any snippet that already matches the override prefix is treated as ground truth and must not be rewritten to a per-IDE path that does not exist on disk.
-4. Otherwise, compare the extracted prefix against the current target's `skill_root`
-5. If they differ, replace the prefix with the target's `skill_root`, preserving the skill name
+3. **Resolve the effective target prefix:** If `snippet_skill_root_override` is set in config.yaml, use the override value as the effective target prefix for this rebuild — by the override contract every skill in the repo lives under that single shared on-disk directory, so the managed section must reference the override for *every* snippet (not just the ones that already match it). Otherwise, use the current target's `skill_root` as the effective target prefix.
+4. Compare the extracted prefix against the effective target prefix
+5. If they differ, replace the prefix with the effective target prefix, preserving the skill name. When the override is set, this rewrites stale per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, so the rebuilt managed section uniformly references the real on-disk location instead of mixing override and per-IDE paths.
 6. Example: if snippet has `root: .claude/skills/my-lib/` but target skill_root is `.windsurf/skills/`, rewrite to `root: .windsurf/skills/my-lib/`
-7. Example: if snippet has legacy `root: skills/my-lib/` and target skill_root is `.github/skills/`, rewrite to `root: .github/skills/my-lib/` — **unless** `snippet_skill_root_override: skills/` is set, in which case the `skills/` prefix is preserved
+7. Example: if `snippet_skill_root_override: skills/` is set, the effective target prefix is `skills/` regardless of the IDE mapping. A snippet with `root: skills/my-lib/` passes through unchanged; a sibling snippet with `root: .claude/skills/my-other/` (carried over from a pre-override export) is rewritten to `root: skills/my-other/`.
 
 This algorithm handles any IDE's skill root path — including future IDEs — without enumerating known prefixes. The legacy `skills/` prefix (no leading dot) may appear in draft snippets generated by create-skill/quick-skill before export.
 

package/src/skf-rename-skill/steps-c/step-02-execute.md

@@ -199,7 +199,7 @@ For each entry in `target_context_files`:
 
 4. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step-04 section 4d:
 
-   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the current entry's `skill_root` if different. **Override guard:** If `snippet_skill_root_override` is set in config.yaml AND the extracted prefix equals the override value, skip the rewrite — leave the root path untouched. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
+   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in config.yaml — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
 
 5. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
 

package/src/skf-test-skill/steps-c/step-03-coverage-check.md

@@ -79,7 +79,7 @@ test-skill is a quality gate — it MUST NOT trust subagent output blindly. Befo
 
 **Schema validation (required keys + types):**
 
-1. Parse the subagent response as JSON. On parse failure → HALT "coverage-check: subagent response not valid JSON".
+1. Strip wrapping markdown fences before parsing. Subagents frequently return JSON wrapped in a code fence — a line of three backticks (optionally followed by a language tag like `json`) preceding the JSON and a closing line of three backticks after it — despite prompt instructions to return raw JSON. When the first non-empty line of the response is three backticks (optionally with a language tag) and the last non-empty line is three backticks, remove those two fence lines before parsing. Then parse the remaining content as JSON. On parse failure of the inner content → HALT "coverage-check: subagent response not valid JSON".
 2. Required keys present: `exports` (list), `cross_check_mismatches` (list — may be empty). Missing key or wrong type → HALT "coverage-check: subagent JSON schema invalid — missing/typo: {key}". Note: the parent already knows the skill name from workflow context (`{resolved_skill_package}` from step-01) — the subagent is not required to echo it back, and doing so introduces a contract-drift surface without improving verification.
 3. Each `exports[]` entry must be a dict with at minimum `name` (non-empty string) and `kind` (one of `function|class|type|constant|hook|interface|method`). Reject entries violating this; if >0 rejections, HALT "coverage-check: subagent returned malformed export entries — {count} entries do not match schema".
 4. `cross_check_mismatches[]` entries (when non-empty) must carry `export`, `skill_md_line`, `reference_file`, `reference_line`, `issue`. Missing fields → HALT.

package/src/skf-update-skill/steps-c/step-02-detect-changes.md

@@ -131,6 +131,80 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, NOT in the change manifest. But §2 Category A ("files in source but not in provenance map → ADDED") would still find the promoted doc files on disk and classify them as ADDED if nothing prevents it. The coordination mechanism is an explicit pre-filter exclusion set built in §2.0 (below) that every Category A subprocess worker receives as an input before it starts scanning. See §2.0 for the exact contract. The exclusion set is the only mechanism guaranteeing that parallel subprocesses cannot double-count `promoted_docs_new[]` paths — prose-level "skip any path" instructions cannot cross subprocess boundaries.
 
+### 1c. Major-Version Scope Reconciliation (Pre-Detection)
+
+**Purpose:** When upstream undergoes a paradigm shift (rebrand, package restructure, major-version rewrite), the brief's `scope.include` no longer reflects the real public API. §1b handles new authoritative-doc files; §1c handles new **code globs** that fall outside the original scope. Without it, update-skill silently misses the new surface and pays the gap cost on every future update — the cocoindex `0.3.37 → 1.0.0` and cognee `0.5.8 → 1.0.0` runs are existence proofs that this case is real and recurring.
+
+**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
+- No audit drift report is available at the path computed in step 1 below.
+
+**Procedure:**
+
+1. **Locate the most recent audit drift report.** Search `{forge_data_folder}/{skill_name}/{baseline_version}/drift-report-*.md`, sorted by timestamp descending. Pick the latest. If none found, **skip §1c entirely** — the post-detection deletion-ratio trigger in §2.2 still catches major restructures even without an audit pass.
+
+2. **Parse the report for an "Out-of-Scope Observations" section.** Look for either a top-level `## Out-of-Scope Observations` heading or a `### Out-of-Scope New Public API` subsection under `## Remediation Suggestions`. Each entry must expose:
+
+   - `path` — literal file path or directory glob (e.g., `python/cocoindex/_internal/api.py` or `python/cocoindex/resources/**`)
+   - `evidence` — short one-liner from the report (export count, rationale)
+
+   **Note:** This section is an optional audit-skill output. `skf-audit-skill` does not currently discover new files (per `src/skf-audit-skill/steps-c/step-02-re-index.md` — new-file detection is the responsibility of update-skill). The section is a forward-looking integration point: manual additions to the drift report or a future audit-skill enhancement populate it. If absent, no candidates from this trigger — proceed to step 6.
+
+3. **Reconcile against existing amendments.** For each candidate, consult `brief.scope.amendments[]`:
+
+   - `action: "promoted"` AND `path` matches → already in scope, skip silently.
+   - `action: "skipped"` AND `path` matches → user previously declined, honor silently.
+   - `action: "demoted-include"` or `action: "demoted-exclude"` AND `path` matches → user previously narrowed scope on this path, do not re-prompt; record as `pre_decided`.
+   - No matching amendment → continue to user prompt.
+
+4. **Prompt for each unresolved candidate.** Present the same menu shape as §1b:
+
+   ```
+   **Out-of-scope new public API discovered**
+
+   Path:          {candidate.path}
+   Evidence:      {evidence from drift report}
+   Drift report:  {report relative path}
+
+   This path was not in the brief's `scope.include` when the skill was created. How should update-skill handle it?
+
+   [P] Promote — add to scope.include AND extract in this run
+   [S] Skip    — leave out of scope AND record skip in amendments (no re-prompt)
+   [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"`, `category: "scope-expansion"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently expand scope.
+
+6. **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.
+
+   - **[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."`
+
+   - **[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.
+
+7. **Summary:** After all candidates are resolved (or none were found):
+
+   - `"Scope reconciliation: {N} candidates, {P} promoted, {S} skipped, {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.
+
+**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).
+
 ### 2. Compare Against Provenance Map
 
 **If normal mode (provenance map available):**
@@ -183,6 +257,55 @@ Aggregate all subprocess results into a unified change manifest.
 - All exports will be fully re-extracted in step 03
 - Skip export-level comparison
 
+#### 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.
+
+**Skip this section entirely if:**
+
+- `update_mode == "gap-driven"` (test-report mode), OR
+- `degraded_mode == true` (no provenance baseline to compare against — every export looks "modified", deletion ratio is meaningless), OR
+- Provenance map's tracked export count is zero.
+
+**Trigger:** Compute
+
+```
+deleted_export_count = (sum of exports across Category A DELETED files)
+                     + (DELETED_EXPORT count from Category B)
+total_provenance_exports = provenance_map.entries.length
+deletion_ratio = deleted_export_count / total_provenance_exports
+```
+
+If `deletion_ratio >= 0.50`, present the prompt below. Otherwise skip §2.2 silently and continue to §3.
+
+**Prompt:**
+
+```
+**Major-version scope shift detected**
+
+Deleted exports:        {deleted_export_count} of {total_provenance_exports} ({percent}%)
+Deleted files:          {deleted_file_count}
+Added files (in scope): {added_in_scope_count}
+Renamed/moved exports:  {renamed_or_moved_count}
+
+The upstream surface appears to have been substantially replaced. The brief's
+`scope.include` patterns may no longer reflect the real public API.
+
+[C] Continue — proceed with re-extraction; the deletion is intentional
+[B] Brief    — halt and re-run skf-brief-skill to refine scope first
+[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-07's report. A non-interactive run must not silently halt, but the user must be able to see the signal post-hoc.
+
+**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.
+
+**Why both §1c and §2.2:** §1c is precise (per-path P/S/U) but requires upstream signal from audit-skill. §2.2 is coarse (single halt/continue) but self-contained — it fires even when the user runs update-skill directly without audit. Together they cover the major-version case across the two real workflows.
+
 ### 3. Build Change Manifest
 
 Compile the change manifest with structured entries:

package/tools/validate-docs-drift.js

@@ -5,6 +5,9 @@
  * every version number, commit SHA, and library reference the docs cite.
  *
  * What it checks:
+ * - The anchor `skf_version` matches `package.json.version` (self-reference invariant
+ *   declared in pinned.yaml's header; enforced here at CI/pre-commit time AND bumped
+ *   by release.yaml on every release)
  * - Every skill listed in `docs/_data/pinned.yaml` actually exists at the
  *   claimed version and commit in $OMS/skills/<name>/<version>/<name>/metadata.json
  * - The metadata.json `version` field matches the anchor `version`
@@ -32,6 +35,7 @@ const yaml = require('js-yaml');
 const SKF_ROOT = path.resolve(__dirname, '..');
 const DOCS_DIR = path.join(SKF_ROOT, 'docs');
 const ANCHORS_PATH = path.join(DOCS_DIR, '_data', 'pinned.yaml');
+const PACKAGE_JSON_PATH = path.join(SKF_ROOT, 'package.json');
 
 function loadAnchors() {
   if (!fs.existsSync(ANCHORS_PATH)) {
@@ -46,6 +50,38 @@ function loadAnchors() {
   }
 }
 
+function checkSkfVersionAgainstPackageJson(anchors) {
+  const errors = [];
+  if (!fs.existsSync(PACKAGE_JSON_PATH)) {
+    errors.push(`CRITICAL: package.json not found at ${PACKAGE_JSON_PATH}`);
+    return errors;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, 'utf8'));
+  } catch (error) {
+    errors.push(`CRITICAL: could not parse ${PACKAGE_JSON_PATH}: ${error.message}`);
+    return errors;
+  }
+  const anchorVersion = anchors.skf_version;
+  const packageVersion = pkg.version;
+  if (!anchorVersion) {
+    errors.push(`MISSING_ANCHOR: pinned.yaml has no skf_version key`);
+    return errors;
+  }
+  if (!packageVersion) {
+    errors.push(`MISSING_PKG_VERSION: package.json has no version field`);
+    return errors;
+  }
+  if (anchorVersion !== packageVersion) {
+    errors.push(
+      `SKF_VERSION_DRIFT: pinned.yaml skf_version "${anchorVersion}" !== package.json version "${packageVersion}" ` +
+        `— bump pinned.yaml or check that release.yaml's "Update pinned.yaml skf_version" step fired`,
+    );
+  }
+  return errors;
+}
+
 function resolveOmsPath(anchors) {
   if (process.env.OMS) {
     return path.resolve(process.env.OMS);
@@ -172,7 +208,11 @@ function main() {
   const anchors = loadAnchors();
   const omsPath = resolveOmsPath(anchors);
 
-  const errors = [...checkCanonicalFiles(anchors, omsPath), ...checkDocsForStaleVersions(anchors)];
+  const errors = [
+    ...checkSkfVersionAgainstPackageJson(anchors),
+    ...checkCanonicalFiles(anchors, omsPath),
+    ...checkDocsForStaleVersions(anchors),
+  ];
 
   if (errors.length > 0) {
     console.error('DRIFT DETECTED:\n');
@@ -186,7 +226,7 @@ function main() {
   }
 
   const skillCount = Object.keys(anchors.skills).length;
-  console.log(`OK: ${skillCount} skills checked against ${omsPath}, no drift.`);
+  console.log(`OK: skf_version ${anchors.skf_version} matches package.json; ${skillCount} skills checked against ${omsPath}, no drift.`);
   process.exit(0);
 }