create-harness-vibe-coding 0.8.19 → 0.9.3

package/templates/common/.claude/skills/wf-search/references/policies/fact.md

@@ -0,0 +1,39 @@
+# Policy: fact
+
+Mode `fact` — confirm a single object, version, date, capability, or other
+discrete fact.
+
+## What to Confirm
+
+Identify exactly what is being confirmed: the artifact name, the version or
+date (if the question is versioned), and the precision the user needs. A
+"fact" pass answers one bounded question, not a survey.
+
+## Source Priority
+
+Official primary text first: vendor documentation, release notes, the
+standard/spec text, or the project's own source code. Source code outranks
+blog posts and summaries. Community restatements are corroboration only,
+never the primary support for a supported fact.
+
+## Early Stop
+
+If direct official evidence fully answers the question (for example a
+changelog entry naming the exact version and date), stop after that single
+query/read. Record the early stop reason in `stopReason`. Do not spend the
+remaining budget re-confirming an already-direct answer.
+
+## Dates
+
+Record `publishedAt` only when the source itself states or clearly implies a
+publication date. When the date is unknown, set `publishedAt: null` — never
+infer, approximate, or copy an unrelated page date. A null date is valid; a
+fabricated date is not. An old source is not automatically wrong, but do not
+claim a current version was verified from stale evidence.
+
+## Claims
+
+The confirmed fact is normally one `fact` claim with `importance: major` and
+at least one supporting source whose `access` is not `snippet`. Note
+versioning caveats (e.g. "as of the checked date") in `confidenceReason` or
+`limitations`.

package/templates/common/.claude/skills/wf-search/references/policies/troubleshoot.md

@@ -0,0 +1,39 @@
+# Policy: troubleshoot
+
+Mode `troubleshoot` — diagnose an error or misbehavior using external
+evidence matched to the local environment.
+
+## Local Facts First
+
+Before any external search, confirm the local facts: the exact error text,
+the tool/library versions in use, the platform, and what already changed
+recently. A mismatched-version answer is worse than no answer; record the
+local environment in `constraints`.
+
+## Redacted Minimal Query
+
+Build the smallest query that identifies the problem: the distinctive error
+token or message fragment plus the exact version, with paths, usernames,
+hostnames, tokens, and business data removed. Never paste raw private logs
+into a search tool. Redact first; if a log line cannot be safely reduced to
+its distinctive tokens, do not send it.
+
+## Environment-Matched Evidence
+
+Weight found evidence by how closely its environment matches the local one
+(same major version, same platform). An applicable fix for a different
+version is a hint, not an answer — record the version it actually applies
+to in the claim or source notes.
+
+## No Uploads
+
+This mode never uploads raw private logs, configuration files, or secrets to
+any search tool, paste site, or third-party service. Evidence flows in
+(search results), private data does not flow out.
+
+## Outcome
+
+Report the most probable cause with its evidence, the steps to verify it
+locally, and alternatives when several causes match. If no
+environment-matched evidence is found within budget, say so and record the
+gap rather than generalizing from mismatched versions.

package/templates/common/.claude/skills/wf-search/references/policies/verify.md

@@ -0,0 +1,44 @@
+# Policy: verify
+
+Mode `verify` — check an existing claim or statement against real evidence,
+actively looking for counter-evidence.
+
+## Decompose First
+
+Split the original statement into separately checkable atomic claims. A
+compound statement ("X is deprecated, fast, and unsupported on Windows") is
+verified claim by claim; the overall verdict is assembled from the parts,
+never asserted wholesale.
+
+## Support and Counter-Evidence
+
+For each atomic claim, look for supporting evidence AND significant
+counter-evidence. Searching only for confirmation is a protocol violation:
+record contradiction sources in `contradictionIds`, not only in free text.
+Counter-evidence that is significant must be kept even when inconvenient.
+
+## Handling Conflicts
+
+- Evidence conflicts but one side is clearly primary/official and newer:
+  the claim may stay `supported` with the conflict noted in `gaps` or
+  `confidenceReason`.
+- Conflict is unresolvable within budget or credibility: mark the claim
+  `disputed`, keep both sides' sources, and set the overall `status` to
+  `incomplete`. A disputed result is a legitimate outcome; do not force a
+  verdict.
+- A `complete` result that still carries an unexplained significant
+  contradiction is invalid (see `references/evidence-contract.md`).
+
+## Independence
+
+Treat source independence explicitly. Different domains are not
+automatically independent sources; syndicated or mirrored coverage needs an
+explicit `originGroup`. When independence is unknown, say so — an
+independence of `unknown` never counts as proven independent corroboration.
+
+## Absence of Evidence
+
+If the claim is about absence ("feature X does not exist"), record what was
+searched and where; absence findings are `insufficient` rather than
+`supported` unless an authoritative negative statement (official "not
+supported" note) is found.

package/templates/common/.claude/skills/wf-search/references/source-routing.md

@@ -0,0 +1,40 @@
+# Source Routing
+
+Pick source types per question before picking tools. This mirrors the local
+research protocol's tool order (local first, optional external tools, free
+fallback, no paid-tool requirement).
+
+## Source Types
+
+`official`, `source-code`, `issue`, `paper`, `community`, `news`, `other`.
+
+## Routing by Question Type
+
+| Question type | Preferred sources | Notes |
+| --- | --- | --- |
+| Version/date/capability fact | official, source-code | changelogs, release notes, specs, in-repo code |
+| Behavior/API correctness | source-code, official, issue | source outranks summaries; maintainer answers in issues are official-ish |
+| Contested claim | official + independent community/news | deliberately seek counter-evidence, not only confirmation |
+| Option comparison | official, source-code, issue, community | same-condition grid; popularity signals stay community-observation |
+| Error diagnosis | issue, source-code, community | match versions/platform; official bug trackers first |
+| Ecosystem/news/practice | news, community, official | check dates; news syndication needs originGroup |
+
+## Local First
+
+Before external sources, check the local repo: existing docs, lockfiles,
+vendored code, tests, package metadata, and prior recorded research
+(`Harness/research/research-results.md`). Local evidence can answer or
+sharpen the question; it does not replace a user-requested current external
+verification.
+
+## Independence Rules
+
+- Different domains do not automatically mean independent sources — press
+  releases and news coverage are frequently copies of one origin.
+- Syndicated/mirrored/republished coverage of one origin must carry the same
+  explicit `originGroup` value so it is not counted as independent
+  corroboration.
+- When independence is unknown, leave it unknown; `unknown` never counts as
+  proven independent support.
+- Do not merge URLs across origins; normalization removes only known
+  tracking parameters (see `evidence-contract.md`).

package/templates/common/.claude/skills/wf-search/references/tool-adapters.md

@@ -0,0 +1,38 @@
+# Tool Adapters
+
+Pick the tool after the source types are known, from tools actually
+available in the current host. Discover capabilities at runtime.
+
+## Host Tools
+
+| Tool | Use for | Notes |
+| --- | --- | --- |
+| WebSearch / built-in web search | broad query, source discovery | free fallback; expect less structure, verify more |
+| WebFetch / page read | fetching a specific URL's text | counts as a read per URL |
+| GitHub CLI (`gh`) / GitHub API | repos, issues, code search, releases | needs auth for rate-heavy use |
+| Tavily (optional) | broad web search, source discovery | only when configured; never required |
+| TinyFish (optional) | rendered/dynamic pages, structured extraction | only when configured; never required |
+| User-designated browser | pages needing interaction or login | user must name it; never assume |
+
+## Availability Rules
+
+- Configuration existing does not mean authenticated and callable. A tool
+  counts as available only when a call with it actually succeeds in this
+  session; verify before relying on it.
+- If a tool requires installation or login that is not already satisfied,
+  record the operation as `unavailable` and use a legitimate fallback. Do not
+  install or log in automatically from this command.
+- No tool is mandatory and no paid tool is required. When Tavily/TinyFish is
+  absent, use the built-in fallback and record the limitation.
+- When every usable tool is unavailable, record all operations as
+  `unavailable` and report the failure honestly. Never fabricate citations
+  for searches that did not run.
+- `--depth deep` is this command's budget tier (12 query / 20 read). It does
+  not invoke any external deep-research plugin; such a plugin is used only
+  when the user's intent matches its own real trigger conditions.
+
+## Read the Docs After Choosing
+
+Read a tool's own Skill/documentation only after selecting it for this run,
+not upfront for every candidate tool. Record which tool served each
+operation in `operations[].tool`.

package/templates/common/.claude/skills/wf-ui/SKILL.md

@@ -30,34 +30,55 @@ Do not paste full API responses, accessibility trees, or terminal transcripts.
 Run from the project root:
 
 ```text
-create-harness-vibe-coding wf-ui --project . --host 127.0.0.1 --port 0 --open
+create-harness-vibe-coding wf-ui --project . --host 127.0.0.1 --port 56670 --open --detach
 ```
 
-If the global binary is not available, use:
+If you are inside the generator source repository and the global binary is not
+available, use:
 
 ```text
-npx create-harness-vibe-coding@0.8.19 wf-ui --project . --host 127.0.0.1 --port 0 --open
+node bin/create-harness-vibe-coding.js wf-ui --project . --host 127.0.0.1 --port 56670 --open --detach
+```
+
+Otherwise use:
+
+```text
+npx create-harness-vibe-coding@0.8.21 wf-ui --project . --host 127.0.0.1 --port 56670 --open --detach
 ```
 
 Rules:
 - Bind only to `127.0.0.1`; never `0.0.0.0`.
-- Default port `0` for an OS-assigned free port.
-- Generate a random one-time token.
-- Open `http://127.0.0.1:<port>/?token=<token>`.
-- Leave the server running until the user stops it.
+- Default port `56670`; if occupied, wf-ui tries the next port upward until one opens. Use `--port 0` only when you explicitly want an OS-assigned free port.
+- Open the local URL printed by the command; frontend/API token auth is not required for this trusted loopback UI.
+- Detach the server so command timeouts do not stop the control panel.
+
+## Relationship To WF-Browser
+
+Use this skill to start and operate the local Harness control panel. When the
+task involves designing, debugging, or controlling a web UI through agent-visible
+browser primitives, also use `wf-browser`.
+
+`wf-ui` provides the local server, task/session graph, terminal bridge, and the
+wf-browser backend control plane. `wf-browser` defines how a frontend should
+expose route/capability/UI-tree/state/log/action contracts to that control
+plane.
 
 ## Architecture
 
 ```text
-Browser UI (React + TypeScript + Motion for React + Lucide)
+Agent script/skill
     |
-    | HTTP JSON APIs + WebSocket
+    | Harness/scripts/wf-ui-control.mjs + HTTP JSON APIs
     v
 Local Node server bound to 127.0.0.1 only
     |
-    | fs + task-state.mjs + optional node-pty
+    | tasks/sessions/a2a + wf-browser run/window/lease/artifact stores
+    v
+Project-local Harness files
+    |
+    | /ws/events invalidation, /ws/terminal PTY, /ws/wf-browser observe/act
     v
-Project-local Harness files (tasks/**, settings, version, command surfaces)
+Browser UI (React + TypeScript + Motion for React + Lucide)
 ```
 
 ## Communication Protocol
@@ -67,11 +88,124 @@ Project-local Harness files (tasks/**, settings, version, command surfaces)
   on reconnect or sequence gaps.
 - Browser writes go through typed `POST` endpoints.
 - `Harness/tasks/**` is the durable source of truth; UI state is derived.
+- WF browser runs are stored under `Harness/wf-browser/runs/<runId>/`.
+- WF browser backend primitives:
+  - `GET /api/wf-browser/capabilities`
+  - `POST /api/wf-browser/runs`
+  - `GET /api/wf-browser/runs/:runId/windows`
+  - `POST /api/wf-browser/runs/:runId/windows`
+  - `POST /api/wf-browser/runs/:runId/windows/:windowId/lease`
+  - `POST /api/wf-browser/runs/:runId/windows/:windowId/commands`
+  - `POST /api/wf-browser/runs/:runId/windows/:windowId/artifacts`
+  - `GET /api/wf-browser/connections`
+  - `POST /api/wf-browser/cleanup`
+- A control lease is exclusive per window. Observe leases are read-only.
+- Artifacts store screenshots, UI trees, state, logs, network, AST, replay, and
+  analysis files instead of pasting bulky data into task docs.
+- The frontend debug runtime connects only when the page URL or sessionStorage
+  has `wfRun` and `wfWindow`; add `wfDebug=1` to show the virtual cursor overlay.
+
+## Agent Commands
+
+After `/wf-ui` starts, agents can use the control script when
+`HARNESS_WF_UI_URL` is available. `HARNESS_WF_UI_TOKEN` is accepted only as a
+legacy optional value:
+
+```text
+node Harness/scripts/wf-ui-control.mjs browser-allocate --mode runtime --route /workflow
+node Harness/scripts/wf-ui-control.mjs browser-allocate-many --mode runtime --agents agent-a,agent-b --routes /workflow,/agents
+node Harness/scripts/wf-ui-control.mjs browser-run --mode runtime --route /workflow
+node Harness/scripts/wf-ui-control.mjs browser-window --run <runId> --route /workflow
+node Harness/scripts/wf-ui-control.mjs browser-windows --run <runId>
+node Harness/scripts/wf-ui-control.mjs browser-lease --run <runId> --window <windowId> --type control
+node Harness/scripts/wf-ui-control.mjs browser-url --run <runId> --window <windowId> --lease <leaseId>
+node Harness/scripts/wf-ui-control.mjs browser-open --run <runId> --window <windowId> --lease <leaseId> --context isolated
+node Harness/scripts/wf-ui-control.mjs browser-launches --run <runId> --window <windowId>
+node Harness/scripts/wf-ui-control.mjs browser-close --run <runId> --window <windowId> --launch <launchId> --remove-profile true
+node Harness/scripts/wf-ui-control.mjs browser-wait --run <runId> --window <windowId> --agent <agentId>
+node Harness/scripts/wf-ui-control.mjs browser-connections
+node Harness/scripts/wf-ui-control.mjs browser-cleanup --keep-latest 20 --max-age-days 7
+node Harness/scripts/wf-ui-control.mjs browser-command --run <runId> --window <windowId> --lease <leaseId> --primitive observe.uiTree
+node Harness/scripts/wf-ui-control.mjs browser-snapshot --run <runId> --window <windowId> --lease <leaseId>
+node Harness/scripts/wf-ui-control.mjs browser-command --run <runId> --window <windowId> --lease <leaseId> --primitive act.click --testid save-button
+node Harness/scripts/wf-ui-control.mjs browser-release --run <runId> --window <windowId> --lease <leaseId> --close true --remove-profile true
+node Harness/scripts/wf-ui-control.mjs browser-artifacts --run <runId> --window <windowId>
+```
+
+Prefer `browser-allocate` for one subagent and `browser-allocate-many` for a
+batch of subagents. They create or reuse a run, create window slots, grant
+leases, and return `launchUrl` values. Use `browser-url` to regenerate a URL
+later. Use `browser-open --context isolated` when an agent needs Harness to open
+a visible browser window with a per-window profile instead of asking the user to
+open the URL manually. `browser-open` records `browser-launches.json` under the
+run/window folder; use `browser-launches` to inspect local process/profile state
+and `browser-close --remove-profile true` or `browser-release --close true` for
+closeout. Use `browser-wait` after opening or refreshing a launch URL when the
+next step needs the frontend WebSocket bridge to be connected.
+Opening or refreshing the UI with the returned URL sets these debug parameters:
+
+```text
+?wfRun=<runId>&wfWindow=<windowId>&wfAgent=<agentId>&wfLease=<leaseId>&wfDebug=1
+```
+
+The first-party bridge supports `observe.route`, `observe.capabilities`,
+`observe.uiTree`, `observe.state`, `observe.logs`, `observe.network`,
+`observe.replay`, `observe.diff`, plus visible `act.hover`, `act.click`,
+`act.focus`, `act.type`, `act.clear`, `act.select`, `act.press`, `act.drag`,
+`act.scroll`, and `act.wait`. The React shell also registers route capability
+maps for tasks, workflow, agents, roles, settings, and terminal drawer surfaces
+through `wfBrowserRouteCapabilities`; `observe.uiTree` annotates matching nodes
+with `registeredCapabilityIds`.
+Use Playwright/CDP only for unsupported browser facts such as trusted screenshots,
+native downloads, permissions, or third-party pages, and normalize evidence into
+the same run/window artifact layout.
+Use `browser-snapshot` before subagent handoff, after a visible action sequence,
+or before release. It serially captures route, capabilities, UI tree, state,
+logs, network, replay, and diff observations through the connected window lease
+and returns the artifact paths.
+
+## Readiness Boundary
+
+Current wf-ui target:
+
+- L2 foundation: run/window/lease/artifact APIs, command API, and control script.
+- L3-minimal bridge: `/ws/wf-browser` dispatches bounded `observe.*`/`act.*`
+  commands to an opt-in frontend debug runtime with virtual cursor feedback.
+- L3 route map: wf-ui registers first-party route/page/canvas/graph/form/list
+  capabilities for the current route and exposes those ids in UI-tree nodes.
+- L3 observability: frontend runtime records bounded network entries, replay
+  timeline entries, and compact before/after diffs as artifact-ready outputs.
+- Connected-window handoff: `browser-snapshot` captures the standard observation
+  bundle for an existing window/lease and stores each observation as run/window
+  artifacts.
+- Isolated browser launch: `browser-open` starts a visible Chrome/Edge/Chromium
+  window with a per-run/window profile, stores launch metadata as an `analysis`
+  artifact, and records local lifecycle state in `browser-launches.json`;
+  dry-run mode proves arguments without starting a browser.
+- Browser lifecycle foundation: `browser-launches` lists per-window launches
+  with process liveness, `browser-close` closes selected/all launches and safely
+  removes isolated profiles, and `browser-release --close true` links lease
+  release to local browser cleanup.
+- Connection wait: `browser-wait` polls `/api/wf-browser/connections` until the
+  requested run/window/agent frontend registers or the timeout expires.
+- Window allocator foundation: `browser-allocate` returns per-agent launch URLs
+  for independent visible windows without requiring manual query construction;
+  `browser-allocate-many` creates a batch of independent window/lease/launchUrl
+  assignments for concurrent subagents, and `browser-windows` lists the run's
+  current window pool for dispatch and handoff.
+- Artifact retention foundation: `browser-cleanup` previews or applies the
+  default latest-20-runs / 7-day retention policy through the backend cleanup
+  API.
+- Do not claim full L3 until trusted screenshot/AST coverage and deeper
+  route-owned component maps are implemented for every major surface.
+- Full L4 multi-agent-ready still requires runtime proof that subagents operate
+  isolated visible windows concurrently, plus automatic cleanup coverage on all
+  closeout paths.
 
 ## Security
 
 - Loopback-only binding (`127.0.0.1`).
-- One-time token auth on HTTP and WebSocket.
+- Trusted local no-token HTTP and WebSocket access on loopback.
 - Path traversal prevention on all task capsule reads.
 - Command allowlist for PTY: `claude`, `codex`, `opencode`.
 - Terminal default mode: watch/read-only; attach mode is explicit.

package/templates/common/.claude/skills/wf-update/SKILL.md

@@ -45,7 +45,11 @@ 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`.
+`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`.
+
+All update paths are bounded: pass `--timeout-ms <positive-ms>` or set
+`WF_UPDATE_TIMEOUT_MS`; timeout exits with code `3`, an active update lock with
+code `4`, and successful transaction state is removed from `Harness/.temp`.
 
 1. Run `node Harness/scripts/wf-update-runner.mjs --json` first when present; otherwise run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan. Current updaters try npm `create-harness-vibe-coding@latest` first, then canonical GitHub `LiWeny16/create-harness-vibe-coding`, then legacy mirror `zingspark/create-harness-vibe-coding`.
 2. Preserve all PRESERVE files. Never overwrite user task, memory, research, root README.md, package, progress, or architecture files. Harness/README.md is merge-tier, not PRESERVE.