Enhancement idea: extend forensics Stuck Loop pattern to decisions, with ancestry tracking

[wcvessels]

Hi, I've been using gsd for a few months on solo work and it's become critical to how I run, especially the phase → plan → execute → verify → forensics shape. Floating an enhancement idea that builds on patterns in workflows/forensics.md and workflows/autonomous-smart-discuss.md, filing as a Discussion (per CONTRIBUTING) before any code.

Saw #3232 / #3233. The proposal sits in the workflow layer (forensics + decisions), which current CONTEXT.md and the existing ADRs don't cover. Happy to align with VISION.md and your ADR + test conventions for any code that comes from this.

And yes, I used AI to help me format and structure my thoughts for this post because my brain can otherwise be a mess.

Solo-developer problem addressed

On longer-running projects (multiple milestones, work resumed after weeks away), I've noticed two places where I'd get more leverage out of gsd:

1. When I start a new phase that touches an area with existing locked decisions in CONTEXT.md, those decisions don't always get surfaced into the new conversation early enough to keep me from re-deciding them. references/universal-anti-patterns.md is clear that locked decisions shouldn't be relitigated; in my actual usage I just sometimes forget what's locked, especially after a break.
2. When a later decision intentionally supersedes an earlier one, there's no captured ancestry link, so a few months later I can't easily trace "why did this change?" The information is in commit messages and DECISION_JOURNAL-style files, but it's not queryable in a way that helps a future session.

Both of these feel like extensions of work gsd is already doing.

Patterns this builds on

• workflows/forensics.md Stuck Loop Detection ("same file in 3+ consecutive commits") is the structural template: same shape of detector, applied to decisions instead of file commits.
• workflows/autonomous-smart-discuss.md prior_decisions loader already reads CONTEXT.md and surfaces locked decisions to a new round; it's the natural read-side of a decision registry.
• references/universal-anti-patterns.md already states the immutability stance. The proposal makes it machine-checkable in addition to documented.
• references/agent-contracts.md frontmatter handoffs would carry the new optional ancestry field.

Proposed enhancement

A lightweight Decision Registry that:

1. Reads existing CONTEXT.md decisions through the prior_decisions loader pattern (no new file format required for users; back-compat with projects that don't opt in).
2. At decision-write time, runs a similarity check against the registry. If similarity is above threshold and the new decision contradicts a tier-A locked decision, halts with the same explicit-override pattern map-codebase.md already uses for scan_for_secrets.
3. Tracks ancestry via optional supersedes[] / ancestors[] fields, so the supersession chain is queryable from forensics and from new sessions.
4. Three immutability tiers (A: locked, B: revisable with override, C: working hypothesis), tagged at write time. Conventional rules, not heuristic.
5. Hooks into existing workflows: extends autonomous-smart-discuss.md (read), adds a small write hook callable from any workflow that produces a CONTEXT.md decision, and gives forensics.md a second surface to run oscillation detection over (decisions, not just commits).

Files / system impact

• New: references/decision-registry.md (spec doc), one workflow file or skill exposing the write path, a small JSONL-backed index for the similarity check.
• Modified: workflows/autonomous-smart-discuss.md (adds registry-aware read, falls back to current behavior if registry empty), workflows/forensics.md (oscillation check optionally runs over registry entries), references/agent-contracts.md (adds optional decision_id / supersedes frontmatter fields).
• Untouched: spec-phase ambiguity_model, plan-review-convergence, gates structure, anything in the rendering layer.

User stories

• As a solo dev resuming a project after a few weeks, I'd like the planner to surface decisions relevant to the new phase early in the conversation, so I don't accidentally re-decide them.
• As a solo dev mid-session, when I make a decision that supersedes an earlier one, I'd like the registry to capture the ancestry so the supersession is auditable later without grep.
• As a solo dev running forensics post-incident, I'd like oscillation detection to optionally run over decisions, so "we kept changing our minds" is detectable separately from "we kept editing the same file."

Acceptance criteria (proposed; reshape freely)

• Decision write path produces a registry entry with content hash, tier, ancestors, supersedes, and source workflow.
• Similarity check halts a write when a new entry contradicts a tier-A decision; resolution requires an explicit override mirroring the scan_for_secrets pattern.
• autonomous-smart-discuss.md reads from the registry when present; behavior unchanged when registry is empty.
• Forensics oscillation check works against registry entries with the same shape as the existing commit-based check.
• Tests via runGsdTools() CLI execution, behavioral not text-grep, per CONTRIBUTING.

Alternatives considered

• Pure prose enforcement (status quo). Works for users who read CONTEXT.md every session; slips when context pressure makes that infeasible.
• Decision tags in CONTEXT.md only, no registry. Simpler but doesn't help when the relitigation happens in a session that didn't read all of CONTEXT.md.
• Defer to git log / commit messages. Git tracks code changes; decision ancestry is a different graph. Forensics already had to build its own anomaly detection on top of commits for similar reasons.

Maintenance burden assessment

I'd implement through approved spec → PR → review → one round of post-merge fixes, then hand off ownership. I don't have the bandwidth to sign up for indefinite maintenance or project involvement. The similarity-check backend is the only piece with real ongoing risk. v1 could be substring + frontmatter-tag match (no embeddings) with a hook for an embeddings-based v2 later if that's a direction you want. That keeps day-one maintenance close to zero.

Scope

Deliberately a single subsystem with three small touchpoints in existing files. Not proposing a UI, not proposing a new workflow file, not proposing changes to the planning or review loops. If the scope reads too big, the registry-without-ancestry version is also a sensible starting point.

Would love your read on

• Whether this fits gsd's roadmap direction.
• If it does, what shape you'd actually want. My instinct on tier semantics, similarity check, and write-hook placement may not match how you'd want it to land.
• If it doesn't, totally fine; appreciate the consideration either way.

Thanks for building this; it genuinely changed how I work on solo projects.