R77.B — Contract
Behavioural contract for R77.B. Upstream of the packet (Step 3). Based on inventory in r77-b-refs-config-audit.md.
1. Preconditions
| # | Precondition | Verification |
|---|---|---|
| P1 | Worktree .worktrees/claude/r77-b-refs-config exists on branch feature/r77-b-refs-config |
git worktree list |
| P2 | Base main is at ea5055e0 (R77.F2 merged) |
git log main -1 --oneline |
| P3 | Current docs tree has 1 broken ADR ref + 1 stray-docs/ ref in live docs |
Audit §1.3 inventory |
| P4 | Current docs/_config.yml missing @v0.12.0 pin, color_scheme, callouts:, mermaid: blocks |
Audit §2.2 |
| P5 | Test suite baseline: 1085/1085 green | npm test on main |
2. Invariants (MUST NOT CHANGE)
| # | Invariant | Scope |
|---|---|---|
| I1 | No src/ file changes |
R77 ships no code |
| I2 | docs/_config.yml keys outside the hardening list remain byte-identical |
Audit §2.4 list: title, description, baseurl, url, plugins, relative_links, search_enabled, search, aux_links, footer_content, nav_sort, back_to_top, back_to_top_text, markdown, highlighter, kramdown, exclude, defaults |
| I3 | Link text in the 2 broken-ref fixes stays byte-identical | Only the URL target changes; the visible text does not |
| I4 | npm run build && npm run lint && npm test remain green (1085/1085) |
Step 5 verification |
| I5 | No files added under docs/audits/, docs/packets/, or docs/verification/ beyond the R77.B 5-step artefacts themselves |
Exclusion zone stays read-only except for this task’s own chain documents |
| I6 | No edits to the Obsidian vault mirror zone | CLAUDE.md §3 forbid rule |
3. Behavioural goals (MUST CHANGE)
Goal A — Fix ADR-004-tool-surface.md:99 casing
Before (line 99):
| Router | all δ tools | Deferred to Phase 1.5 per [ADR-005](adr-005-multi-model-defer.md). Phase 0 is Claude-only. |
After (line 99):
| Router | all δ tools | Deferred to Phase 1.5 per [ADR-005](ADR-005-multi-model-defer.md). Phase 0 is Claude-only. |
Diff scope: adr-005 → ADR-005 in the () target only. Link text [ADR-005] unchanged.
Goal B — Fix world-schema.md:3 stray docs/ prefix
Before (line 3):
> Derived from the handwritten layer sketch (2026-04-13), [`docs/colibri-system.md`](docs/colibri-system.md), and a full 7-pass review of all 672 repo .md files (224 docs/ + 257 .agents/ + 79 data/ + 112 other zones).
After (line 3):
> Derived from the handwritten layer sketch (2026-04-13), [`docs/colibri-system.md`](colibri-system.md), and a full 7-pass review of all 672 repo .md files (224 docs/ + 257 .agents/ + 79 data/ + 112 other zones).
Diff scope: ](docs/colibri-system.md) → ](colibri-system.md) — the visible link-text `docs/colibri-system.md` (in backticks, inside the []) is preserved verbatim. Only the URL target changes to a sibling-relative reference.
Goal C — Pin remote_theme to stable tag
Before (line 10 of docs/_config.yml):
remote_theme: just-the-docs/just-the-docs
After:
remote_theme: just-the-docs/just-the-docs@v0.12.0
Goal D — Add explicit color_scheme
After the remote_theme: line, add:
color_scheme: light
With an above-line comment explaining explicit-default intent.
Goal E — Add callouts: block
Insert a canonical callouts: block with the 5 just-the-docs standard variants (highlight, important, new, note, warning) matching the upstream _config.yml reference. Placement: after back_to_top_text, before # Markdown processing.
Goal F — Add mermaid: block
Insert a mermaid: block with version: "9.1.6" (just-the-docs canonical reference version). Placement: immediately after the callouts: block (so the theme-rendering options cluster is contiguous).
4. Contract test — acceptance criteria
| # | Criterion | Pass signal |
|---|---|---|
| A1 | Grep for ]\(adr- in docs/**/*.md excluding audits/packets/verification returns zero hits |
Step 5 evidence |
| A2 | Grep for ]\(docs/ in docs/**/*.md excluding audits/packets/verification returns zero hits |
Step 5 evidence |
| A3 | docs/_config.yml remote_theme: value ends with @v0.12.0 |
Step 5 diff + parse |
| A4 | docs/_config.yml contains color_scheme: top-level key with value light |
Step 5 diff + parse |
| A5 | docs/_config.yml contains callouts: top-level key with 5 named children |
Step 5 diff + parse |
| A6 | docs/_config.yml contains mermaid: top-level key with version: child equal to "9.1.6" |
Step 5 diff + parse |
| A7 | npm run build exit 0 |
Step 5 shell log |
| A8 | npm run lint exit 0 |
Step 5 shell log |
| A9 | npm test exits 0, 1085/1085 or better |
Step 5 shell log |
| A10 | docs/_config.yml protected keys (I2 list) match pre-edit bytes modulo the hardening block additions |
Step 5 diff review |
5. Out of scope
- Stray
docs/prefixes insidedocs/audits/,docs/packets/,docs/verification/— left as-is (historical artefacts; they document past fixes, not live hyperlinks). - Cross-ref hygiene sweeps in
.agents/,.claude/, or_vault/— not part of R77.B. - Frontmatter edits — R77.B does not touch any doc frontmatter.
- Any
.yml/.yamlfiles outsidedocs/_config.yml. - Any Pages GitHub Actions workflow changes.
6. Rollback plan
Single-branch commit chain; git reset --hard ea5055e0 (base) if a Pages or test regression surfaces post-merge. All edits are surgical enough that a revert commit would be a clean inversion.
7. Contract gate
Step 2 complete. Step 3 (packet) will enumerate the exact Edit operations.