@xulthekl/team-flow 0.22.4

package/tests/lib/hash.test.mjs

@@ -0,0 +1,138 @@
+// tests/lib/hash.test.mjs
+// Tests for scripts/lib/hash.mjs
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import crypto from 'node:crypto';
+
+let tempDir;
+
+describe('hash: computeArtifactsHash()', () => {
+  let hashMod;
+
+  before(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'tf-hash-test-'));
+    const modulePath = join(process.cwd(), 'scripts/lib/hash.mjs');
+    hashMod = await import(modulePath);
+  });
+
+  after(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns null when no artifacts exist', () => {
+    const hash = hashMod.computeArtifactsHash(tempDir);
+    assert.equal(hash, null);
+  });
+
+  it('computes hash from proposal.md alone', () => {
+    writeFileSync(join(tempDir, 'proposal.md'), '## Why\nTest proposal content');
+
+    const hash = hashMod.computeArtifactsHash(tempDir);
+    assert.ok(hash.startsWith('sha256:'));
+    assert.equal(hash.length, 64 + 7); // 'sha256:' + 64 hex chars
+  });
+
+  it('is deterministic — same content produces same hash', () => {
+    const content = '## Why\nTest proposal for hash determinism';
+    writeFileSync(join(tempDir, 'proposal.md'), content);
+
+    const h1 = hashMod.computeArtifactsHash(tempDir);
+    const h2 = hashMod.computeArtifactsHash(tempDir);
+    assert.equal(h1, h2);
+  });
+
+  it('different content produces different hash', () => {
+    writeFileSync(join(tempDir, 'proposal.md'), '## Why\nContent version A');
+    const h1 = hashMod.computeArtifactsHash(tempDir);
+
+    writeFileSync(join(tempDir, 'proposal.md'), '## Why\nContent version B');
+    const h2 = hashMod.computeArtifactsHash(tempDir);
+
+    assert.notEqual(h1, h2);
+  });
+
+  it('includes all four artifacts in hash', () => {
+    writeFileSync(join(tempDir, 'proposal.md'), '## Why\nproposal content');
+    mkdirSync(join(tempDir, 'specs', 'ui-theme'), { recursive: true });
+    writeFileSync(join(tempDir, 'specs', 'ui-theme', 'spec.md'), '# Spec\nRequirement content');
+    writeFileSync(join(tempDir, 'design.md'), '# Design\nDesign content');
+    writeFileSync(join(tempDir, 'tasks.md'), '# Tasks\nTasks content');
+
+    const h1 = hashMod.computeArtifactsHash(tempDir);
+
+    // Change one artifact → hash should change
+    writeFileSync(join(tempDir, 'design.md'), '# Design\nModified design content');
+    const h2 = hashMod.computeArtifactsHash(tempDir);
+
+    assert.notEqual(h1, h2);
+  });
+
+  it('reads canonical specs in sorted order for determinism', () => {
+    mkdirSync(join(tempDir, 'specs', 'z-auth'), { recursive: true });
+    mkdirSync(join(tempDir, 'specs', 'a-ui'), { recursive: true });
+    writeFileSync(join(tempDir, 'proposal.md'), 'proposal');
+    writeFileSync(join(tempDir, 'specs', 'z-auth', 'spec.md'), 'auth spec');
+    writeFileSync(join(tempDir, 'specs', 'a-ui', 'spec.md'), 'ui spec');
+
+    const h1 = hashMod.computeArtifactsHash(tempDir);
+
+    // Same files, same content → same hash
+    const h2 = hashMod.computeArtifactsHash(tempDir);
+    assert.equal(h1, h2);
+  });
+
+  it('ignores non-.md files in specs directory', () => {
+    mkdirSync(join(tempDir, 'specs', 'ui-theme'), { recursive: true });
+    writeFileSync(join(tempDir, 'proposal.md'), 'proposal');
+    writeFileSync(join(tempDir, 'specs', 'ui-theme', 'spec.md'), 'spec content');
+    writeFileSync(join(tempDir, 'specs', 'notes.txt'), 'some notes'); // non-.md
+
+    const h1 = hashMod.computeArtifactsHash(tempDir);
+
+    // Change non-.md file → hash should NOT change
+    writeFileSync(join(tempDir, 'specs', 'notes.txt'), 'modified notes');
+    const h2 = hashMod.computeArtifactsHash(tempDir);
+
+    assert.equal(h1, h2);
+  });
+});
+
+describe('hash: computeContractHash()', () => {
+  let hashMod;
+
+  before(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'tf-hash-contract-'));
+    const modulePath = join(process.cwd(), 'scripts/lib/hash.mjs');
+    hashMod = await import(modulePath);
+  });
+
+  after(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns null when execution-contract.md does not exist', () => {
+    const hash = hashMod.computeContractHash(tempDir);
+    assert.equal(hash, null);
+  });
+
+  it('computes hash of execution-contract.md', () => {
+    writeFileSync(join(tempDir, 'execution-contract.md'), '## Intent Lock\nContract content');
+
+    const hash = hashMod.computeContractHash(tempDir);
+    assert.ok(hash.startsWith('sha256:'));
+    assert.equal(hash.length, 64 + 7);
+  });
+
+  it('is independent of artifacts hash', () => {
+    writeFileSync(join(tempDir, 'execution-contract.md'), 'contract v1');
+    writeFileSync(join(tempDir, 'proposal.md'), 'proposal v1');
+
+    const contractHash = hashMod.computeContractHash(tempDir);
+    const artifactsHash = hashMod.computeArtifactsHash(tempDir);
+
+    assert.notEqual(contractHash, artifactsHash);
+  });
+});

package/tests/lib/infer-workflow.test.mjs

@@ -0,0 +1,161 @@
+// tests/lib/infer-workflow.test.mjs
+// Tests for scripts/infer-workflow.mjs — mode inference logic
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tempDir;
+
+describe('infer-workflow: inferMode()', () => {
+  let inferMode;
+
+  before(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'tf-infer-'));
+    const modulePath = join(process.cwd(), 'scripts/infer-workflow.mjs');
+    const mod = await import(modulePath);
+    inferMode = mod.inferMode;
+  });
+
+  after(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns full mode for empty directory (no artifacts)', () => {
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'full');
+    assert.equal(result.explicit, false);
+  });
+
+  it('preserves explicit hotfix override', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: executing\nworkflow: hotfix');
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'hotfix');
+    assert.equal(result.explicit, true);
+  });
+
+  it('preserves explicit tweak override', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: executing\nworkflow: tweak');
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'tweak');
+    assert.equal(result.explicit, true);
+  });
+
+  it('infers hotfix for small change (≤2 tasks, ≤2 files, no code files in tasks)', () => {
+    // Use consistent paths — same file names in proposal AND tasks to avoid unique-count inflation
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Proposal\nFix typo in README.md');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Fix typo in README.md\n- [ ] Verify fix');
+
+    const result = inferMode(tempDir);
+    // Hotfix check runs before tweak; 2 tasks, 1 file, no keywords → hotfix wins
+    assert.equal(result.mode, 'hotfix', `Expected hotfix but got ${result.mode}: ${result.reason}`);
+  });
+
+  it('infers hotfix for small code change (≤2 tasks, ≤2 files, no schema)', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Proposal\nFix null check in util.ts');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Add null check in util.ts\n- [ ] Add test for null case');
+
+    const result = inferMode(tempDir);
+    // 2 tasks, 1 file (util.ts), no schema keyword, code file → hotfix
+    assert.equal(result.mode, 'hotfix', `Expected hotfix but got ${result.mode}: ${result.reason}`);
+  });
+
+  it('infers hotfix for small Java code changes', () => {
+    const changeDir = mkdtempSync(join(tempDir, 'java-hotfix-'));
+    writeFileSync(join(changeDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(changeDir, 'proposal.md'), '# Proposal\nFix null check in src/Main.java');
+    writeFileSync(join(changeDir, 'tasks.md'), '- [ ] Fix null check in src/Main.java\n- [ ] Add regression test');
+
+    const result = inferMode(changeDir);
+
+    assert.equal(result.mode, 'hotfix', `Expected hotfix but got ${result.mode}: ${result.reason}`);
+  });
+
+  it('does not infer tweak for multi-task Java and Go code changes', () => {
+    const javaDir = mkdtempSync(join(tempDir, 'java-code-'));
+    writeFileSync(join(javaDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(javaDir, 'proposal.md'), '# Proposal\nRefactor service in src/Main.java');
+    writeFileSync(join(javaDir, 'tasks.md'), '- [ ] Update service in src/Main.java\n- [ ] Add unit test\n- [ ] Update integration test');
+
+    const goDir = mkdtempSync(join(tempDir, 'go-code-'));
+    writeFileSync(join(goDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(goDir, 'proposal.md'), '# Proposal\nRefactor handler in cmd/server/main.go');
+    writeFileSync(join(goDir, 'tasks.md'), '- [ ] Update handler in cmd/server/main.go\n- [ ] Add unit test\n- [ ] Update wiring');
+
+    assert.equal(inferMode(javaDir).mode, 'full');
+    assert.equal(inferMode(goDir).mode, 'full');
+  });
+
+  it('does not infer tweak for multi-task Python and Rust code changes', () => {
+    const pythonDir = mkdtempSync(join(tempDir, 'python-code-'));
+    writeFileSync(join(pythonDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(pythonDir, 'proposal.md'), '# Proposal\nRefactor worker in app/worker.py');
+    writeFileSync(join(pythonDir, 'tasks.md'), '- [ ] Update worker in app/worker.py\n- [ ] Add unit test\n- [ ] Update scheduler');
+
+    const rustDir = mkdtempSync(join(tempDir, 'rust-code-'));
+    writeFileSync(join(rustDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(rustDir, 'proposal.md'), '# Proposal\nRefactor parser in src/parser.rs');
+    writeFileSync(join(rustDir, 'tasks.md'), '- [ ] Update parser in src/parser.rs\n- [ ] Add unit test\n- [ ] Update caller');
+
+    assert.equal(inferMode(pythonDir).mode, 'full');
+    assert.equal(inferMode(rustDir).mode, 'full');
+  });
+
+  it('infers tweak for config/doc-only change (≤4 tasks)', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Proposal\nUpdate README.md');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Update README.md\n- [ ] Update CHANGELOG.md\n- [ ] Update version in package.json');
+
+    const result = inferMode(tempDir);
+    // 3 tasks, only doc/config files → tweak
+    assert.equal(result.mode, 'tweak', `Expected tweak but got ${result.mode}: ${result.reason}`);
+  });
+
+  it('infers full when schema keyword detected', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Proposal\nChange the API interface for src/auth.ts');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Update API\n- [ ] Update tests');
+
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'full');
+    assert.ok(result.reason.includes('schema/API'));
+  });
+
+  it('infers full when new module keyword detected', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Proposal\nAdd 新增模块 for payment processing');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Create new module');
+
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'full');
+    assert.ok(result.reason.includes('new module'));
+  });
+
+  it('infers full when too many files (> 2) for hotfix', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Big change\nModify src/a.ts src/b.ts src/c.ts');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Task 1\n- [ ] Task 2\n- [ ] Task 3');
+
+    const result = inferMode(tempDir);
+    // 3 files > 2 → not hotfix; 3 tasks ≤ 4 but files contain code → not tweak → full
+    assert.equal(result.mode, 'full');
+  });
+
+  it('infers full when too many tasks (> 2) for hotfix (but not tweak due to code files)', () => {
+    writeFileSync(join(tempDir, '.team-flow.yaml'), 'state: exploring\nworkflow: auto');
+    writeFileSync(join(tempDir, 'proposal.md'), '# Change\nModify src/a.ts');
+    writeFileSync(join(tempDir, 'tasks.md'), '- [ ] Task 1\n- [ ] Task 2\n- [ ] Task 3\n- [ ] Task 4\n- [ ] Task 5');
+
+    const result = inferMode(tempDir);
+    assert.equal(result.mode, 'full');
+  });
+
+  it('returns reason string for all modes', () => {
+    const result = inferMode(tempDir);
+    assert.ok(typeof result.reason === 'string');
+    assert.ok(result.reason.length > 0);
+  });
+});

package/tests/lib/install-git-hooks.test.mjs

@@ -0,0 +1,20 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const source = readFileSync(join(process.cwd(), 'scripts', 'install-git-hooks.mjs'), 'utf8');
+
+describe('install-git-hooks', () => {
+  it('resolves the hook directory and checked repository from Git at runtime', () => {
+    assert.match(source, /git rev-parse --git-path hooks/);
+    assert.match(source, /git rev-parse --show-toplevel/);
+    assert.doesNotMatch(source, /REPO_ROOT="\$\(cd "\$\(dirname "\$0"\)\/\.\.\/\.\." && pwd\)"/);
+  });
+
+  it('upgrades an existing team-flow hook when its generated content is stale', () => {
+    assert.match(source, /existing === HOOK_SCRIPT/);
+    assert.match(source, /Updating existing pre-commit hook/);
+    assert.doesNotMatch(source, /if \(existing\.includes\(MARKER\)\) \{\s*console\.log\([^\n]+\);\s*process\.exit\(0\);/s);
+  });
+});

package/tests/lib/marketplace-release-docs.test.mjs

@@ -0,0 +1,31 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const read = file => readFileSync(join(process.cwd(), file), 'utf8');
+
+describe('marketplace release documentation', () => {
+  it('uses the real Codex selectors and upgrade flow', () => {
+    for (const text of [read('README.md'), read('INSTALL.md')]) {
+      assert.match(text, /team-flow@awesome-codex-plugins/);
+      assert.match(text, /team-flow@team-flow/);
+      assert.match(text, /codex plugin marketplace upgrade awesome-codex-plugins/);
+      assert.doesNotMatch(text, /codex plugin update/);
+      assert.match(text, /codex plugin list/);
+    }
+  });
+
+  it('records v0.9.0 highlights and the external delivery gate', () => {
+    const readme = read('README.md');
+    const checklist = read('docs/release-checklist.md');
+    assert.match(readme, /v0\.9\.0/);
+    assert.match(readme, /Node 20/);
+    assert.match(readme, /model profiles/);
+    assert.match(readme, /最小性/);
+    assert.match(checklist, /AI Agent Marketplace Delivery/);
+    assert.match(checklist, /verify-marketplace-release/);
+    assert.match(checklist, /同步 PR/);
+    assert.match(checklist, /干净 Codex/);
+  });
+});

package/tests/lib/minimality-discipline.test.mjs

@@ -0,0 +1,37 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const read = file => readFileSync(join(ROOT, file), 'utf8');
+
+describe('minimality discipline: broad reviewer', () => {
+  it('traces unrequested complexity to the missing requirement and diff line', () => {
+    const skill = read('skills/code-reviewer/SKILL.md');
+    const prompt = read('skills/code-reviewer/code-reviewer-prompt.md');
+    assert.match(skill, /## Minimality And Scope/);
+    assert.match(skill, /missing task requirement and diff line/);
+    assert.match(skill, /Important for merge-blocking complexity/);
+    assert.match(skill, /Minor for safe/);
+    assert.match(skill, /never score by line count/);
+    assert.match(prompt, /## Minimality And Scope/);
+    assert.match(prompt, /unrequested dependency, configuration surface, abstraction, or unrelated refactor/);
+    assert.match(prompt, /missing task requirement and diff line/);
+    assert.match(prompt, /merge-blocking complexity as Important/);
+    assert.match(prompt, /behavior-neutral redundancy as Minor/);
+    assert.match(prompt, /Do not use line count as evidence/);
+    assert.match(prompt, /do not recommend removing\s+required tests, validation, security, or error handling/);
+  });
+
+  it('records #38 without adding a Ponytail dependency', () => {
+    const changelog = read('CHANGELOG.md');
+    const pkg = JSON.parse(read('package.json'));
+    const lock = JSON.parse(read('package-lock.json'));
+    assert.match(changelog, /#38/);
+    assert.match(changelog, /不引入 Ponytail 或任何 runtime dependency/);
+    assert.equal(pkg.dependencies?.ponytail, undefined);
+    assert.equal(pkg.devDependencies?.ponytail, undefined);
+    assert.equal(lock.packages['node_modules/ponytail'], undefined);
+  });
+});

package/tests/lib/model-profiles-docs.test.mjs

@@ -0,0 +1,33 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const PROFILES = ['mechanical', 'standard', 'strong', 'review'];
+const FILES = [
+  'skills/build-executor/SKILL.md',
+  'README.md',
+  'docs/README_en.md',
+  'CHANGELOG.md',
+];
+
+describe('model profile documentation', () => {
+  it('names every supported profile in all affected documentation', () => {
+    for (const file of FILES) {
+      const content = readFileSync(join(ROOT, file), 'utf8');
+      for (const profile of PROFILES) {
+        assert.match(content, new RegExp(`\\b${profile}\\b`), `${file} must name ${profile}`);
+      }
+    }
+  });
+
+  it('documents read-only resolution without automatic switching', () => {
+    const zh = readFileSync(join(ROOT, 'README.md'), 'utf8');
+    const en = readFileSync(join(ROOT, 'docs/README_en.md'), 'utf8');
+    assert.match(zh, /--resolve-model/);
+    assert.match(zh, /不切换当前会话模型/);
+    assert.match(en, /--resolve-model/);
+    assert.match(en, /does not switch models/);
+  });
+});

package/tests/lib/node20-compatibility.test.mjs

@@ -0,0 +1,73 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const read = file => readFileSync(join(ROOT, file), 'utf8');
+const ciJob = (ci, name, nextName) => {
+  const start = ci.indexOf(`  ${name}:`);
+  const end = nextName ? ci.indexOf(`  ${nextName}:`, start) : ci.length;
+  return ci.slice(start, end);
+};
+
+describe('Node 20 compatibility contract', () => {
+  it('declares Node 20 in package metadata and lockfile', () => {
+    const pkg = JSON.parse(read('package.json'));
+    const lock = JSON.parse(read('package-lock.json'));
+    assert.equal(pkg.engines.node, '>=20');
+    assert.equal(lock.packages[''].engines.node, '>=20');
+    assert.equal(lock.packages['node_modules/typescript'].engines.node, '>=14.17');
+  });
+
+  it('isolates CI jobs so adjacent runtime settings cannot satisfy a job contract', () => {
+    const fixture = `  build-and-test:
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/setup-node
+        with:
+          node-version: 22
+  platform-install-smoke:
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/setup-node
+        with:
+          node-version: \${{ matrix.node-version }}`;
+
+    assert.doesNotMatch(
+      ciJob(fixture, 'build-and-test', 'platform-install-smoke'),
+      /node-version: \$\{\{ matrix\.node-version \}\}/,
+    );
+  });
+
+  it('runs build, test, doctor, CLI smoke, and installers on Node 20 and 22', () => {
+    const ci = read('.github/workflows/ci.yml');
+    const build = ciJob(ci, 'build-and-test', 'platform-install-smoke');
+    const platform = ciJob(ci, 'platform-install-smoke', 'release');
+    const release = ciJob(ci, 'release');
+
+    for (const job of [build, platform]) {
+      assert.match(job, /node-version: \[20, 22\]/);
+      assert.match(job, /node-version: \$\{\{ matrix\.node-version \}\}/);
+    }
+
+    assert.match(build, /- run: npm run build/);
+    assert.match(build, /- run: npm test/);
+    assert.match(build, /run: node scripts\/check-version-consistency\.mjs/);
+    assert.match(build, /node scripts\/team-flow\.mjs doctor/);
+    assert.match(build, /node scripts\/team-flow\.mjs --version/);
+    assert.match(build, /config --get execution\.inlineThreshold/);
+    assert.match(release, /node-version: 22\n          registry-url:/);
+  });
+
+  it('keeps project guidance aligned with the Node 20 test command', () => {
+    const guide = read('AGENTS.md');
+    assert.match(guide, /Node 20\+ native test runner/);
+    assert.match(guide, /tests\/e2e\.test\.mjs/);
+    assert.doesNotMatch(guide, /experimental-strip-types/);
+  });
+});

package/tests/lib/node20-test-entry.test.mjs

@@ -0,0 +1,17 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+
+describe('Node 20 test entry', () => {
+  it('runs only ESM JavaScript test files without strip-types', () => {
+    assert.match(pkg.scripts.test, /tests\/e2e\.test\.mjs/);
+    assert.match(pkg.scripts.test, /tests\/lib\/\*\.test\.mjs/);
+    assert.doesNotMatch(pkg.scripts.test, /experimental-strip-types/);
+    assert.equal(existsSync(join(ROOT, 'tests', 'e2e.test.mjs')), true);
+    assert.equal(existsSync(join(ROOT, 'tests', 'e2e.test.ts')), false);
+  });
+});

package/tests/lib/platform-runtime-distribution.test.mjs

@@ -0,0 +1,150 @@
+// Canonical skill protocol checks. Later distribution waves extend this file
+// with installer and platform inventory fixtures.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { PLATFORM_RUNTIME_INVENTORY, ZCODE_COMPATIBILITY_PATH } from '../../scripts/lib/platform-runtime-inventory.mjs';
+
+const ROOT = process.cwd();
+const VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+const PREFIX = `npx --yes --package @xulthekl/team-flow@${VERSION} tf`;
+const CLI = join(ROOT, 'scripts', 'team-flow.mjs');
+const RUNTIME_SKILLS = [
+  'workflow-start',
+  'need-explorer',
+  'spec-writer',
+  'contract-builder',
+  'build-executor',
+  'code-reviewer',
+  'bug-investigator',
+  'release-archivist',
+  'spec-merger',
+];
+
+function skill(name) {
+  return readFileSync(join(ROOT, 'skills', name, 'SKILL.md'), 'utf8');
+}
+
+describe('canonical skill runtime protocol', () => {
+  it('uses the exact package-version prefix for every runtime-dependent skill', () => {
+    for (const name of RUNTIME_SKILLS) {
+      const content = skill(name);
+      assert.match(content, new RegExp(PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
+        `${name} should use the canonical portable prefix`);
+      assert.doesNotMatch(content, /\$\{CLAUDE_PLUGIN_ROOT\}|\$\{PLUGIN_ROOT\}/,
+        `${name} should not require a host plugin-root variable`);
+    }
+  });
+
+  it('uses allowlisted runtime assets for build-executor prompts', () => {
+    const content = skill('build-executor');
+
+    assert.match(content, /runtime asset read skills\/build-executor\/implementer-prompt\.md/);
+    assert.match(content, /runtime asset read skills\/build-executor\/task-reviewer-prompt\.md/);
+  });
+
+  it('does not leave bare tf commands in runtime instructions or reviewer templates', () => {
+    const files = [
+      ...RUNTIME_SKILLS.map(name => join(ROOT, 'skills', name, 'SKILL.md')),
+      join(ROOT, 'skills', 'build-executor', 'implementer-prompt.md'),
+      join(ROOT, 'skills', 'build-executor', 'task-reviewer-prompt.md'),
+      join(ROOT, 'skills', 'code-reviewer', 'code-reviewer-prompt.md'),
+    ];
+
+    for (const file of files) {
+      const content = readFileSync(file, 'utf8');
+      assert.doesNotMatch(content, /`tf\s+(?:handoff|checkpoint|execution|state|runtime|validate|doctor|config|version)\b/,
+        `${file} contains a bare tf command`);
+      assert.doesNotMatch(content, /^\s*tf\s+(?:handoff|checkpoint|execution|state|runtime|validate|doctor|config|version)\b/m,
+        `${file} contains an unprefixed tf command line`);
+    }
+  });
+});
+
+describe('local runtime deployment', () => {
+  it('rewrites the canonical prefix to ZCODE\'s installed runtime tree', () => {
+    const target = mkdtempSync(join(tmpdir(), 'tf-zcode-runtime-'));
+    try {
+      execFileSync(process.execPath, [CLI, 'install-zcode', '--local', ROOT], {
+        cwd: target,
+        stdio: 'pipe',
+      });
+
+      const pluginRoot = join(target, '.zcode', 'team-flow');
+      const content = readFileSync(join(target, '.zcode', 'skills', 'workflow-start', 'SKILL.md'), 'utf8');
+      const localPrefix = `node '${join(realpathSync(pluginRoot), 'scripts', 'team-flow.mjs')}'`;
+
+      assert.match(content, new RegExp(localPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+      assert.doesNotMatch(content, new RegExp(PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    } finally {
+      rmSync(target, { recursive: true, force: true });
+    }
+  });
+
+  it('emits a shell-literal local runtime command when the target path contains a dollar sign', () => {
+    const target = mkdtempSync(join(tmpdir(), 'tf-$runtime-'));
+    try {
+      execFileSync(process.execPath, [CLI, 'install-zcode', '--local', ROOT], {
+        cwd: target,
+        stdio: 'pipe',
+      });
+
+      const content = readFileSync(join(target, '.zcode', 'skills', 'workflow-start', 'SKILL.md'), 'utf8');
+      const command = content.match(/node '[^']+' runtime asset read docs\/state-machine\.md/);
+      assert.ok(command, 'workflow-start should contain a shell-literal local runtime command');
+
+      const output = execFileSync('sh', ['-c', command[0]], { cwd: target, encoding: 'utf8' });
+      assert.match(output, /State Machine/);
+    } finally {
+      rmSync(target, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('platform runtime inventory', () => {
+  it('lists every documented platform and the ZCODE compatibility path', () => {
+    const ids = new Set(PLATFORM_RUNTIME_INVENTORY.map(platform => platform.id));
+
+    assert.deepEqual(ids, new Set([
+      'claude-code', 'cursor', 'codex-cli', 'codex-app', 'copilot-cli', 'gemini-cli',
+      'opencode', 'workbuddy', 'trae', 'cline', 'kiro', 'windsurf', 'qwen',
+      'amazon-q', 'roocode', 'continue', 'pi',
+    ]));
+    assert.equal(ZCODE_COMPATIBILITY_PATH.id, 'zcode');
+  });
+
+  it('gives each documented distribution an explicit, testable runtime mode', () => {
+    const validModes = new Set(['native-root', 'installer-rewrite', 'canonical-fallback']);
+
+    for (const platform of PLATFORM_RUNTIME_INVENTORY) {
+      assert.ok(platform.modes.length > 0, `${platform.id} needs at least one distribution mode`);
+      for (const mode of platform.modes) assert.ok(validModes.has(mode), `${platform.id}: ${mode}`);
+    }
+    assert.deepEqual(ZCODE_COMPATIBILITY_PATH.modes, ['installer-rewrite']);
+    assert.ok(idsWithMode('codex-cli', 'canonical-fallback'));
+    assert.ok(idsWithMode('codex-app', 'canonical-fallback'));
+    assert.ok(idsWithMode('opencode', 'canonical-fallback'));
+  });
+});
+
+describe('runtime version synchronization', () => {
+  it('includes code-reviewer when a release version is dry-run', () => {
+    const output = execFileSync(process.execPath, [CLI, 'version', '0.9.2', '--dry-run'], {
+      cwd: ROOT,
+      encoding: 'utf8',
+    });
+
+    assert.match(output, /skills\/code-reviewer\/SKILL\.md: version string updated/);
+    assert.match(output, /skills\/build-executor\/implementer-prompt\.md: version string updated/);
+    assert.match(output, /skills\/build-executor\/task-reviewer-prompt\.md: version string updated/);
+    assert.match(output, /skills\/code-reviewer\/code-reviewer-prompt\.md: version string updated/);
+  });
+});
+
+function idsWithMode(id, mode) {
+  return PLATFORM_RUNTIME_INVENTORY.find(platform => platform.id === id)?.modes.includes(mode);
+}