ADR-008 — Contract

Step: 2 of 5 (contract) Date: 2026-05-06 Branch: feature/adr-008-mode-enforcement Worktree: .worktrees/claude/adr-008-mode-enforcement Audit: docs/audits/adr-008-mode-enforcement-audit.md (Step 1) Deliverable: ADR-only. No source-code changes.

1. What this task ships

A single ADR file at docs/architecture/decisions/ADR-008-mode-enforcement.md, plus the two-line index update in docs/architecture/decisions/index.md and the corresponding row in docs/architecture/decisions/README.md.

The ADR records the architectural decision for closing the gap surfaced by Finding #1. It does not implement the decision — implementation is split into one or more follow-up tasks Sigma will dispatch in a later round.

2. The eight invariants the ADR must satisfy

I-1. Standard ADR frontmatter

YAML frontmatter matching the format used by ADR-001 through ADR-006:

  • title — quoted, contains “ADR-008”
  • description — single-sentence summary, ≤ 240 chars
  • tags — includes adr, decision, plus topic tags
  • type: adr
  • round: R84 (or the active round name; ADR-008 was carved from a whole-system code review under R84)
  • status: proposed (Phase 0 PROPOSED → ACCEPTED rule from README.md)
  • parent: Architecture Decision Records
  • updated: 2026-05-06
  • nav_order: 80 (next after ADR-006’s nav_order: 60; ADR-005 occupies 50; ADR-007 will occupy 70)

I-2. Required §sections

The ADR must contain, in order:

  1. Status / Date / Round / Supersedes / Superseded by header.
  2. §Context — stating Finding #1 explicitly, citing src/server.ts:229 (the void call) and src/modes.ts:174 (capabilitiesFor) by line number, and citing the doc surfaces (modes.md:31, mcp-tools-phase-0.md:930, ADR-004 line 68).
  3. §Decision — picking exactly one option (A, B, or C) and stating the choice in one sentence followed by a bullet list of mechanics.
  4. §Alternatives Considered — for each of A, B, C: implementation cost, runtime cost, test surface, schema impact, ergonomics for tool authors, and a short reasoned tradeoff.
  5. §Consequences — split into Positive / Negative / Neutral.
  6. §Implementation — concrete file paths and per-file deltas a follow-up task can split. Includes the mutates: true/false table for all 14 shipped tools if Option A is chosen.
  7. §Verification — Sigma’s gate criteria. Pass-or-fail items.
  8. §References — links to the audit, the cited docs, and ADR-007 for coexistence.

I-3. Numbered as ADR-008

The file lives at docs/architecture/decisions/ADR-008-mode-enforcement.md. The number is reserved against ADR-007 which is being drafted in parallel in a sibling worktree. The two ADRs assume each other will land; ADR-008 must not edit ADR-007 and must not assume ADR-007’s content beyond “ADR-007 ships η session lifecycle and is independent of mode enforcement.”

I-4. Date 2026-05-06

Per dispatch. The frontmatter updated: and the body **Date:** line both read 2026-05-06.

I-5. Status: Proposed

The ADR ships in PROPOSED status (capitalized Proposed per the README format note). The owner moves it to ACCEPTED in a later round; sub-agents do not.

I-6. Recommendation is Option A unless audit gives a strong reason otherwise

The dispatch prompt named A as the recommended option. The audit (Step 1) surfaced no evidence that A is unsafe, costly, or ergonomically wrong. A is therefore the §Decision. B and C are documented in §Alternatives with the reasons they were not chosen.

I-7. The mutating-tool list is correct

If Option A is the §Decision, the ADR’s §Implementation must list which of the 14 shipped tools are mutates: true and which are mutates: false. The audit has the full table; the ADR re-states it (the inventory is small enough to be a single table). The mapping:

  • mutates: true (5): task_create, task_update, thought_record, audit_session_start, merkle_finalize
  • mutates: false (9): server_ping, server_health, task_get, task_list, task_next_actions, skill_list, thought_record_list, audit_verify_chain, merkle_root

I-8. Index updates

docs/architecture/decisions/index.md: add a bullet for ADR-008 between ADR-006 and the §”See also” footer. ADR-007 will add its own bullet in its own worktree; ADR-008 must not pre-write ADR-007’s bullet (avoid merge conflict).

docs/architecture/decisions/README.md: add a row to the §Index status table for ADR-008 with status PROPOSED and domain Architecture / γ Server Lifecycle. Same merge-conflict caveat as above for ADR-007.

3. Out of scope (forbidden by the dispatch packet)

  • No source code changes. src/, tests/, package.json, migrations/, *.ts, *.test.ts MUST remain untouched.
  • No edits to CLAUDE.md, AGENTS.md, docs/colibri-system.md, docs/reference/mcp-tools-phase-0.md. These are touched by the follow-up implementation task, not by this ADR.
  • No new tools. The ADR may describe mutates as a new field on ColibriToolConfig but must not implement it.
  • No restructure of the existing ADR set. ADR-001 through ADR-006 remain unchanged.

4. Pass/fail acceptance

  • npm run build && npm run lint && npm test exits zero with the same test count as main at the worktree base (86e430fb). The ADR itself is markdown; the gate must still pass to confirm no .ts was touched.
  • The ADR file exists, parses as valid YAML+Markdown, and its frontmatter matches I-1.
  • The ADR contains all eight required §sections in order (I-2).
  • Every code citation in the ADR is line-accurate against the worktree base.
  • Both index files contain a new ADR-008 row/bullet (I-8).

5. Risks and mitigations

Risk Mitigation
ADR-007 lands first and the index merges conflict Add only ADR-008’s row; let the merge handle ordering. Both rows are independent line additions.
Recommendation drifts from A The audit confirms A is the right call; the §Alternatives section explains why B and C are not.
Word count creeps beyond useful Target 1,800–2,400 words in the ADR body. Concise prose, single tables for inventories.
Reader confuses “Proposed” status with “shipped” The §Implementation section is explicitly labelled “follow-up tasks”; status: proposed in frontmatter; PROPOSED in body header.
Reader assumes ADR-008 binds the runtime today §Verification states the gate is “the follow-up implementation task lands the code described in §Implementation”; the ADR alone does not change runtime behavior.

6. References

  • Audit: docs/audits/adr-008-mode-enforcement-audit.md
  • Code: src/modes.ts:174, src/server.ts:229, src/server.ts:412-437
  • Docs: docs/2-plugin/modes.md:31, docs/reference/mcp-tools-phase-0.md:930, docs/architecture/decisions/ADR-004-tool-surface.md:68
  • ADR format: docs/architecture/decisions/README.md
  • Sibling ADR: ADR-007 (η session lifecycle, independent worktree)

Back to top

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

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