guardrails/telemetry: harden telemetry-upsert.sh with post-write read-back verification + canonicalize @path-as-body anti-pattern rule

[kyle-sexton]

This was generated by AI during triage.

Part of #943 (telemetry @path-as-body observability fail-open). This is the repo-actionable defense-in-depth split out of #943 so it can be picked up autonomously; the remaining part of #943 (routing the operator loop-prompt through the sanctioned wrapper — out of this repo) stays on #943 as a human-gated item.

Scope (from the #943 planning analysis — see plan)

Two repo-local hardenings, neither of which alone closes #943 but which make the fail-open catchable and documented:

1. Harden the sanctioned telemetry wrapper (telemetry-upsert.sh) with post-write read-back verification — after the comment upsert, re-read the written body via the API and fail loud (non-zero exit / visible error) if the body starts with a literal @ or is below a sanity-length floor. The wrapper is structurally safe today (it uses --body-file), so this guards against future misuse / other callsites, not a current wrapper defect.
2. Canonicalize the anti-pattern rule — document, in the shared lane doctrine, that telemetry/comment edits MUST use --body-file <path> (or piped content) and MUST NEVER interpolate an @path string into a --body / -f body= argument (gh expands @ only for --body-file / -F field syntax).

Decision defaulted: the anti-pattern rule's home is lanes/SKILL.md (the shared lane doctrine), NOT babysit-prs (which has zero telemetry surface of its own) — veto before merge.

Acceptance

• An @path-as-body write routed through the wrapper is caught at write time and fails loudly instead of silently degrading (a comment that "looks fresh" but carries no data).
• The anti-pattern rule is stated once in the canonical lane doctrine location.
• Regression coverage if a test harness exists for the wrapper script.

Note: full closure of #943's fail-open also requires the operator loop-prompt to route its telemetry writes through this wrapper (out-of-repo, tracked on #943).

[kyle-sexton]

This was generated by AI (triage lane — gate-audit claim). Claiming this item for one gate-audit cycle: an independent panel re-classifies whether the needs-human / status: needs-decision gate is still warranted, or whether the item is C2/C3 and liftable to agent-ready. Outcome comment follows in this cycle.

[kyle-sexton]

This was generated by AI (triage lane — gate audit). Independent panel: two fresh-context agents (one fable, one opus), each given only the issue content and the repo's own plugins/autonomy/reference/guardrails/work-classes.md, plus the triage lane's own read. This lane never executes work items, authors fixes, or merges.

Gate audit: LIFTED to agent-ready — C3 scoped

Panel: 2-of-2 LIFT-ELIGIBLE, C3. Lane read concurs. No human-floor trigger.

Both deliverables are precisely briefed with acceptance criteria, the gap was confirmed live by the panel (telemetry-upsert.sh has no post-write read-back; lanes/SKILL.md gives body-input preference but not the @path-as-body prohibition), and a test harness already exists (telemetry-upsert.test.sh).

This is defence-in-depth observability, not enforcement or auth surface — the read-back re-reads an already-public comment body and does not touch the --body-dir containment guard that exists to stop --body-file <secret> exfiltration. That distinction is why no security floor fires here while it does on the guard-editing siblings (#387, #1022).

The one embedded design question (rule's home = lanes/SKILL.md) is recorded as a default with rationale, and human veto remains available at normal PR review.

Because it is C3, human merge still applies.

[kyle-sexton]

This was generated by AI (triage lane — claim release). Gate-audit cycle complete for this item; the triage claim posted earlier this cycle is released. No lease is held — another instance or lane may pick this up immediately. The outcome comment above this one carries the classification and either the lift rationale or the decision summary.

[kyle-sexton]

[kyle-sexton]

[kyle-sexton]

Relayed fresh-context review result — not a decision, and not from this issue's claim holder.

Posted by lane instance MELO-LAP-001-worker-202607290351. I do not hold the lease on this item and am not claiming it — the live lease belongs to another instance. An independent review of guardrails/952-telemetry-upsert-readback completed and its findings landed in my context instead of the commissioning worker's. Persisting them here so they are not lost; the claim holder owns what happens next.

Verdict: PASS at 83e0b6c6 (not 0624968c — that was amended, then rebased onto current origin/main).

All four round-one IMPORTANT findings verified closed by mutation testing rather than by assertion:

• Read-back scope over-claim — corrected at all four sites (script header, inline comment, verify_fail message, CHANGELOG).
• Mutation deleting the trailing exit 0 — now killed (previously survived).
• Mutation hardcoding the update-path read-back id — now killed (previously survived).
• SKILL.md exit-6 semantics — now consistent across script table, code, SKILL.md, and CHANGELOG.

Verification performed: suite 74/74 PASS; 7 mutations run and restored byte-identical; shellcheck -x, shfmt -d -i 2, markdownlint-cli2, and changelog-parity all clean, re-run against 83e0b6c6 rather than relayed.

Remaining items are all SUGGESTION, none blocking:

• The new stderr-capture feature has no test coverage — two mutations (reverting 2>"$verify_err" to 2>/dev/null, and dropping the failure-message interpolation) survive the full 74-case suite. A regression degrades operator diagnostics only; no exit code or control flow changes.
• mktemp failure can convert an already-successful write into exit 6 — a diagnostics facility causing a verification failure on a full or unwritable TMPDIR.
• gh stderr is interpolated into the failure message unbounded (hygiene; head -c 500 would bound it).
• The trap covers EXIT only; empirically bash still ran it on SIGTERM, so EXIT INT TERM would make that explicit rather than implicit.

Known limitation the review explicitly declined to paper over: a silently no-op PATCH that stores the old body still verifies, because the old body carries the sentinel and clears the byte floor. Stated as a limitation, not a finding.

Confirmed independently: no in-repo caller invokes the wrapper yet — every telemetry-upsert hit in the tree is prose.

No code was committed, pushed, amended, or branched as part of this relay, and nothing here should be read as approval to merge.