nubos-pilot 1.3.3 → 1.3.5

package/bin/np-tools/loop-commands.test.cjs

@@ -426,6 +426,125 @@ function _seedSpawnEvidence(taskId, round, agents, cwd) {
   }
 }
 
+test('LCLI-RR-2a: phase=post-architect refuses without np-task-architect spawn audit', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  require('../../lib/nubosloop.cjs').recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  const loopRunRound = require('./loop-run-round.cjs');
+  await assert.rejects(
+    () => loopRunRound.run(
+      ['M001-S001-T0001', '--phase', 'post-architect'],
+      { cwd: r, stdout: _cap().stub },
+    ),
+    (err) => err && err.code === 'loop-post-architect-missing-spawn-audit',
+  );
+});
+
+test('LCLI-RR-2b: phase=post-architect with stamp → spawn-test-writer, no round bump', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  _seedSpawnEvidence('M001-S001-T0001', 1, ['np-task-architect'], r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(['M001-S001-T0001', '--phase', 'post-architect'], { cwd: r, stdout: cap.stub });
+  const out = JSON.parse(cap.get());
+  assert.equal(out.phase, 'post-architect');
+  assert.equal(out.next_action, 'spawn-test-writer');
+  const cp = checkpoint.readCheckpoint('M001-S001-T0001', r);
+  assert.equal(cp.nubosloop.last_phase, 'post-architect');
+  assert.equal(cp.nubosloop.round, 1, 'prep step must not bump the round counter');
+});
+
+test('LCLI-RR-2c: phase=post-architect --force-post-architect bypasses the audit gate', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  require('../../lib/nubosloop.cjs').recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(
+    ['M001-S001-T0001', '--phase', 'post-architect', '--force-post-architect'],
+    { cwd: r, stdout: cap.stub },
+  );
+  const out = JSON.parse(cap.get());
+  assert.equal(out.forced, true);
+  assert.equal(out.next_action, 'spawn-test-writer');
+});
+
+test('LCLI-RR-2d: phase=post-test-writer refuses without np-test-writer spawn audit', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  require('../../lib/nubosloop.cjs').recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  const loopRunRound = require('./loop-run-round.cjs');
+  await assert.rejects(
+    () => loopRunRound.run(
+      ['M001-S001-T0001', '--phase', 'post-test-writer'],
+      { cwd: r, stdout: _cap().stub },
+    ),
+    (err) => err && err.code === 'loop-post-test-writer-missing-spawn-audit',
+  );
+});
+
+test('LCLI-RR-2e: phase=post-test-writer with stamp → spawn-executor, no round bump', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  _seedSpawnEvidence('M001-S001-T0001', 1, ['np-test-writer'], r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(['M001-S001-T0001', '--phase', 'post-test-writer'], { cwd: r, stdout: cap.stub });
+  const out = JSON.parse(cap.get());
+  assert.equal(out.phase, 'post-test-writer');
+  assert.equal(out.next_action, 'spawn-executor');
+  const cp = checkpoint.readCheckpoint('M001-S001-T0001', r);
+  assert.equal(cp.nubosloop.last_phase, 'post-test-writer');
+  assert.equal(cp.nubosloop.round, 1);
+});
+
+test('LCLI-RR-2f: phase=post-test-writer --tests records the written paths in nubosloop.tdd_tests', async () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  _seedSpawnEvidence('M001-S001-T0001', 1, ['np-test-writer'], r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(
+    ['M001-S001-T0001', '--phase', 'post-test-writer', '--tests', 'tests/a.test.ts, tests/b.test.ts'],
+    { cwd: r, stdout: cap.stub },
+  );
+  const out = JSON.parse(cap.get());
+  assert.deepEqual(out.tdd_tests, ['tests/a.test.ts', 'tests/b.test.ts']);
+  const cp = checkpoint.readCheckpoint('M001-S001-T0001', r);
+  assert.deepEqual(cp.nubosloop.tdd_tests, ['tests/a.test.ts', 'tests/b.test.ts']);
+});
+
+test('LCLI-RR-2g: post-researcher next_action skips disabled prep steps (architect off → test-writer)', async () => {
+  const r = _mkRoot();
+  fs.writeFileSync(
+    path.join(r, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ agents: { architect: false } }),
+    'utf-8',
+  );
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  _seedSpawnEvidence('M001-S001-T0001', 1, ['np-researcher', 'np-researcher', 'np-researcher'], r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(['M001-S001-T0001', '--phase', 'post-researcher'], { cwd: r, stdout: cap.stub });
+  assert.equal(JSON.parse(cap.get()).next_action, 'spawn-test-writer');
+});
+
+test('LCLI-RR-2h: post-researcher next_action → executor when both prep steps are off', async () => {
+  const r = _mkRoot();
+  fs.writeFileSync(
+    path.join(r, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ agents: { architect: false, test_writer: false } }),
+    'utf-8',
+  );
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  _seedSpawnEvidence('M001-S001-T0001', 1, ['np-researcher', 'np-researcher', 'np-researcher'], r);
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  await loopRunRound.run(['M001-S001-T0001', '--phase', 'post-researcher'], { cwd: r, stdout: cap.stub });
+  assert.equal(JSON.parse(cap.get()).next_action, 'spawn-executor');
+});
+
 test('LCLI-RR-3: loop-run-round phase=post-executor with verify-green → spawn-critic-schwarm', async () => {
   const r = _mkRoot();
   checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
@@ -1184,7 +1303,7 @@ test('LCLI-RR-35: post-researcher accepts when k=3 np-researcher audits exist (T
     { cwd: r, stdout: cap.stub },
   );
   const out = JSON.parse(cap.get());
-  assert.equal(out.next_action, 'spawn-executor');
+  assert.equal(out.next_action, 'spawn-architect');
   assert.equal(out.forced, false);
   assert.equal(out.expected_researcher_count, 3);
 });
@@ -1207,7 +1326,7 @@ test('LCLI-RR-35b: post-researcher k-gate honors swarm.research.k config (Gap #6
   );
   const out = JSON.parse(cap.get());
   assert.equal(out.expected_researcher_count, 1);
-  assert.equal(out.next_action, 'spawn-executor');
+  assert.equal(out.next_action, 'spawn-architect');
 });
 
 test('LCLI-RR-36: --force-post-researcher bypasses Layer-C gate + stamps flag (T2)', async () => {

package/bin/np-tools/loop-run-round.cjs

@@ -7,6 +7,7 @@ const { NubosPilotError, safeAssign } = require('../../lib/core.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 
 const checkpoint = require('../../lib/checkpoint.cjs');
+const config = require('../../lib/config.cjs');
 const nubosloop = require('../../lib/nubosloop.cjs');
 const messaging = require('../../lib/messaging.cjs');
 const compress = require('../../lib/compress.cjs');
@@ -40,6 +41,8 @@ function _verifyExcerpt(verifyOutput, cwd) {
 const VALID_PHASES = new Set([
   'preflight',
   'post-researcher',
+  'post-architect',
+  'post-test-writer',
   'post-executor',
   'post-critics',
   'commit',
@@ -153,13 +156,124 @@ function _runPostResearcher(taskId, list, cwd) {
   );
   return {
     phase: 'post-researcher',
-    next_action: 'spawn-executor',
+    next_action: _nextAfterResearcher(cwd),
     forced: force,
     expected_researcher_count: expectedK,
     round: merged.nubosloop ? merged.nubosloop.round : null,
   };
 }
 
+// Round-1 preparation steps (architect, test-writer) that run between the
+// researcher swarm and the executor. Each verifies its spawn was stamped via
+// `loop-audit-tool-use` (Layer-C SKIP-GUARD) and records last_phase. They never
+// bump the round counter — TDD writes tests once; build-fixer rounds iterate.
+// Config-gated in the orchestrator: when agents.architect / agents.test_writer
+// is off the step (and this phase) is simply never invoked.
+function _checkPrepSpawnAudited(taskId, list, cwd, agent, forceFlag) {
+  const force = list.includes(forceFlag);
+  const cur = checkpoint.readCheckpoint(taskId, cwd) || {};
+  const round = Number((cur.nubosloop && cur.nubosloop.round)) || 1;
+  const satisfied = force
+    ? true
+    : nubosloop.assertSpawnsAuditedForRound(taskId, [agent], round, cwd).satisfied;
+  return { force, round, satisfied };
+}
+
+function _stampPrepPhase(taskId, cwd, phase, lastAction, forcedKey, force, extraFn) {
+  return checkpoint.mergeCheckpoint(
+    taskId,
+    (curCp) => {
+      const prev = (curCp && curCp.nubosloop) || {};
+      const partial = { last_phase: phase, last_action: lastAction };
+      if (force) partial[forcedKey] = true;
+      if (typeof extraFn === 'function') safeAssign(partial, extraFn(prev));
+      return { nubosloop: safeAssign({}, prev, partial) };
+    },
+    cwd,
+  );
+}
+
+// The round-1 prep steps are config-gated, so the emitted next_action hint must
+// reflect which downstream steps are actually enabled — a consumer driving off
+// the JSON hint (rather than the ACTION CONTRACT prose) must not skip an enabled
+// architect/test-writer or stall on a disabled one.
+function _nextEnabled(cwd, steps) {
+  for (const [path, action] of steps) {
+    if (config.tryReadConfigPath(cwd, path, true, { onWarn() {} })) return action;
+  }
+  return 'spawn-executor';
+}
+
+function _nextAfterResearcher(cwd) {
+  return _nextEnabled(cwd, [['agents.architect', 'spawn-architect'], ['agents.test_writer', 'spawn-test-writer']]);
+}
+
+function _nextAfterArchitect(cwd) {
+  return _nextEnabled(cwd, [['agents.test_writer', 'spawn-test-writer']]);
+}
+
+// `--tests "a, b, c"` → ['a','b','c']; the post-test-writer phase records these
+// (the paths np-test-writer wrote) so commit-task can fold them into the commit.
+function _parseTestPaths(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+  return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function _runPostArchitect(taskId, list, cwd) {
+  const g = _checkPrepSpawnAudited(taskId, list, cwd, 'np-task-architect', '--force-post-architect');
+  if (!g.satisfied) {
+    throw new NubosPilotError(
+      'loop-post-architect-missing-spawn-audit',
+      'phase=post-architect refused: no `loop-audit-tool-use` record for round=' + g.round +
+      ', agent=np-task-architect on ' + taskId + '. ' +
+      'Spawn np-task-architect and call `loop-audit-tool-use ' + taskId +
+      ' --agent np-task-architect --tool-use-log <json>` after the spawn, ' +
+      'or pass --force-post-architect for an explicit override.',
+      { taskId, round: g.round, missing: ['np-task-architect'], required: ['np-task-architect'] },
+    );
+  }
+  const merged = _stampPrepPhase(taskId, cwd, 'post-architect', 'architect-spawned', 'forced_post_architect', g.force);
+  return {
+    phase: 'post-architect',
+    next_action: _nextAfterArchitect(cwd),
+    forced: g.force,
+    round: merged.nubosloop ? merged.nubosloop.round : g.round,
+  };
+}
+
+function _runPostTestWriter(taskId, list, cwd) {
+  const g = _checkPrepSpawnAudited(taskId, list, cwd, 'np-test-writer', '--force-post-test-writer');
+  if (!g.satisfied) {
+    throw new NubosPilotError(
+      'loop-post-test-writer-missing-spawn-audit',
+      'phase=post-test-writer refused: no `loop-audit-tool-use` record for round=' + g.round +
+      ', agent=np-test-writer on ' + taskId + '. ' +
+      'Spawn np-test-writer and call `loop-audit-tool-use ' + taskId +
+      ' --agent np-test-writer --tool-use-log <json>` after the spawn, ' +
+      'or pass --force-post-test-writer for an explicit override.',
+      { taskId, round: g.round, missing: ['np-test-writer'], required: ['np-test-writer'] },
+    );
+  }
+  const testPaths = _parseTestPaths(args.getFlag(list, '--tests'));
+  const merged = _stampPrepPhase(
+    taskId, cwd, 'post-test-writer', 'test-writer-spawned', 'forced_post_test_writer', g.force,
+    (prev) => {
+      const prior = Array.isArray(prev.tdd_tests) ? prev.tdd_tests : [];
+      const seen = new Set(prior);
+      const tdd_tests = prior.slice();
+      for (const p of testPaths) { if (!seen.has(p)) { seen.add(p); tdd_tests.push(p); } }
+      return { tdd_tests };
+    },
+  );
+  return {
+    phase: 'post-test-writer',
+    next_action: 'spawn-executor',
+    forced: g.force,
+    tdd_tests: merged.nubosloop && Array.isArray(merged.nubosloop.tdd_tests) ? merged.nubosloop.tdd_tests : [],
+    round: merged.nubosloop ? merged.nubosloop.round : g.round,
+  };
+}
+
 function _runPostExecutor(taskId, list, cwd) {
   const verifyExitCode = args.getFlag(list, '--verify-exit-code');
   if (verifyExitCode === undefined) {
@@ -557,7 +671,7 @@ async function run(argv, ctx) {
   if (!phase) {
     throw new NubosPilotError(
       'loop-run-round-missing-phase',
-      'loop-run-round requires --phase <preflight|post-researcher|post-executor|post-critics|commit|stuck>',
+      'loop-run-round requires --phase <preflight|post-researcher|post-architect|post-test-writer|post-executor|post-critics|commit|stuck>',
       { hint: 'each phase corresponds to a non-LLM transition between LLM spawns' },
     );
   }
@@ -572,9 +686,11 @@ async function run(argv, ctx) {
   const tail = list.slice(1);
   let result;
   switch (phase) {
-    case 'preflight':       result = await _runPreflight(taskId, tail, cwd); break;
-    case 'post-researcher': result = _runPostResearcher(taskId, tail, cwd); break;
-    case 'post-executor':   result = _runPostExecutor(taskId, tail, cwd); break;
+    case 'preflight':        result = await _runPreflight(taskId, tail, cwd); break;
+    case 'post-researcher':  result = _runPostResearcher(taskId, tail, cwd); break;
+    case 'post-architect':   result = _runPostArchitect(taskId, tail, cwd); break;
+    case 'post-test-writer': result = _runPostTestWriter(taskId, tail, cwd); break;
+    case 'post-executor':    result = _runPostExecutor(taskId, tail, cwd); break;
     case 'post-critics':    result = _runPostCritics(taskId, tail, cwd); break;
     case 'commit':          result = _runCommit(taskId, tail, cwd); break;
     case 'stuck':           result = _runStuck(taskId, tail, cwd); break;

package/lib/agents-registry.cjs

@@ -15,6 +15,14 @@ const BUILD_FIXER_AGENT = 'np-build-fixer';
 
 const RESEARCHER_AGENT = 'np-researcher';
 
+// Round-1 preparation agents that run between the researcher swarm and the
+// executor. Config-gated (agents.architect / agents.test_writer). They get
+// Layer-C spawn-evidence stamps but are NOT Rule-9 audited (not in
+// AUDITED_AGENTS) — the architect is advisory/read-only and the test-writer's
+// quality is enforced downstream by the np-critic-tests axis.
+const TASK_ARCHITECT_AGENT = 'np-task-architect';
+const TEST_WRITER_AGENT = 'np-test-writer';
+
 const AUDITED_AGENTS = Object.freeze([
   EXECUTOR_AGENT,
   BUILD_FIXER_AGENT,
@@ -29,5 +37,7 @@ module.exports = {
   EXECUTOR_AGENT,
   BUILD_FIXER_AGENT,
   RESEARCHER_AGENT,
+  TASK_ARCHITECT_AGENT,
+  TEST_WRITER_AGENT,
   AUDITED_AGENTS,
 };

package/lib/agents.test.cjs

@@ -242,6 +242,8 @@ const NP_AGENTS = [
   { file: 'np-researcher-reconciler', expected_tier: 'sonnet' },
   { file: 'np-codebase-documenter', expected_tier: 'sonnet' },
   { file: 'np-architect', expected_tier: 'sonnet' },
+  { file: 'np-task-architect', expected_tier: 'sonnet' },
+  { file: 'np-test-writer', expected_tier: 'sonnet' },
   { file: 'np-build-fixer', expected_tier: 'sonnet' },
   { file: 'np-security-reviewer', expected_tier: 'sonnet' },
   { file: 'np-nyquist-auditor', expected_tier: 'haiku' },

package/lib/config-defaults.cjs

@@ -18,6 +18,14 @@ const DEFAULT_AGENTS = Object.freeze({
   research: true,
   plan_checker: true,
   verifier: true,
+  // Per-task architecture step in the Nubosloop (np-task-architect). Runs in
+  // round 1 after the researcher swarm, before the test-writer and executor.
+  // Backfilled to true on install/update when absent (see bin/install.js).
+  architect: true,
+  // Per-task TDD step (np-test-writer). Runs in round 1 after the architect,
+  // before the executor — writes the tests the executor must make green.
+  // Backfilled to true on install/update when absent (see bin/install.js).
+  test_writer: true,
   // Economy axis level (off|lite|full|ultra). Default `lite` = prevention-first:
   // the climb-the-ladder discipline is on, the in-loop critic is opt-in (full/ultra).
   // Resolved via lib/economy-mode.cjs; legacy `economy_critic` bool still honoured.

package/lib/config-schema.cjs

@@ -33,6 +33,8 @@ const SCHEMA = Object.freeze({
       research:        { type: 'boolean', optional: true },
       plan_checker:    { type: 'boolean', optional: true },
       verifier:        { type: 'boolean', optional: true },
+      architect:       { type: 'boolean', optional: true },
+      test_writer:     { type: 'boolean', optional: true },
       economy:         { type: 'enum', values: VALID_ECONOMY_MODES, optional: true },
       economy_critic:  { type: 'boolean', optional: true },
     },

package/lib/git.cjs

@@ -58,7 +58,7 @@ function assertCommittablePaths(paths, opts) {
   return committable;
 }
 
-function commitTask(taskId, files, message) {
+function commitTask(taskId, files, message, body) {
   const { committable, ignored } = classifyCommittablePaths(files);
   if (committable.length === 0) {
     if (ignored.length > 0) {
@@ -84,7 +84,11 @@ function commitTask(taskId, files, message) {
     });
   }
   execFileSync('git', ['add', '--', ...committable], { stdio: 'pipe', timeout: GIT_TIMEOUT_MS });
-  execFileSync('git', ['commit', '-m', message, '--', ...committable], { stdio: 'pipe', timeout: GIT_TIMEOUT_MS });
+  const commitArgs = ['commit', '-m', message];
+  if (typeof body === 'string' && body.trim().length > 0) {
+    commitArgs.push('-m', body);
+  }
+  execFileSync('git', [...commitArgs, '--', ...committable], { stdio: 'pipe', timeout: GIT_TIMEOUT_MS });
   return {
     committed: true,
     files_committed: committable.slice(),

package/lib/git.test.cjs

@@ -199,6 +199,34 @@ test('GIT-5: commitTask creates a single commit containing exactly the supplied
   });
 });
 
+test('GIT-5b: commitTask attaches a multi-line body via a second -m when body is supplied', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'lib/git.cjs', '// stub');
+    git.commitTask(
+      'M006-S001-T0001',
+      ['lib/git.cjs'],
+      'task(M006-S001-T0001): add git helper',
+      'Implements the git helper.\n\nTask: M006-S001-T0001',
+    );
+    const subject = execFileSync('git', ['log', '-n', '1', '--format=%s'], { encoding: 'utf-8' }).trim();
+    const fullBody = execFileSync('git', ['log', '-n', '1', '--format=%b'], { encoding: 'utf-8' });
+    assert.equal(subject, 'task(M006-S001-T0001): add git helper');
+    assert.match(fullBody, /Implements the git helper\./);
+    assert.match(fullBody, /Task: M006-S001-T0001/);
+  });
+});
+
+test('GIT-5c: commitTask omits the body -m when body is empty/whitespace (backward-compatible)', () => {
+  const root = makeRepo();
+  inRepo(root, () => {
+    writeFile(root, 'lib/git.cjs', '// stub');
+    git.commitTask('M006-S001-T0001', ['lib/git.cjs'], 'task(M006-S001-T0001): add git helper', '   ');
+    const fullBody = execFileSync('git', ['log', '-n', '1', '--format=%b'], { encoding: 'utf-8' }).trim();
+    assert.equal(fullBody, '');
+  });
+});
+
 test('GIT-6: findCommitByTaskId returns 40-char SHA for known task commit', () => {
   const root = makeRepo();
   inRepo(root, () => {

package/lib/template.cjs

@@ -3,15 +3,14 @@ const path = require('node:path');
 const { projectStateDir, NubosPilotError } = require('./core.cjs');
 
 const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+const PACKAGE_TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
 
 function templatesDir(cwd) {
   return path.join(projectStateDir(cwd), 'templates');
 }
 
-function loadTemplate(name, vars, cwd = process.cwd()) {
-  const dir = templatesDir(cwd);
+function resolveInDir(dir, name) {
   const filePath = path.resolve(dir, name + '.md');
-
   const dirWithSep = dir.endsWith(path.sep) ? dir : dir + path.sep;
   if (!filePath.startsWith(dirWithSep)) {
     throw new NubosPilotError(
@@ -20,21 +19,27 @@ function loadTemplate(name, vars, cwd = process.cwd()) {
       { template: name, path: filePath },
     );
   }
+  return filePath;
+}
 
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf-8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') {
-      throw new NubosPilotError(
-        'template-not-found',
-        `Template "${name}" not found at ${filePath}`,
-        { template: name, path: filePath },
-      );
-    }
-    throw err;
+function loadTemplate(name, vars, cwd = process.cwd()) {
+  const localPath = resolveInDir(templatesDir(cwd), name);
+  const packagePath = resolveInDir(PACKAGE_TEMPLATES_DIR, name);
+
+  let filePath = null;
+  if (fs.existsSync(localPath)) filePath = localPath;
+  else if (fs.existsSync(packagePath)) filePath = packagePath;
+
+  if (filePath === null) {
+    throw new NubosPilotError(
+      'template-not-found',
+      `Template "${name}" not found in project overlay (${localPath}) or package templates (${packagePath})`,
+      { template: name, path: localPath, packagePath },
+    );
   }
 
+  const raw = fs.readFileSync(filePath, 'utf-8');
+
   return raw.replace(PLACEHOLDER_RE, (_match, key) => {
     if (!(key in vars)) {
       throw new NubosPilotError(

package/lib/template.test.cjs

@@ -144,6 +144,41 @@ test('TPL-12: listTemplates on sandbox without templates dir returns []', () =>
   assert.deepEqual(list, []);
 });
 
+test('TPL-14: name absent in project overlay falls back to package template', () => {
+  const cwd = makeSandbox({});
+  const anyVars = new Proxy({}, { has: () => true, get: () => 'X' });
+  let out = null;
+  let thrown = null;
+  try {
+    out = tpl.loadTemplate('milestone/CONTEXT', anyVars, cwd);
+  } catch (err) {
+    thrown = err;
+  }
+  assert.equal(thrown, null, 'package fallback should resolve, not throw');
+  assert.equal(typeof out, 'string');
+  assert.ok(out.length > 0, 'package template rendered to non-empty output');
+});
+
+test('TPL-15: project overlay wins over package template of the same name', () => {
+  const cwd = makeSandbox({ RULES: 'LOCAL-OVERLAY {{x}}' });
+  const out = tpl.loadTemplate('RULES', { x: '1' }, cwd);
+  assert.equal(out, 'LOCAL-OVERLAY 1');
+});
+
+test('TPL-16: name absent in BOTH overlay and package → template-not-found with both paths', () => {
+  const cwd = makeSandbox({});
+  let thrown = null;
+  try {
+    tpl.loadTemplate('definitely-missing-xyz', {}, cwd);
+  } catch (err) {
+    thrown = err;
+  }
+  assert.ok(thrown, 'expected throw');
+  assert.equal(thrown.code, 'template-not-found');
+  assert.ok(thrown.details.path.endsWith(path.join('templates', 'definitely-missing-xyz.md')));
+  assert.ok(thrown.details.packagePath.endsWith(path.join('templates', 'definitely-missing-xyz.md')));
+});
+
 test('TPL-13: cwd with no .nubos-pilot ancestor → projectStateDir throws not-in-project', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'nubos-pilot-tpl-noroot-'));
   _sandboxes.push(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Self-hosted AI pilot for any codebase. Researcher and critic agents plan, execute and verify each change.",
   "homepage": "https://pilot.nubos.cloud",
   "repository": {

package/templates/RULES.md

@@ -79,7 +79,33 @@ Examples:
 -->
 - _TBD — fill with logging policy._
 
-## Code Style
+## Conventions
+
+> **How your code must be built.** These rules bind the architect (`np-task-architect`),
+> the test-writer (`np-test-writer`), the executor, and the style critic
+> (`np-critic-style`). They are read on every task. Each subsection is **MUST FILL** —
+> use `- _none — <reason>_` only when a subsection genuinely does not apply.
+
+### Class / Module Structure
+
+<!-- How classes, modules, and units are shaped. Examples:
+- One public class per file; file name matches the class name.
+- Constructor injection only — no service-locator / static singletons.
+- Business logic lives in Services/Actions; controllers stay thin (no DB access).
+- Public surface ≤ 5 methods; split when it grows past that.
+-->
+- _TBD — fill with class/module construction rules._
+
+### Naming
+
+<!-- Identifier conventions. Examples:
+- Classes PascalCase, methods camelCase, constants UPPER_SNAKE.
+- Booleans read as predicates (`isActive`, `hasAccess`), never `flag`/`status`.
+- Table names follow the framework's pluralization — never override.
+-->
+- _TBD — fill with naming conventions._
+
+### Code Style
 
 <!-- Format/lint/comment policy. Examples:
 - No comments inside source — names + tests carry intent.
@@ -88,6 +114,15 @@ Examples:
 -->
 - _TBD — fill with style policy._
 
+### Patterns & Paradigms
+
+<!-- Architectural patterns that are required or banned. Examples:
+- Required: Repository pattern for all persistence; Result objects over exceptions for control flow.
+- Banned: anemic domain models; inheritance for code reuse (prefer composition).
+- Errors are typed and surfaced — never swallowed or stringly-typed.
+-->
+- _TBD — fill with required/banned patterns._
+
 ## Out-of-Scope (Forever)
 
 <!-- Things this project explicitly will never do. Distinct from deferred ideas.