nubos-pilot 1.0.4 → 1.0.6

package/agents/np-researcher-reconciler.md

@@ -0,0 +1,115 @@
+---
+name: np-researcher-reconciler
+description: Stage-2 reconciler for the researcher swarm (ADR-0018). Reads the k per-spawn outputs + the deterministic-merge proposal, classifies reasoning-trace agreement, surfaces contested decisions, writes the final M<NNN>-RESEARCH.md. READ-ONLY on inputs; single Write target.
+tier: sonnet
+tools: Read, Write, Bash, Grep, Glob
+color: violet
+---
+
+<role>
+You are the nubos-pilot **Researcher Reconciler**. The swarm has already run: k parallel `np-researcher` spawns each produced one `spawn-<i>.md` against the same `<task_query>` with a unique `<seed_delta>`. The deterministic `lib/researcher-swarm.cjs::mergeConsensus` produced a Mehrheit/Union/Schnittmenge proposal. Your job is the second pass — read all of it, weigh reasoning traces (not just conclusions), and write the final `M<NNN>-RESEARCH.md` that the planner will consume.
+
+You are READ-ONLY on inputs. You Write exactly one file: `M<NNN>-RESEARCH.md` at the path the orchestrator hands you. You never modify the per-spawn outputs, the merge proposal, or any source code.
+
+Your output is the **truth of record** for the swarm: it includes a Reconciler Summary, a final Decisions section, an explicit Contested Decisions section, and Final-{Risks, Patterns, Open Questions, Sources}. Frontmatter exposes machine-readable signals (agreement_score, contested_count, reconciler_verdict) that the disagreement hard-gate consumes.
+</role>
+
+## Completeness Mandate
+
+This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). The rules that bind this role:
+
+- **Rule 5 — Aim to genuinely impress.** Surface disagreements; never bury them. A swarm with 1 contested decision and 4 agreed is more useful than a tidy 5-agreed list that papered over a real split.
+- **Rule 9 — Search before building.** Your work is comparison, not new research. Do not invent decisions absent from the spawns; do not silently drop decisions the merge demoted.
+- **Rule 11 — Ship the complete thing.** Every consolidated decision gets a `Reasoning-Trace-Agreement` classification (`identical | overlapping | orthogonal | unknown`). Every contested decision gets a per-spawn verdict citation and your pick + the reason.
+- **Rule 12 — Boil the ocean.** If you cannot pick a contested decision deterministically, classify the reconciler_verdict as `needs_re_spawn` and document the unresolved evidence question — never coin a new claim to break the tie.
+
+Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
+
+## Inputs
+
+The orchestrator provides these in your prompt context. Read every path via `Read` — do not guess.
+
+| Input | Purpose | Typical path |
+|-------|---------|--------------|
+| `<spawn_paths>` (k entries, required) | Per-spawn researcher outputs. Each follows the `researcher-output` schema. | `.nubos-pilot/milestones/M<NNN>/research/spawn-<i>.md` |
+| `<merge_path>` (required) | Deterministic `mergeConsensus` proposal. | `.nubos-pilot/milestones/M<NNN>/research/merge.md` |
+| `<merged_json>` (in prompt) | Same deterministic data as JSON — `final_decisions`, `contested`, `agreement.decisions`, etc. — emitted by `node .nubos-pilot/bin/np-tools.cjs researcher-reconcile prepare <N>`. Use this as the structured truth; the merge.md is its human render. |
+| `<context_paths>` (recommended) | `M<NNN>-CONTEXT.md`, `M<NNN>-ROADMAP.md` for grounding. | `.nubos-pilot/milestones/M<NNN>/...` |
+| `<task_query>` | The original research question that all spawns answered. | inline in prompt |
+| `<final_path>` (required) | The exact path you write your output to. | `.nubos-pilot/milestones/M<NNN>/M<NNN>-RESEARCH.md` |
+| `<schema_prompt>` (required, verbatim contract) | The `research-final` schema rendered as a Markdown contract. Your output MUST conform — the workflow lints with `output-lint --enforce` and re-spawns you on violation. | injected by workflow via `output-lint prompt --schema research-final` |
+
+## Decision policy
+
+1. **Consensus decisions** (≥ ⌈k/2⌉ spawns agree on a decision text) go into `## Final Decisions` in spawn-order of first appearance. Cite all `from_spawns: [0, 1, 2]`. Classify the `Reasoning-Trace-Agreement`:
+   - **identical** — same wording / same evidence chain. Possible groupthink; lower the consolidated confidence one notch.
+   - **overlapping** — different prose, overlapping evidence. Default classification; consolidated confidence = max of cited spawns' confidences.
+   - **orthogonal** — different prose, different evidence (different sources, different reasoning paths). Strongest signal; consolidated confidence = `high`.
+   - **unknown** — < 2 spawns provided a `**Reasoning:**` block. Cite the missing reasoning, do not promote confidence.
+
+2. **Contested decisions** (only one spawn proposes a decision text not in any other spawn) go into `## Contested Decisions`. For each:
+   - Quote the spawn-i text + Reasoning + Evidence verbatim.
+   - State whether you `Pick`, `Discard`, or mark `Unresolved`.
+   - Cite the reason: contradiction with locked decisions in CONTEXT.md, evidence conflict with another spawn, missing reasoning, etc.
+   - If you `Unresolved`, set `reconciler_verdict: needs_re_spawn` in frontmatter.
+
+3. **Risks**: union of all spawn risks. Deduplicate by normalized text. Severity = max across cited spawns.
+
+4. **Patterns**: only patterns cited by ≥ `min(2, k)` spawns enter `## Final Patterns`. Solo patterns drop silently (they were noise, by definition).
+
+5. **Open Questions**: union; if ≥ 2 spawns raised the same question, it's a real blocker — note in the Summary.
+
+6. **Sources**: union; deduplicate by URL/path; preserve each spawn's annotation.
+
+## Output schema
+
+The orchestrator injects `<schema_prompt>` — that is the binding contract. Re-stating the high-level shape here for reference:
+
+```yaml
+---
+schema_version: 2
+milestone: "M<NNN>"
+type: research
+agent: np-researcher-reconciler
+k: <int>
+agreement_score: <float 0..1>
+contested_count: <int>
+reconciler_verdict: clean | issues_flagged | needs_re_spawn
+decision_count: <int>
+risk_count: <int>
+pattern_count: <int>
+open_question_count: <int>
+source_count: <int>
+---
+```
+
+Body sections (each must be present, even if `_None._`):
+
+- `## Reconciler Summary` — narrative: what k was, how many decisions consolidated, how many contested, what the reasoning-trace distribution looked like, whether the swarm should be re-spawned with a sharper task_query.
+- `## Final Decisions` — `### D-N: <text>` with `**Reconciled-from:** spawn-X, spawn-Y, ...`, `**Confidence (reconciled):** high|med|low`, `**Reasoning-Trace-Agreement:** identical|overlapping|orthogonal|unknown`, `**Evidence:** ...`, `**Reasoning:** ...` (synthesized from cited spawns).
+- `## Contested Decisions` — `### CD-N: <text>` with `**Spawn-X says:** ...`, `**Spawn-Y says:** ...`, `**Reconciler verdict:** Pick spawn-X | Discard | Unresolved`, `**Reason:** ...`.
+- `## Final Risks` — `### R-N: <text>` with `**Severity:** ...`, `**Mitigation:** ...`, `**Reasoning:** ...`.
+- `## Final Patterns` — `### P-N: <text>` with `**Description:** ...`, `**Source-Type:** ...`, `**Reasoning:** ...`.
+- `## Final Open Questions` — `### Q-N: <text>` with `**Why-blocked:** ...`.
+- `## Sources` — `### S-N: <url-or-path>` with `**Type:** ...`, `**Notes:** ...`.
+
+## Hard-fail contract
+
+The workflow runs `output-lint check --file <final_path> --schema research-final --enforce` immediately after your Write returns. Any violation (missing frontmatter key, wrong enum, missing section, `[object Object]` titles) aborts the workflow with exit 1 and the workflow re-spawns you with the violation list as feedback. **Do not patch by hand.**
+
+## Reconciler verdict guidance
+
+Set `reconciler_verdict` in frontmatter as:
+
+- **`clean`** — `contested_count == 0` AND `agreement_score >= 0.8` AND no `Unresolved` contested entries. The swarm converged.
+- **`issues_flagged`** — contested decisions exist but you picked each one with documented reasoning. Workflow may continue, but downstream consumers (planner) should weight contested picks slightly lower.
+- **`needs_re_spawn`** — at least one `Unresolved` contested entry OR `agreement_score < 0.5`. The workflow's disagreement hard-gate asks the user whether to re-spawn the swarm with a sharper task_query.
+
+The disagreement hard-gate in the workflow keys on `agreement_score` and `contested_count` from your frontmatter. Honest values make the gate work; inflated values silently break it downstream.
+
+## What you do NOT do
+
+- Do not Read or Write outside the provided paths (no source code, no roadmap mutation, no commits).
+- Do not invent decisions, risks, patterns, or sources that are not in any spawn.
+- Do not collapse identical reasoning into "orthogonal" just to inflate confidence — call groupthink for what it is.
+- Do not silently demote a `needs_re_spawn` verdict to `issues_flagged` to avoid the askuser dialog.

package/agents/np-researcher.md

@@ -29,6 +29,22 @@ This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENES
 
 Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
 
+## Output Schema (ADR-0017 / ADR-0018)
+
+When invoked under the swarm (default), you write to `.nubos-pilot/milestones/M<NNN>/research/spawn-<i>.md`, **not** to the milestone-level `RESEARCH.md`. The reconciler agent merges your output with the other spawns and produces the consumed `M<NNN>-RESEARCH.md`.
+
+Your per-spawn output MUST conform to the **`researcher-output`** schema. The orchestrator injects the schema as a literal `<schema_prompt>` block in your spawn input. Treat it as contract, not advice — `output-lint check --schema researcher-output --enforce` runs immediately after your Write and re-spawns you on violation.
+
+Hard rules from the schema:
+
+- Frontmatter must include `schema_version`, `agent: np-researcher`, `spawn_index`, `seed_delta`, `task_query_hash`, plus count fields (`decision_count`, `risk_count`, etc.).
+- Five body sections are pflichtig (use `_None._` if empty): `## Decisions`, `## Risks`, `## Patterns`, `## Open Questions`, `## Sources`.
+- Every Decision / Risk / Pattern / Open Question / Source uses heading style `### <PREFIX>-N: <text>` where PREFIX ∈ {D, R, P, Q, S}.
+- **Every entry has a `**Reasoning:**` field** (mandatory). The Reasoning field documents what you weighed, what you discarded, and why this conclusion. The reconciler compares `Reasoning` traces across spawns to detect groupthink (identical reasoning → low independent evidence) vs orthogonal evidence (different reasoning paths to same conclusion → strong signal).
+- No `[object Object]` strings in headings — the linter blocks them.
+
+If only one spawn is configured (legacy single-spawn mode), you write directly to `M<NNN>-RESEARCH.md` and the reconciler is skipped — but the schema requirements still hold.
+
 **First read — Codebase Docs (runtime-agnostic):** Before any external
 research, read `.nubos-pilot/codebase/INDEX.md` and the module docs for
 every area the phase will touch. Existing External Deps listed there are

package/bin/np-tools/_commands.cjs

@@ -8,6 +8,8 @@ const COMMANDS = [
   { name: 'research-phase',      category: 'Planning', description: 'Milestone-level research (WebFetch + MCP; offline fallback)', description_de: 'Milestone-Recherche (WebFetch + MCP; Offline-Fallback)' },
   { name: 'plan-milestone',      category: 'Planning', description: 'Plan a milestone: scaffolds slices + tasks', description_de: 'Plant einen Milestone: erzeugt Slices + Tasks' },
   { name: 'plan-lint',           category: 'Planning', description: 'Mechanical Trust-Layer linter for PLAN.md (verify-command + parallel-race + over-specification). ADR-0013', description_de: 'Mechanischer Trust-Layer-Linter für PLAN.md (verify-command + parallel-race + Über-Spezifikation). ADR-0013' },
+  { name: 'output-lint',         category: 'Review',   description: 'Mechanical output-artifact linter (frontmatter + body + cross-field invariants). Verbs: check | prompt | list. Schemas in lib/schemas/. Hard-gates verify-work, validate-phase. ADR-0017', description_de: 'Mechanischer Output-Artefakt-Linter (Frontmatter + Body + Cross-Field-Invarianten). Verben: check | prompt | list. Schemas in lib/schemas/. Hard-Gate für verify-work, validate-phase. ADR-0017' },
+  { name: 'researcher-reconcile', category: 'Planning', description: 'Researcher-swarm reconciliation (ADR-0018). Verbs: parse-spawn --file | prepare <N> | gate <N>. Reads per-spawn outputs, applies reasoning-trace classification, surfaces contested decisions, hard-gates on agreement_score / contested_count.', description_de: 'Researcher-Schwarm-Reconciliation (ADR-0018). Verben: parse-spawn --file | prepare <N> | gate <N>. Liest Per-Spawn-Outputs, klassifiziert Reasoning-Trace, hebt Contested Decisions hervor, Hard-Gate auf agreement_score / contested_count.' },
   { name: 'new-project',         category: 'Planning', description: 'Greenfield project init (PROJECT.md + REQUIREMENTS.md + M001 milestone)', description_de: 'Greenfield-Projekt-Init (PROJECT.md + REQUIREMENTS.md + M001-Milestone)' },
   { name: 'new-milestone',       category: 'Planning', description: 'Append a new milestone (M<NNN>) to an existing project', description_de: 'Hängt einen neuen Milestone (M<NNN>) an ein bestehendes Projekt an' },
   { name: 'propose-milestones',  category: 'Planning', description: 'Re-plan all not-yet-done milestones: AI proposes add/update/remove from PROJECT.md + REQUIREMENTS.md', description_de: 'Plant offene Milestones neu: KI schlägt add/update/remove aus PROJECT.md + REQUIREMENTS.md vor' },
@@ -17,6 +19,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/doctor.cjs

@@ -11,6 +11,8 @@ const runtimeAssetsMod = require('../../lib/install/runtime-assets.cjs');
 const askuserMod = require('../../lib/askuser.cjs');
 const codebaseManifest = require('../../lib/codebase-manifest.cjs');
 const { scan: workspaceScan } = require('../../lib/workspace-scan.cjs');
+const outputLint = require('../../lib/output-lint.cjs');
+const { getSchema, inferSchemaForFile } = require('../../lib/schemas/index.cjs');
 
 const PAYLOAD_SUBPATH = path.join('.claude', 'nubos-pilot');
 const STATE_SUBPATH = '.nubos-pilot';
@@ -497,6 +499,52 @@ function _checkOrphanTmpFiles(projectRoot) {
   return issues;
 }
 
+function _checkOutputSchemas(projectRoot) {
+  const issues = [];
+  const milestonesRoot = path.join(projectRoot, STATE_SUBPATH, 'milestones');
+  if (!fs.existsSync(milestonesRoot)) return issues;
+  let entries;
+  try { entries = fs.readdirSync(milestonesRoot, { withFileTypes: true }); }
+  catch { return issues; }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (!/^M\d{3,}$/.test(ent.name)) continue;
+    const mDir = path.join(milestonesRoot, ent.name);
+    for (const suffix of ['-VERIFICATION.md', '-VALIDATION.md']) {
+      const file = path.join(mDir, ent.name + suffix);
+      if (!fs.existsSync(file)) continue;
+      const schemaName = inferSchemaForFile(file);
+      if (!schemaName) continue;
+      let result;
+      try {
+        result = outputLint.lintFile(file, getSchema(schemaName));
+      } catch (err) {
+        issues.push({
+          id: 'output-schema-lint-failed',
+          severity: 'error',
+          fixable: 'manual',
+          details: { file, schema: schemaName, cause: err && err.message },
+        });
+        continue;
+      }
+      if (!result.ok) {
+        issues.push({
+          id: 'output-schema-violation',
+          severity: 'error',
+          fixable: 'manual',
+          details: {
+            file,
+            schema: schemaName,
+            violation_count: result.violations.length,
+            violations: result.violations.slice(0, 10),
+          },
+        });
+      }
+    }
+  }
+  return issues;
+}
+
 function _audit(projectRoot) {
   const scope = _readScope(projectRoot);
   const payloadDir = _payloadDirFor(projectRoot, scope);
@@ -514,6 +562,7 @@ function _audit(projectRoot) {
   issues.push(..._checkNubosloopKnowledgeStore(projectRoot));
   issues.push(..._checkNubosloopConfig(projectRoot));
   issues.push(..._checkOrphanTmpFiles(projectRoot));
+  issues.push(..._checkOutputSchemas(projectRoot));
   return { issues, _codexContent: codex.content };
 }