Contract — R82.H docs/2-plugin/health.md reconciliation

Scope. Behavioral contract for the rewritten docs/2-plugin/health.md. Defines the invariants the post-edit file must satisfy, the sweep commands that will be run in Step 5 to prove them, and the no-go conditions that block merge. Docs-only slice; no source code is edited.

Target file: docs/2-plugin/health.md Audit of record: docs/audits/r82-h-health-audit.md (792be44a) Live handler: src/tools/health.ts:100-139 Live input schema: src/tools/health.ts:57 → z.object({})

1. Invariants (what must be true after the edit)

1.1 Payload-shape invariants (positive)

The post-edit health.md must name every one of the 6 live payload fields at least once as a payload field. Per R82 manifest row H acceptance criterion: “Documented response is exactly { status, version, uptime_ms, db_tables, phase, mode } with no extra fields”.

Field Required occurrences Source of truth
status ≥ 1 src/tools/health.ts:132
version ≥ 1 src/tools/health.ts:133
uptime_ms ≥ 1 src/tools/health.ts:134
db_tables ≥ 1 src/tools/health.ts:135
phase ≥ 1 src/tools/health.ts:136
mode ≥ 1 src/tools/health.ts:137

1.2 Payload-shape invariants (negative — strike list)

These must not appear as payload-field claims in the rewritten file. Where they appear in other contexts (e.g. an Obsidian-adjacent Phase 1+ future callout), the text must make clear they are aspirational and not part of the Phase 0 response.

Term Grep target Post-edit count
detail=summary\|detail=full request parameter file body 0
tool_count file body 0
capability_set file body 0
middleware_registry file body 0
process_metrics file body 0
server_version (as a payload field name) file body 0
uptime_seconds (as a payload field name) file body 0
SAFE_MODE (as a payload mode transition) file body 0
DIAGNOSE (as a payload mode transition) file body 0
heap_used_mb / heap_total_mb / rss_mb file body 0
sqlite_integrity (as a payload check field) file body 0
memory_threshold (as a payload check field) file body 0
event_loop_lag_ms (as a payload check field) file body 0
unified_init (as a Phase 0 peer tool claim) file body 0
unified_vitals (as a Phase 0 peer tool claim) file body 0
src/domains/system/tools.ts (as the live path) file body 0
19-tool surface / 19 tools file body 0

1.3 Document-structure invariants

  • Jekyll frontmatter preserved — lines 1-7 must still be a valid YAML frontmatter block with the existing title, tags, updated, parent, nav_order keys. The updated field may bump to 2026-04-19.
  • Phase 0 stdio rationale preserved — the “Why an MCP tool, not an HTTP endpoint” paragraph survives unchanged in content.
  • Never-throws invariant preserved — explicit single-sentence claim that server_health never throws must remain.
  • Logging + COLIBRI_LOG_LEVEL section preserved — already accurate per Wave H reconcile; keep intact.
  • Cross-references preserved — ADR-004, boot.md, database.md, middleware.md, s18-stdio.md, s17-environment.md cross-link block kept.
  • Heritage pointers allowed — references to ../reference/extractions/ may remain as long as they are framed as donor heritage and not as live Phase 0 behavior.

1.4 Forward-reference invariants (allowed)

  • A “Phase 1+ future” section or callout may reference the periodic-check ring buffer, the SAFE_MODE / DIAGNOSE reporting surface, and the memory / event-loop probes only if explicitly labelled as aspirational (e.g. heading “Deferred to Phase 1+” or an admonition block). Any such mention must not suggest these exist in the Phase 0 response.

2. Sweep commands (to be run in Step 5)

All sweeps run from the worktree root. They operate against the rewritten docs/2-plugin/health.md file.

2.1 Negative sweeps (each must return 0) 

grep -cE "detail=summary\|detail=full" docs/2-plugin/health.md
grep -cE "tool_count|capability_set|middleware_registry|process_metrics" docs/2-plugin/health.md
grep -cE "server_version|uptime_seconds" docs/2-plugin/health.md
grep -cE "heap_used_mb|heap_total_mb|rss_mb" docs/2-plugin/health.md
grep -cE "sqlite_integrity|memory_threshold|event_loop_lag_ms" docs/2-plugin/health.md
grep -cE "unified_init|unified_vitals" docs/2-plugin/health.md
grep -cE "src/domains/system/tools\.ts" docs/2-plugin/health.md
grep -cE "19-tool surface|19 tools" docs/2-plugin/health.md

2.2 Positive sweeps (each must return ≥ 1) 

grep -c "status" docs/2-plugin/health.md
grep -c "version" docs/2-plugin/health.md
grep -c "uptime_ms" docs/2-plugin/health.md
grep -c "db_tables" docs/2-plugin/health.md
grep -c "phase" docs/2-plugin/health.md
grep -c "mode" docs/2-plugin/health.md

2.3 Frontmatter preservation sweep 

head -10 docs/2-plugin/health.md | grep -c "^---$"   # Must return 2 (open + close)
head -10 docs/2-plugin/health.md | grep -c "^title:" # Must return 1
head -10 docs/2-plugin/health.md | grep -c "^parent:" # Must return 1
head -10 docs/2-plugin/health.md | grep -c "^nav_order:" # Must return 1

2.4 Never-throws invariant sweep 

grep -cE "never throws" docs/2-plugin/health.md   # Must return ≥ 1

3. Error contracts (how the doc describes handler failure)

The rewritten file must describe failure posture consistent with the live handler:

  • ctx.db undefined / closed / locked → db_tables: 0 (via countTables try/catch at src/tools/health.ts:104-111).
  • The tool never throws. Schema-validation failures are caught by the stage-2 α middleware and return the standard INVALID_PARAMS envelope at the tool-surface level. (Covered in middleware.md stage-2 description; health.md does not need to restate the envelope format.)
  • There is no status: "degraded" or status: "error" return in Phase 0. The status field is the literal "ok".

4. Dependency rules (what the doc may reference)

Allowed cross-links:

  • ../architecture/decisions/ADR-004-tool-surface.md
  • boot.md (sibling, same folder)
  • database.md, middleware.md (same folder)
  • ../spec/s17-environment.md, ../spec/s18-stdio.md
  • ../reference/extractions/ (heritage, zoning per CLAUDE.md §9.2)
  • ../../CLAUDE.md (for the bootstrap chain reference)

Forbidden cross-links:

  • src/domains/system/tools.ts (not a real path)
  • src/domains/system/health.ts (not a real path)
  • Any donor-era AMS_* env var citation as live Phase 0 behavior

5. Public-vs-internal surface

The file is pure documentation. It has no public API. Its callers are:

  • Human agents reading the Jekyll-built Pages site
  • Claude sessions (T1/T2/T3) cross-linking the file from skill prose
  • Obsidian vault mirror of docs/

All three use-cases require the document to be truthful about the Phase 0 surface — no aspirational claims presented as current behavior.

6. Rollback plan

If sweeps fail or the rewritten file introduces regression:

  1. git restore --source=<pre-impl-SHA> -- docs/2-plugin/health.md
  2. Re-read the audit; identify the sweep that failed.
  3. Adjust the Step-4 Edit operations; re-run the sweeps.
  4. If structural rewrite cannot pass all sweeps, escalate to PM: the contract invariants are non-negotiable and a partial fix is not acceptable.

7. Commit 

contract(r82-h-health): behavioral contract

Back to top

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

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