Glossary

Reference. Canonical terms used across nubos-pilot. Every other page links here when a term first appears.

Execution ontology

Milestone

Top-level project goal. Identified as M<NNN> (for example M001). Lives at .nubos-pilot/milestones/M<NNN>/. One milestone produces one or more slices, plus its own context, research, plan-review and verification artifacts. See Unit Types § Milestone.

Slice (= wave)

Execution wave inside a milestone. Identified as S<NNN> within its milestone (full-id M<NNN>-S<NNN>). All tasks inside one slice run in parallel; slices run serially. Cross-slice dependencies flow forward only: a task in S002 may depend on a task in S001, never the reverse. There is no separate "wave" entity; the slice is the wave.

Task

Atomic unit of work inside a slice. Full-id M<NNN>-S<NNN>-T<NNNN>. Produces exactly one git commit with subject task(<full-id>): <title> (ADR-0004). Lifecycle: pending → in-progress → verifying → pre-commit → done (with skipped and parked as alternative terminals).

Capture ontology

Todo

Captured-on-the-fly idea. Lives at .nubos-pilot/todos/pending/YYYY-MM-DD-<slug>.md until scheduled into a milestone. Created by /np:add-todo.

Note

Free-form scratch. Project scope writes to .nubos-pilot/notes/ and commits to git. Global scope writes to ~/.nubos-pilot/notes/ and never commits. Created by /np:note.

Thread

Cross-session context store at .nubos-pilot/threads/<slug>.md. Lifecycle in frontmatter: OPEN → IN_PROGRESS → RESOLVED. Created and resumed by /np:thread <slug>.

"Phase" vs. "milestone"

User-facing slash-commands keep the word phase for backwards compatibility:

• /np:discuss-phase <N> — operates on milestone M<N>
• /np:plan-phase <N> — plans milestone M<N>
• /np:execute-phase <N> — executes milestone M<N>
• /np:research-phase <N>, /np:architect-phase <N>, /np:validate-phase <N> — same pattern

On disk, in IDs and in roadmap.yaml, the noun is always milestone. The mismatch is intentional, since renaming the slash-commands would break every project's muscle memory. New documentation, error messages and code paths use "milestone" exclusively.

File trees

Source

The tools/nubos-pilot/ git repo. Only contributors see this. Normal git lifecycle.

Install-Payload

Owned by the installer. Lives under the host runtime's config directory (for example .claude/nubos-pilot/ or .opencode/nubos-pilot/). Manifest-tracked; rewritten on npx nubos-pilot update. User edits are backed up to .bak.<n> before being overwritten.

Project-State

Lives at .nubos-pilot/ next to your code. Owned by the user, mutated only by workflows under a single-writer file lock. Survives uninstall: your plans, decisions and history persist even after removing the tool. See ADR-0005.

Agents

Subagent

A one-shot, role-prompted invocation of the host runtime's "spawn a subordinate agent" capability (Claude's Task, Codex's equivalent, and so on). Lives as a single Markdown file in agents/. No daemon and no caching; loadAgent() re-reads the file every time.

Tier

Single model-selection knob (haiku / sonnet / opus) that every agent declares in its frontmatter. The concrete model id is resolved at spawn time by np-tools.cjs resolve-model against the active model_profile. Embedding a literal model id is forbidden by D-09.

Handoff

Persistent agent-to-agent note for cross-phase signals. Lives at milestones/M<NNN>/handoffs/ (milestone-scoped) or top-level handoffs/ (project-global). Status lifecycle open → read → acted → archived. Written via np-tools.cjs handoff-write, read via handoff-list + handoff-read.

Verification and validation

Success criterion (SC)

Observable outcome a milestone must achieve. Lives in roadmap.yaml as success_criteria[] per milestone. Verified post-execution by np-verifier, classified as Pass / Fail / Defer / Needs-User-Confirm.

Verification

Goal-backward post-execution check that the implementation satisfies each SC. Output: M<NNN>-VERIFICATION.md. Run by /np:verify-work <N>.

Validation (Nyquist)

Test-coverage audit that at least one test directly observes each requirement's behavior. Output: M<NNN>-VALIDATION.md with COVERED / UNDER_SAMPLED / UNCOVERED per requirement. Run by /np:validate-phase <N>.

A milestone that passes verification but fails validation shipped working code with inadequate regression coverage.

Configuration shorthand

Term	Meaning
model_profile	Tier → model resolution profile (frontier / quality / balanced / budget / inherit); set in config.json
runtime	Active host CLI adapter (one of 14 ids)
scope	local (project-scoped install) or global (user-home install)
text_mode	Plain-text prompt rendering for non-TTY shells; falls back to process.env.CLAUDECODE

Full key reference: Configuration.

Project lifecycle (ADR-0016)

Term	Meaning
Project lifecycle state	One of idle, active, completed, archived. Sits above the milestone lifecycle. See Project Lifecycle.
project_status	Top-level key in roadmap.yaml: active or completed. Set by /np:close-project mark-completed when all milestones pass.
Project close	The /np:close-project workflow — aggregates every milestone's verification + validation, writes PROJECT-SUMMARY.md, flips project_status: completed when no blockers remain.
Archive	.nubos-pilot/archive/<slug>-<YYYYMMDD>[-N]/ — frozen snapshot of a predecessor project. Produced by /np:new-project Phase -1 or /np:archive-project do. Includes ARCHIVE.json manifest.
Carry-over	Files copied into the archive AND kept top-level for the successor project. Defaults: learnings/, solutions/. Opt out with --no-carry-over.

Output schemas (ADR-0017)

Term	Meaning
Output schema	Plain JS object in lib/schemas/<name>.cjs defining required frontmatter keys, type/enum constraints, cross-field invariants, body header patterns, required block fields. Consumed by output-lint.
Schema-prompt	Markdown rendering of a schema (output-lint prompt --schema <name>) injected verbatim into agent spawn prompts as a binding contract.
Write-time enforcement	Hard-fail lint executed immediately after the agent's Write returns; exit 1 on violation, agent re-spawned with the violation list. Never edit the artefact by hand.
Drift scan	np:doctor's _checkOutputSchemas — walks every milestone, lints existing artefacts. Surfaces drift in files written before the rule existed.

Researcher reconciliation (ADR-0018)

Term	Meaning
Stage 1 — Parallel spawn	k np-researcher invocations in parallel, identical task_query, unique seed_delta per spawn. Each writes a schema-bound research/spawn-<i>.md.
Stage 2 — Reconciler	np-researcher-reconciler sees all k per-spawn outputs + the deterministic mergeConsensus proposal, classifies reasoning traces, picks contested decisions, writes M<NNN>-RESEARCH.md.
Reasoning-Trace agreement	Per consensus decision: orthogonal (distinct evidence paths → strongest), overlapping (Jaccard > 0.6 → default), identical (same normalized text → groupthink, confidence demoted), unknown (< 2 spawns provided reasoning).
Contested decision	A decision proposed by only one spawn (no Mehrheit). Listed in ## Contested Decisions of the reconciler output with per-spawn verdicts + the Reconciler-Pick + reason.
Disagreement hard-gate	Workflow Step 5.7 — researcher-reconcile gate <N> checks agreement_score >= min_agreement_score (default 0.5) AND contested_count <= max_contested (default 2). Below threshold → askuser (re-spawn / continue / manual).
Reconciler verdict	Frontmatter field of M<NNN>-RESEARCH.md: clean, issues_flagged, needs_re_spawn.

Acronyms

Acronym	Expansion	Where it appears
ADR	Architectural Decision Record	docs/adr/, ADR Index
SC	Success Criterion	roadmap.yaml, M<NNN>-VERIFICATION.md
UAT	User Acceptance Test	S<NNN>-UAT.md
SSOT	Single Source Of Truth	informal — used to argue against duplication
REQ	Requirement	REQUIREMENTS.md (REQ-NN ids)
D-NN	Decision (locked, project- or milestone-scope)	M<NNN>-CONTEXT.md, RULES.md
CD-NN	Contested Decision (reconciler output)	M<NNN>-RESEARCH.md ## Contested Decisions
TTL	(Not used in nubos-pilot)	—