@michaelxwb/code-flow 0.8.1 → 1.0.0

package/lib/hook.js

@@ -0,0 +1,99 @@
+'use strict';
+const path = require('node:path');
+const f = require('./fs');
+const config = require('./config');
+const session = require('./session');
+const task = require('./task');
+const render = require('./render');
+const markdown = require('./markdown');
+function cleanPrompt(text) {
+  let fence = null;
+  return text.replace(/<(task-notification|output-file)\b[^>]*>[\s\S]*?(?:<\/\1>|$)/gi, '')
+    .split('\n').filter(line => {
+      const marker = markdown.fenceMarker(line, fence);
+      if (marker) {
+        fence = marker.next;
+        return false;
+      }
+      return !fence && !/^\s*>/.test(line);
+    }).join('\n').replace(/\b[a-z]+:\/\/[^\s<>]+/gi, '');
+}
+function paths(prompt, root) {
+  const text = prompt.replace(/^task:[^\n]*$/gm, '');
+  const found = [];
+  const pattern = /(?:@)?(?:"([^"\r\n]+)"|'([^'\r\n]+)'|`([^`\r\n]+)`|([A-Za-z0-9_.@/\\:-]+))/g;
+  for (const match of text.matchAll(pattern)) {
+    const value = (match[1] || match[2] || match[3] || match[4]).replace(/^@/, '').replace(/[.,;:]+$/, '');
+    if (!/[\\/]/.test(value) && !/\.[A-Za-z][A-Za-z0-9]{0,9}$/.test(value)) continue;
+    try { found.push(...render.normalizePaths(root, [value])); } catch (error) {
+      if (error.code !== 'invalid_path') throw error;
+    }
+  }
+  return [...new Set(found)];
+}
+function nativeEvent(data, format) {
+  f.object(data, 'Hook input');
+  if (format === 'opencode') {
+    f.object(data.event, 'OpenCode event');
+    return { cwd: data.directory, sessionId: data.event.sessionID, prompt: data.event.prompt?.text };
+  }
+  f.demand(['claude', 'codex', 'costrict'].includes(format), 'hook_format', 'Unknown Hook format');
+  return { cwd: data.cwd, sessionId: data.session_id, prompt: data.prompt };
+}
+function parseTaskRef(value) {
+  const match = /^(.+\.md)#(TASK-\d+)$/.exec(String(value).trim());
+  f.demand(match, 'task_reference', 'Use task: <task-document>.md#TASK-NNN');
+  return { taskFile: match[1], taskId: match[2] };
+}
+
+function choose(root, prompt, token, diagnostics) {
+  const explicit = [...prompt.matchAll(/^task:[ \t]*(.+?)[ \t]*$/gm)].map(match => match[1]);
+  if (explicit.length) {
+    if (explicit.length !== 1) diagnostics.push({ code: 'task_ambiguous', message: 'Use exactly one task: <task-document>.md#TASK-NNN' });
+    else {
+      try {
+        const ref = parseTaskRef(explicit[0]);
+        const selected = task.loadTask(root, ref.taskFile, ref.taskId);
+        return { taskFile: selected.relative, taskId: selected.id };
+      } catch (error) { diagnostics.push({ code: error.code, message: error.message }); }
+    }
+    return null;
+  }
+  if (!token) return null;
+  try {
+    const binding = session.read(root, token);
+    if (!binding) return null;
+    const selected = task.loadTask(root, binding.task_file, binding.task_id);
+    f.demand(selected.status === 'in-progress', 'binding_stale', 'Bound Task is no longer in-progress');
+    return { taskFile: selected.relative, taskId: selected.id };
+  } catch (error) { diagnostics.push({ code: error.code || 'binding_invalid', message: error.message }); return null; }
+}
+function payload(format, text) {
+  return format === 'opencode' ? { context: text } :
+    { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } };
+}
+function build(data, format) {
+  const diagnostics = [];
+  try {
+    const event = nativeEvent(data, format);
+    f.demand(typeof event.prompt === 'string', 'hook_prompt', 'prompt must be a string');
+    if (!event.prompt.trim()) return { payload: null, diagnostics };
+    f.string(event.cwd, 'Hook cwd');
+    f.demand(path.isAbsolute(event.cwd), 'hook_cwd', 'Hook cwd must be absolute');
+    const root = config.findRoot(event.cwd, false);
+    if (!root) return { payload: null, diagnostics };
+    config.load(root);
+    const prompt = cleanPrompt(event.prompt);
+    const token = typeof event.sessionId === 'string' && event.sessionId ?
+      session.token(root, format, event.sessionId) : null;
+    if (!token) diagnostics.push({ code: 'session_missing', message: 'No session ID; explicit paths remain available' });
+    const selected = choose(root, prompt, token, diagnostics);
+    const result = render.inject(root, { taskFile: selected?.taskFile, taskId: selected?.taskId,
+      paths: paths(prompt, root), session: token });
+    return { ...result, payload: payload(format, result.text), diagnostics: [...diagnostics, ...result.diagnostics] };
+  } catch (error) {
+    diagnostics.push({ code: error.code || 'hook_error', message: error.message });
+    return { payload: payload(format, ''), diagnostics };
+  }
+}
+module.exports = { build, payload, paths, cleanPrompt, choose, parseTaskRef, nativeEvent };

package/lib/init.js

@@ -0,0 +1,132 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const f = require('./fs');
+const config = require('./config');
+const adapters = require('./adapters');
+const templateRoot = path.join(__dirname, '../templates');
+const SKILLS = [
+  { name: 'cf-init', path: 'cf-init' },
+  { name: 'cf-check', path: 'cf-check' },
+  { name: 'cf-spec', path: 'cf-spec' },
+  { name: 'cf-task-prd', path: 'cf-task/prd' },
+  { name: 'cf-task-align', path: 'cf-task/align' },
+  { name: 'cf-task-plan', path: 'cf-task/plan' },
+  { name: 'cf-task-start', path: 'cf-task/start' },
+  { name: 'cf-task-archive', path: 'cf-task/archive' }
+];
+const WORKFLOW_TEMPLATES = ['prd.md', 'design-lite.md', 'design-full.md',
+  'design-frontend.md', 'scenarios.md', 'task.md', 'project-guidelines.md'];
+const LAUNCHER_TEMPLATES = ['bridge.cjs', 'hook.sh', 'hook.cmd', 'hook.ps1'];
+
+function launcherContent(name, node, entry) {
+  const template = fs.readFileSync(path.join(templateRoot, 'launcher', name), 'utf8');
+  const sh = value => value.replace(/'/g, "'\\''");
+  const cmd = value => value.replace(/%/g, '%%');
+  const ps = value => value.replace(/'/g, "''");
+  if (name === 'hook.sh') return template.replaceAll('__FIXED_NODE__', sh(node))
+    .replaceAll('__FIXED_ENTRY__', sh(entry));
+  if (name === 'hook.cmd') return template.replaceAll('__FIXED_NODE__', cmd(node))
+    .replaceAll('__FIXED_ENTRY__', cmd(entry));
+  if (name === 'hook.ps1') return template.replaceAll('__FIXED_NODE__', ps(node))
+    .replaceAll('__FIXED_ENTRY__', ps(entry));
+  return template;
+}
+function installed(root) {
+  return Object.entries(adapters.PLATFORMS).filter(([name, value]) => {
+    const text = f.readText(f.inside(root, value.hooks));
+    if (text === null) return false;
+    if (name === 'opencode') return adapters.owned(text);
+    const data = f.object(JSON.parse(text), 'platform config');
+    return Object.values(data.hooks ?? {}).some(groups => Array.isArray(groups) &&
+      groups.some(group => Array.isArray(group.hooks) && group.hooks.some(adapters.managed)));
+  }).map(([name]) => name);
+}
+function add(plans, conflicts, root, relative, after, managed = false) {
+  const file = f.inside(root, relative), before = f.readText(file);
+  if (managed && before !== null && !adapters.owned(before)) {
+    conflicts.push({ path: relative, code: 'file_unmanaged',
+      message: 'Preserve/remove unmanaged file before init' });
+    return;
+  }
+  if (before !== after) plans.set(relative, { file, path: relative, before, after });
+}
+function attempt(conflicts, relative, operation) {
+  try { operation(); } catch (error) {
+    conflicts.push({ path: relative, code: error.code || 'init_file_failed', message: error.message });
+  }
+}
+function platformPlan(plans, conflicts, root, platform, node, entry) {
+  const target = adapters.PLATFORMS[platform];
+  const hookFile = f.inside(root, target.hooks);
+  const before = f.readText(hookFile);
+  if (platform === 'opencode') {
+    add(plans, conflicts, root, target.hooks, adapters.plugin(node, entry), true);
+    add(plans, conflicts, root, '.opencode/plugins/code-flow/package.json',
+      JSON.stringify({ private: true, type: 'module', managed: adapters.MARKER }, null, 2) + '\n', true);
+  }
+  else attempt(conflicts, target.hooks, () => add(plans, conflicts, root, target.hooks,
+    adapters.mergeHooks(before, platform, node, entry)));
+  const instruction = fs.readFileSync(path.join(templateRoot, 'instructions.md'), 'utf8');
+  attempt(conflicts, target.instructions, () => add(plans, conflicts, root, target.instructions,
+    adapters.instructions(f.readText(f.inside(root, target.instructions)), instruction)));
+  for (const skill of SKILLS) {
+    const name = platform === 'codex' ? skill.name : skill.path;
+    const relative = target.skills + '/' + name + (platform === 'codex' ? '/SKILL.md' : '.md');
+    add(plans, conflicts, root, relative,
+      fs.readFileSync(path.join(templateRoot, 'skills', skill.name + '.md'), 'utf8'), true);
+  }
+  if (platform === 'codex') {
+    const relative = '.codex/config.toml';
+    attempt(conflicts, relative, () => add(plans, conflicts, root, relative,
+      adapters.codexConfig(f.readText(f.inside(root, relative)))));
+  }
+}
+function plan(root, options = {}) {
+  const dataDir = f.inside(root, '.code-flow'), configuration = f.inside(root, '.code-flow/config.json');
+  const before = f.readText(configuration, 65536);
+  f.demand(before !== null || !fs.existsSync(dataDir) || fs.readdirSync(dataDir).length === 0,
+    'directory_format', 'Nonempty .code-flow without v1 config; preserve it outside the project before init');
+  if (before !== null) config.load(root);
+  const platforms = installed(root);
+  if (options.platform === 'all') {
+    for (const name of Object.keys(adapters.PLATFORMS)) if (!platforms.includes(name)) platforms.push(name);
+  } else if (options.platform) {
+    f.demand(Object.hasOwn(adapters.PLATFORMS, options.platform), 'platform_invalid', 'Unknown platform: ' + options.platform);
+    if (!platforms.includes(options.platform)) platforms.push(options.platform);
+  }
+  f.demand(platforms.length > 0, 'platform_required', 'First init requires --platform');
+  const plans = new Map(), conflicts = [];
+  if (before === null) add(plans, conflicts, root, '.code-flow/config.json',
+    fs.readFileSync(path.join(templateRoot, 'config.json'), 'utf8'));
+  for (const name of WORKFLOW_TEMPLATES) {
+    add(plans, conflicts, root, '.code-flow/templates/' + name,
+      fs.readFileSync(path.join(templateRoot, 'workflow', name), 'utf8'));
+  }
+  const node = options.node ?? process.execPath, entry = options.entry ?? path.resolve(__dirname, '../bin/code-flow.js');
+  for (const name of LAUNCHER_TEMPLATES) {
+    add(plans, conflicts, root, '.code-flow/launcher/' + name, launcherContent(name, node, entry));
+  }
+  for (const platform of platforms.sort()) platformPlan(plans, conflicts, root, platform, node, entry);
+  return { plans: [...plans.values()], platforms, conflicts };
+}
+async function init(root, options = {}) {
+  const build = () => plan(root, options);
+  const execute = prepared => {
+    if (!options.dryRun) {
+      for (const item of prepared.plans) f.atomicWrite(item.file, item.after, item.before);
+      for (const directory of ['.code-flow/specs', '.code-flow/tasks',
+        '.code-flow/templates', '.code-flow/launcher'])
+        fs.mkdirSync(f.inside(root, directory), { recursive: true });
+    }
+    return { ok: prepared.conflicts.length === 0, action: 'init', dry_run: Boolean(options.dryRun),
+      platforms: prepared.platforms, conflicts: prepared.conflicts,
+      changes: prepared.plans.map(item => ({ path: item.path,
+        action: item.before === null ? 'create' : 'update' })),
+      next: prepared.conflicts.length ? 'Resolve reported file conflicts, then re-run init.' :
+        prepared.platforms.includes('codex') ? 'Review/trust changed hooks in Codex /hooks.' : 'Reload platform configuration.' };
+  };
+  if (options.dryRun) return execute(build());
+  return f.withLock(root, 'write', async () => execute(build()));
+}
+module.exports = { init, plan, installed, WORKFLOW_TEMPLATES, LAUNCHER_TEMPLATES };

package/lib/learn.js

@@ -0,0 +1,170 @@
+'use strict';
+const path = require('node:path');
+const f = require('./fs');
+const fm = require('./frontmatter');
+const spec = require('./spec');
+const { reference } = require('./config');
+const markdown = require('./markdown');
+function normalize(text) { return text.replace(/\r\n/g, '\n').trim(); }
+function validate(delta) {
+  f.object(delta, 'Delta');
+  f.demand(typeof delta.id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(delta.id), 'delta_id', 'Invalid Delta ID');
+  f.demand(['add', 'update', 'remove'].includes(delta.op), 'delta_op', 'Invalid Delta operation');
+  const target = reference(delta.target);
+  f.demand(!target.rule, 'delta_target', 'Delta target must be a Spec path');
+  const result = { id: delta.id, op: delta.op, target: target.id,
+    evidence: normalize(f.string(delta.evidence, 'Delta evidence')) };
+  if (delta.op !== 'remove') result.rule = normalize(f.string(delta.rule, 'Delta rule'));
+  if (delta.op !== 'add') {
+    f.string(delta.ref, 'Delta ref');
+    f.demand(/^RULE-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(delta.ref), 'delta_ref', 'Invalid Delta Rule reference');
+    result.ref = delta.ref; result.before = normalize(f.string(delta.before, 'Delta before'));
+  }
+  return result;
+}
+function deltas(task) {
+  const source = task.specDelta ?? [];
+  f.demand(Array.isArray(source), 'delta_invalid', 'Spec Delta must be an array');
+  const ids = new Set();
+  return source.map(item => {
+    const delta = validate(item);
+    f.demand(!ids.has(delta.id), 'delta_duplicate', 'Duplicate Delta ID: ' + delta.id); ids.add(delta.id);
+    return delta;
+  });
+}
+function section(body, name) {
+  const lines = body.replace(/\r\n/g, '\n').split('\n');
+  let start = -1, fence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const marker = markdown.fenceMarker(lines[i], fence);
+    if (marker) {
+      fence = marker.next;
+      continue;
+    }
+    if (fence) continue;
+    if (lines[i] === '## ' + name && start === -1) { start = i; continue; }
+    if (start !== -1 && /^## /.test(lines[i])) return { lines, start, end: i };
+  }
+  return { lines, start, end: lines.length };
+}
+function records(body) {
+  const area = section(body, 'Applied Deltas');
+  if (area.start < 0) return [];
+  return area.lines.slice(area.start + 1, area.end).filter(line => line.startsWith('- ')).map(line => {
+    let record;
+    try { record = JSON.parse(line.slice(2)); } catch (error) {
+      throw new f.FlowError('delta_history', 'Invalid Applied Deltas JSON: ' + error.message);
+    }
+    f.object(record, 'Applied Delta');
+    f.string(record.source, 'Applied Delta source');
+    f.demand(/^RULE-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(record.rule) &&
+      /^[a-f0-9]{64}$/.test(record.payload_sha256), 'delta_history', 'Invalid Applied Delta record');
+    return record;
+  });
+}
+function appendSection(body, name, addition) {
+  const area = section(body, name), lines = area.lines;
+  if (area.start < 0) return body.replace(/\s*$/, '') + '\n\n## ' + name + '\n\n' + addition + '\n';
+  lines.splice(area.end, 0, addition, '');
+  return lines.join('\n');
+}
+function ruleBlock(id, text) {
+  return normalize(text).split('\n').map((line, index) => index ? (line ? '  ' + line : '') : '- [' + id + '] ' + line).join('\n');
+}
+function mutate(document, delta, history) {
+  const parsed = spec.parseRules(document.body), meta = { ...document.meta };
+  const existing = parsed.rules.find(rule => rule.id === delta.ref);
+  if (delta.op !== 'add') {
+    f.demand(existing && normalize(existing.text) === delta.before, 'delta_precondition',
+      'Rule changed or missing: ' + delta.target + '#' + delta.ref, 1);
+    const lines = parsed.lines;
+    lines.splice(existing.start, existing.end - existing.start,
+      ...(delta.op === 'remove' ? [] : [ruleBlock(existing.id, delta.rule), '']));
+    return { body: lines.join('\n'), meta, rule: existing.id, status: 'applied' };
+  }
+  const duplicate = parsed.rules.find(rule => normalize(rule.text) === delta.rule);
+  if (duplicate) return { body: document.body, meta, rule: duplicate.id, status: 'duplicate' };
+  const used = [...parsed.rules.map(rule => rule.id), ...history.map(item => item.rule)];
+  f.demand(!used.some(id => /^RULE-\d+$/.test(id) && Number(id.slice(5)) >= meta.next_rule),
+    'rule_counter', 'next_rule would reuse an allocated Rule ID', 1);
+  f.demand(Number.isSafeInteger(meta.next_rule + 1), 'rule_counter', 'next_rule exhausted', 1);
+  const id = 'RULE-' + String(meta.next_rule).padStart(3, '0'); meta.next_rule++;
+  return { body: appendSection(document.body, 'Rules', ruleBlock(id, delta.rule)), meta, rule: id, status: 'applied' };
+}
+function applyDelta(document, delta, source, globalHistory) {
+  const targetHistory = records(document.body);
+  const payload = f.hash(JSON.stringify(delta));
+  const previous = globalHistory.get(source) ?? [];
+  f.demand(previous.length <= 1, 'delta_history', 'Duplicate Applied Delta identity: ' + source, 1);
+  if (previous.length) {
+    f.demand(previous[0].record.payload_sha256 === payload, 'delta_conflict',
+      'Applied Delta payload changed: ' + source, 1);
+    return { document, result: { source, target: delta.target, rule: previous[0].record.rule,
+      status: 'already-applied' } };
+  }
+  const mutation = mutate({ ...document, body: document.body.replace(/\r\n/g, '\n') }, delta, targetHistory);
+  const record = { source, op: delta.op, rule: mutation.rule, payload_sha256: payload, at: new Date().toISOString() };
+  const body = appendSection(mutation.body, 'Applied Deltas', '- ' + JSON.stringify(record));
+  spec.parseRules(body);
+  globalHistory.set(source, [{ record, target: document.id }]);
+  const after = fm.stringify(document, mutation.meta, body.replace(/\n/g, document.eol));
+  const updated = { ...fm.parse(after), id: document.id, file: document.file };
+  return { document: updated, result: { source, target: delta.target, rule: mutation.rule, status: mutation.status } };
+}
+
+function loadHistory(root) {
+  const base = path.join(root, '.code-flow/specs'), history = new Map();
+  for (const relative of spec.walk(base)) {
+    const id = relative.slice(0, -3), document = spec.load(root, id);
+    for (const record of records(document.body)) {
+      const list = history.get(record.source) ?? [];
+      list.push({ record, target: id });
+      history.set(record.source, list);
+    }
+  }
+  return history;
+}
+function plan(root, tasks) {
+  const changes = new Map(), results = [], sources = new Map(), history = loadHistory(root);
+  const ordered = [...tasks].sort((a, b) =>
+    a.relative.localeCompare(b.relative) || a.id.localeCompare(b.id));
+  for (const task of ordered) {
+    f.demand(task.status === 'done' && !task.relative.startsWith('.code-flow/tasks/archived/'),
+      'learn_state', 'Learning requires an unarchived done Task', 1);
+    sources.set(task.relative, { file: task.document.file, raw: task.document.raw });
+    for (const delta of deltas(task)) {
+      if (!changes.has(delta.target)) {
+        const loaded = spec.load(root, delta.target);
+        changes.set(delta.target, { before: loaded.raw, document: loaded });
+      }
+      const item = changes.get(delta.target);
+      const source = task.relative.slice('.code-flow/tasks/'.length) + '#' + task.id + '#' + delta.id;
+      const applied = applyDelta(item.document, delta, source, history);
+      item.document = applied.document; results.push(applied.result);
+    }
+  }
+  return { changes: [...changes.values()].sort((a, b) => a.document.id.localeCompare(b.document.id)), results,
+    sources: [...sources.values()] };
+}
+function checkSources(prepared) {
+  for (const item of prepared.sources) f.demand(f.readText(item.file) === item.raw,
+    'concurrent_change', 'Task changed during learning: ' + item.file, 1);
+}
+function commit(prepared, writer = f.atomicWrite) {
+  checkSources(prepared);
+  for (const item of prepared.changes) {
+    checkSources(prepared);
+    if (item.document.raw !== item.before) writer(item.document.file, item.document.raw, item.before);
+  }
+  return { ok: true, action: 'learn', results: prepared.results };
+}
+function preview(prepared) {
+  return { ok: true, action: 'learn', dry_run: true, results: prepared.results,
+    changes: prepared.changes.filter(item => item.before !== item.document.raw)
+      .map(item => ({ file: item.document.file, before: item.before, after: item.document.raw })) };
+}
+async function apply(root, documents, dryRun = false) {
+  if (dryRun) return preview(plan(root, documents));
+  return f.withLock(root, 'write', async () => commit(plan(root, documents)));
+}
+module.exports = { validate, deltas, plan, commit, preview, apply, records, normalize };

package/lib/locks.js

@@ -0,0 +1,52 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const f = require('./fs');
+const repo = require('./repo');
+
+const bases = new Map();
+
+function base(root) {
+  const real = f.realpath(root);
+  if (bases.has(real)) return bases.get(real);
+  const identity = repo.identity(real);
+  const value = identity.git ? identity.git_common_dir : real;
+  bases.set(real, value);
+  return value;
+}
+
+function directory(root) {
+  return path.join(f.transientRoot(base(root)), 'locks');
+}
+
+function withRepository(root, operation) {
+  return f.withLockIn(directory(root), 'repository', operation);
+}
+
+function withRepositorySync(root, operation) {
+  const lock = f.acquireIn(directory(root), 'repository');
+  try { return operation(); } finally { f.releaseLock(lock); }
+}
+
+function acquireGroup(root, group, timeoutSeconds, signal) {
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  return new Promise((resolve, reject) => {
+    const attempt = () => {
+      if (signal.aborted) { reject(Object.assign(new Error('cancelled'), { code: 'cancelled' })); return; }
+      try { resolve(f.acquireIn(directory(root), 'group:' + group)); return; } catch (error) {
+        if (error.code !== 'locked') { reject(error); return; }
+      }
+      if (Date.now() >= deadline) {
+        reject(Object.assign(new Error('group lock timeout: ' + group), { code: 'lock_timeout' })); return;
+      }
+      setTimeout(attempt, 25);
+    };
+    attempt();
+  });
+}
+
+function release(lock) {
+  f.releaseLock(lock);
+}
+
+module.exports = { base, directory, withRepository, withRepositorySync, acquireGroup, release };

package/lib/markdown.js

@@ -0,0 +1,13 @@
+'use strict';
+
+function fenceMarker(line, current) {
+  const match = /^\s*(`{3,}|~{3,})/.exec(line);
+  if (!match) return null;
+  const token = match[1];
+  if (!current) return { next: token };
+  const closes = token[0] === current[0] && token.length >= current.length &&
+    line.slice(match[0].length).trim() === '';
+  return { next: closes ? null : current };
+}
+
+module.exports = { fenceMarker };

package/lib/process.js

@@ -0,0 +1,116 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const config = require('./config');
+const task = require('./task');
+const spec = require('./spec');
+const doctor = require('./doctor');
+
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function write(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+}
+
+function json(file, value) {
+  write(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function walk(directory, prefix = '') {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap(entry => {
+      const relative = prefix + entry.name;
+      return entry.isDirectory() ? walk(path.join(directory, entry.name), relative + '/') : [relative];
+    });
+}
+
+function copyTree(source, target) {
+  if (fs.existsSync(source)) fs.cpSync(source, target, { recursive: true });
+}
+
+function git(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  return result.status === 0 ? result.stdout : 'git unavailable\n';
+}
+
+function safe(operation) {
+  try { return operation(); } catch (error) {
+    return { error: { code: error.code || 'operation_failed', message: error.message } };
+  }
+}
+
+const README = `code-flow process bundle
+
+events.jsonl           optional CLI/Hook event log (command, args, exit, ms, byte counts, compact summary)
+task-status.json       code-flow task status --json
+doctor.json            code-flow doctor --json
+spec-list.json         code-flow spec list --json
+code-flow/specs/       project Spec snapshot
+code-flow/tasks/       project task/requirement document snapshot
+code-flow/config.json  project config
+files.sha256           SHA-256 of Specs and task documents
+git-status.txt         working tree status
+git-log.txt            recent commits
+git-diff-stat.txt      uncommitted diff summary
+transcript.jsonl       optional host conversation transcript
+
+Privacy: this bundle can contain project paths, requirement text, and conversation
+content. Review it before sharing. The event log does not store rule text or source code.
+
+Analysis targets: command sequence and timing, finish retries, blocked states,
+injected/omitted rules and byte counts, spec learn/archive results, task status,
+and the requirement documents produced by the workflow.
+`;
+
+function collect(root, options = {}) {
+  const settings = config.load(root);
+  const out = options.out ? path.resolve(options.out) :
+    path.join(root, settings.capture.path, 'bundle-' + stamp());
+  fs.mkdirSync(out, { recursive: true });
+  json(path.join(out, 'task-status.json'), safe(() => task.list(root)));
+  json(path.join(out, 'doctor.json'), safe(() => doctor.run(root)));
+  json(path.join(out, 'spec-list.json'), safe(() => spec.list(root)));
+  const events = process.env.CF_EVENT_LOG || path.join(root, settings.capture.path, 'events.jsonl');
+  if (fs.existsSync(events)) fs.copyFileSync(events, path.join(out, 'events.jsonl'));
+  copyTree(path.join(root, '.code-flow/specs'), path.join(out, 'code-flow/specs'));
+  copyTree(path.join(root, '.code-flow/tasks'), path.join(out, 'code-flow/tasks'));
+  if (fs.existsSync(path.join(root, '.code-flow/config.json'))) {
+    fs.copyFileSync(path.join(root, '.code-flow/config.json'), path.join(out, 'code-flow/config.json'));
+  }
+  const documents = [];
+  for (const name of ['specs', 'tasks']) {
+    const base = path.join(root, '.code-flow', name);
+    for (const relative of walk(base)) if (relative.endsWith('.md')) documents.push([base, relative]);
+  }
+  const lines = documents.sort(([leftBase, left], [rightBase, right]) =>
+    (leftBase + '/' + left).localeCompare(rightBase + '/' + right)).map(([base, relative]) => {
+    const file = path.join(base, relative);
+    const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    return digest + '  ' + path.relative(root, file).split(path.sep).join('/');
+  });
+  write(path.join(out, 'files.sha256'), lines.join('\n') + (lines.length ? '\n' : ''));
+  for (const [name, args] of [['git-status.txt', ['status', '--short']],
+    ['git-log.txt', ['log', '--oneline', '-20']], ['git-diff-stat.txt', ['diff', '--stat']]]) {
+    write(path.join(out, name), git(root, args));
+  }
+  let transcript = false;
+  if (options.transcript) {
+    const file = path.resolve(options.transcript);
+    if (fs.existsSync(file)) {
+      fs.copyFileSync(file, path.join(out, 'transcript.jsonl'));
+      transcript = true;
+    }
+  }
+  write(path.join(out, 'README.txt'), README);
+  return { ok: true, action: 'process collect', out, transcript,
+    text: 'Process bundle: ' + out + '\n' };
+}
+
+module.exports = { collect };