@entelligentsia/forgecli 0.21.0 → 1.0.3

package/dist/forge-payload/meta/workflows/meta-new-sprint.md

@@ -0,0 +1,84 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+deps:
+  personas: [product-manager]
+  skills: [architect, generic]
+  templates: [SPRINT_REQUIREMENTS_TEMPLATE, SPRINT_MANIFEST_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [MASTER_INDEX.md, architecture/stack.md]
+  config_fields: [project.prefix, paths.engineering]
+---
+
+# 🌸 Meta-Workflow: Sprint Intake
+
+## Purpose
+
+Capture sprint requirements via a structured interview and document them for planning.
+
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Capture requirements accurately; do not editorialize or pre-select options on the user's behalf. The product manager documents what the user says, not what the agent thinks is best.
+- Read `.forge/personas/product-manager.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.
+
+## Algorithm
+
+```
+0. Project Orientation:
+   - Your current working directory is the project root.
+   - Forge config lives at `.forge/config.json` (relative to cwd); the `forge_config` MCP tool returns canonical values.
+   - Engineering knowledge lives under `engineering/` (relative to cwd) — `MASTER_INDEX.md`, `architecture/`, `business-domain/`, `sprints/`, `features/`.
+   - Paths in subsequent steps resolve against this cwd.
+
+1. Pre-flight Gate Check:
+   - Probe token reporting: if the host runtime exposes a `/cost` slash command
+     (Claude Code), invoke it; on any other runtime treat as unavailable and
+     proceed. Do NOT search for or invent a `cost-cli.cjs` — there is no such tool.
+   - If the probe succeeds → note for later (will use reported data)
+   - If the probe fails or is unavailable → note for later (will use estimates)
+
+2. Load Context:
+   - Read `engineering/MASTER_INDEX.md` (relative to cwd)
+   - Read any pending feature requests or bug reports under `engineering/`
+
+3. Requirements Interview:
+   - Conduct a structured interview with the user
+   - Capture: Objectives, Constraints, Deliverables, and Success Criteria
+   - Clarify ambiguous requirements through iterative questioning
+
+4. Document Requirements:
+   - Generate `engineering/sprints/<SPRINT_ID>/SPRINT_REQUIREMENTS.md`
+   - Map requirements to existing Features if applicable
+   - Ensure all deliverables are measurable and testable
+
+5. Finalize:
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status planning`
+   - **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.
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/product-manager.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.
+- **Workflow Structure:** The generated `sprint_intake.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of requirement analysis; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Reference project-specific requirement templates.
+- **Token Reporting:** The generated workflow MUST mandate the following before returning:
+  1. Probe session token usage: invoke `/cost` if the host runtime supports it
+     (Claude Code only); on any other runtime treat as unavailable. Do NOT
+     shell out to a `cost-cli.cjs` — there is no such tool.
+  2. If the probe succeeds:
+     - Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
+     - Add `"source": "reported"` to sidecar JSON.
+  3. If the probe fails or is unavailable:
+     - Set token fields to `null`: `"inputTokens": null, "outputTokens": null, "estimatedCostUSD": null`.
+     - Add `"source": "missing"` to sidecar JSON.
+     - Log: "Token data unavailable (cost probe failed). Backfill later via estimate-usage.cjs."
+  4. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+  5. **NEVER skip sidecar write.** Always emit (reported or placeholder with nulls).
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -172,7 +172,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`.
@@ -199,7 +199,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 = [
@@ -435,6 +435,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 "
@@ -442,6 +456,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"
@@ -490,6 +505,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"
@@ -952,7 +968,7 @@ Refer subagents to `.forge/schemas/event.schema.json` instead.
 
 ## 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):
 
@@ -992,4 +1008,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/meta/workflows/meta-plan-sprint.md

@@ -0,0 +1,152 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: [SPRINT_MANIFEST_TEMPLATE, TASK_PROMPT_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [MASTER_INDEX.md, architecture/stack.md]
+  config_fields: [project.prefix, paths.engineering]
+---
+
+# 🗻 Meta-Workflow: Sprint Plan
+
+## Purpose
+
+Break sprint requirements into a set of estimated tasks with a dependency graph.
+
+## Algorithm
+
+```
+0. Pre-flight Gate Check:
+   - Probe token reporting: if the host runtime exposes a `/cost` slash command
+     (Claude Code), invoke it; on any other runtime treat as unavailable. Do
+     NOT search for or invent a `cost-cli.cjs` — there is no such tool.
+   - If the probe succeeds → note for later (will use reported data)
+   - If the probe fails or is unavailable → note for later (will use estimates)
+
+1. Load Context:
+   - Query the store to orient on current project state before reading docs:
+     ```sh
+     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "latest sprint"
+     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "open bugs"
+     ```
+     Use results (titles, statuses, excerpts, file refs) to skip manual MASTER_INDEX.md navigation where sufficient.
+   - Read SPRINT_REQUIREMENTS.md
+   - Read architecture and domain docs
+   - Read the stack checklist
+
+2. Task Decomposition:
+   - Break requirements into atomic tasks
+   - Assign each task to a Feature (if applicable)
+   - Define clear acceptance criteria for each task
+   - Use the `ID-description` format (e.g., `FORGE-S05-agent-runtime-portability`) for sprint and task folders.
+
+3. Estimation and Sequencing:
+   - Estimate each task (S, M, L) based on complexity
+   - Define the dependency graph (which tasks must precede others)
+   - Identify the critical path
+
+4. Documentation:
+   - Write SPRINT_PLAN.md to `engineering/sprints/{sprintId}/SPRINT_PLAN.md`
+   - Create each task via `node "$FORGE_ROOT/tools/store-cli.cjs" write task '{task-json}'`.
+     If the command exits non-zero or the PreToolUse hook blocks the write:
+     parse the error, correct the JSON, and retry (see Store-Write Verification).
+     Do not proceed to the next task until this write succeeds.
+   - Update the sprint record with all new task IDs via `node "$FORGE_ROOT/tools/store-cli.cjs" write sprint '{updated-sprint-json}'` (the sprint JSON must include the complete `taskIds` array with all newly created task IDs).
+     If the command exits non-zero or the PreToolUse hook blocks the write:
+     parse the error, correct the JSON, and retry (see Store-Write Verification).
+     Do not proceed until this write succeeds.
+   - For each task, create its task folder and write TASK_PROMPT.md:
+     * Folder: `engineering/sprints/{sprintId}/{taskId}/`
+     * File: `TASK_PROMPT.md` — populate from `.forge/templates/TASK_PROMPT_TEMPLATE.md`
+       filling in title, objective, acceptance criteria, entities, DSL/CLI changes, and operational impact
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status active`.
+     If the command exits non-zero, parse the error and retry
+     (see Store-Write Verification). Do not proceed until this write succeeds.
+
+5. Finalize:
+   - **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.
+```
+
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance (sprint-plan uses verbatim Anti-Pattern Guard pattern — orchestrator-special case) -->
+## Anti-Pattern Guard
+
+The generated workflow MUST include the following section verbatim, placed immediately
+after the Purpose heading and before the Algorithm block:
+
+```
+## Iron Laws
+
+- YOU MUST NOT write any code, pseudocode, or implementation sketch.
+- YOU MUST NOT produce a plan of your own before reading this workflow.
+- YOU MUST follow the Algorithm below step by step. Reading it is not optional.
+- If you have already read SPRINT_REQUIREMENTS.md and feel ready to decompose tasks:
+  stop. Return to step 1 of the Algorithm and proceed from there.
+```
+
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally expanded
+     Store-Write Verification variant that explains what counts as a store write in the sprint-plan
+     context (includes direct Write/Edit tool calls). Canonical fragment is reference only. -->
+## Store-Write Verification
+
+Every write to the Forge store MUST succeed before the agent proceeds to the next
+step. Store writes include `store-cli` commands (`write`, `update-status`, `emit`)
+and direct `Write`/`Edit` tool calls against Forge-owned paths under
+`.forge/store/`.
+
+If a write is rejected — either by `store-cli` exiting non-zero or by the
+`PreToolUse` write-boundary hook blocking the call with exit code 2 — the agent
+MUST:
+
+1. **Parse the error.** Both `store-cli` and the write-boundary hook emit
+   structured messages naming the offending field and referencing the relevant
+   schema file (e.g. `forge/schemas/task.schema.json`). Read the error carefully
+   to identify which field is wrong and what the schema expects.
+2. **Correct the data.** Fix the JSON payload to satisfy the schema: add missing
+   required fields, fix type mismatches, remove undeclared properties, correct
+   enum values, etc. If the hook message mentions a schema file, read that file
+   to understand the full shape.
+3. **Retry the write.** Re-attempt the same store write with the corrected payload.
+4. **Repeat until success.** Do NOT advance past the current step, emit events,
+   or produce further artifacts until the write is confirmed successful.
+
+**Maximum retries: 3.** If the write still fails after 3 correction attempts,
+halt and escalate to the human. Include the original payload, the corrected
+payload, and all error messages in the escalation.
+
+**Do NOT** set `FORGE_SKIP_WRITE_VALIDATION=1` to bypass a schema error. That
+environment variable is reserved for emergency operator repair only.
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.
+- **Workflow Structure:** The generated `sprint_plan.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of task decomposition or estimation; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Use project-specific estimation guidelines.
+  - Reference project's task manifest schema.
+- **Token Reporting:** The generated workflow MUST mandate the following before returning:
+  1. Probe session token usage: invoke `/cost` if the host runtime supports it
+     (Claude Code only); on any other runtime treat as unavailable. Do NOT
+     shell out to a `cost-cli.cjs` — there is no such tool.
+  2. If the probe succeeds:
+     - Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
+     - Add `"source": "reported"` to sidecar JSON.
+  3. If the probe fails or is unavailable:
+     - Set token fields to `null`: `"inputTokens": null, "outputTokens": null, "estimatedCostUSD": null`.
+     - Add `"source": "missing"` to sidecar JSON.
+     - Log: "Token data unavailable (cost probe failed). Backfill later via estimate-usage.cjs."
+  4. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+  5. **NEVER skip sidecar write.** Always emit (reported or placeholder with nulls).
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.
+- **Store-Write Verification:** The generated workflow MUST include the "Store-Write
+  Verification" section verbatim. Every `store-cli write`, `store-cli update-status`,
+  and `store-cli emit` command in the Algorithm must be annotated with the
+  parse-correct-retry instruction: "If the command exits non-zero or the
+  PreToolUse hook blocks the write: parse the error, correct the JSON, and retry
+  (see Store-Write Verification). Do not proceed until this write succeeds."

package/dist/forge-payload/meta/workflows/meta-plan-task.md

@@ -30,13 +30,25 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
 
 ```
 
-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.

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

@@ -0,0 +1,73 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: [RETROSPECTIVE_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [paths.engineering]
+---
+
+# 🗻 Meta-Workflow: Retrospective
+
+## Purpose
+
+Close a sprint by reviewing learnings, updating the knowledge base, and improving workflows.
+
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Never mutate JSON records during retrospective; the store is the source of truth and retrospective flows downstream from it. Retrospective operations read store data and write markdown views only.
+- 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.
+
+## Algorithm
+
+```
+1. Load Context:
+   - Read all task manifests for the sprint
+   - Read all event logs (including token usage)
+   - Read all retrospective notes gathered during the sprint
+
+2. Analysis:
+   - Calculate total sprint cost (tokens/USD)
+   - Identify "bottleneck" tasks (high iteration counts or long duration)
+   - Analyze common failure modes in reviews
+
+3. Knowledge Update:
+   - Update architecture/domain docs with "lessons learned"
+   - Propose improvements to meta-workflows based on analysis
+   - Update stack-checklist with new verification steps
+
+4. Finalize:
+   - Write SPRINT_RETROSPECTIVE.md
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status retrospective-done`
+   - Run `node "$FORGE_ROOT/tools/collate.cjs" {sprintId} --purge-events`
+     This single deterministic step: generates COST_REPORT.md from all
+     accumulated events, then deletes `.forge/store/events/{sprintId}/`.
+     COST_REPORT.md is the durable record; the raw event files are not
+     retained after retrospective close.
+   - **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.
+     (tombstone — written after the purge; the only event in the directory
+     going forward)
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.
+- **Workflow Structure:** The generated `retrospective.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of cost analysis or doc updates; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Reference project's cost reporting templates.
+- **Token Reporting:** The generated workflow MUST mandate the following before returning:
+  1. Probe session token usage: invoke `/cost` if the host runtime supports it
+     (Claude Code only); on any other runtime treat as unavailable and proceed.
+     Do NOT shell out to a `cost-cli.cjs` — there is no such tool.
+  2. Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
+  3. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

package/dist/forge-payload/meta/workflows/meta-review-implementation.md

@@ -41,43 +41,73 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 ```
 
-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/meta/workflows/meta-review-plan.md

@@ -37,30 +37,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`
@@ -70,7 +100,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/meta/workflows/meta-validate.md

@@ -41,38 +41,68 @@ The Supervisor performs a final validation of the implementation against the acc
 
 ```
 
-0. Pre-flight Gate Check:
+0a. 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 validate --task {taskId}`
+   - **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 validate --{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`, `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: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 `VALIDATION_REPORT.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[validate].maxIterations`
+     - Restart from validation: `/forge:validate {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt
    - Read approved PLAN.md
    - Read the implementation
    - Read PROGRESS.md
 
-2. Validation:
+3. Validation:
    - Execute the "Acceptance Criteria" checklist from the plan
    - Verify that all technical constraints (e.g., performance, security) are met
    - Check for any regressions in related functionality
    - When re-running the test suite, use the **resolved test command** from `commands.test` in `.forge/config.json` (i.e. `` `${commands.test}` ``, e.g. `.venv/bin/python -m pytest`). Template placeholder: {{TEST_COMMAND}}. Do NOT invoke bare `python` / `python3` — the project interpreter is rarely on `$PATH`.
 
-3. Verdict:
+4. Verdict:
    - Write the validation report via:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-report", content:"<markdown>" })`
      The markdown content must use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: list the failed criteria and required fixes
      - If Approved: confirm the task is validated
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Finalize:
+5. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status code-revision-required` (if Revision Required)
    - **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 validation summary via:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-summary", content:"<JSON>" })`
      The JSON content must have the following shape: