cool-workflow 0.1.79 → 0.1.81

package/scripts/coverage-gate.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+"use strict";
+
+// coverage-gate — run the smoke suite under V8 coverage and fail closed when
+// line coverage of dist/ drops below the floor.
+//
+// Why this exists: nothing measured coverage, so a subsystem could ship dark.
+// It happened: scheduler.ts sat at 12.7% line coverage (only `schedule list`
+// was ever exercised) and no gate noticed. This script makes that class of
+// regression visible and blocking.
+//
+// MECHANISM (this file): spawn test/run-all.js with NODE_V8_COVERAGE set —
+// Node's built-in inspector coverage, inherited by every child process the
+// smokes spawn (CLI invocations, MCP server, workers), so the numbers reflect
+// the real end-to-end surface. Merge the per-process reports byte-wise
+// (covered-by-any-process wins), project onto executable lines of dist/**/*.js,
+// print the worst files, and compare the overall percentage to the floor.
+// node only — no c8, no dependency, same portability constraint as run-all.
+//
+// POLICY (flags/env): the floor. Default 80; override with --min <pct> or
+// CW_COVERAGE_MIN. Raise the default as gaps close — never lower it (ratchet).
+//
+// FAIL CLOSED: a failing suite fails the gate with the suite's exit code; zero
+// coverage reports found fails rather than passing vacuously.
+//
+// Usage: node scripts/coverage-gate.js [--min 80] [--concurrency <n|auto>]
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SELF = path.basename(__filename);
+const packageDir = path.resolve(__dirname, "..");
+const distDir = path.join(packageDir, "dist");
+
+function flagValue(name) {
+  const args = process.argv.slice(2);
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1);
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+const floor = Number(flagValue("--min") ?? process.env.CW_COVERAGE_MIN ?? 80);
+if (!Number.isFinite(floor) || floor < 0 || floor > 100) {
+  process.stderr.write(`${SELF}: invalid coverage floor — expected 0..100.\n`);
+  process.exit(1);
+}
+
+const covDir = fs.mkdtempSync(path.join(os.tmpdir(), "cw-coverage-"));
+
+function runSuite() {
+  return new Promise((resolve) => {
+    const args = [path.join(packageDir, "test", "run-all.js")];
+    const concurrency = flagValue("--concurrency");
+    if (concurrency) args.push("--concurrency", concurrency);
+    const child = spawn(process.execPath, args, {
+      cwd: packageDir,
+      stdio: "inherit",
+      env: { ...process.env, NODE_V8_COVERAGE: covDir }
+    });
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+// Merge per-process V8 reports for one file. Within a single process the
+// ranges nest (function range, then narrower uncovered branches), so paint
+// larger ranges first and let nested ranges override. Across processes a byte
+// is covered if ANY process covered it — a count-0 range in one process must
+// not erase another process's hit.
+function paintProcess(functions, length) {
+  const ranges = [];
+  for (const fn of functions || []) for (const range of fn.ranges || []) ranges.push(range);
+  ranges.sort((a, b) => (b.endOffset - b.startOffset) - (a.endOffset - a.startOffset));
+  const view = new Uint8Array(length); // 0 unreported, 1 covered, 2 uncovered
+  for (const range of ranges) {
+    view.fill(range.count > 0 ? 1 : 2, Math.max(0, range.startOffset), Math.min(range.endOffset, length));
+  }
+  return view;
+}
+
+// A line counts as executable unless it is blank, a comment, or a lone closer.
+// Heuristic, but applied uniformly — the ratchet compares like with like.
+function isExecutableLine(line) {
+  const t = line.trim();
+  return (
+    t.length > 0 && !t.startsWith("//") && !t.startsWith("/*") && !t.startsWith("*") &&
+    t !== "}" && t !== "};" && t !== "});"
+  );
+}
+
+function listDistFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listDistFiles(p));
+    else if (entry.name.endsWith(".js")) out.push(p);
+  }
+  return out;
+}
+
+function aggregate() {
+  const reports = fs.readdirSync(covDir).filter((f) => f.endsWith(".json"));
+  if (reports.length === 0) {
+    process.stderr.write(`${SELF}: no V8 coverage reports produced — refusing to pass vacuously.\n`);
+    process.exit(1);
+  }
+  const covered = new Map(); // file -> Uint8Array, 1 = covered by any process
+  const uncovered = new Map(); // file -> Uint8Array, 1 = reported count-0 somewhere
+  const lengths = new Map();
+  for (const report of reports) {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(path.join(covDir, report), "utf8"));
+    } catch {
+      continue; // a process killed mid-write leaves a truncated report
+    }
+    for (const script of data.result || []) {
+      if (!script.url || !script.url.startsWith("file://")) continue;
+      const file = decodeURIComponent(script.url.slice("file://".length));
+      if (!file.startsWith(distDir + path.sep)) continue;
+      let length = lengths.get(file);
+      if (length === undefined) {
+        try {
+          length = fs.readFileSync(file, "utf8").length;
+        } catch {
+          continue;
+        }
+        lengths.set(file, length);
+        covered.set(file, new Uint8Array(length));
+        uncovered.set(file, new Uint8Array(length));
+      }
+      const view = paintProcess(script.functions, length);
+      const coveredBytes = covered.get(file);
+      const uncoveredBytes = uncovered.get(file);
+      for (let i = 0; i < length; i++) {
+        if (view[i] === 1) coveredBytes[i] = 1;
+        else if (view[i] === 2) uncoveredBytes[i] = 1;
+      }
+    }
+  }
+
+  const rows = [];
+  for (const file of listDistFiles(distDir)) {
+    const source = fs.readFileSync(file, "utf8");
+    const length = source.length;
+    const coveredBytes = covered.get(file) || new Uint8Array(length);
+    const uncoveredBytes = uncovered.get(file) || new Uint8Array(length);
+    const loaded = lengths.has(file);
+    let offset = 0;
+    let total = 0;
+    let hit = 0;
+    for (const line of source.split("\n")) {
+      if (isExecutableLine(line)) {
+        total += 1;
+        let lineCovered = false;
+        let lineReported = false;
+        for (let i = offset; i < offset + line.length; i++) {
+          if (coveredBytes[i]) {
+            lineCovered = true;
+            break;
+          }
+          if (uncoveredBytes[i]) lineReported = true;
+        }
+        // Unreported bytes in a loaded file are top-level code that ran at
+        // require time; in a never-loaded file nothing ran.
+        if (lineCovered || (loaded && !lineReported)) hit += 1;
+      }
+      offset += line.length + 1;
+    }
+    rows.push({ file: path.relative(distDir, file), total, hit, loaded });
+  }
+  return rows;
+}
+
+(async () => {
+  const suiteExit = await runSuite();
+  if (suiteExit !== 0) {
+    process.stderr.write(`${SELF}: smoke suite failed (exit ${suiteExit}) — coverage not evaluated.\n`);
+    process.exit(suiteExit);
+  }
+  const rows = aggregate();
+  let total = 0;
+  let hit = 0;
+  for (const row of rows) {
+    total += row.total;
+    hit += row.hit;
+  }
+  const overall = total ? (100 * hit) / total : 0;
+
+  rows.sort((a, b) => a.hit / Math.max(1, a.total) - b.hit / Math.max(1, b.total));
+  process.stdout.write(`\n${SELF}: line coverage of dist/ under the full smoke suite\n`);
+  process.stdout.write("  lowest-covered files:\n");
+  // Type-only modules compile to a 2-line "use strict" stub that is never
+  // require()d; they count toward the overall number but would bury the
+  // actionable entries in this list.
+  const actionable = rows.filter((row) => row.total > 5);
+  for (const row of actionable.slice(0, 10)) {
+    const pct = ((100 * row.hit) / Math.max(1, row.total)).toFixed(1).padStart(5);
+    process.stdout.write(`    ${pct}%  ${String(row.hit).padStart(5)}/${String(row.total).padEnd(5)} ${row.file}${row.loaded ? "" : "  (never loaded)"}\n`);
+  }
+  process.stdout.write(`  OVERALL: ${hit}/${total} executable lines = ${overall.toFixed(1)}% (floor ${floor}%)\n`);
+
+  fs.rmSync(covDir, { recursive: true, force: true });
+  if (overall < floor) {
+    process.stderr.write(`${SELF}: FAIL — overall coverage ${overall.toFixed(1)}% is below the ${floor}% floor.\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`${SELF}: PASS — coverage holds the ${floor}% floor.\n`);
+})();

package/scripts/dogfood-release.js

@@ -5,7 +5,7 @@ const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
-const TARGET_VERSION = "0.1.79";
+const TARGET_VERSION = "0.1.81";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.79");
+    assert.equal(appValidation.summary.version, "0.1.81");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.79 end-to-end golden path."
+        "Prove the deterministic v0.1.81 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.79");
+    assert.equal(state.workflow.app.version, "0.1.81");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.79/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.81/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/parity-check.js

@@ -150,6 +150,11 @@ async function payloadParity() {
     for (const [capability, mcpTool] of GLOBAL_PROBES) {
       const cap = capById(capability);
       assert.equal(cap.mcp.tool, mcpTool, `probe/registry MCP tool mismatch for ${capability}`);
+      // jsonMode is the single source for the CLI's --json policy; this probe only
+      // appends --json for "flag" verbs and JSON.parse-es the result. The human
+      // rendering and "default"-verb no-flag JSON are pinned to cap.cli.jsonMode by
+      // the companion test/cli-jsonmode-parity-smoke.js, so cli.ts can't silently
+      // re-encode that policy by hand and drift from this registry data.
       const cliArgv = [...cap.cli.path, ...(cap.cli.jsonMode === "flag" ? ["--json"] : [])];
       const cliOut = JSON.parse(execFileSync(node, [cli, ...cliArgv], { cwd: workspace, encoding: "utf8" }));
       const mcpOut = await mcp.tool(mcpTool, { cwd: workspace });

package/scripts/release-check.js

@@ -58,7 +58,11 @@ const checks = [
   { name: "dist freshness", command: ["npm", "run", "dist:check"] },
   { name: "type check", command: ["npm", "run", "check"] },
   { name: "run-state schema consistency", command: ["node", "scripts/validate-run-state-schema.js"] },
-  { name: "tests", command: ["npm", "test"] },
+  // Parallel suite (test:ci = run-all.js --concurrency auto). Each smoke runs in
+  // a private cwd + state roots (CW_HOME/HOME/TMPDIR), so concurrency is race-free.
+  // The bare `npm test` and the tag-gate (release-gate.sh) stay sequential as the
+  // deterministic backstop.
+  { name: "tests", command: ["npm", "run", "test:ci"] },
   { name: "canonical apps", command: ["npm", "run", "canonical-apps"] },
   { name: "golden path", command: ["npm", "run", "golden-path"] },
   { name: "CLI MCP parity", command: ["npm", "run", "parity:check"] },

package/scripts/source-context.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+"use strict";
+
+// source-context — opt-in JSONL source context exporter.
+//
+// Policy is data in manifest/source-context-profiles.json. This script is only
+// mechanism: enumerate tracked files for a git ref, classify them through the
+// selected profile, hash the committed bytes, and print JSONL to stdout.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const defaultRepoRoot = path.resolve(pluginRoot, "..", "..");
+let repoRoot = defaultRepoRoot;
+const DEFAULT_PROFILE_FILE = path.join(pluginRoot, "manifest", "source-context-profiles.json");
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+function main() {
+  if (!["export", "manifest", "profiles"].includes(command)) {
+    usage(1, `unknown command: ${command || "(missing)"}`);
+    return;
+  }
+
+  const profileFile = valueArg("--profile-file") || DEFAULT_PROFILE_FILE;
+  repoRoot = path.resolve(valueArg("--repo-root") || defaultRepoRoot);
+  const profiles = readProfiles(profileFile);
+
+  if (command === "profiles") {
+    for (const [id, profile] of Object.entries(profiles.profiles)) {
+      writeJsonl({
+        schemaVersion: profiles.schemaVersion,
+        id,
+        description: profile.description || "",
+        maxLines: Number(profile.maxLines) || null,
+        include: profile.include || [],
+        exclude: profile.exclude || []
+      });
+    }
+    return;
+  }
+
+  const profileId = valueArg("--profile") || "core";
+  const profile = profiles.profiles[profileId];
+  if (!profile) die(`unknown profile: ${profileId}`);
+
+  const ref = resolveRef(valueArg("--ref") || "HEAD");
+  const changedFrom = valueArg("--changed-from") ? resolveRef(valueArg("--changed-from")) : "";
+  const changedPaths = changedFrom ? changedPathSet(changedFrom, ref) : null;
+  const cacheDir = command === "export" ? valueArg("--cache-dir") : "";
+  const cachePath = cacheDir ? sourceContextCachePath(cacheDir, profileId, ref, profile, changedFrom) : "";
+  if (cachePath && fs.existsSync(cachePath)) {
+    process.stdout.write(readValidCache(cachePath, profileId, ref, changedFrom));
+    return;
+  }
+
+  const files = gitLines(["ls-tree", "-r", "--name-only", ref]).filter((file) => !changedPaths || changedPaths.has(file));
+  let exportedLines = 0;
+  const buffered = cachePath ? [] : null;
+  const emit = (value) => {
+    if (buffered) buffered.push(JSON.stringify(value));
+    else writeJsonl(value);
+  };
+
+  for (const file of files) {
+    const classification = classify(file, profile);
+    const blob = gitBlob(ref, file);
+    const binary = isBinary(blob);
+    const record = {
+      schemaVersion: profiles.schemaVersion,
+      profile: profileId,
+      ref,
+      path: file,
+      bytes: blob.length,
+      lines: binary ? null : countLines(blob),
+      sha256: sha256(blob),
+      included: classification.included,
+      reason: classification.reason,
+      ...(changedFrom ? { changedFrom } : {})
+    };
+
+    if (command === "manifest") {
+      emit(record);
+      continue;
+    }
+
+    if (!classification.included) continue;
+    if (binary) die(`included file is binary: ${file}`);
+    exportedLines += record.lines || 0;
+    emit({ ...record, content: blob.toString("utf8") });
+  }
+
+  const maxLines = Number(profile.maxLines) || 0;
+  if (command === "export" && maxLines > 0 && exportedLines > maxLines) {
+    die(`profile ${profileId} exported ${exportedLines} lines, above maxLines ${maxLines}`);
+  }
+  if (cachePath && buffered) {
+    const text = buffered.map((line) => `${line}\n`).join("");
+    writeCache(cachePath, text);
+    process.stdout.write(text);
+  }
+}
+
+function usage(code, message) {
+  if (message) process.stderr.write(`source-context: ${message}\n`);
+  process.stderr.write(
+    [
+      "usage:",
+      "  node scripts/source-context.js profiles",
+      "  node scripts/source-context.js manifest [--profile core] [--ref HEAD] [--changed-from REF] [--repo-root DIR]",
+      "  node scripts/source-context.js export [--profile core] [--ref HEAD] [--changed-from REF] [--repo-root DIR] [--cache-dir DIR]"
+    ].join("\n") + "\n"
+  );
+  process.exitCode = code;
+}
+
+function valueArg(name) {
+  const eq = args.find((arg) => arg.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1);
+  const idx = args.indexOf(name);
+  return idx >= 0 ? args[idx + 1] : "";
+}
+
+function readProfiles(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    die(`cannot read profile file ${rel(file)}: ${error.message}`);
+  }
+  if (!parsed || parsed.schemaVersion !== 1 || !parsed.profiles || typeof parsed.profiles !== "object") {
+    die(`invalid source context profile file: ${rel(file)}`);
+  }
+  for (const [id, profile] of Object.entries(parsed.profiles)) {
+    if (!Array.isArray(profile.include) || !Array.isArray(profile.exclude)) {
+      die(`profile ${id} must define include and exclude arrays`);
+    }
+  }
+  return parsed;
+}
+
+function resolveRef(ref) {
+  return git(["rev-parse", "--verify", `${ref}^{commit}`]).trim();
+}
+
+function gitLines(argv) {
+  return git(argv).split(/\r?\n/).filter(Boolean);
+}
+
+function changedPathSet(base, ref) {
+  return new Set(gitLines(["diff", "--name-only", "--diff-filter=ACMRT", `${base}..${ref}`]));
+}
+
+function git(argv) {
+  const result = spawnSync("git", argv, { cwd: repoRoot, encoding: "utf8" });
+  if (result.status !== 0) die((result.stderr || result.stdout || `git ${argv.join(" ")} failed`).trim());
+  return result.stdout;
+}
+
+function gitBlob(ref, file) {
+  const result = spawnSync("git", ["show", `${ref}:${file}`], { cwd: repoRoot, encoding: "buffer", maxBuffer: 1024 * 1024 * 64 });
+  if (result.status !== 0) die((result.stderr || result.stdout || `cannot read ${file} at ${ref}`).toString().trim());
+  return result.stdout;
+}
+
+function classify(file, profile) {
+  const excludedBy = (profile.exclude || []).find((pattern) => matches(pattern, file));
+  if (excludedBy) return { included: false, reason: `excluded:${excludedBy}` };
+  const includedBy = (profile.include || []).find((pattern) => matches(pattern, file));
+  if (includedBy) return { included: true, reason: `included:${includedBy}` };
+  return { included: false, reason: "not-included" };
+}
+
+function matches(pattern, file) {
+  if (pattern.endsWith("/**")) {
+    const dir = pattern.slice(0, -3);
+    return file === dir || file.startsWith(`${dir}/`);
+  }
+  if (!pattern.includes("*")) return file === pattern;
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, "\\$&"))
+    .join("[^/]*");
+  return new RegExp(`^${escaped}$`).test(file);
+}
+
+function countLines(buffer) {
+  if (buffer.length === 0) return 0;
+  let count = 0;
+  for (const byte of buffer) if (byte === 10) count++;
+  return buffer[buffer.length - 1] === 10 ? count : count + 1;
+}
+
+function isBinary(buffer) {
+  return buffer.includes(0);
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function profileDigest(profileId, profile) {
+  return sha256(Buffer.from(stableStringify({ profileId, profile }), "utf8"));
+}
+
+function sourceContextCachePath(cacheDir, profileId, ref, profile, changedFrom) {
+  const safeProfile = String(profileId).replace(/[^A-Za-z0-9_.-]/g, "_");
+  const diffPart = changedFrom ? `-changed-${changedFrom.slice(0, 12)}` : "";
+  const digest = sha256(Buffer.from(stableStringify({ profileId, profile, changedFrom: changedFrom || "" }), "utf8")).slice(0, 16);
+  return path.join(path.resolve(cacheDir), `${safeProfile}-${ref.slice(0, 12)}${diffPart}-${digest}.jsonl`);
+}
+
+function readValidCache(file, profileId, ref, changedFrom) {
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    die(`cannot read source context cache ${rel(file)}: ${error.message}`);
+  }
+  if (text.length > 0 && !text.endsWith("\n")) {
+    die(`invalid source context cache ${rel(file)}: missing trailing newline`);
+  }
+  for (const line of text.split(/\n/)) {
+    if (!line) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      die(`invalid source context cache ${rel(file)}: non-JSONL record`);
+    }
+    if (
+      !record ||
+      record.profile !== profileId ||
+      record.ref !== ref ||
+      String(record.changedFrom || "") !== String(changedFrom || "") ||
+      record.included !== true ||
+      typeof record.path !== "string" ||
+      typeof record.content !== "string" ||
+      !/^[0-9a-f]{64}$/.test(String(record.sha256 || ""))
+    ) {
+      die(`invalid source context cache ${rel(file)}: record does not match profile/ref`);
+    }
+    const contentBytes = Buffer.from(record.content, "utf8");
+    if (
+      record.sha256 !== sha256(contentBytes) ||
+      record.bytes !== contentBytes.length ||
+      record.lines !== countLines(contentBytes)
+    ) {
+      die(`invalid source context cache ${rel(file)}: content digest mismatch`);
+    }
+  }
+  return text;
+}
+
+function writeCache(file, text) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, "utf8");
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    die(`cannot write source context cache ${rel(file)}: ${error.message}`);
+  }
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function writeJsonl(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function rel(file) {
+  return path.relative(repoRoot, path.resolve(file));
+}
+
+function die(message) {
+  process.stderr.write(`source-context: ${message}\n`);
+  process.exit(1);
+}
+
+main();

package/scripts/version-sync-check.js

@@ -5,6 +5,7 @@ const assert = require("node:assert/strict");
 const fs = require("node:fs");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
+const { CANONICAL_APP_IDS } = require("./canonical-apps-list.js");
 
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");
@@ -47,13 +48,10 @@ function readReleaseSource(relativePath) {
 // Read it from the released commit so the asserted-against version is itself
 // taken from HEAD, not a half-written working copy.
 const VERSION = JSON.parse(readReleaseSource("plugins/cool-workflow/package.json").text).version;
-const canonicalApps = [
-  "architecture-review",
-  "end-to-end-golden-path",
-  "pr-review-fix-ci",
-  "release-cut",
-  "research-synthesis"
-];
+// Canonical app ids are DERIVED from apps/ (excluding metadata.example demos) by
+// scripts/canonical-apps-list.js — the single source bump-version.js bumps and
+// canonical-apps.js smoke-tests. No hand-copied list to drift (audit M5).
+const canonicalApps = CANONICAL_APP_IDS;
 
 function main() {
   const checks = [];

package/skills/ci-triage/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ci-triage
+description: >-
+  Diagnose failing CI, build, release-gate, or test runs for Cool Workflow. Use
+  when a GitHub Actions check, local npm test, npm run build, release gate,
+  smoke test, or generated-manifest check fails and Codex must identify the
+  first actionable failure with logs and verifier commands.
+---
+
+# CI Triage
+
+## Overview
+
+Triage the failure before editing. Keep stdout/log evidence separate from
+diagnosis, identify the first failing command, and end with one verifier command
+that proves the proposed fix.
+
+## Workflow
+
+1. Capture the failing command, exit code, and the earliest meaningful error.
+2. Classify the failure as code, test expectation, generated artifact drift,
+   environment, timeout, or external service.
+3. Inspect only the files needed to explain that first failure.
+4. Propose or implement the smallest fix.
+5. Run the narrow verifier first, then the full gate when the fix is plausible.
+6. Write the lesson back to `PROJECT_MEMORY.md`, an eval case, or the matching
+   workflow skill when the failure pattern is likely to recur.
+
+## Commands
+
+```bash
+npm run build
+npm test
+npm run gen:manifests -- --check
+npm run index:check
+git diff --check
+```
+
+Use smoke tests directly for narrow verification:
+
+```bash
+node test/<name>-smoke.js
+```
+
+## Output Rules
+
+- Lead with the failing command and root cause.
+- Quote only the shortest relevant log lines.
+- Separate "confirmed" from "inference".
+- Include the verifier commands actually run or still required.

package/skills/ci-triage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CI Triage"
+  short_description: "Diagnose failing CI with evidence."
+  default_prompt: "Use $ci-triage to diagnose the failing CI run."

package/skills/cool-workflow/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: cool-workflow
-description: Use when the user asks for Cool Workflow, CW, agent workflow control-plane, TypeScript workflow orchestration, phased multi-agent work, background workflow tasks, or reusable workflow apps.
+description: >-
+  Use when the user asks for Cool Workflow, CW, agent workflow control-plane,
+  TypeScript workflow orchestration, phased multi-agent work, background
+  workflow tasks, reusable workflow apps, or auditable agent run state.
 ---
 
 # Cool Workflow