@tgoodington/intuition 10.3.0 → 10.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "10.3.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-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 — 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 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.
+
+**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,51 +165,38 @@ 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:
+For each modified file, determine which test tier drives its testing:
 
-| 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 |
+| 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 |
 
-### Edge Case Enumeration
+### Edge Cases, Mocking, and Coverage
 
-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
+**Edge cases** to enumerate per interface: boundary values, null/undefined inputs, error paths (invalid input, failed external calls, timeouts), permission edges, state transitions.
 
-### Mock Strategy
+**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.
 
-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
-
-### Coverage Target
-
-- 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)
+**Coverage target**: Match existing config threshold, or 80% line coverage for modified files. Focus on decision-heavy code paths (`[USER]` and `[SPEC]` decisions).
 
 ### Spec Oracle Hierarchy
 
-Tests derive their expected behavior from spec artifacts, NOT from reading source code. The oracle has three tiers, used in combination:
+Tests derive expected behavior from spec artifacts, NOT from reading source code. Each oracle maps to a test tier:
 
-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).
+| 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.
 
@@ -169,11 +204,15 @@ When a test fails, the failure means the implementation disagrees with the spec
 
 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.
+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
 
@@ -188,11 +227,12 @@ 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, **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.
+- 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)
 
@@ -204,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?"
@@ -226,33 +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. 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 (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)
 
-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.
+```
+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]
 
-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).
+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 6 until every planned test file is confirmed on disk.
+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
 
@@ -317,15 +441,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 +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"]