nubos-pilot 1.0.4 → 1.0.5

package/bin/np-tools/_commands.cjs

@@ -17,6 +17,8 @@ const COMMANDS = [
   { name: 'commit-task',         category: 'Execution', description: 'Atomic per-task git commit via lib/git.cjs', description_de: 'Atomarer Per-Task-Git-Commit über lib/git.cjs' },
   { name: 'checkpoint',          category: 'Execution', description: 'Per-task crash-safety checkpoint CRUD (start/transition/touch/show)', description_de: 'Per-Task-Checkpoint-CRUD für Crash-Safety (start/transition/touch/show)' },
   { name: 'verify-work',         category: 'Execution', description: 'Two-pass goal-backward verification (milestone-level VERIFICATION.md)', description_de: 'Zweistufige Goal-Backward-Verifikation (Milestone-Ebene VERIFICATION.md)' },
+  { name: 'close-project',       category: 'Review',    description: 'Aggregate verification of every milestone; writes PROJECT-SUMMARY.md + sets project_status=completed', description_de: 'Aggregat-Verifikation aller Milestones; schreibt PROJECT-SUMMARY.md + setzt project_status=completed' },
+  { name: 'archive-project',     category: 'Planning',  description: 'Move current .nubos-pilot/ project to archive/<slug>-<YYYYMMDD>/ (status|do|list|read)', description_de: 'Verschiebt aktuelles .nubos-pilot/-Projekt nach archive/<slug>-<YYYYMMDD>/ (status|do|list|read)' },
   { name: 'add-tests',           category: 'Execution', description: 'Persist VERIFICATION Pass-cases as node:test UAT (Sentinel-preserving)', description_de: 'Persistiert VERIFICATION-Pass-Cases als node:test-UAT (Sentinel-erhaltend)' },
   { name: 'pause-work',          category: 'Execution', description: 'Stamp STATE.session.stopped_at + resume_file for explicit handoff', description_de: 'Setzt STATE.session.stopped_at + resume_file für expliziten Handoff' },
   { name: 'resume-work',         category: 'Execution', description: 'Classify session state (resume | orphan | clean) from STATE + checkpoints', description_de: 'Klassifiziert Session-Zustand (resume | orphan | clean) aus STATE + Checkpoints' },

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

@@ -0,0 +1,87 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const archive = require('../../lib/archive.cjs');
+
+function _parseCarryOver(raw) {
+  if (raw == null || raw === '') return null;
+  return String(raw).split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function _parseArgs(list) {
+  const out = { force: false, carry_over: null, name: null, rel_path: null };
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i];
+    if (a === '--force') out.force = true;
+    else if (a === '--carry-over') out.carry_over = _parseCarryOver(list[++i]);
+    else if (a.startsWith('--carry-over=')) out.carry_over = _parseCarryOver(a.slice('--carry-over='.length));
+    else if (a === '--no-carry-over') out.carry_over = [];
+    else if (a === '--name') out.name = list[++i];
+    else if (a === '--rel') out.rel_path = list[++i];
+  }
+  return out;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+  const rest = list.slice(1);
+  const flags = _parseArgs(rest);
+
+  switch (verb) {
+    case 'status':
+    case 'check': {
+      const payload = {
+        project_exists: archive.projectExists(cwd),
+        completion: archive.computeCompletionStatus(cwd),
+        archive_root: archive.archiveRoot(cwd),
+      };
+      stdout.write(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    case 'do':
+    case 'create': {
+      const opts = {};
+      if (flags.force) opts.force = true;
+      if (flags.carry_over != null) opts.carry_over = flags.carry_over;
+      const result = archive.archiveProject(cwd, opts);
+      stdout.write(JSON.stringify(result, null, 2));
+      return result;
+    }
+    case 'list': {
+      const items = archive.listArchives(cwd);
+      stdout.write(JSON.stringify(items, null, 2));
+      return items;
+    }
+    case 'read': {
+      if (!flags.name) {
+        throw new NubosPilotError(
+          'archive-read-missing-name',
+          'archive-project read requires --name <archive-dir-name>',
+          { args: list.slice() },
+        );
+      }
+      if (!flags.rel_path) {
+        throw new NubosPilotError(
+          'archive-read-missing-rel',
+          'archive-project read requires --rel <relative-path>',
+          { args: list.slice() },
+        );
+      }
+      const content = archive.readArchiveFile(cwd, flags.name, flags.rel_path);
+      stdout.write(content);
+      return { ok: true };
+    }
+    default:
+      throw new NubosPilotError(
+        'archive-project-unknown-verb',
+        'archive-project: unknown verb: ' + String(verb),
+        { verb, allowed: ['status', 'do', 'list', 'read'] },
+      );
+  }
+}
+
+module.exports = { run };

package/bin/np-tools/archive-project.test.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const subcmd = require('./archive-project.cjs');
+const layout = require('../../lib/layout.cjs');
+
+const _sandboxes = [];
+
+function _completeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-arc-'));
+  _sandboxes.push(root);
+  const sd = path.join(root, '.nubos-pilot');
+  fs.mkdirSync(sd, { recursive: true });
+  fs.writeFileSync(path.join(sd, 'PROJECT.md'), '# Demo\n\nbody\n', 'utf-8');
+  fs.writeFileSync(
+    path.join(sd, 'roadmap.yaml'),
+    YAML.stringify({
+      schema_version: 2,
+      milestones: [{ id: 'M001', number: 1, name: 'a', status: 'done', success_criteria: ['x'], slices: [] }],
+    }),
+    'utf-8',
+  );
+  const mDir = layout.milestoneDir(1, root);
+  fs.mkdirSync(mDir, { recursive: true });
+  fs.writeFileSync(path.join(mDir, 'M001-VERIFICATION.md'),
+    '**Milestone Status:** verified\n### SC-1: x\n- **Status:** Pass\n- **Classified by:** np-verifier\n- **Evidence:** abc\n', 'utf-8');
+  fs.writeFileSync(path.join(mDir, 'M001-VALIDATION.md'),
+    '- REQ-01: COVERED\n', 'utf-8');
+  return root;
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {}
+  }
+});
+
+function _capture() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+test('AP-1: status verb returns project_exists + completion', () => {
+  const sb = _completeSandbox();
+  const cap = _capture();
+  subcmd.run(['status'], { cwd: sb, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.project_exists, true);
+  assert.equal(payload.completion.complete, true);
+});
+
+test('AP-2: do verb archives a complete project', () => {
+  const sb = _completeSandbox();
+  const cap = _capture();
+  subcmd.run(['do'], { cwd: sb, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.ok(payload.archive_dir.includes('archive'));
+  assert.ok(fs.existsSync(path.join(payload.archive_dir, 'ARCHIVE.json')));
+  assert.equal(fs.existsSync(path.join(sb, '.nubos-pilot', 'PROJECT.md')), false);
+});
+
+test('AP-3: list verb returns archives in newest-first order', () => {
+  const sb = _completeSandbox();
+  subcmd.run(['do'], { cwd: sb, stdout: _capture().stub });
+  const cap = _capture();
+  subcmd.run(['list'], { cwd: sb, stdout: cap.stub });
+  const items = JSON.parse(cap.get().trim());
+  assert.equal(items.length, 1);
+  assert.equal(items[0].completion_status, 'complete');
+});
+
+test('AP-4: unknown verb throws', () => {
+  const sb = _completeSandbox();
+  assert.throws(
+    () => subcmd.run(['nope'], { cwd: sb, stdout: _capture().stub }),
+    (err) => err.code === 'archive-project-unknown-verb',
+  );
+});
+
+test('AP-5: read verb returns archived file content', () => {
+  const sb = _completeSandbox();
+  const cap1 = _capture();
+  subcmd.run(['do'], { cwd: sb, stdout: cap1.stub });
+  const archiveResult = JSON.parse(cap1.get().trim());
+  const archiveName = path.basename(archiveResult.archive_dir);
+  const cap2 = _capture();
+  subcmd.run(['read', '--name', archiveName, '--rel', 'PROJECT.md'], { cwd: sb, stdout: cap2.stub });
+  assert.match(cap2.get(), /# Demo/);
+});
+
+test('AP-6: read verb refuses missing flags', () => {
+  const sb = _completeSandbox();
+  subcmd.run(['do'], { cwd: sb, stdout: _capture().stub });
+  assert.throws(
+    () => subcmd.run(['read'], { cwd: sb, stdout: _capture().stub }),
+    (err) => err.code === 'archive-read-missing-name',
+  );
+});
+
+test('AP-7: --no-carry-over skips archive copy but leaves originals in place', () => {
+  const sb = _completeSandbox();
+  fs.mkdirSync(path.join(sb, '.nubos-pilot', 'learnings'), { recursive: true });
+  fs.writeFileSync(path.join(sb, '.nubos-pilot', 'learnings', 'x.md'), 'hi', 'utf-8');
+  const cap = _capture();
+  subcmd.run(['do', '--no-carry-over'], { cwd: sb, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.deepEqual(payload.carried_over, []);
+  assert.equal(fs.existsSync(path.join(sb, '.nubos-pilot', 'learnings', 'x.md')), true);
+  assert.equal(fs.existsSync(path.join(payload.archive_dir, 'learnings')), false);
+});

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

@@ -0,0 +1,103 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const {
+  NubosPilotError,
+  projectStateDir,
+} = require('../../lib/core.cjs');
+const archive = require('../../lib/archive.cjs');
+const textMode = require('../../lib/text-mode.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+
+function _emit(payload, stdout, cwd) {
+  const json = JSON.stringify(payload, null, 2);
+  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD_BYTES) {
+    stdout.write(json);
+    return;
+  }
+  let tmpDir;
+  try {
+    tmpDir = path.join(projectStateDir(cwd), '.tmp');
+    fs.mkdirSync(tmpDir, { recursive: true });
+  } catch { tmpDir = os.tmpdir(); }
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'init-close-project-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function _initPayload(cwd) {
+  const completion = archive.computeCompletionStatus(cwd);
+  const tmDetail = textMode.resolveTextModeDetail(cwd);
+  return {
+    _workflow: 'close-project',
+    cwd,
+    project_exists: archive.projectExists(cwd),
+    completion,
+    summary_path: archive.projectSummaryPath(cwd),
+    text_mode: tmDetail.enabled,
+    text_mode_source: tmDetail.source,
+  };
+}
+
+function _emitSummary(cwd) {
+  return archive.writeProjectSummary(cwd);
+}
+
+function _mark(cwd) {
+  return archive.setProjectStatus(cwd, 'completed');
+}
+
+function _unmark(cwd) {
+  return archive.setProjectStatus(cwd, 'active');
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+
+  switch (verb) {
+    case 'init':
+    case undefined: {
+      const payload = _initPayload(cwd);
+      _emit(payload, stdout, cwd);
+      return payload;
+    }
+    case 'check': {
+      const payload = archive.computeCompletionStatus(cwd);
+      stdout.write(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    case 'write-summary': {
+      const result = _emitSummary(cwd);
+      stdout.write(JSON.stringify(result));
+      return result;
+    }
+    case 'mark-completed': {
+      const result = _mark(cwd);
+      stdout.write(JSON.stringify(result));
+      return result;
+    }
+    case 'unmark': {
+      const result = _unmark(cwd);
+      stdout.write(JSON.stringify(result));
+      return result;
+    }
+    default:
+      throw new NubosPilotError(
+        'close-project-unknown-verb',
+        'close-project: unknown verb: ' + String(verb),
+        { verb },
+      );
+  }
+}
+
+module.exports = { run };

package/bin/np-tools/close-project.test.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const subcmd = require('./close-project.cjs');
+const layout = require('../../lib/layout.cjs');
+
+const _sandboxes = [];
+
+function _sandbox(milestones, milestoneArtifacts) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-cp-'));
+  _sandboxes.push(root);
+  const sd = path.join(root, '.nubos-pilot');
+  fs.mkdirSync(sd, { recursive: true });
+  fs.writeFileSync(path.join(sd, 'PROJECT.md'), '# Demo Project\n\nbody\n', 'utf-8');
+  fs.writeFileSync(
+    path.join(sd, 'roadmap.yaml'),
+    YAML.stringify({ schema_version: 2, milestones }),
+    'utf-8',
+  );
+  for (const m of (milestoneArtifacts || [])) {
+    const mDir = layout.milestoneDir(m.number, root);
+    fs.mkdirSync(mDir, { recursive: true });
+    if (m.verification) fs.writeFileSync(path.join(mDir, 'M' + String(m.number).padStart(3, '0') + '-VERIFICATION.md'), m.verification, 'utf-8');
+    if (m.validation) fs.writeFileSync(path.join(mDir, 'M' + String(m.number).padStart(3, '0') + '-VALIDATION.md'), m.validation, 'utf-8');
+  }
+  return root;
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {}
+  }
+});
+
+function _capture() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+function _verified() {
+  return '# M001\n\n**Verified:** 2026-05-11\n**Milestone Status:** verified\n\n## Success Criteria\n\n### SC-1: x\n- **Status:** Pass\n- **Classified by:** np-verifier\n- **Evidence:** abc\n';
+}
+
+function _validation() {
+  return '# M001 Validation\n- REQ-01: COVERED\n';
+}
+
+test('CP-1: init returns completion payload', () => {
+  const sb = _sandbox(
+    [{ id: 'M001', number: 1, name: 'a', status: 'done', success_criteria: ['x'], slices: [] }],
+    [{ number: 1, verification: _verified(), validation: _validation() }],
+  );
+  const cap = _capture();
+  subcmd.run(['init'], { cwd: sb, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload._workflow, 'close-project');
+  assert.equal(payload.project_exists, true);
+  assert.equal(payload.completion.status, 'complete');
+});
+
+test('CP-2: write-summary writes PROJECT-SUMMARY.md', () => {
+  const sb = _sandbox(
+    [{ id: 'M001', number: 1, name: 'a', status: 'done', success_criteria: ['x'], slices: [] }],
+    [{ number: 1, verification: _verified(), validation: _validation() }],
+  );
+  const cap = _capture();
+  subcmd.run(['write-summary'], { cwd: sb, stdout: cap.stub });
+  const summaryPath = path.join(sb, '.nubos-pilot', 'PROJECT-SUMMARY.md');
+  assert.ok(fs.existsSync(summaryPath));
+  const md = fs.readFileSync(summaryPath, 'utf-8');
+  assert.match(md, /Project Summary/);
+});
+
+test('CP-3: mark-completed sets project_status in roadmap.yaml', () => {
+  const sb = _sandbox(
+    [{ id: 'M001', number: 1, name: 'a', status: 'done', success_criteria: ['x'], slices: [] }],
+    [{ number: 1, verification: _verified(), validation: _validation() }],
+  );
+  subcmd.run(['mark-completed'], { cwd: sb, stdout: _capture().stub });
+  const doc = YAML.parse(fs.readFileSync(path.join(sb, '.nubos-pilot', 'roadmap.yaml'), 'utf-8'));
+  assert.equal(doc.project_status, 'completed');
+});
+
+test('CP-4: unknown verb throws NubosPilotError', () => {
+  const sb = _sandbox(
+    [{ id: 'M001', number: 1, name: 'a', status: 'done', success_criteria: ['x'], slices: [] }],
+    [],
+  );
+  assert.throws(
+    () => subcmd.run(['frobnicate'], { cwd: sb, stdout: _capture().stub }),
+    (err) => err.code === 'close-project-unknown-verb',
+  );
+});
+
+test('CP-5: check verb prints completion JSON', () => {
+  const sb = _sandbox(
+    [{ id: 'M001', number: 1, name: 'a', status: 'pending', success_criteria: ['x'], slices: [] }],
+    [],
+  );
+  const cap = _capture();
+  subcmd.run(['check'], { cwd: sb, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.status, 'incomplete');
+  assert.ok(payload.blockers.length > 0);
+});

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

@@ -11,6 +11,7 @@ const {
 const { writeState } = require('../../lib/state.cjs');
 const layout = require('../../lib/layout.cjs');
 const textMode = require('../../lib/text-mode.cjs');
+const archive = require('../../lib/archive.cjs');
 
 const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
 const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
@@ -43,12 +44,29 @@ function _todayIso() {
   return new Date().toISOString().slice(0, 10);
 }
 
+function _detectPayload(cwd) {
+  const exists = archive.projectExists(cwd);
+  if (!exists) {
+    return {
+      existing_project: false,
+      completion: null,
+      archives: archive.listArchives(cwd),
+    };
+  }
+  return {
+    existing_project: true,
+    completion: archive.computeCompletionStatus(cwd),
+    archives: archive.listArchives(cwd),
+  };
+}
+
 function _interviewPayload(cwd) {
   const tmDetail = textMode.resolveTextModeDetail(cwd);
   return {
     mode: 'interview',
     text_mode: tmDetail.enabled,
     text_mode_source: tmDetail.source,
+    detection: _detectPayload(cwd),
     questions: [
       { key: 'project_name', type: 'input',
         question: 'Project name?' },
@@ -285,6 +303,11 @@ function run(args, ctx) {
   const stdout = context.stdout || process.stdout;
   const argv = args || [];
 
+  if (argv.includes('--detect')) {
+    _emit(stdout, { mode: 'detect', detection: _detectPayload(cwd) });
+    return;
+  }
+
   const applyIdx = argv.indexOf('--apply');
   if (applyIdx >= 0) {
     const answersPath = argv[applyIdx + 1];
@@ -302,4 +325,4 @@ function run(args, ctx) {
   _emit(stdout, _interviewPayload(cwd));
 }
 
-module.exports = { run, _interviewPayload, _slugify };
+module.exports = { run, _interviewPayload, _detectPayload, _slugify };

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

@@ -171,3 +171,34 @@ test('NP-9: backwards compat — accepts legacy first_phase_name as goal fallbac
   const doc = YAML.parse(fs.readFileSync(path.join(sandbox, '.nubos-pilot', 'roadmap.yaml'), 'utf-8'));
   assert.equal(doc.milestones[0].goal, 'Legacy phase-name');
 });
+
+test('NP-10: --detect on empty workspace returns existing_project=false', () => {
+  const sandbox = makeEmptySandbox();
+  const cap = _captureStdout();
+  subcmd.run(['--detect'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.mode, 'detect');
+  assert.equal(payload.detection.existing_project, false);
+});
+
+test('NP-11: --detect after apply returns existing_project=true with completion payload', () => {
+  const sandbox = makeEmptySandbox();
+  const answersPath = _writeAnswers(sandbox, _baseAnswers());
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub });
+
+  const cap = _captureStdout();
+  subcmd.run(['--detect'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.detection.existing_project, true);
+  assert.ok(payload.detection.completion);
+  assert.ok(['complete', 'incomplete'].includes(payload.detection.completion.status));
+});
+
+test('NP-12: run([]) interview payload embeds detection block', () => {
+  const sandbox = makeEmptySandbox();
+  const cap = _captureStdout();
+  subcmd.run([], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.ok(payload.detection);
+  assert.equal(payload.detection.existing_project, false);
+});

package/docs/adr/0002-zero-runtime-dependencies.md

@@ -4,6 +4,7 @@
 * Date: 2026-04-14
 * Supersedes: None
 * **Amendment:** [ADR-0006](0006-yaml-dependency-amendment.md) permits `yaml@^2.8` as a narrowly-scoped runtime dependency (2026-04-15).
+* **Amendment:** [ADR-0014](0014-vector-memory-layer.md) permits `@huggingface/transformers` and `usearch` under `optionalDependencies` for the opt-in Vector-Memory layer (2026-05-08).
 
 ## Context and Problem Statement
 
@@ -45,7 +46,7 @@ Chosen: **"Zero runtime dependencies"**, because it is the only option that rein
 * Good, because the install-payload tree (see [ADR-0005](0005-three-orthogonal-file-trees.md)) contains only `.cjs` files and markdown — no `node_modules/` subtree ever appears there.
 * Bad, because we reimplement small utilities — YAML frontmatter via hand-rolled parser (`lib/frontmatter.cjs`), readline prompts instead of `inquirer`/`@clack/prompts`, raw ANSI escape constants instead of `chalk`. This is an accepted cost documented at length in CLAUDE.md §"Alternatives Considered".
 * Neutral, because `devDependencies` are permitted and do not ship to users — we can still adopt `c8` for coverage, `esbuild` for optional hook bundling, or `node:test` (builtin) for the test runner.
-* Neutral, because `optionalDependencies` for native prebuilt binaries is ALSO rejected by this ADR — see Rust N-API option below — so no accidental backdoor.
+* Neutral, because `optionalDependencies` for native prebuilt binaries is rejected as a general escape hatch by this ADR — see Rust N-API option below — so no accidental backdoor. The narrow exemption permitted by [ADR-0014](0014-vector-memory-layer.md) is opt-in (config-gated, `memory.enabled=true`), lazy-loaded, and only resolves at install time when explicitly requested via `npm install --include=optional`.
 
 ## Pros and Cons of the Options
 

package/docs/adr/0014-vector-memory-layer.md

@@ -36,11 +36,11 @@ The layer is **opt-in** — disabled by default; enabled via `memory.enabled = t
 * **A — No vector memory.** Status quo. Reject: BM25-only Pre-flight has measurable false-negative rate on rephrased tickets; cache-hit ceiling is artificially low.
 * **B — External vector DB (AgentDB / Weaviate / Pinecone).** Reject: violates ADR-0001 (daemon shape) and ADR-0002 (heavy network dep). Inappropriate for a CLI shipping into arbitrary third-party projects.
 * **C — Pure-JS HNSW implementation, no native code, no WASM.** Reject: 200–300 LoC of subtle index code is a maintenance burden disproportionate to the benefit; performance ceiling at O(10K) records is fragile.
-* **D — `usearch` WASM + `@xenova/transformers` for local embedding, lazy-loaded as opt-in deps.** Chosen.
+* **D — `usearch` + `@huggingface/transformers` for local embedding, lazy-loaded as opt-in deps.** Chosen.
 
 ## Decision Outcome
 
-Chosen: **Option D — local-first vector memory with `usearch` WASM and `@xenova/transformers`, lazy-loaded behind a config gate**, because it preserves ADR-0001's no-daemon stance, integrates with the existing `lib/learnings.cjs` Pre-flight without weakening ADR-0011's `[CACHED]` provenance semantics, and leaves a clean seam for future remote providers.
+Chosen: **Option D — local-first vector memory with `usearch` and `@huggingface/transformers`, lazy-loaded behind a config gate**, because it preserves ADR-0001's no-daemon stance, integrates with the existing `lib/learnings.cjs` Pre-flight without weakening ADR-0011's `[CACHED]` provenance semantics, and leaves a clean seam for future remote providers.
 
 ### Layout
 
@@ -103,18 +103,19 @@ Where `Hit = { id, score, record }`. Provider selection happens once at module i
 
 ### Embedding Provider — Local Default
 
-`@xenova/transformers` running `Xenova/bge-small-en-v1.5` (or `Xenova/bge-multilingual-base` when project locale ≠ English):
+`@huggingface/transformers` (the successor to `@xenova/transformers`, maintained by the original author at Hugging Face) running `Xenova/bge-small-en-v1.5` (or `Xenova/bge-multilingual-base` when project locale ≠ English):
 
 * **Model size:** ~70 MB downloaded on first run; cached under `~/.cache/nubos-pilot/models/`.
 * **Vector dim:** 384 (bge-small) or 768 (bge-multilingual).
 * **Provider interface:** `provider.embed(texts: string[]) → Promise<Float32Array[]>`.
 * **First-run UX:** `np:memory index` prints a one-time progress indicator while the model downloads. Subsequent runs load the cached model.
+* **CJS-compatible:** v4 ships dual CJS+ESM (`main: ./dist/transformers.node.cjs`), so `lib/memory-provider-local.cjs` keeps using `require()`.
 
-### Index Engine — `usearch` WASM
+### Index Engine — `usearch`
 
-`usearch` (WASM build) provides HNSW with cosine similarity:
+`usearch` provides HNSW with cosine similarity:
 
-* **Why WASM:** ADR-0002 admits no native compile on the consumer machine. WASM ships precompiled in the package; no `node-gyp`, no Python, no build chain.
+* **Why prebuilt binaries, not WASM:** Both `@huggingface/transformers` (via `onnxruntime-node`) and `usearch` ship platform-specific prebuilt binaries via `node-gyp-build` / `@img/sharp-*`-style platform packages. No `node-gyp` invocation, no Python, no build chain on the consumer machine — same UX as WASM, faster runtime. The `prebuild-install` package (deprecated) is not in the dependency tree of these pinned versions.
 * **Capacity:** O(100K) records mühelos. nubos-pilot's per-project memory expectation is O(1K–10K) records over the project lifetime.
 * **Persistence:** `index.usearch` written via `atomicWriteFileSync`; corruption recovery via `np:memory rebuild` from `records.jsonl`.
 
@@ -122,8 +123,8 @@ Where `Hit = { id, score, record }`. Provider selection happens once at module i
 
 This ADR introduces **two new runtime dependencies** in `package.json`:
 
-* `usearch` (~1 MB, WASM, no native build)
-* `@xenova/transformers` (~5 MB package; ~70 MB model downloaded on first use; no native build)
+* `usearch@^2.25` (prebuilt platform binaries via `node-gyp-build`, no native compile on install)
+* `@huggingface/transformers@^4` (~5 MB package; ~70 MB model downloaded on first use; prebuilt `onnxruntime-node` binaries, no native compile on install)
 
 Both are **lazy-loaded** — the `require()` lives inside `lib/memory.cjs` factory functions and is reached only when `memory.enabled=true` AND a memory operation is invoked. The package.json declares them under `optionalDependencies`, so a Free-tier install with `memory.enabled=false` never resolves them at install time either.
 
@@ -162,7 +163,7 @@ The local-default provider keeps everything on the consumer machine — no data
 * **Config schema:** `.nubos-pilot/config.json::memory = { enabled: false, provider: "local", alpha: 0.6, model: "Xenova/bge-small-en-v1.5" }`.
 * **Related ADRs:**
   * [ADR-0001](0001-no-daemon-invariant.md) — index is a file, not a process.
-  * [ADR-0002](0002-zero-runtime-dependencies.md) — amended to admit `usearch` + `@xenova/transformers` under `optionalDependencies`.
+  * [ADR-0002](0002-zero-runtime-dependencies.md) — amended to admit `usearch` + `@huggingface/transformers` under `optionalDependencies`.
   * [ADR-0005](0005-three-orthogonal-file-trees.md) — `.nubos-pilot/memory/` is a strict Project-State sub-tree.
   * [ADR-0006](0006-yaml-dependency-amendment.md) — same shape of amendment, different scope.
   * [ADR-0010](0010-nubosloop.md) — Pre-flight integration point.