create-harness-vibe-coding 0.8.19 → 0.9.3

package/templates/common/Harness/project/architecture.md

@@ -45,6 +45,24 @@ Use interfaces and module boundaries to protect real seams in the generator, not
 - 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.
 
+## 2.1 Intelligence Routing and Source Reuse
+
+Context and research are routing boundaries, not implicit dependencies. WF and
+WF-MAX create a role-scoped task-context pack and consult the local research
+policy only for a capability gap, volatile API, explicit request, repeated
+failure, or benchmark gap. A source is recorded with URL, checked date,
+version/terms, and an adopt/adapt/reject reason before any contract is reused;
+prose ideas do not imply copied code or a dependency.
+
+| Source | Reuse decision | Boundary |
+| --- | --- | --- |
+| [Anthropic: Building effective agents](https://www.anthropic.com/research/building-effective-agents) | Adapt composable-role and evaluator ideas | Validate against local runtime evidence; no code copied |
+| [Anthropic: Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | Adapt finite, task-specific context budgeting | Implement as bounded packs; do not claim provider cache gains without telemetry |
+| [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) | Adapt resumable handoff/evaluation framing | Bind to local STATE/A2A contracts and holdout checks |
+| [OpenAI: Harness engineering](https://openai.com/index/harness-engineering/) | Adapt repository feedback-loop concepts | Process reference only; no equivalence or SOTA claim |
+| [Hugging Face: smolagents agents reference](https://huggingface.co/docs/smolagents/en/reference/agents) | Adapt bounded managed-agent/step-limit concepts | Reject Python dependency import; verify version before reuse |
+| [Hugging Face: ScreenSuite](https://huggingface.co/blog/screensuite) | Adapt hierarchical/holdout evaluation framing | Do not borrow scores or claim SOTA |
+
 ## 3. State Design
 
 State in this repo should be explicit, serializable, and owned by one layer.
@@ -55,6 +73,406 @@ State in this repo should be explicit, serializable, and owned by one layer.
 - 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`.
 
+### 3.1 WF-UI Component Node State Contract
+
+WF-UI component nodes have three distinct state shapes. Code, tests, and fixtures
+must keep them separate:
+
+- **Persistent state** lives at `Harness/a2a/component-nodes/<nodeId>/state.json`.
+  It is backend-owned, revisioned, and is the source of truth for user-editable
+  Markdown, Excalidraw, and File component state.
+- **Agent refs** live in `stateRef`, `contentRef`, and `componentStateRefs`.
+  Refs contain only enough metadata for agents to locate state: path, revision,
+  type, title, and small file metadata when needed. Refs are not renderable UI
+  state and must not inline `markdown`, `scene`, or editable file payloads.
+- **UI hydration state** lives in `/api/a2a/snapshot#componentNodes`. The first
+  paint workflow UI must receive full component state here so previews,
+  fullscreen editors, save buttons, and thumbnails hydrate from the same
+  revision the backend will later guard on save.
+
+Invariants:
+
+- `index.json`, `state.json`, `/api/workflow/nodes/:nodeId`,
+  `graph.componentStateRefs`, and `snapshot.componentNodes` must agree on
+  `nodeId`, `type`, `statePath`, and `revision`.
+- `statePath` must use `Harness/a2a/component-nodes/<nodeId>/state.json`; the
+  legacy `Harness/a2a/component-nodes/<nodeId>.json` shape is invalid for new
+  code, tests, and docs.
+- Defaults may seed newly created component nodes only. Existing persisted nodes
+  must not silently hydrate to empty Markdown, empty Excalidraw scenes, or empty
+  file metadata when their state file is missing or malformed.
+- Global workflow snapshots, graph maps, runtime node lists, and Agent contexts
+  enumerate live component nodes only. If `index.json` still references a
+  missing, malformed, or revision-mismatched `state.json`, the global snapshot
+  must skip that component and any dangling edges instead of crashing the
+  backend or synthesizing empty state.
+- Direct component reads remain strict: `GET /api/a2a/component-nodes/:id` and
+  typed component state updates must return the state mismatch error until the
+  stale index entry is deleted or repaired. Delete paths must still be able to
+  remove stale index entries whose state file is already gone.
+- UI tests and Playwright fixtures must either use real backend endpoints or
+  mirror this contract exactly; mocks must not invent alternate handles, paths,
+  revisions, or hydration shapes.
+
+### 3.2 WF-UI Workflow Connection State Contract
+
+WF-UI graph connections are bidirectional by default. Persisted edge endpoint
+fields preserve geometry and handle ordering; they are not a semantic permission
+direction.
+
+Invariants:
+
+- Persisted graph edges may store `from`/`to` and `source`/`target`, but these
+  fields identify stable endpoint order for rendering, handles, offsets, and
+  revisioned graph writes only.
+- Runtime node snapshots, A2A resource refs, and agent-readable graph context
+  must expose `direction: "bidirectional"` plus endpoint-specific
+  `endpointRole: "source" | "target"`.
+- Connection refs must include `edgeId`, `localHandle`, `peerHandle`,
+  `sourceHandle`, `targetHandle`, and `relation`. UI display labels must not be
+  reused as semantic `relation` values.
+- Resource nodes with one shared editable surface must expose one semantic
+  bidirectional resource port and separate physical side handles. Markdown uses
+  semantic port `markdown`; Excalidraw uses semantic port `scene`. ReactFlow may
+  render them as `markdown:left`/`markdown:right` and
+  `scene:left`/`scene:right`, but those physical handles are geometry only.
+- Markdown and Excalidraw must not be modeled as `input`/`output` split ports.
+  Both physical sides can start or receive a connection. Agent-readable context,
+  labels, and capability checks use the semantic port, not the physical side.
+- A bidirectional physical side must render as exactly one user-visible and DOM
+  handle for that side. Do not stack hidden source/target handles with the same
+  id to simulate bidirectionality; that creates ambiguous ReactFlow hit targets
+  and can snap a user drag to the wrong node. If a canvas library cannot support
+  one DOM handle that can start and receive connections, add an adapter-level
+  abstraction or tests before shipping that node.
+- Graph readers and writers must normalize missing or legacy aliases at every
+  boundary that touches persisted graph state: graph-map load/write, workflow
+  edge APIs, A2A snapshots, runtime node snapshots, and ReactFlow import/export.
+- Bare physical aliases such as `left` and `right` preserve their side before
+  semantic fallback. Normalizers must not invert them by source/target role.
+- Duplicate edge validation is undirected. `A -> B` and `B -> A` are the same
+  workflow connection unless a future explicit permission/direction mode adds a
+  separate contract.
+- UI labels and markers must present default workflow links as bidirectional.
+  Tests and fixtures must include the same connection shape as production and
+  must reject reverse duplicate pairs.
+
+### 3.3 WF-UI Node Catalog Contract
+
+WF-UI node creation must be registry-driven. The top-right create button and the
+canvas create-node path render the same searchable catalog; they must not keep
+separate hardcoded button grids.
+
+Invariants:
+
+- `src/ui/src/components/workflow/nodeRegistry.tsx` owns create-node catalog
+  metadata: `kind`, `category`, `state`, `label`, `description`,
+  `agentSemantics`, `searchText`, and icon.
+- Catalog `state` is either `ready` or `planned`. `ready` items may create
+  runtime nodes. `planned` items are visible for discoverability. Most planned
+  items are disabled, but planned capability items may open a read-only Hub
+  drawer when they declare explicit hub metadata; opening a Hub is not the same
+  as creating a runtime node.
+- The ready direct-create set is currently Agent, File, Markdown, Diagram, and
+  Timer. Skill group and MCP connector catalog entries open Hubs that may create
+  backend-owned capability nodes. Single Skill remains attach-only through an
+  Agent-targeted Skills Hub. Planned items still cover Trigger, GitHub trigger,
+  and Group/subgraph. Goal nodes are synthetic views over active Harness tasks
+  and are not direct-create catalog items.
+- Search, category grouping, disabled state, and semantic copy are derived from
+  catalog metadata. UI tests must assert the same selectors used by production:
+  `workflow-create-node-search`, `workflow-create-node-options`,
+  `workflow-create-node-group`, and `workflow-create-node-option` with
+  `data-node-kind`, `data-node-category`, `data-node-state`,
+  `data-node-action`, optional `data-node-hub`, and `data-agent-semantics`.
+- A future node type may not become `ready` as a canvas-only widget. It must
+  declare its Node Runtime adapter, storage/state ownership, graph ports,
+  direction semantics, settings/action schema, and browser/API regression tests
+  first.
+
+### 3.4 WF-UI Capability Hub Contract
+
+Skills and MCP entries are capability providers for Agent nodes. They are not
+standalone executors until a later runtime contract defines lifecycle,
+sandboxing, permissions, and audit logs.
+
+Invariants:
+
+- `GET /api/workflow/skills-hub` is a read-only metadata index. It scans only
+  allowed skill roots, defaults to project scope, reads only bounded `SKILL.md`
+  files, and returns `schemaVersion`, `query`, `roots`, `summary`,
+  `nodeSemantics`, `skills`, and `groups`.
+- Hub responses must not expose absolute local paths, skill bodies, secrets, or
+  executable command output. Source locations are project-relative or `~/...`
+  display paths only.
+- The create-node catalog may open the Skills Hub for Skill and Skill group
+  entries and may open the MCP Hub for MCP connector entries. Runtime creation
+  is allowed only for node types with backend-owned state, runtime adapters,
+  graph ports, Agent context refs, and browser/API regression tests.
+- The Hub drawer contract is stable: `workflow-capability-hub-drawer`,
+  `workflow-capability-hub-search`, `workflow-capability-hub-item`,
+  `workflow-capability-attach`, and `workflow-capability-create-node`, with
+  `data-hub-kind`, `data-origin`, and optional `data-target-agent-id`.
+- Skill attachment is enabled only when the Hub has a target Agent node. The
+  attach action updates that Agent config through `skills` and
+  `skillPolicy: "manual"`; a Hub opened without an Agent target remains
+  read-only with disabled attach controls.
+- Agent-readable context exposes attached skills through
+  `connectedCapabilityRefs`, `effectiveSkills`, and `skillPolicy`. These refs
+  use relation `capability`, `direction: "bidirectional"`, and
+  `executor: "agent"` because the Agent remains the executor and mediator.
+- `skill-group` is the first runtime capability-provider node. Its state lives
+  under `Harness/a2a/capability-nodes/<nodeId>/state.json`, is revisioned, and
+  appears in snapshots through `capabilityNodes` and `capabilityStateRefs`.
+- A Skill group node is created from a Skills Hub group, not as a standalone
+  executor. It exposes one semantic bidirectional `capability` port rendered as
+  physical handles `capability:left` and `capability:right`; both sides may start
+  or receive resource/capability links.
+- When connected to an Agent, a Skill group contributes
+  `connectedCapabilityNodeRefs`, merged `connectedCapabilityRefs`, and
+  `effectiveSkills` to that Agent context. The link uses relation `capability`,
+  `direction: "bidirectional"`, and `executor: "agent"`.
+- Skill group nodes may store only bounded metadata: group id/label/kind, skill
+  names, source summaries, and counts. They must not persist skill bodies,
+  absolute local paths, command output, secrets, or MCP credential probes.
+- `GET /api/workflow/mcp-hub` is a no-spawn, no-secret, read-only metadata
+  endpoint. It indexes project MCP config files only, exposes redacted server
+  metadata and summary counts, and never launches servers, tests credentials, or
+  leaks environment values.
+- `mcp-connector` is a runtime capability-provider node created from MCP Hub
+  server metadata. The frontend sends only `mcpServerId`; the backend re-reads
+  the Hub and persists only the sanitized record: server names, transport,
+  command basename, arg count, redacted URL, env key names, source summaries,
+  risk flags, and counts. It exposes the same bidirectional `capability` port
+  and `capability:left|right` physical handles as other capability providers.
+- When connected to an Agent, an MCP connector contributes
+  `connectedCapabilityNodeRefs` and merged `connectedCapabilityRefs`, but does
+  not add server names to `effectiveSkills`. Direct MCP attach, credential
+  probing, tool listing, and tool invocation remain gated until a separate
+  permission/audit/runtime contract exists.
+
+### 3.5 WF-UI Event Node Contract
+
+Timer is the first runtime event node. Event nodes may use directed event
+outputs, but that direction is explicit and local to event emission. It must not
+change the default bidirectional semantics of Agent, Markdown, Excalidraw, File,
+Skill, or MCP capability links.
+
+Invariants:
+
+- Timer state lives under `Harness/a2a/event-nodes/<nodeId>/state.json` and is
+  backend-owned, revisioned, and represented in snapshots through `eventNodes`,
+  `eventStateRefs`, and `connectedEventRefs`.
+- Timer exposes a directed `event` output, a `config` input, and an optional
+  bidirectional `status` port. The persisted Timer-to-Agent event edge uses
+  `direction: "source-to-target"` and relation `event`; Agent-to-Timer mutable
+  control uses a separate relation `control` edge.
+- Advanced Timer state may include once, interval, cron, loop, adaptive,
+  watchdog, while, and task cadence metadata plus base heartbeat, watchdog
+  heartbeat, task binding, and control policy. Loop/while/task/adaptive modes
+  are declarative metadata only; runtime tick logic must never evaluate
+  user-authored code from Timer settings.
+- Timer double-click opens the expanded Timer workbench for schedule mode,
+  base heartbeat, and WDT configuration. The right-click settings panel stays a
+  lightweight management surface and must not be the only way to edit schedule
+  details.
+- Agent Timer actions such as interval changes, WDT ack/reset, enable/disable,
+  and mode changes require an explicit control edge and must be exposed through
+  bounded runtime actions instead of direct state-file writes.
+- A directed event edge is duplicate-checked by ordered endpoints, relation, and
+  handles. This is separate from the unordered duplicate rule for default
+  bidirectional workflow links.
+- Event node catalog entries become `ready` only after storage, runtime adapter,
+  graph-map direction persistence, agent context refs, settings/actions, and
+  browser/API regression tests are green.
+- Trigger and GitHub trigger remain planned until their webhook/auth/replay,
+  dedupe, security, and audit contracts are written and tested.
+
+### 3.6 WF-UI Goal Node Contract
+
+Goal nodes are synthetic task-state nodes generated from active Harness tasks.
+They let the workflow canvas show completion intent, acceptance state, progress,
+and watchdog state without giving arbitrary Agents direct authority over task
+closeout.
+
+Invariants:
+
+- Goal node ids are derived from task ids and state is read from
+  `Harness/tasks/<taskId>/STATE.json` plus a backend-owned sidecar under
+  `Harness/a2a/goal-nodes/<goalId>/state.json`.
+- Goal nodes expose bidirectional `goal:left|right` handles for Agent
+  collaboration links and appear in snapshots through `goalNodes` and
+  `connectedGoalRefs`.
+- Goal double-click opens the expanded Goal workbench for user-owned edits to
+  title, objective, next action, acceptance rows, and WDT settings. These edits
+  write the Goal sidecar and do not directly mutate task `STATE.json`.
+- `goal.update` must not accept closeout authority fields such as task status,
+  phase, or gate. Completion/status transitions use the dedicated two-phase
+  Goal actions.
+- Agent-authored mutable Goal actions, including `goal.update`, require an
+  existing bidirectional `goal` edge when `actorNodeId` is present. UI/user
+  edits omit `actorNodeId`; unlinked Agent writes are rejected with
+  `GOAL_EDGE_REQUIRED`.
+- Agent completion is two-phase: `goal.requestCompletion` writes a proposal to
+  the sidecar, while direct mutation of task `STATE.json` remains gated behind a
+  separate closeout authority contract.
+- Goal WDT acknowledgement/feed state is separate from task completion state so
+  failed or stopped Agents can be recovered without marking the task complete.
+
+### 3.7 WF-UI Node Operation Language
+
+Workflow node gestures must map to a stable operation model across node kinds.
+
+Invariants:
+
+- Single-click selects a node and never opens a heavy editor.
+- Right-click opens a lightweight context menu or settings panel for node
+  management actions such as settings, delete, duplicate, copy, cut, and
+  open-config affordances.
+- Double-click opens the node's primary workbench: Agent opens terminal mode,
+  Markdown opens the enlarged editor, Excalidraw opens the enlarged scene
+  editor, Timer opens the expanded schedule workbench, and Goal opens the
+  expanded Goal workbench.
+- Expanded workbenches own draft UI state and save through typed node runtime
+  actions. Backend-owned snapshots and revisioned sidecars remain the source of
+  truth after save.
+
+### 3.8 Agent Graph Operation Control
+
+Agent-authored graph changes are first-class operations, not inferred UI state.
+
+Invariants:
+
+- Main Agent graph authority is exposed through typed `agent.*` node runtime
+  actions: `agent.readGraph`, `agent.createNode`, `agent.connectNodes`,
+  `agent.disconnectNodes`, `agent.moveNode`, `agent.deleteNode`, and
+  `agent.deleteNodes`.
+- Agent node-map skills and CLI commands are API wrappers over
+  `POST /api/workflow/nodes/:actor/actions/agent.*`. `Harness/a2a/workflow-map.json`
+  and node state sidecars are backend-owned storage and may be read for
+  diagnostics only; Agent nodes must never edit or delete those files to control
+  the canvas.
+- Compatibility commands such as `wf-ui-control.mjs connect` and
+  `wf-ui-control.mjs delete-node` must delegate to the same typed `agent.*`
+  actions instead of writing a whole graph map or calling legacy graph-node
+  delete routes directly.
+- Non-main Agents cannot mutate the whole graph unless a future permission model
+  grants that authority explicitly. Unauthorized graph mutations must fail with a
+  403-style error.
+- Every successful Agent graph action appends a bounded operation record under
+  `workflow.operations.recent[]` with only audit/animation metadata:
+  `id`, `kind`, `actor`, `targetNodeIds`, `edgeIds`, `status`, `startedAt`,
+  `completedAt`, and `expiresAt`.
+- Operation records must not store prompts, transcripts, payload bodies, secrets,
+  raw MCP config, or large user content.
+- The frontend visualizes Agent control from operation records only. Canvas
+  aura, controlled-node glow, and Agent-to-node data-flow edge animation must
+  read `targetNodeIds` and `edgeIds`; they must not guess control from node type,
+  handle side, or edge direction.
+- Browser bridge graph intents use the same operation vocabulary as human UI:
+  `graph.createNode`, `graph.connectNodes`, `graph.disconnectNodes`, and
+  `graph.moveNode`, `graph.deleteNode`, and `graph.deleteNodes`. A semantic
+  intent must issue one semantic mutation request and return operation metadata
+  on success.
+- Delete operations must protect the active controller: self-delete is rejected,
+  bulk delete skips the actor and live Agents by default, and virtual Goal node
+  deletion hides the canvas node without mutating the underlying task capsule.
+- Operation records are observability and handoff metadata. They are not a durable
+  scheduler, retry engine, authorization policy, or workflow-run state machine.
+
+### 3.9 Agent Node Context, Workspace, Skills, and Final Debug Matrix
+
+Agent nodes are graph actors with a bounded local workspace and a typed control
+plane. They must not rely on terminal prompt text alone to understand the graph.
+
+Current required contract:
+
+- Identity comes from environment plus node home:
+  `HARNESS_WORKFLOW_NODE_ID`, `HARNESS_PEER_SESSION_ID`,
+  `HARNESS_AGENT_KIND`, `HARNESS_WF_UI_URL`, `HARNESS_NODE_HOME`, and
+  `HARNESS_NODE_INIT`.
+- Each Agent node owns a durable node home under
+  `Harness/a2a/nodes/<sessionId>/` with `STATE.json`, `init.md`, and a startup
+  `graph-snapshot.json`. This folder is the Agent's local run workspace, not the
+  node-map control surface.
+- Agent working directory (`cwd`) is explicit session config and remains bounded
+  by the project workspace APIs. Workspace file changes go through
+  `/api/workspace/*`; graph and node state changes go through `/api/workflow/*`.
+- Canonical context has one shape. `GET /api/workflow/context/:node`,
+  `workflow-context`, and `agent.readContext` must expose the same core Agent
+  context fields: `identity`, `workspace`, `connectedResourceRefs`, `connectedAgentRefs`,
+  `connectedEventRefs`, `connectedCapabilityRefs`,
+  `connectedCapabilityNodeRefs`, `connectedGoalRefs`, `defaultSkills`,
+  `effectiveSkills`, `skillTriggers`, `ontology`, `affordances`, and
+  `outputRouting`.
+- Default Agent skills are machine-readable capabilities, not only prompt text:
+  `workflow-ontology`, `workflow-context`, `workflow-node-actions`,
+  `workflow-node-map`, and `terminal-control`. Each workflow skill must include
+  short trigger phrases for semantic selection, for example graph control,
+  connected-context observation, flowchart/diagram output, Goal updates, Timer
+  control, direct Agent messaging, broadcast Agent messaging, shared Markdown
+  context, worker delegation, and output readback.
+- Capability nodes and Skill groups attach metadata to Agent context. They do
+  not execute independently. MCP connector nodes are metadata-only until a
+  separate permission, tool-list, invocation, audit, and sandbox contract exists.
+- Before acting, an Agent must run the loop `observe -> plan -> act -> verify ->
+  report`: read ontology, read its context, choose connected affordances, perform
+  typed actions, then verify by reading the mutated node or peer output.
+- Durable output selection is modality-aware. Connected writable Excalidraw is
+  the preferred target for diagrams, flowcharts, sketches, and visual plans.
+  Connected writable Markdown is the preferred target for reports, notes, plans,
+  and long-form text. Terminal prose is a summary or fallback.
+- Connected Agent nodes are collaborators only when they appear in
+  `connectedAgentRefs`. Any connected Agent may send a one-to-one message with
+  `send-agent-message`/`agent.sendMessage` and reply through the same action.
+  One-to-many communication uses `broadcast-agent-message`/
+  `agent.broadcastMessage`, which records one bridge envelope per recipient.
+  Main Agents may still use legacy `delegate-agent`/`agent.sendInput` for
+  worker prompt submission, then verify with `read-agent`,
+  `read-agent-messages`, or `bridge-messages`. Built-in subagents are a
+  fallback when the graph lacks a suitable connected worker.
+- A connected Markdown node with relation `shared-context` is the local
+  blackboard for Agent collaboration. Agents read/write it through typed
+  Markdown actions only; File nodes can be shared read context through file
+  actions but are not the default writable blackboard.
+- Parallelism is a graph scheduling decision, not a terminal waiting habit.
+  Independent work packets may fan out to connected Agent workers; dependent
+  packets must wait for verified outputs or explicit Goal/Timer state.
+- Agent prompt delivery must use the canonical prompt-submit path: write prompt
+  body first, then send Enter after a short delay. Tests must cover delayed
+  Enter behavior and durable node-state readback.
+
+Final debug matrix:
+
+| Area | Probe | Pass condition |
+| --- | --- | --- |
+| Agent identity/workspace | Start or create Agent, read node home and `self` output | `STATE.json`, `init.md`, env ids, `cwd`, `nodeHomeRel`, and graph node id agree |
+| Canonical context | Compare `workflow-context` and `agent.readContext` | Both expose ontology, effective skills, connected refs, affordances, and output routing |
+| Connected resource output | Ask Agent for a flowchart or long-form note | Agent uses connected Excalidraw/Markdown node actions and verifies revision/content |
+| Graph control | Ask Main Agent to create/connect/move/delete nodes | Only typed `agent.*` actions mutate graph; operation records appear in `workflow.operations.recent[]` |
+| Agent direct communication | Connect A-B and ask each side to message/reply | Both sides use `agent.sendMessage`, bridge envelopes record node/session ids, and `agent.readMessages` reads the thread |
+| Agent broadcast communication | Connect A to B/C and broadcast one task | A records one delivered bridge envelope per connected recipient and reports skipped/unconnected recipients |
+| Shared context | Connect A/B to one Markdown `shared-context` node | Both Agents see the same Markdown ref and use typed Markdown actions as a local blackboard |
+| Worker orchestration | Connect Agent workers and delegate independent tasks | Main Agent chooses connected workers first, submits prompts, reads outputs, and records bridge evidence |
+| Authority edges | Try Timer/Goal writes with and without links | Timer control needs `control`; Goal writes need bidirectional `goal`; unlinked Agent writes fail |
+| Readback consistency | After every mutation, read through API, context, and UI snapshot | Node ids, revisions, handles, relations, and affordances match across all paths |
+| Browser evidence | Run wf-browser or Browser-plugin route checks | UI-visible graph operations and operation animations match backend operation records |
+
+Implementation path:
+
+1. Keep closing duplicate context surfaces first. Any Agent-readable context API
+   must delegate to the canonical builder or prove field parity in tests.
+2. Expand default workflow skills by semantic trigger phrases and keep generated
+   templates, dogfood manifests, Agent init text, and tests synchronized.
+3. Add an Agent-run orchestrator only after connected-Agent delegation, retry,
+   cancel, timeout, result collation, and Goal/Timer state transitions have a
+   durable state machine separate from `workflow.operations.recent[]`.
+4. Add scheduler/event delivery only after Timer due events have a durable queue,
+   replay/idempotency keys, watchdog recovery, and Agent wake-up semantics.
+5. Treat every new node type as incomplete until it has storage, runtime actions,
+   ontology entries, context refs, UI handles, settings/workbench UX, browser
+   evidence, and readback tests.
+
 ## 4. Core Components
 
 ### 4.1 CLI Entry
@@ -96,6 +514,77 @@ State in this repo should be explicit, serializable, and owned by one layer.
 - **Responsibility**: Govern future AI-agent work in this repository.
 - **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
 
+### 4.7 WF-UI Agent-Operable Browser Control Plane
+
+- **Location**: `src/wf-ui-server/wf-browser-store.mjs`, `src/wf-ui-server/ws-wf-browser.mjs`, `src/wf-ui-server/server.mjs`, `src/ui/src/wfBrowserClient.ts`, `src/ui/src/wfBrowserDebug.tsx`, `src/ui/src/wfBrowserRouteCapabilities.ts`, `Harness/scripts/wf-ui-control.mjs`
+- **Template location**: `templates/common/Harness/scripts/wf-ui-control.mjs`, `templates/common/.claude/skills/wf-ui/SKILL.md`
+- **Responsibility**: Provide the backend foundation, launch URL allocator, frontend debug bridge, visible action primitives, first-party route capability maps, and local browser launch/close lifecycle for `wf-browser` run/window/lease/artifact/command control without coupling it to task parsing, terminal PTY state, or the existing task invalidation WebSocket.
+- **Does NOT handle yet**: Trusted screenshot capture from the browser process, browser-process network/AST capture, replay playback UI, automatic close on every closeout path, or deep route-owned capability maps for every nested wf-ui surface.
+
+Data contract:
+
+```text
+Harness/wf-browser/
+  runs/
+    <runId>/
+      manifest.json
+      timeline.jsonl
+      sessions.json
+      windows/
+        <windowId>/
+          window.json
+          leases.json
+          browser-launches.json
+          artifacts.jsonl
+          screenshots/
+          ui-tree/
+          state/
+          logs/
+          network/
+          ast/
+          replay/
+          analysis/
+```
+
+Control rules:
+
+- `POST /api/wf-browser/runs` creates an isolated browser evidence run.
+- `GET /api/wf-browser/runs/:runId/windows` lists a run's current window pool for multi-subagent dispatch and handoff.
+- `POST /api/wf-browser/runs/:runId/windows` creates a logical browser window slot for one agent, route, viewport, and fixture scope.
+- `POST /api/wf-browser/runs/:runId/windows/:windowId/lease` grants `control` or read-only `observe` access.
+- A `control` lease is exclusive per window; conflicting mutating agents receive `LEASE_CONFLICT`.
+- `GET /api/wf-browser/runs/:runId/windows/:windowId/launch-url` returns the local wf-ui URL with no frontend token and debug-only params: `wfRun`, `wfWindow`, optional `wfLease`, and `wfDebug`.
+- `GET /api/wf-browser/connections` lists currently registered frontend debug clients; `Harness/scripts/wf-ui-control.mjs browser-wait` polls it before command dispatch when a launch URL was just opened or refreshed.
+- `POST /api/wf-browser/runs/:runId/windows/:windowId/commands` validates the lease, dispatches a bounded `observe.*` or `act.*` command over `/ws/wf-browser`, records action evidence, and stores observation artifacts when applicable.
+- `POST /api/wf-browser/runs/:runId/windows/:windowId/artifacts` stores bulky evidence files under the run/window folder and records compact metadata.
+- `Harness/scripts/wf-ui-control.mjs browser-open` launches a visible browser for a launch URL, uses an isolated per-run/window profile when `--context isolated` is set, stores launch metadata as an `analysis` artifact, and records local lifecycle state in `browser-launches.json`.
+- `Harness/scripts/wf-ui-control.mjs browser-launches` lists per-window launch state with process liveness; `browser-close` closes selected or all launches and safely removes per-window profiles under `Harness/wf-browser/tmp/browser-profiles/`.
+- `Harness/scripts/wf-ui-control.mjs browser-release --close true` releases the backend lease and runs local browser cleanup as one closeout command.
+- `POST /api/wf-browser/cleanup` previews or removes non-active run folders by retention policy; `Harness/scripts/wf-ui-control.mjs browser-cleanup` exposes this to agents.
+
+Readiness boundary:
+
+- Current implementation is an L3-minimal bridge for wf-browser: the opt-in frontend runtime registers with `/ws/wf-browser`, returns compact route/capability/UI-tree/state/log/network/replay/diff observations, and executes visible hover/click/focus/type/clear/select/press/drag/scroll/wait operations.
+- `Harness/scripts/wf-ui-control.mjs browser-snapshot` captures a connected
+  window handoff bundle by serially running the standard observation primitives
+  through the current lease and returning artifact paths.
+- `Harness/scripts/wf-ui-control.mjs browser-wait` is the connection-readiness
+  guard: it waits for the requested run/window/agent frontend registration
+  before `observe.*`, `act.*`, or snapshot dispatch.
+- `Harness/scripts/wf-ui-control.mjs browser-open` is the isolated visible
+  launch foundation: it can create a per-window browser profile under
+  `Harness/wf-browser/tmp/browser-profiles/`, launch Chrome/Edge/Chromium,
+  record the exact command/profile metadata as a run/window artifact, and write
+  `browser-launches.json` for later closeout.
+- `Harness/scripts/wf-ui-control.mjs browser-launches`, `browser-close`, and
+  `browser-release --close true` provide the first local process/profile
+  lifecycle layer for visible isolated agent windows.
+- `Harness/scripts/wf-ui-control.mjs browser-allocate` is the window allocator foundation: it creates or reuses a run, creates a window, grants a lease, and returns a launch URL for one visible agent window. `browser-allocate-many` repeats that allocation for a batch of subagents in one run, and `browser-windows` lists allocated windows before dispatch, handoff, or cleanup.
+- The React app shell registers base wf-browser capabilities for `app.shell`, header, navigation routes, theme toggle, and route-specific task/workflow/agents/roles/settings/terminal surfaces. `observe.uiTree` annotates matched DOM nodes with `registeredCapabilityIds`.
+- Claim full L3 only after trusted screenshot/AST coverage and deeper route-owned component maps are implemented.
+- Claim full L4 only after automatic cleanup coverage on all closeout paths and
+  concurrent isolated-window subagent runtime proof are recorded.
+
 ## 5. Data Flow
 
 ```text
@@ -124,3 +613,13 @@ CLI args / prompts
 - 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.
+
+## 8. Agent Terminal Trigger Model
+
+Agent terminals are triggered through three layers, depending on task kind:
+
+1. **Spawn-time task**: `initialPrompt` argv → the runtime TUI auto-submits the initial message (codex/claude positional prompt; opencode `--prompt`). Enter-free, preferred path.
+2. **In-session task**: ready-gated injection — wait for the prompt marker (`❯`/`›`), write the text, then a single `\r`; retry once on swallow; never send `\r\n`.
+3. **Headless task**: `codex exec --json` (one process per task, JSONL result capture, exit semantics). Interface reserved; full productization later.
+
+The PTY input sink is single: `writePtyInput` → `ptyProcess.write`. Frontend xterm WS `pty:input` and backend `send-input` share it, so a fix at the sink fixes both paths.

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

@@ -111,6 +111,26 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Architecture Decision References
 
+## Executable research policy (0.9.2)
+
+Use `node Harness/scripts/research-policy.mjs decide --task-type chore --json`
+before external research. The optional repeatable triggers are
+`capability-gap`, `volatile-api`, `user-request`, `repeated-failure`, and
+`benchmark-gap`; without a trigger a simple local chore does not require web
+research. The decision output is `{search, reasons, addDependency:false}`.
+
+Record a checked source in the task capsule with:
+
+```text
+node Harness/scripts/research-policy.mjs record --project ROOT --task TASK --input REFERENCE.json [--apply] --json
+```
+
+The JSON reference contains `url`, `title`, `sourceType`, `version`, `license`,
+`decision` (`adopt|adapt|reject`), `reason`, `acIds`, and `checkedAt`. Recording
+is dry-run unless `--apply` is supplied, writes only that task's
+`REFERENCES.md`, rejects adopting a code dependency without a license, and does
+not download or execute external code.
+
 When filling `Harness/project/architecture.md` and `Harness/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
 
 ### System Design & Architecture Patterns

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

@@ -9,16 +9,18 @@ Agents: use `task-state.mjs` for all task lifecycle operations. Other scripts ar
 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]
+# Task routing and lifecycle
+node Harness/scripts/task-state.mjs list [--project <project>] [--status <status>] [--json]
+node Harness/scripts/task-state.mjs open [--project <project>] [--status <status>] [--json]
+node Harness/scripts/task-state.mjs index
+node Harness/scripts/task-state.mjs query <keyword> [--project <project>] [--status <status>] --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 set-active <task-id>  # focus an open WF task when one is managed
 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 <task-id> --create --text "goal" [--status <s>] [--phase <p>] [--project <project>] [--tag <tag[,tag...]>] [--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/)
@@ -33,13 +35,75 @@ node Harness/scripts/task-state.mjs history delete <task-id> [--dry-run|--apply]
 
 **When to use:**
 - `/wf-task-list` calls `task-state.mjs list`
+- `index` rebuilds the generated task route after task metadata changes.
+- `query` performs deterministic keyword lookup across task metadata and capsule notes.
 - `/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
+- Closeout: transition a task to `closed`, then run `task-state.mjs archive --apply`
+- Durable WF: only tasks explicitly created with `--mode wf` or `--mode wf-max` auto-resume across sessions; mode is immutable and closed is terminal.
+- Direct coexistence: direct tasks may stay open, but cannot replace an open WF focus or be promoted into WF.
 - Debug: run `task-state.mjs validate --strict` to check state integrity
 - Research: run `task-state.mjs history search <keyword>` to find past solutions
 
+### Bounded context and conditional research
+
+Workflow controllers and workers can exchange a bounded, role-scoped task pack:
+
+```bash
+node Harness/scripts/task-context.mjs pack <task-id> --project <absolutePath> --role <role> --budget-bytes <n> --json
+node Harness/scripts/task-context.mjs show <task-id> --project <absolutePath> --json
+```
+
+`pack` is also the resume input; it omits entries outside the role/work item or
+the byte budget. The output is a structural context boundary, not a semantic
+safety guarantee. `update` is write-enabled only with `--apply`; without it the
+command is a dry run and changes no task state.
+
+Ask whether external research is warranted before using a network tool:
+
+```bash
+node Harness/scripts/research-policy.mjs decide --trigger <trigger> --task-type <type> --json
+node Harness/scripts/research-policy.mjs record --project <absolutePath> --task <task-id> --input <reference.json> --apply --json
+```
+
+Use `capability-gap`, `volatile-api`, `user-request`, `repeated-failure`, or
+`benchmark-gap` as triggers. A permitted search must read the actual primary
+source and retain its URL, title, version, license/terms, date, and
+adopt/adapt/reject rationale in task evidence.
+
+### Runtime capability declarations
+
+Native provider catalogs are preferred. A runtime without a native effort
+catalog may use an exact operator declaration in `Harness/settings.json`:
+
+```json
+{
+  "runtimeCapabilities": {
+    "claude": {
+      "models": {
+        "gateway/claude-luna": {
+          "supportedEfforts": ["low", "high", "xhigh"]
+        }
+      }
+    }
+  }
+}
+```
+
+The model key and effort names are exact. `operator-configured` is provenance
+only: it is not provider measurement, account entitlement, or task success.
+HTTP settings updates must preserve the declaration; payloads cannot add,
+replace, delete, null, or invalidate `runtimeCapabilities`. Reject invalid
+capability mutations before any settings write.
+
+### Scoped memory learning
+
+`memory-context.mjs query` narrows existing entries before `validate`, `apply`,
+or task-local `feedback`; it is not a full-memory preload. A method candidate
+needs evidence, a counterexample, and passed verification, but this structural
+gate does not replace semantic review.
+
 ### `archive-tasks.mjs`
 
 Compatibility alias for `task-state.mjs archive`. Delegates all flags.