bmad-module-skill-forge 1.4.0 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -181,14 +181,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
 
-## Versioning & Stability
-
-The v1.0.0 public API contract is documented in [docs/_internal/STABILITY.md](docs/_internal/STABILITY.md).
-
-## Release Process
-
-Maintainers: see [docs/_internal/RELEASING.md](docs/_internal/RELEASING.md) for branch-protection rules, required status checks, the [`release` environment with required-reviewer gate](docs/_internal/RELEASING.md#release-environment), the [npm Trusted Publisher registration](docs/_internal/RELEASING.md#npm-trusted-publisher) (OIDC-backed publish, auto-provenance), and the [rollback playbook](docs/_internal/RELEASING.md#rollback-playbook) covering seven failure scenarios.
-
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.4.0"
+skf_version: "1.5.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/_internal/STABILITY.md

@@ -86,7 +86,7 @@ SKF supports the Node.js major versions declared in `package.json` `engines.node
 The following surfaces are explicitly excluded from the v1.0.0 contract. Changes to any of these may land in any release — patch, minor, or major — without constituting a "breaking change" from a SemVer perspective. Downstream consumers SHOULD NOT pin against these surfaces.
 
 - **`tools/cli/lib/*` internal helper modules** — implementation detail of the CLI; not a library. Any refactor that preserves the observable CLI surface and install layout above is allowed.
-- **Internal structure of workflow step files under `src/skf-*/steps-c/`** — the workflow authoring format is an SKF-internal authoring surface; step numbering, file names, and prose can change.
+- **Internal structure of workflow step files under `src/skf-*/references/`** — the workflow authoring format is an SKF-internal authoring surface; step numbering, file names, and prose can change.
 - **`_bmad/_memory/forger-sidecar/*.yaml` file schemas** — Ferris sidecar state. Stable as a runtime contract between SKF versions during one install's lifetime (so `skf update` works), but not a downstream-consumable schema.
 - **Ferris agent persona prose and menu wording** — the in-product agent persona can be rephrased or restructured at any time.
 - **Exact chalk styling / ANSI color choices in command output** — stylistic; see the output-format bucket above for what IS committed.

package/docs/architecture.md

@@ -22,7 +22,7 @@ Each workflow directory contains these files, and each has a specific job:
 | File                      | What it does                                                                                                        | When it loads                                     |
 |---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
 | `SKILL.md`                | Human-readable entry point — goals, role definition, initialization sequence, invocation contract, routes to first step | Entry point per workflow                          |
-| `steps-c/*.md`            | **Create** steps — primary execution, 4–10 sequential files per workflow (the last one always chains to the shared health check) | One at a time (just-in-time)                      |
+| `references/*.md`            | **Create** steps — primary execution, 4–10 sequential files per workflow (the last one always chains to the shared health check) | One at a time (just-in-time)                      |
 | `references/*.md`         | Workflow-specific reference data — rules, patterns, protocols                                                       | Read by steps on demand                           |
 | `assets/*.md`             | Workflow-specific output formats — schemas, templates, heuristics                                                   | Read by steps on demand                           |
 | `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
@@ -41,7 +41,7 @@ Each workflow directory contains these files, and each has a specific job:
 flowchart LR
   U[User] --> A[Agent Persona]
   A --> W[Workflow Entry: SKILL.md]
-  W --> S[Step Files: steps-c/]
+  W --> S[Step Files: references/]
   S --> K[Knowledge Fragments<br/>skf-knowledge-index.csv → knowledge/*.md]
   S --> D[References & Assets<br/>references/*.md, assets/*.md, templates/*.md]
   S --> P[Scripts<br/>scripts/*.py, shared/scripts/*.py]

package/docs/examples.md

@@ -210,7 +210,7 @@ No source code to clone — only API documentation. Example: you're integrating
 # When asked for target version, specify: 2025-04-30.basil
 # Ferris confirms your doc URLs match that API version
 @Ferris CS
-# step-03 skips (no source to clone), step-03c fetches docs via doc_fetcher
+# step 3 skips (no source to clone), step 3c fetches docs via doc_fetcher
 # All content is T3 [EXT:url] confidence. source_authority: community
 ```
 

package/docs/workflows.md

@@ -361,7 +361,7 @@ You can also set `headless_mode: true` in your forge preferences (`_bmad/_memory
 SKF_SETUP_RESULT_JSON: {"skf_setup":{"tier":"Deep","previous_tier":"Forge","tier_changed":true,"tools":{...},"tools_added":[...],"tools_removed":[],"config_path":"...","ccc_index":{...},"files_written":[...],"tier_override_active":false,"tier_override_invalid":false,"require_tier_satisfied":null,"warnings":[],"error":null}}
 ```
 
-Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/steps-c/step-02-write-config.md) writer. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
+Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/references/write-config.md) writer. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
 
 **Exception — `/skf-quick-skill` headless emits structured progress + result envelopes.** Headless `/skf-quick-skill` runs are first-class building blocks for batch automators. Three operational contracts beyond per-gate auto-proceed:
 
@@ -386,13 +386,13 @@ Parent skills and CI pipelines `grep` one line out of the workflow log to learn
    | 6    | compile-cancelled   |
    | 7    | finalize-blocked    |
 
-3. **Error-variant result contract on every HARD HALT.** A `SKF_QUICK_SKILL_RESULT_JSON: {…}` envelope is emitted on `stderr` (always) and copied to `{skill_package}/quick-skill-result-latest.json` when the skill package is known (HALTs at step-05 §1 onward). The schema and full population rules live in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Result Contract on HARD HALT".
+3. **Error-variant result contract on every HARD HALT.** A `SKF_QUICK_SKILL_RESULT_JSON: {…}` envelope is emitted on `stderr` (always) and copied to `{skill_package}/quick-skill-result-latest.json` when the skill package is known (HALTs at step 5 §1 onward). The schema and full population rules live in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Result Contract on HARD HALT".
 
 **Batch mode (`--batch <file>`).** Drives N targets through the full pipeline (steps 1–7 each) in sequence. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Per-target output lands in `{skill_package}/` as today; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. Full input grammar, summary schema, and exit-code semantics in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Batch Mode".
 
 **Exception — `/skf-brief-skill` headless emits a final result envelope and supports presets.** Headless `/skf-brief-skill` is a first-class building block for scripted brief generation (e.g. seeding briefs for N SaaS SDKs that share scope/authority defaults). Three operational contracts beyond per-gate auto-proceed:
 
-1. **Pre-supplied inputs replace prompts.** Headless args are consumed at step-01's GATE in place of the interactive menus: `target_repo`, `skill_name`, `target_version`, `language`, `source_type`, `source_authority`, `doc_urls`, `scope_type`, `scripts_intent`, `force`, `preset`. Required-arg shape depends on `source_type` (`target_repo` + `skill_name` for source-backed; `doc_urls` + `skill_name` for `docs-only`). Absent `source_authority` and `scope_type` are NOT guessed — they're resolved by signal-driven detection (`gh api user` vs. repo owner for authority; the 5-rule heuristic ladder for scope). Full grammar in [`src/skf-brief-skill/references/headless-args.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/references/headless-args.md).
+1. **Pre-supplied inputs replace prompts.** Headless args are consumed at step 1's GATE in place of the interactive menus: `target_repo`, `skill_name`, `target_version`, `language`, `source_type`, `source_authority`, `doc_urls`, `scope_type`, `scripts_intent`, `force`, `preset`. Required-arg shape depends on `source_type` (`target_repo` + `skill_name` for source-backed; `doc_urls` + `skill_name` for `docs-only`). Absent `source_authority` and `scope_type` are NOT guessed — they're resolved by signal-driven detection (`gh api user` vs. repo owner for authority; the 5-rule heuristic ladder for scope). Full grammar in [`src/skf-brief-skill/references/headless-args.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/references/headless-args.md).
 
 2. **Structured exit-code map.** Every HARD HALT exits with a stable code so pipelines branch on the failure class without grepping message text:
 
@@ -405,9 +405,9 @@ Parent skills and CI pipelines `grep` one line out of the workflow log to learn
    | 5    | overwrite-cancelled           |
    | 6    | user-cancelled                |
 
-3. **Final result envelope on every terminal exit.** Step-05 emits a single-line `SKF_BRIEF_RESULT_JSON: {…}` envelope on **stdout** before chaining to step-06 on success; every HARD HALT emits the same envelope shape on **stderr** with `status: "error"` and a typed `halt_reason` (`input-missing`, `input-invalid`, `forge-tier-missing`, `target-inaccessible`, `gh-auth-failed`, `write-failed`, `overwrite-cancelled`, `user-cancelled`). Full envelope schema and population rules in [`src/skf-brief-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/SKILL.md) § "Result Contract (Headless)".
+3. **Final result envelope on every terminal exit.** Step-05 emits a single-line `SKF_BRIEF_RESULT_JSON: {…}` envelope on **stdout** before chaining to step 6 on success; every HARD HALT emits the same envelope shape on **stderr** with `status: "error"` and a typed `halt_reason` (`input-missing`, `input-invalid`, `forge-tier-missing`, `target-inaccessible`, `gh-auth-failed`, `write-failed`, `overwrite-cancelled`, `user-cancelled`). Full envelope schema and population rules in [`src/skf-brief-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/SKILL.md) § "Result Contract (Headless)".
 
-**Presets (`--preset <name>`).** Loads `{sidecar_path}/brief-presets/{name}.yaml` and merges its keys as defaults at step-01 §8; explicit headless args override preset values. The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning. Useful for repeated patterns — e.g. briefing 5 SaaS SDKs that all share `source_authority=community`, `scope_type=full-library`, `scripts_intent=skip`.
+**Presets (`--preset <name>`).** Loads `{sidecar_path}/brief-presets/{name}.yaml` and merges its keys as defaults at step 1 §8; explicit headless args override preset values. The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning. Useful for repeated patterns — e.g. briefing 5 SaaS SDKs that all share `source_authority=community`, `scope_type=full-library`, `scripts_intent=skip`.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/README.md

@@ -16,7 +16,7 @@ src/
 │   └── ...
 ├── skf-{name}/               # 13 workflow skills (one directory each)
 │   ├── SKILL.md              # Skill entry point (overview, stages, invocation contract)
-│   ├── steps-c/              # Sequential step files
+│   ├── references/              # Sequential step files
 │   ├── references/           # Rules, patterns, protocols (decision-making)
 │   ├── assets/               # Schemas, output formats
 │   └── templates/            # Output skeletons (used by some skills)

package/src/knowledge/ccc-bridge.md

@@ -43,7 +43,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 
 **Resolves to:** Check `ccc_index.status` in forge-tier.yaml. If `"none"` or the indexed_path does not match, run `cd {path} && ccc init` then `ccc index` and update forge-tier.yaml. Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory.
 
-**Usage context:** Called by setup step-01b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
+**Usage context:** Called by setup step 1b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
 
 ### `ccc_bridge.status()`
 
@@ -51,7 +51,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 1. `ccc --help` — confirms binary exists (exit 0) AND output contains the `CocoIndex Code` identity marker (rejects unrelated `ccc`-named binaries shadowing PATH)
 2. `ccc doctor` — confirms daemon is running, extracts version string, validates embedding model
 
-**Usage context:** Called exclusively by setup step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.
+**Usage context:** Called exclusively by setup step 1 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.
 
 ## Confidence
 
@@ -67,7 +67,7 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 
 ### When Indexing Happens
 
-1. **setup step-01b:** Indexes the project root when setup runs. This is the primary indexing point.
+1. **setup step 1b:** Indexes the project root when setup runs. This is the primary indexing point.
 2. **Workflow discovery steps:** If `ccc_index.status` is `"stale"` or `"none"`, discovery steps trigger a re-index and warn the user. They do not block.
 3. **ccc daemon:** Incremental indexing means re-indexing unchanged files is a near-no-op.
 
@@ -81,7 +81,7 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 
 CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. This file contains `exclude_patterns` and `include_patterns` arrays in glob format. `ccc init` creates the file with sensible defaults (excludes `node_modules`, `__pycache__`, hidden dirs, etc.).
 
-**SKF infrastructure exclusions:** setup step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
+**SKF infrastructure exclusions:** setup step 1b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
 
 | Pattern | Purpose |
 |---------|---------|
@@ -98,13 +98,13 @@ The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in
 
 ### Deferred Discovery (Remote Sources)
 
-For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The workspace clone or ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
+For remote repository sources (GitHub URLs), CCC cannot operate during step 2b because no local code exists yet. The workspace clone or ephemeral clone happens in step 3. To provide CCC pre-ranking for remote sources:
 
-1. **step-02b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
-2. **step-03:** After source resolution succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND remote_clone_path is set AND tier is Forge+/Deep`)
-3. **step-03 (workspace fast path):** If `{remote_clone_path}/.cocoindex_code/` already exists (persisted workspace index), skips init/index and uses `ccc search --refresh` — CCC daemon re-indexes only if files changed since last index. This is near-instant for unchanged repos.
-4. **step-03 (first-time path):** If no existing CCC index, runs `cd {remote_clone_path} && ccc init`, applies standard build/dependency exclusions (node_modules, dist, .git, vendor, etc.) to `settings.yml`, then runs `ccc index`. Brief-specific `include_patterns`/`exclude_patterns` are NOT written to `settings.yml` — the CCC index is general-purpose. Filtering happens at search result time.
-5. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+1. **step 2b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
+2. **step 3:** After source resolution succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND remote_clone_path is set AND tier is Forge+/Deep`)
+3. **step 3 (workspace fast path):** If `{remote_clone_path}/.cocoindex_code/` already exists (persisted workspace index), skips init/index and uses `ccc search --refresh` — CCC daemon re-indexes only if files changed since last index. This is near-instant for unchanged repos.
+4. **step 3 (first-time path):** If no existing CCC index, runs `cd {remote_clone_path} && ccc init`, applies standard build/dependency exclusions (node_modules, dist, .git, vendor, etc.) to `settings.yml`, then runs `ccc index`. Brief-specific `include_patterns`/`exclude_patterns` are NOT written to `settings.yml` — the CCC index is general-purpose. Filtering happens at search result time.
+5. **step 3:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
 
 For workspace repos, the CCC index persists at `{workspace_repo_path}/.cocoindex_code/` and is reused across forges, projects, and sessions. For ephemeral fallback clones, the index is not registered in `ccc_index_registry` — the clone is deleted after extraction.
 
@@ -114,7 +114,7 @@ ccc_index and qmd_collections are **orthogonal**:
 - `ccc_index` in forge-tier.yaml tracks the persistent source code index (one per project)
 - `qmd_collections[]` in forge-tier.yaml tracks per-skill workflow artifact collections
 - ccc indexes source code for semantic search; QMD indexes curated artifacts for temporal/knowledge search
-- The janitor role for QMD (setup step-03) operates independently of ccc_index
+- The janitor role for QMD (setup step 3) operates independently of ccc_index
 
 ## Query Volume Bounds
 
@@ -133,7 +133,7 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 - Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
 - Indexing without configuring exclusions — for project root indexes, apply SKF exclusions (framework/output directories); for workspace repo indexes, apply standard build artifact exclusions (node_modules, dist, .git, etc.)
 - Writing brief-specific `exclude_patterns` to a workspace repo's `settings.yml` — workspace indexes are general-purpose and serve multiple briefs. Apply brief patterns at search result time, not index time. (Exception: ephemeral fallback clones are single-use, so brief exclusions may be applied to their `settings.yml` to reduce indexing time.)
-- Skipping CCC discovery for remote sources without deferring to step-03 — remote repos deserve the same pre-ranking as local sources
+- Skipping CCC discovery for remote sources without deferring to step 3 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments
 

package/src/knowledge/qmd-registry.md

@@ -51,10 +51,10 @@ The `status` field is only present when QMD embed verification fails during coll
 
 | Type | Producer | Content | Primary Consumers |
 | --- | --- | --- | --- |
-| `extraction` | create-skill step-07 | Compiled SKILL.md, references, context-snippet — structured, confidence-rated exports | audit-skill (drift detection), update-skill (T2 enrichment) |
-| `brief` | brief-skill step-05 | skill-brief.yaml — intent, scope, target repository metadata | Portfolio-level search (cross-skill deduplication) |
-| `temporal` | create-skill step-03b | GitHub issues, PRs, releases, changelogs — historical and planned context at T2 confidence | step-04 enrichment (temporal annotations per exported function) |
-| `docs` | create-skill step-03c | Fetched external documentation — API references, guides, usage examples (T3 confidence) | step-04 enrichment (cross-reference doc context with source-extracted functions) |
+| `extraction` | create-skill step 7 | Compiled SKILL.md, references, context-snippet — structured, confidence-rated exports | audit-skill (drift detection), update-skill (T2 enrichment) |
+| `brief` | brief-skill step 5 | skill-brief.yaml — intent, scope, target repository metadata | Portfolio-level search (cross-skill deduplication) |
+| `temporal` | create-skill step 3b | GitHub issues, PRs, releases, changelogs — historical and planned context at T2 confidence | step 4 enrichment (temporal annotations per exported function) |
+| `docs` | create-skill step 3c | Fetched external documentation — API references, guides, usage examples (T3 confidence) | step 4 enrichment (cross-reference doc context with source-extracted functions) |
 
 ### Lifecycle
 
@@ -112,7 +112,7 @@ The `ccc_index_registry` array in forge-tier.yaml is a **parallel but separate**
 | **What is indexed** | Curated workflow artifacts (SKILL.md, briefs, temporal data) | Source code (the actual codebase) |
 | **Index engine** | QMD (BM25 + optional vector search) | cocoindex-code (AST + vector embeddings) |
 | **Lifecycle** | Per-skill: created by create-skill, consumed by audit/update-skill | Per-project: created by setup, verified by create-skill |
-| **Janitor** | setup step-03 (orphan/stale QMD collection cleanup) | setup step-03 section 5b (stale path cleanup) |
+| **Janitor** | setup step 3 (orphan/stale QMD collection cleanup) | setup step 3 section 5b (stale path cleanup) |
 | **Availability** | Deep tier only | Forge+ and Deep tiers |
 
 These registries are orthogonal — they never reference each other, and their janitor sections operate independently.

package/src/shared/health-check.md

@@ -90,7 +90,7 @@ For each genuine finding, present it in this format:
 |-------|-------|
 | **Severity** | `bug` / `friction` / `gap` |
 | **Workflow** | {workflow name} |
-| **Step File** | `src/skf-{workflow}/steps-c/{step-file-path}` |
+| **Step File** | `src/skf-{workflow}/references/{step-file-path}` |
 | **Section** | {the specific section or instruction number — use a stable section heading slug, not line numbers} |
 | **Fingerprint** | `fp-{7-hex}` — first 7 hex chars of `sha1("{severity}|{workflow}|{step_file}|{section-slug}")` |
 
@@ -223,7 +223,7 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 {workflow name, e.g. `skf-create-skill`}
 
 ## Step File
-`src/skf-{workflow}/steps-c/step-NN-name.md`
+`src/skf-{workflow}/references/step-NN-name.md`
 
 ## Severity
 `{bug | friction | gap}`
@@ -246,7 +246,7 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 
 ## Actual
 <!-- ONE sentence. What did you observe instead? -->
-{e.g. No staging path specified, so artifacts were written to `skills/{name}/` and step-07 had to reorganize them.}
+{e.g. No staging path specified, so artifacts were written to `skills/{name}/` and step 7 had to reorganize them.}
 
 ## Evidence
 <!-- Bulleted `file:line` citations. 2-5 bullets. No narrative prose. -->
@@ -255,11 +255,11 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 
 ## Impact
 <!-- ONE sentence. What did this cost in THIS session? -->
-{e.g. 50KB of artifacts written to the wrong path; step-07 required a file-move pass.}
+{e.g. 50KB of artifacts written to the wrong path; step 7 required a file-move pass.}
 
 ## Suggested Fix
 <!-- ONE recommended change. 1-3 sentences. Do NOT list multiple options here. -->
-{e.g. Add a rule to step-05 naming `_bmad-output/{skill-name}/` as the staging directory used by step-06 validation.}
+{e.g. Add a rule to step 5 naming `_bmad-output/{skill-name}/` as the staging directory used by step 6 validation.}
 
 <details>
 <summary>Alternatives considered (optional)</summary>

package/src/shared/references/description-guard-protocol.md

@@ -0,0 +1,100 @@
+# Description Guard Protocol
+
+## Overview
+
+External validators (`skill-check check --fix`, `skill-check split-body`, and any future tool that may rewrite SKILL.md frontmatter) occasionally replace, truncate, or otherwise mutate the `description` field — sometimes substituting a generic version, sometimes re-introducing angle-bracket tokens that earlier sanitization removed.
+
+The on-disk description is **authoritative**: it has been compiled (in `skf-create-skill`) or merged (in `skf-update-skill`) with deliberate trigger-optimization. Losing it to a tool's well-meaning rewrite breaks agent discovery quality and can re-introduce the angle-bracket failure mode that breaks tessl on the next run.
+
+Any tool invocation that may touch SKILL.md must run inside the four-phase guard below. Workflows invoke the deterministic phases (1, 3, 4) via `src/shared/scripts/skf-description-guard.py`; the LLM only performs phase 2 (the tool call itself).
+
+## The Four-Phase Guard
+
+### 1. Capture
+
+Before invoking the tool, snapshot the on-disk `description` value:
+
+```bash
+uv run {project-root}/src/shared/scripts/skf-description-guard.py \
+    capture <skill-md-path>
+```
+
+Output JSON:
+
+```json
+{
+  "description": "the snapshotted value",
+  "schema_hash": "sha256:..."
+}
+```
+
+Stash the `description` value in workflow context as `guarded_description`. Also keep the in-context copy synced with the on-disk pre-call state.
+
+### 2. Execute
+
+Run the tool as specified in its section. The LLM performs this step normally — `skill-check check --fix`, `skill-check split-body`, or whatever is documented in the calling stage.
+
+### 3 + 4. Verify and Restore
+
+After the tool completes, run:
+
+```bash
+uv run {project-root}/src/shared/scripts/skf-description-guard.py \
+    verify-restore <skill-md-path> \
+    --captured-description "{guarded_description}"
+```
+
+The script:
+
+1. Re-reads on-disk `description`
+2. Compares against `guarded_description` using **token-stream equality** — split each string on whitespace, compare resulting token lists element-by-element
+3. If diverged: atomically rewrites the frontmatter `description` field with `guarded_description`
+
+Output JSON:
+
+```json
+{
+  "diverged": true|false,
+  "restored": true|false,
+  "diff_kind": "none|whitespace-only|replaced|truncated|deleted",
+  "current_description": "what was on disk before any restore"
+}
+```
+
+If `restored == true`, also update the in-context copy of `description` to match `guarded_description` so subsequent stages do not work from a stale tool-mutated version. Record `description_guard_restored: true` (with the tool name) in workflow context for the evidence report.
+
+## Why Token-Stream Comparison
+
+Token-stream comparison is the documented sweet spot between two failure modes:
+
+- **Looser fuzzy matching** would let a tool swap one word past the guard (e.g., replace "compile" with "build").
+- **Naive whitespace-normalized equality** would trip on a tool that collapses `"foo  bar"` → `"foo bar"` (cosmetic whitespace fix), forcing unnecessary restore writes.
+
+Splitting on whitespace and comparing token lists catches replaced words, truncation, deletion, and angle-bracket re-introduction while ignoring trailing newlines, re-wrapped quoted strings, and collapsed inner runs.
+
+## What Counts as Divergence
+
+- **`replaced`** — different content (any word changed)
+- **`truncated`** — current tokens are a strict prefix of captured
+- **`deleted`** — the field is empty or whitespace-only on disk
+- **`whitespace-only`** — token streams match but raw strings differ (**not** divergence; do not restore)
+- **`none`** — byte-identical (**not** divergence)
+
+## Post-Restore Re-Validation (Optional)
+
+Skills that run frontmatter compliance checks (e.g. `skf-create-skill validate.md`) should additionally re-validate the restored description against the frontmatter contract after restore — a restored value must still satisfy length limits, forbidden-token rules, and required-field shape. Run:
+
+```bash
+uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <skill-md-path>
+```
+
+If the validator reports failure for the `description` field, flip the Schema row in the evidence report back to `FAIL` and record `description_guard_revalidation: FAIL` with the validator diagnostic. Do not halt — let the failure surface through the normal artifact path so step health-check and the result contract record it.
+
+## Why This Protocol Is Centralized
+
+Previously, each tool invocation in each calling stage carried its own copy of the capture/verify/restore prose. Duplicated defensive logic drifts: a fix in one section did not propagate to the other, and adding a new tool invocation required remembering to copy the pattern. Centralizing the protocol gives every calling stage one place to update when external validator behavior changes.
+
+## Calling Workflows
+
+- `src/skf-create-skill/references/validate.md` — wraps `skill-check check --fix` (§2) and `split-body` (§4). Runs the optional post-restore re-validation.
+- `src/skf-update-skill/references/write.md` — wraps `skill-check check --fix` and `skill-check split-body --write` in §7. Does not run post-restore re-validation today; the post-write checks in §1 catch downstream issues.

package/src/shared/references/output-contract-schema.md

@@ -42,4 +42,4 @@ There is no generic helper that writes the schema above; each skill assembles th
 
 A generalised emitter (matching this document's schema) is a reasonable future helper when a second consumer materialises with the same shape. For now, skills that write this contract assemble the JSON in their terminal step — the work is small (5–8 fields) and skill-specific summary content benefits from being expressed inline alongside the rest of the step's logic.
 
-skf-quick-skill writes both the success-variant contract (`step-06-finalize.md` §3) and the error-variant contract on every HARD HALT (per `SKILL.md` § "Result Contract on HARD HALT") in this hand-assembled style.
+skf-quick-skill writes both the success-variant contract (`finalize.md` §3) and the error-variant contract on every HARD HALT (per `SKILL.md` § "Result Contract on HARD HALT") in this hand-assembled style.

package/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json",
   "title": "SKF_BRIEF_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document emitted by skf-brief-skill step-05 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
+  "description": "Single-line JSON document emitted by skf-brief-skill step 5 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
   "type": "object",
   "additionalProperties": false,
   "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason"],
@@ -10,7 +10,7 @@
     "status": {
       "type": "string",
       "enum": ["success", "error"],
-      "description": "'success' on the terminal happy path (after step-05 wrote the brief and step-06 returned). 'error' on any HARD HALT."
+      "description": "'success' on the terminal happy path (after step 5 wrote the brief and step 6 returned). 'error' on any HARD HALT."
     },
     "brief_path": {
       "type": ["string", "null"],
@@ -19,20 +19,20 @@
     "skill_name": {
       "type": "string",
       "minLength": 1,
-      "description": "Brief's skill_name field — present in every envelope (success and error) since it is captured at step-01 §6 before any of the other failure branches."
+      "description": "Brief's skill_name field — present in every envelope (success and error) since it is captured at step 1 §6 before any of the other failure branches."
     },
     "version": {
       "type": ["string", "null"],
-      "description": "Resolved brief version (target_version if set, else auto-detected, else '1.0.0'). Null when the run errored before step-05's version-resolution ran."
+      "description": "Resolved brief version (target_version if set, else auto-detected, else '1.0.0'). Null when the run errored before step 5's version-resolution ran."
     },
     "language": {
       "type": ["string", "null"],
-      "description": "Detected or user-confirmed primary language. Null when the run errored before step-02's language-detection ran."
+      "description": "Detected or user-confirmed primary language. Null when the run errored before step 2's language-detection ran."
     },
     "scope_type": {
       "type": ["string", "null"],
       "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only", null],
-      "description": "Confirmed scope.type from step-03. Null when the run errored before scope was confirmed."
+      "description": "Confirmed scope.type from step 3. Null when the run errored before scope was confirmed."
     },
     "exit_code": {
       "type": "integer",

package/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json",
   "title": "SKF_SETUP_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document emitted by skf-setup step-04 §4 when {headless_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer. Schema added in PR #247, extended in PR #248 (header / outputs / failure modes), extended again in this PR with previous_tier / tier_changed / tools_added / tools_removed / error.",
+  "description": "Single-line JSON document emitted by skf-setup step 4 §4 when {headless_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer. Schema added in PR #247, extended in PR #248 (header / outputs / failure modes), extended again in this PR with previous_tier / tier_changed / tools_added / tools_removed / error.",
   "type": "object",
   "additionalProperties": false,
   "required": ["skf_setup"],
@@ -11,6 +11,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": [
+        "status",
         "tier",
         "previous_tier",
         "tier_changed",
@@ -27,6 +28,11 @@
         "error"
       ],
       "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["success", "tier_failure", "write_failure", "blocked"],
+          "description": "Single-field outcome for pipeline branching. 'success' when no error and tier requirement (if any) is satisfied. 'tier_failure' when require_tier was set and is not satisfied. 'write_failure' when forge-tier.yaml or preferences.yaml could not be written. 'blocked' for any other halt that still produced an envelope (e.g. foreign ccc binary rejected pre-index)."
+        },
         "tier": {
           "type": "string",
           "enum": ["Quick", "Forge", "Forge+", "Deep"],
@@ -76,7 +82,7 @@
           "properties": {
             "status": {
               "type": "string",
-              "enum": ["fresh", "created", "failed", "none"]
+              "enum": ["fresh", "created", "failed", "none", "skipped"]
             },
             "indexed_path": { "type": ["string", "null"] },
             "file_count": { "type": ["integer", "null"], "minimum": 0 }
@@ -119,7 +125,7 @@
                 "phase": {
                   "type": "string",
                   "minLength": 1,
-                  "description": "Step or operation that failed (e.g. 'step-02-write-config:forge-tier.yaml')."
+                  "description": "Step or operation that failed (e.g. 'write-config:forge-tier.yaml')."
                 },
                 "path": { "type": "string", "minLength": 1, "description": "Absolute path of the file the failed operation targeted." },
                 "reason": { "type": "string", "minLength": 1, "description": "Human-readable error message." }