buildanything 1.8.0 → 2.0.0

package/protocols/state-schema.md

@@ -0,0 +1,172 @@
+# .build-state.json Schema
+
+## Purpose
+
+`docs/plans/.build-state.json` is the **typed source of truth** for build state. The human-readable `docs/plans/.build-state.md` file is an **auto-rendered view** regenerated on every state change — it is never edited directly. This document defines the required fields, their types, the rendering contract that produces the markdown view, and the validation rules a well-formed state file must satisfy. Introduced in Wave 1 (W1-2) to eliminate the drift observed in freeform markdown state (duplicate `Autonomous:` fields, Phase Progress append-instead-of-replace, mode branch collisions) and to give the Wave 2 `PreToolUse` schema lint hook something concrete to validate against.
+
+**Machine-authoritative source:** `protocols/state-schema.json` is the SSOT (Stage 1 A8). If this prose doc and the JSON Schema diverge, the JSON Schema wins. Update both together; changes here that are not reflected there will be caught by the W2-2 lint hook.
+
+## Schema versions
+
+`schema_version` is a monotonically increasing integer bumped on each Shape-B migration stage. The runtime reads the incoming `.build-state.json` and compares `schema_version` against its compiled-in `MAX_SUPPORTED_SCHEMA_VERSION` constant.
+
+| Version | Stage | Fields added | Rollback semantics |
+|---|---|---|---|
+| 1 | Stages 1-3 | initial schema (all pre-Stage-4 fields) | n/a |
+| 2 | Stage 4 | `backward_routing_count` (newly typed), `backward_routing_count_by_target_phase`, `in_flight_backward_edge`, `mode_transitions[]` | A7 forward-reject on `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`; A3 stale-edge decrement on `--resume` |
+| 3 | Stage 5 | `lrr_cycle_state` (object; interior fields loose-typed pending Stage 5 iteration — see "Fields added at v3" below) | `BUILDANYTHING_SDK_LRR=false` reverts to markdown aggregator; `lrr_cycle_state` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
+| 4 | Stage 6 | `current_sprint_context_hash` | `BUILDANYTHING_SDK_SPRINT_CONTEXT=false` (web) and/or `BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS=false` (iOS parity gate) reverts Phase 4 to per-task refs re-send; `current_sprint_context_hash` becomes an ignored field on the orchestrator read path (additive-only, no data loss on downgrade) |
+
+**A7 forward-reject rule.** When `bin/buildanything-runtime.ts` reads `.build-state.json` at session start, if `schema_version > MAX_SUPPORTED_SCHEMA_VERSION`, the runtime refuses to proceed and emits a clear error pointing to the compat matrix (`docs/migration/sdk-host-compat.md`). This is the A7 defense against silent schema drift — an old runtime must never silently ignore fields a newer runtime persisted. See **Task 4.5.2** for the runtime implementation (out of scope for this prose-only update).
+
+## Required fields
+
+```jsonc
+{
+  "schema_version": 1,
+  "project_type": "ios",
+  "phase": 6,
+  "step": "6.4",
+  "session_id": "6f3a9c82-7d4e-4b51-9f2a-1e8c6d3f4a0b",
+  "session_started": "2026-04-13T09:12:00Z",
+  "session_last_saved": "2026-04-13T11:47:33Z",
+  "autonomous": false,
+  "mode": "interactive",
+  "build_request": "iOS app blocker that uses on-device AI to gate access to distracting apps.",
+  "context_level": "raw_idea",
+  "git_branch": "main",
+  "completed_tasks": [
+    { "task_id": "M3-T04", "task_name": "Implement Foundation Models allow/deny classifier", "status": "done", "evidence_files": ["cap/Features/Chat/GateClassifier.swift"], "completed_at": "2026-04-13T10:52:11Z" },
+    { "task_id": "M3-T03", "task_name": "Create shield configuration UI", "status": "done", "evidence_files": ["cap/Features/Shield/ShieldConfigView.swift"], "completed_at": "2026-04-13T10:30:00Z" }
+  ],
+  "pending_tasks": ["M3-T06", "M3-T07"],
+  "metric_loop_history": [
+    { "phase": 2, "iteration": 1, "score": 86, "target": 85, "top_issue": "Shield handoff data contract underspecified", "timestamp": "2026-04-13T10:05:00Z" }
+    // ... additional entries follow same pattern
+  ],
+  "resume_point": { "phase": 6, "step": "6.4", "autonomous": false, "completed_summary": "Phases -1..5 done; Reality Check in progress", "git_branch": "main" }
+  // ... additional fields per schema below
+}
+```
+
+## Field definitions
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `schema_version` | integer | yes | Currently `2` (Stage 4); see version table above. Bumped on each Shape-B migration stage. |
+| `project_type` | enum | yes | `"ios"` or `"web"`. Drives mode-branch routing. |
+| `phase` | integer | yes | Current phase, one of `-1, 0, 1, 2, 3, 4, 5, 6, 7`. |
+| `step` | string | yes | Dotted step identifier within the phase (e.g., `"5.3b"`, `"6.4"`). |
+| `session_id` | string | yes | UUID generated at session start; stable across compactions within a session. |
+| `session_started` | ISO 8601 string | yes | When the current session began. |
+| `session_last_saved` | ISO 8601 string | yes | Timestamp of the most recent state write. |
+| `autonomous` | boolean | yes | Whether `--autonomous` was passed. |
+| `mode` | enum | yes | `"interactive"` or `"autonomous"`. Must agree with `autonomous` (interactive iff `autonomous === false`). |
+| `app_name` | string | iOS only | App display name; present iff `project_type === "ios"`. |
+| `bundle_id` | string | iOS only | Bundle identifier; present iff `project_type === "ios"`. |
+| `xcodeproj_path` | string | iOS only | Absolute path to `.xcodeproj`; present iff `project_type === "ios"`. |
+| `build_request` | string | yes | Original user prompt that initiated the build. |
+| `context_level` | enum | yes | `"raw_idea"`, `"decision_brief"`, `"partial_context"`, or `"full_design"`. |
+| `git_branch` | string | yes | Current branch; `"main"` if uninitialized. |
+| `completed_tasks` | array | yes | Tasks finished. Each: `{task_id, task_name, status, evidence_files[], completed_at}`. May be empty `[]`. |
+| `in_progress_task` | object | no | Task currently executing. `{task_id, task_name, started_at}`. |
+| `pending_tasks` | array of strings | yes | `task_id`s still to be dispatched. May be empty `[]`. |
+| `phase_artifacts` | object | yes | Paths to persisted phase outputs. All properties optional; empty `{}` is valid. |
+| `metric_loop_history` | array | yes | Scored iterations across all phases. Each: `{phase, iteration, score, target, top_issue, timestamp, scoring_criteria_checklist?, extraction_method?}`. May be empty. Optional `scoring_criteria_checklist` (string) records the extracted checklist for LRR audit trail. Optional `extraction_method` (`"mechanical"`, `"one-shot-dispatch"`, `"mixed"`). |
+| `active_metric_loop` | object | no | Present only while a metric loop is running. Contains: `{phase, artifact, metric, target, max_iterations, scoring_criteria_checklist?, extraction_method?, current_iteration}`. Removed when the loop completes (results move to `metric_loop_history`). |
+| `dispatch_counter` | object | yes | `{dispatches_since_save, last_save_phase}`. Used by the "save every N dispatches" heuristic. |
+| `ios_features` | object | iOS only | YAML-in-JSON mirror of resolved feature flags (16 boolean keys). Present iff `project_type === "ios"`. |
+| `phase_progress` | object | yes | Boolean per phase (`phase_minus_1` through `phase_7`). `phase_minus_1` is optional (iOS only). |
+| `resume_point` | object | yes | `{phase, step, autonomous, completed_summary, git_branch}`. Snapshot used by Phase-0 resume logic. |
+| `verification` | object | yes | `{last_verify_result, last_verify_timestamp}`. `last_verify_result` is one of `"PRODUCTION_READY"`, `"NEEDS_WORK"`, `"BLOCKED"`, or `null`. |
+| `blockers` | array | no | Open blockers. Each: `{id, description, surfaced_at, type}`. Type is `"build"`, `"design"`, `"dep"`, or `"external"`. |
+
+### Fields added at v2 (Stage 4)
+
+These fields are present only when `schema_version >= 2`. They support the Shape-B SDK migration's backward-routing bookkeeping (A3, A6) and SDK/markdown mode-flip audit trail.
+
+| Field | Type | Required | Added in | Notes |
+|---|---|---|---|---|
+| `backward_routing_count` | object (string → integer ≥ 0) | no | v2 | Per-decision backward-routing counter keyed by `decision_id`. Existed informally pre-v2; formally typed at v2 and paired with the by-phase counter below. Incremented atomically with `in_flight_backward_edge` on dispatch. |
+| `backward_routing_count_by_target_phase` | object (string → integer ≥ 0) | no | v2 | **A6 off-by-one fix.** Per-target-phase backward-routing counter keyed by target phase number (e.g., `"4"`, `"5"`). Lets the max-backward-routes guard count by destination phase rather than by decision, which previously miscounted when a single decision routed back to multiple phases. |
+| `in_flight_backward_edge` | object | no | v2 | **A3 crash-seam defense.** Present only while a backward-route dispatch is mid-flight. Written atomically with the counter increment; cleared by the target phase on re-entry. Fields: `decision_id` (string), `target_phase` (string), `counter_value` (integer ≥ 0), `started_at` (ISO 8601). On `--resume`, stale edges (>60s old) trigger a counter decrement so a crashed dispatch does not permanently inflate the guard. |
+| `mode_transitions` | array of objects | no | v2 | SDK/markdown flag-flip audit trail (Task 4.7.1). Each entry: `{flag, old_value, new_value, post_flags?, session_id?, timestamp}` — `flag` is the env-var name (e.g., `"BUILDANYTHING_SDK"`, `"BUILDANYTHING_ENFORCE_WRITER_OWNER"`); `old_value`/`new_value` are the string-typed prior and new values; `post_flags` is an optional snapshot (string→string) of all tracked flag values AFTER this flip; `session_id` is nullable; `timestamp` is ISO 8601. Append-only within a session. **A7 adversarial fix:** the v2-initial narrow shape `{from, to, timestamp}` could not identify WHICH flag flipped, making the audit trail useless for schema-rollback debugging — widened to capture `flag` + full post-flip snapshot. Canonical emitter: `hooks/record-mode-transitions.ts`. |
+
+### Fields added at v3 (Stage 5)
+
+These fields are present only when `schema_version >= 3`. They support the Shape-B SDK migration's Lazy Reference Resolution (LRR) aggregator — the Phase 6 Launch Readiness Review aggregator promoted from prose to `src/lrr/aggregator.ts` (Task 5.1). The top-level shape is documented here; the aggregator's own output file `docs/plans/evidence/lrr-aggregate.json` is governed by `protocols/launch-readiness.md` and is NOT part of this state schema.
+
+| Field | Type | Required | Added in | Notes |
+|---|---|---|---|---|
+| `lrr_cycle_state` | object | no | v3 | Per-cycle LRR bookkeeping written by the aggregator path (`src/lrr/aggregator.ts`). **Interior fields are intentionally loose-typed at v3** — the JSON Schema (`protocols/state-schema.json` `$defs.lrr_cycle_state` implied by `properties.lrr_cycle_state: {type: "object"}`) does not fix the field set because Stage 5 iteration on aggregator output fields (`combined_verdict`, `triggered_rule`, `star_rule_triggered`, `star_rule_decision_ids`, chapter-completion markers) is still in progress. Once Stage 5 lands, this entry will be tightened in a follow-up task (tracked under 5.4.2's "aggregator output fields" scope) and the `additionalProperties: true` implicit allowance will be removed. Present only when `BUILDANYTHING_SDK_LRR=true` (and hence `schema_version` has been bumped to `3`). |
+
+**v3 migration concern — none in wild.** As of this task (5.4.1), Stage 5 has not shipped. No `.build-state.json` files with `schema_version: 3` exist outside development probes. `bin/buildanything-runtime.ts` `MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK` is still `2` (see Task 4.5.2) — a v3 state file would currently be forward-rejected by A7, which is the intended pre-Stage-5 behavior. The runtime will be bumped to `3` as part of Stage 5 activation, not here.
+
+**v3 rollback semantics.** Rollback is via `BUILDANYTHING_SDK_LRR=false` (see `MIGRATION-PLAN-FINAL.md` §Stage 5 rollback). Because `lrr_cycle_state` is additive and optional, a Stage 4 runtime reading a Stage 5 state file with `schema_version` downgraded to `2` will ignore the field without data loss on the read path. The persisted value survives in place until the next state write overwrites it; orchestrator code paths gated on `BUILDANYTHING_SDK_LRR` are responsible for not writing `lrr_cycle_state` under markdown aggregator mode.
+
+### Fields added at v4 (Stage 6)
+
+These fields are present only when `schema_version >= 4`. They support the Shape-B SDK migration's archetype-aware Phase 4 shared-context hoisting (Stage 6, `MIGRATION-PLAN-FINAL.md` §11) — a sprint-scoped shared-context block is rendered once per sprint by `src/orchestrator/phase4-shared-context.ts` (Task 6.1.1) and injected into Phase 4 implementer/reviewer/critic dispatches via the Stage 3 SubagentStart hook. The hash is persisted in state so re-renders only fire on sprint boundary (or when refs mutate mid-sprint via the `state_save` invalidation callback).
+
+| Field | Type | Required | Added in | Notes |
+|---|---|---|---|---|
+| `current_sprint_context_hash` | string | no | v4 | 16-char SHA-256 prefix (per `phase4-shared-context.ts`) of the rendered sprint-scoped shared-context block. Written by the Phase 4 orchestrator path when `BUILDANYTHING_SDK_SPRINT_CONTEXT=true` (web) / `BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS=true` (iOS). Compared on each Phase 4 dispatch against a fresh render of `{buildState, refs, architecture, qualityTargets, iosFeatures?}`; mismatch forces re-render and rewrite before dispatch. Present only under Stage 6 flag; absent on markdown / Stage 5 runs. |
+
+**v4 migration concern — none in wild.** As of this task (6.5.1), Stage 6 has not shipped. No `.build-state.json` files with `schema_version: 4` exist outside development probes (P6 Habita/Pacely evals per `MIGRATION-PLAN-FINAL.md` §11.3). `bin/buildanything-runtime.ts` `MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK` is still `2` (see Task 4.5.2) — a v4 state file would currently be forward-rejected by A7, which is the intended pre-Stage-6 behavior. The runtime will be bumped to `4` as part of Stage 6 activation (after P6 probe gate passes), not here.
+
+**v4 rollback semantics.** Rollback is via `BUILDANYTHING_SDK_SPRINT_CONTEXT=false` (web) and/or `BUILDANYTHING_SDK_SPRINT_CONTEXT_IOS=false` (iOS parity gate; see `MIGRATION-PLAN-FINAL.md` §Stage 6 rollback and Risk 2). Because `current_sprint_context_hash` is additive and optional, a Stage 5 runtime reading a Stage 6 state file with `schema_version` downgraded to `3` will ignore the field without data loss on the read path — Phase 4 simply reverts to per-task refs re-send. The persisted value survives in place until the next state write overwrites it; orchestrator code paths gated on the Stage 6 flags are responsible for not writing `current_sprint_context_hash` under per-task-refs mode.
+
+**SSOT note.** Kiro-owned `protocols/state-schema.json` is authoritative: `properties.current_sprint_context_hash` (string) is already declared, `schema_version.maximum` is already `4`, and the top-level `$comment` migration table already lists Stage 6. This prose mirrors that shape; any future interior fields (should the sprint-context module persist more than a hash) will be documented by tightening this entry alongside a JSON Schema update.
+
+## Rendering contract
+
+`.build-state.md` is regenerated from `.build-state.json` on every state change by the orchestrator's state-save routine. It is a view, not a source. The rendering is deterministic: same JSON in → same markdown out.
+
+The rendered markdown MUST contain these sections in this order:
+
+1. **Header** — one line: `# Build State`
+2. **Current Phase** — `**project_type:** {project_type}`, `**Phase:** {phase} — {phase_name}`, `**Step:** {step}`, `**Mode:** {mode}`, `**Autonomous:** {autonomous}`. iOS builds also render `**app_name:**`, `**bundle_id:**`, `**xcodeproj:**`.
+3. **Input** — `**Build request:** {build_request}` and `**Context Level:** {context_level}`.
+4. **Dispatch Counter** — two lines: `- dispatches_since_save: {n}`, `- last_save: Phase {k}`.
+5. **Metric Loop Scores** — table rendered from `metric_loop_history`. Columns: Phase, Iteration, Score, Target, Top Issue. Rows sorted by phase then iteration.
+5a. **Active Metric Loop** (only if `active_metric_loop` is present) — render artifact, metric, target, current iteration, extraction method, and the scoring criteria checklist as a fenced block.
+6. **Resume Point** — bulleted `resume_point` fields.
+7. **Phase Artifacts** — bulleted list of `phase_artifacts` entries that are non-null.
+8. **iOS Features** (iOS only) — YAML fenced block mirroring `ios_features`.
+9. **Phase Progress** — checkbox list `[x]`/`[ ]` per phase from `phase_progress`. Rendered **once**, replacing any prior block. Never appended.
+10. **Blockers** (only if non-empty) — bulleted list of blocker descriptions with id and type.
+
+The renderer MUST replace the entire file on write — never append, never diff-edit. This guarantees that drift introduced by partial writes (the capdotai `Phase Progress` duplication bug) is impossible by construction.
+
+## Atomic write protocol
+
+Every orchestrator write to `.build-state.json` (and its rendered `.build-state.md` view) MUST use write-then-rename to survive mid-write interruption (compaction, crash, Ctrl-C):
+
+1. Write the full new contents to `docs/plans/.build-state.json.tmp`.
+2. Rename `.build-state.json.tmp` → `.build-state.json` (POSIX `mv`, which is atomic on the same filesystem).
+3. If step 1 or 2 fails, delete the leftover `.tmp` file. Never leave `.tmp` behind on a failed write.
+
+Direct writes to `.build-state.json` are prohibited — a partial write leaves unparseable JSON and the build cannot resume.
+
+**Read-side recovery check:** on session start / resume, if `.build-state.json.tmp` exists and `.build-state.json` does not (or is empty), treat it as a corrupted interrupted write. Do not auto-parse the `.tmp` file. Surface to the user and halt — resuming from partial state is worse than stopping.
+
+This section is the authoritative write contract. Other protocol/command files that say "write to `.build-state.json`" mean "via this protocol."
+
+## Validation rules
+
+A well-formed `.build-state.json` must satisfy:
+
+1. **Required fields present** — every field marked required above exists and is non-null (except where explicitly `null`-allowed like `verification.last_verify_result`).
+2. **No duplicate keys** — JSON parse succeeds with strict mode. (Addresses the duplicate-`Autonomous:` drift.)
+3. **Type correctness** — every field matches the declared type. Integers are integers, booleans are booleans, ISO timestamps parse.
+4. **Phase bounds** — `phase ∈ {-1, 0, 1, 2, 3, 4, 5, 6, 7}`. `phase === -1` only if `project_type === "ios"`.
+5. **Step matches phase** — `step` starts with the current phase number (e.g., phase 5 → `"5.x"`). Exception: iOS bootstrap step `"-1.x"`.
+6. **Mode/autonomous consistency** — `mode === "autonomous" iff autonomous === true`.
+7. **iOS fields gating** — `app_name`, `bundle_id`, `xcodeproj_path`, `ios_features`, `phase_progress.phase_minus_1` exist iff `project_type === "ios"`. On web builds these must be absent.
+8. **ios_features shape** — if present, contains exactly the 16 documented boolean keys. No extras, no omissions.
+9. **Completed tasks well-formed** — each entry has all five sub-fields; `evidence_files` is an array (possibly empty); `status ∈ {"done", "skipped", "deferred"}`.
+10. **Pending/in-progress disjoint** — `in_progress_task.task_id` (if present) does not appear in `pending_tasks` or `completed_tasks`.
+11. **Resume point consistency** — `resume_point.phase` and `resume_point.step` must not be ahead of the top-level `phase`/`step`.
+12. **Timestamps monotonic** — `session_last_saved >= session_started`.
+
+The Wave 2 `PreToolUse` schema lint hook (W2-2) validates every Write|Edit to `.build-state.json` against these rules and denies writes that fail.

package/protocols/verify.md

@@ -19,7 +19,11 @@ Before running checks, detect the project's stack from manifest files:
 
 Behavioral check: if `tests/e2e/acceptance/` exists, run `npx playwright test tests/e2e/acceptance/ --reporter=list`. If agent-browser is available, also run `agent-browser errors` to check for runtime exceptions.
 
-Skip any check that does not apply (e.g., skip Build for a pure Python script, skip Type-Check for JavaScript without TypeScript). A skipped check counts as PASS.
+A check **does not apply** when the project structurally cannot run it (e.g., Type-Check on JavaScript without TypeScript, Build on a pure Python script, Behavioral on a project with no `tests/e2e/acceptance/` AND no `cap*Tests/` AND no test directory anywhere). A check that does not apply is logged as `N/A — [reason]`, NOT as PASS.
+
+A check that **applies but the tooling is missing** (e.g., npm test on a project with package.json but no `test` script defined, xcodebuild test on an iOS project with no test target) is **NOT skipped**. It is logged as BLOCKED and the orchestrator dispatches a fix agent to make it runnable, MAX 2 attempts, before failing the verification.
+
+`PASS` requires *successful execution*, not absence of execution. A check that did not run is never PASS.
 
 ## Step 2: Run Checks Sequentially
 
@@ -37,12 +41,68 @@ The agent runs these checks in order, stopping on the first FAIL:
 | 4 | Test | All tests pass |
 | 5 | Security | No known vulnerabilities in deps |
 | 6 | Diff Review | `git diff` of uncommitted changes — no debug code, no secrets, no obvious regressions |
-| 7 | Behavioral | Acceptance tests pass against running app (skip if no tests/e2e/acceptance/ directory) |
+| 7 | Behavioral | Acceptance tests pass against running app. Verify the test directory matches the project mode: web requires `tests/e2e/acceptance/`, iOS requires `cap*Tests/` or named test target with non-stub bodies (per `protocols/verify.md` Step 2 stub detector). If no test directory exists in either path AND `sprint-tasks.md` has any non-N/A Behavioral Test fields, FAIL with directive: "Behavioral Test fields are declared but no test directory exists. Either implement the tests or downgrade the fields to N/A." |
 
 <HARD-GATE>
 ONE AGENT, ONE PASS: The orchestrator spawns exactly ONE agent for the entire verification. This is a single Agent tool call, not 6 separate agents. The agent runs each check as a sequential shell command and evaluates the result before proceeding.
 </HARD-GATE>
 
+## Step 2b — Test stub detector
+
+After running the Test check in Step 2, AND after running it as PASS, the orchestrator MUST run the test-stub detector. The detector greps every test file in the project's test directory and fails the verification if any file matches a stub pattern.
+
+**Detection rules — a file is a STUB if ANY of:**
+
+1. **Size threshold:** file size < 500 bytes (capdotai's `capTests.swift` was 358 bytes / 17 lines as the unmodified Apple Xcode 26 template; a real test with one assertion + setup + teardown is ≥ 600 bytes).
+
+2. **Apple template marker grep — Swift Testing:**
+   - Contains `Use XCTAssert and related functions`
+   - Contains `Write your test here`
+   - Contains `XCUIApplication Documentation`
+   - Contains `Swift Testing Documentation`
+   - Contains `// https://developer.apple.com/documentation/testing`
+   - Contains `// https://developer.apple.com/documentation/xcuiautomation`
+
+3. **JavaScript test placeholder grep:**
+   - Contains `it.todo(`
+   - Contains `test.todo(`
+   - Contains `expect(true).toBe(true)`
+   - Function body is a single comment + nothing else
+
+4. **Zero assertions:** no `#expect`, `XCTAssert`, `XCTAssertEqual`, `XCTAssertTrue`, `expect(`, `assert(`, `expect_eq!`, `assertEquals` calls anywhere outside comments. (A test file with declarations but no assertions is a stub.)
+
+**The detector:**
+
+```bash
+# pseudocode — actual implementation can be inline grep or a tiny dispatched subagent
+EXIT=0
+for f in $(find . -path '*/cap*Tests/*.swift' -o -path '*Tests*/*.swift' -o -path '*/__tests__/*.{js,ts}' -o -path '*/tests/*.py' -type f); do
+  size=$(wc -c < "$f")
+  has_template=$(grep -cE 'Use XCTAssert and related functions|Write your test here|XCUIApplication Documentation|Swift Testing Documentation|developer\.apple\.com/documentation/testing|developer\.apple\.com/documentation/xcuiautomation|it\.todo\(|test\.todo\(|expect\(true\)\.toBe\(true\)' "$f")
+  has_assertions=$(grep -cE '#expect\(|XCTAssert|expect\(|assert\(|expect_eq!|assertEquals' "$f")
+
+  if [ "$size" -lt 500 ]; then
+    echo "STUB: $f (size $size bytes < 500)"
+    EXIT=1
+  elif [ "$has_template" -gt 0 ]; then
+    echo "STUB: $f (Apple template markers detected)"
+    EXIT=1
+  elif [ "$has_assertions" -eq 0 ]; then
+    echo "STUB: $f (zero assertion calls)"
+    EXIT=1
+  fi
+done
+exit $EXIT
+```
+
+**Behavior on stub detection:**
+
+- Spawn a fix agent with the SPECIFIC directive: "Test stub detected at [file_path]. The corresponding spec field in `sprint-tasks.md` is [Behavioral Test field]. Implement the test body — write the named test, no other changes. Do not modify production code. Do not modify other test files. Return when the stub detector passes for this file."
+- Re-run the stub detector after the fix agent returns.
+- MAX 2 fix attempts per stub file. If still a stub after 2 attempts, FAIL the verification with a hard directive to the user that the spec declared a Behavioral Test the implementer agent could not implement.
+
+**Why size+content+assertion-count combined:** each rule alone has false positives. Size alone misses the case where the developer kept the function name `testExample` but wrote real assertions inside. Template markers alone miss the case where someone deleted the comments but left the body empty. Zero assertions alone catches the most cases but would false-positive on a "test fixtures" file that defines helpers without assertions. Composite check catches the high-confidence cases (capdotai matches all three) and only false-positives on files that are deliberately small AND deliberately template-marked AND deliberately assertion-free — which is structurally impossible for a real test.
+
 ## Step 3: Handle Result
 
 **On PASS:** Log `VERIFY: PASS (7/7)` to `docs/plans/.build-state.md`. Proceed to next phase.

package/protocols/visual-dna.md

@@ -0,0 +1,185 @@
+# Visual DNA Protocol
+
+Phase 3.0 Brand Guardian locks a 7-axis Visual DNA card that becomes the single source of truth for every downstream Phase 3 design step and every Phase 4 implementer that touches visual output. Visual Research (3.1), Visual Designer (3.2, 3.4), UX Architect (3.3), Inclusive Visuals Specialist (3.5), Frontend Developer generator (3.6), Design Critic (3.6), Accessibility Auditor (3.7), and every Phase 4 implementer via `refs.json` read this card before producing any visual artifact. It is the most load-bearing artifact in the visual pipeline — if the DNA drifts, every downstream surface drifts with it. This protocol exists to make the schema, ownership, and legal-combination rules explicit.
+
+## 1. The 7 axes
+
+Each axis has a closed value set. Brand Guardian picks one value per axis at Phase 3.0 and never revises it mid-build (a DNA revision is a new build session).
+
+### Scope
+
+**Values:** Marketing / Product / Dashboard / Internal Tool
+
+Scope is the **gating axis**. It decides which libraries get vendored into the Phase 4 scaffold and sets the per-page bundle budget enforced by the Phase 6 SRE chapter. Three.js/WebGL libraries install only for Marketing or Product-with-Expressive-motion; dashboards and internal tools never ship them. Perf budgets: Marketing 500KB, Product 300KB, Dashboard 400KB, Internal Tool 200KB (gzipped, excluding images). Exceeding budget by >25% auto-blocks the LRR SRE chapter.
+
+### Density
+
+**Values:** Airy / Balanced / Dense
+
+Density controls the spacing scale, type size ramp, whitespace rhythm, and information-per-viewport target. Airy is marketing-friendly breathing room; Dense is power-user tool territory (Linear, Superhuman, Datadog consoles). The Visual Designer at 3.4 maps this to concrete Tailwind spacing tokens and line-height ramps.
+
+### Character
+
+**Values:** Minimal / Editorial / Maximalist / Brutalist / Playful
+
+Character is the overall visual personality. It drives typographic choice, color saturation, decoration rules, and the general "what kind of product is this" read within 200ms of page load. Minimal is Stripe-adjacent. Editorial is magazine-like with strong type hierarchy. Maximalist is decoration-heavy (aceternity/ui territory). Brutalist is raw and aggressive. Playful is rounded, animated, approachable.
+
+### Material
+
+**Values:** Flat / Glassy / Physical / Neumorphic
+
+Material is the surface treatment across every card, modal, button, and panel. It determines blur radii, border styles, elevation system, and shadow character. Flat is modern shadcn default. Glassy is backdrop-filter blur + subtle borders (Apple / Vercel aesthetic). Physical is realistic drop shadows and depth. Neumorphic is soft inset/outset shadows (fragile — breaks contrast easily).
+
+### Motion
+
+**Values:** Still / Subtle / Expressive / Cinematic
+
+Motion drives easing curves, animation durations, scroll choreography, hover feedback, and page transitions. Still is no motion. Subtle is shadcn-default hover transitions (150-200ms ease-out). Expressive is framer-motion choreography with spring physics. Cinematic is GSAP + ScrollTrigger with 500-800ms eases — the Neuform / aura.build kind of motion that requires heavy libraries and is bundle-expensive.
+
+### Type
+
+**Values:** Neutral Sans / Humanist Sans / Serif-forward / Display-forward / Mono-accented
+
+Type is the font-pairing strategy. It controls primary/secondary font choice, tracking rules, and optical sizing decisions. Neutral Sans is Inter / Geist (safe default). Humanist Sans is Söhne / Söhne Breit (warmer). Serif-forward is Tiempos / GT Super (editorial feel). Display-forward is a bold display face paired with a neutral body. Mono-accented uses JetBrains Mono / IBM Plex Mono for labels and callouts inside an otherwise-sans design. Specific font pairings live in `docs/library-refs/component-library-catalog.md`, not here.
+
+### Copy
+
+**Values:** Functional / Narrative / Punchy / Technical
+
+Copy is the language register across headlines, CTAs, labels, and microcopy. It controls vocabulary density, sentence rhythm, and the emotional distance between product and user. Functional is labels-only, no sales language — content-first (Notion, Linear dashboard). Narrative uses scene-setting and emotional pull — headlines paint a moment (Stripe, Loom). Punchy enforces 3-5 word headlines, one idea per sentence, newspaper economy — cut half, then cut again (Arc, Raycast). Technical uses precise terminology, spec-like voice, avoids marketing softeners — values exactness over warmth (Vercel, Railway).
+
+## 2. Incompatibility matrix
+
+<HARD-GATE>
+Brand Guardian is forbidden from locking any of the combinations below. If the user's references or design doc push toward an illegal combo, Brand Guardian picks the closest legal alternative and emits a decision-log row explaining the rejection.
+</HARD-GATE>
+
+| # | Illegal combination | Why |
+|---|---|---|
+| 1 | Dashboard + Cinematic motion | Dashboards need snappy feedback (100-200ms), not 650ms cinematic eases. Users lose their place. |
+| 2 | Internal Tool + Maximalist character | Internal tools exist for fast parse; decoration-heavy styling buries the data users came for. |
+| 3 | Internal Tool + Expressive or Cinematic motion | Internal tools ship at <200KB budget; framer-motion choreography + GSAP break that budget. |
+| 4 | Marketing + Dense density | Marketing pages need breathing room to sell; dense kills scroll rhythm and conversion. |
+| 5 | Dashboard + Glassy material + Dense density | Glass blur on dense data surfaces renders unreadable — the backdrop-filter eats legibility. |
+| 6 | Dashboard + Serif-forward type | Dashboards need high-readability UI faces at small sizes; serifs lose clarity at 12-14px. |
+| 7 | Product + Neumorphic material (with WCAG AA target) | Neumorphic shadows depend on low-contrast surfaces; AA contrast math fails by construction. |
+| 8 | Brutalist character + Glassy material | Brutalism is raw, unapologetic, unadorned; glass is the opposite ethos. Visual contradiction. |
+| 9 | Playful character + Still motion | Playful without motion reads as stiff and off-brand. Playful implies at least Subtle motion. |
+| 10 | Marketing + Still motion | Marketing pages rely on scroll reveal and choreography to guide attention; Still kills that. |
+| 11 | Internal Tool + Display-forward type | Display faces are for hero moments, not tool chrome. Clashes with fast-parse requirement. |
+| 12 | Dashboard + Physical material | Heavy drop shadows on data grids add visual noise that competes with the chart ink. |
+| 13 | Playful character + Technical copy | Playful implies approachable warmth; technical copy creates cognitive dissonance — the visual feel promises friendliness, the words deliver distance. |
+| 14 | Brutalist character + Narrative copy | Brutalism is raw, direct, unapologetic; narrative copy is storytelling and emotional pull — the aesthetic actively rejects the storytelling register. |
+
+Anything not on this list is legal. When two legal combinations both fit the user's references, Brand Guardian reads `quality-targets.json` and the architecture stack to resolve ties (e.g., if the stack is Next.js + shadcn default and quality-targets say "fast MVP," prefer Flat over Glassy).
+
+## 3. Schema
+
+The DNA card lives at `docs/plans/visual-dna.md` — one file per build, locked at Phase 3.0. Shape:
+
+```markdown
+---
+locked_at: 2026-04-14T01:23:45Z
+locked_by: Brand Guardian
+build_session: <session_id>
+---
+
+# Visual DNA
+
+## Axes
+
+- Scope: Marketing
+- Density: Airy
+- Character: Editorial
+- Material: Glassy
+- Motion: Expressive
+- Type: Display-forward
+- Copy: Punchy
+
+## Rationale
+
+<why these axes, with explicit references to design-doc.md sections and findings-digest signals
+that pushed each axis to the chosen value; 4-8 sentences total, no padding>
+
+## References that exemplify this DNA
+
+- <url or path> — exemplifies Character + Motion
+- <url or path> — exemplifies Material + Type
+- <url or path> — exemplifies Scope + Density
+```
+
+<HARD-GATE>
+SCHEMA CONTRACT:
+
+- All seven axis fields MUST be present and MUST be one of the allowed values from Section 1.
+- The combination across all six axes MUST NOT appear in the Section 2 incompatibility matrix.
+- `locked_at` is set exactly once, at Phase 3.0 Brand Guardian completion, and is never rewritten.
+- `References that exemplify this DNA` MUST contain at least two entries, each tied to specific axis pairs. "Looks good" without axis attribution is not permitted.
+- Only `docs/plans/visual-dna.md` is the canonical location. No other path is read.
+</HARD-GATE>
+
+## 4. Ownership
+
+**Writer:** Brand Guardian at Phase 3.0, exactly once per build. No other agent writes `visual-dna.md`. If the user requests a DNA revision mid-build, that is a new Phase 3.0 invocation, not an edit.
+
+**Readers:**
+
+| Phase / Step | Agent | Why it reads DNA |
+|---|---|---|
+| 3.1 | Visual Research | Frames reference-site lookup queries around the locked axes instead of casting wide. |
+| 3.2 | Visual Designer (Component Library Mapping) | Picks component variants from `component-library-catalog.md` matching the DNA axis combination. |
+| 3.3 | UX Architect | Information architecture and flow choices respect Density and Character. |
+| 3.4 | Visual Designer (Visual Design Spec) | Material system, motion system, and typographic tuning all derive from Material/Motion/Type axes. |
+| 3.5 | Inclusive Visuals Specialist | Checks DNA for a11y risks (Neumorphic contrast, Dense density tap targets, Cinematic motion reduced-motion fallback). |
+| 3.6 | Frontend Developer generator | Every generated surface honors DNA; deviations flagged by Design Critic. |
+| 3.6 | Design Critic | Scores rendered output against DNA on all seven axes + craft dimensions in the metric loop. |
+| 3.7 | Accessibility Auditor | Re-verifies DNA-level a11y claims from 3.5 against real rendered output. |
+| 4 | Phase 4 implementers | Read via `refs.json` primary anchor; every component they write must match DNA or compose from the DNA-matching library variants. |
+| 5 | Drift check | Verifies visual output still reads as the locked DNA. |
+| 6 | Brand Guardian chapter | Final verdict pass against DNA as ground truth. |
+
+## 5. Legal-combo examples
+
+**Premium marketing landing page — Stripe / Linear / Neuform aesthetic:**
+
+- Scope: Marketing
+- Density: Airy
+- Character: Editorial
+- Material: Glassy
+- Motion: Expressive
+- Type: Display-forward
+- Copy: Punchy
+
+Airy density + Editorial character gives the breathing room and strong type hierarchy. Glassy material + Display-forward type hits the premium feel. Expressive motion is the bundle budget ceiling Marketing scope can afford without tipping into Cinematic territory. Punchy copy matches the premium marketing register — short, declarative headlines that let the type and motion carry the emotional weight. All seven axes reinforce the same read.
+
+**Internal analytics dashboard — Datadog / Grafana aesthetic:**
+
+- Scope: Dashboard
+- Density: Balanced
+- Character: Minimal
+- Material: Flat
+- Motion: Subtle
+- Type: Humanist Sans
+- Copy: Functional
+
+Minimal character + Flat material + Humanist Sans is the "tool chrome that disappears" combination. Subtle motion keeps interactions snappy without distracting from the data. Balanced density fits dashboard chart density without triggering the Glassy + Dense incompatibility. Functional copy keeps labels terse and data-first — no marketing softeners competing with the charts for attention. Ships well under the 400KB Dashboard budget.
+
+**Consumer productivity app — Notion / Superhuman aesthetic:**
+
+- Scope: Product
+- Density: Balanced
+- Character: Minimal
+- Material: Physical
+- Motion: Expressive
+- Type: Neutral Sans
+- Copy: Functional
+
+Minimal + Neutral Sans is the "content is the hero" base. Physical material adds just enough depth to make interactive surfaces feel tactile. Expressive motion is where Superhuman-style transitions live. Functional copy keeps the interface out of the way of the user's content — the app labels actions, it doesn't narrate them. Product scope allows the motion library cost, since it's inside the 300KB budget when managed carefully.
+
+## 6. Illegal-combo example
+
+**Dashboard + Maximalist + Cinematic — rejected.**
+
+Three conflicts at once. Dashboards need parse-speed, which Maximalist actively fights by burying data under decoration. Cinematic motion (650ms+ eases) is too slow for the interaction rhythm dashboards require — a user filtering a table cannot wait 800ms for every state change. And the combined library cost of aceternity-heavy maximalist surfaces + GSAP cinematic motion blows the 400KB Dashboard budget on its own before any app code is added.
+
+When the user's references push toward this combination (e.g., "I want it to feel like [Neuform marketing page] but it's actually a dashboard"), Brand Guardian rejects the combination, writes a decision-log row naming the incompatibility, and asks the user to pick a direction: keep the scope and drop the Maximalist/Cinematic, or change the product scope to Marketing (which will change the whole app's shape, not just its look). There is no middle ground — the axes are load-bearing, not decorative.