R82.F — deploy.md + boot.md behavioral contract

1. Scope

Two files:

  1. docs/guides/deploy.md — Phase-0 deploy runbook.
  2. docs/2-plugin/boot.md — 6-step boot sequence.

Nothing else. Not docs/2-plugin/modes.md (already 14-tool-correct since Wave H), not docs/reference/mcp-tools-phase-0.md (owned by R82.E), not the Phase-0 status note at docs/guides/deploy.md:13 (owned by R82.B surface).

2. Invariants (hard constraints — must all hold after Step 4)

2.1 Negative sweeps (must return zero)

Regex Files Expected count
19 tools\|all 19 docs/guides/deploy.md, docs/2-plugin/boot.md 0 in each
server_shutdown\|server_status\|task_transition\|audit_session_end\|task_delete\|task_depends_on docs/guides/deploy.md, docs/2-plugin/boot.md 0 in each
server_info docs/guides/deploy.md, docs/2-plugin/boot.md 0 in each (not in scope per R82 survey but struck preemptively since it is a phantom across the corpus)

Note on interpretation. Per the task prompt: “allow for explicit 19-tool pre-amendment budget framing if it exists — flag in audit if ambiguous.” Inspection confirms no such pre-amendment framing appears in either file — every “19 tools” mention is a live, unqualified claim about the current surface. Zero exemptions.

2.2 Positive sweeps (must return ≥ 1 in each file)

Regex Files Expected count
14 tools\|14 shipped docs/guides/deploy.md ≥ 1
14 tools\|14 shipped docs/2-plugin/boot.md ≥ 1

2.3 Collective tool coverage

All 14 live tool names must appear collectively across the two files:

  • server_ping, server_health — at least once each (both files reference them via MINIMAL / α-system text).
  • thought_record, thought_record_list, audit_verify_chain, skill_list, task_create, task_list, task_get, task_update, task_next_actions, audit_session_start, merkle_finalize, merkle_root — may all be covered via docs/2-plugin/boot.md Step 2 handler table.

This is a collective invariant, not a per-file invariant. deploy.md is a runbook; boot.md is the handler-registration reference.

2.4 Jekyll frontmatter preserved

Both files must retain their YAML frontmatter block with identical keys:

  • docs/guides/deploy.md L1–L9: title, description, tags, type, updated, parent, nav_order.
  • docs/2-plugin/boot.md L1–L9: title, description, tags, round, updated, parent, nav_order.

Values may be updated only where the task directly demands it. For R82.F, values are preserved as-is (this is prose + table edits, not a frontmatter migration).

All [text](../path/file.md) references in both files must continue to resolve. R82.F does not add, rename, or remove cross-links.

2.6 Markdown table structure preserved

The mode tables in both files must retain their column count and column names. Only cell contents change in the three target rows (FULL, TEST, MINIMAL).

2.7 capabilitiesFor() advisory callout added

A callout note in docs/guides/deploy.md §Boot sequence (step 5 prose) must explicitly state:

capabilitiesFor(mode) is read at construction time but currently advisory in Phase 0 — every registered tool is exposed in every mode regardless of the active capability record. Enforcement at registration time is a Phase 1 follow-up.

This is a fact straight out of src/server.ts:226-229 (“Capability read — currently advisory … kept as an explicit reference so the mode → capability dependency is compiled-in for future P0.2.3 / P0.4.2 wiring”). No prose beyond that fact is admitted.

2.8 Shutdown wording reality

In docs/2-plugin/boot.md L171 exit-code-0 row, the “Clean shutdown via server_shutdown” phrasing must be replaced with “Clean shutdown via SIGINT/SIGTERM”. Rationale: docs/2-plugin/modes.md §Tool surface per mode canonicalises “Process-level shutdown (SIGTERM/SIGINT) is the Phase 0 signal for clean teardown — there is no MCP-exposed shutdown tool.”

3. Out-of-scope / explicit do-not-touch

  • docs/2-plugin/modes.md — already 14-tool-correct (source of truth).
  • docs/2-plugin/health.md — R82.H slice.
  • docs/2-plugin/middleware.md — untouched.
  • docs/reference/mcp-tools-phase-0.md — R82.E slice (Wave 2 parallel).
  • docs/guides/deploy.md:13 Phase-0 status note (“No Colibri TypeScript code exists yet”) — belongs to R82.B surface; leave untouched.
  • docs/guides/troubleshoot.md — cross-linked but untouched.
  • Any src/ file — R82.F is docs-only.

4. Error contracts

None — this is a docs-only task. No runtime behavior changes. No test failures are possible; the gate is the sweep regex set in §2.

5. Non-goals

  • No re-layout of section ordering.
  • No new sections.
  • No re-heading.
  • No cross-link additions.
  • No heritage-banner rewrites (out of R82.F; see R82.J).
  • No ADR reference additions or removals.

6. Verification protocol

Step 5 must produce a verification document at docs/verification/r82-f-deploy-boot-verification.md containing:

  1. Captured stdout of every grep command in §2.
  2. A one-line confirmation that frontmatter is intact on both files (via head -10 output).
  3. A one-line confirmation that no test runner gate applies (docs-only).
  4. A one-line confirmation that the advisory-capabilities callout lands in deploy.md boot-sequence step 5.

7. Dependency rules

  • docs/guides/deploy.md may continue to import from docs/2-plugin/* and docs/reference/* (cross-link only).
  • docs/2-plugin/boot.md may continue to import from docs/2-plugin/* and docs/colibri-system.md (cross-link only).
  • Neither file may introduce a new dependency on docs/reference/mcp-tools-phase-0.md body content (only a cross-link to it is permitted, and that cross-link is already present in both files).

8. Definition of done (from manifest)

“Tool-count references match the 14-tool reality; mode-tool-lists do not name server_shutdown, server_status, task_transition, task_delete, audit_session_end; any ‘advisory vs. enforced’ mode-registration nuance is called out where the code currently treats capabilitiesFor(mode) as advisory.”

All three clauses are covered by §2.1 + §2.2 + §2.7 above.

9. Audit → Contract traceability

Audit finding Contract invariant
§3.1 L48, L50, L104 mode-table “all 19 tools” §2.1 negative sweep + §2.2 positive sweep
§3.1 L51 server_status phantom §2.1 negative sweep
§3.1 L53 “19 tools” in doc link caption §2.1 negative sweep + §2.2 positive sweep
§3.1 L63 “19 Phase 0 tools … gated out by COLIBRI_MODE” §2.7 advisory callout + §2.1 negative sweep
§3.1 L141 “not in the 19 tools” §2.1 negative sweep
§3.1 L179 “the 19 tools per ADR-004” §2.1 negative sweep
§4.1 L116 “all 19 tools active” §2.1 negative sweep + §2.2 positive sweep
§4.1 L119 “health/shutdown tools only” §2.1 negative sweep (via shutdown strike)
§4.1 L159 “19 schemas is malformed” §2.1 negative sweep
§4.1 L171 “Clean shutdown via server_shutdown” §2.1 negative sweep + §2.8 shutdown wording

Every audit row has a contract hook. Nothing is dropped between Step 1 and Step 2.

Part of R82 Phase 0-1 stabilization, Wave 2 (task F). Governed by docs/agents/executor-contract.md.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.