@xulthekl/team-flow 0.22.4

package/tests/lib/cmd-handoff.test.mjs

@@ -0,0 +1,137 @@
+// Dispatcher-level tests for tf handoff.
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const CLI = join(process.cwd(), 'scripts/team-flow.mjs');
+let changeDir;
+
+function runSsf(args) {
+  try {
+    const stdout = execFileSync(process.execPath, [CLI, ...args], {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { exitCode: 0, stdout, stderr: '' };
+  } catch (error) {
+    return {
+      exitCode: error.status || 1,
+      stdout: error.stdout?.toString() || '',
+      stderr: error.stderr?.toString() || error.message,
+    };
+  }
+}
+
+beforeEach(() => {
+  changeDir = mkdtempSync(join(tmpdir(), 'tf-handoff-'));
+  writeFileSync(join(changeDir, 'proposal.md'), '# Proposal\n\nA valid proposal.\n');
+  writeFileSync(join(changeDir, 'design.md'), '# Design\n\nA valid design.\n');
+  writeFileSync(join(changeDir, 'tasks.md'), '# Tasks\n\n- [ ] 1.1 Original task text\n');
+  writeFileSync(join(changeDir, '.team-flow.yaml'), 'state: executing\nworkflow: auto\n');
+});
+
+afterEach(() => {
+  rmSync(changeDir, { recursive: true, force: true });
+});
+
+describe('tf handoff', () => {
+  it('creates, finishes, and resolves a prototype contract without mutating planning files', () => {
+    const designBefore = readFileSync(join(changeDir, 'design.md'));
+    const tasksBefore = readFileSync(join(changeDir, 'tasks.md'));
+    const create = runSsf([
+      'handoff', 'create', changeDir, '--type', 'prototype',
+      '--objective', 'Compare two filter interactions',
+      '--expected-output', 'A short recommendation with evidence',
+      '--acceptance', 'Document one recommended interaction',
+      '--boundary', 'Do not alter planning artifacts', '--boundary', 'Use only fixture data',
+    ]);
+    assert.equal(create.exitCode, 0, create.stderr);
+
+    const listed = runSsf(['handoff', 'list', changeDir, '--json']);
+    assert.equal(listed.exitCode, 0, listed.stderr);
+    const handoff = JSON.parse(listed.stdout).handoffs[0];
+    assert.equal(handoff.type, 'prototype');
+    assert.match(handoff.source, /- Do not alter planning artifacts/);
+    assert.match(handoff.source, /- Use only fixture data/);
+
+    writeFileSync(join(handoff.directory, 'HANDOFF_RESULT.md'), validResult());
+    assert.equal(runSsf(['handoff', 'finish', changeDir, handoff.id]).exitCode, 0);
+    assert.equal(runSsf(['handoff', 'resolve', changeDir, handoff.id, '--decision', 'accept']).exitCode, 0);
+    assert.deepEqual(readFileSync(join(changeDir, 'design.md')), designBefore);
+    assert.deepEqual(readFileSync(join(changeDir, 'tasks.md')), tasksBefore);
+  });
+
+  it('rejects an unknown handoff type', () => {
+    const result = runSsf([
+      'handoff', 'create', changeDir, '--type', 'unknown', '--objective', 'Objective',
+      '--expected-output', 'Expected output', '--acceptance', 'Acceptance',
+    ]);
+    assert.equal(result.exitCode, 1);
+    assert.match(result.stderr, /Unsupported handoff type 'unknown'/);
+  });
+
+  it('rejects a result without evidence and leaves the handoff active', () => {
+    const handoff = createHandoff();
+    writeFileSync(join(handoff.directory, 'HANDOFF_RESULT.md'), validResult().replace('Prototype screenshots and task notes.', ''));
+
+    const result = runSsf(['handoff', 'finish', changeDir, handoff.id]);
+    assert.equal(result.exitCode, 1);
+    assert.match(result.stderr, /Evidence must contain non-empty content/);
+    assert.equal(getHandoff(handoff.id).status, 'active');
+  });
+
+  it('rejects an active handoff resolution', () => {
+    const handoff = createHandoff();
+    const result = runSsf(['handoff', 'resolve', changeDir, handoff.id, '--decision', 'accept']);
+    assert.equal(result.exitCode, 1);
+    assert.match(result.stderr, /is not result-ready/);
+  });
+
+  it('rejects an unknown resolution decision', () => {
+    const handoff = createHandoff();
+    const result = runSsf(['handoff', 'resolve', changeDir, handoff.id, '--decision', 'ignore']);
+    assert.equal(result.exitCode, 1);
+    assert.match(result.stderr, /Unsupported handoff decision 'ignore'/);
+  });
+
+  it('requires acknowledgement when source artifacts drift', () => {
+    const handoff = createHandoff();
+    writeFileSync(join(handoff.directory, 'HANDOFF_RESULT.md'), validResult());
+    assert.equal(runSsf(['handoff', 'finish', changeDir, handoff.id]).exitCode, 0);
+    writeFileSync(join(changeDir, 'proposal.md'), '# Proposal\n\nChanged after handoff creation.\n');
+
+    const unresolved = runSsf(['handoff', 'resolve', changeDir, handoff.id, '--decision', 'accept']);
+    assert.equal(unresolved.exitCode, 1);
+    assert.match(unresolved.stderr, /acknowledge-source-drift/);
+    assert.equal(runSsf([
+      'handoff', 'resolve', changeDir, handoff.id, '--decision', 'accept', '--acknowledge-source-drift',
+    ]).exitCode, 0);
+  });
+});
+
+function createHandoff() {
+  const result = runSsf([
+    'handoff', 'create', changeDir, '--type', 'research', '--objective', 'Inspect behavior',
+    '--expected-output', 'Document findings', '--acceptance', 'List evidence',
+  ]);
+  assert.equal(result.exitCode, 0, result.stderr);
+  return JSON.parse(runSsf(['handoff', 'list', changeDir, '--json']).stdout).handoffs[0];
+}
+
+function getHandoff(id) {
+  return JSON.parse(runSsf(['handoff', 'list', changeDir, '--json']).stdout)
+    .handoffs.find(handoff => handoff.id === id);
+}
+
+function validResult() {
+  return [
+    '## Conclusion\n\nKeep the compact filter interaction.',
+    '## Evidence\n\nPrototype screenshots and task notes.',
+    '## Produced Artifacts\n\nprototype/filter.md',
+    '## Risks\n\nKeyboard flow needs a follow-up.',
+    '## Suggested Changes\n\n- Add keyboard behavior to tasks.md.',
+    '',
+  ].join('\n');
+}

package/tests/lib/cmd-inject.test.mjs

@@ -0,0 +1,218 @@
+// tests/lib/cmd-inject.test.mjs
+// Tests for scripts/lib/cmd-inject.mjs
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let generatePhaseGuard, toCursorMdc, toCopilotInstructions;
+
+describe('cmd-inject: generatePhaseGuard()', () => {
+  before(async () => {
+    const modulePath = join(process.cwd(), 'scripts/lib/cmd-inject.mjs');
+    const mod = await import(modulePath);
+    generatePhaseGuard = mod.generatePhaseGuard;
+    toCursorMdc = mod.toCursorMdc;
+    toCopilotInstructions = mod.toCopilotInstructions;
+  });
+
+  it('replaces {{change_name}} placeholder', () => {
+    const result = generatePhaseGuard({ state: 'exploring', change_name: 'add-csv-export' });
+    assert.ok(result.includes('add-csv-export'), `Expected "add-csv-export" in output, got: ${result.substring(0, 100)}`);
+  });
+
+  it('replaces {{state}} placeholder', () => {
+    const result = generatePhaseGuard({ state: 'executing', change_name: 'test' });
+    assert.ok(result.includes('executing'));
+  });
+
+  it('replaces {{workflow}} placeholder', () => {
+    const result = generatePhaseGuard({ state: 'exploring', workflow: 'hotfix', change_name: 'test' });
+    assert.ok(result.includes('hotfix'));
+  });
+
+  it('generates exploring phase with allowed operations', () => {
+    const result = generatePhaseGuard({ state: 'exploring', change_name: 'test' });
+    assert.ok(result.includes('澄清需求'));
+    assert.ok(result.includes('禁止操作'));
+  });
+
+  it('generates specifying phase with allowed operations', () => {
+    const result = generatePhaseGuard({ state: 'specifying', change_name: 'test' });
+    assert.ok(result.includes('specs/'));
+    assert.ok(result.includes('design.md'));
+  });
+
+  it('generates bridging phase with contract operations', () => {
+    const result = generatePhaseGuard({ state: 'bridging', change_name: 'test' });
+    assert.ok(result.includes('execution-contract.md'));
+    assert.ok(result.includes('tf validate'));
+  });
+
+  it('generates approved-for-build phase', () => {
+    const result = generatePhaseGuard({ state: 'approved-for-build', change_name: 'test' });
+    assert.ok(result.includes('执行模式'));
+    assert.ok(result.includes('DP-4'));
+    assert.match(result, /execution plan/);
+    assert.match(result, /不得开始实现/);
+  });
+
+  it('generates executing phase with test prohibition', () => {
+    const result = generatePhaseGuard({ state: 'executing', change_name: 'test' });
+    assert.ok(result.includes('跳过测试'));
+    assert.match(result, /wave review/);
+    assert.match(result, /review receipt/);
+  });
+
+  it('generates debugging phase with root cause analysis', () => {
+    const result = generatePhaseGuard({ state: 'debugging', change_name: 'test' });
+    assert.ok(result.includes('根因分析'));
+    assert.ok(result.includes('TDD 修复循环'));
+  });
+
+  it('generates closing phase with verification', () => {
+    const result = generatePhaseGuard({ state: 'closing', change_name: 'test' });
+    assert.ok(result.includes('三维验证'));
+    assert.ok(result.includes('DP-7'));
+  });
+
+  it('generates abandoned terminal state', () => {
+    const result = generatePhaseGuard({ state: 'abandoned', change_name: 'test' });
+    assert.ok(result.includes('终止状态'));
+    assert.ok(result.includes('不得合并'));
+  });
+
+  it('falls back to exploring for unknown state', () => {
+    const result = generatePhaseGuard({ state: 'unknown-state', change_name: 'test' });
+    assert.ok(result.includes('澄清需求'), `Expected exploring fallback, got: ${result.substring(0, 200)}`);
+  });
+
+  it('uses defaults when optional fields missing', () => {
+    const result = generatePhaseGuard({ state: 'exploring' });
+    // change_name defaults to 'unknown'
+    assert.ok(result.includes('unknown'));
+    // workflow defaults to 'full'
+    assert.ok(result.includes('full'));
+  });
+});
+
+describe('cmd-inject: toCursorMdc()', () => {
+  it('wraps base content with Cursor MDC frontmatter', () => {
+    const base = '# Phase Guard: test-change\n\n## Allowed\n- Do stuff';
+    const result = toCursorMdc(base);
+
+    assert.ok(result.includes('---'), 'Should have frontmatter delimiter');
+    assert.ok(result.includes('description: team-flow phase guard'));
+    assert.ok(result.includes('alwaysApply: true'));
+    assert.ok(result.includes('test-change'));
+  });
+});
+
+describe('cmd-inject: toCopilotInstructions()', () => {
+  it('simplifies heading for Copilot format', () => {
+    const base = '# Phase Guard: test-change\n\n## Allowed\n- Do stuff';
+    const result = toCopilotInstructions(base);
+
+    assert.ok(result.includes('# Phase Guard'));
+    assert.ok(result.includes('## Allowed'));
+    // Should NOT contain the change name in heading
+    assert.ok(!result.includes('# Phase Guard: test-change'));
+  });
+});
+
+describe('cmd-inject: platform resolution', () => {
+  let resolvePlatforms, detectProjectPlatforms;
+
+  before(async () => {
+    const modulePath = join(process.cwd(), 'scripts/lib/cmd-inject.mjs');
+    const mod = await import(modulePath);
+    resolvePlatforms = mod.resolvePlatforms;
+    detectProjectPlatforms = mod.detectProjectPlatforms;
+  });
+
+  it('resolves explicit all to all supported platforms', () => {
+    const result = resolvePlatforms('all', process.cwd());
+    assert.deepEqual(result, { ok: true, platforms: ['claude', 'cursor', 'copilot', 'gemini'] });
+  });
+
+  it('detects Cursor from .cursor marker', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'tf-inject-cursor-'));
+    try {
+      mkdirSync(join(dir, '.cursor'), { recursive: true });
+      assert.deepEqual(detectProjectPlatforms(dir), ['cursor']);
+      assert.deepEqual(resolvePlatforms(undefined, dir), { ok: true, platforms: ['cursor'] });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects omitted platforms when no marker exists', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'tf-inject-none-'));
+    try {
+      const result = resolvePlatforms(undefined, dir);
+      assert.equal(result.ok, false);
+      assert.match(result.message, /--platforms/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects omitted platforms when multiple markers exist', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'tf-inject-multi-'));
+    try {
+      mkdirSync(join(dir, '.cursor'), { recursive: true });
+      mkdirSync(join(dir, '.claude'), { recursive: true });
+      const result = resolvePlatforms(undefined, dir);
+      assert.equal(result.ok, false);
+      assert.match(result.message, /multiple/i);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('cmd-inject: CLI writes', () => {
+  const CLI = join(process.cwd(), 'scripts/team-flow.mjs');
+
+  function runInject(cwd, changeDir, extraArgs = []) {
+    try {
+      const stdout = execFileSync(process.execPath, [CLI, 'inject', changeDir, ...extraArgs], { cwd, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+      return { exitCode: 0, stdout, stderr: '' };
+    } catch (err) {
+      return { exitCode: err.status || 1, stdout: err.stdout?.toString() || '', stderr: err.stderr?.toString() || err.message };
+    }
+  }
+
+  it('cursor-only injection does not write GEMINI.md', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tf-inject-cli-cursor-'));
+    try {
+      const change = join(root, 'change');
+      mkdirSync(change, { recursive: true });
+      writeFileSync(join(change, '.team-flow.yaml'), 'state: exploring\nworkflow: full\nchange_name: inject-test\n');
+      const result = runInject(root, change, ['--platforms', 'cursor']);
+      assert.equal(result.exitCode, 0, result.stdout + result.stderr);
+      assert.equal(existsSync(join(root, '.cursor', 'rules', 'phase-guard.mdc')), true);
+      assert.equal(existsSync(join(root, 'GEMINI.md')), false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('omitted ambiguous platform exits before writing files', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tf-inject-cli-none-'));
+    try {
+      const change = join(root, 'change');
+      mkdirSync(change, { recursive: true });
+      writeFileSync(join(change, '.team-flow.yaml'), 'state: exploring\nworkflow: full\nchange_name: inject-test\n');
+      const result = runInject(root, change);
+      assert.equal(result.exitCode, 2);
+      assert.match(result.stderr || result.stdout, /--platforms/);
+      assert.equal(existsSync(join(root, '.cursor')), false);
+      assert.equal(existsSync(join(root, 'GEMINI.md')), false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/tests/lib/cmd-install-workbuddy.test.mjs

@@ -0,0 +1,113 @@
+// tests/lib/cmd-install-workbuddy.test.mjs
+// Tests for scripts/lib/cmd-install-workbuddy.mjs
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tempDir;
+let planInstall, installWorkBuddy;
+
+describe('cmd-install-workbuddy', () => {
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'tf-workbuddy-'));
+    const mod = await import(join(process.cwd(), 'scripts/lib/cmd-install-workbuddy.mjs'));
+    planInstall = mod.planInstall;
+    installWorkBuddy = mod.installWorkBuddy;
+  });
+
+  afterEach(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function makePluginRoot() {
+    const pluginRoot = join(tempDir, 'team-flow');
+    const skillsDir = join(pluginRoot, 'skills');
+    mkdirSync(join(skillsDir, 'workflow-start'), { recursive: true });
+    mkdirSync(join(skillsDir, 'need-explorer'), { recursive: true });
+    writeFileSync(join(skillsDir, 'workflow-start', 'SKILL.md'), '---\nname: workflow-start\n---\n');
+    writeFileSync(join(skillsDir, 'need-explorer', 'SKILL.md'), '---\nname: need-explorer\n---\n');
+    writeFileSync(join(pluginRoot, 'package.json'), JSON.stringify({ version: '0.8.14' }));
+    return pluginRoot;
+  }
+
+  it('plans WorkBuddy marketplace paths and single enabled plugin key', () => {
+    const pluginRoot = makePluginRoot();
+    const plan = planInstall({
+      pluginRoot,
+      homeDir: join(tempDir, 'home'),
+      marketplaceName: 'cb_teams_marketplace',
+    });
+
+    assert.deepEqual(plan.skillNames, ['need-explorer', 'workflow-start']);
+    assert.equal(
+      plan.pluginsDir,
+      join(tempDir, 'home', '.workbuddy', 'plugins', 'marketplaces', 'cb_teams_marketplace', 'plugins'),
+    );
+    // Single plugin key, not per-skill.
+    assert.equal(plan.enabledPluginKey, 'team-flow@cb_teams_marketplace');
+    // Plugin dir targets team-flow, not per-skill.
+    assert.equal(plan.targetPluginDir, join(plan.pluginsDir, 'team-flow'));
+    assert.equal(plan.targetSkills, join(plan.targetPluginDir, 'skills'));
+    assert.equal(plan.targetRules, join(plan.targetPluginDir, 'rules'));
+  });
+
+  it('deploys skills, runtime dirs, rules, manifest, and preserves existing settings', async () => {
+    const pluginRoot = makePluginRoot();
+    const homeDir = join(tempDir, 'home');
+    const settingsDir = join(homeDir, '.workbuddy');
+    mkdirSync(settingsDir, { recursive: true });
+    writeFileSync(
+      join(settingsDir, 'settings.json'),
+      JSON.stringify({ enabledPlugins: { 'existing@codebuddy-plugins-official': true } }, null, 2),
+    );
+
+    // Create a scripts dir so RUNTIME_DIRS copy has something to copy.
+    mkdirSync(join(pluginRoot, 'scripts'), { recursive: true });
+    writeFileSync(join(pluginRoot, 'scripts', 'check-update.mjs'), '// test');
+
+    const result = await installWorkBuddy({ pluginRoot, homeDir, marketplaceName: 'cb_teams_marketplace' });
+    assert.equal(result.skillNames.length, 2);
+
+    // Settings: existing key preserved, single team-flow key added.
+    const settings = JSON.parse(readFileSync(join(settingsDir, 'settings.json'), 'utf-8'));
+    assert.equal(settings.enabledPlugins['existing@codebuddy-plugins-official'], true);
+    assert.equal(settings.enabledPlugins['team-flow@cb_teams_marketplace'], true);
+    // Old per-skill keys should NOT exist.
+    assert.equal(settings.enabledPlugins['workflow-start@cb_teams_marketplace'], undefined);
+    assert.equal(settings.enabledPlugins['need-explorer@cb_teams_marketplace'], undefined);
+
+    // Skills deployed under <plugin>/skills/<name>/SKILL.md
+    const pluginDir = join(homeDir, '.workbuddy', 'plugins', 'marketplaces', 'cb_teams_marketplace', 'plugins', 'team-flow');
+    assert.match(
+      readFileSync(join(pluginDir, 'skills', 'workflow-start', 'SKILL.md'), 'utf-8'),
+      /workflow-start/,
+    );
+
+    // Runtime dirs copied.
+    assert.ok(existsSync(join(pluginDir, 'scripts', 'check-update.mjs')));
+
+    // Phase-guard rule deployed.
+    assert.ok(existsSync(join(pluginDir, 'rules', 'phase-guard.md')));
+
+    // Plugin manifest deployed.
+    const manifest = JSON.parse(readFileSync(join(pluginDir, '.codebuddy-plugin', 'plugin.json'), 'utf-8'));
+    assert.equal(manifest.name, 'team-flow');
+    assert.equal(manifest.skills.length, 2);
+  });
+
+  it('uses the package root by default instead of the caller cwd', () => {
+    const previousCwd = process.cwd();
+    process.chdir(tempDir);
+    try {
+      const plan = planInstall({ homeDir: join(tempDir, 'home') });
+      assert.equal(plan.skillNames.length, 23);
+      assert.equal(plan.skillsDir, join(plan.pluginRoot, 'skills'));
+      assert.ok(existsSync(plan.skillsDir));
+      assert.notEqual(plan.skillsDir, join(tempDir, 'skills'));
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+});

package/tests/lib/cmd-install-zcode.test.mjs

@@ -0,0 +1,42 @@
+// tests/lib/cmd-install-zcode.test.mjs
+// Regression for #29: `tf install-zcode` deploys skills to .zcode/ with the
+// CLAUDE_PLUGIN_ROOT placeholder rewritten to an absolute path.
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+const CLI = join(ROOT, 'scripts', 'team-flow.mjs');
+
+describe('BUG/#29: install-zcode deploys skills', () => {
+  let cwd;
+  before(() => { cwd = mkdtempSync(join(tmpdir(), 'tf-zcode-install-')); });
+  after(() => { if (existsSync(cwd)) rmSync(cwd, { recursive: true, force: true }); });
+
+  it('SHALL deploy skills to .zcode/skills/ with CLAUDE_PLUGIN_ROOT rewritten', () => {
+    execSync(`node ${CLI} install-zcode --local "${ROOT}"`, { cwd, stdio: 'pipe', timeout: 60000 });
+    const skillsDir = join(cwd, '.zcode', 'skills');
+    assert.equal(existsSync(skillsDir), true, '.zcode/skills should exist');
+    const wfStart = join(skillsDir, 'workflow-start', 'SKILL.md');
+    assert.equal(existsSync(wfStart), true, 'workflow-start skill should be deployed');
+    const content = readFileSync(wfStart, 'utf-8');
+    assert.equal(content.includes('${CLAUDE_PLUGIN_ROOT}'), false, 'CLAUDE_PLUGIN_ROOT should be rewritten to an absolute path');
+    assert.equal(existsSync(join(cwd, '.zcode', 'rules', 'phase-guard.mdc')), true, 'phase guard should be written');
+  });
+
+  it('SHALL give contract-builder the portable execution-contract asset command', () => {
+    execSync(`node ${CLI} install-zcode --local "${ROOT}"`, { cwd, stdio: 'pipe', timeout: 60000 });
+
+    const templatePath = join(cwd, '.zcode', 'team-flow', 'templates', 'execution-contract.md');
+    const contractBuilder = readFileSync(join(cwd, '.zcode', 'skills', 'contract-builder', 'SKILL.md'), 'utf-8');
+
+    assert.equal(existsSync(templatePath), true, 'deployed template should exist');
+    assert.match(contractBuilder, /runtime asset read templates\/execution-contract\.md/);
+  });
+});

package/tests/lib/cmd-isolate.test.mjs

@@ -0,0 +1,68 @@
+// Regression tests for #52: optional isolate names must not become the
+// literal string "undefined" when cmd-isolate invokes ensure-branch.
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const ROOT = process.cwd();
+const CLI = join(ROOT, 'scripts', 'team-flow.mjs');
+const ENSURE = join(ROOT, 'scripts', 'ensure-branch.mjs');
+const tempDirs = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+function runIsolate(args) {
+  const tempDir = mkdtempSync(join(tmpdir(), 'tf-cmd-isolate-'));
+  tempDirs.push(tempDir);
+  const binDir = join(tempDir, 'bin');
+  const capture = join(tempDir, 'argv.txt');
+  const fakeNode = join(binDir, 'node');
+
+  mkdirSync(binDir);
+  writeFileSync(fakeNode, '#!/bin/sh\nprintf "%s\\n" "$@" > "$SSF_CAPTURE"\n', 'utf8');
+  chmodSync(fakeNode, 0o755);
+
+  const result = spawnSync(process.execPath, [CLI, 'isolate', ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      PATH: `${binDir}:${process.env.PATH}`,
+      SSF_CAPTURE: capture,
+    },
+  });
+
+  return {
+    result,
+    argv: readFileSync(capture, 'utf8').trimEnd().split('\n'),
+  };
+}
+
+describe('cmd-isolate optional change name (#52)', () => {
+  it('omits the optional name from ensure-branch argv when the caller omits it', () => {
+    const { result, argv } = runIsolate(['/tmp/changes/demo']);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(argv, [ENSURE, '/tmp/changes/demo']);
+  });
+
+  it('forwards an explicitly supplied name unchanged', () => {
+    const { result, argv } = runIsolate(['/tmp/changes/demo', 'runtime-fix']);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(argv, [ENSURE, '/tmp/changes/demo', 'runtime-fix']);
+  });
+
+  it('forwards force without manufacturing an optional name', () => {
+    const { result, argv } = runIsolate(['/tmp/changes/demo', '--force']);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(argv, [ENSURE, '/tmp/changes/demo', '--force']);
+  });
+});