opencode-swarm 7.122.0 → 7.123.0

package/.opencode/skills/issue-tracer/references/critic-gate.md

@@ -0,0 +1,245 @@
+# Independent Critic Gate
+
+This reference drives three independent gates: the Phase 3 plan critic, the Phase 4.5 implementation review, and the Phase 4.6 final critic. Each is adversarial and independent — it does not improve wording; it tries to prove the work is not done. None of them writes production code.
+
+Every verdict artifact records the exact commit SHA it examined (or, for an uncommitted tree, a diff hash such as `git diff | git hash-object --stdin`). Closure requires the final-approval SHA/hash to equal the shipped HEAD; a later edit invalidates the approval and re-runs the affected gate. Freshness is checked by comparing hashes, never by recollection.
+
+Before any fallback pass: attempt the delegation mechanism and record the verbatim tool-call error, or quote the user/session text forbidding subagents. If authorization is merely unclear and the session is interactive, ask the user. Non-interactive sessions may fall back only with the recorded failure output, stated in the artifact.
+
+## Plan Critic (Phase 3)
+
+Use before presenting the plan to the user. The critic reviews only evidence and plan quality and tries to prove the plan would fail to fully close the issue and its defect class.
+
+### Preferred Invocation
+
+If subagent delegation is available, launch a separate critic with this prompt:
+
+```markdown
+You are an independent critic reviewing an issue-tracer fix plan before implementation.
+
+Your task is to find gaps, unwired functionality, unsupported assumptions, missed edge cases, missing tests, unsafe scope, an under-scoped defect-class sweep, and root-cause errors.
+
+Read these artifacts:
+- 01-issue-summary.md
+- 02-reproduction.md
+- 03-localization-log.md
+- 04-root-cause.md
+- 05-fix-plan.md
+
+Also inspect any files referenced in the plan. Do not trust summaries if the underlying code is available.
+
+Return exactly:
+
+# Critic Review
+
+## Reviewed SHA / diff hash
+[The commit SHA or diff hash of the tree/plan you examined.]
+
+## Verdict
+APPROVE / NEEDS_REVISION / BLOCKED
+
+## Evidence Sufficiency
+[Is root cause proven? What evidence is missing?]
+
+## Plan Correctness
+[Would the selected fix address the root cause?]
+
+## Unwired Functionality
+[Any entry point, export, caller, config, route, UI path, CLI path, docs path, or test path not connected?]
+
+## Edge Cases
+[Missed null/empty/error/concurrent/idempotent/security/backward-compat cases.]
+
+## Defect-Class Sweep
+[Is the anticipated Phase 4.2 sweep scoped to the real class, or too narrow?]
+
+## Test Gaps
+[Positive, negative, regression, integration, fixture, drift, and adversarial gaps.]
+
+## Scope Risk
+[Overreach, underreach, public API, migration, external service, or rollout risks.]
+
+## Required Revisions
+- [Required change or NONE]
+```
+
+### Fallback Invocation
+
+If no independent subagent is available, create `06-critic-review.md` with the same headings (including `## Reviewed SHA / diff hash`) in one clean adversarial pass, prefixed with "Fallback self-critic: independent critic unavailable." Do not leave a stub artifact containing only the disclosure.
+
+### Required Critic Questions
+
+The critic must answer:
+
+1. Does the reproduction actually match the issue, or did the tracer reproduce a nearby symptom?
+2. Is the claimed root cause necessary and sufficient?
+3. Could the fix make the test pass while leaving the real runtime path unwired?
+4. Are all callers/importers/entry points covered?
+5. Are config defaults, feature flags, docs, and generated code surfaces considered?
+6. Are both positive and negative tests included?
+7. Are boundary cases covered: null, empty, missing, malformed, duplicate, concurrent, retry, cancellation, timeout, permission denied, and partial failure?
+8. Does the patch preserve public API and backward compatibility?
+9. Does the plan avoid broad refactors and unrelated cleanup? (The Phase 4.2 defect-class sweep is in-scope by definition and is NOT "unrelated cleanup".)
+10. Is rollback straightforward?
+11. If the fix's exact invocation depends on subtle CLI/subprocess/flag semantics (git flags, gitignore anchoring, shell globs), was the exact candidate invocation empirically verified in an isolated environment — not just asserted as correct?
+12. If the fix scopes or restricts a destructive/broad-acting operation, was it checked against the real target's full blast radius (a dry-run against the actual environment), not only a minimal reproduction?
+
+### Verdict Semantics
+
+- `APPROVE`: No blocker remains. Implementation can proceed after user approval.
+- `NEEDS_REVISION`: The plan is probably fixable, but one or more revisions are required before user approval.
+- `BLOCKED`: The plan lacks enough evidence, has a wrong root cause, requires a product decision, or needs unavailable context.
+
+### Revision Rules
+
+If the critic returns `NEEDS_REVISION` or `BLOCKED`: revise `05-fix-plan.md`, record the response to every critic item, and re-run the critic. Do not present the plan as ready until blockers are resolved or explicitly escalated. **Loop bound:** after three revision cycles without convergence, stop and escalate to the user with both positions and the evidence. Never resolve a deadlock by rewording a blocker.
+
+## Implementation Review (Phase 4.5)
+
+Use AFTER the fix is implemented and validated, to challenge the actual diff. It is independent of the Phase 3 plan critic: the plan critic challenges the plan; this reviewer challenges the real patch and its evidence. The context that wrote the patch must not be the only context that approves it.
+
+### Reviewer Mission
+
+Find a concrete case where the implemented patch is wrong, incomplete, overfits the regression test, leaves a runtime path unwired, misses a defect-class sibling, or regresses an existing contract. Verify claims against the real code and captured command output — do not trust the implementer's narrative.
+
+### Reviewer Inputs (strict)
+
+The reviewer receives ONLY: the full diff, `04-root-cause.md`, `07-approved-plan.md`, `08-test-results.md`, `08a-recurrence-sweep.md`, and the files the diff touches. It is NOT given the implementer's `05-fix-plan.md` reasoning or `06-critic-review.md` narrative — those can anchor the reviewer to the implementer's framing. Open the touched files; do not trust summaries.
+
+### Preferred Invocation
+
+If subagent delegation is available, launch a separate reviewer with this prompt:
+
+```markdown
+You are an independent implementation reviewer for an issue-tracer fix that has already been implemented and validated. Your job is to REFUTE it, not to agree with it.
+
+Inputs (and only these):
+- the full diff (e.g. `git diff origin/<default-branch>...HEAD`)
+- 04-root-cause.md, 07-approved-plan.md, 08-test-results.md, 08a-recurrence-sweep.md
+- the files the diff touches (open them; do not trust summaries)
+
+Find, with concrete evidence:
+- a specific input/environment/caller/sequence where the patch is wrong or incomplete
+- whether the new test would still pass if the bug were only partially fixed (overfitting / plausible-not-correct)
+- any changed path that is not wired into the real runtime path
+- any defect-class sibling the Phase 4.2 sweep missed or misdispositioned
+- any regressed public API, CLI, UI, config, persistence, or concurrency contract
+- any "passed"/"validated" claim not backed by a shown command + output
+- if the fix depends on CLI/subprocess/flag semantics, independently re-run the exact invocation yourself and confirm the observed behavior matches the claim
+- if the fix scopes a destructive/broad-acting operation, independently re-check it against the real target's full blast radius
+
+Return exactly:
+
+# Implementation Review
+
+## Reviewed SHA / diff hash
+[The commit SHA or diff hash you examined.]
+
+## Verdict
+APPROVE / NEEDS_REVISION / BLOCKED
+
+## Correctness vs Root Cause
+[Does the diff fix the documented root cause, or only the symptom/test?]
+
+## Overfitting Check
+[Could the patch be wrong while still passing the new test? Show how or why not.]
+
+## Unwired / Runtime-Path Gaps
+[Entry points, exports, callers, config, routes, CLI/UI paths not connected.]
+
+## Defect-Class Sweep Integrity
+[Did Phase 4.2 characterize the class correctly, sweep completely, and install a guardrail that bites?]
+
+## Contract & Regression Risk
+[Public API, backward-compat, migration, concurrency, security.]
+
+## Evidence Integrity
+[Validation claims not backed by captured command output.]
+
+## Deferred / Scoped-Out / Unwired
+[Any work silently deferred, scoped out, or left unwired. State NONE only if truly none.]
+
+## Required Revisions
+- [Required change or NONE]
+```
+
+### Fallback Invocation
+
+If no independent subagent is available, write `08b-implementation-review.md` using the same headings (including `## Reviewed SHA / diff hash` and `## Deferred / Scoped-Out / Unwired`) in one clean adversarial pass, prefixed with "Fallback self-review: independent reviewer unavailable." Do not leave a stub containing only the disclosure.
+
+### Verdict Semantics
+
+- `APPROVE`: no blocker remains; closure may proceed.
+- `NEEDS_REVISION`: one or more code or evidence changes are required before closure.
+- `BLOCKED`: the patch does not address the root cause, overfits, or needs context/decision the reviewer lacks.
+
+### Revision Rules
+
+Resolve every `NEEDS_REVISION`/`BLOCKED` item by changing code or capturing real evidence, then re-review. Do not downgrade a blocker by rewording it. Record the response to every reviewer item in `08b-implementation-review.md`. **Loop bound:** after three reviewer/critic revision cycles without convergence, stop and escalate to the user with both positions and evidence.
+
+## Final Critic (Phase 4.6)
+
+Use after the implementation reviewer has approved the current diff. This critic challenges the entire completion claim, including code, tests, docs, release notes, package metadata, validation evidence, and the reviewer artifact.
+
+### Preferred Invocation
+
+If subagent delegation is available, launch a separate critic with this prompt:
+
+```markdown
+You are the final critic for an issue-tracer implementation that already passed implementation review. Your job is to prove the completion claim is still wrong.
+
+Inputs:
+- the current full diff
+- 01-issue-summary.md through 08b-implementation-review.md, including 08a-recurrence-sweep.md
+- 08-test-results.md with captured command output
+- all changed files
+
+Check:
+- the reviewer approval is on the latest diff (matching SHA/hash), not an earlier state
+- every NEEDS_REVISION/BLOCKED reviewer item was actually fixed and re-reviewed
+- docs, release notes, package metadata, CLI/API claims, and tests match the implemented behavior
+- the Phase 4.2 guardrail exists and demonstrably bites
+- every acceptance criterion maps to concrete evidence
+- validation claims are backed by commands and output
+- no work was silently deferred, scoped out, or left unwired
+
+Return exactly:
+
+# Final Critic
+
+## Reviewed SHA / diff hash
+[The commit SHA or diff hash you examined; confirm it equals the shipped HEAD.]
+
+## Verdict
+APPROVE / NEEDS_REVISION / BLOCKED
+
+## Completion Integrity
+[Does the current diff satisfy the issue, the Full-Resolution Contract, and the no-gap checklist?]
+
+## Review Freshness
+[Did reviewer approval happen on this exact SHA/hash?]
+
+## Drift Check
+[Any mismatch among code, tests, docs, release notes, package metadata, and final summary?]
+
+## Deferred / Scoped-Out / Unwired
+[Any work silently deferred, scoped out, or left unwired. State NONE only if truly none.]
+
+## Evidence Integrity
+[Any unbacked validation or correctness claim?]
+
+## Required Revisions
+- [Required change or NONE]
+```
+
+### Fallback Invocation
+
+If no independent critic is available, write `09-final-critic.md` with the same headings (including `## Reviewed SHA / diff hash` and `## Deferred / Scoped-Out / Unwired`) in one clean adversarial pass, prefixed with "Fallback final critic: independent critic unavailable." Do not leave a stub artifact containing only the disclosure.
+
+### Verdict Semantics
+
+- `APPROVE`: no blocker remains; closure may proceed if no later edit happens.
+- `NEEDS_REVISION`: one or more code, docs, tests, or evidence changes are required before closure.
+- `BLOCKED`: the completion claim depends on missing context or an unresolved decision.
+
+Any edit after final critic approval invalidates the approval. Re-run implementation review when the edit changes the diff, then re-run the final critic. **Loop bound:** after three reviewer/critic revision cycles without convergence, stop and escalate to the user with both positions and evidence.

package/.opencode/skills/issue-tracer/references/evidence-artifacts.md

@@ -0,0 +1,267 @@
+# Evidence Artifacts
+
+Use these templates to keep the investigation auditable and resumable. In compact mode each template may be a clearly-headed in-thread block with the identical required content — the storage changes, the required content does not.
+
+## `01-issue-summary.md`
+
+```markdown
+# Issue Summary
+
+## Source
+- Issue: [URL or user-provided text]
+- Repo: [owner/repo or local path]
+- Labels: [labels]
+- State: [open/closed/unknown]
+
+## Observed Behavior
+[What actually happens. Include exact errors and stack traces.]
+
+## Expected Behavior
+[What should happen.]
+
+## Reproduction Steps
+1. [Step]
+2. [Step]
+
+## Environment
+- Runtime:
+- OS/platform:
+- Browser/device:
+- Feature flags/config:
+- External services:
+
+## Acceptance Criteria
+- [ ] [Measurable behavior]
+- [ ] [Measurable behavior]
+
+## Ambiguities
+- [Question or missing input]
+```
+
+## `02-reproduction.md`
+
+```markdown
+# Reproduction Evidence
+
+## Commands Tried
+
+### Attempt 1
+- Command:
+- Exit code:
+- Result: CONFIRMED / NOT REPRODUCED / BLOCKED
+
+```text
+[Exact output]
+```
+
+## Minimal Reproduction
+- Test/script/checklist:
+- Why it matches the reported issue:
+
+## Reproduction Verdict
+[Confirmed, blocked, or non-reproducible with reason.]
+```
+
+## `03-localization-log.md`
+
+```markdown
+# Localization Log
+
+## Active Hypotheses
+
+### H1: [Hypothesis]
+- Status: active / confirmed / ruled_out / inconclusive
+- Suspected file/symbol:
+- Evidence for:
+- Evidence against:
+- Commands/tests:
+- Verdict:
+
+## Files Read
+- `path/file.ext:lines` — [why read] — [what was learned]
+
+## Searches Run
+- `<search pattern>` — [result]
+
+## Tests/Commands Run
+- `command` — PASS/FAIL/BLOCKED — [meaning]
+
+## Ruled-Out Paths
+- [Path] — [why ruled out]
+```
+
+## `04-root-cause.md`
+
+```markdown
+# Root Cause
+
+## Summary
+[What failed, where, and why.]
+
+## Exact Location
+- File:
+- Symbol:
+- Lines:
+
+## Broken Contract
+[Invariant or behavioral contract violated.]
+
+## Triggering Conditions
+[Inputs/state/environment required.]
+
+## Evidence Chain
+1. [Symptom]
+2. [Code evidence]
+3. [Command/test evidence]
+4. [Ruled-out alternatives]
+
+## Confidence
+[0–100% with reason. Below 90%, return to localization with a NAMED missing-evidence target instead of guessing. If two hypotheses remain equally supported after a second pass, escalate to the user.]
+```
+
+## `05-fix-plan.md`
+
+```markdown
+# Fix Plan
+
+## Issue
+[Short summary.]
+
+## Root Cause
+[From 04-root-cause.md.]
+
+## Candidate Fixes
+| Candidate | Approach | Files | Pros | Cons | Verdict |
+|---|---|---|---|---|---|
+| A | [Minimal guard/logic/config/state/API fix] | [files] | [pros] | [cons] | selected/rejected |
+
+## Selected Fix
+[Exact behavioral change and why it is necessary and sufficient.]
+
+## Files Expected to Change
+- `path/file.ext` — [exact reason]
+
+## Impact Analysis
+- Callers/importers:
+- Tests/fixtures:
+- Config/docs:
+- API/UI/CLI:
+- Persistence/migrations:
+- Security/privacy:
+- Concurrency/idempotency:
+
+## Anticipated Defect-Class Sweep (Phase 4.2)
+- Pattern statement (draft):
+- Search predicates (draft):
+- Guardrail rung intended:
+
+## Edge Cases
+- [edge] — covered by [test/check]
+
+## Test Plan
+1. [Failing regression test]
+2. [Impacted suite]
+3. [Lint/type/build/security checks]
+
+## Unwired Functionality Checklist
+- [ ] Entry point reaches new/changed logic.
+- [ ] All callers use the updated contract correctly.
+- [ ] Error path is observable and handled.
+- [ ] No new branch lacks tests or manual verification.
+- [ ] Documentation/comments match actual behavior.
+
+## Risk and Rollback
+- Risk:
+- Rollback:
+
+## Critic Status
+- Critic verdict:
+- Required revisions:
+```
+
+## `06-critic-review.md`
+
+Use `references/critic-gate.md` (Plan Critic section). The artifact records the reviewed SHA/diff hash and a verdict.
+
+## `07-approved-plan.md`
+
+```markdown
+# Reviewed Plan Awaiting Approval
+
+[Copy final 05-fix-plan.md here.]
+
+## User Approval
+- [ ] User explicitly approved implementation on [date/time/session note]
+```
+
+## `08-test-results.md`
+
+```markdown
+# Test Results
+
+## Regression Test
+- Command:
+- Before fix: FAIL / not run with reason
+- After fix: PASS / FAIL
+
+## Impacted Tests
+- Command:
+- Result:
+
+## Quality Checks
+- Lint:
+- Typecheck:
+- Build:
+- Format:
+- Security/static checks:
+
+## Deferred-Work Scan
+- Command: `.opencode/skills/issue-tracer/scripts/scan-deferred.sh`
+- Result: [clean, or each hit + disposition]
+
+## Verification Reasoning
+[Why the fix is correct beyond merely making tests pass.]
+
+## Test Drift Review
+[Any stale tests found and how they were handled.]
+```
+
+## `08a-recurrence-sweep.md`
+
+```markdown
+# Recurrence Sweep and Guardrail
+
+(If the change corrects no incorrect behavior/data/docs — pure style/naming — record "no defect class" with a one-line justification and stop here.)
+
+## Defect Class
+[One-sentence pattern statement: the shape of the mistake — API misused, guard omitted, contract assumed, encoding confused — not the site of it.]
+
+## Predicates and Results
+- Predicate 1: `<rg/AST/type query>`
+
+```text
+[Full result set. An empty result is evidence only if the predicate is shown.]
+```
+
+## Dispositions
+| Hit (file:line) | Disposition | Justification |
+|---|---|---|
+| path:line | FIX / FALSE_POSITIVE / OUT_OF_CLASS / DEFERRED_WITH_USER_APPROVAL | [why; for DEFERRED: tracked issue link + quoted user acknowledgment] |
+
+## Guardrail
+- Rung chosen: [lint/static rule > type constraint > runtime/trust-boundary assertion > CI check > documented invariant + regression family]
+- Infeasibility reasons (required if landing on either of the two weakest rungs): [why each stronger rung is infeasible for this class — "faster" is not a reason]
+- Demonstration: [revert-check / mutation / synthetic instance] — captured output showing it FAILS on the original defect and PASSES on the fixed code.
+```
+
+## `08b-implementation-review.md`
+
+Use `references/critic-gate.md` (Implementation Review section). The artifact records the reviewed SHA/diff hash, a verdict, and the `## Deferred / Scoped-Out / Unwired` finding.
+
+## `09-final-critic.md`
+
+Use `references/critic-gate.md` (Final Critic section). The artifact records the reviewed SHA/diff hash (confirmed equal to shipped HEAD), a verdict, and the `## Deferred / Scoped-Out / Unwired` finding.
+
+## `10-pr-body.md`
+
+Use `assets/pr-template.md`, including the `## Acceptance Criteria → Evidence` map and the `## Waivers (or none)` section.

package/.opencode/skills/issue-tracer/references/install.md

@@ -0,0 +1,63 @@
+# Install and Version Reconciliation
+
+This skill is distributed as ONE canonical source with thin per-agent adapters. This reference documents where each of the five supported agents discovers the skill, how user-level installs can shadow the project copy, and how to reconcile a stale copy against the canonical version stamp.
+
+The canonical version is the `metadata.version` field in the canonical `SKILL.md` frontmatter. Treat that stamp as the source of truth: when two resolvable copies disagree on `metadata.version`, the lower one is stale and must be reconciled.
+
+## Discovery per agent (project-level)
+
+| Agent | Loads (project-level) | Resolves to |
+|---|---|---|
+| OpenCode | `.opencode/skills/issue-tracer/SKILL.md` | canonical |
+| Claude Code | `.claude/skills/issue-tracer/SKILL.md` | adapter shim → canonical |
+| OpenAI Codex | `.agents/skills/issue-tracer/SKILL.md` | adapter shim → canonical |
+| ZCode | `.agents/skills/issue-tracer/SKILL.md` | adapter shim → canonical |
+| GitHub coding agent | repo-root `AGENTS.md` pointer | canonical |
+
+The adapter shims are one-line pointers to `../../../.opencode/skills/issue-tracer/SKILL.md`; they carry no protocol of their own, so a project checkout always executes a single canonical body.
+
+### Agent Adapter table — how each row was filled
+
+The canonical SKILL.md's Agent Adapter table maps each capability to a concrete tool per agent. Those rows were filled from each agent's current tool surface: OpenCode (`edit`/`write`, `todowrite`, `webfetch`, `task`), Claude Code (`Edit`/`Write`/`MultiEdit`, `TodoWrite`, `WebFetch`/`WebSearch`, `Agent`/`Task`), OpenAI Codex (`apply_patch`, `update_plan`, `web`), and the GitHub coding agent (`edit`, built-in task list, `web`). **ZCode** is mapped to the Codex-native tool surface (`apply_patch`/`update_plan`/`web`) because it is a Codex-family CLI that shares the project-level `.agents/skills/` discovery tree with Codex; if your ZCode build exposes different tool names, treat the table as capability-first and substitute your build's names.
+
+## User-level installs can SHADOW the project copy
+
+Several CLIs also search a user-level (home-directory) skills root in addition to the project root, for example:
+
+- Claude Code: `~/.claude/skills/issue-tracer/`
+- ZCode: `~/.zcode/skills/issue-tracer/`
+- Codex: `~/.codex/skills/issue-tracer/` (or the runtime's configured user skills root)
+- OpenCode: the user-level OpenCode config skills root
+
+Resolution precedence between the project copy and a same-named user-level copy **varies by CLI and CLI version**, and some resolve the user-level copy first. That makes a **stale user-level copy the dangerous case**: it can silently shadow the up-to-date project canonical, so the agent runs an old protocol (missing, e.g., the Full-Resolution Contract or the Phase 4.2 sweep) while the repository looks correct. Do not assume project-wins; verify with the version stamp.
+
+## Reconcile against `metadata.version`
+
+Read the canonical stamp first:
+
+```sh
+grep -A2 '^metadata:' .opencode/skills/issue-tracer/SKILL.md | grep 'version:'
+```
+
+Then, for each CLI you use, compare the user-level copy's stamp to the project canonical and remove or refresh the user-level copy if it is older or absent-of-stamp (a legacy fork with no `metadata.version` is by definition stale):
+
+```sh
+# Claude Code
+diff <(grep 'version:' ~/.claude/skills/issue-tracer/SKILL.md 2>/dev/null || echo 'version: none') \
+     <(grep 'version:' .opencode/skills/issue-tracer/SKILL.md) \
+  && echo 'in sync' || echo 'STALE user-level copy — remove ~/.claude/skills/issue-tracer or re-sync it'
+
+# ZCode
+diff <(grep 'version:' ~/.zcode/skills/issue-tracer/SKILL.md 2>/dev/null || echo 'version: none') \
+     <(grep 'version:' .opencode/skills/issue-tracer/SKILL.md) \
+  && echo 'in sync' || echo 'STALE user-level copy — remove ~/.zcode/skills/issue-tracer or re-sync it'
+
+# Codex
+diff <(grep 'version:' ~/.codex/skills/issue-tracer/SKILL.md 2>/dev/null || echo 'version: none') \
+     <(grep 'version:' .opencode/skills/issue-tracer/SKILL.md) \
+  && echo 'in sync' || echo 'STALE user-level copy — remove ~/.codex/skills/issue-tracer or re-sync it'
+```
+
+The safest default is to keep no user-level `issue-tracer` copy at all and let each project ship its own canonical, so version drift cannot occur. If you do keep a user-level copy, reconcile it whenever the project canonical's `metadata.version` changes.
+
+GitHub coding agents load the repository's checked-in `AGENTS.md` and `.opencode/skills/issue-tracer/SKILL.md` directly, with no user-level home directory, so shadowing does not apply to that surface.

package/.opencode/skills/issue-tracer/references/localization-playbook.md

@@ -0,0 +1,95 @@
+# Localization Playbook
+
+Use this playbook during Phase 2. The goal is not to read the most code. The goal is to build the shortest evidence chain from symptom to root cause.
+
+## Tier 1: Trace-Driven Localization
+
+Use when the issue includes a stack trace, failing test output, panic, exception, compiler error, log line, request ID, or command output.
+
+1. Extract file paths, symbols, line numbers, route names, command names, config keys, and exact error strings.
+2. Start from the first project-owned frame, not framework/library frames.
+3. Read the frame, its immediate caller, and any input validation or error-mapping code.
+4. Confirm whether the visible crash site is the cause or only the symptom.
+5. If the trace points to generic error handling, walk backward to the first domain-specific invariant break.
+
+Common trace interpretations:
+
+- Null/undefined/type errors often originate at a missing guard or wrong contract before the crash line.
+- Index/bounds errors often originate in filtering, slicing, pagination, or off-by-one logic.
+- Assertion failures often indicate an upstream invariant break.
+- Timeout/deadlock symptoms require call-chain, lock, retry, cancellation, and external-service review.
+- Serialization errors often require checking both producer and consumer schemas.
+
+## Tier 2: Semantic and Structural Localization
+
+Use when the stack trace is missing, generic, misleading, or incomplete.
+
+1. Convert issue text into search terms:
+   - user-visible strings
+   - endpoint names
+   - component labels
+   - command flags
+   - config names
+   - domain nouns and verbs
+2. Search broadly, then narrow, using your repository search tool:
+   - the exact error string
+   - the route or command name
+   - domain terms, config keys, flags
+   - tracked-symbol confirmation
+3. Build a candidate file table: file, relevant symbol, why it could cause the symptom, confidence, next evidence needed.
+4. Inspect dependency direction: who calls this code, what this code calls, where state/config enters, where errors are transformed.
+5. Use git archaeology sparingly but deliberately:
+   - `git log --oneline -- <path>`
+   - `git show <commit> -- <path>`
+   - `git blame -L <start>,<end> -- <path>`
+
+## Tier 3: Hypothesis-Driven Localization
+
+Use when multiple plausible locations remain.
+
+1. Generate 2–5 competing hypotheses.
+2. For each hypothesis, define the evidence that would confirm it and the evidence that would falsify it.
+3. Test hypotheses in likelihood order.
+4. Keep no more than three active hypotheses.
+5. Do not preserve weak hypotheses once evidence contradicts them.
+
+Hypothesis format:
+
+```markdown
+### H[N]: [short name]
+The bug is in `path:symbol` because [specific condition] violates [specific contract], causing [reported symptom] when [triggering input/state].
+
+- Confirm if:
+- Falsify if:
+- Evidence:
+- Verdict:
+```
+
+## Granularity Rules
+
+Localize at multiple levels before planning a patch:
+
+1. File-level: which file owns the failing behavior.
+2. Element-level: which function/class/config/test helper is responsible.
+3. Line-level: which condition, call, assignment, invariant, or boundary check is wrong.
+
+Function or element-level evidence is usually the most useful planning granularity. Line-level evidence is required before editing, but avoid overfitting the plan to one line if the issue is a broken contract across a whole function.
+
+## Call-Chain Exploration
+
+When the failure propagates across components:
+
+1. Start at the failing entry point.
+2. Follow calls one layer at a time.
+3. At each layer, ask: what data enters, what contract is assumed, what state changes, what errors are swallowed/transformed, what output leaves.
+4. Backtrack when evidence weakens.
+5. Record pruned branches in `03-localization-log.md`.
+
+## Stop Conditions
+
+Stop localization and escalate if:
+
+- the root cause requires unavailable production-only data
+- two hypotheses remain equally supported after a second pass
+- the issue requires a product decision rather than a code correction
+- the suspected fix crosses subsystem boundaries beyond the approved scope

package/.opencode/skills/issue-tracer/references/method-provenance.md

@@ -0,0 +1,13 @@
+# Method Provenance (state of the art)
+
+The quality methods in this skill are grounded in current agentic-repair and agent-reliability research, adapted to a plan-first, evidence-first, full-resolution workflow:
+
+- Hierarchical file → function → line localization, multi-sample candidate patches, and validate-then-select repair: Agentless (Xia et al. 2024, https://arxiv.org/abs/2407.01489).
+- Reasoning-guided, explanation-ranked fault localization (a causal explanation per candidate, not surface similarity): RGFL (https://arxiv.org/pdf/2601.18044); structure/spectrum-aware search: AutoCodeRover (https://arxiv.org/abs/2404.05427).
+- "Tests passing is plausible, not correct" / patch overfitting: patch-correctness survey (https://dl.acm.org/doi/10.1145/3702972).
+- Self-consistency across independent passes: Wang et al. 2022 (https://arxiv.org/abs/2203.11171).
+- A fresh independent context refutes the result (the doer is not the grader) and evidence-grounded reporting (show the command and its output, do not assert success): Anthropic, "Effective harnesses for long-running agents" (https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
+- Plan → implement → review separation as explicit quality gates: Anthropic, "Building Effective Agents" (https://www.anthropic.com/research/building-effective-agents).
+- Escalate when the issue lacks reproducible steps or acceptance criteria (issue clarity predicts resolution success): GitHub coding-agent best practices (https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/best-practices-for-using-copilot-to-work-on-tasks).
+
+Recurrence-class eradication (Phase 4.2) generalizes the "fix the class, not the instance" principle: a single-site repair that leaves the defect class searchable and reintroducible has not closed the issue's real surface. The guardrail ladder (static rule → type constraint → runtime/trust-boundary assertion → CI check → documented invariant + regression family) prefers machine-enforced prevention over human vigilance.