@entelligentsia/forgecli 0.21.0 → 1.0.3

package/dist/forge-payload/.base-pack/commands/sprint-intake.md

@@ -1,22 +1,6 @@
 ---
 name: sprint-intake
-description: Elicit and structure requirements for a new sprint
+description: Renamed in v1.0 — use /{{PREFIX}}:new-sprint
 ---
 
-# /{{PREFIX}}:sprint-intake
-
-Read the sprint-intake workflow and follow it.
-
-## Locate the Forge plugin
-
-```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
-```
-
-## Execute
-
-Read `.forge/workflows/architect_sprint_intake.md` and follow it.
-
-## Arguments
-
-$ARGUMENTS
+× /{{PREFIX}}:sprint-intake was renamed to /{{PREFIX}}:new-sprint in v1.0.

package/dist/forge-payload/.base-pack/commands/sprint-plan.md

@@ -1,22 +1,6 @@
 ---
 name: sprint-plan
-description: Decompose sprint requirements into tasks with dependencies
+description: Renamed in v1.0 — use /{{PREFIX}}:plan-sprint
 ---
 
-# /{{PREFIX}}:sprint-plan
-
-Read the sprint-plan workflow and follow it.
-
-## Locate the Forge plugin
-
-```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
-```
-
-## Execute
-
-Read `.forge/workflows/architect_sprint_plan.md` and follow it.
-
-## Arguments
-
-$ARGUMENTS
+× /{{PREFIX}}:sprint-plan was renamed to /{{PREFIX}}:plan-sprint in v1.0.

package/dist/forge-payload/.base-pack/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/.base-pack/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/.base-pack/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/.base-pack/workflows/architect_approve.md

@@ -36,13 +36,25 @@ deps:
 
 ```
 
-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/.base-pack/workflows/commit_task.md

@@ -36,7 +36,7 @@ deps:
 
 ```
 
-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}`
@@ -44,6 +44,17 @@ deps:
    - 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/.base-pack/workflows/enhance.md

@@ -20,7 +20,7 @@ deps:
 ## Iron Laws
 
 - Orchestrator-only: this workflow runs with full tool access in the orchestrator session. NEVER delegate it to a subagent.
-- Read `.forge/personas/engineer.md` first; print the persona identity line to stdout before any other tool use.
+- Read `.forge/personas/engineer.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.
 - Phase 1 only touches `{{KEY}}` token text; never rewrite persona prose, algorithm steps, or role definitions.
 
@@ -93,7 +93,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.
 
@@ -115,7 +115,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
 
@@ -196,7 +196,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
 
@@ -584,8 +584,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/.base-pack/workflows/fix_bug.md

@@ -23,7 +23,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 |
@@ -93,24 +93,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
 
@@ -156,16 +143,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
@@ -424,7 +406,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/.base-pack/workflows/implement_plan.md

@@ -26,13 +26,25 @@ deps:
 
 ```
 
-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.
@@ -89,7 +101,7 @@ deps:
 ## Iron Laws
 
 - Follow the Algorithm step by step. Execute the approved PLAN.md exactly; do not invent scope or skip steps without updating the plan first.
-- Read `.forge/personas/engineer.md` first; print the persona identity line to stdout before any other tool use.
+- Read `.forge/personas/engineer.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.
 - Run the full test suite before declaring the task implemented. Silent continuation past test failures is never acceptable.
 

package/dist/forge-payload/.base-pack/workflows/migrate_structural.md

@@ -52,7 +52,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).**
@@ -277,7 +277,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

package/dist/forge-payload/.base-pack/workflows/orchestrate_task.md

@@ -167,7 +167,7 @@ and what capabilities it has. Two modes are supported, selected by the
 | `reference` | Compact summary from `.forge/cache/persona-pack.json`, plus a file_ref pointer to the full persona/skill definitions. | ✅ |
 | `inline` | Legacy: inject the full verbatim persona and skill file contents. Kept for one version as a rollback path. | |
 
-The pack is built by `/forge:regenerate` and `/forge:materialize` via
+The pack is built by `/forge:rebuild` via
 `forge/tools/build-persona-pack.cjs`. It compiles YAML frontmatter from
 `$FORGE_ROOT/meta/personas/meta-*.md` and `$FORGE_ROOT/meta/skills/meta-*.md`
 into `.forge/cache/persona-pack.json`.
@@ -194,7 +194,7 @@ def compose_role_block(persona_noun):
         # regeneration bug and should be reported via /forge:report-bug.
         raise OrchestratorError(
             f"persona '{persona_noun}' not in persona-pack. "
-            "Run /forge:regenerate to rebuild the pack."
+            "Run /forge:rebuild to rebuild the pack."
         )
 
     lines = [
@@ -430,6 +430,20 @@ for each task in dependency_sorted(tasks):
     # --- Load finalize fragment (token reporting contract) ---
     finalize_fragment = read_file(f"{FORGE_ROOT}/meta/workflows/_fragments/finalize.md") if file_exists(f"{FORGE_ROOT}/meta/workflows/_fragments/finalize.md") else ""
 
+    # --- Compose review loop context block (review-role phases only) ---
+    # Injected between summary_block and role_block so reviewers know their
+    # position in the revision loop at the moment they are spawned.
+    # `iteration` is the current attempt number (pre-spawn, not post-increment).
+    # `phase.maxIterations` is the configured limit (default 3).
+    if phase.role in ("review-plan", "review-code", "validate"):
+      review_loop_context = (
+        f"### Review Loop Context\n"
+        f"- Iteration: {iteration} of {phase.maxIterations}\n"
+        f"- Is final iteration: {iteration >= phase.maxIterations}\n\n"
+      )
+    else:
+      review_loop_context = ""
+
     spawn_kwargs = dict(
       prompt=(
         f"Append progress entries to {progress_log_path} via store-cli "
@@ -437,6 +451,7 @@ for each task in dependency_sorted(tasks):
         f"---\n\n"
         f"{architecture_block}"
         f"{summary_block}"
+        f"{review_loop_context}"
         f"{role_block}\n\n"
         f"### Project Context\n"
         f"{overlay_md}\n\n"
@@ -485,6 +500,7 @@ for each task in dependency_sorted(tasks):
           f"- Banner key: {banner_name}\n\n"
           f"Append progress entries as you work.\n\n"
           f"---\n\n"
+          f"{review_loop_context}"
           f"{role_block}\n\n"
           f"### Current Working Context\n"
           f"- Sprint Root: {sprint_root_path}\n"
@@ -875,7 +891,7 @@ Refer subagents to `.forge/schemas/event.schema.json` instead.
 <!-- See _fragments/generation-instructions.md for Generation Instructions template (orchestrate uses orchestrator-special long-form prose — cannot be reduced to standard subsections) -->
 ## Friction Emit
 
-When the Orchestrator detects skill friction during orchestrate-task — 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. This is the writer side of the channel whose reader landed in S13-T08; the reader is empty without these emits.
+When the Orchestrator detects skill friction during orchestrate-task — 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:rebuild --enrich` (phase 2) can act on the signal. This is the writer side of the channel whose reader landed in S13-T08; the reader is empty without these emits.
 
 **Trigger conditions** (set `issue` to the matching token):
 
@@ -915,4 +931,4 @@ experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal
 — do not coalesce.
 
 The generated `orchestrate_task.md` MUST carry this section verbatim —
-`/forge:enhance --phase 2` greps for it.
+`/forge:rebuild --enrich` (phase 2) greps for it.

package/dist/forge-payload/.base-pack/workflows/plan_task.md

@@ -26,13 +26,25 @@ deps:
 
 ```
 
-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 plan --{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: `draft`, `planned`, `plan-revision-required`.
+   - 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:plan cannot run from this state; a reset or reassignment must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
 1. Load Context:
    - Read `.forge/personas/architect.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.
@@ -100,7 +112,7 @@ deps:
 ## Iron Laws
 
 - Follow the Algorithm step by step. No code, pseudocode, or implementation sketches in the plan.
-- Read `.forge/personas/architect.md` first; print the persona identity line to stdout before any other tool use.
+- Read `.forge/personas/architect.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.
 
 ## Store-Write Verification

package/dist/forge-payload/.base-pack/workflows/review_code.md

@@ -36,43 +36,73 @@ deps:
 
 ```
 
-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 review-code --{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.
-1. Load Context:
+
+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: `implemented`, `implementing`.
+   - 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:implement must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
+1. Read Review Loop Context:
+   - Check the spawning prompt for a `### Review Loop Context` block.
+   - If present, extract:
+     - `Iteration: N of M` — current attempt number and the configured limit
+     - `Is final iteration: true/false`
+   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
+     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
+   - Include `(iteration N of M)` in the opening line of the `CODE_REVIEW.md` artifact.
+   - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
+     append a `### Next Steps` section to the artifact showing:
+     ```
+     ### Next Steps
+     - Force-approve (bypass remaining reviews): `/forge:approve --force {task_id}`
+     - Increase iteration limit: edit `config.pipelines.{pipeline}.phases[review-code].maxIterations`
+     - Restart from review: `/forge:review-code {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt
    - Read approved PLAN.md
    - Read PROGRESS.md
 
    **Read mode: diff-first.** Read `git diff $(git merge-base HEAD origin/main)..HEAD -- <files-listed-in-PLAN>` first. Read full source files only when the diff context is insufficient to judge a finding (e.g., the change is an inversion of an invariant defined elsewhere). Do not pre-load full source — tool calls earn their tokens.
 
-2. Review:
+3. Review:
    - Verify all plan steps were executed
    - Review code for quality, security, and architecture alignment
    - Verify test evidence in PROGRESS.md is authentic and complete
 
-3. Verdict:
+4. Verdict:
    - Write the code review via forge_artifact:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"code-review", content:"<markdown>" })`
      Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Knowledge Writeback:
+5. Knowledge Writeback:
    - Update stack-checklist.md if new patterns or pitfalls were discovered
 
-5. Finalize:
+6. Finalize:
    - Transitions:
      - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `... status code-revision-required` (if Revision Required).
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.code_review.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) 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. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
-6. Emit Summary Sidecar:
+7. Emit Summary Sidecar:
    - Write the review summary via forge_artifact:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-impl-summary", content:"<JSON>" })`
      The JSON shape:

package/dist/forge-payload/.base-pack/workflows/review_plan.md

@@ -38,30 +38,60 @@ deps:
 
 ```
 
-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 review-plan --{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.
-1. Load Context:
+
+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: `planned`.
+   - 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:plan must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
+1. Read Review Loop Context:
+   - Check the spawning prompt for a `### Review Loop Context` block.
+   - If present, extract:
+     - `Iteration: N of M` — current attempt number and the configured limit
+     - `Is final iteration: true/false`
+   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
+     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
+   - Include `(iteration N of M)` in the opening line of the `PLAN_REVIEW.md` artifact.
+   - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
+     append a `### Next Steps` section to the artifact showing:
+     ```
+     ### Next Steps
+     - Force-approve (bypass remaining reviews): `/forge:approve --force {task_id}`
+     - Increase iteration limit: edit `config.pipelines.{pipeline}.phases[review-plan].maxIterations`
+     - Restart from review: `/forge:review-plan {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt (source of truth)
    - Read PLAN.md (subject of review)
    - Read stack checklist if available
 
-2. Review:
+3. Review:
    - Evaluate feasibility, completeness, security, architecture alignment, and testing strategy
    - Identify missing edge cases or failure modes
 
-3. Verdict:
+4. Verdict:
    - Write the plan review via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan-review", content:"<markdown>" })
      Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Finalize:
+5. Finalize:
    - Transitions:
      - **Task mode** — predecessor must be `planned`.
        - Approved          → `plan-approved`
@@ -71,7 +101,7 @@ deps:
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.review_plan.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **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. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
-5. Emit Summary Sidecar:
+6. Emit Summary Sidecar:
    - Write the review-plan summary via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-plan-summary", content:"<JSON>" })
      The JSON must have the following shape:
      ```json

package/dist/forge-payload/.base-pack/workflows/run_sprint.md

@@ -181,7 +181,7 @@ Once all tasks have reached a terminal status:
    ── Carried over / abandoned: N tasks
    ```
 3. Update sprint `status` to `completed` or `partially-completed`
-4. Suggest: "Run `/forge:retrospective {SPRINT_ID}` to close out the sprint."
+4. Suggest: "Run `/forge:retro {SPRINT_ID}` to close out the sprint."
 
 ## Sprint Lifecycle Hooks
 
@@ -189,7 +189,7 @@ Once all tasks have reached a terminal status:
 |---|---|---|
 | `collate` | After all tasks terminal | Run `node "$FORGE_ROOT/tools/collate.cjs"` |
 | `report` | After collation | Print outcome summary (committed/escalated/carried-over counts) |
-| `suggest` | After report | Suggest `/forge:retrospective {SPRINT_ID}` |
+| `suggest` | After report | Suggest `/forge:retro {SPRINT_ID}` |
 
 ## Resume Semantics