@entelligentsia/forgecli 0.20.3 → 1.0.2

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-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
 
@@ -376,7 +376,20 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
    usage telemetry, not friction, so recurrence is neutral by construction).
 
 5b.5. **Compression gate (reject >20% growth without 3+ frictions)** — a cheap
-   deterministic filter that runs BEFORE the LLM judge (step 5c). Any
+   deterministic filter that runs BEFORE the LLM judge (step 5c).
+
+   **Before writing any rejections**, ensure the target directory exists:
+   ```sh
+   mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
+   ```
+
+   All gate and judge rejections MUST be written to:
+   ```
+   $PROJECT_ROOT/.forge/enhancement-proposals/phase2-<timestamp>-rejections.json
+   ```
+   NEVER write a bare `rejections.json` to the project root or any other location.
+
+   Any
    `update_skill` proposal that would grow the target file by more than 20%
    (byte-wise, UTF-8) must be backed by at least 3 supporting friction events;
    otherwise it is rejected here and never reaches the judge. `insert_skill`
@@ -416,9 +429,10 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
    "
    ```
 
-   **Logging gate rejections.** Append every rejection from this step to the
-   same `phase2-<timestamp>-rejections.json` sibling that step 5c uses, with
-   the rejection record carrying `{ proposal, admit: false,
+   **Logging gate rejections.** Append every rejection from this step to
+   `$PROJECT_ROOT/.forge/enhancement-proposals/phase2-<timestamp>-rejections.json`
+   (the same file the LLM-judge gate in step 5c writes to). The rejection
+   record carries `{ proposal, admit: false,
    reason: 'compression_gate_growth_unsupported', growthRatio, currentBytes,
    newBytes, supportingFrictionCount, threshold, minSupportingFrictions }`.
    This keeps every drop — gate or judge — traceable in one place.
@@ -520,6 +534,22 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
    delete proposals from short-history runs as advisory until the full
    window is populated.
 
+   **Verification (after steps 5b.5 + 5c).** If any proposals were
+   rejected by either gate, verify the rejections file landed at the
+   contracted path:
+   ```sh
+   ls "$PROJECT_ROOT/.forge/enhancement-proposals/phase2-"*"-rejections.json"
+   ```
+   If the file is missing but rejections were recorded, the write targeted
+   the wrong path. Check for a stray `rejections.json` at the project root
+   and move it:
+   ```sh
+   [ -f "$PROJECT_ROOT/rejections.json" ] && \
+     mv "$PROJECT_ROOT/rejections.json" \
+        "$PROJECT_ROOT/.forge/enhancement-proposals/phase2-${TIMESTAMP}-rejections.json"
+   ```
+   NEVER leave a bare `rejections.json` at the project root.
+
 6. **Write proposal artifact**:
    ```sh
    mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
@@ -565,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

@@ -467,7 +467,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

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.