@entelligentsia/forgecli 1.0.3 → 1.0.14

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

@@ -1,446 +0,0 @@
----
-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]
----
-
-
-# Fix Bug
-## 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 | `triage.md` | 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 / Path B eligibility
-
-See `triage.md § Path A / Path B Eligibility` for the criteria the triage
-subagent applies. The criteria are single-sourced in the triage workflow;
-this orchestrator only reads the resulting `summaries.triage.route` value.
-
-### 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 (workflow: `triage.md`, persona: bug-fixer).
-     It MUST write `TRIAGE.md` + `TRIAGE-SUMMARY.json` with a `route` field
-     (`"A"` or `"B"`) and call `set-bug-summary {bugId} triage` per
-     `triage.md`. The triage workflow is `audience: subagent`, `phase: triage`;
-     the orchestrator MUST NOT pass any other workflow body to this subagent.
-   - 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).
-
-<!-- See _fragments/generation-instructions.md for Generation Instructions template (fix-bug uses orchestrator-special long-form prose — cannot be reduced to standard subsections) -->
-## 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:rebuild --enrich` (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.