@entelligentsia/forgecli 1.0.3 → 1.0.14

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

@@ -18,7 +18,7 @@ deps:
 
 - 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
@@ -41,8 +41,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
@@ -56,9 +55,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
@@ -67,7 +65,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>",

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

@@ -26,7 +26,7 @@ deps:
 
 - 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
 
@@ -37,9 +37,8 @@ deps:
 ```
 
 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.
@@ -48,7 +47,7 @@ deps:
    - 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:
@@ -57,9 +56,8 @@ deps:
 
 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:
@@ -75,8 +73,8 @@ deps:
 
 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/.base-pack/workflows/enhance.md

@@ -10,7 +10,7 @@ deps:
   templates: []
   sub_workflows: []
   kb_docs: []
-  config_fields: [paths.engineering, paths.forgeRoot]
+  config_fields: [paths.engineering]
 ---
 
 
@@ -21,7 +21,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
@@ -129,7 +129,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
@@ -161,7 +161,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>"
    ```
@@ -169,7 +169,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/.base-pack/workflows/implement_plan.md

@@ -27,9 +27,8 @@ deps:
 ```
 
 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.
@@ -38,7 +37,7 @@ deps:
    - 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:
@@ -79,10 +78,10 @@ deps:
        - 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.
 
@@ -92,9 +91,10 @@ deps:
      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.
 ```
 
 <!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
@@ -102,7 +102,7 @@ deps:
 
 - 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/.base-pack/workflows/migrate_structural.md

@@ -19,15 +19,18 @@ deps:
 
 - 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}"
   ```
 
 ---
@@ -42,7 +45,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.**
 
@@ -257,8 +260,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
@@ -268,7 +270,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" \
@@ -286,8 +288,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`
@@ -331,9 +332,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
@@ -359,9 +359,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}",

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

@@ -27,9 +27,8 @@ deps:
 ```
 
 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 plan --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase plan --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -38,7 +37,7 @@ deps:
    - 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: `draft`, `planned`, `plan-revision-required`.
    - If the current status is NOT in the allowed set:
@@ -51,7 +50,7 @@ deps:
    - Read task prompt (source of truth)
    - Query the store for this task and any related entities:
      ```sh
-     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "{taskId} with sprint with feature"
+     node .forge/tools/store-cli.cjs nlp "{taskId} with sprint with feature"
      ```
      Use store results directly if they include title, status, sprint, and excerpt.
    - Read the architecture summary from your injected context (if present).
@@ -82,7 +81,7 @@ deps:
 5. Finalize:
    - Transitions:
      - **Task mode** — legal target from this step: `draft → planned`. Out-of-band escapes (any state): `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`.
-       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
+       Update status: `node .forge/tools/store-cli.cjs update-status task {taskId} status planned`
      - **Bug mode** — NO status write. The bug remains `in-progress` until the commit phase transitions it to `fixed`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
@@ -113,7 +112,7 @@ deps:
 
 - 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 (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
 

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

@@ -26,7 +26,7 @@ deps:
 
 - Evaluate the code against the approved PLAN.md and the original task prompt. Do not accept "it works" as a substitute for "it is correct and maintainable."
 - Read `.forge/personas/supervisor.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
-- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Store-Write Verification
 
@@ -37,9 +37,8 @@ deps:
 ```
 
 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 review-code --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase review-code --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -48,7 +47,7 @@ deps:
    - 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: `implemented`, `implementing`.
    - If the current status is NOT in the allowed set:
@@ -98,7 +97,7 @@ deps:
 
 6. Finalize:
    - Transitions:
-     - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `... status code-revision-required` (if Revision Required).
+     - **Task mode** — Update status: `node .forge/tools/store-cli.cjs update-status task {taskId} status review-approved` (if Approved) or `... status code-revision-required` (if Revision Required).
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.code_review.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
@@ -116,10 +115,11 @@ deps:
      }
      ```
    - Call (task mode):
-     `forge_store({ command:"set-summary", entity:"task", id:"{taskId}", phase:"code_review" })`
+     `forge_store({ command:"set-summary", args:["{taskId}", "code_review"] })`
      Or (bug mode):
-     `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.
+     `forge_store({ command:"set-bug-summary", args:["{bugId}", "code_review"] })`
+     `args[1]` is the LITERAL phase key `code_review`, never the record id; `forge_store` has no `entity`/`id`/`phase` field (see `_fragments/store-cli-verbs.md`).
+   - If set-summary exits non-zero, `args[1]` was wrong — fix it to `code_review` and retry. Do not return without a valid summary; the orchestrator halts as "verdict missing" if `summaries.code_review` is absent.
 ```
 
 <!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -28,7 +28,7 @@ deps:
 
 - Evaluate the plan against what the task actually requires, not against what the plan claims to deliver. Plans routinely understate complexity, omit edge cases, or skip security steps. Your job is adversarial review, not approval.
 - Read `.forge/personas/supervisor.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
-- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Store-Write Verification
 
@@ -39,9 +39,8 @@ deps:
 ```
 
 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 review-plan --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase review-plan --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -50,7 +49,7 @@ deps:
    - 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: `planned`.
    - If the current status is NOT in the allowed set:
@@ -97,7 +96,7 @@ deps:
        - Approved          → `plan-approved`
        - Revision Required → `plan-revision-required`
        - Out-of-band escapes (any state): `code-revision-required`, `blocked`, `escalated`, `abandoned`
-       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status plan-approved` (if Approved) or `... status plan-revision-required` (if Revision Required)
+       Update status: `node .forge/tools/store-cli.cjs update-status task {taskId} status plan-approved` (if Approved) or `... status plan-revision-required` (if Revision Required)
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.review_plan.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
@@ -115,13 +114,14 @@ deps:
      ```
    - Call (task mode):
      ```
-     forge_store({ command:"set-summary", entity:"task", id:"{record_id}", phase:"review_plan" })
+     forge_store({ command:"set-summary", args:["{record_id}", "review_plan"] })
      ```
      Or (bug mode):
      ```
-     forge_store({ command:"set-bug-summary", entity:"bug", id:"{record_id}", phase:"review_plan" })
+     forge_store({ command:"set-bug-summary", args:["{record_id}", "review_plan"] })
      ```
-   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     `args[1]` is the LITERAL phase key `review_plan`, never the record id; `forge_store` has no `entity`/`id`/`phase` field (see `_fragments/store-cli-verbs.md`).
+   - If set-summary exits non-zero (guard: `expected summary key 'review_plan'`), `args[1]` was wrong — fix it to `review_plan` and retry. Do not return without a valid summary; the orchestrator halts as "verdict missing" if `summaries.review_plan` is absent.
 ```
 
 <!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -18,7 +18,7 @@ deps:
 
 - 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.
+- All store I/O via `forge_store` (or `node .forge/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
 
 ## Algorithm
 
@@ -40,8 +40,8 @@ deps:
 
 4. Finalize:
    - Write SPRINT_RETROSPECTIVE.md
-   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status retrospective-done`
-   - Run `node "$FORGE_ROOT/tools/collate.cjs" {sprintId} --purge-events`
+   - Update sprint status via `node .forge/tools/store-cli.cjs update-status sprint {sprintId} status retrospective-done`
+   - Run `node .forge/tools/collate.cjs {sprintId} --purge-events`
      This single deterministic step: generates COST_REPORT.md from all
      accumulated events, then deletes `.forge/store/events/{sprintId}/`.
      COST_REPORT.md is the durable record; the raw event files are not

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

@@ -28,7 +28,7 @@ deps:
   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.
@@ -51,8 +51,7 @@ deps:
 ```
 
 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.
@@ -61,7 +60,7 @@ deps:
    - 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` |
@@ -129,13 +128,17 @@ deps:
 
    - 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/.base-pack/workflows/update_implementation.md

@@ -26,7 +26,7 @@ deps:
 
 - Address every "Revision Required" item from the review artifact at the correct code location; do not paper over them with comments. If a finding is wrong, escalate rather than ignore.
 - 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
 
@@ -50,7 +50,7 @@ deps:
    - Update PROGRESS.md with a summary of the revisions
 
 4. Finalize:
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
+   - Update task status via `node .forge/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.
 ```
 

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

@@ -26,7 +26,7 @@ deps:
 
 - Address every numbered finding in the review artifact. Do not silently drop items; if a finding is wrong, note the reason in the revised plan rather than ignoring it.
 - 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
 
@@ -50,7 +50,7 @@ deps:
    - Update the "Operational Impact" or "Testing Strategy" if the revision changed them
 
 4. Finalize:
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
+   - Update task status via `node .forge/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.
 ```
 

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

@@ -26,7 +26,7 @@ deps:
 
 - Validate against the acceptance criteria as written; do not soften, expand, or reinterpret them. The validator's job is to catch what the implementer optimistically considered "done".
 - Read `.forge/personas/qa-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
 
@@ -37,9 +37,8 @@ deps:
 ```
 
 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 validate --{entity_kind} {record_id}`
+   - Run: `node .forge/tools/preflight-gate.cjs --phase validate --{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.
@@ -48,7 +47,7 @@ deps:
    - 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: `implemented`, `review-approved`.
    - If the current status is NOT in the allowed set:
@@ -94,7 +93,7 @@ deps:
      - See step 1 for iteration header and final-iteration Next Steps requirements.
 
 5. Finalize:
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status code-revision-required` (if Revision Required)
+   - Update task status via `node .forge/tools/store-cli.cjs update-status task {taskId} status review-approved` (if Approved) or `node .forge/tools/store-cli.cjs update-status task {taskId} status code-revision-required` (if Revision Required)
    - **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:
@@ -110,10 +109,9 @@ deps:
        "artifact_ref":"VALIDATION_REPORT.md"
      }
      ```
-   - Call:
+   - Call (the sidecar path is auto-resolved from the task record's `path` — never pass it):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} validation \
-       engineering/sprints/{sprint}/{task}/VALIDATION-SUMMARY.json
+     node .forge/tools/store-cli.cjs set-summary {task_id} validation
      ```
    - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```