@entelligentsia/forgecli 0.15.0 → 0.19.0

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

@@ -12,7 +12,14 @@ deps:
   config_fields: [project.prefix, paths.engineering]
 ---
 
+
 # Sprint Intake
+## 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
 
 ```
@@ -46,4 +53,6 @@ deps:
 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 -->

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

@@ -12,6 +12,7 @@ deps:
   config_fields: [project.prefix, paths.engineering]
 ---
 
+
 # Sprint Plan
 ## Algorithm
 
@@ -67,6 +68,7 @@ deps:
    - **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
@@ -82,6 +84,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
@@ -110,4 +115,6 @@ halt and escalate to the human. Include the original payload, the corrected
 payload, and all error messages in the escalation.
 
 **Do NOT** set `FORGE_SKIP_WRITE_VALIDATION=1` to bypass a schema error. That
-environment variable is reserved for emergency operator repair only.
+environment variable is reserved for emergency operator repair only.
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -12,13 +12,18 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Collate
 ## Iron Laws
 
 - Collation is a read-and-rewrite of generated markdown. Do not mutate any JSON record under `.forge/store/`; the store is the source of truth and collation flows downstream from it.
 - Read `.forge/personas/collator.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
 - All store reads via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+- Do NOT call `set-summary` or `set-bug-summary` from within collation. The collator writes markdown views and a `WRITEBACK-SUMMARY.json` disk file only. Calling `set-summary` mutates the JSON store and violates Iron Law 1 (the store is the source of truth; collation flows downstream from it, not into it). The orchestrator reads `WRITEBACK-SUMMARY.json` directly — no store write is needed.
 
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally modified
+     Store-Write Verification variant: collation typically writes markdown views (not JSON records),
+     so the preamble explains when `forge_store` calls apply. Canonical fragment is reference only. -->
 ## Store-Write Verification
 
 Collation typically writes markdown views, not JSON records. If a remediation
@@ -62,10 +67,22 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 4. Finalize:
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
+   - Write `WRITEBACK-SUMMARY.json` to the sprint directory (`engineering/sprints/{sprintId}/`) with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what views were regenerated>",
+       "key_changes": ["<up to 6 bullets — which files were written>"],
+       "verdict":     "n/a",
+       "written_at":  "<current ISO 8601 timestamp>"
+     }
+     ```
+     The orchestrator reads this file directly to compose the collation event narrative. Do NOT call `set-summary` to register it — that would mutate the store in violation of Iron Law 1.
    - Invoke Tomoshibi via Skill tool to refresh KB and workflow links in agent
      instruction files:
      ```
      Use the Skill tool:
        skill: "forge:refresh-kb-links"
      ```
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Commit Task
 ## Iron Laws
 
@@ -29,15 +30,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
 
@@ -76,4 +69,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 5. Finalize:
    - **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.
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -13,8 +13,10 @@ deps:
   config_fields: [paths.engineering, paths.forgeRoot]
 ---
 
+
 # Enhancement Agent
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Orchestrator-only: this workflow runs with full tool access in the orchestrator session. NEVER delegate it to a subagent.
@@ -22,6 +24,9 @@ deps:
 - All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
 - Phase 1 only touches `{{KEY}}` token text; never rewrite persona prose, algorithm steps, or role definitions.
 
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally abbreviated
+     Store-Write Verification variant (4-line condensed form for orchestrator-only workflow).
+     Canonical fragment is reference only. -->
 ## Store-Write Verification
 
 Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
@@ -598,3 +603,5 @@ Invoked by `/forge:enhance --phase 3` (default when no phase given), or delegate
 If any step fails unexpectedly, describe what went wrong and offer:
 
 > "This looks like a Forge bug. Would you like to file a report? Run `/forge:report-bug`."
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -14,6 +14,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Fix Bug
 ## Pipeline Phases
 
@@ -159,8 +160,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
@@ -386,6 +391,8 @@ Note: the `forbid bug.status == approved | verified` rows are defensive — no
 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) -->
 ## Iron Laws
 
 <!-- Shared orchestrator laws live in generic-skills.md § Orchestrator Iron Laws. -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Implement Plan
 ## Algorithm
 
@@ -50,10 +51,9 @@ deps:
    - 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
@@ -65,34 +65,27 @@ deps:
        - `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.
@@ -102,15 +95,9 @@ 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 -->
 
 ## Friction Emit
-Emit `type:friction` `{workflow:implement, persona:engineer, issue}` per `_fragments/friction-emit.md`.
+Emit `type:friction` `{workflow:implement, persona:engineer, issue}` per `_fragments/friction-emit.md`.
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -13,7 +13,14 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Structural Migration (v0.x → v0.40)
+## 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.
@@ -437,3 +444,5 @@ 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 -->

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

@@ -14,6 +14,7 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Orchestrate Task
 ## Pipeline Phases
 
@@ -809,6 +810,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. -->
@@ -869,6 +871,8 @@ subagent returns, the orchestrator:
 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) -->
 ## 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.

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Plan Task
 ## Algorithm
 
@@ -58,7 +59,9 @@ deps:
      - 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:
@@ -72,7 +75,7 @@ deps:
    - **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>",
@@ -82,19 +85,18 @@ deps:
        "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.
@@ -103,15 +105,9 @@ 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 -->
 
 ## Friction Emit
-Emit `type:friction` `{workflow:plan-task, persona:architect, issue}` per `_fragments/friction-emit.md`.
+Emit `type:friction` `{workflow:plan-task, persona:architect, issue}` per `_fragments/friction-emit.md`.
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Review Implementation
 ## Iron Laws
 
@@ -29,15 +30,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
 
@@ -63,7 +56,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
@@ -78,7 +73,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>",
@@ -89,14 +86,10 @@ 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 -->

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

@@ -20,8 +20,10 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # 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 +32,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 +55,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 +72,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,20 +85,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} 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
-
-- 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.
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -12,7 +12,14 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Retrospective
+## 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
 
 ```
@@ -42,4 +49,6 @@ deps:
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
      (tombstone — written after the purge; the only event in the directory
      going forward)
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Update Implementation
 ## Iron Laws
 
@@ -29,15 +30,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
 
@@ -59,4 +52,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 4. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
    - **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 -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Update Plan
 ## Iron Laws
 
@@ -29,15 +30,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
 
@@ -59,4 +52,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 4. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
    - **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 -->