create-harness-vibe-coding 0.8.18 → 0.8.19

package/templates/common/.opencode/commands/wf-update.md

@@ -22,7 +22,23 @@ targeted inspection.
 
 ## Flow
 
-1. Run `node Harness/scripts/wf-update-check.mjs --json` first and use the
+Scope resolution is deterministic:
+
+- Current project has `Harness/scripts/wf-update-check.mjs`: update the project
+  install from that script.
+- A global runtime is discoverable from `Harness/.harness-version.globalDir`,
+  `HARNESS_GLOBAL_HOME`, or the default `~/.harness/create-harness-vibe-coding`:
+  update that runtime too, then sync its Claude/Codex/OpenCode host-global
+  copies.
+- Current project has no Harness install: update only the global runtime and
+  host-global copies. Do not scaffold or modify the project unless the user
+  explicitly asks to install Harness there.
+`Harness/scripts/wf-update-runner.mjs` implements this multi-scope routing.
+Older installs that do not have the runner fall back to
+`Harness/scripts/wf-update-check.mjs`.
+
+1. Run `node Harness/scripts/wf-update-runner.mjs --json` first when present;
+   otherwise run `node Harness/scripts/wf-update-check.mjs --json`. Use the
    `agent` block as the action plan. Preserve `agent.releaseHighlights` for the
    user-facing update summary. Current updaters try npm
    `create-harness-vibe-coding@latest` first, then the canonical GitHub source
@@ -33,9 +49,11 @@ targeted inspection.
    starter files may be created, and checksum-matching legacy architecture can
    move to `Harness/project/architecture.md`. Harness/README.md is merge-tier,
    not PRESERVE.
-3. If `agent.safeApplyCommand` is present, run it to apply SAFE, NEW, and
-   adopted metadata-only files before spending AI time on conflicts. Default
-   command: `node Harness/scripts/wf-update-check.mjs --apply-safe`.
+3. If `agent.safeApplyCommand` is present, run the runner apply path to apply
+   SAFE, NEW, and adopted metadata-only files across every discovered scope
+   before spending AI time on conflicts. Default multi-scope command:
+   `node Harness/scripts/wf-update-runner.mjs --apply-safe --json`. Single-scope
+   fallback command: `node Harness/scripts/wf-update-check.mjs --apply-safe`.
    Framework-owned templates, commands, skills, agents, and scripts are
    script-owned and should be overwritten by the updater after checksum
    validation.
@@ -53,11 +71,38 @@ targeted inspection.
    `--accept-local <file>`, `--accept-merged <file>`, or
    `--accept-template <file>`; do not hand-edit `Harness/.harness-version`.
    Ask the user only when the intent is ambiguous.
-7. Run `node Harness/scripts/wf-update-check.mjs --finalize` after all
-   conflicts have script-recorded decisions. Use strict `--apply` only when the
-   JSON plan has zero conflicts.
-8. After update, run `node Harness/scripts/validate-harness.mjs` and then
-   `node Harness/scripts/scan-clean.mjs`.
+7. Run `node Harness/scripts/wf-update-runner.mjs --finalize --json` after all
+   conflicts have script-recorded decisions. Single-scope fallback:
+   `node Harness/scripts/wf-update-check.mjs --finalize`. Use strict `--apply` only when
+   the JSON plan has zero conflicts.
+8. After update, sync and validate all machine surfaces:
+   ```
+   node Harness/scripts/sync-host-global.mjs --json
+   node Harness/scripts/sync-host-global.mjs --apply --json
+   node Harness/scripts/validate-harness.mjs
+   node Harness/scripts/validate-harness.mjs --manifest-audit
+   node Harness/scripts/scan-clean.mjs --json
+   ```
+   `sync-host-global.mjs` is a no-op for project-only installs. For global
+   installs it compares host-global files against the runtime sources listed in
+   `.harness-version.hostGlobal.targets`; missing or Harness-marked stale copies
+   are repaired by script, while user-looking files stay conflicts.
+9. If the update reports "Already up to date" but files are missing (e.g.,
+   new commands not showing up on a platform), run:
+   ```
+   node Harness/scripts/wf-update-runner.mjs --repair --json
+   node Harness/scripts/wf-update-runner.mjs --repair --apply-safe --json
+   node Harness/scripts/wf-update-runner.mjs --repair --finalize --json
+   node Harness/scripts/wf-update-check.mjs --repair --json
+   node Harness/scripts/wf-update-check.mjs --repair --apply-safe
+   node Harness/scripts/wf-update-check.mjs --repair --finalize
+   node Harness/scripts/sync-host-global.mjs --apply --json
+   node Harness/scripts/validate-harness.mjs --manifest-audit
+   ```
+   `--repair` bypasses the version check and forces a full file diff against
+   the latest remote template. This catches files that were missed during a
+   previous partial update where the version was bumped but not all files
+   were written.
 
 Codex users without a direct command surface: use `$wf-update` (skill path) or
 `node Harness/scripts/wf-update-check.mjs`.

package/templates/common/CLAUDE.md

@@ -14,7 +14,7 @@ In direct mode, do not load the full Harness router. Inspect only the files need
 
 Complex work may use direct planning, task capsules, tests, and subagents without entering WF. WF execution modes are explicit only: the user must type `/wf`, `$wf`, `/skills wf`, `/wf-max`, `$wf-max`, `/skills wf-max`, `/wf-auto`, `$wf-auto`, `/skills wf-auto`, `/wf-auto-spark`, `$wf-auto-spark`, or `/skills wf-auto-spark` to enter the WF kernel. No other phrasing, complexity heuristic, or inferred intent triggers WF.
 
-`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, `/skills wf-update`, `/wf-task-record`, `$wf-task-record`, `/skills wf-task-record`, `/wf-task-list`, `$wf-task-list`, `/skills wf-task-list`, `/wf-task-archive`, `$wf-task-archive`, `/skills wf-task-archive`, `/wf-command-create`, `$wf-command-create`, and `/skills wf-command-create` are **direct/compat commands** — do NOT load `Harness/MEMORY.md`, do NOT enter WF. Claude Code and OpenCode execute the direct command files; Codex may invoke the matching compatibility skill shim.
+`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, `/skills wf-update`, `/wf-task-record`, `$wf-task-record`, `/skills wf-task-record`, `/wf-task-list`, `$wf-task-list`, `/skills wf-task-list`, `/wf-task-archive`, `$wf-task-archive`, `/skills wf-task-archive`, `/wf-command-create`, `$wf-command-create`, `/skills wf-command-create`, `/wf-ui`, `$wf-ui`, and `/skills wf-ui` are **direct/compat commands** — do NOT load `Harness/MEMORY.md`, do NOT enter WF. Claude Code and OpenCode execute the direct command files; Codex may invoke the matching compatibility skill shim.
 
 For non-direct workflow commands (`/wf`, `/wf-max`, `/wf-auto`, `/wf-review`, `/wf-learn`, `/wf-readme`, `/wf-remove`, `/wf-browser`, `/wf-auto-spark`, and matching `$wf-*` or `/skills wf-*` forms except the direct/compat commands above), load `Harness/MEMORY.md` first, then `Harness/README.md`.
 

package/templates/common/Harness/MEMORY.md

@@ -42,6 +42,7 @@ Stack-specific agents can be added after the product shape is known.
 - [wf-auto](../.claude/skills/wf-auto/SKILL.md) - perpetual adaptive auto-optimization: evidence-selected probes, dynamic obligations, intent checkpoints, evidence ledger.
 - [wf-auto-spark](../.claude/skills/wf-auto-spark/SKILL.md) - perpetual inspiration mode: external spark search, long-term roadmap with staged milestones, <=50% deviation guard.
 - [wf-browser](../.claude/skills/wf-browser/SKILL.md) - built-in browser automation/E2E workflow with controllable UI contracts, Browser Use, Playwright, CDP/network evidence, screenshots, traces, and validation matrix.
+- [wf-ui](../.claude/skills/wf-ui/SKILL.md) - Codex compatibility shim for `$wf-ui` / `/skills wf-ui`; direct command starts the local browser control panel without entering WF.
 - [tdd](../.claude/skills/tdd/SKILL.md) - acceptance-driven TDD: AC-linked RED tests, real UI clicks for browser-visible behavior, Playwright/CDP evidence, and configured coverage gate.
 - [wf-remove](../.claude/skills/wf-remove/SKILL.md) - safely remove Harness framework files (SAFE/MODIFIED/USER classes), auto-prune empty directories, backup option.
 - [wf-task-record](../.claude/skills/wf-task-record/SKILL.md) - Codex compatibility: use $wf-task-record or /skills wf-task-record to wrap task-state.mjs record.
@@ -59,6 +60,7 @@ Codex repo-skill mirrors live under `../.agents/skills/` with the same skill nam
 - [wf-task-list](../.claude/commands/wf-task-list.md) - direct `/wf-task-list` command that wraps `node Harness/scripts/task-state.mjs list`.
 - [wf-task-archive](../.claude/commands/wf-task-archive.md) - direct `/wf-task-archive` command that wraps `node Harness/scripts/task-state.mjs archive`.
 - [wf-command-create](../.claude/commands/wf-command-create.md) - direct `/wf-command-create` command for task-backed wf-* command surface changes.
+- [wf-ui](../.claude/commands/wf-ui.md) - direct `/wf-ui` command that starts the local Harness backend and browser control panel.
 
 Stack-specific skills can be added after the product shape is known.
 

package/templates/common/Harness/README.md

@@ -4,7 +4,7 @@ Purpose: route humans and agents to the smallest useful context. `CLAUDE.md` is
 
 Default load: `CLAUDE.md`. For workflow commands (`/wf`, `/wf-max`, `/wf-auto`, `/wf-review`, `/wf-learn`, `/wf-readme`, `/wf-remove`, `/wf-browser`, `/wf-auto-spark`), also load `Harness/MEMORY.md` (index only per Memory Preflight), this file, and `Harness/PROGRESS.md` when work is active.
 
-`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, `/skills wf-update`, `/wf-task-record`, `$wf-task-record`, `/skills wf-task-record`, `/wf-task-list`, `$wf-task-list`, `/skills wf-task-list`, `/wf-task-archive`, `$wf-task-archive`, `/skills wf-task-archive`, `/wf-command-create`, `$wf-command-create`, and `/skills wf-command-create` are **direct/compat commands**: skip the router, do NOT load `Harness/MEMORY.md`, do NOT enter WF. Claude Code and OpenCode execute direct command files; Codex uses the matching compatibility skill shim.
+`/wf-help` `$wf-help` `/skills wf-help`, `/wf-update` `$wf-update` `/skills wf-update`, `/wf-task-record` `$wf-task-record` `/skills wf-task-record`, `/wf-task-list` `$wf-task-list` `/skills wf-task-list`, `/wf-task-archive` `$wf-task-archive` `/skills wf-task-archive`, `/wf-command-create` `$wf-command-create` `/skills wf-command-create`, `/wf-ui` `$wf-ui` `/skills wf-ui` are **direct/compat commands**: skip router, skip `Harness/MEMORY.md`, never enter WF. Claude/OpenCode use command files; Codex uses shims.
 
 Do not read the whole `Harness/` tree.
 
@@ -55,8 +55,8 @@ For the full phase contract, load [lifecycle.md](specs/guides/lifecycle.md).
 - This file is a router, not a full spec.
 - If the task does not clearly match a row below, search by keywords before loading more docs.
 - 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 the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Task records are compact by default: PLAN holds goal, decisions, scope, risks; PROGRESS holds status/next, changes, verification. Do not paste command logs, full transcripts, or broad PRDs when a link or one-line evidence entry is enough.
+- Write assumptions, decisions, blockers, evidence, and handoffs to the current task docs, feature doc, `Harness/MEMORY.md`, or `Harness/memory/*`.
+- Task records are compact by default: PLAN holds goal, decisions, scope, risks; PROGRESS holds status/next, changes, verification. Link logs/transcripts instead of pasting them.
 - Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
 - README rewrites are optional project-doc work. Use `wf-readme` and preserve existing public docs unless the user approves a broader restructure.
 - Code architecture belongs in [architecture.md](project/architecture.md) or the current feature doc, not `CLAUDE.md`.
@@ -107,6 +107,7 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 | Need perpetual auto-optimization | /wf-auto, $wf-auto, /skills wf-auto (explicit user token only) | [WF-AUTO.md](specs/workflows/WF-AUTO.md), [WF-AUTO-ANGLES.md](specs/workflows/WF-AUTO-ANGLES.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | perpetual loop, adaptive probe selection, dynamic risk obligations, spark search, intent checkpoint, evidence ledger; CEO never writes code |
 | Need perpetual inspiration mode | /wf-auto-spark, $wf-auto-spark, /skills wf-auto-spark (explicit user token only) | [WF-AUTO-SPARK.md](specs/workflows/WF-AUTO-SPARK.md), [WF-AUTO.md](specs/workflows/WF-AUTO.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | roadmap-anchored: North Star + milestones; external spark search; <=50% deviation guard; never auto-stops |
 | Need WF-MAX mode (explicit only) | /wf-max, $wf-max, /skills wf-max (explicit user token only) | [WF-MAX.md](specs/workflows/WF-MAX.md), [WF-KERNEL.md](specs/workflows/WF-KERNEL.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | /wf kernel + max safe fan-out (WF-Max-Useful default, WF-Max-Strict override) |
+| Need Harness control panel | /wf-ui, $wf-ui, /skills wf-ui (direct command) | `.claude/commands/wf-ui.md`, `.opencode/commands/wf-ui.md`; Codex shim: `.claude/skills/wf-ui/SKILL.md` | start local backend + browser UI directly; no WF/router load |
 | 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`, `.opencode/commands/wf-review.md` | peer CLI when available; otherwise installed `reviewer` role subagent; controller decides |
 | Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](specs/guides/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](project/architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
@@ -162,7 +163,8 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 | `/wf-task-list`, `$wf-task-list` | List tasks with dependency view, open tasks filter, and archive summary. Direct/compat — no Harness/MEMORY.md load. |
 | `/wf-task-archive`, `$wf-task-archive` | Archive completed/verified task capsules. Direct/compat — no Harness/MEMORY.md load. |
 | `/wf-command-create`, `$wf-command-create` | Create or modify wf-* command surfaces from `command-surface.json`. Direct/compat — creates/resumes a task capsule, no Harness/MEMORY.md load. |
+| `/wf-ui`, `$wf-ui` | Start the local Harness backend and browser control panel. Direct/compat — no Harness/MEMORY.md load. |
 
 ## Skill Commands
 
-Workflow commands: `/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, `/wf-learn`, `/wf-browser`, `/wf-readme`, `/wf-remove` with matching Codex `$...` and `/skills ...` forms. They load `Harness/MEMORY.md` and follow the registered task capsule policy. `/wf-update` remains direct.
+Workflow commands: `/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, `/wf-learn`, `/wf-browser`, `/wf-readme`, `/wf-remove` with matching Codex `$...` and `/skills ...` forms. They load `Harness/MEMORY.md` and follow the registered task capsule policy. `/wf-update` and `/wf-ui` remain direct.

package/templates/common/Harness/a2a/role-graph.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 1,
+  "rootAgentId": "ceo",
+  "agents": [
+    {
+      "agentId": "ceo",
+      "role": "CEO Leader",
+      "level": 0,
+      "kind": "controller",
+      "skills": ["wf", "subagent-orchestrator", "terminal-control"],
+      "permissions": ["plan", "dispatch", "read-terminals", "send-terminal-input"]
+    },
+    {
+      "agentId": "product-manager",
+      "role": "Product Manager",
+      "level": 1,
+      "kind": "planner",
+      "skills": ["product-shape", "acceptance"],
+      "permissions": ["read-state", "define-ac"]
+    },
+    {
+      "agentId": "architect",
+      "role": "Architect",
+      "level": 1,
+      "kind": "architecture",
+      "skills": ["architecture", "contracts"],
+      "permissions": ["read-code", "define-contracts"]
+    },
+    {
+      "agentId": "backend-expert",
+      "role": "Backend Expert",
+      "level": 1,
+      "kind": "implementer",
+      "skills": ["runtime-detection", "terminal-control", "a2a-files"],
+      "permissions": ["read-code", "write-backend", "terminal-io"]
+    },
+    {
+      "agentId": "frontend-expert",
+      "role": "Frontend Expert",
+      "level": 1,
+      "kind": "implementer",
+      "skills": ["ui-control-plane"],
+      "permissions": ["read-code", "write-ui"]
+    },
+    {
+      "agentId": "reviewer",
+      "role": "Reviewer",
+      "level": 1,
+      "kind": "review",
+      "skills": ["wf-review"],
+      "permissions": ["read-code", "read-evidence"]
+    },
+    {
+      "agentId": "verifier",
+      "role": "Verifier",
+      "level": 1,
+      "kind": "validation",
+      "skills": ["wf-browser", "test-runner"],
+      "permissions": ["run-tests", "read-evidence"]
+    },
+    {
+      "agentId": "terminal-controller",
+      "role": "Terminal Controller",
+      "level": 1,
+      "kind": "runtime",
+      "skills": ["terminal-control"],
+      "permissions": ["read-terminals", "send-terminal-input"]
+    }
+  ],
+  "edges": [
+    { "from": "ceo", "to": "product-manager", "relation": "defines" },
+    { "from": "ceo", "to": "architect", "relation": "routes" },
+    { "from": "ceo", "to": "backend-expert", "relation": "dispatches" },
+    { "from": "ceo", "to": "frontend-expert", "relation": "dispatches" },
+    { "from": "ceo", "to": "reviewer", "relation": "requests-review" },
+    { "from": "ceo", "to": "verifier", "relation": "requests-evidence" },
+    { "from": "ceo", "to": "terminal-controller", "relation": "controls" }
+  ]
+}

package/templates/common/Harness/a2a/runtime-registry.json

@@ -0,0 +1,5 @@
+{
+  "schemaVersion": 1,
+  "source": "backend-runtime-detector",
+  "runtimes": ["claude", "cc", "codex", "opencode", "openclaw", "pi"]
+}

package/templates/common/Harness/a2a/skills/terminal-control.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "skillId": "terminal-control",
+  "name": "Terminal Control",
+  "source": "Harness/a2a/skills/terminal-control.json",
+  "description": "Bounded A2A tools for listing terminal sessions, reading output ranges, globbing terminal events, and attach-gated input forwarding.",
+  "tools": [
+    { "name": "list-sessions", "reads": ["Harness/tasks/**/sessions/**/STATE.json"] },
+    { "name": "read-range", "reads": ["Harness/tasks/**/sessions/**/terminal.jsonl"], "args": ["session", "from", "to", "tail"] },
+    { "name": "glob-events", "reads": ["Harness/tasks/**/sessions/**/events.jsonl"], "args": ["pattern", "since", "limit"] },
+    { "name": "send-input", "writes": ["Harness/tasks/**/sessions/**/input-requests.jsonl"], "args": ["session", "text"] }
+  ],
+  "defaultMode": "watch",
+  "inputPolicy": "attach-mode-required"
+}

package/templates/common/Harness/ownership.manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "generator": "0.8.18",
+  "generator": "0.8.19",
   "source": "https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/",
-  "generated": "2026-07-29T06:33:44.000Z",
+  "generated": "2026-07-30T14:31:29.365Z",
   "preserve": [
     "Harness/PROGRESS.md",
     "Harness/tasks/**",
@@ -246,6 +246,11 @@
       "kind": "skill",
       "overwrite": "safe"
     },
+    {
+      "path": ".agents/skills/wf-ui/SKILL.md",
+      "kind": "skill",
+      "overwrite": "safe"
+    },
     {
       "path": ".agents/skills/wf-update/SKILL.md",
       "kind": "skill",
@@ -416,6 +421,11 @@
       "kind": "command",
       "overwrite": "safe"
     },
+    {
+      "path": ".claude/commands/wf-ui.md",
+      "kind": "command",
+      "overwrite": "safe"
+    },
     {
       "path": ".claude/commands/wf-update.md",
       "kind": "command",
@@ -516,6 +526,11 @@
       "kind": "skill",
       "overwrite": "safe"
     },
+    {
+      "path": ".claude/skills/wf-ui/SKILL.md",
+      "kind": "skill",
+      "overwrite": "safe"
+    },
     {
       "path": ".claude/skills/wf-update/SKILL.md",
       "kind": "skill",
@@ -696,6 +711,11 @@
       "kind": "command",
       "overwrite": "safe"
     },
+    {
+      "path": ".opencode/commands/wf-ui.md",
+      "kind": "command",
+      "overwrite": "safe"
+    },
     {
       "path": ".opencode/commands/wf-update.md",
       "kind": "command",
@@ -711,6 +731,21 @@
       "kind": "config",
       "overwrite": "safe"
     },
+    {
+      "path": "Harness/a2a/role-graph.json",
+      "kind": "config",
+      "overwrite": "safe"
+    },
+    {
+      "path": "Harness/a2a/runtime-registry.json",
+      "kind": "config",
+      "overwrite": "safe"
+    },
+    {
+      "path": "Harness/a2a/skills/terminal-control.json",
+      "kind": "config",
+      "overwrite": "safe"
+    },
     {
       "path": "Harness/ownership.manifest.json",
       "kind": "config",
@@ -721,6 +756,16 @@
       "kind": "config",
       "overwrite": "safe"
     },
+    {
+      "path": "Harness/scripts/README.md",
+      "kind": "script",
+      "overwrite": "safe"
+    },
+    {
+      "path": "Harness/scripts/a2a-terminal.mjs",
+      "kind": "script",
+      "overwrite": "safe"
+    },
     {
       "path": "Harness/scripts/archive-tasks.mjs",
       "kind": "script",
@@ -741,6 +786,11 @@
       "kind": "script",
       "overwrite": "safe"
     },
+    {
+      "path": "Harness/scripts/sync-host-global.mjs",
+      "kind": "script",
+      "overwrite": "safe"
+    },
     {
       "path": "Harness/scripts/task-state.mjs",
       "kind": "script",
@@ -766,6 +816,11 @@
       "kind": "script",
       "overwrite": "safe"
     },
+    {
+      "path": "Harness/scripts/wf-update-runner.mjs",
+      "kind": "script",
+      "overwrite": "safe"
+    },
     {
       "path": "Harness/specs/guides/ECC-GUIDE.md",
       "kind": "doc",

package/templates/common/Harness/scripts/README.md

@@ -0,0 +1,134 @@
+# Harness Scripts
+
+Agents: use `task-state.mjs` for all task lifecycle operations. Other scripts are purpose-built tools invoked on demand.
+
+## Task Lifecycle (primary)
+
+### `task-state.mjs`
+
+Single entry point for all task capsule operations. Use this for any task CRUD.
+
+```bash
+# Active tasks
+node Harness/scripts/task-state.mjs list [--json]
+node Harness/scripts/task-state.mjs open [--json]
+node Harness/scripts/task-state.mjs validate [--strict] [--json]
+node Harness/scripts/task-state.mjs reconcile [--dry-run|--apply] [--json]
+node Harness/scripts/task-state.mjs set-active <task-id>
+node Harness/scripts/task-state.mjs transition <task-id> --status <s> --phase <p>
+
+# Task creation
+node Harness/scripts/task-state.mjs record <task-id> --create --text "goal" [--status <s>] [--dry-run|--apply]
+node Harness/scripts/task-state.mjs record --title "title" --note "note"  # auto-generates ID
+
+# Archive (moves completed tasks to _archive/YYYY/MM/DD/)
+node Harness/scripts/task-state.mjs archive [--dry-run|--apply] [--keep n] [--task id] [--json]
+
+# History (archived task management)
+node Harness/scripts/task-state.mjs history list [--year YYYY] [--month MM] [--json]
+node Harness/scripts/task-state.mjs history search <keyword> [--json]
+node Harness/scripts/task-state.mjs history load <task-id> [--json]
+node Harness/scripts/task-state.mjs history delete <task-id> [--dry-run|--apply] [--json]
+```
+
+**When to use:**
+- `/wf-task-list` calls `task-state.mjs list`
+- `/wf-task-archive` calls `task-state.mjs archive`
+- `/wf-task-record` calls `task-state.mjs record`
+- Resume: check `task-state.mjs open` for blocked/open tasks
+- Closeout: run `task-state.mjs archive --apply` to clean up verified tasks
+- Debug: run `task-state.mjs validate --strict` to check state integrity
+- Research: run `task-state.mjs history search <keyword>` to find past solutions
+
+### `archive-tasks.mjs`
+
+Compatibility alias for `task-state.mjs archive`. Delegates all flags.
+
+## Validation
+
+### `validate-harness.mjs`
+
+Validates harness structure, task state, file integrity.
+
+```bash
+node Harness/scripts/validate-harness.mjs [--strict] [--json]
+```
+
+**When to use:** pre-commit checks, CI gates, release validation. Strict mode fails on any violation.
+
+## Maintenance
+
+### `wf-remove.mjs`
+
+Safely removes the Harness scaffold from a project.
+
+```bash
+node Harness/scripts/wf-remove.mjs [--dry-run|--apply] [--json]
+```
+
+**When to use:** uninstalling Harness, cleaning up test installs. Always dry-run first.
+
+### `wf-update-check.mjs`
+
+Checks if a newer Harness version is available.
+
+```bash
+node Harness/scripts/wf-update-check.mjs [--json]
+```
+
+**When to use:** `/wf-update` command, periodic drift detection.
+
+### `wf-auto-update-prompt.mjs`
+
+Generates context-aware update prompts for WF-AUTO cycles.
+
+```bash
+node Harness/scripts/wf-auto-update-prompt.mjs
+```
+
+**When to use:** internally by WF-AUTO/WF-AUTO-SPARK cycles. Not invoked directly.
+
+### `scan-clean.mjs`
+
+Scans and cleans stale artifacts, temp files, orphaned references.
+
+```bash
+node Harness/scripts/scan-clean.mjs [--dry-run|--apply] [--json]
+```
+
+**When to use:** before releases, after large refactors, periodic housekeeping.
+
+## Telemetry
+
+### `l2-cache-telemetry.mjs`
+
+Measures prompt-cache hit rates across CLI runtimes (Claude Code, Codex, OpenCode).
+
+```bash
+node Harness/scripts/l2-cache-telemetry.mjs --groups <g1>,<g2> --turns <n> [--json]
+```
+
+**When to use:** benchmarking cache performance, tuning context loading, regression detection.
+
+### `context-budget.mjs`
+
+Estimates context budget usage for a given task or workflow tier.
+
+```bash
+node Harness/scripts/context-budget.mjs [--tier wf-light|wf-standard|wf-full|wf-max]
+```
+
+**When to use:** before large workflows, capacity planning, timeout risk assessment.
+
+## Agent Quick Reference
+
+| Goal | Command |
+|------|---------|
+| List active tasks + graph | `node Harness/scripts/task-state.mjs list` |
+| Find blocked tasks | `node Harness/scripts/task-state.mjs open --json` |
+| Create new task | `node Harness/scripts/task-state.mjs record --title "..." --note "..." --apply` |
+| Archive completed tasks | `node Harness/scripts/task-state.mjs archive --apply` |
+| Search history for "timeout" | `node Harness/scripts/task-state.mjs history search timeout --json` |
+| Load old task full record | `node Harness/scripts/task-state.mjs history load <task-id> --json` |
+| Validate state integrity | `node Harness/scripts/validate-harness.mjs --strict` |
+| Pre-release cleanup | `node Harness/scripts/scan-clean.mjs --dry-run` |