create-harness-vibe-coding 0.2.1 → 0.3.1

package/templates/common/docs/harness/context-loading.md

@@ -6,9 +6,9 @@ Use when context is growing, subagents are needed, or an agent is unsure which h
 
 `Harness/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
 
-If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `Harness/PLAN.md`, and update this file later.
+If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`, and update this file later.
 
-project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Main Context
 
@@ -17,7 +17,9 @@ Always keep:
 - `CLAUDE.md`
 - `Harness/MEMORY.md`
 - `Harness/README.md`
-- `Harness/PLAN.md` when active
+- `Harness/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PLAN.md` when active
 - current feature doc when active
 
 Load other docs only by trigger.
@@ -30,8 +32,8 @@ Load other docs only by trigger.
 | research, competitors, stack choice | `Harness/research/README.md`, `Harness/research/research-results.md` |
 | official docs, API, SDK, version, limits | `Harness/research/README.md`, `Harness/architecture.md`, `Harness/domain/ports.md` as needed |
 | layer, dependency, module boundary | `Harness/architecture.md`, `Harness/domain/ports.md` |
-| task split, owner, write set | `Harness/PLAN.md`, `Harness/agent-workflow.md` |
-| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/PLAN.md` |
+| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
 | memory, repeated tool failure, repeated user correction, reusable lesson | `Harness/MEMORY.md`, the relevant `Harness/memory/*.md` file |
 | event, retry, failure path | `Harness/data-flow.md` |
 | status, transition, resume | `Harness/state-machines.md` |
@@ -89,6 +91,16 @@ Verifier:
 - forbid: code changes
 - return: commands run, results, residual risk
 
+Memory Master:
+- inject: trigger reason, current failure/user-correction/closeout context, task PROGRESS.md section
+- forbid: source code, unrelated Harness docs
+- return: memory action summary, files written, cross-project flag
+
+Context Master:
+- inject: trigger reason (threshold % or closeout), current task PROGRESS.md, task phase
+- forbid: source code, memory files, MEMORY.md writes
+- return: context usage %, stale blocks, compressible blocks, durable knowledge candidates, compression suggestion
+
 ## Handoff Rule
 
 Only the subagent summary enters main context. If details are needed, load the named files directly instead of replaying the subagent conversation.

package/templates/common/docs/harness/dispatch.md

@@ -10,18 +10,19 @@ Use when work needs parallel reading, independent review, cross-layer analysis,
 
 - Main agent owns the final decision, integration, and verification.
 - project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
-- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Prefer three or fewer active agents.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+- Prefer three or fewer active agents (WF mode overrides this; see [WF.md](WF.md)).
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint.
 - Use a worktree when two agents may touch overlapping files or long-running branches.
 - Only summaries enter main context. Load named files directly when details are needed.
+- Subagents read task files, return findings and PLAN patch suggestions. Only the main agent commits changes to PROGRESS.md and PLAN.md.
 
 ## Dispatch Loop
 
 ```text
 Goal
--> Fill PLAN tasks and Parallel Dispatch
+-> Fill task PROGRESS.md and PLAN.md
 -> Apply subagents.md efficiency ladder
 -> Run parallel read-only agents
 -> Main agent integrates findings
@@ -29,7 +30,7 @@ Goal
 -> Implementer makes bounded change
 -> Reviewer checks diff
 -> Verifier records evidence
--> Main agent updates PLAN and closes or iterates
+-> Main agent updates task files and closes or iterates
 ```
 
 ## Modes
@@ -54,6 +55,8 @@ Goal
 | `debugger` | Serial Write | smallest fix for a reproduced failure |
 | `reviewer` | Parallel Read | diff review, risks, missing tests |
 | `verifier` | Parallel Read | run checks and record evidence |
+| `memory-master` | Serial Write | write/consolidate memory entries, dedup, cross-project extraction |
+| `context-master` | Parallel Read | analyze context usage, recommend compression, extract session knowledge |
 
 ## Dispatch Rules
 
@@ -61,7 +64,8 @@ Goal
 - A write set of `none` means read-only.
 - If two write sets overlap, do not run those agents in parallel.
 - If an agent returns uncertainty, mark the row `Blocked` or add a follow-up row.
-- If docs, tests, and code disagree, stop implementation and record the conflict in `PLAN.md`.
+- If docs, tests, and code disagree, stop implementation and record the conflict in `Harness/tasks/<task-id>/PROGRESS.md`.
+- In /wf max, file claims must respect WF-MAX.md leaf condition: no split below 50 avgLines, no split when files ≤ span×2.
 
 ## Handoff Format
 
@@ -78,10 +82,13 @@ Evidence:
 Risks:
 Next:
 PLAN patch:
+Concurrency group:  <wave number — 0=exploration, 1,2,3,...=implementation waves. Optional; only used in /wf max.>
+File claim:         <list of exact file paths this agent exclusively owns. Optional; only used in /wf max.>
+Granularity floor:  <50 avgLines → do NOT spawn. Apply leaf condition from WF-MAX.md.>
 ```
 
 Use `Files changed: none` for read-only agents. Use `PLAN patch: none` when no state update is needed.
-If a handoff matters after context loss, write it to `Harness/PLAN.md`, the current feature doc, or `Harness/memory/*`; do not rely on chat transcript state.
+If a handoff matters after context loss, write it to `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, or `Harness/memory/*`; do not rely on chat transcript state.
 
 ## Statuses
 

package/templates/common/docs/harness/extension.md

@@ -12,7 +12,7 @@ Extensions must preserve project and harness ownership boundaries.
 - Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
 - Register added agents, skills, workflows, rules, and hooks in `Harness/MEMORY.md` and this docs router where applicable.
 - Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `Harness/workflows/`, but they must not replace core harness docs.
-- Core harness docs are `Harness/README.md`, `Harness/PLAN.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
+- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
 - If an optional workflow needs a new command or tool, document the command and fallback in `Harness/workflows/<name>.md` instead of changing core harness behavior.
 
 ## Agent Contract
@@ -55,10 +55,10 @@ Every added skill must state:
 - required inputs
 - allowed writes
 - output format
-- whether to update `Harness/PLAN.md`
+- whether to update `Harness/PROGRESS.md` and task files
 - whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
 
-Skills should extend the harness. They should not replace `Harness/README.md`, `PLAN.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
+Skills should extend the harness. They should not replace `Harness/README.md`, `Harness/PROGRESS.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
 
 ## Rules
 
@@ -75,5 +75,5 @@ After adding assets:
 - list agents in `Harness/MEMORY.md#Agents`
 - list skills in `Harness/MEMORY.md#Skills`
 - list workflows by path in `Harness/MEMORY.md` or `Harness/README.md`
-- update `Harness/PLAN.md` when the asset affects current work
+- update `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md` when the asset affects current work
 - run `node Harness/scripts/validate-harness.mjs`

package/templates/common/docs/harness/lifecycle.md

@@ -10,10 +10,10 @@ Use when starting a new product, clarifying a vague idea, or deciding the next p
 | Research | problem and constraints | `research/research-results.md` | `research/README.md` followed; at least 3 references or explicit reason not possible |
 | PRD | research decision | `research/PRD.md` | MVP, non-goals, acceptance criteria are verifiable |
 | Architecture | PRD | `Harness/architecture.md`, `Harness/domain/ports.md` | boundaries and first ports are defined |
-| Plan | PRD and architecture | `Harness/PLAN.md`, optional `Harness/dispatch.md`, one `Harness/features/<name>.md` per PRD scope item | tasks have owners, write sets, verification |
+| Plan | PRD and architecture | `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, optional `Harness/dispatch.md`, one `Harness/features/<name>.md` per PRD scope item | tasks have owners, write sets, verification |
 | Build | plan and tests | minimal vertical slice | tests or manual checks prove behavior |
 | Verify | implementation | review findings, test evidence | no unresolved critical/high findings |
-| Feedback | verified slice | next iteration or release decision | learnings recorded in PRD, PLAN, or MEMORY |
+| Feedback | verified slice | next iteration or release decision | learnings recorded in PRD, `Harness/tasks/<task-id>/PROGRESS.md`, or MEMORY |
 
 ## Operating Rules
 

package/templates/common/docs/harness/subagents.md

@@ -4,7 +4,7 @@ Purpose: coordinate subagents for speed without losing control of scope, evidenc
 
 Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or `/wf`.
 
-project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Source Attribution
 
@@ -28,7 +28,7 @@ The main agent is the controller. It owns:
 - intent confidence and user questions
 - task decomposition
 - read/write set boundaries
-- dispatch table in `Harness/PLAN.md`
+- dispatch table in `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`
 - integration of returned summaries
 - final verification and closeout
 
@@ -49,6 +49,8 @@ Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
 | `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
 | `debugger` | reproduced failures, root cause isolation, smallest safe fix |
 | `verifier` | command execution, real browser/API checks, final evidence |
+| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
+| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
 
 ## WF Default Fan-Out
 
@@ -67,6 +69,8 @@ Then add phase-specific agents:
 - `reviewer` for spec and code-quality gates
 - `debugger` after a reproduced verification failure
 - `verifier` for final command/browser/API evidence
+- `context-master` before closeout for knowledge extraction
+- `memory-master` after repeated failures and during closeout for consolidation
 
 The default decision ratio is a 7:3 collaboration bias: choose multi-agent collaboration for substantial or uncertain work about 70% of the time; choose solo mode only for clearly local, low-risk work that is not explicitly in WF/WK mode.
 
@@ -81,6 +85,7 @@ Choose the cheapest coordination level that is safe.
 | Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
 | Serial build lane | normal feature or fix | test-writer -> implementer -> reviewers -> verifier |
 | Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
+| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
 
 Default for automatic WF triggers: 3-5 active read-only agents before second planning. For explicit WF/WK mode, never use the solo pass unless subagents are unavailable; use bounded role passes as the recorded fallback.
 
@@ -102,6 +107,18 @@ controller intake
 
 Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
 
+```text
+/wf max orchestration shape:
+controller intake
+-> wave 0: max-parallel exploration (4-14 read-only agents)
+-> controller synthesis: dependency graph + write-set coloring
+-> wave 1: N parallel implementers (disjoint file claims)
+-> wave 1 review: parallel spec/code/security reviewers
+-> wave 2+: dependent implementers (if any)
+-> integration verifier
+-> closeout with evidence
+```
+
 ## Dispatch Pack
 
 Every subagent dispatch must be self-contained:
@@ -127,8 +144,9 @@ Do not make a subagent rediscover the entire project or read the whole harness.
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint and the controller has chosen an isolated worktree.
 - Reviewers may run in parallel after implementation, but spec compliance is evaluated before code-quality approval.
-- Do not let two agents edit `Harness/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
-- If two agents disagree, the controller records the conflict in `Harness/PLAN.md` and chooses the smallest reversible next step.
+- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) commits state changes to task files.
+- Do not let two agents edit `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
+- If two agents disagree, the controller records the conflict in `Harness/tasks/<task-id>/PLAN.md` and chooses the smallest reversible next step.
 
 ## Review Gates
 
@@ -144,7 +162,7 @@ If either reviewer finds issues, the implementer or debugger fixes them and the
 | Status | Controller Action |
 | --- | --- |
 | `DONE` | start review gates |
-| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `PLAN.md` |
+| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `Harness/tasks/<task-id>/PROGRESS.md` |
 | `NEEDS_CONTEXT` | provide only missing context and re-dispatch |
 | `BLOCKED` | change something: add context, split task, upgrade reasoning, use debugger, or ask user |
 
@@ -153,14 +171,14 @@ Never retry the same failed prompt unchanged.
 ## Failure Recovery
 
 - First failed verification: record evidence, dispatch debugger with the smallest reproduced failure.
-- Second same-class failure: narrow scope, update `PLAN.md#Heartbeat`, and add a reviewer before another fix.
+- Second same-class failure: narrow scope, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`, and add a reviewer before another fix.
 - Third same-class failure: stop blind fixes. Present evidence-backed options to the user.
 
 The recovery loop must preserve the same evidence standard as the main workflow: real commands, real browser/API checks when applicable, and recorded logs or artifacts.
 
 ## Synthesis Output
 
-After subagents return, the controller writes one synthesis into `Harness/PLAN.md`:
+After subagents return, the controller writes one synthesis into `Harness/tasks/<task-id>/PLAN.md`:
 
 ```text
 Agents used:

package/templates/common/docs/research/README.md

@@ -6,7 +6,7 @@ Purpose: guide agent research. Record conclusions in [research-results.md](resea
 
 Use this before PRD, stack choice, external API use, public dependency choice, pricing/legal/security assumptions, or any fact likely to change.
 
-Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/PLAN.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PROGRESS.md`.
 
 ## Research Agent
 
@@ -21,7 +21,7 @@ Built-in agents:
 - `.claude/agents/researcher.md`: product, market, open-source, dependency, pricing, policy, and ecosystem research.
 - `.claude/agents/docs-researcher.md`: official docs, API, SDK, config, limits, errors, and examples verification.
 
-For multi-agent research plus build work, create the dispatch table in `Harness/PLAN.md` and follow `Harness/dispatch.md`.
+For multi-agent research plus build work, create the dispatch table in `Harness/tasks/<task-id>/PLAN.md` and follow `Harness/dispatch.md`.
 
 Research Agent input:
 
@@ -104,7 +104,7 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Write Target
 
-- Research process, queries, and limitations: this file or `Harness/PLAN.md`.
+- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PROGRESS.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
 - Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.

package/templates/common/docs/tasks/_template/ARTIFACTS.md

@@ -0,0 +1,3 @@
+# {{TASK_ID}} — Artifacts
+
+Optional: screenshots, logs, API responses, links. Create only when evidence is too large for this task's PLAN.md verification table.

package/templates/common/docs/tasks/_template/NOTES.md

@@ -0,0 +1,3 @@
+# {{TASK_ID}} — Notes
+
+Optional: exploration notes, design alternatives, research leads. Create only when notes are too long for this task's PLAN.md.

package/templates/common/docs/tasks/_template/PLAN.md

@@ -0,0 +1,40 @@
+# {{TASK_ID}} — PLAN
+
+Task-level implementation plan and evidence. Main agent writes after second planning; implementer reads before coding.
+
+## Goal
+
+## Acceptance Criteria
+
+- [ ]
+
+## Scope
+
+Allowed write set:
+- 
+
+Forbidden:
+- 
+
+## Loaded Context
+
+- 
+
+## Subagent Dispatch
+
+| Agent | Mode | Read Set | Write Set | Status |
+|-------|------|----------|-----------|--------|
+
+## Subagent Synthesis
+
+Agents used:
+Findings accepted:
+Findings rejected:
+Conflicts:
+Decisions:
+Residual risk:
+
+## Verification
+
+| Check | Result | Notes |
+|-------|--------|-------|

package/templates/common/docs/tasks/_template/PROGRESS.md

@@ -0,0 +1,29 @@
+# {{TASK_ID}} — PROGRESS
+
+Task-level progress and heartbeat. Main agent updates; subagents read only.
+
+## Current Goal
+
+## Phase
+
+Current: Intake
+
+## Heartbeat
+
+Last beat:
+Current phase: Intake
+Current blocker: none
+Next beat trigger:
+Failure count: 0
+Recovery action: none
+
+## Tasks
+
+| # | Task | Owner | Verify | Status |
+|---|------|-------|--------|--------|
+| 1 | Define goal and scope | main agent | recorded above | Pending |
+
+## Agent Handoffs
+
+| Agent | Role | Context Pack | Result |
+|-------|------|-------------|--------|

package/templates/common/scripts/validate-harness.mjs

@@ -25,6 +25,8 @@ const commonAgents = [
   'debugger',
   'reviewer',
   'verifier',
+  'memory-master',
+  'context-master',
 ];
 
 const commonSkills = [
@@ -34,6 +36,8 @@ const commonSkills = [
   'harness-context',
   'harness-build-loop',
   'wf-mode',
+  'wf-update',
+  'wf-max',
   'subagent-orchestrator',
   'readme-optimizer',
 ];
@@ -50,13 +54,16 @@ const required = [
   'README.md',
   'Harness/MEMORY.md',
   'Harness/WF.md',
+  'Harness/WF-MAX.md',
   ...memoryFiles,
   '.claude/settings.json',
   '.claude/commands/wf.md',
+  '.claude/commands/wf-max.md',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
   ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
   'Harness/README.md',
+  'Harness/PROGRESS.md',
   'Harness/PLAN.md',
   'Harness/lifecycle.md',
   'Harness/subagents.md',
@@ -72,10 +79,13 @@ const required = [
   'Harness/research/research-results.md',
   'Harness/research/PRD.md',
   'Harness/domain/ports.md',
+  '.claude/skills/wf-update/SKILL.md',
+  '.claude/commands/update.md',
+  'Harness/.harness-version',
 ];
 
 const projectFacts = [
-  'Harness/PLAN.md',
+  'Harness/PROGRESS.md',
   'Harness/research/PRD.md',
   'Harness/research/research-results.md',
   'Harness/architecture.md',
@@ -93,6 +103,8 @@ const contextPacks = [
   'Reviewer:',
   'Debugger:',
   'Verifier:',
+  'Memory Master:',
+  'Context Master:',
 ];
 
 const durableCommunicationDocs = [
@@ -181,6 +193,37 @@ for (const rel of required) {
   }
 }
 
+// Task capsule template files
+const taskTemplateDir = path.join(root, 'Harness', 'tasks', '_template');
+if (!fs.existsSync(taskTemplateDir)) {
+  errors.push('missing directory: Harness/tasks/_template/');
+} else {
+  for (const f of ['PROGRESS.md', 'PLAN.md']) {
+    if (!fs.existsSync(path.join(taskTemplateDir, f))) {
+      errors.push(`missing task template file: Harness/tasks/_template/${f}`);
+    }
+  }
+}
+
+// Cross-reference: DONE files in task PLAN.md must exist on disk
+const taskDirs = fs.existsSync(path.join(root, 'Harness', 'tasks'))
+  ? fs.readdirSync(path.join(root, 'Harness', 'tasks'), { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== '_template')
+      .map(e => e.name)
+  : [];
+for (const taskDir of taskDirs) {
+  const planPath = `Harness/tasks/${taskDir}/PLAN.md`;
+  const planText = read(planPath);
+  if (!planText) continue;
+  const donePattern = /`([^`]+\.(?:md|mjs|js|ts|json|html|css))`[^\n]*DONE/gi;
+  for (const match of planText.matchAll(donePattern)) {
+    const claimedFile = match[1];
+    if (!fs.existsSync(path.join(root, claimedFile))) {
+      errors.push(`${planPath} claims '${claimedFile}' is DONE but file does not exist`);
+    }
+  }
+}
+
 if (fs.existsSync(path.join(root, 'Harness/research/scaffolds.md'))) {
   errors.push('legacy research file should be renamed: Harness/research/scaffolds.md -> Harness/research/research-results.md');
 }
@@ -218,17 +261,26 @@ requireText('CLAUDE.md', 'Harness/MEMORY.md` is the memory/resource router', 'me
 requireText('CLAUDE.md', 'Harness/README.md#Load By Task', 'Harness task router');
 requireText('CLAUDE.md', 'Harness/SETUP.md` exists, follow it before normal project work', 'setup bootstrap contract');
 requireText('CLAUDE.md', 'subagent-orchestrator` and `Harness/subagents.md', 'subagent orchestrator entry trigger');
+requireText('CLAUDE.md', 'Harness/PROGRESS.md` is the global task index', 'PROGRESS global task index');
+requireText('CLAUDE.md', 'Harness/tasks/', 'task capsule directory reference');
+requireText('CLAUDE.md', 'Subagents are readers and reporters', 'subagent state committer rule');
 for (const heading of ['## 2. Think Before Coding', '## 3. Simplicity First', '## 4. Surgical Changes', '## 5. Goal-Driven Execution']) {
   requireText('CLAUDE.md', heading, `Karpathy-style rule heading: ${heading}`);
 }
 
+// Root PROGRESS.md structure check
+const progress = read('Harness/PROGRESS.md');
+if (progress) {
+  for (const heading of ['## Active Task', '## Task Index', '## Cross-Task Decisions']) {
+    if (!progress.includes(heading)) errors.push(`Harness/PROGRESS.md missing heading: ${heading}`);
+  }
+}
+
+// Legacy PLAN.md deprecation check (it exists as stub, no longer requires active task headings)
 const plan = read('Harness/PLAN.md');
 if (plan) {
-  for (const heading of ['## Current Goal', '## Phase', '## Heartbeat', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Subagent Synthesis', '## Verification']) {
-    if (!plan.includes(heading)) errors.push(`Harness/PLAN.md missing heading: ${heading}`);
-  }
-  for (const marker of ['Next beat trigger', 'Recovery action']) {
-    if (!plan.includes(marker)) errors.push(`Harness/PLAN.md missing heartbeat marker: ${marker}`);
+  if (!plan.includes('DEPRECATED')) {
+    errors.push('Harness/PLAN.md should be a deprecation stub; see Harness/PROGRESS.md');
   }
 }
 
@@ -349,7 +401,7 @@ for (const agent of commonAgents) {
 }
 
 requireText('Harness/extension.md', 'Skills should extend the harness');
-requireText('Harness/agent-workflow.md', 'Harness/PLAN.md');
+requireText('Harness/agent-workflow.md', 'Harness/tasks/<task-id>/PROGRESS.md');
 requireText('Harness/research/README.md', 'research-results.md');
 requireText('Harness/WF.md', 'Ralph-style harness loop', 'WF loop description');
 requireText('Harness/WF.md', 'Heartbeat Protocol', 'heartbeat protocol');
@@ -357,6 +409,7 @@ requireText('Harness/WF.md', 'WF mode requires multi-subagent orchestration by d
 requireText('Harness/WF.md', 'Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents', 'explicit WF/WK subagent minimum');
 requireText('Harness/WF.md', '.claude/agents/', 'WF built-in agent roster path');
 requireText('Harness/WF.md', '7:3 collaboration bias', 'WF collaboration bias');
+requireText('Harness/WF.md', 'Harness/tasks/', 'WF task directory reference');
 requireText('Harness/README.md', '`/wf`, `wf mode`, `workflow mode`, or `wk mode`', 'WF/WK router aliases');
 requireText('Harness/README.md', 'explicit WF/WK loads subagent docs immediately', 'explicit WF/WK router output');
 requireText('.claude/skills/harness-router/SKILL.md', '`/wf`, `wf mode`, `workflow mode`, `wk mode`', 'harness-router WF/WK aliases');
@@ -384,6 +437,16 @@ requireText('Harness/architecture.md', '## 2. Interface Decoupling', 'architectu
 requireText('Harness/architecture.md', '## 3. State Design', 'architecture state design');
 requireText('Harness/architecture.md', 'Avoid speculative abstraction', 'anti-overengineering architecture rule');
 requireText('CLAUDE.md', 'Use explicit interfaces or state models only when they protect a real boundary', 'CLAUDE interface/state simplicity rule');
+requireText('CLAUDE.md', '/wf update', 'wf update startup instruction');
+requireText('Harness/README.md', 'Need harness update', 'update routing row');
+requireText('Harness/WF-MAX.md', 'write-set coloring', 'WF-MAX coloring algorithm');
+requireText('Harness/WF-MAX.md', 'wave dispatch', 'WF-MAX wave dispatch');
+requireText('Harness/README.md', '/wf max', 'wf max router alias');
+requireText('Harness/README.md', 'WF-MAX.md', 'WF-MAX router reference');
+requireText('Harness/subagents.md', 'Max parallelism', 'subagents max parallelism row');
+requireText('Harness/dispatch.md', 'Concurrency group', 'dispatch concurrency group field');
+requireText('Harness/dispatch.md', 'File claim', 'dispatch file claim field');
+requireText('CLAUDE.md', '/wf max', 'wf max startup instruction');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);