create-harness-vibe-coding 0.8.8 → 0.8.9

package/templates/common/Harness/TASK_ARCHIVE.md

@@ -0,0 +1,56 @@
+# TASK_ARCHIVE — Task Archive Mechanism
+
+Purpose: keep `Harness/tasks/` lean by archiving completed/abandoned tasks while preserving all evidence.
+
+## Archive Location
+
+Active tasks stay in `Harness/tasks/<task-id>/`.
+Archived tasks move to `Harness/tasks/_archive/YYYY/<task-id>/`.
+
+## What Is Never Archived
+
+- `Harness/tasks/_template/` — scaffold template, never moved.
+- `Harness/tasks/auto/` — WF-AUTO permanent state capsule, never moved unless explicitly allowed by WF-AUTO docs.
+- `Harness/tasks/_archive/` — the archive directory itself.
+- Active, blocked, in-progress, or needs-user-decision tasks.
+- Tasks whose STATE.json status is `active`, `blocked`, `in_progress`, `running`, `pending`, or `needs-user-decision`.
+
+## What May Be Archived
+
+Tasks whose STATE.json or PROGRESS.md status is: `complete`, `verified`, `archived`, `abandoned`, `obsolete`, `done`, `closed`, or `closeout`.
+
+The script reads STATE.json `status`/`phase` first, then falls back to the first `- Phase:`, `Phase:`, or `Current:` marker in the task's PROGRESS.md (first word wins). Ambiguous phases are never auto-archived.
+
+## Archive Process
+
+1. Verify the task is not active/blocked.
+2. Ensure `Harness/tasks/_archive/YYYY/` exists.
+3. Move `Harness/tasks/<task-id>/` → `Harness/tasks/_archive/YYYY/<task-id>/`.
+4. Update the moved STATE.json: `status` → `archived`, `phase` → `archived`.
+5. Update `Harness/tasks/_archive/INDEX.md`.
+6. Update `Harness/PROGRESS.md` Task Index — remove or annotate `(archived)`.
+
+## Retention
+
+- Archived tasks retain: PLAN, PROGRESS, STATE, ARTIFACTS, NOTES.
+- Do NOT delete historical evidence.
+- `Harness/PROGRESS.md` keeps the last 5 non-archived task entries in the Task Index.
+- When outer task capsules exceed 5 completed/abandoned/obsolete, archive the oldest.
+- The validator (`Harness/scripts/validate-harness.mjs`) warns when `Harness/tasks/` holds more than 5 outer task capsules (excluding `_archive`, `_template`, `auto`) and fails in `--strict` mode.
+
+## Script
+
+Use `Harness/scripts/archive-tasks.mjs`:
+- Default: dry-run
+- `--apply` to execute
+- `--keep 5` to set the non-archived task threshold
+- `--task <task-id>` to archive a specific task
+- `--json` for machine-readable output
+- `node Harness/scripts/archive-tasks.mjs --dry-run --json` must always run
+
+## Safety Rules
+
+- Windows path safe. Use `path.resolve()` before moving.
+- Confirm target is within `Harness/tasks/` before any move.
+- Do NOT recursively delete.
+- Tasks with `needs-user-decision` status are never auto-archived.

package/templates/common/Harness/WF-AUTO-SPARK.md

@@ -4,10 +4,12 @@
 
 ## Trigger
 
-- User explicitly invokes `/wf-auto-spark` or `$wf-auto-spark`
+- User explicitly invokes `/wf-auto-spark`, `$wf-auto-spark`, or `/skills wf-auto-spark`
 - Auto-degrade from `/wf-auto` when user can't clarify direction at Re-Anchor Gate
 - Auto-activate when adaptive internal coverage returns empty for 3+ consecutive cycles AND oracle also empty
 
+Note: Natural-language phrases like "spark mode", "external inspiration", "discover mode", "never stop" are NOT triggers — only explicit command tokens or documented auto-degrade/auto-activate paths from inside WF-AUTO enter WF-AUTO-SPARK.
+
 ## Core Philosophy
 
 **"Inspiration never runs dry, but direction must hold."**
@@ -18,20 +20,9 @@ But perpetual search without direction = drift. The **Roadmap** is the anchor.
 
 ## Inherited Execution Chain
 
-WF-AUTO-SPARK inherits WF-AUTO and WF constraints. External spark search replaces discovery only; it does not replace acceptance, implementation, review, verification, reflection, or evidence.
-
-Every accepted spark candidate must re-enter the same per-cycle chain:
-
-```text
-spark search -> Value Gate -> deviation check -> Mini PRD -> AC IDs
--> test/validation plan -> implementer -> verifier -> cross-review
--> reflector PASS -> evidence ledger -> next spark cycle
-```
+WF-AUTO-SPARK is a `/wf` variant layered on WF-AUTO: it inherits the WF-KERNEL contract via WF-AUTO and WF constraints, and does not define an independent heavy process. External spark search replaces discovery only; it does not replace acceptance, implementation, review, verification, reflection, or evidence.
 
-Spark searchers are read-only. Any implementation must use the dispatch packet
-from `Harness/dispatch.md` with explicit write set, forbidden truth files, AC
-IDs, and verification commands. A candidate with no verifier evidence or no
-reflector PASS is not accepted, even if the idea is valuable.
+Accepted spark candidates re-enter the standard W2-W5 gates per [WF-KERNEL.md](WF-KERNEL.md): implementer (one file_claim, ≤3 files, ≤50 lines), verifier, reviewer(s), reflector. Spark searchers are read-only. Any implementation must use the dispatch packet from `Harness/dispatch.md` with explicit write set, forbidden truth files, AC IDs, and verification commands. A candidate with no verifier evidence or no reflector PASS is not accepted, even if the idea is valuable.
 
 ## Startup: Roadmap Declaration
 

package/templates/common/Harness/WF-AUTO.md

@@ -2,9 +2,9 @@
 
 ## Trigger
 
-- Explicit: `/wf-auto`, `wf auto`, `auto mode`
-- The user wants continuous improvement that never stops on its own.
-- The user is done giving instructions and wants the system to self-direct.
+- Explicit: `/wf-auto`, `$wf-auto`, `/skills wf-auto`
+- The user must type one of these exact tokens to enter WF-AUTO.
+- These phrases are NOT triggers and must NOT auto-enter WF-AUTO: "auto mode", "never stop", "self-improve", "continuous optimize", "unbounded self-directed optimization", "keep going", or any natural-language description of perpetual work. Only explicit command tokens enter.
 
 ## Core Principle
 
@@ -12,7 +12,7 @@
 
 This fills the gap between:
 - `/wf` — task-bounded, stops on completion
-- `/wf-max` - task-bounded WF strict superset: complete role chain plus maximum parallelism
+- `/wf-max` - task-bounded `/wf` variant on the same WF kernel: maximum safe fan-out, WF-Max-Useful by default, WF-Max-Strict only on explicit strict request
 - `/wf-auto` — **unbounded, self-directed, perpetual improvement**
 
 ## Organization Model
@@ -39,7 +39,7 @@ does not edit production source. Implementation happens only through dispatched
 workers with explicit write sets, forbidden truth files, and verification
 commands.
 
-WF-AUTO does not inherit WF-MAX mandatory maximum fan-out unless `/wf-max` is
+WF-AUTO does not inherit WF-MAX fan-out modes (Useful or Strict) unless `/wf-max` is
 explicitly invoked or the selected change exceeds the auto cycle cap and
 escalates. Auto mode stays one accepted change per cycle.
 
@@ -260,53 +260,13 @@ Before W2, CEO writes a cycle Mini PRD:
 - UI/API/state contracts, if touched
 - Verification commands and evidence expected
 
-### W2: IMPLEMENT
+### W2-W5: IMPLEMENT → REVIEW → DEBUG → VERIFY
 
-Modeled on WF's build loop but scoped to ONE change:
+WF-AUTO inherits the standard WF-KERNEL write/review/fix/verify gates per cycle. Each accepted finding follows:
 
-1. CEO writes the change spec in `Harness/tasks/auto/PROGRESS.md` (cycle number, angle, finding, planned change, write set ≤3 files)
-2. CEO dispatches `implementer` with the change spec
-3. Implementer changes ONLY the declared write set
+[WF-KERNEL.md](WF-KERNEL.md) write gate (implementer, one file_claim per cycle, ≤3 files, ≤50 lines net), review gate (at least one independent reviewer; two for critical/security), fix gate (debugger on failure, max 2 fix attempts per cycle), and verify gate (test suite, real browser/API check, AC-by-AC evidence).
 
-CEO NEVER writes production code — this rule is inherited from WF-MAX (AP1: CEO-as-Worker).
-
-Acceptance-specific implementation rules:
-
-- Dispatch `test-writer` when AC IDs need new or updated tests.
-- Dispatch `implementer` with forbidden truth files: PRD, AC, UI/API contracts, test plan, and validation report.
-- Implementer may not rewrite ACs/contracts to make the implementation pass.
-
-### W3: REVIEW
-
-Two-gate review (from WF/subagents.md), then reflection:
-
-1. **Spec review**: Did the change address the finding without introducing extras?
-2. **Code-quality review**: Is the change correct, maintainable, safe?
-3. **Reflector gate**: Does review evidence, verifier evidence, and residual
-   risk support acceptance?
-
-At least one `reviewer` subagent. For critical/security findings, dispatch two independent reviewers.
-Do not record the cycle as accepted until `reflector` returns PASS.
-
-### W4: DEBUG (Recovery)
-
-If review or verification fails:
-1. `debugger` isolates the smallest failing path
-2. Fix and re-review (max 2 attempts per cycle)
-3. On 3rd failure: record the finding as "attempted, blocked" and move to next finding in W1
-4. Blocked findings are revisited after 3 cycles (the codebase may have changed enough to unblock)
-
-### W5: VERIFY
-
-- Run project test suite (or relevant subset)
-- For browser-visible changes: real browser check
-- For API changes: real request/response check
-- Record evidence in `Harness/tasks/auto/PROGRESS.md`
-- Final acceptance still requires cross-review and reflector PASS after
-  verification. A passing command alone is not acceptance.
-
-Validation must include AC-by-AC evidence in `Harness/tasks/auto/PROGRESS.md`,
-not only a generic pass/fail command result.
+CEO NEVER writes production code (per WF-KERNEL State Ownership). Implementer writes ONLY the declared write set. Production agents never write task state.
 
 ### RECORD
 
@@ -483,36 +443,13 @@ If a spark cycle's measured result is NEGLIGIBLE or REVERTED, increment `weakSpa
 
 ## CEO Constraints
 
-The CEO operates under the same strict tool boundary as WF-MAX:
-
-| CEO Has | CEO MUST NOT Use (on source code) |
-|---------|-----------------------------------|
-| Task (spawn agents) | Edit (on source files) |
-| Read (for scoping) | Write (on source files) |
-| Grep/Glob (for scoping) | MultiEdit (on source files) |
-| Write (to PROGRESS.md only) | Bash (except final verification) |
-
-**Exception**: CEO MAY write to `Harness/tasks/auto/PROGRESS.md` and `Harness/tasks/auto/PLAN.md` — these are task-tracking artifacts.
+CEO tool boundaries follow [WF-KERNEL.md](WF-KERNEL.md) State Ownership: CEO plans, dispatches, synthesizes, and writes ONLY the auto task capsule (`Harness/tasks/auto/PROGRESS.md`, `Harness/tasks/auto/PLAN.md`). CEO never writes production source code — all implementation is delegated to Workers.
 
 ## Anti-Pattern Catalog
 
-| # | Anti-Pattern | Symptom | Fix |
-|---|-------------|---------|-----|
-| AP1 | **CEO-as-Worker** | CEO writes production code | Delegate ALL implementation to Workers |
-| AP2 | **Premature stop** | CEO decides "good enough" before A-GATE | A-GATE is the ONLY stop. No exceptions. |
-| AP3 | **Shallow probe scan** | Probe returns "exhausted" after scanning 1-2 files | Require ≥80% relevant-surface coverage and record the coverage basis |
-| AP4 | **Batch implementation** | Multiple unrelated changes in one cycle | ONE finding per cycle. Split if needed. |
-| AP5 | **Wasteful probe scan** | Every catalog item is dispatched every cycle | Select probes by risk, relevance, evidence gap, novelty, and scan cost |
-| AP6 | **Skip review** | Implementation → verify without review | Review gate is mandatory, every cycle |
-| AP7 | **Scope creep** | A "simple fix" grows to 5+ files | Hard cap: ≤3 files per cycle. Split larger changes across cycles. |
-| AP8 | **False exhaustion** | Probe returns exhausted=true with low confidence | Require confidence and coverage ≥0.8 on exhausted. Re-dispatch only the uncertain probe. |
-| AP9 | **Stale probe strategy** | Same scan strategy every cycle → blind spots emerge | Rotate breadth, depth, change-first, failure-first, and contract-first scans |
-| AP10 | **Unjustified oracle** | CEO invokes another CLI on every empty scan | Invoke the oracle only for unresolved high-risk uncertainty or borderline coverage |
-| AP11 | **Spark as escape hatch** | Using spark to avoid the discipline of internal scan | Spark activates ONLY when internal + oracle are empty. It augments W0, not replaces it. |
-| AP12 | **Fake value scoring** | Inflating Value Gate scores to pass candidates through | CEO must justify each dimension score. Reviewer checks Value Gate scores as part of spec review. |
-| AP13 | **Shiny object syndrome** | Implementing every spark candidate without Value Gate filtering | All spark candidates MUST pass the Value Gate (≥18/25, no dimension <3). |
-| AP14 | **Inspiration theater** | Spark cycles without evidence ledger → no way to know if they worked | Evidence ledger is mandatory per cycle. Weak spark count tracked. |
-| AP15 | **Interrogation checkpoint** | Asking 5+ aggressive questions → user tunes out | Exactly 2 questions: "Still aligned?" + "What should change?" |
+Core anti-patterns AP1 (CEO-as-Worker), AP4 (batch implementation), AP6 (skip review), AP7 (scope creep) are covered by [WF-KERNEL.md](WF-KERNEL.md) State Ownership and Tier-Aware Acceptance Gates.
+
+WF-AUTO-specific anti-patterns:
 
 ## Safety Controls
 

package/templates/common/Harness/WF-KERNEL.md

@@ -0,0 +1,189 @@
+# WF Kernel — Shared Orchestration Engine
+
+The WF Kernel is the shared engine for `/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, and `/wf-browser`. Variants extend the kernel; they do not duplicate the orchestration logic.
+
+## Role / Model Matrix
+
+The orchestrator dispatches agents by role, model tier, and task type. No single agent type handles all work.
+
+### Small-Fast (haiku)
+
+Chore and scoped read-only work. Dispatch early and often.
+
+| Agent | Writes | Purpose |
+|---|---|---|
+| `task-scribe` | Task state only | Heartbeat, dispatch ledger, evidence pointers, compact PLAN/PROGRESS updates |
+| `codebase-explorer` | None | Scoped read-only source exploration, file discovery, symbol tracing |
+| `context-master` | Heartbeat compression line only | Context analysis, compression suggestions |
+
+### Standard (sonnet)
+
+Most decision-bound and implementation work.
+
+| Agent | Writes | Purpose |
+|---|---|---|
+| `planner` | None (returns PLAN patch) | Task decomposition, dependencies, writeSet, verification commands |
+| `researcher` | None (returns research patch) | Product, market, dependency, ecosystem research |
+| `docs-researcher` | None | Official docs, API, SDK, version, limits |
+| `architect` | None (returns architecture patch) | Boundaries, ports, data flow, state impact, migration risks |
+| `test-writer` / `tdd-guide` | Tests/plan only | AC-linked failing tests, manual verification plans |
+| `implementer` | Assigned writeSet only | Minimal production code changes |
+| `debugger` | Smallest fix path | Root-cause isolation and fix |
+| `verifier` | None | Command execution, AC evidence, validation matrix |
+| `reviewer` | None | Spec/code/security/architecture/test review findings |
+| `reflector` | None | Closeout synthesis, PASS/RETURN_TO_DEBUG/BLOCKED verdict |
+| `memory-master` | Memory files + MEMORY.md index | Durable memory write, dedup, consolidation |
+
+### High-Reasoning (opus)
+
+Reserved for architecture conflicts, security/data-loss risk, multi-layer ambiguity, or user explicitly requests.
+
+### WF-MAX Managers (sonnet)
+
+| Manager | Spawns | Purpose |
+|---|---|---|
+| `explore-manager` | 5-10 read-only researchers/explorers | W0 exploration fan-out |
+| `architect-manager` | 3 architects | W1 boundary/interface contracts |
+| `implement-manager` | 5-7 implementers (one file_claim each) | W2 parallel implementation |
+| `review-manager` | 3-4 reviewers (spec/code/security/perf) | W2R review fan-out |
+
+## Dynamic Ready-Queue Orchestration
+
+`/wf` is NOT a fixed serial pipeline. It uses a dependency-driven ready queue, persisted across sessions via [WF-STATE.md](WF-STATE.md).
+
+```text
+while task not accepted:
+    update readyQueue from dependency graph
+
+    // Phase-independent: dispatch anything ready
+    dispatch all ready read-only agents in parallel
+        (codebase-explorer, docs-researcher, researcher, planner, architect)
+    dispatch task-scribe to maintain state alongside any work
+
+    // Write gate: only when AC + contracts + test plan exist
+    for each independent writeSet:
+        dispatch implementer (one file_claim each)
+        wait for wave complete
+        dispatch verifier on completed wave
+
+    // Review gate: wave-level, not end-of-task
+    when verifier evidence exists for a wave:
+        dispatch reviewer(s) on that wave
+
+    // Fix gate: on-demand only
+    if review finding or failed AC:
+        dispatch debugger or implementer (smallest fix)
+        re-run verifier on the fixed wave
+
+    // Reflect gate: WF-Full only, or risk-triggered
+    if WF-Full or unresolved contradiction or high-risk behavior:
+        dispatch reflector before final acceptance
+
+    // Closeout
+    task-scribe records final state
+    if durable lesson found:
+        dispatch context-master -> memory-master
+
+    stop on: accepted | blocked | user decision required
+```
+
+### Concurrency Rules
+
+1. Read-only agents always run in parallel (different readSets = no conflict).
+2. `task-scribe` runs alongside any wave — task state is its own writeSet, disjoint from source.
+3. Write agents serial within wave; parallel across waves only when writeSets are disjoint.
+4. `verifier` launches per-wave as soon as that wave's write agents complete.
+5. `reviewer` launches per-wave when verifier evidence is ready.
+6. `debugger` launches on-demand when a specific AC or review finding fails.
+7. `reflector` launches only in WF-Full, or when risk/contradiction is detected.
+8. Idle capacity is immediately filled with the next ready item from the queue.
+
+## Dispatch Packet (Extended)
+
+Every dispatch MUST carry:
+
+```text
+Role:
+Objective:
+TaskType:           ui-browser | api-backend | architecture-migration | docs-readme | dependency-sdk | bug-fix | refactor | chore
+ModelTier:          small-fast | standard | high-reasoning
+AgentName:
+Skills:             list or none
+ReadSet:
+WriteSet:
+Forbidden:
+AC IDs:
+MaxReturnTokens:
+ReturnSchema:
+```
+
+## Task Type → Agent/Skill Routing
+
+| Task Type | Primary Agents | Skills |
+|---|---|---|
+| UI/browser behavior | test-writer, implementer, verifier, reviewer | browser-e2e, wf-browser |
+| API/backend | docs-researcher, test-writer, implementer, verifier, reviewer (security) | tdd |
+| Architecture/migration | architect, codebase-explorer, planner, reviewer | — |
+| Docs/README | wf-readme, reviewer, task-scribe | wf-readme |
+| Dependency/SDK/API upgrade | docs-researcher, researcher, implementer | — |
+| Bug/failing test | debugger, verifier, implementer, reviewer | tdd |
+| Large refactor | planner, architect, codebase-explorer fan-out, implement-manager, review-manager | — |
+| Task state/log/evidence only | task-scribe (haiku) | — |
+| Source discovery/tracing | codebase-explorer (haiku) fan-out | — |
+
+## Tier-Aware Acceptance Gates
+
+Acceptance is tier-dependent. No single gate covers all tiers.
+
+### WF-Light
+
+1-2 files, well-understood, low risk.
+- planner + test-writer + implementer + verifier
+- Task-scribe maintains state throughout
+- Codebase-explorer optional
+- **Acceptance**: verification passes + task state recorded = closeout
+- Cross-review and reflector are NOT mandatory
+- Heartbeat: phase boundaries, failure, closeout
+
+### WF-Standard
+
+Multi-file or behavior change.
+- WF-Light baseline + research/docs + at least one independent review lens
+- Parallel: codebase-explorer(s), docs-researcher/researcher, planner, task-scribe
+- **Acceptance**: verifier evidence + one review PASS = closeout
+- Reflector: triggered only by risk, contradiction, or high-impact behavior
+- Heartbeat: wave boundaries, failure, blocker, closeout
+
+### WF-Full
+
+High-risk, cross-layer, security/data-loss, browser/API acceptance, ambiguous architecture.
+- Full chain: planner + research/docs + architect + test-writer + implementer + verifier + multi-review + reflector
+- **Acceptance**: cross-review PASS + reflector PASS
+- Maximize parallel reads; serial writes only when writeSets overlap
+- Heartbeat: wave boundaries, gate results, failure, blocker, closeout
+
+### WF-MAX
+
+`/wf-max` = `/wf` kernel + maximum safe fan-out. It is NOT a separate workflow.
+
+Delta from `/wf`:
+- Tasks are decomposed into smallest safe write-units
+- Each write-unit = one file_claim = one implementer Worker
+- Managers coordinate per-domain fan-out (explore, architect, implement, review)
+- CEO/controller never writes source; delegates all production edits to Workers
+- WF-Max-Useful (default): fan-out only where writeSets are meaningfully independent
+- WF-Max-Strict (explicit `--strict`): unconditional fan-out per span formula
+- Disjoint writeSets → parallel; overlapping → serial wave or worktree isolation
+- task-scribe continuously maintains dispatch ledger and heartbeat
+- `idleWorker -> nextReady` queue: dispatch immediately when a slot opens
+- Write workers return <=250 tokens + evidence/file paths
+
+## State Ownership
+
+- **Controller (main agent or CEO)**: owns decisions, decomposition, synthesis, final verification, dispatch
+- **task-scribe**: writes task state (PROGRESS, PLAN, ARTIFACTS, NOTES). Controller or CEO supplies structured updates; task-scribe formats and writes them.
+- **Production source agents (implementer, debugger, test-writer)**: write ONLY their assigned writeSet. Never write task state.
+- **Reviewer, verifier, reflector, architect, planner, researcher**: read-only. Return findings/patches to controller for synthesis.
+
+Old rule: "Only main agent writes task PROGRESS/PLAN."
+New rule: "Only controller or task-scribe writes task state. Production source agents never write task state unless explicitly dispatched as task-scribe."