chamba 0.6.1 → 0.7.0

package/templates/skills/dx-spec/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: dx-spec
+description: Build a work specification in the Specs tab of this session's web pane, or pick up one in progress. Every step the user answers is a form on that tab. User-invoked only.
+disable-model-invocation: true
+argument-hint: "[what the work is, or the name of a piece of work to pick up]"
+---
+
+# dx-spec - build a work specification
+
+This skill runs when the user types `/dx-spec`. It never starts on its own.
+
+The skill turns work into a spec directory the Specs tab shows.
+A fresh agent opens that directory later and builds the work from it, without asking the user anything, even though it never saw this conversation.
+Everything is on disk, so the work stops at any point and continues in a later session, with any agent.
+
+**This skill plans. It does not build.**
+Do not edit application code while it runs, whatever the request asks for.
+`/dx-spec-execute` builds the work after the spec is ready.
+
+## The web session
+
+This family runs inside a chamba web session, where the Specs tab holds the work.
+Check for one before anything else:
+
+```
+specs stages
+```
+
+The answer holds `root` - the directory the tab serves - and the stage catalog.
+A refusal means there is no pane.
+Say this and stop:
+
+> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then run `/dx-spec` there.
+
+Start no flow, and offer no substitute.
+There is one flow, and it needs the tab.
+
+## The one hard rule
+
+**Everything you ask the user goes on the Specs tab.**
+The tab draws the form, the user answers it there, and the answer comes back as a file.
+`specs await` is how you ask.
+Nothing you ask the user is a message in this terminal, and nothing is an `AskUserQuestion` call.
+
+Three shapes, and one mechanism under all of them:
+
+- A **gate** judges one artifact. The user approves it, or asks for changes with the words that say what to change.
+- A **round** asks questions. Each question carries its options, whether one answer or several are allowed, and a box of its own for anything the options missed.
+- A **decision card** carries a finding that needs the user's judgment: the evidence, the trade-off, and apply or dismiss.
+
+Ask, then stop.
+Declaring something is the end of your turn.
+The pane types one line into this terminal when the user answers, and that line is what starts you again.
+Do not poll, and do not carry on with the thing the question was there to settle.
+
+You write to the user in plain messages in exactly four places:
+
+- The **collect invitation** - one short line that asks what the work is.
+- The **exploration stage** - thinking out loud is its whole point.
+- A **line of fact** the user needs before a form makes sense, sent in the same turn as the form.
+- The **closing line** that ends the run.
+
+**Raise a doubt. Never guess at it.**
+Do not settle a doubt on your own while a spec is being built, however small it looks.
+A fresh agent builds from this spec without asking anything, so a doubt this session swallows becomes a wrong build later.
+
+Raise a doubt in one of three ways, by where it comes up:
+
+- Outside a stage that writes `SPEC.md`: ask it in the next round.
+- Inside a stage that writes `SPEC.md`: queue it in place as a `[NEEDS CLARIFICATION: ...]` marker, and ask it at the next round or gate, once it clears the bar in `references/spec-guide.md`.
+- Below that bar: write it to disk as a labeled assumption, naming the guess you made.
+
+The same rule covers any other guess that has to stand: label it on disk, so no choice stays silent.
+
+## The tool owns the state
+
+The Specs tool writes `state.json` and the `README.md` of each spec directory.
+**Never edit either one.**
+Never write a protocol list, a stage checkbox, a status line or a log line by hand.
+You move the work with the verbs below, and the tool writes both files in the same act, so the board in the pane and the file in git cannot disagree.
+
+Everything else in the spec directory is yours: `spec/SPEC.md`, the research, the mocks, the plan, the review, and the visuals beside them.
+
+## The verbs
+
+`specs <verb> [<spec>]` takes JSON on stdin where a verb needs a payload, and answers JSON on stdout.
+`<spec>` is the directory name the tab shows.
+
+```
+specs stages                              where the specs live, and the stage catalog
+specs state <spec>                        where the work stands, and what awaits the user
+echo '<json>' | specs intake              file a new piece of work
+echo '<json>' | specs propose <spec>      recommend a protocol, and put it to the user
+echo '<json>' | specs await <spec>        declare a gate, a round or a decision card
+echo '<json>' | specs post <spec>         say what is happening
+echo '<json>' | specs review <spec>       post one round of quality review
+echo '{"id":"<id>"}' | specs answers <spec>   read back what the user answered
+```
+
+**Filing an intake:**
+
+```json
+{ "name": "Checkout discounts", "text": "everything the user said, in their words", "attachments": [] }
+```
+
+The answer is `{ "entry": "checkout-discounts", "path": "checkout-discounts/intake.md" }`.
+An attachment is `{ "name": "sketch.png", "type": "image/png", "data": "<base64>" }`.
+
+**Recommending a protocol:**
+
+```json
+{ "stages": [{ "id": "interview", "recommended": true, "why": "the scope has open edges" }], "note": "" }
+```
+
+Name every stage you have an opinion about.
+The form shows the whole catalog either way, so the user sees what you did not recommend.
+
+**Declaring a round:**
+
+```json
+{ "id": "interview-1", "kind": "round", "title": "A few things about the checkout", "file": "",
+  "payload": { "kind": "round", "questions": [
+    { "id": "scope", "ask": "Which orders can be partly cancelled?", "multi": false,
+      "invite": "Anything the options miss?",
+      "options": [
+        { "id": "any", "said": "Any order, at any time", "recommended": true },
+        { "id": "unshipped", "said": "Only an order nothing has shipped from" } ] } ] } }
+```
+
+**Declaring a gate:**
+
+```json
+{ "id": "spec-gate", "kind": "gate", "title": "Does the spec look right?", "file": "spec/SPEC.md",
+  "payload": { "kind": "gate", "asks": "Approve it, or say what to change." } }
+```
+
+`file` is the artifact the gate judges, relative to the spec directory.
+The tab opens that artifact and puts the gate under it.
+
+**Declaring a decision card:**
+
+```json
+{ "id": "rv-04", "kind": "gate", "title": "The plan leans on one mechanism", "file": "plan/PLAN.md",
+  "payload": { "kind": "decision",
+    "evidence": "what was found, and what it rests on",
+    "tradeoff": "what each way costs" } }
+```
+
+**Posting progress:**
+
+```json
+{ "kind": "activity", "said": "Reading the checkout code" }
+{ "kind": "stage", "stage": "codebase-analysis", "status": "done", "artifacts": ["spec/SPEC.md"] }
+{ "kind": "status", "status": "ready" }
+{ "kind": "note", "said": "one dated line for the log" }
+```
+
+Post an activity when you start something that takes a while, so the board says what is happening.
+Post a stage as `running` when it starts, and as `done` with its artifacts when it ends.
+
+**Reading an answer back:**
+
+```json
+{ "outcome": "approved", "said": "", "questions": [] }
+```
+
+An outcome is `approved` or `changes` for a gate, `apply` or `dismiss` for a decision card, and `answered` for a round.
+A round's answer carries one line per question, and a question the user left alone is there too, marked `"answered": false`.
+Treat that as skipped. It is not a "no".
+`{ "answer": null }` means the user has not answered yet.
+
+## Writing a question
+
+The pane's form has no limit on questions or options, so ask the whole round at once rather than in a chain of small ones.
+Every question still follows these rules:
+
+- Write for someone who has never used these skills.
+- Do not use internal terms - directory layout, phase files, stage names - unless the option explains them in the same breath.
+- Put the option you would choose first, and mark it `"recommended": true`.
+- Keep an option's `said` short. Put the reasoning and the trade-off in the question's `ask`.
+- Where a real trade-off exists, lay it out and let the user decide. Never decide it silently.
+- Give every question an `invite` when a typed answer would be worth more than a choice.
+
+Give each round and each gate an id that says what it is: `interview-1`, `spec-gate`, `mocks-gate`.
+An id is answered once. Ask again with a new id.
+
+## What a finished spec is
+
+A complete spec lets a fresh agent open the directory with no other context and know what to build.
+That agent learns where the edges are, how to tell the work is done, and roughly where the code goes.
+No question for the user is left.
+Aim for a production-grade spec every time.
+
+## What is on disk
+
+The tab serves one root, and each piece of work is one directory under it.
+
+```
+<root>/
+  principles.md          the settings and principles, owned by /dx-spec-config
+  <slug>/
+    README.md            written by the tool, from the state - never by you
+    intake.md            what the work started as
+    spec/
+      SPEC.md            the specification
+      *.md, *.svg        what the user shared, and visuals written beside the spec
+    research/RESEARCH.md written by the research stage
+    mocks/<mock-id>.html one standalone page per screen
+    plan/PLAN.md         the execution plan, plus one file per phase during the run
+    review/REVIEW.md     the quality review report
+  archive/
+    YYYY-MM-DD-<slug>/   work that is finished and signed off
+```
+
+A stage directory appears when its stage writes something. Nothing is created empty.
+
+## A page you make during this work
+
+You may draw a page to explain something - a flow, a comparison, a diagram.
+During spec work, that page belongs to the spec, so save it into the spec directory under a lowercase name.
+The tab lists it beside the other artifacts and renders it, and the user comments on it there.
+Do not publish it to the Pages tab: a page on Pages belongs to this conversation, and this one belongs to the work.
+
+Outside spec work, `webpane` and the Pages tab are the right home for a page.
+
+Keep a page standalone: no external stylesheet, no script that fetches anything, and images as data URLs.
+
+## Flow
+
+Run the bootstrap in `../dx-spec-config/SKILL.md` before step 1.
+It resolves the root, reads the principles file, offers the one-time setup when there is none, and gives you the settings for the rest of the run.
+
+### 1. Start
+
+The user reaches this skill in one of three ways.
+
+**A line arrived from the pane.** The user filed an intake on the tab, and the terminal carries one line naming the file. Read that file, and go to step 3.
+
+**The user passed text.** Treat it as their opening input. When it names a piece of work that already exists, go to step 2.
+
+**Nothing.** Read the root with `specs stages`.
+With one piece of work or more there, declare a round that asks which one, with one option per directory and one for something new.
+Declare it on the piece of work that changed last.
+Every asking verb names a spec, and there is no spec for "which spec" - so the round sits on a real one, and the tab shows it wherever the user is.
+Never name an empty spec or a spec that is not there: the verb refuses it, and the question is not asked at all.
+With nothing there, go straight to the collect invitation in step 2.
+
+### 2. Collect
+
+Let the user say everything they have before you ask anything.
+
+Send this invitation as one short message, in these words:
+
+> Tell me about the work. Paste everything you have - notes, links, screenshots, file paths, snippets, examples, prior art - in one go, and I'll take it from there.
+
+Then end your turn and wait.
+Skip the invitation when their opening input already covers it.
+
+With their input in, file it:
+
+```
+echo '{"name":"<a working name>","text":"<everything they said>","attachments":[]}' | specs intake
+```
+
+The tool makes the directory, writes `intake.md`, and starts the state file.
+The tab opens on it.
+
+### 3. Pick up work in progress
+
+Read `specs state <spec>` and every artifact in the directory.
+The state says which stages were confirmed, where each one stands, and what is waiting for the user.
+
+`.specs/user-feedback.json` in the directory holds annotations the user sent that nobody has applied.
+Apply them as `references/stages.md` defines, before anything else.
+
+Then declare a round: what the work is, where it stands, and what happens next - continue, redo something, or change the steps.
+
+### 4. Choose the protocol
+
+Read what the input points to in the codebase, enough to judge the shape and the size of the work.
+
+Then recommend the stages this work needs:
+
+```
+echo '{"stages":[...],"note":""}' | specs propose <spec>
+```
+
+Give every stage you recommend a `why` of one sentence, in the user's terms.
+The form shows the whole catalog, recommended or not, so the user sees the choice whole.
+Confirming writes the protocol into the state, in catalog order.
+
+Rough rules for what to recommend:
+
+- A bug fix: codebase analysis and an execution plan.
+- A small feature or a chore: interview, codebase analysis, execution plan.
+- A new user-facing feature: exploration, interview, codebase analysis, technical specs, UI mocks, execution plan.
+- Work in a subject you or the user do not know well: add research.
+- Pure thinking, or one decision to make: exploration, maybe research, and no plan.
+- Large or risky work: add the quality review. Many phases, several stages feeding one spec, or anything that touches security, data or money.
+
+The pane offers imagination mode when the confirmed protocol holds exploration or UI mocks.
+Read `references/imagination-guide.md` when the state comes back with `modes.imagination` true, when the user asks for the mode by name, and at no other time.
+
+Save what the user shared into `spec/` under lowercase names of their own.
+
+### 5. Run the stages
+
+Run the stages in the order the confirmed protocol lists.
+`references/stages.md` defines each one.
+Read a stage's section when the stage starts, and run the stage from that definition: it carries gates and rules the stage name alone does not state.
+
+Every stage that writes into `SPEC.md` also uses `references/spec-guide.md`.
+
+Post the stage as `running` when it starts.
+Post it as `done` with its artifacts when its gate is approved.
+Every stage ends at a gate, except codebase analysis, which feeds the next stage and has none.
+
+Every gate also clears the open markers.
+Before you declare a gate, read `SPEC.md` for open `[NEEDS CLARIFICATION: ...]` markers.
+Put them in the same round as the gate, in the priority order in `references/spec-guide.md`.
+Each answer replaces its marker in `SPEC.md` in the same round.
+This is what makes every marker reach the user.
+Codebase analysis has no gate, so what it opens is asked at the gate of the stage after it.
+The interview asks its own markers in its own rounds.
+
+### 6. The coherence rewrite
+
+Before the finalize gate, rewrite what the work changed after it was first written.
+`references/spec-guide.md` defines this step: when it runs, what it produces, and the one round of review that follows it.
+
+### 7. Finalize
+
+Read every file in the spec directory from start to end, and check:
+
+- Every assumption and open question is labeled.
+- No two files disagree.
+- Each requirement carries its own acceptance criterion, where the spec carries requirement IDs.
+- Every ID appears in some phase's `Covers` line, where the protocol includes the execution plan.
+
+Skip `mocks/candidates/`: it holds directions nobody chose.
+
+When `review/REVIEW.md` is there, this read covers less ground.
+Read the parts no reviewer saw: the fixes the stage made, and the edits that came from the user's decisions at the review gate.
+Treat the rest as covered, because the review stage ran the deeper version of this check over it.
+
+Ask any marker still open in `SPEC.md` before the gate.
+The gate does not pass while a marker stays open.
+
+Then declare the finalize gate on `spec/SPEC.md`, saying what the spec covers in a sentence or two.
+On changes: revise, and declare a new gate.
+Loop until the user approves it.
+
+After they approve:
+
+```
+echo '{"kind":"status","status":"ready"}' | specs post <spec>
+```
+
+Then declare one last gate: whether to commit the spec.
+On approval, stage the spec directory by path and commit it with a one-line message.
+Compose the message from the commit style in the principles file, with "spec ready" as its descriptive part.
+Commit only. Never push.
+Staging by path leaves every other change in the working tree alone.
+
+Close with one short message: what the spec covers, where it is, whether it was committed, and, when a plan exists, that `/dx-spec-execute` runs it.

package/templates/skills/dx-spec/references/imagination-guide.md

@@ -0,0 +1,140 @@
+# Imagination mode
+
+This file holds imagination mode for `/dx-spec` (`SKILL.md` in the directory above).
+Read it when the mode is on, or when the user asks for it by name, and not before.
+
+## What the mode is
+
+Imagination mode is a budget for divergence.
+A normal run narrows the work from the first question.
+A run in the mode holds the space open on purpose, spends real effort to look wide, and narrows late.
+
+The mode adds no stage.
+It changes three things:
+
+- The early stages ask for the ideal first, and practicality waits its turn.
+- The UI mocks stage starts with a fan-out: many deliberately different candidate screens, and the user chooses among them.
+- The UI mocks stage runs before the technical specs stage, so the spec is written to the direction the user chose.
+
+Token cost is not a concern here. Depth and range are the point.
+
+**Raise a doubt, never guess** holds in full.
+The mode widens the solution space.
+It never lets you settle a doubt on your own.
+
+## The offer
+
+The pane offers the mode on the protocol form, and only when the protocol holds high-level exploration or UI mocks.
+You do not ask for it.
+The state comes back with `modes.imagination` true when the user turned it on.
+
+The user also turns it on by naming it, at any time before the technical specs stage writes the spec.
+
+**Late activation.**
+The mode applies to the stages still ahead.
+Run every one of them in the mode.
+For a stage that already finished, judge whether the mode would change its outcome.
+When it would, ask in a round whether to run that stage again.
+Say plainly that what exists stays until a new round replaces it.
+
+## The stage order
+
+With the mode on, and both stages in the protocol, the UI mocks stage runs **before** the technical specs stage.
+The reorder applies to those two stages alone.
+Every other stage keeps its place.
+
+## High-level exploration in the mode
+
+Run the first pass magic-first.
+Name the ideal experience as if everything were possible: no cost, no platform limit, no legacy code.
+**No talk of feasibility is allowed in that first pass.**
+Let no answer of yours, and no answer of the user's, pull the conversation to what is practical.
+When the user raises a constraint, write it down, and say it comes back once the ideal is clear.
+
+Practicality enters after the first pass has a gate-confirmed conclusion.
+The stage therefore gates twice.
+
+Gate the ideal pass first: the ideal is clear, or there is more to imagine.
+On "clear", write the ideal into the `North star` section of `spec/SPEC.md`, and run the second pass.
+`references/spec-guide.md` defines that section. Create it here, and let the later stages fill in its other parts.
+The second pass holds the ideal against the real code, the real cost and the real limits, and names what survives.
+Gate that pass with the exploration gate in `stages.md`, which ends the stage.
+
+## The interview in the mode
+
+Ask for the ideal experience first.
+The constraint questions follow.
+A constraint then applies to a vision, rather than standing in for one.
+Every other rule of the interview stage holds.
+
+## The UI mocks stage in the mode
+
+The stage keeps every rule in its `stages.md` section.
+The mode puts a fan-out in front of the normal loop.
+
+### The creative research pass
+
+Before the fan-out, study prior art and unusual patterns for work of this kind.
+Look at how other products solved it, and at patterns the user has probably not seen.
+Size the pass by your own judgment.
+
+This pass belongs to the mode. It is not the research stage, and it leaves no document of its own.
+Write what shaped the candidates as a short note in the north-star section of `SPEC.md`.
+
+### The fan-out round
+
+Form your own feel for how many distinct directions this work holds.
+Then ask one round, before you build anything: how many versions to make, and on which axes they differ.
+Name the axes in the question, because the axes are what makes the candidates different.
+Offer your own count, a smaller one, and one option that means "push for more than that".
+Mark your count recommended.
+
+On "push for more": go back to the axes, find directions outside the ones you named, and come back with a wider set.
+
+### The candidates
+
+Build each candidate as a standalone page at `mocks/candidates/<NN>-<short name>.html`.
+`<NN>` is the candidate's number, and it runs on across rounds, so no two candidates share one.
+The candidate's id is its file name without the extension, such as `03-split-view`.
+
+Every candidate differs from every other on a named axis.
+Name that axis at the top of the candidate's page, in one line.
+A candidate that differs in a color or a word alone is not a direction, and it does not earn a place in the set.
+
+### The choice
+
+The tab renders every candidate page in the directory, so the user opens each one there.
+Declare one round asking which candidates to keep: one question, multi-select, one option per candidate carrying its id, its title and its axis.
+Give the round an `invite` for what the user thinks of the set as a whole.
+
+Then apply the choice:
+
+- Move every candidate the user keeps to `mocks/<mock-id>.html`, under a name that says what the screen is. These are the mocks now, and they enter the normal loop of the UI mocks stage.
+- Leave every discarded candidate in `mocks/candidates/` as a record. A rejected direction can inspire a later feature, so delete none of them.
+
+List the survivors in the `Mocks` section of `SPEC.md`.
+List no candidate there: that section holds the screens to build.
+
+### When nothing is kept
+
+A round can end with no candidate kept.
+Ask what was wrong with them, in a round: they are all too close to each other, they all solve the wrong problem, or another reading the round suggests.
+Mark the reading you find most likely, and leave the marker off when you have no view.
+
+Then run another fan-out with fresh axes, informed by the answer.
+Keep the discarded set on disk.
+This loop has no fixed limit.
+It ends when one direction survives at least, or when the user takes the work somewhere else.
+
+## The mocks checkpoint after the spec
+
+With the mode on, the mocks are approved before the spec is written.
+The spec can then settle something the approved mocks show.
+
+After the technical specs gate passes, compare the approved mocks against the approved spec.
+When the spec settled anything the mocks show - a flow, a state, a field, a name on the screen, a rule the screen obeys - ask in a round whether to bring the screens up to date.
+Name what changed.
+
+On yes: revise the mocks, and take a re-approval through the normal mocks gate.
+On no: change nothing.
+Offer no checkpoint when nothing the mocks show changed.

package/templates/skills/dx-spec/references/review-guide.md

@@ -0,0 +1,173 @@
+# The quality review
+
+This file holds the reviewer briefs, the detection lenses, the severities, the report format, and the design-blockers loop.
+The stage itself is defined in `stages.md`.
+Read this file when the stage starts, and not before.
+
+## The reviewer brief
+
+Every reviewer subagent gets this brief, with the angle-bracket parts filled in.
+An agent that runs the review itself acts as both the reviewer and the assembler.
+
+```markdown
+You are reviewing a written specification you did not help write.
+Your focus is <the reviewer's one focus>, and the lenses that belong to it are <the lenses of that focus>.
+
+Read every file in the spec directory at <path to the spec directory>, in this order, whichever of them exist: `README.md` first, since it tells you which stages this work ran, then `intake.md`, `spec/SPEC.md`, `research/RESEARCH.md`, `plan/PLAN.md` and the phase files beside it, and every page directly under `mocks/`.
+Skip `mocks/candidates/`: it is a record of directions nobody chose, and it is not part of the work under review.
+The screens to build are the mocks the `Mocks` section of `spec/SPEC.md` lists.
+Read the principles file at <path to principles.md>.
+Read the repo's own rule files, `CLAUDE.md` and `AGENTS.md`, wherever they exist.
+
+Judge the artifacts as written.
+Do not take the conclusions of the session that wrote them as settled: you were not in that session, and judging this work with fresh eyes is exactly your value.
+You share no context with the other reviewers, you are not told what they found, and you must not ask another agent for context.
+The deviations recorded in the plan's principles check are exceptions the user already approved, so raise one only when the reason written next to it does not hold.
+
+Before you read anything, turn your lenses into a checklist: one check per lens, split further where a lens covers several things.
+Then run every check, and return that checklist in your reply, with a pass or fail line per check.
+Return every failed check as a finding, carrying its severity from the levels below, the artifact and the section it points at, a one-line title, and the reasoning behind it.
+When a check fails on a decision that is the user's to make rather than a plain fix, say so, list the options, and name the one you would pick.
+A check that passes can still leave you with something better to propose - a simpler shape, a design choice you would make differently, code the repo already ships that does part of the work.
+Report that as a finding in the same form, and say in its reasoning that nothing failed and this is an improvement you are offering.
+Give it the severity of what it would be worth.
+Give your findings no id and no state, and write no header block: the agent running the review assembles the report and fills those in.
+A finding you are unsure about is still reported, and you say in its reasoning that it is a judgment call.
+
+Change no file and write nothing to disk.
+Your reply is everything you produce.
+
+<the severity levels of this file, copied into the brief>
+```
+
+## The detection lenses
+
+Each lens has one line, so a brief names the lenses that belong to its focus.
+
+- Inconsistency between artifacts - reads `spec/SPEC.md`, `research/RESEARCH.md`, `plan/PLAN.md` and the mocks against each other, for two statements that cannot both be true.
+- Coverage of the requirements - see the block below.
+- Missing detail and unhandled edge cases - reads the requirements and the flows for the empty, error and limit cases nobody wrote down.
+- Ambiguity and untestable requirements - reads `spec/SPEC.md` for an open `[NEEDS CLARIFICATION: ...]` marker, a requirement with no acceptance criterion, and a requirement nobody could call pass or fail.
+- Duplication and overlap - reads the artifacts for the same thing stated twice, in two places that can drift apart.
+- Terminology drift - reads every artifact for one idea under several names, or one name over several ideas.
+- Principles alignment - reads the artifacts against the principles file and the repo's own rule files.
+- Better ways to do this - reads the design against the codebase for a simpler shape, and for code the repo already ships that does part of the work.
+- Design blockers - reads the design for what would send the build wrong, and reports at HIGH and CRITICAL alone.
+
+The consistency-and-completeness reviewer takes every lens except principles alignment, better ways to do this, and design blockers, which go to the reviewers of those names.
+A focus outside this set takes the lenses that touch it.
+Every lens goes to exactly one reviewer on the confirmed panel, so a panel that drops a focus hands that focus's lenses to the reviewer nearest to it.
+
+## The coverage lens
+
+When the protocol includes the execution plan stage, the coverage lens runs two checks.
+It checks that every requirement ID in `spec/SPEC.md` appears in some phase's `Covers` line in `plan/PLAN.md`.
+It also checks that every ID named in a `Covers` line exists in `spec/SPEC.md`.
+A requirement with no plan coverage is a CRITICAL finding.
+The reviewer states which of two causes it looks like: a missing phase, or scope that belongs in the non-goals.
+When the protocol has no execution plan stage, the lens checks instead that every requirement carries its own acceptance criterion, and reads as a pass or a fail.
+
+## The severity levels
+
+- **CRITICAL** - a principles violation, a contradiction between artifacts, or a requirement with no plan coverage.
+- **HIGH** - a conflicting or untestable requirement, an ambiguous security or performance attribute.
+- **MEDIUM** - terminology drift, an edge case with missing detail.
+- **LOW** - style and wording.
+
+Fix a conflict with a principle by changing the work.
+Never resolve it by softening the principle.
+
+## The design-blockers loop
+
+One reviewer on every panel has the design-blockers focus.
+Its brief is the brief above, with two additions:
+
+- It reports HIGH and CRITICAL findings alone. Anything below that is not its business, and another reviewer has it.
+- It reads for what would send the build wrong: a design that cannot hold, a contract two artifacts read differently, a requirement whose shape makes it unbuildable as written.
+
+**The loop.**
+Run the blockers reviewer.
+Fix what it found.
+Then run it again, with fresh context, over the fixed artifacts.
+Repeat until a round returns nothing.
+A fresh run each time is the point: a reviewer that saw the last round would grade its own fixes.
+
+**The guardrail.**
+A scoped reviewer has no natural zero.
+Given fixed artifacts and a mandate to find HIGH findings, a reviewer finds HIGH findings, and the rounds degrade into ever smaller material dressed in a severity it does not carry.
+
+So judge every returned finding before you loop again, against one criterion:
+
+> A finding an executing agent would likely have resolved on its own is not a true design blocker, whatever severity the reviewer gave it.
+
+An executing agent reads the code, runs the tests, and makes the small calls the spec left open.
+That is its job.
+A finding that names one of those calls is execution's work, and the plan's own review checkpoints cover it.
+
+**The close.**
+A round whose findings all fail that test closes the loop.
+Record the judgment per finding in the report - what it was, and why it failed the test - and leave that material to execution.
+Only a finding that passes the test justifies another round.
+
+Convergence here is judged, never awaited.
+Do not run a further round in the hope of a zero.
+
+## The report format
+
+`review/REVIEW.md`:
+
+```markdown
+# Quality review - <title of the work>
+
+- Run: YYYY-MM-DD
+- Mode: fresh-context subagents | inline - the session that wrote the spec
+- Panel: <one focus per reviewer>
+- Blockers loop: <n> rounds, closed by <a zero round | judgment>
+- Findings: <total>, of which <n> applied, <n> dismissed, <n> waiting on you
+
+## <the first reviewer's focus>
+
+- [x] <a check this reviewer ran and passed>
+- [ ] <a check it ran and failed>
+
+### RV-01 - <the finding in one line>
+
+- Severity: HIGH
+- Points at: SPEC.md, the Requirements section, FR-04
+- State: FOR YOUR DECISION
+- Options: <first option> | <second option>
+- Reasoning: <why the reviewer raised it>
+- Note: <the fix applied, the reason it was dismissed, or what the reviewer recommends>
+
+### RV-02 - <the finding in one line>
+
+- Severity: MEDIUM
+- Points at: SPEC.md, the Data section
+- State: APPLIED
+- Reasoning: <why the reviewer raised it>
+- Note: <the fix that was applied>
+
+## Design blockers
+
+### Round 1
+
+<the findings of that round, in the form above>
+
+### Round 2 - closed by judgment
+
+<each finding, with the judgment against the criterion and where the material was left>
+```
+
+The running agent assembles this report from the reviewers' replies.
+It writes the header block, and puts each reviewer's checklist and findings under that reviewer's focus.
+It assigns the ids and the states.
+Finding ids run `RV-01`, `RV-02`, and so on, in writing order across the whole report.
+An id never changes, so a decision that names a finding still points at the same finding.
+
+`State:` holds `APPLIED`, `DISMISSED` or `FOR YOUR DECISION`.
+A finding that waits on the user carries an `Options:` line, recommended option first.
+Every other finding leaves that line out.
+The report keeps every finding, applied and dismissed included.
+A finding the user decides on keeps its id and gains the outcome in its `Note:` line.
+Applying that decision changes its `State:` line: `APPLIED` when the decision changed the artifacts, and `DISMISSED` when the user left them as they are.
+Either way, drop the `Options:` line and update the counts in the header.