feat(feature-flow): questions deck, note tags, contract step, contract-check, acceptance deck, close-out Contract section

.claude/rules/feature-flow.md

@@ -0,0 +1,78 @@
+---
+paths:
+  # Workspace-root paths, written plainly like landing-page.md's `scripts/ui-review/**`:
+  # the audit's glob check requires a slash before a `**/` prefix, so `**/scripts/…`
+  # matches nothing at the root. A worktree session's project root IS the worktree, so
+  # the plain form fires there too.
+  - "scripts/ui-review/deck/**"
+  - "scripts/ui-review/review-cards.py"
+  - "scripts/ui-review/contract-agent.md"
+  - "docs/active/design/**"
+  - "scripts/close-out.sh"
+last_verified: 2026-09-01
+verify:
+  - path: scripts/ui-review/deck/contract.py
+    contains: "def check_contract"
+  - path: scripts/ui-review/contract-agent.md
+  - test: scripts/ui-review/tests/test_contract.py
+  - test: scripts/ui-review/tests/test_words.py
+---
+
+# Feature flow — the deck is the one surface
+
+Design: `docs/active/specs/2026-09-01-feature-flow-design.md`.
+
+## Questions before drawing
+**Invariant:** a new feature's step-2 questions are a words-only deck (`<feature>.questions.json`,
+`"words": true` decide steps, 1–3 options), served and submitted before any UI is drawn. A note
+with no tag (answers files from before 2026-09-01) counts as **just noting**, same as a tagged one.
+(untagged-note rule: `scripts/ui-review/contract-agent.md` prose — none — candidate)
+**Why:** answers in chat are not a source; a contract row must resolve to an answered step.
+**Guard:** `test_words.py` covers the words-deck invariant only; the `ui-mockup` skill's
+"Before drawing anything" section (prose — not enforced).
+
+## The contract is a deck, and its sources are answered steps
+**Invariant:** `<feature>.contract.json` is a one-step `rows` deck; every row's `source` is
+`<deck key>#<step id>` of a submitted, non-skipped answer. Not the design spec, not the plan,
+not the transcript. Written by a FRESH agent from `scripts/ui-review/contract-agent.md`.
+**Why:** provenance — the rows are Destin's decisions, and a generator grading itself is generous.
+**Guard:** `review-cards.py contract-check`; `test_contract.py`.
+
+## Answers files are committed
+**Invariant:** `docs/**/*.answers.json` (and the stamped rotations) are tracked; only `scratch/`
+is ignored. Never add them back to `.gitignore`.
+**Why:** they are the only record of decisions; ignored for three months, they lived on one disk.
+**Guard:** none — candidate (an anchor test on `.gitignore`).
+
+## Reopen only through a deck
+**Invariant:** when implementation contradicts approved UI, the implementing session serves a
+one-step words-only `decide` deck and waits; a chat question is not a route back. The answer
+amends the contract row's `source`.
+**Why:** a chat answer is not a source (see above).
+**Guard:** none — candidate.
+
+## The gate is three facts, and one command reports them
+**Invariant:** `review-cards.py contract-check <feature>.contract.json` is the only reader of
+the gate: (1) every row's source resolves and every `mechanical` guard exists on disk or on
+the contract's `branch` (exit 1 otherwise); (2) the contract was signed — `<feature>.contract.answers.json`
+submitted with the contract step `yes`; (3) `<feature>.contract.acceptance.answers.json` is
+submitted. `close-out.sh` relays its `ok:` / `todo:` lines and reads no answers file itself.
+**Why:** a guard the branch adds is not in the main checkout until merge; a contract nobody
+signed is not a definition of done; two readers of one file drift.
+**Guard:** `test_contract.py` (ContractCheckTests); `close-out-contract.test.sh`.
+
+## The build stage is reviewed, capped, and recorded
+**Invariant:** between the signed contract and the branch: a technical design → reviewer rounds
+that each write `docs/active/reviews/<date>-<feature>-design-review-<n>.md` (findings `R<n>-<k>`
+marked accepted / rejected / already handled, reversals tagged `reverses:`), stopping on a round
+with nothing accepted, cap three → task breakdown (descriptions by default; pre-written code
+only for cross-repo / stored-data / strict-order work) → subagent build with a reviewer per task.
+**Why:** nothing yet shows whether review rounds improve a design or churn it; the files are the data.
+**Guard:** none — candidate (design §8b: tooling after three features).
+
+## Acceptance is graded rows plus human rows
+**Invariant:** the grader writes `<feature>.contract.verdicts.json` (beside the contract, same
+stem — the CLI reads exactly that name); `review-cards.py acceptance` refuses when a
+`mechanical` or `deck` row has no verdict.
+**Why:** an ungraded row is not a pass.
+**Guard:** `test_contract.py` (AcceptanceTests).

.claude/skills/ui-mockup/SKILL.md

@@ -10,6 +10,16 @@ approved changes — see `docs/archive/specs/2026-07-16-ui-consistency-design-sp
 output format it produced). That process still holds. What changed on 2026-07-29 is **where the
 rendering happens**.
 
+## Before drawing anything: the questions deck
+
+Step 2 of the feature flow (`docs/active/specs/2026-09-01-feature-flow-design.md` §5) is a
+deck, not a chat. Write `docs/active/design/<date>-<feature>/<feature>.questions.json` — one
+`"words": true` step per question, one to three options (the recommended one first, its why in
+`summary`), no picture — and `serve` it in the background. Do not ask what the design guide or
+the code already answers; do not ask what has an obvious answer (state it, the review deck
+will show it). Draw only after it is submitted: its answers are the first source of the
+contract.
+
 ## The mechanism: edit the real components
 
 `bash scripts/run-workbench.sh` boots the **real renderer** in a browser tab at
@@ -76,14 +86,25 @@ feel right" — is his, and he can usually eyeball it in 30 seconds. Tell him wh
 
 ## After approval
 
-Decisions must not live only in chat:
+Decisions must not live only in chat — and the deck answers ARE the record (they are committed):
 
-1. Capture them in a spec under `docs/active/specs/` — ledger, the surfaces touched, migration
-   notes.
+1. **Write the contract.** Dispatch a fresh agent with `scripts/ui-review/contract-agent.md`,
+   the questions deck, every round's spec and answers, and the branch name. Serve
+   `<feature>.contract.json`; it is the last thing Destin answers before the build. Run
+   `review-cards.py contract-check` on it and paste the output into the handoff.
 2. Turn the `MOCK_ONLY` entries the approved UI depends on into real handlers (main +
    `preload.ts` + `remote-shim.ts` + `SessionService.kt`, guarded by `ipc-channels.test.ts`),
    then drop them from the registry.
-3. Add ROADMAP entries for anything deferred, and follow the workspace knowledge rules
-   (pinning test > ast-grep rule > WHY comment > path-scoped rule) for anything durable.
+3. **Run the build stage** (design §8): a short technical design (backend, data shape, reuse)
+   → adversarial review, one findings file per round under `docs/active/reviews/`, stop on a
+   round with nothing accepted, cap three → task breakdown, descriptions by default and
+   pre-written code only for cross-repo / stored-data / strict-order work → subagent-driven
+   build with a reviewer per task. Destin is not in this stage; a contradiction with the
+   approved UI is a reopen deck, never a silent change.
+4. Add ROADMAP entries for every *fix later* note the contract agent listed, and follow the
+   workspace knowledge rules (pinning test > ast-grep rule > WHY comment > path-scoped rule).
+5. At the end: write `<feature>.contract.verdicts.json` beside the contract, run
+   `review-cards.py acceptance`, serve the acceptance deck; `bash scripts/close-out.sh <branch>`
+   reports whether the contract holds, was signed, and was accepted.
 
 Merging cannot shift appearance, because nothing was ever copied.

.github/workflows/workspace-ci.yml

@@ -93,18 +93,19 @@ jobs:
       # (`-t .` cannot import a directory with no __init__.py). Same shape as the
       # hooks above: a check that stops checking goes quiet, not red.
       #
-      # ONLY these three suites. Every other one shells out to `magick` (test_boxes,
+      # ONLY these five suites. Every other one shells out to `magick` (test_boxes,
       # test_build, test_crops, test_cli, test_serve) or drives Chrome/ffmpeg (the
       # three *.test.mjs), none of which this runner has — so they stay local and
-      # scripts/ui-review/README.md says so. test_live is written picture-free on
-      # purpose to keep the new coverage on this side of that line.
+      # scripts/ui-review/README.md says so. test_live, test_words and test_contract
+      # are written picture-free on purpose to keep the new coverage on this side of
+      # that line.
       #
       # working-directory, not `-t`: the suites live outside a package, so each one
       # bootstraps its own sys.path and must be imported as a top-level module.
       - name: Test the review deck
         if: ${{ !cancelled() }}
         working-directory: scripts/ui-review/tests
-        run: python3 -m unittest -v test_spec test_tokens test_live
+        run: python3 -m unittest -v test_spec test_tokens test_live test_words test_contract
 
       # A command printed in a doc is a promise nobody checks. The deck's test command sat
       # WRONG in two docs for months — `-t .` cannot start at all — which is why that suite

.gitignore

@@ -109,8 +109,8 @@ docs/active/design/*-ui-audit/images/
 # (scratch/ already covers the fixture HOME, the downloaded engine/model assets and
 # the per-boot desktop.log copies.)
 perf-reports/shots/
-*.answers.json
-*.answers.*.json
+# Deck answers (*.answers.json) are Destin's decisions and are COMMITTED (feature-flow design §2).
+# Throwaway decks live in scratch/, which is ignored above. `*.serve.json` is a runtime lock.
 *.serve.json
 
 # Python bytecode from the deck tooling + its tests

CLAUDE.md

@@ -122,7 +122,7 @@ bash scripts/run-dev.sh <branch-or-worktree> --label "Feature Name"
 
 ### New Features & UI/UX Changes
 
-When designing new features or making changes to user-facing app interfaces, the first step should always be to visualize and design the UI/UX of the final feature. Planning sessions should prioritize iterative UI design using the workbench and other tooling to help Destin shape the final user experience of the feature before building backend. When Destin provides final sign-off on the UI/UX design for the feature, the UI/UX should be treated as largely final and backend should be designed around the UI/UX accordingly. The standard every new surface is measured against is `docs/active/design/2026-08-25-ui-design-guide.md` (five laws, primitives, per-surface anatomies, checklist); show him the change as a **review deck** (scripts/ui-review/review-cards.py — one point per step: Before | After with the changed region boxed by the rig, a headline and three cards — What changed / You'll notice / Risk — Yes / No / Other, answers saved to a file and handed to Claude on Submit; `serve <spec>` in the background does it all), built from the UI review rig below; never a gallery, a prose page or a chat description (all three were rejected). **For motion, drag or hover, use a LIVE step** — panes of the running app he can actually operate, one authored candidate each out of `youcoded`'s `compare/registry.tsx` (`serve` boots the worktree's workbench for them). A recording is the wrong tool for a 200 ms animation: four clip steps were rejected on 2026-08-31 as "just rough to compare". `scripts/ui-review/README.md` → "Live panes".
+When designing new features or making changes to user-facing app interfaces, the first step should always be to visualize and design the UI/UX of the final feature. Planning sessions should prioritize iterative UI design using the workbench and other tooling to help Destin shape the final user experience of the feature before building backend. When Destin provides final sign-off on the UI/UX design for the feature, the UI/UX should be treated as largely final and backend should be designed around the UI/UX accordingly. The standard every new surface is measured against is `docs/active/design/2026-08-25-ui-design-guide.md` (five laws, primitives, per-surface anatomies, checklist); show him the change as a **review deck** (scripts/ui-review/review-cards.py — one point per step: Before | After with the changed region boxed by the rig, a headline and three cards — What changed / You'll notice / Risk — Yes / No / Other, answers saved to a file and handed to Claude on Submit; `serve <spec>` in the background does it all), built from the UI review rig below; never a gallery, a prose page or a chat description (all three were rejected). The flow around the deck — questions deck first, contract at sign-off, acceptance deck at the end, then the build stage (technical design → capped review → task breakdown → subagent build) — is `.claude/rules/feature-flow.md`. **This overrides the brainstorming skill's habit of asking in chat:** on a YouCoded feature, its opening questions go on a questions deck (`ui-mockup` skill → "Before drawing anything"), and a chat answer is not a source for the contract. **For motion, drag or hover, use a LIVE step** — panes of the running app he can actually operate, one authored candidate each out of `youcoded`'s `compare/registry.tsx` (`serve` boots the worktree's workbench for them). A recording is the wrong tool for a 200 ms animation: four clip steps were rejected on 2026-08-31 as "just rough to compare". `scripts/ui-review/README.md` → "Live panes".
 
 ### UI Workbench
 

ROADMAP.md

@@ -858,6 +858,10 @@ surface, not a history.
 
 ## Features
 
+- [ ] **Feature flow: questions deck → review rounds → contract → acceptance, with contract-check in close-out** — design `docs/active/specs/2026-09-01-feature-flow-design.md`, plan `docs/active/plans/2026-09-01-feature-flow-plan.md`. All four §9 assumptions answered as recommended on 2026-09-02 (§8 rewritten 2026-09-02 as the build stage: technical design → capped, self-recording review → task breakdown → subagent build). `feature` `#workspace` `#ui-review` (added 2026-09-01)
+- [ ] Measure the design-review loop (design §8b): after three features have run through it, count accepted findings, reversals (`reverses:`) and defect-vs-taste per round from `docs/active/reviews/*-design-review-*.md`, and set the default round count from the numbers — today nobody knows whether round three improves a design or churns it. Tooling (a findings-file parser, a stop-rule check) waits for that data. `idea` `#workspace` `#ui-review` (added 2026-09-02)
+- [ ] Feature-flow coverage debt left by the 2026-09-01 final review: no browser test for the contract table (`rowsTable`, verdict column, pass/fail tint); `close-out-contract.test.sh` is local-only so the Contract section has no unattended guard; no pinning test for `verdict: ''` vs an absent key, a two-`#` source, a corrupt verdicts file or a missing `git`; `close-out.sh` reads `rg` exit 1 and 2 alike (shared by its three older `rg` calls). None is a known failure. `idea` `#ui-review` `#tests` (added 2026-09-01)
+
 - [ ] **Agents & Automations view — work that runs on a schedule or trigger without the user, with an inbox** `feature` `#agents` `#automations` `#native-runtime` (added 2026-09-01, backfilled — designed 2026-07-09 as platform-vision Phase 4, never tracked here)
   A third top-level view beside Chat and Projects. Triggers v1 = "Run now" + cron/one-time; runner = a main-process scheduler with a persisted, restart-surviving job store spawning headless harness sessions under step/token/time/**cost** budgets that are hard stops; inbox = run states `scheduled / running / needs-approval / completed / failed`, status-bar chip, notifications, Android/remote push later; a run's transcript is an ordinary read-only session and its files land in the artifact viewer. Backend-agnostic from day one (local model = free 24/7, OpenRouter, or Claude Code headless). Exit criterion: "every morning at 8, summarize my project's new GitHub issues into a note and ping me if any look urgent" is creatable by a non-developer and its runs appear in an inbox. **Verified 2026-09-01: zero scheduling/trigger/automation code exists in either app.** Blocked on the "Assistants made of Duties" ruling (Someday, below) — the unit of organization decides what a manifest even is — plus cost accounting and specialists stage two's durable journal. The 2026-09-01 roadmap-restructure taxonomy has no area for this family yet. Full shape: `docs/active/specs/2026-09-01-agent-platform-vision-and-state.md` §6.1.