Enforce Outcome-First Closure and Machine-Parsable Debug Metadata

[s070681]

Idea: Make Outcomes First-Class in BEADS (Resolution + Repro/Verify + Anchors)

This proposal is about turning BEADS into a better long-term substrate for agentic work by making outcomes and debugging metadata reliably capturable and parseable, without forcing schema migrations or heavy process.

---

Problem

BEADS currently permits closing beads with low-information outcomes (e.g., “done”, “fixed”). That destroys downstream value:

• Closed work stops being reusable knowledge.
• LLMs and humans can’t quickly learn what changed, why, or how it was validated.
• Retrospectives, search, and automation become unreliable because the dataset is inconsistent.
• Beads Viewer's bv robot triage could also benefit from expanding this feature and @Dicklesworthstone could implement this into the TUI

---

Goal

Make BEADS a reliable source of:

• High-signal resolutions (outcomes)
• Stable references for debugging (semantic anchors)
• Lightweight reproduction + verification signals

…while keeping the workflow CLI-friendly and incrementally adoptable.

---

Proposal (Minimal Disruption, Progressive Enforcement)

1) Treat --reason as a first-class “Resolution/Outcome”

Behavioral shift (and/or naming shift):

• Interpret bd close --reason="..." as the canonical resolution/outcome, not an optional comment.
• Ensure it exports consistently under a stable field name (e.g., close_reason, resolution, or outcome).

Why

• This becomes the single most valuable artifact for agents: “what was done and why it worked.”

---

2) Project-level enforcement option: require outcomes on close

Add an opt-in policy flag, e.g.:

// .beads/config.json (or equivalent)
{
  "close_requires_reason": true
}

Behavior

• If enabled, bd close <id> without --reason should error or prompt in interactive mode.

Why

• Lets teams/projects that want compounding knowledge enforce it.
• Default behavior can remain unchanged for existing users.

---

3) Outcome quality guidance in docs / bd close --help

Add short “good vs bad” examples and a minimal checklist:

Good

• what changed (actual change)
• where (module/file/function)
• why (cause/intent)
• validation (verified? how?)

Bad

• “done”
• “fixed it”
• “completed”

---

4) Lightweight structured markers inside the reason string (no schema change)

Standardize optional markers that remain a single string but can be parsed:

• Repro: reproduced | unable | flaky
• Verify: verified | not-verified
• Anchor: module:action

Example:

Fixed null reference in videoPlayer:play by adding guard before play().
Repro: reproduced. Verify: verified. Anchor: videoPlayer:play.

Why

• Enables reliable triage/reporting/search without requiring new storage structures.
• Compatible with “plain text everywhere” workflows.

---

5) Optional: “convenience commands” that write standardized comments/markers

If you want stronger ergonomics while staying backwards compatible:

• bd repro <id> --status=reproduced|failed|flaky → writes a standardized comment
• bd verify <id> --status=verified|failed → writes a standardized comment

Why

• Makes consistent capture easier for agents and humans.
• Avoids inventing new schema primitives; just standardizes the log trail.

---

Semantic Anchors (Convention, Not Enforcement)

Codify module:action as a recommended semantic anchor format that appears in logs, comments, and outcomes:

• Stable across refactors (unlike line numbers)
• Optimized for LLM debugging and cross-session referencing
• Works as an index key for hotspot detection downstream

---

Optional “Outcome Schema” (Soft Enforcement Only)

If the project wants to go slightly further (still as plain text), the “reason” can optionally follow a mini-schema that is human-readable and machine-parsable:

{
  "summary": "Fixed videoPlayer null reference",
  "cause": "play() called before readiness check",
  "change": "Added null guard + readiness gate",
  "verification": "Reproduced → fixed → re-verified via automation",
  "anchors": ["videoPlayer:play"]
}

Adoption model:

• Start with “warn if trivial,” not “block if missing.”
• Tooling can parse it when present; ignore otherwise.

---

Why This Matters

• Outcomes are compounding leverage: they turn one-off debugging into reusable knowledge.
• Consistent resolution capture unlocks higher-quality triage, dedupe, automation, and safer releases.
• BEADS becomes a durable substrate for agent workflows because reproduction and verification state can be inferred reliably.

---

Suggested Implementation Order

1. Docs/help: redefine “reason = outcome” + examples
2. Config flag: close_requires_reason
3. Optional markers: Repro/Verify/Anchor conventions
4. Optional helper commands (bd repro, bd verify)
5. Optional structured outcome schema support (soft)