feat: execution protocol, review agents, DNS and SES findings

docs/08-execution-protocol.md

@@ -0,0 +1,127 @@
+# 08 — How we work
+
+`AGENTS.md` D17. Pouya architects. Claude Code implements, then adversarially
+reviews its own work. This is a standing agreement encoded in the repository, so
+it does not need restating in every prompt.
+
+---
+
+## The short version
+
+```
+/build the /med-arb/ page
+```
+
+That single command runs: plan → implement → adversarial review → resolve →
+verify → record. It requests deep reasoning, reads `AGENTS.md` and the specs,
+stops if the task conflicts with a locked decision, invokes two independent
+reviewers on the finished diff, resolves what they find, runs the checks, and
+appends the Change Log entry.
+
+You do not need to ask for thinking, for review, or for the record to be updated.
+Those are the agreement, not the request.
+
+## The three commands
+
+| Command | Does |
+|---|---|
+| `/build <task>` | The full loop. Use for every substantive change |
+| `/review [scope]` | The review pass alone, on the working tree or a named scope. Reports; fixes nothing without your say-so |
+| `/wrap` | End of session — updates `AGENTS.md` under its constitution and leaves the tree clean |
+
+## The two reviewers
+
+Both are defined in `.claude/agents/` and run in parallel on the diff.
+
+**`adversarial-reviewer`** reads the code: correctness and edge cases,
+accessibility, crawlability, performance budgets, security, and whether a
+materially simpler correct version exists.
+
+**`claims-auditor`** reads the copy against `AGENTS.md` §4 and nothing else. It
+extracts every factual assertion — credentials, roles, numbers, languages,
+locations, capabilities, and the JSON-LD — and traces each to the Verified table.
+Anything untraceable is reported and does not ship.
+
+It is a separate agent on purpose. A general-purpose reviewer will happily
+approve elegant code containing a claim that should never have been published,
+because professional-conduct compliance is not what it is looking at. On this
+project that is the highest-stakes failure mode, so it gets its own pass.
+
+**Both are instructed to treat uncertainty as a defect.** They will sometimes be
+wrong. That is the intended trade: explaining why a finding is mistaken costs
+minutes, and a missed defect on a licensed professional's public marketing page
+costs a great deal more.
+
+## The rule that makes it work
+
+**The reviewers are given the diff and the specs — never the implementer's
+explanation of why the work is correct.**
+
+A rationale anchors the reviewer. Told why something is right, a reviewer looks
+for confirmation and finds it; given only the artefact, it forms an independent
+view. That independence is the entire mechanism. Every other detail of this
+protocol is adjustable. This one is not.
+
+---
+
+## Writing a task
+
+The commands carry the process, so your prompt only needs to carry the decision.
+Short and specific beats long and hedged.
+
+**Good:**
+
+```
+/build the /med-arb/ page per docs/01-architecture.md
+```
+
+```
+/build step 5 of the build order — the practice index and all six area pages
+```
+
+```
+/build the intake form on /contact/, per docs/05-backend-spec.md.
+Booking stays parked — reserve the slot, render nothing.
+```
+
+**When you are making a decision rather than assigning work**, say so plainly and
+let it record the decision:
+
+```
+Decision: drop the /for-parties/ page. The plain-language audience can be
+served by a section on /mediation/ instead. Update AGENTS.md and the
+architecture spec, then tell me what else this affects.
+```
+
+**When you want an opinion before committing**, ask for one — do not ask for
+code:
+
+```
+Before building /fees/: read docs/07-fees.md and tell me what a referring
+lawyer would find missing from that page. Do not write anything yet.
+```
+
+## What it will do without being asked
+
+- Stop and ask when a task conflicts with a locked decision, or needs a fact it
+  does not have. A blocked build is a correct build.
+- Leave `TODO(pouya)` in the source and a numbered question in `AGENTS.md` §9
+  rather than inventing a fact or softening a claim into something defensible.
+- Surface `AGENTS.md` §12 Standing Reminders at the start of a substantial
+  session — including R1, your standing instruction about the licensure wording.
+- Refuse to publish a claim that is not in the §4 Verified register.
+- Append a Change Log entry covering decisions and plans, not only code.
+
+## What to watch for
+
+**A review that finds nothing.** Possible, but it should be rare, and it must
+list which lenses were applied and what was checked. "Looks good" is not a
+review — send it back.
+
+**Findings declined without a reason.** Declining is legitimate. Declining
+silently is not; the reasoning belongs in the Change Log so a later reader can
+see that judgement was exercised rather than the finding missed.
+
+**A check reported as passing that was not run.** "Should pass" is not a result.
+If a build, a Lighthouse run, or a JavaScript-disabled render was not actually
+executed, it must say so.