ma-agents 3.0.1 → 3.2.0

package/test/cross-repo-validation.test.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Tests for Story 16.4: Validate Cross-Repo Path Resolution
+ * Verifies config-driven path resolution and backward compatibility
+ */
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  \u2717 ${name}: ${err.message}`);
+    failed++;
+    errors.push({ name, error: err.message });
+  }
+}
+
+let writeRepoLayoutConfig, writeConfigField;
+try {
+  ({ writeRepoLayoutConfig, writeConfigField } = require('../bin/cli.js'));
+} catch (e) {
+  console.error('\n  FATAL: Cannot load exports from cli.js');
+  console.error(' ', e.message);
+  process.exit(1);
+}
+
+// ─── Task 1: Audit verification ─────────────────────────────────────────────
+console.log('\nTask 1 — Workflow audit: no hardcoded _bmad-output/ paths');
+
+test('no workflow files contain hardcoded _bmad-output/', () => {
+  const bmadDir = path.join(__dirname, '..', '_bmad', 'bmm');
+  if (!fs.existsSync(bmadDir)) {
+    console.log('    SKIP: _bmad/bmm not found (BMAD not installed)');
+    return;
+  }
+
+  function scanDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...scanDir(full));
+      } else if ((entry.name.endsWith('.md') || entry.name.endsWith('.yaml')) && entry.name !== 'config.yaml') {
+        // Exclude config.yaml — it stores resolved path values, not hardcoded references
+        const content = fs.readFileSync(full, 'utf-8');
+        // Look for literal _bmad-output/ that isn't in a comment or template variable context
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          if (line.includes('_bmad-output/') && !line.includes('{') && !line.includes('#')) {
+            results.push({ file: full, line: i + 1, content: line.trim() });
+          }
+        }
+      }
+    }
+    return results;
+  }
+
+  const hardcoded = scanDir(bmadDir);
+  assert.strictEqual(hardcoded.length, 0,
+    `Found ${hardcoded.length} hardcoded _bmad-output/ references:\n` +
+    hardcoded.map(h => `  ${h.file}:${h.line}: ${h.content}`).join('\n'));
+});
+
+// ─── Task 2: Config-driven path resolution ──────────────────────────────────
+console.log('\nTask 2 — Config writes planning_artifacts and implementation_artifacts');
+
+test('single-repo: writes default artifact paths', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+  const origCwd = process.cwd();
+  try {
+    process.chdir(tmpDir);
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '# config\n{}');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'same', path: '.' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    assert.ok(content.includes('planning_artifacts: "_bmad-output/planning-artifacts"'),
+      `Expected default planning_artifacts. Got:\n${content}`);
+    assert.ok(content.includes('implementation_artifacts: "_bmad-output/implementation-artifacts"'),
+      `Expected default implementation_artifacts. Got:\n${content}`);
+  } finally {
+    process.chdir(origCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('multi-repo: writes external artifact paths', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+  const origCwd = process.cwd();
+  try {
+    process.chdir(tmpDir);
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '# config\n{}');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'local', path: 'd:\\Code\\kb-repo' },
+      sprintManagement: { mode: 'local', path: 'd:\\Code\\sprint-repo' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    assert.ok(content.includes('planning_artifacts: "d:/Code/kb-repo/_bmad-output/planning-artifacts"'),
+      `Expected external planning_artifacts. Got:\n${content}`);
+    assert.ok(content.includes('implementation_artifacts: "d:/Code/sprint-repo/_bmad-output/implementation-artifacts"'),
+      `Expected external implementation_artifacts. Got:\n${content}`);
+  } finally {
+    process.chdir(origCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('mixed mode: kb external, sprint same', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+  const origCwd = process.cwd();
+  try {
+    process.chdir(tmpDir);
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '# config\n{}');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'local', path: '/ext/kb' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    assert.ok(content.includes('planning_artifacts: "/ext/kb/_bmad-output/planning-artifacts"'),
+      `Got:\n${content}`);
+    assert.ok(content.includes('implementation_artifacts: "_bmad-output/implementation-artifacts"'),
+      `Got:\n${content}`);
+  } finally {
+    process.chdir(origCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ─── Task 3: Single-repo backward compatibility ─────────────────────────────
+console.log('\nTask 3 — Single-repo backward compatibility');
+
+test('single-repo config matches pre-Epic-16 defaults', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+  const origCwd = process.cwd();
+  try {
+    process.chdir(tmpDir);
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '{}');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'same', path: '.' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    // These are the default relative paths that workflows used before Epic 16
+    assert.ok(content.includes('planning_artifacts: "_bmad-output/planning-artifacts"'));
+    assert.ok(content.includes('implementation_artifacts: "_bmad-output/implementation-artifacts"'));
+    assert.ok(content.includes('knowledgebase_path: "."'));
+    assert.ok(content.includes('sprint_management_path: "."'));
+  } finally {
+    process.chdir(origCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ─── Task 4: Source-of-truth precedence ─────────────────────────────────────
+console.log('\nTask 4 — Source-of-truth precedence documented');
+
+test('validation report exists', () => {
+  const reportPath = path.join(__dirname, '..', '_bmad-output', 'implementation-artifacts', '16-4-validation-report.md');
+  assert.ok(fs.existsSync(reportPath), 'Validation report should exist');
+  const content = fs.readFileSync(reportPath, 'utf-8');
+  assert.ok(content.includes('Source-of-Truth Precedence'), 'Should document precedence');
+  assert.ok(content.includes('PRIMARY'), 'Should identify primary source');
+  assert.ok(content.includes('config.yaml'), 'Should mention config.yaml as primary');
+});
+
+test('path accessibility: fs.accessSync pattern available', () => {
+  // Verify fs.accessSync works for testing path accessibility
+  assert.ok(typeof fs.accessSync === 'function', 'fs.accessSync should be available');
+  // Test with known accessible path
+  assert.doesNotThrow(() => fs.accessSync(__dirname, fs.constants.R_OK));
+});
+
+// ─── Summary ────────────────────────────────────────────────────────────────
+console.log(`\n${passed} passed, ${failed} failed`);
+if (errors.length > 0) {
+  console.log('\nFailed tests:');
+  errors.forEach(e => console.log(`  - ${e.name}: ${e.error}`));
+}
+if (failed > 0) process.exit(1);

package/test/generate-project-context.test.js

@@ -47,9 +47,9 @@ async function test(name, fn) {
 // Template path derived directly — not imported from module (avoids leaking internals)
 const _TEMPLATE_PATH = path.join(__dirname, '..', 'lib', 'templates', 'project-context.template.md');
 
-let generateProjectContext, updateProjectContextManifestPaths;
+let generateProjectContext, updateProjectContextManifestPaths, generateRepoLayoutSection, updateProjectContextRepoLayout;
 try {
-  ({ generateProjectContext, _updateProjectContextManifestPaths: updateProjectContextManifestPaths } = require('../lib/installer'));
+  ({ generateProjectContext, _updateProjectContextManifestPaths: updateProjectContextManifestPaths, generateRepoLayoutSection, updateProjectContextRepoLayout } = require('../lib/installer'));
 } catch (e) {
   console.error('\n  FATAL: Cannot load installer module');
   console.error(' ', e.message);
@@ -326,6 +326,152 @@ async function runAll() {
     fs.rmSync(tmpDir, { recursive: true });
   });
 
+  // ─── Story 16.3: generateRepoLayoutSection tests ─────────────────────────
+
+  // 5.1 null layout → empty string
+  await test('5.1 generateRepoLayoutSection: null layout returns empty string', async () => {
+    assert.strictEqual(generateRepoLayoutSection(null), '');
+  });
+
+  // 5.2 single-repo (both same) → empty string
+  await test('5.2 generateRepoLayoutSection: both same mode returns empty string', async () => {
+    const result = generateRepoLayoutSection({
+      knowledgebase: { mode: 'same', path: '.' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    assert.strictEqual(result, '');
+  });
+
+  // 5.3 multi-repo returns section with markers
+  await test('5.3 generateRepoLayoutSection: multi-repo returns section with markers', async () => {
+    const result = generateRepoLayoutSection({
+      knowledgebase: { mode: 'local', path: '/path/to/kb' },
+      sprintManagement: { mode: 'local', path: '/path/to/sprint' }
+    });
+    assert.ok(result.includes('<!-- ma-agents:repo-layout-start -->'), 'should have start marker');
+    assert.ok(result.includes('<!-- ma-agents:repo-layout-end -->'), 'should have end marker');
+    assert.ok(result.includes('### Repository Layout'), 'should have section header');
+    assert.ok(result.includes('/path/to/kb'), 'should include kb path');
+    assert.ok(result.includes('/path/to/sprint'), 'should include sprint path');
+  });
+
+  // 5.4 mixed config: one external + one same
+  await test('5.4 generateRepoLayoutSection: mixed config shows "current repository" for same', async () => {
+    const result = generateRepoLayoutSection({
+      knowledgebase: { mode: 'local', path: '/ext/kb' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    assert.ok(result.includes('/ext/kb'), 'should include external kb path');
+    assert.ok(result.includes('current repository (default)'), 'should show default for same mode');
+    assert.ok(result.includes('planning artifacts'), 'should have kb usage instruction');
+    assert.ok(!result.includes('sprint/story artifacts'), 'should NOT have sprint instruction when sprint is same');
+  });
+
+  // 5.5 path normalization
+  await test('5.5 generateRepoLayoutSection: normalizes backslashes', async () => {
+    const result = generateRepoLayoutSection({
+      knowledgebase: { mode: 'local', path: 'C:\\Users\\dev\\kb' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    assert.ok(result.includes('C:/Users/dev/kb'), 'should normalize backslashes');
+    assert.ok(!result.includes('\\'), 'should not contain backslashes');
+  });
+
+  // 5.6 backward compat: generateProjectContext without layout still works
+  await test('5.6 generateProjectContext: no layout param → no crash, no placeholder in output', async () => {
+    const content = await generateProjectContext('/some/root', [agent('.claude/skills')]);
+    assert.ok(!content.includes('{{REPO_LAYOUT_SECTION}}'), 'placeholder should be removed');
+    assert.ok(!content.includes('repo-layout-start'), 'should not have layout markers without layout');
+  });
+
+  // 5.7 generateProjectContext with multi-repo layout inserts section
+  await test('5.7 generateProjectContext: multi-repo layout inserts Repository Layout section', async () => {
+    const layout = {
+      knowledgebase: { mode: 'local', path: '/ext/kb' },
+      sprintManagement: { mode: 'same', path: '.' }
+    };
+    const content = await generateProjectContext('/some/root', [agent('.claude/skills')], layout);
+    assert.ok(content.includes('### Repository Layout'), 'should include Repository Layout section');
+    assert.ok(content.includes('/ext/kb'), 'should include kb path');
+    assert.ok(content.includes('<!-- ma-agents:repo-layout-start -->'), 'should have start marker');
+  });
+
+  // 5.8 no double blank lines when section is empty
+  await test('5.8 generateProjectContext: single-repo layout → no double blank lines', async () => {
+    const layout = {
+      knowledgebase: { mode: 'same', path: '.' },
+      sprintManagement: { mode: 'same', path: '.' }
+    };
+    const content = await generateProjectContext('/some/root', [agent('.claude/skills')], layout);
+    assert.ok(!content.includes('\n\n\n'), 'should not have triple newlines (double blank lines)');
+    assert.ok(!content.includes('repo-layout'), 'should not have any layout markers');
+  });
+
+  // ─── updateProjectContextRepoLayout tests ──────────────────────────────────
+
+  // 5.9 markers present → update content
+  await test('5.9 updateProjectContextRepoLayout: existing markers → updates content', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+    const outputPath = path.join(tmpDir, 'project-context.md');
+    const initial = [
+      '# Project Context',
+      '<!-- ma-agents:repo-layout-start -->',
+      '### Repository Layout',
+      '- old content',
+      '<!-- ma-agents:repo-layout-end -->',
+      '## Technology Stack'
+    ].join('\n');
+    fs.writeFileSync(outputPath, initial, 'utf8');
+
+    const result = await updateProjectContextRepoLayout(outputPath, {
+      knowledgebase: { mode: 'local', path: '/new/kb' },
+      sprintManagement: { mode: 'local', path: '/new/sprint' }
+    });
+    assert.strictEqual(result, true, 'should return true');
+    const content = fs.readFileSync(outputPath, 'utf8');
+    assert.ok(content.includes('/new/kb'), 'should have new kb path');
+    assert.ok(!content.includes('old content'), 'old content should be replaced');
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  // 5.10 no markers + multi-repo → inserts before Technology Stack
+  await test('5.10 updateProjectContextRepoLayout: no markers → inserts before Technology Stack', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+    const outputPath = path.join(tmpDir, 'project-context.md');
+    const initial = '# Project Context\nSome content\n\n## Technology Stack\nmore content';
+    fs.writeFileSync(outputPath, initial, 'utf8');
+
+    const result = await updateProjectContextRepoLayout(outputPath, {
+      knowledgebase: { mode: 'local', path: '/ext/kb' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    assert.strictEqual(result, true, 'should return true');
+    const content = fs.readFileSync(outputPath, 'utf8');
+    assert.ok(content.includes('### Repository Layout'), 'should insert section');
+    assert.ok(content.indexOf('Repository Layout') < content.indexOf('## Technology Stack'), 'section before Tech Stack');
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  // 5.11 single-repo + no markers → returns false (nothing to do)
+  await test('5.11 updateProjectContextRepoLayout: single-repo + no markers → returns false', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+    const outputPath = path.join(tmpDir, 'project-context.md');
+    fs.writeFileSync(outputPath, '# Project Context\n## Technology Stack\n', 'utf8');
+
+    const result = await updateProjectContextRepoLayout(outputPath, {
+      knowledgebase: { mode: 'same', path: '.' },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    assert.strictEqual(result, false, 'should return false for single-repo with no markers');
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  // 5.12 missing layout fields → no crash
+  await test('5.12 generateRepoLayoutSection: missing layout fields returns empty string', async () => {
+    assert.strictEqual(generateRepoLayoutSection({}), '');
+    assert.strictEqual(generateRepoLayoutSection({ knowledgebase: null }), '');
+  });
+
   // ─── Report ────────────────────────────────────────────────────────────────
   console.log(`\n  ${passed} passed, ${failed} failed\n`);
   if (failed > 0) {

package/test/portable-paths.test.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/**
+ * Tests for Story 16.7: Portable Path Storage
+ * Tests toPortablePath(), resolveStoredPath(), and round-trip write/read with relative paths
+ */
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  \u2717 ${name}: ${err.message}`);
+    failed++;
+    errors.push({ name, error: err.message });
+  }
+}
+
+// ─── Load module ─────────────────────────────────────────────────────────────
+let toPortablePath, resolveStoredPath, normalizePath, writeProjectLayoutYaml, writeRepoLayoutConfig, readExistingLayout;
+try {
+  ({ toPortablePath, resolveStoredPath, normalizePath, writeProjectLayoutYaml, writeRepoLayoutConfig, readExistingLayout } = require('../bin/cli.js'));
+} catch (e) {
+  console.error('\n  FATAL: Cannot load exports from cli.js');
+  console.error(' ', e.message);
+  process.exit(1);
+}
+
+// Helper
+function withTmpDir() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ma-test-'));
+  const origCwd = process.cwd();
+  process.chdir(tmpDir);
+  return { tmpDir, cleanup() { process.chdir(origCwd); fs.rmSync(tmpDir, { recursive: true, force: true }); } };
+}
+
+// ─── toPortablePath ────────────────────────────────────────────────────────
+console.log('\ntoPortablePath');
+
+test('sibling path stored as relative: d:/Code/kb from d:/Code/agents becomes ../kb', () => {
+  const result = toPortablePath('d:/Code/kb', 'd:/Code/agents');
+  assert.strictEqual(result.portable, '../kb');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('nested relative works: ../../other/kb', () => {
+  const result = toPortablePath('/home/user/other/kb', '/home/user/projects/myapp');
+  assert.strictEqual(result.portable, '../../other/kb');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('dot path stays as dot', () => {
+  const result = toPortablePath('.', '/any/root');
+  assert.strictEqual(result.portable, '.');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('null/empty returns dot', () => {
+  const result = toPortablePath('', '/any/root');
+  assert.strictEqual(result.portable, '.');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('deeply nested (>3 levels up) falls back to absolute', () => {
+  const result = toPortablePath('/a/b', '/a/b/c/d/e/f');
+  assert.strictEqual(result.isAbsolute, true, 'should be marked absolute');
+  // Path should be the normalized absolute path
+  assert.ok(!result.portable.startsWith('.'), 'should not be relative');
+});
+
+test('same directory returns dot', () => {
+  const result = toPortablePath('/home/user/project', '/home/user/project');
+  assert.strictEqual(result.portable, '.');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('subdirectory becomes simple relative', () => {
+  const result = toPortablePath('/home/user/project/sub', '/home/user/project');
+  assert.strictEqual(result.portable, 'sub');
+  assert.strictEqual(result.isAbsolute, false);
+});
+
+test('backslashes in result are normalized to forward slashes', () => {
+  // On Windows, path.relative may return backslashes
+  const result = toPortablePath('d:\\Code\\kb', 'd:\\Code\\agents');
+  assert.ok(!result.portable.includes('\\'), 'should not contain backslashes');
+});
+
+// ─── resolveStoredPath ─────────────────────────────────────────────────────
+console.log('\nresolveStoredPath');
+
+test('dot path stays as dot', () => {
+  assert.strictEqual(resolveStoredPath('.', '/any/root'), '.');
+});
+
+test('null returns dot (safe default)', () => {
+  assert.strictEqual(resolveStoredPath(null, '/any/root'), '.');
+});
+
+test('absolute path passes through unchanged', () => {
+  assert.strictEqual(resolveStoredPath('/absolute/path', '/any/root'), '/absolute/path');
+});
+
+test('relative path resolved from project root', () => {
+  const result = resolveStoredPath('../kb', '/home/user/project');
+  assert.strictEqual(result, normalizePath(path.resolve('/home/user/project', '../kb')));
+});
+
+test('Windows drive letter path passes through', () => {
+  assert.strictEqual(resolveStoredPath('d:/Code/kb', '/any/root'), 'd:/Code/kb');
+});
+
+// ─── writeProjectLayoutYaml with portable paths ───────────────────────────
+console.log('\nwriteProjectLayoutYaml (portable paths)');
+
+test('writes relative paths for sibling directories', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    const siblingPath = path.join(path.dirname(tmpDir), 'kb-repo');
+    writeProjectLayoutYaml({
+      knowledgebase: { mode: 'local', path: siblingPath },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(tmpDir, '_bmad-output', 'project-layout.yaml'), 'utf-8');
+    assert.ok(content.includes('../kb-repo'), `should contain relative path, got: ${content}`);
+    assert.ok(!content.includes('PORTABILITY'), 'should not have portability warning');
+  } finally {
+    cleanup();
+  }
+});
+
+test('writes dot path unchanged for same-repo', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    writeProjectLayoutYaml({
+      knowledgebase: { mode: 'local', path: '.' },
+      sprintManagement: { mode: 'local', path: path.join(path.dirname(tmpDir), 'sprint') }
+    });
+    const content = fs.readFileSync(path.join(tmpDir, '_bmad-output', 'project-layout.yaml'), 'utf-8');
+    assert.ok(content.includes('path: "."'), `dot path should be preserved, got: ${content}`);
+    assert.ok(content.includes('../sprint'), 'sibling should be relative');
+  } finally {
+    cleanup();
+  }
+});
+
+// ─── writeRepoLayoutConfig with portable paths ────────────────────────────
+console.log('\nwriteRepoLayoutConfig (portable paths)');
+
+test('writes relative paths to config.yaml', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '# existing config\n{}');
+    const siblingKb = path.join(path.dirname(tmpDir), 'kb-repo');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'local', path: siblingKb },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    assert.ok(content.includes('knowledgebase_path: "../kb-repo"'), `should have relative path, got: ${content}`);
+    assert.ok(content.includes('sprint_management_path: "."'), `dot path preserved, got: ${content}`);
+  } finally {
+    cleanup();
+  }
+});
+
+test('derived artifact paths are relative when base is relative', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    const configDir = path.join(tmpDir, '_bmad', 'bmm');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.yaml'), '# config\n{}');
+    const siblingKb = path.join(path.dirname(tmpDir), 'kb-repo');
+    writeRepoLayoutConfig({
+      knowledgebase: { mode: 'local', path: siblingKb },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const content = fs.readFileSync(path.join(configDir, 'config.yaml'), 'utf-8');
+    assert.ok(content.includes('planning_artifacts: "../kb-repo/_bmad-output/planning-artifacts"'),
+      `planning_artifacts should be relative, got: ${content}`);
+    assert.ok(content.includes('implementation_artifacts: "_bmad-output/implementation-artifacts"'),
+      `impl_artifacts should use default for ".", got: ${content}`);
+  } finally {
+    cleanup();
+  }
+});
+
+// ─── Round-trip: write relative → read → resolve to absolute ───────────────
+console.log('\nRound-trip: write relative, read back, resolve to absolute');
+
+test('round-trip: sibling path written as relative, read back as resolved absolute', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    const siblingPath = normalizePath(path.join(path.dirname(tmpDir), 'kb-repo'));
+    writeProjectLayoutYaml({
+      knowledgebase: { mode: 'local', path: siblingPath },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    // Verify file has relative path
+    const fileContent = fs.readFileSync(path.join(tmpDir, '_bmad-output', 'project-layout.yaml'), 'utf-8');
+    assert.ok(fileContent.includes('../kb-repo'), 'file should store relative');
+
+    // Read back — should resolve to absolute
+    const result = readExistingLayout();
+    assert.ok(result, 'should read layout');
+    const resolvedKb = normalizePath(result.knowledgebase.path);
+    assert.strictEqual(resolvedKb, siblingPath, `should resolve back to original: got ${resolvedKb}`);
+  } finally {
+    cleanup();
+  }
+});
+
+test('round-trip: dot path stays as dot', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    writeProjectLayoutYaml({
+      knowledgebase: { mode: 'local', path: path.join(path.dirname(tmpDir), 'kb') },
+      sprintManagement: { mode: 'same', path: '.' }
+    });
+    const result = readExistingLayout();
+    assert.strictEqual(result.sprintManagement.path, '.', 'dot should stay as dot');
+  } finally {
+    cleanup();
+  }
+});
+
+test('backward compat: absolute paths in existing files still work', () => {
+  const { tmpDir, cleanup } = withTmpDir();
+  try {
+    // Manually write absolute path (old format)
+    const dir = path.join(tmpDir, '_bmad-output');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'project-layout.yaml'), [
+      'knowledgebase:',
+      '  mode: local',
+      '  path: "/absolute/old/kb"',
+      'sprint_management:',
+      '  mode: same',
+      '  path: "."',
+    ].join('\n'));
+
+    const result = readExistingLayout();
+    assert.ok(result, 'should read layout');
+    assert.strictEqual(result.knowledgebase.path, '/absolute/old/kb', 'absolute path should pass through');
+  } finally {
+    cleanup();
+  }
+});
+
+// ─── Summary ───────────────────────────────────────────────────────────────
+console.log(`\n${passed} passed, ${failed} failed`);
+if (errors.length > 0) {
+  console.log('\nFailed tests:');
+  errors.forEach(e => console.log(`  - ${e.name}: ${e.error}`));
+}
+if (failed > 0) process.exit(1);