cool-workflow 0.1.80 → 0.1.82

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "description": "Auditable workflow control-plane and orchestration runtime: TypeScript dispatch, evidence-gated verification, state commits, scheduling, routines, multi-agent coordination, and MCP. Delegates execution to external agents — never runs models.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "description": "Auditable workflow control-plane and orchestration runtime: TypeScript dispatch, evidence-gated verification, state commits, scheduling, routines, multi-agent coordination, and MCP. Delegates execution to external agents — never runs models.",
   "author": {
     "name": "COOLWHITE LLC"

package/README.md

@@ -263,6 +263,40 @@ write paths, command execution, network access, and environment exposure. CW
 stores and validates the policy, while the agent host enforces OS/process
 runtime controls. See [docs/sandbox-profiles.7.md](docs/sandbox-profiles.7.md).
 
+## Quickstart
+
+**30-second proof, no install** — see that a recorded telemetry verdict can't be forged:
+
+```bash
+npx cool-workflow demo tamper
+# builds a signed ed25519 ledger, forges it 2 ways, both caught offline
+# -> VERDICT: tamper-evidence holds ✓
+```
+
+**Try a real run** — no clone needed; drive an architecture review with your own agent:
+
+```bash
+npx cool-workflow quickstart architecture-review --repo /path/to/repo \
+  --question "Is this architecture sound?" --agent-command builtin:claude
+```
+
+CW DELEGATES worker execution to your own agent. With no `--agent-command` (or
+`CW_AGENT_COMMAND`) the drive fails closed (status `blocked`) — it never fabricates a
+result. `--agent-command builtin:claude` resolves to a bundled read-only `claude -p`
+wrapper (needs `claude` on your PATH).
+
+**Re-prove a finished run, offline** (`cw` is the installed bin; or `npx cool-workflow <cmd>`):
+
+```bash
+cw telemetry verify <run-id>                  # re-checks the hash-chained ledger
+cw telemetry verify <run-id> --pubkey pub.pem # also re-runs ed25519 signature checks
+cw audit verify <run-id>                      # re-proves the trust-audit hash chain
+```
+
+More: `cw quickstart <app> --preview` (read-only dry run), `cw run resume <run-id> --drive`
+(continue an interrupted run), `cw run inspect-archive <archive>` (integrity-check a
+portable run archive without importing it).
+
 ## Structure
 
 ```text
@@ -300,6 +334,10 @@ cool-workflow
 
 ## Commands
 
+Installed via npm, the bin is `cw` (alias `cool-workflow`): e.g. `cw list`,
+`cw quickstart …`. From a cloned source checkout, before `npm run build`, use the
+equivalent `node scripts/cw.js <cmd>` form shown in the examples below.
+
 List bundled workflows:
 
 ```bash
@@ -619,7 +657,7 @@ Replaces the linear migration chain with a BFS graph path resolver (`findMigrati
 
 ## Vendor-Adapter Registry (v0.1.47)
 
-Data-driven manifest generation: vendor JSON shapes extracted from `gen-manifests.js` into declarative templates in `plugin.manifest.json`. A `_resolveTemplate()` engine resolves `{{path.to.field}}` markers. Adding a new AI platform is pure data.
+Data-driven manifest generation: vendor JSON shapes extracted from `gen-manifests.js` into declarative templates in `plugin.manifest.json`. A `_resolveTemplate()` engine resolves `{{path.to.field}}` markers. Adding a new AI platform is pure data. Cross-vendor is proven by boot, not just by generation: `npm run manifest:load-check` (`node test/vendor-manifest-load-smoke.js`) loads every generated manifest (claude, codex, agents, gemini, opencode) and asserts each exposes the full tool surface (184 tools).
 
 ## P2 Fixes (v0.1.48)
 
@@ -651,7 +689,7 @@ The orchestration vision landed in one release, all reviewer-gated:
 
 ## Tamper-evidence demo (v0.1.79)
 
-`cw demo tamper` — a hermetic, one-command proof that a recorded telemetry verdict cannot be forged undetected: it builds a real ed25519-signed ledger, forges it at the ledger layer (verdict flip + recomputed local hash → the chain still breaks) and the signature layer (inflated tokens, reused signature → ed25519 rejects), all verified offline with only the public key. `cw telemetry verify <run>` is the operator-facing half (`cw_telemetry_verify` on MCP).
+`cw demo tamper` — a hermetic, one-command proof that a recorded telemetry verdict cannot be forged undetected: it builds a real ed25519-signed ledger, forges it at the ledger layer (verdict flip + recomputed local hash → the chain still breaks) and the signature layer (inflated tokens, reused signature → ed25519 rejects), all verified offline with only the public key. `cw telemetry verify <run>` (`cw_telemetry_verify` on MCP) is the operator-facing re-proof: by default it recomputes the hash chain on disk so any later edit to a recorded verdict or usage digest is caught; add `--pubkey <pem-or-path>` to re-run each `attested` hop's ed25519 signature check against the stored raw usage too. What this does and does **not** prove — including the single-keyholder ceiling — is documented honestly in [Trust Model & Limitations](docs/trust-model.md); read it before relying on a green verdict.
 
 ## Opt-in live agent output during a drive (on main, ships next)
 
@@ -662,3 +700,5 @@ v0.1.79
 ## Fast Architecture Review (v0.1.80)
 
 Adds the opt-in fast architecture-review lane: scoped JSONL source contexts, diff-aware exports, reusable Map and Assess results, measurable wrapper metrics, actionable background full-review handoff, and userland model policy flags for routing fast/strong workers without changing the full review contract.
+
+_This documentation tracks Cool Workflow v0.1.82. See [CHANGELOG](../../CHANGELOG.md) for the release notes._

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/agent-config.js

@@ -139,18 +139,30 @@ function agentConfigFromArgs(args) {
 // npx/global install, where $(pwd)-relative paths don't exist) can configure a
 // WORKING agent without knowing where the package landed on disk:
 //   --agent-command builtin:claude   (or CW_AGENT_COMMAND=builtin:claude)
-// resolves to the packaged claude wrapper invocation. Still pure config — the
-// template is an out-of-process delegation script; CW never calls a model API.
-const BUILTIN_AGENT_TEMPLATES = {
-    claude: `node ${node_path_1.default.join(__dirname, "..", "scripts", "agents", "claude-p-agent.js")} {{input}} {{result}}`
-};
+// resolves to the packaged wrapper invocation. Still pure config — the template
+// is an out-of-process delegation script; CW never calls a model API.
+//
+// The builtin set is DATA, not a kernel TS literal (FreeBSD-audit L15): it lives
+// in scripts/agents/builtin-templates.json (vendor name -> wrapper script name).
+// Adding a vendor is a content/distribution step (drop a wrapper + a JSON line),
+// not a kernel edit — keeping CW vendor-agnostic at the source level.
+function builtinAgentTemplates() {
+    const agentsDir = node_path_1.default.join(__dirname, "..", "scripts", "agents");
+    const manifest = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(agentsDir, "builtin-templates.json"), "utf8"));
+    const out = {};
+    for (const [name, script] of Object.entries(manifest.templates || {})) {
+        out[name] = `node ${node_path_1.default.join(agentsDir, script)} {{input}} {{result}}`;
+    }
+    return out;
+}
 function expandBuiltinAgentCommand(command) {
     if (!command || !command.startsWith("builtin:"))
         return command;
     const name = command.slice("builtin:".length).trim();
-    const template = BUILTIN_AGENT_TEMPLATES[name];
+    const templates = builtinAgentTemplates();
+    const template = templates[name];
     if (!template) {
-        throw new Error(`Unknown builtin agent template "${name}" — available: ${Object.keys(BUILTIN_AGENT_TEMPLATES).join(", ")}`);
+        throw new Error(`Unknown builtin agent template "${name}" — available: ${Object.keys(templates).join(", ")}`);
     }
     return template;
 }
@@ -200,6 +212,8 @@ function setAgentConfigFile(patch, env = process.env) {
         endpoint: firstDefined(incoming.endpoint, current.endpoint),
         model: firstDefined(incoming.model, current.model),
         timeoutMs: firstDefined(incoming.timeoutMs, current.timeoutMs),
+        attestPublicKey: firstDefined(incoming.attestPublicKey, current.attestPublicKey),
+        requireAttestedTelemetry: firstDefined(incoming.requireAttestedTelemetry, current.requireAttestedTelemetry),
         source: "file"
     };
     const stored = redacted(merged);

package/dist/candidate-scoring.js

@@ -20,7 +20,16 @@ const state_1 = require("./state");
 const state_node_1 = require("./state-node");
 const trust_audit_1 = require("./trust-audit");
 const collaboration_1 = require("./collaboration");
+const compare_1 = require("./compare");
+const gates_1 = require("./gates");
+const validation_1 = require("./validation");
 exports.CANDIDATE_SCHEMA_VERSION = 1;
+/** Verdict thresholds on a score's normalized value [0,1], declared once so the
+ *  numbers carry intent instead of being buried as literals in verdictFor(). A
+ *  normalized score at-or-above PASS is "pass"; at-or-above WARN (but below
+ *  PASS) is "warn"; anything lower is "fail". Same numbers as before. */
+const VERDICT_PASS_THRESHOLD = 0.7;
+const VERDICT_WARN_THRESHOLD = 0.4;
 function createCandidateScoring(options = {}) {
     return {
         registerCandidate: (run, input) => registerCandidate(run, input, options),
@@ -39,7 +48,7 @@ function registerCandidate(run, input, options = {}) {
     if (existing)
         return existing;
     const now = new Date().toISOString();
-    const id = input.id || createCandidateId(input.kind || "manual", input.workerId || input.taskId || input.resultNodeId);
+    const id = input.id || createCandidateId(run, input.kind || "manual", input.workerId || input.taskId || input.resultNodeId);
     const candidate = {
         schemaVersion: exports.CANDIDATE_SCHEMA_VERSION,
         id,
@@ -103,13 +112,16 @@ function getCandidate(run, candidateId) {
     const file = candidateFile(run, candidateId);
     if (!node_fs_1.default.existsSync(file))
         return undefined;
-    const candidate = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    // Fail-closed integrity boundary (F4/F5): validate the parsed record against
+    // its type def BEFORE upserting it as a trusted CandidateRecord. A corrupt or
+    // forged candidate.json must throw here rather than flow into the run.
+    const candidate = (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
     upsertCandidate(run, candidate);
     return candidate;
 }
 function scoreCandidate(run, candidateId, input, options = {}) {
     const candidate = requireCandidate(run, candidateId);
-    const scoreId = input.id || createScoreId(candidateId);
+    const scoreId = input.id || createScoreId(candidate);
     const evidence = (0, trust_audit_1.normalizeEvidence)(run, input.evidence || [], {
         source: "operator-recorded",
         candidateId,
@@ -238,10 +250,11 @@ function selectCandidate(run, candidateId, options = {}, scoringOptions = {}) {
         else if (!verifierNode.evidence.length) {
             failures.push(error("candidate-selection-missing-evidence", `Candidate ${candidateId} verifier node has no evidence`));
         }
-        else if (emptyCaptureWarning(run, verifierNode)) {
-            // HARD no-false-green gate (v0.1.43) — kept in SYNC with the commit gate
-            // (commit.ts emptyCaptureWarning): a verifier node whose backing result was
-            // an empty-capture must not be selectable, so selection + commit agree.
+        else if ((0, gates_1.emptyCaptureWarning)(run, verifierNode)) {
+            // HARD no-false-green gate (v0.1.43) — selection and the commit gate now
+            // share ONE emptyCaptureWarning (src/gates.ts), so they CANNOT drift: a
+            // verifier node whose backing result was an empty-capture is unselectable
+            // here for the same reason it is uncommittable, by construction.
             failures.push(error("candidate-selection-empty-capture", `Candidate ${candidateId} verifier node has no real evidence (empty-capture result)`));
         }
     }
@@ -279,7 +292,7 @@ function selectCandidate(run, candidateId, options = {}, scoringOptions = {}) {
     const now = new Date().toISOString();
     const selection = {
         schemaVersion: exports.CANDIDATE_SCHEMA_VERSION,
-        id: createSelectionId(candidateId),
+        id: createSelectionId(run, candidateId),
         runId: run.id,
         candidateId,
         selectedAt: now,
@@ -305,7 +318,7 @@ function selectCandidate(run, candidateId, options = {}, scoringOptions = {}) {
             scoreCriteria: bestScore?.criteria,
             verifierNodeId: candidate.verifierNodeId,
             evidenceCount: mergeEvidence(candidate.evidence, verifierNode?.evidence || []).length,
-            sandboxProfileId: sandboxProfileForCandidate(run, candidate),
+            sandboxProfileId: (0, gates_1.sandboxProfileForCandidate)(run, candidate),
             workerId: candidate.workerId,
             commitGateResult: "passed"
         }),
@@ -521,7 +534,10 @@ function loadCandidatesFromDisk(run) {
         .filter((entry) => entry.isDirectory() && entry.name !== "selections")
         .map((entry) => node_path_1.default.join(candidateRoot(run), entry.name, "candidate.json"))
         .filter((file) => node_fs_1.default.existsSync(file))
-        .map((file) => JSON.parse(node_fs_1.default.readFileSync(file, "utf8")));
+        // Fail-closed integrity boundary (F4/F5): each candidate.json is validated
+        // against CandidateRecord before it merges into the run; a corrupt record
+        // throws rather than entering the candidate set as a trusted cast.
+        .map((file) => (0, validation_1.validateCandidateRecord)(JSON.parse(node_fs_1.default.readFileSync(file, "utf8"))));
 }
 function readScores(run, candidateId) {
     const dir = node_path_1.default.join(candidateDir(run, candidateId), "scores");
@@ -531,7 +547,10 @@ function readScores(run, candidateId) {
         .readdirSync(dir)
         .filter((file) => file.endsWith(".json"))
         .sort()
-        .map((file) => JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), "utf8")));
+        // Fail-closed integrity boundary (F4/F5): a score file is validated against
+        // CandidateScore before it can feed ranking/selection. A corrupt score must
+        // throw, not silently widen the normalized/verdict surface the gate reads.
+        .map((file) => (0, validation_1.validateCandidateScore)(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, file), "utf8"))));
 }
 function candidateArtifacts(run, candidate) {
     return [
@@ -558,16 +577,16 @@ function inferCandidateKind(input) {
     return "manual";
 }
 function bestScore(scores) {
-    return [...scores].sort((left, right) => right.normalized - left.normalized || left.createdAt.localeCompare(right.createdAt))[0];
+    return [...scores].sort((left, right) => right.normalized - left.normalized || (0, compare_1.compareBytes)(left.createdAt, right.createdAt))[0];
 }
 function compareRows(left, right, policy) {
     const byScore = right.normalized - left.normalized;
     if (byScore !== 0)
         return byScore;
     if (policy.tieBreaker === "candidateId")
-        return left.candidate.id.localeCompare(right.candidate.id);
-    const byCreated = left.candidate.createdAt.localeCompare(right.candidate.createdAt);
-    return byCreated || left.candidate.id.localeCompare(right.candidate.id);
+        return (0, compare_1.compareBytes)(left.candidate.id, right.candidate.id);
+    const byCreated = (0, compare_1.compareBytes)(left.candidate.createdAt, right.candidate.createdAt);
+    return byCreated || (0, compare_1.compareBytes)(left.candidate.id, right.candidate.id);
 }
 function detectTies(candidates) {
     const groups = new Map();
@@ -578,10 +597,15 @@ function detectTies(candidates) {
     return Array.from(groups.values()).filter((group) => group.length > 1);
 }
 function mergePolicy(policy = {}) {
+    // NOTE: `policy.criteria` (string[]) is intentionally NOT carried here. A
+    // whole-repo grep shows it has no read points — scoring reads each score's
+    // own `input.criteria` (Record<string, number>), not this list. Emitting a
+    // default `criteria: []` advertised a guarantee the code never honored and
+    // could silently drift, so it is dropped. The field stays OPTIONAL on
+    // CandidateScoringPolicy / CandidateRanking.policy for forward-compat input.
     return {
         id: policy.id || "cw.candidate.default",
         title: policy.title || "Default Candidate Scoring",
-        criteria: policy.criteria || [],
         requireEvidence: policy.requireEvidence ?? true,
         requireVerifierGate: policy.requireVerifierGate ?? true,
         minNormalized: policy.minNormalized,
@@ -591,9 +615,9 @@ function mergePolicy(policy = {}) {
 function verdictFor(normalized, policy) {
     if (policy.minNormalized !== undefined && normalized < policy.minNormalized)
         return "fail";
-    if (normalized >= 0.7)
+    if (normalized >= VERDICT_PASS_THRESHOLD)
         return "pass";
-    if (normalized >= 0.4)
+    if (normalized >= VERDICT_WARN_THRESHOLD)
         return "warn";
     return "fail";
 }
@@ -616,18 +640,26 @@ function indexPath(run) {
 function rankingPath(run) {
     return node_path_1.default.join(candidateRoot(run), "ranking.json");
 }
-function createCandidateId(kind, seed) {
-    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
-    const suffix = Math.random().toString(36).slice(2, 8);
-    return `candidate-${(0, state_1.safeFileName)(kind)}-${seed ? `${(0, state_1.safeFileName)(seed)}-` : ""}${stamp}-${suffix}`;
-}
-function createScoreId(candidateId) {
-    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
-    return `score-${(0, state_1.safeFileName)(candidateId)}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
-}
-function createSelectionId(candidateId) {
-    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
-    return `selection-${(0, state_1.safeFileName)(candidateId)}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+// Deterministic candidate id (FreeBSD-audit L12/L13): the candidate's POSITION in
+// the run's candidate set, qualified by kind + seed (a stable worker/task/result
+// id) for readability. No wall-clock stamp, no PRNG suffix — re-running the same
+// workflow mints byte-identical candidate ids, keeping fingerprints replay-stable.
+function createCandidateId(run, kind, seed) {
+    const seq = (run.candidates || []).length + 1;
+    return `candidate-${(0, state_1.safeFileName)(kind)}-${seed ? `${(0, state_1.safeFileName)(seed)}-` : ""}${String(seq).padStart(4, "0")}`;
+}
+// Deterministic score id (FreeBSD-audit L12/L13): the score's POSITION within its
+// candidate's score list. Scores only ever append, so the sequence is unique per
+// candidate and stable across replays.
+function createScoreId(candidate) {
+    const seq = (candidate.scores || []).length + 1;
+    return `score-${(0, state_1.safeFileName)(candidate.id)}-${String(seq).padStart(4, "0")}`;
+}
+// Deterministic selection id (FreeBSD-audit L12/L13): the selection's POSITION in
+// the run's append-only selection log. No clock, no PRNG.
+function createSelectionId(run, candidateId) {
+    const seq = (run.candidateSelections || []).length + 1;
+    return `selection-${(0, state_1.safeFileName)(candidateId)}-${String(seq).padStart(4, "0")}`;
 }
 function shouldPersist(options) {
     return options.persist !== false;
@@ -641,17 +673,6 @@ function error(code, message, options = {}) {
         details: options.details
     };
 }
-/** HARD no-false-green gate (v0.1.43) — kept in SYNC with commit.ts. Traces a
- *  verifier node back to its source result node and returns the empty-capture
- *  marker (set at ingest via isEmptyCapture) when present. Reads ONLY persisted
- *  state, so selection replays deterministically. */
-function emptyCaptureWarning(run, verifierNode) {
-    const resultNodeId = (typeof verifierNode.inputs?.inputNodeId === "string" ? verifierNode.inputs.inputNodeId : undefined) ||
-        verifierNode.parents[0];
-    const resultNode = resultNodeId ? run.nodes?.find((node) => node.id === resultNodeId) : undefined;
-    const warning = resultNode?.metadata?.captureWarning;
-    return typeof warning === "string" && warning ? warning : undefined;
-}
 function mergeCandidates(left, right) {
     const merged = [...left];
     for (const candidate of right) {
@@ -688,13 +709,6 @@ function mergeEvidence(left, right) {
     }
     return merged;
 }
-function sandboxProfileForCandidate(run, candidate) {
-    const worker = candidate.workerId ? (run.workers || []).find((entry) => entry.id === candidate.workerId) : undefined;
-    if (worker?.sandboxProfileId)
-        return worker.sandboxProfileId;
-    const task = candidate.taskId ? (run.tasks || []).find((entry) => entry.id === candidate.taskId) : undefined;
-    return task?.sandboxProfileId;
-}
 function unique(values) {
     return Array.from(new Set(values.filter(Boolean)));
 }