@entelligentsia/forgecli 0.11.3 → 0.19.0

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

@@ -168,8 +168,12 @@ Differences are confined to the **triage** step and the **path branch**.
      • Reproduce the bug (failing test or reproduction script).
      • Confirm the root cause via codebase research.
      • Decide Path A vs Path B by the criteria above.
-     • Write TRIAGE.md and TRIAGE-SUMMARY.json (with `path` field).
-     • Call set-bug-summary {bugId} triage TRIAGE-SUMMARY.json
+     • Write triage artifact:
+       forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}", artifact:"triage", content:"<markdown>" })
+     • Write triage-summary artifact (JSON shape documented in § Triage Judgement):
+       forge_artifact({ command:"write", entity:"bug", entityId:"{bugId}", artifact:"triage-summary", content:"<JSON>" })
+     • Call set-bug-summary {bugId} triage via forge_store:
+       forge_store({ command:"set-bug-summary", bugId:"{bugId}", phase:"triage", file:"TRIAGE-SUMMARY.json" })
    - On return, orchestrator transitions status:
        store-cli update-status bug {bugId} status triaged
        store-cli update-status bug {bugId} status in-progress
@@ -396,6 +400,7 @@ phase in this workflow writes those values, and a follow-up cleanup should
 drop them from `bug.schema.json` entirely. Until then, these gates halt any
 LLM-improvised attempt to land in the run-task trap (see today's regression).
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template (fix-bug uses orchestrator-special long-form prose — cannot be reduced to standard subsections) -->
 ## Generation Instructions
 
 Mirrors `meta-orchestrate.md § Generation Instructions` with these
@@ -430,6 +435,7 @@ adjustments:
   they share the gate-and-verdict machinery with their `--task` paths via
   `BUG_PHASE_VERDICT_SOURCE` in `read-verdict.cjs`.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance (fix-bug uses orchestrator-special deferral to generic-skills.md § Orchestrator Iron Laws) -->
 ## Iron Laws
 
 <!-- Shared orchestrator laws live in generic-skills.md § Orchestrator Iron Laws. -->

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

@@ -55,10 +55,9 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
    - Run build if frontend assets modified: {BUILD_COMMAND}
 
 4. Documentation:
-   - Write PROGRESS.md containing:
-     - Summary of changes
-     - Test evidence (copy of output)
-     - Files changed manifest
+   - Write PROGRESS.md via `forge_artifact`:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"progress", content:"<markdown>" })`
+     Content must include: summary of changes, test evidence (copy of output), files changed manifest.
 
 5. Knowledge Writeback:
    - Update architecture/domain/stack-checklist if discoveries were made
@@ -70,56 +69,42 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
        - `planned`        → `implemented` (workflow-prose path — direct)
        - `plan-approved`  → `implementing` → `implemented` (supervisor-review path)
        - 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 implemented`
+       Update status — check current state first:
+       - If predecessor is `planned` or `implementing`:
+         `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
+       - If predecessor is `plan-approved` (two-step mandatory — FSM forbids skipping `implementing`):
+         `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implementing`
+         `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
      - **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.
 
 7. Emit Summary Sidecar:
-   - Write `IMPLEMENTATION-SUMMARY.json` to the record's directory with the following shape:
-     ```json
-     {
-       "objective":   "<one sentence — what this implementation delivered>",
-       "key_changes": ["<up to 12 bullets, 200 chars each — files changed, key decisions>"],
-       "verdict":     "n/a",
-       "written_at":  "<current ISO 8601 timestamp>",
-       "artifact_ref":"PROGRESS.md"
-     }
-     ```
-   - Call (task mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} implementation \
-       engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json
-     ```
+   - Write `IMPLEMENTATION-SUMMARY.json` via `forge_artifact`:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"implementation-summary", content:"<JSON>" })`
+     JSON shape: `{"objective":"<one sentence>", "key_changes":["<up to 12 bullets>"], "verdict":"n/a", "written_at":"<ISO 8601>", "artifact_ref":"PROGRESS.md"}`
+     The tool validates required fields automatically — fix and retry if it rejects.
+   - Then link sidecar to store (task mode):
+     `forge_store({ command:"set-summary", args:["{taskId}", "implementation", "engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json"] })`
      Or (bug mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} implementation \
-       engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json
-     ```
-   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation", "engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json"] })`
 ```
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Follow the Algorithm step by step. Execute the approved PLAN.md exactly; do not invent scope or skip steps without updating the plan first.
-- Read `.forge/personas/engineer.md` first; print the persona identity line to stdout before any other tool use.
+- Read `.forge/personas/engineer.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
 - All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
 - Run the full test suite before declaring the task implemented. Silent continuation past test failures is never acceptable.
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Friction Emit
 Emit `type:friction` `{workflow:implement, persona:engineer, issue}` per `_fragments/friction-emit.md`.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** Strict "Algorithm" block format.

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

@@ -30,6 +30,13 @@ or when `.forge/structure-versions.json` is absent (pre-T05 install detected).
 
 ---
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Migration operations are reversible and user-confirmed before any destructive writes. Do not skip the Phase 2 confirmation gate — proceed only after the user explicitly accepts the migration plan.
+- Read `.forge/personas/engineer.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
 ## Pre-conditions
 
 - `/forge:init` has run: `.forge/config.json` exists and is readable.
@@ -453,3 +460,14 @@ cd .forge && md5sum -c archive/pre-migration/MANIFEST.md5 2>/dev/null | grep -v
 | `manage-versions.cjs init` exits non-zero | Halt. Report error. Archive is complete — rollback is available. |
 | `store-cli.cjs emit` exits non-zero | Report error. Continue — event is diagnostic only. |
 | Any unexpected error | Describe the error, point user to rollback procedure, suggest `/forge:report-bug`. |
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- **Workflow Structure:** The generated `migrate_structural.md` must follow the strict multi-phase Algorithm block format (Phase 0 pre-flight → Phase 1 read/extract → Phase 2 confirmation gate → Phase 3 write → Phase 4 verify/emit → Rollback Procedure → Error Handling).
+- **Context Isolation:** Forbid inline execution of archival or substitution operations; use `forge_store` reads and structured `node` invocations for all store interactions.
+- **Project Specifics:**
+  - Reference the project's `paths.engineering` and `paths.forgeRoot` from `.forge/config.json` for all path resolutions.
+  - Include the project's migration path docs in the Error Handling table (e.g., expected schema files, archive paths).
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`. Token reporting is diagnostic only (migration is not an orchestrated phase — it emits its own record via `store-cli emit` in Phase 4).
+- **Event Emission:** Migration emits its own completion event directly via `store-cli emit` in Phase 4 (orchestrator-exception; this is not a task phase). The "do NOT emit yourself" rule does not apply here.

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

@@ -815,6 +815,7 @@ route you take.
 write through and append an audit line to the affected sprint's
 `progress.log`.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance (orchestrate uses orchestrator-special deferral to generic-skills.md § Orchestrator Iron Laws) -->
 ## Iron Laws
 
 <!-- Shared orchestrator laws live in generic-skills.md § Orchestrator Iron Laws. -->
@@ -876,6 +877,7 @@ Do not include hardcoded example `model` or `provider` strings in the
 generated orchestrator prose — they are the seed of LLM hallucination.
 Refer subagents to `.forge/schemas/event.schema.json` instead.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template (orchestrate uses orchestrator-special long-form prose — cannot be reduced to standard subsections) -->
 ## Generation Instructions
 - Fill in concrete test/build/lint commands from .forge/config.json
 - Reference generated workflows by exact filename in .forge/workflows/

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

@@ -63,7 +63,9 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
      - Docs-only changes → NOT material
 
 3. Plan:
-   - Generate PLAN.md using the project plan template
+   - Write the plan via forge_artifact:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan", content:"<markdown>" })`
+     where `<markdown>` follows 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:
@@ -77,7 +79,7 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
    - **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:
+   - Write the plan summary via forge_artifact. Shape:
      ```json
      {
        "objective":   "<one sentence — what this plan sets out to build>",
@@ -87,40 +89,32 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
        "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
-     ```
+     Task mode:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan-summary", content:"<JSON>" })`
+     Bug mode:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan-summary", content:"<JSON>" })`
+   - Register the summary with the store (task mode):
+     `forge_store({ command:"set-summary", args:["{record_id}", "plan"] })`
      Or (bug mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} plan \
-       engineering/bugs/{bugDir}/BUG-FIX-PLAN-SUMMARY.json
-     ```
+     `forge_store({ command:"set-bug-summary", args:["{record_id}", "plan"] })`
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Follow the Algorithm step by step. No code, pseudocode, or implementation sketches in the plan.
-- Read `.forge/personas/architect.md` first; print the persona identity line to stdout before any other tool use.
+- Read `.forge/personas/architect.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
 - All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
 
 ## Store-Write Verification
 
-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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Friction Emit
 Emit `type:friction` `{workflow:plan-task, persona:architect, issue}` per `_fragments/friction-emit.md`.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** Strict "Algorithm" block format.

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

@@ -23,6 +23,8 @@ 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
 
 ```
@@ -57,6 +59,7 @@ 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
@@ -95,7 +98,7 @@ 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
+## Template Output Format
 
 ```markdown
 # 🍵 Workflow: Quiz Agent — {Project Name}

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

@@ -18,6 +18,13 @@ deps:
 
 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
 
 ```
@@ -49,6 +56,7 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
      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.

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

@@ -26,6 +26,7 @@ deps:
 
 The Supervisor reviews the Engineer's implementation for correctness, quality, and compliance with the approved plan.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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."
@@ -34,15 +35,7 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -68,7 +61,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Verify test evidence in PROGRESS.md is authentic and complete
 
 3. Verdict:
-   - Write CODE_REVIEW.md using the format:
+   - 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
@@ -83,7 +78,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **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:
+   - 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:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -94,18 +91,13 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      }
      ```
    - Call (task mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} code_review \
-       engineering/sprints/{sprint}/{task}/REVIEW-IMPL-SUMMARY.json
-     ```
+     `forge_store({ command:"set-summary", entity:"task", id:"{taskId}", phase:"code_review" })`
      Or (bug mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} code_review \
-       engineering/bugs/{bugDir}/REVIEW-IMPL-SUMMARY.json
-     ```
+     `forge_store({ command:"set-bug-summary", entity:"bug", id:"{bugId}", phase:"code_review" })`
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `review_implementation.md` must follow the strict "Algorithm" block format.

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

@@ -22,6 +22,7 @@ deps:
 
 # 🌿 Meta-Workflow: Review Plan
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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.
@@ -30,15 +31,7 @@ deps:
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -61,7 +54,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Identify missing edge cases or failure modes
 
 3. Verdict:
-   - Write PLAN_REVIEW.md using the format:
+   - 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
@@ -77,7 +71,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **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:
+   - 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
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -89,18 +84,17 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      ```
    - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} review_plan \
-       engineering/sprints/{sprint}/{task}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-summary", entity:"task", id:"{record_id}", phase:"review_plan" })
      ```
      Or (bug mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} review_plan \
-       engineering/bugs/{bugDir}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-bug-summary", entity:"bug", id:"{record_id}", phase:"review_plan" })
      ```
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
-## Generation Notes
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
 
 - 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.

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

@@ -18,6 +18,8 @@ deps:
 
 Verify that all tasks in a sprint have been completed, committed, and validated before closing the sprint.
 
+<!-- No Iron Laws section: review-sprint-completion is a read-only verification workflow. No store writes; no entity state transitions (status update in step 4 is the only write — it matches the standard store-I/O law applied by the generated workflow). Intentional omission per N-CM-5 audit. -->
+
 ## Algorithm
 
 ```
@@ -50,6 +52,7 @@ Verify that all tasks in a sprint have been completed, committed, and validated
    - **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/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.

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

@@ -18,6 +18,13 @@ deps:
 
 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
 
 ```
@@ -53,6 +60,7 @@ Capture sprint requirements via a structured interview and document them for pla
    - **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.

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

@@ -72,6 +72,7 @@ Break sprint requirements into a set of estimated tasks with a dependency graph.
    - **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
@@ -87,6 +88,9 @@ after the Purpose heading and before the Algorithm block:
   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
@@ -117,6 +121,7 @@ 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.

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

@@ -26,6 +26,7 @@ deps:
 
 Update the implementation of a task based on a "Revision Required" verdict from a review phase.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Address every "Revision Required" item from the review artifact at the correct code location; do not paper over them with comments. If a finding is wrong, escalate rather than ignore.
@@ -34,15 +35,7 @@ Update the implementation of a task based on a "Revision Required" verdict from
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -66,6 +59,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **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
 
 - **Workflow Structure:** The generated `update_implementation.md` must follow the strict "Algorithm" block format.

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

@@ -26,6 +26,7 @@ deps:
 
 Update the implementation plan of a task based on a "Revision Required" verdict from the plan review phase.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Address every numbered finding in the review artifact. Do not silently drop items; if a finding is wrong, note the reason in the revised plan rather than ignoring it.
@@ -34,15 +35,7 @@ Update the implementation plan of a task based on a "Revision Required" verdict
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -66,6 +59,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **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
 
 - **Workflow Structure:** The generated `update_plan.md` must follow the strict "Algorithm" block format.

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

@@ -26,6 +26,7 @@ deps:
 
 The Supervisor performs a final validation of the implementation against the acceptance criteria and the technical spec.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Validate against the acceptance criteria as written; do not soften, expand, or reinterpret them. The validator's job is to catch what the implementer optimistically considered "done".
@@ -34,15 +35,7 @@ The Supervisor performs a final validation of the implementation against the acc
 
 ## 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.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -68,7 +61,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - 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:
-   - Write VALIDATION_REPORT.md using the format:
+   - 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
@@ -78,7 +73,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **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 `VALIDATION-SUMMARY.json` to the task directory with the following shape:
+   - 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:
      ```json
      {
        "objective":   "<one sentence — what acceptance criteria were validated>",
@@ -99,6 +96,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 ## Friction Emit
 Emit `type:friction` `{workflow:validate, persona:qa-engineer, issue}` per `_fragments/friction-emit.md`.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `validate_task.md` must follow the strict "Algorithm" block format.