Completeness Doctrine

The Completeness Doctrine is the set of rules every nubos-pilot agent and workflow operates under. The canonical text lives in templates/COMPLETENESS.md in the source tree, quoted here verbatim:

The marginal cost of completeness is near zero with AI. Do the whole thing. Do it right. Do it with tests. Do it with documentation. Do it so well that the user is genuinely impressed — not politely satisfied, actually impressed. Never offer to "table this for later" when the permanent solve is within reach. Never leave a dangling thread when tying it off takes five more minutes. Never present a workaround when the real fix exists.

The standard isn't "good enough" — it's "holy shit, that's done." Search before building. Test before shipping.

Ship the complete thing. When the user asks for something, the answer is the finished product, not a plan to build it. Time is not an excuse. Fatigue is not an excuse. Complexity is not an excuse. Boil the ocean.

The doctrine is mechanically enforced by bin/check-completeness.cjs.

ADR-0012 ratifies this design.

The 12 rules

#	Rule	Mechanical check
1	Do the whole thing.	np-verifier + np-critic-acceptance audit the diff against success_criteria and the implicit boundary list.
2	Do it right.	np-critic-style rejects TODO / FIXME / XXX markers and dead-code paths.
3	Do it with tests.	task verify runs the test suite; Nubosloop refuses red tests; np-critic-tests audits coverage.
4	Do it with documentation.	np-tools.cjs update-docs after every task; scripts/generate-docs.cjs --check in CI.
5	Aim to genuinely impress, not politely satisfy.	np-critic-acceptance runs against success_criteria and rejects "good-enough" outputs.
6	Never offer to "table this for later".	np-planner rejects acceptance criteria reading "stub" / "placeholder" without a Deferred marker in CONTEXT.
7	Never leave a dangling thread.	np-critic-style audits dangling imports, dead exports, unreferenced files in files_modified.
8	Never present a workaround when the real fix exists.	np-plan-checker flags task plans containing "workaround" / "monkey-patch" / "hack" without ADR reference.
9	Search before building.	loop-audit-tool-use --agent <name> --tool-use-log <json> checks each np-researcher / np-executor / np-build-fixer spawn for SEARCH_TOOLS invocations; missing → rule-9-violation finding routed to executor.
10	Test before shipping.	commit-task refuses to commit when verify was not green within the last checkpoint transition.
11	Ship the complete thing.	execute-phase is the only workflow that closes tasks; plan-phase produces plans, never tasks marked done.
12	Boil the ocean.	np-tools.cjs nubosloop run enforces the loop counter; stuck state surfaces in STATE.md and the dashboard.

How agents reference the doctrine

Every agents/np-*.md carries a ## Completeness Mandate block that cites the rules binding that role and links to templates/COMPLETENESS.md. The linter fails the build when the block or link is missing.

## Completeness Mandate

This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). The rules that bind this role:

- **Rule 3 — Do it with tests.** Every commit ships tests for the production code it adds or changes.
- **Rule 9 — Search before building.** Run `knowledge-search` for the symbols you plan to introduce before writing them.
…
Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.

How workflows reference the doctrine

Every workflows/*.md carries a ## Definition of Done block that lists the rules its exit gate enforces, and links to COMPLETENESS.md.

## Definition of Done

This workflow exits successfully only when, per [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md):

- Rule 3 (tests): every task's verify command was green.
- Rule 4 (docs): `update-docs` ran for every committed task.
- Rule 12 (boil the ocean): no task left in `stuck` state.

Any violation = workflow exits non-zero. The orchestrator does not relax these.

Linter contract

bin/check-completeness.cjs exposes:

Function	Purpose
checkAgents(rootDir)	Every agents/*.md must contain ## Completeness Mandate and link to COMPLETENESS.md.
checkWorkflows(rootDir)	Every workflows/*.md must contain ## Definition of Done and link to COMPLETENESS.md.
checkCompletenessFile(rootDir)	The doctrine itself must contain exactly twelve sequentially numbered rule headings (### 1. … ### 12.).
checkAll(rootDir)	Runs all three.

Tests live in bin/check-completeness.test.cjs. Test CC-9 validates the live tree on every npm test run.

Updating the doctrine

The doctrine is append-only. To change a rule:

1. Author a new ADR that supersedes (or amends) ADR-0012.
2. Update templates/COMPLETENESS.md per the ADR.
3. Update every agents/np-*.md and workflows/*.md block that cites the changed rule. The linter fails the build until the references are consistent.

There is no edit-in-place path. The linter's doctrine-drift check catches numbering or count mismatches.

Related

• Nubosloop — the runtime that mechanically enforces several rules per task.
• Researcher-Schwarm — Rule 9 is enforced by the cache-first lookup.
• Findings Routing — how Critic findings get back to the right agent.
• ADR-0012 — full architectural decision record.