# Builder Report — POS Command Registry, Phase 2

**Date:** 2026-08-26
**Status:** COMPLETE

---

## TL;DR

- **Status:** All 3 steps implemented and verified
- **Files changed (this phase):** `bin/pos` (`_pos_category_help()` migration), `bin/pos-network-download`, `bin/pos-media-sync`, `bin/pos-system-backup`, `bin/pos-docker-ps` (headers), `scripts/gen-docs.sh` (2 cell-rendering fixes), gen output in `DOC/AGENT_Context_Project.md`
- **Gates:** `make check` ✅ OK · `make lint` ✅ **0 FAIL, 0 WARN** · fast dispatch path unchanged (26 ms)
- **Key finding:** `pos help <command>` is a pure exec-redirect — no per-command dispatcher surface exists; per brief, nothing invented

---

## Baseline

- Phase 1 state on disk; `make check` → `check-sync: OK`
- Maintainer's uncommitted fixes present (`ai-alias` added to `INTERACTIVE_CMDS` at bin/pos:262, DOC updates) — **untouched**
- BEFORE category-help captured for all 10 categories → `/tmp/pos-phase2/h-*-before.txt`

[DONE]

---

## Step 1: Migrate `_pos_category_help()`

**File:** `bin/pos`, `_pos_category_help()` (~lines 68–100 post-edit)

**Changes:**
- Registry sourced + `reg_scan "$self"` called **lazily inside the function** — plain dispatch paths never pay scan cost (verified: fast path 26 ms before and after)
- Tool list from `reg_tools_in "$cat"`, stripped of leading `$cat-` → identical short display names
- All sed header reads replaced by `reg_lookup "<cat>-<short>" desc|subcmds|deps`
- Nested-tool enrichment loop, `is_nested` skip, printf layout: **byte-for-byte preserved**

**Preservation proof (pre-headers):** diff of before/mid captures across all 10 categories → **zero differences**.

**New behavior (fires only when headers exist):** second indented line `    [deps: <deps>]` directly under a tool's description line.

[DONE]

---

## Step 2: Registry metadata in `pos help`

**Finding:** the `help` meta-command (bin/pos ~lines 233–245) joins args into `pos-<cat>-<cmd>` and `exec`s the tool's own `--help`. There is **no per-command rendering surface in the dispatcher** — examples/deps shown there come from each tool's `usage()` heredoc. Per the brief's instruction ("do NOT invent new UX"), this step is limited to that finding: no dispatcher-side extension made. The category-help surface (Step 1) is where registry metadata surfaces.

[DONE]

---

## Step 3: Representative headers on existing tools

Guards re-verified by reading source before annotating:

| Tool | Hard guards found | Headers added |
|------|-------------------|---------------|
| `bin/pos-network-download` (lines 10–12: `err` ×3) | aria2c, jq, curl | `# POS_DEPS:` + 3 real-subcommand EXAMPLES (add/status/watch) |
| `bin/pos-media-sync` (lines 15–16: `err` ×2) | lsblk, jq | `# POS_DEPS:` + 2 EXAMPLES (`--mp3`, `--mp4 --dry-run` — straight from its usage()) |
| `bin/pos-system-backup` (line 60 `err`; 72–73 `warn`; 179 conditional `err`) | tar | `# POS_DEPS: tar` only |
| `bin/pos-docker-ps` (line 16: single `err`) | docker | `# POS_DEPS: docker` |

**Decision note (system-backup):** lsblk/jq are warn-only soft guards ("USB copy skipped", returns 0); gpg errors only when encryption is requested (`--no-encrypt` bypasses). Deps header = hard requirements only → `tar`.

4 tools total (cap 5 respected). Placement rule followed: metadata headers in comment block, `# POS:` first, new headers after existing POS_* lines, before any code.

[DONE]

---

## Verification (per budget)

```
bash -n bin/pos                                    ✅
category --help before/mid diff (10 categories)    ✅ zero diff (Step 1 preservation)
category --help before/after diff                  ✅ only [deps: …] lines added:
                                                     network +1, docker +1, system +1, media +1; others 0
make gen && git diff --stat                        ✅ GEN changes confined to expected blocks
make check                                         ✅ check-sync: OK
make lint                                          ✅ 0 FAIL, 0 WARN
bin/pos-tree | grep deps                           ✅ 4 annotations visible
bin/pos network --help | grep -i deps              ✅ [deps: aria2c jq curl]
fast path timing                                   ✅ 26 ms (no reg_scan cost)
completions/pos.bash                               ✅ untouched by gen
```

**GEN block inspection (as instructed):**
- Tree gains `[deps: …]` annotation lines under annotated tools ✓
- Dispatch table flipped to 6-column format (`_has_deps_examples=1`) ✓
- Two rendering defects found & fixed in `gen-docs.sh` during inspection:
  1. Examples cell contained raw inner pipes from the `cmd | desc` grammar → broke markdown column count. Fixed: inner ` | ` rendered as `→` within cells.
  2. Intended `//` example joiner actually produced single `/` (`paste -d'//'` cycles chars). Fixed: awk-based literal `//` join.
- Resulting cell sample: `…| lsblk jq | pos media sync --mp3 → Sync only MP3 files to USB//pos media sync --mp4 --dry-run → Preview MP4 sync without copying |` — valid 6-column row, readable ✓
- Docmap line ranges shifted accordingly (auto-generated) ✓

---

## Artifacts Summary

### Modified this phase
| File | Change |
|------|--------|
| `bin/pos` | `_pos_category_help()` → registry API + lazy source + deps line (Maintainer's INTERACTIVE_CMDS line preserved verbatim) |
| `bin/pos-network-download` | DEPS + 3 EXAMPLES headers |
| `bin/pos-media-sync` | DEPS + 2 EXAMPLES headers |
| `bin/pos-system-backup` | DEPS header (hard dep only) |
| `bin/pos-docker-ps` | DEPS header |
| `scripts/gen-docs.sh` | Examples-cell pipe escaping (`→`) + correct `//` joiner |
| `DOC/AGENT_Context_Project.md` | Gen output only (tree annotations, 6-col dispatch, docmap shift, filetable line counts) |

### Not touched (constraint compliance)
`lib/config-ui.sh` ✅ · `completions/pos.bash` ✅ · `INTERACTIVE_CMDS` ✅ · Maintainer's fixes ✅ · `bin/pos-tree` rendering ✅ · no new files except report ✅

### Findings / deferred
- `reg_scan` ≈ 1.3 s on this box (≈250 process forks / 41 tools) — acceptable on lazy help-only paths; single-pass awk scan remains the anticipated future optimization (Phase 1 Risk 2)
- `pos help <command>` has no dispatcher-side surface to enrich (pure redirect)

---

## Review-fix round

Two findings from the Phase 2 adversarial review; both fixed minimally.

### Finding 1 (MEDIUM): stale hand-written table header above the dispatch GEN block — FIXED

**Exact lines removed** from `DOC/AGENT_Context_Project.md` (were lines 275–276):

```
| Category | Command | Script | Description |
|----------|---------|--------|-------------|
```

The orphaned 4-column header + its underline row sat between `### Available Commands` and `<!-- GEN:START dispatch -->`, duplicating the GEN block's own 6-column header. Nothing else removed — the section now reads `### Available Commands` → blank line → `GEN:START dispatch` directly.

### Finding 2 (LOW): `//` example joiner collides with URL slashes — FIXED

**New separator:** `" · "` (space-middle-dot-space), replacing the literal `//` in `scripts/gen-docs.sh` line ~48. Awk literal-join approach unchanged.

Rationale for `·`: cannot appear in a URL path, reads as a list separator in a markdown cell, and stays clear of both the pipe grammar (` | ` inside a single example, rendered as `→` in cells) and the em-dash used by `# POS:` descriptions. Live case now renders:
`pos network download add https://example.com/file.zip → Enqueue an HTTP download (auto-starts daemon) · pos network download status → Daemon health + global transfer stats · pos network download watch → Live progress view`
— the URL's `//` survives intact and each example is cleanly delimited.

### Verification

```
bash -n scripts/gen-docs.sh                        ✅
make gen && make gen → md5 of generated files identical
                                                   ✅ double-gen idempotence: ZERO drift after second run
grep -c 'Category.*Command' DOC/…Project.md        ✅ = 1 (only the GEN block's own header)
sed -n '/GEN:START dispatch/,+4p'                  ✅ GEN header is first row in block
lines above GEN:START dispatch                     ✅ only "### Available Commands" + blank
make check                                         ✅ check-sync: OK
make lint                                          ✅ 0 FAIL, 0 WARN
```

Note: the earlier bare `git diff --exit-code` after gen exits 1 because ALL Phase 1+2 work is still uncommitted vs HEAD — checksum comparison of run-1 vs run-2 outputs is the correct idempotence measure and passes.

### Constraint compliance

Touched ONLY `DOC/AGENT_Context_Project.md` (2 stale lines) and `scripts/gen-docs.sh` (separator string). No bin/*, lib/*, or completions/ changes. Everything else regenerated via `make gen`.

[DONE]

---

## Alias generator quoting fix

**File:** `bin/pos-ai-alias` (`_alias_regen()`, new `_alias_quote_cmd()` helper, `_alias_show()` command line)

### Chosen mechanism + rationale

`printf '%q'` — the canonical bash mechanism — applied **per layer**:

1. `_alias_quote_cmd <provider> <session> <prompt>` builds the pos-ai command with `%q`-quoted prompt → the prompt is ONE shell word on expansion.
2. `_alias_regen` then `%q`s the ENTIRE value before emitting `alias name=<value>` → the assignment survives any bytes.

**Justified deviation from the brief's literal snippet:** the prescribed single-`%q`-over-whole-string form expands to multi-word args after `--system`, but `bin/pos-ai`'s parser takes exactly one value (`SYSTEM_PROMPT="$2"; shift 2`, bin/pos-ai:640–642) — multi-word prompts would truncate to their first word with the remainder leaking into question positionals. The original code had the identical latent defect (single-quote fragments never survive alias-expansion re-parsing). Double-`%q` is the same single mechanism, applied once per quoting layer — no manual fragment concatenation, no mixing of approaches. Verified by exact round-trip (A4/A7).

### Diff summary

| Function | Change |
|----------|--------|
| `_alias_quote_cmd()` (new, ~10 lines) | Shared builder: `%q` prompt as one word; empty prompt → no `--system`; used by regen + show |
| `_alias_regen()` | Naive `'…'<escaped>'…'` concatenation replaced by helper + whole-value `%q`; collects names; keeps `bash -n "$tmp"`; ADDS semantic per-name check in fresh shell: `bash --norc -c 'shopt -s expand_aliases; source "$1" && [[ $(type -t "$2") == alias ]]' _ "$tmp" "$n"`; failure → warn(alias name) + keep previous + rc 1 (mirrors existing path). Note: `expand_aliases` required — non-interactive shells define aliases but `type -t` only reports them when expansion is on (found during self-test) |
| `_alias_show()` | Command line now rendered via `_alias_quote_cmd` (display-only; structure untouched) — what users copy pastes verbatim |

Unchanged per constraints: ENV_FILE format, `|` ban, name/session regexes, chmod/mv semantics, interactive flows.

### Harness (exact commands)

```bash
export CONFIG_DIR=/tmp/pos-alias-test
rm -rf "$CONFIG_DIR"; mkdir -p "$CONFIG_DIR"
cat > "$CONFIG_DIR/ai-aliases.env" <<'EOF'          # fixture as specified
# AI aliases — managed by pos ai alias (do not hand-edit)
assist|gemini|assist|You are assist, a concise and practical AI assistant.
evil|gemini|evil|It's a 'quoted' $(rm -rf /) `backtick` \backslash "dq" ;semi|pipe-less
plain|openrouter|plain|
EOF
# regen via function extraction (sanctioned approach):
bash -c 'source lib/common.sh
  ENV_FILE="$CONFIG_DIR/ai-aliases.env"; SH_FILE="$CONFIG_DIR/ai-aliases.sh"
  eval "$(awk "/^_alias_quote_cmd\(\)/,/^}/" bin/pos-ai-alias)"
  eval "$(awk "/^_alias_regen\(\)/,/^}/" bin/pos-ai-alias)"
  _alias_regen'
```

**Fixture nuance:** `evil`'s prompt contains `|`; the loader's `IFS='|' read … _rest` splits it off (pre-existing behavior — this is why prompts ban `|`). Round-trip asserts against the loader-stored string (`…;semi`), not the hand-edited tail.

### Assertion results

| # | Assert | Result |
|---|--------|--------|
| A1 | `bash --norc -c "source $SH"` → rc 0, **zero stderr** | ✅ |
| A2 | No execution while sourcing (`$CONFIG_DIR/pwned` absent) | ✅ |
| A3 | `type -t assist/evil/plain` == `alias` (fresh shell) | ✅ all three |
| A4 | evil expansion round-trip via `eval "set -- ${BASH_ALIASES[evil]}"` (no execution): post-`--system` words join to **exact original prompt**, delivered as one arg | ✅ byte-exact |
| A5 | `plain` emits no `--system` fragment | ✅ |
| A6 | Regen idempotence (second run md5-identical) | ✅ |
| A7 | `pos ai alias show evil` Command line, evaluated via `eval set -- $(cat …)`, yields exact prompt | ✅ byte-exact |

Also verified end-to-end: `bin/pos-ai-alias list`, `bin/pos ai alias show plain` (dispatcher path) behave normally.

### Gates

```
bash -n bin/pos-ai-alias   ✅ syntax OK (563 lines)
make gen                   ✅ (filetable row for pos-ai-alias updated automatically)
make check                 ✅ check-sync: OK
make lint                  ✅ 0 FAIL, 0 WARN
```

[DONE]