cool-workflow 0.1.78

package/scripts/gen-manifests.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+"use strict";
+
+// Generate every vendor plugin manifest from a single source of truth.
+//
+//   node scripts/gen-manifests.js            # write generated manifests
+//   node scripts/gen-manifests.js --check    # fail (exit 1) if any drift
+//
+// Mechanism vs policy (BSD discipline): the shared assets (skills/, dist/,
+// apps/, the MCP server) live once; each vendor manifest is a thin, generated
+// adapter. Edit manifest/plugin.manifest.json, never the generated files.
+//
+// v0.1.47 — VENDOR ADAPTER REGISTRY: vendor outputs are now declarative
+// templates in plugin.manifest.json's `vendors` section. Adding a new AI
+// platform is just data — no gen-manifests.js changes needed.
+//
+// Supported template markers:
+//   {{path.to.field}}          — resolve a dot-path in the source object
+//   {{path.to.field|lowercase}}— apply transformer (only |lowercase)
+//   {{pluginRootVar}}          — resolve to the vendor's pluginRootVar
+//   Bare strings without {{ }} are literal values
+
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+const SOURCE = path.join(pluginRoot, "manifest", "plugin.manifest.json");
+
+function loadSource() {
+  assert.ok(fs.existsSync(SOURCE), `source of truth missing: ${rel(SOURCE)}`);
+  return JSON.parse(fs.readFileSync(SOURCE, "utf8"));
+}
+
+// ---- Template engine (BSD: mechanism — one pure resolver, policy is data) --
+
+/** Resolve a dot-path string in the source object. Returns undefined if not found. */
+function _resolvePath(obj, pathStr) {
+  const parts = pathStr.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || typeof current !== "object") return undefined;
+    if (!(part in current)) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/** Interpolate {{path.to.field}} or {{path.to.field|transformer}} markers.
+ *  Bare strings without markers are returned as-is. */
+function _interpolate(template, src, pluginRootVar) {
+  if (typeof template !== "string") return template;
+  // Whole-string interpolation: if the entire value is a single marker, resolve
+  // to the actual JS value (object, array, string) rather than a string.
+  const wholeMatch = template.match(/^\{\{([^}]+)\}\}$/);
+  if (wholeMatch) {
+    const expr = wholeMatch[1];
+    // Check for transformer: {{path|lowercase}}
+    const pipeIdx = expr.lastIndexOf("|");
+    const pathStr = pipeIdx >= 0 ? expr.slice(0, pipeIdx) : expr;
+    const transformer = pipeIdx >= 0 ? expr.slice(pipeIdx + 1).trim() : null;
+    let value;
+    if (pathStr === "pluginRootVar") {
+      value = pluginRootVar;
+    } else {
+      value = _resolvePath(src, pathStr);
+    }
+    if (transformer === "lowercase" && typeof value === "string") return value.toLowerCase();
+    return value !== undefined ? value : `{{${expr}}}`;
+  }
+  // Partial interpolation: replace {{...}} in the string
+  return template.replace(/\{\{([^}]+)\}\}/g, (_match, expr) => {
+    const pipeIdx = expr.lastIndexOf("|");
+    const pathStr = pipeIdx >= 0 ? expr.slice(0, pipeIdx) : expr;
+    const transformer = pipeIdx >= 0 ? expr.slice(pipeIdx + 1).trim() : null;
+    let value;
+    if (pathStr === "pluginRootVar") {
+      value = pluginRootVar;
+    } else {
+      value = _resolvePath(src, pathStr);
+    }
+    if (value === undefined) return `{{${expr}}}`;
+    if (transformer === "lowercase" && typeof value === "string") return value.toLowerCase();
+    return String(value);
+  });
+}
+
+/** Recursively resolve a template (object/array/string) against the source.
+ *  Object keys containing {{...}} are resolved; bare keys pass through.
+ *  Values that are arrays/objects are recursed; strings are interpolated. */
+function _resolveTemplate(template, src, pluginRootVar) {
+  if (template === null || template === undefined) return template;
+  if (typeof template === "string") return _interpolate(template, src, pluginRootVar);
+  if (Array.isArray(template)) return template.map(item => _resolveTemplate(item, src, pluginRootVar));
+  if (typeof template === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(template)) {
+      // Resolve key: {{mcp.serverName}} -> "cool-workflow"
+      const resolvedKey = _interpolate(key, src, pluginRootVar);
+      const keyStr = typeof resolvedKey === "string" ? resolvedKey : key;
+      result[keyStr] = _resolveTemplate(value, src, pluginRootVar);
+    }
+    return result;
+  }
+  return template;
+}
+
+// ---- Build from vendor adapter registry -----------------------------------
+
+function build(src) {
+  const { targets, vendors } = src;
+  // Backward compat: if no `vendors` key, build from legacy targets
+  if (!vendors || typeof vendors !== "object" || Object.keys(vendors).length === 0) {
+    return buildLegacy(src);
+  }
+  const outputs = [];
+  for (const [vendorId, vendorDef] of Object.entries(vendors)) {
+    const targetConfig = targets && targets[vendorId] ? targets[vendorId] : {};
+    const pluginRootVar = targetConfig.pluginRootVar || "./";
+    const vendorOutputs = vendorDef.outputs || [];
+    for (const output of vendorOutputs) {
+      const resolved = _resolveTemplate(output, src, pluginRootVar);
+      outputs.push({
+        path: typeof resolved.path === "string" ? resolved.path : `vendor-${vendorId}-${outputs.length}`,
+        json: resolved.json || {}
+      });
+    }
+  }
+  return outputs;
+}
+
+/** Legacy path: build from hardcoded shapes (backward compat if no `vendors` key). */
+function buildLegacy(src) {
+  const { identity, descriptions, interface: ui, layout, mcp, targets } = src;
+  const outputs = [];
+
+  if (targets && targets.claude) {
+    outputs.push({
+      path: targets.claude.marketplace,
+      json: { name: identity.name, owner: identity.author, metadata: { description: descriptions.standard, version: identity.version }, plugins: [{ name: identity.name, source: layout.pluginPathFromRepoRoot, description: descriptions.standard, category: ui.category.toLowerCase() }] }
+    });
+    outputs.push({
+      path: targets.claude.plugin,
+      json: { name: identity.name, description: descriptions.standard, version: identity.version, author: identity.author, homepage: identity.homepage, license: identity.license, keywords: identity.keywords }
+    });
+    outputs.push({
+      path: targets.claude.mcp,
+      json: legacyMcpConfig(mcp, layout, targets.claude.pluginRootVar)
+    });
+  }
+  if (targets && targets.codex) {
+    outputs.push({
+      path: targets.codex.marketplace,
+      json: { name: identity.name, interface: { displayName: ui.displayName }, plugins: [{ name: identity.name, source: { source: "local", path: layout.pluginPathFromRepoRoot }, policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: ui.category }] }
+    });
+    outputs.push({
+      path: targets.codex.plugin,
+      json: { name: identity.name, version: identity.version, description: descriptions.standard, author: identity.author, keywords: identity.keywords, skills: layout.skillsDir, mcpServers: "./.codex-plugin/mcp.json", interface: { displayName: ui.displayName, shortDescription: descriptions.short, longDescription: descriptions.long, developerName: identity.author.name, category: ui.category, capabilities: ui.capabilities, brandColor: ui.brandColor, defaultPrompt: ui.defaultPrompt } }
+    });
+    outputs.push({
+      path: targets.codex.mcp,
+      json: legacyMcpConfig(mcp, layout, targets.codex.pluginRootVar)
+    });
+  }
+  if (targets && targets.agents) {
+    outputs.push({
+      path: targets.agents.plugin,
+      json: { name: identity.name, description: descriptions.standard, version: identity.version, author: identity.author, homepage: identity.homepage, license: identity.license, keywords: identity.keywords, skills: layout.skillsDir, mcpServers: "./.codex-plugin/mcp.json", interface: { displayName: ui.displayName, shortDescription: descriptions.short, longDescription: descriptions.long, developerName: identity.author.name, category: ui.category, capabilities: ui.capabilities, brandColor: ui.brandColor, defaultPrompt: ui.defaultPrompt } }
+    });
+    outputs.push({
+      path: targets.agents.mcp,
+      json: legacyMcpConfig(mcp, layout, targets.agents.pluginRootVar)
+    });
+  }
+
+  return outputs;
+}
+
+function legacyMcpConfig(mcp, layout, pluginRootVar) {
+  return {
+    mcpServers: {
+      [mcp.serverName]: {
+        command: mcp.command,
+        args: [`${pluginRootVar}${layout.mcpServerScript}`]
+      }
+    }
+  };
+}
+
+function serialize(json) {
+  return `${JSON.stringify(json, null, 2)}\n`;
+}
+
+function rel(absolute) {
+  return path.relative(repoRoot, absolute);
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+  const outputs = build(loadSource());
+  const results = [];
+  const drift = [];
+
+  for (const output of outputs) {
+    const absolute = path.join(repoRoot, output.path);
+    const next = serialize(output.json);
+    if (check) {
+      const current = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : null;
+      const ok = current === next;
+      if (!ok) drift.push(output.path);
+      results.push({ path: output.path, ok, status: current === null ? "missing" : ok ? "in-sync" : "drift" });
+    } else {
+      fs.mkdirSync(path.dirname(absolute), { recursive: true });
+      fs.writeFileSync(absolute, next);
+      results.push({ path: output.path, status: "written" });
+    }
+  }
+
+  process.stdout.write(`${JSON.stringify({ ok: drift.length === 0, mode: check ? "check" : "write", results }, null, 2)}\n`);
+
+  if (check && drift.length > 0) {
+    process.stderr.write(
+      `\n${drift.length} generated manifest(s) drifted from manifest/plugin.manifest.json:\n` +
+        drift.map((p) => `  - ${p}`).join("\n") +
+        `\nRun \`npm run gen:manifests\` and commit the result.\n`
+    );
+    process.exitCode = 1;
+  }
+}
+
+main();

package/scripts/golden-path.js

@@ -0,0 +1,300 @@
+#!/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 args = new Set(process.argv.slice(2));
+const jsonOutput = args.has("--json");
+const quiet = args.has("--quiet") || jsonOutput;
+const cleanup = args.has("--cleanup");
+
+function main() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "cw-e2e-golden-path-"));
+  const evidencePath = path.join(tmp, "golden-evidence.md");
+  fs.writeFileSync(
+    evidencePath,
+    [
+      "# Golden Evidence",
+      "The golden path evidence file proves the worker result and candidate score are backed by a stable file:line locator.",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  const evidenceLocator = `${evidencePath}:2`;
+
+  try {
+    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.78");
+
+    const plan = runJson(
+      [
+        "plan",
+        "end-to-end-golden-path",
+        "--repo",
+        tmp,
+        "--question",
+        "Prove the deterministic v0.1.78 end-to-end golden path."
+      ],
+      pluginRoot
+    );
+    assert.equal(plan.workflowId, "end-to-end-golden-path");
+    assert.equal(plan.pendingTasks, 1);
+    assert.ok(fs.existsSync(plan.statePath));
+
+    let state = readJson(plan.statePath);
+    assert.equal(state.workflow.app.id, "end-to-end-golden-path");
+    assert.equal(state.workflow.app.version, "0.1.78");
+    assert.equal(state.loopStage, "interpret");
+
+    const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
+    assert.ok(dispatch.dispatchId);
+    assert.equal(dispatch.tasks.length, 1);
+    assert.equal(dispatch.sandboxProfileId, "readonly");
+    assert.equal(dispatch.tasks[0].sandboxProfileId, "readonly");
+    assert.ok(dispatch.tasks[0].workerId);
+    assert.ok(dispatch.tasks[0].workerManifestPath);
+    assert.ok(dispatch.tasks[0].workerResultPath);
+    assert.ok(fs.existsSync(dispatch.manifestPath));
+
+    const dispatchState = readJson(plan.statePath);
+    const dispatchRecord = dispatchState.dispatches.find((entry) => entry.id === dispatch.dispatchId);
+    assert.ok(dispatchRecord);
+    assert.equal(dispatchRecord.sandboxProfileId, "readonly");
+    assert.deepEqual(dispatchRecord.workerIds, [dispatch.tasks[0].workerId]);
+
+    const workerId = dispatch.tasks[0].workerId;
+    const workerManifest = runJson(["worker", "manifest", plan.runId, workerId], tmp);
+    assert.equal(workerManifest.id, workerId);
+    assert.equal(workerManifest.sandboxProfileId, "readonly");
+    assert.equal(workerManifest.sandbox.profileId, "readonly");
+    assert.equal(workerManifest.sandbox.policy.network.mode, "none");
+    assert.ok(workerManifest.sandbox.policy.enforcement.enforcedByCW.length > 0);
+    assert.ok(workerManifest.sandbox.policy.enforcement.hostRequired.length > 0);
+    assert.equal(workerManifest.resultPath, dispatch.tasks[0].workerResultPath);
+
+    const manifestFile = readJson(dispatch.tasks[0].workerManifestPath);
+    assert.equal(manifestFile.id, workerId);
+    assert.equal(manifestFile.sandboxPolicy.id, "readonly");
+
+    writeWorkerResult(workerManifest.resultPath, evidenceLocator);
+    assert.ok(fs.existsSync(workerManifest.resultPath));
+
+    const workerSummary = runJson(["worker", "output", plan.runId, workerId, workerManifest.resultPath], tmp);
+    assert.equal(workerSummary.tasks.completed, 1);
+    assert.equal(workerSummary.workers.byStatus.verified, 1);
+    assert.equal(workerSummary.loopStage, "observe");
+
+    state = readJson(plan.statePath);
+    const worker = state.workers.find((entry) => entry.id === workerId);
+    assert.equal(worker.status, "verified");
+    assert.equal(worker.sandboxProfileId, "readonly");
+    assert.ok(worker.output.stateNodeId);
+    assert.ok(worker.output.verifierNodeId);
+
+    const task = state.tasks.find((entry) => entry.workerId === workerId);
+    assert.equal(task.status, "completed");
+    assert.equal(task.requiresEvidence, true);
+    assert.equal(task.sandboxProfileId, "readonly");
+
+    const resultNode = state.nodes.find((entry) => entry.id === task.resultNodeId);
+    const verifierNode = state.nodes.find((entry) => entry.id === task.verifierNodeId);
+    assert.equal(resultNode.kind, "result");
+    assert.equal(resultNode.status, "completed");
+    assert.ok(resultNode.evidence.some((entry) => entry.locator === evidenceLocator));
+    assert.equal(verifierNode.kind, "verifier");
+    assert.equal(verifierNode.status, "verified");
+    assert.ok(verifierNode.evidence.some((entry) => entry.locator === evidenceLocator));
+
+    const candidate = runJson(
+      ["candidate", "register", plan.runId, "--worker", workerId, "--id", "golden-candidate"],
+      tmp
+    );
+    assert.equal(candidate.id, "golden-candidate");
+    assert.equal(candidate.workerId, workerId);
+    assert.equal(candidate.status, "registered");
+    assert.equal(candidate.resultNodeId, resultNode.id);
+    assert.equal(candidate.verifierNodeId, verifierNode.id);
+    assert.ok(fs.existsSync(path.join(tmp, ".cw", "runs", plan.runId, "candidates", "golden-candidate", "candidate.json")));
+
+    const score = runJson(
+      [
+        "candidate",
+        "score",
+        plan.runId,
+        "golden-candidate",
+        "--criterion",
+        "correctness=4",
+        "--criterion",
+        "evidence=4",
+        "--criterion",
+        "fit=2",
+        "--maxTotal",
+        "10",
+        "--evidence",
+        evidenceLocator
+      ],
+      tmp
+    );
+    assert.equal(score.candidateId, "golden-candidate");
+    assert.equal(score.total, 10);
+    assert.equal(score.normalized, 1);
+    assert.equal(score.verdict, "pass");
+    assert.ok(
+      fs.existsSync(path.join(tmp, ".cw", "runs", plan.runId, "candidates", "golden-candidate", "scores", `${score.id}.json`))
+    );
+
+    const ranking = runJson(["candidate", "rank", plan.runId], tmp);
+    assert.equal(ranking.candidates[0].candidateId, "golden-candidate");
+    assert.equal(ranking.candidates[0].rank, 1);
+    const rankingPath = path.join(tmp, ".cw", "runs", plan.runId, "candidates", "ranking.json");
+    assert.ok(fs.existsSync(rankingPath));
+
+    const selection = runJson(
+      ["candidate", "select", plan.runId, "golden-candidate", "--reason", "golden path verified"],
+      tmp
+    );
+    assert.equal(selection.candidateId, "golden-candidate");
+    assert.equal(selection.verifierNodeId, verifierNode.id);
+    assert.equal(selection.scoreId, score.id);
+    assert.ok(selection.evidence.length > 0);
+
+    state = readJson(plan.statePath);
+    const verifiedCandidate = state.candidates.find((entry) => entry.id === "golden-candidate");
+    assert.equal(verifiedCandidate.status, "verified");
+
+    const commitResult = runJson(
+      [
+        "commit",
+        plan.runId,
+        "--selection",
+        selection.id,
+        "--reason",
+        "golden path verifier-gated commit"
+      ],
+      tmp
+    );
+    assert.equal(commitResult.runId, plan.runId);
+    assert.equal(commitResult.commit.verifierGated, true);
+    assert.equal(commitResult.commit.checkpoint, false);
+    assert.equal(commitResult.commit.selectionId, selection.id);
+    assert.equal(commitResult.commit.candidateId, "golden-candidate");
+    assert.equal(commitResult.commit.verifierNodeId, verifierNode.id);
+    assert.ok(commitResult.commit.evidence.some((entry) => entry.locator === evidenceLocator));
+    assert.ok(fs.existsSync(commitResult.commit.snapshotPath));
+
+    const reportPath = runText(["report", plan.runId], tmp).trim();
+    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\.78/);
+    assert.match(report, /## Candidates/);
+    assert.match(report, /## Trust Audit/);
+    assert.match(report, /## Acceptance Rationale/);
+    assert.match(report, /golden-candidate/);
+    assert.match(report, /verifier-gated commit/);
+    assert.match(report, /golden path verifier-gated commit/);
+
+    state = readJson(plan.statePath);
+    const finalCommit = state.commits[state.commits.length - 1];
+    assert.equal(finalCommit.id, commitResult.commit.id);
+    assert.equal(finalCommit.verifierGated, true);
+    assert.equal(finalCommit.checkpoint, false);
+    assert.equal(finalCommit.selectionId, selection.id);
+    assert.equal(finalCommit.candidateId, "golden-candidate");
+    assert.equal(finalCommit.verifierNodeId, verifierNode.id);
+    assert.ok(finalCommit.evidence.some((entry) => entry.locator === evidenceLocator));
+    assert.equal((state.feedback || []).length, 0);
+
+    const summary = {
+      ok: true,
+      runId: plan.runId,
+      workspace: tmp,
+      statePath: plan.statePath,
+      reportPath,
+      workerId,
+      candidateId: "golden-candidate",
+      selectionId: selection.id,
+      commitId: finalCommit.id,
+      evidence: [evidenceLocator, reportPath, finalCommit.snapshotPath]
+    };
+    if (jsonOutput) {
+      process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+    } else if (!quiet) {
+      process.stdout.write(
+        [
+          "golden-path: ok",
+          `run: ${summary.runId}`,
+          `report: ${summary.reportPath}`,
+          `commit: ${summary.commitId}`,
+          ""
+        ].join("\n")
+      );
+    }
+    if (cleanup) fs.rmSync(tmp, { recursive: true, force: true });
+    return summary;
+  } catch (error) {
+    if (cleanup) fs.rmSync(tmp, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function writeWorkerResult(resultPath, evidenceLocator) {
+  fs.writeFileSync(
+    resultPath,
+    [
+      "# Golden Worker Result",
+      "",
+      "The isolated worker produced deterministic evidence for the end-to-end golden path.",
+      "",
+      "```cw:result",
+      JSON.stringify({
+        summary: "Golden path worker result accepted with durable evidence.",
+        findings: [],
+        evidence: [evidenceLocator]
+      }),
+      "```",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+}
+
+function runJson(commandArgs, cwd) {
+  return JSON.parse(runText(commandArgs, cwd));
+}
+
+function runText(commandArgs, cwd) {
+  try {
+    return execFileSync(node, [cli, ...commandArgs], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    const rendered = [
+      `Command failed: node ${path.relative(pluginRoot, cli)} ${commandArgs.join(" ")}`,
+      `cwd: ${cwd}`,
+      error.stdout ? `stdout:\n${String(error.stdout)}` : "",
+      error.stderr ? `stderr:\n${String(error.stderr)}` : ""
+    ]
+      .filter(Boolean)
+      .join("\n");
+    error.message = `${error.message}\n${rendered}`;
+    throw error;
+  }
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+main();

package/scripts/mcp-server.js

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

package/scripts/new-feature.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+"use strict";
+
+// Scaffold the per-tag boilerplate for a new feature so the agent spends tokens
+// on novel logic, not on recreating the same file shapes every release.
+//
+//   node scripts/new-feature.js <slug> "<Title>" ["one-line summary"]
+//   npm run new:feature -- team-x "Team X" "what it does"
+//
+// Generates the man-page doc, the smoke-test skeleton, and a CHANGELOG entry,
+// then PRINTS the exact gate-file edits to make by hand (capability registry,
+// version:sync assertions, release-check docs-presence, npm test chain) — those
+// are intentionally not auto-edited so a scaffold can never break a gate file.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+
+function fail(msg) {
+  process.stderr.write(`new:feature error: ${msg}\n`);
+  process.exit(1);
+}
+
+function writeNew(absPath, content) {
+  if (fs.existsSync(absPath)) fail(`${path.relative(pluginRoot, absPath)} already exists`);
+  fs.writeFileSync(absPath, content);
+}
+
+function main() {
+  const slug = process.argv[2];
+  const title = process.argv[3];
+  const summary = process.argv[4] || `${title}: TODO one-line summary.`;
+  if (!slug || !title) fail('usage: node scripts/new-feature.js <slug> "<Title>" ["summary"]');
+  if (!/^[a-z][a-z0-9-]+$/.test(slug)) fail("slug must be kebab-case, e.g. team-collaboration");
+
+  const version = JSON.parse(fs.readFileSync(path.join(pluginRoot, "package.json"), "utf8")).version;
+  const docRel = `docs/${slug}.7.md`;
+  const testRel = `test/${slug}-smoke.js`;
+
+  // 1. docs/<slug>.7.md — title + version line satisfy version:sync checkIncludes.
+  writeNew(path.join(pluginRoot, docRel), `# ${title}
+
+CW v${version} adds ${title}: TODO one-paragraph description of the feature, the
+problem it solves, and what existed before it. Keep the base-system voice:
+explicit data flow, no hidden state.
+
+## Design Discipline
+
+- TODO: mechanism vs policy — what is the kernel mechanism, what is configurable policy.
+- TODO: fail-closed rule — what ambiguous/missing state surfaces as, never a guess.
+- TODO: reuse — which existing records/types this builds on without forking.
+- TODO: parity — the verbs are declared in capability-registry.ts so CLI === MCP.
+
+## CLI
+
+\`\`\`text
+TODO node dist/cli.js <verb> ... [--json]
+\`\`\`
+
+## Compatibility
+
+${title} is introduced in CW v${version}. Fields are additive and optional; older
+run state loads unchanged.
+
+## See Also
+
+cli-mcp-parity(7), web-desktop-workbench(7), security-trust-hardening(7)
+`);
+
+  // 2. test/<slug>-smoke.js — runnable stub; the "<slug>-smoke" marker satisfies
+  //    version:sync; replace the stub assertion with real coverage.
+  writeNew(path.join(pluginRoot, testRel), `"use strict";
+// ${slug}-smoke (v${version}). TODO prove, end to end:
+//   1. the happy path produces the expected durable records;
+//   2. the fail-closed rule actually refuses ambiguous/missing input;
+//   3. cw <cmd> --json === cw_<cmd> (CLI <-> MCP parity).
+
+const assert = require("node:assert/strict");
+
+function main() {
+  // TODO: build a run, exercise the feature, assert on durable state.
+  assert.ok(true, "${slug}-smoke: replace this stub with real coverage");
+  process.stdout.write("${slug}-smoke: ok (STUB — implement real assertions)\\n");
+}
+
+main();
+`);
+
+  // 3. CHANGELOG.md — ensure a section for this version, add a bullet.
+  const changelogPath = path.join(pluginRoot, "..", "..", "CHANGELOG.md");
+  let changelog = fs.readFileSync(changelogPath, "utf8");
+  const bullet = `- Added ${title}: ${summary}\n`;
+  if (changelog.includes(`## ${version}`)) {
+    changelog = changelog.replace(`## ${version}\n`, `## ${version}\n\n${bullet}`);
+  } else {
+    changelog = changelog.replace(/^# Changelog\n/, `# Changelog\n\n## ${version}\n\n${bullet}`);
+  }
+  fs.writeFileSync(changelogPath, changelog);
+
+  process.stdout.write(`new:feature "${title}" (v${version})\n`);
+  process.stdout.write(`  created  ${docRel}\n`);
+  process.stdout.write(`  created  ${testRel}\n`);
+  process.stdout.write(`  updated  CHANGELOG.md\n\n`);
+
+  // 4. Gate-file edits to make by hand (printed, never auto-applied).
+  process.stdout.write(`Remaining wiring (edit by hand — kept manual so a scaffold can't break a gate):\n\n`);
+  process.stdout.write(`  docs/index.md\n    add:  N. [${title}](${slug}.7.md) - ${summary}\n\n`);
+  process.stdout.write(`  package.json  "test" chain\n    add:  && node ${testRel}\n\n`);
+  process.stdout.write(`  scripts/release-check.js  "docs presence" list\n    add:  "${docRel}",\n\n`);
+  process.stdout.write(`  scripts/version-sync-check.js  (assert the new surfaces carry the version)\n`);
+  process.stdout.write(`    checkIncludes("plugins/cool-workflow/${docRel}", "${title}", checks);\n`);
+  process.stdout.write(`    checkIncludes("plugins/cool-workflow/${docRel}", VERSION, checks);\n`);
+  process.stdout.write(`    checkIncludes("plugins/cool-workflow/docs/index.md", "${slug}.7.md", checks);\n`);
+  process.stdout.write(`    checkIncludes("plugins/cool-workflow/${testRel}", "${slug}-smoke", checks);\n\n`);
+  process.stdout.write(`  src/capability-registry.ts  — declare the new verb(s) so CLI === MCP (parity gate).\n`);
+  process.stdout.write(`  sibling docs/*.7.md  — append a "## ${title} (v${version})" forward-reference section\n`);
+  process.stdout.write(`    to the docs version:sync checks for VERSION (that's the repo's per-release pattern).\n`);
+}
+
+main();