@tgoodington/intuition 10.3.0 → 10.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "10.3.0",
+  "version": "10.5.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-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,26 +67,13 @@ 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.
-
-From build_report.md, extract:
-- **Files modified** — the scope boundary for testing and fixes
-- **Task results** — which tasks passed/failed build review
-- **Deviations** — any blueprint deviations that may need test coverage
-- **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:
-- 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
-- Map each `[SPEC]` decision to its chosen option and rationale
-- This index is used in Step 6 for fix boundary checking
+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 these files, extract: **build_report** → files modified (scope boundary), task results, deviations, decision compliance, deferred test deliverables. **Blueprints** → Section 5 behavioral contracts (signatures, return schemas, error conditions, naming), Section 6 AC mapping, Section 9 file paths. **test_advisory** → edge cases, critical paths, failure modes. **Decisions** → index of all [USER] and [SPEC] decisions with chosen options (used in Step 6 boundary checking).
 
 ## STEP 2: RESEARCH (2 Parallel Research Agents)
 
@@ -94,19 +82,50 @@ 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 — Interface Extraction:**
-"Read each of these files modified during build: [list files from build_report]. For each file, extract ONLY structural information — do NOT describe implementation logic or return value computations. Report: exported functions/classes/methods with their signatures (name, parameters, types), constructor arguments, import paths, class hierarchies, existing test coverage (search for test files matching the source file name pattern), external dependencies that would need mocking. Output a clean interface stub per file that a test writer could use to call the code without knowing what it does internally."
+**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 per blueprint as: `## {specialist} — {file}` then per module: Import, Interface, Return schema, Error conditions, Naming conventions, Mocking targets, Existing tests. Mark any unspecified field as 'Not specified in blueprint'.
+
+CRITICAL: Extract ONLY what the blueprint SPECIFIES — not what the source code does."
+
+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.
+
+**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
 
-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 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)
 
@@ -117,63 +136,44 @@ Use process_flow.md to identify cross-component integration boundaries and E2E p
 
 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 Type Heuristic
+### File-to-Tier Mapping
 
-For each modified file, classify the appropriate test type:
+| File Type | Primary Tier |
+|-----------|-------------|
+| Route / controller | Tier 1 (AC tests via HTTP) |
+| Engine / orchestrator | Tier 1 (AC tests of engine API) |
+| Service / provider | Tier 2 (blueprint contract) |
+| Model / schema | Tier 2 (blueprint contract) |
+| Utility / helper | Tier 3, or Tier 2 if blueprint specifies |
+| Configuration / Template | Skip (test indirectly via Tier 1) |
 
-| 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 |
+### Tier Distribution Minimums
 
-### Edge Case Enumeration
+The test plan MUST satisfy these ratios (calculated against total test count):
+- **Tier 1 ≥ 40%** — If the plan has fewer than 40% Tier 1 tests, add more AC-level tests before adding Tier 2/3. If there are not enough ACs to reach 40%, document why in the test strategy.
+- **Tier 3 ≤ 30%** — Coverage gap-fillers must not dominate the suite. If Tier 3 exceeds 30%, cut the lowest-value coverage tests.
 
-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
+### Negative Test Minimums
 
-### Mock Strategy
+At least **30% of Tier 1 and Tier 2 tests** must exercise error/failure/invalid-input paths: invalid inputs, dependency failures (timeout, connection refused), state violations (e.g., stopping a non-running container), missing config. If the spec doesn't describe error behavior, flag as spec gap with `# SPEC_AMBIGUOUS` — do NOT skip negative testing.
 
-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
+### Edge Cases, Mocking, and Coverage
 
-### Coverage Target
+**Edge cases** to enumerate per interface: boundary values, null/undefined inputs, error paths (invalid input, failed external calls, timeouts), permission edges, state transitions.
 
-- 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)
+**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.
 
-### Spec Oracle Hierarchy
+**Mock depth rule for infrastructure/DevOps projects**: When the project orchestrates external systems (Docker, cloud APIs, CLI tools, databases), pure-mock tests risk testing only mock setup. For each external-system wrapper, at least one Tier 1 test MUST assert **mock interaction depth** — not just return values, but that the mock was called with correct arguments, order, and count per the blueprint spec.
 
-Tests derive their expected behavior from spec artifacts, NOT from reading source code. The oracle has three tiers, used in combination:
+**Coverage target**: Match existing config threshold, or 80% line coverage for modified files. Focus on decision-heavy code paths (`[USER]` and `[SPEC]` decisions).
 
-1. **Acceptance criteria** (outline.md) — Primary oracle for behavioral correctness. Each criterion describes an observable outcome the implementation must produce. Tests assert these outcomes directly.
-2. **Blueprint deliverable specs** (blueprints or test_advisory.md) — Secondary oracle for domain-specific assertions, edge cases, and expected input/output examples. Use Section 6 (Acceptance Mapping) and Section 9 (Producer Handoff) for concrete expected behaviors.
-3. **Process flow** (process_flow.md) — Tertiary oracle for integration contracts and cross-component handoffs. Subject to accepted deviations (see Process Flow Coverage above).
+### Spec Oracle Hierarchy
 
-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.
+Tests derive expected behavior from specs, NOT source code. Oracle priority: **outline.md ACs** (Tier 1) → **blueprints Sections 5+6** (Tier 2) → **process_flow.md** (Tier 1+2 integration) → **test_advisory.md** (advisory, Tier 2+3). When a test fails, the implementation disagrees with the spec — classify per Step 6, don't assume either is wrong.
 
 ### 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 **expected output as described by the spec** (acceptance criterion + blueprint deliverable spec) — not on whatever the implementation happens to return.
-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.
+For every AC with observable behavior, at least one Tier 1 test MUST exercise the **actual entry point at the AC's abstraction level** (HTTP route → test the route, engine API → test the engine, CLI → test the command). NEVER satisfy an AC exclusively with a unit test of an internal helper. Assertions MUST match spec-defined expected output. Conditional behavior ("when X, do Y") requires both branches tested. Tier 2 supplements but does NOT substitute for Tier 1.
 
 ### Specialist Test Recommendations
 
@@ -181,18 +181,22 @@ Before finalizing the test plan, review specialist domain knowledge from bluepri
 - **Testability Notes**: Edge cases, critical paths, failure modes, and boundary conditions from each blueprint's Approach section (Section 3, `### Testability Notes` subheading)
 - **Deferred test deliverables**: Any test specs from build_report.md's "Test Deliverables Deferred" section (legacy — older blueprints may still include test files in Producer Handoff)
 
-Specialists have domain expertise about what should be tested. Incorporate their testability insights into your test plan, but you own the test strategy — use specialist input as advisory, not prescriptive.
+Incorporate specialist insights as advisory, not prescriptive — you own the test strategy.
 
 ### Output
 
 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, **which spec artifact defines the expected behavior**)
-- 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.
+- **Tier distribution**: Total count per tier with percentages. Verify: Tier 1 ≥ 40%, Tier 3 ≤ 30%. If not met, adjust plan before proceeding.
+- **Negative test inventory**: List each negative/error-path test explicitly. Verify: ≥ 30% of Tier 1/2 tests are negative. If not met, add more error-path tests.
+- Test files to create (path, tier, target source file)
+- Test cases per file (name, tier, positive/negative, 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). For infra projects: flag files needing mock-depth assertions (call args, call order, call count).
 - Framework command to run tests
-- Estimated test count and distribution
+- Estimated test count and distribution by tier
+- **Mutation spot-check candidates**: 3 source files with highest Tier 1/2 coverage, and one candidate mutation per file
 - 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)
 
@@ -204,10 +208,15 @@ 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 ([X]% of total, min 40%) covering [M] of [P] acceptance criteria
+  - Tier 2 (blueprint contracts): [N] tests
+  - Tier 3 (coverage): [N] tests ([X]% of total, max 30%)
+**Negative tests:** [N] of [M] Tier 1/2 tests ([X]%, min 30%)
+**AC coverage:** [M]/[P] acceptance criteria have Tier 1 tests [list any uncovered ACs]
 **Coverage target:** [threshold]%
+**Post-pass:** Mutation spot-check on 3 files
 
 Proceed?"
 
@@ -226,33 +235,131 @@ 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. Your job is to write tests that verify the code does what the SPEC says — not to verify the code does what the code does.
+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]
 
-**Interface stub (from Step 2 research):**
-[Paste the interface stub for this source file — signatures, exports, types, import paths. This is how you call the code.]
+**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] — use Deliverable Specification and Acceptance Mapping sections to determine expected inputs, outputs, and behaviors
-- Flow context (integration/E2E tests only): Read `{context_path}/process_flow.md` (if exists) for cross-component contracts
+- 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 with: name, type, what it validates per the spec, expected behavior from spec, 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: add `# blueprint:{specialist}:L{line} — "{spec quote}"`. If no spec defines the value: `# SPEC_AMBIGUOUS: spec says "{quote}" — value not specified`.
+
+Tier 1: test at AC's abstraction level, mock ONLY external systems, assert user-observable outcomes.
+Tier 2: test at blueprint's module level, mock external deps per blueprint, assert behavioral contracts.
+
+## ASSERTION DEPTH RULES
+Prefer DEEP assertions over shallow ones. Instead of `assert result is not None` or `assert "key" in result`, assert specific values: `assert result["network_name"] == "myapp-network"`. For infra/DevOps code: assert mock call arguments, order, and count — not just return values.
+
+Write the complete test file. Follow existing test style. Do NOT add test infrastructure.
+```
+
+### Tier 3 Test Writer Prompt (coverage gap-filling only)
+
+```
+You are a coverage test writer. Your job is to increase test coverage for code paths not covered by Tier 1/2 spec tests.
+
+**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
 
-CRITICAL: Derive ALL assertions from the spec artifacts above. Do NOT read [source file path] to determine expected return values or behavior. You have the interface stub for structural info (how to call the code). The spec tells you what it should return. If the spec is ambiguous about a specific expected value, write the test with a clear comment marking the assertion as "SPEC_AMBIGUOUS" so the orchestrator can flag it.
+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: Assertion Depth Scoring
+
+For each Tier 1 and Tier 2 test file, classify every assertion as **shallow** or **deep**:
+
+| Shallow (low signal) | Deep (high signal) |
+|---|---|
+| `is not None` | `== "expected-specific-value"` |
+| `isinstance(result, dict)` | `result["network_name"] == "myapp-network"` |
+| `"key" in result` | `mock_docker.run.assert_called_with(image="x", ports={...})` |
+| `len(result) > 0` | `error.message == "Container myapp not found"` |
+| `result["success"] == True` (when mock returns True) | `result["status"] == "running"` (verified against spec behavior) |
+
+**Threshold**: If >50% of assertions in a test file are shallow, flag the file. The test exists but proves almost nothing.
+
+**Escalation**: If >30% of ALL Tier 1/2 test files are flagged as shallow-dominant, present via AskUserQuestion:
+
+```
+Header: "Assertion Depth Warning"
+Question: "[N] of [M] test files have >50% shallow assertions.
+These tests pass trivially and won't catch real bugs.
+
+Examples: [list 2-3 worst offenders with their shallow assertion patterns]
+
+Options: fix shallow tests / accept as-is / skip to Step 6"
+```
+
+If "fix": delegate to `intuition-code-writer` agents with instructions to replace shallow assertions with specific value checks traced to blueprint specs. If the blueprint doesn't specify the value, add `SPEC_AMBIGUOUS` marker.
+
+### Part C: 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**
+
+### Reporting
+
+If Part A finds >20% source-derived assertions, Part B flags >30% shallow-dominant files, OR Part C finds any abstraction gaps, present via AskUserQuestion:
 
-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).
 ```
+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.
 
-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.
+**If "accept as-is":** Note findings in test report. Proceed to Step 6.
 
 ## STEP 6: RUN TESTS + FIX CYCLE
 
@@ -270,29 +377,24 @@ Also run `mcp__ide__getDiagnostics` to catch type errors and lint issues in the
 
 For each failure, classify. The first question is always: **does the spec clearly define the expected behavior the test asserts?**
 
-| 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) |
+| Classification | Action |
+|---|---|
+| **Test bug** (wrong assertion, mock, import) | Fix autonomously — `intuition-code-writer` |
+| **Spec Violation** (code disagrees with clear spec) | Escalate: "expects [spec] per [source], got [actual]. Fix code / update spec / investigate?" |
+| **Spec Ambiguity** (SPEC_AMBIGUOUS or underspecified) | Escalate: "Spec unclear for [scenario]. Code does [X]. Correct? Lock in / change / skip?" |
+| **Impl bug, trivial** (1-3 lines, spec is clear) | Fix directly — `intuition-code-writer` |
+| **Impl bug, moderate** (one file, spec is clear) | Fix — `intuition-code-writer` with diagnosis |
+| **Impl bug, complex** (multi-file structural) | Escalate to user |
+| **Violates [USER] decision** | STOP — escalate immediately |
+| **Violates [SPEC] decision** | Note conflict, proceed with fix |
+| **Touches files outside build scope** | Escalate (scope creep) |
 
 ### Decision Boundary Checking
 
-Before ANY implementation fix (not test-only fixes):
-
-1. Read ALL `{context_path}/scratch/*-decisions.json` files + `docs/project_notes/decisions.md`
-2. Check: does the proposed fix contradict any `[USER]`-tier decision?
-   - If YES → STOP. Report the conflict to the user via AskUserQuestion: "Test failure in [file] requires changing [what], but this contradicts your decision on [D{N}: title] where you chose [chosen option]. How should I proceed?" Options: "Change my decision" / "Skip this test" / "I'll fix manually"
-3. Check: does the proposed fix contradict any `[SPEC]`-tier decision?
-   - If YES → note the conflict in the test report, proceed with the fix (specialist decisions are advisory)
-4. Check: does the fix modify files NOT listed in build_report's "Files Modified" section?
-   - If YES → escalate: "Fixing [test] requires modifying [file] which wasn't part of this build. Allow scope expansion?" Options: "Allow this file" / "Skip this test"
+Before ANY implementation fix (not test-only fixes), read all `{context_path}/scratch/*-decisions.json` + `docs/project_notes/decisions.md`. Check:
+1. **[USER] decision conflict** → STOP, escalate via AskUserQuestion with options: "Change decision" / "Skip test" / "Fix manually"
+2. **[SPEC] decision conflict** → note in report, proceed with fix
+3. **File outside build scope** → escalate: "Allow scope expansion?" / "Skip test"
 
 ### Fix Cycle
 
@@ -305,6 +407,29 @@ For each failure:
 
 After all failures are addressed (fixed or escalated), run the full test suite one final time to verify no regressions.
 
+### Mutation Spot-Check (Post-Pass Gate)
+
+After the final test run passes, perform a lightweight mutation check to verify the tests can actually detect bugs. This is NOT full mutation testing — it's a targeted sanity check.
+
+1. Select **3 source files** with the most Tier 1/2 test coverage (highest test count targeting them).
+2. For each file, make ONE small, obvious mutation via an `intuition-code-writer` agent:
+   - Change a return value (e.g., `"running"` → `"stopped"`, `True` → `False`)
+   - Change a string literal (e.g., resource name, error message)
+   - Remove a function call (e.g., comment out a validation step)
+   - The mutation MUST break behavior that at least one test claims to verify
+3. Re-run ONLY the tests targeting that file.
+4. **Expected result:** At least one test fails per mutation. If a mutation causes zero test failures, the tests covering that file are hollow.
+5. **Revert every mutation immediately** after checking (use `git checkout -- {file}` or re-apply the original content).
+
+**If any mutation survives** (0 test failures):
+- Report via AskUserQuestion: "Mutation spot-check: changed [what] in [file] — zero tests caught it. The [N] tests covering this file may be testing mock wiring rather than real behavior. Options: strengthen tests / accept risk / skip"
+- If "strengthen tests": delegate to `intuition-code-writer` with the specific mutation that survived, and instructions to add a test that would catch it.
+
+**Track results** in the test report under a new "## Mutation Spot-Check" section:
+| File | Mutation | Tests Run | Caught? |
+|------|----------|-----------|---------|
+| [path] | [what was changed] | [N] | Yes/No |
+
 ## STEP 7: TEST REPORT
 
 Write `{context_path}/test_report.md`:
@@ -317,15 +442,16 @@ 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
 
@@ -345,6 +471,30 @@ 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"]
+
+## Assertion Depth
+- Tier 1/2 files audited: **[N]**
+- Shallow-dominant files (>50% shallow assertions): **[N]** [list any]
+- User disposition: [fixed / accepted as-is / N/A]
+
+## Negative Test Coverage
+- Tier 1/2 negative tests: **[N]** of **[M]** total Tier 1/2 tests (**[X]%**, target: ≥30%)
+- Error paths tested: [list categories — invalid input, dependency failure, state violation, etc.]
+
+## Mutation Spot-Check
+| File | Mutation | Tests Run | Caught? |
+|------|----------|-----------|---------|
+| [path] | [what was changed] | [N] | Yes/No |
+
+- Mutations tested: **[N]**
+- Caught: **[N]**
+- Survived: **[N]** [list any — with disposition: strengthened / accepted risk]
+
 ## Decision Compliance
 - Checked **[N]** decisions across **[M]** specialist decision logs
 - `[USER]` violations: [count — list any, or "None"]