@rosenfan/matrix 0.1.0

package/src/installer.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createDistribution } from "./distribution.js";
+import { MATRIX_SKILLS, MATT_SKILLS, PLATFORMS, sourceSkillsRoot } from "./catalog.js";
+import { createMattAdapter } from "./matt.js";
+
+export { MATRIX_SKILLS, MATT_SKILLS, sourceSkillsRoot };
+
+export function destinationFor({ scope, projectRoot, platform = "claude-code", home }) {
+  const base = scope === "global" ? (home ?? process.env.USERPROFILE ?? process.env.HOME) : projectRoot;
+  return PLATFORMS[platform].skillRoot(base);
+}
+
+export function inspectInstallation(destination) {
+  const inspect = (names) => names.filter((skill) => {
+    try { return Boolean(destination) && requireExists(destination, skill); } catch { return false; }
+  });
+  const installed = inspect(MATRIX_SKILLS);
+  const mattInstalled = inspect(MATT_SKILLS);
+  return { installed, missing: MATRIX_SKILLS.filter((skill) => !installed.includes(skill)), mattInstalled, mattMissing: MATT_SKILLS.filter((skill) => !mattInstalled.includes(skill)) };
+}
+
+function requireExists(destination, skill) {
+  // Avoid exposing a second installation policy through this legacy helper.
+  return fs.existsSync(path.join(destination, skill, "SKILL.md"));
+}
+
+export function installMatrix({ destination, mode = "copy", conflict = "error", dryRun = false }) {
+  const platform = destination?.includes(".agents") ? "codex" : "claude-code";
+  const projectRoot = path.resolve(destination, "..", "..");
+  const distribution = createDistribution();
+  const evaluation = distribution.evaluate({ projectRoot, scope: "project", platforms: [platform], mode, matrixPolicy: conflict === "replace" ? "replace" : "safe", dryRun });
+  if (!evaluation.ok) throw new Error(evaluation.diagnostics?.[0]?.message ?? evaluation.code);
+  const result = distribution.commit(evaluation.plan);
+  if (!result.ok) throw new Error(result.error ?? result.code);
+  return { installed: result.committed ?? MATRIX_SKILLS, skipped: [], existing: [], backupRoot: result.backups?.[0] ? result.backups[0].backup : null };
+}
+
+export function installMattSkills({ projectRoot, platforms = ["claude-code"], skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
+  const result = createMattAdapter().installMissing({ projectRoot, platforms, skills, global, timeout });
+  if (!result.ok) throw new Error(`${result.code}: ${result.message}`);
+  return result;
+}
+
+export function findPython() { return null; }

package/src/matt.js

@@ -0,0 +1,34 @@
+import { execFileSync } from "node:child_process";
+import { PLATFORMS, MATT_SKILLS } from "./catalog.js";
+
+export function defaultProcessRunner({ command, args, cwd, timeout }) {
+  const executable = process.platform === "win32" && command === "npx" ? "npx.cmd" : command;
+  // The only shell-enabled case is the Windows npm shim; all inputs are catalog values.
+  return execFileSync(executable, args, { cwd, stdio: "inherit", timeout, shell: process.platform === "win32" && command === "npx" });
+}
+
+export function createMattAdapter({ run = defaultProcessRunner } = {}) {
+  return {
+    installMissing({ projectRoot, platforms, skills = MATT_SKILLS, global = false, timeout = 300_000 }) {
+      const attempted = [];
+      try {
+        for (const platform of platforms) {
+          const args = ["--yes", "skills@latest", "add", "mattpocock/skills", "--yes", "--agent", PLATFORMS[platform].skillsCliAgent];
+          for (const skill of skills) args.push("--skill", skill);
+          if (global) args.push("--global");
+          run({ command: "npx", args, cwd: projectRoot, timeout });
+          attempted.push(platform);
+        }
+        return { ok: true, code: "OK", attempted };
+      } catch (error) {
+        return {
+          ok: false,
+          code: "MATT_INSTALL_FAILED",
+          attempted,
+          message: error.message,
+          recovery: "Run matrix init --with-mattpocock after resolving the skills CLI error."
+        };
+      }
+    }
+  };
+}

package/src/messages.js

@@ -0,0 +1,33 @@
+export const messages = {
+  en: {
+    title: "Evidence-driven workflow for Matt Pocock's agent skills",
+    recommended: "Recommended setup", apply: "Apply", customize: "Customize", cancel: "Cancel",
+    project: "Project (current directory)", global: "Global (all projects)",
+    copy: "Copy (recommended)", symlink: "Symlink (advanced)",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "installed", ready: "Matrix is ready.",
+    noPlatform: "No verified platform was detected. Select Claude Code, Codex, or both.",
+    preview: "Planned changes", confirm: "Apply these changes?", doctor: "Installation diagnosis",
+    languageQuestion: "Language", scopeQuestion: "Installation scope", platformsQuestion: "Platforms",
+    mattQuestion: "Install missing Matt Pocock skills?", replaceQuestion: "Existing Matrix files are not proven managed. Back up and replace?",
+    yes: "Yes", no: "No", stateMissing: "missing", stateMatching: "up to date", stateComplete: "complete", stateUserModified: "user-modified", statePartial: "partial", stateOutdated: "outdated",
+    actionInstall: "install", actionKeep: "keep", actionBackupReplace: "back up and replace", actionRepair: "repair", actionBlocked: "requires approval",
+    dryRunComplete: "Dry run complete.", manifestMissing: "No Matrix installation manifest was found for this scope.", transactionPending: "An interrupted Matrix transaction is awaiting recovery. Run matrix init again before applying a new plan.", runtimeMissing: "Bundled Matrix runtime is missing.", brokenLink: "Broken Matrix link detected.", mattInherited: "Matt skills are satisfied by the global installation."
+  },
+  "zh-CN": {
+    manifestMissing: "当前安装范围没有 Matrix 安装清单。", transactionPending: "发现中断的 Matrix 安装事务。请再次运行 matrix init 后再应用新计划。", runtimeMissing: "缺少随附的 Matrix runtime。", brokenLink: "检测到断开的 Matrix 链接。", mattInherited: "Matt skills 由全局安装提供。",
+    languageQuestion: "语言", scopeQuestion: "安装范围", platformsQuestion: "要配置的平台",
+    mattQuestion: "是否安装缺失的 Matt Pocock skills？", replaceQuestion: "现有 Matrix 文件无法确认由 Matrix 管理。是否备份并替换？",
+    yes: "是", no: "否", stateMissing: "未安装", stateMatching: "已是最新", stateComplete: "完整", stateUserModified: "已被用户修改", statePartial: "不完整", stateOutdated: "可更新",
+    actionInstall: "安装", actionKeep: "保留", actionBackupReplace: "备份并替换", actionRepair: "修复", actionBlocked: "需要确认",
+    dryRunComplete: "预览完成。",
+    title: "面向 Matt Pocock Agent Skills 的证据驱动工作流",
+    recommended: "推荐配置", apply: "开始安装", customize: "自定义", cancel: "取消",
+    project: "项目（当前目录）", global: "全局（所有项目）",
+    copy: "复制（推荐）", symlink: "符号链接（高级）",
+    matrix: "Matrix", matt: "Matt Pocock skills", installed: "已安装", ready: "Matrix 已就绪。",
+    noPlatform: "未检测到已验证的平台。请选择 Claude Code、Codex，或两者。",
+    preview: "计划变更", confirm: "确认应用这些变更？", doctor: "安装诊断"
+  }
+};
+
+export function text(language, key) { return messages[language]?.[key] ?? messages.en[key] ?? key; }

package/src/ui.js

@@ -0,0 +1,89 @@
+import readline from "node:readline";
+import { stdin, stdout } from "node:process";
+
+const codes = { cyan: "\u001b[96m", blue: "\u001b[94m", green: "\u001b[92m", yellow: "\u001b[93m", magenta: "\u001b[95m", dim: "\u001b[2m", reset: "\u001b[0m" };
+const pause = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const logo = String.raw`███╗   ███╗ █████╗ ████████╗██████╗ ██╗██╗  ██╗
+████╗ ████║██╔══██╗╚══██╔══╝██╔══██╗██║╚██╗██╔╝
+██╔████╔██║███████║   ██║   ██████╔╝██║ ╚███╔╝
+██║╚██╔╝██║██╔══██║   ██║   ██╔══██╗██║ ██╔██╗
+██║ ╚═╝ ██║██║  ██║   ██║   ██║  ██║██║██╔╝ ██╗
+╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝`;
+const bannerLines = 9;
+
+function cancelled() {
+  const error = new Error("Cancelled.");
+  error.code = "CANCELLED";
+  return error;
+}
+
+export function createUi({ color = stdout.isTTY, animate = true } = {}) {
+  const paint = (name, value) => color ? `${codes[name]}${value}${codes.reset}` : value;
+  const shouldAnimate = animate && color && stdout.isTTY;
+  const writeFrame = (stage, status, clearPrevious = false) => {
+    if (clearPrevious) stdout.write(`\u001b[${bannerLines}A`);
+    stdout.write("\u001b[2K" + paint("green", `[ MATRIX BOOT // ${status} ]`) + "\n");
+    for (const line of logo.split("\n")) {
+      const reveal = Math.floor(line.length * stage);
+      const stable = line.slice(0, reveal);
+      const interference = stage === 1 ? "" : "#@%/\\|~".repeat(Math.ceil((line.length - reveal) / 7)).slice(0, line.length - reveal);
+      stdout.write("\u001b[2K" + paint(stage < 0.7 ? "green" : "cyan", stable + interference) + "\n");
+    }
+    stdout.write("\u001b[2K" + paint("yellow", `    ${Math.round(stage * 100)}%  ${status}`) + "\n\n");
+  };
+  return {
+    async banner() {
+      if (shouldAnimate) {
+        const sequence = [
+          [0.04, "SIGNAL LOST", 260],
+          [0.28, "MAGNETIC INTERFERENCE", 320],
+          [0.62, "NEURAL LINK FORMING", 360],
+          [1, "SIGNAL LOCKED", 420]
+        ];
+        stdout.write("\u001b[?25l");
+        try {
+          for (let index = 0; index < sequence.length; index += 1) {
+            const [stage, status, duration] = sequence[index];
+            writeFrame(stage, status, index > 0);
+            await pause(duration);
+          }
+        } finally {
+          stdout.write("\u001b[?25h");
+        }
+        stdout.write(`\u001b[${bannerLines}A`);
+      }
+      console.log(paint("cyan", logo));
+      console.log(paint("yellow", "Evidence-driven workflow for Matt Pocock's agent skills"));
+      console.log();
+    },
+    info(message) { console.log(`${paint("blue", "> ")} ${message}`); },
+    success(message) { console.log(`${paint("green", "OK")} ${message}`); },
+    warn(message) { console.log(`${paint("yellow", "!")} ${message}`); },
+    muted(message) { console.log(paint("dim", message)); },
+    async select(question, choices, initial = 0) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices[initial].value;
+      let selected = initial;
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); stdout.write(`${index === selected ? paint("blue", ">") : " "} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "return") { cleanup(); resolve(choices[selected].value); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async selectMany(question, choices) {
+      if (!stdin.isTTY || !stdout.isTTY) return choices.map((choice) => choice.value);
+      let selected = 0; const checked = new Set(choices.map((choice) => choice.value));
+      readline.emitKeypressEvents(stdin); const wasRaw = stdin.isRaw; stdin.setRawMode(true); stdin.resume(); stdout.write(`? ${question}\n`);
+      const render = (clear = false) => { if (clear) stdout.write(`\u001b[${choices.length}A`); choices.forEach((choice, index) => { stdout.write("\u001b[2K"); const marker = checked.has(choice.value) ? "[x]" : "[ ]"; stdout.write(`${index === selected ? paint("blue", ">") : " "} ${marker} ${index === selected ? paint("blue", choice.label) : choice.label}\n`); }); };
+      render();
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { stdin.off("keypress", onKeypress); stdin.setRawMode(Boolean(wasRaw)); stdin.pause(); };
+        const onKeypress = (_value, key = {}) => { if (key.ctrl && key.name === "c") { cleanup(); reject(cancelled()); } else if (["up", "k"].includes(key.name)) { selected = (selected - 1 + choices.length) % choices.length; render(true); } else if (["down", "j"].includes(key.name)) { selected = (selected + 1) % choices.length; render(true); } else if (key.name === "space") { const value = choices[selected].value; checked.has(value) ? checked.delete(value) : checked.add(value); render(true); } else if (key.name === "return") { cleanup(); resolve(choices.filter((choice) => checked.has(choice.value)).map((choice) => choice.value)); } };
+        stdin.on("keypress", onKeypress);
+      });
+    },
+    async confirm(question, defaultValue = true, labels = { yes: "Yes", no: "No" }) { return this.select(question, [{ label: defaultValue ? labels.yes : labels.no, value: defaultValue }, { label: defaultValue ? labels.no : labels.yes, value: !defaultValue }]); }
+  };
+}

package/src/workflow.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const PHASES = ["open", "design", "build", "verify", "archive"];
+const NEXT = { open: "design", design: "build", build: "verify", verify: "archive" };
+const skill = (phase) => `$matrix-${phase}`;
+const stamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+const rootFor = (cwd) => path.join(cwd, ".matrix");
+const exists = (file) => fs.existsSync(file);
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const write = (file, value) => fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+
+function fail(code, message) { return { ok: false, code, message }; }
+function taskContent(change, taskId, proposal, design, plan, resultPath) {
+  return `# Claude Code task: ${taskId}\n\n## Metadata\n\n| Field | Value |\n| --- | --- |\n| Status | CLAUDE_QUEUED |\n| Matrix change | ${change} |\n| Decision owner | Codex |\n| Implementation actor | Claude Code |\n| Result | ${resultPath} |\n\n## Objective\n\nThe frozen Matrix artifacts below are authoritative. Do not expand their scope.\n\n## Proposal\n\n${proposal}\n\n## Frozen design\n\n${design}\n\n## Ordered plan\n\n${plan}\n\n## Allowed work\n\n- Read repository instructions and existing tests before implementing.\n- Change only files required by the frozen design and plan.\n- Run every validation command specified by the plan.\n\n## Prohibited work\n\n- Do not edit Matrix state, transition its phase, archive it, or alter the frozen design.\n- Do not add unrelated features, public APIs, dependencies, or external side effects.\n- Do not claim completion without recording verifiable evidence.\n\n## Stop and report\n\nStop with \`NEEDS_DECISION\` if the scope must expand, the design conflicts with the repository, validation cannot pass within scope, or an authorization/safety issue arises.\n\n## Required result\n\nCreate \`${resultPath}\` with metadata, changed files and reasons, commands and outcomes, test results, boundary confirmation, residual risks, and any \`NEEDS_DECISION\` items. Codex reviews the result and the actual diff.\n`;
+}
+function activeBoard(taskId, taskPath, resultPath, change) {
+  return `# Active task board\n\n## Current objective\n\n| Field | Value |\n| --- | --- |\n| ID | ${taskId} |\n| Status | CLAUDE_QUEUED |\n| Matrix change | ${change} |\n| Task | ${taskPath} |\n| Result | ${resultPath} |\n`;
+}
+function paths(cwd, id) { const root = rootFor(cwd); return { root, active: path.join(root, "active.json"), change: path.join(root, "changes", id), flow: path.join(root, "changes", id, "matrix.json"), legacyFlow: path.join(root, "changes", id, "matrix.yaml"), artifacts: path.join(root, "changes", id, "artifacts") }; }
+function readFlow(p) { if (fs.existsSync(p.flow)) return read(p.flow); if (!fs.existsSync(p.legacyFlow)) return null; return Object.fromEntries(fs.readFileSync(p.legacyFlow, "utf8").split(/\r?\n/).filter((line) => line.includes(":") && !line.startsWith(" ")).map((line) => { const [key, ...value] = line.split(":"); return [key.trim(), value.join(":").trim().replace(/^"|"$/g, "")]; })); }
+function writeFlow(p, flow) { if (fs.existsSync(p.legacyFlow)) { const order = ["schema", "id", "workflow", "status", "phase", "title", "created_at", "updated_at", "acceptance", "scope"]; fs.writeFileSync(p.legacyFlow, `${order.map((key) => `${key}: ${flow[key] ?? ""}`).join("\n")}\n`); } else write(p.flow, flow); }
+function active(cwd) { const activeFile = path.join(rootFor(cwd), "active.json"); if (!fs.existsSync(activeFile)) return null; return read(activeFile).change_id; }
+function meaningful(file, headings) { if (!fs.existsSync(file)) return false; const value = fs.readFileSync(file, "utf8").trim(); return value.length >= 40 && headings.every((heading) => value.includes(heading)); }
+function guard(cwd, id, phase) {
+  const base = paths(cwd, id).artifacts;
+  const checks = phase === "open" ? [["proposal", meaningful(path.join(base, "proposal.md"), ["## Goal", "## Scope", "## Acceptance"])]]
+    : phase === "design" ? [["design", meaningful(path.join(base, "design.md"), ["## Decisions", "## Test seams"])], ["plan", meaningful(path.join(base, "plan.md"), ["## Steps", "## Validation"])]]
+      : phase === "build" ? [["plan", meaningful(path.join(base, "plan.md"), ["## Steps"])], ["build evidence", meaningful(path.join(base, "verification.md"), ["## Build evidence"])]]
+        : [["verification", meaningful(path.join(base, "verification.md"), ["## Test evidence", "## Review evidence"])]];
+  return { pass: checks.every(([, result]) => result), checks };
+}
+function event(p, name, before, after) { fs.appendFileSync(path.join(p.change, "events.jsonl"), `${JSON.stringify({ at: stamp(), event: name, from: before, to: after })}\n`); }
+
+export function invoke(argv, { cwd = process.cwd() } = {}) {
+  const [command, ...args] = argv;
+  if (command === "init") {
+    const id = (args.shift() ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+    const workflow = args.includes("--workflow") ? args[args.indexOf("--workflow") + 1] : "full";
+    const title = args.includes("--title") ? args[args.indexOf("--title") + 1] : null;
+    if (!id || !title || !["full", "hotfix", "tweak"].includes(workflow)) return fail("INVALID_INTENT", "init requires a valid change id and --title.");
+    if (active(cwd)) return fail("ACTIVE_CHANGE_EXISTS", `Active Matrix change already exists: ${active(cwd)}.`);
+    const p = paths(cwd, id); if (fs.existsSync(p.change) || fs.existsSync(path.join(p.root, "archive", id))) return fail("CHANGE_EXISTS", `Matrix change already exists: ${id}.`);
+    fs.mkdirSync(p.artifacts, { recursive: true }); fs.mkdirSync(path.join(p.root, "archive"), { recursive: true });
+    if (!fs.existsSync(path.join(p.root, "config.yaml"))) fs.writeFileSync(path.join(p.root, "config.yaml"), "schema: matrix/config/v1\nauto_transition: true\n");
+    if (!fs.existsSync(path.join(p.root, ".gitignore"))) fs.writeFileSync(path.join(p.root, ".gitignore"), "active.json\ninstallation.json\nchanges/*/run-state.json\nchanges/*/events.jsonl\nchanges/*/artifacts/handoff.md\n");
+    const flow = { schema: "matrix/change/v1", id, workflow, status: "active", phase: "open", title, created_at: stamp(), updated_at: stamp(), acceptance: "pending", scope: "pending" };
+    fs.writeFileSync(p.legacyFlow, ""); writeFlow(p, flow); write(path.join(p.change, "run-state.json"), { schema: "matrix/run/v1", current_step: "open", iteration: 0, pending_gate: null, updated_at: stamp() }); write(p.active, { change_id: id }); event(p, "initialized", null, "open"); return { ok: true, code: "OK", change_id: id, next_skill: skill("open") };
+  }
+  const id = active(cwd); if (!id) return fail("NO_ACTIVE_CHANGE", "No active Matrix change. Start with $matrix <request>.");
+  const p = paths(cwd, id); const flow = readFlow(p); if (!flow) return fail("STATE_INVALID", "active.json does not reference a valid Matrix change.");
+  if (command === "inspect") { const result = guard(cwd, id, flow.phase); return { ok: true, code: "OK", change_id: id, workflow: flow.workflow, phase: flow.phase, next_skill: skill(flow.phase), guard_pass: result.pass }; }
+  if (command === "guard") { const phase = args[0] ?? flow.phase; if (!PHASES.includes(phase)) return fail("INVALID_INTENT", "Unknown phase."); const result = guard(cwd, id, phase); return { ok: result.pass, code: result.pass ? "OK" : "GUARD_FAILED", phase, ...result }; }
+  if (command === "transition") { const to = args[0]; if (NEXT[flow.phase] !== to) return fail("ILLEGAL_TRANSITION", `Illegal transition ${flow.phase} -> ${to}.`); const result = guard(cwd, id, flow.phase); if (!result.pass) return fail("GUARD_FAILED", "Current phase guard failed."); const before = flow.phase; flow.phase = to; flow.updated_at = stamp(); writeFlow(p, flow); event(p, "transition", before, to); return { ok: true, code: "OK", change_id: id, phase: to, next_skill: skill(to) }; }
+  if (command === "archive") {
+    if (flow.phase !== "archive") return fail("ILLEGAL_TRANSITION", "Only an archive-phase change can be archived.");
+    const result = guard(cwd, id, "archive"); if (!result.pass) return fail("GUARD_FAILED", "Archive guard failed.");
+    flow.status = "archived"; flow.updated_at = stamp(); writeFlow(p, flow); event(p, "archived", "archive", "archived");
+    const target = path.join(p.root, "archive", id); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.renameSync(p.change, target); fs.rmSync(p.active);
+    return { ok: true, code: "OK", archived: id };
+  }
+  if (command === "handoff") { const destination = path.join(p.artifacts, "handoff.md"); fs.writeFileSync(destination, `# Matrix handoff: ${id}\n\n- Workflow: ${flow.workflow}\n- Current phase: ${flow.phase}\n- Resume with: \`${skill(flow.phase)}\`\n- Guard passes: ${guard(cwd, id, flow.phase).pass}\n`); return { ok: true, code: "OK", path: destination }; }
+  if (command === "export") {
+    if (flow.phase !== "design") return fail("ILLEGAL_PHASE", "Export requires the design phase.");
+    if (!guard(cwd, id, "design").pass) return fail("GUARD_FAILED", "Design guard failed.");
+    const taskId = args.includes("--task-id") ? args[args.indexOf("--task-id") + 1] : args[0];
+    const target = args.includes("--target") ? args[args.indexOf("--target") + 1] : "generic";
+    const applyBoard = args.includes("--apply-fnsec-board");
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(taskId ?? "") || !["generic", "fnsec"].includes(target)) return fail("INVALID_INTENT", "export requires a task id and target generic or fnsec.");
+    const artifacts = ["proposal.md", "design.md", "plan.md"].map((name) => path.join(p.artifacts, name));
+    if (artifacts.some((file) => !fs.existsSync(file))) return fail("ARTIFACT_MISSING", "Export requires proposal.md, design.md, and plan.md.");
+    const [proposal, design, plan] = artifacts.map((file) => fs.readFileSync(file, "utf8"));
+    if (target === "generic") {
+      const destination = path.join(p.artifacts, "claude-task.md"); const result = path.join(p.artifacts, "claude-result.md");
+      fs.writeFileSync(destination, taskContent(id, taskId, proposal, design, plan, path.relative(cwd, result).replaceAll("\\", "/")));
+      return { ok: true, code: "OK", path: destination };
+    }
+    const tasks = path.join(cwd, "docs", "tasks"); const board = path.join(tasks, "active.md");
+    if (!exists(tasks) || !exists(board)) return fail("FNSEC_TARGET_UNAVAILABLE", "FnSec target requires docs/tasks/active.md in the current project.");
+    const destination = path.join(tasks, `claude-task-${taskId}.md`); const result = path.join(tasks, `claude-result-${taskId}.md`);
+    if (exists(destination) || exists(result)) return fail("FNSEC_TASK_EXISTS", `FnSec task or result path already exists for ${taskId}.`);
+    const currentBoard = fs.readFileSync(board, "utf8");
+    if (applyBoard && !currentBoard.includes("NO_ACTIVE_OBJECTIVE")) return fail("FNSEC_BOARD_OCCUPIED", "FnSec active.md already has an objective; refused to overwrite it.");
+    fs.writeFileSync(destination, taskContent(id, taskId, proposal, design, plan, path.relative(cwd, result).replaceAll("\\", "/")));
+    if (applyBoard) fs.writeFileSync(board, activeBoard(taskId, path.relative(cwd, destination).replaceAll("\\", "/"), path.relative(cwd, result).replaceAll("\\", "/"), id));
+    return { ok: true, code: "OK", path: destination, board: applyBoard ? board : null };
+  }
+  return fail("INVALID_INTENT", `Unknown workflow command: ${command}.`);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1].replaceAll("\\", "/")}`).href) {
+  const result = invoke(process.argv.slice(2));
+  console.log(JSON.stringify(result));
+  if (!result.ok) process.exitCode = 2;
+}