create-harness-vibe-coding 0.8.6 → 0.8.8

package/templates/common/Harness/WF.md

@@ -34,41 +34,51 @@ Two distinct trigger classes; do not conflate them:
 - Explicit invocation (`/wf`, `$wf`, `wf mode`, `workflow mode`, `wk mode`,
   `/wf-max`, `$wf-max`): role fan-out is mandatory and unconditional. File
   count, task size, and subsystem count are irrelevant. A one-file task invoked
-  with WF still uses at least three role passes before the second plan.
+  with WF still schedules the complete role chain before closeout.
 - Auto-triggering decides whether the harness enters WF mode on its own. It can
   only escalate into WF, never downgrade an explicit command out of WF.
 
-## Multi-Subagent Requirement
-
-WF mode requires multi-subagent orchestration by default.
-
-Normative rule: Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at least 3 distinct role passes before second planning.
-
-- Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at
-  least 3 distinct role passes before second planning. Use real subagents when
-  the runtime supports them; otherwise emulate those roles as bounded passes and
-  record the fallback.
+## Complete Role Chain Requirement
+
+WF mode requires the complete role chain by default.
+
+Normative rule: Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST cover every mandatory role class before closeout: Plan, Research, Architecture, Test, Implement, Independent Validation, Cross-Review, Reflect, and Final Acceptance.
+
+- Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST schedule
+  the complete role chain at intake. Use real subagents when the runtime
+  supports them; otherwise emulate those roles as bounded passes and record the
+  fallback.
+- Mandatory role classes:
+  - Plan: `planner`
+  - Research: `researcher` or `docs-researcher`; use both when local and external/current facts matter
+  - Architecture: `architect`
+  - Test: `test-writer`
+  - Implement: `implementer` and `debugger` when needed
+  - Independent Validation: `verifier` records AC-mapped evidence before cross-review
+  - Cross-Review: at least two independent review lenses after implementation
+  - Reflect: `reflector`
+  - Final Acceptance: controller accepts only after cross-review passes and `reflector` returns PASS
 - Runtime mapping:
   - Claude Code: prefer subagents from `.claude/agents/`.
   - Codex: prefer the available Codex subagent surface; if unavailable, use
     bounded passes with the same roles and evidence contract.
 - Collaboration decision tree (replaces the old "7:3" heuristic with concrete
   conditions):
-  - Explicit WF/WK mode -> always multi-role, no exceptions.
-  - 3+ files changed -> multi-role at minimum: planner, implementer, reviewer.
-  - Cross-layer change -> architect plus implementers plus reviewer.
-  - Uncertain scope or approach -> planner plus researcher plus architect.
+  - Explicit WF/WK mode -> complete role chain, no exceptions.
+  - 3+ files changed -> complete role chain.
+  - Cross-layer change -> complete role chain plus separate architecture review.
+  - Uncertain scope or approach -> complete role chain with both researcher and architect passes.
   - 1-2 files, well-understood, not in WF mode -> solo is acceptable.
   - Repeated failure on the same task -> stop solo and switch to multi-role.
-- Default initial fan-out: `planner`, `researcher` or `docs-researcher`, and
-  `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when
-  the phase needs them.
+- Default `/wf` startup records the full chain in the task plan. Dependency-bound
+  roles run when their phase is ready; they are not optional.
 
 ## Exploration Gate
 
 - [ ] Controller has not read source files directly; only Harness docs, root
   agent entries, and subagent or bounded-pass returns.
-- [ ] At least 3 distinct role types, each with one specific question.
+- [ ] Complete role chain is scheduled in the task plan.
+- [ ] Plan, Research, and Architecture role passes each have one specific question before second planning.
 - [ ] Role passes were dispatched together when the runtime supports parallel
   dispatch.
 - [ ] Agent count is at least `max(3, ceil(estimated_dirs / 2))`; estimate from
@@ -93,8 +103,9 @@ Intake
 -> test-writer
 -> implementer
 -> independent validator
--> reviewers
--> if failed: debugger -> review -> e2e/API validation -> loop
+-> cross-review: spec/AC reviewer + code/architecture/test reviewer
+-> reflector
+-> if failed: debugger -> verifier -> cross-review -> reflector -> loop
 -> memory closeout with evidence
 ```
 
@@ -166,9 +177,12 @@ The second plan must pass:
 
 1. `test-writer` defines failing tests or written manual checks from AC IDs and contracts first.
 2. `implementer` changes only the declared write set and may not edit truth files without Change Request.
-3. `verifier` or independent validator runs AC-mapped checks against running behavior and records an acceptance result matrix.
-4. At least one `reviewer` checks diff, architecture, risks, missing tests, and AC traceability.
-5. For cross-layer or risky work, run separate reviewers for spec/AC compliance, architecture, and test adequacy.
+3. `verifier` or independent validator runs AC-mapped checks against running behavior and records an evidence matrix before cross-review.
+4. Cross-review is mandatory: at least two independent review lenses must pass before acceptance.
+   - Spec/AC review checks request, scope, contracts, and non-goals.
+   - Code/architecture/test review checks implementation risk, maintainability, security, and verification adequacy.
+5. `reflector` reads verifier evidence and reviewer findings, resolves contradictions with the controller, and returns PASS before final acceptance.
+6. For cross-layer or risky work, run separate reviewers for spec/AC compliance, architecture, security, and test adequacy.
 
 ## Browser And API Evidence
 
@@ -197,9 +211,10 @@ If verification fails:
 2. Dispatch `debugger` with the failed AC ID, failing command, error output,
    trace/screenshot/network evidence, and smallest relevant files.
 3. Classify the failure layer using [DEBUG_PROTOCOL.md](DEBUG_PROTOCOL.md), then fix the smallest reproduced failure.
-4. Run reviewer again.
-5. Run verifier again.
-6. Repeat until verified or blocked by missing user input/external state.
+4. Run verifier again and record fresh AC-mapped evidence.
+5. Run cross-review again.
+6. Run reflector again.
+7. Repeat until verified or blocked by missing user input/external state.
 
 Before asking the user after repeated failures, run the context-master then
 memory-master learning cycle or use `wf-learn`.
@@ -207,6 +222,8 @@ memory-master learning cycle or use `wf-learn`.
 ## Heartbeat Protocol
 
 Heartbeat is a lightweight recovery protocol, not a background daemon.
+Keep heartbeat entries to one or two lines: phase, blocker/failure, next action,
+and evidence pointer. Do not paste command logs or subagent transcripts.
 
 Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`:
 
@@ -224,9 +241,10 @@ equivalent bounded pass to append a compression suggestion to the task heartbeat
 
 Close only when:
 
-- PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, and REVIEW-GATE are satisfied
+- PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, REVIEW-GATE, and REFLECT-GATE are satisfied
 - acceptance criteria are satisfied and reported by AC ID
-- reviewer has no unresolved critical/high findings
+- cross-review has passed with no unresolved critical/high findings
+- reflector verdict is PASS
 - test/API/browser evidence is recorded
 - affected Harness docs are synced
 - context-master has analyzed the session and extracted durable knowledge

package/templates/common/Harness/agent-workflow.md

@@ -1,5 +1,5 @@
-# Agent Workflow
-
+# Agent Workflow
+
 Use when implementing, reviewing, debugging, or coordinating subagents.
 
 This workflow is acceptance-driven. PRD-derived Acceptance Criteria are the
@@ -8,33 +8,47 @@ must trace to AC IDs. Load [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) for
 gate rules, [TDD-GUIDE.md](TDD-GUIDE.md) for AC-linked RED tests,
 [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) for UI/API/browser evidence, and
 [AGENT_ISOLATION.md](AGENT_ISOLATION.md) before role splits.
-
-## ReAct Loop
-
-```text
-Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/tasks/<task-id>/PROGRESS.md
-```
-
-If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [subagents.md](subagents.md) and [dispatch.md](dispatch.md).
-
-## Feature Packet
-
-Every PRD scope item must be covered by AC IDs and a task plan at `Harness/tasks/<task-id>/PLAN.md`
-created from `Harness/tasks/_template/PLAN.md` (the primary work tracking system).
-**Cohesion rule**: if multiple PRD scope items share the same write set, the same
-test/verification path, and the same review boundary, group them into a single
-feature doc. The PRD owns scope decomposition; the feature doc owns the
-implementation unit. The number of feature docs should reflect the number of
-distinguishable implementation units, not the number of PRD checkboxes.
-
-**Minimum bar**: a task plan is required when the implementation touches more than one
-file or changes user-visible behavior. Record the plan in `Harness/tasks/<task-id>/PLAN.md`.
-For single-file fixes with no behavior change, a brief note in `PROGRESS.md` is enough.
-
-**New vs iterate**: if a PRD scope item overlaps with an existing task, reopen the existing
-task capsule and append to its `PROGRESS.md`. Only create a new task capsule when the
-scope is substantially different. When unsure, ask.
-
+
+## ReAct Loop
+
+```text
+Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/tasks/<task-id>/PROGRESS.md
+```
+
+If context grows, load [context-loading.md](context-loading.md) and split the
+work. If more than one agent is useful, load [subagents.md](subagents.md) and
+[dispatch.md](dispatch.md).
+
+## Feature Packet
+
+Every PRD scope item must be covered by AC IDs and a task plan at
+`Harness/tasks/<task-id>/PLAN.md` created from
+`Harness/tasks/_template/PLAN.md` (the primary work tracking system).
+
+**Cohesion rule**: if multiple PRD scope items share the same write set, the
+same test/verification path, and the same review boundary, group them into a
+single feature doc. The PRD owns scope decomposition; the feature doc owns the
+implementation unit.
+
+**Minimum bar**: a task plan is required when the implementation touches more
+than one file or changes user-visible behavior. Record the plan in
+`Harness/tasks/<task-id>/PLAN.md`. For single-file fixes with no behavior
+change, a brief note in `PROGRESS.md` is enough.
+
+Use the compact task template by default. `PLAN.md` owns goal, decisions,
+scope/write set, agents, verification intent, and risks. `PROGRESS.md` owns
+status/next/blocker, completed tasks, changed files, verification evidence, and
+notes. Expand sections only when they change an implementation or review
+decision.
+
+**AC record size**: default to 1-3 concise ACs. Use full UI/API contracts and an
+AC-by-AC validation matrix only for browser-visible, API/integration,
+security/data-loss, cross-module, or other high-risk behavior.
+
+**New vs iterate**: if a PRD scope item overlaps with an existing task, reopen
+the existing task capsule and append to its `PROGRESS.md`. Only create a new
+task capsule when the scope is substantially different. When unsure, ask.
+
 ## Acceptance-Driven Build Loop
 
 ```text
@@ -45,7 +59,9 @@ Mini PRD
 -> failing test or manual check
 -> minimal implementation
 -> independent validation
--> review
+-> cross-review (spec/AC + code/architecture/test)
+-> reflector PASS
+-> final acceptance
 -> debug if needed
 -> docs sync
 -> memory
@@ -61,27 +77,31 @@ Rules:
 - Frontend-backend behavior must include network/API assertions against the contract.
 - Implementer cannot modify PRD, acceptance criteria, UI/API contracts, test plan, or validation report unless a Change Request is recorded.
 - Validator must be independent from implementer and must produce an AC-by-AC result matrix.
-
-## Subagent Use
-
-Use subagents when a task needs broad reading, parallel work, cross-layer changes, independent review, or isolated debugging. Follow [subagents.md](subagents.md) for controller-led orchestration and [dispatch.md](dispatch.md) for the dispatch table.
-
-Before spawn, define:
-
-- role
-- task
-- mode
-- read boundary
-- write boundary
-- dependency
-- injected docs from [context-loading.md](context-loading.md)
-- return format
-
-Rules:
-
-- Explorer Pass, Reviewer, and Verifier are read-only.
-- Researcher and Docs Researcher are read-only unless explicitly asked to return a docs patch.
-- Planner and Architect are read-only unless explicitly asked to return a docs patch.
+- Cross-review and reflector PASS are required before final acceptance.
+
+## Subagent Use
+
+Use subagents when a task needs broad reading, parallel work, cross-layer
+changes, independent review, or isolated debugging. Follow
+[subagents.md](subagents.md) for controller-led orchestration and
+[dispatch.md](dispatch.md) for the dispatch table.
+
+Before spawn, define:
+
+- role
+- task
+- mode
+- read boundary
+- write boundary
+- dependency
+- injected docs from [context-loading.md](context-loading.md)
+- return format
+
+Rules:
+
+- Explorer Pass, Reviewer, Verifier, and Reflector are read-only.
+- Researcher and Docs Researcher are read-only unless explicitly asked to return a docs patch.
+- Planner and Architect are read-only unless explicitly asked to return a docs patch.
 - Test Writer writes tests before Implementer writes production code.
 - Implementer only writes inside its declared write set.
 - Implementer forbidden set includes PRD, acceptance criteria, UI/API contracts, test plan, and validation report by default.
@@ -89,31 +109,43 @@ Rules:
 - Debugger fixes the smallest failing path, not adjacent design.
 - Debugger receives failed AC IDs, evidence, and failing layer hypothesis before editing.
 - Main agent integrates summaries, resolves conflicts, and runs final verification.
-
-## Parallel Dispatch
-
-Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). In `/wf max`, the CEO/Manager/Worker hierarchy in [WF-MAX.md](WF-MAX.md) overrides this limit entirely with wave-based parallel dispatch. Prefer parallel read-only work first, then serial writes.
-
-Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
-
-## Conflict Rule
-
-If PRD, acceptance criteria, UI/API contracts, task PLAN.md, architecture, ports, tests, or code disagree:
-
-1. stop implementation
-2. record the conflict in `Harness/tasks/<task-id>/PROGRESS.md` or the feature doc
-3. choose the smallest reversible decision
-4. ask the maintainer when user-visible behavior or security is affected
-
-## Completion Gate
-
-Close only when:
-
+
+## Parallel Dispatch
+
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work.
+
+**Agent count by mode:**
+| Mode | Agent Count Rule | Source |
+|------|-----------------|--------|
+| Default (non-WF) | up to 3 active agents by default | This file |
+| `/wf` | complete role chain mandatory before closeout | [WF.md](WF.md) |
+| `/wf max` | complete WF role chain plus maximum useful fan-out | [WF-MAX.md](WF-MAX.md) |
+
+Prefer parallel read-only work first, then serial writes.
+
+Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
+
+## Conflict Rule
+
+If PRD, acceptance criteria, UI/API contracts, task PLAN.md, architecture,
+ports, tests, or code disagree:
+
+1. stop implementation
+2. record the conflict in `Harness/tasks/<task-id>/PROGRESS.md` or the feature doc
+3. choose the smallest reversible decision
+4. ask the maintainer when user-visible behavior or security is affected
+
+## Completion Gate
+
+Close only when:
+
 - acceptance criteria are satisfied by AC ID
 - validation result matrix exists for user-visible behavior
 - verification evidence is recorded
-- architecture docs are synced if affected
-- no unresolved critical/high review findings remain
-- any optimistic UI mutation has a declared and verified rollback path
-- any file declared as DONE in PLAN.md or PROGRESS.md exists on disk (chat output is not durable evidence)
-- `Harness/tasks/<task-id>/PROGRESS.md` states the final status or next iteration
+- cross-review has passed with no unresolved critical/high findings
+- reflector verdict is PASS
+- architecture docs are synced if affected
+- no unresolved critical/high review findings remain
+- any optimistic UI mutation has a declared and verified rollback path
+- any file declared as DONE in PLAN.md or PROGRESS.md exists on disk (chat output is not durable evidence)
+- `Harness/tasks/<task-id>/PROGRESS.md` states the final status or next iteration

package/templates/common/Harness/architecture.md

@@ -1,126 +1,126 @@
-# Harness Architecture - create-harness-vibe-coding
-
-> **Responsibility**: Define the repository structure and scaffold generation boundaries.
-> **Does NOT cover**: Generated target-project business architecture.
-
----
-
-## 1. Layering Rules
-
-```text
-bin/
-  CLI executable shim. Calls src/index.js.
-
-src/
-  CLI orchestration and scaffold generation logic.
-  May read templates/ and write the chosen target directory.
-
-templates/
-  Source of generated scaffold assets.
-  Must stay declarative: markdown, skill files, agent files, scripts, and optional workflow docs.
-
-Harness/ and .claude/
-  Dogfood runtime for this repository's own agent work.
-  Must not be treated as package source unless intentionally copied into templates/.
-
-tests/
-  Node test suite for CLI behavior, generator behavior, package contents, and generated harness validation.
-```
-
-Hard constraints:
-
-- `templates/common/**` and `templates/optional/**` are the source of generated output.
-- Root `Harness/**` is this repository's operating harness; changing it does not change generated projects.
-- Generated output paths are normalized by `harnessDest()` in `src/generator.js`.
-- Existing-project safety is owned by conflict planning in `src/generator.js`, not by template prose alone.
-- Package publication is constrained by `package.json#files`; root dogfood files are not package contents.
-
-## 2. Interface Decoupling
-
-Use interfaces and module boundaries to protect real seams in the generator, not to decorate straightforward code.
-
-- `src/index.js` owns CLI/user interaction; `src/generator.js` owns planning and file writes.
-- Template files are declarative inputs; source code should not depend on root dogfood `Harness/**`.
-- Optional catalog structure is the extension contract for presets and optional skills.
-- Avoid speculative abstraction: do not add plugin systems, generic runners, extra config layers, or service containers until a real second use or testability boundary exists.
-- When a boundary is real, express it with a small data contract and test it through generated output behavior.
-
-## 3. State Design
-
-State in this repo should be explicit, serializable, and owned by one layer.
-
-- Generator plan state is computed in memory and returned as `plan`/`summary`; file writes consume that plan instead of re-deciding conflicts.
-- Filesystem state is authoritative only through existence/type checks and write results.
-- Optional selection state comes from CLI flags plus `templates/optional/catalog.json`; do not duplicate it in template prose.
-- Release state lives in `package.json`, npm, git tags, and GitHub; document commands in `README.md`, not `CLAUDE.md`.
-- Long-running agent work records resumable status in `Harness/tasks/<task-id>/PLAN.md#Heartbeat`.
-
-## 4. Core Components
-
-### 4.1 CLI Entry
-
-- **Location**: `bin/create-harness-vibe-coding.js`, `src/index.js`
-- **Responsibility**: Parse flags, handle interactive/non-interactive modes, print plans/results, and call the generator.
-- **Does NOT handle**: Template walking, conflict classification, or file writing internals.
-
-### 4.2 Prompt Layer
-
-- **Location**: `src/prompts.js`
-- **Responsibility**: Ask basic interactive npx questions: project name and target directory.
-- **Does NOT handle**: Agent-link install intake. That matrix is read by coding agents from `README.md` and `Harness/SETUP.md`.
-
-### 4.3 Generator Core
-
-- **Location**: `src/generator.js`
+# Harness Architecture - create-harness-vibe-coding
+
+> **Responsibility**: Define the repository structure and scaffold generation boundaries.
+> **Does NOT cover**: Generated target-project business architecture.
+
+---
+
+## 1. Layering Rules
+
+```text
+bin/
+  CLI executable shim. Calls src/index.js.
+
+src/
+  CLI orchestration and scaffold generation logic.
+  May read templates/ and write the chosen target directory.
+
+templates/
+  Source of generated scaffold assets.
+  Must stay declarative: markdown, skill files, agent files, scripts, and optional workflow docs.
+
+Harness/ and .claude/
+  Dogfood runtime for this repository's own agent work.
+  Must not be treated as package source unless intentionally copied into templates/.
+
+tests/
+  Node test suite for CLI behavior, generator behavior, package contents, and generated harness validation.
+```
+
+Hard constraints:
+
+- `templates/common/**` and `templates/optional/**` are the source of generated output.
+- Root `Harness/**` is this repository's operating harness; changing it does not change generated projects.
+- Generated output paths are normalized by `harnessDest()` in `src/generator.js`.
+- Existing-project safety is owned by conflict planning in `src/generator.js`, not by template prose alone.
+- Package publication is constrained by `package.json#files`; root dogfood files are not package contents.
+
+## 2. Interface Decoupling
+
+Use interfaces and module boundaries to protect real seams in the generator, not to decorate straightforward code.
+
+- `src/index.js` owns CLI/user interaction; `src/generator.js` owns planning and file writes.
+- Template files are declarative inputs; source code should not depend on root dogfood `Harness/**`.
+- Optional catalog structure is the extension contract for presets and optional skills.
+- Avoid speculative abstraction: do not add plugin systems, generic runners, extra config layers, or service containers until a real second use or testability boundary exists.
+- When a boundary is real, express it with a small data contract and test it through generated output behavior.
+
+## 3. State Design
+
+State in this repo should be explicit, serializable, and owned by one layer.
+
+- Generator plan state is computed in memory and returned as `plan`/`summary`; file writes consume that plan instead of re-deciding conflicts.
+- Filesystem state is authoritative only through existence/type checks and write results.
+- Optional selection state comes from CLI flags plus `templates/optional/catalog.json`; do not duplicate it in template prose.
+- Release state lives in `package.json`, npm, git tags, and GitHub; document commands in `README.md`, not `CLAUDE.md`.
+- Long-running agent work records resumable status in `Harness/tasks/<task-id>/PLAN.md#Heartbeat`.
+
+## 4. Core Components
+
+### 4.1 CLI Entry
+
+- **Location**: `bin/create-harness-vibe-coding.js`, `src/index.js`
+- **Responsibility**: Parse flags, handle interactive/non-interactive modes, print plans/results, and call the generator.
+- **Does NOT handle**: Template walking, conflict classification, or file writing internals.
+
+### 4.2 Prompt Layer
+
+- **Location**: `src/prompts.js`
+- **Responsibility**: Ask basic interactive npx questions: project name and target directory.
+- **Does NOT handle**: Agent-link install intake. That matrix is read by coding agents from `README.md` and `Harness/SETUP.md`.
+
+### 4.3 Generator Core
+
+- **Location**: `src/generator.js`
 - **Responsibility**: Resolve optional selections, keep Harness-owned template paths under `Harness/**`, detect conflicts, render templates, register optional workflows, and write files.
-- **Critical functions**:
+- **Critical functions**:
   - `harnessDest()` keeps root entry files at root and Harness-owned files under generated root `Harness/*`.
-  - `createPlan()` and `addFileActions()` classify directories and file actions before writes.
-  - `registerOptionalContent()` updates generated router/memory docs when optional workflows are selected.
-
-### 4.4 Template Assets
-
-- **Location**: `templates/common/**`, `templates/optional/**`
-- **Responsibility**: Define generated `CLAUDE.md`, `AGENTS.md`, `README.md`, `Harness/**`, `.claude/**`, optional skills, and optional workflows.
-- **Does NOT handle**: Existing-project decisions. Templates state contracts; generator and agents apply them safely.
-
-### 4.5 Validator
-
-- **Source template**: `templates/common/scripts/validate-harness.mjs`
-- **Generated location**: `Harness/scripts/validate-harness.mjs`
-- **Responsibility**: Validate required scaffold files, skill/agent registrations, router invariants, optional workflow registrations, and strict project-fact placeholders.
-
-### 4.6 Dogfood Runtime
-
-- **Location**: root `Harness/**`, `.claude/**`, `CLAUDE.md`, `AGENTS.md`, `MEMORY.md`
-- **Responsibility**: Govern future AI-agent work in this repository.
-- **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
-
-## 5. Data Flow
-
-```text
-CLI args / prompts
--> src/index.js parse and display
--> src/generator.js resolve optional catalog
--> walk templates/common and selected templates/optional
--> harnessDest maps source paths to generated destinations
--> createPlan/addFileActions classify create/skip/backup/overwrite/conflict
--> renderTemplate substitutes projectName
--> registerOptionalContent updates generated Harness router/memory
--> write files or return dry-run/json plan
--> tests and generated validator verify behavior
-```
-
-## 6. Architectural Constraints
-
-- Do not add generated-output behavior by editing only root `Harness/`; edit `templates/common/**` or `templates/optional/**`.
-- Do not add user-facing CLI behavior without tests in `tests/cli-smoke.test.js` or `tests/generator.test.js`.
-- Do not add required generated files without updating `templates/common/scripts/validate-harness.mjs` and relevant tests.
-- Do not write Harness docs into generated `docs/`; `Harness/` is the generated root for harness-owned docs.
-- Do not make root `CLAUDE.md` a dumping ground for build commands, architecture, or release process.
-
-## 7. Known Follow-Up Risks
-
-- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
-- Some README tests assert exact prose and can be made more structural.
-- `subagent-orchestrator` routing priority should continue to be tightened in templates.
+  - `createPlan()` and `addFileActions()` classify directories and file actions before writes.
+  - `registerOptionalContent()` updates generated router/memory docs when optional workflows are selected.
+
+### 4.4 Template Assets
+
+- **Location**: `templates/common/**`, `templates/optional/**`
+- **Responsibility**: Define generated `CLAUDE.md`, `AGENTS.md`, `README.md`, `Harness/**`, `.claude/**`, optional skills, and optional workflows.
+- **Does NOT handle**: Existing-project decisions. Templates state contracts; generator and agents apply them safely.
+
+### 4.5 Validator
+
+- **Source template**: `templates/common/scripts/validate-harness.mjs`
+- **Generated location**: `Harness/scripts/validate-harness.mjs`
+- **Responsibility**: Validate required scaffold files, skill/agent registrations, router invariants, optional workflow registrations, and strict project-fact placeholders.
+
+### 4.6 Dogfood Runtime
+
+- **Location**: root `Harness/**`, `.claude/**`, `CLAUDE.md`, `AGENTS.md`, `MEMORY.md`
+- **Responsibility**: Govern future AI-agent work in this repository.
+- **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
+
+## 5. Data Flow
+
+```text
+CLI args / prompts
+-> src/index.js parse and display
+-> src/generator.js resolve optional catalog
+-> walk templates/common and selected templates/optional
+-> harnessDest maps source paths to generated destinations
+-> createPlan/addFileActions classify create/skip/backup/overwrite/conflict
+-> renderTemplate substitutes projectName
+-> registerOptionalContent updates generated Harness router/memory
+-> write files or return dry-run/json plan
+-> tests and generated validator verify behavior
+```
+
+## 6. Architectural Constraints
+
+- Do not add generated-output behavior by editing only root `Harness/`; edit `templates/common/**` or `templates/optional/**`.
+- Do not add user-facing CLI behavior without tests in `tests/cli-smoke.test.js` or `tests/generator.test.js`.
+- Do not add required generated files without updating `templates/common/scripts/validate-harness.mjs` and relevant tests.
+- Do not write Harness docs into generated `docs/`; `Harness/` is the generated root for harness-owned docs.
+- Do not make root `CLAUDE.md` a dumping ground for build commands, architecture, or release process.
+
+## 7. Known Follow-Up Risks
+
+- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
+- Some README tests assert exact prose and can be made more structural.
+- `subagent-orchestrator` routing priority should continue to be tightened in templates.