@entelligentsia/forgecli 0.10.1 → 0.11.2

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

@@ -0,0 +1,133 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+audience: subagent
+phase: plan
+context:
+  architecture: true
+  prior_summaries: delta
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: [PLAN_TEMPLATE, TASK_PROMPT_TEMPLATE]
+  sub_workflows: [review_plan]
+  kb_docs: [architecture/stack.md]
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🌱 Meta-Workflow: Plan Task
+
+## Purpose
+
+The Engineer reads the task prompt, researches the codebase, and produces an implementation plan.
+
+## Algorithm
+
+```
+
+0. 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.
+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.
+   - Read task prompt (source of truth)
+   - Query the store for this task and any related entities:
+     ```sh
+     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "{taskId} with sprint with feature"
+     ```
+     Use store results directly if they include title, status, sprint, and excerpt.
+   - Read the architecture summary from your injected context (if present).
+   - Read business domain docs relevant to the task
+   - Read stack checklist
+
+2. Research:
+   - Identify files for modification (Glob, Grep, Read)
+   - Map existing patterns in the target area
+   - Identify existing tests to be maintained or expanded
+   - Identify whether the change is **material** (triggers version bump) or not:
+     - Bug fixes to any command, hook, tool spec, or workflow → material
+     - Tool-spec changes that alter generated tool behaviour → material
+     - Command-file changes that alter behaviour → material
+     - Hook changes → material
+     - Schema changes to `.forge/store/` or `.forge/config.json` → material
+     - Docs-only changes → NOT material
+
+3. Plan:
+   - Generate PLAN.md using the project plan template
+   - Ensure inclusion of: Objective, Approach, Files to Modify, Data Model Changes, Testing Strategy, Acceptance Criteria, and Operational Impact
+
+4. Knowledge Writeback:
+   - If new patterns were discovered, update architecture or business domain docs
+
+5. Finalize:
+   - Transitions:
+     - **Task mode** — legal target from this step: `draft → planned`. Out-of-band escapes (any state): `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`.
+       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
+     - **Bug mode** — NO status write. The bug remains `in-progress` until the commit phase transitions it to `fixed`. 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.
+
+6. Emit Summary Sidecar:
+   - Write `PLAN-SUMMARY.json` (task mode) or `BUG-FIX-PLAN-SUMMARY.json` (bug mode) to the record's directory. Shape:
+     ```json
+     {
+       "objective":   "<one sentence — what this plan sets out to build>",
+       "key_changes": ["<up to 12 bullets, 200 chars each>"],
+       "verdict":     "n/a",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"PLAN.md"
+     }
+     ```
+   - Call (task mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} plan \
+       engineering/sprints/{sprint}/{task}/PLAN-SUMMARY.json
+     ```
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} plan \
+       engineering/bugs/{bugDir}/BUG-FIX-PLAN-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+```
+
+## 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.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
+## Store-Write Verification
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
+## Friction Emit
+Emit `type:friction` `{workflow:plan-task, persona:architect, issue}` per `_fragments/friction-emit.md`.
+
+## Generation Instructions
+
+- **Workflow Structure:** Strict "Algorithm" block format.
+- **Markers (required by `/forge:plan` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `architect.md` persona path. Missing any → kickoff shim refuses to dispatch.
+- **Context Isolation:** Forbid inline execution. Delegate complex sub-tasks via the `Agent` tool.
+- **Project Specifics:**
+  - Replace architecture/domain doc placeholders with actual project file paths.
+  - Embed the project's specific PLAN template path.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -0,0 +1,135 @@
+---
+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.
+
+## 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.
+
+---
+
+## 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.
+
+### File structure
+
+```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-retrospective.md

@@ -0,0 +1,65 @@
+---
+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.
+
+## 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)
+```
+
+## 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

@@ -0,0 +1,119 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+audience: subagent
+phase: review-code
+context:
+  architecture: false
+  prior_summaries: delta
+  persona: summary
+  master_index: false
+  diff_mode: true
+deps:
+  personas: [supervisor]
+  skills: [supervisor, generic]
+  templates: [CODE_REVIEW_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [architecture/stack.md, architecture/routing.md]
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🌿 Meta-Workflow: Review Implementation
+
+## Purpose
+
+The Supervisor reviews the Engineer's implementation for correctness, quality, and compliance with the approved plan.
+
+## Iron Laws
+
+- Evaluate the code against the approved PLAN.md and the original task prompt. Do not accept "it works" as a substitute for "it is correct and maintainable."
+- Read `.forge/personas/supervisor.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
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
+## Algorithm
+
+```
+
+0. 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:
+   - 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:
+   - 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:
+   - Write CODE_REVIEW.md using the format:
+     **Verdict:** [Approved | Revision Required]
+     - If Revision Required: provide numbered, actionable items
+     - If Approved: provide any advisory notes
+
+4. Knowledge Writeback:
+   - Update stack-checklist.md if new patterns or pitfalls were discovered
+
+5. 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:
+   - Write `REVIEW-IMPL-SUMMARY.json` to the record's directory with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what this review assessed>",
+       "findings":    ["<up to 12 bullets, 200 chars each — key issues or confirmations>"],
+       "verdict":     "<approved | revision>",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"CODE_REVIEW.md"
+     }
+     ```
+   - Call (task mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} code_review \
+       engineering/sprints/{sprint}/{task}/REVIEW-IMPL-SUMMARY.json
+     ```
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} code_review \
+       engineering/bugs/{bugDir}/REVIEW-IMPL-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+```
+
+## Generation Instructions
+
+- **Workflow Structure:** The generated `review_implementation.md` must follow the strict "Algorithm" block format.
+- **Markers (required by `/forge:run-task` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `.forge/personas/supervisor.md` persona path. Missing any → kickoff shim refuses to dispatch.
+- **Verdict Detection:** The generated workflow MUST enforce the strict `**Verdict:** [Approved | Revision Required]` format.
+- **Context Isolation:** Forbid inline execution of complex code review logic; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Embed project-specific code quality standards and linting rules.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Diff-mode:** Generated workflow MUST include the diff-first read mode instruction (see PLAN.md A6).
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -0,0 +1,108 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+audience: subagent
+phase: review-plan
+context:
+  architecture: false
+  prior_summaries: delta
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [supervisor]
+  skills: [supervisor, generic]
+  templates: [PLAN_REVIEW_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [paths.engineering]
+---
+
+# 🌿 Meta-Workflow: Review Plan
+
+## Iron Laws
+
+- Evaluate the plan against what the task actually requires, not against what the plan claims to deliver. Plans routinely understate complexity, omit edge cases, or skip security steps. Your job is adversarial review, not approval.
+- Read `.forge/personas/supervisor.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
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
+## Algorithm
+
+```
+
+0. 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:
+   - Read task prompt (source of truth)
+   - Read PLAN.md (subject of review)
+   - Read stack checklist if available
+
+2. Review:
+   - Evaluate feasibility, completeness, security, architecture alignment, and testing strategy
+   - Identify missing edge cases or failure modes
+
+3. Verdict:
+   - Write PLAN_REVIEW.md using the format:
+     **Verdict:** [Approved | Revision Required]
+     - If Revision Required: provide numbered, actionable items
+     - If Approved: provide any advisory notes
+
+4. Finalize:
+   - Transitions:
+     - **Task mode** — predecessor must be `planned`.
+       - Approved          → `plan-approved`
+       - Revision Required → `plan-revision-required`
+       - Out-of-band escapes (any state): `code-revision-required`, `blocked`, `escalated`, `abandoned`
+       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status plan-approved` (if Approved) or `... status plan-revision-required` (if Revision Required)
+     - **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:
+   - Write `REVIEW-PLAN-SUMMARY.json` to the record's directory with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what this review assessed>",
+       "findings":    ["<up to 12 bullets, 200 chars each — key issues or confirmations>"],
+       "verdict":     "<approved | revision>",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"PLAN_REVIEW.md"
+     }
+     ```
+   - Call (task mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} review_plan \
+       engineering/sprints/{sprint}/{task}/REVIEW-PLAN-SUMMARY.json
+     ```
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} review_plan \
+       engineering/bugs/{bugDir}/REVIEW-PLAN-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+```
+
+## Generation Notes
+
+- Enforce `**Verdict:** [Approved | Revision Required]` format exactly — orchestrator branches on this.
+- **Markers (required by `/forge:run-task` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `.forge/personas/supervisor.md` persona path. Missing any → kickoff shim refuses to dispatch.
+- Token Reporting: `_fragments/finalize.md` — wire via `file_ref:`.
+- Event Emission: "complete" event MUST include the `eventId` passed by the orchestrator.

package/dist/forge-payload/meta/workflows/meta-review-sprint-completion.md

@@ -0,0 +1,65 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [paths.engineering]
+---
+
+# 🗻 Meta-Workflow: Review Sprint Completion
+
+## Purpose
+
+Verify that all tasks in a sprint have been completed, committed, and validated before closing the sprint.
+
+## Algorithm
+
+```
+1. Load Context:
+   - Read sprint manifest
+   - Read all task manifests in the sprint
+   - Check VCS for all expected commit hashes
+
+2. Verification:
+   - Confirm every task is in `committed` status
+   - Verify all `approved` tasks have a corresponding commit
+   - Check for any lingering "escalated" tasks
+
+3. Verdict:
+   - Write SPRINT_COMPLETION_REVIEW.md using the format:
+     **Verdict:** [Approved | Revision Required]
+     - If Revision Required: list missing commits or unresolved tasks
+     - If Approved: confirm sprint is ready for retrospective
+
+4. Finalize:
+   - If step-3 verdict is `Approved`:
+     - Update sprint status to `completed` via
+       `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status completed`
+   - If step-3 verdict is `Revision Required` and orchestrator passed `mode=partial`:
+     - Update sprint status to `partially-completed` via
+       `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status partially-completed`
+   - If step-3 verdict is `Revision Required` and orchestrator passed `mode=complete`:
+     - Do NOT transition status. Leave the sprint at its current status and exit;
+       the orchestrator will surface the verdict to the user.
+   - **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.
+```
+
+## 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 `review_sprint_completion.md` must follow the strict "Algorithm" block format.
+- **Verdict Detection:** The generated workflow MUST enforce the strict `**Verdict:** [Approved | Revision Required]` format.
+- **Context Isolation:** Forbid inline execution of sprint-wide audits; use the `Agent` tool for sub-tasks.
+- **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.