nubos-pilot 0.9.0 → 0.9.2

package/bin/np-tools/research-merge.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const swarm = require('../../lib/researcher-swarm.cjs');
+
+function _parseArgs(args) {
+  const out = { inputs: null, output: null, heading: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--inputs')  { out.inputs = args[++i] || null; continue; }
+    if (a === '--output')  { out.output = args[++i] || null; continue; }
+    if (a === '--heading') { out.heading = args[++i] || null; continue; }
+  }
+  return out;
+}
+
+function _readSpawnOutput(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    throw new NubosPilotError(
+      'research-merge-input-missing',
+      'Cannot read spawn output file: ' + filePath + ' — ' + err.message,
+      { path: filePath },
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new NubosPilotError(
+      'research-merge-input-invalid-json',
+      'Spawn output is not valid JSON: ' + filePath + ' — ' + err.message,
+      { path: filePath },
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new NubosPilotError(
+      'research-merge-input-shape',
+      'Spawn output must be a JSON object: ' + filePath,
+      { path: filePath },
+    );
+  }
+  return parsed;
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+
+  if (!parsed.inputs) {
+    throw new NubosPilotError(
+      'research-merge-missing-inputs',
+      'research-merge requires --inputs <comma-separated JSON paths>',
+      { args },
+    );
+  }
+  if (!parsed.output) {
+    throw new NubosPilotError(
+      'research-merge-missing-output',
+      'research-merge requires --output <RESEARCH.md path>',
+      { args },
+    );
+  }
+
+  const inputPaths = parsed.inputs.split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((p) => (path.isAbsolute(p) ? p : path.resolve(cwd, p)));
+  if (!inputPaths.length) {
+    throw new NubosPilotError(
+      'research-merge-empty-inputs',
+      'research-merge --inputs resolved to zero paths',
+      { raw: parsed.inputs },
+    );
+  }
+
+  const spawnOutputs = inputPaths.map(_readSpawnOutput);
+  const consensus = swarm.mergeConsensus(spawnOutputs);
+  const md = swarm.renderConsensusToMarkdown(
+    consensus,
+    parsed.heading ? { heading: parsed.heading } : undefined,
+  );
+
+  const outputPath = path.isAbsolute(parsed.output)
+    ? parsed.output
+    : path.resolve(cwd, parsed.output);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, md, 'utf-8');
+
+  stdout.write(JSON.stringify({
+    output_path: outputPath,
+    inputs: inputPaths,
+    meta: consensus.meta,
+  }) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/research-merge.test.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, cleanupAll } = require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./research-merge.cjs');
+
+afterEach(cleanupAll);
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+function _writeSpawn(sandbox, name, payload) {
+  const dir = path.join(sandbox, '.nubos-pilot', '.tmp-swarm');
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, name);
+  fs.writeFileSync(target, JSON.stringify(payload), 'utf-8');
+  return target;
+}
+
+test('RM-1: merges 3 spawn JSONs into RESEARCH.md and emits meta', () => {
+  const sandbox = makeSandbox();
+  const a = _writeSpawn(sandbox, 'spawn-0.json', {
+    decisions: [{ claim: 'Use jose@6.0.10', confidence: 'HIGH', provenance: '[VERIFIED]' }],
+    risks: [{ description: 'Token expiry not validated', severity: 'HIGH' }],
+    patterns: [{ name: 'JWT verify wrapper' }],
+    open_questions: ['Refresh token rotation policy?'],
+    sources: [{ url: 'https://example.com/jose', credibility: 'HIGH' }],
+  });
+  const b = _writeSpawn(sandbox, 'spawn-1.json', {
+    decisions: [{ claim: 'Use jose@6.0.10', confidence: 'HIGH', provenance: '[VERIFIED]' }],
+    patterns: [{ name: 'JWT verify wrapper' }],
+    open_questions: ['Refresh token rotation policy?'],
+  });
+  const c = _writeSpawn(sandbox, 'spawn-2.json', {
+    decisions: [{ claim: 'Use jose@6.0.10', confidence: 'HIGH', provenance: '[VERIFIED]' }],
+    risks: [{ description: 'Token expiry not validated', severity: 'HIGH' }],
+  });
+
+  const out = path.join(sandbox, '.nubos-pilot', 'milestones', 'M001', 'RESEARCH.md');
+  const cap = _capture();
+  const rc = subcmd.run([
+    '--inputs', [a, b, c].join(','),
+    '--output', out,
+  ], { cwd: sandbox, stdout: cap.stub });
+
+  assert.equal(rc, 0);
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.output_path, out);
+  assert.equal(payload.meta.k, 3);
+  assert.equal(payload.meta.flagged_count, 0);
+  assert.ok(fs.existsSync(out));
+  const md = fs.readFileSync(out, 'utf-8');
+  assert.match(md, /# Researcher-Schwarm Consensus/);
+  assert.match(md, /<consensus_meta>/);
+  assert.match(md, /Use jose@6\.0\.10/);
+});
+
+test('RM-2: --heading overrides default consensus heading', () => {
+  const sandbox = makeSandbox();
+  const a = _writeSpawn(sandbox, 's.json', { decisions: [{ claim: 'X' }] });
+  const out = path.join(sandbox, 'R.md');
+  const cap = _capture();
+  subcmd.run([
+    '--inputs', a,
+    '--output', out,
+    '--heading', 'M001 Phase 5 Research',
+  ], { cwd: sandbox, stdout: cap.stub });
+  const md = fs.readFileSync(out, 'utf-8');
+  assert.match(md, /^# M001 Phase 5 Research/);
+});
+
+test('RM-3: missing --inputs throws structured error', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['--output', 'R.md'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'research-merge-missing-inputs',
+  );
+});
+
+test('RM-4: missing --output throws structured error', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['--inputs', 'a.json'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'research-merge-missing-output',
+  );
+});
+
+test('RM-5: missing input file throws structured error', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run([
+      '--inputs', path.join(sandbox, 'nope.json'),
+      '--output', path.join(sandbox, 'R.md'),
+    ], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'research-merge-input-missing',
+  );
+});
+
+test('RM-6: invalid JSON input throws structured error', () => {
+  const sandbox = makeSandbox();
+  const bad = path.join(sandbox, 'bad.json');
+  fs.writeFileSync(bad, '{not-json', 'utf-8');
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run([
+      '--inputs', bad,
+      '--output', path.join(sandbox, 'R.md'),
+    ], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'research-merge-input-invalid-json',
+  );
+});
+
+test('RM-7: array-shaped JSON input throws structured error', () => {
+  const sandbox = makeSandbox();
+  const bad = path.join(sandbox, 'arr.json');
+  fs.writeFileSync(bad, '[]', 'utf-8');
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run([
+      '--inputs', bad,
+      '--output', path.join(sandbox, 'R.md'),
+    ], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'research-merge-input-shape',
+  );
+});
+
+test('RM-8: relative paths resolve against cwd', () => {
+  const sandbox = makeSandbox();
+  const a = _writeSpawn(sandbox, 'rel.json', { decisions: [{ claim: 'Y' }] });
+  const rel = path.relative(sandbox, a);
+  const cap = _capture();
+  subcmd.run([
+    '--inputs', rel,
+    '--output', 'out.md',
+  ], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.output_path, path.join(sandbox, 'out.md'));
+  assert.ok(fs.existsSync(path.join(sandbox, 'out.md')));
+});
+
+test('RM-9: flagged decision (only 1 of 3 spawns) is marked, not accepted', () => {
+  const sandbox = makeSandbox();
+  const a = _writeSpawn(sandbox, '0.json', { decisions: [{ claim: 'Solo claim' }] });
+  const b = _writeSpawn(sandbox, '1.json', { decisions: [{ claim: 'Other' }] });
+  const c = _writeSpawn(sandbox, '2.json', { decisions: [{ claim: 'Other' }] });
+  const out = path.join(sandbox, 'R.md');
+  const cap = _capture();
+  subcmd.run(['--inputs', [a, b, c].join(','), '--output', out],
+    { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.meta.k, 3);
+  assert.equal(payload.meta.flagged_count, 1);
+  const md = fs.readFileSync(out, 'utf-8');
+  assert.match(md, /## Flagged Decisions \(no majority\)/);
+  assert.match(md, /Solo claim/);
+});

package/lib/install/claude-hooks.cjs

@@ -6,10 +6,10 @@ const os = require('node:os');
 
 const { atomicWriteFileSync, NubosPilotError } = require('../core.cjs');
 
-const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.js';
-const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.js';
-const NP_STATUSLINE_MARKER = 'np-statusline.js';
-const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.js';
+const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.cjs';
+const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.cjs';
+const NP_STATUSLINE_MARKER = 'np-statusline.';
+const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.';
 
 function _settingsPath(scope, projectRoot) {
   if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');

package/lib/install/claude-hooks.test.cjs

@@ -12,8 +12,8 @@ function _mkSandbox() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-'));
   fs.mkdirSync(path.join(dir, '.claude'), { recursive: true });
   fs.mkdirSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks'), { recursive: true });
-  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-statusline.js'), '// stub\n');
-  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-ctx-monitor.js'), '// stub\n');
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-statusline.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-ctx-monitor.cjs'), '// stub\n');
   return dir;
 }
 
@@ -26,10 +26,10 @@ test('claude-hooks: fresh install writes both hooks to local settings', () => {
     assert.equal(res.results.ctxMonitor.action, 'installed');
     const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
     assert.equal(settings.statusLine.type, 'command');
-    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+    assert.ok(settings.statusLine.command.includes('np-statusline.cjs'));
     assert.ok(Array.isArray(settings.hooks.PostToolUse));
     assert.equal(settings.hooks.PostToolUse[0].matcher, '.*');
-    assert.ok(settings.hooks.PostToolUse[0].hooks[0].command.includes('np-ctx-monitor.js'));
+    assert.ok(settings.hooks.PostToolUse[0].hooks[0].command.includes('np-ctx-monitor.cjs'));
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -62,7 +62,7 @@ test('claude-hooks: --force overwrites foreign statusLine', () => {
     const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', force: true });
     assert.equal(res.results.statusline.action, 'overwrote');
     const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
-    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+    assert.ok(settings.statusLine.command.includes('np-statusline.cjs'));
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -98,7 +98,7 @@ test('claude-hooks: preserves unrelated PostToolUse hooks', () => {
     const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
     assert.equal(settings.hooks.PostToolUse.length, 2);
     assert.equal(settings.hooks.PostToolUse[0].matcher, 'Bash');
-    assert.ok(settings.hooks.PostToolUse[1].hooks[0].command.includes('np-ctx-monitor.js'));
+    assert.ok(settings.hooks.PostToolUse[1].hooks[0].command.includes('np-ctx-monitor.cjs'));
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "AI-driven planning and execution tool for code projects",
   "homepage": "https://github.com/Nubos-AI/nubos-pilot",
   "repository": {

package/workflows/execute-phase.md

@@ -102,99 +102,52 @@ if [ "$TOTAL_TASKS" = "0" ]; then
 fi
 ```
 
-## Nubosloop (per task)
+## Execution — per-task Nubosloop, slices serial
 
-Every task runs through the Nubosloop ([ADR-0010](../docs/adr/0010-nubosloop.md), `lib/nubosloop.cjs`). The loop terminates only on (a) zero Critic-Schwarm findings followed by an atomic commit, or (b) the orchestrator-enforced `loop.maxRounds` cap (default `3`), in which case the task transitions to `stuck` and the orchestrator escalates via `askuser`.
+Every task runs through the **Nubosloop** ([ADR-0010](../docs/adr/0010-nubosloop.md), `lib/nubosloop.cjs`) — pre-flight cache lookup → researcher-schwarm (on miss) → executor or build-fixer → mechanical checks + tool-use audit → critic-schwarm → route. The loop terminates only on (a) `loop-evaluate.next_action == "commit"` (zero blocking findings) followed by `commit-task` (atomic commit per ADR-0004), or (b) `loop.maxRounds` cap (default `3`) reached → `loop-run-round --phase stuck` writes the marker, dashboard surfaces it, orchestrator escalates via `askuser`. Single-pass `executor → commit-task` is forbidden — the loop is the only sanctioned path.
 
-**Agent-native driver:** the per-task state machine is exposed through `node .nubos-pilot/bin/np-tools.cjs loop-run-round <task-id> --phase <phase>`. Every non-LLM transition lives in this verb; LLM spawns (researcher, executor, critics) remain extern and feed their results back as `--query` / `--verify-exit-code` / `--critic-outputs` arguments. A non-LLM runtime can drive the loop with five shell-outs per round.
+**Wave shape (slices serial, tasks parallel within a slice):**
 
-**Per task, per round:**
-
-1. **Pre-flight** — agent-native CLI: `node .nubos-pilot/bin/np-tools.cjs loop-preflight --query "$TASK_QUERY" --threshold $THRESHOLD --min-occurrence $MIN_OCC`. Output is `{hit, bypass_swarm, cache_miss_reason}`. A hit at similarity ≥ `swarm.research.threshold` and `occurrence ≥ swarm.research.minOccurrence` short-circuits the Researcher-Schwarm; the cached pattern enters the Executor's prompt with provenance `[CACHED]`. Soft cache failures (mcp-not-implemented, adapter-unknown) downgrade to a miss with `cache_miss_reason` populated; hard failures (corrupt store, version mismatch) propagate.
-2. **Researcher-Schwarm (on demand)** — when no cached pattern exists, the orchestrator spawns `swarm.research.k=3` independent `np-researcher` agents in parallel and merges their outputs through `lib/researcher-swarm.cjs::mergeConsensus` (Mehrheit / Union / Schnittmenge). The merged consensus enters the Executor's prompt.
-3. **Executor (or Build-Fixer on Round ≥ 2)** — single `np-executor` spawn writes code in scope. Round 2+ uses `np-build-fixer` with the prior Critic findings + verify output appended to its prompt.
-4. **Mechanical Checks** — the orchestrator (NOT the agent) runs the task's `verify` command, plus stack-specific linters (`phpstan`, `pint`, `tsc`, `eslint`), plus a tool-use audit confirming the agent invoked `search-knowledge` or `match-existing-learning` at least once. Red ⇒ findings route back to Step 3.
-5. **Critic-Schwarm** — three Critic agents spawn in parallel (`agents/np-critic-style.md` haiku, `agents/np-critic-tests.md` sonnet, `agents/np-critic-acceptance.md` sonnet). Each emits structured findings JSON.
-6. **Route + Loop or Commit** — the orchestrator merges + decides next-action via the agent-native CLI:
-
-   ```bash
-   ROUND=$(node .nubos-pilot/bin/np-tools.cjs loop-state-read "$TASK_ID" | node -e 'process.stdin.on("data",d=>{const s=JSON.parse(d);console.log((s&&s.round)||1)})')
-   EVAL=$(node .nubos-pilot/bin/np-tools.cjs loop-evaluate \
-     --round "$ROUND" --max-rounds "$LOOP_MAX_ROUNDS" \
-     --json "$CRITIC_OUTPUTS_JSON")
-   NEXT=$(echo "$EVAL" | node -e 'process.stdin.on("data",d=>console.log(JSON.parse(d).next_action))')
-   ```
-
-   `next_action` ∈ `{commit, executor, researcher, askuser, plan-checker, stuck}`. Routing rules:
-   - `executor` — Style / Bug / Test / Acceptance findings → spawn `np-build-fixer` on Round ≥ 2.
-   - `researcher` — `information-missing` findings → re-run Researcher-Schwarm with the gap as input.
-   - `askuser` — `question-to-user` findings → block on user reply.
-   - `plan-checker` — `locked-decision-violation` → orchestrator escalation.
-   - `commit` — zero findings → atomic commit per ADR-0004 + auto-`learning-log`.
-   - `stuck` — `loop.maxRounds` reached → `loop-stuck $TASK_ID --reason ... --findings ...`.
-
-**End-to-end round (single CLI surface):**
-
-```bash
-# Step 1 — preflight cache lookup (advances round counter, stamps cache_hit)
-node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase preflight \
-  --query "$TASK_QUERY"
-
-# Step 2 — LLM spawns (researcher swarm if no cache hit, then executor) run extern.
-
-# Step 3 — after executor commits draft, signal verify result
-node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase post-executor \
-  --verify-exit-code "$VERIFY_EXIT" --verify-output-path "$VERIFY_LOG"
+1. Dispatch **all tasks in the slice in parallel** — each task is one independent Nubosloop instance.
+2. Wait until every task in the slice committed OR is `stuck` OR hit `plan-checker`.
+3. If any task is `stuck` or hit `plan-checker` → stop the wave and exit non-zero. Previously committed tasks remain committed.
+4. Move to the next slice.
 
-# Step 4 — LLM spawns (critic schwarm) run extern.
+**Per-task driver (single agent-native CLI surface):** `node .nubos-pilot/bin/np-tools.cjs loop-run-round <task-id> --phase <preflight|post-executor|post-critics|commit|stuck>`. Every non-LLM transition lives in this verb; LLM spawns (researcher, executor / build-fixer, critics) remain extern and feed their results back via `--query` / `--verify-exit-code` / `--critic-outputs`. A non-LLM runtime can drive the loop with five shell-outs per round.
 
-# Step 5 — feed critic outputs into the routing engine
-node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase post-critics \
-  --critic-outputs "$CRITIC_JSON"
+**Per-task, per-round protocol:**
 
-# Step 6 — depending on next_action: commit OR stuck OR back to step 2/4
-node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase commit \
-  --learning-pattern "$CONSENSUS_PATTERN" --learning-outcome verified
-```
+1. **Pre-flight cache lookup** (Round 1 only) — `loop-run-round --phase preflight --query "$TASK_QUERY"`. A hit at similarity ≥ `swarm.research.threshold` and `occurrence ≥ swarm.research.minOccurrence` short-circuits the Researcher-Schwarm; the cached pattern enters the Executor prompt with provenance `[CACHED]`. Soft cache failures (mcp-not-implemented, adapter-unknown) downgrade to a miss with `cache_miss_reason` populated; hard failures (corrupt store, version mismatch) propagate.
+2. **Researcher-Schwarm (on cache miss, or on `next_action=researcher` re-route)** — orchestrator spawns `swarm.research.k=3` independent `np-researcher` agents IN PARALLEL (single message, three Agent blocks) and merges their outputs through `lib/researcher-swarm.cjs::mergeConsensus` (Mehrheit / Union / Schnittmenge). The merged consensus enters the Executor prompt with provenance.
+3. **Executor (R1) or Build-Fixer (R≥2)** — single LLM spawn. Round 1 spawns `agents/np-executor.md`. Round ≥ 2 spawns `agents/np-build-fixer.md` with prior critic findings + verify output appended. Edits ONLY paths in `files_modified` (D-04 — no scope expansion). Does NOT call `commit-task`.
+4. **Mechanical Checks (orchestrator, NOT the agent)** — run task's `<verify>` command + stack linters (`phpstan`, `pint`, `tsc`, `eslint`); capture exit code + output to `$VERIFY_LOG`. Then `loop-audit-tool-use --task-id ... --round ...` confirms the spawn invoked `search-knowledge` or `match-existing-learning` ≥ 1× (Rule 9). Audit findings get round-stamped and feed `loop-evaluate` alongside critic findings. Then call `loop-run-round --phase post-executor --verify-exit-code "$VERIFY_EXIT" --verify-output-path "$VERIFY_LOG"`. On verify-red the verb returns `next_action: spawn-build-fixer` — skip critics, advance to next round directly.
+5. **Critic-Schwarm (verify-green only)** — three Critic agents spawn IN PARALLEL (single message, three Agent blocks): `agents/np-critic-style.md` (haiku), `agents/np-critic-tests.md` (sonnet), `agents/np-critic-acceptance.md` (sonnet). Each emits structured findings JSON.
+6. **Route** — `loop-run-round --phase post-critics --critic-outputs "$CRITIC_JSON"` returns `next_action ∈ {commit, executor, researcher, askuser, plan-checker, stuck}`:
 
-**Per-round state persistence** (lower-level primitives, available for ad-hoc updates):
+   | `next_action`    | Trigger                            | Action                                                          |
+   |------------------|------------------------------------|-----------------------------------------------------------------|
+   | `commit`         | Zero blocking findings             | `loop-run-round --phase commit` + `commit-task` (atomic)        |
+   | `executor`       | Style/Bug/Test/Acceptance findings | R≥2: spawn `np-build-fixer` with prior findings (next round)    |
+   | `researcher`     | `information-missing` finding      | Re-run Researcher-Schwarm with the gap as input (next round)    |
+   | `askuser`        | `question-to-user` finding         | Block on user reply via `askuser`; resume same round            |
+   | `plan-checker`   | `locked-decision-violation`        | Abort wave; orchestrator escalates                              |
+   | `stuck`          | `loop.maxRounds` reached           | `loop-run-round --phase stuck` + dashboard + askuser escalation |
 
-```bash
-node .nubos-pilot/bin/np-tools.cjs loop-state-record "$TASK_ID" \
-  --json "$(printf '{"round":%s,"last_action":"%s","findings":%s}' "$ROUND" "$NEXT" "$FINDINGS_JSON")"
-```
+7. **Commit** — `loop-run-round --phase commit --learning-pattern "$CONSENSUS_PATTERN" --learning-outcome verified` stamps the checkpoint to `pre-commit` and auto-logs the learning (when `auto_log_learning=true`, default — feeds future Round-1 cache hits). Then `node .nubos-pilot/bin/np-tools.cjs commit-task "$TASK_ID"` performs the atomic commit per ADR-0004.
 
-**Auto-`log-learning`** on commit (when `auto_log_learning=true`, default):
+**Per-task loop control values (read once at wave start):**
 
 ```bash
-node .nubos-pilot/bin/np-tools.cjs learning-log \
-  --pattern "$CONSENSUS_PATTERN" --outcome verified \
-  --task-id "$TASK_ID" --milestone-id "$MILESTONE_ID"
-```
-
-Future similar tasks hit the cache and bypass the Researcher-Schwarm at Step 1.
-
-```bash
-# Per-task loop control values (read once from config)
 LOOP_MAX_ROUNDS=$(node .nubos-pilot/bin/np-tools.cjs config-get loop.maxRounds 2>/dev/null || echo 3)
 SWARM_K=$(node .nubos-pilot/bin/np-tools.cjs config-get swarm.research.k 2>/dev/null || echo 3)
+SWARM_THRESHOLD=$(node .nubos-pilot/bin/np-tools.cjs config-get swarm.research.threshold 2>/dev/null || echo 0.9)
+SWARM_MIN_OCC=$(node .nubos-pilot/bin/np-tools.cjs config-get swarm.research.minOccurrence 2>/dev/null || echo 3)
 AUTO_LOG_LEARNING=$(node .nubos-pilot/bin/np-tools.cjs config-get auto_log_learning 2>/dev/null || echo true)
 ```
 
-On `next_action == "stuck"`, `loop-stuck` writes the `stuck` marker into both the per-task `nubosloop` block and the checkpoint envelope, surfaces it on `np:dashboard`, and the orchestrator prompts the operator via `askuser`: continue with manual override, escalate to a human developer, or `np:reset-slice` and re-plan.
-
-## Execution — slices serial, tasks parallel within a slice
-
-For each wave (slice) in `waves[]`, in order:
-
-1. Dispatch **all tasks in the slice in parallel** (one Nubosloop per task — see above).
-2. Wait until every task in the slice is committed OR one failed OR `stuck`.
-3. If any task failed or is `stuck` → stop the wave and exit non-zero. Previous committed tasks remain committed.
-4. Move to the next slice.
+**Wave + per-task pseudocode (this is the executable shape — the orchestrator drives this verbatim, not just „shape but not concrete syntax"):**
 
 ```bash
-# Pseudocode for the per-wave loop. The orchestrator uses its parallel-spawn
-# primitive; this pseudocode shows the shape but not the concrete agent syntax.
 for WAVE_INDEX in 0 1 2 ...; do
   WAVE=$(echo "$INIT" | node -e "process.stdin.on('data', d => console.log(JSON.stringify(JSON.parse(d).waves[$WAVE_INDEX])))")
   [ -z "$WAVE" ] || [ "$WAVE" = "undefined" ] && break
@@ -205,10 +158,9 @@ for WAVE_INDEX in 0 1 2 ...; do
   echo "=== Wave $((WAVE_INDEX+1)): $SLICE_FULL_ID — tasks: $TASK_IDS ===" >&2
 
   # Worktree-Isolation (ADR-0008): when workflow.worktree_isolation=true,
-  # create an isolated git worktree for this slice before spawning executors.
-  # Executors run inside the worktree (cwd = worktree path), commits land on
-  # the slice branch np/<slice-full-id>, and the slice is fast-forward merged
-  # back on success. On failure: worktree stays in place for inspection.
+  # create an isolated git worktree for this slice. Nubosloop instances
+  # run inside the worktree (cwd = worktree path); commits land on the
+  # slice branch np/<slice-full-id>; FF-merged back on success.
   SLICE_CWD="$PWD"
   if [ "$WORKTREE_ISOLATION" = "true" ]; then
     WT_CREATE=$(node .nubos-pilot/bin/np-tools.cjs worktree-create "$SLICE_FULL_ID")
@@ -216,27 +168,120 @@ for WAVE_INDEX in 0 1 2 ...; do
     echo "[np:execute-phase] worktree created at $SLICE_CWD (branch np/$SLICE_FULL_ID)" >&2
   fi
 
-  # For each task id in TASK_IDS, spawn an executor IN PARALLEL.
-  # The orchestrator's parallel primitive dispatches all of them in a single
-  # message (multiple Agent tool use blocks in one send).
+  # PARALLEL DISPATCH per task — one Nubosloop instance per task.
+  # The orchestrator's parallel primitive dispatches each task's loop
+  # body in a single message (one Agent block per task per LLM step).
   for TASK_ID in $TASK_IDS; do
-    # IN PARALLEL:
-    node .nubos-pilot/bin/np-tools.cjs checkpoint start "$TASK_ID" --phase "$PHASE" --plan "$SLICE_FULL_ID" --wave "$((WAVE_INDEX+1))"
+    # IN PARALLEL across tasks in the slice:
+
+    node .nubos-pilot/bin/np-tools.cjs checkpoint start "$TASK_ID" \
+      --phase "$PHASE" --plan "$SLICE_FULL_ID" --wave "$((WAVE_INDEX+1))"
 
     TASK_JSON=$(node .nubos-pilot/bin/np-tools.cjs init execute-milestone execute-task "$PHASE" "$TASK_ID")
     if [[ "$TASK_JSON" == @file:* ]]; then TASK_JSON=$(cat "${TASK_JSON#@file:}"); fi
+    TASK_QUERY=$(echo "$TASK_JSON" | node -e "process.stdin.on('data', d => { const j=JSON.parse(d); console.log(j.query || j.name || ''); })")
 
     EXECUTOR_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
-    EXECUTOR_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-executor --profile frontier)
+    CONSENSUS_PATTERN=""
+    NEXT_ACTION=""
+    CACHE_HIT="false"
+    ROUND=1
+
+    while [ "$ROUND" -le "$LOOP_MAX_ROUNDS" ]; do
+
+      # === Step 1: pre-flight cache lookup (Round 1 only) ===
+      if [ "$ROUND" -eq 1 ]; then
+        PREFLIGHT=$(node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
+          --phase preflight --query "$TASK_QUERY")
+        CACHE_HIT=$(echo "$PREFLIGHT" | node -e 'process.stdin.on("data",d=>console.log(JSON.parse(d).hit||false))')
+      fi
 
-    # Spawn agents/np-executor.md (tier: sonnet, model resolved as $EXECUTOR_MODEL)
-    # with a <files_to_read> block containing: the task plan file, the slice
-    # plan file, prior slice SUMMARY files, milestone CONTEXT.md.
-    # Executor edits EXACTLY the paths in files_modified (D-04 — no scope
-    # expansion), runs <verify> commands, then invokes commit-task:
+      # === Step 2: Researcher-Schwarm (cache miss on R1, or re-route on R≥2) ===
+      # PARALLEL spawn of $SWARM_K agents/np-researcher.md (single message,
+      # $SWARM_K Agent blocks). Merge via lib/researcher-swarm.cjs::mergeConsensus.
+      # Result is injected into the next executor prompt as $CONSENSUS_PATTERN
+      # with provenance ([VERIFIED] on majority + spawn-citation, else [PROVISIONAL]).
+      if { [ "$ROUND" -eq 1 ] && [ "$CACHE_HIT" != "true" ]; } || [ "$NEXT_ACTION" = "researcher" ]; then
+        CONSENSUS_PATTERN="<merged consensus from $SWARM_K researchers>"
+      elif [ "$CACHE_HIT" = "true" ] && [ -z "$CONSENSUS_PATTERN" ]; then
+        CONSENSUS_PATTERN="<cached pattern from preflight ([CACHED] provenance)>"
+      fi
+
+      # === Step 3: Executor (R1) or Build-Fixer (R≥2) — LLM spawn extern ===
+      if [ "$ROUND" -eq 1 ]; then
+        EXECUTOR_AGENT="np-executor"
+      else
+        EXECUTOR_AGENT="np-build-fixer"
+      fi
+      EXECUTOR_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model "$EXECUTOR_AGENT" --profile frontier)
+      # Spawn agents/${EXECUTOR_AGENT}.md (model resolved as $EXECUTOR_MODEL) with:
+      #   - <files_to_read>: task plan, slice plan, prior slice SUMMARYs, CONTEXT.md
+      #   - $CONSENSUS_PATTERN with provenance
+      #   - On Round ≥ 2: prior critic findings + verify output excerpt
+      #   - $LANG_DIRECTIVE + $AGENT_SKILLS_EXECUTOR (skill triggers from §Skills mapping)
+      # Agent edits ONLY paths in files_modified (D-04). Does NOT call commit-task.
+
+      node .nubos-pilot/bin/np-tools.cjs checkpoint transition "$TASK_ID" verifying
+
+      # === Step 4: Mechanical Checks + tool-use audit (orchestrator-side) ===
+      VERIFY_LOG="${TMPDIR:-/tmp}/np-verify-${TASK_ID}-r${ROUND}.log"
+      # Orchestrator (NOT the agent) runs the task's <verify> command + stack
+      # linters; redirect stdout+stderr to $VERIFY_LOG.
+      VERIFY_EXIT=$?
+      node .nubos-pilot/bin/np-tools.cjs loop-audit-tool-use "$TASK_ID" \
+        --round "$ROUND" --agent "$EXECUTOR_AGENT"
+
+      POST_EXEC=$(node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
+        --phase post-executor \
+        --verify-exit-code "$VERIFY_EXIT" --verify-output-path "$VERIFY_LOG")
+      POST_EXEC_NEXT=$(echo "$POST_EXEC" | node -e 'process.stdin.on("data",d=>console.log(JSON.parse(d).next_action))')
+
+      # Verify-red short-circuits to build-fixer next round (skip critics).
+      if [ "$POST_EXEC_NEXT" = "spawn-build-fixer" ]; then
+        ROUND=$((ROUND+1))
+        continue
+      fi
 
-    node .nubos-pilot/bin/np-tools.cjs checkpoint transition "$TASK_ID" verifying
-    node .nubos-pilot/bin/np-tools.cjs checkpoint transition "$TASK_ID" pre-commit
+      # === Step 5: Critic-Schwarm — three agents in PARALLEL ===
+      # Spawn IN PARALLEL (single message, three Agent blocks):
+      #   - agents/np-critic-style.md       (haiku)  → CRITIC_STYLE_JSON
+      #   - agents/np-critic-tests.md       (sonnet) → CRITIC_TESTS_JSON
+      #   - agents/np-critic-acceptance.md  (sonnet) → CRITIC_ACCEPTANCE_JSON
+      CRITIC_OUTPUTS_JSON=$(printf '[%s,%s,%s]' "$CRITIC_STYLE_JSON" "$CRITIC_TESTS_JSON" "$CRITIC_ACCEPTANCE_JSON")
+
+      # === Step 6: Route via loop-evaluate (post-critics) ===
+      POST_CRIT=$(node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
+        --phase post-critics --critic-outputs "$CRITIC_OUTPUTS_JSON")
+      NEXT_ACTION=$(echo "$POST_CRIT" | node -e 'process.stdin.on("data",d=>console.log(JSON.parse(d).next_action))')
+
+      case "$NEXT_ACTION" in
+        commit)        break ;;
+        executor)      ROUND=$((ROUND+1)); continue ;;
+        researcher)    ROUND=$((ROUND+1)); continue ;;
+        askuser)       # spec from POST_CRIT.routing — block on user reply,
+                       # then resume the same round (no ROUND increment).
+                       node .nubos-pilot/bin/np-tools.cjs askuser --json "$ASKUSER_SPEC"
+                       continue ;;
+        plan-checker)  echo "[np:execute-phase] $TASK_ID hit locked-decision-violation — see loop-state for details." >&2
+                       exit 2 ;;
+        stuck)         node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
+                         --phase stuck --reason "max-rounds" --findings "$CRITIC_OUTPUTS_JSON"
+                       echo "[np:execute-phase] $TASK_ID stuck after $LOOP_MAX_ROUNDS rounds." >&2
+                       exit 3 ;;
+      esac
+    done
+
+    # Defensive: if the while loop exited without NEXT_ACTION=commit (shouldn't
+    # happen — loop-evaluate emits stuck at maxRounds), stamp stuck and bail.
+    if [ "$NEXT_ACTION" != "commit" ]; then
+      node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
+        --phase stuck --reason "loop-exited-without-commit"
+      exit 3
+    fi
+
+    # === Step 7: atomic commit ===
+    node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase commit \
+      --learning-pattern "$CONSENSUS_PATTERN" --learning-outcome verified
     node .nubos-pilot/bin/np-tools.cjs commit-task "$TASK_ID"
     COMMIT_STATUS=$?
 
@@ -244,11 +289,11 @@ for WAVE_INDEX in 0 1 2 ...; do
     EXECUTOR_STATUS=ok
     [ "$COMMIT_STATUS" -ne 0 ] && EXECUTOR_STATUS=error
     node .nubos-pilot/bin/np-tools.cjs metrics record \
-      --agent np-executor --tier sonnet --resolved-model "$EXECUTOR_MODEL" \
+      --agent "$EXECUTOR_AGENT" --tier sonnet --resolved-model "$EXECUTOR_MODEL" \
       --phase "$PHASE" --plan "$SLICE_FULL_ID" --task "$TASK_ID" \
       --started "$EXECUTOR_START" --ended "$EXECUTOR_END" \
       --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
-      --retry-count "${RETRY_COUNT:-0}" --status "$EXECUTOR_STATUS" --runtime "$RUNTIME"
+      --retry-count "$((ROUND-1))" --status "$EXECUTOR_STATUS" --runtime "$RUNTIME"
 
     if [ "$COMMIT_STATUS" -ne 0 ]; then
       echo "[np:execute-phase] commit-task failed for $TASK_ID — aborting wave $SLICE_FULL_ID." >&2
@@ -258,7 +303,7 @@ for WAVE_INDEX in 0 1 2 ...; do
       exit "$COMMIT_STATUS"
     fi
   done
-  # wait for all parallel executors in this wave to finish before next wave
+  # Wait for all parallel Nubosloop instances in this wave to finish before next wave.
 
   # After every task in the slice committed: aggregate per-task summaries into
   # the slice-level S<NNN>-SUMMARY.md so /np:validate-phase can audit it.
@@ -294,16 +339,26 @@ After every slice completes, point the operator at `/np:validate-phase $PHASE` t
 
 <!-- scope_guardrail -->
 **Do:**
-- Dispatch all tasks in a slice **in parallel** (one executor per task).
-- Move to next slice **only after** every task in the current slice is committed.
-- Start one checkpoint per task before spawning the executor agent.
-- Spawn `agents/np-executor.md` once per task with only that task's `files_modified` in scope.
+- Dispatch all tasks in a slice **in parallel** — one Nubosloop instance per task.
+- Move to next slice **only after** every task in the current slice committed (or `stuck`/`plan-checker` aborted the wave).
+- Start one checkpoint per task before kicking off the loop.
+- Run `loop-run-round --phase preflight` BEFORE every Round-1 executor spawn — never skip the cache lookup.
+- Spawn `agents/np-executor.md` on Round 1, `agents/np-build-fixer.md` on Round ≥ 2 — once per round, with only that task's `files_modified` in scope (D-04, no scope expansion).
+- Spawn the three Critic agents (`np-critic-style`, `np-critic-tests`, `np-critic-acceptance`) IN PARALLEL — single message, three Agent blocks per task per round.
+- Run `loop-run-round --phase post-executor` AFTER mechanical checks; honor `next_action: spawn-build-fixer` (verify-red short-circuit, skip critics this round).
+- Run `loop-run-round --phase post-critics` AFTER critics return, to obtain the routing `next_action`.
+- Run `loop-audit-tool-use` per round per spawn — Rule 9 (search-knowledge / match-existing-learning) is mechanically enforced.
 - Route every commit through `node .nubos-pilot/bin/np-tools.cjs commit-task` so `assertCommittablePaths` (D-25) runs.
-- Hard-stop the wave when `commit-task` returns a non-zero exit.
+- Hard-stop the wave when `commit-task` returns non-zero, OR a task hits `stuck`/`plan-checker`.
 
 **Don't:**
 - Run tasks across slices in parallel — slices are serial.
 - Run intra-slice tasks serially — they're parallel by planner contract.
+- Skip the Nubosloop and call `commit-task` directly after the executor (single-pass executor → commit is forbidden — ADR-0010).
+- Spawn the Critic agents serially — they MUST run in parallel (single message, three Agent blocks).
+- Use `np-executor` on Round ≥ 2 — use `np-build-fixer` (it gets prior critic findings + verify output excerpt).
+- Skip `loop-audit-tool-use` — Rule 9 violations must surface as `rule-9-violation` findings, not be silenced.
+- Extend a task's scope beyond `files_modified` — D-04 violations route to `plan-checker`, not post-hoc PLAN.md mutations.
 - Invoke `git commit`, `git add`, or any bare git command from this workflow or the spawned agent (CLAUDE.md §Git operations).
 - Bundle two tasks into one commit (ADR-0004 atomicity).
 - Skip the checkpoint start step — it's the crash-safety primitive `resume-work` depends on.
@@ -313,18 +368,22 @@ After every slice completes, point the operator at `/np:validate-phase $PHASE` t
 ## Output
 
 - One git commit per completed task (`task(<milestone-id>-<slice-id>-T<NNNN>): <name>`).
-- Per-task checkpoint lifetime: `start` → (`transition verifying|pre-commit`)+ → `deleteCheckpoint` (inside commit-task on success).
+- Per-task checkpoint lifetime: `start` → (`transition verifying`)+ → `pre-commit` (set by `loop-run-round --phase commit`) → `deleteCheckpoint` (inside commit-task on success).
+- Per-task `nubosloop` state block on the checkpoint envelope: `last_phase`, `last_action`, `round`, `findings`, `committed_at` / `stuck_at` — surfaced on `np:dashboard`.
+- Auto-`learning-log` entry per committed task (when `auto_log_learning=true`, default) — feeds future Round-1 cache hits.
 - STATE.md updated via `startTask`'s coordinated lock-cycle (D-08).
-- Per slice: updated `S<NNN>-SUMMARY.md` aggregated from task summaries (triggered by the executor agent after the last task in a wave).
+- Per slice: updated `S<NNN>-SUMMARY.md` aggregated from task summaries (triggered after the last task in the wave).
 - Verified work surface for `/np:validate-phase $PHASE`.
+
 ## Definition of Done
 
 This workflow exits successfully only when, per [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md):
 
-- Rule 1 (Do the whole thing) — every task in every slice committed; no partial slices left.
-- Rule 3 (Do it with tests) — every commit ships verify-green; commits without verify transitions are refused by `commit-task`.
-- Rule 4 (Do it with documentation) — `update-docs` ran for every committed task; stale module docs fail the workflow.
-- Rule 10 (Test before shipping) — verify-green is a hard gate, not advice.
-- Rule 12 (Boil the ocean) — no task left in `stuck` state; the orchestrator escalates rather than silently downgrading.
+- Rule 1 (Do the whole thing) — every task in every slice ran its Nubosloop to `next_action=commit` and committed; no partial slices, no `stuck` left silent.
+- Rule 3 (Do it with tests) — every commit ships verify-green; mechanical checks per round are a hard gate; `commit-task` refuses commits without a `verifying` → `pre-commit` transition.
+- Rule 4 (Do it with documentation) — `update-docs` ran for every committed task; stale module docs surface as a `np-critic-acceptance` finding and route the loop back, not forward.
+- Rule 9 (Tool-use audit) — `loop-audit-tool-use` confirms every spawn invoked `search-knowledge` or `match-existing-learning` ≥ 1×; violations route as `rule-9-violation` findings into `loop-evaluate`.
+- Rule 10 (Test before shipping) — verify-green is a hard gate per round, not advice.
+- Rule 12 (Boil the ocean) — no task left in `stuck` state; the orchestrator escalates via askuser rather than silently downgrading or retrying past `loop.maxRounds`.
 
 Any violation = workflow exits non-zero. The orchestrator does not relax these.