@entelligentsia/forgecli 0.21.0 → 1.0.3

package/dist/forge-payload/meta/workflows/_fragments/friction-emit.md

@@ -1,6 +1,6 @@
 <!-- Canonical Friction Emit fragment.
      Referenced from meta-implement.md, meta-fix-bug.md, meta-validate.md,
-     meta-plan-task.md, and meta-orchestrate.md. /forge:enhance --phase 2
+     meta-plan-task.md, and meta-orchestrate.md. /forge:rebuild --enrich (phase 2)
      greps generated workflows for `## Friction Emit` to discover the channel.
 
      PLAN-11 / SLICE-2 (2026-05-14): friction is now recorded via the
@@ -16,7 +16,7 @@ When the persona detects skill friction during the workflow — a referenced
 skill is unused, fails on invocation, is missing from the registry, has gone
 stale relative to current architecture, or is redundant with another skill —
 record a judgement-only friction signal. The orchestrator drains the
-signals and emits the corresponding events so `/forge:enhance --phase 2`
+signals and emits the corresponding events so `/forge:rebuild --enrich` (phase 2)
 can act on them.
 
 ## Trigger conditions

package/dist/forge-payload/meta/workflows/_fragments/generation-instructions.md

@@ -33,8 +33,8 @@
 **`Persona Self-Load`** — *conditional*. Required when the generated workflow uses the
 Persona Self-Load pattern (the generated file must begin by reading a persona `.md` file
 before any other tool use). Specify the exact persona path. Used in: `meta-collate.md`,
-`meta-retrospective.md`, `meta-review-sprint-completion.md`, `meta-sprint-intake.md`,
-`meta-sprint-plan.md`. Omit for subagent-targeted workflows where the persona is loaded
+`meta-retro.md`, `meta-review-sprint-completion.md`, `meta-new-sprint.md`,
+`meta-plan-sprint.md`. Omit for subagent-targeted workflows where the persona is loaded
 by the orchestrator before dispatch.
 
 **`Workflow Structure`** — *required*. Names the generated file slug and asserts the
@@ -51,8 +51,8 @@ run inline, and mandates the `Agent` tool for sub-tasks.
 substitutions the generator must embed (stack commands, KB paths, template references,
 task ID format, etc.).
 
-**`Token Reporting`** — *required* (with one exception: `meta-quiz-agent.md` omits it
-because quiz-agent is an inline helper, not an orchestrated phase). Standard form: `See
+**`Token Reporting`** — *required* (with one exception: `meta-check-agent.md` omits it
+because check-agent is an inline helper, not an orchestrated phase). Standard form: `See
 \`_fragments/finalize.md\` — wire via \`file_ref:\`.` Expanded token-reporting prose is
 used in workflows where the generated file must mandate a specific sidecar-emit sequence
 (retrospective, sprint-intake, sprint-plan, review-sprint-completion) — in those cases,

package/dist/forge-payload/meta/workflows/_fragments/iron-laws.md

@@ -52,7 +52,7 @@ into the standard three-bullet structure.
 
 Some workflows have no `## Iron Laws` section by design:
 
-- `meta-quiz-agent.md` — utility workflow; no store writes; no output contract.
+- `meta-check-agent.md` — utility workflow; no store writes; no output contract.
 - `meta-review-sprint-completion.md` — read-only verification; no state transitions.
 
 Intentional omissions are documented with an inline comment before the `## Algorithm`

package/dist/forge-payload/meta/workflows/meta-approve.md

@@ -41,13 +41,25 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase approve --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
+
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `review-approved`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:review-code (or /forge:validate) must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
 1. Load Context:
    - Read task prompt
    - Read final PLAN.md

package/dist/forge-payload/meta/workflows/meta-bug-triage.md

@@ -0,0 +1,210 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Medium
+audience: subagent
+phase: triage
+context:
+  architecture: false
+  prior_summaries: delta
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [bug-fixer]
+  skills: [bug-fixer, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🍂 Meta-Workflow: Bug Triage
+
+## Purpose
+
+The Bug Fixer reproduces a reported bug, confirms root cause, decides the
+fix route (Path A short-circuit vs Path B full loop), and writes the
+triage artifact + summary. This is the **first phase** of `/forge:fix-bug`
+and the only phase that records the route decision read by the orchestrator
+(`meta-fix-bug.md`) to select `phases_A` vs `phases_B`.
+
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Reproduce the bug before deciding anything. A bug without a confirmed
+  reproduction has no business going to plan-fix or implement.
+- Read `.forge/personas/bug-fixer.md` first; print the persona identity
+  line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`).
+  Never edit `.forge/store/*.json` directly.
+- **Triage NEVER writes `bug.status`.** The orchestrator (`meta-fix-bug.md`)
+  owns the `reported → triaged` and `triaged → in-progress` transitions.
+  Writing `bug.status` from this workflow violates `meta-fix-bug.md
+  § Iron Laws #2` (parallel to `meta-review-plan.md`'s "Supervisor NEVER
+  writes entity status" rule).
+- Triage is a **single phase**. Do NOT call `forge_preflight` with any
+  other `--phase` value. Do NOT call `forge_store update-status`,
+  `set-bug-summary` for any non-triage phase, or `forge_store emit`.
+  These are orchestrator-owned or other-phase-owned actions. The
+  phase-ownership guard in forge-cli will reject violations at the tool
+  layer, but the Iron Law names the rule.
+
+## Store-Write Verification
+
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
+
+## Algorithm
+
+```
+
+0. Pre-flight Gate Check:
+   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase triage --bug {bugId}`
+   - Exit 1 (gate failed) → print stderr and HALT. Do not proceed.
+   - Exit 2 (misconfiguration) → print stderr and HALT.
+   - Exit 0 → continue.
+
+1. Load Context:
+   - Read `.forge/personas/bug-fixer.md` first; print the persona identity
+     line to stdout before any other tool use.
+   - Read the bug record:
+     `forge_store({ command:"read", entity:"bug", id:"{bugId}" })`
+   - Read business domain docs relevant to the reported symptom.
+   - store-cli verbs: `read` | `list` | `write` | `emit` |
+     `update-status` | `set-summary` | `set-bug-summary` | `describe` |
+     `nlp` | `query` | `delete` — there is no `get`/`set`/`find`. See
+     `_fragments/store-cli-verbs.md` for full notes.
+
+2. Reproduce:
+   - Construct a minimal reproduction: a failing test, a short script,
+     or a documented manual sequence that triggers the reported symptom.
+   - If reproduction cannot be achieved with the information in the bug
+     record, write what was tried in TRIAGE.md, set the route to "B"
+     (any uncertainty defaults to Path B), and continue to root-cause
+     research with the reporter's narrative as the working hypothesis.
+
+3. Root-Cause Research:
+   - Read the code paths implicated by the reproduction.
+   - Confirm (or revise) the reporter's stated root cause via direct
+     inspection of source files and tests.
+   - Note collateral damage: which other call sites, schemas, or
+     workflows share the defective shape.
+
+4. Path A / Path B Eligibility:
+   - Apply the criteria in § "Path A / Path B Eligibility" below.
+   - Record the route decision and the explicit enumeration of each
+     criterion in the findings section of the triage summary.
+
+5. Write Triage Artifacts:
+   - Write the triage artifact (markdown narrative):
+     `forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}",
+                       artifact:"triage", content:"<markdown>" })`
+   - Write the triage-summary sidecar (JSON shape below):
+     `forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}",
+                       artifact:"triage-summary", content:"<JSON>" })`
+
+6. Finalize:
+   - **No status write.** The orchestrator (`meta-fix-bug.md`) writes the
+     `reported → triaged` and `triaged → in-progress` transitions on
+     return. Writing `bug.status` from this workflow is forbidden by
+     Iron Laws above and is rejected by the phase-ownership guard.
+   - **Do NOT emit a phase event yourself.** The orchestrator owns event
+     emission — it composes the canonical event from runtime telemetry
+     (model, provider, tokens, wall times) plus the SUMMARY you write
+     in the next step.
+
+7. Emit Summary Sidecar:
+   - The JSON written in step 5 MUST have this shape (the `route` field
+     is required; allowed values: `"A"` or `"B"`):
+
+     ```json
+     {
+       "objective":   "Triage FORGE-BUG-NNN — reproduce, locate, decide route.",
+       "key_changes": ["<up to 12 bullets, 200 chars each — findings or actions>"],
+       "findings": [
+         "Root cause: <one line>",
+         "Reproduction: <one line>",
+         "Route decision: A | B",
+         "Rationale: <one line>"
+       ],
+       "verdict":     "n/a",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"TRIAGE.md",
+       "route":       "A"
+     }
+     ```
+
+   - Call:
+     ```
+     forge_store({ command:"set-bug-summary", entity:"bug",
+                   id:"{bugId}", phase:"triage",
+                   file:"engineering/bugs/{bugDir}/TRIAGE-SUMMARY.json" })
+     ```
+   - If the set-bug-summary call exits non-zero, fix the sidecar JSON
+     and retry (up to 3 attempts per the Store-Write Verification rule).
+     Do not proceed without a valid summary.
+
+> **Field-naming caution — runtime-tested.** The route field is named
+> `route`, never `path`. The bug schema's top-level `path` field is the
+> bug's **artifact directory** (e.g. `engineering/bugs/EMG-BUG-001-...`).
+> Conflating the two caused EMBERGLOW-BUG-001 (v0.44.0 first run) to land
+> its `TRIAGE.md` under `.forge/store/bugs/` instead of `engineering/bugs/`.
+> Triage MUST NOT touch `bug.path` — that field is set at bug creation
+> and never modified by triage.
+```
+
+## Path A / Path B Eligibility
+
+Path A is **eligible only when ALL** of the following hold. The triage
+summary `findings` array MUST enumerate each criterion explicitly with a
+pass/fail mark, so reviewers can audit the decision:
+
+- `bug.severity ∈ {minor}`
+- Fix is contained in a single file
+- Estimated diff ≤ ~20 lines (judgement call; one screen)
+- No schema, API, migration, security, or build-system change
+- A regression test is obvious from the reproduction script (single short
+  test case, no new fixtures, no test-harness change)
+
+If any criterion fails, the triage subagent MUST select Path B.
+
+**Path B is the default.** Any uncertainty resolves to Path B. It runs the
+same plan/review/implement/review/approve/commit shape as
+`meta-orchestrate.md`. Picking Path A under uncertainty is the documented
+failure mode (over-eager short-circuit).
+
+## Triage Artifact Contents (TRIAGE.md)
+
+The narrative artifact MUST contain:
+
+1. **Reported symptom** — one paragraph summarising the bug report.
+2. **Reproduction** — exact steps, commands, or test case that triggers
+   the symptom; copy of the failing output.
+3. **Root cause** — one or two paragraphs naming the defective code path,
+   schema, or workflow. Cite file paths and line numbers.
+4. **Path A / Path B enumeration** — for each criterion above, mark
+   pass/fail with one-line evidence.
+5. **Route decision and rationale** — the chosen route and the
+   single-sentence justification.
+6. **Collateral findings** — any related shapes, call sites, or
+   workflows that share the defective pattern (filed as follow-ups in
+   the commit phase, not fixed here).
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- The generated `triage.md` MUST include all four markers required by
+  `forge-cli/src/extensions/forgecli/lib/manifest-checker.ts §
+  checkMaterialization`: (1) `## Store-Write Verification` heading;
+  (2) `## Iron Laws` heading; (3) literal `forge_store` token in body;
+  (4) `.forge/personas/bug-fixer.md` referenced in body.
+- Token Reporting: `_fragments/finalize.md` — wire via `file_ref:`.
+- Event Emission: orchestrator-owned; this workflow MUST NOT call
+  `forge_store emit` for phase events.
+
+## Friction Emit
+
+Emit `type:friction` `{workflow:triage, persona:bug-fixer, issue}` per
+`_fragments/friction-emit.md`.

package/dist/forge-payload/meta/workflows/meta-check-agent.md

@@ -0,0 +1,138 @@
+---
+requirements:
+  reasoning: Medium
+  context: High
+  speed: Low
+deps:
+  personas: [qa-engineer]
+  skills: [qa-engineer, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: [architecture/stack.md, MASTER_INDEX.md]
+  config_fields: [paths.engineering]
+---
+
+# 🍵 Meta-Workflow: Quiz Agent
+
+## Purpose
+
+Verify that an agent has correctly loaded and understood the project's knowledge
+base before beginning a high-stakes task (e.g. a schema change, a significant
+refactor, a deployment, or a migration step).
+
+The quiz is short — 5–7 questions drawn directly from the project's own architecture
+and process docs. Vague answers fail. Pass requires specific, factual responses.
+
+<!-- No Iron Laws section: quiz-agent is a utility workflow that makes no store writes and enforces no output contract. Knowledge-check only. It is invoked inline by other workflows, not dispatched as a task phase by the orchestrator. -->
+
+## Algorithm
+
+```
+1. Ask the quiz questions below (in order).
+
+2. Evaluate each answer:
+   - PASS: specific and factually correct per the project KB
+   - FAIL: vague ("some validation"), wrong, or "I'm not sure"
+
+3. Verdict:
+   - All pass → proceed with the original task.
+   - Any fail → re-read the KB docs listed in "Fail Action", then retry the quiz.
+   - Fail twice → escalate to the user before beginning the task.
+```
+
+## Questions
+
+(Project-specific questions are generated here during init — see Generation Instructions.)
+
+## Pass Criteria
+
+All questions answered correctly and specifically. Vague answers fail.
+
+## Fail Action
+
+Re-read the project knowledge base docs listed here, then retry:
+
+(Project-specific KB doc paths are embedded here during init.)
+
+Then retry the quiz. If the agent fails twice, escalate to the user before
+beginning the task.
+
+---
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template (quiz-agent: no token-reporting or event-emission — inline helper workflow) -->
+## Generation Instructions
+
+### Overview
+
+The generated `quiz_agent.md` tests whether an agent genuinely understands
+THIS project's conventions, architecture, and processes — not Forge in general.
+
+Questions must be answerable only by reading the project's own KB docs.
+Generic questions about Claude Code or Forge internals are NOT appropriate
+unless this project's KB explicitly documents them as project conventions.
+
+### Question generation
+
+Read the following (already generated by earlier phases):
+- `{KB_PATH}/architecture/` — all .md files
+- `{KB_PATH}/business-domain/` — all .md files
+- `{KB_PATH}/stack-checklist.md`
+- `{KB_PATH}/MASTER_INDEX.md`
+
+Generate 5–7 questions that test specific knowledge of this project. Each
+question must:
+1. Reference a specific fact from the project KB (not common knowledge)
+2. Have an unambiguous correct answer findable in the KB
+3. Cover at least three of these categories:
+   - Stack conventions (language, framework rules, linting, build)
+   - Architecture (key components, service boundaries, data flow)
+   - Domain entities (core business objects and their relationships)
+   - Process (how work is tracked, committed, reviewed, deployed)
+   - Constraints (what is explicitly forbidden or required)
+
+Avoid yes/no questions. Prefer "what", "where", "name", "describe" forms.
+
+### Fail Action doc list
+
+List the architecture and business-domain docs that cover the question topics.
+Use the actual paths as generated (e.g. `{KB_PATH}/architecture/stack.md`).
+Include `{KB_PATH}/stack-checklist.md` always.
+
+## Template Output Format
+
+```markdown
+# 🍵 Workflow: Quiz Agent — {Project Name}
+
+## Purpose
+
+Verify that an agent has correctly loaded and understood the {Project Name}
+knowledge base before beginning a high-stakes task.
+
+---
+
+## Questions
+
+1. **[Category]:** [Question text]
+2. ...
+
+## Pass Criteria
+
+All [N] questions answered correctly and specifically. Vague answers
+("generally something", "I think it's...") fail.
+
+## Fail Action
+
+Re-read:
+- `{KB_PATH}/architecture/[doc1].md`
+- `{KB_PATH}/architecture/[doc2].md`
+- `{KB_PATH}/stack-checklist.md`
+- (any other docs covering the question topics)
+
+Then retry the quiz. If the agent fails twice, escalate to the user before
+beginning the task.
+```
+
+### Token Reporting
+
+The generated `quiz_agent.md` does NOT include Token Reporting or Event Emission —
+it is invoked inline by other workflows (not by the orchestrator as a task phase).

package/dist/forge-payload/meta/workflows/meta-commit.md

@@ -41,7 +41,7 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase commit --{entity_kind} {record_id}`
@@ -49,6 +49,17 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
 
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `approved`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:approve must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
 1. Load Context:
    - Read the record manifest (task or bug, per entity_kind).
    - Read ARCHITECT_APPROVAL.md from the record's artifact directory:

package/dist/forge-payload/meta/workflows/meta-enhance.md

@@ -104,7 +104,7 @@ Receive the phase flag from the command invocation:
 |------|------|
 | `--phase 1` or `--auto` | Auto-apply: placeholder fills only — **use after** `/forge:init` completes to fill `{{KEY}}` placeholders from project signals |
 | `--phase 2` | Propose-diffs: sprint artifact + friction scan — **use after** a sprint completes to turn friction events into persona/skill enrichments |
-| `--phase 3` | Drift detection: full codebase vs structural-element comparison — **use on-demand** or after `/forge:calibrate` to detect stale references |
+| `--phase 3` | Drift detection: full codebase vs structural-element comparison — **use on-demand** or after `/forge:health --fix` to detect stale references |
 
 Default to `--phase 3` if no phase flag is given.
 
@@ -126,7 +126,7 @@ Read `.forge/config.json`. Resolve:
 
 ### When to run
 
-Invoked by T09 post-init hook (`--auto`) or manually via `/forge:enhance --phase 1`.
+Invoked by T09 post-init hook (`--auto`) or manually via `/forge:rebuild --enrich --phase 1`.
 
 ### Algorithm
 
@@ -207,7 +207,7 @@ Invoked by T09 post-init hook (`--auto`) or manually via `/forge:enhance --phase
 
 ### When to run
 
-Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
+Invoked by T09 post-sprint hook or manually via `/forge:rebuild --enrich --phase 2`.
 
 ### Algorithm
 
@@ -595,8 +595,8 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
 
 ### When to run
 
-Invoked by `/forge:enhance --phase 3` (default when no phase given), or delegated by
-`/forge:calibrate` after its Step 4 drift categorization.
+Invoked by `/forge:rebuild --enrich --phase 3` (default when no phase given), or delegated by
+`/forge:health --fix` after its Step 4 drift categorization.
 
 ### Algorithm
 

package/dist/forge-payload/meta/workflows/meta-fix-bug.md

@@ -31,7 +31,7 @@ Phases`):
 
 | Phase | Role | Persona | Workflow | Path A | Path B |
 |---|---|---|---|---|---|
-| triage | `triage` | bug-fixer | (inline algorithm) | yes | yes |
+| triage | `triage` | bug-fixer | `triage.md` | yes | yes |
 | plan-fix | `plan` | engineer | `plan_task.md` (bug-mode) | no | yes |
 | review-plan | `review-plan` | supervisor | `review_plan.md` | no | yes |
 | implement | `implement` | engineer | `implement_plan.md` (bug-mode) | yes | yes |
@@ -101,24 +101,11 @@ The `route` field is required. Allowed values: `"A"` or `"B"`.
 > Triage subagents MUST NOT touch `bug.path` — that field is set at bug
 > creation and never modified by triage.
 
-### Path A — short-circuit (eligibility)
+### Path A / Path B eligibility
 
-Path A is **eligible only when ALL** of the following hold. Triage subagent
-must enumerate each in its findings:
-
-- `bug.severity ∈ {minor}`
-- Fix is contained in a single file
-- Estimated diff ≤ ~20 lines (judgement call; one screen)
-- No schema, API, migration, security, or build-system change
-- A regression test is obvious from the reproduction script (single short
-  test case, no new fixtures, no test-harness change)
-
-If any criterion fails, the triage subagent MUST select Path B.
-
-### Path B — full loop (default)
-
-Path B runs the same plan/review/implement/review/approve/commit shape as
-`meta-orchestrate.md`. It is the default. Any uncertainty defaults Path B.
+See `triage.md § Path A / Path B Eligibility` for the criteria the triage
+subagent applies. The criteria are single-sourced in the triage workflow;
+this orchestrator only reads the resulting `summaries.triage.route` value.
 
 ### Pipeline selection by path
 
@@ -164,16 +151,11 @@ Differences are confined to the **triage** step and the **path branch**.
      b. If .forge/store/bugs/{BUG_ID}.json does NOT exist, write a fresh record
         via store-cli with status="reported".
      c. Read the now-guaranteed record.
-   - Spawn the triage subagent (persona: bug-fixer). It MUST:
-     • Reproduce the bug (failing test or reproduction script).
-     • Confirm the root cause via codebase research.
-     • Decide Path A vs Path B by the criteria above.
-     • Write triage artifact:
-       forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}", artifact:"triage", content:"<markdown>" })
-     • Write triage-summary artifact (JSON shape documented in § Triage Judgement):
-       forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}", artifact:"triage-summary", content:"<JSON>" })
-     • Call set-bug-summary {bugId} triage via forge_store:
-       forge_store({ command:"set-bug-summary", bugId:"{bugId}", phase:"triage", file:"TRIAGE-SUMMARY.json" })
+   - Spawn the triage subagent (workflow: `triage.md`, persona: bug-fixer).
+     It MUST write `TRIAGE.md` + `TRIAGE-SUMMARY.json` with a `route` field
+     (`"A"` or `"B"`) and call `set-bug-summary {bugId} triage` per
+     `triage.md`. The triage workflow is `audience: subagent`, `phase: triage`;
+     the orchestrator MUST NOT pass any other workflow body to this subagent.
    - On return, orchestrator transitions status:
        store-cli update-status bug {bugId} status triaged
        store-cli update-status bug {bugId} status in-progress
@@ -467,7 +449,7 @@ When the Bug Fixer, Supervisor, Architect, Engineer, or Collator detects skill
 friction during fix-bug — a referenced skill is unused, fails on invocation,
 is missing from the registry, has gone stale relative to current architecture,
 or is redundant with another skill — emit a `friction` event so
-`/forge:enhance --phase 2` can act on the signal.
+`/forge:rebuild --enrich` (phase 2) can act on the signal.
 
 **Trigger conditions** (set `issue` to the matching token):
 

package/dist/forge-payload/meta/workflows/meta-implement.md

@@ -30,13 +30,25 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase implement --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
+
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `plan-approved`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:review-plan must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
 1. Load Context:
    - Read `.forge/personas/engineer.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
    - store-cli verbs: `read` | `list` | `write` | `emit` | `update-status` | `set-summary` | `describe` | `nlp` | `query` | `delete` — there is no `get`/`set`/`find`. See `_fragments/store-cli-verbs.md` for full notes; run `--help` before improvising.

package/dist/forge-payload/meta/workflows/meta-migrate.md

@@ -22,7 +22,7 @@ Translate a prose-heavy v0.x `.forge/` instance into the v0.40 format:
 `structure-versions.json` snapshot tracking (T05). Every operation is
 reversible, guarded by user confirmation, and idempotent on re-run.
 
-**Trigger:** Invoked by `/forge:migrate` when the user passes `--structural`
+**Trigger:** Invoked by `/forge:init --migrate` when the user passes `--structural`
 or when `.forge/structure-versions.json` is absent (pre-T05 install detected).
 
 **Scope:** v0.x → v0.40 only. Installs older than v0.x should use
@@ -68,7 +68,7 @@ ls .forge/structure-versions.json 2>/dev/null && echo "EXISTS" || echo "ABSENT"
 
 - If `structure-versions.json` EXISTS: this is a post-T05 install. Warn the
   user that structural migration is not needed and offer to run the standard
-  store-schema migration (Steps 1–7 of `/forge:migrate`) instead. Stop.
+  store-schema migration (Steps 1–7 of `/forge:init --migrate`) instead. Stop.
 - If ABSENT: proceed (pre-T05 install confirmed).
 
 **0c. Check for in-progress sentinel (idempotency).**
@@ -293,7 +293,7 @@ node "$FORGE_ROOT/tools/substitute-placeholders.cjs" \
 ```
 
 This overwrites `.forge/personas/`, `.forge/skills/`, `.forge/workflows/`,
-`.forge/templates/`, and `.claude/commands/forge/` with the freshly substituted
+`.forge/templates/`, and `.claude/commands/<prefix>/` with the freshly substituted
 base-pack.
 
 If `substitute-placeholders.cjs` exits non-zero: halt, report the error to the