Linux_post_install/AgentsReport/maintainer/2026-08-26_registry-docs-sync.md

2026-08-26 — registry-docs sync (Maintainer)

TL;DR

• Drift: command-registry feature (lib/registry.sh, optional # POS_DEPS:/# POS_EXAMPLES: headers) landed without syncing 3 agent/convention docs — confirmed: AGENTS.md (header enumeration + pos tree description), DOC/SCRIPTS.md (Phase-2 lib list, no lib section, stale TOC), MAINTENANCE.md (no record of the convention change).
• Corrections: all three synced to implemented reality (code + # POS_* headers as ground truth); docs-only, nothing else touched.
• Sweep findings (reported): 2 out-of-fence staleness spots in DOC/AGENT_Context_Project.md (:548 header enumeration, :598 wrongly lists gen-docs.sh as a registry consumer); 1 minor incomplete phrasing in DOC/POS.md:498. In-fence extra fixed: SCRIPTS.md TOC was missing 5 pre-existing lib sections.
• MAINTENANCE.md decision: no phase-log/conventions-summary section exists → did NOT invent one; used the file's own sanctioned mechanism instead (one appended ticket, M-024, dated Fix line).
• Validation: make gen zero new drift beyond pre-existing uncommitted feature work · make check OK · make lint 0 FAIL, 0 WARN · grep -n "POS_DEPS" present in AGENTS.md / DEV.md / SCRIPTS.md.

Standard established (evidence)

Ground truth verified before editing:

• templates/pos-tool.sh:13-14 documents optional # POS_DEPS: / # POS_EXAMPLES:.
• DOC/DEV.md:126-134 already documents both headers + semantics; DOC/DEV.md:34 already lists registry.sh → only AGENTS.md / DOC/SCRIPTS.md / MAINTENANCE.md drifted.
• install.sh:143 lib_names: registry.sh is LAST (… usb-lib.sh share-lib.sh menu-lib.sh registry.sh) — SCRIPTS.md Phase-2 row must append it after menu-lib.sh.
• Consumers: bin/pos-tree:7 sources lib/registry.sh; bin/pos:68-90 _pos_category_help() lazy-sources it (reg_scan/reg_tools_in/reg_lookup, incl. deps).
• scripts/gen-docs.sh:47-48 parses the same headers independently (predates registry) — must NOT be listed as a registry consumer.
• lib/registry.sh (199 lines): no shebang, not executable, installed 644; guarded log/warn/err fallbacks ("mirrors lib/config-ui.sh", :18-21); key = filename after pos-, category split at first dash (empty when category-less, :66-78); fields cat/desc/flags/subcmds/deps/examples (:11); config scope helpers (:171-186); reg_each callback contract cb(cat, key, desc) (:189-194); sorts under LC_ALL=C inside reg_scan (:50-51,120-125).

Step 1: AGENTS.md — Tool model bullet (+POS_DEPS/+POS_EXAMPLES/+registry API)

AGENTS.md:17 — extended the header sentence with both optional headers (deps = space-separated runtime binaries hard-required via command -v guards; examples = one per line, <command> | <description>) and one clause naming lib/registry.sh as the shared query API over all POS_* headers (reg_scan + reg_list/reg_lookup/…), new consumers to prefer it. Kept the original terse single-bullet style; nothing else in the bullet touched.

[DONE]

Step 2: AGENTS.md — Categories bullet (pos tree metadata source)

AGENTS.md:18 — minimal extension: hierarchy still derives from filenames + # POS:/# POS_SUBCMDS: headers; now also states it reads metadata through lib/registry.sh and annotates declared # POS_DEPS:. Matches observable behavior of bin/pos-tree (sources registry.sh:7; [deps: …] annotations visible in the generated tree block).

[DONE]

Step 3: DOC/SCRIPTS.md — Phase 2 lib list + registry section + TOC

a) Phase-2 row — appended + lib/registry.sh after + lib/menu-lib.sh, i.e. LAST in the list, matching install.sh:143 lib_names actual order (… usb-lib share-lib menu-lib registry).

b) New section ## lib/registry.sh — tool metadata query API inserted between lib/menu-lib.sh and the features sections (install order), in the neighbors' File/Purpose/Sourced-by dense-paragraph format. Claims grounded: reg_scan LC_ALL=C + lazy (bin/pos:70 comment), key/category convention, six fields, config-scope helpers, reg_each cb(cat,key,desc) contract, reg_tool_exists, guarded log/warn/err "like lib/config-ui.sh" (:18-21 says it verbatim), no shebang/not executable/installed 644. Consumers listed as bin/pos-tree + bin/pos _pos_category_help() only; gen-docs.sh explicitly noted as parsing independently (predates registry).

c) TOC — added - [lib/registry.sh — tool metadata query API](#libregistrysh--tool-metadata-query-api) in matching format. Sweep-driven extra (unambiguous staleness INSIDE this item file, authorized by sweep clause): TOC was also missing rows for five sections that already existed in the body (entertainment-lib, user-timers-lib, usb-lib, share-lib, menu-lib) — added those five too, anchors derived by the same slug pattern as existing entries.

[DONE]

Step 4: MAINTENANCE.md — judgment call

Structure read: Phase 0 authority order / Baseline / Checklist matrix / Lint results / Findings tickets (M-001..M-023, all resolved 2026-08-14) / Deep-dive notes / Next-session brief / Checked & clean. No phase log or conventions-summary section exists, so per the brief's escape clause a new section was NOT invented.

However the file is not frozen: its own header instructs "Keep the structure below; append findings as they land", and its native dated-record mechanism is exactly one ticket entry ending Fix (date): …. Docs-category findings belong under ### P2 — doc drift / consistency / style. → Added ONE entry, ticket M-024, in the established field set, with the required content: template documents the optional headers (pre-existing), registry.sh added as shared query API, consumers migrated (pos-tree, bin/pos category help), lint unchanged. Nothing else in the file touched.

Deliberately NOT changed: the Checklist line enumerating # POS_FLAGS:/# POS_SUBCMDS:/# POS_CONFIG: — it is a historical snapshot of the audit-time convention matrix ("from AGENTS.md … DEV.md" at audit date), and rewriting completed-audit history isn't standard restoration; M-024 records the current state instead.

[DONE]

Step 5: Sweep check + gates

Sweep (grep over DOC/*.md, AGENTS.md, README.md, MAINTENANCE.md for stale header/consumer claims):

Findings — outside the fence, reported only, NOT touched:

1. DOC/AGENT_Context_Project.md:548 ("Adding a New Tool" step 2, hand-maintained row) — header enumeration lists only # POS_FLAGS:/# POS_SUBCMDS:; missing both new optional headers.
2. DOC/AGENT_Context_Project.md:598 (hand-maintained registry.sh filetable row) — says "used by pos-tree and gen-docs.sh"; false for gen-docs.sh, which parses the headers itself (scripts/gen-docs.sh:47-48) and never sources the lib (its only "registry" hit is a comment naming the # POS_CONFIG: concept). Line count 199 is still correct. This is exactly the "each consumer parses headers itself"-class claim the sweep was told to hunt.
3. DOC/POS.md:498 — minor: describes pos tree data as derived from filenames + # POS_SUBCMDS: headers annotated with descriptions; incomplete (no deps annotation / registry mention) but not unambiguously false → left.

Finding inside the fence — deliberately not fixed: MAINTENANCE.md:37 checklist matrix enumerates only the three original headers. It is a historical snapshot of the completed 2026-08-14 audit's convention matrix; current state is recorded by M-024 instead of rewriting audit history.

In-fence staleness fixed under the sweep clause: SCRIPTS.md TOC missing 5 pre-existing lib sections (done in Step 3c).

Clean: DOC/DEV.md (already fully updated with headers + registry), README.md and DOC/README.md (no lib/header enumerations), howto/*.

Gates (tails)

$ make gen && git diff --stat   → gen-docs: write OK; diff = my 3 docs + AgentsReport +
                                   pre-existing uncommitted registry-feature work
                                   (bin/*, templates/, scripts/gen-docs.sh, install.sh,
                                   AGENT_Context) — zero drift introduced by this session
$ make check                    → check-sync: OK
$ make lint                     → 0 FAIL, 0 WARN (convention lint)
$ grep -n "POS_DEPS" …          → AGENTS.md:17,18 · DOC/DEV.md:131,134 · DOC/SCRIPTS.md:241 ✓

---

Status: MAINTENANCE_COMPLETE

Maintenance objective: Sync the three agent/convention docs that drifted when the command-registry feature landed; code + # POS: headers are ground truth.

Findings addressed: AGENTS.md Tool-model + Categories bullets (fixed); DOC/SCRIPTS.md Phase-2 lib list + new registry section + TOC (fixed, incl. 5 pre-existing TOC omissions); MAINTENANCE.md record (added as ticket M-024 via the file's own append-findings mechanism).

Standard enforced: Authority order per MAINTENANCE.md Phase 0 — code + # POS: headers ground truth; template/DEV.md codified convention; doc drift in SCRIPTS = doc bug.

Files changed: AGENTS.md · DOC/SCRIPTS.md · MAINTENANCE.md · AgentsReport/maintainer/2026-08-26_registry-docs-sync.md (nothing else)

Verification performed: make gen (idempotent, no new drift) · make check OK · make lint 0 FAIL / 0 WARN · POS_DEPS grep present where expected · diffs reviewed line-by-line against intended edits.

Records updated: This report; MAINTENANCE.md M-024.

Scope compliance: In-scope corrections + one explicitly-reasoned sweep fix (SCRIPTS.md TOC) inside an item file; out-of-scope changes: none (3 sweep findings reported, untouched).

Remaining / deferred items: AGENT_CONTEXT :548/:598 + POS.md:498 need a follow-up pass (outside this fence); MAINTENANCE.md:37 checklist left historical by design.

Recommended next agent: Reviewer — independent adversarial review of the three doc edits before commit (per constraints, nothing is committed).

Changes made by Maintainer: Smallest corrective doc changes only; no code, no templates, no GEN blocks, no completions.