@entelligentsia/forgecli 0.10.0 → 0.11.2

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

@@ -0,0 +1,501 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Medium
+audience: orchestrator-only
+deps:
+  personas: [bug-fixer, supervisor, architect, engineer, collator]
+  skills: [bug-fixer, supervisor, architect, engineer, generic]
+  templates: [PROGRESS_TEMPLATE]
+  sub_workflows: [plan_task, implement_plan, review_plan, review_code, architect_approve, commit_task]
+  kb_docs: [architecture/stack.md, architecture/routing.md]
+  context_pack: .forge/cache/context-pack.md
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🍂 Meta-Workflow: Fix Bug
+
+## Purpose
+
+Drive a single bug through its complete lifecycle. The pipeline mirrors
+`meta-orchestrate.md` so personas, phases, gates, and event emission stay
+identical — the only deviation is **the judgement step after triage**, which
+branches the bug into a short Path A or the full Path B. Everything past the
+branch reuses the run-task phases verbatim.
+
+## Pipeline Phases
+
+A fix-bug pipeline has these phases (mirrors `meta-orchestrate.md § Pipeline
+Phases`):
+
+| Phase | Role | Persona | Workflow | Path A | Path B |
+|---|---|---|---|---|---|
+| triage | `triage` | bug-fixer | (inline algorithm) | yes | yes |
+| plan-fix | `plan` | engineer | `plan_task.md` (bug-mode) | no | yes |
+| review-plan | `review-plan` | supervisor | `review_plan.md` | no | yes |
+| implement | `implement` | engineer | `implement_plan.md` (bug-mode) | yes | yes |
+| review-code | `review-code` | supervisor | `review_code.md` | yes | yes |
+| approve | `approve` | architect | `architect_approve.md` (bug-mode) | yes | yes |
+| commit | `commit` | engineer | `commit_task.md` (bug-mode) | yes | yes |
+| finalize | `finalize` | collator | (inline algorithm) | yes | yes |
+
+Phases past triage are the same workflows used by the run-task pipeline. The
+generated orchestrator passes `--bug {bugId}` (in place of `--task {taskId}`)
+to every sub-workflow and to `preflight-gate.cjs`. Sub-workflows resolve the
+record kind from the flag and adjust their verdict-source mapping via
+`BUG_PHASE_VERDICT_SOURCE` in `tools/read-verdict.cjs`.
+
+## Status State Machine
+
+Bug status writes are owned by specific phases — never by the workflow source
+in finalize, never by an LLM improvising on a task workflow.
+
+```
+reported -> triaged -> in-progress -> fixed
+                       (terminal)
+```
+
+| Transition | Owner | Trigger |
+|---|---|---|
+| `reported → triaged` | triage subagent | after reproduction confirmed |
+| `triaged → in-progress` | triage subagent | after route decision recorded in `summaries.triage.route` |
+| `in-progress → fixed` | commit phase | after git commit succeeds (terminal) |
+
+The schema's `approved` and `verified` enum members are vestigial — no phase in
+this workflow writes them, and the verdict gate reads
+`summaries.approve.verdict`, not `bug.status`. A follow-up cleanup should drop
+both members from `bug.schema.json` to remove the runtime trap. Until then,
+this workflow MUST NOT write either value. The Phase Gates below `forbid`
+them defensively.
+
+## Triage Judgement (the only run-task deviation)
+
+After the triage subagent reproduces the bug and confirms root cause, it MUST
+record a **route** decision in its summary:
+
+```json
+{
+  "objective": "Triage FORGE-BUG-NNN — reproduce, locate, decide route.",
+  "key_changes": [...],
+  "findings": [
+    "Root cause: <one line>",
+    "Reproduction: <one line>",
+    "Route decision: A | B",
+    "Rationale: <one line>"
+  ],
+  "verdict": "n/a",
+  "written_at": "<iso>",
+  "artifact_ref": "TRIAGE.md",
+  "route": "A"
+}
+```
+
+The `route` field is required. Allowed values: `"A"` or `"B"`.
+
+> **Field-naming caution — runtime-tested.** The route field is named
+> `route`, never `path`. The bug schema's top-level `path` field is the
+> bug's **artifact directory** (e.g. `engineering/bugs/EMG-BUG-001-...`).
+> Conflating the two caused EMBERGLOW-BUG-001 (v0.44.0 first run) to land
+> its `TRIAGE.md` under `.forge/store/bugs/` instead of `engineering/bugs/`.
+> Triage subagents MUST NOT touch `bug.path` — that field is set at bug
+> creation and never modified by triage.
+
+### Path A — short-circuit (eligibility)
+
+Path A is **eligible only when ALL** of the following hold. Triage subagent
+must enumerate each in its findings:
+
+- `bug.severity ∈ {minor}`
+- Fix is contained in a single file
+- Estimated diff ≤ ~20 lines (judgement call; one screen)
+- No schema, API, migration, security, or build-system change
+- A regression test is obvious from the reproduction script (single short
+  test case, no new fixtures, no test-harness change)
+
+If any criterion fails, the triage subagent MUST select Path B.
+
+### Path B — full loop (default)
+
+Path B runs the same plan/review/implement/review/approve/commit shape as
+`meta-orchestrate.md`. It is the default. Any uncertainty defaults Path B.
+
+### Pipeline selection by path
+
+```
+phases_A = [triage, implement, review-code, approve, commit, finalize]
+phases_B = [triage, plan-fix, review-plan, implement, review-code, approve, commit, finalize]
+
+if summaries.triage.route == "A": phases = phases_A
+else:                            phases = phases_B
+```
+
+The orchestrator MUST read `summaries.triage.route` from the bug record after
+the triage subagent returns and select the phase list before entering the main
+loop. The selection is final for the run — no mid-pipeline switching.
+
+## Pipeline Resolution
+
+Fix-bug does **not** read `task.pipeline` from config. The path-branch decision
+above replaces the task pipeline lookup. The orchestrator MAY honour
+`config.pipelines.bug` to override the default Path A / Path B phase lists,
+mirroring `meta-orchestrate.md § Pipeline Resolution`; if unset, the lists
+above are used.
+
+## Algorithm
+
+The fix-bug orchestrator MUST follow this procedure exactly. The structure
+mirrors `meta-orchestrate.md § Execution Algorithm` — same persona-map, same
+banner-map, same cluster detection, same preflight gate, same event emission.
+Differences are confined to the **triage** step and the **path branch**.
+
+```
+1. Pre-loop setup (mirrors meta-orchestrate.md):
+   - Resolve FORGE_ROOT.
+   - Detect execution cluster from ANTHROPIC_DEFAULT_*_MODEL env vars.
+   - Clear progress log: store-cli progress-clear bugs
+   - Read bug record. If status ∈ {blocked, escalated, fixed, abandoned}:
+     skip the run, emit a single `bug_skipped` event, return.
+
+2. Triage:
+   - Locate or create the bug record (MANDATORY — do this before anything else):
+     a. Determine the bug ID: if $ARGUMENTS is an existing FORGE-BUG-NNN ID, use it.
+        Otherwise derive the next available ID by listing .forge/store/bugs/.
+     b. If .forge/store/bugs/{BUG_ID}.json does NOT exist, write a fresh record
+        via store-cli with status="reported".
+     c. Read the now-guaranteed record.
+   - Spawn the triage subagent (persona: bug-fixer). It MUST:
+     • Reproduce the bug (failing test or reproduction script).
+     • Confirm the root cause via codebase research.
+     • Decide Path A vs Path B by the criteria above.
+     • Write TRIAGE.md and TRIAGE-SUMMARY.json (with `path` field).
+     • Call set-bug-summary {bugId} triage TRIAGE-SUMMARY.json
+   - On return, orchestrator transitions status:
+       store-cli update-status bug {bugId} status triaged
+       store-cli update-status bug {bugId} status in-progress
+   - Read summaries.triage.route. If neither "A" nor "B": escalate
+     (verdict_malformed). Do not guess.
+
+3. Path selection:
+   - phases = phases_A if route == "A" else phases_B
+   - Begin main phase loop.
+
+4. Phase loop (identical to meta-orchestrate.md § Execution Algorithm):
+   for each phase in phases[1:]:    # triage already done
+     - Resolve model (cluster + ROLE_TIER).
+     - Compute eventId, agent_name, banner_name (from PERSONA_MAP /
+       BANNER_MAP below).
+     - Announce phase: banner + "→ {bugId}  [{display_model}]".
+     - Start progress Monitor on .forge/store/events/bugs/progress.log.
+     - Preflight gate: preflight-gate.cjs --phase {role} --bug {bugId}
+       Exit 1 or 2 → escalate (see meta-orchestrate.md § Escalation Procedure)
+       with bug_id substituted for task_id. Update bug.status to "escalated"
+       only if it is currently "in-progress" (do not downgrade other states).
+     - Compose role-block, architecture-block, summary-block, overlay (via
+       build-overlay.cjs --bug {bugId}).
+     - Spawn subagent via Agent tool. Subagent prompt passes:
+         sprint_or_bug_id = "bugs"   # virtual sprint dir for emit/sidecar
+         record_id        = {bugId}
+         sidecar_path     = .forge/store/events/bugs/_{event_id}_usage.json
+     - On return: merge sidecar, emit canonical event (orchestrator-owned),
+       stop progress Monitor, print phase-exit signal (✓ / ↻ / ⚠), run
+       /compact with checkpoint line.
+     - If phase is a review and verdict == "revision": re-enter the loop
+       on the on_revision predecessor up to max_iterations. Exhaust →
+       escalate (see meta-orchestrate.md § Escalation Procedure).
+
+5. Phase-specific responsibilities (sub-workflow contracts):
+   - plan-fix (Path B): engineer writes BUG_FIX_PLAN.md and BUG-FIX-PLAN-SUMMARY.json
+     (verdict: "n/a"). No status write.
+   - review-plan (Path B): supervisor writes REVIEW-PLAN-SUMMARY.json
+     (verdict: approved | revision). No status write.
+   - implement: engineer (or bug-fixer for Path A) applies the fix, runs the
+     regression test, writes IMPLEMENTATION-SUMMARY.json (verdict: "n/a").
+     No status write — bug stays at "in-progress".
+   - review-code: supervisor reads the actual diff and the regression test,
+     writes REVIEW-CODE-SUMMARY.json (verdict: approved | revision).
+   - approve: architect writes ARCHITECT_APPROVAL.md and APPROVE-SUMMARY.json
+     (verdict: approved | revision). No status write — the verdict signal is
+     the summary, not bug.status (see read-verdict.cjs:44).
+   - commit: engineer makes the git commit and runs:
+       store-cli update-status bug {bugId} status fixed
+     Then writes COMMIT-SUMMARY.json (verdict: "n/a"). This is the ONLY
+     phase that writes bug.status post-triage.
+
+6. Finalize (collator, housekeeping):
+   - Aggregate cost data from .forge/store/events/bugs/*.json filtered by
+     this bugId, and append a "## Cost Summary" section to the bug's
+     INDEX.md artifact.
+   - Run `node "$FORGE_ROOT/tools/collate.cjs" {bugId} --purge-events`.
+     Collate purges only this bug's events from the shared bugs/ dir
+     (filtered by bugId reference) — it does NOT purge other bugs' events.
+   - Run preflight finalize gate: preflight-gate.cjs --phase finalize --bug {bugId}.
+     Exit 1 → escalate. Do NOT downgrade bug.status (it is already "fixed").
+   - Do NOT emit a phase event yourself. The orchestrator owns event
+     emission for finalize as it does for every other phase — composed from
+     runtime telemetry plus the collator's summary.
+```
+
+## Persona and Banner Maps
+
+Mirrors `meta-orchestrate.md` for shared roles. Bug-only role is `triage`.
+
+```
+# --- Role-to-noun mapping (persona and skill file lookups) ---
+ROLE_TO_NOUN = {
+  "triage":      "bug-fixer",
+  "plan":        "engineer",         # Path B only
+  "review-plan": "supervisor",       # Path B only
+  "implement":   "engineer",
+  "review-code": "supervisor",
+  "approve":     "architect",
+  "commit":      "engineer",
+  "finalize":    "collator",
+}
+# Default fallback: "bug-fixer"
+
+# --- Persona symbol lookup (emoji, name, tagline) ---
+PERSONA_MAP = {
+  "triage":      ("🍂", "Bug Fixer",  "I find what has decayed and decide the path."),
+  "plan":        ("🌱", "Engineer",   "I plan what will be built before any code is written."),
+  "review-plan": ("🌿", "Supervisor", "I review before things move forward. I read the actual fix, not just the plan."),
+  "implement":   ("🌱", "Engineer",   "I build what was planned. I do not move forward until the code is clean."),
+  "review-code": ("🌿", "Supervisor", "I review before things move forward. I read the actual code, not the report."),
+  "approve":     ("🗻", "Architect",  "I hold the shape of the whole. I give final sign-off before commit."),
+  "commit":      ("🌱", "Engineer",   "I close out completed work with a clean, honest commit."),
+  "finalize":    ("🍃", "Collator",   "I gather what exists and arrange it into views."),
+}
+# Default fallback: ("🍂", "Bug Fixer", "I find what has decayed and decide the path.")
+
+# --- Banner identity map (banner name per phase role) ---
+BANNER_MAP = {
+  "triage":      "rift",
+  "plan":        "forge",
+  "review-plan": "oracle",
+  "implement":   "forge",
+  "review-code": "oracle",
+  "approve":     "north",
+  "commit":      "forge",
+  "finalize":    "drift",
+}
+# Default fallback: "rift"
+```
+
+## Subagent Prompt Composition
+
+Identical pattern to `meta-orchestrate.md § Execution Algorithm`. The only
+differences are:
+
+- `--bug {bugId}` flag passed to preflight-gate.cjs and sub-workflows.
+- `sprint_or_bug_id = "bugs"` for emit/sidecar/progress (virtual sprint dir).
+- `build-overlay.cjs --bug {bugId}` for the overlay (matches the task pattern
+  `build-overlay.cjs --task {taskId}`).
+- Sidecar path uses `.forge/store/events/bugs/_{event_id}_usage.json` — the
+  shared bugs virtual dir. Collate filters by bug reference at purge time.
+
+```
+# --- Materialize project overlay (replaces MASTER_INDEX.md read in subagent) ---
+overlay_result = run_bash(
+  f'node "$FORGE_ROOT/tools/build-overlay.cjs" --bug {bug_id} --format md'
+)
+bug_overlay_md = overlay_result.stdout if overlay_result.exit_code == 0 else ""
+
+spawn_subagent(
+  prompt=compose_subagent_prompt(
+    agent_name=agent_name, progress_log_path=progress_log_path, banner_name=banner_name,
+    sprint_or_bug_id="bugs", phase_role=phase.role,
+    architecture_block=bug_architecture_block, summary_block=bug_summary_block,
+    role_block=role_block, overlay_md=bug_overlay_md,
+    context={"Bug Root": bug_root_path, "Store Root": store_root_path,
+             "Events Root": ".forge/store/events/bugs/"},
+    workflow=phase.workflow, record_id=bug_id,
+    sidecar_path=f".forge/store/events/bugs/_{event_id}_usage.json"
+  ),
+  description=f"{emoji} {persona_name} — {phase.name} for {bug_id}",
+  model=phase_model
+)
+```
+
+## Phase Gates
+
+Declarative pre-flight gates. Evaluated by `forge/tools/preflight-gate.cjs`
+before every subagent spawn. Grammar identical to `meta-orchestrate.md §
+Phase Gates`. Gates encode both the path-A/path-B split (via `after`
+predecessors that differ per path) and the status-trap defences.
+
+```gates phase=triage
+forbid bug.status == blocked
+forbid bug.status == escalated
+forbid bug.status == fixed
+forbid bug.status == abandoned
+forbid bug.status == approved
+forbid bug.status == verified
+```
+
+```gates phase=plan
+artifact {engineering}/bugs/{bug}/TRIAGE.md min=200
+after triage = n/a
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=review-plan
+artifact {engineering}/bugs/{bug}/BUG_FIX_PLAN.md min=200
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=implement
+artifact {engineering}/bugs/{bug}/TRIAGE.md min=200
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=review-code
+after implement = n/a
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=approve
+after review-code = approved
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=commit
+after approve = approved
+forbid bug.status == fixed
+forbid bug.status == approved
+forbid bug.status == verified
+forbid bug.status == blocked
+forbid bug.status == escalated
+```
+
+```gates phase=finalize
+artifact {engineering}/bugs/{bug}/INDEX.md
+```
+
+Note: the `forbid bug.status == approved | verified` rows are defensive — no
+phase in this workflow writes those values, and a follow-up cleanup should
+drop them from `bug.schema.json` entirely. Until then, these gates halt any
+LLM-improvised attempt to land in the run-task trap (see today's regression).
+
+## Generation Instructions
+
+Mirrors `meta-orchestrate.md § Generation Instructions` with these
+adjustments:
+
+- The generated `fix_bug.md` must include the **Triage Judgement** section
+  verbatim, including the JSON shape, the Path A eligibility criteria, and
+  the path-selection algorithm.
+- `ROLE_TO_NOUN` MUST include `triage` and `finalize` in addition to the
+  five run-task roles.
+- The generated orchestrator MUST read `summaries.triage.route` and select
+  `phases_A` or `phases_B` before entering the main loop.
+- Sub-workflow invocations pass `--bug {bugId}` (mirroring `--task {taskId}`).
+- Event emission uses `sprint_or_bug_id="bugs"` (the reserved virtual sprint
+  dir; matches `validate-store.spec.md` and the reservation in
+  `store-cli.cjs`).
+- Build-overlay uses `--bug {bugId}` and falls back to the bug record's
+  `path` field for KB context if the overlay is empty.
+- Subagent personas, banners, and skills are loaded by noun via
+  `{persona_noun}.md` and `{persona_noun}-skills.md` — never by phase role.
+- Phase banners are orchestrator-owned (see `meta-orchestrate.md`). Subagent
+  prompts MUST NOT contain banner commands.
+- Include the cluster-detection block, model-resolution dispatch, progress
+  IPC, phase-exit signals, post-phase `/compact` with checkpoint line
+  `[checkpoint] bug={bug_id} phase={phase.role} iterations={iteration_counts}`,
+  and context-pack injection — identical to `meta-orchestrate.md`.
+- Token reporting: see `_fragments/finalize.md` — wire via `file_ref:` in
+  each subagent prompt.
+- Sub-workflows (`plan_task.md`, `implement_plan.md`, `review_plan.md`,
+  `review_code.md`, `architect_approve.md`, `commit_task.md`) MUST detect
+  the `--bug` flag and resolve their entity context against the bug record;
+  they share the gate-and-verdict machinery with their `--task` paths via
+  `BUG_PHASE_VERDICT_SOURCE` in `read-verdict.cjs`.
+
+## 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 laws specific to fix-bug:**
+
+1. **Path is decided once.** The triage subagent records `summaries.triage.route`.
+   The orchestrator selects the phase list and does not switch paths mid-run.
+   If the architect or supervisor concludes Path A was wrong, the verdict is
+   `revision` — re-enter the loop, escalate on exhaustion. Never silently
+   promote a Path A run into Path B.
+
+2. **No status writes outside owned phases.** Only `triage` (`reported →
+   triaged → in-progress`) and `commit` (`in-progress → fixed`) write
+   `bug.status`. No phase writes `approved` or `verified`. No phase writes
+   anything in finalize. LLM improvisation that mirrors a task workflow's
+   status writes is a violation; the gates catch it, the iron law names it.
+
+3. **No silent skipping.** A bug at `fixed`/`abandoned`/`blocked`/`escalated`
+   is skipped at pre-loop with one `bug_skipped` event. Skipping inside the
+   phase loop (writing "phase skipped" summaries) is forbidden — that pattern
+   produced the inconsistent-skip drift that surfaced today's regression.
+
+## Friction Emit
+
+When the Bug Fixer, Supervisor, Architect, Engineer, or Collator detects skill
+friction during fix-bug — 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:enhance --phase 2` can act on the signal.
+
+**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.   |
+
+**Recording friction (subagent side):** call `node "$FORGE_ROOT/tools/friction-emit.cjs` `--workflow {workflow} --persona {persona-noun} --issue {token} [--subkind {token}] [--evidence '{...}']`. The tool appends one judgement-only record to `.forge/cache/FRICTION-{workflow}.jsonl`. The orchestrator drains the file at phase-end, stamps runtime attribution (model, provider, usage, wall times, eventId) onto each record, and emits the events via `store-cli emit` as event type `"friction"`. The schema enforces `{workflow, persona, issue}` as required when `type === "friction"`; `subkind` is the frozen enum `skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant` or experimental `^x_[a-z_]+$`. Emit one record per distinct friction signal — do not coalesce.
+
+## 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/bugs/progress.log`. Agent name format: `{bugId}:{persona_noun}:{phase.role}:{iteration}`. Clear at bug start: `store-cli progress-clear bugs`.
+
+## Phase-Exit Signals
+
+After each subagent returns: `✓` for completed/approved, `↻` for revision required (with iteration count), `⚠` for escalated. Format mirrors `meta-orchestrate.md § Phase-Exit Signals` with `bug_id` in place of `task_id`.
+
+## 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. All bug-phase events use `sprintId="bugs"` (the reserved virtual
+sprint dir). The schema's `event.bugId` field carries the originating bug
+ID for cross-bug filtering at collate time. Subagents write
+`{PHASE}-SUMMARY.json` and return; the orchestrator composes the canonical
+event and emits it.

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

@@ -0,0 +1,132 @@
+---
+requirements:
+  reasoning: Medium
+  context: Medium
+  speed: Medium
+audience: subagent
+phase: implement
+context:
+  architecture: false
+  prior_summaries: delta
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [engineer]
+  skills: [engineer, generic]
+  templates: [PROGRESS_TEMPLATE]
+  sub_workflows: [review_code]
+  kb_docs: [architecture/stack.md, architecture/routing.md]
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🌱 Meta-Workflow: Implement Plan
+
+## Purpose
+
+The Engineer implements the approved plan: write code, run tests, verify, and document progress.
+
+## Algorithm
+
+```
+
+0. Pre-flight Gate Check:
+   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase implement --{entity_kind} {record_id}`
+   - 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.
+1. Load Context:
+   - Read `.forge/personas/engineer.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+   - store-cli verbs: `read` | `list` | `write` | `emit` | `update-status` | `set-summary` | `describe` | `nlp` | `query` | `delete` — there is no `get`/`set`/`find`. See `_fragments/store-cli-verbs.md` for full notes; run `--help` before improvising.
+   - Read the approved PLAN.md
+   - Read business domain docs relevant to the task
+
+2. Implementation:
+   - Execute plan steps incrementally
+   - Perform "compile/check" after each significant change
+   - Ensure all new code follows established project patterns
+
+3. Verification:
+   - Run syntax verification: {SYNTAX_CHECK}
+   - Run test suite using the **resolved test command** from `commands.test` in `.forge/config.json` (i.e. `` `${commands.test}` ``, e.g. `.venv/bin/python -m pytest`, `npm test`, `cargo test`). Do NOT invoke bare `python` / `python3` / `pytest` — the project interpreter is rarely on `$PATH`; using the resolved command avoids `python: command not found` and `No module named pytest`.
+   - Template placeholder: {{TEST_COMMAND}} (resolved at materialize time from `commands.test`).
+   - Run build if frontend assets modified: {BUILD_COMMAND}
+
+4. Documentation:
+   - Write PROGRESS.md containing:
+     - Summary of changes
+     - Test evidence (copy of output)
+     - Files changed manifest
+
+5. Knowledge Writeback:
+   - Update architecture/domain/stack-checklist if discoveries were made
+   - Tag updates: `<!-- Discovered during {TASK_ID} — {date} -->`
+
+6. Finalize:
+   - Transitions:
+     - **Task mode** — legal predecessors are `planned`, `plan-approved`, or `implementing`; target is `implemented`.
+       - `planned`        → `implemented` (workflow-prose path — direct)
+       - `plan-approved`  → `implementing` → `implemented` (supervisor-review path)
+       - 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 implemented`
+     - **Bug mode** — NO status write. The bug remains `in-progress` until the commit phase transitions it to `fixed`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
+   - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
+
+7. Emit Summary Sidecar:
+   - Write `IMPLEMENTATION-SUMMARY.json` to the record's directory with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what this implementation delivered>",
+       "key_changes": ["<up to 12 bullets, 200 chars each — files changed, key decisions>"],
+       "verdict":     "n/a",
+       "written_at":  "<current ISO 8601 timestamp>",
+       "artifact_ref":"PROGRESS.md"
+     }
+     ```
+   - Call (task mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} implementation \
+       engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json
+     ```
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} implementation \
+       engineering/bugs/{bugDir}/IMPLEMENTATION-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+```
+
+## Iron Laws
+
+- Follow the Algorithm step by step. Execute the approved PLAN.md exactly; do not invent scope or skip steps without updating the plan first.
+- Read `.forge/personas/engineer.md` first; print the persona identity line 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.
+- Run the full test suite before declaring the task implemented. Silent continuation past test failures is never acceptable.
+
+## Store-Write Verification
+
+Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
+non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
+
+1. Parse the structured error (names the offending field + schema file).
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times.
+4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
+## Friction Emit
+Emit `type:friction` `{workflow:implement, persona:engineer, issue}` per `_fragments/friction-emit.md`.
+
+## Generation Instructions
+
+- **Workflow Structure:** Strict "Algorithm" block format.
+- **Markers (required by `/forge:implement` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `engineer.md` persona path. Missing any → kickoff shim refuses to dispatch.
+- **Context Isolation:** Forbid inline execution of complex logic; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Replace {SYNTAX_CHECK}, {TEST_COMMAND}, and {BUILD_COMMAND} with actual project commands.
+  - Reference project-specific architecture docs by name.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.