Investigate AGENTS.md / docs/plan.html duplication and ownership

[cfuehrmann]

Problem

Two project-governance documents overlap heavily:

• AGENTS.md (149 lines) — the "contract" for anyone (human or AI) making changes: layout, commands, testing doctrine, feature workflow, conventions, migration policy.
• docs/plan.html (710 lines) — the "living plan": issues → remedies, key decisions, architecture, testing strategy, quality gates, CV loop, phases with badges, UX direction, deployment.

They were written from different angles (contract vs. living history) and cover much of the same ground, without an explicit statement of which is authoritative for what.

Observed overlap

• Workflow: AGENTS.md "Workflow for a feature prompt" (6 steps) vs. plan.html "Each phase ends green: gate passes, tests written, targeted mutation run clean on new logic" and the phase checklists.
• Testing doctrine: AGENTS.md "Testing doctrine" (browser e2e as the only public test surface, mutation testing, snapshot testing, CV loop) vs. plan.html sections on testing strategy, quality gates, and the computer-vision loop.
• Repo layout: AGENTS.md "Stack & layout" vs. plan.html "Repo layout".
• Deployment: AGENTS.md "Deploy: push to GitHub, then sudo /opt/flasher/update.sh" vs. plan.html deployment section and deploy/DEPLOY.md.
• Migration policy: AGENTS.md "SQLite migration policy" vs. plan.html "Data & migration".
• Single-user model / dev bypass: described in both.

Risks

• Drift: plan.html is explicitly a living document updated per feature; AGENTS.md is a static contract. A change made in one can silently contradict the other (historical example: AGENTS.md still frames Phase 7 as "the old app remains in git history" — already true, but the status/decision history lives only in plan.html).
• Conflicting authority: an agent or human following AGENTS.md may miss decisions recorded only in plan.html (e.g. review-round deferrals), and vice versa.
• Maintenance cost: keeping both current on every feature is redundant, and the hand-written HTML in plan.html is noisy to diff, which discourages updates.

Questions to answer

1. What is the intended division of labor? Proposal: AGENTS.md = stable process contract (rules applying to every change); plan.html = living status/history (phases, decisions, deferrals). Or the reverse — decide explicitly.
2. Where do cross-cutting rules (testing doctrine, gates, deployment, migration policy) live so there is exactly one authoritative copy?
3. Should plan.html become Markdown (e.g. docs/plan.md) for cheaper diffs and easier maintenance, or stay HTML?
4. How do the two stay in sync: explicit cross-links + a documented convention, a CI check, or consolidation into one file?

Acceptance criteria

• Decision recorded on the ownership/division of labor between AGENTS.md and docs/plan.html
• Duplicated content consolidated to one authoritative source; the other file links to it instead
• The chosen sync convention is documented and applied to the next feature
• The final authoritative process instructions explicitly require models to conduct an independent adversarial review for every non-trivial code change, and preserve that requirement wherever the instructions live. This guardrail is required because a review was missed in an observed case.
• Lighthouse is run for every non-trivial change, with the documented performance and quality thresholds checked before completion.