nubos-pilot 0.8.0 → 0.8.2

package/bin/np-tools/new-project.cjs

@@ -177,6 +177,14 @@ function _apply(answersPath, cwd, stdout) {
     _render(_loadTemplate('REQUIREMENTS'), reqVars, 'REQUIREMENTS'),
   );
 
+  atomicWriteFileSync(
+    path.join(stateDir, 'RULES.md'),
+    _render(_loadTemplate('RULES'), {
+      project_name: answers.project_name,
+      created_date: createdDate,
+    }, 'RULES'),
+  );
+
   layout.createMilestoneDir(firstMilestoneNumber, root);
   const msTemplatesDir = path.join(TEMPLATES_DIR, 'milestone');
   const msCtx = _render(
@@ -261,6 +269,7 @@ function _apply(answersPath, cwd, stdout) {
     created: [
       '.nubos-pilot/PROJECT.md',
       '.nubos-pilot/REQUIREMENTS.md',
+      '.nubos-pilot/RULES.md',
       '.nubos-pilot/roadmap.yaml',
       '.nubos-pilot/STATE.md',
       path.relative(root, layout.milestoneContextPath(firstMilestoneNumber, root)),

package/bin/np-tools/pause-work.cjs

@@ -1,4 +1,25 @@
+const { execFileSync } = require('node:child_process');
+
 const { mutateState } = require('../../lib/state.cjs');
+const { captureSnapshot, writeSnapshot } = require('../../lib/session-snapshot.cjs');
+
+function _gitCommits(cwd, limit) {
+  try {
+    const out = execFileSync('git', [
+      '-C', cwd,
+      'log',
+      '--no-color',
+      '--max-count=' + Number(limit),
+      '--pretty=format:%H%x09%s%x09%cI',
+    ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [sha, subject, iso] = line.split('\t');
+      return { sha, subject, committed_at: iso };
+    });
+  } catch {
+    return [];
+  }
+}
 
 function run(_args, ctx) {
   const context = ctx || {};
@@ -12,10 +33,20 @@ function run(_args, ctx) {
       : null;
     return s;
   }, cwd);
+  let snapshotPath = null;
+  let snapshotErr = null;
+  try {
+    const snap = captureSnapshot(cwd, { lastCommits: _gitCommits(cwd, 10) });
+    snapshotPath = writeSnapshot(snap, cwd);
+  } catch (err) {
+    snapshotErr = String((err && err.message) || err);
+  }
   const payload = {
     ok: true,
     stopped_at: next.frontmatter.session.stopped_at,
     resume_file: next.frontmatter.session.resume_file,
+    snapshot_path: snapshotPath,
+    snapshot_error: snapshotErr,
   };
   stdout.write(JSON.stringify(payload));
   return payload;

package/bin/np-tools/resume-work.cjs

@@ -6,6 +6,7 @@ const { readCheckpoint, listCheckpoints } = require('../../lib/checkpoint.cjs');
 const { TASK_ID_RE } = require('../../lib/tasks.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 const layout = require('../../lib/layout.cjs');
+const { readSnapshot } = require('../../lib/session-snapshot.cjs');
 const {
   hasSliceWorktree,
   sliceWorktreePath,
@@ -116,6 +117,17 @@ function run(_args, ctx) {
     }));
   }
 
+  const snap = readSnapshot(cwd);
+  if (snap) {
+    payload.session_snapshot = {
+      captured_at: snap.captured_at,
+      milestone: snap.milestone,
+      current_task: snap.current_task,
+      last_commits: (snap.last_commits || []).slice(0, 5),
+      open_handoffs: snap.open_handoffs || [],
+    };
+  }
+
   stdout.write(JSON.stringify(payload));
   return payload;
 }

package/bin/np-tools/session-snapshot-read.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+const { readSnapshot } = require('../../lib/session-snapshot.cjs');
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const snap = readSnapshot(cwd);
+  stdout.write(JSON.stringify(snap || { ok: false, reason: 'no-snapshot' }));
+  return 0;
+}
+
+module.exports = { run };

package/bin/np-tools/session-snapshot-write.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const { captureSnapshot, writeSnapshot } = require('../../lib/session-snapshot.cjs');
+
+function _gitCommits(cwd, limit) {
+  try {
+    const out = execFileSync('git', [
+      '-C', cwd,
+      'log',
+      '--no-color',
+      '--max-count=' + Number(limit),
+      '--pretty=format:%H%x09%s%x09%cI',
+    ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [sha, subject, iso] = line.split('\t');
+      return { sha, subject, committed_at: iso };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const snap = captureSnapshot(cwd, { lastCommits: _gitCommits(cwd, 10) });
+  const dest = writeSnapshot(snap, cwd);
+  stdout.write(JSON.stringify({
+    ok: true,
+    snapshot_path: dest,
+    captured_at: snap.captured_at,
+    milestone: snap.milestone,
+    current_task: snap.current_task,
+    last_commit_count: snap.last_commits.length,
+    open_handoff_count: snap.open_handoffs.length,
+    checkpoint_count: snap.checkpoint_ids.length,
+  }));
+  return 0;
+}
+
+module.exports = { run };

package/lib/agents.test.cjs

@@ -224,6 +224,9 @@ const NP_AGENTS = [
   { file: 'np-verifier', expected_tier: 'sonnet' },
   { file: 'np-researcher', expected_tier: 'sonnet' },
   { file: 'np-codebase-documenter', expected_tier: 'sonnet' },
+  { file: 'np-architect', expected_tier: 'sonnet' },
+  { file: 'np-build-fixer', expected_tier: 'sonnet' },
+  { file: 'np-security-reviewer', expected_tier: 'sonnet' },
   { file: 'np-nyquist-auditor', expected_tier: 'haiku' },
   { file: 'np-sc-extractor', expected_tier: 'haiku' },
 ];

package/lib/knowledge.cjs

@@ -0,0 +1,256 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { projectStateDir, atomicWriteFileSync, NubosPilotError, withFileLock } = require('./core.cjs');
+
+const INDEX_VERSION = 1;
+const CHUNK_LINES = 40;
+const CHUNK_OVERLAP = 8;
+const MAX_RESULTS_DEFAULT = 10;
+const SNIPPET_LINES = 6;
+
+const STOPWORDS = new Set([
+  'the','a','an','of','to','in','on','for','and','or','is','are','was','were',
+  'be','as','by','at','it','this','that','these','those','with','from','into',
+  'der','die','das','und','oder','von','zu','im','in','auf','für','nicht',
+  'ist','sind','war','waren','sein','als','bei','an','mit','aus','nach',
+]);
+
+const INDEXED_GLOBS = [
+  'PROJECT.md',
+  'REQUIREMENTS.md',
+  'RULES.md',
+  'STATE.md',
+  'codebase/*.md',
+  'milestones/M*/*.md',
+  'milestones/M*/slices/S*/*.md',
+  'milestones/M*/slices/S*/tasks/T*/*.md',
+  'todos/**/*.md',
+  'threads/**/*.md',
+  'notes/**/*.md',
+];
+
+function _stateDir(cwd) {
+  return projectStateDir(cwd);
+}
+
+function _walkMarkdown(stateDir) {
+  const out = [];
+  if (!fs.existsSync(stateDir)) return out;
+
+  function walk(dir, depth) {
+    if (depth > 8) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      const rel = path.relative(stateDir, full);
+      if (rel.startsWith('archive' + path.sep)) continue;
+      if (rel.startsWith('checkpoints' + path.sep)) continue;
+      if (rel.startsWith('worktrees' + path.sep)) continue;
+      if (rel.startsWith('reports' + path.sep)) continue;
+      if (rel.startsWith('.tmp' + path.sep)) continue;
+      if (rel.startsWith('state' + path.sep)) continue;
+      if (e.isDirectory()) { walk(full, depth + 1); continue; }
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      out.push(full);
+    }
+  }
+  walk(stateDir, 0);
+  return out;
+}
+
+function _tokenize(text) {
+  const lower = String(text).toLowerCase();
+  const tokens = lower.match(/[a-z0-9][a-z0-9\-_]{1,}/g) || [];
+  return tokens.filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+
+function _hash(content) {
+  return crypto.createHash('sha1').update(content).digest('hex').slice(0, 16);
+}
+
+function _splitChunks(filePath, content) {
+  const lines = content.split(/\r?\n/);
+  const chunks = [];
+  let id = 0;
+  for (let start = 0; start < lines.length; start += (CHUNK_LINES - CHUNK_OVERLAP)) {
+    const end = Math.min(lines.length, start + CHUNK_LINES);
+    const slice = lines.slice(start, end);
+    const text = slice.join('\n');
+    if (text.trim().length === 0) continue;
+    chunks.push({
+      chunk_id: id++,
+      line_start: start + 1,
+      line_end: end,
+      text,
+    });
+    if (end >= lines.length) break;
+  }
+  return chunks;
+}
+
+function _docFromFile(stateDir, filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const stat = fs.statSync(filePath);
+  const rel = path.relative(stateDir, filePath);
+  const chunks = _splitChunks(filePath, content);
+  const indexedChunks = chunks.map((c) => {
+    const tokens = _tokenize(c.text);
+    const tf = Object.create(null);
+    for (const t of tokens) tf[t] = (tf[t] || 0) + 1;
+    return {
+      chunk_id: c.chunk_id,
+      line_start: c.line_start,
+      line_end: c.line_end,
+      length: tokens.length,
+      tf,
+      preview: c.text.split('\n').slice(0, SNIPPET_LINES).join('\n'),
+    };
+  });
+  return {
+    rel_path: rel,
+    mtime_ms: stat.mtimeMs,
+    size: stat.size,
+    sha: _hash(content),
+    chunks: indexedChunks,
+  };
+}
+
+function buildIndex(cwd) {
+  const stateDir = _stateDir(cwd);
+  const files = _walkMarkdown(stateDir);
+  const docs = files.map((f) => _docFromFile(stateDir, f));
+  const totalChunks = docs.reduce((n, d) => n + d.chunks.length, 0);
+  const avgLen = totalChunks
+    ? docs.reduce((n, d) => n + d.chunks.reduce((m, c) => m + c.length, 0), 0) / totalChunks
+    : 0;
+  const df = Object.create(null);
+  for (const d of docs) {
+    for (const c of d.chunks) {
+      for (const term of Object.keys(c.tf)) df[term] = (df[term] || 0) + 1;
+    }
+  }
+  return {
+    version: INDEX_VERSION,
+    built_at: new Date().toISOString(),
+    state_dir: stateDir,
+    total_files: docs.length,
+    total_chunks: totalChunks,
+    avg_chunk_length: Number(avgLen.toFixed(2)),
+    df,
+    docs,
+  };
+}
+
+function _indexPath(cwd) {
+  return path.join(_stateDir(cwd), 'state', 'knowledge-index.json');
+}
+
+function writeIndex(index, cwd) {
+  const dest = _indexPath(cwd);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  return withFileLock(dest, () => {
+    atomicWriteFileSync(dest, JSON.stringify(index));
+    return dest;
+  });
+}
+
+function readIndex(cwd) {
+  const dest = _indexPath(cwd);
+  if (!fs.existsSync(dest)) return null;
+  try {
+    const obj = JSON.parse(fs.readFileSync(dest, 'utf-8'));
+    if (!obj || obj.version !== INDEX_VERSION) return null;
+    return obj;
+  } catch { return null; }
+}
+
+function _bm25Score(terms, chunk, df, totalChunks, avgLen, k1 = 1.4, b = 0.75) {
+  let score = 0;
+  for (const term of terms) {
+    const f = chunk.tf[term] || 0;
+    if (f === 0) continue;
+    const n = df[term] || 0;
+    const idf = Math.log(1 + (totalChunks - n + 0.5) / (n + 0.5));
+    const denom = f + k1 * (1 - b + b * (chunk.length / Math.max(1, avgLen)));
+    score += idf * (f * (k1 + 1)) / (denom || 1);
+  }
+  return score;
+}
+
+function search(query, cwd, opts) {
+  const o = opts || {};
+  const limit = Math.max(1, Math.min(100, o.limit || MAX_RESULTS_DEFAULT));
+  let index = readIndex(cwd);
+  if (!index) {
+    index = buildIndex(cwd);
+    writeIndex(index, cwd);
+  }
+  const terms = _tokenize(query);
+  if (terms.length === 0) {
+    return { query, terms, total_hits: 0, hits: [], index_built_at: index.built_at };
+  }
+  const hits = [];
+  for (const doc of index.docs) {
+    for (const c of doc.chunks) {
+      const score = _bm25Score(terms, c, index.df, index.total_chunks, index.avg_chunk_length);
+      if (score > 0) {
+        hits.push({
+          rel_path: doc.rel_path,
+          line_start: c.line_start,
+          line_end: c.line_end,
+          score: Number(score.toFixed(4)),
+          preview: c.preview,
+        });
+      }
+    }
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return {
+    query,
+    terms,
+    total_hits: hits.length,
+    hits: hits.slice(0, limit),
+    index_built_at: index.built_at,
+    index_total_files: index.total_files,
+    index_total_chunks: index.total_chunks,
+  };
+}
+
+function indexStats(cwd) {
+  const idx = readIndex(cwd);
+  if (!idx) return { exists: false };
+  const groups = Object.create(null);
+  for (const d of idx.docs) {
+    const top = d.rel_path.split(path.sep)[0] || '<root>';
+    if (!groups[top]) groups[top] = { files: 0, chunks: 0, bytes: 0 };
+    groups[top].files += 1;
+    groups[top].chunks += d.chunks.length;
+    groups[top].bytes += d.size;
+  }
+  return {
+    exists: true,
+    built_at: idx.built_at,
+    total_files: idx.total_files,
+    total_chunks: idx.total_chunks,
+    avg_chunk_length: idx.avg_chunk_length,
+    unique_terms: Object.keys(idx.df).length,
+    groups,
+  };
+}
+
+module.exports = {
+  INDEX_VERSION,
+  INDEXED_GLOBS,
+  buildIndex,
+  writeIndex,
+  readIndex,
+  search,
+  indexStats,
+  _tokenize,
+  _splitChunks,
+};

package/lib/knowledge.test.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { buildIndex, writeIndex, readIndex, search, indexStats, _tokenize } = require('./knowledge.cjs');
+
+function _scratch() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-knowledge-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'milestones', 'M001', 'slices', 'S001', 'tasks', 'T0001'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'codebase'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'PROJECT.md'),
+    '# Project\n\nThe authentication system uses JWT tokens for session security.\n');
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'milestones', 'M001', 'M001-CONTEXT.md'),
+    '# M001 Context\n\nLocked: jose@6 for JWT verification, no hand-rolled crypto allowed.\n');
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'milestones', 'M001', 'slices', 'S001', 'S001-PLAN.md'),
+    '# S001 Plan\n\nTask 1: install jose. Task 2: verify token signature.\n');
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'codebase', 'auth.md'),
+    '# Auth Module\n\nPath: app/Auth/\nExternal Deps: jose, argon2.\n');
+  return root;
+}
+
+test('tokenize strips stopwords + short tokens', () => {
+  const t = _tokenize('The JWT token is verified using jose');
+  assert.ok(t.includes('jwt'));
+  assert.ok(t.includes('token'));
+  assert.ok(t.includes('jose'));
+  assert.ok(!t.includes('the'));
+  assert.ok(!t.includes('is'));
+});
+
+test('buildIndex covers PROJECT + milestones + codebase', () => {
+  const cwd = _scratch();
+  const idx = buildIndex(cwd);
+  assert.equal(idx.version, 1);
+  assert.equal(idx.total_files, 4);
+  assert.ok(idx.total_chunks >= 4);
+  assert.ok(idx.df['jose'] >= 2);
+});
+
+test('writeIndex + readIndex round-trip', () => {
+  const cwd = _scratch();
+  const idx = buildIndex(cwd);
+  const dest = writeIndex(idx, cwd);
+  assert.ok(fs.existsSync(dest));
+  const back = readIndex(cwd);
+  assert.equal(back.version, idx.version);
+  assert.equal(back.total_files, idx.total_files);
+});
+
+test('search ranks JWT-related chunks high', () => {
+  const cwd = _scratch();
+  const res = search('jwt jose', cwd);
+  assert.ok(res.total_hits >= 2);
+  assert.ok(res.hits[0].score > 0);
+  assert.match(res.hits[0].rel_path, /M001|PROJECT/);
+});
+
+test('search auto-builds index if missing', () => {
+  const cwd = _scratch();
+  const res = search('authentication', cwd);
+  assert.ok(res.total_hits >= 1);
+  assert.ok(readIndex(cwd) !== null);
+});
+
+test('search empty query returns 0 hits without crash', () => {
+  const cwd = _scratch();
+  const res = search('the', cwd);
+  assert.equal(res.total_hits, 0);
+});
+
+test('indexStats groups by top-level dir', () => {
+  const cwd = _scratch();
+  buildIndex(cwd);
+  writeIndex(buildIndex(cwd), cwd);
+  const s = indexStats(cwd);
+  assert.equal(s.exists, true);
+  assert.ok(s.groups.milestones);
+  assert.ok(s.groups.codebase);
+});

package/lib/session-snapshot.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { projectStateDir, atomicWriteFileSync, withFileLock } = require('./core.cjs');
+const { readState } = require('./state.cjs');
+
+const SNAPSHOT_VERSION = 1;
+
+function _snapshotPath(cwd) {
+  return path.join(projectStateDir(cwd), 'state', 'session-snapshot.json');
+}
+
+function _safeReadState(cwd) {
+  try { return readState(cwd); } catch { return null; }
+}
+
+function _listOpenHandoffs(cwd) {
+  const dir = path.join(projectStateDir(cwd), 'handoffs');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  function walk(d, depth) {
+    if (depth > 4) return;
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) { walk(full, depth + 1); continue; }
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      let txt = '';
+      try { txt = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+      const m = txt.match(/^---[\s\S]*?status:\s*(open|read)[\s\S]*?---/);
+      if (!m) continue;
+      out.push({
+        id: path.basename(e.name, '.md'),
+        rel_path: path.relative(projectStateDir(cwd), full),
+        status: m[1],
+      });
+    }
+  }
+  walk(dir, 0);
+  return out;
+}
+
+function _listCheckpoints(cwd) {
+  const dir = path.join(projectStateDir(cwd), 'checkpoints');
+  if (!fs.existsSync(dir)) return [];
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  return entries.filter((f) => f.endsWith('.json')).map((f) => path.basename(f, '.json'));
+}
+
+function captureSnapshot(cwd, opts) {
+  const root = cwd || process.cwd();
+  const state = _safeReadState(root);
+  const fm = state && state.frontmatter ? state.frontmatter : {};
+  const lastCommits = (opts && Array.isArray(opts.lastCommits)) ? opts.lastCommits : [];
+  return {
+    version: SNAPSHOT_VERSION,
+    captured_at: new Date().toISOString(),
+    milestone: fm.milestone || null,
+    milestone_name: fm.milestone_name || null,
+    current_task: fm.current_task || null,
+    progress: fm.progress || null,
+    last_commits: lastCommits,
+    open_handoffs: _listOpenHandoffs(root),
+    checkpoint_ids: _listCheckpoints(root),
+  };
+}
+
+function writeSnapshot(snapshot, cwd) {
+  const root = cwd || process.cwd();
+  const dest = _snapshotPath(root);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  return withFileLock(dest, () => {
+    atomicWriteFileSync(dest, JSON.stringify(snapshot, null, 2));
+    return dest;
+  });
+}
+
+function readSnapshot(cwd) {
+  const root = cwd || process.cwd();
+  const dest = _snapshotPath(root);
+  if (!fs.existsSync(dest)) return null;
+  try {
+    const obj = JSON.parse(fs.readFileSync(dest, 'utf-8'));
+    if (!obj || obj.version !== SNAPSHOT_VERSION) return null;
+    return obj;
+  } catch { return null; }
+}
+
+module.exports = { SNAPSHOT_VERSION, captureSnapshot, writeSnapshot, readSnapshot };

package/lib/session-snapshot.test.cjs

@@ -0,0 +1,73 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+const { captureSnapshot, writeSnapshot, readSnapshot } = require('./session-snapshot.cjs');
+const { writeState } = require('./state.cjs');
+
+function _scratch() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-snapshot-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'handoffs'), { recursive: true });
+  execFileSync('git', ['-C', root, 'init', '-q', '-b', 'main'], { stdio: 'ignore' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'snap@test'], { stdio: 'ignore' });
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'Snap'], { stdio: 'ignore' });
+  fs.writeFileSync(path.join(root, 'README.md'), 'x\n');
+  execFileSync('git', ['-C', root, 'add', '-A'], { stdio: 'ignore' });
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', 'task(M001-S001-T0001): initial'], { stdio: 'ignore' });
+  writeState({ frontmatter: {
+    schema_version: 2,
+    milestone: 'M001',
+    milestone_name: 'Test Milestone',
+    current_task: 'M001-S001-T0001',
+    last_updated: new Date().toISOString(),
+    progress: { total_milestones: 1, completed_milestones: 0, total_tasks: 1, completed_tasks: 0, percent: 0 },
+    session: { stopped_at: null, resume_file: null, last_activity: null },
+  }, body: '\n# State\n' }, root);
+  fs.writeFileSync(
+    path.join(root, '.nubos-pilot', 'handoffs', 'h1.md'),
+    '---\nfrom: a\nto: b\nstatus: open\n---\nbody\n',
+  );
+  return root;
+}
+
+test('captureSnapshot pulls state + caller-supplied commits + handoffs', () => {
+  const root = _scratch();
+  const snap = captureSnapshot(root, {
+    lastCommits: [{ sha: 'abc1234', subject: 'task: t1', committed_at: '2026-04-28T00:00:00Z' }],
+  });
+  assert.equal(snap.version, 1);
+  assert.equal(snap.milestone, 'M001');
+  assert.equal(snap.current_task, 'M001-S001-T0001');
+  assert.equal(snap.last_commits.length, 1);
+  assert.equal(snap.last_commits[0].sha, 'abc1234');
+  assert.equal(snap.open_handoffs.length, 1);
+  assert.equal(snap.open_handoffs[0].status, 'open');
+});
+
+test('captureSnapshot defaults last_commits to [] when not supplied', () => {
+  const root = _scratch();
+  const snap = captureSnapshot(root);
+  assert.deepEqual(snap.last_commits, []);
+});
+
+test('writeSnapshot + readSnapshot round-trip', () => {
+  const root = _scratch();
+  const snap = captureSnapshot(root, { lastCommits: [] });
+  const dest = writeSnapshot(snap, root);
+  assert.ok(fs.existsSync(dest));
+  const back = readSnapshot(root);
+  assert.equal(back.milestone, snap.milestone);
+  assert.equal(back.current_task, snap.current_task);
+});
+
+test('readSnapshot returns null when missing', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-snapshot-empty-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  assert.equal(readSnapshot(root), null);
+});