nubos-pilot 1.0.5 → 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' },

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

package/bin/np-tools/execute-milestone.cjs

@@ -18,6 +18,10 @@ const textMode = require('../../lib/text-mode.cjs');
 
 const INLINE_THRESHOLD_BYTES = 16 * 1024;
 
+function _hasVerifyWorkFlag(list) {
+  return Array.isArray(list) && list.some((a) => a === '--verify-work');
+}
+
 function _validateMilestoneArg(raw) {
   if (raw == null || raw === '') {
     throw new NubosPilotError(
@@ -85,7 +89,7 @@ function _sliceTasksSorted(mNum, sNum, cwd) {
   }).filter(Boolean);
 }
 
-function _initPayload(mNum, cwd) {
+function _initPayload(mNum, cwd, opts) {
   let def;
   try {
     def = getPhase(mNum, cwd);
@@ -123,6 +127,8 @@ function _initPayload(mNum, cwd) {
   }
   const tmDetail = textMode.resolveTextModeDetail(cwd);
 
+  const autoVerify = Boolean(opts && opts.auto_verify);
+
   return {
     _workflow: 'execute-milestone',
     milestone: mNum,
@@ -136,6 +142,7 @@ function _initPayload(mNum, cwd) {
     total_tasks: totalTasks,
     slice_count: slices.length,
     executor_tier: 'sonnet',
+    auto_verify: autoVerify,
     text_mode: tmDetail.enabled,
     text_mode_source: tmDetail.source,
     agent_skills: { executor: _safeSkills('np-executor', cwd) },
@@ -279,7 +286,8 @@ function run(args, ctx) {
   switch (verb) {
     case 'init': {
       const mNum = _validateMilestoneArg(list[1]);
-      const payload = _initPayload(mNum, cwd);
+      const autoVerify = _hasVerifyWorkFlag(list.slice(2));
+      const payload = _initPayload(mNum, cwd, { auto_verify: autoVerify });
       _emit(payload, stdout, cwd);
       return payload;
     }

package/bin/np-tools/execute-milestone.test.cjs

@@ -231,6 +231,39 @@ test('EM-9: finalize-milestone iterates every slice and produces one summary per
   assert.ok(fs.existsSync(s2));
 });
 
+test('EM-11: init without --verify-work emits auto_verify=false', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  seedMilestoneDir(sandbox, 1, {});
+  seedSliceDir(sandbox, 1, 1, {});
+  _seedTask(sandbox, 1, 1, 1, ['src/a.ts']);
+  const cap = _capture();
+  const payload = subcmd.run(['init', '1'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(payload.auto_verify, false);
+});
+
+test('EM-12: init with --verify-work emits auto_verify=true', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  seedMilestoneDir(sandbox, 1, {});
+  seedSliceDir(sandbox, 1, 1, {});
+  _seedTask(sandbox, 1, 1, 1, ['src/a.ts']);
+  const cap = _capture();
+  const payload = subcmd.run(['init', '1', '--verify-work'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(payload.auto_verify, true);
+});
+
+test('EM-13: init ignores unknown flags (no --auto-verify alias)', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _roadmap());
+  seedMilestoneDir(sandbox, 1, {});
+  seedSliceDir(sandbox, 1, 1, {});
+  _seedTask(sandbox, 1, 1, 1, ['src/a.ts']);
+  const cap = _capture();
+  const payload = subcmd.run(['init', '1', '--auto-verify'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(payload.auto_verify, false);
+});
+
 test('EM-10: finalize-slice marks tasks without SUMMARY.md but does not fail', () => {
   const sandbox = makeSandbox();
   seedRoadmapYaml(sandbox, _roadmap());

package/bin/np-tools/output-lint.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const outputLint = require('../../lib/output-lint.cjs');
+const { getSchema, listSchemas, inferSchemaForFile } = require('../../lib/schemas/index.cjs');
+
+function _parseArgs(list) {
+  const out = { file: null, schema: null, format: 'json', enforce: false };
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i];
+    if (a === '--file' || a === '-f') out.file = list[++i];
+    else if (a === '--schema' || a === '-s') out.schema = list[++i];
+    else if (a === '--format') out.format = list[++i];
+    else if (a === '--enforce') out.enforce = true;
+    else if (a === '--md') out.format = 'md';
+    else if (a === '--text') out.format = 'text';
+  }
+  return out;
+}
+
+function _renderText(result) {
+  const lines = [];
+  lines.push((result.ok ? 'OK' : 'FAIL') + ' [' + (result.schema_name || '?') + '] ' + (result.path || '<inline>'));
+  if (!result.ok) {
+    for (const v of (result.violations || [])) {
+      lines.push('  - [' + v.code + '] ' + v.path + ': ' + v.message);
+    }
+  }
+  return lines.join('\n');
+}
+
+function _emit(result, format, stdout) {
+  if (format === 'text') {
+    stdout.write(_renderText(result) + '\n');
+    return;
+  }
+  stdout.write(JSON.stringify(result, null, 2));
+}
+
+function _verbCheck(flags, stdout) {
+  if (!flags.file) {
+    throw new NubosPilotError('output-lint-missing-file', 'check requires --file <path>', {});
+  }
+  const schemaName = flags.schema || inferSchemaForFile(flags.file);
+  if (!schemaName) {
+    throw new NubosPilotError(
+      'output-lint-cannot-infer-schema',
+      'cannot infer schema from filename; pass --schema <name>',
+      { file: flags.file, available: listSchemas() },
+    );
+  }
+  const schema = getSchema(schemaName);
+  const result = outputLint.lintFile(flags.file, schema);
+  _emit(result, flags.format, stdout);
+  if (flags.enforce && !result.ok) {
+    return 1;
+  }
+  return 0;
+}
+
+function _verbPrompt(flags, stdout) {
+  if (!flags.schema) {
+    throw new NubosPilotError('output-lint-missing-schema', 'prompt requires --schema <name>', {
+      available: listSchemas(),
+    });
+  }
+  const schema = getSchema(flags.schema);
+  stdout.write(outputLint.schemaPrompt(schema));
+  return 0;
+}
+
+function _verbList(_flags, stdout) {
+  const payload = listSchemas().map((name) => {
+    const s = getSchema(name);
+    return {
+      name,
+      artifact: s.artifact || null,
+      description: s.description || null,
+      required_frontmatter: (s.frontmatter && s.frontmatter.required) || [],
+    };
+  });
+  stdout.write(JSON.stringify(payload, null, 2));
+  return 0;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+  const flags = _parseArgs(list.slice(1));
+
+  switch (verb) {
+    case 'check':
+      return _verbCheck(flags, stdout);
+    case 'prompt':
+    case 'schema-prompt':
+      return _verbPrompt(flags, stdout);
+    case 'list':
+      return _verbList(flags, stdout);
+    default:
+      throw new NubosPilotError(
+        'output-lint-unknown-verb',
+        'output-lint: unknown verb: ' + String(verb),
+        { verb, allowed: ['check', 'prompt', 'list'] },
+      );
+  }
+}
+
+module.exports = { run };

package/bin/np-tools/researcher-reconcile.cjs

@@ -0,0 +1,118 @@
+'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 reconciler = require('../../lib/researcher-reconciler.cjs');
+const layout = require('../../lib/layout.cjs');
+
+const INLINE_THRESHOLD = 16 * 1024;
+
+function _emit(payload, stdout, cwd) {
+  const json = JSON.stringify(payload, null, 2);
+  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD) {
+    stdout.write(json);
+    return;
+  }
+  const tmpDir = path.join(projectStateDir(cwd), '.tmp');
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'researcher-reconcile-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function _validateMilestoneArg(raw) {
+  if (raw == null || !/^\d+$/.test(String(raw))) {
+    throw new NubosPilotError(
+      'researcher-reconcile-invalid-milestone',
+      'milestone must be a positive integer',
+      { value: raw },
+    );
+  }
+  return Number(raw);
+}
+
+function _parseFlags(list) {
+  const out = { min_agreement_score: null, max_contested: null, file: null };
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i];
+    if (a === '--min-agreement-score') out.min_agreement_score = Number(list[++i]);
+    else if (a === '--max-contested') out.max_contested = Number(list[++i]);
+    else if (a === '--file') out.file = list[++i];
+  }
+  return out;
+}
+
+function _verbParseSpawn(args, ctx) {
+  const flags = _parseFlags(args.slice(0));
+  if (!flags.file) {
+    throw new NubosPilotError('researcher-reconcile-missing-file', 'parse-spawn requires --file <path>', {});
+  }
+  return reconciler.parseSpawnOutput(flags.file);
+}
+
+function _verbPrepare(args, ctx) {
+  const cwd = ctx.cwd || process.cwd();
+  const mNum = _validateMilestoneArg(args[0]);
+  const flags = _parseFlags(args.slice(1));
+  const opts = {};
+  if (flags.min_agreement_score != null) opts.min_agreement_score = flags.min_agreement_score;
+  if (flags.max_contested != null) opts.max_contested = flags.max_contested;
+  return reconciler.prepareReconcilerInput(mNum, cwd, opts);
+}
+
+function _verbGate(args, ctx) {
+  const cwd = ctx.cwd || process.cwd();
+  const mNum = _validateMilestoneArg(args[0]);
+  const flags = _parseFlags(args.slice(1));
+  const t = {};
+  if (flags.min_agreement_score != null) t.min_agreement_score = flags.min_agreement_score;
+  if (flags.max_contested != null) t.max_contested = flags.max_contested;
+
+  const finalPath = reconciler.finalResearchPath(mNum, cwd);
+  if (!fs.existsSync(finalPath)) {
+    throw new NubosPilotError(
+      'researcher-reconcile-no-final',
+      'final RESEARCH.md not found at ' + finalPath,
+      { milestone: mNum, path: finalPath },
+    );
+  }
+  const raw = fs.readFileSync(finalPath, 'utf-8');
+  return reconciler.gateFromFinalFrontmatter(raw, t);
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const cwd = context.cwd || process.cwd();
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+
+  let payload;
+  switch (verb) {
+    case 'parse-spawn':
+      payload = _verbParseSpawn(list.slice(1), { cwd });
+      break;
+    case 'prepare':
+    case 'prepare-input':
+      payload = _verbPrepare(list.slice(1), { cwd });
+      break;
+    case 'gate':
+      payload = _verbGate(list.slice(1), { cwd });
+      break;
+    default:
+      throw new NubosPilotError(
+        'researcher-reconcile-unknown-verb',
+        'researcher-reconcile: unknown verb: ' + String(verb),
+        { verb, allowed: ['parse-spawn', 'prepare', 'gate'] },
+      );
+  }
+  _emit(payload, stdout, cwd);
+  return payload;
+}
+
+module.exports = { run };

package/lib/agents.test.cjs

@@ -224,6 +224,7 @@ const NP_AGENTS = [
   { file: 'np-executor', expected_tier: 'sonnet' },
   { file: 'np-verifier', expected_tier: 'sonnet' },
   { file: 'np-researcher', expected_tier: 'sonnet' },
+  { file: 'np-researcher-reconciler', expected_tier: 'sonnet' },
   { file: 'np-codebase-documenter', expected_tier: 'sonnet' },
   { file: 'np-architect', expected_tier: 'sonnet' },
   { file: 'np-build-fixer', expected_tier: 'sonnet' },