Linux_post_install/AgentsReport/builder/2026-08-26_registry-implementation.md

Builder Report — Self-Describing Command Registry for POS

Date: 2026-08-26 Status: COMPLETE

---

TL;DR

• Status: All 8 steps implemented and verified
• Files created: lib/registry.sh (199 lines, mode 664)
• Files modified: scripts/gen-docs.sh, bin/pos-tree, templates/pos-tool.sh, install.sh, DOC/DEV.md, DOC/AGENT_Context_Project.md
• Verification: All gates pass — gen drift ✅, tree output identical ✅, make check ✅, make lint shows only pre-existing issues ⚠️

---

Step 0: Establish Current State

Prerequisite: Pre-existing gen drift from pos-ai-alias was committed as 6566c83 (chore: re-gen docs for pos-ai-alias addition) to get a clean baseline.

Baselines (all clean after gen drift fix):

Gate	Result
pos-tree output	✅ exit 0, captured to /tmp/pos-tree-before.txt
make gen && git diff --exit-code	✅ zero diff (gen output matches committed)
make check	✅ check-sync: OK
make lint	⚠️ 1 FAIL (pre-existing: bin/pos-ai-alias not in INTERACTIVE_CMDS), 1 WARN (pos-ai-alias not in DOC/POS.md) — both unrelated to this task

Notes:

• make lint takes ~2-3 minutes to complete (scans 56+ files with regex)
• The pre-existing lint FAIL on pos-ai-alias is outside our scope

[DONE]

---

Step 1: Create lib/registry.sh

File: lib/registry.sh (191 lines, mode 664, no shebang)

Changes:

• Created the shared query API library following the architect's pseudocode and lib/config-ui.sh structural pattern
• Key derivation: bin/pos-network-download → key network-download, category network; bin/pos-config → key config, category ""
• reg_scan sets/restores LC_ALL=C for deterministic sort
• All associative-array lookups use ${var:-} fallback for missing keys
• reg_categories uses a sentinel __empty__ to handle empty-category associative array limitation in bash
• All API functions implemented: reg_scan, reg_list, reg_categories, reg_tools_in, reg_lookup, reg_config_scopes, reg_config_keys, reg_config_envfile, reg_each, reg_tool_exists

Functional test: Registry loads all ~40 tools, lookups return correct data, categories list correctly, config scopes found.

[DONE]

---

Step 2: Update scripts/gen-docs.sh

File: scripts/gen-docs.sh (modified)

Changes:

1. Tools collection loop (lines ~42-47): Added deps and examples fields to the pipe-delimited tools array format: "$cat|$sub|$desc|$flags|$subcmds|$deps|$examples"
   • deps: parsed with same sed pattern as existing headers
   • examples: parsed with grep | sed | paste (pipe-delimited, || true to handle empty matches with pipefail)
2. _has_deps_examples flag: Scans tools array once to determine if any tool has non-empty deps/examples — drives conditional column rendering
3. gen_tree(): Reads 7 fields now; adds [deps: X] annotation line when non-empty
4. gen_dispatch(): When _has_deps_examples=1, adds Deps/Examples columns to the header and all data rows. When 0, renders unchanged format
5. gen_filetable(): Updated to read 7 fields (output unchanged — no deps/examples columns for now)
6. gen_posflags(): Updated to read 7 fields (output unchanged)
7. gen_possubcmds(): Updated to read 7 fields (output unchanged)

Drift check: git diff -- DOC/AGENT_Context_Project.md completions/pos.bash → zero diff — gen output is byte-identical to current committed output.

[DONE]

---

Step 3: Migrate bin/pos-tree

File: bin/pos-tree (modified)

Changes:

1. Added source lib/registry.sh after common.sh sourcing (with fallback chain)
2. Replaced file-scanning loop (for f in "$self"/pos-*) with reg_scan "$self" + reg_list iteration
3. Tree data collection now uses reg_lookup "$tool_key" cat|desc|subcmds|deps
4. add() and render() functions kept unchanged — only data-collection section changed
5. When deps is non-empty, appended [deps: X] to the description string before passing to add()

Output comparison: diff /tmp/pos-tree-before.txt /tmp/pos-tree-after.txt → empty (identical)

[DONE]

---

Step 4: Update templates/pos-tool.sh

File: templates/pos-tool.sh (modified)

Changes:

• Added # POS_SUBCMDS:, # POS_DEPS:, # POS_EXAMPLES: to the header documentation block (step 2 comment)
• Placed after existing # POS_FLAGS: example

[DONE]

---

Step 5: Update install.sh

File: install.sh (modified)

Changes:

• Added registry.sh to the lib_names array (line 143) alongside other library names

[DONE]

---

Step 6: Update DOC/DEV.md

File: DOC/DEV.md (modified)

Changes:

• Added # POS_DEPS: and # POS_EXAMPLES: to the header code block in "Adding a New CLI Tool → Make it discoverable"
• Added explanation paragraph for both new headers (POS_DEPS: runtime binary names; POS_EXAMPLES: curated usage examples)
• Both documented as optional with graceful degradation

[DONE]

---

Step 7: Update DOC/AGENT_Context_Project.md

File: DOC/AGENT_Context_Project.md (modified)

Changes:

• Added lib/registry.sh | 199 | Shared query API for POS tool metadata headers (...) row to the hand-maintained line-count table (above GEN:START filetable marker)
• Gen blocks updated via make gen (docmap line numbers shifted by +1 section; filetable shows pos-tree at 118 lines)

[DONE]

---

Step 8: Verification

Syntax checks

bash -n lib/registry.sh      ✅
bash -n scripts/gen-docs.sh  ✅
bash -n bin/pos-tree         ✅

Gen drift check

make gen && git diff --exit-code  ✅ (no gen drift)

• Generated blocks (tree, dispatch, filetable, selfcontained, posflags, possubcmds, posconfigscopes) are byte-identical to committed output
• completions/pos.bash has zero diff

Tree output comparison

diff /tmp/pos-tree-before.txt /tmp/pos-tree-final.txt  → empty ✅

Self-consistency gate

make check  →  check-sync: OK  ✅

Convention lint gate

make lint  →  1 FAIL, 1 WARN  (both pre-existing, unrelated to this task)

• FAIL: bin/pos-ai-alias not in INTERACTIVE_CMDS — pre-existing
• WARN: bin/pos-ai-alias not in DOC/POS.md — pre-existing
• Zero new issues from this implementation

Summary

Gate	Result	Notes
Syntax	✅ all pass	registry.sh, gen-docs.sh, pos-tree
Gen drift	✅ zero diff	Gen blocks byte-identical
Tree output	✅ identical	Before/after comparison empty
make check	✅ OK	Full self-consistency gate
make lint	⚠️ 1 FAIL, 1 WARN	Pre-existing only (pos-ai-alias)

[DONE]

---

Artifact Summary

Files Created

File	Mode	Lines	Purpose
lib/registry.sh	664	199	Shared query API for POS tool metadata headers

Files Modified

File	Nature of Change
scripts/gen-docs.sh	Added deps/examples to tools array format; conditional columns in gen_dispatch; deps annotation in gen_tree
bin/pos-tree	Migrated data collection from direct sed to registry API; source registry.sh
templates/pos-tool.sh	Documented POS_SUBCMDS, POS_DEPS, POS_EXAMPLES headers
install.sh	Added registry.sh to lib_names array
DOC/DEV.md	Documented POS_DEPS and POS_EXAMPLES in "Make it discoverable"
DOC/AGENT_Context_Project.md	Added lib/registry.sh row to hand-maintained line-count table; gen blocks updated

Files NOT Modified (scope compliance)

• bin/pos — dispatcher logic untouched ✅
• completions/pos.bash — no changes needed ✅
• lib/config-ui.sh — not integrated with registry ✅
• No # POS_DEPS: or # POS_EXAMPLES: added to existing tools ✅

Prerequisite Commits

1. 6566c83 — chore: re-gen docs for pos-ai-alias addition (pre-existing gen drift)
2. 5d7407e — chore: update docmap + filetable for registry.sh addition (gen output for my changes)

Pre-existing Issues (not in scope)

• bin/pos-ai-alias: FAIL — reads stdin but not in INTERACTIVE_CMDS
• bin/pos-ai-alias: WARN — not referenced in DOC/POS.md