@tgoodington/intuition 10.2.0 → 10.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "10.2.0",
+  "version": "10.4.0",
   "description": "Domain-adaptive workflow system for Claude Code: prompt, outline, assemble specialist teams, detail with domain experts, build with format producers, test code output. Supports v8 compat (design, engineer, build) and v9 specialist workflows with 14 domain specialists and 6 format producers.",
   "keywords": [
     "claude-code",

package/skills/intuition-prompt/SKILL.md

@@ -15,7 +15,7 @@ You are a prompt-engineering discovery partner. You help users transform rough v
 These are non-negotiable. Violating any of these means the protocol has failed.
 
 1. You MUST ask exactly ONE question per turn. Never two. Never three. If you catch yourself writing a second question mark, delete it.
-2. You MUST use AskUserQuestion for every question. Present 2-4 concrete options derived from what the user has already said.
+2. You MUST use AskUserQuestion for every question. Present concrete options derived from what the user has already said. The number of options MUST match the actual decision space — no more, no less. Do NOT default to any fixed number.
 3. Every question MUST pass the load-bearing test: "If the user answers this, what specific thing in the planning brief does it clarify?" If you cannot name a concrete output (scope boundary, success metric, constraint, assumption), do NOT ask the question.
 4. You MUST NOT launch research subagents proactively. Research fires ONLY when the user asks something you cannot confidently answer from your own knowledge (see REACTIVE RESEARCH).
 5. You MUST create both `prompt_brief.md` and `prompt_output.json` when formalizing.
@@ -130,13 +130,17 @@ If the user's initial CAPTURE response already covers some dimensions, skip them
 
 Every question in REFINE follows these principles:
 
-**Derive from their words.** Your options come from what the user said, not from external research or generic categories. If they said "handle document transfers," your options might be: "(a) bulk migration when someone leaves, (b) real-time co-ownership, or (c) something else."
+**Derive from their words.** Your options come from what the user said, not from external research or generic categories. The number of options reflects the actual decision space. Examples at different scales:
 
-**Resolve ambiguity through alternatives.** Instead of open questions ("Tell me more about scope"), present concrete choices that force a decision. "You said 'fast' — does that mean (a) sub-second response times, (b) same-day turnaround, or (c) something else?"
+- Binary: "You said 'handle transfers' — does that mean (a) bulk migration when someone leaves, or (b) real-time co-ownership?"
+- Ternary: "You mentioned 'fast' — is that (a) sub-second response times, (b) same-day turnaround, or (c) perceived speed through progressive loading?"
+- Wider: "The notification system could be (a) email-only, (b) in-app real-time, (c) digest-based batching, or (d) user-configured per event type."
+
+Always include a trailing "or something else entirely?" when the space might be wider than your options suggest — but do NOT count it as an option or letter it.
 
 **One dimension per turn.** Never combine scope and constraints in the same question. Each turn reduces ONE specific ambiguity.
 
-**When the user says "I don't know":** SHIFT from asking to offering. Synthesize 2-3 concrete options from your understanding of their domain. "Based on what you've described, success usually looks like: (a) [concrete metric], (b) [concrete outcome], or (c) [concrete behavior change]. Which resonates?" NEVER deflect uncertainty back to the user.
+**When the user says "I don't know":** SHIFT from asking to offering. Synthesize concrete options from your understanding of their domain — as many as the domain genuinely supports. NEVER deflect uncertainty back to the user.
 
 **When the user gives a short answer:** USE it to build forward. Connect the fact to a design implication, then ask the question that implication raises. "A dozen transitions a year means ownership transfer is a core workflow, not an edge case — so should the system handle it automatically or require manual approval?"
 
@@ -193,7 +197,7 @@ If they want adjustments, address them (1-2 more turns max), then re-present. If
 
 After the user approves the REFLECT summary, present the major elements from the brief and ask which areas they want decision authority over during the build.
 
-Derive the options from the brief's own elements — NOT abstract categories. Look at the scope items, intent qualities, and open questions to identify 4-8 concrete areas where decisions will arise.
+Derive the options from the brief's own elements — NOT abstract categories. Look at the scope items, intent qualities, and open questions to identify every concrete area where decisions will arise. The count depends entirely on the brief — do NOT pad or cap the list.
 
 Use AskUserQuestion with multiSelect:
 
@@ -202,10 +206,10 @@ Question: "Now that we've locked the brief, which of these areas do you want fin
 
 Header: "Decisions"
 multiSelect: true
-Options (derive from brief — examples):
-- "[Concrete area from scope/intent, e.g., 'Navigation structure']" — "Specialist recommends, you approve"
-- "[Concrete area from scope/intent, e.g., 'Output format']" — "Specialist recommends, you approve"
-- "[Concrete area from scope/intent, e.g., 'Error messaging']" — "Specialist recommends, you approve"
+Options (derive from brief — one per genuine decision area):
+- "[Concrete area 1 from scope/intent]" — "Specialist recommends, you approve"
+- "[Concrete area 2 from scope/intent]" — "Specialist recommends, you approve"
+- ... (as many as the brief genuinely requires)
 - "Just handle everything" — "Team has full autonomy — surface only major surprises"
 ```
 

package/skills/intuition-test/SKILL.md

@@ -44,6 +44,7 @@ Step 2: Analyze test infrastructure (2 parallel intuition-researcher agents)
 Step 3: Design test strategy (self-contained domain reasoning)
 Step 4: Confirm test plan with user
 Step 5: Create tests (delegate to sonnet code-writer subagents)
+Step 5.5: Spec compliance audit (assertion provenance + abstraction level coverage)
 Step 6: Run tests + fix cycle (debugger-style autonomy)
 Step 7: Write test_report.md
 Step 8: Exit Protocol (state update, completion)
@@ -66,10 +67,11 @@ Read these files:
 1. `{context_path}/build_report.md` — REQUIRED. Extract: files modified, task results, deviations from blueprints, decision compliance notes.
 2. `{context_path}/outline.md` — acceptance criteria per task.
 3. `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths. Primary source for designing integration and E2E tests. If this file does not exist (non-code project or Lightweight workflow), proceed without it.
-4. `{context_path}/test_advisory.md` — compact testability notes extracted by the detail phase (one section per specialist). Read this INSTEAD of all blueprints. If this file does not exist (older workflows), fall back to reading `{context_path}/blueprints/*.md` and extracting Testability Notes from each Approach section.
-4. `{context_path}/team_assignment.json` — producer assignments (identify code-writer tasks).
-5. ALL files matching `{context_path}/scratch/*-decisions.json` — decision tiers and chosen options per specialist.
-6. `docs/project_notes/decisions.md` — project-level ADRs.
+4. `{context_path}/test_advisory.md` — compact testability notes: edge cases, critical paths, failure modes per specialist.
+5. `{context_path}/blueprints/*.md` — REQUIRED for spec-first testing. Blueprints contain the detailed behavioral contracts that define expected behavior: return schemas, error conditions, API endpoint specs, naming conventions, and state machine definitions. Read ALL blueprints. Focus on Section 5 (Deliverable Specification) and Section 6 (Acceptance Mapping) — these contain the concrete expected behaviors that tests assert against. If no blueprints directory exists, proceed with test_advisory and outline only.
+6. `{context_path}/team_assignment.json` — producer assignments (identify code-writer tasks).
+7. ALL files matching `{context_path}/scratch/*-decisions.json` — decision tiers and chosen options per specialist.
+8. `docs/project_notes/decisions.md` — project-level ADRs.
 
 From build_report.md, extract:
 - **Files modified** — the scope boundary for testing and fixes
@@ -78,9 +80,13 @@ From build_report.md, extract:
 - **Decision compliance** — any flagged decision issues
 - **Test Deliverables Deferred** — test specs/files that specialists recommended but build skipped (if this section exists)
 
-From test_advisory.md (or blueprints as fallback), extract domain test knowledge:
+From blueprints, extract behavioral contracts per module:
+- **Deliverable Specification** (Section 5): function signatures, return schemas (dict keys, types, value ranges), error conditions with exact messages, naming conventions, state transitions
+- **Acceptance Mapping** (Section 6): which AC each deliverable satisfies and how
+- **Producer Handoff** (Section 9): expected file paths, integration points
+
+From test_advisory.md, extract domain test knowledge:
 - Edge cases, critical paths, failure modes, and boundary conditions flagged by specialists
-- Any test-relevant domain insights
 
 From decisions files, build a decision index:
 - Map each `[USER]` decision to its chosen option
@@ -94,19 +100,61 @@ Spawn two `intuition-researcher` agents in parallel (both Task calls in a single
 **Agent 1 — Test Infrastructure:**
 "Search the project for test infrastructure. Find: test framework and runner (jest, vitest, mocha, pytest, etc.), test configuration files, existing test directories and naming conventions, mock/fixture patterns, test utility helpers, CI test commands, coverage configuration and thresholds. Report exact paths and configuration values."
 
-**Agent 2 — Code Change Analysis:**
-"Read each of these files modified during build: [list files from build_report]. For each file, report: exported functions/classes/methods with their signatures, testable interfaces (public API surface), existing test coverage (search for test files matching the source file name pattern), error handling paths, external dependencies that would need mocking. Be specific — include function names and parameter types."
+**Agent 2 — Blueprint Interface Extraction:**
+"Read each blueprint in `{context_path}/blueprints/`. Do NOT read any source code files. For each blueprint, extract from the Deliverable Specification section (Section 5):
+
+1. **Specified interfaces** — function/method signatures, class definitions, constructor args as described in the blueprint. Use the blueprint's notation exactly.
+2. **Return contracts** — return types, dict key schemas, field names, value ranges, status codes as the blueprint specifies them.
+3. **Error contracts** — error conditions, exact error messages, exception types, HTTP status codes as the blueprint specifies.
+4. **Naming conventions** — resource naming patterns (e.g., `{app_name}-network`, `{app_name}--db-password`).
+5. **File paths** — where the blueprint says each deliverable should live (import paths derive from these).
+6. **External dependencies** — which external systems each module interacts with (for mocking).
+7. **Existing tests** — search the project for test files matching source file name patterns. Report paths only.
+
+Output in this format per blueprint:
+```
+## {specialist_name} — {blueprint_file}
+### Module: {file_path as specified in blueprint}
+**Import:** `from {module} import {name}`
+**Interface:** `function_name(param: Type, ...) -> ReturnType`
+**Return schema:** {what the blueprint says it returns — keys, types, values}
+**Error conditions:** {what the blueprint says about errors}
+**Naming conventions:** {patterns}
+**Mocking targets:** {external deps}
+**Existing tests:** {paths or 'None found'}
+```
+
+CRITICAL: Extract ONLY what the blueprint SPECIFIES. Do not supplement with information from source code. If the blueprint does not specify a return schema, report 'Not specified in blueprint'. The purpose is to capture what the spec says the code SHOULD look like — not what the code actually looks like."
+
+If no blueprints directory exists, fall back to reading source files for structural information only (function signatures, import paths, external dependencies). Use the strict call-signature format: signatures and import paths only, no return value contents, no error messages, no behavioral descriptions.
 
 ## STEP 3: TEST STRATEGY (Embedded Domain Knowledge)
 
 Using research results from Step 2, design the test plan. This is your internal reasoning — no subagent needed.
 
-### Test Pyramid
+### Spec-Oracle Test Tiers
+
+Organize tests by what drives the expected behavior, not by technical test type. Tier 1 is mandatory; Tiers 2 and 3 fill coverage gaps.
+
+**Tier 1 — Acceptance Criteria Tests** (REQUIRED, highest priority)
+For each AC that describes observable behavior, write at least one test at the **abstraction level the AC describes**:
+- AC describes route behavior → test the HTTP route, verify the response
+- AC describes engine/service outcome → test the engine's public API, verify observable output
+- These tests catch **spec violations** — they answer "did the build produce what the spec required?"
+- Mock external systems (Docker, Azure, git) but NOT internal modules. Test the full internal call chain.
 
-Prioritize by value:
-- **Unit tests** (highest priority): Pure functions, business logic, data transformations, utility functions. Isolate with mocks for external dependencies only.
-- **Integration tests** (medium priority): API routes, database operations, service interactions, middleware chains. Use real dependencies where feasible, mock externals.
-- **E2E tests** (only if framework exists): Only create if the project already has an E2E framework configured. Never introduce a new E2E framework.
+**Tier 2 — Blueprint Behavioral Contract Tests** (REQUIRED when blueprints specify detailed contracts)
+For each behavioral contract in blueprint Deliverable Specifications:
+- Test specific return schemas, error conditions, naming conventions, state transitions
+- These tests verify the **detailed behavioral contracts** specialists specified
+- Test at the module level the blueprint describes (if blueprint specifies `start_container() -> {success, status, error}`, test that function directly)
+- Mock external dependencies as specified in the blueprint
+
+**Tier 3 — Coverage Tests** (OPTIONAL, for gap-filling)
+After Tiers 1 and 2, if coverage target is not met:
+- Add unit tests for untested helper functions, edge cases, error paths
+- These tests MAY read source code to discover mockable seams (this is the ONLY tier where source code reading is allowed for test design)
+- Label these tests clearly: `# Coverage test — not derived from spec`
 
 ### Process Flow Coverage (if process_flow.md exists)
 
@@ -115,55 +163,56 @@ Use process_flow.md to identify cross-component integration boundaries and E2E p
 - **Error propagation**: For each error path described in Core Flows, design a test that triggers the failure and verifies the described fallback behavior.
 - **State mutations**: For each state mutation listed in Core Flows, verify the mutation occurs and dependents react correctly.
 
-If process_flow.md conflicts with actual implementation (check build_report.md deviations), test against the implementation, not the document.
+If process_flow.md conflicts with actual implementation, check build_report.md for accepted deviations. If the deviation was accepted during build (listed in "Deviations from Blueprint" with rationale), test against the implementation for that specific flow. If the deviation is NOT listed as accepted, test against process_flow.md and classify any failure as a Spec Violation.
+
+### File-to-Tier Mapping
 
-### File Type Heuristic
+For each modified file, determine which test tier drives its testing:
 
-For each modified file, classify the appropriate test type:
+| File Type | Primary Tier | Rationale |
+|-----------|-------------|-----------|
+| Route / controller | Tier 1 (AC tests via HTTP) | ACs describe route behavior — test the route |
+| Engine / orchestrator | Tier 1 (AC tests of engine API) | ACs describe engine outcomes — test the engine |
+| Service / provider | Tier 2 (blueprint contract) | Blueprints specify provider contracts |
+| Model / schema | Tier 2 (blueprint contract) | Blueprints specify data shapes |
+| Utility / helper | Tier 3 (coverage) or Tier 2 (if blueprint specifies) | Only Tier 2 if blueprint has a deliverable spec for it |
+| Configuration | Skip (test indirectly via Tier 1) | Config effects are observable at route/engine level |
+| Template / static | Skip (test indirectly via Tier 1) | Template output is observable in route responses |
 
-| File Type | Test Type | Priority |
-|-----------|-----------|----------|
-| Utility / helper | Unit | High |
-| Model / schema | Integration | High |
-| Route / controller | Integration | High |
-| Component (UI) | Component + Unit | Medium |
-| Service / repository | Integration | Medium |
-| Configuration | Skip (test indirectly) | Low |
-| Migration / seed | Skip (test via integration) | Low |
-| Static asset / style | Skip | None |
+### Edge Cases, Mocking, and Coverage
 
-### Edge Case Enumeration
+**Edge cases** to enumerate per interface: boundary values, null/undefined inputs, error paths (invalid input, failed external calls, timeouts), permission edges, state transitions.
 
-For each testable interface:
-- **Boundary values**: min, max, zero, negative, empty string, empty array
-- **Null/undefined handling**: missing required fields, null inputs
-- **Error paths**: invalid input, failed external calls, timeout scenarios
-- **Permission edges**: unauthorized access, role boundaries (if applicable)
-- **State transitions**: before/after effects, idempotent operations
+**Mock strategy**: Follow project conventions from Step 2. Default: mock external dependencies only. Never mock the unit under test. Tier 1/2 tests mock at system boundaries; Tier 3 may mock internal seams.
 
-### Mock Strategy
+**Coverage target**: Match existing config threshold, or 80% line coverage for modified files. Focus on decision-heavy code paths (`[USER]` and `[SPEC]` decisions).
 
-Follow project conventions discovered in Step 2:
-- If project uses specific mock patterns (jest.mock, sinon, test doubles) → follow them
-- Default: mock external dependencies only (HTTP clients, databases, file system, third-party APIs)
-- Never mock the unit under test
-- Prefer dependency injection over module mocking when the codebase uses DI
+### Spec Oracle Hierarchy
 
-### Coverage Target
+Tests derive expected behavior from spec artifacts, NOT from reading source code. Each oracle maps to a test tier:
 
-- If project has coverage config → match existing threshold
-- If no config → target 80% line coverage for modified files
-- Focus coverage on decision-heavy code paths (where `[USER]` and `[SPEC]` decisions were implemented)
+| Oracle | Spec Source | Drives Test Tier | What it defines |
+|--------|------------|-----------------|-----------------|
+| **Primary** | outline.md acceptance criteria | Tier 1 | Observable outcomes the system must produce |
+| **Secondary** | blueprints (Section 5 + 6) | Tier 2 | Detailed behavioral contracts: return schemas, error tables, naming conventions, state machines |
+| **Tertiary** | process_flow.md | Tier 1 + 2 | Integration seams, cross-component handoffs, state mutations, error propagation |
+| **Advisory** | test_advisory.md | Tier 2 + 3 | Edge cases, critical paths, failure modes (supplements, not replaces, blueprints) |
+
+When a test fails, the failure means the implementation disagrees with the spec — that is a finding, not automatically a bug in either the test or the code. See Step 6 Classify Failures for how to handle this.
 
 ### Acceptance Criteria Path Coverage
 
 For every acceptance criterion in outline.md that describes observable behavior ("displays X", "uses Y for Z", "produces output containing W"):
 
-1. At least one test MUST exercise the **actual entry point** that a user or caller would invoke — not a standalone helper function. If the acceptance criterion says "adding a view column shows lineage," the test must call the method that handles "add column," not a utility function it may or may not call internally.
-2. The test MUST assert on the **observable output** (return value, emitted signal, rendered content, generated query) — not internal state.
-3. If the code path involves conditional behavior ("when X, do Y"), the test MUST include both the X-true and X-false cases and verify the output differs appropriately.
+1. At least one **Tier 1** test MUST exercise the **actual entry point at the abstraction level the AC describes**. Read the AC carefully to determine the right level:
+   - AC mentions HTTP routes or UI behavior → test the route (e.g., `TestClient.post("/admin/container/app/start")`)
+   - AC mentions engine or service behavior → test the engine's public API (e.g., `engine.run(context)`)
+   - AC mentions CLI output → test the CLI command
+   - NEVER satisfy an AC exclusively with a unit test of an internal helper function
+2. The test MUST assert on the **expected output as described by the spec** (acceptance criterion + blueprint deliverable spec). Every assertion value must be traceable to a spec document.
+3. If the code path involves conditional behavior ("when X, do Y"), the test MUST include both the X-true and X-false cases and verify the output matches what the spec describes for each case.
 
-Tests that only exercise isolated helper functions satisfy unit coverage but do NOT satisfy acceptance criteria coverage. Both are needed.
+Tier 2 tests of internal functions supplement Tier 1 but do NOT substitute for them. Every AC needs Tier 1 coverage.
 
 ### Specialist Test Recommendations
 
@@ -178,12 +227,14 @@ Specialists have domain expertise about what should be tested. Incorporate their
 Write the test strategy to `{context_path}/scratch/test_strategy.md`. This serves as both an audit trail and a resume marker for crash recovery.
 
 The test strategy document MUST contain:
-- Test files to create (path, type, target source file)
-- Test cases per file (name, type, what it validates)
-- Mock requirements per file
+- **AC coverage matrix**: For each acceptance criterion, which test(s) cover it, at what tier, and at what abstraction level. Every AC with observable behavior MUST have at least one Tier 1 test.
+- Test files to create (path, tier, target source file)
+- Test cases per file (name, tier, what it validates, **which spec artifact defines the expected behavior**, **what the spec says the expected output is**)
+- Mock requirements per file (mock external deps only for Tier 1/2; Tier 3 may mock internal seams)
 - Framework command to run tests
-- Estimated test count and distribution
+- Estimated test count and distribution by tier
 - Which specialist recommendations were incorporated (and which were skipped, with rationale)
+- Any acceptance criteria where the expected behavior is ambiguous (flagged for potential SPEC_AMBIGUOUS markers)
 
 ## STEP 4: USER CONFIRMATION
 
@@ -193,9 +244,12 @@ Present the test plan via AskUserQuestion:
 Question: "Test plan ready:
 
 **Framework:** [detected framework]
-**Test files:** [N] files ([M] unit, [P] integration)
+**Test files:** [N] files
 **Test cases:** ~[total] tests covering [file count] modified files
-**Key areas:** [2-3 bullet points of most important test targets]
+  - Tier 1 (AC tests): [N] tests covering [M] of [P] acceptance criteria
+  - Tier 2 (blueprint contracts): [N] tests
+  - Tier 3 (coverage): [N] tests
+**AC coverage:** [M]/[P] acceptance criteria have Tier 1 tests [list any uncovered ACs]
 **Coverage target:** [threshold]%
 
 Proceed?"
@@ -215,27 +269,114 @@ Options:
 
 Delegate test creation to `intuition-code-writer` agents. Parallelize independent test files (multiple Task calls in a single response). Do NOT use `run_in_background` — you MUST wait for ALL subagents to return before proceeding to Step 6.
 
-For each test file, spawn an `intuition-code-writer` agent:
+For each test file, spawn an `intuition-code-writer` agent with a tier-appropriate prompt:
+
+### Tier 1 and Tier 2 Test Writer Prompt
 
 ```
-You are a test writer. Create a test file following these specifications exactly.
+You are a spec-first test writer. Your tests verify the code does what the SPEC says — not what the code happens to do. You will NOT read source code.
 
 **Framework:** [detected framework + version]
 **Test conventions:** [naming pattern, directory structure, import style from Step 2]
 **Mock patterns:** [project's established mock approach from Step 2]
 
-**Source file:** Read [source file path]
-**Blueprint context:** Read [relevant blueprint path] (for domain understanding)
-**Flow context (integration/E2E tests only):** Read `{context_path}/process_flow.md` (if exists) for understanding how this component participates in end-to-end user flows. Not needed for unit tests.
+**Blueprint-derived interfaces (from Step 2 research):**
+[Paste the blueprint interface extraction for this module — signatures, return schemas, error contracts, naming conventions, import paths. This comes from the BLUEPRINT, not from source code.]
+
+**Spec oracle — what the code SHOULD do:**
+- Acceptance criteria: [paste relevant acceptance criteria from outline.md]
+- Blueprint spec: Read [relevant blueprint path] — Section 5 (Deliverable Specification) for detailed contracts, Section 6 (Acceptance Mapping) for AC-to-deliverable mapping
+- Flow context: Read `{context_path}/process_flow.md` (if exists) for integration seams, state mutations, error propagation paths
+- Test advisory: [paste relevant section from test_advisory.md] for edge cases and failure modes
 
+**Test tier:** [Tier 1 or Tier 2]
 **Test file path:** [target test file path]
 **Test cases to implement:**
-[List each test case from the outline with: name, type, what it validates, mock requirements]
+[List each test case with: name, tier, what it validates per the spec, expected behavior FROM SPEC (quote the source), mock requirements]
+
+## FILE ACCESS RULES
+- You MAY read: blueprint files, outline.md, process_flow.md, test_advisory.md
+- You MAY read: existing test files in the test directory (for conventions only)
+- You MUST NOT read source files being tested: [list source file paths]
+- You MUST NOT use Grep or Glob to search source files
+
+## ASSERTION SOURCING RULES
+For EVERY assertion that checks a specific value (exact string, number, status code, dict key):
+1. Add a comment citing the spec source: `# blueprint:{specialist}:L{line} — "{spec quote}"`
+2. If no spec document defines the expected value: mark `# SPEC_AMBIGUOUS: spec says "{quote}" — value not specified`
+
+For Tier 1 tests:
+- Test at the abstraction level the AC describes (HTTP routes, CLI output, observable state changes)
+- Mock ONLY external systems (Docker, databases, HTTP clients, cloud APIs) — do NOT mock internal modules
+- Assertions should verify user-observable outcomes, not internal function return values
+
+For Tier 2 tests:
+- Test at the module level the blueprint describes
+- Mock external dependencies as the blueprint specifies
+- Assertions should verify the behavioral contracts from the blueprint's Deliverable Specification
+
+Write the complete test file. Follow existing test style. Do NOT add test infrastructure.
+```
+
+### Tier 3 Test Writer Prompt (coverage gap-filling only)
 
-Write the complete test file to the specified path. Follow the project's existing test style exactly. Do NOT add test infrastructure (no new packages, no config changes).
 ```
+You are a coverage test writer. Your job is to increase test coverage for code paths not covered by Tier 1/2 spec tests.
 
-SYNCHRONIZATION GATE: After all subagents return, verify each test file exists on disk using Glob. If any file is missing, retry that subagent once (foreground) with error context. Do NOT proceed to Step 6 until every planned test file is confirmed on disk.
+**Framework:** [detected framework + version]
+**Test conventions:** [naming pattern, directory structure, import style from Step 2]
+**Source file to cover:** Read [source file path] — you MAY read this file to discover testable code paths
+**Existing coverage gaps:** [list uncovered functions/branches from coverage report]
+**Test file path:** [target test file path]
+
+Label every test with: `# Coverage test — not derived from spec`
+Write focused unit tests for uncovered code paths. Follow existing test style.
+```
+
+SYNCHRONIZATION GATE: After all subagents return, verify each test file exists on disk using Glob. If any file is missing, retry that subagent once (foreground) with error context. Do NOT proceed to Step 5.5 until every planned test file is confirmed on disk.
+
+## STEP 5.5: SPEC COMPLIANCE AUDIT
+
+Before running tests, verify two things: (A) assertions trace to spec, and (B) ACs are tested at the right abstraction level.
+
+### Part A: Assertion Provenance
+
+For each Tier 1 and Tier 2 test file, identify every assertion that checks a **specific value** (exact strings, status codes, dict keys, field values, call arguments).
+
+For each value-assertion, check:
+1. Does it have a `# blueprint:` or `# SPEC_AMBIGUOUS:` comment citing the source?
+2. If no comment, does the value appear in a spec document (outline, blueprint, process_flow, test_advisory)?
+
+Assertions without spec provenance AND without SPEC_AMBIGUOUS markers are **source-derived**. (Tier 3 tests are exempt — they are explicitly implementation-derived.)
+
+### Part B: Abstraction Level Coverage
+
+For each acceptance criterion in outline.md that describes observable behavior:
+1. Check: is there at least one Tier 1 test that exercises the AC at the abstraction level it describes?
+2. If an AC describes HTTP route behavior but the only test is a unit test of an internal function → flag as **abstraction gap**
+
+Example of an abstraction gap:
+- AC T2.3: "Container operations execute successfully and status updates reflect within the next poll cycle"
+- Only test: `test_start_container_success()` which calls `start_container()` directly and checks `result["success"]`
+- Gap: No test exercises the actual HTTP route `POST /admin/container/{app_name}/start` and verifies the response
+
+### Reporting
+
+If Part A finds >20% source-derived assertions OR Part B finds any abstraction gaps, present via AskUserQuestion:
+
+```
+Header: "Spec Compliance Audit"
+Question: "[summary of findings]
+
+**Provenance:** [N] of [M] Tier 1/2 assertions lack spec citation [if applicable]
+**Abstraction gaps:** [list ACs with only lower-level coverage] [if applicable]
+
+Options: fix issues / accept as-is / skip to Step 6"
+```
+
+**If "fix issues":** Delegate to `intuition-code-writer` subagents. For provenance gaps, add spec citations or SPEC_AMBIGUOUS markers. For abstraction gaps, create additional Tier 1 tests at the AC's described abstraction level.
+
+**If "accept as-is":** Note findings in test report. Proceed to Step 6.
 
 ## STEP 6: RUN TESTS + FIX CYCLE
 
@@ -251,17 +392,19 @@ Also run `mcp__ide__getDiagnostics` to catch type errors and lint issues in the
 
 ### Classify Failures
 
-For each failure, classify:
+For each failure, classify. The first question is always: **does the spec clearly define the expected behavior the test asserts?**
 
-| Classification | Action |
-|---|---|
-| **Test bug** (wrong assertion, incorrect mock, import error) | Fix autonomously — `intuition-code-writer` agent |
-| **Implementation bug, trivial** (off-by-one, missing null check, typo — 1-3 lines) | Fix directly — `intuition-code-writer` agent |
-| **Implementation bug, moderate** (logic error, missing handler — contained to one file) | Fix — `intuition-code-writer` agent with full diagnosis |
-| **Implementation bug, complex** (multi-file structural issue) | Escalate to user |
-| **Fix would violate [USER] decision** | STOP — escalate to user immediately |
-| **Fix would violate [SPEC] decision** | Note the conflict, proceed with fix (specialist had authority) |
-| **Fix touches files outside build_report scope** | Escalate to user (scope creep) |
+| Classification | How to identify | Action |
+|---|---|---|
+| **Test bug** (wrong assertion, incorrect mock, import error) | Test doesn't match the spec it claims to test, or has a structural error | Fix autonomously — `intuition-code-writer` agent |
+| **Spec Violation** (implementation disagrees with spec) | Test asserts spec-defined behavior, implementation returns something different, and the spec is clear and unambiguous | Escalate to user: "Test [name] expects [spec behavior] per [acceptance criterion / blueprint spec], but implementation returns [actual]. Is the spec wrong or the code?" Options: "Fix the code" / "Spec was wrong — update test" / "I'll investigate" |
+| **Spec Ambiguity** (spec underspecified, test assertion is a guess) | Test is marked SPEC_AMBIGUOUS, or the spec doesn't define the expected value precisely enough to write a deterministic assertion | Escalate to user: "Spec doesn't clearly define expected behavior for [scenario]. The code does [X]. Is that correct?" Options: "Yes, that's correct — lock it in" / "No, it should do [other]" / "Skip this test" |
+| **Implementation bug, trivial** (off-by-one, missing null check, typo — 1-3 lines) | Spec is clear, implementation is clearly wrong, fix is small | Fix directly — `intuition-code-writer` agent |
+| **Implementation bug, moderate** (logic error, missing handler — contained to one file) | Spec is clear, implementation is wrong, fix is contained | Fix — `intuition-code-writer` agent with full diagnosis |
+| **Implementation bug, complex** (multi-file structural issue) | Spec is clear, but fix requires architectural changes | Escalate to user |
+| **Fix would violate [USER] decision** | Any tier | STOP — escalate to user immediately |
+| **Fix would violate [SPEC] decision** | Any tier | Note the conflict, proceed with fix (specialist had authority) |
+| **Fix touches files outside build_report scope** | Any tier | Escalate to user (scope creep) |
 
 ### Decision Boundary Checking
 
@@ -298,22 +441,24 @@ Write `{context_path}/test_report.md`:
 **Status:** Pass | Partial | Failed
 
 ## Test Summary
-- **Tests created:** [N]
+- **Tests created:** [N] (Tier 1: [N], Tier 2: [N], Tier 3: [N])
 - **Passing:** [N]
 - **Failing:** [N]
+- **AC coverage:** [M]/[P] acceptance criteria have Tier 1 tests
 - **Coverage:** [X]% (target: [Y]%)
 
 ## Test Files Created
-| File | Tests | Covers |
-|------|-------|--------|
-| [path] | [count] | [source file — what it tests] |
+| File | Tier | Tests | Covers |
+|------|------|-------|--------|
+| [path] | [1/2/3] | [count] | [what it tests — AC reference or blueprint section] |
 
 ## Failures & Resolutions
 
 ### [Test name]
-- **Type:** [test bug / implementation bug — trivial/moderate/complex]
-- **Root cause:** [description]
-- **Resolution:** [fix applied] OR **Escalated:** [reason not fixable autonomously]
+- **Type:** [test bug / spec violation / spec ambiguity / implementation bug — trivial/moderate/complex]
+- **Spec source:** [which acceptance criterion, blueprint spec, or process_flow section defined the expected behavior]
+- **Root cause:** [description — what the spec says vs. what the implementation does]
+- **Resolution:** [fix applied] OR **Escalated:** [reason — spec violation pending user decision / ambiguity / architectural / scope creep / max retries]
 
 ## Implementation Fixes Applied
 | File | Change | Rationale |
@@ -325,6 +470,12 @@ Write `{context_path}/test_report.md`:
 |-------|--------|
 | [description] | [why not fixable: USER decision conflict / architectural / scope creep / max retries] |
 
+## Assertion Provenance
+- Value-assertions audited: **[N]**
+- Spec-traced: **[N]** (value found in outline, blueprint, process_flow, or test_advisory)
+- SPEC_AMBIGUOUS marked: **[N]** (spec underspecified, asserting implementation value)
+- Source-derived (untraced): **[N]** [if any — list examples and user disposition: "accepted as-is" / "fixed"]
+
 ## Decision Compliance
 - Checked **[N]** decisions across **[M]** specialist decision logs
 - `[USER]` violations: [count — list any, or "None"]