@entelligentsia/forgecli 1.0.3 → 1.0.14

package/dist/forge-payload/meta/workflows/_fragments/friction-emit.md

@@ -42,7 +42,7 @@ fields (`model`, `provider`, `eventId`, timestamps, token counts) are
 at drain time.
 
 ```sh
-node "$FORGE_ROOT/tools/friction-emit.cjs" \
+node .forge/tools/friction-emit.cjs \
   --workflow {workflow-key} \
   --persona  {persona-noun} \
   --issue    skill_unused \

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

@@ -21,7 +21,7 @@ An Iron Laws section MUST contain exactly these three bullets in this order:
 
 - {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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 ```
 
 ### Slot definitions

package/dist/forge-payload/meta/workflows/_fragments/progress-reporting.md

@@ -25,7 +25,7 @@ orchestrator monitors in real time.
 **Writing entries:** Use `store-cli progress`:
 
 ```
-node "$FORGE_ROOT/tools/store-cli.cjs" progress {sprintId} {agentName} {bannerKey} {status} "detail text"
+node .forge/tools/store-cli.cjs progress {sprintId} {agentName} {bannerKey} {status} "detail text"
 ```
 
 **Monitoring:** The orchestrator starts a Monitor on the progress log before
@@ -34,5 +34,5 @@ spawning each subagent and stops it after the subagent returns.
 **Clearing:** The orchestrator clears the progress log at task start:
 
 ```
-node "$FORGE_ROOT/tools/store-cli.cjs" progress-clear {sprintId}
+node .forge/tools/store-cli.cjs progress-clear {sprintId}
 ```

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

@@ -28,20 +28,44 @@ Notes for subagents:
   Do not `write` a task back with a new `status` field; the FSM is enforced
   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}`
+  `node .forge/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`.
+- **`set-summary <id> <phase>`** / **`set-bug-summary <id> <phase>`** link a
+  phase summary onto the entity record. The JSON-file argument is **optional**:
+  when omitted, the sidecar is auto-resolved from the record's `path` plus the
+  canonical phase→filename map (so `set-summary {taskId} validation` just works).
+  Never pass a hand-built `engineering/sprints/.../…-SUMMARY.json` path. Do not
+  inline summaries into the entity via `write`.
+  - **`forge_store` tool shape (not CLI flags).** The tool has exactly two
+    fields: `command` (string) and `args` (positional string array). There is
+    NO `entity` / `id` / `phase` named field — passing them silently drops them.
+    The summary call is `forge_store({ command:"set-summary", args:["<id>", "<phase>"] })`
+    where `args[0]` is the record id and `args[1]` is the LITERAL phase key
+    (`plan`, `review_plan`, `implementation`, `code_review`, `validation`,
+    `triage`, `approve`). `args[1]` is NEVER the record id and NEVER a path —
+    putting the id in both slots is the canonical failure and the phase-ownership
+    guard rejects it with `expected summary key '<phase>'`.
 - **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`.
+  `forge_artifact`, link it to the store record via `forge_store set-summary {id} {phase}` (no path).
   Example: `forge_artifact({ command:"write", entity:"task", entityId:"{taskId}", artifact:"progress", content:"..." })`
+- **Artifact addressing (canonical) — never reconstruct a path.** Address an
+  artifact by `(entity, entityId, kind)` via `forge_artifact`, or read the
+  entity's `path` field from the store record. The on-disk directory is owned by
+  the record's `path`, NOT by any id template. Token glossary:
+  - `{sprintId}` / `{taskId}` / `{bugId}` — the **store record filenames**
+    (`.forge/store/<kind>s/<id>.json`); deterministic and safe to use as IDs.
+  - `{sprint}` / `{task}` / `{bug}` — runtime path-template substitutions used by
+    the **preflight gate**, derived from the record's `path` (not the bare ID).
+  - The engineering artifact directory always comes from `record.path`.
+  These spellings are parsed literally by tools (`preflight-gate.cjs`,
+  `collate.cjs`) — do not invent new spellings or rename them in prose.
 - If you need a verb not on this list, run
-  `node "$FORGE_ROOT/tools/store-cli.cjs" --help` before improvising.
+  `node .forge/tools/store-cli.cjs --help` before improvising.
 - If you supply an unknown verb, entity type, enum value, or field name,
   store-cli appends a **Did you mean?** suggestion to the error message.
   Suggestions use Levenshtein distance (≤ 2) and a curated drift map for

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

@@ -31,7 +31,7 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 
 - 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.
 - 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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Store-Write Verification
 
@@ -42,9 +42,8 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 ```
 
 0a. Pre-flight Gate Check:
-   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase approve --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase approve --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -53,7 +52,7 @@ The Architect gives final sign-off on a completed task after Supervisor approval
    - If `--force` is present in the invocation arguments, skip this step entirely.
    - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
    - Read current task state:
-     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+     `node .forge/tools/store-cli.cjs read task {record_id} --json`
    - Extract the `status` field from the JSON output.
    - Allowed states for this phase: `review-approved`.
    - If the current status is NOT in the allowed set:
@@ -86,7 +85,7 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 
 4. Finalize:
    - Transitions:
-     - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status approved`. The status IS the verdict signal for task-mode commit gate (`STATUS_SOURCE` in `read-verdict.cjs`).
+     - **Task mode** — Update status: `node .forge/tools/store-cli.cjs update-status task {taskId} status approved`. The status IS the verdict signal for task-mode commit gate (`STATUS_SOURCE` in `read-verdict.cjs`).
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.approve.verdict` written in step 5 below (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`). Writing `bug.status` here — especially writing `approved` or `verified` — violates `meta-fix-bug.md § Iron Laws #2` and is the trap that produced the FORGE-BUG-002 regression.
    - **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.
 
@@ -103,15 +102,14 @@ The Architect gives final sign-off on a completed task after Supervisor approval
        "artifact_ref":"ARCHITECT_APPROVAL.md"
      }
      ```
-   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal:
+   - Call (task mode) — optional for tasks, since `task.status` is the canonical signal.
+     The sidecar path is auto-resolved from the record's `path` — never pass it:
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} approve \
-       engineering/sprints/{sprint}/{task}/APPROVE-SUMMARY.json
+     node .forge/tools/store-cli.cjs set-summary {taskId} approve
      ```
      Or (bug mode) — REQUIRED for bugs, this is the canonical verdict signal:
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} approve \
-       engineering/bugs/{bugDir}/APPROVE-SUMMARY.json
+     node .forge/tools/store-cli.cjs set-bug-summary {bugId} approve
      ```
    - 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.
 ```

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

@@ -37,7 +37,7 @@ and the only phase that records the route decision read by the orchestrator
   reproduction has no business going to plan-fix or implement.
 - Read `.forge/personas/bug-fixer.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"`).
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`).
   Never edit `.forge/store/*.json` directly.
 - **Triage NEVER writes `bug.status`.** The orchestrator (`meta-fix-bug.md`)
   owns the `reported → triaged` and `triaged → in-progress` transitions.
@@ -60,8 +60,7 @@ and the only phase that records the route decision read by the orchestrator
 ```
 
 0. Pre-flight Gate Check:
-   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase triage --bug {bugId}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase triage --bug {bugId}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -70,7 +69,7 @@ and the only phase that records the route decision read by the orchestrator
    - Read `.forge/personas/bug-fixer.md` first; print the persona identity
      line to stdout before any other tool use.
    - Read the bug record:
-     `forge_store({ command:"read", entity:"bug", id:"{bugId}" })`
+     `forge_store({ command:"read", args:["bug", "{bugId}"] })`
    - Read business domain docs relevant to the reported symptom.
    - store-cli verbs: `read` | `list` | `write` | `emit` |
      `update-status` | `set-summary` | `set-bug-summary` | `describe` |
@@ -138,13 +137,17 @@ and the only phase that records the route decision read by the orchestrator
 
    - Call:
      ```
-     forge_store({ command:"set-bug-summary", entity:"bug",
-                   id:"{bugId}", phase:"triage",
-                   file:"engineering/bugs/{bugDir}/TRIAGE-SUMMARY.json" })
+     forge_store({ command:"set-bug-summary", args:["{bugId}", "triage"] })
+     // sidecar path auto-resolved from the bug record's `path` — never pass it
      ```
-   - If the set-bug-summary call exits non-zero, fix the sidecar JSON
-     and retry (up to 3 attempts per the Store-Write Verification rule).
-     Do not proceed without a valid summary.
+     `forge_store` has only `command` + `args` (positional) — no
+     `entity`/`id`/`phase` field. `args[0]` is the bug id, `args[1]` is the
+     LITERAL phase key `triage` (never the bug id, never a path). See
+     `_fragments/store-cli-verbs.md`.
+   - If the set-bug-summary call exits non-zero (phase-ownership guard:
+     `expected summary key 'triage'`), `args[1]` was wrong — set it to `triage`
+     and retry (up to 3 attempts per the Store-Write Verification rule). Do not
+     proceed without a valid summary.
 
 > **Field-naming caution — runtime-tested.** The route field is named
 > `route`, never `path`. The bug schema's top-level `path` field is the

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

@@ -23,7 +23,7 @@ Regenerate markdown views from the JSON store. This is a deterministic operation
 
 - 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.
+- All store reads via `forge_store` (or `node .forge/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
@@ -46,8 +46,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 ```
 1. Preferred: Run Plugin Tool
-   - Read `paths.forgeRoot` from `.forge/config.json` as `FORGE_ROOT`
-   - Run: `node "$FORGE_ROOT/tools/collate.cjs" [SPRINT_ID]`
+   - Run: `node .forge/tools/collate.cjs [SPRINT_ID]`
    - If tool succeeds, proceed to Finalize
 
 2. Fallback: Manual Collation
@@ -61,9 +60,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Rebuild the architecture context pack so orchestrators have a fresh summary
      after any KB updates (architecture docs may have changed during the sprint):
      ```
-     FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
-     ENGINEERING=$(node "$FORGE_ROOT/tools/manage-config.cjs" get paths.engineering 2>/dev/null || echo engineering)
-     node "$FORGE_ROOT/tools/build-context-pack.cjs" \
+     ENGINEERING=$(node .forge/tools/manage-config.cjs get paths.engineering 2>/dev/null || echo engineering)
+     node .forge/tools/build-context-pack.cjs \
        --arch-dir "$ENGINEERING/architecture" \
        --out-md .forge/cache/context-pack.md \
        --out-json .forge/cache/context-pack.json
@@ -72,7 +70,7 @@ 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:
+   - Write `WRITEBACK-SUMMARY.json` to the sprint's artifact directory — use the sprint record's `path` field (read it from the store), not a reconstructed `engineering/sprints/{sprintId}/` template — with the following shape:
      ```json
      {
        "objective":   "<one sentence — what views were regenerated>",
@@ -101,5 +99,5 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      (Claude Code only); on any other runtime treat as unavailable and proceed.
      Do NOT shell out to a `cost-cli.cjs` — there is no such tool.
   2. Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
-  3. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+  3. Write the usage sidecar via `node .forge/tools/store-cli.cjs emit {sprintId} '{sidecar-json}' --sidecar`.
 - **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -31,7 +31,7 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 - 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.
 - 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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Store-Write Verification
 
@@ -42,9 +42,8 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 ```
 
 0a. Pre-flight Gate Check:
-   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase commit --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase commit --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -53,7 +52,7 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
    - If `--force` is present in the invocation arguments, skip this step entirely.
    - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
    - Read current task state:
-     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+     `node .forge/tools/store-cli.cjs read task {record_id} --json`
    - Extract the `status` field from the JSON output.
    - Allowed states for this phase: `approved`.
    - If the current status is NOT in the allowed set:
@@ -62,9 +61,8 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 1. Load Context:
    - Read the record manifest (task or bug, per entity_kind).
-   - Read ARCHITECT_APPROVAL.md from the record's artifact directory:
-     - Task mode: `engineering/sprints/{sprint}/{task}/ARCHITECT_APPROVAL.md`
-     - Bug mode:  `engineering/bugs/{bugDir}/ARCHITECT_APPROVAL.md`
+   - Read ARCHITECT_APPROVAL.md by kind — never construct the path:
+     `forge_artifact({ command:"read", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval" })`
 
 2. Staging:
    - Stage all record-related artifacts and the code changes:
@@ -80,8 +78,8 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 4. Store Finalization:
    - Transitions:
-     - **Task mode** — `approved → committed` (terminal): `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status committed`
-     - **Bug mode** — `in-progress → fixed` (terminal): `node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug {bugId} status fixed`. This is the ONLY phase in the bug pipeline that writes `bug.status` post-triage (see `meta-fix-bug.md § Iron Laws #2`). Do NOT write `approved` or `verified` — those values are vestigial enum members slated for removal.
+     - **Task mode** — `approved → committed` (terminal): `node .forge/tools/store-cli.cjs update-status task {taskId} status committed`
+     - **Bug mode** — `in-progress → fixed` (terminal): `node .forge/tools/store-cli.cjs update-status bug {bugId} status fixed`. This is the ONLY phase in the bug pipeline that writes `bug.status` post-triage (see `meta-fix-bug.md § Iron Laws #2`). Do NOT write `approved` or `verified` — those values are vestigial enum members slated for removal.
 
 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.

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

@@ -10,7 +10,7 @@ deps:
   templates: []
   sub_workflows: []
   kb_docs: []
-  config_fields: [paths.engineering, paths.forgeRoot]
+  config_fields: [paths.engineering]
 ---
 
 # Meta-Workflow: Enhancement Agent
@@ -20,7 +20,7 @@ deps:
 
 - 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 (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.
+- All store I/O via `forge_store` (or `node .forge/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
@@ -140,7 +140,7 @@ Invoked by T09 post-init hook (`--auto`) or manually via `/forge:rebuild --enric
 
 2. **Skip runtime passthrough keys** — keys used at runtime (e.g., `{{TASK_ID}}`, `{{SPRINT_ID}}`,
    `{{ARGUMENTS}}`) are intentional and must not be substituted. Read
-   `$FORGE_ROOT/tools/substitute-placeholders.cjs` to identify the RUNTIME_PASSTHROUGH_KEYS list.
+   `.forge/tools/substitute-placeholders.cjs` to identify the RUNTIME_PASSTHROUGH_KEYS list.
    Exclude them from the fill candidates.
 
 3. **Derive values from codebase signals** — for each remaining `{{KEY}}`, attempt to derive a
@@ -172,7 +172,7 @@ Invoked by T09 post-init hook (`--auto`) or manually via `/forge:rebuild --enric
 
 6. **Snapshot gate** — if at least one fill was applied:
    ```sh
-   node "$FORGE_ROOT/tools/manage-versions.cjs" add-snapshot \
+   node .forge/tools/manage-versions.cjs add-snapshot \
      --source post-init \
      --enhanced-elements "<comma-separated list of relative .forge/ paths that were modified>"
    ```
@@ -180,7 +180,7 @@ Invoked by T09 post-init hook (`--auto`) or manually via `/forge:rebuild --enric
 
 7. **Emit enhancement event** to the store:
    ```sh
-   node "$FORGE_ROOT/tools/store-cli.cjs" emit enhancement '{
+   node .forge/tools/store-cli.cjs emit enhancement '{
      "eventId": "<ISO timestamp slug>_enhance_phase1",
      "taskId": "enhancement",
      "sprintId": "enhancement",

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

@@ -138,7 +138,13 @@ Differences are confined to the **triage** step and the **path branch**.
 
 ```
 1. Pre-loop setup (mirrors meta-orchestrate.md):
-   - Resolve FORGE_ROOT.
+   - Session Preflight (see `meta-orchestrate.md § Session Preflight`):
+     Read `.forge/cache/preflight-status.json` if present and fresh; otherwise
+     run `node .forge/tools/forge-preflight.cjs --bug {bugId}` and read
+     its stdout. Use `blob.forgeRoot` as FORGE_ROOT for the remainder of the
+     run — do not re-derive it. Branch on `blob.ok`: ok:true → proceed;
+     ok:false → halt (fast-fail-safe), emit escalation event, instruct operator
+     to fix the surfaced preflight warning before re-running.
    - Detect execution cluster from ANTHROPIC_DEFAULT_*_MODEL env vars.
    - Clear progress log: store-cli progress-clear bugs
    - Read bug record. If status ∈ {blocked, escalated, fixed, abandoned}:
@@ -159,6 +165,12 @@ Differences are confined to the **triage** step and the **path branch**.
    - On return, orchestrator transitions status:
        store-cli update-status bug {bugId} status triaged
        store-cli update-status bug {bugId} status in-progress
+     # Digest-compliance note (FORGE-S27-T05): update-status is already silent on
+     # success (no stdout on the success path). The two-step triaged→in-progress
+     # transition is a required state-machine contract per Iron Law 2 — only triage
+     # and commit own bug.status writes. Collapsing these two writes into one would
+     # be a behavioral violation. This is not LLM-hand-run glue; it executes as a
+     # direct tool call after the triage subagent returns.
    - Read summaries.triage.route. If neither "A" nor "B": escalate
      (verdict_malformed). Do not guess.
 
@@ -171,12 +183,22 @@ Differences are confined to the **triage** step and the **path branch**.
      - Resolve model (cluster + ROLE_TIER).
      - Compute eventId, agent_name, banner_name (from PERSONA_MAP /
        BANNER_MAP below).
-     - Announce phase: banner + "→ {bugId}  [{display_model}]".
+     - Announce phase:
+       run_bash(f'node .forge/tools/banners.cjs --badge {banner_name} --quiet')
+       # Digest-compliance note (FORGE-S27-T05): --quiet makes banners.cjs emit
+       # zero stdout (unconditional; no isTTY branch). The badge is fully
+       # suppressed during the automated run_bash call — it does not enter the
+       # LLM context window. Mirrors meta-orchestrate.md:399–411 treatment.
+       print(f"  → {bugId}  [{display_model}]\n")
      - Start progress Monitor on .forge/store/events/bugs/progress.log.
      - Preflight gate: preflight-gate.cjs --phase {role} --bug {bugId}
-       Exit 1 or 2 → escalate (see meta-orchestrate.md § Escalation Procedure)
-       with bug_id substituted for task_id. Update bug.status to "escalated"
-       only if it is currently "in-progress" (do not downgrade other states).
+       Exit 1 → structured JSON on stdout ({ phase, reasonCode, detail, remediation });
+       parse and render it exactly as meta-orchestrate.md § Execution Algorithm
+       does for tasks (safe_parse_json(stdout) → format reason + remediation).
+       Exit 2 → escalate (misconfiguration). In both cases:
+       see meta-orchestrate.md § Escalation Procedure with bug_id substituted
+       for task_id. Update bug.status to "escalated" only if it is currently
+       "in-progress" (do not downgrade other states).
      - Compose role-block, architecture-block, summary-block, overlay (via
        build-overlay.cjs --bug {bugId}).
      - Spawn subagent via Agent tool. Subagent prompt passes:
@@ -209,10 +231,12 @@ Differences are confined to the **triage** step and the **path branch**.
      phase that writes bug.status post-triage.
 
 6. Finalize (collator, housekeeping):
-   - Aggregate cost data from .forge/store/events/bugs/*.json filtered by
-     this bugId, and append a "## Cost Summary" section to the bug's
-     INDEX.md artifact.
-   - Run `node "$FORGE_ROOT/tools/collate.cjs" {bugId} --purge-events`.
+   - Run `node .forge/tools/collate.cjs {bugId} --purge-events`.
+     # Note (FORGE-S27-T05): collate.cjs --purge-events already handles cost
+     # aggregation and embeds the "## Cost" section into the bug's INDEX.md
+     # automatically (see collate.cjs buildBugIndex). Do NOT attempt a separate
+     # cost-aggregation round-trip before calling collate — it is redundant and
+     # may produce a duplicate section. The collate call is the single step.
      Collate purges only this bug's events from the shared bugs/ dir
      (filtered by bugId reference) — it does NOT purge other bugs' events.
    - Run preflight finalize gate: preflight-gate.cjs --phase finalize --bug {bugId}.
@@ -282,7 +306,7 @@ differences are:
 ```
 # --- Materialize project overlay (replaces MASTER_INDEX.md read in subagent) ---
 overlay_result = run_bash(
-  f'node "$FORGE_ROOT/tools/build-overlay.cjs" --bug {bug_id} --format md'
+  f'node .forge/tools/build-overlay.cjs --bug {bug_id} --format md'
 )
 bug_overlay_md = overlay_result.stdout if overlay_result.exit_code == 0 else ""
 
@@ -461,7 +485,7 @@ or is redundant with another skill — emit a `friction` event so
 | `skill_stale`      | A skill's guidance contradicts current architecture / supersedes its own advice. |
 | `skill_redundant`  | Two skills provided overlapping or conflicting guidance for the same decision.   |
 
-**Recording friction (subagent side):** call `node "$FORGE_ROOT/tools/friction-emit.cjs` `--workflow {workflow} --persona {persona-noun} --issue {token} [--subkind {token}] [--evidence '{...}']`. The tool appends one judgement-only record to `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains the file at phase-end, stamps runtime attribution (model, provider, usage, wall times, eventId) onto each record, and emits the events via `store-cli emit` as event type `"friction"`. The schema enforces `{workflow, persona, issue}` as required when `type === "friction"`; `subkind` is the frozen enum `skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant` or experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal — do not coalesce.
+**Recording friction (subagent side):** call `node .forge/tools/friction-emit.cjs` `--workflow {workflow} --persona {persona-noun} --issue {token} [--subkind {token}] [--evidence '{...}']`. The tool appends one judgement-only record to `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains the file at phase-end, stamps runtime attribution (model, provider, usage, wall times, eventId) onto each record, and emits the events via `store-cli emit` as event type `"friction"`. The schema enforces `{workflow, persona, issue}` as required when `type === "friction"`; `subkind` is the frozen enum `skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant` or experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal — do not coalesce.
 
 ## Progress Reporting
 

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

@@ -31,9 +31,8 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
 ```
 
 0a. Pre-flight Gate Check:
-   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase implement --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase implement --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -42,7 +41,7 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
    - If `--force` is present in the invocation arguments, skip this step entirely.
    - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
    - Read current task state:
-     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+     `node .forge/tools/store-cli.cjs read task {record_id} --json`
    - Extract the `status` field from the JSON output.
    - Allowed states for this phase: `plan-approved`.
    - If the current status is NOT in the allowed set:
@@ -83,10 +82,10 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
        - Out-of-band escapes (any state): `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`
        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`
+         `node .forge/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`
+         `node .forge/tools/store-cli.cjs update-status task {taskId} status implementing`
+         `node .forge/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.
 
@@ -96,9 +95,19 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
      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"] })`
+     `forge_store({ command:"set-summary", args:["{taskId}", "implementation"] })`
      Or (bug mode):
-     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation", "engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json"] })`
+     `forge_store({ command:"set-bug-summary", args:["{bugId}", "implementation"] })`
+     The sidecar path is auto-resolved from the record's `path` — never pass it.
+
+8. Post-Phase Output Guard: the `outputs` block below is the authoritative enforcer.
+   You MUST satisfy it before returning. If PROGRESS.md is missing or too small,
+   re-run the relevant step before emitting the complete event.
+```
+
+```outputs phase=implement
+artifact {engineering}/{sprint}/{task}/PROGRESS.md min=200
+require summaries.implementation.verdict == n/a
 ```
 
 <!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
@@ -106,7 +115,7 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
 
 - 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 (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.
+- All store I/O via `forge_store` (or `node .forge/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

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

@@ -35,15 +35,18 @@ or when `.forge/structure-versions.json` is absent (pre-T05 install detected).
 
 - 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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Pre-conditions
 
 - `/forge:init` has run: `.forge/config.json` exists and is readable.
 - `.forge/structure-versions.json` is absent OR `--structural` was passed.
-- The Forge plugin root is resolvable:
+- The Forge plugin root is resolvable. Migration reads plugin source
+  (`$FORGE_ROOT/init/base-pack`, `$FORGE_ROOT/.claude-plugin/plugin.json`)
+  that is not vendored into `.forge/`, so resolve the active plugin install
+  root from `CLAUDE_PLUGIN_ROOT` (this workflow runs plugin-side):
   ```sh
-  export FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
+  export FORGE_ROOT="${CLAUDE_PLUGIN_ROOT}"
   ```
 
 ---
@@ -58,7 +61,7 @@ Check that `.forge/config.json` exists. If it does not, stop:
 
 > "Forge has not been initialised in this project. Run `/forge:init` first."
 
-Read `FORGE_ROOT` from `.forge/config.json`.
+Resolve `FORGE_ROOT` from `${CLAUDE_PLUGIN_ROOT}` (the active plugin install root).
 
 **0b. Detect install generation.**
 
@@ -273,8 +276,7 @@ Write `.forge/project-context.json` with the synthesised content.
 
 Validate via the store tool:
 ```sh
-export FORGE_ROOT
-node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+node .forge/tools/validate-store.cjs --dry-run
 ```
 
 If this exits non-zero, report the validation errors to the user and HALT. Do
@@ -284,7 +286,7 @@ NOT remove the sentinel — the user can fix the issue and re-run.
 
 ```sh
 export FORGE_ROOT
-node "$FORGE_ROOT/tools/substitute-placeholders.cjs" \
+node .forge/tools/substitute-placeholders.cjs \
   --forge-root "$FORGE_ROOT" \
   --base-pack  "$FORGE_ROOT/init/base-pack" \
   --config     ".forge/config.json" \
@@ -302,8 +304,7 @@ user. Do NOT remove the sentinel (preserves ability to re-run after fixing).
 #### Step 3d — Register snapshot (T05)
 
 ```sh
-export FORGE_ROOT
-node "$FORGE_ROOT/tools/manage-versions.cjs" init
+node .forge/tools/manage-versions.cjs init
 ```
 
 `manage-versions init` is idempotent. Since `.forge/structure-versions.json`
@@ -347,9 +348,8 @@ rm .forge/archive/pre-migration/.migration-in-progress
 **Verification (CLI-accessible only — do NOT invoke `/forge:health` here):**
 
 ```sh
-export FORGE_ROOT
 # 1. Validate the store
-node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+node .forge/tools/validate-store.cjs --dry-run
 
 # 2. Verify substitution outputs are non-empty
 ls .forge/personas/*.md .forge/skills/*.md .forge/workflows/*.md .forge/templates/*.md
@@ -375,9 +375,8 @@ Read that file and extract the `sprintId` field. If no sprint files exist, use
 `"migration"` as the `sprintId` placeholder.
 
 ```sh
-export FORGE_ROOT
 MIGRATION_END=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-node "$FORGE_ROOT/tools/store-cli.cjs" emit "{projectSprintId}" '{
+node .forge/tools/store-cli.cjs emit "{projectSprintId}" '{
   "eventId": "migration-'"$(date -u +%Y%m%dT%H%M%SZ)"'",
   "taskId": "migration",
   "sprintId": "{projectSprintId}",
@@ -467,7 +466,7 @@ cd .forge && md5sum -c archive/pre-migration/MANIFEST.md5 2>/dev/null | grep -v
 - **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.
+  - Reference the project's `paths.engineering` from `.forge/config.json` for path resolutions; resolve the plugin root from `${CLAUDE_PLUGIN_ROOT}` (not `config.paths.forgeRoot`, which is retired).
   - 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-new-sprint.md

@@ -23,7 +23,7 @@ Capture sprint requirements via a structured interview and document them for pla
 
 - 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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Algorithm
 
@@ -56,7 +56,7 @@ Capture sprint requirements via a structured interview and document them for pla
    - Ensure all deliverables are measurable and testable
 
 5. Finalize:
-   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status planning`
+   - Update sprint status via `node .forge/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.
 ```
 
@@ -79,6 +79,6 @@ Capture sprint requirements via a structured interview and document them for pla
      - Set token fields to `null`: `"inputTokens": null, "outputTokens": null, "estimatedCostUSD": null`.
      - Add `"source": "missing"` to sidecar JSON.
      - Log: "Token data unavailable (cost probe failed). Backfill later via estimate-usage.cjs."
-  4. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+  4. Write the usage sidecar via `node .forge/tools/store-cli.cjs emit {sprintId} '{sidecar-json}' --sidecar`.
   5. **NEVER skip sidecar write.** Always emit (reported or placeholder with nulls).
 - **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.