release: v1.10.0 — vendored design method, security certification, validation engine

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+.playwright-mcp/

AI/mcp-setup.md

@@ -8,9 +8,9 @@
 
 | Integration | Provides | Required by |
 |-------------|----------|-------------|
-| **Notion MCP** | BRD read/write: `notion-search`, `notion-fetch`, `notion-update-page`, `notion-query-data-sources`, `notion-create-pages` | orchestrator + every stage (hard requirement) |
-| **GitHub (`gh` CLI)** | branch/PR/CI/merge: `gh pr create/view/checks/merge` | git, code-review, release stages |
-| **Figma MCP** | design context, screenshots, design-system reads | ui-workflow, design-system-workflow — only when the BRD references Figma |
+| **Notion MCP** | BRD read/write: `notion-fetch`, `notion-update-page`, `notion-query-data-sources`, `notion-create-pages` — registered databases/pages only, no workspace search ([integration-map](../Architecture/integration-map.md) §2b) | orchestrator + every stage (hard requirement) |
+| **GitHub (`gh` CLI)** | branch/PR/CI/merge: `gh pr create/view/checks/merge` — bound repositories only | git, code-review, release stages |
+| **Figma MCP** | design context, screenshots, design-system reads, navigation-map writes — bound file keys only | ui-workflow, design-system-workflow, flow-visualization — only when `resources.figma.product_design_file` (or the design-system library) is bound in the Project Resource Registry. Unbound → flow-visualization degrades loudly to the markdown map, never silently skips |
 | **Local shell/files** | build, test, serve prototype | implementation, qa, debug, prototype Run Local |
 
 ## 2. Setup Checks (per machine, once)

AI/model-routing.md

@@ -27,6 +27,11 @@ Pin to latest within each family; exact IDs live here so projects inherit update
 | Design: UI planning (06) | T2 | DS mapping against explicit inventory |
 | Design: Prototype (07) | T2 | Assembly against spec; DS check is procedural |
 | Design: Self-audit (08) | **T3** | Adversarial pass; catches what the builder can't (§5 cross-model rule) |
+| Design Review: user review (09) | T2 | Packaging + capture; the judgment is the user's |
+| Design Review: revision triage (10) | **T3** | Root-cause routing — a misroute costs three cycles, and did |
+| Design Review: final output (11) | T2 | Freeze, hash and completeness are mechanical against the matrix |
+| Design: flow visualization (12) | T2; **T3** for the first derivation's reconciliation and the state-vocabulary normalization | Derivation is a tool; deciding registry-vs-flows disagreements is not |
+| Security certification (`C_SECURITY`) | **T3** | Adversarial, and a miss ships to production (§6 T4 reserve applies to auth/payment/PII scope) |
 | Dev Planning (FE/BE) | **T3** | Architecture + contracts freeze here; rework cost peaks |
 | Implementation | T2; T1 for mechanical slices (boilerplate, config, copy, codemods) | Plan quality already bought; assembly is standard work |
 | QA | T2 | Procedural verification + exploratory judgment |
@@ -43,7 +48,7 @@ Every S16 stage-enter entry appends the model: `— Stage-Enter (model: T2/sonne
 ## 4. Escalation Rules
 
 1. **Retry escalation:** a stage failing its exit checklist twice at its default tier re-runs at +1 tier, with the failed rules as corrective constraints. (First retry stays at-tier — most failures are attention, not capability.)
-2. **Loop escalation:** re-entry via a loop (`L_QA`, `L_REVIEW`, `L_DESIGN` second iteration onward) escalates the **producing** stage's model +1 tier — the bounce is evidence the work needed more depth, not more speed.
+2. **Loop escalation:** re-entry via a loop (`L_QA`, `L_REVIEW`, `L_DESIGN`/`L_REVISION` second iteration onward) escalates the **producing** stage's model +1 tier — the bounce is evidence the work needed more depth, not more speed.
 3. **Debug escalation:** T2 → T3 when 2 hypotheses die without narrowing the mechanism, or at half the timebox — whichever first.
 4. **No mid-stage downgrade.** Tier changes happen at stage boundaries only; a stage finishes at the tier it escalated to.
 5. **De-escalation:** next BRD's same stage returns to the table default — escalations don't ratchet permanently; recurring escalation of the same stage across BRDs = routing-table bug, fix it here (minor bump).

AI/orchestrator.md

@@ -7,11 +7,20 @@
 
 ## 1. Responsibilities
 
-0. **Manifest gate** — before ANY project work: `C_MANIFEST` ([../Architecture/project-manifest.md](../Architecture/project-manifest.md)). Missing/incomplete manifest → refuse BRD work, offer [project-onboarding](../Workflows/project-onboarding.md). Stale `last_validated` → run [integration-validation](../Workflows/integration-validation.md) first. Project facts come from the manifest — never re-ask the user for manifest-held values.
+0. **Manifest Gate** — at session entry, before ANY project work (pickup **and** resume alike). A fixed pipeline; each step's failure action is the only permitted next move:
+   1. Load the **Toolkit Registry** (`~/.toolkit/registry.yaml`, [../Architecture/toolkit-registry.md](../Architecture/toolkit-registry.md)). Missing → offer one-time setup (README); nothing else runs.
+   2. Load `project-manifest.yaml`. Missing / `onboarding.status: incomplete` → refuse BRD work, offer [project-onboarding](../Workflows/project-onboarding.md).
+   3. `manifest_version` older than current → run **Migration** ([project-onboarding §Migration](../Workflows/project-onboarding.md)) — automatic offer, seeded from the old fields, resumable; runs **before** staleness/validation (those need registry ids the old manifest lacks). In-flight BRDs resume normally once it completes.
+   4. `last_validated` stale (>30 days) → run [integration-validation](../Workflows/integration-validation.md).
+   5. `C_MANIFEST` full check ([../Architecture/workflow-state-machine.md](../Architecture/workflow-state-machine.md) §4) → fail: report exactly what unblocks.
+   Project facts come from the manifest — never re-ask the user for manifest-held values.
+0b. **Resource boundary** (v1.5 — [Project Boundary Rule](../Architecture/integration-map.md) §2b). All external access resolves through the Project Resource Registry by **stable identifier**. Never workspace-search Notion, browse Figma, or list repositories; never guess a resource. A stage requiring a slot that is missing, skipped, or `health: unreachable` → raise a **Resource Decision** ([project-manifest §3](../Architecture/project-manifest.md)): *connect existing / create new / confirm absence*. While it is pending, set `Status: Blocked`, `Blocked Reason: resource: <slot> — <reason>` — this makes the stop resumable at session entry (§2) and fires the Telegram failure trigger (responsibility 9). Log the decision S16; clear `Blocked` on resolution.
 1. **Pickup** — select next BRD from `Ready` (priority order) when a slot is free (<3 in-flight) and `C_MANIFEST` holds for its project.
 2. **Stage routing** — map `Status` → workflow module → skill → model tier per [model-routing.md](model-routing.md); load only what the stage needs; log the model in the Stage-Enter S16 entry.
 3. **Input verification** — before running a stage, check `C_SECTIONS(required)`: required BRD sections exist and are non-empty. Missing input → back-transition to the producing stage, never improvise the input.
-4. **Gate enforcement** — never cross a human gate without the approval token in `Approvals`; revoke tokens when gated content changes (stale-approval rule). At Dev Planning entry additionally run `C_CONTRACT` ([../Checklists/screen-contract.md](../Checklists/screen-contract.md)): any missing mapping → stop, report `SCR-id · block · gap` lines, route to the owning stage, log S16. No implementation on an incomplete Screen Contract.
+4. **Gate enforcement** — never cross a human gate without the approval token in `Approvals`; revoke tokens when gated content changes (stale-approval rule; classify the delta first — bug-fix-only → scope confirm with byte-level evidence, feature delta → a ruling). On `Design Gate` approval, evaluate `C_HANDOFF_REQUIRED` ([../Architecture/workflow-state-machine.md](../Architecture/workflow-state-machine.md) §4): true → run design state 12 ([../Workflows/flow-visualization.md](../Workflows/flow-visualization.md)) and hold the BRD in `Design Review` until the **Developer Handoff Gate** resolves; false → log the skip in S16 and continue. At **QA entry and again at Tech Review entry** run `C_SECURITY` ([../Checklists/security.md](../Checklists/security.md)): S14 must carry a `certified` Security Certificate whose `certified_commit` equals the current branch head — stale or missing → stop, route to [../Workflows/security-certification.md](../Workflows/security-certification.md), log S16. No QA on uncertified code, no review on a certificate that predates the fixes. At Dev Planning entry additionally run `C_CONTRACT` ([../Checklists/screen-contract.md](../Checklists/screen-contract.md)): any missing mapping → stop, report `SCR-id · block · gap` lines, route to the owning stage, log S16. No implementation on an incomplete Screen Contract.
+4b. **Check evidence, not claims** — where a gate's evidence is a tool run ([../Architecture/validation-engine.md](../Architecture/validation-engine.md)), read the **exit code**: `0` pass, `1` findings, `2` **the check did not run** — *unevaluable*, never a pass. A stage reporting "checks passed" with no exit code recorded has not produced gate evidence.
+
 5. **Loop accounting** — increment `Loop Count` before re-entry; enforce ceilings; on breach set `Blocked` + escalation summary in S16, never loop silently.
 6. **Notion updates** — advance `Status`, set `Stage Owner`, write the S16 transition entry after every transition (atomic: status + log together).
 7. **Resume** — reconstruct everything from Notion properties + S16. Session memory is never machine state.
@@ -26,7 +35,8 @@
 
 On any session start (or `resume <brd-id>` request):
 
-1. Query the BRD DB: in-flight pages (Status ∈ Analysis…Human Review) + `Ready` pages, filtered to this project unless told otherwise.
+0. Run the **Manifest Gate** (responsibility 0, all five steps). Only after it passes may any external system be touched.
+1. Query the BRD DB — via the registry binding (`resources.notion.brd_database.id`): in-flight pages (Status ∈ Analysis…Human Review) + `Ready` pages, filtered to this project unless told otherwise.
 2. If a specific BRD named → load it. Else: continue oldest in-flight first; pick up new `Ready` BRDs only when slots free and user confirms pickup.
 3. Read BRD properties + S16 tail (last 10 entries) → determine exact machine position, pending gates, open loops.
 4. Announce: BRD, stage, pending gates/blockers, planned action. Then run the stage.
@@ -42,6 +52,9 @@ ENTER   verify C_SECTIONS(stage.inputs)          → missing? back-transition
 RUN     load Workflows/<stage>.md + Skills/<role>.md + referenced Standards/
         act ONLY with that role's permission-matrix rights
         write findings to BRD immediately when discovered (living doc), not at exit
+        design fidelity: when a PO handoff skips the Design Gate, schedule the
+        fidelity review (ui-workflow M7, a reviewer who did not build the screen)
+        BEFORE device proof — never skipped silently; the skip would be logged S16
 EXIT    run stage exit checklist (Checklists/ when built; workflow
         Completion Criteria until then)
         pass → write outputs summary + S16 [Stage-Exit] entry → advance Status
@@ -57,9 +70,9 @@ GATE    if stage exits through a human gate: present decision package
 When a human gate is pending, present exactly:
 
 1. **BRD** — ID, name, link.
-2. **Gate** — which (Direction / Design / Final) and what approval unlocks.
-3. **Review target** — Direction: S01–S06 summary. Design: running prototype URL (Run Local, port 8765 default) + S07–S09. Final: PR link + diff summary + S13/S14 verdicts.
-4. **Known limitations** — from audits, transparently.
+2. **Gate** — which (Direction / Design / **Developer Handoff** / Final) and what approval unlocks.
+3. **Review target** — Direction: S01–S06 summary. Design: running prototype URL (Run Local, port 8765 default) + the **deep-link hook table** + S07–S09. Developer Handoff: the **derivation report** (`navmap-report.md`) — never the picture — plus registry sha, derivation run and prototype versions. Final: PR link + diff summary + S13/S14 verdicts.
+4. **Known limitations** — from audits, transparently, at full strength. Every waiver names its rider debt item, grantor and closing condition; an acceptance with qualifications is recorded with its qualifications.
 5. **Ask** — `approve` / `request-changes` (structured, each with target) / `reject` / `stop`.
 
 Multiple pending gates across parallel BRDs → batch, oldest first.
@@ -82,3 +95,5 @@ Multiple pending gates across parallel BRDs → batch, oldest first.
 - Never advances Status without the exit check passing.
 - Never carries approvals across content changes.
 - Never holds state only in conversation. If it isn't in Notion, it didn't happen.
+- Never lands a screen whose Design block lacks reading order / chrome / alignment for its bound frame, or that deviates from the frame on arrangement or hierarchy without a recorded Product Owner ruling (screen-contract §4a).
+- Never touches a resource outside the Project Resource Registry — no workspace searches, no repo listing, no unregistered files. Missing resource → connect/create offer, never a guess (responsibility 0b).

Architecture/brd-schema.md

@@ -56,7 +56,7 @@ Sections are H2 headings in the page body, in this order. Each heading carries i
 | S11 | Component Plan & API Notes | revise | Files/components to create or modify; API contracts |
 | S12 | Implementation Notes & Progress | append | Dated progress entries; deviations from plan with reason |
 | S13 | Test Cases, Bugs & Verification | revise | Test cases mapped to ACs; bug list with severity; verification status per AC |
-| S14 | Review Summary & Approval | revise | Review findings, concerns, recommendations, approval status |
+| S14 | Review Summary & Approval | revise | Review findings, concerns, recommendations, approval status. **Subsections (append-only, each owned by its issuing role):** `design-audit` (design state 08), `security-certificate` (`C_SECURITY`, before QA — [template](../Templates/security-certificate.md)), `handoff-gate` (design state 12, when in scope) |
 | S15 | Release Notes | revise | User-facing change summary; version; date |
 | S16 | Decision Log | append-only | See format below. Never edited or deleted, only appended |
 

Architecture/context-package.md

@@ -1,6 +1,6 @@
 # AI Context Package
 
-> **Module:** Architecture / Foundation (v1.3)
+> **Module:** Architecture / Foundation (v1.5)
 > **Status:** Stable
 > **Purpose:** `context/` — small generated summaries a session reads at bootstrap for consistent AI behavior, without loading the full toolkit. **Generated, never hand-edited.** The manifest and toolkit stay authoritative; `context/` is a derived cache.
 
@@ -10,7 +10,7 @@
 
 | File | Summarizes | Source of truth |
 |------|-----------|-----------------|
-| `design.md` | Design config: Figma refs (or prototype-only mode), component library, token source, icon/typography, DS state + where the DS lives | manifest `design.*` + DS docs |
+| `design.md` | Design config: Figma bindings (or prototype-only mode), component library, token source, icon/typography, DS state + where the DS lives | manifest `design.*` + `resources.figma.*` + DS docs |
 | `stack.md` | Stack + resolved profile + the exact list of applicable Standards/ files + declared gaps | manifest `stack.*` + [stack-profiles](stack-profiles.md) |
 | `integrations.md` | Last validation results per integration + per-stage degradation consequences of anything unavailable | manifest `integrations.*` + [../Workflows/integration-validation.md](../Workflows/integration-validation.md) |
 | `conventions.md` | Naming/branch/commit/PR contracts resolved for this project + pointer to `project-overrides.md` entries | manifest `git.*` + [integration-map](integration-map.md) §3 + overrides |