Linux_post_install/AgentsReport/reviewer/2026-08-25-reviewer-r5-chain.md

Reviewer — R5 Chain Adversarial Review

Date: 2026-08-25 Reviewed work: Four consecutive Builder passes (R5, R5b, R5c, R5d) on bin/pos-ai-gemini and docs Approved scope: tmp_request.md R5 — terse prompt + markdown rendering, --last + default session, answer separation + staleness transparency, machine context

---

TL;DR

Status: ACCEPT_WITH_NOTES

• 21 checklist items assessed: 18 PASS, 1 FAIL (duplicate line in ai.md doc), 1 WARN (chat REPL extra whitespace — cosmetic), 1 NOT-APPLICABLE (chat subcommands that never existed)
• 1 BLOCKING finding: duplicate line in DOC/howto/ai.md (lines 135–138)
• 0 regressions detected in non-tty output path or pre-R5 behavior
• 0 scope creep into share-lib, menu-lib, cmd_unmount, or Telegram bridge
• 3 unverified items (require make gen, bash -n, runtime testing — sandbox blocked)

---

Step 1: Scope compliance

Files in R5 scope (per approved scope):

• bin/pos-ai-gemini — ✅ Changed, 311→565 lines
• DOC/howto/ai.md — ✅ Changed
• DOC/POS.md — ✅ Changed (ai section updated)
• completions/pos.bash — ✅ Changed (GEN: block, --full --last added)
• DOC/AGENT_Context_Project.md — ✅ Changed (line-count resync only)

Out-of-scope files also modified in working tree (from concurrent work, NOT caused by R5):

• bin/pos-docker-vbox, bin/pos-share-nfs-client, bin/pos-share-smb-client — R1/R3/R6 work
• lib/common.sh — R4 confirm convention
• DOC/DEV.md, DOC/howto/docker.md, DOC/howto/share.md — doc sync for R3/R4/R6

These are concurrent uncommitted changes, not scope creep by R5.

Verdict	PASS
Rationale	All R5-scope files are modified; no R5-authored changes found in out-of-scope files

---

Step 2: Default system prompt (R5)

Check	Verdict	Evidence
Terse clause present	PASS	Line 23: "Be extremely terse: lead with the exact command(s) to run; one-line explanations max; no greetings, no closing offers, no essays."
Troubleshooting clause present	PASS	Line 23: "diagnose it from that and lead with the fix command(s)."
Machine context appended dynamically	PASS	cmd_ask lines 411–414: mc="$(machine_context)"; [ -n "$mc" ] && mc=" $mc"; system="$DEFAULT_SYSTEM_PROMPT$mc"

---

Step 3: --system replaces wholesale

Verdict	PASS
Evidence	Lines 410–415: system="$SYSTEM_PROMPT" then if [ -z "$system" ] && [ "$FULL_MODE" -eq 0 ]; then .... When --system sets SYSTEM_PROMPT, the condition [ -z "$system" ] is false → built-in prompt + machine context are never assembled.

---

Step 4: --full drops built-in

Verdict	PASS
Evidence	Line 411: if [ -z "$system" ] && [ "$FULL_MODE" -eq 0 ]. With FULL_MODE=1, the entire block is skipped → system stays as SYSTEM_PROMPT which defaults to "". No built-in or machine context injected.

---

Step 5: --last resolves + injects + announces

Verdict	PASS
Evidence	newest_pos_log() (lines 131–138) finds newest non-pos.log, verifies non-empty. cmd_ask (lines 398–403): calls last_log_annotate for stderr info, last_log_context for the tail, appends [last command output:] block. last_log_annotate (lines 171–185): prints [i] attaching last pos output — <basename> (<age>) + preview line to stderr.

---

Step 6: Staleness >60min warning

Verdict	PASS
Evidence	Line 182: if [ "$age_s" -gt "$LAST_LOG_STALE_SECS" ] (LAST_LOG_SECS=3600). Prints [!] that log is %s old and may not match your current problem... to stderr with pipe-fresh hint.

---

Step 7: Session "default" persists

Verdict	PASS
Evidence	Line 16: SESSION="default" (was SESSION="" in baseline). session_load() / session_save() no longer gated on [ -n "$SESSION" ] in ask/chat — always writes to default.json.

---

Step 8: --session overrides default

Verdict	PASS
Evidence	Flag parser lines 534–535: --session) SESSION="$2"; shift 2. Overrides the default before any session operation.

---

Step 9: Tty answer separation

Verdict	PASS
Evidence	render_markdown tty path (line 318): printf '\n%s\n' "$rendered" — exactly one leading blank line + content + one trailing newline. Non-tty path (lines 262–264): printf '%s\n' "$text" — raw bytes, zero added newlines.

---

Step 10: Markdown renderer coverage

Verdict	PASS
Evidence	Fenced blocks: line 280 toggle + line 281 dimmed indent. Inline code: lines 291–295 → yellow. Bold **…**: lines 298–302. Bold __…__: lines 305–309. Headers #{1,4}: lines 282–285 → bold cyan, # stripped. HR ---/***___: line 287 → thin rule. List markers: no-op (passed through as-is, which is correct). glow: lines 313–314, command -v glow >/dev/null 2>&1 — opportunistic.

---

Step 11: Machine context fallback chain

Verdict	PASS
Evidence	machine_context() lines 337–386: hostnamectl first (lines 340–356), os-release fallback for distro (lines 359–368), uname fallback for kernel+arch (lines 370–371). [ -n "$out" ] || return 0 on line 384 — clause omitted when all fail. mc_clean() strips ANSI, control chars, collapses whitespace.

---

Step 12: Non-tty stdout byte-identical

Verdict	PASS
Evidence	Old baseline cmd_ask: printf '%s\n' "$out". New cmd_ask: render_markdown "$out" where non-tty path is printf '%s\n' "$text". Byte-equivalent output format. The system prompt change affects what the model generates but not the print format — opt-in behavioral change within scope.

---

Step 13: Chat REPL commands intact

Verdict	NOT-APPLICABLE
Rationale	Checklist references /history, /export, /help — these never existed in either baseline or current code. Old code only had /reset and q/Q/quit/exit. Current code preserves both exactly (lines 441–446). No regression.

---

Step 14: Telegram listener bridge untouched

Verdict	PASS
Evidence	git diff --name-only shows no changes to communication listener/sender files. Telegram bridge calls pos ai gemini ask — the non-tty stdout path is byte-identical (check 12).

---

Step 15: Pipe stdin still works

Verdict	PASS
Evidence	Lines 392–394: elif [ ! -t 0 ]; then prompt="$(cat)". Identical to baseline.

---

Step 16: POS_FLAGS complete

Verdict	PASS
Evidence	Line 5: # POS_FLAGS: --model --session --system --full --last. All five flags from checklist present. Completions line 6 matches: _pos_flags[ai-gemini]="--model --session --system --full --last".

---

Step 17: make gen idempotency

Verdict	UNVERIFIED
Rationale	Cannot run make gen in sandbox. Static evidence: completions posflags block (line 6) matches POS_FLAGS header; filetable row updated to 565 lines (confirmed by wc -l). The docker-vbox, nfs-client, smb-client, and completions line-count rows in the GEN block reflect concurrent work, not R5 drift. Strong inference: gen output would be byte-identical, but UNVERIFIED without running it.

---

Step 18: glow deps guard

Verdict	PASS
Evidence	Line 313: if command -v glow >/dev/null 2>&1 — standard pattern, never errors when absent, falls back to awk renderer. No other reference to glow in the file.

---

Step 19: Lint convention compliance

Verdict	PASS
Evidence	Shebang: line 1 #!/usr/bin/env bash. Strict mode: line 2 set -euo pipefail. Help dispatch: line 529 -h|--help) usage ;; in flag parse loop (before subcommand dispatch). No new external deps required (glow is optional).

---

Step 20: --last scoped to ask

Verdict	PASS
Evidence	Lines 554–556: if [ "$LAST_MODE" -eq 1 ] && [ "${cmd:-}" != "ask" ]; then err "--last only applies to 'pos ai gemini ask'". Hard error for any other subcommand.

---

Step 21: Error→stderr, answer→stdout

Verdict	PASS
Evidence	err() from common.sh → stderr. warn() at line 450 → stderr. gemini_generate error echo at line 246 → >&2. last_log_annotate all output → >&2. render_markdown → stdout. API errors → stderr + exit 1.

---

Findings

Finding 1 — Duplicate line in DOC/howto/ai.md

• Severity: REQUIRED
• Evidence: Lines 135–138 in DOC/howto/ai.md:

  - On a non-2xx response the API's `error.message` is shown and the exit code is
    non-zero — so scripts can rely on `ask` failing loudly.
  - On a non-2xx response the API's `error.message` is shown and the exit code is
    non-zero — so scripts can rely on `ask` failing loudly.
  

  The diff confirms: the new line was appended but the old identical line was not removed.
• Relevant files/lines: DOC/howto/ai.md:135-138
• Approved scope reference: R5 doc updates to ai.md
• Why it matters: Duplicate text is a doc bug — readers see the same bullet twice. Trivial to fix (delete one).

Finding 2 — Chat REPL uses raw SYSTEM_PROMPT (no built-in default)

• Severity: NOTE
• Evidence: cmd_chat line 449: gemini_generate "$model" "$contents" "$SYSTEM_PROMPT" — passes the raw SYSTEM_PROMPT var. When no --system is given, this is "" (empty), meaning chat gets NO system instruction — not even the terse prompt. This is consistent with the scope ("chat keeps its neutral behavior, only --system applies") and with ai.md line 39: "chat keeps its neutral behavior (only --system applies)."
• Why it matters: Not a defect — explicitly documented behavior. But worth noting that chat and ask have asymmetric prompt treatment.

Finding 3 — Chat REPL extra leading whitespace on tty

• Severity: SUGGESTED
• Evidence: cmd_chat lines 458–460: printf '\n'; render_markdown "$answer"; printf '\n\n'. On a tty, render_markdown emits \n<rendered>\n, so total after > prompt close is: \n (from printf) + \n (render_markdown leading) + content + \n (render_markdown trailing) + \n\n (printf). This produces 2 leading blank lines and 3 trailing blank lines — more visual whitespace than the baseline's printf '\n%s\n\n'.
• Why it matters: Cosmetic. The extra separation is arguably better for interactive readability. Non-blocking.

---

Verification verified

1. ✅ Default system prompt has terse + troubleshooting clauses (line 23)
2. ✅ Machine context function implements hostnamectl → os-release → uname fallback chain (lines 337–386)
3. ✅ --system prevents built-in assembly (line 411 condition)
4. ✅ --full prevents built-in assembly (line 411 FULL_MODE check)
5. ✅ --last injects [last command output:] block (lines 398–403)
6. ✅ --last announces to stderr with basename + age + preview (lines 171–185)
7. ✅ Staleness warning at >60min (line 182, LAST_LOG_SECS=3600)
8. ✅ Session default persists (SESSION="default", no conditional on load/save)
9. ✅ Tty rendering: glow opportunistic + awk fallback, non-tty raw (lines 260–318)
10. ✅ POS_FLAGS header has all 5 flags (line 5)
11. ✅ Completions match POS_FLAGS (line 6)
12. ✅ Filetable line count accurate (565 matches wc -l)
13. ✅ --last scoped to ask only (lines 554–556)
14. ✅ Errors to stderr throughout
15. ✅ Pipe stdin preserved (lines 392–394)
16. ✅ Telegram bridge path untouched (no file changes)
17. ✅ Conventions: shebang, strict mode, help dispatch order

Verification unverified

1. make gen byte-idempotency (sandbox cannot execute make)
2. bash -n syntax check (sandbox cannot execute bash on non-git commands)
3. Runtime test: --last with actual dispatcher logs, staleness warning timing, glow rendering

---

Scope compliance

• In-scope confirmed: All R5/R5b/R5c/R5d features implemented in bin/pos-ai-gemini + docs
• Out-of-scope found: None authored by R5. Working tree contains concurrent changes from R1/R3/R4/R6 work (separate feature branches mixed into working tree before commit)
• No regressions: Non-tty output byte-equivalent, chat REPL preserved, stdin pipe preserved, Telegram bridge untouched

---

Remaining uncertainty

1. Whether make gen output is byte-identical to committed GEN blocks — strong inference says yes (flag set matches header, line counts match), but unverified.
2. Whether the awk markdown renderer handles all edge cases at runtime (nested bold inside code blocks, unclosed fences, etc.) — static review shows correct structure but edge-case behavior is runtime-only.

---

Recommended next agent

Builder

Reason: One REQUIRED finding (duplicate doc line in DOC/howto/ai.md) is a trivial fix within approved scope — delete lines 137–138. The builder can resolve this and then the chain is ready for commit.

---

Changes made by Reviewer

None — read-only review.