create-harness-vibe-coding 0.8.2 → 0.8.4

package/templates/common/Harness/HARNESS_BRIDGE.md

@@ -0,0 +1,128 @@
+# Harness Bridge
+
+Purpose: define a test-only bridge for validating frontend, backend, state, and side effects without making test selectors part of production behavior.
+
+Harness Bridge is not a business feature. It is enabled only in dev/test environments and must be absent or inert in production builds.
+
+## Modules
+
+| Module | Purpose | Output |
+| --- | --- | --- |
+| UI Test ID Contract | stable selectors for browser tests | `UI_CONTRACT.md` or task contract table |
+| API Contract | endpoint, payload, response, and failure behavior | `API_CONTRACT.md` or OpenAPI/schema reference |
+| Test Data Seeder | deterministic local data and mock external services | seed script or test fixture |
+| Runtime State Probe | test-only access to route/store/toast state | `window.__HARNESS__` or equivalent |
+| Network Trace Collector | CDP/Playwright capture of request/response behavior | trace file and assertion output |
+
+## UI Test ID Contract
+
+Every critical interactive element needs a stable selector before UI acceptance.
+
+```tsx
+<button data-testid="login-submit-button">Log in</button>
+```
+
+Contract shape:
+
+```markdown
+# UI Contract
+
+| Element | data-testid | Role | AC IDs |
+| --- | --- | --- | --- |
+| Phone input | `phone-input` | input phone number | AC-001, AC-002 |
+| Submit button | `login-submit-button` | submit login | AC-004, AC-006 |
+```
+
+No `data-testid`, no UI acceptance, unless a stable accessible role/label is explicitly documented.
+
+## API Contract
+
+API-facing ACs need method, URL, payload, success response, failure response, and side effects.
+
+````markdown
+# API Contract
+
+## POST /api/auth/send-code
+
+Request:
+```json
+{ "phone": "13800138000" }
+```
+
+Success:
+```json
+{ "ok": true }
+```
+
+Failure:
+```json
+{ "ok": false, "message": "Invalid phone number" }
+```
+````
+
+No API contract, no backend integration acceptance.
+
+## Test Data Seeder
+
+E2E tests must not depend on real SMS, payment providers, emails, or third-party side effects.
+
+Example contract:
+
+```ts
+await bridge.seed({
+  user: {
+    phone: "13800138000",
+    code: "123456"
+  }
+});
+```
+
+Seeder requirements:
+
+- deterministic
+- resettable between tests
+- scoped to dev/test
+- records seeded IDs needed for assertions
+
+## Runtime State Probe
+
+Expose only safe test state in dev/test:
+
+```ts
+window.__HARNESS__ = {
+  getRoute: () => router.currentRoute.value,
+  getAuthState: () => authStore.state,
+  getLastToast: () => toastStore.lastMessage
+};
+```
+
+Playwright may assert:
+
+```ts
+const authState = await page.evaluate(() => window.__HARNESS__.getAuthState());
+expect(authState.isLoggedIn).toBe(true);
+```
+
+Production builds must not expose secrets, tokens, private user data, or privileged mutation APIs through `window.__HARNESS__`.
+
+## Network Trace Collector
+
+For frontend-backend ACs, collect network evidence:
+
+```text
+user action
+-> CDP/Playwright records request
+-> assert URL, method, payload, response, duplicate-request behavior
+-> compare against API Contract
+```
+
+Minimum checks:
+
+- request sent or intentionally not sent
+- method and URL
+- payload shape and key values
+- response handling
+- disabled/loading behavior prevents duplicate submission
+- error state for network failure
+
+Trace evidence belongs under the task evidence folder or Playwright `test-results/`.

package/templates/common/Harness/MEMORY_PROTOCOL.md

@@ -0,0 +1,114 @@
+# Memory Protocol
+
+Purpose: record durable lessons from acceptance, validation, and debug work without storing noisy or sensitive context.
+
+Memory is downstream of evidence. It records reusable patterns, not raw transcripts.
+
+## When To Write Memory
+
+Write memory when any condition applies:
+
+- the same tool or command pattern fails 3+ times
+- the user corrects the same assumption or preference 2+ times
+- a review/debug loop reveals a reusable lesson
+- WF closeout extracts durable acceptance, validation, or debug knowledge
+
+## What To Record
+
+Memory entries should be short, newest-first, and AC-aware when possible:
+
+```markdown
+## 2026-07-02 - Playwright login validation needs network trace
+
+- Context: AC-003 passed visually but failed API payload validation.
+- Lesson: For login flows, require CDP/Playwright request assertions in addition to DOM checks.
+- Applies to: `ACCEPTANCE_PROTOCOL.md`, `HARNESS_BRIDGE.md`
+```
+
+Good memory:
+
+- failure mode
+- root cause pattern
+- better command or protocol
+- affected AC IDs or workflow docs
+- proof that the lesson is durable
+
+Bad memory:
+
+- secrets, tokens, credentials, private user data
+- full logs when a summary is enough
+- transient speculation
+- implementation summaries with no reusable lesson
+
+## Closeout Flow
+
+For WF closeout:
+
+```text
+context-master
+-> extract durable acceptance/debug/validation lessons
+-> memory-master
+-> deduplicate
+-> write concise memory entry
+```
+
+Memory Master writes to:
+
+- `Harness/memory/tool-usage-reflections.md`
+- `Harness/memory/user-corrections-preferences.md`
+- `Harness/memory/agent-lessons-patterns.md`
+- `Harness/MEMORY.md` only for routing/index updates
+
+## Scenario Memory Hints
+
+Controllers, context-master, or memory-master may load a compact memory hint
+when the current task matches a known scenario. Hints must be scenario-specific
+and must not dump full memory files into context.
+
+Scenario hints are allowed when they help the current task avoid a known failure
+mode:
+
+| Scenario | Load Or Hint |
+| --- | --- |
+| new session / startup | `Harness/MEMORY.md` index only |
+| same tool or command error repeats | matching entries from `memory/tool-usage-reflections.md` |
+| user repeats a correction or preference | matching entries from `memory/user-corrections-preferences.md` |
+| review/debug/validation failure | matching entries from `memory/agent-lessons-patterns.md` |
+| acceptance/UI/API work | relevant AC/debug lessons plus `ACCEPTANCE_PROTOCOL.md` and `HARNESS_BRIDGE.md` |
+| WF closeout | context-master extraction, then memory-master write/dedup |
+| `/wf-auto` cycle start | auto PROGRESS/PLAN summary plus memory hints tied to the selected angle |
+
+Hint rules:
+
+- load or summarize 3-10 bullets, not whole memory files
+- include file paths and trigger reasons
+- include AC IDs or failure signatures when available
+- load nothing when no relevant memory exists
+- never inject secrets, credentials, tokens, private data, or raw transcripts
+- memory-master owns writes; controller/context-master route context
+
+## Memory Write Flow
+
+Memory write triggers must never append raw logs directly to memory files.
+
+Safe write flow:
+
+```text
+controller detects trigger
+-> context-master extracts durable candidate
+-> memory-master reads existing memory
+-> memory-master deduplicates or merges
+-> memory-master writes concise entry
+-> controller records file path and reason
+```
+
+## Traceability
+
+When a lesson comes from acceptance work, include:
+
+- AC ID or contract name
+- command or validation method
+- failure layer
+- final fix or operating rule
+
+This keeps future agents from relearning the same acceptance gap.

package/templates/common/Harness/README.md

@@ -7,7 +7,7 @@ Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS
 ## 0-1 Flow
 
 ```text
-Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
+Idea -> Research -> Mini PRD -> Acceptance Criteria -> Contracts -> Tests -> Build -> Independent Validation -> Debug -> Memory
 ```
 
 For the full phase contract, load [lifecycle.md](lifecycle.md).
@@ -24,7 +24,10 @@ For the full phase contract, load [lifecycle.md](lifecycle.md).
 - Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
 - WF mode rules live in [WF.md](WF.md).
 - Phase rules live in [lifecycle.md](lifecycle.md).
-- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md).
+- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md); AC-linked TDD rules live in [TDD-GUIDE.md](TDD-GUIDE.md).
+- Acceptance-driven gates live in [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md). PRD-derived Acceptance Criteria are the source of truth for implementation, tests, review, validation, debug, and memory.
+- Role/context isolation rules live in [AGENT_ISOLATION.md](AGENT_ISOLATION.md).
+- Frontend-backend test harness and CDP/network evidence rules live in [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md).
 - Parallel dispatch rules live in [dispatch.md](dispatch.md).
 - Subagent orchestration methodology lives in [subagents.md](subagents.md).
 - Extension rules live in [extension.md](extension.md).
@@ -57,21 +60,22 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 | --- | --- | --- | --- |
 | Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
 | Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
-| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
+| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | Mini PRD with AC IDs and verifiable acceptance criteria |
 | Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](architecture.md) | layer map, ports, constraints |
+| Need WF command help | /wf-help, wf help, command list, list wf commands | `.claude/commands/wf-help.md` | direct command table; no skill invocation |
 | Need WF mode | wf, /wf, $wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
-| Need perpetual auto-optimization | /wf-auto, $wf-auto, wf auto, auto mode, never stop, self-improve, continuous optimize | [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | perpetual loop, 8-angle scan, spark search, intent checkpoint, evidence ledger; CEO never writes code |
+| Need perpetual auto-optimization | /wf-auto, $wf-auto, wf auto, auto mode, never stop, self-improve, continuous optimize | [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | perpetual loop, bounded ticks, optional wf-auto-only hook exception, 8-angle scan, spark search, intent checkpoint, evidence ledger; CEO never writes code |
 | Need perpetual inspiration mode | /wf-auto-spark, $wf-auto-spark, wf auto spark, spark mode, external inspiration, discover mode, never stop | [WF-AUTO-SPARK.md](WF-AUTO-SPARK.md), [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | roadmap-anchored: North Star + milestones; external spark search; ≤50% deviation guard; never auto-stops |
 | Need WF-MAX mode | /wf-max, $wf-max, wf max, maximum parallelism, CEO, Manager, Worker, fan-out | [WF-MAX.md](WF-MAX.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | CEO-only dispatch, W0 fan-out, D-GATE, wave evidence |
 | Need peer review | /wf-review, $wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `.agents/skills/wf-review/SKILL.md`, `Harness/README.md` | cross-model multi-dimension review with severity classification |
 | Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
 | README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
-| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
-| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use | browser-e2e workflow, wf-browser skill, Browser Use skill | CLI commands, screenshots, agent history, verification pass/fail evidence |
+| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | tasks, AC IDs, write set, verification commands |
+| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use, CDP | browser-e2e workflow, [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md), wf-browser skill, Browser Use skill | UI/API contract, CLI commands, screenshots, traces, validation matrix |
 | Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
-| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
-| Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
-| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md) | task plan, tests, implementation loop |
+| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection, scenario memory | [MEMORY.md](MEMORY.md), [MEMORY_PROTOCOL.md](MEMORY_PROTOCOL.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry, scenario memory hint, or no-op rationale |
+| Need subagents | subagent, role pack, context, inject, return format, orchestrator, isolation | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md), [AGENT_ISOLATION.md](AGENT_ISOLATION.md) | controller plan, role-specific context pack, isolation-aware dispatch pack |
+| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md), [TDD-GUIDE.md](TDD-GUIDE.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | task plan, AC-linked RED tests, implementation loop |
 | Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
 | Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
 | Need harness update | /wf-update, $wf-update, update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `.agents/skills/wf-update/SKILL.md`, `Harness/.harness-version`, `Harness/scripts/wf-update-check.mjs` | script-driven comparison, SAFE/CONFLICT/PRESERVE classification, user decides conflicts |
@@ -82,10 +86,13 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 - Move phases in order unless the user asks for a fast lane.
 - Use `/wf <task>` in Claude Code, `$wf` in Codex, `/wf-max [task]` or `$wf-max`, `wf mode`, `workflow mode`, or `wk mode` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
 - Use `/wf-auto` for perpetual self-directed optimization that never stops until 8-angle exhaustion.
-- **WF-MAX Role Contract**: Three-layer architecture — global mode (`wf-max`), agent role (`ceo|manager|worker|reviewer`), dispatch permission (`writeSet`, `forbidden`, `verification`). CEO never writes source code. Workers edit only dispatch.writeSet. Edit/Write/MultiEdit enforced by PreToolUse hook per agentRole. See `CLAUDE.md` §1a.
+- **WF-MAX Role Contract**: Three-layer architecture — global mode (`wf-max`), agent role (`ceo|manager|worker|reviewer`), dispatch permission (`writeSet`, `forbidden`, `verification`). CEO never writes source code. Workers edit only dispatch.writeSet. Compliance is checked through dispatch packets, independent review, validation evidence, and task capsules. See `CLAUDE.md` §1a.
 - **WF-REVIEW Anti-Self-Review**: Must invoke the OTHER CLI (Codex↔Claude). Same-model simulation is forbidden.
-- Mode state persists in `Harness/.runtime/current-mode.json` (gitignored). SessionStart hook injects role-aware context (CEO/Worker/Manager/Reviewer). Stale modes (>30 min) auto-clear. Per-turn reinforcement prevents drift after compression.
-- Do not code before the PRD has MVP, non-goals, and acceptance criteria.
+- WF-MAX has no runtime hook state. The durable state is the task capsule, dispatch table, review findings, and validation evidence. The only runtime hook exception in Harness is the optional `/wf-auto` bounded tick hook described in `WF-AUTO.md`.
+- Do not code before PRD-GATE, AC-GATE, CONTRACT-GATE, and TEST-GATE are satisfied or explicitly compressed into a documented fast lane.
+- PRD-derived Acceptance Criteria are the source of truth. Code, tests, reviews, validation, debug, and memory must trace to AC IDs.
+- No acceptance criteria, no tests. No acceptance criteria, no code.
+- No `data-testid` or stable accessible selector, no UI acceptance. No API contract, no backend integration acceptance.
 - Unsure whether to open a task? Read [agent-workflow.md](agent-workflow.md) Section 1.
 - Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
 - Do not run writing agents in parallel unless write sets are disjoint.
@@ -97,7 +104,6 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 - Do not close work without tests or recorded manual verification.
 - Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
 - Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
-- Run `node tests/e2e-wf-hooks.test.mjs` to verify hook enforcement works before deploying WF-MAX.
 - If a doc still has `{{...}}`, treat that section as a template, not project fact.
 
 ## Doc Map
@@ -107,13 +113,22 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 | **Router + Index** | `README.md`, `MEMORY.md`, `PROGRESS.md` |
 | **Task Capsule** | `tasks/<id>/PROGRESS.md`, `tasks/<id>/PLAN.md`, `tasks/_template/` |
 | **Workflows** | `WF.md`, `WF-MAX.md`, `WF-AUTO.md`, `WF-AUTO-SPARK.md` |
+| **Protocols** | `ACCEPTANCE_PROTOCOL.md`, `AGENT_ISOLATION.md`, `HARNESS_BRIDGE.md`, `DEBUG_PROTOCOL.md`, `MEMORY_PROTOCOL.md` |
 | **Guides** | `ECC-GUIDE.md`, `TDD-GUIDE.md`, `lifecycle.md`, `architecture.md` |
 | **Orchestration** | `subagents.md`, `context-loading.md`, `dispatch.md`, `agent-workflow.md`, `extension.md` |
 | **Research** | `research/README.md`, `research/PRD.md`, `research/research-results.md` |
+| **Acceptance Templates** | `templates/PRD.template.md`, `templates/ACCEPTANCE.template.md`, `templates/UI_CONTRACT.template.md`, `templates/API_CONTRACT.template.md`, `templates/TEST_PLAN.template.md`, `templates/PLAYWRIGHT_SPEC.template.ts`, `templates/VALIDATION_REPORT.template.md` |
 | **Memory** | `memory/tool-usage-reflections.md`, `memory/user-corrections-preferences.md`, `memory/agent-lessons-patterns.md` |
-| **Scripts** | `scripts/wf-mode-hook.mjs`, `scripts/validate-harness.mjs`, `scripts/wf-update-check.mjs`, `scripts/wf-remove.mjs` |
-| **Runtime** | `.runtime/current-mode.json` (gitignored, hook-managed), `.harness-version` |
+| **Scripts** | `scripts/validate-harness.mjs`, `scripts/wf-update-check.mjs`, `scripts/wf-remove.mjs` |
+| **Runtime** | `.harness-version` |
 | **Agents + Skills** | `.claude/agents/*`, `.claude/skills/*`, `.agents/skills/*` |
+| **Direct Commands** | `.claude/commands/wf-help.md` |
+
+## Direct Commands
+
+| Command | Purpose |
+|---|---|
+| `/wf-help` | Directly returns a table of all Harness WF commands, usage, and purpose. It does not invoke a skill or start a workflow. |
 
 ## Skill Commands
 
@@ -126,6 +141,6 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 | `/wf-review [focus]` | `$wf-review [focus]` | Cross-model peer review via Codex <-> Claude |
 | `/wf-learn` | `$wf-learn` | Force learning cycle: context-master -> memory-master |
 | `/wf-browser [task]` | `$wf-browser [task]` | AI-driven browser automation for E2E testing |
+| `/wf-readme [task]` | `$wf-readme [task]` | README preservation, merge, and documentation improvement workflow |
 | `/wf-update` | `$wf-update` | Script-driven harness update: fetch + compare + apply |
 | `/wf-remove` | `$wf-remove` | Safe harness removal: auto-delete SAFE, confirm MODIFIED, preserve USER DATA |
-```

package/templates/common/Harness/TDD-GUIDE.md

@@ -1,83 +1,165 @@
-# TDD Guide — Test-Driven Development in Harness
+# TDD Guide - Test-Driven Development in Harness
 
-TDD is NOT optional in Harness. The agent-workflow loop requires a failing test before implementation.
-This guide specifies when, how, and what to test.
+TDD is NOT optional in Harness. The workflow loop requires failing executable tests before implementation.
+For behavior changes, tests must be derived from PRD acceptance criteria, not from the implementation.
 
-## When TDD is Mandatory
+## Source Of Truth
+
+The source of truth for tests is the PRD-derived Acceptance Criteria in `ACCEPTANCE_PROTOCOL.md`.
+
+Required trace:
+
+```text
+Mini PRD -> AC ID -> UI/API/state contract -> RED test -> implementation -> validation evidence
+```
+
+Every behavior test must reference an AC ID in the test name, test comment, or validation matrix. A test that cannot be traced to an AC ID is not an acceptance test.
+
+## When TDD Is Mandatory
 
 | Trigger | Action |
-|---------|--------|
-| New feature | Write failing test first. Implementation MUST NOT start without it. |
-| Bug fix | Write failing regression test that reproduces the bug. Fix only after test fails. |
+| --- | --- |
+| New feature | Write failing AC-linked test first. Implementation MUST NOT start without it. |
+| Bug fix | Write failing regression test that reproduces the bug and links to the affected AC or incident. |
 | Refactor | Existing tests MUST be green before refactoring. Keep green throughout. |
-| API endpoint | Integration test first (request → expected response). |
-| UI component | Visual regression or behavior test first (render → user action → expected state). |
-| Database change | Migration test first (apply → verify schema → rollback → verify). |
+| API endpoint | Integration/API contract test first: request -> expected response -> error response. |
+| UI component | Behavior test first: real user action -> DOM/state/API result. |
+| Browser-visible flow | Playwright/CDP or documented real-browser test first; unit tests are supporting checks only. |
+| Database change | Migration test first: apply -> verify schema/data -> rollback -> verify. |
+
+## TDD Cycle
+
+```text
+RED:
+  Write the smallest AC-linked failing test.
+  Run it and confirm it fails for the expected product reason.
+
+GREEN:
+  Write the smallest implementation needed to pass.
+  Run the target test and confirm it passes.
+  Run the declared broader test set.
+
+IMPROVE:
+  Refactor while keeping tests green.
+  Re-run the declared verification commands.
+  Record coverage and acceptance evidence.
+```
 
-## TDD Cycle (Red-Green-Refactor)
+If the RED test passes immediately, the test is wrong, the fixture is wrong, or the behavior already exists. Stop and record which case is true before implementation.
 
+## Browser/UI Acceptance TDD Gate
+
+For user-visible or browser-visible behavior, syntax checks, type checks, shallow renders, import tests, and assertion-only unit tests are not acceptance tests.
+
+The first acceptance test for a UI flow must exercise the real user path:
+
+1. Open the real route/page in a browser-capable runner.
+2. Interact through stable selectors such as `data-testid` or accessible roles.
+3. Click, type, select, drag, submit, or navigate as a user would.
+4. Assert the DOM result and the relevant URL, route, store, localStorage, or runtime state change.
+5. For frontend-backend behavior, assert network/API behavior with Playwright request capture, CDP, or the Harness Bridge Network Trace Collector.
+6. Capture evidence: screenshot, trace, video, console log, network log, or validation report path.
+7. Record the AC-by-AC result matrix.
+
+Default frontend verification, when tooling exists:
+
+```bash
+npm run test
+npm run typecheck
+npm run lint
+npx playwright test
 ```
-RED:    Write minimal failing test
-        → Run test → FAILS (if it passes, test is wrong)
-GREEN:  Write minimal code to make test pass
-        → Run test → PASSES
-        → Run ALL tests → ALL GREEN
-IMPROVE: Refactor while keeping green
-        → Run ALL tests → ALL GREEN
-        → Coverage check (≥80%)
+
+For frontend-backend flows or suspected flakes:
+
+```bash
+npx playwright test --trace on
 ```
 
+`npm test`, typecheck, lint, and component-unit tests are useful supporting checks. They cannot replace Playwright/CDP or documented real-browser validation for a browser-visible AC.
+
+## Contract Requirements
+
+Before writing browser or API acceptance tests, load the relevant contracts:
+
+- UI selectors from `UI_CONTRACT.md` or the task PLAN contract table
+- API requests/responses from `API_CONTRACT.md` or the task PLAN contract table
+- Harness Bridge rules from `HARNESS_BRIDGE.md`
+- Agent isolation rules from `AGENT_ISOLATION.md`
+
+Missing selectors or contracts are blockers. Do not silently invent selectors in tests without updating the UI contract through the proper planning/acceptance role.
+
 ## ECC Testing Rules
 
-Coverage thresholds, AAA structure, test naming, and per-stack setup live in ECC testing rules (`common/testing.md` + stack-specific). This guide defines Harness sequencing only: failing test/manual check first, implementation second, verification last.
+Coverage thresholds, AAA structure, test naming, and per-stack setup live in ECC testing rules (`common/testing.md` plus stack-specific files). This guide defines Harness sequencing and acceptance depth: failing test first, implementation second, real behavior validation last.
 
-## Agent Dispatch — TDD Gate
+## Agent Dispatch - TDD Gate
 
-Before dispatching an Implementer, the Planner MUST verify:
+Before dispatching an Implementer, the Planner or Test Manager MUST verify:
 
-1. [ ] Test file exists for the target module
-2. [ ] Test is RED (fails) for new feature / bug fix
-3. [ ] Test covers acceptance criteria
-4. [ ] Test covers error paths (not just happy path)
-5. [ ] Coverage threshold declared in PLAN.md
+1. [ ] Each behavior change has a Mini PRD or task PLAN entry.
+2. [ ] Each behavior change has AC IDs.
+3. [ ] Test files or test specs reference the relevant AC IDs.
+4. [ ] Tests are RED for new feature / bug fix work and fail for the expected reason.
+5. [ ] Tests cover happy path, error path, empty/loading/disabled states where applicable.
+6. [ ] Browser-visible ACs have real user interaction tests, not syntax-only or shallow render tests.
+7. [ ] Frontend-backend ACs include network/API assertions against the contract.
+8. [ ] Evidence capture is declared: screenshot, trace, video, log, or report path.
+9. [ ] Coverage threshold and verification commands are declared in PLAN.md.
 
-If any check fails → dispatch Test Writer first, then Implementer.
+If any check fails, dispatch Test Writer or Acceptance Agent first, then Implementer.
 
-## TDD Anti-Patterns
+## Forbidden Shortcuts
 
-| Anti-Pattern | Symptom | Fix |
-|-------------|---------|-----|
-| **Test-last** | Writing implementation first, then tests "to verify" | Reverse order. Tests first. |
-| **Test-the-test** | Test passes immediately (testing nothing) | Add real assertion. Delete and rewrite. |
-| **Giant test** | One test covering entire feature | Split into unit (logic) + integration (API) + E2E (flow) |
-| **Mock everything** | All dependencies mocked, no real behavior tested | Mock only external I/O (network, disk). Test real logic. |
-| **Skip coverage** | "80% is too hard, let's move on" | Coverage is a gate. Don't merge without it. |
+These are not valid acceptance tests for browser-visible behavior:
+
+- A test that only imports a component and asserts it renders.
+- A test that only checks TypeScript, lint, formatting, or build success.
+- A snapshot with no user action and no AC-linked assertion.
+- A mocked path where the browser, router, store, API boundary, and side effects are all replaced.
+- An assertion against implementation internals instead of user-observable behavior.
+- A test written from the implementer's code rather than from PRD/AC/contracts.
+- Changing PRD, AC, UI contract, or API contract to make implementation tests pass.
 
-## TDD in WF-MAX Mode
+## TDD Anti-Patterns
 
-In `/wf-max`, tests and implementation are dispatched in SEPARATE waves.
+| Anti-Pattern | Symptom | Fix |
+| --- | --- | --- |
+| Test-last | Writing implementation first, then tests "to verify" | Reverse order. Tests first. |
+| Test-the-test | Test passes immediately and proves no product behavior | Rewrite around the AC and expected RED reason. |
+| Syntax-only acceptance | UI flow "tested" by typecheck/build/import assertions | Add Playwright/CDP real user path coverage. |
+| Mocked browser path | All browser, state, and network behavior mocked away | Keep only external services mocked; exercise real page behavior. |
+| Network-blind UI test | UI assertion passes but request URL/method/payload is unchecked | Add Playwright/CDP/Harness Bridge network assertions. |
+| No AC ID | Test name does not map to acceptance criteria | Add AC ID in name/comment and validation matrix. |
+| Giant test | One test covering entire feature | Split into unit, API/integration, and E2E acceptance checks. |
+| Mock everything | All dependencies mocked, no real behavior tested | Mock only external I/O when needed. Test real logic and boundaries. |
+| Skip coverage | Coverage gate ignored | Record configured threshold and command evidence before closeout. |
+
+## TDD In WF-MAX Mode
+
+In `/wf-max`, acceptance/test planning and implementation are separate waves.
 Test Writers MUST complete before Implementers start. No parallel overlap.
 
-```
-W2a — TEST WAVE (Test Writers, parallel):
-  1. Test Writer (FE) → write failing tests for UserProfile
-  2. Test Writer (BE) → write failing API tests for GET /users
-  ↓ BARRIER: all tests written and confirmed RED ↓
-
-W2b — IMPLEMENTATION WAVE (Implementers, parallel):
-  3. Implementer (FE) → make FE tests pass
-  4. Implementer (BE) → make BE tests pass
-  ↓ BARRIER: all tests GREEN ↓
-
-W2R — REVIEW WAVE:
-  5. Reviewer → verify test coverage + implementation correctness
+```text
+W2a - ACCEPTANCE/TEST WAVE:
+  1. Acceptance Agent -> confirm AC IDs and contracts
+  2. Test Writer (FE) -> write RED Playwright/user-path tests for UI ACs
+  3. Test Writer (BE) -> write RED API/integration tests for API ACs
+  4. CDP/Network Agent -> define request/response assertions
+  -> BARRIER: all AC-linked tests written and confirmed RED
+
+W2b - IMPLEMENTATION WAVE:
+  5. Implementer (FE) -> make FE acceptance tests pass
+  6. Implementer (BE) -> make API tests pass
+  -> BARRIER: target tests GREEN and broader checks run
+
+W2R - REVIEW/VALIDATION WAVE:
+  7. Reviewer -> verify diff, AC coverage, and forbidden-file discipline
+  8. Validator -> run real browser/API validation and produce AC matrix
 ```
 
-**Why separate waves:** Workers in the same WF-MAX wave run in parallel.
-If Test Writers and Implementers share a wave, Implementers start before RED
-tests exist — violating the TDD gate. Two waves with an explicit barrier
-ensures tests exist before any implementation begins.
+Workers in the same WF-MAX wave run in parallel. If Test Writers and Implementers share a wave, Implementers can start before RED tests exist, violating the TDD gate.
 
 ## Verification
 
-Run the verification commands declared in the task PLAN or dispatch packet. Do not claim TDD completion until RED, GREEN, and full-check evidence are recorded.
+Run the verification commands declared in the task PLAN or dispatch packet. Do not claim TDD completion until RED, GREEN, full-check evidence, and AC-by-AC validation evidence are recorded.