nubos-pilot 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +37 -6
  4. package/SECURITY.md +60 -0
  5. package/agents/np-architect.md +1 -1
  6. package/agents/np-build-fixer.md +4 -4
  7. package/agents/np-executor.md +1 -1
  8. package/agents/np-plan-checker.md +5 -5
  9. package/agents/np-planner.md +2 -2
  10. package/agents/np-researcher.md +2 -2
  11. package/bin/check-workflows.cjs +1 -8
  12. package/bin/install.js +113 -62
  13. package/bin/np-tools/_args.cjs +16 -2
  14. package/bin/np-tools/_commands.cjs +4 -8
  15. package/bin/np-tools/_commands.test.cjs +31 -0
  16. package/bin/np-tools/_memory-resolve.cjs +4 -4
  17. package/bin/np-tools/askuser.cjs +2 -8
  18. package/bin/np-tools/checkpoint.cjs +1 -1
  19. package/bin/np-tools/close-project.cjs +3 -29
  20. package/bin/np-tools/commit-task.cjs +31 -37
  21. package/bin/np-tools/commit.cjs +2 -11
  22. package/bin/np-tools/config.cjs +6 -21
  23. package/bin/np-tools/discuss-phase.cjs +4 -27
  24. package/bin/np-tools/discuss-project.cjs +0 -27
  25. package/bin/np-tools/doctor.cjs +79 -30
  26. package/bin/np-tools/doctor.test.cjs +14 -0
  27. package/bin/np-tools/execute-milestone.cjs +6 -27
  28. package/bin/np-tools/handoff-write.cjs +16 -2
  29. package/bin/np-tools/help.cjs +5 -2
  30. package/bin/np-tools/init-dispatch.test.cjs +21 -0
  31. package/bin/np-tools/knowledge-search.cjs +7 -1
  32. package/bin/np-tools/lang-directive.cjs +2 -8
  33. package/bin/np-tools/learning-list.cjs +0 -2
  34. package/bin/np-tools/learning-log.cjs +6 -16
  35. package/bin/np-tools/loop-audit-tool-use.cjs +1 -11
  36. package/bin/np-tools/loop-preflight.cjs +4 -8
  37. package/bin/np-tools/loop-run-round.cjs +51 -148
  38. package/bin/np-tools/loop-state-read.cjs +1 -5
  39. package/bin/np-tools/loop-state-record.cjs +1 -27
  40. package/bin/np-tools/loop-stuck.cjs +1 -8
  41. package/bin/np-tools/messages-send.cjs +16 -2
  42. package/bin/np-tools/metrics.test.cjs +4 -4
  43. package/bin/np-tools/new-milestone.cjs +14 -3
  44. package/bin/np-tools/new-project.cjs +4 -2
  45. package/bin/np-tools/new-project.test.cjs +12 -0
  46. package/bin/np-tools/park.cjs +3 -2
  47. package/bin/np-tools/plan-lint.cjs +0 -19
  48. package/bin/np-tools/plan-milestone.cjs +9 -30
  49. package/bin/np-tools/propose-milestones.cjs +14 -3
  50. package/bin/np-tools/propose-milestones.test.cjs +27 -0
  51. package/bin/np-tools/research-phase.cjs +8 -41
  52. package/bin/np-tools/research-phase.test.cjs +2 -1
  53. package/bin/np-tools/researcher-reconcile.cjs +3 -21
  54. package/bin/np-tools/reset-slice.cjs +12 -18
  55. package/bin/np-tools/resolve-model.cjs +21 -26
  56. package/bin/np-tools/resolve-model.test.cjs +15 -5
  57. package/bin/np-tools/resume-work.cjs +1 -7
  58. package/bin/np-tools/scan-codebase.test.cjs +1 -1
  59. package/bin/np-tools/skip.cjs +3 -2
  60. package/bin/np-tools/spawn-headless.cjs +138 -19
  61. package/bin/np-tools/spawn-headless.test.cjs +310 -0
  62. package/bin/np-tools/state.cjs +3 -4
  63. package/bin/np-tools/state.test.cjs +2 -2
  64. package/bin/np-tools/stats.cjs +3 -9
  65. package/bin/np-tools/template-path.cjs +2 -8
  66. package/bin/np-tools/text-mode.cjs +2 -8
  67. package/bin/np-tools/undo-task.cjs +3 -2
  68. package/bin/np-tools/undo.cjs +7 -5
  69. package/bin/np-tools/unpark.cjs +3 -2
  70. package/bin/np-tools/update-docs.test.cjs +1 -1
  71. package/bin/np-tools/verify-work.cjs +82 -25
  72. package/bin/np-tools/verify-work.test.cjs +211 -1
  73. package/bin/researcher-merge.cjs +9 -2
  74. package/bin/researcher-merge.test.cjs +14 -0
  75. package/lib/agents-registry.cjs +32 -0
  76. package/lib/agents.cjs +16 -6
  77. package/lib/agents.test.cjs +44 -0
  78. package/lib/archive.cjs +105 -39
  79. package/lib/archive.test.cjs +147 -5
  80. package/lib/checkpoint.cjs +43 -27
  81. package/lib/checkpoint.test.cjs +67 -6
  82. package/lib/codebase-docs.cjs +7 -9
  83. package/lib/codebase-docs.test.cjs +2 -2
  84. package/lib/codebase-manifest.cjs +2 -0
  85. package/lib/commit-policy.cjs +6 -29
  86. package/lib/commit-policy.test.cjs +6 -0
  87. package/lib/config-defaults.cjs +5 -2
  88. package/lib/config-defaults.test.cjs +71 -0
  89. package/lib/config-schema.cjs +204 -0
  90. package/lib/config-schema.test.cjs +148 -0
  91. package/lib/config.cjs +194 -9
  92. package/lib/config.test.cjs +234 -0
  93. package/lib/core.cjs +231 -47
  94. package/lib/core.test.cjs +193 -10
  95. package/lib/dashboard.cjs +0 -12
  96. package/lib/frontmatter.cjs +12 -18
  97. package/lib/git.cjs +34 -56
  98. package/lib/git.test.cjs +11 -3
  99. package/lib/handoff.cjs +19 -20
  100. package/lib/handoff.test.cjs +24 -0
  101. package/lib/ids.cjs +6 -0
  102. package/lib/init-emit.cjs +33 -0
  103. package/lib/install/backup.cjs +19 -14
  104. package/lib/install/claude-hooks.cjs +46 -25
  105. package/lib/install/claude-hooks.test.cjs +64 -0
  106. package/lib/install/codex-toml.cjs +15 -66
  107. package/lib/install/manifest.cjs +19 -0
  108. package/lib/install/manifest.test.cjs +107 -0
  109. package/lib/install/runtime-assets.cjs +4 -3
  110. package/lib/install/runtime-detect.cjs +1 -1
  111. package/lib/install/runtimes-registry.cjs +0 -5
  112. package/lib/knowledge-adapter.cjs +4 -57
  113. package/lib/knowledge-adapter.test.cjs +0 -20
  114. package/lib/knowledge.cjs +21 -5
  115. package/lib/language.cjs +3 -19
  116. package/lib/learnings.cjs +3 -108
  117. package/lib/logger.cjs +157 -0
  118. package/lib/logger.test.cjs +159 -0
  119. package/lib/memory-index-usearch.cjs +9 -12
  120. package/lib/memory-provider-local.cjs +8 -0
  121. package/lib/memory.cjs +90 -23
  122. package/lib/memory.test.cjs +135 -0
  123. package/lib/messaging.cjs +155 -83
  124. package/lib/metrics-aggregate.cjs +28 -28
  125. package/lib/metrics.cjs +10 -4
  126. package/lib/metrics.test.cjs +6 -5
  127. package/lib/migrations.cjs +89 -0
  128. package/lib/migrations.test.cjs +82 -0
  129. package/lib/milestone-meta.cjs +70 -0
  130. package/lib/model-profiles.cjs +2 -0
  131. package/lib/nubosloop-audit.cjs +244 -0
  132. package/lib/nubosloop.cjs +79 -412
  133. package/lib/nubosloop.test.cjs +52 -21
  134. package/lib/output-lint.cjs +1 -1
  135. package/lib/plan-lint.cjs +0 -67
  136. package/lib/researcher-reconciler.cjs +5 -10
  137. package/lib/researcher-swarm.cjs +54 -101
  138. package/lib/roadmap-render.cjs +108 -34
  139. package/lib/roadmap-schema.cjs +42 -0
  140. package/lib/roadmap.cjs +99 -35
  141. package/lib/roadmap.test.cjs +215 -0
  142. package/lib/run-context.cjs +54 -0
  143. package/lib/run-context.test.cjs +53 -0
  144. package/lib/runtime/_factory.cjs +19 -0
  145. package/lib/runtime/antigravity.cjs +4 -12
  146. package/lib/runtime/augment.cjs +4 -12
  147. package/lib/runtime/claude.cjs +2 -0
  148. package/lib/runtime/cline.cjs +4 -12
  149. package/lib/runtime/codebuddy.cjs +4 -12
  150. package/lib/runtime/codex.cjs +4 -12
  151. package/lib/runtime/copilot.cjs +4 -12
  152. package/lib/runtime/cursor.cjs +4 -12
  153. package/lib/runtime/gemini.cjs +4 -12
  154. package/lib/runtime/index.cjs +7 -10
  155. package/lib/runtime/index.test.cjs +13 -1
  156. package/lib/runtime/kilo.cjs +4 -12
  157. package/lib/runtime/opencode.cjs +4 -12
  158. package/lib/runtime/qwen.cjs +4 -12
  159. package/lib/runtime/trae.cjs +4 -12
  160. package/lib/runtime/windsurf.cjs +4 -12
  161. package/lib/safe-path.cjs +156 -0
  162. package/lib/safe-path.test.cjs +164 -0
  163. package/lib/state.cjs +33 -10
  164. package/lib/state.test.cjs +90 -21
  165. package/lib/tasks.cjs +92 -14
  166. package/lib/tasks.test.cjs +65 -0
  167. package/lib/template.cjs +0 -1
  168. package/lib/text-mode.cjs +4 -30
  169. package/lib/todo.cjs +7 -5
  170. package/lib/verify.cjs +47 -16
  171. package/lib/workspace-scan.cjs +2 -0
  172. package/lib/worktree.cjs +3 -9
  173. package/lib/yaml.cjs +44 -0
  174. package/lib/yaml.test.cjs +65 -0
  175. package/np-tools.cjs +39 -50
  176. package/package.json +7 -6
  177. package/templates/COMPLETENESS.md +3 -3
  178. package/workflows/add-tests.md +1 -1
  179. package/workflows/architect-phase.md +1 -1
  180. package/workflows/doctor.md +7 -5
  181. package/workflows/execute-phase.md +13 -9
  182. package/workflows/plan-phase.md +3 -3
  183. package/workflows/research-phase.md +2 -2
  184. package/bin/np-tools/research-merge.cjs +0 -105
  185. package/bin/np-tools/research-merge.test.cjs +0 -166
  186. package/docs/adr/0001-no-daemon-invariant.md +0 -82
  187. package/docs/adr/0002-zero-runtime-dependencies.md +0 -91
  188. package/docs/adr/0003-max-six-unit-types.md +0 -85
  189. package/docs/adr/0004-atomic-commit-per-unit.md +0 -102
  190. package/docs/adr/0005-three-orthogonal-file-trees.md +0 -98
  191. package/docs/adr/0006-yaml-dependency-amendment.md +0 -60
  192. package/docs/adr/0007-codebase-docs-layer.md +0 -273
  193. package/docs/adr/0008-worktree-isolation-per-slice.md +0 -140
  194. package/docs/adr/0009-tui-framework-for-dashboard.md +0 -95
  195. package/docs/adr/0010-nubosloop.md +0 -244
  196. package/docs/adr/0011-researcher-swarm-consensus.md +0 -84
  197. package/docs/adr/0012-completeness-doctrine.md +0 -85
  198. package/docs/adr/0013-learnings-store-schema-evolution.md +0 -128
  199. package/docs/adr/0013-plan-trust-layer.md +0 -95
  200. package/docs/adr/0014-vector-memory-layer.md +0 -175
  201. package/docs/adr/0015-named-agent-messaging.md +0 -162
  202. package/docs/adr/README.md +0 -37
  203. package/docs/agent-frontmatter-schema.md +0 -105
  204. package/docs/phase-artifact-schemas.md +0 -292
  205. package/docs/phase-directory-layout.md +0 -82
  206. package/lib/install/mcp-writer.cjs +0 -127
  207. package/mcp-configs/README.md +0 -41
  208. package/mcp-configs/claude-code.example.json +0 -27
  209. package/mcp-configs/codex.example.toml +0 -17
  210. package/mcp-configs/nubos-knowledge.notes.md +0 -42
package/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ All notable changes to nubos-pilot are documented in this file. Format
4
+ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
5
+ follows [SemVer](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [1.1.4] — 2026-05-25
8
+
9
+ Public release.
10
+
11
+ - Plan, execute, and verify code changes through a researcher + critic
12
+ agent loop.
13
+ - Wave-based milestone execution; one atomic git commit per task.
14
+ - Multi-runtime install for 14 host CLIs (Claude Code, Codex, Gemini,
15
+ OpenCode, Cursor, and more) via `npx nubos-pilot`.
16
+ - Local vector memory for cross-task learnings.
17
+ - Inter-agent messages, handoffs, and project archive with crash-safe
18
+ resume.
19
+ - Hardened filesystem operations: symlink-rejecting locks, restricted
20
+ permissions on audit logs, path containment for file-input flags,
21
+ frontmatter sanitisation, and a memory-model allow-list.
22
+
23
+ Full documentation at <https://pilot.nubos.cloud>.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Nubos AI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -5,7 +5,7 @@ AI-driven planning and execution tool for code projects. Installs into 14 host C
5
5
  - **No daemon.** Every command runs as a short-lived `node` invocation.
6
6
  - **Markdown-first.** Workflows and agents are plain `.md` files — the host reads them directly.
7
7
  - **Atomic per-task commits.** One `task(M<NNN>-S<NNN>-T<NNNN>): …` commit per unit of work. `/np:undo-task` and `/np:undo` are mechanical reverts.
8
- - **Multi-runtime.** One source tree, one install payload, four first-class host CLIs.
8
+ - **Multi-runtime.** One source tree, one install payload, fourteen supported host CLIs.
9
9
 
10
10
  ## Install
11
11
 
@@ -95,16 +95,18 @@ task(M001-S001-T0002): wire login handler
95
95
 
96
96
  ## Agents
97
97
 
98
- Eleven subagents are installed into the host's agent directory:
98
+ Thirteen spawnable subagents are installed into the host's agent directory (alongside three `np-critic-*` audit modules consumed by `np-critic`):
99
99
 
100
100
  - `np-planner` (opus) — breaks a milestone into slices + tasks
101
101
  - `np-plan-checker` (opus) — adversarial goal-backward review before execution
102
102
  - `np-architect` (sonnet) — optional ADR-style decisions before planning
103
103
  - `np-researcher` (sonnet) — milestone-level stack + pitfalls research
104
+ - `np-researcher-reconciler` (sonnet) — reconciles disagreements across researcher-swarm outputs
104
105
  - `np-sc-extractor` (haiku) — derives observable Success Criteria from goal + CONTEXT
105
106
  - `np-codebase-documenter` (sonnet) — maintains `.nubos-pilot/codebase/` module docs
106
107
  - `np-executor` (sonnet) — one task per spawn, one commit per task
107
108
  - `np-build-fixer` (sonnet) — recovery patcher for executor verify failures (manual spawn)
109
+ - `np-critic` (sonnet) — Nubosloop critic; audits executor output across style, tests and acceptance
108
110
  - `np-verifier` (sonnet) — post-execution Pass/Fail/Defer per success_criterion
109
111
  - `np-nyquist-auditor` (haiku) — requirement test-coverage audit
110
112
  - `np-security-reviewer` (sonnet) — OWASP-aligned read-only audit (manual spawn)
@@ -113,7 +115,7 @@ Every spawn runs with an **explicit tier** (`haiku` / `sonnet` / `opus`) resolve
113
115
 
114
116
  ## Model profile
115
117
 
116
- Five profiles (`frontier`, `quality`, `balanced`, `budget`, `inherit`) map each tier (`haiku` / `sonnet` / `opus`) to a concrete model. Set at install time (`Model-Profile?` prompt) or in `.nubos-pilot/config.json`. Full matrix in `docs/agent-frontmatter-schema.md`.
118
+ Five profiles (`frontier`, `quality`, `balanced`, `budget`, `inherit`) map each tier (`haiku` / `sonnet` / `opus`) to a concrete model. Set at install time (`Model-Profile?` prompt) or in `.nubos-pilot/config.json`.
117
119
 
118
120
  ## Requirements
119
121
 
@@ -131,11 +133,11 @@ node np-tools.cjs help # JSON: { commands: [ { name, category, descrip
131
133
  ## Doctor
132
134
 
133
135
  ```bash
134
- npx nubos-pilot doctor # 6-check integrity scan
136
+ npx nubos-pilot doctor # 12-check integrity scan
135
137
  npx nubos-pilot doctor --fix # auto-fix what's safely fixable
136
138
  ```
137
139
 
138
- Checks: payload manifest integrity, version mismatch, hooks presence, codex-toml sanity, askuser runtime availability, codebase docs freshness, milestone/slice directory layout.
140
+ Checks: payload manifest integrity, version mismatch, hooks presence, codex-toml sanity, askuser runtime availability, codebase docs freshness, milestone/slice directory layout, the three Nubosloop checks (critics present, knowledge store, config), orphan temp files, and output schemas.
139
141
 
140
142
  ## Development
141
143
 
@@ -144,6 +146,35 @@ npm test # all unit tests via node:test
144
146
  node bin/check-workflows.cjs # workflow linter
145
147
  ```
146
148
 
149
+ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for setup, code conventions, ADR
150
+ map and commit format.
151
+
152
+ ## Architecture Decisions
153
+
154
+ ADRs live in the VitePress at
155
+ [`pilot.nubos.cloud/v1/adr/`](https://pilot.nubos.cloud/v1/adr/). The
156
+ load-bearing ones for users and contributors:
157
+
158
+ | ADR | What it pins |
159
+ |---|---|
160
+ | 0004 | `workflow.commit_artifacts` controls whether `.nubos-pilot/` is committed |
161
+ | 0010 | Nubosloop — researcher → executor → critic-schwarm is mandatory in `/np:execute-phase` |
162
+ | 0012 | Completeness doctrine (12 rules in `templates/COMPLETENESS.md`) |
163
+ | 0013 | Learnings-store schema evolution |
164
+ | 0017 | Strict output-schema enforcement |
165
+ | 0019 | Plan-side trust layer (`lib/plan-lint.cjs`) |
166
+
167
+ ## Security
168
+
169
+ See [`SECURITY.md`](./SECURITY.md) for the vulnerability disclosure policy
170
+ and threat model.
171
+
172
+ ## Support
173
+
174
+ - Bugs / features: [GitHub issues](https://github.com/Nubos-AI/nubos-pilot/issues)
175
+ - Security: `security@nubos.ai` (see [`SECURITY.md`](./SECURITY.md))
176
+ - Docs: <https://pilot.nubos.cloud>
177
+
147
178
  ## License
148
179
 
149
- MIT
180
+ MIT — see [`LICENSE`](./LICENSE).
package/SECURITY.md ADDED
@@ -0,0 +1,60 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a Vulnerability
4
+
5
+ If you discover a security issue in nubos-pilot, **do not open a public issue**.
6
+ Email **security@nubos.ai** with:
7
+
8
+ - A description of the issue and its impact.
9
+ - Steps to reproduce (PoC if possible).
10
+ - The affected version (`npx nubos-pilot --version` or check `package.json`).
11
+ - Your preferred contact channel for follow-up.
12
+
13
+ We will acknowledge receipt within **3 business days** and provide a
14
+ resolution plan within **14 business days**. Fixes are released as patch
15
+ versions and announced in `CHANGELOG.md`.
16
+
17
+ ## Supported Versions
18
+
19
+ | Version | Supported |
20
+ |---------|-----------|
21
+ | 0.2.x | ✅ active |
22
+ | < 0.2 | ❌ end of life |
23
+
24
+ Only the latest minor on the current major receives security patches until
25
+ 1.0 is reached.
26
+
27
+ ## Threat Model
28
+
29
+ nubos-pilot is a **local CLI** distributed via npm to developer workstations
30
+ and CI. It is **not** a hosted service. The threat surface and assumptions:
31
+
32
+ | What nubos-pilot reads | What it writes | What it executes |
33
+ |---|---|---|
34
+ | `.nubos-pilot/`, project source for context | `.nubos-pilot/` state, `~/.codex/`, `~/.claude/` config (install only) | `git`, `claude`/`codex` headless via `child_process.spawn` |
35
+
36
+ **Trust boundaries:**
37
+
38
+ - **Project source code** — untrusted in the sense that agent-authored
39
+ files (`PLAN.md`, `RESEARCH.md` etc.) may contain hostile YAML. nubos-pilot
40
+ rejects prototype-pollution keys, refuses symlink-escape via `safe-path`,
41
+ caps message bodies, and whitelists ML model identifiers.
42
+ - **`.nubos-pilot/messages/`** — multi-agent inbox; entries are written
43
+ atomically with `O_CREAT|O_EXCL|O_NOFOLLOW` (POSIX) so a pre-planted
44
+ symlink cannot redirect writes.
45
+ - **Subprocess spawn** — `claude`/`codex` are invoked via `spawnSync` (no
46
+ shell). The binary path is overridable via `NUBOS_PILOT_CLAUDE_BIN` /
47
+ `NUBOS_PILOT_CODEX_BIN`; treat operators who can set those env vars as
48
+ trusted.
49
+ - **`workflow.commit_artifacts`** flag controls whether `.nubos-pilot/`
50
+ artifacts are committed to git. Default is `true`; downstream projects
51
+ that consider artifacts sensitive should set it to `false`.
52
+
53
+ ## What is Out of Scope
54
+
55
+ - Vulnerabilities in `@huggingface/transformers`, `usearch`, or the
56
+ `yaml` package — report those upstream.
57
+ - Operator-controlled config (`config.json`) that the operator themselves
58
+ wrote — config is trusted input from the project owner.
59
+ - DoS from running nubos-pilot in obviously bad conditions
60
+ (no disk space, no Node 22+, broken `git`).
@@ -70,7 +70,7 @@ If the project already documents a module/pattern that fits, extend it instead o
70
70
 
71
71
  ## Output Contract
72
72
 
73
- **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.
73
+ **Granularity (ADR-0019).** Architecture decisions are intent-level: which library, which boundary, which protocol. They do NOT prescribe implementation — no schema DDL, no exact framework-generated filenames, no code-style edicts. Those are executor-territory and downstream `np-planner` will refuse plans that bake them in (Plan-side Trust Layer, ADR-0019). If you find yourself describing how a controller method should be structured, stop — that's not architecture.
74
74
 
75
75
  ```markdown
76
76
  # M<NNN> — <milestone name> — Architecture
@@ -58,9 +58,9 @@ The orchestrator provides these in your prompt context. Read every path it hands
58
58
  - `infra` (missing tool, network, env var) → STOP and emit `## INFRA BLOCKER` block; do not edit source.
59
59
  1a. **MANDATORY knowledge lookup (Rule 9 — non-optional, runs before any Edit).** Pick the failing symbol or error class from Step 1 and run:
60
60
  ```bash
61
- node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol-or-error-class>" --limit 5
61
+ node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol-or-error-class>" --task <task-id> --limit 5
62
62
  ```
63
- If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Skipping this step stamps `rule-9-violation` in the Layer-C audit log and the loop routes back to the researcher swarm next round — it is **not** an opt-out.
63
+ The `--task <task-id>` flag is required: it records the Rule 9 evidence the tool-use audit cross-checks. A `knowledge-search` run without it leaves no ledger entry, so the audit treats the spawn as if it never searched (`rule-9-search-tool-unverified`). If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Skipping this step stamps `rule-9-violation` in the Layer-C audit log and the loop routes back to the researcher swarm next round — it is **not** an opt-out.
64
64
  2. **Locate the failure surface** strictly inside `files_modified`. If the failure points outside that set, emit `## SCOPE EXPANSION REQUEST` and stop — do NOT edit out-of-scope files.
65
65
  3. **Propose the smallest patch** that addresses the root cause:
66
66
  - For `compile` / `lint`: edit the offending file directly.
@@ -72,10 +72,10 @@ The orchestrator provides these in your prompt context. Read every path it hands
72
72
 
73
73
  ## Mandatory Knowledge Lookup (Rule 9)
74
74
 
75
- **This is non-optional, not advisory.** Workflow Step 1a runs the lookup before any Edit. Skipping it stamps `rule-9-violation` in the audit log and forces a re-route to the researcher swarm.
75
+ **This is non-optional, not advisory.** Workflow Step 1a runs the lookup before any Edit. Skipping it — or running it without `--task` — stamps `rule-9-violation` in the audit log and forces a re-route to the researcher swarm.
76
76
 
77
77
  ```bash
78
- node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol>" --limit 5
78
+ node .nubos-pilot/bin/np-tools.cjs knowledge-search "<failing-symbol>" --task <task-id> --limit 5
79
79
  ```
80
80
 
81
81
  If a hit lives in `.nubos-pilot/codebase/<module>.md`, `Read` that doc before patching. Cross-task context belongs in `RULES.md` and `M<NNN>-CONTEXT.md`.
@@ -31,7 +31,7 @@ This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENES
31
31
  - **Rule 3 — Do it with tests.** Every commit ships tests for the production code it adds or changes. No "trivial enough to skip tests" exceptions.
32
32
  - **Rule 4 — Do it with documentation.** Update `.nubos-pilot/codebase/<module>.md` after every commit (`update-docs` is mandatory, not optional).
33
33
  - **Rule 7 — Never leave a dangling thread.** Dead imports, unused symbols, half-renamed identifiers — clean them up in the same commit that introduces the change.
34
- - **Rule 9 — Search before building.** Run `knowledge-search` for the symbols you plan to introduce before writing them. Reuse beats reinvention.
34
+ - **Rule 9 — Search before building.** Before writing any new symbol, run `node np-tools.cjs knowledge-search "<symbol>" --task <task-id>` via Bash. The `--task <task-id>` flag is mandatory — it records the evidence the Rule 9 tool-use audit cross-checks; a lookup without it counts as no search. Reuse beats reinvention.
35
35
  - **Rule 10 — Test before shipping.** Verify must be green before you call `commit-task`. Manual "I ran it once" is not proof of work.
36
36
 
37
37
  Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
@@ -28,7 +28,7 @@ Refusal of any rule is a hard-stop. Surface the violation to the orchestrator ve
28
28
 
29
29
  ## Role
30
30
 
31
- Adversarial reader of milestone plans. You assume the planner made mistakes and look for them systematically. You enforce the canonical finding-category taxonomy published in `docs/agent-frontmatter-schema.md` — every issue you emit MUST use one of those codes verbatim.
31
+ Adversarial reader of milestone plans. You assume the planner made mistakes and look for them systematically. You enforce the canonical finding-category taxonomy defined below — every issue you emit MUST use one of those codes verbatim.
32
32
 
33
33
  You are NOT the executor (`/np:execute-phase`) and NOT the post-execution verifier (`/np:validate-phase`). You verify plans WILL work before execution; the verifier confirms code DID work after execution. Same goal-backward methodology, different timing.
34
34
 
@@ -53,7 +53,7 @@ Additional context the orchestrator may inline in the prompt:
53
53
 
54
54
  ## Review Dimensions
55
55
 
56
- Each dimension maps to one or more canonical finding categories from `docs/agent-frontmatter-schema.md`. The 14 canonical codes are:
56
+ Each dimension maps to one or more canonical finding categories. The 14 canonical codes are:
57
57
 
58
58
  - `missing-success-criterion` — a ROADMAP SC-X is not mapped to any task.
59
59
  - `non-atomic-task` — a task bundles multiple distinct deliverables that should be split.
@@ -66,9 +66,9 @@ Each dimension maps to one or more canonical finding categories from `docs/agent
66
66
  - `hook-field-present` — agent frontmatter contains `hooks:` (D-10).
67
67
  - `forbidden-agent-field` — agent frontmatter contains `model:` or `model_profile:` (D-10).
68
68
  - `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).
69
- - `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.
70
- - `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).
71
- - `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).
69
+ - `verify-command-unknown` — a `<verify>` block invokes a command that is not a known np-tools verb, declared composer/npm script, vendor binary, or POSIX baseline tool (Plan-side Trust Layer, ADR-0019). Mechanically detected by `np-tools.cjs plan-lint`; you mirror the verdict into your findings array so the loop handler treats it uniformly with semantic findings.
70
+ - `parallel-task-implicit-dependency` — tasks marked `depends_on: []` in the same slice but one of them runs a working-tree-reading verify (`update-docs`, `phpstan analyse`, `git diff`, etc.) against files another sibling modifies. Implicit ordering must be made explicit (Plan-side Trust Layer, ADR-0019).
71
+ - `plan-over-specifies-implementation` — PLAN.md body contains schema DDL, framework-controlled timestamped filenames, or large inline code snippets. Plans specify intent + boundary + acceptance, not implementation. Severity is `major` (advisory) — not a hard block, but you flag it so the planner course-corrects (Plan-side Granularity Doctrine, ADR-0019).
72
72
 
73
73
  Note on the Nubosloop critic: as of 2026-05-05 a single `np-critic` agent covers style + tests + acceptance in one spawn (ADR-0010 §Single-Critic Revision). The legacy three-critic schwarm (`np-critic-style`/`np-critic-tests`/`np-critic-acceptance`) is removed. References in older plans should be updated.
74
74
 
@@ -277,7 +277,7 @@ Every PLAN.md you write will be consumed by an executor agent that:
277
277
  **Implications for your writing style:**
278
278
 
279
279
  - **Name the library, not the category.** "Use `jose` for JWT" > "use a JWT library".
280
- - **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).
280
+ - **Name the file, not the area** — for *deterministic edits the planner can know up-front*. "Modify `src/api/auth/login.ts`" > "update the auth layer". For *scaffolding tasks where a framework generates files at install/publish time*, use a glob (`database/migrations/*_cashier_*.php`) or leave `files_modified` empty — the executor resolves the real paths from the actual publish output and `commit-task` falls back to `checkpoint.files_touched` (D-04, ADR-0019 Layer-D Granularity).
281
281
  - **Name the command, not the intent.** "Run `npm test -- --filter=auth`" > "run the tests".
282
282
  - **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.
283
283
  - **Document deviations from canonical advice.** If you deviate from CONTEXT.md's stack choice, say so explicitly and note why.
@@ -286,7 +286,7 @@ If the executor has to stop and read three more files to figure out what you mea
286
286
  </downstream_awareness>
287
287
 
288
288
  <plan_granularity>
289
- ## Plan Granularity Doctrine — Intent + Boundary + Acceptance, NOT Implementation (ADR-0013)
289
+ ## Plan Granularity Doctrine — Intent + Boundary + Acceptance, NOT Implementation (ADR-0019)
290
290
 
291
291
  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.
292
292
 
@@ -24,7 +24,7 @@ Your output is prescriptive, not exploratory: "Use library X at version Y" beats
24
24
  This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). The rules that bind this role:
25
25
 
26
26
  - **Rule 5 — Aim to genuinely impress.** Prescriptive beats exploratory. "Use `jose@6.0.10`" beats "consider a JWT library". Vague research produces vague plans, vague plans produce vague software.
27
- - **Rule 9 — Search before building.** This is your core job. Before any new claim, search the local knowledge index (`knowledge-search`), the codebase docs (`.nubos-pilot/codebase/`), and Context7 / WebFetch. Reuse prior learnings.
27
+ - **Rule 9 — Search before building.** This is your core job. Before any new claim, search the local knowledge index via `node np-tools.cjs knowledge-search "<query>"` (pass `--task <task-id>` when spawned inside the execute-loop so the Rule 9 audit ledger records the call), the codebase docs (`.nubos-pilot/codebase/`), and Context7 / WebFetch. Reuse prior learnings.
28
28
  - **Rule 11 — Ship the complete thing.** RESEARCH.md is a deliverable, not a draft. Every claim has provenance, every assumption is tagged `[ASSUMED]`, every gap is listed in `Open Questions`. No half-research.
29
29
 
30
30
  Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
@@ -37,7 +37,7 @@ Your per-spawn output MUST conform to the **`researcher-output`** schema. The or
37
37
 
38
38
  Hard rules from the schema:
39
39
 
40
- - Frontmatter must include `schema_version`, `agent: np-researcher`, `spawn_index`, `seed_delta`, `task_query_hash`, plus count fields (`decision_count`, `risk_count`, etc.).
40
+ - Frontmatter must include `schema_version`, `agent: np-researcher`, `spawn_index`, `seed_delta`, `task_query_hash`, plus count fields (`decision_count`, `risk_count`, etc.). `spawn_index` and `seed_delta` are **integers** — copy them verbatim from the `index` / `seed_delta` fields of your spawn spec. The prose perspective nudge arrives on the spawn spec's separate `seed_nudge` field; it shapes HOW you investigate and never goes into frontmatter.
41
41
  - Five body sections are pflichtig (use `_None._` if empty): `## Decisions`, `## Risks`, `## Patterns`, `## Open Questions`, `## Sources`.
42
42
  - Every Decision / Risk / Pattern / Open Question / Source uses heading style `### <PREFIX>-N: <text>` where PREFIX ∈ {D, R, P, Q, S}.
43
43
  - **Every entry has a `**Reasoning:**` field** (mandatory). The Reasoning field documents what you weighed, what you discarded, and why this conclusion. The reconciler compares `Reasoning` traces across spawns to detect groupthink (identical reasoning → low independent evidence) vs orthogonal evidence (different reasoning paths to same conclusion → strong signal).
@@ -66,8 +66,6 @@ function _scanMetricsCoverage(files) {
66
66
  const raw = fs.readFileSync(file, 'utf-8');
67
67
  const lines = raw.split(/\r?\n/);
68
68
 
69
-
70
-
71
69
  let inAnyFence = false;
72
70
  let inBashFence = false;
73
71
  for (let i = 0; i < lines.length; i++) {
@@ -102,10 +100,6 @@ function _scanMetricsCoverage(files) {
102
100
  return warnings;
103
101
  }
104
102
 
105
- function _scan(dir) {
106
- return _scanFiles(_walk(dir, [], { ext: ['.md'] }));
107
- }
108
-
109
103
  function _scanInstallerSurface(cwd) {
110
104
  const root = cwd || process.cwd();
111
105
  const files = [];
@@ -131,7 +125,7 @@ function checkWorkflows(dir) {
131
125
  violations.push(..._scanFiles(workflowFiles));
132
126
  warnings.push(..._scanMetricsCoverage(workflowFiles));
133
127
  }
134
- } catch { }
128
+ } catch {}
135
129
  violations.push(..._scanInstallerSurface());
136
130
  return { violations, warnings, exitCode: violations.length ? 1 : 0 };
137
131
  }
@@ -158,7 +152,6 @@ if (require.main === module) main();
158
152
 
159
153
  module.exports = {
160
154
  checkWorkflows,
161
- _scan,
162
155
  _scanFiles,
163
156
  _scanInstallerSurface,
164
157
  _scanMetricsCoverage,