@entelligentsia/forgecli 1.0.10 → 1.0.20

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

@@ -21,6 +21,38 @@ deps:
 Wire the atomic workflows into a pipeline that drives a single task through
 the complete lifecycle. This is the task state machine.
 
+## Session Preflight (run once, before the phase loop)
+
+The deterministic pre-dispatch glue — FORGE_ROOT resolution, config
+reconciliation, generation-manifest state, calibration-baseline freshness,
+MASTER_INDEX hashing, and the structure check — is bundled into a single
+deterministic tool, `forge/tools/forge-preflight.cjs`. **Do NOT hand-run these
+checks turn-by-turn.** Read the one compact blob it produces, once, at the top
+of the orchestration:
+
+1. The SessionStart hook (`hooks/preflight-session.cjs`) primes the blob at
+   `.forge/cache/preflight-status.json` for any project that has a `.forge/`
+   directory. Read that file. If it is absent or stale, run the tool once:
+   `node .forge/tools/forge-preflight.cjs` and read its stdout.
+2. Branch on `blob.ok`:
+   - **`ok: true`** → proceed to the phase loop using `blob.forgeRoot` and the
+     recorded state. Do not re-derive any field the blob already carries
+     (`masterIndexHash`, `calibrationFresh`, `manifestState`, `structureOk`);
+     surface `calibrationFresh.suggest` to the operator if `fresh` is false, but
+     this is advisory and does not block the run.
+   - **`ok: false`** → **halt before phase 1** (fast-fail-safe). This is a
+     pre-dispatch halt: print `blob.warnings`, route through the existing
+     escalation idiom (see `§ Escalation Procedure`) — emit the standard
+     escalation event and message — and instruct the operator to fix the
+     surfaced preflight warning and re-run. A half-initialized run must never
+     proceed.
+
+The blob is the single source of truth for these concerns for the remainder of
+the run. The SessionStart hook is command-name-independent (SessionStart fires
+before any command and carries no per-command signal); the scoping to
+run-task / fix-bug / run-sprint contexts lives here, in the orchestration
+preamble, which only those commands reach.
+
 ## Pipeline Phases
 
 Each phase has:
@@ -116,7 +148,7 @@ Each phase subagent is responsible for reporting its own token usage via a sidec
    Do NOT shell out to a `cost-cli.cjs` — there is no such tool.
 2. Parse the output for the five fields:
    `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
-3. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar` with the exact format:
+3. Write the usage sidecar via `node .forge/tools/store-cli.cjs emit {sprintId} '{sidecar-json}' --sidecar` with the exact format:
    ```json
    {
      "inputTokens": <integer>,
@@ -234,11 +266,26 @@ def compose_role_block(persona_noun):
 **Rollback:** set `FORGE_PROMPT_MODE=inline`. No persisted state to revert.
 The `inline` branch will be removed one version after `reference` ships.
 
+> **Scope note (added FORGE-S27-T02, 2026-05-31):** `FORGE_PROMPT_MODE=inline` restores
+> the **role block only** — full verbatim persona + skill file contents. It does NOT restore
+> the full `MASTER_INDEX`: the overlay (`build-overlay.cjs`, line 462) is unconditional and
+> delivers the same task-scoped slice in both modes. It also does NOT affect the workflow file,
+> which is read verbatim from disk in both modes. There is currently no per-call escape hatch
+> to the full `MASTER_INDEX` — a separate overlay-bypass flag would be required.
+
 ## Execution Algorithm
 
 The orchestrator MUST follow this procedure exactly. Do not deviate.
 
 ```
+# --- Utility helpers ---
+def safe_parse_json(text):
+    """Attempt to parse a JSON string; return dict or None on failure."""
+    try:
+        return json.loads(text.strip()) if text and text.strip() else None
+    except Exception:
+        return None
+
 # --- Persona symbol lookup (emoji, name, tagline) ---
 PERSONA_MAP = {
   "plan":        ("🌱", "Engineer",    "I plan what will be built before any code is written."),
@@ -314,7 +361,7 @@ for each task in dependency_sorted(tasks):
 
   # --- Clear progress log for this sprint ---
   progress_log_path = f".forge/store/events/{sprint_id}/progress.log"
-  run_bash(f'FORGE_ROOT=$(node -e "console.log(require(\'./.forge/config.json\').paths.forgeRoot)") && node "$FORGE_ROOT/tools/store-cli.cjs" progress-clear {sprint_id}')
+  run_bash(f'node .forge/tools/store-cli.cjs progress-clear {sprint_id}')
 
   while i < len(phases):
     phase = phases[i]
@@ -359,9 +406,27 @@ for each task in dependency_sorted(tasks):
     agent_name = f"{task_id}:{persona_noun}:{phase.role}:{iteration}"
 
     # --- Announce phase with identity banner (badge) + task context ---
+    # --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 and is not shown on the human terminal.
+    # The human-visible per-phase marker is the print() line below.
+    #
+    # Digest-compliance note (FORGE-S27-T03): every deterministic tool call this
+    # loop body makes is already digest-compliant on its success path:
+    #   store-cli write verbs (update-status, emit, merge-sidecar, set-summary,
+    #   progress-clear) → silent on success.
+    #   preflight-gate.cjs → silent on success (stderr only on failure).
+    #   read-verdict.cjs   → one load-bearing token (e.g. "approved"); orchestrator
+    #                        branches on it — must not be suppressed.
+    #   banners.cjs --badge → 1-line ANSI badge; made zero-cost via --quiet below.
+    #   build-overlay.cjs  → ~1185 chars captured into overlay_md and injected into
+    #                        the subagent prompt as Project Context. This is payload
+    #                        data, not a log — reducing it would break prompt assembly.
+    #                        Reference-mode redesign is deferred to the T02/forge-compress
+    #                        work; leave unchanged here.
     emoji, persona_name, tagline = PERSONA_MAP.get(phase.role, ("🌊", "Orchestrator", "I move tasks through their lifecycle."))
     banner_name = BANNER_MAP.get(phase.role, "forge")
-    run_bash(f'FORGE_ROOT=$(node -e "console.log(require(\'./.forge/config.json\').paths.forgeRoot)") && node "$FORGE_ROOT/tools/banners.cjs" --badge {banner_name}')
+    run_bash(f'node .forge/tools/banners.cjs --badge {banner_name} --quiet')
     print(f"  → {task_id}  [{display_model}]\n")
 
     # --- Start progress Monitor before spawning subagent ---
@@ -374,23 +439,35 @@ for each task in dependency_sorted(tasks):
     )
 
     # --- Pre-flight gate check (see Phase Gates below) ---
-    # Resolve FORGE_ROOT once so the CLI shim can locate the gate parser.
+    # Resolve FORGE_ROOT once (needed for meta/workflows fragment reads below).
     FORGE_ROOT = resolve_forge_root()
     preflight_result = run_bash(
-      f'node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase {phase.role} --task {task_id}'
+      f'node .forge/tools/preflight-gate.cjs --phase {phase.role} --task {task_id}'
     )
     if preflight_result.exit_code == 1:
       # Gate failed: halt the orchestrator loop for THIS task. Do not retry,
-      # do not spawn. Missing prerequisites are listed on stderr.
-      print(f"  ✗ {task_id}  {phase.role}  — gate failed\n{preflight_result.stderr}")
-      append_progress(progress_log_path, f"❌ Gate failed for {phase.role}: {preflight_result.stderr}")
-      emit_event(task, phase, action="gate_failed", notes=preflight_result.stderr)
+      # do not spawn. Structured failure JSON is on stdout; human-readable detail on stderr.
+      # Parse the structured JSON for a user-friendly advisory.
+      gate_failure = safe_parse_json(preflight_result.stdout)
+      if gate_failure:
+        reason_code   = gate_failure.get("reasonCode", "unknown")
+        gate_detail   = gate_failure.get("detail", preflight_result.stderr.strip())
+        gate_remedy   = gate_failure.get("remediation", "")
+        print(f"  ✗ {task_id}  {phase.role}  — gate failed [{reason_code}]")
+        print(f"    Detail:      {gate_detail}")
+        print(f"    Remediation: {gate_remedy}")
+        gate_notes = f"gate_failed [{reason_code}]: {gate_detail}"
+      else:
+        print(f"  ✗ {task_id}  {phase.role}  — gate failed\n{preflight_result.stderr}")
+        gate_notes = f"gate_failed: {preflight_result.stderr}"
+      append_progress(progress_log_path, f"❌ Gate failed for {phase.role}: {gate_notes}")
+      emit_event(task, phase, action="gate_failed", notes=gate_notes)
       # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-      run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+      run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
       emit_event(task, phase, eventId=event_id, iteration=iteration,
                  action="escalated", verdict="escalated",
-                 notes=f"gate_failed: {preflight_result.stderr}")
-      print(f"  ⚠ Task {task_id} escalated: gate_failed: {preflight_result.stderr}\n")
+                 notes=gate_notes)
+      print(f"  ⚠ Task {task_id} escalated: {gate_notes}\n")
       print(f"  Review artifact: {artifact_path}\n")
       print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
       break                                   # stop processing this task
@@ -398,7 +475,7 @@ for each task in dependency_sorted(tasks):
       # Misconfiguration (unknown phase, malformed gates block). Fail loud.
       print(f"  ⚠ {task_id}  {phase.role}  — gate misconfigured\n{preflight_result.stderr}")
       # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-      run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+      run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
       emit_event(task, phase, eventId=event_id, iteration=iteration,
                  action="escalated", verdict="escalated",
                  notes=f"gate_misconfigured: {preflight_result.stderr}")
@@ -428,7 +505,7 @@ for each task in dependency_sorted(tasks):
 
     # --- Materialize project overlay (replaces MASTER_INDEX.md read in subagent) ---
     overlay_result = run_bash(
-      f'node "$FORGE_ROOT/tools/build-overlay.cjs" --task {task_id} --format md'
+      f'node .forge/tools/build-overlay.cjs --task {task_id} --format md'
     )
     overlay_md = overlay_result.stdout if overlay_result.exit_code == 0 else ""
 
@@ -526,7 +603,7 @@ for each task in dependency_sorted(tasks):
           emit_event(task, phase, action="subagent_escalated",
                      notes=f"second failure: {subagent_failure_reason(result)}")
           # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-          run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+          run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
           emit_event(task, phase, eventId=event_id, iteration=iteration,
                      action="escalated", verdict="escalated",
                      notes=f"subagent failed after retry: {subagent_failure_reason(result)}")
@@ -539,7 +616,7 @@ for each task in dependency_sorted(tasks):
         emit_event(task, phase, action="subagent_escalated",
                    notes=f"second failure: {subagent_failure_reason(result)}")
         # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-        run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+        run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
         emit_event(task, phase, eventId=event_id, iteration=iteration,
                    action="escalated", verdict="escalated",
                    notes=f"subagent failed after retry: {subagent_failure_reason(result)}")
@@ -548,10 +625,9 @@ for each task in dependency_sorted(tasks):
         break
 
     # --- Sidecar merge: merge token usage written by subagent via custodian ---
-    # The subagent wrote the sidecar via node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar
+    # The subagent wrote the sidecar via node .forge/tools/store-cli.cjs emit {sprintId} '{sidecar-json}' --sidecar
     # Merge the sidecar into the canonical event and delete the sidecar file
-    FORGE_ROOT = resolve_forge_root()
-    run: node "$FORGE_ROOT/tools/store-cli.cjs" merge-sidecar {sprint_id} {event_id}
+    run: node .forge/tools/store-cli.cjs merge-sidecar {sprint_id} {event_id}
     # merge-sidecar reads the sidecar, merges token fields into the canonical event, and deletes the sidecar
     # If the sidecar does not exist, merge-sidecar exits 1 — treat as non-fatal (subagent may have skipped it)
     emit_event(task, phase, action="complete")
@@ -561,7 +637,10 @@ for each task in dependency_sorted(tasks):
     if phase.role not in ("review-plan", "review-code", "validate"):
       print(f"  ✓ {task_id}  {phase.role}  — completed\n")
       i += 1
-      # Compact context: all state is on disk; preserve loop bookkeeping in the summary
+      # State-ledger compaction: the [checkpoint] line IS the state ledger — it carries
+      # the loop bookkeeping (task_id, sprint_id, phase_index, iteration_counts) that
+      # /compact must preserve verbatim. Raw tool output and subagent return text is
+      # shed here; do not retain it between phases. The durable state is on disk.
       print(f"[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}")
       /compact
       continue
@@ -572,7 +651,7 @@ for each task in dependency_sorted(tasks):
     # stdout is one of: approved | revision | n/a | unknown. Never pattern-match a
     # **Verdict:** line — the closed vocabulary lives in the tool.
     verdict_result = run_bash(
-      f'node "$FORGE_ROOT/tools/read-verdict.cjs" --phase {phase.role} --task {task_id}'
+      f'node .forge/tools/read-verdict.cjs --phase {phase.role} --task {task_id}'
     )
     verdict_token = verdict_result.stdout.strip()
     if verdict_token == "approved":
@@ -586,19 +665,22 @@ for each task in dependency_sorted(tasks):
       emit_event(task, phase, action="verdict_malformed",
                  notes=f"read-verdict stdout='{verdict_token}' exit={verdict_result.exit_code}")
       # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-      run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+      run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
       emit_event(task, phase, eventId=event_id, iteration=iteration,
                  action="escalated", verdict="escalated",
                  notes="verdict_malformed: no verdict recorded in the phase summary / record")
       print(f"  ⚠ Task {task_id} escalated: verdict_malformed — no verdict recorded for {phase.role}\n")
-      print(f"  Inspect with: node \"$FORGE_ROOT/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
+      print(f"  Inspect with: node \.forge/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
       print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
       break
 
     if verdict == "Approved":
       print(f"  ✓ {task_id}  {phase.role}  — Approved\n")
       i += 1                                # advance to next phase
-      # Compact context: all state is on disk; preserve loop bookkeeping in the summary
+      # State-ledger compaction: the [checkpoint] line IS the state ledger — it carries
+      # the loop bookkeeping (task_id, sprint_id, phase_index, iteration_counts) that
+      # /compact must preserve verbatim. Raw tool output and subagent return text is
+      # shed here; do not retain it between phases. The durable state is on disk.
       print(f"[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}")
       /compact
 
@@ -608,12 +690,12 @@ for each task in dependency_sorted(tasks):
 
       if iteration_counts[phase.command] >= phase.maxIterations: # default 3
         # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-        run_bash(f'node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {task_id} status escalated')
+        run_bash(f'node .forge/tools/store-cli.cjs update-status task {task_id} status escalated')
         emit_event(task, phase, eventId=event_id, iteration=iteration,
                    action="escalated", verdict="escalated",
                    notes="max iterations reached")
         print(f"  ⚠ Task {task_id} escalated: max iterations reached\n")
-        print(f"  Inspect with: node \"$FORGE_ROOT/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
+        print(f"  Inspect with: node \.forge/tools/read-verdict.cjs\" --phase {phase.role} --task {task_id}\n")
         print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
         break
         break                               # stop processing this task
@@ -621,7 +703,10 @@ for each task in dependency_sorted(tasks):
       # Route back to the revision target
       target = phase.on_revision or nearest_preceding_non_review(phases, i)
       i = index_of(phases, target)          # loop back
-      # Compact context: all state is on disk; preserve loop bookkeeping in the summary
+      # State-ledger compaction: the [checkpoint] line IS the state ledger — it carries
+      # the loop bookkeeping (task_id, sprint_id, phase_index, iteration_counts) that
+      # /compact must preserve verbatim. Raw tool output and subagent return text is
+      # shed here; do not retain it between phases. The durable state is on disk.
       print(f"[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}")
       /compact
 
@@ -696,8 +781,7 @@ enforces a closed vocabulary so typos, case drift, and reviewer prose cannot
 cause silent misclassification:
 
 ```
-FORGE_ROOT = resolve_forge_root()
-result = run_bash(f'node "$FORGE_ROOT/tools/read-verdict.cjs" --phase {phase.role} --task {task_id}')
+result = run_bash(f'node .forge/tools/read-verdict.cjs --phase {phase.role} --task {task_id}')
 # stdout "approved" → approved
 # stdout "revision" → revision
 # stdout "n/a" | "unknown" → no verdict recorded (treat as malformed; do NOT guess)
@@ -724,7 +808,7 @@ applies the bug-specific phase→summary map.)
 
 When escalating to the human:
 
-1. Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status escalated`
+1. Update task status via `node .forge/tools/store-cli.cjs update-status task {taskId} status escalated`
 2. Emit a final event with `verdict: "escalated"` and `notes` explaining the reason
 3. Output a clear message:
    ```
@@ -880,7 +964,7 @@ subagent returns, the orchestrator:
 4. Composes the canonical event with `eventId`, `taskId`, `sprintId`, `role`,
    `action`, `phase`, `iteration` from its own task state and `tokenSource:
    "reported"` when the runtime surfaced usage.
-5. Calls `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{event-json}'`
+5. Calls `node .forge/tools/store-cli.cjs emit {sprintId} '{event-json}'`
    with the complete record.
 
 Do not include hardcoded example `model` or `provider` strings in the
@@ -904,7 +988,7 @@ Refer subagents to `.forge/schemas/event.schema.json` instead.
   Do NOT generate a "Model Assignments" table — the Model Resolution section
   above is the single source of truth.
 - **Include the sidecar merge pattern.** After each subagent returns, run
-  `node "$FORGE_ROOT/tools/store-cli.cjs" merge-sidecar {sprintId} {eventId}` to merge token fields from the
+  `node .forge/tools/store-cli.cjs merge-sidecar {sprintId} {eventId}` to merge token fields from the
   sidecar into the canonical event and delete the sidecar. If the sidecar does not
   exist (merge-sidecar exits 1), treat as non-fatal and emit the event without token
   fields (graceful fallback — no error).
@@ -932,7 +1016,7 @@ Refer subagents to `.forge/schemas/event.schema.json` instead.
   subagents do not display banners. Instead, include progress reporting instructions
   in the subagent prompt with the agent name, progress log path, and banner key.
 - **Include the progress IPC pattern.** Each generated orchestrator MUST:
-  1. Clear the progress log at task start: `node "$FORGE_ROOT/tools/store-cli.cjs" progress-clear {sprintId}`
+  1. Clear the progress log at task start: `node .forge/tools/store-cli.cjs progress-clear {sprintId}`
   2. Compute the agent name before each spawn: `{taskId}:{persona_noun}:{phase.role}:{iteration}`
   3. Start a Monitor on the progress log before each subagent spawn
   4. Include progress reporting instructions in the subagent prompt (agent name,
@@ -952,13 +1036,28 @@ Refer subagents to `.forge/schemas/event.schema.json` instead.
   `Read engineering/architecture/stack.md` calls with a single cached summary.
   Subagents instructed by this block should read full docs **only** when the
   summary is insufficient.
-- **Include post-phase /compact calls.** After each phase-exit signal (for every
-  non-escalation outcome), the generated orchestrator MUST:
+- **Include post-phase /compact calls with state-ledger discipline.** After each
+  phase-exit signal (for every non-escalation outcome), the generated orchestrator
+  MUST:
   1. Print a checkpoint line: `[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}`
   2. Run `/compact` to free orchestrator context before the next phase.
-  All durable state is on disk; the checkpoint line ensures the compact summary
-  preserves the loop bookkeeping (task ID, sprint ID, current phase index,
-  iteration counts). Do NOT compact on escalation — the human needs full context.
+
+  The `[checkpoint]` line IS the state ledger. It carries the loop bookkeeping
+  (task ID, sprint ID, current phase index, iteration counts) that `/compact` must
+  preserve verbatim in its summary. It is not an optional debug breadcrumb — it is
+  the one line the orchestrator must carry forward through each compaction boundary.
+
+  Raw tool output (bash stdout, subagent return blobs, multi-KB phase responses)
+  is shed at every `/compact` call. The generated orchestrator MUST NOT retain
+  verbatim tool output or subagent return text between phases — only the
+  checkpoint ledger line and on-disk artifact pointers survive compaction.
+
+  The compact summary MUST contain: the checkpoint line verbatim, the task/sprint
+  IDs, and the current phase index. The compact summary MUST NOT contain: raw
+  subagent return text, bash stdout blobs, or multi-line phase responses.
+
+  Do NOT compact on escalation (verdict_malformed or max-iterations break paths) —
+  the human needs the full uncompacted context to diagnose and resume.
 
 ## Friction Emit
 
@@ -978,7 +1077,7 @@ When the Orchestrator detects skill friction during orchestrate-task — a refer
 
 1. **Subagent-experienced friction** (the persona running plan / implement /
    validate / etc. detects skill friction). The subagent records the signal
-   via `node "$FORGE_ROOT/tools/friction-emit.cjs" --workflow {wf} --persona {p}
+   via `node .forge/tools/friction-emit.cjs --workflow {wf} --persona {p}
    --issue {token} [--subkind {token}] [--evidence '{...}']`, which appends a
    judgement-only record to `.forge/cache/FRICTION-{wf}.jsonl`. After the
    subagent returns, the orchestrator drains this file, stamps the

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

@@ -31,8 +31,8 @@ Break sprint requirements into a set of estimated tasks with a dependency graph.
 1. Load Context:
    - Query the store to orient on current project state before reading docs:
      ```sh
-     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "latest sprint"
-     node "$FORGE_ROOT/tools/store-cli.cjs" nlp "open bugs"
+     node .forge/tools/store-cli.cjs nlp "latest sprint"
+     node .forge/tools/store-cli.cjs nlp "open bugs"
      ```
      Use results (titles, statuses, excerpts, file refs) to skip manual MASTER_INDEX.md navigation where sufficient.
    - Read SPRINT_REQUIREMENTS.md
@@ -52,11 +52,11 @@ Break sprint requirements into a set of estimated tasks with a dependency graph.
 
 4. Documentation:
    - Write SPRINT_PLAN.md to `engineering/sprints/{sprintId}/SPRINT_PLAN.md`
-   - Create each task via `node "$FORGE_ROOT/tools/store-cli.cjs" write task '{task-json}'`.
+   - Create each task via `node .forge/tools/store-cli.cjs write task '{task-json}'`.
      If the command exits non-zero or the PreToolUse hook blocks the write:
      parse the error, correct the JSON, and retry (see Store-Write Verification).
      Do not proceed to the next task until this write succeeds.
-   - Update the sprint record with all new task IDs via `node "$FORGE_ROOT/tools/store-cli.cjs" write sprint '{updated-sprint-json}'` (the sprint JSON must include the complete `taskIds` array with all newly created task IDs).
+   - Update the sprint record with all new task IDs via `node .forge/tools/store-cli.cjs write sprint '{updated-sprint-json}'` (the sprint JSON must include the complete `taskIds` array with all newly created task IDs).
      If the command exits non-zero or the PreToolUse hook blocks the write:
      parse the error, correct the JSON, and retry (see Store-Write Verification).
      Do not proceed until this write succeeds.
@@ -64,7 +64,7 @@ Break sprint requirements into a set of estimated tasks with a dependency graph.
      * Folder: `engineering/sprints/{sprintId}/{taskId}/`
      * File: `TASK_PROMPT.md` — populate from `.forge/templates/TASK_PROMPT_TEMPLATE.md`
        filling in title, objective, acceptance criteria, entities, DSL/CLI changes, and operational impact
-   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status active`.
+   - Update sprint status via `node .forge/tools/store-cli.cjs update-status sprint {sprintId} status active`.
      If the command exits non-zero, parse the error and retry
      (see Store-Write Verification). Do not proceed until this write succeeds.
 
@@ -141,7 +141,7 @@ environment variable is reserved for emergency operator repair only.
      - 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.
 - **Store-Write Verification:** The generated workflow MUST include the "Store-Write

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

@@ -31,9 +31,8 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
 ```
 
 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.
@@ -42,7 +41,7 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
    - 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:
@@ -55,7 +54,7 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
    - 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).
@@ -86,7 +85,7 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
 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.
 
@@ -110,6 +109,13 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
      Or (bug mode):
      `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.
+
+7. Post-Phase Output Guard: satisfy the `outputs` block before returning.
+```
+
+```outputs phase=plan
+artifact {engineering}/{sprint}/{task}/PLAN.md min=200
+require summaries.plan.verdict == n/a
 ```
 
 <!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
@@ -117,7 +123,7 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
 
 - 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/meta/workflows/meta-retro.md

@@ -23,7 +23,7 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
 
 - 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
 
@@ -45,8 +45,8 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
 
 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
@@ -69,5 +69,5 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
      (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-retrospective.md

@@ -23,7 +23,7 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
 
 - 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
 
@@ -45,8 +45,8 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
 
 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
@@ -69,5 +69,5 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
      (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-review-implementation.md

@@ -31,7 +31,7 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 - 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
 
@@ -42,9 +42,8 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 ```
 
 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.
@@ -53,7 +52,7 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
    - 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:
@@ -65,9 +64,10 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
    - If present, extract:
      - `Iteration: N of M` — current attempt number and the configured limit
      - `Is final iteration: true/false`
-   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
-     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
-   - Include `(iteration N of M)` in the opening line of the `CODE_REVIEW.md` artifact.
+   - If absent (user-invoked, not orchestrated): treat as `iteration 1`, no limit — do
+     NOT read any iteration cap from config. The orchestrator owns loop budgets; a human
+     standalone re-run is the escape hatch for stuck items (forge-engineering#34).
+   - Include `(iteration N of M)` (orchestrated) or `(standalone review)` in the opening line of the `CODE_REVIEW.md` artifact.
    - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
      append a `### Next Steps` section to the artifact showing:
      ```
@@ -103,7 +103,7 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 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.
 
@@ -121,10 +121,11 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
      }
      ```
    - 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 -->