bmad-module-skill-forge 2.0.0 → 2.0.1

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
 
@@ -53,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
 
@@ -64,58 +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.
 
-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.
+## Inline Actions
 
-**Pipeline activation:**
+These menu codes resolve to a handler here, not a registered skill:
 
-1. **Parse the sequence** — split codes, expand aliases (`forge-auto` → `AN[auto] BS[auto] CS TS[min:90] EX`, `forge` → `BS CS TS EX`, `forge-quick` → `QS TS EX`, `maintain` → `AS US TS EX`), extract any bracket arguments (`CS[cocoindex]`, `TS[min:80]`)
-   **Deprecated aliases:** If the parsed alias is `deepwiki`, expand it exactly as `forge-auto` and set `{pipeline_alias}` to `forge-auto`, but first emit a one-time notice:
+- **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
 
-   > ⚠️ **`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.
+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.
 
-   **Removed aliases:** If the parsed alias is `onboard`, do NOT expand it. Instead, HALT with:
+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 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>`.
+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 (`forge-auto`, `forge`, `forge-quick`, `maintain`, or `null` for ad-hoc sequences; a `deepwiki` invocation resolves to `forge-auto`), 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:
 
-**forge-auto pipeline note:** `forge-auto <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.

package/src/skf-forger/scripts/parse-pipeline.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic parse + validation of a forger pipeline invocation.
+
+Pipeline Mode (references/pipeline-mode.md §1-2) turns a raw code sequence
+(`BS CS[cocoindex] TS[min:80] EX`, `AN -> CS -> TS -> EX`, or a bare alias like
+`forge-auto`) into a normalized run plan and a list of sequence anti-patterns.
+Splitting the tokens, expanding aliases against a fixed table, classifying each
+bracket argument, and detecting anti-patterns (duplicates, ordering, missing
+prerequisites) is set/order plumbing with exactly one correct answer per input —
+so it runs here, not in the prompt. The prompt keeps only the judgment the
+script cannot make: interpreting the user's freeform request into a code
+sequence, and deciding whether to proceed past a warned anti-pattern.
+
+The alias-expansion and anti-pattern tables mirror
+`src/shared/references/pipeline-contracts.md` (the human-readable contract);
+this script is the executable form the forger consumes.
+
+CLI usage:
+  uv run scripts/parse-pipeline.py 'BS CS TS EX'      # positional
+  uv run scripts/parse-pipeline.py 'forge-auto'       # bare alias
+  echo 'AN -> CS -> TS -> EX' | uv run scripts/parse-pipeline.py --stdin
+
+Output (stdout, one object):
+  {
+    "raw": "<input>",
+    "alias": "forge" | null,          # set when the input was a lone alias
+    "deprecated_alias": "deepwiki" | null,
+    "removed_alias": "onboard" | null,
+    "expanded": ["BS", "CS", "TS", "EX"],   # normalized tokens (post-expansion)
+    "plan": [{"code","min","mode","target"}, ...],
+    "codes": ["BS", "CS", "TS", "EX"],
+    "unknown_codes": [],
+    "anti_patterns": [{"pattern","message","suggestion"}, ...],
+    "valid": <bool>                   # runnable: real codes, no unknowns, not removed
+  }
+
+Exit codes:
+  0  — parsed, runnable (anti-patterns and a deprecated alias are warnings)
+  1  — no input provided (usage error)
+  2  — removed alias (e.g. `onboard`) — the forger HALTs
+  3  — nothing runnable (empty, or unknown codes) — the forger corrects course
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+# Workflow codes that can appear in a pipeline. KI/WS are inline actions, not
+# pipeline steps; `campaign` is a standalone workflow, not a pipeline code.
+KNOWN_CODES = frozenset(
+    {"SF", "AN", "BS", "CS", "QS", "SS", "US", "AS", "VS", "RA", "TS", "EX", "RS", "DS"}
+)
+
+# Only these accept a `min:N` circuit-breaker override; on other codes a
+# `min:N` bracket is ignored (recorded as `min: null`).
+CIRCUIT_BREAKER_CODES = frozenset({"AN", "CS", "TS", "AS", "VS"})
+
+# Alias table — mirrors pipeline-contracts.md. `forge-auto`'s TS[min:90] gate is
+# non-default and is kept in lockstep with init.md §1b's forge-auto → 90 lookup.
+ALIASES = {
+    "forge-auto": ["AN[auto]", "BS[auto]", "CS", "TS[min:90]", "EX"],
+    "forge": ["BS", "CS", "TS", "EX"],
+    "forge-quick": ["QS", "TS", "EX"],
+    "maintain": ["AS", "US", "TS", "EX"],
+}
+DEPRECATED_ALIASES = {"deepwiki": "forge-auto"}  # renamed; still expands
+REMOVED_ALIASES = {"onboard"}  # no expansion — the forger HALTs
+
+_TOKEN_RE = re.compile(r"^([A-Za-z]+)(?:\[([^\]]*)\])?$")
+_ARROWS = re.compile(r"->|→|—>|»")
+
+
+def _tokenize(raw):
+    """Split a raw sequence on whitespace and arrow separators."""
+    normalized = _ARROWS.sub(" ", raw)
+    return [t for t in normalized.split() if t]
+
+
+def _classify_bracket(code, value):
+    """Return (min, mode, target) for a bracket value on a given code."""
+    if value is None or value == "":
+        return None, None, None
+    m = re.fullmatch(r"min:(\d+)", value)
+    if m:
+        # min:N only applies to circuit-breaker codes; ignored elsewhere.
+        return (int(m.group(1)) if code in CIRCUIT_BREAKER_CODES else None), None, None
+    if value == "auto":
+        return None, "auto", None
+    return None, None, value
+
+
+def _detect_anti_patterns(codes):
+    """Deterministic sequence checks — mirrors pipeline-contracts.md."""
+    found = []
+
+    # Duplicate codes.
+    seen = set()
+    dupes = []
+    for c in codes:
+        if c in seen and c not in dupes:
+            dupes.append(c)
+        seen.add(c)
+    if dupes:
+        found.append(
+            {
+                "pattern": "duplicate-codes",
+                "codes": dupes,
+                "message": f"same workflow appears more than once: {', '.join(dupes)}",
+                "suggestion": "remove the duplicate",
+            }
+        )
+
+    # EX before TS (equivalently, TS after EX).
+    ex_idxs = [i for i, c in enumerate(codes) if c == "EX"]
+    ts_idxs = [i for i, c in enumerate(codes) if c == "TS"]
+    if ex_idxs and ts_idxs and min(ex_idxs) < max(ts_idxs):
+        found.append(
+            {
+                "pattern": "ex-before-ts",
+                "codes": ["EX", "TS"],
+                "message": "EX (export) runs before TS (test) — exporting an untested skill",
+                "suggestion": "move TS before EX",
+            }
+        )
+
+    # CS without BS or AN.
+    if "CS" in codes and "BS" not in codes and "AN" not in codes:
+        found.append(
+            {
+                "pattern": "cs-without-brief",
+                "codes": ["CS"],
+                "message": "CS (compile) has no preceding BS or AN — compiling without a brief",
+                "suggestion": "use QS for the quick path, or add AN/BS to produce a brief",
+            }
+        )
+
+    # US without AS.
+    if "US" in codes and "AS" not in codes:
+        found.append(
+            {
+                "pattern": "us-without-audit",
+                "codes": ["US"],
+                "message": "US (update) has no preceding AS — updating without an audit",
+                "suggestion": "run AS first to detect what changed",
+            }
+        )
+
+    return found
+
+
+def parse_pipeline(raw):
+    """Parse and validate a raw pipeline sequence. Deterministic."""
+    tokens = _tokenize(raw)
+    result = {
+        "raw": raw,
+        "alias": None,
+        "deprecated_alias": None,
+        "removed_alias": None,
+        "expanded": [],
+        "plan": [],
+        "codes": [],
+        "unknown_codes": [],
+        "anti_patterns": [],
+        "valid": False,
+    }
+    if not tokens:
+        return result
+
+    # Alias handling — only when the sequence is a lone alias token.
+    if len(tokens) == 1:
+        lone = tokens[0].lower()
+        if lone in REMOVED_ALIASES:
+            result["removed_alias"] = lone
+            return result
+        if lone in DEPRECATED_ALIASES:
+            result["deprecated_alias"] = lone
+            target = DEPRECATED_ALIASES[lone]
+            result["alias"] = target
+            tokens = list(ALIASES[target])
+        elif lone in ALIASES:
+            result["alias"] = lone
+            tokens = list(ALIASES[lone])
+
+    result["expanded"] = []
+    for tok in tokens:
+        m = _TOKEN_RE.match(tok)
+        if not m:
+            result["unknown_codes"].append(tok)
+            continue
+        code = m.group(1).upper()
+        value = m.group(2)
+        result["expanded"].append(
+            f"{code}[{value}]" if value not in (None, "") else code
+        )
+        if code not in KNOWN_CODES:
+            result["unknown_codes"].append(tok)
+            continue
+        min_n, mode, target = _classify_bracket(code, value)
+        result["codes"].append(code)
+        result["plan"].append(
+            {"code": code, "min": min_n, "mode": mode, "target": target}
+        )
+
+    result["anti_patterns"] = _detect_anti_patterns(result["codes"])
+    result["valid"] = bool(result["codes"]) and not result["unknown_codes"]
+    return result
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="parse-pipeline",
+        description=(
+            "Deterministic parse + validation of a forger pipeline invocation "
+            "(pipeline-mode.md §1-2): tokenize, expand aliases, classify bracket "
+            "arguments, and detect sequence anti-patterns, returning a normalized "
+            "run plan as JSON."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "sequence",
+        nargs="?",
+        help="Raw pipeline sequence as a positional argument.",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the raw sequence from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.sequence is not None:
+        return args.sequence
+    return ""
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print("error: no input provided (positional arg or --stdin)", file=sys.stderr)
+        return 1
+
+    result = parse_pipeline(raw)
+    print(json.dumps(result, indent=2))
+    if result["removed_alias"]:
+        return 2
+    if not result["valid"]:
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())