feat(wiki): deterministic wiki-lint (pilot step 2) — drift check that actually gates #164

Merged

clawdie merged 2 commits from feature/wiki-lint into main

2026-06-24 10:37:07 +02:00

clawdie commented

2026-06-24 10:36:04 +02:00

Owner

Pilot step 2: a deterministic wiki-lint that checks docs/wiki/ against the codebase — dangling references, resurrected old names, orphan pages. Advisory by default, --strict to gate.

Evaluation of the original draft

The approach was right (the three checks, FreeBSD-portable, advisory + --strict). But check #2 — "resurrected old names," the most important one and the exact drift that motivated this — was non-functional. Proof: planting hermes-agent + usb_nodes + COLIBRI_AUTOSPAWN_PI in a real source file passed clean, exit 0 under --strict. Three bugs:

It ran in a pipeline (echo | tr | while) → fail/pass happened in a subshell, so counts and the --strict exit were lost.
Hit files were accumulated with literal \n → the per-file filter never matched → nothing detected even if the subshell worked.
OLD_NAMES was hardcoded and already stale (no usb_nodes), despite the comment claiming it parsed the ledger.

Fix

Parse old names from the Shipped table of naming-decisions.md — self-updating, no hardcoded list to rot (the meta-point of the wiki).
Loop in the main shell (read from a file) so counters and --strict propagate.
xargs grep -nHF across the file list; filter legit contexts case-insensitively (migration / rename / back-compat / alias / changelog) so the serde alias and the setup-mother migration code don't false-positive.
Moved usb_nodes → hive_nodes from In-flight to Shipped (#161 merged) → now enforced.

Verified

Clean run: PASS 37 / FAIL 0, exit 0.
Planting hermes-agent / usb_nodes / COLIBRI_AUTOSPAWN_PI → each FAILs, --strict exits 1.
Fixed a serde-alias false-positive (multi-line #[serde(\n alias = …)]). sh -n + markdown gate green.

Recommend wiring it advisory-first alongside ci-checks.sh (it's already in AGENTS.md); graduate to --strict in the gate once trusted.

🤖 Generated with Claude Code

Pilot step 2: a deterministic `wiki-lint` that checks `docs/wiki/` against the codebase — dangling references, **resurrected old names**, orphan pages. Advisory by default, `--strict` to gate. ## Evaluation of the original draft The approach was right (the three checks, FreeBSD-portable, advisory + `--strict`). But check #2 — "resurrected old names," the most important one and the exact drift that motivated this — was **non-functional**. Proof: planting `hermes-agent` + `usb_nodes` + `COLIBRI_AUTOSPAWN_PI` in a real source file passed **clean, exit 0** under `--strict`. Three bugs: 1. It ran in a pipeline (`echo | tr | while`) → `fail`/`pass` happened in a **subshell**, so counts and the `--strict` exit were lost. 2. Hit files were accumulated with literal `\n` → the per-file filter never matched → nothing detected even if the subshell worked. 3. `OLD_NAMES` was **hardcoded and already stale** (no `usb_nodes`), despite the comment claiming it parsed the ledger. ## Fix - **Parse old names from the Shipped table of `naming-decisions.md`** — self-updating, no hardcoded list to rot (the meta-point of the wiki). - Loop in the **main shell** (read from a file) so counters and `--strict` propagate. - `xargs grep -nHF` across the file list; filter legit contexts case-insensitively (migration / rename / back-compat / `alias` / changelog) so the serde alias and the `setup-mother` migration code don't false-positive. - Moved `usb_nodes → hive_nodes` from In-flight to **Shipped** (#161 merged) → now enforced. ## Verified - Clean run: `PASS 37 / FAIL 0`, exit 0. - Planting `hermes-agent` / `usb_nodes` / `COLIBRI_AUTOSPAWN_PI` → each FAILs, `--strict` exits 1. - Fixed a serde-alias false-positive (multi-line `#[serde(\n alias = …)]`). `sh -n` + markdown gate green. Recommend wiring it **advisory-first** alongside `ci-checks.sh` (it's already in `AGENTS.md`); graduate to `--strict` in the gate once trusted. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

clawdie added 2 commits 2026-06-24 10:36:06 +02:00

feat(wiki): deterministic wiki-lint — pilot step 2 77061e4510

Three checks (no LLM, CI-friendly, portable /bin/sh):

1. Dangling references — every file path cited in docs/wiki/*.md
   must exist (short names resolved via find fallback). Skips
   cross-repo paths (clawdie-iso/*), example paths (path/to/*),
   and wiki-documented absences (ADR-agent-harness-consolidation.md).

2. Resurrected old names — the five "Shipped" renames from
   naming-decisions.md must not reappear in code outside the wiki.
   Filters out legitimate migrations (setup-mother.sh sed line,
   lib.rs #[serde(alias)]) and SQL migration boilerplate.

3. Orphan pages — every docs/wiki/*.md is linked from index.md.

Advisory by default (exit 0); --strict gates with non-zero exit.
Added to AGENTS.md alongside ci-checks.sh.

FreeBSD-portable: find-based file discovery instead of GNU greps
--exclude-dir; temp files instead of process substitution.

fix(wiki-lint): make check 2 actually work + parse ledger

CI / rust (pull_request) Has been cancelled

Details

CI / markdown (pull_request) Has been cancelled

Details

CI / port (pull_request) Has been cancelled

Details

CI / agent-jail-pkgs (pull_request) Has been cancelled

Details

9947da9edc

The 'resurrected old names' check was non-functional: it ran in a pipeline
subshell (fail/pass counts and --strict exit were lost), accumulated hit files
with literal \\n (so the per-file filter never matched), and hardcoded the old
names — already stale (missing usb_nodes, the rename that motivated this).
Planting hermes-agent + usb_nodes + COLIBRI_AUTOSPAWN_PI in a source file
passed clean under --strict.

Rewrite:
- Parse old names from the Shipped table of naming-decisions.md (self-updating;
  no hardcoded list to rot).
- Loop in the main shell (read from a file) so counters and --strict propagate.
- xargs grep -nHF across the file list; filter legit contexts case-insensitively
  (migration/rename/back-compat/alias/changelog) so the serde alias and the
  setup-mother migration code don't false-positive.
- Move usb_nodes → hive_nodes from In-flight to Shipped (colibri #161 merged) so
  it is now enforced.

Verified: clean run exits 0 (PASS 37); planting hermes-agent/usb_nodes/
COLIBRI_AUTOSPAWN_PI now FAILs and --strict exits 1. Fixed a serde-alias
false-positive (multi-line attribute). sh -n + markdown gate green.