bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-export-skill/references/token-report.md

@@ -1,5 +1,14 @@
 ---
 nextStepFile: 'summary.md'
+# Resolve `{countTokensHelper}` by probing `{countTokensProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); the first
+# existing path wins. The helper emits deterministic per-artifact word/token
+# metrics as JSON so this step renders exact numbers instead of re-reading every
+# reference file to word-count it in-prompt. `tokens` is the char-over-four
+# estimate shared with skf-validate-output.py so all SKF token numbers agree.
+countTokensProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-count-tokens.py'
+  - '{project-root}/src/shared/scripts/skf-count-tokens.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Render the token report in {document_output_language}. -->
@@ -14,27 +23,48 @@ To calculate approximate token counts for all exported artifacts and present a c
 
 - Focus only on token counting and reporting — read-only measurement
 - Auto-proceed when complete
-- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), compute token counts per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total). Measure the managed section once for the run — it is shared across the batch. See step 1 §1c.
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), run the helper once per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total). The `managed_section` value is identical across runs (same target files) — measure and report it once for the run. See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-### 1. Calculate Token Counts
+### 1. Measure Token Counts
 
-For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers). This same heuristic is used in step 3 for snippet token estimation.
+Resolve `{countTokensHelper}` from `{countTokensProbeOrder}` (see frontmatter) — the first existing path wins. Then run it against the resolved skill package, passing every target context file so the shared managed section is measured:
 
-**Artifacts to measure:**
+```bash
+python3 {countTokensHelper} {resolved_skill_package} --target-file {context_file_1} --target-file {context_file_2}
+```
 
-1. **context-snippet.md** — The compressed snippet (if generated)
-2. **Managed section** — The complete `<!-- SKF:BEGIN/END -->` block (all skills, not just this one)
-3. **SKILL.md** — The full active skill document
-4. **metadata.json** — The machine-readable metadata
-5. **references/** — Total across all reference files (if present)
-6. **Full package total** — Sum of this skill's own artifacts (context-snippet.md + SKILL.md + metadata.json + references/). **Exclude the Managed section row (item 2)** — it is a shared all-skills cost (it bundles this skill's snippet plus every other skill's snippet), reported separately under Context Budget Impact. Including it would double-count this skill's snippet and fold in unrelated skills' costs.
+Pass one `--target-file` per entry in `target_context_files` (resolved in step 1). The helper measures the managed section from the first target file that contains a `<!-- SKF:BEGIN -->…<!-- SKF:END -->` block.
 
-**If passive_context was disabled:** Skip context-snippet.md and managed section measurements, note as "N/A (disabled)".
+The helper emits JSON:
+
+```json
+{
+  "files": [{"path": "…", "role": "…", "exists": true, "words": 0, "tokens": 0}],
+  "references_total": {"count": 0, "words": 0, "tokens": 0},
+  "managed_section": {"present": true, "source_file": "…", "words": 0, "tokens": 0},
+  "package_total": {"words": 0, "tokens": 0}
+}
+```
+
+**Read the JSON — do not re-count words in-prompt.** Each `tokens` value is a char-over-four estimate (`len(text)//4`, the SKF-wide convention shared with `skf-validate-output.py`); each `words` value is the whitespace-split count for the report's Words column. The `files` array carries one row per artifact — `role` is one of `context-snippet`, `skill-md`, `metadata`, `reference`. `package_total` already sums context-snippet.md + SKILL.md + metadata.json + `references_total` and **excludes** the `managed_section` row: the managed section is a shared all-skills cost (it bundles this skill's snippet plus every other skill's snippet), so folding it in would double-count this skill's snippet and pull in unrelated skills. It is reported separately under Context Budget Impact.
+
+**If `passive_context` was disabled:** the helper reports the `context-snippet.md` row with `exists: false` and `managed_section.present: false` — render both as "N/A (disabled)".
+
+**Graceful fallback (helper cannot run — e.g. no Python/uv on claude.ai web):** count the same artifacts in-prompt using the char-over-four convention (`tokens ≈ len(text)//4`, `words` = whitespace-split count). The JSON shape above documents exactly what to measure: context-snippet.md, SKILL.md, metadata.json, each file under references/ (summed as references_total), and the `<!-- SKF:BEGIN -->…<!-- SKF:END -->` block from the first target context file. The package total sums the first four and excludes the managed section.
 
 ### 2. Present Token Report
 
+Render the table straight from the helper JSON — no re-counting.
+
+- `context-snippet.md` row → `files[].tokens` / `.words` for `role: context-snippet`
+- `Managed section` row → `managed_section.words` / `.tokens` (report once for the run)
+- `SKILL.md` row → `files[]` for `role: skill-md`
+- `metadata.json` row → `files[]` for `role: metadata`
+- `references/` row → `references_total.words` / `.tokens`; `{count}` files = `references_total.count`
+- `Package total` row → `package_total.words` / `.tokens`
+
 "**Token Report**
 
 | Artifact | Words | Est. Tokens | Notes |
@@ -57,16 +87,4 @@ For each artifact, estimate tokens using the heuristic: **words * 1.3** (approxi
 
 Display: "**Proceeding to export summary...**"
 
-#### Menu Handling Logic:
-
-- After token report is displayed, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after reporting
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the token report is displayed will you load and read fully `{nextStepFile}` to execute the export summary.
-
+Auto-proceed (no user choices): once the token report is displayed, load, read entirely, and execute `{nextStepFile}`.

package/src/skf-export-skill/references/update-context.md

@@ -99,9 +99,9 @@ The helper handles v2-schema enforcement, v1→v2 migration, and the `platforms`
 
 Determine the set of skills to include in the rebuilt index:
 
-1. Start with all skill names listed in the manifest's `exports` object (if manifest exists)
-2. For each skill, record its `active_version` from the manifest (v2 schema)
-3. **Integrity guard — `active_version` must resolve to a versions entry:** Check that `versions[active_version]` exists as a key. If `active_version` is set but there is no matching entry under `versions`, the manifest is inconsistent (possible corruption or a botched v1→v2 migration). Skip this skill and log a loud warning: "**Manifest integrity warning:** `{skill-name}.active_version = v{active_version}` has no matching entry under `versions`. Skipping. Re-run `[EX] Export Skill` on `{skill-name}` to repair the manifest entry."
+1. Start with the manifest `exports` entries that survived the §4a integrity guard — those whose `active_version` resolves to a key in `versions` (if manifest exists)
+2. For each surviving skill, record its `active_version` from the manifest (v2 schema)
+3. The §4a integrity guard already skipped (and warned about) any entry whose `active_version` has no matching `versions` key, so build only from those survivors — no re-check or re-warning here.
 4. **Exclude deprecated skills:** If the `active_version` entry in `versions.{active_version}` has `status: "deprecated"`, skip this skill entirely — it has been dropped via drop-skill workflow and must not appear in the managed section. Log: "Skipping {skill-name} — active version v{active_version} is deprecated"
 5. Add the current export target skill name (ensures it is always included even before manifest is written) — use the version from `{resolved_skill_package}/metadata.json` as its `active_version`
 6. This is the **exported skill set** — each entry has a skill name and its resolved `active_version`
@@ -114,7 +114,9 @@ Instead of globbing `{skills_output_folder}/*/context-snippet.md`, resolve snipp
 1. Resolve `{skill_package}` using the skill's `active_version`: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
 2. Read `{skill_package}/context-snippet.md`
 3. **If snippet exists:** Add to skill index
-4. **If snippet does not exist at the versioned path:** Check for `active` symlink at `{skills_output_folder}/{skill-name}/active/{skill-name}/context-snippet.md`. If still not found, skip with warning: "Snippet missing for {skill-name} v{active_version} — skipping from managed section"
+4. **If snippet does not exist at the versioned path:** Check for `active` symlink at `{skills_output_folder}/{skill-name}/active/{skill-name}/context-snippet.md`.
+5. **If still not found, try the flat layout:** Read `{skills_output_folder}/{skill-name}/context-snippet.md` — a skill still on the pre-versioned flat layout (see `knowledge/version-paths.md` "Migration: Flat to Versioned"). This mirrors the flat-path fallback used when resolving a skill's SKILL.md in `load-skill.md` §1, so a manifest entry (or a first-export `--all` entry) that is still flat on disk is not silently dropped from the managed section.
+6. **If none of the three paths yields a snippet, skip with warning:** "Snippet missing for {skill-name} v{active_version} — skipping from managed section"
 
 **Skills NOT in the exported skill set are never scanned** — they have not been through export-skill and must not appear in the managed section (ADR-K).
 
@@ -126,15 +128,21 @@ A managed-section row becomes orphaned when a `[skill-name v...]` entry already
 
 **Cheap pre-check (always run before §5 assembly).** Scan **every** target context file (not just the first), deduplicate by `(skill_name, version)`, and present one consolidated gate. Asymmetric orphans — a row present in `.cursorrules` but absent from `CLAUDE.md`, or vice versa — must be detected; otherwise the §4 rebuild loop silently overwrites the orphan-bearing file's content (ADR-J violation: silent loss of user content).
 
-1. Initialize `orphan_managed_rows = []` (a list of `{skill_name, version, snippet_text, source_files: []}` entries — `source_files` carries provenance for the gate display and the audit `deviations[]` entry).
-2. **Iterate every entry in `target_context_files`:**
-   a. Read the prior managed section from `{entry.context_file}`. If the file does not exist or has no `<!-- SKF:BEGIN -->` marker, skip this entry — it has no orphans by definition.
-   b. Parse the `[skill-name v...]` rows between `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` into `file_rows` — a list of `{skill_name, version, snippet_text}` triples (capture the original snippet line(s) verbatim so they can be re-emitted unchanged if (b) is chosen).
-   c. For each `row` in `file_rows`:
-      - If `row.skill_name` is in the exported skill set built in 4b (manifest entries plus current-export targets), skip — not an orphan.
-      - Otherwise look up `(row.skill_name, row.version)` in `orphan_managed_rows`:
-        - If already present, append `entry.context_file` to that row's `source_files` list (deduplicated). Keep the first-encountered `snippet_text` — divergent snippets across files for the same `(skill, version)` are themselves a user-content asymmetry but the `(b) Preserve verbatim` semantic writes one canonical row to every target file, so picking the first is deterministic and avoids silently choosing.
-        - If new, append `{skill_name: row.skill_name, version: row.version, snippet_text: row.snippet_text, source_files: [entry.context_file]}`.
+The parse / dedup-by-`(skill_name, version)` / set-diff-against-the-exported-set is deterministic marker surgery with one correct answer per input — a mis-parsed row silently drops an installed skill from the rebuilt managed section (the ADR-J/K regression this gate guards against). Delegate it to `{rebuildManagedSectionsHelper}` (resolve from `{rebuildManagedSectionsProbeOrder}` in frontmatter — first existing path wins; if no candidate exists, the same HALT as §9 applies: exit code 4, `halt_reason: "context-rebuild-failed"`). Do not re-derive the rows in-prompt.
+
+1. Run the detector once across **every** target context file — pass each `target_context_files[].context_file` as a positional argument, and the comma-joined list of skill **names** from the exported skill set built in §4b (version is not needed for the orphan test) as `--exported-skills`:
+
+   ```bash
+   python3 {rebuildManagedSectionsHelper} orphan-detect {context-file-1} {context-file-2} … --exported-skills {name1,name2,…}
+   ```
+
+2. Set `orphan_managed_rows = result["orphan_managed_rows"]`. The helper reads each context file that exists and has a `<!-- SKF:BEGIN -->` marker, parses its `[skill-name v...]` rows, drops those whose `skill_name` is in the exported set, and deduplicates the survivors by `(skill_name, version)` — first-seen `snippet_text` wins (divergent snippets across files for the same `(skill, version)` are a user-content asymmetry, but `(b) Preserve verbatim` writes one canonical row to every target file, so first-seen is deterministic), and each file the row appears in is appended to a sorted `source_files`. The returned shape is:
+
+   ```json
+   {"status": "ok", "orphan_managed_rows": [{"skill_name": "…", "version": "…", "snippet_text": "…", "source_files": ["…"]}]}
+   ```
+
+   Each entry's `snippet_text` is the byte-exact prior snippet (re-emitted unchanged if (b) is chosen — the only surviving copy of an orphan's snippet is this known-exact string, never model-reconstructed); `source_files` carries provenance for the gate display and the audit `deviations[]` entry. A missing file, a file with no marker, or a section with no skill rows contributes nothing — the helper already handles those, so the list is empty in those cases.
 
 **If `orphan_managed_rows` is non-empty:** load `references/orphan-row-detection.md` and follow its (a) Drop / (b) Preserve verbatim / (c) Cancel gate protocol. The reference handles user prompting (with per-orphan `source_files` provenance), headless default (Preserve verbatim), `deviations[]` recording (including `source_files` per orphan for audit), and §6 result-contract integration.
 
@@ -211,7 +219,7 @@ Assemble the managed section in **two shapes** — the §9 write paths consume d
 **Case 4: Malformed markers (file contains `<!-- SKF:BEGIN` but no `<!-- SKF:END -->`)**
 - Action: HALT (exit code 5, `halt_reason: "malformed-markers"`) with warning: "Malformed SKF markers detected in `{target-file}` — `<!-- SKF:BEGIN` found but `<!-- SKF:END -->` is missing. Please restore the end marker manually before running export."
 - Do NOT attempt to write or append — the file is in an inconsistent state.
-- In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `manifest_path: null`, `context_files_updated: []`.
+- In headless mode, emit the error envelope per `references/result-envelope.md` with `manifest_path: null`, `context_files_updated: []`.
 
 ### 7. Present Change Preview
 
@@ -253,18 +261,13 @@ Display: "**Select:** [C] Continue — write changes to {target-file} | [X] Canc
 
 Display: "**Select:** [C] Continue — write changes to all targets | [X] Cancel and exit"
 
-#### Menu Handling Logic:
-
-- IF C: Write the changes to all target files (or single target), verify each write succeeded, then load, read entire file, then execute {nextStepFile}
-- IF X (or `cancel` / `exit` / `:q`): Display "Cancelled — no context files were written." and HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `skills`, `context_files_updated: []`, and `manifest_path: null`.
-- IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
+#### Gate handling
 
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve context file update"
-- ONLY proceed to next step when user selects 'C'
-- In dry-run mode, auto-proceed without writing
+- **[C]** — write the changes to all target files (or the single target), verify each write succeeded, then load, read entirely, and execute `{nextStepFile}`.
+- **[X]** / `cancel` / `exit` / `:q` — Display "Cancelled — no context files were written." and HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless, emit the error envelope per `references/result-envelope.md` with the resolved `skills`, `context_files_updated: []`, and `manifest_path: null`.
+- **Any other input** — help the user respond, then redisplay this gate.
+- **Headless** [default C]: auto-approve with [C], log "headless: auto-approve context file update".
+- **Dry-run**: auto-proceed without writing.
 
 ### 9. Write and Verify (Non-Dry-Run Only)
 
@@ -274,7 +277,7 @@ After user confirms with 'C', resolve the helpers in parallel — these are inde
 - `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` (used for Case 1)
 - `{manifestOpsHelper}` ← first existing path in `{manifestOpsProbeOrder}` (used in §9b)
 
-If any helper has no existing candidate, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) and emit the error envelope per SKILL.md "Result Contract (Headless)" — the rewrite's safety guarantees depend on these helpers and a fall-through to LLM-driven writes would silently regress atomicity, marker preservation, and the Case 4 malformed-marker HARD HALT contract.
+If any helper has no existing candidate, HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) and emit the error envelope per `references/result-envelope.md` — the rewrite's safety guarantees depend on these helpers and a fall-through to LLM-driven writes would silently regress atomicity, marker preservation, and the Case 4 malformed-marker HARD HALT contract.
 
 **Stage content via a shell-safe channel (all cases).** Managed-section snippets routinely contain backticks and `$` — API names like `` `Room::connect(...)` ``, tokens like `$threshold` and `${…}`. Inlining them as a double-quoted shell argument (`--content "…"`) or via `echo "…"` lets bash run command substitution and variable expansion, silently corrupting the written bytes — and because the helper's byte-identity verify runs against the already-corrupted string, it would still report success. No quoting style is safe (content can also contain single quotes, e.g. `'eager' | 'on-demand'`), so **never** inline the section into the command. Instead write the assembled section to a staging file with your file-write tool (which performs no shell interpretation), then feed it to the helper via stdin redirection — the helper reads stdin whenever `--content` is absent:
 
@@ -313,7 +316,7 @@ The helper performs the surgical between-marker swap with post-write verificatio
 **Verification (deferred to helpers):** the `replace`/`insert`/`write` actions above each perform their own verification. Treat any non-zero exit as a write failure:
 
 - HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) and report `{target-file}: {captured stderr}`.
-- In headless mode, emit the error envelope.
+- In headless mode, emit the error envelope per `references/result-envelope.md`.
 - Continue to the next target file only on success — partial-batch writes are acceptable in single-skill mode but the overall envelope reports per-target outcomes.
 
 On success per file, report: "**{target-file} updated successfully.** Verified by `{rebuildManagedSectionsHelper}` (or `{atomicWriteHelper}` for Case 1)."
@@ -322,7 +325,7 @@ On success per file, report: "**{target-file} updated successfully.** Verified b
 
 **This section executes ONCE after all context-file iterations complete** (outside the per-context-file loop defined in section 3). Only IDEs whose target context files were successfully written and verified in section 9 are recorded.
 
-**`ides` field definition:** `ides` is the list of IDE identifiers from `config.yaml.ides` (e.g. `claude-code`, `cursor`, `github-copilot`) whose context files were successfully written and verified in section 9. It is NOT the context file name (`CLAUDE.md`) and NOT the skill root path (`.claude/skills/`). Each IDE → context file → skill root mapping is defined in `skf-export-skill/assets/managed-section-format.md`.
+**`ides` field definition:** `ides` is the list of IDE identifiers from `config.yaml.ides` (e.g. `claude-code`, `cursor`, `github-copilot`) whose context files were successfully written and verified in section 9. It is NOT the context file name (`CLAUDE.md`) and NOT the skill root path (`.claude/skills/`). Each IDE → context file → skill root mapping is defined in `{managedSectionData}`.
 
 1. Read `{skills_output_folder}/.export-manifest.json` (or start with `{"schema_version": "2", "exports": {}}` if it does not exist)
 2. Ensure `schema_version` is `"2"` (if v1 was migrated in section 4a, the migrated structure is already in context). If any version entry still has a legacy `platforms` key, rename it to `ides` in place (see §4a).
@@ -356,9 +359,5 @@ On success per file, report: "**{target-file} updated successfully.** Verified b
 
 **Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name-list} — ides: {ides_written}.**" (list every skill in `skill_batch`)
 
-**Error handling:** If `{manifestOpsHelper}` exits non-zero, HALT (exit code 4, `halt_reason: "manifest-write-failed"`) with the captured `stderr`. The managed section was already written successfully; the operator's recovery path is to manually reconcile the on-disk managed section with the manifest, then re-run `[EX] Export Skill --all` to refresh the manifest. In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `manifest_path: null` and the partial `context_files_updated` list.
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run) and the write is verified will you load and read fully `{nextStepFile}` to execute the token report.
+**Error handling:** If `{manifestOpsHelper}` exits non-zero, HALT (exit code 4, `halt_reason: "manifest-write-failed"`) with the captured `stderr`. The managed section was already written successfully; the operator's recovery path is to manually reconcile the on-disk managed section with the manifest, then re-run `[EX] Export Skill --all` to refresh the manifest. In headless mode, emit the error envelope per `references/result-envelope.md` with `manifest_path: null` and the partial `context_files_updated` list.
 

package/src/skf-forger/SKILL.md

@@ -7,7 +7,7 @@ description: Skill compilation specialist — the forge master. Use when the use
 
 ## Overview
 
-This skill provides the Skill Forge's resident agent — Ferris, the forge master. Ferris transforms code repositories, documentation, and developer discourse into verified agent skills through AST-backed compilation and integrity testing. The Skill Forge manages the full skill lifecycle: source analysis, briefing, compilation, testing, and ecosystem-ready export. Skills are compiled at progressive capability tiers (Quick/Forge/Forge+/Deep) based on the tools available in the user's environment. Ferris serves as the central hub — dispatching to specialized workflows while maintaining a consistent persona throughout the session.
+Resident agent of the Skill Forge — the central hub that dispatches to specialized workflows across the skill lifecycle (source analysis, briefing, compilation, testing, ecosystem export) while holding one persona for the whole session.
 
 ## Identity & Principles
 
@@ -43,8 +43,9 @@ Structured reports with inline AST citations during work — no metaphor, no com
 | 12 | EX | Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules | skf-export-skill |
 | 13 | RS | Rename a skill across all its versions (transactional) | skf-rename-skill |
 | 14 | DS | Drop a skill — deprecate (soft) or purge (hard) | skf-drop-skill |
-| 15 | KI | List available knowledge fragments | (inline action) |
-| 16 | WS | Show current lifecycle position and forge tier status | (inline action) |
+| 15 | — | Orchestrate multi-library skill campaigns with dependency tracking | skf-campaign |
+| 16 | KI | List available knowledge fragments | (inline action) |
+| 17 | WS | Show current lifecycle position and forge tier status | (inline action) |
 
 Say "dismiss" or "exit persona" to leave Ferris at any time.
 
@@ -52,9 +53,8 @@ Say "dismiss" or "exit persona" to leave Ferris at any time.
 
 - **GUARD (config):** Verify `{project-root}/_bmad/skf/config.yaml` exists. If missing — HARD HALT: "**Cannot initialize.** SKF config not found. Run the `skf-setup` skill to initialize your forge environment."
 - **GUARD (sidecar):** Verify `{sidecar_path}` resolves to an actual directory path (not a literal `{sidecar_path}` string). If it does not resolve — HARD HALT: "**Cannot initialize.** `sidecar_path` is not defined in your installed config.yaml. Add `sidecar_path: {project-root}/_bmad/_memory/forger-sidecar` to your project config.yaml and retry. This is a known installer issue with `prompt: false` config variables."
-- Load COMPLETE file `{sidecar_path}/preferences.yaml`
-- Load COMPLETE file `{sidecar_path}/forge-tier.yaml`
-- ONLY write STATE files to `{project-root}/_bmad/_memory/forger-sidecar/` — reading from knowledge/ and workflow files is expected
+- Load `{sidecar_path}/preferences.yaml` and `{sidecar_path}/forge-tier.yaml` in full. If either is absent — a first run before `skf-setup` populated the sidecar — treat it as empty defaults and continue; the first-run path below handles a null tier.
+- Write state files only to `{project-root}/_bmad/_memory/forger-sidecar/`; reading from knowledge/ and workflow files elsewhere is expected.
 - When a workflow step directs knowledge consultation, consult `{project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv` to select the relevant fragment(s) and load only those files. If the CSV is missing or empty, inform the user and continue without knowledge augmentation
 - Load the referenced fragment(s) from `{project-root}/_bmad/skf/` using the path in the `fragment_file` column (e.g., `knowledge/overview.md` resolves to `{project-root}/_bmad/skf/knowledge/overview.md`) before giving recommendations on the topic the step directed
 
@@ -63,54 +63,47 @@ Say "dismiss" or "exit persona" to leave Ferris at any time.
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `sidecar_path`, `skills_output_folder`, `forge_data_folder`
 
-2. Execute Critical Actions above. Load `preferences.yaml` and `forge-tier.yaml` in parallel.
+2. Execute the Critical Actions above, loading `preferences.yaml` and `forge-tier.yaml` in parallel.
 
-3. **Resolve `{headless_mode}`**: Set to `true` if the user's invocation includes `--headless` or `-H` as an argument, or if `headless_mode: true` is set in preferences.yaml. Default: `false`. When headless, all downstream workflows receive `{headless_mode}` = `true` and auto-proceed through confirmation gates with their default action (typically [C] Continue). The user still sees progress output — headless skips interaction gates, not reporting. See `shared/references/headless-gate-convention.md` for the full gate-type specification and resolution rules.
+3. **Resolve `{headless_mode}`**: `true` if the invocation includes `--headless`/`-H` or preferences sets `headless_mode: true`, else `false`; pass it to all downstream workflows. Headless skips interaction gates, not progress reporting. See `shared/references/headless-gate-convention.md` for gate-type resolution.
 
 4. **Detect user context** from forge-tier.yaml:
-   - If `tier` is null/missing → first-run user. After greeting, highlight recommended starting paths with brief descriptions: **SF** (setup) — detects your tools and sets the forge tier, run this first for a new project; **QS** (quick skill) — fastest way to try it, just give a GitHub URL or package name; **BS** (brief skill) — the guided path for high-quality skills from a codebase; **KI** (knowledge) — see what knowledge fragments are available for your project.
+   - If `tier` is null/missing → first-run user. After greeting, highlight the recommended starting paths: **SF** (run this first — detects tools, sets the forge tier), **QS** (fastest trial — give a GitHub URL or package name), **BS** (guided path for a high-quality skill from a codebase), **KI** (see available knowledge fragments).
    - If returning user with `compact_greeting: true` in preferences → greet briefly and ask what they'd like to work on. Show the capabilities table only if they ask.
    - Otherwise → present the full capabilities table.
 
 5. **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. Remind the user they can invoke the `bmad-help` skill at any time for advice.
 
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+   The menu is a choice point — wait for the user's input rather than firing a workflow they never picked. Accept a number, a menu code, or a fuzzy command match.
 
-**CRITICAL Handling:** When user responds with a code, line number, or skill, check if the input contains **multiple codes** (space-separated or arrow-separated). If so, enter **Pipeline Mode** below. Otherwise, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. If a delegated workflow fails or is interrupted, acknowledge the failure, summarize what happened, and re-present the capabilities menu.
+6. **Surface any interrupted pipeline** — glob `{sidecar_path}/pipeline-result-latest.json`. If it exists and its overall pipeline status (`summary.status`) is `failed` or `partial`, read the recorded per-step status for the workflow it halted on and the workflows still pending, and include a resume offer in the greeting as the recommended next action. Accepting it re-enters Pipeline Mode with the pending codes; the user may pick any menu code instead. If the file is absent or its status is `success`, stay silent.
 
-## Pipeline Mode
+**Dispatch** — when the user responds with a code, number, or command:
+
+- **Multiple codes** (space- or arrow-separated, or a pipeline alias) → enter **Pipeline Mode** below.
+- **`KI` or `WS`** → run the matching handler under **Inline Actions** below (these rows carry no registered skill).
+- **Any other single code** → invoke the skill named in its Capabilities row, by that exact name. Dispatching to a name not in the table invents a capability that does not exist, so match the input to an exact registered skill first.
+- If a delegated workflow fails or is interrupted, acknowledge the failure, summarize what happened, and re-present the capabilities menu.
+
+## Inline Actions
 
-When the user provides multiple workflow codes (e.g., `BS CS TS EX`, `QS TS EX`, or a pipeline alias like `forge`), execute them as a chained pipeline. Load `shared/references/pipeline-contracts.md` for the full specification.
+These menu codes resolve to a handler here, not a registered skill:
+
+- **KI** — Load and display `{project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv`, the cross-cutting knowledge fragments available for JiT loading. If the CSV is missing, inform the user and suggest running SF (setup).
+- **WS** — Show the current lifecycle position, active skill briefs, and forge tier status.
+
+## Pipeline Mode
 
-**Pipeline activation:**
+When the user provides multiple workflow codes (e.g. `BS CS TS EX`, `QS TS EX`) or a pipeline alias (`forge`, `forge-auto`, `forge-quick`, `maintain`), execute them as a chained pipeline. Load `references/pipeline-mode.md` for the run procedure — parsing, sequence validation, the execute loop, circuit breakers, result contract, and special behaviors — and `shared/references/pipeline-contracts.md` for the alias, data-flow, and threshold tables.
 
-1. **Parse the sequence** — split codes, expand aliases (`deepwiki` → `AN[auto] BS[auto] CS TS[min:90] EX`, `forge` → `BS CS TS EX`, `forge-quick` → `QS TS EX`, `onboard` → `AN CS TS EX`, `maintain` → `AS US TS EX`), extract any bracket arguments (`CS[cocoindex]`, `TS[min:80]`)
-   **Alias lifecycle:** When the parsed alias is `onboard`, emit a deprecation notice **before** expanding the alias and **before** pipeline progress reporting begins. Emit on **every** invocation — this is not a one-time warning. After emitting the notice, expand `onboard` → `AN CS TS EX` as normal (no behavioral change — existing 80% default threshold applies):
+Only the alias names need recognizing here; `pipeline-mode.md` step 1 expands them against the pipeline-contracts.md table. One expansion is pinned here because its test gate is non-default: `forge-auto` → `AN[auto] BS[auto] CS TS[min:90] EX`, whose `TS[min:90]` matches init.md §1b's `forge-auto` → 90. Each chained workflow runs with `{pipeline_alias}` set to the alias name (`forge-auto`, `forge`, `forge-quick`, `maintain`) or `null` for ad-hoc code sequences.
 
-   > ⚠️ **onboard is deprecated — use deepwiki instead.** The onboard pipeline (AN CS TS EX at 80% threshold) still runs, but will be removed in v2.0. To migrate: replace `onboard` with `deepwiki <repo-url>`. deepwiki adds auto-brief generation (BS[auto]) and a 90% quality threshold.
+Two alias gotchas must be caught here, at recognition, before that procedure runs:
 
-2. **Validate the sequence** — check for anti-patterns (EX before TS, CS without BS, duplicates). If found, warn the user and ask to confirm or adjust. In `{headless_mode}`, warn but proceed.
-3. **Set `{headless_mode}` = true** — pipelines auto-activate headless mode for all workflows in the chain. The user committed to the sequence by providing it.
-4. **Execute left to right** — for each workflow in the sequence:
-   - a. **Report start**: "Pipeline [{current}/{total}]: Starting {code} ({description})..."
-   - b. **Resolve inputs** from the previous workflow's output using the Data Flow table in pipeline-contracts.md. If the previous workflow produced a `skill_name`, `brief_path`, or other handoff data, pass it as the input argument.
-   - c. **Invoke the workflow** with `{headless_mode}` = true, `{pipeline_alias}` set to the alias name (`deepwiki`, `forge`, `forge-quick`, `onboard`, `maintain`, or `null` for ad-hoc sequences), and any resolved arguments.
-   - d. **Check circuit breaker** after completion. Load the output artifact and validate against the threshold (default or user-specified via `[min:N]`). If the check fails: halt the pipeline, report what completed and what remains.
-   - e. **Report completion**: "Pipeline [{current}/{total}]: {code} complete — {brief summary of output}."
-5. **Pipeline summary** — after all workflows complete (or on halt), present a summary:
-   - Completed workflows with key outputs
-   - Failed/halted workflow (if any) with the halt reason
-   - Remaining workflows that were not executed
-   - Next steps recommendation
-6. **Result Contract** — write the pipeline result contract per `shared/references/output-contract-schema.md`: the per-run record at `{sidecar_path}/pipeline-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{sidecar_path}/pipeline-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include one entry per completed workflow in `outputs` (referencing each workflow's own `-latest.json` result record); include per-step status and the overall pipeline status in `summary`.
+**Deprecated (`deepwiki`):** expand it exactly as `forge-auto` and set `{pipeline_alias}` = `forge-auto`, but first emit a one-time notice:
 
-**deepwiki pipeline note:** `deepwiki <repo-url> --pin <version>` — the `--pin` argument is passed to AN's pipeline data context alongside the `[auto]` flag. AN's `step-auto-scope.md §0b` consumes it for pin resolution.
+> ⚠️ **`deepwiki` is now `forge-auto`.** The alias was renamed to avoid confusion with the DeepWiki MCP — this pipeline auto-forges a verified skill from source and does **not** call that MCP. `deepwiki` still works as a deprecated alias; prefer `forge-auto <repo-url>` going forward.
 
-**Special pipeline behaviors:**
-- `AN` in a pipeline with `CS`: if AN produces multiple recommended briefs, auto-select all and process sequentially in batch mode. If only one unit found, auto-select it.
-- `AS` followed by `US`: if `summary.severity` in `audit-skill-result-latest.json` is CLEAN, skip US and report "No drift detected — skipping update."
-- `TS` followed by `EX`: if test result is FAIL and score is below the circuit breaker threshold, halt before EX.
+**Removed (`onboard`):** do NOT expand it. HALT with:
 
-**Inline action handling:**
-- **KI**: Load and display `{project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv` — cross-cutting knowledge fragments available for JiT loading. If the CSV is missing, inform the user and suggest running SF (setup).
-- **WS**: Show current lifecycle position, active skill briefs, and forge tier status.
+> 🚫 **onboard has been removed.** Use `forge-auto <repo-url>` instead. forge-auto auto-scopes, auto-briefs, and tests at 90% quality. Run `forge-auto` with any GitHub URL, doc URL, or `--pin <version>`.

package/src/skf-forger/references/pipeline-mode.md

@@ -0,0 +1,34 @@
+# Pipeline Mode Execution
+
+The forger enters this procedure when the user supplies multiple workflow codes (e.g. `BS CS TS EX`, `QS TS EX`) or a pipeline alias (`forge`, `forge-auto`, `forge-quick`, `maintain`). It chains the workflows left to right, forwarding each output to the next input.
+
+Load `shared/references/pipeline-contracts.md` for the alias-expansion table, the Data Flow output→input map, circuit-breaker thresholds, bracket syntax, and the anti-pattern list. This file covers the run procedure that consumes those tables.
+
+## Activation
+
+1. **Parse the sequence** — run `uv run scripts/parse-pipeline.py '<sequence>'` (from the skf-forger skill root). It tokenizes (space or arrow separated), expands aliases, classifies each bracket argument (`CS[cocoindex]` → target, `TS[min:80]` → circuit-breaker override, `AN[auto]` → mode flag), and returns the normalized `plan`/`codes` plus any `anti_patterns` as JSON. Consume that output rather than re-deriving the expansion or checks by hand. `deepwiki`/`onboard` are already resolved at recognition before this procedure runs, so the sequence reaching this step is normalized. If the script cannot run, fall back to expanding aliases against the pipeline-contracts.md alias table and applying its anti-pattern table by hand.
+
+2. **Validate the sequence** — the parse output's `anti_patterns` array already lists any matches (EX before TS, CS without a brief, duplicate codes, US without AS), each with a message and suggestion. If it is non-empty, warn the user and ask to confirm or adjust. In `{headless_mode}`, warn but proceed.
+
+3. **Force `{headless_mode}` = true** — pipelines auto-activate headless mode for every workflow in the chain; the user committed to the sequence by providing it.
+
+4. **Execute left to right** — for each workflow:
+   - a. **Report start:** "Pipeline [{current}/{total}]: Starting {code} ({description})..."
+   - b. **Resolve inputs** from the previous workflow's output using the Data Flow table in pipeline-contracts.md. Pass any produced `skill_name`, `brief_path`, or other handoff data as the input argument.
+   - c. **Invoke the workflow** with `{headless_mode}` = true, `{pipeline_alias}` set to the alias name (`forge-auto`, `forge`, `forge-quick`, `maintain`, or `null` for ad-hoc sequences), and any resolved arguments.
+   - d. **Check the circuit breaker** after completion — load the output artifact and validate it against the threshold (default, or user-specified via `[min:N]`). On failure, halt the pipeline and report what completed and what remains.
+   - e. **Report completion:** "Pipeline [{current}/{total}]: {code} complete — {brief summary of output}."
+
+5. **Pipeline summary** — after all workflows complete (or on halt), present: completed workflows with key outputs; the failed/halted workflow (if any) with its halt reason; remaining unexecuted workflows; and a next-steps recommendation.
+
+6. **Result contract** — write the pipeline result contract per `shared/references/output-contract-schema.md`: the per-run record at `{sidecar_path}/pipeline-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{sidecar_path}/pipeline-result-latest.json` (stable path for consumers — copy, not symlink). Include one entry per completed workflow in `outputs` (each referencing that workflow's own `-latest.json` record); record per-step status for every workflow in the sequence — completed, halted, and not-yet-run — plus the overall pipeline status (`summary.status` — one of `success`, `failed`, or `partial`) in `summary`. On a `failed`/`partial` status, the forger's On Activation resume check reads that per-step record to offer continuation of the not-yet-run workflows.
+
+## forge-auto argument passing
+
+`forge-auto <repo-url> --pin <version>` — the `--pin` argument flows to AN's pipeline data context alongside the `[auto]` flag. AN's `step-auto-scope.md §0b` consumes it for pin resolution.
+
+## Special behaviors
+
+- **`AN` with `CS`:** if AN produces multiple recommended briefs, auto-select all and process them sequentially in batch mode. If only one unit is found, auto-select it.
+- **`AS` followed by `US`:** if `summary.severity` in `audit-skill-result-latest.json` is CLEAN, skip US and report "No drift detected — skipping update."
+- **`TS` followed by `EX`:** if the test result is FAIL and the score is below the circuit-breaker threshold, halt before EX.