R75 PLAN-RED — Step 2 Contract

This contract defines the invariants that MUST hold after the PLAN-RED rebuild lands. It gates the packet step (Step 3): the packet may not change any invariant stated here without amending this document first. Every invariant is verifiable; Step 5 verification MUST cite each one.

Upstream authority: docs/PLAN-RED.md (T0-authorized 2026-04-13) and docs/colibri-system.md (canonical vision). Where this contract tightens or narrows PLAN-RED it is because Phase 2 is further along than PLAN-RED assumed and the audit (Step 1, commit eb15dd31) surfaced 12 missing glue files, 41 pending ABSORB pairs, and 453 inbound KILL-path links. User directive 2026-04-16 overrides any earlier wording: Phase 0 documentation MUST be written accurately and sufficiently for implementation; donor residue MUST be deleted or rewritten, not preserved for genealogy.

§1. Post-rebuild shape invariants

The docs/ tree after this round MUST match the World Schema v3 spine from PLAN-RED §21-39. The following top-level paths under docs/ MUST exist and MUST NOT exist:

MUST exist (each as a directory with an index.md, or a single file as noted):

  • docs/0-mutate/ — foundational layer
  • docs/1-transport/ — MCP + JSON-RPC + 19 tools
  • docs/2-plugin/ — server boot, modes, database, middleware, health
  • docs/3-world/ with subdirs physics/, social/, execution/, and physics/laws/, physics/enforcement/
  • docs/4-additions/ — ν integrations
  • docs/5-time/ — session → round → task → roadmap
  • docs/spec/ (SEED, untouched: s01–s19 + index)
  • docs/architecture/decisions/ (SEED, untouched: ADR-001 through ADR-006 + README)
  • docs/agents/ (SEED, untouched except for outbound link fixes)
  • docs/reference/extractions/ (SEED, untouched: 49 heritage archive files)
  • docs/reference/glossary.md, docs/reference/cross-reference.md, docs/reference/design-system.md, docs/reference/mcp-tools-phase-0.md (all SEED or ABSORB-target)
  • docs/guides/ — quick-start, first-pr, write-a-skill, agent-bootstrap, agent-handoff, self-build-loop, deploy, troubleshoot, backup, implementation/
  • docs/index.md, docs/world-schema.md, docs/colibri-system.md, docs/PLAN-RED.md

MUST NOT exist (Phase 4 deletions):

  • docs/concepts/ (directory gone — includes α–ξ concept files, index.md, map.md, arbitration.md)
  • docs/how-it-works/ (directory gone)
  • docs/security/ (directory gone — content absorbed into 3-world/physics/hardening.md)
  • docs/operations/ (directory gone — content absorbed into 2-plugin/health.md and guides/)
  • docs/comparisons/ (directory gone)
  • docs/developers/ (directory gone)
  • docs/roadmap/ (directory gone — content absorbed into 5-time/roadmap.md)
  • docs/architecture/*.md — every non-decisions file at the docs/architecture/ level is removed; only the decisions/ subdirectory survives
  • docs/colibri-master-context.md, docs/faq.md, docs/inventory-r74-2.md, docs/session-seal-s6.md, docs/README.md, docs/constraints.md, docs/truth.md, docs/promise.md, docs/scenario.md, docs/scale.md, docs/extensions.md, docs/glossary.md, docs/cross-reference.md, docs/design-system.md, docs/multi-surface-topology.md, docs/master-flow.md, docs/pipeline-definition.md — all ABSORB-sources, removed after content migrates

§2. Content freshness invariants (Phase 0 accuracy)

No CANON doc MAY contain any of the following phrases as an unqualified current-Colibri fact. An “unqualified” occurrence is one not enclosed in a heritage banner, not under zone: heritage frontmatter, and not on a line that explicitly negates the claim.

Banned phrases in CANON:

  • 78 tables, 74 regular + 4 FTS5, or any donor AMS table count
  • 484 tools, 490 tools, 493 tools, or any donor tool count (except 19 tools which is the Phase 0 canon)
  • 11 middleware layers, 6-layer middleware, or any donor middleware count outside a labeled heritage block
  • data/ams.db presented as the live Colibri write target. The only permitted phrasing is: “donor AMS task store, retained as HERITAGE during Phase 0 bootstrap, writeable only by task/writeback tools”
  • AMS_* environment variables presented as the Colibri namespace. Colibri Phase 0 uses COLIBRI_* (see 2-plugin/boot.md for the intended namespace, e.g. COLIBRI_MODE, COLIBRI_LOG_LEVEL)
  • ~85 env vars or any bulk env-var count without an explicit heritage label

Permitted locations for donor-era numbers:

  • Files under docs/reference/extractions/ (49 HERITAGE archive files, frozen)
  • Files carrying zone: heritage frontmatter AND an explicit HERITAGE banner in the body. Post-round, there MUST be at most three such files inside docs/ outside of reference/extractions/
  • docs/PLAN-RED.md (historical record of what was deleted — it MUST cite old numbers to describe them)
  • Root README.md and CLAUDE.md when referencing the donor lineage as history

Phase 0 target values that Phase 0-authored docs MUST align with (upstream source: docs/colibri-system.md):

  • Database: exactly data/colibri.db. Single-writer. WAL mode. better-sqlite3 driver.
  • Middleware: exactly 5 stages, in order — tool-lock → schema-validate → audit-enter → dispatch → audit-exit. This is the α chain.
  • Tool surface (Phase 0): 14 tools shipped (was a 19-tool plan at R74.5 — see ADR-004 R75 Wave H amendment for the 5 closed/deferred tools and the 1 added): 5 β Task (task_create, task_list, task_get, task_update, task_next_actions) + 4 ζ Audit (audit_session_start, thought_record, thought_record_list, audit_verify_chain) + 2 η Proof (merkle_finalize, merkle_root) + 1 ε (skill_list) + 2 System (server_ping, server_health). This is a subset of the 60–80 long-horizon ceiling. Phase 0 docs that pre-date Wave H may still cite 19; new docs must cite the shipped 14.
  • Tables load-bearing for Phase 0: at minimum thought_records, merkle_nodes, audit_events. Any additional table named in a Phase 0 doc MUST be earned by a Phase 0 sub-task acceptance criterion (P0.1.1 – P0.9.3).
  • Phase 0 sub-task count: exactly 28 (P0.1.1 through P0.9.3, across 9 task groups, 6 rounds R75–R80). This is the Phase 0 subset of the 63-task full-phase catalog at docs/guides/implementation/task-breakdown.md. No doc may conflate the two counts.
  • Model tier: Claude only in Phase 0. Kimi, Codex, and GPT-class models are deferred to Phase 1.5 per ADR-005.

After Phase 4 deletions run, the following MUST hold across every CANON markdown file (all files under docs/ except reference/extractions/ and files with zone: heritage frontmatter):

  • Every outbound markdown link of form ](relative/path.md) or ](relative/path.md#anchor) MUST resolve to a file that exists in the post-round tree.
  • Every doc in docs/ MUST be reachable from docs/index.md in at most three hops.
  • Spec files s01–s19 MUST be reachable via the path docs/index.md → docs/spec/index.md → docs/spec/sNN-*.md.
  • The three root docs CLAUDE.md, AGENTS.md, README.md MUST link only into paths that survive the rebuild.
  • All 453 inbound KILL-path links inventoried by the Step 1 audit MUST be either (a) rewritten to a surviving target, (b) redirected via an updated section, or (c) deleted together with their host file.
  • The two link-rot hotspots identified by the audit — docs/reference/glossary.md (34 KILL links) and docs/reference/cross-reference.md (50 KILL links) — MUST have every one of those 84 links resolved.

§4. Root-file invariants

  • CLAUDE.md §9.3 “Root-level files” count MUST read 6 (bumped from 5 in R74.3.2 when SECURITY.md was added). The list MUST enumerate AGENTS.md · CLAUDE.md · CODE_OF_CONDUCT.md · CONTRIBUTING.md · README.md · SECURITY.md.
  • CLAUDE.md §11 “Documentation reference” path list MUST point only at post-round paths. Any reference to concepts/, how-it-works/, architecture/*.md (other than architecture/decisions/), security/, or operations/ MUST be gone.
  • CLAUDE.md §9.2 docs/ row MUST describe the new World Schema v3 tree and MUST NOT reference temp/plan-red-cleanup.bat as a pending action once Phase 4 runs.
  • AGENTS.md reading order MUST be aligned with World Schema v3 layers 0-mutate → 5-time. Any link to docs/concepts/index.md (audit identified two at lines 156, 167, and 168) MUST be rewritten.
  • AGENTS.md MUST NOT link to docs/multi-surface-topology.md or docs/pipeline-definition.md as standalone files (both are ABSORB-sources that get deleted). Targets become 3-world/social/surfaces.md and 5-time/round.md + 5-time/task.md respectively.
  • CONTRIBUTING.md MUST NOT link to docs/concepts/index.md (audit identified two occurrences at lines 11, 15).
  • README.md “Documentation” link MUST point at docs/index.md (the rebuilt master hub).
  • colibri-world-schema.md at repo root MUST NOT exist post-round. The canonical copy is docs/world-schema.md. The root duplicate is deleted (audit §6 flagged both files coexisting).

§5. Skill-layer invariants

  • .claude/skills/ams-executor/, .claude/skills/ams-observability/, .claude/skills/ams-pm/, .claude/skills/ams-tier1-chains/ — all four redirect-stub skills MUST NOT exist post-round.
  • .claude/skills/README.md MUST NOT reference any ams-* skill.
  • .agents/README.md MUST carry an active-vs-deferred skill classification per PLAN-RED §267-269: 10 Phase 0 active skills explicitly listed, 12 heritage/deferred skills explicitly listed, swarms/colibri-5/ explicitly reclassified from HERITAGE to ACTIVE.
  • No .agents/skills/colibri-* SKILL.md file is altered by this round (out of scope — skills resync is deferred to a later R75.x).

§6. Data/ zone invariants

Per PLAN-RED §297-308:

  • data/ams.db (binary, ~72MB) MUST be retained untouched.
  • data/README.md MUST be retained and MUST be reduced to a one-line heritage banner describing ams.db as the Phase 0 writeback target.
  • data/meta-prompts/ (15 .md files) MUST NOT exist post-round.
  • data/roadmaps/ (58 .md files + JSON deps) MUST NOT exist post-round.
  • data/projects/ — MUST NOT exist post-round (audit confirmed it is already gone in this worktree; invariant preserves that state).
  • Every other .md file under data/ MUST NOT exist post-round.
  • Total data/*.md file count post-round MUST equal 1 (the retained README.md).

§7. Non-regressions

In this round, the following files and directories MUST NOT be modified except to fix outbound links into KILL paths:

  • Every file under docs/spec/ (s01 through s19 plus index.md). These are SEED and frozen.
  • Every file under docs/architecture/decisions/ (ADR-001 through ADR-006 plus README.md). Frozen except for outbound link fixes.
  • Every file under docs/agents/ (sigma-orchestrator.md, pm-contract.md, executor-contract.md, writeback-protocol.md). Frozen except for outbound link fixes.
  • Every file under docs/reference/extractions/ (49 heritage archive files). Frozen.
  • Every file under .agents/spawns/, .agents/swarms/, .agents/archive/. HERITAGE, read-only.
  • Every file under .github/ (issue templates, PR template, workflow docs).
  • Every file under assets/ and _includes/.
  • _config.yml MAY be edited only for the nav key reflecting the new tree; no other keys change.

Phase 0 TypeScript code is out of scope entirely: no file under src/ is created in this round, and tests/ remains absent. This round ships Phase 0 documentation; it does not begin Phase 0 implementation.

§8. Verifiable acceptance criteria (Step 5 input)

Step 5 verification passes if and only if every one of the following holds. Each MUST be explicitly cited in docs/verification/r75-plan-red-verification.md.

  1. find docs -name "*.md" | wc -l returns a value in the inclusive range [110, 135] (target ~120 per PLAN-RED §236).
  2. grep -rE "78 tables|484 tools|data/ams\.db" docs/ matches only inside files under docs/reference/extractions/, files with zone: heritage frontmatter, or docs/PLAN-RED.md. Any other match fails this criterion.
  3. An automated link-checker run over every CANON .md under docs/ reports zero broken ]( ) targets. The checker MUST follow relative paths and MUST ignore anchors pointing at heading IDs that exist in the target file.
  4. The /colibri-docs-check slash-command output classifies the tree as PASS: no orphans, no broken links, no unlabeled stale numbers, no missing indexes.
  5. All six WARN items from the /colibri-docs-check baseline run at the start of this session are each cited in docs/verification/r75-plan-red-verification.md with a resolution note.
  6. GitHub Pages CI on feature/r75-plan-red-execution MUST be green (build + deploy both succeed) before the PR is opened for merge.
  7. ls colibri-world-schema.md at the repo root MUST return “No such file or directory”.
  8. ls .claude/skills/ams-* MUST return “No such file or directory”.
  9. find data -name "*.md" | wc -l MUST return exactly 1.

§9. Scope boundary

Explicitly out of scope for this round:

  • Phase 0 code (P0.1.1 through P0.9.3). No src/, no tests/, no package.json, no tsconfig.json. This round writes the documentation that supports Phase 0, not Phase 0 itself.
  • Obsidian vault re-sync. The vault is updated post-merge by the user via the canonical temp/sync-full.bat recipe; no vault file is edited in this round.
  • Full resync of .claude/skills/colibri-* against the .agents/skills/ canon. Deferred to a later R75.x task.
  • Any edit to .agents/spawns/, .agents/swarms/ (other than the README classification note), or .agents/archive/.
  • Any edit to GitHub workflow files under .github/workflows/.

Step 2 of 5 — gates docs/packets/r75-plan-red-packet.md. Audit baseline: commit eb15dd31. Authority: docs/PLAN-RED.md + docs/colibri-system.md. Any invariant here that conflicts with those upstream docs is a bug in this 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.