nubos-pilot 0.8.1 → 0.8.3

package/agents/np-plan-checker.md

@@ -41,7 +41,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 10 canonical codes are:
+Each dimension maps to one or more canonical finding categories from `docs/agent-frontmatter-schema.md`. The 11 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.
@@ -53,6 +53,7 @@ Each dimension maps to one or more canonical finding categories from `docs/agent
 - `bare-askuser-call` — workflow MD emits `AskUserQuestion` directly instead of `node np-tools.cjs askuser --json '{…}'` (D-04).
 - `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).
 
 Run each dimension below; for every failure, emit one finding using the matching canonical code.
 
@@ -117,6 +118,24 @@ Run each dimension below; for every failure, emit one finding using the matching
 - Extract actionable directives (forbidden patterns, required conventions, mandated tools).
 - Any plan action that violates them → map to the closest canonical code; if nothing fits, emit `unknown-category`.
 
+### Dimension 12: Reality-Check Completeness (Slice-Level, MANDATORY)
+
+This dimension exists because plans that look structurally fine still fail at execute-time when the planner encoded an unverified assumption (wrong package version, stale interface signature, prescribed command that does not exist in this env). The planner is required to produce a `<reality_check>` block per slice; you enforce that it actually did, and that the evidence is real.
+
+For every `S<NNN>-PLAN.md`:
+
+1. **Block presence** — confirm a `<reality_check>` block exists and appears ABOVE `<tasks>`. Missing or empty block → `unverified-assumption`, severity `critical`, target `S<NNN>-PLAN.md §reality_check`.
+2. **Sub-blocks present** — confirm `<files_read>`, `<commands_run>`, `<assumptions>`, and `<unknowns>` sub-blocks all exist. Missing sub-block → `unverified-assumption`, severity `critical`.
+3. **`<files_read>` integrity** — for each `path:line` (or `path:line-line`) entry, use `Glob` or `Read` to confirm the file exists in the repo. A path that does not resolve → `unverified-assumption`, severity `critical`, target the offending entry. (You do NOT need to confirm the line content — that is the planner's professional honesty, audited by the iter-2 PLAN-REVIEW trail.)
+4. **`<assumption>` `verified_by` integrity** — every `<assumption>` MUST carry a `verified_by` attribute. The attribute value MUST be either:
+   - a `path:line` string that appears verbatim in the slice's `<files_read>` block, OR
+   - a `cmd:<command>` string whose `<command>` substring appears verbatim in the slice's `<commands_run>` block.
+   Missing `verified_by`, empty `verified_by`, or `verified_by` pointing at evidence not present in the same `<reality_check>` → `unverified-assumption`, severity `critical`, target the offending `<assumption>`.
+5. **`<unknowns>` discipline** — if `<unknowns>` is non-empty, confirm the slice has a Wave-0 reconnaissance task (the first `<task>` in the slice, intra-slice parallel-safe) whose `<name>` or `<action>` references the unknown by phrase. No matching Wave-0 task → `unverified-assumption`, severity `critical`, target the unknown.
+6. **No silent waivers** — phrases like "TBD", "to be confirmed", "assume defaults", "should work", "presumably", "likely" inside `<reality_check>` are equivalent to a missing `verified_by` and emit `unverified-assumption`.
+
+This dimension is the empirical complement to Dimensions 1-11 (which are structural). Together they make the 2-iteration loop sufficient: structural defects caught by 1-11, empirical defects caught by 12.
+
 ## Verdict Format
 
 Emit exactly one fenced YAML block. No commentary before or after. The loop in Plan 05-10 parses only `status` and `findings[].category`.
@@ -156,7 +175,7 @@ Fields:
 
 | Severity | Meaning | Examples |
 |----------|---------|----------|
-| critical | Plan will not deliver the phase goal as written. MUST be fixed before execution. | `missing-success-criterion`, `cyclic-dependency`, `broken-dependency`, `forbidden-agent-field`, `hook-field-present`, `bare-askuser-call`. |
+| critical | Plan will not deliver the phase goal as written. MUST be fixed before execution. | `missing-success-criterion`, `cyclic-dependency`, `broken-dependency`, `forbidden-agent-field`, `hook-field-present`, `bare-askuser-call`, `unverified-assumption`. |
 | major | Plan will technically deliver but with defects the verifier will catch post-execution. SHOULD be fixed. | `non-atomic-task`, `missing-coverage-annotation`, `fake-promotion-trigger` when the mis-classification affects wave ordering. |
 | minor | Plan quality issue that does not block execution. INFO-level for the planner's revision. | `unbounded-scope` with obvious bounded intent, minor wording that hints at scope creep. |
 

package/agents/np-planner.md

@@ -86,6 +86,41 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Return structured results to orchestrator
 </role>
 
+<reality_check_protocol>
+## CRITICAL: Reality-Check Before Planning (MANDATORY)
+
+Plans fail at execute-time when they encode assumptions the planner never verified against the actual repo. To stop the replan-after-execute loop, BEFORE writing any `S<NNN>-PLAN.md` you MUST empirically verify every load-bearing assumption and record the evidence inside the slice plan.
+
+This is not optional. Plan-checker rejects any slice plan whose `<reality_check>` block is absent, empty, or contains `<assumption>` entries without a `verified_by` attribute (canonical category: `unverified-assumption`, severity `critical`).
+
+### What MUST be reality-checked per slice
+
+For every slice you plan, BEFORE writing its `S<NNN>-PLAN.md`:
+
+1. **Versions** — every library / framework / runtime version your plan will pin or rely on. Read the actual manifest the project loads (`composer.lock`, `package-lock.json`, `Gemfile.lock`, `go.mod`, `pyproject.toml`/`uv.lock`, `Pipfile.lock`, `cargo.lock`, etc.) at the precise line. Never derive a version from training data, RESEARCH.md narrative, or a web search alone — confirm it in the lockfile.
+2. **Interfaces** — every function / class / method / hook your plan tells the executor to call or modify. Open the file with `Read` and quote the actual signature in the slice plan. Do not trust memory; signatures change between versions.
+3. **Commands** — every shell command your plan prescribes (test runner, build, migration, package install, container exec). Run a non-mutating probe (`--version`, `--help`, `which <cmd>`, `<cmd> list`) to confirm the command exists and behaves as expected. Never prescribe a command you have not seen succeed in this environment.
+4. **Conventions** — every project convention your plan relies on (naming, dir layout, test framework choice, ORM patterns, auth stack). Confirm by reading at least one existing example in the repo. If `./CLAUDE.md` exists, it is authoritative — quote the relevant line.
+
+### Reality-check the riskiest assumption first
+
+If the slice introduces a new dependency, a major-version bump, or touches a stack you have not verified in this run, verify THAT first. A failed reality-check there changes the whole plan; finding it after writing tasks wastes the iteration.
+
+### When you cannot verify
+
+If an assumption cannot be empirically resolved from the repo or environment (the library is not yet installed, an external service is unreachable, the lockfile lacks a transitive resolution):
+
+- Add it to `<unknowns>` inside `<reality_check>` with the concrete reason.
+- Either resolve it via a Wave-0 reconnaissance task in this same slice (named after the unknown), OR exit the planning run and request `/np:research-phase` for this slice.
+- You may NOT silently encode an unverified assumption. The downstream cost is one wasted execute-phase plus one wasted plan-revision iteration — orders of magnitude higher than one extra `Read` or `Bash` call now.
+
+### What this is NOT
+
+- Not a security review (that's `np-security-reviewer`).
+- Not a research substitute (that's `np-researcher` — research finds what *should* be used; reality-check confirms what *is* installed/available).
+- Not exhaustive code reading. Read what the slice's tasks will touch — no more, no less.
+</reality_check_protocol>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 
@@ -227,19 +262,56 @@ If the executor has to stop and read three more files to figure out what you mea
 
 Before emitting a `PLAN.md`, run through this list once:
 
-1. **Frontmatter:** `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `requirements`, `must_haves` present and non-empty where required.
-2. **Objective:** Single `<objective>` block, names the PLAN-XX requirement it closes, states output explicitly.
-3. **Context:** `@path/to/file` references exist in the repo (do a quick `ls` / `Read` round-trip if unsure).
-4. **Tasks:** 1-3 tasks, each with `<files>`, `<action>`, `<verify><automated>…</automated></verify>`, `<done>`.
-5. **Dependencies:** `depends_on` references plan IDs that exist in the current ROADMAP wave graph.
-6. **Verification:** Every `<verify>` has an `<automated>` command. If no test exists yet, the task itself creates it (TDD) or a Wave-0 task does.
-7. **Success criteria:** Measurable, not prose-only. "Executes without throwing" > "works correctly".
-8. **No forbidden patterns:** No bare `AskUserQuestion` calls (use `node np-tools.cjs askuser --json '{...}'`); no legacy helper-CLI references (all helper calls use `np-tools.cjs`); no `hooks:` / `model:` / `model_profile:` fields in agent frontmatter.
+1. **Reality-Check Block:** `<reality_check>` is present, non-empty, and every `<assumption>` carries a non-empty `verified_by` attribute pointing to a `<files_read>` or `<commands_run>` entry. `<unknowns>` is either empty OR each entry maps to a Wave-0 reconnaissance task in this slice. (Failing this is a guaranteed plan-checker reject.)
+2. **Frontmatter:** `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `requirements`, `must_haves` present and non-empty where required.
+3. **Objective:** Single `<objective>` block, names the PLAN-XX requirement it closes, states output explicitly.
+4. **Context:** `@path/to/file` references exist in the repo (do a quick `ls` / `Read` round-trip if unsure).
+5. **Tasks:** 1-3 tasks, each with `<files>`, `<action>`, `<verify><automated>…</automated></verify>`, `<done>`.
+6. **Dependencies:** `depends_on` references plan IDs that exist in the current ROADMAP wave graph.
+7. **Verification:** Every `<verify>` has an `<automated>` command. If no test exists yet, the task itself creates it (TDD) or a Wave-0 task does.
+8. **Success criteria:** Measurable, not prose-only. "Executes without throwing" > "works correctly".
+9. **No forbidden patterns:** No bare `AskUserQuestion` calls (use `node np-tools.cjs askuser --json '{...}'`); no legacy helper-CLI references (all helper calls use `np-tools.cjs`); no `hooks:` / `model:` / `model_profile:` fields in agent frontmatter.
 
 If any check fails, fix before returning. Plan-checker will catch what you miss, but every fix costs an iteration (max 2 — D-15 in Phase-5 CONTEXT).
 </answer_validation>
 
 <task_format>
+## Slice Plan Layout (MANDATORY)
+
+Every `S<NNN>-PLAN.md` MUST open with a `<reality_check>` block ABOVE `<tasks>`. The block records the empirical evidence behind the slice's assumptions. Plan-checker fails any slice plan that omits it, leaves it empty, or whose `<assumption>` entries lack a `verified_by` attribute (`unverified-assumption`, critical).
+
+Required shape:
+
+```
+<reality_check>
+  <files_read>
+    - composer.lock:1245 (laravel/framework version)
+    - app/Models/User.php:18 (HasRoles trait already mixed in)
+  </files_read>
+  <commands_run>
+    - `php artisan about` → "Laravel Version: 11.31.0"
+    - `composer show spatie/laravel-permission` → "versions : * 6.10.1"
+  </commands_run>
+  <assumptions>
+    <assumption verified_by="composer.lock:1245">Laravel 11.31 is the installed major.minor — plan targets 11.x APIs.</assumption>
+    <assumption verified_by="app/Models/User.php:18">HasRoles trait already present — plan does NOT re-add it.</assumption>
+    <assumption verified_by="cmd:composer show spatie/laravel-permission">spatie/laravel-permission 6.10 is installed — no install task needed.</assumption>
+  </assumptions>
+  <unknowns>
+    <!-- Empty when every assumption is verified. Otherwise list each unresolved item with a reason and a Wave-0 task ID that resolves it. -->
+  </unknowns>
+</reality_check>
+```
+
+Rules:
+
+- **`<files_read>`**: every entry is `path:line` or `path:line-line` (a range). Plan-checker re-reads each path and confirms the file exists. Paste the precise line — do not paraphrase.
+- **`<commands_run>`**: every entry is `` `cmd` → "literal output substring" ``. The substring is what the planner observed. Plan-checker does NOT re-run commands; honesty is enforced by the iter-2 audit trail.
+- **`<assumptions>`**: every `<assumption>` MUST carry a non-empty `verified_by` attribute pointing to either a `<files_read>` path:line entry or a `cmd:<command>` entry already listed in `<commands_run>`. An assumption without `verified_by` is the same as no reality-check.
+- **`<unknowns>`**: empty in the happy path. If non-empty, the slice MUST contain a Wave-0 reconnaissance task (the first task in the slice) that resolves the unknown before downstream tasks run.
+
+Reality-check is a planner responsibility, not an executor responsibility. Anything the executor would discover in the first 60 seconds of work belongs in `<reality_check>`.
+
 ## Task XML Format (MANDATORY)
 
 Inside each `S<NNN>-PLAN.md`, every `<task>` tag MUST have these four attributes on the opening tag:

package/docs/agent-frontmatter-schema.md

@@ -69,6 +69,7 @@ Canonical identifiers for findings that `agents/np-plan-checker.md` emits. Start
 - `bare-askuser-call` — workflow MD emits `AskUserQuestion` directly instead of `node np-tools.cjs askuser --json '{…}'` (D-04).
 - `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. Enforces the empirical pre-flight performed by `agents/np-planner.md` so version / interface / command assumptions cannot reach the executor unverified.
 
 Each finding returned by plan-checker carries one of these codes plus an anchor `{file, line}` pair so the planner's revise-mode can address them without re-deriving context.
 

package/lib/plan-checker-contract.test.cjs

@@ -28,6 +28,7 @@ const CATEGORIES = [
   'bare-askuser-call',
   'hook-field-present',
   'forbidden-agent-field',
+  'unverified-assumption',
 ];
 
 const REQUIRED_H2 = [
@@ -51,7 +52,7 @@ test('PC-1: loadAgent(plan-checker) returns tier=opus and name=plan-checker', ()
   }
 });
 
-test('PC-2: body contains all 10 canonical finding-category identifiers', () => {
+test('PC-2: body contains all 11 canonical finding-category identifiers', () => {
   for (const c of CATEGORIES) {
     assert.ok(BODY.includes(c), 'missing canonical category: ' + c);
   }

package/package.json

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