dev-playbooks 1.2.8 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks",
-  "version": "1.2.8",
+  "version": "1.4.0",
   "description": "AI-powered spec-driven development workflow",
   "keywords": [
     "devbooks",

package/skills/_shared/references/spec-structure-template.md

@@ -0,0 +1,161 @@
+# Spec Structure Template
+
+> This template defines the standard structure for Spec truth files, ensuring Specs are verifiable, traceable, and can drive test generation.
+
+## File Location
+
+```
+<truth-root>/specs/<capability>/spec.md
+```
+
+## Standard Structure
+
+```markdown
+---
+# Metadata (required)
+capability: <capability-name>
+owner: @<owner>
+last_verified: YYYY-MM-DD
+last_referenced_by: <last-referencing-change-id>
+health: active | stale | deprecated
+freshness_check: monthly | quarterly | on-change
+---
+
+# <Capability Name> Specification
+
+## Glossary
+
+> Capability-specific terms, consistent with `<truth-root>/_meta/glossary.md`.
+
+| Term | Definition | Constraints |
+|------|------------|-------------|
+| Order | Order entity | Must have at least one OrderItem |
+| OrderItem | Order line item | qty > 0, price >= 0 |
+
+## Invariants
+
+> Constraints that must always hold; violations are system bugs.
+
+| ID | Description | Verification |
+|----|-------------|--------------|
+| INV-001 | Order total = SUM(item.price * item.qty) | A (automated test) |
+| INV-002 | Inventory quantity >= 0 | A (automated test) |
+| INV-003 | Shipped orders cannot be cancelled | A (state machine test) |
+
+## Contracts
+
+### Preconditions
+
+| ID | Operation | Condition | Violation Behavior |
+|----|-----------|-----------|-------------------|
+| PRE-001 | Create order | user.isAuthenticated | Return 401 |
+| PRE-002 | Pay order | order.status == 'pending' | Return 400 |
+
+### Postconditions
+
+| ID | Operation | Guarantee |
+|----|-----------|-----------|
+| POST-001 | Create order success | Generate unique order.id |
+| POST-002 | Payment success | inventory.decreased(qty) |
+
+## State Machine
+
+> If this capability involves state transitions, a state machine must be defined.
+
+### State Set
+
+```
+States: {Created, Paid, Shipped, Done, Cancelled}
+```
+
+### Transition Rules
+
+| Current State | Action | Target State | Condition |
+|---------------|--------|--------------|-----------|
+| Created | pay | Paid | payment.success |
+| Created | cancel | Cancelled | - |
+| Paid | ship | Shipped | inventory.reserved |
+| Paid | refund | Cancelled | - |
+| Shipped | deliver | Done | - |
+
+### Forbidden Transitions
+
+| Current State | Action | Reason |
+|---------------|--------|--------|
+| Shipped | cancel | Violates INV-003 |
+| Done | * | Terminal state, cannot exit |
+| Cancelled | * | Terminal state, cannot exit |
+
+## Requirements
+
+### REQ-001: <Requirement Title>
+
+**Description**: <one-sentence description>
+
+**SHALL/SHOULD/MAY**:
+- The system **SHALL** ...
+- The system **SHOULD** ...
+
+**Trace**: AC-001 (from design.md)
+
+#### Scenario: <scenario-name>
+
+- **GIVEN** user is logged in and cart is non-empty
+- **WHEN** user clicks "Submit Order"
+- **THEN** system creates order and returns order ID
+
+**Data Instances** (boundary conditions):
+
+| Input | Expected Output | Notes |
+|-------|-----------------|-------|
+| qty=1, price=100 | total=100 | Normal value |
+| qty=0 | Reject | Boundary - zero |
+| qty=-1 | Reject | Boundary - negative |
+
+---
+
+## Change History
+
+| Date | Change Package | Changes |
+|------|----------------|---------|
+| 2024-01-16 | 20240116-1030-add-cancel | Add cancel order scenario |
+```
+
+## Usage Guide
+
+### 1. Who Writes Specs?
+
+- **spec-contract skill**: Creates/updates spec deltas
+- **archiver skill**: Merges spec deltas into truth-root
+
+### 2. Who Reads Specs?
+
+| Skill | Reading Purpose |
+|-------|-----------------|
+| design-doc | Check if design conflicts with existing Specs, reference REQ-xxx |
+| test-owner | Generate tests from contracts/state machines |
+| impact-analysis | Identify affected Specs |
+| code-review | Check terminology consistency |
+| archiver | Update metadata, build reference chain |
+
+### 3. Test Generation Mapping
+
+| Spec Element | Generated Test Type |
+|--------------|---------------------|
+| INV-xxx | Invariant tests |
+| PRE-xxx | Precondition tests (satisfied + violated) |
+| POST-xxx | Postcondition tests |
+| State Transition | State transition tests |
+| Forbidden Transition | Forbidden transition tests |
+| Data Instance Table | Parameterized test cases |
+
+### 4. Health Detection
+
+The `health` field in Spec files is automatically detected by entropy-monitor:
+
+| Condition | health Status |
+|-----------|---------------|
+| last_verified < 90 days | `active` |
+| last_verified > 90 days | `stale` (needs review) |
+| Explicitly marked deprecated | `deprecated` |
+| last_referenced_by empty for >6 months | Recommend deletion |

package/skills/devbooks-archiver/SKILL.md

@@ -120,6 +120,32 @@ Merge change package spec artifacts into `<truth-root>`:
 | `<change-root>/<change-id>/specs/**` | `<truth-root>/specs/**` | Incremental merge |
 | `<change-root>/<change-id>/contracts/**` | `<truth-root>/contracts/**` | Versioned merge |
 
+**Spec Metadata Update** (must execute during merge):
+
+When merging specs into truth-root, the following metadata must be updated:
+
+```yaml
+# Update in each merged/referenced spec file header
+---
+last_referenced_by: <change-id>           # Last change package referencing this spec
+last_verified: <archive-date>             # Last verification date
+health: active                            # Health status: active | stale | deprecated
+---
+```
+
+**Metadata Update Rules**:
+
+| Scenario | Update Behavior |
+|----------|-----------------|
+| New Spec | Create complete metadata header |
+| Modify existing Spec | Update `last_referenced_by` and `last_verified` |
+| Spec referenced by design doc but not modified | Update only `last_referenced_by` |
+| Marked as deprecated | Set `health: deprecated` |
+
+**Building Reference Traceability Chain**:
+
+During archiving, archiver automatically scans the "Affected Specs" declared in design.md and updates the `last_referenced_by` field for these Specs, even if they weren't directly modified. This establishes a reverse traceability chain from Specs to change packages.
+
 ### Step 4: Architecture Merge
 
 > **Design Decision**: C4 architecture changes are recorded in design.md's Architecture Impact section and merged into truth by Archiver during archiving.

package/skills/devbooks-code-review/references/code-review-prompt.md

@@ -13,6 +13,10 @@ Inputs (provided by me):
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 - High-ROI pitfalls list (if present): `<truth-root>/engineering/pitfalls.md`
 
+**Required Spec Truth Reading** (mandatory before review):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: verify code naming/structure aligns with terminology and contracts defined in Specs
+
 Hard constraints (must follow):
 1) Output only review findings and concrete change suggestions; do not directly modify `tests/` or design documents.
 2) Do not debate business correctness (tests/specs decide that); focus only on maintainability and engineering quality.
@@ -64,6 +68,12 @@ Review focus (must cover):
 - Is the same concept named inconsistently across modules (e.g., User/Account/Member mixed)?
 - Is Entity vs Value Object modeled correctly? (Entity has an ID; VO has no ID and is immutable.)
 
+**Spec Truth Terminology Alignment** (must check):
+- Do code names match terminology defined in `<truth-root>/specs/`?
+- Do state names/enum values match state machine definitions in Specs?
+- Do method names reflect actions/transitions in Specs? (e.g., `cancel()` corresponds to `order --[cancel]--> cancelled`)
+- If naming inconsistencies are found, mark as "terminology drift risk" and recommend unification
+
 ---
 
 ## Invariant Protection (must check)

package/skills/devbooks-coder/SKILL.md

@@ -14,16 +14,27 @@ allowed-tools:
 
 ## Workflow Position Awareness
 
-> **Core Principle**: Coder executes after Test Owner Phase 1 and hands off to Test Owner Phase 2 for verification upon completion.
+> **Core Principle**: Coder executes after Test Owner Phase 1, achieving mental clarity through **mode labels** (not session isolation).
 
 ### My Position in the Overall Workflow
 
 ```
-proposal → design → test-owner(phase1) → [Coder] → test-owner(phase2) → code-review → archive
-                                            ↓
-                                    Implement code, make tests green
+proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
+                                      ↓              ↓
+                               Implement+fast track    Evidence audit
+                              (@smoke/@critical)      (no @full rerun)
 ```
 
+### AI Era Solo Development Optimization
+
+> **Important Change**: This protocol is optimized for AI programming + solo development scenarios, **removing the mandatory "separate session" requirement**.
+
+| Old Design | New Design | Reason |
+|------------|------------|--------|
+| Test Owner and Coder must use separate sessions | Same session, switch with `[TEST-OWNER]` / `[CODER]` mode labels | Reduce context rebuilding cost |
+| Coder runs full tests and waits | Coder runs fast track (`@smoke`/`@critical`), `@full` triggered async | Fast iteration |
+| Completion goes directly to Test Owner | Completion status is `Implementation Done`, wait for @full | Async doesn't block, archive is sync |
+
 ### Coder's Responsibility Boundaries
 
 | Allowed | Prohibited |
@@ -31,18 +42,60 @@ proposal → design → test-owner(phase1) → [Coder] → test-owner(phase2)
 | Modify `src/**` code | ❌ Modify `tests/**` |
 | Check off `tasks.md` items | ❌ Modify `verification.md` |
 | Record deviations to `deviation-log.md` | ❌ Check off AC coverage matrix |
-| Run tests to verify | ❌ Set verification.md Status |
+| Run fast track tests (`@smoke`/`@critical`) | ❌ Set verification.md Status to Verified/Done |
+| Trigger `@full` tests (CI/background) | ❌ Wait for @full completion (can start next change) |
 
 ### Flow After Coder Completes
 
-1. **Tasks complete**: tasks.md all `[x]`
-2. **Tests green**: Run `npm test` to confirm passing
-3. **Hand off to Test Owner**: Notify Test Owner to enter Phase 2 verification
-4. **Wait for verification result**:
-   - Test Owner confirms green → Proceed to Code Review
-   - Test Owner finds issues → Coder fixes
+1. **Fast track tests green**: `@smoke` + `@critical` pass
+2. **Trigger @full**: Commit code, CI starts running @full tests async
+3. **Status change**: Set change status to `Implementation Done`
+4. **Can start next change** (not blocked)
+5. **Wait for @full results**:
+   - @full passes → Test Owner enters Phase 2 to audit evidence
+   - @full fails → Coder fixes
+
+**Key Reminders**:
+- After Coder completes, status is `Implementation Done`, **not directly to Code Review**
+- Dev iteration is async (can start next change), but archive is sync (must wait for @full to pass)
+
+---
+
+## Test Layering and Run Strategy (Critical!)
+
+> **Core Principle**: Coder only runs fast track tests, @full tests are triggered async, not blocking dev iteration.
+
+### Test Layering Labels
+
+| Label | Purpose | When Coder Runs | Expected Time |
+|-------|---------|-----------------|---------------|
+| `@smoke` | Fast feedback, core paths | After each code change | Seconds |
+| `@critical` | Key functionality verification | Before commit | Minutes |
+| `@full` | Complete acceptance tests | **Don't run**, trigger CI async | Can be slow |
 
-**Key Reminder**: After Coder completes, **do not go directly to Code Review**, first let Test Owner verify and check off.
+### Coder's Test Run Strategy
+
+```bash
+# During development: frequently run @smoke
+npm test -- --grep "@smoke"
+
+# Before commit: run @critical
+npm test -- --grep "@smoke|@critical"
+
+# After commit: CI automatically runs @full (Coder doesn't wait)
+git push  # triggers CI
+# → Coder can start next task
+```
+
+### Async vs Sync Boundary
+
+| Action | Blocking/Async | Description |
+|--------|----------------|-------------|
+| `@smoke` tests | Sync | Run immediately after each change |
+| `@critical` tests | Sync | Must pass before commit |
+| `@full` tests | **Async** | CI runs in background, doesn't block Coder |
+| Start next change | **Not blocked** | Coder can start immediately |
+| Archive | **Blocked** | Must wait for @full to pass |
 
 ---
 
@@ -319,26 +372,29 @@ During implementation, you **must immediately** write to `deviation-log.md` in t
 
 | Code | Status | Determination Criteria | Next Step |
 |:----:|--------|------------------------|-----------|
-| ✅ | COMPLETED | All tasks done, no deviations | `devbooks-code-review` |
-| ⚠️ | COMPLETED_WITH_DEVIATION | Tasks done, deviation-log has pending records | `devbooks-design-backport` |
-| 🔄 | HANDOFF | Found test issues needing modification | `devbooks-test-owner` |
+| ✅ | IMPLEMENTATION_DONE | Fast track tests green, @full triggered, no deviations | Switch to `[TEST-OWNER]` wait for @full |
+| ⚠️ | IMPLEMENTATION_DONE_WITH_DEVIATION | Fast track green, deviation-log has pending records | `devbooks-design-backport` |
+| 🔄 | HANDOFF | Found test issues needing modification | Switch to `[TEST-OWNER]` mode to fix tests |
 | ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
-| 💥 | FAILED | Gates not passed | Fix and retry |
+| 💥 | FAILED | Fast track tests not passing | Fix and retry |
 
 ### Status Determination Flow
 
 ```
 1. Check if deviation-log.md has "| ❌" records
-   → Yes: COMPLETED_WITH_DEVIATION
+   → Yes: IMPLEMENTATION_DONE_WITH_DEVIATION
 
 2. Check if tests/ modification needed
-   → Yes: HANDOFF to test-owner
+   → Yes: HANDOFF to [TEST-OWNER] mode
+
+3. Check if fast track tests (@smoke + @critical) all pass
+   → No: FAILED
 
-3. Check if tasks.md is fully completed
-   → No: BLOCKED or FAILED
+4. Check if tasks.md is fully completed
+   → No: BLOCKED or continue implementation
 
-4. All checks passed
-   → COMPLETED
+5. All checks passed, trigger @full
+   → IMPLEMENTATION_DONE
 ```
 
 ### Routing Output Template (Required)
@@ -348,37 +404,41 @@ After completing coder, you **must** output in this format:
 ```markdown
 ## Completion Status
 
-**Status**: ✅ COMPLETED / ⚠️ COMPLETED_WITH_DEVIATION / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
+**Status**: ✅ IMPLEMENTATION_DONE / ⚠️ ... / 🔄 HANDOFF / ❌ BLOCKED / 💥 FAILED
 
 **Task Progress**: X/Y completed
 
+**Fast Track Tests**: @smoke ✅ / @critical ✅
+
+**@full Tests**: Triggered (CI running async)
+
 **Deviation Records**: Has N pending / None
 
 ## Next Step
 
-**Recommended**: `devbooks-xxx skill`
+**Recommended**: Switch to `[TEST-OWNER]` mode wait for @full / `devbooks-xxx skill`
 
 **Reason**: [specific reason]
 
-### How to invoke
-Run devbooks-xxx skill for change <change-id>
+**Note**: Can start next change, no need to wait for @full completion
 ```
 
 ### Specific Routing Rules
 
 | My Status | Next Step | Reason |
 |-----------|-----------|--------|
-| COMPLETED | `devbooks-test-owner` (Phase 2 verification) | Tasks complete, need Test Owner to verify and check off |
-| COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then let Test Owner verify |
-| HANDOFF (test issue) | `devbooks-test-owner` | Coder cannot modify tests |
+| IMPLEMENTATION_DONE | Switch to `[TEST-OWNER]` mode (wait for @full) | Fast track green, wait for @full to pass then audit evidence |
+| IMPLEMENTATION_DONE_WITH_DEVIATION | `devbooks-design-backport` | Backport design first |
+| HANDOFF (test issue) | Switch to `[TEST-OWNER]` mode | Coder cannot modify tests |
 | BLOCKED | Wait for user | Record breakpoint area |
 | FAILED | Fix and retry | Analyze failure reason |
 
 **Critical Constraints**:
 - Coder **can never modify** `tests/**`
-- If test issues found, must HANDOFF to Test Owner (separate session)
+- If test issues found, must switch to `[TEST-OWNER]` mode to handle
 - If deviations exist, must design-backport first before continuing
-- **Coder must go through Test Owner Phase 2 verification before Code Review**
+- **Coder completion status is `Implementation Done`, must wait for @full to pass before entering Test Owner Phase 2**
+- **Mode switching replaces session isolation**: Use `[TEST-OWNER]` / `[CODER]` labels to switch modes
 
 ---
 

package/skills/devbooks-design-doc/references/design-doc-prompt.md

@@ -18,6 +18,10 @@ Inputs (provided by me):
 - Chat history
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 
+**Required Spec Truth Reading** (mandatory before designing):
+- `<truth-root>/specs/**`: existing spec files (REQ/Invariants/Contracts)
+- Purpose: ensure design does not conflict with existing specs and explicitly references affected specs
+
 Tasks:
 1) Output a design doc (not an implementation plan, not code).
 2) The doc must be concrete enough to drive acceptance and task decomposition: clear boundaries, contracts, red lines, and acceptance.
@@ -182,7 +186,13 @@ Limits:
 
 Additional requirements (for traceability in large projects):
 - Explicitly list affected capabilities/modules/external contracts (names and boundaries only; no implementation)
-- If external interfaces/APIs/events/data structures are involved: specify versioning strategy in the “Core data and event contracts” section (`schema_version`, compatibility window, migration/replay principles)
-- If architecture boundaries change: add an optional **C4 Delta** subsection under “Target architecture” describing what C1/C2/C3 elements were added/modified/removed (full maps are maintained by the C4 map maintainer)
+- If external interfaces/APIs/events/data structures are involved: specify versioning strategy in the "Core data and event contracts" section (`schema_version`, compatibility window, migration/replay principles)
+- If architecture boundaries change: add an optional **C4 Delta** subsection under "Target architecture" describing what C1/C2/C3 elements were added/modified/removed (full maps are maintained by the C4 map maintainer)
+
+**Spec Truth Reference Requirements** (core traceability):
+- **Must declare affected existing Specs**: list spec files under `<truth-root>/specs/` impacted by this design
+- **Must reference REQ/Invariant**: each constraint in the design must trace back to REQ-xxx or INV-xxx in Specs
+- **Gap declaration**: if design cannot satisfy an existing REQ, explicitly declare it as a Gap with justification
+- **Terminology consistency**: domain terms must match `<truth-root>/_meta/glossary.md`; new terms must be declared and proposed for glossary addition
 
 Now output the Design Doc in Markdown. Do not output extra explanations.

package/skills/devbooks-impact-analysis/references/impact-analysis-prompt.md

@@ -17,6 +17,10 @@ Input materials (provided by me):
 - Current truth source: `<truth-root>/`
 - Codebase (read-only analysis)
 
+**Required Spec Truth Reading** (mandatory before analysis):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: identify which existing Specs (REQ/Invariants/Contracts) are impacted by this change
+
 Hard constraints (must follow):
 - Impact analysis first, code later
 - No "decorative/surface refactors" unless they directly reduce risk for this change
@@ -53,6 +57,19 @@ Output format (MECE):
        - Are external system/API changes isolated by ACL? (External model changes must not leak into internal models)
        - Are there direct calls to external APIs bypassing the adapter layer?
        - If adding external dependency: suggested ACL interface definition
+   - **F. Affected Spec Truth** (required):
+     - List spec files under `<truth-root>/specs/` impacted by this change
+     - For each affected Spec, mark impact type:
+       - `[BREAK]`: breaks existing REQ/Invariant (needs Spec update or redesign)
+       - `[EXTEND]`: extends existing capability (needs new REQ/Scenario)
+       - `[DEPRECATE]`: deprecates existing capability (needs Spec marked deprecated)
+     - Output format:
+       ```
+       Affected Specs:
+       - [EXTEND] specs/order/spec.md - add cancel order scenario
+       - [BREAK] specs/payment/spec.md - INV-002 "paid orders cannot be cancelled" needs modification
+       - [DEPRECATE] specs/legacy-checkout/spec.md - entire spec deprecated
+       ```
 4) Compatibility and Risks
    - Breaking changes (explicitly mark if any)
    - Migration/rollback paths

package/skills/devbooks-spec-contract/references/spec-change-prompt.md

@@ -18,6 +18,10 @@ Inputs (provided by me):
 - Project profile (if present; follow formatting conventions first): `<truth-root>/_meta/project-profile.md`
 - Glossary / ubiquitous language (if present): `<truth-root>/_meta/glossary.md`
 
+**Spec Truth Conflict Detection** (must complete before writing):
+- **Must read existing Specs**: before writing spec delta, read all specs under `<truth-root>/specs/**`
+- **Purpose**: detect conflicts between new spec delta and existing Specs
+
 Hard constraints (must follow):
 - Output a **spec delta**, not a design doc, not an implementation plan, not code
 - Do not write implementation details (class names/function names/specific production file paths/library calls)
@@ -26,6 +30,13 @@ Hard constraints (must follow):
 - Avoid duplicating capabilities: search/reuse/modify existing capability specs first; create a new capability only when necessary
 - Ubiquitous language: if `<truth-root>/_meta/glossary.md` exists, you must use those terms; do not invent new terms
 
+**Conceptual Integrity Guardian** (conflict detection rules):
+- **Terminology conflict**: does the new spec use terminology inconsistent with existing specs? (e.g., `Order.status` vs `Order.state`)
+- **Rule conflict**: do new spec rules contradict existing spec rules? (e.g., "paid orders can be cancelled" vs "paid orders cannot be cancelled")
+- **Boundary conflict**: does the new spec's responsibility overlap with existing specs? (e.g., two specs both claim ownership of payment logic)
+- **Invariant compatibility**: does the new spec violate Invariants declared in existing specs?
+- **Conflict report**: if conflicts are detected, declare them at the top of the spec delta with resolution suggestions; archiving is forbidden until conflicts are resolved
+
 Workshop (internal step; do not output separately):
 - Before writing the spec, run a “virtual three-amigos workshop” (business/dev/test) and incorporate consensus + edge examples into Requirements/Scenarios; do not output workshop notes.
 

package/skills/devbooks-test-owner/SKILL.md

@@ -14,44 +14,98 @@ allowed-tools:
 
 ## Workflow Position Awareness
 
-> **Core Principle**: Test Owner has **dual-phase responsibilities** in the overall workflow, ensuring role isolation from Coder.
+> **Core Principle**: Test Owner has **dual-phase responsibilities** in the overall workflow, achieving mental clarity through **mode labels** (not session isolation).
 
 ### My Position in the Overall Workflow
 
 ```
-proposal → design → [Test Owner Phase 1] → coder → [Test Owner Phase 2] → code-review → archive
-                         ↓                              ↓
-                    Red baseline output          Green verification + check off
+proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-review → archive
+                         ↓              ↓           ↓
+                    Red baseline    Implement    Evidence audit
+                   (incremental)   (@smoke)     (no @full rerun)
 ```
 
+### AI Era Solo Development Optimization
+
+> **Important Change**: This protocol is optimized for AI programming + solo development scenarios, **removing the mandatory "separate session" requirement**.
+
+| Old Design | New Design | Reason |
+|------------|------------|--------|
+| Test Owner and Coder must use separate sessions | Same session, switch with `[TEST-OWNER]` / `[CODER]` mode labels | Reduce context rebuilding cost |
+| Phase 2 reruns full tests | Phase 2 defaults to **evidence audit**, optional sampling rerun | Avoid slow test multiple runs |
+| No test layering requirement | Mandatory test layering: `@smoke`/`@critical`/`@full` | Fast feedback loop |
+
 ### Test Owner's Dual-Phase Responsibilities
 
-| Phase | Trigger | Core Responsibility | Output |
-|-------|---------|---------------------|--------|
-| **Phase 1: Red Baseline** | After design.md is complete | Write tests, produce failure evidence | verification.md (Status=Ready), Red baseline |
-| **Phase 2: Green Verification** | After Coder completes | Verify tests pass, check off AC matrix | AC matrix checked, Status remains Ready (wait for Reviewer to set Done) |
+| Phase | Trigger | Core Responsibility | Test Run Method | Output |
+|-------|---------|---------------------|-----------------|--------|
+| **Phase 1: Red Baseline** | After design.md is complete | Write tests, produce failure evidence | Only run **incremental tests** (new/P0) | verification.md (Status=Ready), Red baseline |
+| **Phase 2: Green Verification** | After Coder completes + @full passes | **Audit evidence**, check off AC matrix | Default no rerun, optional sampling | AC matrix checked, Status=Verified |
 
 ### Phase 2 Detailed Responsibilities (Critical!)
 
 When user says "Coder is done, please verify" or similar, Test Owner enters **Phase 2**:
 
-1. **Run all tests**: Execute `npm test` or project test command
-2. **Verify Green status**: Confirm all tests pass
-3. **Check off AC Coverage Matrix**: Change `[ ]` to `[x]` in verification.md AC Coverage Matrix
-4. **Collect Green evidence**: Save to `evidence/green-final/`
-5. **Output verification report**: Summarize test results and coverage
+1. **Check prerequisites**: Confirm @full tests have passed (check CI results or `evidence/green-final/`)
+2. **Audit evidence** (default mode):
+   - Check test logs in `evidence/green-final/` directory
+   - Verify commit hash matches current code
+   - Confirm tests cover all ACs
+3. **Optional sampling rerun**: Sample verify high-risk ACs or questionable tests
+4. **Check off AC Coverage Matrix**: Change `[ ]` to `[x]` in verification.md AC Coverage Matrix
+5. **Set status to Verified**: Indicates test verification passed, waiting for Code Review
 
 ### AC Coverage Matrix Checkbox Permissions (Important!)
 
 | Checkbox Location | Who Can Check | When to Check |
 |-------------------|---------------|---------------|
-| `[ ]` in AC Coverage Matrix | **Test Owner** | Phase 2 after verifying Green status |
+| `[ ]` in AC Coverage Matrix | **Test Owner** | Phase 2 after evidence audit confirmed |
+| Status field `Verified` | **Test Owner** | After Phase 2 completion |
 | Status field `Done` | Reviewer | After Code Review passes |
 
 **Prohibited**: Coder cannot check AC Coverage Matrix, cannot modify verification.md.
 
 ---
 
+## Test Layering and Run Strategy (Critical!)
+
+> **Core Principle**: Test layering is key to solving "slow tests blocking development".
+
+### Test Layering Labels (Must Use)
+
+| Label | Purpose | Who Runs | Expected Time | When to Run |
+|-------|---------|----------|---------------|-------------|
+| `@smoke` | Fast feedback, core paths | Coder runs frequently | Seconds | After each code change |
+| `@critical` | Key functionality verification | Coder before commit | Minutes | Before commit |
+| `@full` | Complete acceptance tests | CI runs async | Can be slow (hours) | Background/CI |
+
+### Test Run Strategy by Phase
+
+| Phase | What to Run | Purpose | Blocking/Async |
+|-------|-------------|---------|----------------|
+| **Test Owner Phase 1** | Only **newly written tests** | Confirm Red status | Sync (but incremental only) |
+| **Coder during dev** | `@smoke` | Fast feedback loop | Sync |
+| **Coder before commit** | `@critical` | Key path verification | Sync |
+| **Coder on completion** | `@full` (trigger CI) | Complete acceptance | **Async** (doesn't block dev) |
+| **Test Owner Phase 2** | **No run** (audit evidence) | Independent verification | N/A |
+
+### Async vs Sync Boundary (Critical!)
+
+```
+✅ Async: Dev iteration (Coder can start next change after completion, no waiting for @full)
+❌ Sync: Archive gate (Archive must wait for @full to pass)
+
+Timeline example:
+T1: Coder completes implementation, triggers @full async test → Status = Implementation Done
+T2: Coder can start next change (not blocked)
+T3: @full tests pass → Status = Ready for Phase 2
+T4: Test Owner audits evidence + checks off → Status = Verified
+T5: Code Review → Status = Done
+T6: Archive (at this point @full has definitely passed)
+```
+
+---
+
 ## Prerequisites: Configuration Discovery (Protocol-Agnostic)
 
 - `<truth-root>`: Current truth directory root
@@ -86,10 +140,15 @@ Test Owner must produce a structured `verification.md` that serves as both test
 |--------|---------|-------------|
 | `Draft` | Initial state | Auto-generated |
 | `Ready` | Test plan ready | **Test Owner** |
+| `Implementation Done` | Implementation complete, waiting for @full tests | **Coder** |
+| `Verified` | @full passed + evidence audit complete | **Test Owner** |
 | `Done` | Review passed | Reviewer (Test Owner/Coder prohibited) |
-| `Archived` | Archived | Spec Gardener |
+| `Archived` | Archived | Archiver |
 
-**Constraint**: After completing the test plan, Test Owner should set Status to `Ready`.
+**Key Constraints**:
+- `Verified` status requires @full tests to have passed
+- Only changes with `Verified` or `Done` status can be archived
+- Test Owner sets `Ready` after completing test plan, sets `Verified` after evidence audit
 
 ```markdown
 # Verification Plan: <change-id>
@@ -385,14 +444,14 @@ Test Owner has two phases, completion status varies by phase:
 
 | Current Phase | How to Determine | Next Step After Completion |
 |---------------|------------------|---------------------------|
-| **Phase 1** | verification.md doesn't exist or Red baseline not produced | → Coder |
-| **Phase 2** | User says "verify/check off" and Coder has completed | → Code Review |
+| **Phase 1** | verification.md doesn't exist or Red baseline not produced | → `[CODER]` mode |
+| **Phase 2** | User says "verify/check off" and @full tests have passed | → Code Review |
 
 ### Phase 1 Completion Status Classification (MECE)
 
 | Code | Status | Determination Criteria | Next Step |
 |:----:|--------|------------------------|-----------|
-| ✅ | PHASE1_COMPLETED | Red baseline produced, no deviations | `devbooks-coder` (separate session) |
+| ✅ | PHASE1_COMPLETED | Red baseline produced, no deviations | Switch to `[CODER]` mode |
 | ⚠️ | PHASE1_COMPLETED_WITH_DEVIATION | Red baseline produced, deviation-log has pending records | `devbooks-design-backport` |
 | ❌ | BLOCKED | Needs external input/decision | Record breakpoint, wait for user |
 | 💥 | FAILED | Test framework issues etc. | Fix and retry |
@@ -401,8 +460,9 @@ Test Owner has two phases, completion status varies by phase:
 
 | Code | Status | Determination Criteria | Next Step |
 |:----:|--------|------------------------|-----------|
-| ✅ | PHASE2_VERIFIED | Tests all green, AC matrix checked | `devbooks-code-review` |
-| ❌ | PHASE2_FAILED | Tests not passing | Notify Coder to fix, or HANDOFF |
+| ✅ | PHASE2_VERIFIED | Evidence audit passed, AC matrix checked | `devbooks-code-review` |
+| ⏳ | PHASE2_WAITING | @full tests still running | Wait for CI to complete |
+| ❌ | PHASE2_FAILED | @full tests not passing | Notify Coder to fix |
 | 🔄 | PHASE2_HANDOFF | Found issues with tests themselves | Fix tests then re-verify |
 
 ### Phase Determination Flow
@@ -421,11 +481,13 @@ Test Owner has two phases, completion status varies by phase:
    c. All above pass → PHASE1_COMPLETED
 
 3. Phase 2 status determination:
-   a. Run tests, check if all green
+   a. Check if @full tests have completed
+      → No: PHASE2_WAITING
+   b. Check if @full tests passed
       → No: PHASE2_FAILED
-   b. Check if tests themselves have issues
+   c. Check if tests themselves have issues
       → Yes: PHASE2_HANDOFF
-   c. All green and no issues → PHASE2_VERIFIED
+   d. Audit evidence, confirm coverage → PHASE2_VERIFIED
 ```
 
 ### Routing Output Template (Required)
@@ -437,11 +499,13 @@ After completing test-owner, **must** output in this format:
 
 **Phase**: Phase 1 (Red Baseline) / Phase 2 (Green Verification)
 
-**Status**: ✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⚠️ ... / ❌ ... / 💥 ...
+**Status**: ✅ PHASE1_COMPLETED / ✅ PHASE2_VERIFIED / ⏳ PHASE2_WAITING / ...
 
 **Red Baseline**: Produced / Not completed (Phase 1 only)
 
-**Green Verification**: All green / Has failures (Phase 2 only)
+**@full Tests**: Passed / Running / Failed (Phase 2 only)
+
+**Evidence Audit**: Completed / Pending (Phase 2 only)
 
 **AC Matrix**: Checked N/M / Not checked (Phase 2 only)
 
@@ -449,31 +513,29 @@ After completing test-owner, **must** output in this format:
 
 ## Next Step
 
-**Recommended**: `devbooks-xxx skill`
+**Recommended**: Switch to `[CODER]` mode / `devbooks-xxx skill`
 
 **Reason**: [specific reason]
-
-### How to invoke
-Run devbooks-xxx skill for change <change-id>
 ```
 
 ### Specific Routing Rules
 
 | My Status | Next Step | Reason |
 |-----------|-----------|--------|
-| PHASE1_COMPLETED | `devbooks-coder` (separate session) | Red baseline produced, Coder implements to make Green |
+| PHASE1_COMPLETED | Switch to `[CODER]` mode | Red baseline produced, Coder implements to make Green |
 | PHASE1_COMPLETED_WITH_DEVIATION | `devbooks-design-backport` | Backport design first, then hand to Coder |
-| PHASE2_VERIFIED | `devbooks-code-review` | Tests all green, can proceed to code review |
-| PHASE2_FAILED | Notify Coder | Tests not passing, need Coder to fix |
+| PHASE2_VERIFIED | `devbooks-code-review` | Evidence audit passed, can proceed to code review |
+| PHASE2_WAITING | Wait for CI | @full tests still running |
+| PHASE2_FAILED | Notify Coder to fix | Tests not passing, need Coder to fix |
 | PHASE2_HANDOFF | Fix tests | Tests themselves have issues, Test Owner fixes |
 | BLOCKED | Wait for user | Record breakpoint area |
 | FAILED | Fix and retry | Analyze failure reason |
 
 **Critical Constraints**:
-- **Role Isolation**: Coder must work in a **separate conversation/instance**
-- Test Owner and Coder cannot share the same session context
+- **Mode switching replaces session isolation**: Use `[TEST-OWNER]` / `[CODER]` labels to switch modes
 - If deviations exist, must design-backport first before handing to Coder
 - **Phase 2 AC matrix checking can only be done by Test Owner**
+- **Phase 2 can only check off after @full tests have passed**
 
 ---
 

package/skills/devbooks-test-owner/references/test-code-prompt.md

@@ -11,6 +11,10 @@ Inputs (provided by me):
 - Design/spec documents
 - Test methodology references (see: `references/test-driven-development.md`)
 
+**Required Spec Truth Reading** (mandatory before testing):
+- `<truth-root>/specs/**`: existing spec files
+- Purpose: auto-generate test skeletons from contracts (Preconditions/Postconditions/Invariants) and state machines
+
 Artifact locations (directory conventions; protocol-agnostic):
 - Test plan + traceability should live at: `<change-root>/<change-id>/verification.md`
 - Test code changes live in the repo’s normal place (e.g., `tests/`), but traceability matrices and MANUAL-* checklists should live in the change package (`verification.md`), not scattered into external `docs/`
@@ -63,6 +67,16 @@ Core principles (must follow):
 3) **Deterministic and reproducible**: default to offline, no real external services; freeze time; fix random seeds; use fakes/mocks; fixed inputs.
 4) **Few but strong (risk-driven)**: prioritize the highest-risk failure modes (isolation, idempotency/replay, quality gates, error cascades, contract drift).
 
+**Contract Tests from Spec Truth** (must follow):
+- **Invariants → invariant tests**: each `[Invariant]` or `INV-xxx` in Specs must have a corresponding test
+- **Preconditions → precondition tests**: each `PRE-xxx` generates two tests: (1) success when satisfied (2) rejection when violated
+- **Postconditions → postcondition tests**: each `POST-xxx` generates result verification tests
+- **State Machine → transition tests**: if Spec contains state machine, generate:
+  - All legal transition path tests
+  - All forbidden transition rejection tests
+  - Terminal state cannot exit tests
+- **REQ coverage traceability**: each test must annotate which REQ-xxx/INV-xxx/PRE-xxx/POST-xxx it covers (in comments or verification.md)
+
 Coverage targets (debate edition; guidance only):
 
 | Code type | Coverage target | Rationale |