cool-workflow 0.2.3 → 0.2.5

package/ui/workbench/app.js

@@ -15,7 +15,30 @@ const PANEL_GROUPS = [
   { key: "collaboration", label: "Review & collaboration", panels: ["review", "comments"] }
 ];
 
-const state = { activeRunId: null, activeTab: "graph" };
+// `indexSeq` is a request sequence number: the debounced filter input can
+// start a second /api/index fetch while an older one is still in flight, and
+// only the NEWEST request may render (an old slow response must not
+// overwrite a new fast one). `viewFetchedAt` is when the active run's view
+// was fetched, shown as "as of HH:MM:SS" in the detail header.
+const state = { activeRunId: null, activeTab: "graph", indexSeq: 0, viewFetchedAt: null };
+
+// The host's auth token, read ONCE at startup from the page URL. When
+// CW_WORKBENCH_TOKEN is set on the host, every /api/* request must carry it;
+// the static UI files themselves are served without it, so the page loads
+// and can explain what to do instead of rendering broken.
+const TOKEN = new URLSearchParams(location.search).get("token") || "";
+
+// Build a request URL with URLSearchParams so the token composes with any
+// other query params (e.g. the index filter's ?text=).
+function apiUrl(pathname, params = {}) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value) search.set(key, value);
+  }
+  if (TOKEN) search.set("token", TOKEN);
+  const query = search.toString();
+  return query ? `${pathname}?${query}` : pathname;
+}
 
 async function getJson(url) {
   const res = await fetch(url, { headers: { Accept: "application/json" } });
@@ -24,7 +47,10 @@ async function getJson(url) {
   try {
     body = JSON.parse(text);
   } catch {
-    throw new Error(`non-JSON response (${res.status})`);
+    throw new Error(`non-JSON response (${res.status}): ${text.slice(0, 120)}`);
+  }
+  if (res.status === 401) {
+    throw new Error("unauthorized — reopen as /?token=<your CW_WORKBENCH_TOKEN value>");
   }
   if (!res.ok) throw new Error(body && body.error ? body.error : `HTTP ${res.status}`);
   return body;
@@ -43,34 +69,71 @@ function el(tag, attrs = {}, children = []) {
   return node;
 }
 
-function freshnessBadge(value) {
+function freshnessBadge(value, title) {
   const v = String(value || "").toLowerCase();
-  return el("span", { class: `badge ${v || "absent"}`, text: value || "unknown" });
+  const attrs = { class: `badge ${v || "absent"}`, text: value || "unknown" };
+  if (title) attrs.title = title;
+  return el("span", attrs);
 }
 
 async function loadIndex() {
+  const seq = ++state.indexSeq;
   const filter = document.getElementById("filter").value.trim();
   const list = document.getElementById("run-list");
+  // A loading placeholder, not a bare wipe: the same pattern the detail
+  // pane uses, so the sidebar never flashes empty while the fetch runs.
   list.innerHTML = "";
+  list.appendChild(el("li", { class: "muted", text: "loading runs…" }));
   let view;
   try {
-    view = await getJson(`/api/index${filter ? `?text=${encodeURIComponent(filter)}` : ""}`);
+    view = await getJson(apiUrl("/api/index", { text: filter }));
   } catch (error) {
+    if (seq !== state.indexSeq) return;
+    list.innerHTML = "";
     list.appendChild(el("li", { class: "err", text: `failed to load index: ${error.message}` }));
+    // Clear the stale "registry valid · scope …" line — leaving the last
+    // successful freshness next to a load error is itself a stale badge on
+    // the one panel whose whole point is freshness.
+    const fresh = document.getElementById("registry-freshness");
+    fresh.innerHTML = "";
+    fresh.append("registry ", freshnessBadge("unavailable"), " · index unreachable");
     return;
   }
+  // Only the newest request may render (see state.indexSeq).
+  if (seq !== state.indexSeq) return;
+  list.innerHTML = "";
   const reg = view.registry || {};
   const fresh = document.getElementById("registry-freshness");
   fresh.innerHTML = "";
-  fresh.append("registry ", freshnessBadge(reg.freshness && reg.freshness.status), ` · scope ${view.scope}`);
-  const records = (view.runs && view.runs.records) || [];
+  const regStatus = reg.freshness && reg.freshness.status;
+  const regTitle = String(regStatus || "").toLowerCase() === "absent"
+    ? "no home registry data yet — runs made in this repo still show; `cw registry refresh` builds it"
+    : undefined;
+  fresh.append("registry ", freshnessBadge(regStatus, regTitle), ` · scope ${view.scope}`);
+  const runs = view.runs || {};
+  const records = runs.records || [];
   if (!records.length) {
-    list.appendChild(el("li", { class: "muted", text: "no runs indexed in this scope" }));
+    list.appendChild(el("li", { class: "muted" }, [
+      el("div", { text: "no runs indexed in this scope" }),
+      el("div", { class: "hint", text: 'create one with: cw quickstart <app> --repo <path> --question "..."' })
+    ]));
     return;
   }
-  for (const record of records) {
+  // Tell the user when the page is only part of the run set (the server
+  // returns the newest page but caps it) — otherwise a scope with more runs
+  // than the page size silently hides the rest, and someone checking "did my
+  // run get created" is misled into thinking it doesn't exist.
+  if (typeof runs.total === "number" && runs.total > records.length) {
+    list.appendChild(el("li", { class: "muted hint", text: `showing latest ${records.length} of ${runs.total} runs` }));
+  }
+  // The server returns the page sorted oldest-first; show newest at the top.
+  for (const record of [...records].reverse()) {
     const lifecycle = record.lifecycle || record.status || "";
-    const li = el("li", { class: state.activeRunId === record.runId ? "active" : "" }, [
+    // A real <button>, not a bare <li> with a click listener: Tab reaches
+    // it, Enter/Space activate it, and it gets a focus ring for free — no
+    // extra ARIA needed. Same CSS classes as before so the row/card look
+    // is unchanged (see app.css .run-list button rules).
+    const btn = el("button", { type: "button", "data-runid": record.runId, class: state.activeRunId === record.runId ? "active" : "" }, [
       el("div", { class: "rid" }, [
         el("span", { class: `status-dot ${lifecycle}`, title: lifecycle || "unknown" }),
         document.createTextNode(record.runId)
@@ -80,28 +143,61 @@ async function loadIndex() {
         text: [record.appId || record.workflowId, lifecycle, record.repo].filter(Boolean).join(" · ")
       })
     ]);
-    li.addEventListener("click", () => selectRun(record.runId));
-    list.appendChild(li);
+    btn.addEventListener("click", () => selectRun(record.runId));
+    list.appendChild(btn);
   }
 }
 
-async function selectRun(runId) {
+// Move the "active" highlight to the chosen run's button WITHOUT rebuilding
+// the list. Rebuilding (the old `loadIndex()` call in selectRun) removed the
+// very <button> the user had just clicked/Entered, dropping keyboard focus to
+// <body> and flashing the whole sidebar on every selection.
+function markActiveRow(runId) {
+  const list = document.getElementById("run-list");
+  for (const btn of list.querySelectorAll("button[data-runid]")) {
+    btn.classList.toggle("active", btn.getAttribute("data-runid") === runId);
+  }
+}
+
+function selectRun(runId) {
   state.activeRunId = runId;
-  loadIndex();
+  markActiveRow(runId);
+  return loadRunDetail(runId);
+}
+
+async function loadRunDetail(runId) {
   const detail = document.getElementById("run-panel");
   detail.innerHTML = "";
   detail.appendChild(el("p", { class: "muted", text: `loading ${runId}…` }));
   let view;
   try {
-    view = await getJson(`/api/run/${encodeURIComponent(runId)}`);
+    view = await getJson(apiUrl(`/api/run/${encodeURIComponent(runId)}`));
   } catch (error) {
+    if (state.activeRunId !== runId) return;
     detail.innerHTML = "";
     detail.appendChild(el("p", { class: "err", text: `failed to load run: ${error.message}` }));
     return;
   }
+  // The user may have clicked another run while this fetch was in flight;
+  // a stale response must not overwrite the newer selection's render.
+  if (state.activeRunId !== runId) return;
+  state.viewFetchedAt = new Date();
   renderRun(view);
 }
 
+// The refresh button re-derives BOTH panes from disk: the sidebar index AND
+// the currently-open run's detail. Refreshing only the index (the old
+// behavior) left the detail header's lifecycle badge showing stale state
+// while the sidebar dot next to it had already changed.
+function refreshAll() {
+  loadIndex();
+  if (state.activeRunId) loadRunDetail(state.activeRunId);
+}
+
+function formatClock(date) {
+  return date ? date.toTimeString().slice(0, 8) : "";
+}
+
 function renderRun(view) {
   const detail = document.getElementById("run-panel");
   detail.innerHTML = "";
@@ -109,12 +205,29 @@ function renderRun(view) {
     el("span", {}, [el("b", { text: "run " }), document.createTextNode(view.runId)]),
     el("span", {}, [document.createTextNode("resolved "), freshnessBadge(view.resolved ? "valid" : "missing")])
   ]);
+  if (view.lifecycle) {
+    header.appendChild(el("span", {}, [document.createTextNode("lifecycle "), freshnessBadge(view.lifecycle)]));
+  }
+  if (state.viewFetchedAt) {
+    header.appendChild(el("span", { class: "muted", text: `as of ${formatClock(state.viewFetchedAt)}` }));
+  }
   if (view.error) header.appendChild(el("span", { class: "err", text: view.error }));
   detail.appendChild(header);
+  if (view.lifecycle === "blocked" || view.lifecycle === "failed") {
+    detail.appendChild(
+      el("p", { class: "recovery-hint", text: `${view.lifecycle} — run 'cw run status ${view.runId}' or 'cw doctor' for next steps` })
+    );
+  }
 
-  const tabs = el("div", { class: "tabs" });
+  const tabs = el("div", { class: "tabs", role: "tablist" });
   for (const group of PANEL_GROUPS) {
-    const btn = el("button", { class: `tab ${state.activeTab === group.key ? "active" : ""}`, text: group.label });
+    const active = state.activeTab === group.key;
+    const btn = el("button", {
+      class: `tab ${active ? "active" : ""}`,
+      text: group.label,
+      role: "tab",
+      "aria-selected": active ? "true" : "false"
+    });
     btn.addEventListener("click", () => {
       state.activeTab = group.key;
       renderRun(view);
@@ -125,9 +238,21 @@ function renderRun(view) {
 
   const group = PANEL_GROUPS.find((g) => g.key === state.activeTab) || PANEL_GROUPS[0];
   const panels = (view.panels && view.panels[group.key]) || {};
+  // Some groups declare two panel names that map to the same capability on
+  // the server (e.g. graph's compact/criticalPath both come from
+  // summary.show), so they carry byte-identical payloads. Render such a pair
+  // ONCE under a merged label instead of showing the same JSON twice under
+  // two names that promise distinct views.
+  const rendered = [];
   for (const name of group.panels) {
     const panel = panels[name];
-    if (panel) detail.appendChild(renderPanel(name, panel));
+    if (!panel) continue;
+    const twin = rendered.find((entry) => JSON.stringify(entry.panel) === JSON.stringify(panel));
+    if (twin) twin.names.push(name);
+    else rendered.push({ names: [name], panel });
+  }
+  for (const entry of rendered) {
+    detail.appendChild(renderPanel(entry.names.join(" / "), entry.panel));
   }
 }
 
@@ -173,17 +298,27 @@ function renderStructured(data) {
   return null;
 }
 
+// A semantically-correct data table: header cells in a <thead> with
+// scope="col", body rows in a <tbody> — screen readers can then associate
+// each cell with its column header.
+function structTable(headers) {
+  const table = el("table", { class: "struct-table" }, [
+    el("thead", {}, [el("tr", {}, headers.map((h) => el("th", { scope: "col", text: h })))])
+  ]);
+  const tbody = el("tbody");
+  table.appendChild(tbody);
+  return { table, tbody };
+}
+
 function renderGraph(data) {
   const wrap = el("div");
   const nodesBlock = el("div", { class: "struct-block" }, [el("div", { class: "struct-title", text: `nodes (${data.nodes.length})` })]);
   if (data.nodes.length === 0) {
     nodesBlock.appendChild(el("div", { class: "struct-empty", text: "none" }));
   } else {
-    const table = el("table", { class: "struct-table" }, [
-      el("tr", {}, ["id", "kind", "status", "label"].map((h) => el("th", { text: h })))
-    ]);
+    const { table, tbody } = structTable(["id", "kind", "status", "label"]);
     for (const node of data.nodes) {
-      table.appendChild(
+      tbody.appendChild(
         el("tr", {}, [
           el("td", { text: node.id }),
           el("td", { text: node.kind }),
@@ -235,11 +370,9 @@ function renderEventGroups(data, confirmedEventKeys) {
   for (const key of eventKeys) {
     const events = [...data[key]].sort((a, b) => String(a.createdAt || "").localeCompare(String(b.createdAt || "")));
     const block = el("div", { class: "struct-block" }, [el("div", { class: "struct-title", text: `${humanizeKey(key)} (${events.length})` })]);
-    const table = el("table", { class: "struct-table" }, [
-      el("tr", {}, ["time", "kind", "decision", "source", "actor"].map((h) => el("th", { text: h })))
-    ]);
+    const { table, tbody } = structTable(["time", "kind", "decision", "source", "actor"]);
     for (const event of events) {
-      table.appendChild(
+      tbody.appendChild(
         el("tr", {}, [
           el("td", { text: event.createdAt || "" }),
           el("td", { text: event.kind || "" }),
@@ -263,7 +396,7 @@ function renderEventGroups(data, confirmedEventKeys) {
   return wrap;
 }
 
-document.getElementById("refresh").addEventListener("click", loadIndex);
+document.getElementById("refresh").addEventListener("click", refreshAll);
 document.getElementById("filter").addEventListener("input", debounce(loadIndex, 200));
 
 function debounce(fn, ms) {

package/ui/workbench/index.html

@@ -16,10 +16,10 @@
     <main>
       <section id="index-panel" class="sidebar">
         <div class="bar">
-          <strong>Runs</strong>
+          <h2>Runs</h2>
           <button id="refresh" title="Re-derive from disk">refresh</button>
         </div>
-        <input id="filter" type="search" placeholder="filter runs (app/status/text)" />
+        <input id="filter" type="search" placeholder="filter runs (app/status/text)" aria-label="filter runs" />
         <div id="registry-freshness" class="freshness"></div>
         <ul id="run-list" class="run-list"></ul>
       </section>

package/docs/agent-framework.md

@@ -1,177 +0,0 @@
-# Workflow App framework
-
-CW is made as an independent agent workflow control-plane.
-
-The aim is to make agent development feel like building inside a platform
-ecosystem. CW gives the runtime, contracts, storage, CLI, MCP bridge, and
-package structure. Developers make workflow apps that keep to those contracts.
-
-The framework is guided by five useful systems rules: small kernel, explicit
-state, pipes you can put together, separate workers, and commits that a verifier
-lets through. See
-[unix-principles.md](unix-principles.md).
-
-## Platform Contract
-
-Every CW workflow keeps to this loop:
-
-```text
-interpret -> act -> observe -> adjust -> checkpoint
-```
-
-The loop maps to real framework operations:
-
-| Loop stage | framework operation | Responsibility |
-| --- | --- | --- |
-| Interpret | `plan()` | Load workflow, check inputs, make tasks |
-| Act | `dispatch()` | Move tasks that can run from pending to running |
-| Observe | `recordResult()` | Read Markdown/JSON-RPC result evidence |
-| Adjust | verifier gates | Check evidence and pick the next phase |
-| Checkpoint | `commitState()` | Take a snapshot of state after important changes |
-
-The v0.1.12 operator UX layer makes read-only summaries over run state:
-human `status`, graph maps, report summaries, resource summaries, and
-fixed next-step suggestions. Scripts can go on using `--json` or
-`--format json`.
-
-The v0.1.13 MCP app surface gives the same runtime operations to agent hosts
-with stable JSON tools: app run, dispatch, worker inspection/output, candidate
-scoring/selection, sandbox profile resolution, verifier-gated commit, and
-operator status/graph/report summaries.
-
-The v0.1.13 canonical app matrix checks and plans the kept userland
-apps with public CLI commands:
-
-```bash
-npm run canonical-apps
-```
-
-The golden path runs the full integration chain from start to end:
-
-```bash
-npm run golden-path
-```
-
-It checks an app, plans a run, dispatches a readonly worker, takes a
-worker-local `cw:result`, scores and picks a candidate, makes a
-verifier-gated commit, and makes a report. See
-[end-to-end-golden-path.7.md](end-to-end-golden-path.7.md).
-
-## Developer Contract
-
-A workflow app defines:
-
-- `id`, `title`, and `summary`
-- `schemaVersion`, app `version`, compatibility, and metadata when using the
-  first-class Workflow App framework contract
-- needed and repeated inputs
-- phase order
-- agent tasks
-- artifact tasks
-- concurrency limits
-- evidence requirements
-- sandbox profile hints
-
-Example:
-
-```js
-const {
-  defineWorkflowApp,
-  workflow,
-  phase,
-  agent,
-  artifact,
-  input
-} = require("../dist/workflow-app-framework");
-
-const inputs = [input("repo", { type: "path", required: true })];
-
-module.exports = defineWorkflowApp({
-  schemaVersion: 1,
-  id: "example-review",
-  title: "Example Review",
-  summary: "Review a repository with evidence.",
-  version: "0.1.0",
-  inputs,
-  sandboxProfiles: ["readonly"],
-  compatibility: {
-    minVersion: "0.1.9"
-  },
-  workflow: workflow({
-    id: "example-review",
-    title: "Example Review",
-    inputs,
-    sandboxProfiles: ["readonly"],
-    phases: [
-      phase("Map", [
-        agent("map:system", "Map the system boundaries.", {
-          sandboxProfileId: "readonly"
-        })
-      ]),
-      phase("Verdict", [
-        artifact("verdict", "Write the final evidence-backed verdict.", {
-          requiresEvidence: true,
-          sandboxProfileId: "readonly"
-        })
-      ])
-    ]
-  })
-});
-```
-
-Legacy `module.exports = ({ workflow, phase, agent, artifact }) => workflow(...)`
-files can still be loaded. CW wraps them as compatibility apps with version `0.0.0`
-so workflow files still plan and dispatch. When a canonical app owns the public
-id, compatibility wrappers use explicit ids such as `legacy-research-synthesis`.
-
-## Language Contract
-
-The CW platform is TypeScript:
-
-```text
-src/*.ts -> dist/*.js
-```
-
-Workflow apps are JavaScript modules:
-
-```text
-workflows/*.workflow.js
-apps/<app-id>/app.json
-apps/<app-id>/workflow.js
-```
-
-This is done on purpose. The runtime is strongly typed so it is simple to keep
-up, while workflow scripts can run without `ts-node`.
-
-See [workflow-app-framework.7.md](workflow-app-framework.7.md) for the full app contract,
-the rules for checking, CLI commands, MCP tools, and state/report fields.
-See [mcp-app-surface.7.md](mcp-app-surface.7.md) for the agent-host runtime
-surface over MCP.
-See [operator-ux.7.md](operator-ux.7.md) for the operator inspection surface.
-See [canonical-workflow-apps.7.md](canonical-workflow-apps.7.md) for the
-official app matrix.
-See [end-to-end-golden-path.7.md](end-to-end-golden-path.7.md) for the
-fixed release proof that those parts connect.
-
-## Evidence Contract
-
-Verification and verdict tasks should give back:
-
-````text
-```cw:result
-{
-  "summary": "short summary",
-  "findings": [],
-  "evidence": ["/absolute/path/file.ts:42"]
-}
-```
-````
-
-CW says no to high-priority findings without evidence. This keeps agent work
-nearer to engineering output you can look into than to free talk.
-
-## Boundary
-
-CW is an independent workflow control-plane by COOLWHITE LLC. It puts into effect
-workflows that change, scheduled tasks, local scheduling, routine triggers, state
-checkpoints, and multi-agent verification.

package/docs/designs/handoff-ledger.md

@@ -1,145 +0,0 @@
-# Design — Cross-agent handoff ledger
-
-Status: DRAFT / proposal. Nothing here is built yet. This file ships no
-behavior, no new command, no man-page contract, and changes no existing
-output. It exists so two people (the operator and the reviewer agent) can
-agree on the shape before any code is written.
-
-North Star track: **Track B** (portable, verifiable state — the same
-`run export` → `run restore` recovery story, now used as the channel
-between two agents).
-
-## Goal
-
-Two agents work on two repositories:
-
-- one agent scoped to repo **A** (for example `cool-workflow`),
-- one agent scoped to repo **B** (for example `chime`).
-
-The operator wants them to "share data, review each other, and each be
-able to raise a pull request to the other". In plain terms:
-
-- each side can hand the other a **change proposal**, and
-- each side can hand the other a **review verdict** on a diff or PR,
-- with saved, inspectable, fail-closed state — never a fabricated hand-off.
-
-## The hard constraint (why the obvious design does not work)
-
-The first idea is a shared local folder (for example `~/.chime/handoff/`)
-that both agents read and append to. That only works when both agents run
-on **one machine** with **one filesystem**.
-
-In the operator's setup the two agents run as **two separate cloud
-sessions**. Each session is a fresh, throwaway VM. Two facts follow, and
-the design must respect both:
-
-1. **No shared filesystem.** A file the B-agent writes to `~/.chime/handoff/`
-   in its VM is invisible to the A-agent's VM, and is gone when the session
-   ends. A local folder cannot be the channel.
-2. **Single-repo scope.** Each session's GitHub reach is scoped to one repo
-   at launch (A-agent → repo A, B-agent → repo B). The A-agent cannot read
-   repo B through its GitHub tools, and the reverse is also true. Scope is
-   fixed at launch and cannot be widened mid-session.
-
-The only medium both sessions can durably reach is **git / GitHub**. So the
-ledger is a set of committed files, not a local folder — and the scope wall
-means the hand-off still needs either a shared repo or a human relay for the
-cross-repo step. This document is honest about that; it does not pretend the
-wall is not there.
-
-## What we reuse (no new trust machinery)
-
-CW already has the parts this needs. The design adds a thin verb layer over
-them; it invents no new crypto and no new state format.
-
-- `run export` produces a **verifiable bundle** (file digests, telemetry
-  ledger, trust-audit hash chains).
-- `run restore` **imports fail-closed**: it inspects first, refuses a corrupt
-  or tampered bundle without writing anything, and exits non-zero when the
-  chain does not verify. (`run import` is the exit-0 sibling; the hand-off
-  path must use the fail-closed `restore` contract.)
-- `report verify` checks a run's evidence and citations.
-
-A hand-off entry is therefore just a CW bundle. The receiving side trusts it
-the same way it trusts any restored run: by verification, not by good faith.
-
-## Two verbs
-
-Both live under a single new `cw ledger` verb, so the existing surface is
-untouched and the new behavior is opt-in (POLA). (The name `handoff` was already
-taken by an unrelated collaboration primitive — ownership transfer of a run/task
-— so the cross-agent verb is `ledger`, not `handoff`.) Stage 1 ships as
-`cw ledger propose|review|verify`; see
-[cross-agent-ledger](../cross-agent-ledger.7.md) for the contract.
-
-- **`propose`** — the read-only side writes a structured *change proposal*
-  (title, rationale, target files, suggested diff) as a ledger entry. It does
-  **not** mutate the other repo. The write-capable side picks the entry up,
-  verifies it, and turns it into a **real GitHub pull request**.
-- **`review`** — the reviewing side writes a structured *review verdict*
-  (`APPROVED` / `REJECTED`, findings, the diff or PR it judged) as a ledger
-  entry. The other side surfaces it and can act on it.
-
-This keeps a read-only agent honest: it emits proposals and verdicts as
-**data**, and the write-capable side is the only one that opens PRs. Neither
-side has to be trusted to have mutated the other's code.
-
-## Transports (how an entry actually crosses)
-
-The verbs above produce and consume entries; the transport is how an entry
-moves from one VM to the other. Two are in scope, smallest first.
-
-- **T1 — Human relay (MVP, works today, zero infra).** The producing side
-  prints the entry (a verifiable bundle, or its safe text form) to stdout;
-  the operator carries it to the other session; the consuming side verifies
-  it fail-closed and acts (opens the PR, or records the verdict). This is
-  exactly the loop the operator is already running by hand. It needs no new
-  code beyond a stable print/parse shape.
-- **T2 — Git-as-ledger.** Each entry is committed to a repo under a known
-  path (for example `handoff/<from>-<to>/<id>.bundle`). Because scope is
-  single-repo, this needs one of:
-  - **T2a — a shared handoff repo** both agents are scoped to (cleanest, but
-    the operator must create it and launch both sessions against it), or
-  - **T2b — each side writes to its own repo** and a bridge (the operator, or
-    a scheduled job that *is* scoped to both) moves entries across. The
-    cross-repo read cannot be automatic inside a single scoped session — this
-    is the scope wall, stated plainly, not a gap to be quietly filled.
-
-## Fail-closed rules (non-negotiable)
-
-- An entry that does not verify is **refused**, never acted on. No PR is
-  opened, no verdict is recorded, and the refusal is explicit on stderr with
-  a non-zero exit — the same contract as `run restore`.
-- A proposal is a **suggestion only**. It never edits the target repo by
-  itself; a human-or-agent on the write side always makes the real PR, so the
-  read-only vow of the proposing side holds.
-- stdout stays data (the entry / the machine result); stderr stays
-  diagnostics; a piped run is silent on success. `--json` is stable and
-  decoration-free.
-
-## Non-goals / POLA
-
-- No existing command, output byte, exit code, or file layout changes.
-- No new runtime dependency (zero-dependency red line holds).
-- No vendor-specific logic in core; the verbs move opaque bundles.
-- Nothing ships until its own cycle lands with a test that fails before and
-  passes after, and a `docs/*.7.md` contract page — this design file is not
-  that contract and claims no shipped behavior.
-
-## Suggested rollout (each stage its own reviewed cycle)
-
-0. **This design doc** (no behavior). ← you are here.
-1. **T1 human-relay shape** — a stable, documented print/parse form for a
-   proposal and a verdict, plus a smoke that round-trips one of each and
-   proves a tampered entry is refused.
-2. **`cw ledger propose` / `review`** over `run export` / `restore`, with the
-   fail-closed refusal test.
-3. **T2 git-ledger** (shared-repo first), then optionally a scoped bridge job
-   for T2b.
-
-## Open decisions for the operator
-
-- T2a (shared handoff repo) or T2b (own repos + bridge)? T2a is simpler and
-  should be the default unless a shared repo is not acceptable.
-- Should a verdict be able to **block** a PR merge on the other side, or only
-  advise? Advise-only is the safer default and matches "review as data".

package/docs/dogfood/resume-drive-real-agent-2026-06-14.md

@@ -1,40 +0,0 @@
-# Dogfood: real `builtin:claude` agent + `run resume --drive` (2026-06-14)
-
-A live dogfood run with a REAL external agent (`CW_AGENT_COMMAND=builtin:claude`, the
-bundled read-only claude wrapper). The model ran in the agent's own process; CW
-spawned it and recorded the attested output — CW holds no API key and imports no
-model SDK. This run had two purposes and delivered both: it confirmed the real-agent
-delegation path works end to end, and — because it exercised the **CLI** rather than
-the unit-test function path — it **caught a real shipped bug** in `run resume --drive`.
-
-## What ran
-
-- `cw run architecture-review --drive --once --repo <tmp> --question "…"` with a real
-  `builtin:claude` agent: **1 worker completed** end-to-end with zero hand-written
-  result.md — the worker's `result.md` was produced by real claude, passed the
-  evidence-gated acceptance, and a `report.md` (7.5 KB, "# Architecture Review …")
-  + 3 state commits were written. The real-agent path (spawn → attested output →
-  evidence gate → commit) works.
-- Run: `architecture-review-20260614T104416Z-upkor2`, status `in-progress` (1/14)
-  after the single `--once` step.
-
-## The bug it caught (and the fix)
-
-Resuming the partway run with `cw run resume <id> --drive` failed:
-`cw: Workflow app not found: resume`. The `run` command's early `--drive` branch
-(the `cw run <app> --drive` one-command form) intercepted the invocation *before* the
-subcommand switch, so the `resume` keyword was misread as an app name and never
-reached the `runResume` continuation shipped in #155.
-
-The A1 unit smoke (`run-resume-drive-smoke`) had tested `runResume()` **directly**, so
-it never exercised the CLI dispatch — only a real CLI run surfaced it. Fixed by
-guarding the early app-drive route so a leading run-registry subcommand keyword
-(resume/show/export/…) falls through to the switch; `run-resume-drive-smoke` now drives
-`cw run resume <id> --drive` through the actual CLI and asserts it routes to the verb,
-plus a regression guard that `run <app> --drive` still routes to the app drive.
-
-## Takeaway
-
-Unit tests that call the capability function directly can miss CLI-dispatch bugs.
-Every both-surface verb that adds a flag wants at least one test through the real CLI
-argv path, not just the exported function.