@entelligentsia/forgecli 1.0.3 → 1.0.14

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

@@ -1,934 +0,0 @@
----
-requirements:
-  reasoning: High
-  context: High
-  speed: Medium
-audience: orchestrator-only
-deps:
-  personas: [architect, engineer, supervisor, bug-fixer, collator, qa-engineer]
-  skills: [architect, engineer, supervisor, generic]
-  templates: []
-  sub_workflows: [plan_task, implement_plan, review_plan, review_code, fix_bug, architect_approve, commit_task, validate_task]
-  kb_docs: [architecture/stack.md]
-  context_pack: .forge/cache/context-pack.md
-  config_fields: [paths.engineering]
----
-
-
-# Orchestrate Task
-## Pipeline Phases
-
-Each phase has:
-- `name` — identifier
-- `agent` — which role executes
-- `workflow` — which workflow file to load
-- `requires` — prerequisite artifact
-- `produces` — output artifact
-- `max_iterations` — revision loop limit (for review phases)
-- `gate_checks` — conditions that must pass before proceeding
-
-## Model Resolution
-
-Detect cluster from env vars at session start, then dispatch accordingly:
-
-| Env var | Purpose |
-|---------|---------|
-| `ANTHROPIC_DEFAULT_OPUS_MODEL` | What "opus" resolves to |
-| `ANTHROPIC_DEFAULT_SONNET_MODEL` | What "sonnet" resolves to |
-| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | What "haiku" resolves to |
-
-- **Single cluster** — all three vars equal (or unset): omit `model` on Agent spawns; subagents inherit the parent.
-- **Tiered cluster** — vars differ: pass `model=tier` (opus/sonnet/haiku) based on ROLE_TIER mapping.
-- **Unknown cluster** — no `ANTHROPIC_DEFAULT_*` vars: pass the canonical model ID from ROLE_TIER_DEFAULTS.
-- **Per-phase override** — `model` field in `config.pipelines` phase takes highest precedence.
-
-### Role-to-Tier Mapping
-
-| Role | Tier |
-|------|------|
-| `review-plan`, `review-code`, `validate`, `approve` | opus |
-| `plan`, `implement` | sonnet |
-| `commit`, `writeback` | haiku |
-
-Unknown cluster canonical defaults: opus → `claude-opus-4-5`, sonnet → `claude-sonnet-4-6`, haiku → `claude-haiku-4-5`.
-
-Phase announcement format: `→ TASK-ID  [tier → resolved-model]` (e.g. `→ SPECT-T01  [opus → claude-opus-4-6]`).
-On single cluster, show the model directly. On unknown, show `tier → canonical`.
-
-## Pipeline Resolution
-
-The orchestrator supports pluggable pipelines. When starting a task:
-
-1. Read the task manifest from `.forge/store/tasks/{TASK_ID}.json`.
-2. If `task.pipeline` is set, look up that key in `.forge/config.json` → `pipelines`.
-3. If found, use the phases defined in that pipeline.
-4. If `task.pipeline` is not set or the key is not found, use the `default` pipeline
-   (either from `config.pipelines.default` or the hardcoded default below).
-
-Each phase in a pipeline has:
-- `command` — the slash command to invoke (passed the task ID as argument)
-- `role` — semantic role (`plan`, `review-plan`, `implement`, `review-code`, `approve`, `commit`)
-- `maxIterations` — for review roles, the revision loop limit (default 3)
-- `on_revision` — (optional) command name of the phase to re-invoke on "Revision Required";
-  if absent, defaults to the nearest preceding phase whose role is not a review role
-
-## Default Pipeline
-
-```
-plan → review-plan → [loop max 3] → implement → review-code → [loop max 3] → validate → [loop max 3] → approve → writeback → commit
-```
-
-When no `pipelines` section exists in config, the orchestrator uses this
-hardcoded default. Projects that define `config.pipelines.default` override it.
-
-## Context Isolation
-
-**Each phase MUST run as a subagent (Agent tool call), NOT inline.**
-
-Invoking phases inline accumulates context from every prior phase and task into
-the orchestrator's window. This violates Forge's design principle of keeping
-context light and nimble. By the time a sprint reaches its third or fourth task,
-an inline orchestrator is carrying tens of thousands of tokens of prior work that
-is irrelevant to the current phase.
-
-The fix: use the Agent tool to spawn a subagent per phase. Each subagent:
-- Starts with a fresh context window
-- Receives only what it needs: the workflow file path and the task ID
-- Receives a PROJECT_OVERLAY (task-scoped index slice) instead of reading MASTER_INDEX.md directly
-- Writes results to disk (artifacts, task status updates)
-- Returns to the orchestrator, which then reads the verdict from disk
-
-The orchestrator itself stays minimal — it only holds the phase loop and event log.
-
-## Token Self-Reporting
-
-Each phase subagent is responsible for reporting its own token usage via a sidecar file.
-
-**Before returning, every subagent MUST:**
-
-1. Probe token usage for the session: invoke `/cost` if the host runtime
-   supports it (Claude Code only); on any other runtime treat as unavailable.
-   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:
-   ```json
-   {
-     "inputTokens": <integer>,
-     "outputTokens": <integer>,
-     "cacheReadTokens": <integer>,
-     "cacheWriteTokens": <integer>,
-     "estimatedCostUSD": <number>
-   }
-   ```
-
-The `eventId` is computed by the orchestrator before spawning and passed in the subagent prompt —
-it follows the format `{ISO_TIMESTAMP}_{TASK_ID}_{role}_{action}` (e.g.
-`20260415T141523000Z_ACME-S02-T03_engineer_implement`).
-
-The leading underscore on the sidecar filename marks it as ephemeral — `validate-store.cjs` skips
-files prefixed with `_`, so the sidecar will never be treated as a real event record. If `/cost` is
-unavailable or token data cannot be parsed, skip writing the sidecar silently — the orchestrator
-handles missing sidecars gracefully (see Execution Algorithm below).
-
-## Role-to-Noun Mapping
-
-The orchestrator resolves persona and skill file lookups using **noun-based**
-filenames, not role-literal filenames. A role like `plan` maps to the noun
-`engineer`, so the persona file is `engineer.md`, not `plan.md`.
-
-```
-ROLE_TO_NOUN = {
-  "plan":        "engineer",
-  "implement":   "engineer",
-  "update-plan": "engineer",
-  "update-impl": "engineer",
-  "commit":      "engineer",
-  "review-plan": "supervisor",
-  "review-code": "supervisor",
-  "validate":    "qa-engineer",
-  "approve":     "architect",
-  "writeback":   "collator",
-}
-```
-
-The `.get(key, fallback)` pattern preserves the old role-literal behaviour for
-any role not yet in the table, which is a safe degradation path for custom
-pipeline roles.
-
-## Persona Injection Modes
-
-Subagent prompts include a **role block** that tells the agent who it is
-and what capabilities it has. Two modes are supported, selected by the
-`FORGE_PROMPT_MODE` environment variable:
-
-| Mode | Behaviour | Default |
-|------|-----------|---------|
-| `reference` | Compact summary from `.forge/cache/persona-pack.json`, plus a file_ref pointer to the full persona/skill definitions. | ✅ |
-| `inline` | Legacy: inject the full verbatim persona and skill file contents. Kept for one version as a rollback path. | |
-
-The pack is built by `/forge:rebuild` via
-`forge/tools/build-persona-pack.cjs`. It compiles YAML frontmatter from
-`$FORGE_ROOT/meta/personas/meta-*.md` and `$FORGE_ROOT/meta/skills/meta-*.md`
-into `.forge/cache/persona-pack.json`.
-
-### Helper: `compose_role_block(persona_noun)`
-
-```
-def compose_role_block(persona_noun):
-    mode = os.environ.get("FORGE_PROMPT_MODE", "reference")
-
-    if mode == "inline":
-        # Legacy behaviour — full persona + skill prose inline.
-        persona_content = read_file(f".forge/personas/{persona_noun}.md")
-        skill_content   = read_file(f".forge/skills/{persona_noun}-skills.md")
-        return f"{persona_content}\n\n{skill_content}"
-
-    # Reference mode (default) — compact summary from the pack.
-    pack = read_json(".forge/cache/persona-pack.json")
-    persona = pack["personas"].get(persona_noun)
-    skill   = pack["skills"].get(f"{persona_noun}-skills")
-
-    if not persona:
-        # Fail loud rather than silently degrade. Missing pack entry is a
-        # regeneration bug and should be reported via /forge:report-bug.
-        raise OrchestratorError(
-            f"persona '{persona_noun}' not in persona-pack. "
-            "Run /forge:rebuild to rebuild the pack."
-        )
-
-    lines = [
-        f"You are acting as the {persona['role']}.",
-        "",
-        f"Persona: {persona['id']} — {persona['summary']}",
-        "",
-        "Your responsibilities:",
-    ]
-    for r in persona.get("responsibilities", []):
-        lines.append(f"- {r}")
-    if persona.get("outputs"):
-        lines.append("")
-        lines.append(f"Your outputs: {', '.join(persona['outputs'])}")
-
-    if skill:
-        lines.append("")
-        lines.append("Skill capabilities you have available:")
-        for c in skill.get("capabilities", []):
-            lines.append(f"- {c}")
-
-    lines.append("")
-    lines.append(
-        f"Full persona definition: {persona['file_ref']}. "
-        + (f"Full skill definition: {skill['file_ref']}. " if skill else "")
-        + "The summary above is authoritative. If insufficient, escalate — "
-        + "do not read the full persona or skill file."
-    )
-    return "\n".join(lines)
-```
-
-**Rollback:** set `FORGE_PROMPT_MODE=inline`. No persisted state to revert.
-The `inline` branch will be removed one version after `reference` ships.
-
-## Execution Algorithm
-
-The orchestrator MUST follow this procedure exactly. Do not deviate.
-
-```
-# --- Persona symbol lookup (emoji, name, tagline) ---
-PERSONA_MAP = {
-  "plan":        ("🌱", "Engineer",    "I plan what will be built before any code is written."),
-  "implement":   ("🌱", "Engineer",    "I build what was planned. I do not move forward until the code is clean."),
-  "update-plan": ("🌱", "Engineer",    "I address what the Supervisor found. No more, no less."),
-  "update-impl": ("🌱", "Engineer",    "I address what the Supervisor found. No more, no less."),
-  "commit":      ("🌱", "Engineer",    "I close out completed work with a clean, honest commit."),
-  "review-plan": ("🌿", "Supervisor",  "I review before things move forward. I read the actual task prompt, not just the plan."),
-  "review-code": ("🌿", "Supervisor",  "I review before things move forward. I read the actual code, not the report."),
-  "validate":    ("🍵", "QA Engineer", "I validate against what was promised. The code compiling is not enough."),
-  "approve":     ("🗻", "Architect",   "I hold the shape of the whole. I give final sign-off before commit."),
-  "writeback":   ("🍃", "Collator",    "I gather what exists and arrange it into views."),
-}
-
-# --- Banner identity map (banner name per phase role) ---
-# Maps each role to a banner in forge/tools/banners.cjs.
-# Displayed by the orchestrator ONLY (badge before spawn, exit signal after return).
-# Subagents do NOT display banners — the orchestrator owns phase announcements.
-BANNER_MAP = {
-  "plan":        "forge",
-  "implement":   "forge",
-  "update-plan": "forge",
-  "update-impl": "forge",
-  "commit":      "forge",
-  "review-plan": "oracle",
-  "review-code": "oracle",
-  "validate":    "lumen",
-  "approve":     "north",
-  "writeback":   "drift",
-}
-
-for each task in dependency_sorted(tasks):
-  # --- Pre-task status guard ---
-  # If a task is already blocked or escalated from a prior sprint/run,
-  # skip it entirely rather than attempting any phase.
-  task_record = read_json(f".forge/store/tasks/{task.taskId}.json")
-  if task_record and task_record.get("status") in ("blocked", "escalated"):
-    print(f"  ⚠ {task.taskId}  — status is {task_record['status']}, skipping\n")
-    emit_event(task, phase=None, action="task_skipped",
-               notes=f"task status is {task_record['status']}")
-    continue
-
-  phases = resolve_pipeline(task)           # from config.pipelines or default
-  iteration_counts = {}                     # keyed by phase command name
-  retry_count = {}                           # keyed by phase command name (subagent retry tracking)
-  i = 0
-
-  # --- Detect execution cluster from env vars (see Model Resolution) ---
-  opus_model   = env("ANTHROPIC_DEFAULT_OPUS_MODEL", "")
-  sonnet_model = env("ANTHROPIC_DEFAULT_SONNET_MODEL", "")
-  haiku_model  = env("ANTHROPIC_DEFAULT_HAIKU_MODEL", "")
-  if opus_model and opus_model == sonnet_model == haiku_model:
-    cluster = "single"
-    resolved_model = opus_model   # all tiers same model
-  elif opus_model:
-    cluster = "tiered"
-    resolved_model = None         # each tier resolves differently
-  else:
-    cluster = "unknown"
-    resolved_model = env("CLAUDE_CODE_SUBAGENT_MODEL", "unknown")
-
-  # --- Role-to-tier mapping for tiered cluster dispatch ---
-  ROLE_TIER = {
-    "review-plan": "opus",
-    "review-code": "opus",
-    "validate":    "opus",
-    "approve":     "opus",
-    "plan":        "sonnet",
-    "implement":   "sonnet",
-    "commit":      "haiku",
-    "writeback":   "haiku",
-  }
-
-  # --- 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}')
-
-  while i < len(phases):
-    phase = phases[i]
-
-    # --- Resolve model for display and dispatch (see Model Resolution) ---
-    if phase.model:                                   # per-phase override from config
-      display_model = phase.model
-      dispatch_model = phase.model                   # pass override to Agent tool
-      if env(f"ANTHROPIC_DEFAULT_{phase.model.upper()}_MODEL"):
-        resolved = env(f"ANTHROPIC_DEFAULT_{phase.model.upper()}_MODEL")
-        display_model = f"{phase.model} → {resolved}"
-    elif cluster == "single" and resolved_model:
-      display_model = resolved_model
-      dispatch_model = None                           # inherit parent model
-    elif cluster == "tiered":
-      tier = ROLE_TIER.get(phase.role, "sonnet")
-      resolved = env(f"ANTHROPIC_DEFAULT_{tier.upper()}_MODEL", tier)
-      display_model = f"{tier} → {resolved}" if resolved != tier else tier
-      dispatch_model = tier                           # pass tier name, Claude Code resolves
-    else:
-      # Unknown cluster: no ANTHROPIC_DEFAULT_*_MODEL vars set.
-      # Fall back to ROLE_TIER with canonical model defaults so subagents
-      # run on a predictable model instead of inheriting the orchestrator's own.
-      ROLE_TIER_DEFAULTS = {
-        "opus":   "claude-opus-4-5",
-        "sonnet": "claude-sonnet-4-6",
-        "haiku":  "claude-haiku-4-5",
-      }
-      tier = ROLE_TIER.get(phase.role, "sonnet")
-      canonical = ROLE_TIER_DEFAULTS[tier]
-      display_model = f"{tier} → {canonical}"
-      dispatch_model = canonical                      # pass full model id to Agent tool
-
-    # --- Compute eventId before spawning so the subagent can name its sidecar ---
-    start_ts = current_iso_timestamp()       # e.g. "20260415T141523000Z"
-    event_id = f"{start_ts}_{task_id}_{phase.role}_{phase.action}"
-    sidecar_path = f".forge/store/events/{sprint_id}/_{event_id}_usage.json"  # used by merge-sidecar
-
-    # --- Compute agent name for progress IPC ---
-    persona_noun = ROLE_TO_NOUN.get(phase.role, phase.role)
-    iteration = iteration_counts.get(phase.command, 0) + 1
-    agent_name = f"{task_id}:{persona_noun}:{phase.role}:{iteration}"
-
-    # --- Announce phase with identity banner (badge) + task context ---
-    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}')
-    print(f"  → {task_id}  [{display_model}]\n")
-
-    # --- Start progress Monitor before spawning subagent ---
-    # The Monitor streams lines from the progress log as the subagent works.
-    # New lines arrive as notifications while the Agent tool blocks on the subagent.
-    start_monitor(
-      command=f"tail -n +1 -F {progress_log_path} 2>/dev/null || true",
-      description=f"Progress: {agent_name}",
-      persistent=False
-    )
-
-    # --- Pre-flight gate check (see Phase Gates below) ---
-    # Resolve FORGE_ROOT once so the CLI shim can locate the gate parser.
-    FORGE_ROOT = resolve_forge_root()
-    preflight_result = run_bash(
-      f'node "$FORGE_ROOT/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)
-      # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-      run_bash(f'node "$FORGE_ROOT/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")
-      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
-    elif preflight_result.exit_code == 2:
-      # 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')
-      emit_event(task, phase, eventId=event_id, iteration=iteration,
-                 action="escalated", verdict="escalated",
-                 notes=f"gate_misconfigured: {preflight_result.stderr}")
-      print(f"  ⚠ Task {task_id} escalated: gate_misconfigured: {preflight_result.stderr}\n")
-      print(f"  Review artifact: {artifact_path}\n")
-      print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
-      break
-
-    # --- Invoke phase as subagent (fresh context per phase) ---
-    emit_event(task, phase, eventId=event_id, iteration=iteration, action="start")
-
-    # Symmetric Injection Assembly: Persona -> Skill -> Workflow
-    # Mode is governed by FORGE_PROMPT_MODE (default: "reference").
-    # See "Persona injection modes" below for the full helper definition.
-    role_block = compose_role_block(persona_noun)
-
-    # --- Compose prior-phase summary block (delta: last 3 phases only) ---
-    # <!-- See _fragments/context-injection.md for canonical definition -->
-    summary_block = compose_summary_block(task_id, record_type="task") if phase.context.prior_summaries != "none" else ""
-
-    # --- Compose architecture context block (conditional on phase.context.architecture) ---
-    # <!-- See _fragments/context-injection.md for canonical definition -->
-    architecture_block = (
-      compose_architecture_block(".forge/cache/context-pack.md", ".forge/cache/context-pack.json")
-      if phase.context.architecture else ""
-    )
-
-    # --- 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'
-    )
-    overlay_md = overlay_result.stdout if overlay_result.exit_code == 0 else ""
-
-    # --- Load finalize fragment (token reporting contract) ---
-    finalize_fragment = read_file(f"{FORGE_ROOT}/meta/workflows/_fragments/finalize.md") if file_exists(f"{FORGE_ROOT}/meta/workflows/_fragments/finalize.md") else ""
-
-    # --- Compose review loop context block (review-role phases only) ---
-    # Injected between summary_block and role_block so reviewers know their
-    # position in the revision loop at the moment they are spawned.
-    # `iteration` is the current attempt number (pre-spawn, not post-increment).
-    # `phase.maxIterations` is the configured limit (default 3).
-    if phase.role in ("review-plan", "review-code", "validate"):
-      review_loop_context = (
-        f"### Review Loop Context\n"
-        f"- Iteration: {iteration} of {phase.maxIterations}\n"
-        f"- Is final iteration: {iteration >= phase.maxIterations}\n\n"
-      )
-    else:
-      review_loop_context = ""
-
-    spawn_kwargs = dict(
-      prompt=(
-        f"Append progress entries to {progress_log_path} via store-cli "
-        f"(agent: {agent_name}, banner: {banner_name}) — see _fragments/progress-reporting.md.\n\n"
-        f"---\n\n"
-        f"{architecture_block}"
-        f"{summary_block}"
-        f"{review_loop_context}"
-        f"{role_block}\n\n"
-        f"### Project Context\n"
-        f"{overlay_md}\n\n"
-        f"### Current Working Context\n"
-        f"- Sprint Root: {sprint_root_path}\n"
-        f"- Task Root:   {task_root_path}\n"
-        f"- Store Root:  {store_root_path}\n\n"
-        f"Read `.forge/workflows/{phase.workflow}` and follow it. Task ID: {task_id}.\n\n"
-        f"{finalize_fragment}"
-      ),
-      description=f"{emoji} {persona_name} — {phase.name} for {task_id}",
-    )
-    if dispatch_model:
-      spawn_kwargs["model"] = dispatch_model
-    spawn_subagent(**spawn_kwargs)
-    # Subagent reads all context from disk, does its work, writes artifacts/status to disk, then exits.
-
-    # --- Stop progress Monitor ---
-    stop_monitor(progress_log_path)
-
-    # --- Subagent response validation (retry once, escalate on second failure) ---
-    # The subagent must produce a usable result. Three failure classes:
-    #   1. Empty response: subagent returned nothing or whitespace-only output
-    #   2. Subagent error: subagent exited non-zero (crash, OOM, tool error)
-    #   3. Timeout: subagent did not return within the session timeout
-    #
-    # On first failure: retry once with a simplified prompt that strips
-    # non-essential context (summary block, architecture block) and adds
-    # a direct instruction to produce a verdict or error report.
-    # On second failure: escalate to human — do NOT continue the phase loop.
-
-    if subagent_failed_or_empty(result):
-      if retry_count.get(phase.command, 0) == 0:
-        # First failure: retry with simplified prompt
-        retry_count[phase.command] = 1
-        print(f"  ⚠ {task_id}  {phase.role}  — subagent response empty or errored, retrying with simplified prompt\n")
-        emit_event(task, phase, action="subagent_retry",
-                   notes=f"first failure: {subagent_failure_reason(result)}")
-
-        # Simplify: remove summary_block and architecture_block from prompt
-        simplified_kwargs = dict(spawn_kwargs)
-        simplified_kwargs["prompt"] = (
-          f"### Progress Reporting\n"
-          f"- Agent name: {agent_name}\n"
-          f"- Progress log: {progress_log_path}\n"
-          f"- Banner key: {banner_name}\n\n"
-          f"Append progress entries as you work.\n\n"
-          f"---\n\n"
-          f"{review_loop_context}"
-          f"{role_block}\n\n"
-          f"### Current Working Context\n"
-          f"- Sprint Root: {sprint_root_path}\n"
-          f"- Task Root:   {task_root_path}\n"
-          f"- Store Root:  {store_root_path}\n\n"
-          f"Read `.forge/workflows/{phase.workflow}` and follow it. Task ID: {task_id}.\n\n"
-          f"{overlay_md}\n\n"
-          f"IMPORTANT: You MUST produce a result. If the workflow cannot complete, "
-          f"write a verdict or error report to the expected artifact path and return."
-        )
-        spawn_subagent(**simplified_kwargs)
-        stop_monitor(progress_log_path)
-
-        # Re-validate the retry result
-        if subagent_failed_or_empty(result):
-          # Second failure: escalate
-          print(f"  ✗ {task_id}  {phase.role}  — subagent failed after retry, escalating\n")
-          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')
-          emit_event(task, phase, eventId=event_id, iteration=iteration,
-                     action="escalated", verdict="escalated",
-                     notes=f"subagent failed after retry: {subagent_failure_reason(result)}")
-          print(f"  ⚠ Task {task_id} escalated: subagent {phase.role} failed after retry — {subagent_failure_reason(result)}\n")
-          print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
-          break
-      else:
-        # Already retried once — this is the second failure
-        print(f"  ✗ {task_id}  {phase.role}  — subagent failed after retry, escalating\n")
-        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')
-        emit_event(task, phase, eventId=event_id, iteration=iteration,
-                   action="escalated", verdict="escalated",
-                   notes=f"subagent failed after retry: {subagent_failure_reason(result)}")
-        print(f"  ⚠ Task {task_id} escalated: subagent {phase.role} failed after retry — {subagent_failure_reason(result)}\n")
-        print(f"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
-        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
-    # 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}
-    # 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")
-
-    # --- Phase-exit signal ---
-    # Non-review phases always advance with a completion signal
-    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
-      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.
-    verdict_result = run_bash(
-      f'node "$FORGE_ROOT/tools/parse-verdict.cjs" {review_artifact_path(phase, task)}'
-    )
-    if verdict_result.exit_code == 0:
-      verdict = "Approved"
-    elif verdict_result.exit_code == 1:
-      verdict = "Revision Required"
-    else:
-      # exit 2: malformed, missing verdict line, or missing artifact. 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}")
-      # ---- ESCALATION (mandatory hard stop — do NOT continue) ----
-      run_bash(f'node "$FORGE_ROOT/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")
-      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
-      print(f"[checkpoint] task={task_id} sprint={sprint_id} phase_index={i} iterations={iteration_counts}")
-      /compact
-
-    elif verdict == "Revision Required":
-      iteration_counts[phase.command] = iteration_counts.get(phase.command, 0) + 1
-      print(f"  ↻ {task_id}  {phase.role}  — Revision Required (iteration {iteration_counts[phase.command]})\n")
-
-      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')
-        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"  Resume with: /{phase.command} {task_id} after addressing the issues.\n")
-        break
-        break                               # stop processing this task
-
-      # 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
-      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
-    # possibilities (approved | revision | verdict_malformed), and the
-    # malformed case is handled above before this if/elif chain.
-```
-
-## Agent Naming Convention
-
-Each subagent is assigned a structured name at spawn time:
-
-```
-{taskId}:{persona_noun}:{phase.role}:{iteration}
-```
-
-| Component | Source | Example |
-|-----------|--------|---------|
-| `taskId` | Task ID from manifest | `FORGE-S09-T01` |
-| `persona_noun` | `ROLE_TO_NOUN` mapping | `engineer`, `supervisor`, `qa-engineer` |
-| `phase.role` | Pipeline phase role | `plan`, `review-plan`, `implement` |
-| `iteration` | 1-based revision count for this phase | `1`, `2`, `3` |
-
-Examples:
-
-- `FORGE-S09-T01:engineer:plan:1` — First plan attempt for T01
-- `FORGE-S09-T01:supervisor:review-plan:1` — First plan review for T01
-- `FORGE-S09-T01:engineer:update-impl:2` — Second implementation revision for T01
-
-The agent name is passed in the subagent prompt and used in every progress log
-entry the subagent writes. It provides identity and traceability for mid-task
-feedback.
-
-## Progress Reporting
-
-<!-- See _fragments/progress-reporting.md for canonical definition -->
-> See `_fragments/progress-reporting.md` for the full progress log format and `store-cli progress` command reference.
-
-Log path: `.forge/store/events/{sprintId}/progress.log`. Format: `{ISO_TIMESTAMP}|{agent_name}|{banner_key}|{status}|{detail}`. Clear at task start: `store-cli progress-clear {sprintId}`.
-
-## Phase-Exit Signals
-
-After each subagent returns, the orchestrator prints a phase-exit signal:
-
-| Outcome | Format |
-|---------|--------|
-| Non-review phase completed | `  ✓ {task_id}  {phase_role}  — completed` |
-| Review verdict: Approved | `  ✓ {task_id}  {phase_role}  — Approved` |
-| Review verdict: Revision Required | `  ↻ {task_id}  {phase_role}  — Revision Required (iteration {n})` |
-| Escalated | `  ⚠ {task_id}  {phase_role}  — escalated to human` |
-
-Examples:
-
-```
-  ✓ FORGE-S09-T01  plan  — completed
-  ✓ FORGE-S09-T01  review-plan  — Approved
-  ↻ FORGE-S09-T01  review-plan  — Revision Required (iteration 2)
-  ⚠ FORGE-S09-T01  validate  — escalated to human
-```
-
-## 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:**` |
-
-The verdict line format is:
-
-```
-**Verdict:** Approved
-```
-or
-```
-**Verdict:** Revision Required
-```
-
-**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:
-
-```
-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`
-
-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`.
-
-## Escalation Procedure
-
-> **NOTE:** The Escalation Procedure is inlined at every call site in the
-> Execution Algorithm. This section remains as a reference. When adding new
-> escalation points, inline the full procedure — do NOT call `escalate_to_human()`
-> as a bare function name.
-
-When escalating to the human:
-
-1. Update task status via `node "$FORGE_ROOT/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:
-   ```
-   ⚠ Task {TASK_ID} escalated: {reason}
-   Review artifact: {artifact_path}
-   Resume with: /{phase.command} {TASK_ID} after addressing the issues.
-   ```
-4. Stop processing this task. Continue to the next task in the sprint.
-
-## Phase Gates
-
-Declarative pre-flight gates for each phase. The orchestrator evaluates these
-via `forge/tools/preflight-gate.cjs` **before** every subagent spawn. A failing
-gate halts the loop for this task — no retry, no fall-through to the subagent,
-no silent recovery. Gates are data, not prose: the grammar is defined in
-`forge/tools/parse-gates.cjs` and validated by its test suite.
-
-Grammar (one directive per line):
-- `artifact <path> [min=<bytes>]` — file must exist and meet size floor. Path
-  templates: `{sprint}` → sprintId, `{task}` → task suffix, `{bug}` → bugId.
-- `require <field> <op> <value>` — predicate must hold. Ops: `==`, `!=`,
-  `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`).
-
-```gates phase=plan
-forbid task.status == committed
-forbid task.status == abandoned
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=implement
-artifact {engineering}/sprints/{sprint}/{task}/PLAN.md min=200
-after review-plan = approved
-forbid task.status == committed
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=review-plan
-artifact {engineering}/sprints/{sprint}/{task}/PLAN.md min=200
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=review-code
-after review-plan = approved
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=validate
-after review-code = approved
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=approve
-after review-code = approved
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-```gates phase=commit
-after approve = approved
-forbid task.status == blocked
-forbid task.status == escalated
-```
-
-Adjusting a gate is a data change — edit the block above, regenerate workflows
-on the user side via `/forge:update`, and the new gate takes effect on the next
-orchestrator run. No code change required to relax or tighten a gate.
-
-## Write-Boundary Contract
-
-You MAY write Forge-owned JSON (`task.json`, `sprint.json`, `bug.json`,
-events sidecars, `COLLATION_STATE.json`, `progress.log`) directly with the
-`Write` or `Edit` tools. You do NOT need to route every write through
-`store-cli` — the probabilistic layer is free to bypass deterministic tools.
-
-However, **every write to a Forge-owned path is schema-validated at the
-filesystem boundary** by the `PreToolUse` hook at
-`hooks/validate-write.js`. A malformed write is rejected with a message
-naming the offending field and pointing at the relevant
-`forge/schemas/<kind>.schema.json`. Fix the data and retry — do NOT try to
-disable the hook.
-
-`store-cli` is still the most convenient path (it handles ID allocation,
-referential integrity, ghost-event semantics, and sidecar merging), but it
-is one route among several. The schema invariant is preserved whichever
-route you take.
-
-**Emergency bypass.** For operator-driven repair, set
-`FORGE_SKIP_WRITE_VALIDATION=1` for a single turn. The hook will let the
-write through and append an audit line to the affected sprint's
-`progress.log`.
-
-<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance (orchestrate uses orchestrator-special deferral to generic-skills.md § Orchestrator Iron Laws) -->
-## Iron Laws
-
-<!-- Shared orchestrator laws live in generic-skills.md § Orchestrator Iron Laws. -->
-> See `generic-skills.md § Orchestrator Iron Laws` for the six universal laws that apply to all orchestrators.
-
-**Additional law specific to this pipeline:**
-
-**YOU MUST NOT silently work around a blocker.** If a phase fails, a subagent
-returns empty, a gate fails, or a verdict cannot be parsed, the orchestrator
-MUST either retry once (for recoverable failures) or escalate to the human.
-Skipping the phase, fabricating a result, assuming success without evidence,
-or continuing with a degraded response is NEVER acceptable. Every failure MUST
-produce a visible signal (✗ or ⚠) and a structured event. Silent continuation
-is a violation of the Iron Laws.
-
-## Error Recovery
-
-- Test/build failure: pass error to Engineer revision workflow, retry once
-- Verdict "Revision Required": enter revision loop (up to max_iterations)
-- 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
-  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.
-- Revision loop exhaustion: escalate to human immediately. Never approve
-  to unblock.
-- Gate failure (preflight): escalate to human. No retry, no fall-through.
-- Gate misconfiguration: escalate to human. No retry, no fall-through.
-- Git hook failure: diagnose, fix, create new commit
-- Merge conflict: escalate to human
-- Task status is blocked or escalated: skip the task entirely. Do not
-  attempt any phase on it.
-
-## Event Emission
-
-<!-- See _fragments/event-emission-schema.md for canonical contract -->
-> See `_fragments/event-emission-schema.md` for the actor split (subagent
-> writes judgement-only SUMMARY; orchestrator composes the canonical event
-> from runtime telemetry + SUMMARY and emits it).
-
-The **orchestrator** is the only actor that calls `store-cli emit` for phase
-events. Phase subagents write `{PHASE}-SUMMARY.json` and return. After each
-subagent returns, the orchestrator:
-
-1. Captures the subagent's runtime attribution (`model`, `provider`, token
-   usage) from the runtime stream.
-2. Records bracketed wall times around the spawn call (`startTimestamp`,
-   `endTimestamp`, `durationMinutes`).
-3. Reads the SUMMARY for the judgement blob (`verdict`, `notes`, `findings`).
-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}'`
-   with the complete record.
-
-Do not include hardcoded example `model` or `provider` strings in the
-generated orchestrator prose — they are the seed of LLM hallucination.
-Refer subagents to `.forge/schemas/event.schema.json` instead.
-
-<!-- See _fragments/generation-instructions.md for Generation Instructions template (orchestrate uses orchestrator-special long-form prose — cannot be reduced to standard subsections) -->
-## Friction Emit
-
-When the Orchestrator detects skill friction during orchestrate-task — a referenced skill is unused, fails on invocation, is missing from the registry, has gone stale relative to current architecture, or is redundant with another skill — emit a `friction` event so `/forge:rebuild --enrich` (phase 2) can act on the signal. This is the writer side of the channel whose reader landed in S13-T08; the reader is empty without these emits.
-
-**Trigger conditions** (set `issue` to the matching token):
-
-| Token              | When to emit                                                                     |
-|--------------------|----------------------------------------------------------------------------------|
-| `skill_unused`     | A skill listed in the persona's skill block was loaded but never consulted.      |
-| `skill_failed`     | A skill was consulted but its guidance produced an error or required correction. |
-| `skill_missing`    | The workflow needed guidance the available skills did not cover.                 |
-| `skill_stale`      | A skill's guidance contradicts current architecture / supersedes its own advice. |
-| `skill_redundant`  | Two skills provided overlapping or conflicting guidance for the same decision.   |
-
-**Two flavours of friction in orchestrate-task:**
-
-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}
-   --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
-   subagent's captured runtime attribution (model, provider, usage, wall
-   times, eventId) onto each record, and emits the resulting events via
-   `store-cli emit` as event type `"friction"`. The orchestrator truncates
-   the file only after all emits succeed.
-
-2. **Orchestrator-experienced friction** (spawn failure, sidecar missing,
-   FSM rejection, verdict malformed). The orchestrator emits inline using
-   its own model/provider attribution (`persona: "orchestrator"`,
-   `workflow: "orchestrate"`, `phase: "orchestrate"`). Same `store-cli emit`
-   path; no example record is reproduced here because the orchestrator
-   owns the field values — consult `.forge/schemas/event.schema.json` for
-   the required shape.
-
-The schema enforces `{workflow, persona, issue}` as required when
-`type === "friction"`. `subkind` is the frozen enum
-`skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant` or
-experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal
-— do not coalesce.
-
-The generated `orchestrate_task.md` MUST carry this section verbatim —
-`/forge:rebuild --enrich` (phase 2) greps for it.