nubos-pilot 1.1.0 → 1.1.3

package/README.md

@@ -5,7 +5,7 @@ AI-driven planning and execution tool for code projects. Installs into 14 host C
 - **No daemon.** Every command runs as a short-lived `node` invocation.
 - **Markdown-first.** Workflows and agents are plain `.md` files — the host reads them directly.
 - **Atomic per-task commits.** One `task(M<NNN>-S<NNN>-T<NNNN>): …` commit per unit of work. `/np:undo-task` and `/np:undo` are mechanical reverts.
-- **Multi-runtime.** One source tree, one install payload, four first-class host CLIs.
+- **Multi-runtime.** One source tree, one install payload, fourteen supported host CLIs.
 
 ## Install
 
@@ -95,16 +95,18 @@ task(M001-S001-T0002): wire login handler
 
 ## Agents
 
-Eleven subagents are installed into the host's agent directory:
+Thirteen spawnable subagents are installed into the host's agent directory (alongside three `np-critic-*` audit modules consumed by `np-critic`):
 
 - `np-planner` (opus) — breaks a milestone into slices + tasks
 - `np-plan-checker` (opus) — adversarial goal-backward review before execution
 - `np-architect` (sonnet) — optional ADR-style decisions before planning
 - `np-researcher` (sonnet) — milestone-level stack + pitfalls research
+- `np-researcher-reconciler` (sonnet) — reconciles disagreements across researcher-swarm outputs
 - `np-sc-extractor` (haiku) — derives observable Success Criteria from goal + CONTEXT
 - `np-codebase-documenter` (sonnet) — maintains `.nubos-pilot/codebase/` module docs
 - `np-executor` (sonnet) — one task per spawn, one commit per task
 - `np-build-fixer` (sonnet) — recovery patcher for executor verify failures (manual spawn)
+- `np-critic` (sonnet) — Nubosloop critic; audits executor output across style, tests and acceptance
 - `np-verifier` (sonnet) — post-execution Pass/Fail/Defer per success_criterion
 - `np-nyquist-auditor` (haiku) — requirement test-coverage audit
 - `np-security-reviewer` (sonnet) — OWASP-aligned read-only audit (manual spawn)
@@ -113,7 +115,7 @@ Every spawn runs with an **explicit tier** (`haiku` / `sonnet` / `opus`) resolve
 
 ## Model profile
 
-Five profiles (`frontier`, `quality`, `balanced`, `budget`, `inherit`) map each tier (`haiku` / `sonnet` / `opus`) to a concrete model. Set at install time (`Model-Profile?` prompt) or in `.nubos-pilot/config.json`. Full matrix in `docs/agent-frontmatter-schema.md`.
+Five profiles (`frontier`, `quality`, `balanced`, `budget`, `inherit`) map each tier (`haiku` / `sonnet` / `opus`) to a concrete model. Set at install time (`Model-Profile?` prompt) or in `.nubos-pilot/config.json`.
 
 ## Requirements
 
@@ -131,11 +133,11 @@ node np-tools.cjs help           # JSON: { commands: [ { name, category, descrip
 ## Doctor
 
 ```bash
-npx nubos-pilot doctor           # 6-check integrity scan
+npx nubos-pilot doctor           # 12-check integrity scan
 npx nubos-pilot doctor --fix     # auto-fix what's safely fixable
 ```
 
-Checks: payload manifest integrity, version mismatch, hooks presence, codex-toml sanity, askuser runtime availability, codebase docs freshness, milestone/slice directory layout.
+Checks: payload manifest integrity, version mismatch, hooks presence, codex-toml sanity, askuser runtime availability, codebase docs freshness, milestone/slice directory layout, the three Nubosloop checks (critics present, knowledge store, config), orphan temp files, and output schemas.
 
 ## Development
 

package/agents/np-architect.md

@@ -70,7 +70,7 @@ If the project already documents a module/pattern that fits, extend it instead o
 
 ## Output Contract
 
-**Granularity (ADR-0013).** Architecture decisions are intent-level: which library, which boundary, which protocol. They do NOT prescribe implementation — no schema DDL, no exact framework-generated filenames, no code-style edicts. Those are executor-territory and downstream `np-planner` will refuse plans that bake them in (Plan-side Trust Layer, ADR-0013). If you find yourself describing how a controller method should be structured, stop — that's not architecture.
+**Granularity (ADR-0019).** Architecture decisions are intent-level: which library, which boundary, which protocol. They do NOT prescribe implementation — no schema DDL, no exact framework-generated filenames, no code-style edicts. Those are executor-territory and downstream `np-planner` will refuse plans that bake them in (Plan-side Trust Layer, ADR-0019). If you find yourself describing how a controller method should be structured, stop — that's not architecture.
 
 ```markdown
 # M<NNN> — <milestone name> — Architecture

package/agents/np-build-fixer.md

@@ -58,9 +58,9 @@ The orchestrator provides these in your prompt context. Read every path it hands
    - `infra` (missing tool, network, env var) → STOP and emit `## INFRA BLOCKER` block; do not edit source.
 1a. **MANDATORY knowledge lookup (Rule 9 — non-optional, runs before any Edit).** Pick the failing symbol or error class from Step 1 and run:
     ```bash
-    node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol-or-error-class>" --limit 5
+    node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol-or-error-class>" --task <task-id> --limit 5
     ```
-    If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Skipping this step stamps `rule-9-violation` in the Layer-C audit log and the loop routes back to the researcher swarm next round — it is **not** an opt-out.
+    The `--task <task-id>` flag is required: it records the Rule 9 evidence the tool-use audit cross-checks. A `knowledge-search` run without it leaves no ledger entry, so the audit treats the spawn as if it never searched (`rule-9-search-tool-unverified`). If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Skipping this step stamps `rule-9-violation` in the Layer-C audit log and the loop routes back to the researcher swarm next round — it is **not** an opt-out.
 2. **Locate the failure surface** strictly inside `files_modified`. If the failure points outside that set, emit `## SCOPE EXPANSION REQUEST` and stop — do NOT edit out-of-scope files.
 3. **Propose the smallest patch** that addresses the root cause:
    - For `compile` / `lint`: edit the offending file directly.
@@ -72,10 +72,10 @@ The orchestrator provides these in your prompt context. Read every path it hands
 
 ## Mandatory Knowledge Lookup (Rule 9)
 
-**This is non-optional, not advisory.** Workflow Step 1a runs the lookup before any Edit. Skipping it stamps `rule-9-violation` in the audit log and forces a re-route to the researcher swarm.
+**This is non-optional, not advisory.** Workflow Step 1a runs the lookup before any Edit. Skipping it — or running it without `--task` — stamps `rule-9-violation` in the audit log and forces a re-route to the researcher swarm.
 
 ```bash
-node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol>" --limit 5
+node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol>" --task <task-id> --limit 5
 ```
 
 If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Cross-task context belongs in `RULES.md` and `M<NNN>-CONTEXT.md`.

package/agents/np-executor.md

@@ -31,7 +31,7 @@ This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENES
 - **Rule 3 — Do it with tests.** Every commit ships tests for the production code it adds or changes. No "trivial enough to skip tests" exceptions.
 - **Rule 4 — Do it with documentation.** Update `.nubos-pilot/codebase/<module>.md` after every commit (`update-docs` is mandatory, not optional).
 - **Rule 7 — Never leave a dangling thread.** Dead imports, unused symbols, half-renamed identifiers — clean them up in the same commit that introduces the change.
-- **Rule 9 — Search before building.** Run `knowledge-search` for the symbols you plan to introduce before writing them. Reuse beats reinvention.
+- **Rule 9 — Search before building.** Before writing any new symbol, run `node np-tools.cjs knowledge-search "<symbol>" --task <task-id>` via Bash. The `--task <task-id>` flag is mandatory — it records the evidence the Rule 9 tool-use audit cross-checks; a lookup without it counts as no search. Reuse beats reinvention.
 - **Rule 10 — Test before shipping.** Verify must be green before you call `commit-task`. Manual "I ran it once" is not proof of work.
 
 Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.

package/agents/np-plan-checker.md

@@ -28,7 +28,7 @@ Refusal of any rule is a hard-stop. Surface the violation to the orchestrator ve
 
 ## Role
 
-Adversarial reader of milestone plans. You assume the planner made mistakes and look for them systematically. You enforce the canonical finding-category taxonomy published in `docs/agent-frontmatter-schema.md` — every issue you emit MUST use one of those codes verbatim.
+Adversarial reader of milestone plans. You assume the planner made mistakes and look for them systematically. You enforce the canonical finding-category taxonomy defined below — every issue you emit MUST use one of those codes verbatim.
 
 You are NOT the executor (`/np:execute-phase`) and NOT the post-execution verifier (`/np:validate-phase`). You verify plans WILL work before execution; the verifier confirms code DID work after execution. Same goal-backward methodology, different timing.
 
@@ -53,7 +53,7 @@ Additional context the orchestrator may inline in the prompt:
 
 ## Review Dimensions
 
-Each dimension maps to one or more canonical finding categories from `docs/agent-frontmatter-schema.md`. The 14 canonical codes are:
+Each dimension maps to one or more canonical finding categories. The 14 canonical codes are:
 
 - `missing-success-criterion` — a ROADMAP SC-X is not mapped to any task.
 - `non-atomic-task` — a task bundles multiple distinct deliverables that should be split.
@@ -66,9 +66,9 @@ Each dimension maps to one or more canonical finding categories from `docs/agent
 - `hook-field-present` — agent frontmatter contains `hooks:` (D-10).
 - `forbidden-agent-field` — agent frontmatter contains `model:` or `model_profile:` (D-10).
 - `unverified-assumption` — a slice plan's `<reality_check>` block is missing, empty, or contains an `<assumption>` without a non-empty `verified_by` attribute, OR a `<files_read>` path does not exist in the repo (Reality-Check rule, see Dimension 12).
-- `verify-command-unknown` — a `<verify>` block invokes a command that is not a known np-tools verb, declared composer/npm script, vendor binary, or POSIX baseline tool (Plan-side Trust Layer, ADR-0013). Mechanically detected by `np-tools.cjs plan-lint`; you mirror the verdict into your findings array so the loop handler treats it uniformly with semantic findings.
-- `parallel-task-implicit-dependency` — tasks marked `depends_on: []` in the same slice but one of them runs a working-tree-reading verify (`update-docs`, `phpstan analyse`, `git diff`, etc.) against files another sibling modifies. Implicit ordering must be made explicit (Plan-side Trust Layer, ADR-0013).
-- `plan-over-specifies-implementation` — PLAN.md body contains schema DDL, framework-controlled timestamped filenames, or large inline code snippets. Plans specify intent + boundary + acceptance, not implementation. Severity is `major` (advisory) — not a hard block, but you flag it so the planner course-corrects (Plan-side Granularity Doctrine, ADR-0013).
+- `verify-command-unknown` — a `<verify>` block invokes a command that is not a known np-tools verb, declared composer/npm script, vendor binary, or POSIX baseline tool (Plan-side Trust Layer, ADR-0019). Mechanically detected by `np-tools.cjs plan-lint`; you mirror the verdict into your findings array so the loop handler treats it uniformly with semantic findings.
+- `parallel-task-implicit-dependency` — tasks marked `depends_on: []` in the same slice but one of them runs a working-tree-reading verify (`update-docs`, `phpstan analyse`, `git diff`, etc.) against files another sibling modifies. Implicit ordering must be made explicit (Plan-side Trust Layer, ADR-0019).
+- `plan-over-specifies-implementation` — PLAN.md body contains schema DDL, framework-controlled timestamped filenames, or large inline code snippets. Plans specify intent + boundary + acceptance, not implementation. Severity is `major` (advisory) — not a hard block, but you flag it so the planner course-corrects (Plan-side Granularity Doctrine, ADR-0019).
 
 Note on the Nubosloop critic: as of 2026-05-05 a single `np-critic` agent covers style + tests + acceptance in one spawn (ADR-0010 §Single-Critic Revision). The legacy three-critic schwarm (`np-critic-style`/`np-critic-tests`/`np-critic-acceptance`) is removed. References in older plans should be updated.
 

package/agents/np-planner.md

@@ -277,7 +277,7 @@ Every PLAN.md you write will be consumed by an executor agent that:
 **Implications for your writing style:**
 
 - **Name the library, not the category.** "Use `jose` for JWT" > "use a JWT library".
-- **Name the file, not the area** — for *deterministic edits the planner can know up-front*. "Modify `src/api/auth/login.ts`" > "update the auth layer". For *scaffolding tasks where a framework generates files at install/publish time*, use a glob (`database/migrations/*_cashier_*.php`) or leave `files_modified` empty — the executor resolves the real paths from the actual publish output and `commit-task` falls back to `checkpoint.files_touched` (D-04, ADR-0013 Layer-D Granularity).
+- **Name the file, not the area** — for *deterministic edits the planner can know up-front*. "Modify `src/api/auth/login.ts`" > "update the auth layer". For *scaffolding tasks where a framework generates files at install/publish time*, use a glob (`database/migrations/*_cashier_*.php`) or leave `files_modified` empty — the executor resolves the real paths from the actual publish output and `commit-task` falls back to `checkpoint.files_touched` (D-04, ADR-0019 Layer-D Granularity).
 - **Name the command, not the intent.** "Run `npm test -- --filter=auth`" > "run the tests".
 - **Cite existing interfaces verbatim.** If `lib/core.cjs` exports `NubosPilotError(code, message, details)` — quote that signature in the task context so the executor doesn't mis-remember.
 - **Document deviations from canonical advice.** If you deviate from CONTEXT.md's stack choice, say so explicitly and note why.
@@ -286,7 +286,7 @@ If the executor has to stop and read three more files to figure out what you mea
 </downstream_awareness>
 
 <plan_granularity>
-## Plan Granularity Doctrine — Intent + Boundary + Acceptance, NOT Implementation (ADR-0013)
+## Plan Granularity Doctrine — Intent + Boundary + Acceptance, NOT Implementation (ADR-0019)
 
 A PLAN.md is a contract. It specifies **what** must be true at the end (intent), **where** the work is allowed to touch (boundary), and **how** success is measured (acceptance). It does NOT specify HOW the implementation looks. That's the executor's territory; you don't have ground-truth on it and pretending you do is the bug class that produced the M004 plan-bugs.
 

package/agents/np-researcher.md

@@ -24,7 +24,7 @@ Your output is prescriptive, not exploratory: "Use library X at version Y" beats
 This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). The rules that bind this role:
 
 - **Rule 5 — Aim to genuinely impress.** Prescriptive beats exploratory. "Use `jose@6.0.10`" beats "consider a JWT library". Vague research produces vague plans, vague plans produce vague software.
-- **Rule 9 — Search before building.** This is your core job. Before any new claim, search the local knowledge index (`knowledge-search`), the codebase docs (`.nubos-pilot/codebase/`), and Context7 / WebFetch. Reuse prior learnings.
+- **Rule 9 — Search before building.** This is your core job. Before any new claim, search the local knowledge index via `node np-tools.cjs knowledge-search "<query>"` (pass `--task <task-id>` when spawned inside the execute-loop so the Rule 9 audit ledger records the call), the codebase docs (`.nubos-pilot/codebase/`), and Context7 / WebFetch. Reuse prior learnings.
 - **Rule 11 — Ship the complete thing.** RESEARCH.md is a deliverable, not a draft. Every claim has provenance, every assumption is tagged `[ASSUMED]`, every gap is listed in `Open Questions`. No half-research.
 
 Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
@@ -37,7 +37,7 @@ Your per-spawn output MUST conform to the **`researcher-output`** schema. The or
 
 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.).
+- Frontmatter must include `schema_version`, `agent: np-researcher`, `spawn_index`, `seed_delta`, `task_query_hash`, plus count fields (`decision_count`, `risk_count`, etc.). `spawn_index` and `seed_delta` are **integers** — copy them verbatim from the `index` / `seed_delta` fields of your spawn spec. The prose perspective nudge arrives on the spawn spec's separate `seed_nudge` field; it shapes HOW you investigate and never goes into frontmatter.
 - 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).

package/bin/check-workflows.cjs

@@ -66,8 +66,6 @@ function _scanMetricsCoverage(files) {
     const raw = fs.readFileSync(file, 'utf-8');
     const lines = raw.split(/\r?\n/);
 
-    
-
     let inAnyFence = false;
     let inBashFence = false;
     for (let i = 0; i < lines.length; i++) {
@@ -102,10 +100,6 @@ function _scanMetricsCoverage(files) {
   return warnings;
 }
 
-function _scan(dir) {
-  return _scanFiles(_walk(dir, [], { ext: ['.md'] }));
-}
-
 function _scanInstallerSurface(cwd) {
   const root = cwd || process.cwd();
   const files = [];
@@ -131,7 +125,7 @@ function checkWorkflows(dir) {
       violations.push(..._scanFiles(workflowFiles));
       warnings.push(..._scanMetricsCoverage(workflowFiles));
     }
-  } catch {  }
+  } catch {}
   violations.push(..._scanInstallerSurface());
   return { violations, warnings, exitCode: violations.length ? 1 : 0 };
 }
@@ -158,7 +152,6 @@ if (require.main === module) main();
 
 module.exports = {
   checkWorkflows,
-  _scan,
   _scanFiles,
   _scanInstallerSurface,
   _scanMetricsCoverage,

package/bin/install.js

@@ -87,7 +87,7 @@ function _parseAgentsFlag(value) {
 }
 
 function parseInstallFlags(args) {
-  const flags = { agent: null, agents: null, scope: null, mcp: false, yes: false };
+  const flags = { agent: null, agents: null, scope: null, yes: false };
   const rest = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -98,7 +98,6 @@ function parseInstallFlags(args) {
     if (a === '--all') { flags.agents = VALID_AGENTS.slice(); continue; }
     if (a === '--scope' || a === '-s') { flags.scope = args[++i] || null; continue; }
     if (a.startsWith('--scope=')) { flags.scope = a.slice('--scope='.length); continue; }
-    if (a === '--mcp') { flags.mcp = true; continue; }
     if (a === '--yes' || a === '-y') { flags.yes = true; continue; }
     rest.push(a);
   }
@@ -229,7 +228,7 @@ function _copyTree(src, dst) {
   try {
     entries = fs.readdirSync(src, { withFileTypes: true });
   } catch (err) {
-    if (err && err.code === 'ENOENT') return; 
+    if (err && err.code === 'ENOENT') return;
     throw err;
   }
   fs.mkdirSync(dst, { recursive: true });
@@ -241,7 +240,6 @@ function _copyTree(src, dst) {
     } else if (e.isFile()) {
       fs.copyFileSync(from, to);
     }
-
   }
 }
 
@@ -280,7 +278,7 @@ async function _runInitQuestions(detectedRuntime, askUser, flags) {
     options: ['frontier', 'quality', 'balanced', 'budget', 'inherit'], default: 'frontier' })).value;
   const response_language = (await askUser({ type: 'input', question: 'Response language (ISO-639 code)?', default: 'en' })).value;
   return configDefaults.buildInstallConfig({
-    runtime, runtimes, scope, mcp: !!f.mcp,
+    runtime, runtimes, scope,
     model_profile,
     response_language,
   });
@@ -330,7 +328,7 @@ function _rewriteManagedMarkdown(projectRoot, runtimes, responseLanguage) {
 
     const base = fs.existsSync(targetPath)
       ? fs.readFileSync(targetPath, 'utf-8')
-      : agentsMdMod.generateAgentsMd(claudeRendered, id === 'gemini' ? 'gemini' : 'codex');
+      : agentsMdMod.generateAgentsMd(claudeRendered, id);
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
     atomicWriteFileSync(targetPath, managedBlockMod.rewriteBlock(base, innerMd));
   }
@@ -462,7 +460,7 @@ async function _runInstallLocked(ctx) {
       scope: resolvedScope,
       wouldWrite: Object.keys(newManifest.files).length,
       wouldBackup: backupLog.length, wouldDelete: diff.stale.length,
-      wouldWriteGemini: true,
+      wouldWriteGemini: selectedRuntimesEarly.includes('gemini'),
       wouldWriteOpencodeJson: opencodeSelected && !fs.existsSync(path.join(projectRoot, 'opencode.json')),
       stale: diff.stale, changed: diff.changed, added: diff.added };
     process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
@@ -541,20 +539,6 @@ async function _runInstallLocked(ctx) {
     console.error(yellow + '  [shim] np-tools shim skipped: ' + (err && err.message) + reset);
   }
 
-  if (initConfig && initConfig.mcp && !dryRun) {
-    try {
-      const mcpWriter = require('../lib/install/mcp-writer.cjs');
-      const result = mcpWriter.writeMcpConfig({
-        runtime: initConfig.runtime,
-        scope: initConfig.scope,
-        projectRoot,
-      });
-      console.error(green + '  [mcp] nubos MCP configured → ' + result.path + reset);
-    } catch (err) {
-      console.error(yellow + '  [mcp] skipped: ' + (err && err.message) + reset);
-    }
-  }
-
   if (opencodeSelected) {
     const projectOpencodeJson = path.join(projectRoot, 'opencode.json');
     if (!fs.existsSync(projectOpencodeJson) && fs.existsSync(OPENCODE_JSON_TEMPLATE)) {
@@ -625,7 +609,9 @@ function _runUninstallLocked(projectRoot) {
   const assetDirs = new Set();
   for (const rel of Object.keys(manifest.files)) {
     const isAsset = runtimeAssetsMod.isAssetManifestKey(rel);
-    const abs = isAsset ? path.join(payloadBase, rel) : path.join(payloadDir, rel);
+    const abs = rel.startsWith('~/')
+      ? path.join(os.homedir(), rel.slice(2))
+      : isAsset ? path.join(payloadBase, rel) : path.join(payloadDir, rel);
     try {
       fs.unlinkSync(abs);
       removed++;
@@ -651,7 +637,7 @@ function _runUninstallLocked(projectRoot) {
 
   try { fs.unlinkSync(path.join(payloadDir, '.manifest.json')); } catch {}
 
-  try { fs.rmdirSync(payloadDir); } catch {  }
+  try { fs.rmdirSync(payloadDir); } catch {}
 
   const cfgPath = path.join(_stateDirFor(projectRoot), 'config.json');
   let installedRuntimes = [];

package/bin/np-tools/_args.cjs

@@ -54,10 +54,18 @@ function assertOptionalMatch(value, re, code, label) {
   assertMatch(value, re, code, label);
 }
 
+function emitErrorEnvelope(err, stderr, fallbackCode) {
+  const code = err && err.name === 'NubosPilotError' ? err.code : fallbackCode;
+  const message = (err && err.message) || String(err);
+  const details = (err && err.details) || null;
+  stderr.write(JSON.stringify({ code, message, details }) + '\n');
+}
+
 module.exports = {
   getFlag,
   getJsonFlag,
   optionalJsonFlag,
   assertMatch,
   assertOptionalMatch,
+  emitErrorEnvelope,
 };

package/bin/np-tools/_commands.cjs

@@ -7,7 +7,7 @@ const COMMANDS = [
   { name: 'discuss-phase',       category: 'Planning', description: 'Adaptive milestone-context interview (writes M<NNN>-CONTEXT.md)', description_de: 'Adaptives Milestone-Kontext-Interview (schreibt M<NNN>-CONTEXT.md)' },
   { 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: 'plan-lint',           category: 'Planning', description: 'Mechanical Trust-Layer linter for PLAN.md (verify-command + parallel-race + over-specification). ADR-0019', description_de: 'Mechanischer Trust-Layer-Linter für PLAN.md (verify-command + parallel-race + Über-Spezifikation). ADR-0019' },
   { 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)' },
@@ -33,17 +33,14 @@ const COMMANDS = [
   { name: 'undo-task',           category: 'Execution', description: 'Revert a single task commit and reset task status to pending', description_de: 'Revertiert einen einzelnen Task-Commit und setzt Task-Status auf pending zurück' },
   { name: 'reset-slice',         category: 'Execution', description: 'Discard in-flight task: restore working tree from HEAD, drop checkpoint, clear STATE.current_task', description_de: 'Verwirft laufenden Task: stellt Working-Tree von HEAD wieder her, löscht Checkpoint, leert STATE.current_task' },
 
-  { name: 'doctor',              category: 'Install', description: '5-check install-integrity scan (--fix for auto-safe fixes)', description_de: '5-Check-Install-Integritäts-Scan (--fix für auto-sichere Fixes)' },
+  { name: 'doctor',              category: 'Install', description: '12-check install-integrity scan (--fix for auto-safe fixes)', description_de: '12-Check-Install-Integritäts-Scan (--fix für auto-sichere Fixes)' },
   { name: 'scan-codebase',       category: 'Install', description: 'Initial deep codebase inventory → .nubos-pilot/codebase/ skill docs', description_de: 'Initiale tiefe Codebase-Inventur → .nubos-pilot/codebase/ Skill-Docs' },
   { name: 'update-docs',         category: 'Install', description: 'Refresh stale module docs after code changes', description_de: 'Aktualisiert veraltete Modul-Docs nach Code-Änderungen' },
 
   { name: 'resolve-model',       category: 'Utility', description: 'Resolve agent/tier to model alias or id (Tier×Profile matrix)', description_de: 'Löst Agent/Tier zu Model-Alias oder -ID auf (Tier×Profile-Matrix)' },
   { name: 'metrics',             category: 'Utility', description: 'Record JSONL metrics entry (record | now | start-timestamp | end-timestamp)', description_de: 'Schreibt JSONL-Metrics-Eintrag (record | now | start-timestamp | end-timestamp)' },
 
-  { name: 'validate-phase',      category: 'Review',  description: 'Nyquist validation gap-fill via np-nyquist-auditor', description_de: 'Nyquist-Validierungs-Gap-Fill über np-nyquist-auditor' },
-
   { name: 'add-todo',            category: 'Capture', description: 'Capture a pending todo to .nubos-pilot/todos/pending/ + increment STATE count', description_de: 'Erfasst pending Todo nach .nubos-pilot/todos/pending/ + erhöht STATE-Counter' },
-  { name: 'note',                category: 'Capture', description: 'Capture a free-form note (project default, --global writes to ~/.nubos-pilot/notes/)', description_de: 'Erfasst freiformige Notiz (Projekt-Default, --global schreibt nach ~/.nubos-pilot/notes/)' },
 
   { name: 'askuser',         category: 'Utility', description: 'Capability-layer prompt wrapper (reads spec JSON, returns chosen label)', description_de: 'Capability-Layer-Prompt-Wrapper (liest Spec-JSON, gibt gewähltes Label zurück)' },
   { name: 'commit',          category: 'Utility', description: 'Atomic git commit wrapper with gitignore-guard', description_de: 'Atomarer Git-Commit-Wrapper mit Gitignore-Guard' },
@@ -64,7 +61,7 @@ const COMMANDS = [
   { 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-inbox',    category: 'Capture',  description: 'List unread messages addressed to an agent (filterable by --kind, --since, --task)', description_de: 'Listet ungelesene 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' },
@@ -80,13 +77,12 @@ const COMMANDS = [
   { name: 'thread-resume',     category: 'Utility',  description: 'Bump a thread markdown on resume (status OPEN→IN_PROGRESS, refresh last_resumed) via atomic write', description_de: 'Bumpt Thread-Markdown beim Resume (Status OPEN→IN_PROGRESS, aktualisiert last_resumed) via atomic write' },
   { name: 'state-incr',        category: 'Capture',  description: 'Increment a whitelisted STATE.md counter (e.g. pending_todos) under withFileLock', description_de: 'Erhöht whitelisteten STATE.md-Counter (z.B. pending_todos) unter withFileLock' },
 
-  { name: 'thread',           category: 'Utility', description: 'Cross-session thread CRUD (create/resume under .nubos-pilot/threads/)', description_de: 'Cross-Session-Thread-CRUD (create/resume unter .nubos-pilot/threads/)' },
   { name: 'session-aggregate',     category: 'Utility', description: 'Aggregate session metrics under withFileLock; reads pointer .last-session unless --since overrides', description_de: 'Aggregiert Session-Metriken unter withFileLock; liest Pointer .last-session, außer --since überschreibt' },
   { name: 'session-pointer-write', category: 'Utility', description: 'Atomic write of .nubos-pilot/reports/.last-session under withFileLock (ISO-8601 UTC)', description_de: 'Atomares Schreiben von .nubos-pilot/reports/.last-session unter withFileLock (ISO-8601 UTC)' },
   { name: 'workspace-scan',        category: 'Install', description: 'Scan a workspace and emit inventory JSON (full result or --summary shape for /np:new-project)', description_de: 'Scannt einen Workspace und liefert Inventar-JSON (volles Ergebnis oder --summary-Shape für /np:new-project)' },
 
   { name: 'knowledge-index',         category: 'Utility', description: 'Build BM25-light index over .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json', description_de: 'Baut BM25-Light-Index über .nubos-pilot/**/*.md → .nubos-pilot/state/knowledge-index.json' },
-  { name: 'knowledge-search',        category: 'Utility', description: 'Query the knowledge index; returns top-N JSON hits (rel_path + lines + score + preview)', description_de: 'Sucht im Knowledge-Index; liefert Top-N-JSON-Treffer (rel_path + Zeilen + Score + Preview)' },
+  { name: 'knowledge-search',        category: 'Utility', description: 'Query the knowledge index; returns top-N JSON hits (rel_path + lines + score + preview). Pass --task <id> inside a Nubosloop task to record Rule 9 audit evidence', description_de: 'Sucht im Knowledge-Index; liefert Top-N-JSON-Treffer (rel_path + Zeilen + Score + Preview). --task <id> innerhalb eines Nubosloop-Tasks schreibt den Rule-9-Audit-Nachweis' },
   { name: 'knowledge-stats',         category: 'Utility', description: 'Print knowledge-index size + grouping (auto-builds if missing)', description_de: 'Gibt Knowledge-Index-Größe + Gruppierung aus (baut auto bei Fehlen)' },
   { name: 'context-stats',           category: 'Utility', description: 'Aggregated context-budget stats (file counts + bytes per group, knowledge-index size)', description_de: 'Aggregierte Context-Budget-Stats (Dateien/Bytes pro Gruppe, Knowledge-Index-Größe)' },
   { name: 'session-snapshot-write',  category: 'Utility', description: 'Capture session snapshot (current_task + recent commits + open handoffs) for resume', description_de: 'Erfasst Session-Snapshot (current_task + letzte Commits + offene Handoffs) für Resume' },

package/bin/np-tools/_commands.test.cjs

@@ -0,0 +1,31 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { COMMANDS } = require('./_commands.cjs');
+const nt = require('../../np-tools.cjs');
+
+const HARD_CASED = ['init', 'state', 'help'];
+
+function dispatchNames() {
+  return new Set([
+    ...HARD_CASED,
+    ...Object.keys(nt.initWorkflows),
+    ...Object.keys(nt.topLevelCommands),
+  ]);
+}
+
+function catalogNames() {
+  return new Set(COMMANDS.map((c) => c.name));
+}
+
+test('CAT-DISPATCH-1: every catalog command has a dispatch entry', () => {
+  const dispatch = dispatchNames();
+  const orphans = [...catalogNames()].filter((n) => !dispatch.has(n));
+  assert.deepEqual(orphans, [], 'catalog commands without a dispatch entry: ' + orphans.join(', '));
+});
+
+test('CAT-DISPATCH-2: every dispatch entry has a catalog command', () => {
+  const catalog = catalogNames();
+  const orphans = [...dispatchNames()].filter((n) => !catalog.has(n));
+  assert.deepEqual(orphans, [], 'dispatch entries without a catalog command: ' + orphans.join(', '));
+});

package/bin/np-tools/askuser.cjs

@@ -1,16 +1,10 @@
 const { askUser } = require('../../lib/askuser.cjs');
+const { emitErrorEnvelope } = require('./_args.cjs');
 
 function _usage() {
   return 'Usage:\n  np-tools.cjs askuser --json \'{...spec...}\'';
 }
 
-function _emitError(err, stderr) {
-  const code = err && err.name === 'NubosPilotError' ? err.code : 'askuser-internal-error';
-  const message = (err && err.message) || String(err);
-  const details = (err && err.details) || null;
-  stderr.write(JSON.stringify({ code, message, details }) + '\n');
-}
-
 async function run(argv, ctx) {
   const context = ctx || {};
   const stdout = context.stdout || process.stdout;
@@ -38,7 +32,7 @@ async function run(argv, ctx) {
     stdout.write(out + '\n');
     return 0;
   } catch (err) {
-    _emitError(err, stderr);
+    emitErrorEnvelope(err, stderr, 'askuser-internal-error');
     return 1;
   }
 }

package/bin/np-tools/commit-task.cjs

@@ -85,8 +85,6 @@ function _resolveTaskFile(taskId, cwd) {
 }
 
 function _resolveSafe(root, p) {
-
-  
   const abs = path.resolve(root, p);
   const rel = path.relative(root, abs);
   if (rel.startsWith('..') || path.isAbsolute(rel)) {
@@ -203,7 +201,7 @@ function run(args, ctx) {
 
   const sha = findCommitByTaskId(taskId);
 
-  try { deleteCheckpoint(taskId, cwd); } catch {  }
+  try { deleteCheckpoint(taskId, cwd); } catch {}
   try { setTaskStatus(taskId, 'done', cwd); } catch (err) {
     process.stderr.write('[nubos-pilot warn] setTaskStatus failed for ' + taskId + ': ' + (err && err.message) + '\n');
   }

package/bin/np-tools/commit.cjs

@@ -4,6 +4,7 @@ const path = require('node:path');
 const { NubosPilotError, findProjectRoot } = require('../../lib/core.cjs');
 const { assertCommittablePaths } = require('../../lib/git.cjs');
 const { resolveCommitArtifacts } = require('../../lib/commit-policy.cjs');
+const { emitErrorEnvelope } = require('./_args.cjs');
 
 const MAX_MSG = 2000;
 
@@ -11,13 +12,6 @@ function _usage() {
   return 'Usage:\n  np-tools.cjs commit "message" --files f1 f2 ...';
 }
 
-function _emitError(err, stderr) {
-  const code = err && err.name === 'NubosPilotError' ? err.code : 'commit-internal-error';
-  const message = (err && err.message) || String(err);
-  const details = (err && err.details) || null;
-  stderr.write(JSON.stringify({ code, message, details }) + '\n');
-}
-
 function _parseArgs(argv) {
   const args = Array.isArray(argv) ? argv.slice() : [];
   let msg = null;
@@ -123,7 +117,7 @@ function run(argv, ctx) {
     stdout.write(JSON.stringify({ committed: true, sha, files: committable }) + '\n');
     return 0;
   } catch (err) {
-    _emitError(err, stderr);
+    emitErrorEnvelope(err, stderr, 'commit-internal-error');
     return 1;
   }
 }

package/bin/np-tools/config.cjs

@@ -2,6 +2,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { findProjectRoot, NubosPilotError } = require('../../lib/core.cjs');
 const { DEFAULT_CONFIG_TREE } = require('../../lib/config-defaults.cjs');
+const { emitErrorEnvelope } = require('./_args.cjs');
 
 const SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
 const BLOCKED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
@@ -10,13 +11,6 @@ function _usage() {
   return 'Usage:\n  np-tools.cjs config-get <dotted.key> [--raw]';
 }
 
-function _emitError(err, stderr) {
-  const code = err && err.name === 'NubosPilotError' ? err.code : 'config-get-internal-error';
-  const message = (err && err.message) || String(err);
-  const details = (err && err.details) || null;
-  stderr.write(JSON.stringify({ code, message, details }) + '\n');
-}
-
 function _readConfig(cwd) {
   let root;
   try {
@@ -89,7 +83,7 @@ function run(argv, ctx) {
     else stdout.write(out + '\n');
     return 0;
   } catch (err) {
-    _emitError(err, stderr);
+    emitErrorEnvelope(err, stderr, 'config-get-internal-error');
     return 1;
   }
 }

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

@@ -6,9 +6,6 @@ const { scan } = require('../../lib/workspace-scan.cjs');
 const { workspaceGitInfo } = require('../../lib/git.cjs');
 const textMode = require('../../lib/text-mode.cjs');
 
-const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
-const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
-
 const REQUIRED_FIELDS = Object.freeze([
   'project_description',
   'domain_text',
@@ -18,19 +15,6 @@ const REQUIRED_FIELDS = Object.freeze([
   'strategic_decisions_text',
 ]);
 
-function _render(raw, vars, name) {
-  return raw.replace(PLACEHOLDER_RE, (_m, key) => {
-    if (!(key in vars)) {
-      throw new NubosPilotError(
-        'template-unresolved-var',
-        `Undefined placeholder {{${key}}} in template "${name}"`,
-        { template: name, variable: key, available: Object.keys(vars) },
-      );
-    }
-    return String(vars[key]);
-  });
-}
-
 function _parseArgs(args) {
   const flags = {
     cwd: null,
@@ -140,17 +124,6 @@ function _readExistingProjectMd(projectMd) {
   }
 }
 
-function _extractExistingField(md, heading) {
-  const re = new RegExp('^##\\s+' + heading.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&') + '\\s*$', 'm');
-  const match = md.match(re);
-  if (!match) return null;
-  const start = match.index + match[0].length;
-  const rest = md.slice(start);
-  const nextHeading = rest.match(/\n##\s+/);
-  const body = nextHeading ? rest.slice(0, nextHeading.index) : rest;
-  return body.trim();
-}
-
 function _replaceSectionBody(md, heading, newBody) {
   const lines = md.split('\n');
   const headingRe = new RegExp('^##\\s+' + heading.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&') + '\\s*$');

package/bin/np-tools/doctor.cjs

@@ -18,7 +18,6 @@ const PAYLOAD_SUBPATH = path.join('.claude', 'nubos-pilot');
 const STATE_SUBPATH = '.nubos-pilot';
 const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
 const OPENCODE_LOCAL_PREFIX = '.opencode/nubos-pilot/';
-const OPENCODE_GLOBAL_PREFIX = '~/.config/opencode/nubos-pilot/';
 
 function _readScope(projectRoot) {
   const cfgPath = path.join(projectRoot, STATE_SUBPATH, 'config.json');
@@ -433,25 +432,15 @@ function _checkNubosloopConfig(projectRoot) {
   try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')); } catch { return issues; }
   const swarm = cfg && cfg.swarm;
   const adapter = swarm && swarm.knowledge_adapter;
-  if (adapter && adapter !== 'local' && adapter !== 'mcp') {
+  if (adapter && adapter !== 'local') {
     issues.push({
       id: 'nubosloop-knowledge-adapter-invalid',
       severity: 'warn',
       fixable: 'manual',
       details: {
         value: adapter,
-        supported: ['local', 'mcp'],
-        hint: 'set swarm.knowledge_adapter to "local" or "mcp" — falls back to "local" silently otherwise.',
-      },
-    });
-  }
-  if (adapter === 'mcp') {
-    issues.push({
-      id: 'nubosloop-knowledge-adapter-mcp-pending',
-      severity: 'info',
-      fixable: 'manual',
-      details: {
-        hint: 'mcp adapter is configured but the transport ships in Phase 7/8; matchExistingLearning will throw mcp-adapter-not-implemented until then.',
+        supported: ['local'],
+        hint: 'set swarm.knowledge_adapter to "local" — falls back to "local" silently otherwise.',
       },
     });
   }