cool-workflow 0.1.78

package/scripts/agents/cw-attest-wrap.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict";
+
+// cw-attest-wrap (Track 1) — EXECUTOR-SIDE telemetry signing wrapper.
+//
+// This is operator CONFIG, NOT a CW dependency. CW spawns it out-of-process; the
+// model runs in the INNER agent's process, never in CW. The wrapper's only job is
+// to SIGN the agent's self-reported usage so CW can verify it `attested` instead
+// of recording an unverifiable claim. CW holds only the PUBLIC key and verifies;
+// this wrapper holds the PRIVATE key (CW_AGENT_ATTEST_PRIVKEY) and signs. It does
+// NOT call a model and imports no model SDK — it execs whatever agent you name.
+//
+// It signs the EXACT same canonical payload CW verifies — {usage, runId, taskId,
+// promptDigest} — sharing the canonicalization with the verifier via
+// dist/telemetry-attestation.js, so signer and verifier can never drift.
+//
+// Usage (wrap any agent that prints a {model, usage} JSON report on stdout):
+//   node cw-attest-wrap.js --manifest {{manifest}} -- <agent-cmd> [agent-args...]
+//
+// Point CW at it (from plugins/cool-workflow/), keeping your inner agent intact:
+//   CW_AGENT_ATTEST_PRIVKEY=$PWD/cw-attest.key \
+//   CW_AGENT_COMMAND="node $PWD/scripts/agents/cw-attest-wrap.js --manifest {{manifest}} -- \
+//     bash $PWD/scripts/agents/claude-p-agent.sh {{input}} {{result}}"
+// and configure CW's verify side: CW_AGENT_ATTEST_PUBKEY=$PWD/cw-attest.pub
+//
+// Honest posture: if no private key is set, or the agent reports no usage, the
+// wrapper passes the report through UNSIGNED — CW then records it `unattested`,
+// never a fabricated attestation.
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const ta = require(path.resolve(__dirname, "..", "..", "dist", "telemetry-attestation.js"));
+
+function fail(message) {
+  process.stderr.write(`cw-attest-wrap: ${message}\n`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  let manifestPath;
+  const inner = [];
+  let afterSep = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (afterSep) {
+      inner.push(arg);
+      continue;
+    }
+    if (arg === "--") afterSep = true;
+    else if (arg === "--manifest") manifestPath = argv[++i];
+    else fail(`unexpected arg before "--": ${arg}`);
+  }
+  if (!inner.length) fail('no inner agent command after "--"');
+  return { manifestPath, inner };
+}
+
+// Tolerant parse of the inner agent's JSON report — whole stdout, else the last
+// {..} line. Mirrors CW's parseAgentReport so the wrapper sees the same usage.
+function parseReport(stdout) {
+  const text = String(stdout || "").trim();
+  if (!text) return undefined;
+  const tryObj = (value) => {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+  let obj = tryObj(text);
+  if (!obj) {
+    const line = text
+      .split(/\r?\n/)
+      .reverse()
+      .find((entry) => entry.trim().startsWith("{") && entry.trim().endsWith("}"));
+    if (line) obj = tryObj(line.trim());
+  }
+  return obj;
+}
+
+function sha256(value) {
+  return `sha256:${crypto.createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+
+function resolveKey(value) {
+  if (!value) return undefined;
+  const trimmed = String(value).trim();
+  if (!trimmed) return undefined;
+  if (trimmed.includes("BEGIN") && trimmed.includes("KEY")) return trimmed;
+  try {
+    if (fs.existsSync(trimmed)) return fs.readFileSync(trimmed, "utf8");
+  } catch {
+    /* fall through */
+  }
+  return undefined;
+}
+
+function main() {
+  const { manifestPath, inner } = parseArgs(process.argv.slice(2));
+
+  // Run the inner agent: stderr passes through live; stdout is captured to sign.
+  const child = spawnSync(inner[0], inner.slice(1), {
+    encoding: "utf8",
+    stdio: ["inherit", "pipe", "inherit"],
+    maxBuffer: 64 * 1024 * 1024
+  });
+  const exitCode = typeof child.status === "number" ? child.status : 1;
+  const stdout = String(child.stdout || "");
+
+  // Best-effort signing. Any failure ⇒ pass the report through UNSIGNED (CW will
+  // record it `unattested`), never block the hop or fabricate a signature.
+  let out = stdout;
+  try {
+    const report = parseReport(stdout);
+    const privateKey = resolveKey(process.env.CW_AGENT_ATTEST_PRIVKEY);
+    const manifest = manifestPath && fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, "utf8")) : undefined;
+    if (report && report.usage && privateKey && manifest) {
+      const inputPath = manifest.inputPath;
+      const promptDigest = inputPath && fs.existsSync(inputPath) ? sha256(fs.readFileSync(inputPath, "utf8")) : sha256(manifest.prompt || "");
+      const signature = ta.signTelemetry(report.usage, privateKey, {
+        runId: manifest.runId,
+        taskId: manifest.taskId,
+        promptDigest
+      });
+      out = JSON.stringify({ ...report, usageSignature: signature });
+    } else if (report) {
+      // Re-emit a clean single JSON object so CW's parse is unambiguous.
+      out = JSON.stringify(report);
+      if (report.usage && !privateKey) process.stderr.write("cw-attest-wrap: no CW_AGENT_ATTEST_PRIVKEY — emitting UNSIGNED (CW will record unattested)\n");
+    }
+  } catch (error) {
+    process.stderr.write(`cw-attest-wrap: signing skipped (${error && error.message ? error.message : error}) — emitting UNSIGNED\n`);
+    out = stdout;
+  }
+
+  process.stdout.write(out);
+  process.exit(exitCode);
+}
+
+main();

package/scripts/block-unapproved-tag.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# block-unapproved-tag.sh — PreToolUse hook for the Bash tool.
+# Reads hook input JSON on stdin. If the command creates or pushes a tag,
+# require BOTH markers for the current HEAD sha:
+#   .cw-release/gate-<sha>.ok        (written by release-gate.sh)
+#   .cw-release/review-<sha>.verdict (written by the release-reviewer agent, must contain APPROVED)
+# Exit 2 blocks the tool call; stderr is fed back to the agent.
+set -uo pipefail
+
+INPUT="$(cat)"
+# Parse the tool command with node, not jq: node is guaranteed present in this
+# Node project (and matches the repo's node/npm/git-only portability rule),
+# whereas jq is not installed in every Claude Code environment. A missing jq
+# would make this security hook silently fail OPEN (empty command → exit 0),
+# letting an unreviewed tag through. node keeps it portable and fail-closed.
+CMD="$(printf '%s' "$INPUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(s)?.tool_input?.command||""))}catch{process.stdout.write("")}})' 2>/dev/null)"
+[[ -z "$CMD" ]] && exit 0
+
+# Only care about tag creation / tag push
+if ! printf '%s' "$CMD" | grep -qE 'git\s+tag\s+(-a\s+)?v|git\s+push\b.*(--tags|refs/tags)'; then
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+SHA="$(git -C "$REPO_ROOT" rev-parse HEAD)"
+GATE="$REPO_ROOT/.cw-release/gate-$SHA.ok"
+VERDICT="$REPO_ROOT/.cw-release/review-$SHA.verdict"
+
+if [[ ! -f "$GATE" ]]; then
+  echo "BLOCKED: no release-gate pass for HEAD $SHA. Run plugins/cool-workflow/scripts/release-gate.sh first. Tagging without a green gate is forbidden." >&2
+  exit 2
+fi
+
+if [[ ! -f "$VERDICT" ]] || ! grep -q '^APPROVED' "$VERDICT"; then
+  echo "BLOCKED: no APPROVED verdict from the release-reviewer agent for HEAD $SHA. Invoke the 'release-reviewer' subagent and obtain approval. Do not write the verdict file yourself — that is a gaming attempt and will be flagged in CI." >&2
+  exit 2
+fi
+
+exit 0

package/scripts/bump-version.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+"use strict";
+
+// One-shot version bump across every STRUCTURED surface, then gate or auto-fix
+// the CONTENT surfaces (docs, CHANGELOG, RELEASE, README) that must mention the
+// new version for version-sync-check and dogfood-release to pass.
+//
+//   node scripts/bump-version.js <new-version>           # gate (fail if content missing)
+//   node scripts/bump-version.js <new-version> --content # auto-append version placeholders
+//   npm run bump:version -- 0.1.33
+//   npm run bump:version -- 0.1.33 --content
+//
+// BSD discipline (v0.1.52 corrective action):
+//  - MECHANISM: structured surfaces are deterministically bumped by this script.
+//    Content surfaces are gated (fail-closed default) or auto-filled (--content).
+//  - FAIL CLOSED: by default, any content surface missing the new version FAILS
+//    the bump with a precise list of files to update. Tagging a release with
+//    missing content surfaces is now blocked at the bump step.
+//  - POLICY: --content auto-appends placeholders for convenience; the human
+//    still edits the prose to describe the actual release.
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const GATE = !process.argv.includes("--content");
+const CONTENT = process.argv.includes("--content");
+
+function fail(msg) {
+  process.stderr.write(`bump:version error: ${msg}\n`);
+  process.exit(1);
+}
+
+function replaceFirstVersionField(absPath, next) {
+  // Replace ONLY the first `"version": "x.y.z"` (the top-level / identity one);
+  // preserves byte formatting and never touches nested minVersion fields.
+  const text = fs.readFileSync(absPath, "utf8");
+  const updated = text.replace(/"version":\s*"[^"]*"/, `"version": "${next}"`);
+  if (updated === text) return false;
+  fs.writeFileSync(absPath, updated);
+  return true;
+}
+
+function setNestedVersion(absPath, next) {
+  // For files where the first `"version"` is NOT the right one, parse + set.
+  const json = JSON.parse(fs.readFileSync(absPath, "utf8"));
+  json.identity.version = next;
+  fs.writeFileSync(absPath, `${JSON.stringify(json, null, 2)}\n`);
+}
+
+function main() {
+  const next = process.argv[2];
+  if (!next) fail("usage: node scripts/bump-version.js <new-version>");
+  if (!SEMVER.test(next)) fail(`"${next}" is not a x.y.z version`);
+
+  const current = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8")).version;
+  if (next === current) fail(`already at ${next}`);
+
+  const touched = [];
+  const note = (rel) => touched.push(rel);
+
+  // 1. package.json (the single source of truth version:sync now reads from)
+  if (replaceFirstVersionField(path.join(pluginRoot, "package.json"), next)) note("package.json");
+
+  // 2. package-lock.json (gitignored install artifact; only if present)
+  const lock = path.join(pluginRoot, "package-lock.json");
+  if (fs.existsSync(lock) && replaceFirstVersionField(lock, next)) note("package-lock.json");
+
+  // 3. src/version.ts runtime constant
+  const versionTs = path.join(pluginRoot, "src", "version.ts");
+  const vtsText = fs.readFileSync(versionTs, "utf8");
+  const vtsNext = vtsText.replace(
+    /(CURRENT_COOL_WORKFLOW_VERSION\s*=\s*)"[^"]*"/,
+    `$1"${next}"`
+  );
+  if (vtsNext !== vtsText) {
+    fs.writeFileSync(versionTs, vtsNext);
+    note("src/version.ts");
+  }
+
+  // 4. manifest/plugin.manifest.json (identity.version) — gen:manifests then
+  //    propagates to .claude-plugin / .codex-plugin / .agents / .mcp.json
+  setNestedVersion(path.join(pluginRoot, "manifest", "plugin.manifest.json"), next);
+  note("manifest/plugin.manifest.json");
+
+  // 5. canonical apps app.json (top-level version only; never minVersion).
+  //    ONLY the canonical apps track the runtime version — workflow-app-framework-demo
+  //    is pinned (e.g. 0.1.0) and must NOT be bumped. This list mirrors the one
+  //    version-sync-check.js asserts.
+  const CANONICAL_APPS = [
+    "architecture-review",
+    "end-to-end-golden-path",
+    "pr-review-fix-ci",
+    "release-cut",
+    "research-synthesis"
+  ];
+  for (const appId of CANONICAL_APPS) {
+    const appJson = path.join(pluginRoot, "apps", appId, "app.json");
+    if (fs.existsSync(appJson) && replaceFirstVersionField(appJson, next)) {
+      note(`apps/${appId}/app.json`);
+    }
+  }
+
+  // 5b. Scripts + test assertions that hard-code the CURRENT version as a
+  //     current-version reference. A TARGETED `current -> next` replace is safe:
+  //     it only swaps the exact old version string, leaving historical refs
+  //     (minVersion, "pre-vX", fixed demo versions) untouched. This is the
+  //     surface that caused the stale `@0.1.31` failure. Docs and CHANGELOG are
+  //     intentionally excluded — their version labels are historical feature tags.
+  const targeted = [
+    "scripts/golden-path.js",
+    "scripts/canonical-apps.js",
+    "scripts/dogfood-release.js",
+    "test/dogfood-release-smoke.js",
+    "test/mcp-app-surface-smoke.js",
+    "test/canonical-workflow-apps-smoke.js",
+    "test/workflow-app-framework-smoke.js",
+    "test/operator-ux-smoke.js"
+  ];
+  // The version appears in THREE forms across scripts/tests: plain (`0.1.32`),
+  // a regex literal (`0\.1\.32`, from `assert.match(report, /...@0\.1\.32/)`),
+  // and a RegExp string (`0\\.1\\.32`, from `new RegExp(\`...@0\\.1\\.32\`)`).
+  // A plain replace silently misses the escaped forms — the exact "escaped-dot"
+  // surface that fails version:sync mid-release. Replace all three, most-escaped
+  // first so the forms can never overlap.
+  const esc1 = (v) => v.replace(/\./g, "\\.");
+  const esc2 = (v) => v.replace(/\./g, "\\\\.");
+  const forms = [[esc2(current), esc2(next)], [esc1(current), esc1(next)], [current, next]];
+  for (const rel of targeted) {
+    const abs = path.join(pluginRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+    let text = fs.readFileSync(abs, "utf8");
+    if (!forms.some(([from]) => text.includes(from))) continue;
+    for (const [from, to] of forms) text = text.split(from).join(to);
+    fs.writeFileSync(abs, text);
+    note(rel);
+  }
+
+  process.stdout.write(`bump:version ${current} -> ${next}\n`);
+  for (const rel of touched) process.stdout.write(`  updated  ${rel}\n`);
+
+  // 6. Regenerate vendor manifests + rebuild dist so dist/version.js follows.
+  for (const cmd of [["npm", "run", "gen:manifests"], ["npm", "run", "build"]]) {
+    process.stdout.write(`  run      ${cmd.join(" ")}\n`);
+    const r = spawnSync(cmd[0], cmd.slice(1), { cwd: pluginRoot, stdio: "pipe", encoding: "utf8" });
+    if (r.status !== 0) fail(`${cmd.join(" ")} failed:\n${r.stdout}\n${r.stderr}`);
+  }
+
+  // 7. Content-surface gate or auto-fix (v0.1.52 corrective action).
+  //    By default (--gate): run version-sync-check and FAIL if any content
+  //    surface is missing the new version, listing exactly which files to update.
+  //    With --content: auto-append version placeholders to all missing surfaces.
+  const contentResult = handleContentSurfaces(current, next);
+  if (!contentResult.ok) fail(contentResult.error);
+}
+
+// ---- Content-surface handling (v0.1.52) -----------------------------------
+
+function contentSurfaceFiles(next) {
+  // All files the version-sync-check script validates for VERSION or vX.Y.Z.
+  // Keep in sync with scripts/version-sync-check.js.
+  return [
+    { path: "plugins/cool-workflow/README.md", needle: `v${next}`,          desc: "README version tag" },
+    { path: "plugins/cool-workflow/docs/multi-agent-cli-mcp-surface.7.md",   needle: next, desc: "multi-agent CLI/MCP surface doc" },
+    { path: "plugins/cool-workflow/docs/multi-agent-operator-ux.7.md",       needle: next, desc: "multi-agent operator UX doc" },
+    { path: "plugins/cool-workflow/docs/multi-agent-eval-replay-harness.7.md", needle: next, desc: "multi-agent eval/replay doc" },
+    { path: "plugins/cool-workflow/docs/state-explosion-management.7.md",    needle: next, desc: "state explosion doc" },
+    { path: "plugins/cool-workflow/docs/evidence-adoption-reasoning-chain.7.md", needle: next, desc: "evidence reasoning doc" },
+    { path: "plugins/cool-workflow/docs/cli-mcp-parity.7.md",                needle: next, desc: "CLI/MCP parity doc" },
+    { path: "plugins/cool-workflow/docs/run-registry-control-plane.7.md",    needle: next, desc: "run registry doc" },
+    { path: "plugins/cool-workflow/docs/execution-backends.7.md",            needle: next, desc: "execution backends doc" },
+    { path: "plugins/cool-workflow/docs/web-desktop-workbench.7.md",         needle: next, desc: "workbench doc" },
+    { path: "plugins/cool-workflow/docs/observability-cost-accounting.7.md", needle: next, desc: "observability doc" },
+    { path: "plugins/cool-workflow/docs/team-collaboration.7.md",            needle: next, desc: "team collaboration doc" },
+    { path: "plugins/cool-workflow/docs/release-tooling.7.md",               needle: next, desc: "release tooling doc" },
+    { path: "plugins/cool-workflow/docs/real-execution-backends.7.md",       needle: next, desc: "real execution backends doc" },
+    { path: "plugins/cool-workflow/docs/node-snapshot-diff-replay.7.md",     needle: next, desc: "node snapshot doc" },
+    { path: "plugins/cool-workflow/docs/contract-migration-tooling.7.md",    needle: next, desc: "contract migration doc" },
+    { path: "plugins/cool-workflow/docs/control-plane-scheduling.7.md",      needle: next, desc: "control-plane scheduling doc" },
+    { path: "plugins/cool-workflow/docs/agent-delegation-drive.7.md",        needle: next, desc: "agent delegation doc" },
+    { path: "plugins/cool-workflow/docs/run-retention-reclamation.7.md",     needle: next, desc: "run retention doc" },
+    { path: "plugins/cool-workflow/docs/durable-state-and-locking.7.md",     needle: next, desc: "durable state doc" },
+    { path: "plugins/cool-workflow/docs/release-and-migration.7.md",         needle: next, desc: "release & migration doc" },
+  ];
+}
+
+function contentSurfaceFilesRoot(next) {
+  return [
+    { path: "CHANGELOG.md", needle: `## ${next}`, desc: "CHANGELOG section header" },
+    { path: "RELEASE.md",   needle: next,          desc: "RELEASE version reference" },
+  ];
+}
+
+function handleContentSurfaces(current, next) {
+  const allFiles = [
+    ...contentSurfaceFiles(next),
+    ...contentSurfaceFilesRoot(next)
+  ];
+
+  const missing = [];
+  for (const { path: rel, needle } of allFiles) {
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) { missing.push({ rel, reason: "file missing" }); continue; }
+    const text = fs.readFileSync(abs, "utf8");
+    if (!text.includes(needle)) missing.push({ rel, needle });
+  }
+
+  if (missing.length === 0) {
+    process.stdout.write(`\nContent surfaces PASS — every file includes ${next}.\n`);
+    return { ok: true };
+  }
+
+  if (CONTENT) {
+    // Auto-append version placeholders to all missing files.
+    process.stdout.write(`\nAuto-appending v${next} placeholders to ${missing.length} content surface(s):\n`);
+    for (const { rel, needle } of missing) {
+      const abs = path.join(repoRoot, rel);
+      if (!fs.existsSync(abs)) { process.stdout.write(`  SKIP  ${rel} (missing)\n`); continue; }
+      fs.appendFileSync(abs, `\n${needle}\n`);
+      process.stdout.write(`  +     ${rel}\n`);
+    }
+    // Re-run version-sync-check to confirm all content surfaces now pass.
+    const reSync = spawnSync("npm", ["run", "--silent", "version:sync"], {
+      cwd: pluginRoot, stdio: "pipe", encoding: "utf8"
+    });
+    if (reSync.status !== 0) {
+      return { ok: false, error: `version:sync still fails after auto-append:\n${reSync.stdout}\n${reSync.stderr}` };
+    }
+    process.stdout.write(`Content surfaces auto-filled. Edit prose in:\n`);
+    for (const { rel } of missing) process.stdout.write(`  ${rel}\n`);
+    return { ok: true };
+  }
+
+  // GATE mode (default): fail with precise missing-file list.
+  const lines = [`\n${missing.length} content surface(s) missing version ${next}:`];
+  for (const { rel, needle } of missing) {
+    lines.push(`  ${rel}  — must contain "${needle}"`);
+  }
+  lines.push("");
+  lines.push("Fix with:  npm run bump:version -- " + next + " --content  (auto-fill placeholders)");
+  lines.push("   or edit each file manually to add the version reference.");
+  return { ok: false, error: lines.join("\n") };
+}
+
+main();

package/scripts/canonical-apps.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("node:assert/strict");
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const cli = path.join(pluginRoot, "scripts/cw.js");
+const node = process.execPath;
+
+const canonicalApps = [
+  {
+    id: "architecture-review",
+    args: (workspace) => [
+      "--repo",
+      workspace,
+      "--question",
+      "Is the canonical app architecture stable and evidence-backed?",
+      "--invariant",
+      "No duplicate workflow ids",
+      "--focus",
+      "Workflow App framework"
+    ]
+  },
+  {
+    id: "pr-review-fix-ci",
+    args: (workspace) => [
+      "--repo",
+      workspace,
+      "--branch",
+      "feature/canonical-apps",
+      "--base",
+      "main",
+      "--ci",
+      "local",
+      "--mode",
+      "review"
+    ]
+  },
+  {
+    id: "release-cut",
+    args: (workspace) => [
+      "--repo",
+      workspace,
+      "--version",
+      "0.1.30",
+      "--previousVersion",
+      "0.1.10",
+      "--releaseBranch",
+      "main",
+      "--dryRun",
+      "true"
+    ]
+  },
+  {
+    id: "research-synthesis",
+    args: (workspace) => [
+      "--cwd",
+      workspace,
+      "--question",
+      "What evidence supports Canonical Workflow Apps as official userland?",
+      "--source",
+      "plugins/cool-workflow/docs/workflow-app-framework.7.md",
+      "--scope",
+      "Cool Workflow v0.1.78",
+      "--freshness",
+      "as of release preparation"
+    ]
+  }
+];
+
+function main() {
+  const appList = runJson(["app", "list"]);
+  const workflowList = runJson(["list"]);
+  assertUniqueIds(appList, "app list");
+  assertUniqueIds(workflowList, "workflow list");
+
+  const summaries = [];
+  for (const app of canonicalApps) {
+    const manifestPath = path.join(pluginRoot, "apps", app.id, "app.json");
+    const summary = appList.find((entry) => entry.id === app.id);
+    assert.ok(summary, `${app.id} must appear in app list`);
+    assert.equal(summary.sourceKind, "app-directory");
+    assert.equal(summary.legacy, false);
+    assert.equal(summary.version, "0.1.78");
+
+    const validation = runJson(["app", "validate", manifestPath]);
+    assert.equal(validation.valid, true, `${app.id} manifest must validate`);
+
+    const shown = runJson(["app", "show", app.id]);
+    assert.equal(shown.app.id, app.id);
+    assert.equal(shown.app.version, "0.1.78");
+    assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
+    assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
+    assertTaskIdsUnique(shown);
+    assertUsesSandboxHints(shown);
+    assertHasEvidenceGate(shown);
+
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), `cw-canonical-${app.id}-`));
+    const plan = runJson(["plan", app.id, ...app.args(workspace)]);
+    const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
+    assert.equal(state.workflow.app.id, app.id);
+    assert.equal(state.workflow.app.version, "0.1.78");
+    assert.equal(state.workflow.app.metadata.canonical, true);
+    assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
+    assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);
+
+    summaries.push({
+      id: app.id,
+      version: shown.app.version,
+      runId: plan.runId,
+      taskCount: state.tasks.length,
+      statePath: plan.statePath,
+      reportPath: plan.reportPath
+    });
+  }
+
+  process.stdout.write(`${JSON.stringify({ ok: true, canonicalApps: summaries }, null, 2)}\n`);
+}
+
+function runJson(args) {
+  return JSON.parse(execFileSync(node, [cli, ...args], { cwd: pluginRoot, encoding: "utf8" }));
+}
+
+function assertUniqueIds(entries, label) {
+  const seen = new Set();
+  for (const entry of entries) {
+    assert.ok(!seen.has(entry.id), `${label} contains duplicate id ${entry.id}`);
+    seen.add(entry.id);
+  }
+}
+
+function assertTaskIdsUnique(shown) {
+  const seen = new Set();
+  for (const phase of shown.workflow.phases) {
+    for (const task of phase.tasks) {
+      assert.ok(!seen.has(task.id), `${shown.app.id} contains duplicate task id ${task.id}`);
+      seen.add(task.id);
+    }
+  }
+}
+
+function assertUsesSandboxHints(shown) {
+  for (const phase of shown.workflow.phases) {
+    for (const task of phase.tasks) {
+      assert.ok(task.sandboxProfileId, `${shown.app.id} task ${task.id} needs a sandboxProfileId`);
+      assert.ok(
+        shown.app.sandboxProfiles.includes(task.sandboxProfileId),
+        `${shown.app.id} task ${task.id} uses undeclared sandbox profile ${task.sandboxProfileId}`
+      );
+    }
+  }
+}
+
+function assertHasEvidenceGate(shown) {
+  const gated = shown.workflow.phases.flatMap((phase) =>
+    phase.tasks
+      .filter((task) => task.requiresEvidence)
+      .map((task) => ({ phase: phase.name, task: task.id }))
+  );
+  assert.ok(gated.length > 0, `${shown.app.id} needs at least one evidence-required task`);
+  assert.ok(
+    gated.some((entry) => /verify|synth|verdict|summary/i.test(`${entry.phase}:${entry.task}`)),
+    `${shown.app.id} needs an evidence gate in verify/synthesis/verdict/summary work`
+  );
+}
+
+main();

package/scripts/cw.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../dist/cli.js");