@xulthekl/team-flow 0.22.4

package/scripts/install-zcode.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// scripts/install-zcode.mjs — deploy team-flow for ZCODE Agent
+//
+// Copies the full plugin tree (skills + scripts + docs + templates + dist + hooks)
+// to .zcode/team-flow/ so that skill instructions referencing
+// ${CLAUDE_PLUGIN_ROOT}/scripts/... and ${CLAUDE_PLUGIN_ROOT}/docs/... resolve
+// correctly. Also copies skills to .zcode/skills/ (where ZCODE reads them).
+//
+// Defaults to the latest GitHub release; use --local <path> to deploy from a local repo.
+import { existsSync, mkdirSync, readdirSync, statSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { cp, writeFile, mkdtemp } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { shellQuote } from './lib/shell-quote.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultPluginRoot = dirname(__dirname); // repository root when running from clone
+const targetRoot = process.cwd();
+
+const GITHUB_REPO = 'MageByte-Zero/team-flow';
+const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+
+// Directories needed by local installer-rewritten runtime commands.
+const RUNTIME_DIRS = ['scripts', 'docs', 'templates', 'dist', 'hooks'];
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+async function fetchLatestTag() {
+  const res = await fetch(GITHUB_API_URL);
+  if (!res.ok) {
+    throw new Error(`GitHub API failed: ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  if (!data.tag_name) {
+    throw new Error('GitHub API response missing tag_name');
+  }
+  return data.tag_name;
+}
+
+async function cloneRelease(tag) {
+  const tmpDir = await mkdtemp(join('/tmp', 'team-flow-'));
+  const url = `https://github.com/${GITHUB_REPO}.git`;
+  console.log(`📥 Cloning ${tag} into ${tmpDir} ...`);
+  execFileSync('git', ['clone', '--depth', '1', '--branch', tag, url, tmpDir], {
+    stdio: 'inherit',
+  });
+  return tmpDir;
+}
+
+/**
+ * Recursively copy a directory.
+ */
+async function copyDir(src, dst) {
+  if (!existsSync(src)) return 0;
+  ensureDir(dst);
+  const entries = readdirSync(src);
+  for (const name of entries) {
+    const srcPath = join(src, name);
+    const dstPath = join(dst, name);
+    const st = statSync(srcPath);
+    if (st.isDirectory()) {
+      await copyDir(srcPath, dstPath);
+    } else {
+      await cp(srcPath, dstPath, { force: true });
+    }
+  }
+  return entries.length;
+}
+
+/**
+ * Copy skills to target, replacing ${CLAUDE_PLUGIN_ROOT} with the actual
+ * plugin root path so skill instructions work in ZCODE's environment.
+ */
+async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
+  // Clean old skill directories before copying
+  if (existsSync(targetSkills)) {
+    const oldEntries = readdirSync(targetSkills).filter(name => {
+      const full = join(targetSkills, name);
+      try { return statSync(full).isDirectory(); } catch { return false; }
+    });
+    for (const name of oldEntries) {
+      rmSync(join(targetSkills, name), { recursive: true, force: true });
+    }
+  }
+  ensureDir(targetSkills);
+  const entries = readdirSync(sourceSkills).filter(name => {
+    const full = join(sourceSkills, name);
+    try { return statSync(full).isDirectory(); } catch { return false; }
+  });
+
+  for (const name of entries) {
+    const src = join(sourceSkills, name);
+    const dst = join(targetSkills, name);
+    await cp(src, dst, { recursive: true, force: true });
+
+    // Replace ${CLAUDE_PLUGIN_ROOT} with the absolute path so commands work
+    const skillMd = join(dst, 'SKILL.md');
+    if (existsSync(skillMd)) {
+      let content = readFileSync(skillMd, 'utf-8');
+      if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
+        content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
+      }
+      content = content.replace(
+        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+      );
+      writeFileSync(skillMd, content, 'utf-8');
+    }
+    // Also fix sub-prompt files (implementer-prompt.md, etc.)
+    const subFiles = readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md');
+    for (const sub of subFiles) {
+      const subPath = join(dst, sub);
+      let content = readFileSync(subPath, 'utf-8');
+      if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
+        content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
+      }
+      content = content.replace(
+        /npx --yes --package @xulthekl\/team-flow@\d+\.\d+\.\d+ tf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'team-flow.mjs'))}`,
+      );
+      writeFileSync(subPath, content, 'utf-8');
+    }
+  }
+
+  return entries.length;
+}
+
+async function writePhaseGuard(targetRules) {
+  ensureDir(targetRules);
+  const content = `---
+description: team-flow phase guard — 防止阶段漂移和未授权实现
+alwaysApply: true
+---
+
+# Phase Guard
+
+## 入口规则
+
+- 所有工作必须从 "/workflow-start" 入口开始。
+- 在 .team-flow.yaml 中确认当前 state 和 workflow 模式之前，不要开始写代码。
+
+## 全局禁止
+
+- 没有 execution-contract.md 或未经用户明确批准，不得进入实现。
+- full/hotfix 必须先运行 tf execution plan <change-dir> ...；没有 current execution plan 不得开始实现。
+- 只有 all pass review receipts 后才可 closing；不得把未审查的 wave 当作完成。
+- 上述 plan/receipt gates 仅适用于 full/hotfix；tweak 免除这些 gates (tweak exempt)。
+- 执行过程中如果发现需求/范围变化，必须回退到 specifying 或 bridging，而不是直接改代码。
+- 不要直接调用执行类 skill（如 "/build-executor"），必须通过入口路由。
+
+## 决策点协议
+
+- DP-0：设计前确认
+- DP-1：需求确认
+- DP-2：工件审查
+- DP-3：是否批准 execution contract？
+- DP-4：先运行 tf execution recommend，展示可用模式与推荐；用户用 --confirm 确认，非推荐选择额外使用 --acknowledge-recommendation
+- DP-5：调试升级
+- DP-6：验证失败
+- DP-7：是否收口归档？
+
+> 本文件由 scripts/install-zcode.mjs 生成；对具体变更的 guard 内容请运行 tf inject <change-dir> 更新。
+`;
+  await writeFile(join(targetRules, 'phase-guard.mdc'), content, 'utf-8');
+}
+
+async function writeZCODEHooks(hooksDir) {
+  ensureDir(join(targetRoot, '.zcode'));
+  const hooksJson = {
+    hooks: [
+      {
+        event: 'sessionStart',
+        command: `bash ${join(hooksDir, 'session-start')}`,
+      },
+    ],
+  };
+  await writeFile(
+    join(targetRoot, '.zcode', 'hooks.json'),
+    JSON.stringify(hooksJson, null, 2) + '\n',
+    'utf-8',
+  );
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      local: { type: 'string' },
+      tag: { type: 'string' },
+    },
+  });
+
+  let pluginRoot = defaultPluginRoot;
+  let isTemp = false;
+  let installedTag = null;
+
+  if (values.local) {
+    pluginRoot = resolve(values.local);
+    console.log(`📁 Using local repo: ${pluginRoot}`);
+  } else {
+    installedTag = values.tag || await fetchLatestTag();
+    console.log(`⬆️  Installing team-flow ${installedTag} ...`);
+    pluginRoot = await cloneRelease(installedTag);
+    isTemp = true;
+  }
+
+  const sourceSkills = join(pluginRoot, 'skills');
+  if (!existsSync(sourceSkills)) {
+    console.error(`❌ skills/ directory not found at ${pluginRoot}`);
+    if (isTemp) rmSync(pluginRoot, { recursive: true, force: true });
+    process.exit(1);
+  }
+
+  // Target paths
+  const targetPluginDir = join(targetRoot, '.zcode', 'team-flow');
+  const targetSkills = join(targetRoot, '.zcode', 'skills');
+  const targetRules = join(targetRoot, '.zcode', 'rules');
+  const pluginRootAbs = resolve(targetPluginDir);
+
+  try {
+    // 1. Copy runtime dependencies to .zcode/team-flow/
+    console.log('📋 Copying runtime dependencies...');
+    for (const dir of RUNTIME_DIRS) {
+      const src = join(pluginRoot, dir);
+      const dst = join(targetPluginDir, dir);
+      if (existsSync(src)) {
+        const count = await copyDir(src, dst);
+        console.log(`   ${dir}/ → ${dst} (${count} entries)`);
+      } else {
+        console.log(`   ${dir}/ — skipped (not found)`);
+      }
+    }
+
+    // 2. Copy skills to .zcode/skills/ with CLAUDE_PLUGIN_ROOT replaced
+    const count = await copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs);
+    console.log(`   skills/ → ${targetSkills} (${count} skills, paths rewritten)`);
+
+    // 3. Write phase guard rule
+    await writePhaseGuard(targetRules);
+    console.log(`   phase guard → ${join(targetRules, 'phase-guard.mdc')}`);
+
+    // 4. Write .zcode/hooks.json for session-start
+    await writeZCODEHooks(join(targetPluginDir, 'hooks'));
+    console.log(`   hooks.json → ${join(targetRoot, '.zcode', 'hooks.json')}`);
+
+    console.log(`\n✅ ZCODE install complete:`);
+    console.log(`   Plugin root: ${pluginRootAbs}`);
+    if (installedTag) {
+      console.log(`   Version:     ${installedTag}`);
+    }
+    console.log(`\nNext: open ZCODE Agent and try "/workflow-start".`);
+  } finally {
+    if (isTemp) {
+      rmSync(pluginRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+main().catch(err => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});

package/scripts/lib/cmd-audit.mjs

@@ -0,0 +1,127 @@
+// scripts/lib/cmd-audit.mjs — tf audit: generate decision-point audit report
+import { existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readState } from './state-loader.mjs';
+
+const DP_NAMES = {
+  0: '用户确认门禁',
+  1: '需求确认',
+  2: '工件审查',
+  3: '契约批准',
+  4: '执行模式选择',
+  5: '调试升级',
+  6: '验证失败',
+  7: '归档确认',
+};
+
+function formatResult(result) {
+  if (result === null || result === undefined || result === '') return 'not recorded';
+  return String(result);
+}
+
+function formatTimestamp(ts) {
+  if (ts === null || ts === undefined || ts === '') return '—';
+  return String(ts);
+}
+
+function isConfirmed(value) {
+  return value === true || value === 'true';
+}
+
+function formatDpResult(state, dp) {
+  const result = formatResult(state[`dp_${dp}_result`]);
+  if (dp === 0 && result === 'not recorded' && isConfirmed(state.dp_0_confirmed)) {
+    return 'confirmed';
+  }
+  return result;
+}
+
+function generateReport(changeDir, state) {
+  const rows = [];
+  for (let i = 0; i <= 7; i++) {
+    const result = formatDpResult(state, i);
+    const timestamp = formatTimestamp(state[`dp_${i}_timestamp`]);
+    rows.push({ dp: i, name: DP_NAMES[i], result, timestamp });
+  }
+
+  const recordedCount = rows.filter(r => r.result !== 'not recorded').length;
+  const missingCount = rows.length - recordedCount;
+
+  let md = `# Decision-Point Audit Report\n\n`;
+  md += `**变更**: ${state.change_name || basename(changeDir)}  \n`;
+  md += `**生成时间**: ${new Date().toISOString()}  \n`;
+  md += `**当前状态**: ${state.state || 'unknown'}  \n\n`;
+
+  md += `## 汇总表\n\n`;
+  md += `| DP | 名称 | 结果 | 时间戳 |\n`;
+  md += `|----|------|------|--------|\n`;
+  for (const r of rows) {
+    md += `| DP-${r.dp} | ${r.name} | ${r.result} | ${r.timestamp} |\n`;
+  }
+
+  md += `\n**统计**: ${recordedCount}/8 已记录，${missingCount}/8 未记录。\n\n`;
+
+  md += `## 逐决策点说明\n\n`;
+  for (const r of rows) {
+    md += `### DP-${r.dp}: ${r.name}\n\n`;
+    md += `- **结果**: ${r.result}\n`;
+    md += `- **时间戳**: ${r.timestamp}\n`;
+    if (r.result === 'not recorded') {
+      md += '- **解读**: 该决策点尚未记录结果。如果工作流已经经过该阶段，请检查是否漏记。\n';
+    } else {
+      md += `- **解读**: 决策点 DP-${r.dp} 已记录为 "${r.result}"。\n`;
+    }
+    md += '\n';
+  }
+
+  md += `---\n\n`;
+  md += `*本报告由 \`tf audit\` 自动生成，仅供审计与归档参考。*\n`;
+
+  return md;
+}
+
+function basename(p) {
+  const parts = p.replace(/\\/g, '/').split('/').filter(Boolean);
+  return parts[parts.length - 1] || 'unknown';
+}
+
+export { generateReport, DP_NAMES };
+
+export async function run(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      output: { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const changeDir = positionals[0];
+  if (!changeDir) {
+    console.error('Usage: tf audit <change-dir> [--output <file>] [--json]');
+    process.exit(2);
+  }
+
+  const stateFile = join(changeDir, '.team-flow.yaml');
+  if (!existsSync(stateFile)) {
+    console.error(`No .team-flow.yaml found in ${changeDir}`);
+    process.exit(1);
+  }
+
+  const state = readState(changeDir);
+  const report = generateReport(changeDir, state);
+  const outputPath = values.output || join(changeDir, 'decision-point-audit.md');
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, report, 'utf-8');
+
+  if (values.json) {
+    console.log(JSON.stringify({ ok: true, output: outputPath, change_name: state.change_name, state: state.state }));
+  } else {
+    console.log(`✅ Audit report written to ${outputPath}`);
+    console.log(`   Change: ${state.change_name} | State: ${state.state}`);
+  }
+}

package/scripts/lib/cmd-checkpoint.mjs

@@ -0,0 +1,118 @@
+// scripts/lib/cmd-checkpoint.mjs - tf checkpoint recovery records
+import { parseArgs } from 'node:util';
+import { getCheckpoint, listCheckpoints, saveCheckpoint } from './sdd-overlay.mjs';
+
+const USAGE = 'Usage: tf checkpoint <save|list|show> <change-dir> [options]';
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      task: { type: 'string' }, next: { type: 'string' }, completed: { type: 'string' },
+      verification: { type: 'string' }, review: { type: 'string' }, risk: { type: 'string' },
+      'commit-start': { type: 'string' }, 'commit-end': { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+  });
+
+  const subcommand = positionals[0];
+  const changeDir = positionals[1];
+  if (!subcommand || !changeDir) usage();
+
+  if (!['save', 'list', 'show'].includes(subcommand)) {
+    console.error(`Unknown checkpoint subcommand: ${subcommand}. Valid: save, list, show`);
+    process.exit(2);
+  }
+
+  if (subcommand === 'save') {
+    if (!hasText(values.task) || !hasText(values.next)) {
+      console.error('Usage: tf checkpoint save <change-dir> --task <id> --next <text>');
+      process.exit(2);
+    }
+
+    const checkpoint = saveCheckpoint(changeDir, {
+      taskId: values.task,
+      next: values.next,
+      completed: values.completed,
+      evidence: values.verification,
+      review: values.review,
+      risk: values.risk,
+      commitStart: values['commit-start'],
+      commitEnd: values['commit-end'],
+    });
+    if (values.json) {
+      console.log(JSON.stringify({ ok: true, checkpoint }));
+    } else {
+      console.log(`Checkpoint saved: ${checkpoint.task_id}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const checkpoints = listCheckpoints(changeDir);
+    if (values.json) {
+      console.log(JSON.stringify({ ok: true, checkpoints }));
+    } else if (checkpoints.length === 0) {
+      console.log('No checkpoints found.');
+    } else {
+      for (const checkpoint of checkpoints) {
+        console.log(`${checkpoint.task_id}  status=${checkpoint.stale ? 'stale' : 'current'}  stale=${checkpoint.stale}`);
+      }
+    }
+    return;
+  }
+
+  const taskId = positionals[2];
+  if (!taskId) usage('Usage: tf checkpoint show <change-dir> <id>');
+  const checkpoint = getCheckpoint(changeDir, taskId);
+  if (!checkpoint) {
+    console.error(`Checkpoint '${taskId}' was not found`);
+    process.exit(1);
+  }
+
+  if (values.json) {
+    console.log(JSON.stringify({ ok: true, checkpoint }));
+  } else {
+    console.log(renderCheckpoint(checkpoint));
+  }
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function usage(message = USAGE) {
+  console.error(message);
+  process.exit(2);
+}
+
+function renderCheckpoint(checkpoint) {
+  return [
+    `# Checkpoint: ${checkpoint.task_id}`,
+    '',
+    `Status: ${checkpoint.stale ? 'stale' : 'current'}`,
+    `Created: ${checkpoint.created_at}`,
+    '',
+    '## Next',
+    checkpoint.next,
+    '',
+    '## Completed',
+    checkpoint.completed,
+    '',
+    '## Evidence',
+    checkpoint.evidence,
+    '',
+    '## Review',
+    checkpoint.review,
+    '',
+    '## Risk',
+    checkpoint.risk,
+    '',
+    '## Commit Start',
+    checkpoint.commit_start,
+    '',
+    '## Commit End',
+    checkpoint.commit_end,
+  ].join('\n');
+}

package/scripts/lib/cmd-config.mjs

@@ -0,0 +1,88 @@
+// tf config — display or modify configuration
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig, getDefaults, resolveModelProfile } from './config-loader.mjs';
+
+export async function run(args) {
+  const config = loadConfig(process.cwd());
+
+  // No args → display full effective config
+  if (args.length === 0) {
+    console.log('Effective configuration:');
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+
+  if (args[0] === '--resolve-model') {
+    if (!args[1]) {
+      console.error('Usage: tf config --resolve-model <profile>');
+      process.exit(2);
+    }
+    try {
+      console.log(JSON.stringify(resolveModelProfile(config, args[1])));
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --get <path>
+  if (args[0] === '--get' && args[1]) {
+    const parts = args[1].split('.');
+    let val = config;
+    for (const p of parts) {
+      if (val === undefined || val === null) { val = undefined; break; }
+      val = val[p];
+    }
+    if (val !== undefined) {
+      console.log(typeof val === 'object' ? JSON.stringify(val, null, 2) : String(val));
+    } else {
+      console.error(`Config path not found: ${args[1]}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --set <path>=<value>
+  if (args[0] === '--set' && args[1]) {
+    const eqIdx = args[1].indexOf('=');
+    if (eqIdx === -1) {
+      console.error('Usage: tf config [--get <path>] [--set <path>=<value>] [--resolve-model <profile>]');
+      process.exit(2);
+    }
+    const path = args[1].slice(0, eqIdx);
+    const rawValue = args[1].slice(eqIdx + 1);
+    // Parse value: try number, boolean, then string
+    let value;
+    if (rawValue === 'true') value = true;
+    else if (rawValue === 'false') value = false;
+    else if (/^\d+$/.test(rawValue)) value = parseInt(rawValue, 10);
+    else value = rawValue;
+
+    // Load existing config file or start from empty
+    const configPath = join(process.cwd(), 'team-flow.config.json');
+    let fileConfig = {};
+    if (existsSync(configPath)) {
+      fileConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+
+    // Set the nested value
+    const parts = path.split('.');
+    let target = fileConfig;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!target[parts[i]] || typeof target[parts[i]] !== 'object') {
+        target[parts[i]] = {};
+      }
+      target = target[parts[i]];
+    }
+    target[parts[parts.length - 1]] = value;
+
+    writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + '\n');
+    console.log(`Set ${path} = ${JSON.stringify(value)}`);
+    return;
+  }
+
+  console.error('Usage: tf config [--get <path>] [--set <path>=<value>] [--resolve-model <profile>]');
+  process.exit(2);
+}