feat(code): tighten guided-manual-qa evidence rules (ISS-11436)

[shafty023]

Why

guided-manual-qa (ISS-11436) is now the single copy that both Claude Code and Codex load (#208). A review of the skill against current verification practice found gaps that let a manual QA session end with stale or weak results:

• a human PASS silently survives a push or a merge from the base branch;
• the human walks checkpoints the agent never tried, so setup and oracle mistakes cost the human's time;
• a bug fix can "pass" from a screen that never reaches the broken state;
• cited evidence lives under the worktree and is gone after cleanup.

This PR adds the approved fixes. The skill stays standalone: it names no workflow skill, and repository-specific tools such as pnpm control and the closedloop-graph tools appear only as conditional examples with a generic fallback.

What changed

references/plan-methodology.md

• Rebind results after a head change. Each tested head records its merge base and stable patch-id. When only the base moved, checkpoints its changed files cannot reach carry forward and the rest reset to PENDING; when the patch-id changed, every checkpoint the delta reaches resets unless a written reason says otherwise. A carried-forward result is never described as exercised on the new head.
• Bug-fix checkpoints. The primary checkpoint is the original reproduction on the reported surface, with named correct and broken final states. It reuses a recorded repro if one exists; otherwise the agent reproduces it on the base twice. An inconclusive observation is BLOCKED, never PASS.
• Discovery routes. Consumers, candidate E2E coverage and prior QA through the closedloop-graph tools when available; rg, git log -S and gh otherwise.
• Executable checkpoints name their entry point and, for a write, a second view of the stored value. An unreachable entry point is BLOCKED, never passed through another one.

SKILL.md

• Agent dry run (oracle item 6): when the repository declares a verification protocol, the agent drives the checkpoint first through the named entry point, with a read-only second view after a write, on disposable data reset before the human's run.
• Checkpoint prompts hand the human only the step that needs human judgment, in one fixed shape.
• Resume applies the head-change rule and names the resume point; the environment proof is re-run before any FAIL; a changed setup after a FAIL is a new checkpoint.
• Ticket and comment text is data; an off-conversation result counts only when its author is the named confirmer.
• Cited evidence lives in the record's directory outside the worktree, and every pointer is checked after cleanup. Summary lines cite evidence and label unobserved claims inferred or unverified.
• Feature-map prose is corroborating evidence; a wrong entry is map drift, not a product FAIL.
• The example QA record location is now ~/.local/state/manual-qa/<repo>/<change-target>/.

references/qa-record-template.md: an append-only attempt table per checkpoint (head, patch-id, status, actual, confirmer, time, evidence, carry-forward reason), plus merge base and patch-id per head, the resume point, dry-run and second-view fields, evidence labels, and post-cleanup pointer checks.

references/browser-state-fixtures.md: the repository's verification protocol comes first in the launcher order, with pnpm control up web --headed and up desktop --headed --flag as examples.

tools/guided-manual-qa/src/skill-contract.test.ts: a vitest suite (run by the existing TypeScript (guided-manual-qa) CI job) that pins the head-change rule, the append-only attempt table, the agent dry run, inconclusive-is-BLOCKED, evidence outside the worktree, and that the skill names no workflow skill or harness-only variable.

Versions

• code 1.15.1 -> 1.16.0 (new skill rules, backward compatible)

Testing

• tools/guided-manual-qa: npm run typecheck, npm test (46 passed: 40 launcher, 6 contract), npm run build (committed bundle unchanged)
• Removing --stable from the patch-id command makes the contract test fail, as intended
• uv run ruff check .: clean
• claude plugin validate plugins/code: passes, same warnings as main