nubos-pilot 1.0.3 → 1.0.5

package/agents/np-build-fixer.md

@@ -40,6 +40,16 @@ The orchestrator provides these in your prompt context. Read every path it hands
 
 ## Workflow
 
+0. **Read inbox first (ADR-0015).** You are always running on round ≥ 2; the prior critic may have addressed clarifying questions to the executor that you must answer:
+   ```bash
+   node np-tools.cjs messages-inbox --agent np-executor --task <task-id>
+   ```
+   For each `kind=request` with `expects_reply=true`, your patch should resolve the question and you must send a response (otherwise commit-phase is blocked by Layer-B):
+   ```bash
+   node np-tools.cjs messages-send --from np-executor --to <orig-from> \
+     --phase <task-id> --round <round> --kind response \
+     --subject <same-subject> --body "<resolution>" --in-reply-to <request-id>
+   ```
 1. **Classify** the failure from the captured output:
    - `compile` (syntax error, missing import, type error)
    - `lint` (style/quality rule violation)

package/agents/np-critic.md

@@ -145,6 +145,26 @@ If `<report_path>` is missing from your prompt or you cannot write the file, do
 - Inline the full findings JSON in the final message. The Verdict-Only Contract exists because that response replays into the orchestrator's context every round and is the dominant token sink — defeating it silently re-introduces the cost ADR-0010 §L5 was designed to remove.
 </scope_guardrail>
 
+## Inter-Agent Messaging (ADR-0015)
+
+When a finding requires per-finding clarification from the executor that does NOT belong in the findings JSON itself (e.g. *"did you intend to delete `FoobarService`, or was that a side-effect?"*), you MAY emit an addressed `request` message via:
+
+```bash
+node np-tools.cjs messages-send \
+  --from np-critic --to np-executor \
+  --phase <task-id> --round <current-round> \
+  --kind request --subject <finding-category> \
+  --body "<question>" --expects-reply
+```
+
+Rules:
+- Messages are **dialogue**, not findings. The findings JSON written to `<report_path>` is canonical for routing. Messages are for clarifications that bounce back to executor / build-fixer.
+- Each `request` you send with `--expects-reply` blocks the next commit-phase via Layer-B (`pendingReplies(taskId) === 0` precondition). Use sparingly.
+- `request` subjects should match a finding-category (`style`, `dead-code`, `missing-test`, `weak-assertion`, `unmet-criterion`, `scope-creep`).
+- Inspect prior dialogue with `messages-thread <msg-id>` if a finding looks like it bounced last round.
+
+If you have nothing to ask, send no message. Default = no dialogue.
+
 ## Stop Conditions
 
 Hard-stop (`Write` the full findings JSON to `<report_path>` if possible, then emit the envelope; do NOT attempt recovery):

package/agents/np-executor.md

@@ -96,6 +96,19 @@ into the `task(…)` commit. If `workflow.commit_docs=true`, the
 2. **Read codebase docs** — `.nubos-pilot/codebase/INDEX.md` plus every
    module doc owning a path in `files_modified`. Pre-edit step of the
    Codebase Docs Protocol.
+2a. **Read inbox (Round 2+ only)** — when round ≥ 2, check for addressed
+    requests from prior critics that need a response before commit:
+    ```bash
+    node np-tools.cjs messages-inbox --agent np-executor --task <task-id>
+    ```
+    For each `kind=request` with `expects_reply=true`, your edit should resolve it.
+    After the edit, send a response and let it auto-archive the request:
+    ```bash
+    node np-tools.cjs messages-send --from np-executor --to <orig-from> \
+      --phase <task-id> --round <round> --kind response \
+      --subject <same-subject> --body "<resolution>" --in-reply-to <request-id>
+    ```
+    Unanswered `expects_reply=true` requests block commit-phase via Layer-B (ADR-0015).
 3. **Transition to in-progress:** `node np-tools.cjs checkpoint transition <task-id> in-progress`.
 4. **Edit files** — only the paths listed in the task's `files_modified` frontmatter. Use `Read` + `Edit` / `Write`. No scope expansion.
 5. **Transition to verifying:** `node np-tools.cjs checkpoint transition <task-id> verifying`.

package/agents/np-planner.md

@@ -99,6 +99,22 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 </role>
 
 <reality_check_protocol>
+## Vector-Memory Recall (ADR-0014)
+
+Before scaffolding tasks, query the local vector memory for prior-phase decisions matching the current milestone. This is *advisory*: the locked-decisions file (`M<NNN>-CONTEXT.md` / `RESEARCH.md`) is canonical, memory-hits inform context-injection only.
+
+```bash
+node np-tools.cjs memory-query --text "<milestone-summary>" --k 5 --type research
+node np-tools.cjs memory-query --text "<milestone-summary>" --k 5 --type learning
+```
+
+If `memory.enabled=false` you'll get `memory-disabled` — silently skip.
+
+For `[VERIFIED]` / `[CITED]` hits whose subject overlaps the current milestone:
+- Reference them in the slice plan's `<context>` block as prior-art.
+- If a prior decision conflicts with a freshly-locked decision in `M<NNN>-CONTEXT.md`, the locked decision wins. Memory is never authoritative against locked-decisions.
+- Do NOT auto-promote `[ASSUMED]` hits; they remain advisory.
+
 ## CRITICAL: Reality-Check Before Planning (MANDATORY)
 
 Plans fail at execute-time when they encode assumptions the planner never verified against the actual repo. To stop the replan-after-execute loop, BEFORE writing any `S<NNN>-PLAN.md` you MUST empirically verify every load-bearing assumption and record the evidence inside the slice plan.

package/agents/np-researcher.md

@@ -36,6 +36,23 @@ anchor points for your research — do not propose replacements without
 explicit justification. If `INDEX.md` is absent, report and stop —
 `np:scan-codebase` must run first.
 
+## Vector-Memory Pre-recall (ADR-0014)
+
+**Before issuing external research**, query the local vector memory for prior decisions matching the current ticket. The hybrid pre-flight (`lib/knowledge-adapter.cjs`) already runs at swarm-entry; this step is the *agent-side* recall for context-injection into your `RESEARCH.md`.
+
+```bash
+node np-tools.cjs memory-query --text "<ticket-summary>" --k 5 --type research
+node np-tools.cjs memory-query --text "<ticket-summary>" --k 3 --type learning
+```
+
+If `memory.enabled=false` you'll get `memory-disabled` — silently skip; this section is opt-in and additive.
+
+For each hit, surface the underlying decision in your `RESEARCH.md` with the original `provenance` preserved:
+- `[VERIFIED]` / `[CITED]` hits become `[CACHED:VERIFIED]` / `[CACHED:CITED]` in your output — the merged `<consensus_meta>` block carries `cache_hit: true`.
+- `[ASSUMED]` hits stay `[CACHED:ASSUMED]` — flagged for plan-checker scrutiny, never auto-promoted.
+
+A high-confidence cache match should *replace* external research for that decision, not duplicate it. Save the swarm tokens.
+
 ## Handoff Protocol
 
 Agent handoffs are persistent notes between phase invocations. Before researching, check handoffs addressed to `np-researcher`:

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' },
@@ -59,6 +61,15 @@ const COMMANDS = [
   { name: 'handoff-read',      category: 'Capture',  description: 'Read a single handoff by id (returns frontmatter + body as JSON)', description_de: 'Liest einzelnen Handoff per ID (gibt Frontmatter + Body als JSON zurück)' },
   { name: 'handoff-list',      category: 'Capture',  description: 'List handoffs (JSON array); filter with --for AGENT, --milestone M<NNN>, --status STATUS, --global', description_de: 'Listet Handoffs (JSON-Array); filtert mit --for AGENT, --milestone M<NNN>, --status STATUS, --global' },
   { name: 'handoff-status',    category: 'Capture',  description: 'Update a handoff status (open|read|acted|archived)', description_de: 'Aktualisiert Handoff-Status (open|read|acted|archived)' },
+  { name: 'messages-send',     category: 'Capture',  description: 'Send addressed inter-agent message (request|response|notify) to .nubos-pilot/messages/inbox/<to>/. ADR-0015', description_de: 'Sendet adressierte Inter-Agent-Nachricht (request|response|notify) an .nubos-pilot/messages/inbox/<to>/. ADR-0015' },
+  { name: 'messages-inbox',    category: 'Capture',  description: 'List ungelesen messages addressed to an agent (filterable by --kind, --since, --task)', description_de: 'Listet ungelesen Messages für einen Agent (filterbar via --kind, --since, --task)' },
+  { name: 'messages-archive',  category: 'Capture',  description: 'Move an inbox message to archive/; refuses request+expects_reply without prior response', description_de: 'Verschiebt Inbox-Message nach archive/; weigert sich bei request+expects_reply ohne Reply' },
+  { name: 'messages-thread',   category: 'Capture',  description: 'Print full reply-chain for a message id (causal order)', description_de: 'Gibt vollständige Reply-Chain für eine Message-ID aus (kausale Reihenfolge)' },
+  { name: 'memory-index',      category: 'Capture',  description: 'Bulk-index records into vector memory (--records JSON or --records-file JSONL). Opt-in via memory.enabled=true. ADR-0014', description_de: 'Bulk-Index für Records ins Vector-Memory (--records JSON oder --records-file JSONL). Opt-in via memory.enabled=true. ADR-0014' },
+  { name: 'memory-query',      category: 'Utility',  description: 'Query vector memory by text; returns top-k JSON hits with score + record. Filter by --type, --phase, --tags', description_de: 'Fragt Vector-Memory by Text; liefert Top-k JSON-Hits mit Score + Record. Filter via --type, --phase, --tags' },
+  { name: 'memory-add',        category: 'Capture',  description: 'Add a single record to vector memory (--type, --title, --body, optional --tags / --provenance / --phase / --id)', description_de: 'Fügt einzelnen Record in Vector-Memory ein (--type, --title, --body, optional --tags / --provenance / --phase / --id)' },
+  { name: 'memory-rebuild',    category: 'Utility',  description: 'Force full re-embed from records.jsonl; required after embedding-model change. ADR-0014', description_de: 'Erzwingt komplettes Re-Embed aus records.jsonl; erforderlich nach Embedding-Model-Wechsel. ADR-0014' },
+  { name: 'memory-stats',      category: 'Utility',  description: 'Print vector-memory stats (count, dim, model, schema_version, created_at)', description_de: 'Gibt Vector-Memory-Stats aus (count, dim, model, schema_version, created_at)' },
   { name: 'worktree-create',   category: 'Execution', description: 'Create an isolated git worktree for a slice (branch np/<mid>-<sid> off current HEAD) under .nubos-pilot/worktrees/', description_de: 'Erstellt isoliertes Git-Worktree für eine Slice (Branch np/<mid>-<sid> vom aktuellen HEAD) unter .nubos-pilot/worktrees/' },
   { name: 'worktree-remove',   category: 'Execution', description: 'Remove a slice worktree + delete its branch (--force / --keep-branch)', description_de: 'Entfernt Slice-Worktree + löscht zugehörigen Branch (--force / --keep-branch)' },
   { name: 'worktree-list',     category: 'Execution', description: 'List all nubos-pilot-managed slice worktrees (np/<mid>-<sid> only) as JSON', description_de: 'Listet alle nubos-pilot-verwalteten Slice-Worktrees (nur np/<mid>-<sid>) als JSON' },

package/bin/np-tools/_memory-resolve.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { readConfigPath } = require('../../lib/config.cjs');
+const { createMemory } = require('../../lib/memory.cjs');
+
+function resolveMemory(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+
+  if (o.provider && o.indexEngine) {
+    return createMemory({
+      provider: o.provider,
+      indexEngine: o.indexEngine,
+      cwd,
+      alpha: o.alpha,
+    });
+  }
+
+  const enabled = readConfigPath(cwd, 'memory.enabled', false);
+  if (!enabled) {
+    throw new NubosPilotError(
+      'memory-disabled',
+      'memory layer is disabled. Set "memory": { "enabled": true } in .nubos-pilot/config.json (ADR-0014).',
+      {},
+    );
+  }
+
+  const model = readConfigPath(cwd, 'memory.model', 'Xenova/bge-small-en-v1.5');
+  const alpha = readConfigPath(cwd, 'memory.alpha', 0.6);
+
+  const { createLocalProvider } = require('../../lib/memory-provider-local.cjs');
+  const { createUsearchIndex } = require('../../lib/memory-index-usearch.cjs');
+
+  const provider = createLocalProvider({ model });
+  const indexEngine = createUsearchIndex({ dim: provider.dim });
+
+  return createMemory({ provider, indexEngine, cwd, alpha });
+}
+
+module.exports = { resolveMemory };

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);
+});