docs(beads): etch project history into memory bank and finalize skill-bb

We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.

Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.

Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.

tests/skills/beadboard-driver/generate-agent-name.test.ts

@@ -0,0 +1,79 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const scriptPath = path.resolve('skills/beadboard-driver/scripts/generate-agent-name.mjs');
+
+async function runName(env: Record<string, string | undefined> = {}) {
+  const { stdout } = await execFileAsync('node', [scriptPath], {
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(stdout);
+}
+
+async function withTempDir(run: (root: string) => Promise<void>) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-name-'));
+  try {
+    await run(root);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}
+
+test('generate-agent-name returns adjective-noun format', async () => {
+  const result = await runName({
+    BB_NAME_ADJECTIVES: 'green',
+    BB_NAME_NOUNS: 'castle',
+    BB_NAME_MAX_RETRIES: '1',
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.agent_name, 'green-castle');
+  assert.match(result.agent_name, /^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+});
+
+test('generate-agent-name retries on collisions', async () => {
+  await withTempDir(async (root) => {
+    const registryDir = path.join(root, 'agents');
+    await fs.mkdir(registryDir, { recursive: true });
+    await fs.writeFile(path.join(registryDir, 'green-castle.json'), '{}', 'utf8');
+
+    const result = await runName({
+      BB_AGENT_REGISTRY_DIR: registryDir,
+      BB_NAME_ADJECTIVES: 'green,blue',
+      BB_NAME_NOUNS: 'castle',
+      BB_NAME_MAX_RETRIES: '3',
+      BB_NAME_SEED_SEQUENCE: '0,0,0.9,0',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.agent_name, 'blue-castle');
+    assert.equal(result.collisions, 2);
+    assert.equal(result.attempts, 3);
+  });
+});
+
+test('generate-agent-name fails after retry exhaustion', async () => {
+  await withTempDir(async (root) => {
+    const registryDir = path.join(root, 'agents');
+    await fs.mkdir(registryDir, { recursive: true });
+    await fs.writeFile(path.join(registryDir, 'green-castle.json'), '{}', 'utf8');
+
+    const result = await runName({
+      BB_AGENT_REGISTRY_DIR: registryDir,
+      BB_NAME_ADJECTIVES: 'green',
+      BB_NAME_NOUNS: 'castle',
+      BB_NAME_MAX_RETRIES: '2',
+      BB_NAME_SEED_SEQUENCE: '0,0,0,0',
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.error_code, 'NAME_GENERATION_EXHAUSTED');
+    assert.equal(result.attempts, 2);
+  });
+});

tests/skills/beadboard-driver/readiness-report.test.ts

@@ -0,0 +1,57 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const scriptPath = path.resolve('skills/beadboard-driver/scripts/readiness-report.mjs');
+
+async function runReport(args: string[]) {
+  const { stdout } = await execFileAsync('node', [scriptPath, ...args], {
+    env: process.env,
+  });
+  return JSON.parse(stdout);
+}
+
+async function withTempDir(run: (root: string) => Promise<void>) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-report-'));
+  try {
+    await run(root);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}
+
+test('readiness-report outputs stable schema', async () => {
+  await withTempDir(async (root) => {
+    const artifact = path.join(root, 'artifact.txt');
+    await fs.writeFile(artifact, 'ok', 'utf8');
+
+    const checks = JSON.stringify([
+      { name: 'typecheck', ok: true, details: 'pass' },
+      { name: 'test', ok: true, details: 'pass' },
+    ]);
+    const artifacts = JSON.stringify([{ path: artifact, required: true }]);
+
+    const result = await runReport(['--checks', checks, '--artifacts', artifacts, '--dependency-note', 'acyclic']);
+
+    assert.equal(result.ok, true);
+    assert.equal(result.summary.ready, true);
+    assert.equal(result.checks.length, 2);
+    assert.equal(result.artifacts[0].exists, true);
+    assert.equal(result.dependency_sanity, 'acyclic');
+  });
+});
+
+test('readiness-report flags missing required artifact', async () => {
+  const checks = JSON.stringify([{ name: 'lint', ok: true, details: 'pass' }]);
+  const artifacts = JSON.stringify([{ path: 'missing.png', required: true }]);
+
+  const result = await runReport(['--checks', checks, '--artifacts', artifacts]);
+  assert.equal(result.ok, true);
+  assert.equal(result.summary.ready, false);
+  assert.equal(result.artifacts[0].exists, false);
+});

tests/skills/beadboard-driver/resolve-bb.test.ts

@@ -0,0 +1,137 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const scriptPath = path.resolve('skills/beadboard-driver/scripts/resolve-bb.mjs');
+
+async function runResolve(env: Record<string, string | undefined> = {}) {
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(stdout);
+}
+
+async function withTempDir(run: (root: string) => Promise<void>) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-resolve-'));
+  try {
+    await run(root);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}
+
+test('resolve-bb uses BB_REPO and returns env source', async () => {
+  await withTempDir(async (root) => {
+    const repo = path.join(root, 'beadboard');
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+
+    const result = await runResolve({
+      BB_REPO: repo,
+      BB_SKILL_HOME: path.join(root, 'home'),
+      PATH: '',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.source, 'env');
+    assert.equal(result.resolved_path, path.join(repo, 'bb.ps1'));
+  });
+});
+
+test('resolve-bb fails with remediation when BB_REPO is invalid', async () => {
+  await withTempDir(async (root) => {
+    const result = await runResolve({
+      BB_REPO: path.join(root, 'missing'),
+      BB_SKILL_HOME: path.join(root, 'home'),
+      PATH: '',
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.source, 'env');
+    assert.match(result.reason, /BB_REPO/i);
+    assert.match(result.remediation, /Set BB_REPO/i);
+  });
+});
+
+test('resolve-bb uses cache when env and global are unavailable', async () => {
+  await withTempDir(async (root) => {
+    const repo = path.join(root, 'beadboard');
+    const home = path.join(root, 'home');
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+    await fs.mkdir(path.join(home, '.beadboard'), { recursive: true });
+    await fs.writeFile(
+      path.join(home, '.beadboard', 'skill-config.json'),
+      JSON.stringify({ bb_path: path.join(repo, 'bb.ps1') }, null, 2),
+      'utf8',
+    );
+
+    const result = await runResolve({
+      BB_SKILL_HOME: home,
+      PATH: '',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.source, 'cache');
+  });
+});
+
+test('resolve-bb discovers repo and self-updates cache', async () => {
+  await withTempDir(async (root) => {
+    const repo = path.join(root, 'workspace', 'beadboard');
+    const home = path.join(root, 'home');
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+
+    const result = await runResolve({
+      BB_SKILL_HOME: home,
+      BB_SEARCH_ROOTS: path.join(root, 'workspace'),
+      PATH: '',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.source, 'discovery');
+
+    const cacheRaw = await fs.readFile(path.join(home, '.beadboard', 'skill-config.json'), 'utf8');
+    const cache = JSON.parse(cacheRaw);
+    assert.equal(cache.bb_path, path.join(repo, 'bb.ps1'));
+  });
+});
+
+test('resolve-bb uses BB_REPO over cache and rewrites stale cache', async () => {
+  await withTempDir(async (root) => {
+    const repoA = path.join(root, 'repo-a');
+    const repoB = path.join(root, 'repo-b');
+    const home = path.join(root, 'home');
+
+    await fs.mkdir(path.join(repoA, 'tools'), { recursive: true });
+    await fs.mkdir(path.join(repoB, 'tools'), { recursive: true });
+    await fs.writeFile(path.join(repoA, 'bb.ps1'), 'echo a', 'utf8');
+    await fs.writeFile(path.join(repoB, 'bb.ps1'), 'echo b', 'utf8');
+    await fs.mkdir(path.join(home, '.beadboard'), { recursive: true });
+    await fs.writeFile(
+      path.join(home, '.beadboard', 'skill-config.json'),
+      JSON.stringify({ bb_path: path.join(repoA, 'bb.ps1') }, null, 2),
+      'utf8',
+    );
+
+    const result = await runResolve({
+      BB_REPO: repoB,
+      BB_SKILL_HOME: home,
+      PATH: '',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.source, 'env');
+    assert.match(result.reason, /cache mismatch/i);
+
+    const cacheRaw = await fs.readFile(path.join(home, '.beadboard', 'skill-config.json'), 'utf8');
+    const cache = JSON.parse(cacheRaw);
+    assert.equal(cache.bb_path, path.join(repoB, 'bb.ps1'));
+  });
+});

tests/skills/beadboard-driver/session-preflight.test.ts

@@ -0,0 +1,60 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const scriptPath = path.resolve('skills/beadboard-driver/scripts/session-preflight.mjs');
+
+async function runPreflight(env: Record<string, string | undefined> = {}) {
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+    env: { ...process.env, ...env },
+  });
+  return JSON.parse(stdout);
+}
+
+async function withTempDir(run: (root: string) => Promise<void>) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bb-skill-preflight-'));
+  try {
+    await run(root);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}
+
+test('session-preflight fails when bd is unavailable', async () => {
+  const result = await runPreflight({
+    PATH: '',
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.error_code, 'BD_NOT_FOUND');
+});
+
+test('session-preflight succeeds with fake bd and BB_REPO', async () => {
+  await withTempDir(async (root) => {
+    const repo = path.join(root, 'beadboard');
+    const toolsDir = path.join(root, 'tools');
+    const bdCmd = path.join(toolsDir, 'bd.cmd');
+
+    await fs.mkdir(path.join(repo, 'tools'), { recursive: true });
+    await fs.mkdir(toolsDir, { recursive: true });
+    await fs.writeFile(path.join(repo, 'bb.ps1'), 'echo ok', 'utf8');
+    await fs.writeFile(bdCmd, '@echo off\r\necho beads\r\n', 'utf8');
+
+    const result = await runPreflight({
+      PATH: toolsDir,
+      BB_REPO: repo,
+      BB_SKILL_HOME: path.join(root, 'home'),
+      BB_SKIP_PROBE: '1',
+    });
+
+    assert.equal(result.ok, true);
+    assert.equal(result.bb.ok, true);
+    assert.equal(result.bb.source, 'env');
+    assert.equal(result.tools.bd.available, true);
+  });
+});

tests/skills/beadboard-driver/skill-local-runner.test.ts

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+test('skill-local runner passes', async () => {
+  const runnerPath = path.resolve('skills/beadboard-driver/tests/run-tests.mjs');
+  const { stdout, stderr } = await execFileAsync(process.execPath, [runnerPath], {
+    env: process.env,
+  });
+  assert.doesNotMatch(`${stdout}\n${stderr}`, /not ok/i);
+});