@entelligentsia/forgecli 0.15.0 → 0.20.0

package/dist/forge-payload/integrity.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.46.1",
-  "generated": "2026-05-22",
+  "version": "0.51.1",
+  "generated": "2026-05-23",
   "note": "Tamper-evident only. Authoritative source: /forge:update from remote.",
   "files": {
     "commands/add-pipeline.md": "402c1deb6f19ad99561b48548ad89e3e1f625b827dce633eb84317556c0a1a4a",
@@ -9,7 +9,7 @@
     "commands/calibrate.md": "c764e735c9212eaf785d3d0afaf926f536fef099421b2b1bde7a4b1e3114d443",
     "commands/config.md": "67251316b806d706bb77f063128e29995c6b4abaf554f4d5558bd97a1a6cfcfe",
     "commands/enhance.md": "4bbfc05cf85c862c49883bc36f1272f87cd49c8cbe00f9196e76d542e6eaa720",
-    "commands/health.md": "cf8a59cfb403ba268922bc60abcdd9255a3b5690ae0175bb2819b3f6789debc0",
+    "commands/health.md": "31fdc6e01529b0ee8cfea4a4937e140bacec78f273260d5406108f8be1bf7aea",
     "commands/init.md": "3c0522294c692e8fbb75f925370caee66f54b23d7dd3a692bedcd69f95718b28",
     "commands/materialize.md": "195292c9e98f50773c1b0c84f9bbc42438c4c8c989a84bd98092f6692799d6d6",
     "commands/migrate.md": "b226f10a6f202bfd4a840314f34d503da34a077abbf1dff8d2b40f864474a76b",
@@ -23,10 +23,16 @@
     "commands/update.md": "6f7be76884888b0cbbe5e60a6926bbaa368f2ee3191f2be40adc8d263ad414aa",
     "agents/store-query-validator.md": "f4c3573edcf6e28809515705362df611806a805c5269404fb17e31433cf3a81c",
     "agents/tomoshibi.md": "0112604af0856235d7f028683dbfa3f4af63355cb2dd79d26592e983a6ecec8b",
-    "hooks/check-update.js": "75a70718d088b7c92ac0343908d07c2eb3bb334c427947490af1d775790859e1",
-    "hooks/forge-permissions.js": "d72fe4a7f010d363798680fa6afeb004f8747e2479ebdf653bc2200c9be073dc",
-    "hooks/triage-error.js": "b1e9c1c9a9f3e4868fff295f2caf87a2a72a817ee767af35f6334c88e45e16d4",
-    "hooks/validate-write.js": "bf17f740ae43d85a7f4b18bc08e2628534c3698ec5202cb51ebd3f0792375f24",
+    "hooks/check-update.cjs": "e66a03eeca609c7426ba7ab8502d41a10b4d740861a6f9728e8ca1e49db8c86a",
+    "hooks/forge-permissions.cjs": "8de18fe7e6c9ee1751926275a37f4bb68a5a53090d366d2aa44157c106e7857e",
+    "hooks/post-init.cjs": "c82bc76e846708a471acfbbc6839f341be843a3fb8d711e3a0f2733aa3da9b3d",
+    "hooks/post-sprint.cjs": "21099458fcde372f0f40895447ea76318de88d2a857d764f8fbbd0adab3ad74a",
+    "hooks/triage-error.cjs": "f33e4fd67168c437d55d059f67cf893f1d11b59df4c712153a1dfd7d9bb55930",
+    "hooks/validate-write.cjs": "3ec7bbbb2cc19f22c78da5a9e7b5031066f4b669c76a10c9f8a92a1a48fcea0a",
+    "schemas/transitions/bug.json": "27b17da42d1cebffbd4f61ab3dcd432a0017aa71997d548ed80d22c2fc3fad6a",
+    "schemas/transitions/sprint.json": "2e0a629396e687b0ca88e1814ac3e35d84533a5d55b25237ab67feddce3c9deb",
+    "schemas/transitions/task.json": "4c71849747baa0d585756e57c56325ff6219c078178374e60815dff91e25e3e7",
+    "schemas/enum-catalog.json": "db3ae83b313b5cea9186b3e28f8290daa1f562afd610d4ce9d1e52abbd0b13a4",
     "tools/verify-integrity.cjs": "3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
   }
 }

package/dist/forge-payload/meta/workflows/_fragments/generation-instructions.md

@@ -0,0 +1,81 @@
+# Fragment: Generation Instructions — Structural Template Guide
+
+> **Pattern:** This fragment is a template guide, not a verbatim include.  
+> Each workflow's `## Generation Instructions` section is kept inline because the
+> content is workflow-specific (slug names, persona paths, project-specific markers,
+> and stack commands vary per workflow). Use this guide to ensure every `## Generation
+> Instructions` section has the required subsections in the required order.
+>
+> **Distinction from verbatim fragments:** CM-6 (Generation Instructions repetition)
+> is closed-as-documented, not closed-as-deduplicated. The prose stays inline; this
+> guide documents the canonical template so future authors follow the same structure.
+> See `doc/decisions/meta-fragment-includes.md`.
+
+---
+
+## Required subsection order
+
+```markdown
+## Generation Instructions
+
+- **Persona Self-Load:** (if applicable — see below)
+- **Workflow Structure:** The generated `{slug}.md` must follow the strict "Algorithm" block format.
+- **Markers:** (if applicable — see kickoff-shim marker requirements)
+- **Context Isolation:** Forbid inline execution of {domain}; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - {stack-specific notes}
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.
+```
+
+### Subsection definitions
+
+**`Persona Self-Load`** — *conditional*. Required when the generated workflow uses the
+Persona Self-Load pattern (the generated file must begin by reading a persona `.md` file
+before any other tool use). Specify the exact persona path. Used in: `meta-collate.md`,
+`meta-retrospective.md`, `meta-review-sprint-completion.md`, `meta-sprint-intake.md`,
+`meta-sprint-plan.md`. Omit for subagent-targeted workflows where the persona is loaded
+by the orchestrator before dispatch.
+
+**`Workflow Structure`** — *required*. Names the generated file slug and asserts the
+"Algorithm" block format. Format: `The generated \`{slug}.md\` must follow the strict "Algorithm" block format.`
+
+**`Markers`** — *conditional*. Required when a kickoff shim validates structural markers
+in the generated workflow (e.g., presence of `## Iron Laws`, `## Store-Write Verification`,
+`forge_store` token, persona path). Omit when no kickoff shim validates the output.
+
+**`Context Isolation`** — *required*. Names the domain-specific operation that must NOT
+run inline, and mandates the `Agent` tool for sub-tasks.
+
+**`Project Specifics`** — *required*. One or more bullets describing the project-context
+substitutions the generator must embed (stack commands, KB paths, template references,
+task ID format, etc.).
+
+**`Token Reporting`** — *required* (with one exception: `meta-quiz-agent.md` omits it
+because quiz-agent is an inline helper, not an orchestrated phase). Standard form: `See
+\`_fragments/finalize.md\` — wire via \`file_ref:\`.` Expanded token-reporting prose is
+used in workflows where the generated file must mandate a specific sidecar-emit sequence
+(retrospective, sprint-intake, sprint-plan, review-sprint-completion) — in those cases,
+the full expanded form lives inline.
+
+**`Event Emission`** — *required* (same exception as Token Reporting). Standard form:
+`Ensure the "complete" event includes the \`eventId\` passed by the orchestrator.`
+
+---
+
+## Orchestrator-special cases
+
+`meta-fix-bug.md` and `meta-orchestrate.md` have Generation Instructions that contain
+workflow-specific structural requirements (role-to-noun mapping, PERSONA_MAP, spawn
+patterns, fault tolerance rules). These cannot be collapsed into the standard subsection
+template. Their Generation Instructions are long-form inline prose.
+
+---
+
+## Byte-budget note
+
+A standard Generation Instructions section (five subsections, no expanded token reporting)
+contributes approximately 350–450 bytes. Sections with expanded token-reporting prose
+(sprint-intake, retrospective) may reach 700–900 bytes. Byte budgets in
+`phase-frontmatter.test.cjs` must be set ≥ the actual byte count of the file (with
+≤ 512 bytes headroom).

package/dist/forge-payload/meta/workflows/_fragments/iron-laws.md

@@ -0,0 +1,72 @@
+# Fragment: Iron Laws — Structural Template Guide
+
+> **Pattern:** This fragment is a template guide, not a verbatim include.  
+> Each workflow's `## Iron Laws` section is kept inline because the opening law and
+> persona load line are workflow-specific. Use this guide to ensure every `## Iron
+> Laws` section has the required structure.
+>
+> **Distinction from verbatim fragments:** CM-2 (Iron Laws structural duplication)
+> and CM-3 (persona-load line repetition) are closed-as-documented, not
+> closed-as-deduplicated. The prose stays inline; this guide documents the canonical
+> structure so future authors follow the same pattern. See `doc/decisions/meta-fragment-includes.md`.
+
+---
+
+## Required structure
+
+An Iron Laws section MUST contain exactly these three bullets in this order:
+
+```markdown
+## Iron Laws
+
+- {WORKFLOW_SPECIFIC_LAW}
+- Read `.forge/personas/{persona}.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.
+```
+
+### Slot definitions
+
+**`{WORKFLOW_SPECIFIC_LAW}`** — first bullet; unique per workflow. Describes the single most
+important constraint of *this workflow* (e.g., "Commit only the artifacts produced for this
+task", "Approve only when the implementation is consistent with the project's architecture",
+"Follow the plan exactly"). Never generic; never copied from another workflow.
+
+**persona load line** — second bullet; constant prose with `{persona}` replaced by the
+workflow's `deps.personas[0]` value (e.g., `engineer`, `architect`, `supervisor`,
+`product-manager`, `qa-engineer`).
+
+**store-I/O law** — third bullet; verbatim identical across all workflows.
+
+---
+
+## Orchestrator-special case
+
+`meta-fix-bug.md` and `meta-orchestrate.md` have Iron Laws that *defer* to
+`generic-skills.md § Orchestrator Iron Laws` via a prose comment, then add
+workflow-specific supplemental laws. This is intentional and cannot be collapsed
+into the standard three-bullet structure.
+
+---
+
+## Intentional omissions
+
+Some workflows have no `## Iron Laws` section by design:
+
+- `meta-quiz-agent.md` — utility workflow; no store writes; no output contract.
+- `meta-review-sprint-completion.md` — read-only verification; no state transitions.
+
+Intentional omissions are documented with an inline comment before the `## Algorithm`
+heading:
+```html
+<!-- No Iron Laws section: {reason} -->
+```
+
+---
+
+## Byte-budget note
+
+The Iron Laws section (three bullets) contributes approximately 280–320 bytes to a
+workflow file. Byte budgets in `phase-frontmatter.test.cjs` must be set ≥ the actual
+byte count of the file (with ≤ 512 bytes headroom). Lowering budgets after removing
+content is always safe; raising budgets requires written justification in the commit
+body naming the new content added.

package/dist/forge-payload/meta/workflows/_fragments/store-cli-verbs.md

@@ -26,10 +26,20 @@ Notes for subagents:
   natural-language lookup.
 - **`update-status`** is the ONLY supported task/bug status mutation path.
   Do not `write` a task back with a new `status` field; the FSM is enforced
-  by `update-status`.
+  by `update-status`. Syntax requires the field keyword `status` as the third
+  argument — four args total:
+  `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status {value}`
+  The three-arg form `update-status task {taskId} {value}` is WRONG and will
+  error. Always include `status` between the id and the value.
 - **`emit`** appends an event. There is no `append-event` / `add-event`.
 - **`set-summary`** / **`set-bug-summary`** write summary sidecars referenced
   from the entity record. Do not inline summaries into the entity via `write`.
+- **Artifact I/O:** Use `forge_artifact` for ALL phase artifact reads and writes
+  (PLAN.md, PROGRESS.md, *-SUMMARY.json, CODE_REVIEW.md, etc.). Never construct
+  artifact file paths manually — the tool resolves paths from entity IDs and
+  validates JSON summary schemas on write. After writing a summary JSON via
+  `forge_artifact`, link it to the store record via `forge_store set-summary`.
+  Example: `forge_artifact({ command:"write", entity:"task", entityId:"{taskId}", artifact:"progress", content:"..." })`
 - If you need a verb not on this list, run
   `node "$FORGE_ROOT/tools/store-cli.cjs" --help` before improvising.
 - If you supply an unknown verb, entity type, enum value, or field name,

package/dist/forge-payload/meta/workflows/_fragments/store-write-verification.md

@@ -0,0 +1,11 @@
+## 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.

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

@@ -26,6 +26,7 @@ deps:
 
 The Architect gives final sign-off on a completed task after Supervisor approval. This is the last gate before commit.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Approve only when the implementation is consistent with the project's architecture and the deployment posture is understood. Architectural sign-off is not a rubber stamp — it is the last point at which cross-cutting concerns can be caught cheaply.
@@ -34,15 +35,7 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 
 ## 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
 
@@ -67,7 +60,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Assess operational impact (deployment changes, migrations)
 
 3. Sign Off:
-   - Write ARCHITECT_APPROVAL.md containing:
+   - Write the architect approval via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval", content:"<markdown>" })`
+     The markdown content must contain:
      - A canonical verdict line for human readers, on its own line, in this exact form:
        ```
        **Verdict:** [Approved | Revision Required]
@@ -84,7 +79,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.
 
 5. Emit Summary Sidecar:
-   - Write `APPROVE-SUMMARY.json` to the record's directory with the following shape:
+   - Write the approve summary via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"approve-summary", content:"<JSON>" })`
+     The JSON content must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what this approval covered>",
@@ -107,6 +104,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - In bug mode, if the set-bug-summary call exits non-zero, fix the sidecar JSON and retry. Do not return without a valid summary — the downstream commit gate has no other way to read the approval verdict.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `approve_task.md` must follow the strict "Algorithm" block format.

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

@@ -18,12 +18,17 @@ deps:
 
 Regenerate markdown views from the JSON store. This is a deterministic operation — prefer the generated tool, fall back to manual collation.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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
@@ -67,6 +72,16 @@ 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:
      ```
@@ -75,6 +90,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      ```
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/collator.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-commit.md

@@ -26,6 +26,7 @@ deps:
 
 Seal a completed and approved task by committing its artifacts to the VCS and updating the store.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Commit only the artifacts produced for this task; do not sweep unrelated working-tree changes into the commit. The commit boundary mirrors the task boundary.
@@ -34,15 +35,7 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 ## 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
 
@@ -83,6 +76,7 @@ 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.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `commit_task.md` must follow the strict "Algorithm" block format.

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

@@ -15,13 +15,17 @@ deps:
 
 # Meta-Workflow: 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.
-- 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.
 - 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
@@ -610,3 +614,14 @@ 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 -->
+## Generation Instructions
+
+- **Workflow Structure:** This is an `audience: orchestrator-only` workflow (not a subagent-targeted phase workflow). The generated `enhance.md` must follow the strict multi-phase Algorithm block format (Phase 1 / Phase 2 / Phase 3 routing).
+- **Context Isolation:** All proposal application steps that modify `.forge/` structural elements must run in the orchestrator session (full tool access required). Do NOT delegate to a subagent.
+- **Project Specifics:**
+  - Reference the project's `commands.test` and `commands.build` from `.forge/config.json` when verifying stack-command fills in Phase 1.
+  - Reference `forge/tools/queue-drain.cjs`, `forge/tools/replay-scoring.cjs`, `forge/tools/compression-gate.cjs`, `forge/tools/judge-proposal.cjs`, and `forge/tools/delete-candidate-detector.cjs` by their resolved `$FORGE_ROOT` paths.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`. Enhancement runs are orchestrator-only and may be long-running; token reporting is advisory (no orchestrator composes a phase event for this workflow).
+- **Event Emission:** Emit enhancement events directly via `store-cli emit` (orchestrator-only exception to the "do NOT emit yourself" rule — this workflow IS the orchestrator for enhancement).

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.