Leather-bound bug registry ledger glowing with unique fingerprint patterns beside each entry, fingerprint-deduplicated closed-loop bug lifecycle
Act IV, Learn · Chapter 23

The Bug Registry

Every bug, fingerprinted. Every fix, validated. The registry remembers.

Closed-loop tracker. Four tools form a closed loop: forge_bug_register → forge_bug_list → forge_bug_update_status → forge_bug_validate_fix. Records live in .forge/bugs/<bugId>.json.

Why a Registry?

Bugs found by the Tempering quorum, visual-diff scanners, or regression guard used to live in ad-hoc CHANGELOG entries and stray comments. They got fixed, forgotten, and then re-discovered three sprints later with different symptoms. The Bug Registry gives every scanner-discovered bug a durable record, fingerprinted, classified, tracked, and validated.

Fingerprint Dedup

When a bug is registered, the classifier computes a fingerprint from the scanner name + test name + assertion message + normalized stack trace. Re-registering the same fingerprint returns DUPLICATE_BUG with the existing bugId, no noise, no duplication.

The Status Lifecycle

Bug registry status machine: bugs start in 'open' (just registered, amber). Forward progression: open -> in-fix (work in progress) -> fixed (terminal green) after forge_bug_validate_fix re-runs the originating scanner and the gate passes. If the validation gate fails, the bug stays in-fix with an entry appended to bug.validationAttempts[]. From 'open' there are two side classifications to dashed gray terminal states: wont-fix and duplicate (links to original). Backward transitions from any terminal state are forbidden (red dashed line crossed out). Fingerprint dedupes on register; re-registering an existing fingerprint does not open a new bug ID.

Every bug moves through an explicit state machine:

Valid status transitions
open → in-fix → validating → fixed
             ↘ wont-fix
             ↘ duplicate
open → noise       (classifier ruled it a false positive)

Transitions are enforced by forge_bug_update_status. An illegal transition returns INVALID_TRANSITION.

Classification

The classifier inspects evidence (test name, assertion message, stack trace, flakiness history) and returns one of:

  • real-bug, evidence is consistent across scanners; record is persisted and captured to L3 memory.
  • flaky, evidence shows inconsistency; ignored unless confirmed across multiple runs.
  • noise, a triage classification applied by the audit classifier (e.g. "known false-positive pattern"). It is not a bug status. Bugs flagged as noise are typically resolved as wont-fix with the classification recorded in bug.triage.

Only real-bug outcomes write to .forge/bugs/ and fire tempering-bug-registered.

Closed-Loop Fix Validation

forge_bug_validate_fix re-runs the scanner that originally found the bug. On pass, the record moves to fixed, a tempering-bug-validated-fixed event fires, and, if OpenBrain is configured, an L3 thought is written so the next session knows what broke and what fixed it.

Scanner override. If the original scanner is no longer registered, pass scannerOverride to validate with an equivalent. The validation log preserves both scanner names for audit.

Skill Advisory

Every successful forge_bug_register, forge_bug_update_status, and forge_bug_validate_fix response includes a skillAdvisory field that nudges the caller toward the /bug-fix skill — the end-to-end TDD-first fix workflow. The advisory is purely informational; the tool itself returns its normal success payload alongside.

{
  "ok": true,
  "bugId": "bug-7af3...",
  "status": "open",
  "skillAdvisory": {
    "skill": "bug-fix",
    "reason": "Bug registered. The /bug-fix skill composes /code-review, /clean-code-review, /test-sweep around forge_bug_validate_fix so a fix never closes without a regression check.",
    "next": "Invoke /bug-fix bug-7af3 in chat to start the guided workflow."
  }
}

The advisory field varies by tool:

  • forge_bug_register — advisory recommends /bug-fix <bugId> to start the TDD red-green cycle
  • forge_bug_update_status — when transitioning to in-fix, advisory points at /bug-fix; when transitioning to fixed outside the skill, advisory warns that forge_bug_validate_fix should have been run first
  • forge_bug_validate_fix — on success, advisory points at /test-sweep for regression confirmation; on failure, advisory points at /code-review + a re-run of /bug-fix

Pass skipAdvisory: true in the tool input to suppress the field entirely. Useful in CI / batched callers where the advisory adds noise without value.

Where You See It

The dashboard's Triage tab shows open bugs by severity, with status chips and quick-transition buttons. The Watcher's Home chip includes an open bugs count. Cross-linked to incidents via forge_incident_capture.