docs(meta): add the context glossary and the plumbing-contract ADR

[Syndic]

Output of a design review of the devcontainer base image work. Two artifacts the repo's documented
structure called for but had never gained, plus the map entry that registers one of them.

meta/CONTEXT.md — the first context glossary

CONTEXT-MAP.md has listed both contexts as (CONTEXT.md not yet written) since it was created.
This writes the first one. Nine terms across two clusters — the base image and repo health — kept
to a glossary, with no implementation detail.

The one worth calling out: "plumbing" collides with git's own vocabulary. git's
plumbing/porcelain split means low-level commands, and .git-plumbing/ pairs the two words in the
way most likely to mislead. The term stays — it is apt in the ordinary sense, and renaming would
reach the devcontainer-plumbing command, the PLUMBING_* env prefix, the plumbing_* function
prefix, the directory, both repos' docs, and a consumer that hasn't adopted yet. Disambiguating it
in the glossary is the cheap fix.

Also opinionated where the code isn't: meta/scripts/README.md calls these things both "gates" and
"guards". The glossary picks check, since that is what the filenames and the on-save labels
already say, and records that whether one blocks is a property of where it runs.

meta/docs/adr/0001-… — the plumbing contract

The first decision scoped to a single context rather than the repo, so it exercises the
<context>/docs/adr/ path docs/agents/domain.md documents.

It records something the code already did and the docs denied. plumbing_apply_git_common
reads $PLUMBING_DIR/host-git-common-path by name and links it to /host-git-common;
plumbing_apply_all reads host-timezone by name. Those are contract terms whether or not anyone
wrote them down — so the base image README's claim that the host stub "does not constrain where the
host keeps anything" was only half true. It constrains the names; it leaves the sources free,
which is what the symlink indirection is for.

Syndic/.dotfiles is the evidence for why the distinction matters. It presents known_hosts and
allowed_signers as snapshot files where this repo presents them as bind-mounted symlinks, and its
copy of the plumbing consequently diverged in kind rather than in detail. Under this ADR, adoption
is conformance: that shape is an artefact of age, not a variant to support.

Numbering note for review

This is meta/docs/adr/0001-… while docs/adr/0001-… (the Go-pure/Python-impure policy) already
exists. ADR-FORMAT.md numbers per directory, so two 0001s in different scopes is what the
documented structure produces. Flagging it because it is the kind of thing that is cheap to change
now and annoying later — say the word if you would rather ADR numbers be globally unique.

What this does not do

The extraction itself — moving the four post-start.sh steps and the timezone parsing into the
shared library, and renaming lib.sh to plumbing.sh — is a separate PR. Filed alongside this
review: #247 (the ssh -G call on every up) and #248 (how consumers share what the image cannot
carry).

Validation

bazel test //... 23/23, pre-commit clean.

🤖 Generated with Claude Code

[Syndic]

Update: ADR numbering is now global, and enforced

The numbering question I flagged for review is resolved in 23749a7. ADR numbers are unique
across the whole repo, not per directory, so meta/docs/adr/0001-… is renumbered to 0002-…
behind docs/adr/0001-….

The convention is documented where it survives

This diverges from the /domain-modeling skill's ADR-FORMAT.md, which says to scan a directory
for the highest number — under global numbering that hands you a number already taken. The skill
ships from a read-only plugin cache that npx skills update overwrites, so the durable place to
record the divergence is our own docs. docs/agents/domain.md now states the rule, says explicitly
that it overrides the skill, and names the enforcing check. CONTEXT-MAP.md gets a one-line
pointer rather than a second copy.

The check

meta/scripts/check_adr_numbers.py enforces two things: no reused number anywhere, and the
NNNN-kebab-slug.md filename shape. The shape is not scope creep — a malformed name has no number
to compare, so skipping it silently would leave a hole in the exact property being enforced. There
is a test for precisely that (test_malformed_name_is_not_also_counted_as_a_number).

Wiring follows check_go_work.py's profile: CI job plus on-save task, no pre-commit hook. It is
the closest sibling — a tree walk over checked-in files with nothing to fix — and the repo's README
already draws that line. Adding a hook would also pull in the test_precommit_docs.py coupling
(hook table plus classifying paragraph) for a check CI already gates.

README.md's script table gains a row; the "four guards" count becomes five.

Verified rather than assumed

• Discovery genuinely spans both directories — printed the file list to confirm it finds
  docs/adr/ and meta/docs/adr/, not just the one the check happens to start from.
• A live duplicate fails: dropped a colliding 0001 into meta/docs/adr/, got the expected
  path:1:1-2: diagnostic naming the file that already owns the number, exit code 1, then removed
  it.
• 10 unit tests, including that a third use of a number is reported too (reporting only the first
  collision would let a fix land and leave a duplicate behind).

bazel test //... 24/24.

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.86%. Comparing base (5aaaf68) to head (58dec80).

Files with missing lines	Patch %	Lines
meta/scripts/check_adr_numbers.py	94.11%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #249      +/-   ##
==========================================
+ Coverage   83.60%   83.86%   +0.25%     
==========================================
  Files          40       41       +1     
  Lines        2025     2076      +51     
  Branches       99      111      +12     
==========================================
+ Hits         1693     1741      +48     
- Misses        316      318       +2     
- Partials       16       17       +1     

Components	Coverage Δ
Go	85.14% <ø> (ø)
Python	80.94% <94.11%> (+1.15%)	⬆️
Category: apps	∅ <ø> (∅)
Category: infra	∅ <ø> (∅)
Category: libs	∅ <ø> (∅)
Category: meta	80.94% <94.11%> (+1.15%)	⬆️
Category: services	∅ <ø> (∅)
Category: tools	85.14% <ø> (ø)
Project: meta/scripts	80.94% <94.11%> (+1.15%)	⬆️
Project: tools/network_infrastructure_maintenance	85.14% <ø> (ø)

Files with missing lines	Coverage Δ
meta/scripts/check_adr_numbers.py	94.11% <94.11%> (ø)

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5aaaf68...58dec80. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Syndic]

Added: --next

Global numbering left no way to find the next number except scanning every docs/adr/ directory — the convention was documented, the way to comply with it wasn't.

python3 meta/scripts/check_adr_numbers.py --next

Prints 0003 and nothing else, so it substitutes straight into a filename. Two behaviours worth knowing:

• It answers during a collision. --next is how you get out of a duplicate, so refusing to answer while one exists would be backwards.
• It is max+1, not count+1. A gap left by a deleted or renamed ADR is never handed out again, because a reused number breaks every reference to the original.

A duplicate now also reports a free number to move to (renumber to 0003 or later — "or later" because several duplicates all see the same free number and only the first can take it), so the failure carries its own fix. Both modes share one number parser, so the check and the suggestion cannot disagree about what counts as a number.

No counter file, deliberately

The numbers already live in the filenames. A counter would be a second source of truth — by this repo's own convention a derived file, needing its own freshness check — and a merge conflict on every concurrent ADR PR.

The race that usually justifies one is already closed here: the ruleset requires up-to-date branches, so a second ADR PR has to rebase onto a main that already contains the first, and then check_adr_numbers.py fails on it. The collision surfaces at the same moment either way, as a clear check failure rather than a conflict on a counter line.

Verified

• Live: dropped a real colliding 0001 in, got duplicate ADR number 0001: already used by docs/adr/0001-go-builds-are-pure-python-is-not.md; renumber to 0003 or later, exit 1 — and --next still printed 0003 during it.
• 21 unit tests now, including both CLI modes driven through a testable run(root, next_only) entry point rather than by shelling out.

bazel test //... 24/24.