bmad-module-skill-forge 1.0.0 → 1.2.0

package/src/skf-setup/steps-c/step-04-report.md

@@ -1,31 +1,47 @@
 ---
 tierRulesData: 'references/tier-rules.md'
 nextStepFile: './step-05-health-check.md'
+# Resolve `{emitEnvelopeHelper}` by probing `{emitEnvelopeProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves when the headless envelope must be emitted
+# — the script is the source of truth for the SKF_SETUP_RESULT_JSON contract;
+# never inline-render the envelope from prose (LLM schema drift is the bug
+# this script exists to prevent).
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
+<!-- Config: communicate in {communication_language}; emit user-visible report text (FORGE STATUS banner, climb hint, REQUIRED TIER NOT MET block, breadcrumb) in {document_output_language}. The JSON envelope from section 4 is a machine contract — its keys and enum values stay English regardless. -->
+
 # Step 4: Forge Status Report
 
 ## STEP GOAL:
 
-Display the forge status report with positive capability framing and report tier changes on re-run.
+Display the forge status report with positive capability framing, surface tier changes and tool-set deltas on re-runs, prominently flag a required-tier miss, and (when headless) emit the schema-locked `SKF_SETUP_RESULT_JSON` envelope via `{emitEnvelopeHelper}`.
 
 ## Rules
 
-- Focus only on displaying the status report
+- Focus only on display + envelope emission
 - Do not use negative framing ("missing", "lacking", "unavailable")
 - Do not list tools that are not available
 - Use tier capability descriptions from tier-rules.md
+- Never inline-render the envelope JSON — the script owns the schema; drift breaks pipelines
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing status report is NOT the terminal step
 
-## MANDATORY SEQUENCE
+## Headless Mode Display Rule
+
+When `{headless_mode}` is `true`, sections 2 (the human-readable banner) and 3 (the REQUIRED TIER NOT MET human prose block) are **skipped entirely**. The single line of stdout in headless mode is the `SKF_SETUP_RESULT_JSON: {…}` envelope from section 4 — every signal the human banner would have surfaced is already in the envelope (`tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`, `tools_removed`, `files_written`, `tier_override_*`, `require_tier_satisfied`, `warnings`, `error`). Parent skills and CI pipelines consume one parseable line; they should not be forced to scroll past 30 lines of ASCII-art they cannot use.
+
+When `{headless_mode}` is `false`, sections 2 and 3 display normally and section 4 is skipped (interactive runs read the human banner; envelope emission would just be log noise).
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+## MANDATORY SEQUENCE
 
 ### 1. Load Capability Descriptions
 
-Load and read {tierRulesData} for the tier capability descriptions and re-run messages.
+Load and read {tierRulesData} for the tier capability descriptions and re-run messages. Needed by section 2; safe to load unconditionally — the data load itself is silent.
 
-### 2. Display Forge Status Report
+### 2. Display Forge Status Report (skip when `{headless_mode}` is true)
 
 **Format the report as follows:**
 
@@ -39,6 +55,17 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 
   Tools Detected:
   {for each tool that is available, show: tool name — version}
+  {if no tools are available: (none yet — see "Climb to next tier" below)}
+
+  {if calculated_tier is not Deep:}
+  Climb to next tier:
+  {if not tools.ast_grep: - Install ast-grep (https://ast-grep.github.io) — unlocks AST-backed code analysis (Forge tier)}
+  {if tools.ast_grep and not tools.ccc: - Install cocoindex-code (https://github.com/cocoindex-io/cocoindex-code) — adds semantic-guided precision compilation (Forge+ tier)}
+  {if tools.ast_grep and not tools.gh_cli: - Install GitHub CLI (https://cli.github.com) — required for Deep tier (cross-repository synthesis)}
+  {if tools.ast_grep and not tools.qmd and qmd_status is "absent": - Install qmd (https://github.com/tobi/qmd) — required for Deep tier (knowledge search)}
+  {if tools.ast_grep and not tools.qmd and qmd_status is "daemon_stopped": - Start the qmd daemon (already installed) — run `qmd start` (or your distribution's qmd service command) to unlock Deep tier (knowledge search)}
+  {if tools.ccc and ccc_daemon is "error": - The ccc daemon is reporting errors — run `ccc doctor` to diagnose. CCC index will fail until resolved (mirrors the qmd daemon-stopped pattern above for parity)}
+  {end if}
 
   {if hygiene_result is "completed":}
   QMD Registry:
@@ -63,30 +90,127 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {if ccc_index_result is "failed": indexing failed — semantic discovery unavailable this session}
   {end if}
 
+  Files written this run:
+  - forge-tier.yaml — {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
+  {if preferences_yaml_created is true:}
+  - preferences.yaml — {project-root}/_bmad/_memory/forger-sidecar/preferences.yaml (first-run defaults)
+  {end if}
+  {if forge_data_dir_created is true:}
+  - {forge_data_folder}/ (directory created)
+  {end if}
+  {if settings_yml_written is true:}
+  - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml ({settings_yml_patterns_added} SKF exclusion pattern(s) merged)
+  {end if}
+  {if ccc_index_result is "created":}
+  - .cocoindex_code/ ccc index — {ccc_file_count} files indexed
+  {end if}
+
 {if tier_override is active:}
   Note: Tier override active (set in preferences.yaml)
 
+{if tier_override_invalid is true:}
+  Note: tier_override value "{tier_override_invalid_value}" in preferences.yaml is not valid.
+        {if tier_override_invalid_suggestion is non-null: Did you mean "{tier_override_invalid_suggestion}"?}
+        Valid values are case-sensitive: Quick, Forge, Forge+, Deep. Using detected tier {calculated_tier}.
+
+{if tier_override_unsafe is true:}
+  Warning: tier_override is forcing {calculated_tier} but the underlying tool prerequisites are not satisfied.
+           Missing: {tier_override_unsafe_missing}. The override is honored, but downstream skills that
+           rely on the missing tool(s) will fail at runtime. Install the missing tool(s) or remove
+           the override from preferences.yaml.
+
 {if re-run with tier change:}
   {appropriate upgrade/downgrade message from tier-rules.md}
 
-{if re-run with same tier:}
+{if re-run with same tier and {tools_added} is empty and {tools_removed} is empty:}
   {same-tier message from tier-rules.md}
 
+{if re-run with same tier and ({tools_added} or {tools_removed} is non-empty):}
+  Tier unchanged: {calculated_tier}.
+  {if {tools_added} non-empty:} Newly detected: {comma-separated tool names from tools_added}{if ccc was added and tier is Deep: " — ccc enhances Deep tier transparently."}
+  {if {tools_removed} non-empty:} No longer detected: {comma-separated tool names from tools_removed} — re-install to restore those capabilities.
+
 ═══════════════════════════════════════
   Forge ready. {calculated_tier} tier active.
 ═══════════════════════════════════════
+
+{if {headless_mode} is false:}
+  Next: try [BS] Brief Skill to scope your first compilation target, or [QS] Quick Skill for a fast template-driven path. Already have a skill? [AS] Audit Skill drift-checks an existing skill against current sources.
 ```
 
+The same-tier-with-tool-deltas branch reads `{tools_added}` and `{tools_removed}` directly from step-01's context (set from `skf-detect-tools.py` output relative to `{previous_tools}`). No LLM-side recomputation.
+
 **Tool display rules:**
+
 - Only show tools that ARE available with their version strings
 - Do NOT list unavailable tools
 - Do NOT show a "missing" column or section
 
-### 3. Chain to Health Check
+### 3. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` is true)
+
+If `{require_tier_satisfied}` is `false` AND `{headless_mode}` is `false`, display this block immediately after the status report. In headless mode the failure surfaces via the envelope's `require_tier_satisfied: false` and the synthesized `warnings` entry — the human prose block would be log noise that pipelines have to scroll past.
+
+When the block does fire (interactive run with require-tier failure):
+
+```
+═══════════════════════════════════════
+  REQUIRED TIER NOT MET
+═══════════════════════════════════════
+
+  Required:  {require_tier}
+  Detected:  {calculated_tier}
+  Missing:   {require_tier_failure_missing_tools}
+
+  Install the missing tool(s) and re-run, or relax `--require-tier`.
+  See "Climb to next tier" above for install URLs.
+═══════════════════════════════════════
+```
+
+This block exists to make pipeline failures visible without the operator parsing the JSON envelope.
+
+### 4. Emit Headless JSON Envelope
+
+When `{headless_mode}` is `true`, build the context payload from this step's accumulated flags and forward it to `{emitEnvelopeHelper}` on stdin. Invoke via `uv run` so the script's PEP 723 dependency declarations are honored (the canonical runtime invocation per `docs/getting-started.md`'s uv prereq — bare `python3` skips the metadata block and breaks on a fresh interpreter). The script computes derived fields (`tools_added`, `tools_removed`, `tier_changed`, `warnings`), validates the assembled envelope against the JSON Schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`, and emits the single prefixed line `SKF_SETUP_RESULT_JSON: {…}` on stdout.
+
+```bash
+echo '{
+  "tier": "{calculated_tier}",
+  "previous_tier": {previous_tier_or_null},
+  "tools": {tools_dict_from_step_01_or_skf_detect_tools_output},
+  "previous_tools": {previous_tools_or_null},
+  "config_path": "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml",
+  "ccc_index": {
+    "status": "{ccc_index_result}",
+    "indexed_path": {ccc_indexed_path_or_null},
+    "file_count": {ccc_file_count_or_null}
+  },
+  "files_written": {
+    "forge-tier.yaml": true,
+    "preferences.yaml": {preferences_yaml_created},
+    "settings.yml": {settings_yml_written},
+    "ccc_index": {ccc_index_result_was_created}
+  },
+  "tier_override_active": {tier_override_active},
+  "tier_override_invalid": {tier_override_invalid},
+  "tier_override_invalid_value": {tier_override_invalid_value_or_null},
+  "tier_override_unsafe": {tier_override_unsafe},
+  "tier_override_unsafe_missing": {tier_override_unsafe_missing_list},
+  "require_tier_satisfied": {require_tier_satisfied_or_null},
+  "require_tier_failure_missing": {require_tier_failure_missing_tools_list},
+  "qmd_status": "{qmd_status}",
+  "ccc_exclusion_warnings": {ccc_exclusion_warnings_list},
+  "ccc_registry_stale_removed": {ccc_registry_stale_removed_paths_list},
+  "ccc_indexing_failed_reason": {ccc_indexing_failed_reason_or_null},
+  "error": {error_object_or_null}
+}' | uv run {emitEnvelopeHelper} emit
+```
+
+The script's documented context-payload shape (see `src/shared/scripts/skf-emit-result-envelope.py` docstring) tolerates two `tools` shapes — bare booleans OR `skf-detect-tools.py`'s `{key: {available: bool, ...}}` output — so either step-01's normalized booleans OR the raw detect-tools output forwarded as-is will produce the correct envelope.
 
-ONLY WHEN the forge status report has been displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+**If the script exits non-zero:** the assembled envelope failed schema validation, which means a context flag from an earlier step is malformed. Surface the error to stderr and continue (the human-readable banner is already displayed; missing JSON envelope on a headless run is a degraded but non-fatal state — the pipeline observer will see no envelope and treat that as "agent did not complete cleanly").
 
-## CRITICAL STEP COMPLETION NOTE
+**When `{headless_mode}` is `false`, do NOT invoke the script** — interactive runs read the human-readable banner.
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the setup workflow is fully done.
+### 5. Chain to Health Check
 
+After the forge status report (and any failure block + JSON envelope) has been displayed, load `{nextStepFile}`, read it fully, and execute it — UNLESS `{require_tier_satisfied}` is `false`, in which case halt the workflow here without chaining to step-05. The health-check step is the true terminal step on success — do not stop after the report on a passing run even though it reads as final. step-05 in turn delegates to `shared/health-check.md`; after that returns, the setup workflow is fully done.

package/src/skf-setup/steps-c/step-05-health-check.md

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. This is a delegation-only step (no user-visible output of its own); shared/health-check.md inherits the language directive on load. -->
+
 # Step 5: Workflow Health Check
 
 ## STEP GOAL:

package/src/skf-test-skill/steps-c/step-01-init.md

@@ -91,10 +91,10 @@ SKF module (`skf init`) or run from a development checkout with src/ present.
 
 Do not proceed. No partial test report is written.
 
-**3b. Run the validator (30s timeout — deterministic validator should finish in <1s; the cap only guards against runaway python):**
+**3b. Run the validator (30s timeout — deterministic validator should finish in <1s; the cap only guards against runaway python).** Invoke via `uv run` so the script's PEP 723 PyYAML dependency resolves automatically; bare `python3` would fail with `ModuleNotFoundError: No module named 'yaml'` on a fresh interpreter (`docs/getting-started.md` documents uv as the runtime prereq for exactly this).
 
 ```bash
-timeout 30s python3 {frontmatterScript} {resolved_skill_package}/SKILL.md --skill-dir-name {skill_name}
+timeout 30s uv run {frontmatterScript} {resolved_skill_package}/SKILL.md --skill-dir-name {skill_name}
 ```
 
 If the command trips the 30s wall-clock (exit code `124`), set
@@ -116,7 +116,7 @@ Parse the JSON output. Per B2, treat each `status` value explicitly:
 This skill will fail `npx skills add` and `npx skill-check check`. {If warn:} Consider fixing frontmatter before proceeding (run `npx skill-check check <skill-dir> --fix` to auto-fix deterministic issues). {If fail:} test-skill cannot proceed — halt and repair frontmatter, then re-run.
 ```
 
-**3c. Python runtime probe.** Before the first invocation, confirm `python3` is on `$PATH` (`command -v python3`). If missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step-05: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing`).
+**3c. Python runtime probe.** Before the first invocation, confirm both `python3` AND `uv` are on `$PATH` (`command -v python3` and `command -v uv`). Both are required: `uv run` shells through to `python3` under the hood AND honors the script's PEP 723 PyYAML dependency declaration that bare `python3` ignores. If either is missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step-05: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing` or `uv-missing` as appropriate). `uv` is a documented runtime prerequisite — see `docs/getting-started.md` for install instructions.
 
 ### 4. Load Forge Tier State
 
@@ -199,7 +199,7 @@ testResult: ''
 score: ''
 threshold: ''
 analysisConfidence: '{full|degraded}'
-toolingStatus: '{ok|python3-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
+toolingStatus: '{ok|python3-missing|uv-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
 workspaceDrift: '{not-checked|ok|overridden}'
 testDate: '{run_id timestamp ISO-8601 UTC}'
 stepsCompleted: ['step-01-init']

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);
 }