cool-workflow 0.1.78 → 0.1.80

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

@@ -49,6 +49,7 @@ function readReleaseSource(relativePath) {
 const VERSION = JSON.parse(readReleaseSource("plugins/cool-workflow/package.json").text).version;
 const canonicalApps = [
   "architecture-review",
+  "architecture-review-fast",
   "end-to-end-golden-path",
   "pr-review-fix-ci",
   "release-cut",

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

package/skills/deploy-check/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: deploy-check
+description: >-
+  Verify Cool Workflow release, publish, deploy, or package readiness. Use when
+  Codex must check build/test gates, generated manifests, project index sync,
+  dist/source contract, changelog/release notes, npm package contents, or
+  pre-tag risk before shipping.
+---
+
+# Deploy Check
+
+## Overview
+
+Deploy check is the verifier side of release work. It confirms the artifact a
+user receives matches the source, docs, manifests, and stated capability.
+
+## Workflow
+
+1. Confirm the intended capability and release scope.
+2. Inspect branch status and generated artifact drift.
+3. Run the deterministic gates.
+4. Check docs/man-page coverage for shipped behavior.
+5. Check package contents and `dist/` policy.
+6. Report risk before any tag or publish step.
+
+## Commands
+
+```bash
+npm run build
+npm test
+npm run gen:manifests -- --check
+npm run index:check
+npm run version:sync
+npm run release:check
+git diff --check
+```
+
+For package inspection:
+
+```bash
+npm pack --dry-run
+```
+
+## Red Lines
+
+- Do not tag without test evidence.
+- Do not write reviewer verdict files by hand.
+- Do not silently skip `dist/` drift if the package still ships `dist/`.
+- Do not publish undocumented behavior.
+- Do not call a release ready if generated manifests or project index drift.
+
+## Output Rules
+
+Return a ship/no-ship verdict, gate results, artifact risks, and the next
+operator action.

package/skills/deploy-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Deploy Check"
+  short_description: "Verify release and deploy readiness."
+  default_prompt: "Use $deploy-check to verify deploy readiness."

package/skills/design-qa/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: design-qa
+description: >-
+  Evaluate Cool Workflow architecture, product design, operator UX,
+  context-pack, workflow-app, MCP/CLI, or release-process proposals. Use when
+  Codex must decide whether a design respects FreeBSD/POLA,
+  mechanism-not-policy, stable JSON surfaces, evidence, and verifier boundaries
+  before implementation.
+---
+
+# Design QA
+
+## Overview
+
+Design QA checks whether a proposed capability belongs in the kernel,
+userland, a manifest, a wrapper, a routine, or an eval before implementation.
+
+## Workflow
+
+1. State the user capability in one sentence.
+2. Identify the contract surface: CLI, MCP, `.cw/` state, file layout, docs,
+   package contents, or external wrapper.
+3. Separate mechanism from policy. Move policy into data, apps, wrappers, env,
+   or docs.
+4. Check POLA: existing outputs, flags, exit codes, and file layouts stay
+   byte-identical unless a new opt-in surface is used.
+5. Define verifier evidence: tests, manifests, screenshots for UI, replay, or
+   logs.
+6. Decide whether the work needs a new eval case or skill update.
+
+## Checks
+
+- Does it preserve stdout-as-data?
+- Does it fail closed instead of guessing?
+- Does it avoid vendor-specific parsing in `src/`?
+- Does it keep generated files verifiable?
+- Does it have a man page or docs contract?
+- Can maker and verifier run in separate worktrees?
+
+## Output Rules
+
+Return:
+
+1. Verdict: acceptable, revise, or reject.
+2. Required contract shape.
+3. Verification plan.
+4. Risks and non-goals.
+
+Do not turn design QA into implementation unless the user asks to proceed.

package/skills/design-qa/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Design QA"
+  short_description: "Check architecture and UX design quality."
+  default_prompt: "Use $design-qa to evaluate this design."

package/skills/pr-review/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pr-review
+description: >-
+  Review Cool Workflow pull requests or branch diffs. Use when Codex must
+  inspect code changes for bugs, regressions, FreeBSD/POLA violations, missing
+  tests, generated artifact drift, release-contract risk, or CI implications,
+  and return findings first with file/line citations.
+---
+
+# PR Review
+
+## Overview
+
+Review for correctness and release risk before style. Findings lead; summaries
+are secondary. Treat missing tests and POLA drift as real risks.
+
+## Workflow
+
+1. Read the diff and identify touched contracts: CLI, MCP, `.cw/` state, docs,
+   dist, manifests, tests, release flow, or public package files.
+2. Inspect the surrounding code for behavioral expectations.
+3. Check whether tests exercise the changed behavior and fail closed.
+4. Look for stdout chatter, silent fallback, hidden policy in core, untracked
+   generated drift, and accidental public-output changes.
+5. Report findings first, ordered by severity, with file and line references.
+6. Include open questions only when they block confidence.
+
+## Review Rules
+
+- Do not request cosmetic rewrites unless they hide a bug.
+- Do not approve undocumented shipped behavior.
+- Do not accept type-only additions without runtime behavior.
+- Do not accept `dist/` edits without matching `src/` changes.
+- For UI work, require screenshots or browser verification.
+
+## Output Shape
+
+Use this order:
+
+1. Findings
+2. Open questions
+3. Test gaps
+4. Short summary
+
+If there are no findings, say so clearly and name residual risk.

package/skills/pr-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PR Review"
+  short_description: "Review pull requests with cited findings."
+  default_prompt: "Use $pr-review to review this pull request."