@entelligentsia/forgecli 0.10.0 → 0.10.1

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

@@ -27,7 +27,8 @@ deps:
 
 0. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase implement --task {taskId}`
+   - **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.
@@ -59,15 +60,17 @@ deps:
    - Tag updates: `<!-- Discovered during {TASK_ID} — {date} -->`
 
 6. Finalize:
-   - Transitions: task FSM 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 task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
+   - 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 task directory with the following shape:
+   - Write `IMPLEMENTATION-SUMMARY.json` to the record's directory with the following shape:
      ```json
      {
        "objective":   "<one sentence — what this implementation delivered>",
@@ -77,12 +80,17 @@ deps:
        "artifact_ref":"PROGRESS.md"
      }
      ```
-   - Call:
+   - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} implementation \
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} implementation \
        engineering/sprints/{sprint}/{task}/IMPLEMENTATION-SUMMARY.json
      ```
-   - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     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

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

@@ -27,7 +27,8 @@ deps:
 
 0. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase plan --task {taskId}`
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase plan --{entity_kind} {record_id}`
    - 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.
@@ -64,14 +65,14 @@ deps:
    - If new patterns were discovered, update architecture or business domain docs
 
 5. Finalize:
-   - Transitions: task FSM legal targets from this step
-     - `draft` → `planned` (this workflow's only legal target)
-     - Out-of-band escapes (any state): `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
+   - Transitions:
+     - **Task mode** — legal target from this step: `draft → planned`. Out-of-band escapes (any state): `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`.
+       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
+     - **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.
 
 6. Emit Summary Sidecar:
-   - Write `PLAN-SUMMARY.json` to the task directory with the following shape:
+   - Write `PLAN-SUMMARY.json` (task mode) or `BUG-FIX-PLAN-SUMMARY.json` (bug mode) to the record's directory. Shape:
      ```json
      {
        "objective":   "<one sentence — what this plan sets out to build>",
@@ -81,12 +82,17 @@ deps:
        "artifact_ref":"PLAN.md"
      }
      ```
-   - Call:
+   - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} plan \
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} plan \
        engineering/sprints/{sprint}/{task}/PLAN-SUMMARY.json
      ```
-   - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} plan \
+       engineering/bugs/{bugDir}/BUG-FIX-PLAN-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

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

@@ -45,7 +45,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 0. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-code --task {taskId}`
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-code --{entity_kind} {record_id}`
    - 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.
@@ -71,11 +72,13 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Update stack-checklist.md if new patterns or pitfalls were discovered
 
 5. Finalize:
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status code-revision-required` (if Revision Required)
+   - Transitions:
+     - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `... status code-revision-required` (if Revision Required).
+     - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.code_review.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
 6. Emit Summary Sidecar:
-   - Write `REVIEW-IMPL-SUMMARY.json` to the task directory with the following shape:
+   - Write `REVIEW-IMPL-SUMMARY.json` to the record's directory with the following shape:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -85,10 +88,15 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
        "artifact_ref":"CODE_REVIEW.md"
      }
      ```
-   - Call:
+   - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} code_review \
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} code_review \
        engineering/sprints/{sprint}/{task}/REVIEW-IMPL-SUMMARY.json
      ```
-   - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} code_review \
+       engineering/bugs/{bugDir}/REVIEW-IMPL-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```

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

@@ -46,7 +46,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 0. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-plan --task {taskId}`
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-plan --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
@@ -66,15 +67,17 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      - If Approved: provide any advisory notes
 
 4. Finalize:
-   - Transitions: task FSM predecessor must be `planned`.
-     - Approved          → `plan-approved`
-     - Revision Required → `plan-revision-required`
-     - Out-of-band escapes (any state): `code-revision-required`, `blocked`, `escalated`, `abandoned`
-   - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status plan-approved` (if Approved) or `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status plan-revision-required` (if Revision Required)
+   - Transitions:
+     - **Task mode** — predecessor must be `planned`.
+       - Approved          → `plan-approved`
+       - Revision Required → `plan-revision-required`
+       - Out-of-band escapes (any state): `code-revision-required`, `blocked`, `escalated`, `abandoned`
+       Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status plan-approved` (if Approved) or `... status plan-revision-required` (if Revision Required)
+     - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.review_plan.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **Do NOT emit a phase event yourself.** The orchestrator 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.
 
 5. Emit Summary Sidecar:
-   - Write `REVIEW-PLAN-SUMMARY.json` to the task directory with the following shape:
+   - Write `REVIEW-PLAN-SUMMARY.json` to the record's directory with the following shape:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -84,12 +87,17 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
        "artifact_ref":"PLAN_REVIEW.md"
      }
      ```
-   - Call:
+   - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {task_id} review_plan \
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} review_plan \
        engineering/sprints/{sprint}/{task}/REVIEW-PLAN-SUMMARY.json
      ```
-   - If set-summary exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
+     Or (bug mode):
+     ```
+     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} review_plan \
+       engineering/bugs/{bugDir}/REVIEW-PLAN-SUMMARY.json
+     ```
+   - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
 ## Generation Notes

package/dist/forge-payload/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "forge",
-  "version": "0.43.19",
+  "version": "0.44.4",
   "description": "Self-enhancing AI software development lifecycle \u2014 generates project-specific SDLC instances from meta-definitions",
   "license": "MIT",
   "author": {

package/dist/forge-payload/.schemas/bug.schema.json

@@ -9,7 +9,7 @@
     "title":               { "type": "string" },
     "description":         { "type": "string" },
     "severity":            { "type": "string", "enum": ["critical", "major", "minor"] },
-    "status":              { "type": "string", "enum": ["reported", "triaged", "in-progress", "fixed", "approved", "verified"] },
+    "status":              { "type": "string", "enum": ["reported", "triaged", "in-progress", "fixed"] },
     "path":                { "type": "string" },
     "rootCauseCategory": {
       "type": "string",
@@ -47,7 +47,8 @@
         "findings":    { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 12 },
         "verdict":     { "type": "string", "enum": ["approved", "revision", "n/a"] },
         "written_at":  { "type": "string", "format": "date-time" },
-        "artifact_ref":{ "type": "string", "description": "Relative path to the full artifact" }
+        "artifact_ref":{ "type": "string", "description": "Relative path to the full artifact" },
+        "route":       { "type": "string", "enum": ["A", "B"], "description": "Fix-bug pipeline route decision. Only set on the triage phase summary by meta-fix-bug.md. A = short-circuit (skip plan-fix + review-plan); B = full loop (default). Optional and meaningless on non-triage phases — see meta-fix-bug.md § Triage Judgement." }
       },
       "additionalProperties": false
     }

package/dist/forge-payload/tools/collate.cjs

@@ -952,10 +952,16 @@ for (const bug of allBugs) {
   // When purging events for a bug, aggregate cost data from event files
   // before they are deleted. The aggregated cost summary is embedded in
   // the bug's INDEX.md so the information survives the purge.
+  //
+  // Bug-phase events live in the shared `events/bugs/` virtual sprint dir
+  // (see meta-fix-bug.md § Event Emission). Read from that dir and filter
+  // by `event.bugId === bug.bugId` — the per-bug `events/{bugId}/` path
+  // never existed (silent data loss before this fix).
   let costTotals;
   if (PURGE_EVENTS && SPRINT_ARG && SPRINT_ARG === bug.bugId) {
-    const { events } = loadSprintEvents(bug.bugId);
-    const tokenEvents = events.filter(e => e.inputTokens !== undefined);
+    const { events } = loadSprintEvents('bugs');
+    const bugEvents = events.filter(e => e.bugId === bug.bugId);
+    const tokenEvents = bugEvents.filter(e => e.inputTokens !== undefined);
     if (tokenEvents.length > 0) {
       const totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, estimatedCostUSD: 0, sources: new Set() };
       for (const e of tokenEvents) {
@@ -1022,16 +1028,35 @@ const tag = DRY_RUN ? '[dry-run] ' : '';
 console.log(`${tag}Collated: ${targetSprints.length} sprint(s), ${allBugs.length} bug(s) → MASTER_INDEX.md updated, ${sprintIndexesWritten} sprint INDEX(es), ${taskIndexesWritten} task INDEX(es), ${bugIndexesWritten} bug INDEX(es), ${costReportsWritten} COST_REPORT(s) written`);
 
 // --- Purge event directory if requested ---
+//
+// Bug arg → purge only the bug-matching events from the shared
+// `events/bugs/` dir (filter by event.bugId). Sprint arg → purge the
+// whole sprint event directory as before.
 if (PURGE_EVENTS) {
-  const relDir = path.relative(cwd, path.join(storeRoot, 'events', SPRINT_ARG));
   try {
-    const result = _getStore().purgeEvents(SPRINT_ARG, { dryRun: DRY_RUN });
-    if (result.fileCount === 0) {
-      console.log(`${tag}Purge: no events directory found for '${SPRINT_ARG}' — nothing to delete`);
-    } else if (DRY_RUN) {
-      console.log(`[dry-run] would purge: ${relDir}/ (${result.fileCount} file(s))`);
+    let result;
+    let relDir;
+    if (IS_BUG_ARG) {
+      relDir = path.relative(cwd, path.join(storeRoot, 'events', 'bugs'));
+      result = _getStore().purgeBugEvents(SPRINT_ARG, { dryRun: DRY_RUN });
+      const label = `'${SPRINT_ARG}' in ${relDir}/`;
+      if (result.fileCount === 0) {
+        console.log(`${tag}Purge: no events for ${label} — nothing to delete`);
+      } else if (DRY_RUN) {
+        console.log(`[dry-run] would purge: ${label} (${result.fileCount} file(s))`);
+      } else {
+        console.log(`Purged: ${label} (${result.fileCount} event file(s) deleted)`);
+      }
     } else {
-      console.log(`Purged: ${relDir}/ (${result.fileCount} event file(s) deleted)`);
+      relDir = path.relative(cwd, path.join(storeRoot, 'events', SPRINT_ARG));
+      result = _getStore().purgeEvents(SPRINT_ARG, { dryRun: DRY_RUN });
+      if (result.fileCount === 0) {
+        console.log(`${tag}Purge: no events directory found for '${SPRINT_ARG}' — nothing to delete`);
+      } else if (DRY_RUN) {
+        console.log(`[dry-run] would purge: ${relDir}/ (${result.fileCount} file(s))`);
+      } else {
+        console.log(`Purged: ${relDir}/ (${result.fileCount} event file(s) deleted)`);
+      }
     }
   } catch (err) {
     console.error(`Error: ${err.message}`);

package/dist/forge-payload/tools/parse-gates.cjs

@@ -18,7 +18,13 @@
 const FENCE_OPEN = /^```gates\s+phase=([A-Za-z0-9_-]+)\s*$/;
 const FENCE_CLOSE = /^```\s*$/;
 
-const VALID_VERDICTS = new Set(['approved', 'revision']);
+// Verdicts a workflow can carry in an `after <phase> = <verdict>` directive.
+// Mirrors `read-verdict.cjs § ALLOWED_VERDICTS` — both must accept the same
+// set. `n/a` is the legitimate verdict for setup phases (plan, implement,
+// triage) that do not produce an approval/revision signal. Rejecting it
+// here caused EMBERGLOW-BUG-001 (v0.44.1) to halt at preflight exit 2
+// when the new fix-bug meta tried to use `after triage = n/a`.
+const VALID_VERDICTS = new Set(['approved', 'revision', 'n/a']);
 
 function parseGates(markdown) {
   if (typeof markdown !== 'string' || markdown.length === 0) return {};
@@ -142,7 +148,7 @@ function parseAfter(rest, lineNo) {
   const verdict = m[2].toLowerCase();
   if (!VALID_VERDICTS.has(verdict)) {
     throw new Error(
-      `parse-gates: line ${lineNo}: "after" verdict must be "approved" or "revision", got "${m[2]}"`,
+      `parse-gates: line ${lineNo}: "after" verdict must be "approved", "revision", or "n/a", got "${m[2]}"`,
     );
   }
   return { phase: m[1], verdict };

package/dist/forge-payload/tools/store-cli.cjs

@@ -140,6 +140,12 @@ const { suggest, suggestEntityType, formatSuggestion } = require('./lib/suggest.
 const VALID_SUMMARY_PHASES = new Set(['plan', 'review_plan', 'implementation', 'code_review', 'validation', 'triage', 'approve']);
 
 // Schema for a single phase summary (used by set-summary / set-bug-summary)
+// Mirror of bug.schema.json § $defs.phaseSummary. Both definitions MUST stay
+// in sync — this constant validates set-summary / set-bug-summary writes;
+// the JSON schema validates entity reads. `route` is an optional triage-only
+// field carrying the fix-bug pipeline route decision (A | B) and exists here
+// for bug.summaries.triage in particular; non-triage phases simply do not
+// set it.
 const PHASE_SUMMARY_SCHEMA = {
   type: 'object',
   required: ['objective', 'written_at'],
@@ -149,7 +155,8 @@ const PHASE_SUMMARY_SCHEMA = {
     findings:    { type: 'array', items: { type: 'string', maxLength: 200 }, maxItems: 12 },
     verdict:     { type: 'string', enum: ['approved', 'revision', 'n/a'] },
     written_at:  { type: 'string' },
-    artifact_ref:{ type: 'string' }
+    artifact_ref:{ type: 'string' },
+    route:       { type: 'string', enum: ['A', 'B'] }
   },
   additionalProperties: false
 };
@@ -181,12 +188,21 @@ const SPRINT_TRANSITIONS = {
 };
 
 const BUG_TRANSITIONS = {
-  reported:     ['triaged'],
-  triaged:      ['in-progress'],
-  'in-progress': ['fixed', 'approved'],   // fixed: code complete; approved: architect direct sign-off
-  fixed:        ['approved', 'in-progress'],   // approved: architect sign-off; in-progress: revision
-  approved:     ['verified', 'in-progress', 'fixed'],   // verified: commit; in-progress/ fixed: revision
-  // Terminal: verified
+  reported:      ['triaged'],
+  triaged:       ['in-progress'],
+  'in-progress': ['fixed'],
+  // Terminal: fixed
+  //
+  // The `approved` and `verified` enum members were removed (forge#GH-NNN).
+  // The architect-approve verdict signal for bugs travels through
+  // `bug.summaries.approve.verdict` (see read-verdict.cjs §
+  // BUG_PHASE_VERDICT_SOURCE), not `bug.status`. Keeping them in the enum
+  // created an LLM-translation trap whereby a task-shaped approve workflow
+  // run on a bug improvised `update-status bug ... approved`, which failed
+  // either at the schema layer (illegal transition out of terminal
+  // `verified`) or, post-FORGE-BUG-002 preflight defence, at the gate
+  // layer (forbid bug.status == approved). Dropping the enum removes the
+  // trap at its source.
 };
 
 const FEATURE_TRANSITIONS = {
@@ -205,7 +221,7 @@ const TRANSITION_MAP = {
 const TERMINAL_STATES = new Set([
   'committed', 'abandoned',          // task
   'retrospective-done',              // sprint
-  'verified',                        // bug
+  'fixed',                           // bug
   'shipped', 'retired'               // feature
 ]);
 
@@ -785,10 +801,13 @@ function cmdEmit() {
   }
 
   // FK check: reject sprintIds that are not in the store and not reserved.
-  // SYS-* prefix is reserved for system-generated events that predate sprint records.
+  // Reserved sprintIds:
+  //   - SYS-*  — system-generated events that predate sprint records
+  //   - bugs   — virtual sprint dir for fix-bug phase events (see
+  //              meta/tool-specs/validate-store.spec.md §"event.sprintId")
   // --allow-synthetic bypasses the check for test-harness or synthetic events.
   if (!allowSynthetic) {
-    const RESERVED_GLOB = /^SYS-/;
+    const RESERVED_GLOB = /^(SYS-|bugs$)/;
     if (!RESERVED_GLOB.test(sprintId)) {
       const validSprintIds = resolveValidSprintIds();
       if (!validSprintIds.includes(sprintId)) {

package/dist/forge-payload/tools/store.cjs

@@ -56,6 +56,7 @@ class Store {
    * @returns {{ purged: boolean, fileCount: number, files: string[] }}
    */
   purgeEvents(sprintId, opts) { return this.impl.purgeEvents(sprintId, opts); }
+  purgeBugEvents(bugId, opts) { return this.impl.purgeBugEvents(bugId, opts); }
   /**
    * List event filenames for a sprint directory.
    * @param {string} sprintId
@@ -287,6 +288,66 @@ class FSImpl {
     return { purged: true, fileCount: files.length, files };
   }
 
+  /**
+   * Purge only the events belonging to a specific bug from the shared
+   * `.forge/store/events/bugs/` virtual sprint dir.
+   *
+   * Bugs share a single events directory (`events/bugs/`) — see
+   * `meta-fix-bug.md § Event Emission` and `validate-store.spec.md`. Purging
+   * by bug therefore must filter primary events by `event.bugId === bugId`
+   * and sweep sidecars whose filename pattern `_{eventId}_usage.json`
+   * matches a purged primary. The `events/bugs/` directory itself is
+   * never removed — other bugs' events remain.
+   *
+   * Returns `{ purged, fileCount, files }` matching `purgeEvents`.
+   */
+  purgeBugEvents(bugId, { dryRun = false } = {}) {
+    const eventsBugsDir = path.join(this.storeRoot, 'events', 'bugs');
+    if (!fs.existsSync(eventsBugsDir)) {
+      return { purged: false, fileCount: 0, files: [] };
+    }
+
+    const all = fs.readdirSync(eventsBugsDir).filter(f => f.endsWith('.json'));
+    const primaries = all.filter(f => !f.startsWith('_'));
+    const sidecars  = all.filter(f =>  f.startsWith('_') && f.endsWith('_usage.json'));
+
+    // Identify primaries whose payload.bugId matches the requested bug.
+    const matchedPrimaries = [];
+    const matchedEventIds = new Set();
+    for (const filename of primaries) {
+      const filePath = path.join(eventsBugsDir, filename);
+      let payload;
+      try {
+        payload = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      } catch (_) {
+        continue; // malformed file — skip
+      }
+      if (payload && payload.bugId === bugId) {
+        matchedPrimaries.push(filename);
+        if (payload.eventId) matchedEventIds.add(payload.eventId);
+      }
+    }
+
+    // Match sidecars by filename pattern: `_{eventId}_usage.json`.
+    const matchedSidecars = sidecars.filter(filename => {
+      const m = filename.match(/^_(.+)_usage\.json$/);
+      return m && matchedEventIds.has(m[1]);
+    });
+
+    const allMatches = [...matchedPrimaries, ...matchedSidecars];
+    if (dryRun) {
+      return { purged: false, fileCount: allMatches.length, files: allMatches };
+    }
+    for (const filename of allMatches) {
+      fs.unlinkSync(path.join(eventsBugsDir, filename));
+    }
+    return {
+      purged: allMatches.length > 0,
+      fileCount: allMatches.length,
+      files: allMatches,
+    };
+  }
+
   /**
    * List all event filenames for a sprint directory.
    * Returns { filename, id } objects for ALL .json files including

package/dist/forge-payload/tools/validate-store.cjs

@@ -494,8 +494,12 @@ for (const sprint of allSprints) {
 
 // --- Pass 2b: Orphan event directories ---
 // Scan .forge/store/events/ for subdirectories whose name does not match any
-// known sprintId and is not a reserved SYS-* prefix.
-const RESERVED_EVENT_PREFIX = /^SYS-/;
+// known sprintId and is not a reserved virtual dir.
+// Reserved:
+//   - SYS-* — system-generated events that predate sprint records
+//   - bugs  — virtual sprint dir for fix-bug phase events (see
+//             meta/tool-specs/validate-store.spec.md §"event.sprintId")
+const RESERVED_EVENT_PREFIX = /^(SYS-|bugs$)/;
 const eventsBaseDir = path.join(storeRootFromConfig, 'events');
 if (fs.existsSync(eventsBaseDir)) {
   let eventDirEntries;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entelligentsia/forgecli",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Forge SDLC ported onto @earendil-works/pi-coding-agent — production launcher with three bin aliases (forge/forgecli/4ge). Bundles a curated fork of pi-coding-agent vendored under earendil-works names.",
   "license": "MIT",
   "author": "Entelligentsia",
@@ -49,7 +49,7 @@
     ]
   },
   "forge": {
-    "bundledVersion": "0.43.19",
+    "bundledVersion": "0.44.3",
     "forgeRoot": "../forge/forge"
   },
   "scripts": {