Issue root resolution

Issue Root Resolution

A cluster is resolved when the mechanism that permits it is removed or guarded at the correct boundary, each affected report has executable evidence, and the implementation remains faithful to Rembric's specifications and invariants. Do not turn a cluster into a collection of symptom patches.

1. Establish the current mechanism

Work from current origin/main, not an issue's historical description.

1. Read full issue bodies, comments, linked PRs, and relevant OpenSpec specs.
2. Reproduce every candidate root through a real caller boundary; include a passing control in the same run.
3. Make a read-only mechanism map before editing. Every claim gets a file:line anchor and explains what happens today, not what the issue says should happen.
4. Record report date and the commit/release being tested. A pre-fix report is not evidence that the current build remains broken.

If the map contradicts the report, say so. The symptom may be valid while the proposed mechanism is wrong; strengthen the repro until it distinguishes them.

2. Shape the smallest root fix

Rank alternatives in this order:

1. remove the mechanism, making the whole class impossible;
2. add a static/invariant guard that makes reintroduction fail;
3. apply a local predicate fix behind a failing real-surface reproduction;
4. only when evidence rules out the above, add a new state, flag, command, compatibility path, or other lasting surface.

For every option that adds surface, explain why a deletion/relaxation shape cannot work. Do not add a parallel representation of truth: memory lifecycle, project scope, and topic convergence already have authoritative locations.

Apply these Rembric constraints while designing:

• Scope is resolved at the service layer. New MCP tools use resolveEffectiveScope; handlers do not construct scopes or infer a default.
• Append-only data remains append-only: do not DELETE memory rows or update content to correct a defect. Use existing lifecycle/replacement semantics.
• SQL belongs in src/db/, services own transactions, and scoped repository methods require Scope.
• A behavioural change, new MCP tool, or invariant change needs an OpenSpec change before implementation. Table-rebuild migrations rely on the runner's FK-safety dance; do not reproduce it ad hoc in a migration.
• Plugin work must preserve one shared implementation across five clients; read rembric-plugin-development before changing apps/plugin/.

Write unresolved maintainer choices as explicit decision items with a recommended default. An existing decision in an issue, spec, or accepted design outranks a new plan table.

3. Implement with proof, not confidence

Make independently reviewable slices, ordered by root mechanism rather than by issue number. For each slice:

1. Turn the minimized real scenario into a failing regression test at the right seam. Confirm it fails before the fix.
2. Apply the smallest change that addresses the root.
3. Run the test, its control, relevant typecheck/lint, and the original repro.
4. When HTTP, MCP, migrations, or client integration changed, run the relevant real-stack smoke from rembric-smoke-tests.
5. Inspect every worker/subagent diff and independently re-run its key proof. A report of success is not evidence.

A new guard is unproven until weakening each condition makes the test that names it fail. Use scripts/mutate.mjs where it fits; a test green on both sides of the change does not establish the guard.

4. Verify and close precisely

For each issue, select exactly one closure basis:

Basis	Required evidence
Fixed	Merged commit/PR and a named passing test/repro on current build
Superseded	Recorded maintainer decision or OpenSpec change that replaces the request
Surface retired	Current-build proof that the affected public surface no longer exists
Duplicate	Canonical issue with its own fixed evidence
Not closable	Missing reproduction, unmerged dependency, or a distinct unresolved root

Do not close an issue whose fix is merely in an unmerged PR. Do not call an issue stale only because its original mechanism disappeared: verify the reported outcome on the current build first. For multi-part reports, document the split and leave the remaining part open.

Before a public closure comment or final report, run the cited evidence yourself and name both the test and the boundary it exercises. Include a reopen path for a current reproduction.

Report format

Deliver a concise resolution packet:

1. Roots table: root | issues | current state | mechanism-map anchors.
2. Plan: deletion-first fix shape, OpenSpec/decision items, owners, and independently revertible slices.
3. Evidence matrix: issue | closure basis | proof run | result.
4. Borderline items: what is still unknown or blocked, and the next exact probe.
5. Verification summary: commands run, controls, smoke results, and any compatibility/migration/client surfaces checked.