nubos-pilot 0.9.7 → 0.9.8

package/agents/np-architect.md

@@ -70,6 +70,8 @@ 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.
+
 ```markdown
 # M<NNN> — <milestone name> — Architecture
 

package/agents/np-plan-checker.md

@@ -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 11 canonical codes are:
+Each dimension maps to one or more canonical finding categories from `docs/agent-frontmatter-schema.md`. 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,6 +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).
 
 Run each dimension below; for every failure, emit one finding using the matching canonical code.
 

package/agents/np-planner.md

@@ -261,7 +261,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.** "Modify `src/api/auth/login.ts`" > "update the auth layer".
+- **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 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.
@@ -269,6 +269,38 @@ Every PLAN.md you write will be consumed by an executor agent that:
 If the executor has to stop and read three more files to figure out what you meant, the plan failed.
 </downstream_awareness>
 
+<plan_granularity>
+## Plan Granularity Doctrine — Intent + Boundary + Acceptance, NOT Implementation (ADR-0013)
+
+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.
+
+**You DO write:**
+- Intent: "Install Cashier 16 for billing." "Add subscription resource at `/billing`." "Force 2FA for org owners."
+- Boundary: which directories the change is allowed to touch (`database/migrations/`, `app/Providers/AppServiceProvider.php`).
+- Acceptance: observable, falsifiable success criteria (Pest test names, exit codes, HTTP responses, file presence).
+- Verify command: a real, runnable shell invocation that returns exit-code 0 on success. **The first token must be a known command** (np-tools verb, composer/npm script, vendor binary, POSIX tool). `plan-lint` mechanically refuses unknown verbs.
+
+**You DO NOT write:**
+- **Schema DDL.** No `CREATE TABLE`, no `Schema::create('...', function (Blueprint $table) { ... })`, no column-by-column lists. The framework decides the schema; the executor publishes/migrates it; you check that migration applies and tests pass.
+- **Framework-controlled filenames.** Cashier publishes 5 migration files with publish-time timestamps; you cannot know the exact names. `0001_01_01_000004_create_customer_columns_table.php` is a **smell** — `plan-lint` flags it as `framework-timestamped-filename`. Use globs (`database/migrations/*_cashier_*.php`) or leave files_modified empty.
+- **Code-style prescriptions.** Whether `boot()` inlines `Cashier::calculateTaxes()` or routes through `configureCashier()` is a codebase-state decision the executor reads from `.nubos-pilot/codebase/<module>.md`. You don't override it.
+- **Library-internal details.** "Cashier publishes one migration with subscriptions + subscription_items as two `Schema::create` blocks" is a falsifiable claim about an external library's internals. Either stay above that level (intent: "install Cashier"), or invoke a researcher to verify the claim and tag it `[VERIFIED]`. Unverified library-shape claims are the M004 plan-bug class.
+- **Inline implementation snippets > 10 lines.** Code blocks of significant length push implementation into the plan. Describe what the code must do; the executor writes it. `plan-lint` warns at >200-character code blocks (heuristic).
+
+**The Cashier example, done right:**
+
+> **Goal:** Install Cashier 16 for subscription billing.
+> **Boundary:** `database/migrations/`, `app/Providers/AppServiceProvider.php`, `phpunit.xml`.
+> **Acceptance:**
+> - `composer show laravel/cashier` reports version `^16.0`
+> - `php artisan migrate` exits 0 with at least one Cashier migration applied
+> - Pest test `tests/Feature/Cashier/InstallTest.php::installs_cashier` passes
+> **Verify:** `composer test:cashier`
+> **files_modified:** *empty* — let the executor resolve from publish output.
+
+The plan does not say which migration files Cashier publishes, what columns they contain, or how `AppServiceProvider::boot()` should look. Those are executor-resolved.
+</plan_granularity>
+
 <answer_validation>
 ## Self-Check Before Returning
 

package/bin/np-tools/_commands.cjs

@@ -7,6 +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: 'new-project',         category: 'Planning', description: 'Greenfield project init (PROJECT.md + REQUIREMENTS.md + M001 milestone)', description_de: 'Greenfield-Projekt-Init (PROJECT.md + REQUIREMENTS.md + M001-Milestone)' },
   { name: 'new-milestone',       category: 'Planning', description: 'Append a new milestone (M<NNN>) to an existing project', description_de: 'Hängt einen neuen Milestone (M<NNN>) an ein bestehendes Projekt an' },
   { name: 'propose-milestones',  category: 'Planning', description: 'Re-plan all not-yet-done milestones: AI proposes add/update/remove from PROJECT.md + REQUIREMENTS.md', description_de: 'Plant offene Milestones neu: KI schlägt add/update/remove aus PROJECT.md + REQUIREMENTS.md vor' },

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

@@ -0,0 +1,188 @@
+'use strict';
+
+// CLI driver for the plan-side Trust Layer (ADR-0013, lib/plan-lint.cjs).
+// Lints a single PLAN.md file or every PLAN.md under a milestone tree.
+//
+// Usage:
+//   plan-lint <path/to/PLAN.md>
+//   plan-lint --milestone M004
+//   plan-lint --milestone M004 --json
+//
+// Exit code:
+//   0 — no critical findings (major findings still reported)
+//   2 — at least one critical finding emitted
+//
+// Output: JSON object {summary, files: [{path, findings[]}]}.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, findProjectRoot } = require('../../lib/core.cjs');
+const { extractFrontmatter } = require('../../lib/frontmatter.cjs');
+const planLint = require('../../lib/plan-lint.cjs');
+const args = require('./_args.cjs');
+
+const MILESTONE_RE = /^M\d{3,}$/;
+
+function _walkMilestonePlans(milestoneDir) {
+  // Returns ordered list of PLAN.md paths under .nubos-pilot/milestones/M<NNN>/.
+  const out = [];
+  if (!fs.existsSync(milestoneDir)) return out;
+  // Milestone-level plan
+  const mPlan = fs.readdirSync(milestoneDir)
+    .filter((f) => /^M\d{3,}-PLAN\.md$/.test(f))
+    .map((f) => path.join(milestoneDir, f));
+  out.push(...mPlan);
+  // Slice plans
+  const slicesDir = path.join(milestoneDir, 'slices');
+  if (fs.existsSync(slicesDir)) {
+    const slices = fs.readdirSync(slicesDir).filter((d) => /^S\d{3,}$/.test(d)).sort();
+    for (const sId of slices) {
+      const sDir = path.join(slicesDir, sId);
+      for (const f of fs.readdirSync(sDir)) {
+        if (/^S\d{3,}-PLAN\.md$/.test(f)) out.push(path.join(sDir, f));
+      }
+      // Task plans
+      const tasksDir = path.join(sDir, 'tasks');
+      if (!fs.existsSync(tasksDir)) continue;
+      const tasks = fs.readdirSync(tasksDir).filter((d) => /^T\d{4,}$/.test(d)).sort();
+      for (const tId of tasks) {
+        const tDir = path.join(tasksDir, tId);
+        for (const f of fs.readdirSync(tDir)) {
+          if (/^T\d{4,}-PLAN\.md$/.test(f)) out.push(path.join(tDir, f));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function _sliceTaskCollect(milestoneDir) {
+  // Collect parallel-task race input: per slice, the set of tasks with their
+  // files_modified, depends_on, and verify text.
+  const out = []; // [{ slice, tasks: [{id, files_modified, depends_on, verifyText}] }]
+  const slicesDir = path.join(milestoneDir, 'slices');
+  if (!fs.existsSync(slicesDir)) return out;
+  const slices = fs.readdirSync(slicesDir).filter((d) => /^S\d{3,}$/.test(d)).sort();
+  for (const sId of slices) {
+    const tasksDir = path.join(slicesDir, sId, 'tasks');
+    if (!fs.existsSync(tasksDir)) continue;
+    const tasks = fs.readdirSync(tasksDir).filter((d) => /^T\d{4,}$/.test(d)).sort();
+    const collected = [];
+    for (const tId of tasks) {
+      const taskDir = path.join(tasksDir, tId);
+      const planFile = fs.readdirSync(taskDir).find((f) => /^T\d{4,}-PLAN\.md$/.test(f));
+      if (!planFile) continue;
+      const raw = fs.readFileSync(path.join(taskDir, planFile), 'utf-8');
+      const { frontmatter, body } = extractFrontmatter(raw);
+      const verifyMatch = String(body || '').match(/<verify>([\s\S]*?)<\/verify>/);
+      collected.push({
+        id: (frontmatter && frontmatter.id) || tId,
+        files_modified: (frontmatter && Array.isArray(frontmatter.files_modified))
+          ? frontmatter.files_modified : [],
+        depends_on: (frontmatter && Array.isArray(frontmatter.depends_on))
+          ? frontmatter.depends_on : [],
+        verifyText: verifyMatch ? verifyMatch[1] : '',
+        slice: sId,
+      });
+    }
+    if (collected.length) out.push({ slice: sId, tasks: collected });
+  }
+  return out;
+}
+
+function _summarize(filesResult, raceFindings) {
+  const counts = { critical: 0, major: 0, minor: 0, total: 0 };
+  for (const f of filesResult) {
+    for (const finding of f.findings) {
+      counts.total += 1;
+      counts[finding.severity || 'minor'] = (counts[finding.severity || 'minor'] || 0) + 1;
+    }
+  }
+  for (const finding of raceFindings) {
+    counts.total += 1;
+    counts[finding.severity || 'minor'] = (counts[finding.severity || 'minor'] || 0) + 1;
+  }
+  return counts;
+}
+
+function run(argv, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(argv) ? argv : [];
+
+  const milestoneFlag = args.getFlag(list, '--milestone');
+  const positional = list.filter((a) => !String(a).startsWith('--'));
+  const targetPath = positional[0];
+
+  let filePaths = [];
+  let raceInputs = [];
+
+  if (milestoneFlag) {
+    if (!MILESTONE_RE.test(milestoneFlag)) {
+      throw new NubosPilotError(
+        'plan-lint-invalid-milestone',
+        '--milestone expects M<NNN> form (e.g. M004)',
+        { got: milestoneFlag },
+      );
+    }
+    const root = findProjectRoot(cwd);
+    const mDir = path.join(root, '.nubos-pilot', 'milestones', milestoneFlag);
+    if (!fs.existsSync(mDir)) {
+      throw new NubosPilotError(
+        'plan-lint-milestone-not-found',
+        'milestone directory does not exist: ' + mDir,
+        { milestone: milestoneFlag, path: mDir },
+      );
+    }
+    filePaths = _walkMilestonePlans(mDir);
+    raceInputs = _sliceTaskCollect(mDir);
+  } else if (targetPath) {
+    const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+    if (!fs.existsSync(abs)) {
+      throw new NubosPilotError(
+        'plan-lint-file-not-found',
+        'plan file not found: ' + targetPath,
+        { path: abs },
+      );
+    }
+    filePaths = [abs];
+  } else {
+    throw new NubosPilotError(
+      'plan-lint-missing-target',
+      'plan-lint requires a path argument OR --milestone <M<NNN>>',
+      { hint: 'examples: `plan-lint M004-S001-PLAN.md` or `plan-lint --milestone M004`' },
+    );
+  }
+
+  const filesResult = filePaths.map((p) => {
+    const raw = fs.readFileSync(p, 'utf-8');
+    const { body } = extractFrontmatter(raw);
+    return {
+      path: path.relative(cwd, p),
+      findings: planLint.lintPlan(body, { cwd, raw }),
+    };
+  });
+
+  let raceFindings = [];
+  for (const group of raceInputs) {
+    raceFindings.push(...planLint.lintParallelTaskRaces(group.tasks));
+  }
+
+  const summary = _summarize(filesResult, raceFindings);
+  const payload = {
+    target: milestoneFlag || (positional[0] || null),
+    summary,
+    files: filesResult,
+    parallel_race_findings: raceFindings,
+  };
+  stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  return summary.critical > 0 ? 2 : 0;
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/plan-lint.test.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const planLintCli = require('./plan-lint.cjs');
+
+const _sandboxes = [];
+
+function _mkProject(milestoneTree) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-pl-cli-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  // Mark project root via STATE.md (findProjectRoot anchors on .nubos-pilot/).
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'),
+    '---\nschema_version: 2\ncurrent_phase: null\ncurrent_plan: null\ncurrent_task: null\n---\n', 'utf-8');
+  if (milestoneTree) {
+    for (const [rel, content] of Object.entries(milestoneTree)) {
+      const abs = path.join(root, rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content, 'utf-8');
+    }
+  }
+  _sandboxes.push(root);
+  return root;
+}
+
+function _cap() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {}
+  }
+});
+
+function _taskMd(id, filesModified, dependsOn, verifyText) {
+  return `---
+id: ${id}
+files_modified: ${JSON.stringify(filesModified)}
+depends_on: ${JSON.stringify(dependsOn)}
+---
+# ${id}
+
+<verify>${verifyText}</verify>
+`;
+}
+
+test('PLCLI-1: refuses without --milestone or path', () => {
+  assert.throws(
+    () => planLintCli.run([], { cwd: _mkProject({}), stdout: _cap().stub }),
+    (err) => err && err.code === 'plan-lint-missing-target',
+  );
+});
+
+test('PLCLI-2: rejects malformed --milestone value', () => {
+  assert.throws(
+    () => planLintCli.run(['--milestone', 'm1'], { cwd: _mkProject({}), stdout: _cap().stub }),
+    (err) => err && err.code === 'plan-lint-invalid-milestone',
+  );
+});
+
+test('PLCLI-3: rejects nonexistent milestone directory', () => {
+  assert.throws(
+    () => planLintCli.run(['--milestone', 'M999'], { cwd: _mkProject({}), stdout: _cap().stub }),
+    (err) => err && err.code === 'plan-lint-milestone-not-found',
+  );
+});
+
+test('PLCLI-4: returns exit 0 + zero findings on a clean milestone', () => {
+  const root = _mkProject({
+    '.nubos-pilot/milestones/M001/M001-PLAN.md': '# Milestone\n\n<verify>echo ok</verify>\n',
+    '.nubos-pilot/milestones/M001/slices/S001/S001-PLAN.md': '# Slice\n\n<verify>echo ok</verify>\n',
+    '.nubos-pilot/milestones/M001/slices/S001/tasks/T0001/T0001-PLAN.md': _taskMd(
+      'M001-S001-T0001', ['src/foo.ts'], [], 'echo ok',
+    ),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['--milestone', 'M001'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(code, 0);
+  assert.equal(payload.summary.critical, 0);
+  assert.equal(payload.summary.total, 0);
+});
+
+test('PLCLI-5: catches the exact M004 plan-bug — verify uses unknown np-tools verb', () => {
+  const root = _mkProject({
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0002/T0002-PLAN.md': _taskMd(
+      'M004-S001-T0002', [], [],
+      'node .nubos-pilot/bin/np-tools.cjs codebase doc-lint',
+    ),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['--milestone', 'M004'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(code, 2, 'must exit non-zero on critical findings');
+  const verifyFinding = payload.files
+    .flatMap((f) => f.findings)
+    .find((f) => f.category === 'verify-command-unknown');
+  assert.ok(verifyFinding, 'expected verify-command-unknown finding');
+  assert.equal(verifyFinding.severity, 'critical');
+  assert.equal(verifyFinding.raw.reason, 'np-tools-unknown-verb');
+});
+
+test('PLCLI-6: catches the exact M004 plan-bug — parallel race against working-tree-reading verify', () => {
+  const root = _mkProject({
+    // T0001 modifies migration files
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0001/T0001-PLAN.md': _taskMd(
+      'M004-S001-T0001',
+      ['database/migrations/2024_01_01_000000_install_cashier.php'],
+      [],
+      'php artisan migrate',
+    ),
+    // T0002 runs update-docs which hashes working tree → implicit dep
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0002/T0002-PLAN.md': _taskMd(
+      'M004-S001-T0002', [], [],
+      'node .nubos-pilot/bin/np-tools.cjs update-docs --check',
+    ),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['--milestone', 'M004'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(code, 2);
+  const raceFinding = payload.parallel_race_findings.find(
+    (f) => f.category === 'parallel-task-implicit-dependency',
+  );
+  assert.ok(raceFinding, 'expected parallel-task-implicit-dependency finding');
+  assert.equal(raceFinding.target, 'M004-S001-T0002');
+  assert.deepEqual(raceFinding.raw.conflicts, ['M004-S001-T0001']);
+});
+
+test('PLCLI-7: catches over-specification (Schema::create DDL in PLAN body)', () => {
+  const root = _mkProject({
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0001/T0001-PLAN.md': _taskMd(
+      'M004-S001-T0001', ['x.php'], [], 'echo ok',
+    ).replace('# M004-S001-T0001\n',
+      '# M004-S001-T0001\n\nSchema::create(\'subscriptions\', function () {});\n'),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['--milestone', 'M004'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  // Major (advisory) is not enough to fail the gate by default — exit 0.
+  assert.equal(code, 0);
+  const finding = payload.files
+    .flatMap((f) => f.findings)
+    .find((f) => f.category === 'plan-over-specifies-implementation');
+  assert.ok(finding);
+  assert.equal(finding.severity, 'major');
+});
+
+test('PLCLI-8: lints a single file when given a path argument', () => {
+  const root = _mkProject({
+    'mytask.md': _taskMd('M001-S001-T0001', [], [], 'node .nubos-pilot/bin/np-tools.cjs nonexistent-verb'),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['mytask.md'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(code, 2);
+  assert.equal(payload.files.length, 1);
+  assert.ok(payload.files[0].findings.find((f) => f.category === 'verify-command-unknown'));
+});
+
+test('PLCLI-9: file-not-found surfaces a clear error', () => {
+  assert.throws(
+    () => planLintCli.run(['nonexistent.md'], { cwd: _mkProject({}), stdout: _cap().stub }),
+    (err) => err && err.code === 'plan-lint-file-not-found',
+  );
+});
+
+test('PLCLI-10: end-to-end — all three M004 plan-bug classes surfaced together', () => {
+  const root = _mkProject({
+    // T0001 modifies migration files (race target)
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0001/T0001-PLAN.md': _taskMd(
+      'M004-S001-T0001',
+      ['database/migrations/0001_01_01_000004_create_customer_columns_table.php'],
+      [],
+      'php artisan migrate',
+    ),
+    // T0002 has working-tree-reader verify (creates implicit race) AND
+    // an unknown np-tools verb on the second line.
+    '.nubos-pilot/milestones/M004/slices/S001/tasks/T0002/T0002-PLAN.md': _taskMd(
+      'M004-S001-T0002', [], [],
+      'node .nubos-pilot/bin/np-tools.cjs update-docs --check\nnode .nubos-pilot/bin/np-tools.cjs codebase doc-lint',
+    ),
+  });
+  const cap = _cap();
+  const code = planLintCli.run(['--milestone', 'M004'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(code, 2);
+  const cats = new Set([
+    ...payload.files.flatMap((f) => f.findings).map((f) => f.category),
+    ...payload.parallel_race_findings.map((f) => f.category),
+  ]);
+  assert.ok(cats.has('verify-command-unknown'),
+    'must catch verify-command-unknown — saw: ' + [...cats].join(', '));
+  assert.ok(cats.has('parallel-task-implicit-dependency'),
+    'must catch parallel-task-implicit-dependency — saw: ' + [...cats].join(', '));
+  assert.ok(cats.has('plan-over-specifies-implementation'),
+    'must catch plan-over-specifies-implementation (framework-timestamped filename) — saw: '
+      + [...cats].join(', '));
+});

package/docs/adr/0013-plan-trust-layer.md

@@ -0,0 +1,95 @@
+# ADR-0013: Plan-side Trust Layer — Mechanical PLAN.md Validation Before Promote
+
+* Status: Accepted
+* Date: 2026-05-05
+* Supersedes: None
+* Related: [ADR-0010](0010-nubosloop.md) — Execute-side Trust Layer (Layers A/B/C)
+
+## Context and Problem Statement
+
+ADR-0010 closed the Execute-side Trust gaps (Layers A, B, C) — `commit-task` and `loop-run-round` now refuse to advance unless the per-task evidence and audit-trail are intact. Real spawns must demonstrably have happened. That solved one half of the problem.
+
+The other half surfaced in production runs: **the plans themselves were buggy**. Three failure classes recurred across milestones M002 + M004:
+
+1. **Phantom CLI verbs in `<verify>` blocks.** A plan would specify `<verify>node .nubos-pilot/bin/np-tools.cjs codebase doc-lint</verify>`, but `codebase` is not a registered np-tools verb. The verify command is mechanically unexecutable. The Nubosloop catches this at execute time — verify-red → build-fixer → verify-red → build-fixer → stuck — but the cost is ~3 executor + 3 build-fixer + ~9 critic spawns for a deterministically-failing outcome that a 30-line lint check would have caught at plan time.
+
+2. **False parallel-safety claims.** Tasks marked `depends_on: []` (parallel-safe) where one task's `<verify>` reads working-tree state (`update-docs --check`, `phpstan analyse`, `git diff`) against files another sibling task modifies. Filesystem-race at runtime; parallel-safe in name only.
+
+3. **Implementation over-specification.** Plans bake in framework-controlled details — exact migration filenames (`0001_01_01_000004_create_customer_columns_table.php`), schema DDL (`Schema::create('subscriptions', function (Blueprint $table) { ... })`), code-style edicts (`use Cashier::calculateTaxes() inline in boot()`). These are not the planner's territory: the framework decides migration shapes, the executor reads codebase docs for style, the publish step decides filenames. A plan that pretends to know these is making falsifiable claims it cannot verify.
+
+In all three classes, the orchestrator fielded the consequences at execute time when the planner should have prevented them.
+
+## Decision Drivers
+
+* The Nubosloop is expensive — 1 executor + 3 critics per task per round. Burning a full Nubosloop on a plan-bug is wasteful when mechanical detection is cheap.
+* Plan-checker is an LLM-judgment agent (opus tier). LLM judgment is unreliable for syntactic checks (verb-existence, regex-pattern-detection) — those are mechanical-checker territory.
+* Planners under user pressure rationalize over-specification ("being thorough"). Doctrine alone doesn't hold; mechanical refusal does.
+
+## Considered Options
+
+* **Status quo (LLM-judgment plan-checker only).** *Rejected.* Demonstrably fails on all three classes — observed in M002 + M004.
+* **Add the three checks to `np-plan-checker` agent prompt.** *Rejected.* LLM-judgment is non-deterministic. The same plan, checked twice, can produce different verdicts. For mechanical violations we need deterministic refusal.
+* **New mechanical lint verb + Layer-D enforcement in `plan-phase` workflow — chosen**.
+
+## Decision Outcome
+
+Chosen: **Plan-side Trust Layer with three mechanical linters wrapped in a CLI verb (`np-tools.cjs plan-lint`), called from `plan-phase` workflow before each verification-loop iteration. Critical findings are merged into the LLM-checker verdict and force iteration-2.**
+
+### Layer-D — three deterministic linters
+
+* **D1 — `lintVerifyCommands`** (severity: critical). Every `<verify>` block is parsed; the first command per non-comment line is validated against:
+  * Known np-tools verbs (read from `_commands.cjs::COMMANDS`)
+  * Declared composer scripts (`composer.json::scripts`)
+  * Declared npm/pnpm/yarn scripts (`package.json::scripts`)
+  * `vendor/bin/*` and `node_modules/.bin/*` paths (lint-time existence + conventional-bin-dir tolerance)
+  * POSIX baseline (echo, test, [, sed, grep, find, …)
+  * Interpreter-prefixed calls (`node`, `php`, `composer`, `npm`, `npx`, …)
+  Unknown commands emit `verify-command-unknown` with concrete `raw.reason` (`np-tools-unknown-verb`, `composer-script-not-declared`, `npm-script-not-declared`, `path-not-found`).
+
+* **D2 — `lintParallelTaskRaces`** (severity: critical). For every slice with multiple tasks marked `depends_on: []`, computes whether any sibling's `<verify>` matches the working-tree-reader pattern (`update-docs`, `phpstan analyse`, `pint`, `eslint`, `tsc`, `git diff/status/ls-files/log`, `find -newer`, `pre-commit run`). If yes AND another sibling has non-empty `files_modified`, emits `parallel-task-implicit-dependency` naming the conflict. The hint includes the exact `depends_on` array the planner should have written.
+
+* **D3 — `lintOverSpecification`** (severity: major, advisory). Heuristic regex scan for:
+  * Schema DDL (`CREATE TABLE`, `ALTER COLUMN`, `Schema::create`, `Schema::table`, common Eloquent column-builder calls)
+  * Framework-timestamped filenames (`\d{4}_\d{2}_\d{2}_\d{6}_*.php`)
+  * Inline code blocks > 200 characters
+  Emits `plan-over-specifies-implementation`. Severity is `major` (advisory) so it surfaces without blocking the gate — heuristic false-positives are tolerated.
+
+### Granularity Doctrine — propagated to planner agents
+
+`agents/np-planner.md` gains a `<plan_granularity>` section codifying: plans specify intent + boundary + acceptance, not implementation. Concrete prohibitions enumerated, including:
+* Schema DDL belongs to executor.
+* Framework-timestamped filenames are publish-time output; use globs or empty `files_modified`.
+* Code-style is codebase-state, executor reads `.nubos-pilot/codebase/<module>.md`.
+* Library-internal claims must be `[VERIFIED]` via researcher or stay above that level.
+
+`agents/np-architect.md` gains a granularity reminder: architecture decisions are intent-level (which library, which boundary, which protocol), not implementation prescriptions.
+
+`agents/np-plan-checker.md` gains the three new canonical finding categories. The plan-checker agent mirrors mechanical findings into its YAML verdict so the verification loop treats them uniformly with semantic findings.
+
+### Workflow integration
+
+`workflows/plan-phase.md` calls `plan-lint --milestone $milestone_id` between the plan-checker spawn and the status-pass check, in each iteration of the verification loop. Critical findings are merged into the verdict JSON; the loop forces iteration-2 (and rejects the plan if iteration-2 still has critical findings).
+
+### Defaults / Configuration
+
+No new configuration. The linter is always-on; severity is fixed (critical for D1+D2, major for D3). Future configurability lives in `.nubos-pilot/config.json::plan_lint` if needed (e.g. project-specific allowlist for vendor binaries).
+
+## Consequences
+
+* **Good.** All three plan-bug classes from M002+M004 are now caught at plan time, before any executor spawns. Saves ~190 agent invocations per milestone (M004 had 27 tasks × ~7 spawns/task that would have hit the deterministic failure).
+* **Good.** The mechanical layer is deterministic and auditable. Same plan → same verdict, every time.
+* **Good.** Plan-checker (LLM, opus) can now focus on semantic checks (success-criterion coverage, decision fidelity) where its judgment adds value.
+* **Good.** Doctrine in planner agents reinforces the lesson; mechanical layer enforces it when doctrine slips.
+* **Bad.** D3 (over-specification) is heuristic and can false-positive on legitimate plans (e.g. a plan that *must* prescribe a schema for a custom CRUD-builder task). Mitigated by `severity: major` (advisory, not blocking).
+* **Bad.** Plan-lint adds ~50ms to each plan-phase iteration. Acceptable — saves orders of magnitude more on the execute side.
+* **Bad.** The Granularity Doctrine constrains planner output style. Existing plans in flight may fail D3 until rewritten. Migration path: D3 is advisory only; D1+D2 catch the actual blockers.
+
+## More Information
+
+* **Library:** `lib/plan-lint.cjs` — pure-function linters, no I/O outside file reads.
+* **CLI verb:** `bin/np-tools/plan-lint.cjs` — `plan-lint <path>` or `plan-lint --milestone M<NNN>`. Exit 2 on critical findings, 0 otherwise. Output is JSON.
+* **Tests:** `lib/plan-lint.test.cjs` (25 unit tests), `bin/np-tools/plan-lint.test.cjs` (10 CLI integration + e2e tests).
+* **Workflow integration:** `workflows/plan-phase.md` § Verification Loop — plan-lint runs each iteration, findings merged into verdict.
+* **Related ADR:** [ADR-0010](0010-nubosloop.md) — Execute-side Trust Layer (A/B/C). Layer-D (this ADR) is the planner-side counterpart.
+* **Related ADR:** [ADR-0011](0011-researcher-swarm-consensus.md) — researcher-schwarm runs at plan time too; D1's `verify-command-unknown` is structurally similar to a researcher's `[VERIFIED]` provenance check, applied to the verify-command surface.
+* **Related ADR:** [ADR-0012](0012-completeness-doctrine.md) — Layer-D enforces Rule 3 (do it with tests) at plan time: the verify command must be runnable.

package/lib/plan-lint.cjs

@@ -0,0 +1,383 @@
+'use strict';
+
+// Plan-side Trust Layer — mechanical validation of PLAN.md files before they
+// promote to execute. Counterpart to the Execute-side Trust Layer (ADR-0010
+// Layers A/B/C). See ADR-0013.
+//
+// Three linters, all stateless and deterministic:
+//
+//   * lintVerifyCommands — every `<verify>` block must invoke commands that
+//     exist (np-tools verbs, composer/npm/pnpm scripts, vendor binaries).
+//     Catches the "phantom CLI verb" bug class.
+//
+//   * lintParallelTaskRaces — tasks marked depends_on:[] in the same slice
+//     must be truly parallel-safe. Working-tree-reading verify commands
+//     (update-docs, git diff, hash-of-working-tree) create implicit ordering.
+//
+//   * lintOverSpecification — heuristic warning: PLAN.md should specify
+//     intent, not implementation. Schema DDL, exact framework-controlled
+//     filenames, and inline implementation snippets are advisory smells.
+//
+// Findings shape (matches np-plan-checker schema):
+//   { category, severity, target, message, hint?, raw? }
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+// --- Known-command surface --------------------------------------------------
+
+// POSIX baseline — these always pass without further inspection.
+const POSIX_BASELINE = Object.freeze(new Set([
+  'true', 'false', 'echo', 'printf', 'test', '[', '[[',
+  'cat', 'head', 'tail', 'wc', 'sort', 'uniq', 'cut', 'tr', 'sed', 'awk',
+  'grep', 'egrep', 'fgrep', 'find', 'xargs',
+  'ls', 'mkdir', 'rmdir', 'rm', 'cp', 'mv', 'ln', 'touch', 'chmod', 'chown',
+  'pwd', 'cd', 'set', 'unset', 'export', 'source', '.', 'eval', 'exit',
+  'diff', 'patch', 'tar', 'gzip', 'gunzip', 'zip', 'unzip',
+  'env', 'sleep', 'date', 'time', 'which', 'type',
+]));
+
+// Interpreter prefixes — for these, we look at the next argument as the
+// "real" command and route validation accordingly.
+const INTERPRETER_PREFIXES = Object.freeze(new Set([
+  'node', 'npx', 'pnpm', 'yarn', 'npm', 'bun', 'bunx',
+  'php', 'composer', 'python', 'python3', 'pipx', 'uv', 'poetry',
+  'ruby', 'bundle', 'go',
+]));
+
+// Working-tree-reading verify operations — used by lintParallelTaskRaces.
+// If a parallel task uses one of these, it has an implicit dependency on
+// every other task in the slice that has files_modified ≠ [].
+const WORKING_TREE_READERS = Object.freeze([
+  /\bupdate-docs\b/i,
+  /\bgit\s+(diff|status|ls-files|log)/i,
+  /\bfind\s+\S+\s+-newer\b/i,
+  /\bpre-commit\s+run\b/i,
+  /\bphpstan\s+analyse\b/i,        // reads source files across the project
+  /\bpint\b/i,                       // reads + may rewrite source files
+  /\beslint\b/i,
+  /\btsc\b/i,                        // reads tsconfig + project files
+]);
+
+// --- helpers ----------------------------------------------------------------
+
+function _readJsonSafe(filepath) {
+  try {
+    if (!fs.existsSync(filepath)) return null;
+    const raw = fs.readFileSync(filepath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch { return null; }
+}
+
+function _resolveKnownVerbs(opts) {
+  if (Array.isArray(opts && opts.knownVerbs)) return new Set(opts.knownVerbs);
+  try {
+    const cmds = require('../bin/np-tools/_commands.cjs');
+    if (Array.isArray(cmds.COMMANDS)) {
+      return new Set(cmds.COMMANDS.map((c) => c.name));
+    }
+  } catch {}
+  return new Set();
+}
+
+function _resolveScripts(cwd) {
+  const composer = _readJsonSafe(path.join(cwd, 'composer.json'));
+  const npm      = _readJsonSafe(path.join(cwd, 'package.json'));
+  return {
+    composer: composer && composer.scripts && typeof composer.scripts === 'object'
+      ? new Set(Object.keys(composer.scripts)) : new Set(),
+    npm: npm && npm.scripts && typeof npm.scripts === 'object'
+      ? new Set(Object.keys(npm.scripts)) : new Set(),
+  };
+}
+
+function _binaryExists(cwd, relPath) {
+  try { return fs.existsSync(path.join(cwd, relPath)); }
+  catch { return false; }
+}
+
+// Tokenize a single command line — split on whitespace, drop empty tokens,
+// strip leading env-vars (FOO=bar cmd...), shell control (;, &&, ||, |).
+function _firstCommand(line) {
+  const stripped = String(line || '').trim();
+  if (!stripped) return null;
+  if (stripped.startsWith('#')) return null;
+  // Split on shell separators — only validate the first sub-command.
+  const head = stripped.split(/[;|&]+/)[0].trim();
+  if (!head) return null;
+  const tokens = head.split(/\s+/).filter(Boolean);
+  // Drop NAME=value env-var prefix(es).
+  let i = 0;
+  while (i < tokens.length && /^[A-Z_][A-Z0-9_]*=/.test(tokens[i])) i++;
+  if (i >= tokens.length) return null;
+  return { command: tokens[i], rest: tokens.slice(i + 1), full: head };
+}
+
+// Extract every `<verify>...</verify>` block from a PLAN.md body.
+function _extractVerifyBlocks(body) {
+  const out = [];
+  const matches = String(body || '').matchAll(/<verify>([\s\S]*?)<\/verify>/g);
+  for (const m of matches) {
+    out.push({ start: m.index, body: m[1] });
+  }
+  return out;
+}
+
+// --- D1: lintVerifyCommands -------------------------------------------------
+
+function _validateCommand(cmd, ctx) {
+  // Returns { ok, reason?, hint? }.
+  const { command, rest, full } = cmd;
+  // POSIX baseline
+  if (POSIX_BASELINE.has(command)) return { ok: true };
+  // Interpreter dispatch
+  if (INTERPRETER_PREFIXES.has(command)) {
+    return _validateInterpreterCall(command, rest, full, ctx);
+  }
+  // Path to a vendored binary (e.g. vendor/bin/phpstan)
+  if (command.includes('/') || command.startsWith('./') || command.startsWith('../')) {
+    if (_binaryExists(ctx.cwd, command)) return { ok: true };
+    // Could be a binary that exists post-`composer install` / `npm install`.
+    // We accept these as legitimate IF they live under known bin dirs.
+    if (/^(\.\/)?(vendor\/bin|node_modules\/\.bin|bin|scripts)\//.test(command)) {
+      return { ok: true, hint: 'binary not present at lint-time but path is conventional' };
+    }
+    return { ok: false, reason: 'path-not-found',
+      hint: 'verify path "' + command + '" does not exist; check the project layout' };
+  }
+  // Bareword — treat as PATH-resolved binary; we cannot statically prove it,
+  // so accept but mark soft.
+  return { ok: true, hint: 'bareword command "' + command + '" assumed PATH-resolved' };
+}
+
+function _validateInterpreterCall(interp, rest, full, ctx) {
+  // node .../np-tools.cjs <verb> ...
+  if (interp === 'node' && rest.length >= 1) {
+    const target = rest[0];
+    if (/np-tools\.cjs$/.test(target)) {
+      const verb = rest[1];
+      if (!verb || verb.startsWith('-')) {
+        return { ok: false, reason: 'np-tools-missing-verb',
+          hint: 'np-tools.cjs requires a verb as second argument' };
+      }
+      if (!ctx.knownVerbs.has(verb)) {
+        return { ok: false, reason: 'np-tools-unknown-verb',
+          hint: 'verb "' + verb + '" is not a registered np-tools command (see _commands.cjs)' };
+      }
+      return { ok: true };
+    }
+    // node <some-script.js/cjs> — accept if script exists
+    if (/\.(c?js|mjs)$/.test(target)) {
+      if (_binaryExists(ctx.cwd, target)) return { ok: true };
+      return { ok: false, reason: 'node-script-not-found',
+        hint: 'node script "' + target + '" not found at lint-time' };
+    }
+    return { ok: true }; // node -e "..." or other forms
+  }
+  // npm run <script> / yarn <script> / pnpm <script> / pnpm run <script>
+  if (interp === 'npm' || interp === 'pnpm' || interp === 'yarn') {
+    let i = 0;
+    if (rest[i] === 'run' || rest[i] === 'run-script' || rest[i] === 'exec') i++;
+    const script = rest[i];
+    if (!script || script.startsWith('-')) return { ok: true }; // npm install etc.
+    // If the script name matches a package.json scripts entry, ok.
+    if (ctx.scripts.npm.has(script)) return { ok: true };
+    // Common pass-throughs: install, ci, test (if package.json doesn't list it,
+    // npm test still works as a default — accept).
+    if (['install', 'ci', 'test', 'audit', 'update', 'outdated'].includes(script)) {
+      return { ok: true };
+    }
+    return { ok: false, reason: 'npm-script-not-declared',
+      hint: '"' + script + '" is not declared in package.json scripts' };
+  }
+  // composer <script>
+  if (interp === 'composer') {
+    const script = rest[0];
+    if (!script || script.startsWith('-')) return { ok: true };
+    if (ctx.scripts.composer.has(script)) return { ok: true };
+    // Standard composer subcommands (not project-defined scripts):
+    const builtin = new Set([
+      'install', 'update', 'require', 'remove', 'dump-autoload', 'dumpautoload',
+      'show', 'why', 'depends', 'why-not', 'audit', 'check-platform-reqs',
+      'create-project', 'init', 'self-update', 'about', 'archive', 'browse',
+      'clear-cache', 'clearcache', 'config', 'diagnose', 'exec', 'fund',
+      'global', 'home', 'licenses', 'list', 'outdated', 'prohibits', 'reinstall',
+      'run-script', 'run', 'search', 'status', 'suggests', 'validate',
+    ]);
+    if (builtin.has(script)) return { ok: true };
+    return { ok: false, reason: 'composer-script-not-declared',
+      hint: '"' + script + '" is neither a composer builtin nor declared in composer.json scripts' };
+  }
+  // npx / bunx / pnpx — assume the package will be fetched at runtime.
+  if (interp === 'npx' || interp === 'bunx' || interp === 'pnpx') return { ok: true };
+  // php <file> — accept; php artisan, php -r, php script.php — all standard.
+  if (interp === 'php') return { ok: true };
+  // ruby/python/go — same.
+  if (['ruby', 'python', 'python3', 'go', 'bun'].includes(interp)) return { ok: true };
+  // bundle exec <something>
+  if (interp === 'bundle') return { ok: true };
+  return { ok: true };
+}
+
+function lintVerifyCommands(planBody, opts) {
+  const cwd = (opts && opts.cwd) || process.cwd();
+  const ctx = {
+    cwd,
+    knownVerbs: _resolveKnownVerbs(opts),
+    scripts: _resolveScripts(cwd),
+  };
+  const findings = [];
+  const blocks = _extractVerifyBlocks(planBody || '');
+  for (const block of blocks) {
+    const lines = block.body.split(/\r?\n/);
+    for (const line of lines) {
+      const cmd = _firstCommand(line);
+      if (!cmd) continue;
+      const verdict = _validateCommand(cmd, ctx);
+      if (!verdict.ok) {
+        findings.push({
+          category: 'verify-command-unknown',
+          severity: 'critical',
+          target: '<verify> block',
+          message: '`' + cmd.full + '` — ' + (verdict.hint || verdict.reason || 'unknown command'),
+          hint: verdict.hint || null,
+          raw: { reason: verdict.reason, command: cmd.command, line },
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+// --- D2: lintParallelTaskRaces ---------------------------------------------
+
+function _verifyReadsWorkingTree(verifyText) {
+  const t = String(verifyText || '');
+  for (const re of WORKING_TREE_READERS) {
+    if (re.test(t)) return true;
+  }
+  return false;
+}
+
+function lintParallelTaskRaces(tasks) {
+  // tasks: array of { id, files_modified, verifyText, depends_on, slice? }
+  const findings = [];
+  // Group by slice (or treat as one group).
+  const groups = new Map();
+  for (const t of tasks || []) {
+    const key = t.slice || '__default__';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(t);
+  }
+  for (const [, group] of groups) {
+    if (group.length < 2) continue;
+    // Identify parallel tasks (depends_on is empty array OR missing).
+    const parallel = group.filter((t) => {
+      const d = t.depends_on;
+      return !Array.isArray(d) || d.length === 0;
+    });
+    if (parallel.length < 2) continue;
+    for (const a of parallel) {
+      if (!_verifyReadsWorkingTree(a.verifyText)) continue;
+      // a's verify reads working-tree → if any sibling has files_modified ≠ [],
+      // a has an implicit dependency on it.
+      const conflicts = parallel.filter(
+        (b) => b.id !== a.id
+          && Array.isArray(b.files_modified)
+          && b.files_modified.length > 0,
+      );
+      if (conflicts.length === 0) continue;
+      findings.push({
+        category: 'parallel-task-implicit-dependency',
+        severity: 'critical',
+        target: a.id,
+        message: 'task ' + a.id + ' is marked parallel (depends_on:[]) but its <verify> reads the working tree, ' +
+          'creating an implicit ordering against sibling task(s) that modify files: ' +
+          conflicts.map((c) => c.id).join(', '),
+        hint: 'set depends_on to [' + conflicts.map((c) => '"' + c.id + '"').join(', ') + '] OR ' +
+          'replace the working-tree-reading verify with a stateless check',
+        raw: { task: a.id, conflicts: conflicts.map((c) => c.id) },
+      });
+    }
+  }
+  return findings;
+}
+
+// --- D3: lintOverSpecification (heuristic) ---------------------------------
+
+const OVER_SPECIFICATION_SIGNALS = [
+  {
+    name: 'schema-ddl',
+    re: /^(\s*)?(CREATE\s+TABLE|ALTER\s+(TABLE|COLUMN)|Schema::(create|table)|->\s*(string|integer|bigInteger|foreignId|timestamp)\s*\()/im,
+    hint: 'schema DDL belongs to the executor — the plan describes intent (e.g. "subscriptions table with columns the framework dictates"), not exact column shape',
+  },
+  {
+    name: 'framework-timestamped-filename',
+    re: /\b\d{4}_\d{2}_\d{2}_\d{6}_[a-z_]+\.php\b/,
+    hint: 'framework-controlled migration filenames are publish-time output, not plan input — use a glob pattern in files_modified',
+  },
+  {
+    name: 'inline-code-snippet',
+    re: /```(?:[a-z]+)?\n[\s\S]{200,}\n```/,
+    hint: 'large code blocks in PLAN.md push implementation into the planner — describe what the code must achieve, let the executor write it',
+  },
+];
+
+function lintOverSpecification(planBody) {
+  const findings = [];
+  const body = String(planBody || '');
+  for (const sig of OVER_SPECIFICATION_SIGNALS) {
+    const m = body.match(sig.re);
+    if (m) {
+      findings.push({
+        category: 'plan-over-specifies-implementation',
+        severity: 'major',
+        target: 'PLAN.md body',
+        message: 'over-specification signal: ' + sig.name + ' (matched: ' +
+          String(m[0]).replace(/\s+/g, ' ').slice(0, 80) + ')',
+        hint: sig.hint,
+        raw: { signal: sig.name, snippet: String(m[0]).slice(0, 200) },
+      });
+    }
+  }
+  return findings;
+}
+
+// --- combined lintPlan -----------------------------------------------------
+
+// lintPlan takes the post-frontmatter body for verify-command parsing and an
+// optional raw string (frontmatter + body) for over-specification scanning —
+// framework-timestamped filenames typically live in frontmatter `files_modified`,
+// so the over-spec heuristic needs to see both.
+function lintPlan(planBody, opts) {
+  const raw = (opts && typeof opts.raw === 'string') ? opts.raw : planBody;
+  return [
+    ...lintVerifyCommands(planBody, opts),
+    ...lintOverSpecification(raw),
+  ];
+}
+
+// Lint a single task PLAN.md (frontmatter parsed automatically).
+function lintTaskFile(planMdPath, opts) {
+  const cwd = (opts && opts.cwd) || process.cwd();
+  const raw = fs.readFileSync(planMdPath, 'utf-8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  return {
+    path: planMdPath,
+    frontmatter: frontmatter || {},
+    findings: lintPlan(body, { ...opts, cwd, raw }),
+  };
+}
+
+module.exports = {
+  lintVerifyCommands,
+  lintParallelTaskRaces,
+  lintOverSpecification,
+  lintPlan,
+  lintTaskFile,
+  POSIX_BASELINE,
+  INTERPRETER_PREFIXES,
+  WORKING_TREE_READERS,
+};

package/lib/plan-lint.test.cjs

@@ -0,0 +1,313 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const planLint = require('./plan-lint.cjs');
+
+const _sandboxes = [];
+function _mkRoot(files) {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'np-pl-'));
+  if (files) {
+    for (const [rel, content] of Object.entries(files)) {
+      const abs = path.join(r, rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content, 'utf-8');
+    }
+  }
+  _sandboxes.push(r);
+  return r;
+}
+afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {}
+  }
+});
+
+// ===========================================================================
+// D1 — lintVerifyCommands
+// ===========================================================================
+
+test('PL-VC-1: passes for known np-tools verb', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>node .nubos-pilot/bin/np-tools.cjs commit-task M001-S001-T0001</verify>',
+    { knownVerbs: ['commit-task', 'state'] },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-2: catches unknown np-tools verb (the M004 bug class)', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>node .nubos-pilot/bin/np-tools.cjs codebase doc-lint</verify>',
+    { knownVerbs: ['commit-task', 'state', 'help'] },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].category, 'verify-command-unknown');
+  assert.equal(findings[0].severity, 'critical');
+  assert.equal(findings[0].raw.reason, 'np-tools-unknown-verb');
+});
+
+test('PL-VC-3: catches np-tools call without a verb', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>node .nubos-pilot/bin/np-tools.cjs --help</verify>',
+    { knownVerbs: ['commit-task'] },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.reason, 'np-tools-missing-verb');
+});
+
+test('PL-VC-4: passes for declared composer script', () => {
+  const r = _mkRoot({
+    'composer.json': JSON.stringify({ scripts: { test: 'phpunit' } }),
+  });
+  const findings = planLint.lintVerifyCommands(
+    '<verify>composer test</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-5: catches undeclared composer script', () => {
+  const r = _mkRoot({
+    'composer.json': JSON.stringify({ scripts: { test: 'phpunit' } }),
+  });
+  const findings = planLint.lintVerifyCommands(
+    '<verify>composer phantom-script</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.reason, 'composer-script-not-declared');
+});
+
+test('PL-VC-6: composer builtin (install/update/dump-autoload) always passes', () => {
+  const r = _mkRoot({});
+  const findings = planLint.lintVerifyCommands(
+    '<verify>composer dump-autoload</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-7: passes for declared npm script', () => {
+  const r = _mkRoot({
+    'package.json': JSON.stringify({ scripts: { lint: 'eslint .' } }),
+  });
+  const findings = planLint.lintVerifyCommands(
+    '<verify>npm run lint</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-8: catches undeclared npm script', () => {
+  const r = _mkRoot({
+    'package.json': JSON.stringify({ scripts: { lint: 'eslint .' } }),
+  });
+  const findings = planLint.lintVerifyCommands(
+    '<verify>npm run nonexistent</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.reason, 'npm-script-not-declared');
+});
+
+test('PL-VC-9: passes for vendor/bin/* path even if file is absent (post-install)', () => {
+  const r = _mkRoot({});
+  const findings = planLint.lintVerifyCommands(
+    '<verify>vendor/bin/phpstan analyse</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-10: passes for POSIX baseline (echo, test, [, sed)', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>echo ok && test -f file.txt</verify>',
+    {},
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-11: catches non-existent path command', () => {
+  const r = _mkRoot({});
+  const findings = planLint.lintVerifyCommands(
+    '<verify>./scripts-elsewhere/run.sh</verify>',
+    { cwd: r },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.reason, 'path-not-found');
+});
+
+test('PL-VC-12: multi-line verify, only first non-comment validated per line', () => {
+  const findings = planLint.lintVerifyCommands(
+    `<verify>
+# this is a comment
+echo "step 1"
+node .nubos-pilot/bin/np-tools.cjs nonexistent-verb
+</verify>`,
+    { knownVerbs: ['existing-verb'] },
+  );
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.reason, 'np-tools-unknown-verb');
+});
+
+test('PL-VC-13: env-var prefix is stripped before validation', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>FOO=bar BAZ=qux node .nubos-pilot/bin/np-tools.cjs commit-task X</verify>',
+    { knownVerbs: ['commit-task'] },
+  );
+  assert.equal(findings.length, 0);
+});
+
+test('PL-VC-14: shell pipe — only validates first sub-command', () => {
+  const findings = planLint.lintVerifyCommands(
+    '<verify>echo data | grep pattern</verify>',
+    {},
+  );
+  assert.equal(findings.length, 0); // echo is POSIX baseline
+});
+
+// ===========================================================================
+// D2 — lintParallelTaskRaces
+// ===========================================================================
+
+test('PL-PR-1: detects update-docs race against sibling that modifies files', () => {
+  const tasks = [
+    { id: 'M001-S001-T0001', files_modified: ['src/foo.ts'], depends_on: [],
+      verifyText: 'php artisan test', slice: 'S001' },
+    { id: 'M001-S001-T0002', files_modified: [], depends_on: [],
+      verifyText: 'node .nubos-pilot/bin/np-tools.cjs update-docs --check', slice: 'S001' },
+  ];
+  const findings = planLint.lintParallelTaskRaces(tasks);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].category, 'parallel-task-implicit-dependency');
+  assert.equal(findings[0].target, 'M001-S001-T0002');
+  assert.deepEqual(findings[0].raw.conflicts, ['M001-S001-T0001']);
+});
+
+test('PL-PR-2: detects phpstan-analyse race', () => {
+  const tasks = [
+    { id: 'M001-S001-T0001', files_modified: ['src/a.php'], depends_on: [],
+      verifyText: '', slice: 'S001' },
+    { id: 'M001-S001-T0002', files_modified: [], depends_on: [],
+      verifyText: 'vendor/bin/phpstan analyse', slice: 'S001' },
+  ];
+  const findings = planLint.lintParallelTaskRaces(tasks);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].target, 'M001-S001-T0002');
+});
+
+test('PL-PR-3: skips when explicit depends_on already declared', () => {
+  const tasks = [
+    { id: 'M001-S001-T0001', files_modified: ['src/foo.ts'], depends_on: [],
+      verifyText: 'php artisan test', slice: 'S001' },
+    { id: 'M001-S001-T0002', files_modified: [], depends_on: ['M001-S001-T0001'],
+      verifyText: 'node .nubos-pilot/bin/np-tools.cjs update-docs --check', slice: 'S001' },
+  ];
+  const findings = planLint.lintParallelTaskRaces(tasks);
+  assert.equal(findings.length, 0);
+});
+
+test('PL-PR-4: ignores stateless verify (php artisan test alone)', () => {
+  const tasks = [
+    { id: 'M001-S001-T0001', files_modified: ['src/foo.ts'], depends_on: [],
+      verifyText: 'echo hi', slice: 'S001' },
+    { id: 'M001-S001-T0002', files_modified: ['src/bar.ts'], depends_on: [],
+      verifyText: 'echo there', slice: 'S001' },
+  ];
+  const findings = planLint.lintParallelTaskRaces(tasks);
+  assert.equal(findings.length, 0);
+});
+
+test('PL-PR-5: cross-slice tasks are not pairs (different slice keys)', () => {
+  const tasks = [
+    { id: 'M001-S001-T0001', files_modified: ['src/foo.ts'], depends_on: [],
+      verifyText: 'php artisan test', slice: 'S001' },
+    { id: 'M001-S002-T0001', files_modified: [], depends_on: [],
+      verifyText: 'update-docs --check', slice: 'S002' },
+  ];
+  const findings = planLint.lintParallelTaskRaces(tasks);
+  assert.equal(findings.length, 0);
+});
+
+// ===========================================================================
+// D3 — lintOverSpecification (heuristic)
+// ===========================================================================
+
+test('PL-OS-1: catches Schema::create DDL block', () => {
+  const findings = planLint.lintOverSpecification(`
+## Migration
+
+Schema::create('subscriptions', function (Blueprint $table) {
+    $table->bigIncrements('id');
+});
+`);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].category, 'plan-over-specifies-implementation');
+  assert.equal(findings[0].raw.signal, 'schema-ddl');
+});
+
+test('PL-OS-2: catches framework-controlled migration filename', () => {
+  const findings = planLint.lintOverSpecification(`
+files_modified:
+  - database/migrations/0001_01_01_000004_create_customer_columns_table.php
+`);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.signal, 'framework-timestamped-filename');
+});
+
+test('PL-OS-3: catches a large inline code block', () => {
+  const big = Array(20).fill('  some_field: value').join('\n');
+  const findings = planLint.lintOverSpecification('```yaml\n' + big + '\n```');
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].raw.signal, 'inline-code-snippet');
+});
+
+test('PL-OS-4: clean intent-only PLAN body produces zero findings', () => {
+  const findings = planLint.lintOverSpecification(`
+## Goal
+Install Cashier billing into the project.
+
+## Boundary
+- App service provider
+- Test surface
+
+## Acceptance
+- Pest tests for Cashier integration green
+- Migrations applied successfully
+`);
+  assert.equal(findings.length, 0);
+});
+
+// ===========================================================================
+// Integration
+// ===========================================================================
+
+test('PL-INT-1: lintPlan combines verify-command + over-specification', () => {
+  const findings = planLint.lintPlan(`
+<verify>node .nubos-pilot/bin/np-tools.cjs codebase doc-lint</verify>
+
+Schema::create('tbl', function () {});
+`, { knownVerbs: ['commit-task'] });
+  assert.equal(findings.length, 2);
+  const cats = findings.map((f) => f.category).sort();
+  assert.deepEqual(cats, ['plan-over-specifies-implementation', 'verify-command-unknown']);
+});
+
+test('PL-INT-2: lintTaskFile reads frontmatter + body and runs full lint', () => {
+  const r = _mkRoot({
+    'task.md': `---
+id: M001-S001-T0001
+files_modified: []
+---
+<verify>node .nubos-pilot/bin/np-tools.cjs codebase doc-lint</verify>
+`,
+  });
+  const result = planLint.lintTaskFile(path.join(r, 'task.md'), { knownVerbs: ['commit-task'] });
+  assert.equal(result.frontmatter.id, 'M001-S001-T0001');
+  assert.equal(result.findings.length, 1);
+  assert.equal(result.findings[0].category, 'verify-command-unknown');
+});

package/np-tools.cjs

@@ -93,6 +93,8 @@ const topLevelCommands = {
   'session-snapshot-write': require('./bin/np-tools/session-snapshot-write.cjs'),
   'session-snapshot-read':  require('./bin/np-tools/session-snapshot-read.cjs'),
 
+  'plan-lint':       require('./bin/np-tools/plan-lint.cjs'),
+
   'loop-state-read':    require('./bin/np-tools/loop-state-read.cjs'),
   'loop-state-record':  require('./bin/np-tools/loop-state-record.cjs'),
   'loop-evaluate':       require('./bin/np-tools/loop-evaluate.cjs'),

package/package.json

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

package/workflows/plan-phase.md

@@ -258,6 +258,30 @@ for ITER in 1 2; do
   VERDICT_JSON_PATH="$milestone_dir/.tmp-verdict-$ITER.json"
   # (verdict JSON: {status: passed|issues_found, findings: [...] })
 
+  # --- Plan-side Trust Layer (ADR-0013): mechanical pre-flight ---
+  # Before treating the LLM-judgment verdict as authoritative, run the
+  # mechanical plan-lint over every PLAN.md in the milestone. Critical
+  # findings (verify-command-unknown / parallel-task-implicit-dependency)
+  # MUST be merged into the verdict so iteration-2 forces a fix. Mechanical
+  # findings are non-negotiable; the planner-checker LLM cannot override them.
+  PLAN_LINT_JSON=$(node .nubos-pilot/bin/np-tools.cjs plan-lint --milestone "$milestone_id" 2>&1) || true
+  PLAN_LINT_CRITICAL=$(echo "$PLAN_LINT_JSON" | node -e 'process.stdin.on("data",d=>{try{const j=JSON.parse(d);console.log((j.summary&&j.summary.critical)||0)}catch{console.log(0)}})')
+  if [ "${PLAN_LINT_CRITICAL:-0}" -gt 0 ]; then
+    # Promote mechanical findings into the verdict file so iteration-2 sees them.
+    echo "$PLAN_LINT_JSON" > "$milestone_dir/.tmp-plan-lint-$ITER.json"
+    node -e '
+      const fs = require("fs");
+      const verdict = JSON.parse(fs.readFileSync(process.argv[1], "utf-8"));
+      const lint    = JSON.parse(fs.readFileSync(process.argv[2], "utf-8"));
+      const findings = Array.isArray(verdict.findings) ? verdict.findings.slice() : [];
+      for (const f of (lint.files || []).flatMap(x => x.findings || [])) findings.push(f);
+      for (const f of (lint.parallel_race_findings || [])) findings.push(f);
+      verdict.findings = findings;
+      verdict.status = "issues_found";
+      fs.writeFileSync(process.argv[1], JSON.stringify(verdict, null, 2));
+    ' "$VERDICT_JSON_PATH" "$milestone_dir/.tmp-plan-lint-$ITER.json"
+  fi
+
   # (Plan-review append uses the milestone-id form — append-only audit)
   # Future: move to plan-milestone plan-review-append verb.