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.
- package/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +37 -6
- package/SECURITY.md +60 -0
- package/agents/np-architect.md +1 -1
- package/agents/np-build-fixer.md +4 -4
- package/agents/np-executor.md +1 -1
- package/agents/np-plan-checker.md +5 -5
- package/agents/np-planner.md +2 -2
- package/agents/np-researcher.md +2 -2
- package/bin/check-workflows.cjs +1 -8
- package/bin/install.js +113 -62
- package/bin/np-tools/_args.cjs +16 -2
- package/bin/np-tools/_commands.cjs +4 -8
- package/bin/np-tools/_commands.test.cjs +31 -0
- package/bin/np-tools/_memory-resolve.cjs +4 -4
- package/bin/np-tools/askuser.cjs +2 -8
- package/bin/np-tools/checkpoint.cjs +1 -1
- package/bin/np-tools/close-project.cjs +3 -29
- package/bin/np-tools/commit-task.cjs +31 -37
- package/bin/np-tools/commit.cjs +2 -11
- package/bin/np-tools/config.cjs +6 -21
- package/bin/np-tools/discuss-phase.cjs +4 -27
- package/bin/np-tools/discuss-project.cjs +0 -27
- package/bin/np-tools/doctor.cjs +79 -30
- package/bin/np-tools/doctor.test.cjs +14 -0
- package/bin/np-tools/execute-milestone.cjs +6 -27
- package/bin/np-tools/handoff-write.cjs +16 -2
- package/bin/np-tools/help.cjs +5 -2
- package/bin/np-tools/init-dispatch.test.cjs +21 -0
- package/bin/np-tools/knowledge-search.cjs +7 -1
- package/bin/np-tools/lang-directive.cjs +2 -8
- package/bin/np-tools/learning-list.cjs +0 -2
- package/bin/np-tools/learning-log.cjs +6 -16
- package/bin/np-tools/loop-audit-tool-use.cjs +1 -11
- package/bin/np-tools/loop-preflight.cjs +4 -8
- package/bin/np-tools/loop-run-round.cjs +51 -148
- package/bin/np-tools/loop-state-read.cjs +1 -5
- package/bin/np-tools/loop-state-record.cjs +1 -27
- package/bin/np-tools/loop-stuck.cjs +1 -8
- package/bin/np-tools/messages-send.cjs +16 -2
- package/bin/np-tools/metrics.test.cjs +4 -4
- package/bin/np-tools/new-milestone.cjs +14 -3
- package/bin/np-tools/new-project.cjs +4 -2
- package/bin/np-tools/new-project.test.cjs +12 -0
- package/bin/np-tools/park.cjs +3 -2
- package/bin/np-tools/plan-lint.cjs +0 -19
- package/bin/np-tools/plan-milestone.cjs +9 -30
- package/bin/np-tools/propose-milestones.cjs +14 -3
- package/bin/np-tools/propose-milestones.test.cjs +27 -0
- package/bin/np-tools/research-phase.cjs +8 -41
- package/bin/np-tools/research-phase.test.cjs +2 -1
- package/bin/np-tools/researcher-reconcile.cjs +3 -21
- package/bin/np-tools/reset-slice.cjs +12 -18
- package/bin/np-tools/resolve-model.cjs +21 -26
- package/bin/np-tools/resolve-model.test.cjs +15 -5
- package/bin/np-tools/resume-work.cjs +1 -7
- package/bin/np-tools/scan-codebase.test.cjs +1 -1
- package/bin/np-tools/skip.cjs +3 -2
- package/bin/np-tools/spawn-headless.cjs +138 -19
- package/bin/np-tools/spawn-headless.test.cjs +310 -0
- package/bin/np-tools/state.cjs +3 -4
- package/bin/np-tools/state.test.cjs +2 -2
- package/bin/np-tools/stats.cjs +3 -9
- package/bin/np-tools/template-path.cjs +2 -8
- package/bin/np-tools/text-mode.cjs +2 -8
- package/bin/np-tools/undo-task.cjs +3 -2
- package/bin/np-tools/undo.cjs +7 -5
- package/bin/np-tools/unpark.cjs +3 -2
- package/bin/np-tools/update-docs.test.cjs +1 -1
- package/bin/np-tools/verify-work.cjs +82 -25
- package/bin/np-tools/verify-work.test.cjs +211 -1
- package/bin/researcher-merge.cjs +9 -2
- package/bin/researcher-merge.test.cjs +14 -0
- package/lib/agents-registry.cjs +32 -0
- package/lib/agents.cjs +16 -6
- package/lib/agents.test.cjs +44 -0
- package/lib/archive.cjs +105 -39
- package/lib/archive.test.cjs +147 -5
- package/lib/checkpoint.cjs +43 -27
- package/lib/checkpoint.test.cjs +67 -6
- package/lib/codebase-docs.cjs +7 -9
- package/lib/codebase-docs.test.cjs +2 -2
- package/lib/codebase-manifest.cjs +2 -0
- package/lib/commit-policy.cjs +6 -29
- package/lib/commit-policy.test.cjs +6 -0
- package/lib/config-defaults.cjs +5 -2
- package/lib/config-defaults.test.cjs +71 -0
- package/lib/config-schema.cjs +204 -0
- package/lib/config-schema.test.cjs +148 -0
- package/lib/config.cjs +194 -9
- package/lib/config.test.cjs +234 -0
- package/lib/core.cjs +231 -47
- package/lib/core.test.cjs +193 -10
- package/lib/dashboard.cjs +0 -12
- package/lib/frontmatter.cjs +12 -18
- package/lib/git.cjs +34 -56
- package/lib/git.test.cjs +11 -3
- package/lib/handoff.cjs +19 -20
- package/lib/handoff.test.cjs +24 -0
- package/lib/ids.cjs +6 -0
- package/lib/init-emit.cjs +33 -0
- package/lib/install/backup.cjs +19 -14
- package/lib/install/claude-hooks.cjs +46 -25
- package/lib/install/claude-hooks.test.cjs +64 -0
- package/lib/install/codex-toml.cjs +15 -66
- package/lib/install/manifest.cjs +19 -0
- package/lib/install/manifest.test.cjs +107 -0
- package/lib/install/runtime-assets.cjs +4 -3
- package/lib/install/runtime-detect.cjs +1 -1
- package/lib/install/runtimes-registry.cjs +0 -5
- package/lib/knowledge-adapter.cjs +4 -57
- package/lib/knowledge-adapter.test.cjs +0 -20
- package/lib/knowledge.cjs +21 -5
- package/lib/language.cjs +3 -19
- package/lib/learnings.cjs +3 -108
- package/lib/logger.cjs +157 -0
- package/lib/logger.test.cjs +159 -0
- package/lib/memory-index-usearch.cjs +9 -12
- package/lib/memory-provider-local.cjs +8 -0
- package/lib/memory.cjs +90 -23
- package/lib/memory.test.cjs +135 -0
- package/lib/messaging.cjs +155 -83
- package/lib/metrics-aggregate.cjs +28 -28
- package/lib/metrics.cjs +10 -4
- package/lib/metrics.test.cjs +6 -5
- package/lib/migrations.cjs +89 -0
- package/lib/migrations.test.cjs +82 -0
- package/lib/milestone-meta.cjs +70 -0
- package/lib/model-profiles.cjs +2 -0
- package/lib/nubosloop-audit.cjs +244 -0
- package/lib/nubosloop.cjs +79 -412
- package/lib/nubosloop.test.cjs +52 -21
- package/lib/output-lint.cjs +1 -1
- package/lib/plan-lint.cjs +0 -67
- package/lib/researcher-reconciler.cjs +5 -10
- package/lib/researcher-swarm.cjs +54 -101
- package/lib/roadmap-render.cjs +108 -34
- package/lib/roadmap-schema.cjs +42 -0
- package/lib/roadmap.cjs +99 -35
- package/lib/roadmap.test.cjs +215 -0
- package/lib/run-context.cjs +54 -0
- package/lib/run-context.test.cjs +53 -0
- package/lib/runtime/_factory.cjs +19 -0
- package/lib/runtime/antigravity.cjs +4 -12
- package/lib/runtime/augment.cjs +4 -12
- package/lib/runtime/claude.cjs +2 -0
- package/lib/runtime/cline.cjs +4 -12
- package/lib/runtime/codebuddy.cjs +4 -12
- package/lib/runtime/codex.cjs +4 -12
- package/lib/runtime/copilot.cjs +4 -12
- package/lib/runtime/cursor.cjs +4 -12
- package/lib/runtime/gemini.cjs +4 -12
- package/lib/runtime/index.cjs +7 -10
- package/lib/runtime/index.test.cjs +13 -1
- package/lib/runtime/kilo.cjs +4 -12
- package/lib/runtime/opencode.cjs +4 -12
- package/lib/runtime/qwen.cjs +4 -12
- package/lib/runtime/trae.cjs +4 -12
- package/lib/runtime/windsurf.cjs +4 -12
- package/lib/safe-path.cjs +156 -0
- package/lib/safe-path.test.cjs +164 -0
- package/lib/state.cjs +33 -10
- package/lib/state.test.cjs +90 -21
- package/lib/tasks.cjs +92 -14
- package/lib/tasks.test.cjs +65 -0
- package/lib/template.cjs +0 -1
- package/lib/text-mode.cjs +4 -30
- package/lib/todo.cjs +7 -5
- package/lib/verify.cjs +47 -16
- package/lib/workspace-scan.cjs +2 -0
- package/lib/worktree.cjs +3 -9
- package/lib/yaml.cjs +44 -0
- package/lib/yaml.test.cjs +65 -0
- package/np-tools.cjs +39 -50
- package/package.json +7 -6
- package/templates/COMPLETENESS.md +3 -3
- package/workflows/add-tests.md +1 -1
- package/workflows/architect-phase.md +1 -1
- package/workflows/doctor.md +7 -5
- package/workflows/execute-phase.md +13 -9
- package/workflows/plan-phase.md +3 -3
- package/workflows/research-phase.md +2 -2
- package/bin/np-tools/research-merge.cjs +0 -105
- package/bin/np-tools/research-merge.test.cjs +0 -166
- package/docs/adr/0001-no-daemon-invariant.md +0 -82
- package/docs/adr/0002-zero-runtime-dependencies.md +0 -91
- package/docs/adr/0003-max-six-unit-types.md +0 -85
- package/docs/adr/0004-atomic-commit-per-unit.md +0 -102
- package/docs/adr/0005-three-orthogonal-file-trees.md +0 -98
- package/docs/adr/0006-yaml-dependency-amendment.md +0 -60
- package/docs/adr/0007-codebase-docs-layer.md +0 -273
- package/docs/adr/0008-worktree-isolation-per-slice.md +0 -140
- package/docs/adr/0009-tui-framework-for-dashboard.md +0 -95
- package/docs/adr/0010-nubosloop.md +0 -244
- package/docs/adr/0011-researcher-swarm-consensus.md +0 -84
- package/docs/adr/0012-completeness-doctrine.md +0 -85
- package/docs/adr/0013-learnings-store-schema-evolution.md +0 -128
- package/docs/adr/0013-plan-trust-layer.md +0 -95
- package/docs/adr/0014-vector-memory-layer.md +0 -175
- package/docs/adr/0015-named-agent-messaging.md +0 -162
- package/docs/adr/README.md +0 -37
- package/docs/agent-frontmatter-schema.md +0 -105
- package/docs/phase-artifact-schemas.md +0 -292
- package/docs/phase-directory-layout.md +0 -82
- package/lib/install/mcp-writer.cjs +0 -127
- package/mcp-configs/README.md +0 -41
- package/mcp-configs/claude-code.example.json +0 -27
- package/mcp-configs/codex.example.toml +0 -17
- 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,
|
|
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
|
-
|
|
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`.
|
|
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 #
|
|
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`).
|
package/agents/np-architect.md
CHANGED
|
@@ -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-
|
|
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
|
package/agents/np-build-fixer.md
CHANGED
|
@@ -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`.
|
package/agents/np-executor.md
CHANGED
|
@@ -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.**
|
|
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
|
|
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
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
|
package/agents/np-planner.md
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
|
package/agents/np-researcher.md
CHANGED
|
@@ -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
|
|
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).
|
package/bin/check-workflows.cjs
CHANGED
|
@@ -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,
|