@entelligentsia/forgecli 1.0.3 → 1.0.14

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,40 +637,50 @@ 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
 
-    # --- Review phase: detect verdict via parse-verdict.cjs (see Verdict Detection below) ---
-    # The CLI returns exit 0/1/2 for approved/revision/unknown. Never pattern-match
-    # the **Verdict:** line manually — the closed vocabulary lives in the tool.
+    # --- Review phase: detect verdict via read-verdict.cjs (see Verdict Detection below) ---
+    # Verdicts come from the STORE record (phase summaries / task.status), NOT from a
+    # markdown review artifact — the orchestrator never constructs an artifact path.
+    # 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/parse-verdict.cjs" {review_artifact_path(phase, task)}'
+      f'node .forge/tools/read-verdict.cjs --phase {phase.role} --task {task_id}'
     )
-    if verdict_result.exit_code == 0:
+    verdict_token = verdict_result.stdout.strip()
+    if verdict_token == "approved":
       verdict = "Approved"
-    elif verdict_result.exit_code == 1:
+    elif verdict_token == "revision":
       verdict = "Revision Required"
     else:
-      # exit 2: malformed, missing verdict line, or missing artifact. Never guess.
+      # "n/a" / "unknown" (no verdict recorded) or exit 2 (record not found / bad args).
+      # Never guess.
       print(f"  ⚠ {task_id}  {phase.role}  — verdict_malformed, escalating\n")
       emit_event(task, phase, action="verdict_malformed",
-                 notes=f"parse-verdict exit={verdict_result.exit_code}")
+                 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: review artifact missing or verdict line unparseable")
-      print(f"  ⚠ Task {task_id} escalated: verdict_malformed — review artifact missing or verdict line unparseable\n")
-      print(f"  Review artifact: {review_artifact_path(phase, task)}\n")
+                 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/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
 
@@ -604,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"  Review artifact: {review_artifact_path(phase, task)}\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
@@ -617,11 +703,14 @@ 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
 
-    # No `else:` branch needed — parse-verdict.cjs already exhausts the
+    # No `else:` branch needed — read-verdict.cjs already exhausts the
     # possibilities (approved | revision | verdict_malformed), and the
     # malformed case is handled above before this if/elif chain.
 ```
@@ -681,45 +770,34 @@ Examples:
 ## Verdict Detection
 
 After each review phase completes, the orchestrator MUST read the verdict
-before branching. Do not infer the verdict from conversation context alone —
-always read the artifact.
-
-| Phase role    | Artifact to read                                                          | Verdict field                |
-|---------------|---------------------------------------------------------------------------|------------------------------|
-| `review-plan` | `{engineering}/sprints/{sprintDir}/{taskDir}/PLAN_REVIEW.md`              | Line matching `**Verdict:**` |
-| `review-code` | `{engineering}/sprints/{sprintDir}/{taskDir}/CODE_REVIEW.md`              | Line matching `**Verdict:**` |
-| `validate`    | `{engineering}/sprints/{sprintDir}/{taskDir}/VALIDATION_REPORT.md`        | Line matching `**Verdict:**` |
+before branching. Do not infer the verdict from conversation context alone, and
+**never construct or read a markdown artifact path** to find it — the verdict
+lives in the **store record** (the phase summary written by `set-summary`, or
+`task.status` for the approve phase).
 
-The verdict line format is:
+**Read the verdict via `read-verdict.cjs`** — addressed by entity ID and phase
+role, never by file path. The tool sources the verdict from the record and
+enforces a closed vocabulary so typos, case drift, and reviewer prose cannot
+cause silent misclassification:
 
 ```
-**Verdict:** Approved
-```
-or
-```
-**Verdict:** Revision Required
+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)
+# exit 2 → record not found / invalid args (treat as malformed)
 ```
 
-**Parse the verdict via `parse-verdict.cjs`** — do NOT pattern-match the
-line manually. The tool enforces a closed verdict vocabulary so typos, case
-drift, and reviewer prose cannot cause silent misclassification:
+Branch on the **stdout token** (exit 1 bundles both `revision` and the
+no-verdict cases, so the token is authoritative). Recognised verdict values:
 
-```
-FORGE_ROOT = resolve_forge_root()
-result = run_bash(f'node "$FORGE_ROOT/tools/parse-verdict.cjs" {artifact_path}')
-# exit 0 → approved   (stdout "approved")
-# exit 1 → revision   (stdout "revision")
-# exit 2 → unknown/malformed/missing (stdout "unknown")
-```
-
-Recognised values (case-insensitive):
-
-- **approved** — `Approved`, `Approve`, `[Approved]`
-- **revision** — `Revision Required`, `Revision`, `Needs Revision`, `Changes Requested`
+- **approved** — written as `verdict: "approved"` in the phase summary (or `task.status == approved` for the approve phase).
+- **revision** — `verdict: "revision"`.
 
-Anything else — including free-form prose, missing bold markers, a missing
-verdict line, or a missing artifact — yields exit 2. Do NOT treat unknown
-as approved or revision; halt the loop and escalate via `verdict_malformed`.
+Anything else — `n/a`, `unknown`, a missing summary, or a missing record —
+must NOT be treated as approved or revision; halt the loop and escalate via
+`verdict_malformed`. (In bug mode pass `--bug {bug_id}`; `read-verdict.cjs`
+applies the bug-specific phase→summary map.)
 
 ## Escalation Procedure
 
@@ -730,7 +808,7 @@ as approved or revision; halt the loop and escalate via `verdict_malformed`.
 
 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:
    ```
@@ -755,8 +833,8 @@ Grammar (one directive per line):
   `in [v1, v2, ...]`. Fields are dotted paths against the store record, e.g.
   `task.status`.
 - `forbid <field> <op> <value>` — predicate must NOT hold.
-- `after <phase> = <approved|revision>` — predecessor phase's review artifact
-  must carry the stated verdict (parsed by `parse-verdict.cjs`).
+- `after <phase> = <approved|revision>` — predecessor phase's stored verdict
+  must match (read from the record by `read-verdict.cjs`, not from markdown).
 
 ```gates phase=plan
 forbid task.status == committed
@@ -854,7 +932,7 @@ is a violation of the Iron Laws.
 - Subagent empty/crash/timeout response: retry once with simplified prompt
   (strip summary and architecture blocks). Escalate on second failure.
   See Subagent Response Validation in the Execution Algorithm.
-- Subagent non-zero exit code (not parse-verdict): same as above — retry
+- Subagent non-zero exit code (not read-verdict): same as above — retry
   once, escalate on second failure. The crash reason is captured in the
   escalation event notes.
 - Verdict malformed or missing: escalate to human immediately. Never guess.
@@ -886,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
@@ -910,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).
@@ -938,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,
@@ -958,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
 
@@ -984,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.