@xulthekl/team-flow 0.22.4

package/scripts/lib/execution-recommendation.mjs

@@ -0,0 +1,221 @@
+// Evidence-based execution-mode recommendation for DP-4.
+
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from './config-loader.mjs';
+import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+import { getOverlayPaths } from './sdd-overlay.mjs';
+import { readState } from './state-loader.mjs';
+
+export function recommendExecutionModes({ workflow, taskCount, inlineThreshold, waves = [] }) {
+  const normalizedWorkflow = typeof workflow === 'string' ? workflow : null;
+  const normalizedTaskCount = Number.isInteger(taskCount) && taskCount >= 0 ? taskCount : null;
+  const threshold = Number.isInteger(inlineThreshold) && inlineThreshold > 0 ? inlineThreshold : 3;
+  const normalizedWaves = Array.isArray(waves) ? waves : [];
+  const plannedTaskCount = normalizedWaves.reduce((count, wave) => (
+    count + (Array.isArray(wave?.tasks) ? wave.tasks.length : 0)
+  ), 0);
+  const hasParallelWave = normalizedWaves.some(wave => wave?.strategy === 'parallel');
+  const hasMultipleWaves = normalizedWaves.length > 1;
+  const facts = {
+    workflow: normalizedWorkflow,
+    documented_task_count: normalizedTaskCount,
+    planned_task_count: plannedTaskCount,
+    planned_wave_count: normalizedWaves.length,
+    has_parallel_wave: hasParallelWave,
+    inline_threshold: threshold,
+  };
+
+  if (normalizedWorkflow === 'tweak') {
+    return result(['inline'], 'inline', [
+      'Tweak uses direct inline execution and is exempt from execution-plan and review-receipt gates.',
+    ], facts);
+  }
+
+  if (hasParallelWave) {
+    return result(['inline', 'batch-inline', 'sdd'], 'sdd', [
+      'The declared execution waves include parallel work, which SDD can dispatch and review independently.',
+    ], facts);
+  }
+
+  if (hasMultipleWaves) {
+    return result(['inline', 'batch-inline', 'sdd'], 'sdd', [
+      'The declared work spans multiple waves, so SDD keeps dependencies and review receipts explicit.',
+    ], facts);
+  }
+
+  const effectiveTaskCount = plannedTaskCount || normalizedTaskCount;
+  if (effectiveTaskCount === 1) {
+    return result(['inline', 'batch-inline', 'sdd'], 'inline', [
+      'The change has a single sequential task, so inline execution keeps the work focused without dispatch overhead.',
+    ], facts);
+  }
+
+  if (effectiveTaskCount !== null && effectiveTaskCount > 1 && effectiveTaskCount <= threshold) {
+    return result(['inline', 'batch-inline', 'sdd'], 'batch-inline', [
+      `The ${effectiveTaskCount} sequential tasks are within the configured inline threshold of ${threshold}.`,
+    ], facts);
+  }
+
+  return result(['inline', 'batch-inline', 'sdd'], 'sdd', [
+    effectiveTaskCount === null
+      ? 'The task count cannot be determined, so SDD is recommended until the execution shape is made explicit.'
+      : `The ${effectiveTaskCount} tasks exceed the configured inline threshold of ${threshold}.`,
+  ], facts);
+}
+
+export function recommendExecutionModesForChange(changeDir, waves = []) {
+  const state = readState(changeDir);
+  const config = loadConfig(changeDir);
+  return recommendExecutionModes({
+    workflow: state.workflow,
+    taskCount: countDocumentedTasks(changeDir),
+    inlineThreshold: config.execution.inlineThreshold,
+    waves,
+  });
+}
+
+export function createRecommendationReceipt(changeDir, waves = []) {
+  const state = readState(changeDir);
+  const receipt = {
+    recommendation: recommendExecutionModesForChange(changeDir, waves),
+    waves: normalizeWaves(waves),
+    artifacts_hash: computeArtifactsHash(changeDir),
+    contract_hash: computeContractHash(changeDir),
+    workflow: state.workflow,
+    execution_plan_revision_at_recommendation: state.execution_plan_revision ?? null,
+    created_at: new Date().toISOString(),
+  };
+  receipt.hash = hashReceipt(receipt);
+  return receipt;
+}
+
+export function writeRecommendationReceipt(changeDir, receipt) {
+  const failures = validateRecommendationReceiptStructure(receipt);
+  if (failures.length > 0) throw new Error(`Invalid execution recommendation: ${failures.join('; ')}`);
+  const paths = getOverlayPaths(changeDir);
+  mkdirSync(paths.root, { recursive: true });
+  atomicWrite(paths.executionRecommendation, `${JSON.stringify(receipt, null, 2)}\n`);
+  return readRecommendationReceipt(changeDir);
+}
+
+export function readRecommendationReceipt(changeDir) {
+  const filePath = getOverlayPaths(changeDir).executionRecommendation;
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Unable to read execution recommendation: ${error.message}`);
+  }
+}
+
+export function readCurrentRecommendationReceipt(changeDir, waves = [], expectedPlanRevision = null) {
+  const receipt = readRecommendationReceipt(changeDir);
+  if (!receipt) {
+    throw new Error('Run "tf execution recommend" for these waves before confirming an execution plan');
+  }
+  const failures = validateRecommendationReceipt(changeDir, receipt, waves, expectedPlanRevision);
+  if (failures.length > 0) {
+    throw new Error(`Run "tf execution recommend" again before confirming an execution plan: ${failures.join('; ')}`);
+  }
+  return receipt;
+}
+
+export function validateRecommendationReceipt(changeDir, receipt, waves = [], expectedPlanRevision = null) {
+  const failures = validateRecommendationReceiptStructure(receipt);
+  if (receipt?.artifacts_hash !== computeArtifactsHash(changeDir)) failures.push('recommendation artifacts hash is stale');
+  if (receipt?.contract_hash !== computeContractHash(changeDir)) failures.push('recommendation contract hash is stale');
+  if (receipt?.workflow !== readState(changeDir).workflow) failures.push('recommendation workflow does not match state');
+  if (stableJson(receipt?.waves) !== stableJson(normalizeWaves(waves))) failures.push('recommendation waves do not match the proposed execution plan');
+  if (receipt?.execution_plan_revision_at_recommendation !== expectedPlanRevision) {
+    failures.push('recommendation was not generated after the current execution plan revision');
+  }
+  return failures;
+}
+
+function countDocumentedTasks(changeDir) {
+  const tasksPath = join(changeDir, 'tasks.md');
+  if (!existsSync(tasksPath)) return null;
+  return (readFileSync(tasksPath, 'utf8').match(/^- \[[ xX]\] /gm) || []).length;
+}
+
+function result(availableModes, mode, reasons, facts) {
+  return {
+    available_modes: availableModes,
+    recommendation: { mode, reasons },
+    facts,
+  };
+}
+
+function validateRecommendationReceiptStructure(receipt) {
+  const failures = [];
+  if (!isObject(receipt)) return ['execution recommendation must be an object'];
+  if (!isObject(receipt.recommendation)) failures.push('execution recommendation payload is required');
+  else {
+    const recommendation = receipt.recommendation;
+    if (!Array.isArray(recommendation.available_modes) || recommendation.available_modes.some(mode => !['inline', 'batch-inline', 'sdd'].includes(mode))) {
+      failures.push('execution recommendation available modes are invalid');
+    }
+    if (!isObject(recommendation.recommendation) || !['inline', 'batch-inline', 'sdd'].includes(recommendation.recommendation.mode)) {
+      failures.push('execution recommendation mode is invalid');
+    }
+    if (!Array.isArray(recommendation.recommendation?.reasons) || recommendation.recommendation.reasons.some(reason => typeof reason !== 'string' || !reason.trim())) {
+      failures.push('execution recommendation reasons are invalid');
+    }
+    if (!isObject(recommendation.facts)) failures.push('execution recommendation facts are invalid');
+  }
+  if (!Array.isArray(receipt.waves)) failures.push('execution recommendation waves are invalid');
+  if (!isNullableHash(receipt.artifacts_hash)) failures.push('execution recommendation artifacts hash is invalid');
+  if (!isNullableHash(receipt.contract_hash)) failures.push('execution recommendation contract hash is invalid');
+  if (typeof receipt.workflow !== 'string' || !receipt.workflow.trim()) failures.push('execution recommendation workflow is invalid');
+  if (receipt.execution_plan_revision_at_recommendation !== null
+    && (!Number.isInteger(receipt.execution_plan_revision_at_recommendation) || receipt.execution_plan_revision_at_recommendation < 1)) {
+    failures.push('execution recommendation plan revision is invalid');
+  }
+  if (typeof receipt.created_at !== 'string' || !receipt.created_at.trim()) failures.push('execution recommendation timestamp is invalid');
+  if (receipt.hash !== hashReceipt(receipt)) failures.push('execution recommendation hash mismatch');
+  return failures;
+}
+
+function normalizeWaves(waves) {
+  return Array.isArray(waves) ? waves.map(wave => ({
+    id: wave?.id,
+    strategy: wave?.strategy,
+    tasks: Array.isArray(wave?.tasks) ? [...wave.tasks] : wave?.tasks,
+    depends_on: Array.isArray(wave?.depends_on) ? [...wave.depends_on] : wave?.depends_on,
+  })) : [];
+}
+
+function hashReceipt(receipt) {
+  const { hash, ...content } = receipt || {};
+  return `sha256:${createHash('sha256').update(stableJson(content)).digest('hex')}`;
+}
+
+function stableJson(value, seen = new WeakSet()) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (seen.has(value)) throw new Error('circular recommendation data');
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = `[${value.map(item => stableJson(item, seen)).join(',')}]`;
+    seen.delete(value);
+    return result;
+  }
+  const result = `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key], seen)}`).join(',')}}`;
+  seen.delete(value);
+  return result;
+}
+
+function atomicWrite(targetPath, content) {
+  const tempPath = `${targetPath}.tmp-${process.pid}-${randomUUID()}`;
+  writeFileSync(tempPath, content, 'utf8');
+  renameSync(tempPath, targetPath);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNullableHash(value) {
+  return value === null || (typeof value === 'string' && value.startsWith('sha256:'));
+}

package/scripts/lib/hash.mjs

@@ -0,0 +1,74 @@
+// scripts/lib/hash.mjs — SHA256 artifact hashing for fast staleness detection
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { findCanonicalSpecFiles } from './spec-paths.mjs';
+
+// Compute a joint SHA256 hash of all 4 planning artifacts.
+// Input: proposal.md + specs/*/spec.md (sorted) + design.md + tasks.md
+export function computeArtifactsHash(changeDir) {
+  const hash = crypto.createHash('sha256');
+  let hasContent = false;
+
+  // proposal.md
+  const proposal = path.join(changeDir, 'proposal.md');
+  if (fs.existsSync(proposal)) {
+    hash.update(fs.readFileSync(proposal, 'utf-8'));
+    hasContent = true;
+  }
+
+  // specs/*/spec.md (sorted for deterministic output)
+  for (const f of findCanonicalSpecFiles(changeDir)) {
+    hash.update(fs.readFileSync(f, 'utf-8'));
+    hasContent = true;
+  }
+
+  // design.md
+  const design = path.join(changeDir, 'design.md');
+  if (fs.existsSync(design)) {
+    hash.update(fs.readFileSync(design, 'utf-8'));
+    hasContent = true;
+  }
+
+  // tasks.md
+  const tasks = path.join(changeDir, 'tasks.md');
+  if (fs.existsSync(tasks)) {
+    hash.update(fs.readFileSync(tasks, 'utf-8'));
+    hasContent = true;
+  }
+
+  return hasContent ? `sha256:${hash.digest('hex')}` : null;
+}
+
+// Compute SHA256 hash of execution-contract.md alone.
+export function computeContractHash(changeDir) {
+  const contract = path.join(changeDir, 'execution-contract.md');
+  if (!fs.existsSync(contract)) return null;
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(contract, 'utf-8'));
+  return `sha256:${hash.digest('hex')}`;
+}
+
+// Fast staleness check: compare stored artifacts_hash against current.
+export function isContractFresh(changeDir, stateLoader) {
+  const stateFile = path.join(changeDir, '.team-flow.yaml');
+  if (!fs.existsSync(stateFile)) return false;
+
+  const raw = fs.readFileSync(stateFile, 'utf-8');
+  const storedHash = extractYamlField(raw, 'artifacts_hash');
+  if (!storedHash || storedHash === 'null') return false;
+
+  const currentHash = computeArtifactsHash(changeDir);
+  return storedHash === currentHash;
+}
+
+function extractYamlField(content, field) {
+  for (const line of content.split('\n')) {
+    const match = line.match(new RegExp(`^${field}:\\s*(.*)`));
+    if (match) {
+      const val = match[1].trim();
+      return val === 'null' || val === '' ? null : val;
+    }
+  }
+  return null;
+}

package/scripts/lib/install.mjs

@@ -0,0 +1,267 @@
+// scripts/lib/install.mjs
+// Shared installer for team-flow cross-platform deployment.
+//
+// Mirrors the proven logic of scripts/install-cursor.mjs, parameterized by a
+// PlatformConfig from ./platforms.mjs. For each platform it:
+//   1. Resolves the plugin source (latest GitHub release or --local <path>).
+//   2. Copies RUNTIME_DIRS (scripts/docs/templates/dist/hooks) to
+//      <skillsDir>/team-flow/ so local runtime commands resolve.
+//   3. Copies skills/ to <skillsDir>/skills/ with portable package commands
+//      rewritten to the bundled runtime.
+//   4. Writes a phase-guard rule file to the platform's rules directory
+//      (when the platform has one) so the workflow entry rule is auto-included.
+//
+// team-flow's guard is the phase-guard RULE (auto-included by the
+// platform), not a PreToolUse hook; no hook configs are written here.
+
+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 { getPlatform, rulesTargetDir, phaseGuardFileName } from './platforms.mjs';
+import { shellQuote } from './shell-quote.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const defaultPluginRoot = resolve(__dirname, '..', '..'); // repo root when run from clone
+
+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; returns the number of top-level entries. */
+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, retaining legacy root replacement and rewriting the
+ * portable package command to the target's bundled runtime.
+ */
+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; }
+  });
+
+  function rewriteRoot(filePath) {
+    if (!existsSync(filePath)) return;
+    let content = readFileSync(filePath, '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(filePath, content, 'utf-8');
+  }
+
+  for (const name of entries) {
+    const src = join(sourceSkills, name);
+    const dst = join(targetSkills, name);
+    await cp(src, dst, { recursive: true, force: true });
+    rewriteRoot(join(dst, 'SKILL.md'));
+    // Also fix sub-prompt / reference markdown files in the skill dir.
+    for (const sub of readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md')) {
+      rewriteRoot(join(dst, sub));
+    }
+  }
+  return entries.length;
+}
+
+/** Phase-guard rule content. `mdc` gets Cursor frontmatter; `md`/`copilot` stay plain. */
+function phaseGuardContent(rulesFormat, platformId) {
+  const body = `# Phase Guard — team-flow (${platformId})
+
+## 入口规则
+
+- 所有工作必须从 "/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：是否收口归档？
+
+> 本文件由 team-flow 安装脚本生成（platform: ${platformId}）；
+> 对具体变更的 guard 内容请运行 \`tf inject <change-dir>\` 更新。
+`;
+  if (rulesFormat === 'mdc') {
+    return `---
+description: team-flow phase guard — 防止阶段漂移和未授权实现
+alwaysApply: true
+---
+
+${body}`;
+  }
+  return body;
+}
+
+/**
+ * Install team-flow for a platform.
+ *
+ * @param {string} platformId - one of NEW_PLATFORM_IDS
+ * @param {Object} [opts]
+ * @param {string} [opts.local]  - deploy from a local repo path instead of release
+ * @param {string} [opts.tag]    - specific release tag to install
+ * @param {string} [opts.cwd]    - target project root (defaults to process.cwd())
+ */
+export async function installPlatform(platformId, opts = {}) {
+  const platform = getPlatform(platformId);
+  const { values } = parseArgs({
+    options: {
+      local: { type: 'string' },
+      tag: { type: 'string' },
+    },
+    // No `args` => parseArgs reads process.argv.slice(2), so `--local`/`--tag`
+    // passed on the CLI (or forwarded by cmd-install-<id>.mjs) are honored.
+  });
+  const local = opts.local ?? values.local;
+  const tag = opts.tag ?? values.tag;
+
+  const targetRoot = opts.cwd || process.cwd();
+
+  let pluginRoot = defaultPluginRoot;
+  let isTemp = false;
+  let installedTag = null;
+
+  if (local) {
+    pluginRoot = resolve(local);
+    console.log(`📁 Using local repo: ${pluginRoot}`);
+  } else {
+    installedTag = tag || await fetchLatestTag();
+    console.log(`⬆️  Installing team-flow ${installedTag} for ${platform.name} ...`);
+    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 (project-local scope).
+  const targetPluginDir = join(targetRoot, platform.skillsDir, 'team-flow');
+  const targetSkills = join(targetRoot, platform.skillsDir, 'skills');
+  const pluginRootAbs = resolve(targetPluginDir);
+
+  try {
+    // 1. Copy runtime dependencies to <skillsDir>/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 <skillsDir>/skills/ with portable commands rewritten
+    const count = await copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs);
+    console.log(`   skills/ → ${targetSkills} (${count} skills, paths rewritten)`);
+
+    // 3. Write phase-guard rule (when the platform has a rules directory)
+    const rulesDir = rulesTargetDir(platform, targetRoot);
+    if (rulesDir) {
+      ensureDir(rulesDir);
+      const fileName = phaseGuardFileName(platform.rulesFormat);
+      const ruleFile = join(rulesDir, fileName);
+      await writeFile(ruleFile, phaseGuardContent(platform.rulesFormat, platformId), 'utf-8');
+      console.log(`   phase guard → ${ruleFile}`);
+    } else {
+      console.log(`   phase guard — skipped (${platform.name} has no rules directory)`);
+    }
+
+    console.log(`\n✅ ${platform.name} install complete:`);
+    console.log(`   Plugin root: ${pluginRootAbs}`);
+    if (installedTag) {
+      console.log(`   Version:     ${installedTag}`);
+    }
+    if (rulesDir) {
+      console.log(`\nNext: the phase-guard rule is auto-included. Try "/workflow-start".`);
+    } else {
+      console.log(`\nNext: ${platform.name} has no rules dir — invoke "/workflow-start" manually to start.`);
+    }
+    if (platform.notes) {
+      console.log(`   Note: ${platform.notes}`);
+    }
+  } finally {
+    if (isTemp) {
+      rmSync(pluginRoot, { recursive: true, force: true });
+    }
+  }
+}

package/scripts/lib/platform-runtime-inventory.mjs

@@ -0,0 +1,27 @@
+// Runtime distribution contract for every platform claimed in the public docs.
+// Modes are intentionally host-agnostic: tests validate the final artifact,
+// rather than assuming that every loader injects a plugin-root environment.
+export const PLATFORM_RUNTIME_INVENTORY = [
+  { id: 'claude-code', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'cursor', modes: ['native-root', 'installer-rewrite'] },
+  { id: 'codex-cli', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'codex-app', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'copilot-cli', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'gemini-cli', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'opencode', modes: ['canonical-fallback'] },
+  { id: 'workbuddy', modes: ['native-root', 'installer-rewrite'] },
+  { id: 'trae', modes: ['native-root', 'canonical-fallback'] },
+  { id: 'cline', modes: ['installer-rewrite'] },
+  { id: 'kiro', modes: ['installer-rewrite'] },
+  { id: 'windsurf', modes: ['installer-rewrite'] },
+  { id: 'qwen', modes: ['installer-rewrite'] },
+  { id: 'amazon-q', modes: ['installer-rewrite'] },
+  { id: 'roocode', modes: ['installer-rewrite'] },
+  { id: 'continue', modes: ['installer-rewrite'] },
+  { id: 'pi', modes: ['installer-rewrite'] },
+];
+
+export const ZCODE_COMPATIBILITY_PATH = {
+  id: 'zcode',
+  modes: ['installer-rewrite'],
+};