instar 1.3.983 → 1.3.985

package/upgrades/side-effects/misplaced-flag-sent-as-message-text.md

@@ -0,0 +1,193 @@
+# Side-Effects Review — a flag after the topic id was sent to the user as message text
+
+**Version / slug:** `misplaced-flag-sent-as-message-text`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `author-applied lenses — see Phase 5 (reduced independence, disclosed)`
+
+## Summary of the change
+
+`telegram-reply.sh` parses flags in a loop that BREAKS at the first non-flag argument —
+the topic id. Everything after that becomes the message via `MSG="$*"`. So
+`telegram-reply.sh 29723 --tone-ack B15 --tone-reason "why"` did two wrong things at once,
+both silently: it sent the literal text `--tone-ack B15 --tone-reason why` to the user, and
+the tone-advisory override never reached the server.
+
+**Measured, not hypothesised.** The pre-fix template is captured verbatim as a fixture
+(SHA `a2cf0215…`, the same SHA registered in the migrator's shipped-SHA allowlist) and the
+test suite runs it against a stub of `/telegram/reply/:topicId`: it returns exit 0, the
+received `text` contains `--tone-ack`, and `metadata.toneAdvisoryAck` is `undefined`.
+
+**The consequence was a corrupted measurement.** On 2026-07-26 the swallowed flags meant a
+tone-gate advisory was re-reviewed as an ordinary send whose text now began with option
+noise. The resulting verdict looked absurd, I read it as a malfunction, and graded a
+**correct** check `wrong` in the decision-quality data. That record is durable and is not
+retracted by this change — see §2.
+
+**The root cause is not the script.** The tone-reaction flags were documented NOWHERE
+agent-facing: not in the script's own usage header (which documents `--format` and
+`--stdin-base64`), not in the CLAUDE.md template. The template documents `metadata.*` — the
+HTTP shape — while simultaneously mandating "ALWAYS the relay script, never a hand-rolled
+curl". The bridge between the two did not exist, so the invocation had to be invented. The
+script then accepted the invention without complaint. A capability shipped without
+instructions, plus a tool silent on the only usage an uninstructed caller would try.
+
+Three parts, because it took three to close the chain: the guard (refuses), the script's
+usage header, and the CLAUDE.md template (documents the correct form).
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| `--*` argument after the topic id → refuse | `invariant` | Deterministic glob on an argument. No judgment, no model, no competing signals. Symmetric with the pre-existing `-*` refusal before the topic id. |
+| stdin path exempt | `invariant` | Structural, not a rule: `$#` is 0 when the message comes from stdin, so the loop has nothing to inspect. |
+| CLAUDE.md content-sniff marker | `invariant` | String presence test. |
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+An argument-form message whose own token is exactly `--something`. For example
+`telegram-reply.sh 29723 the flag --tone-ack means X` is now refused, where before it sent.
+
+This is deliberate and I think correct, but it is a real narrowing and worth stating
+plainly rather than waving away:
+
+- The refusal is **loud, immediate, and actionable** — it prints the corrected ordering and
+  names the escape hatch. The failure mode it replaces was silent and unrecoverable.
+- The escape hatch is **the documented primary path**: stdin (`cat <<'EOF' | …`). Every
+  multi-line message already uses it, and stdin is untouched by this check.
+- The alternative — matching only the eight known flag names — would have let a TYPO'd
+  flag (`--tone-akc`) through silently. That is the realistic mistake, and the whole point
+  is to stop flag-shaped tokens being swallowed. Matching the shape, not the list, is what
+  makes the guard useful rather than decorative.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **The false grade from 2026-07-26 is not retracted.** This stops the cause; it does not
+  undo the effect. Whether a mistaken grade can be corrected at all — and whether a
+  supersede erases the evidence the mistake was made, which would be the opposite defect —
+  is an open question deliberately NOT answered here. Recorded rather than quietly folded in.
+- **A single-token message that is exactly a flag, passed as an argument, is now refused
+  rather than sent.** Correct behaviour, but it is a refusal, not a rescue.
+- **Only this script is fixed.** `slack-reply.sh` and `whatsapp-reply.sh` share the
+  parse-then-break shape. They do not carry tone-reaction flags today, so the same mistake
+  has less to swallow — but the shape is the same. Named here rather than silently
+  extended: widening the change to two more shipped scripts, each needing its own
+  shipped-SHA registration, belongs in its own review.
+- **Documentation coverage generally.** This fixes one undocumented capability. Nothing
+  here establishes that others are documented.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes, and at three layers on purpose, because the defect had three links:
+
+1. **The script** — the only place a misplaced flag can be caught before it becomes text.
+2. **The script's usage header** — where someone reading the tool learns the ordering.
+3. **The CLAUDE.md template** — where the agent that is *mandated* to use the script learns
+   that these flags exist at all. Fixing only the script would have left the root cause
+   (undocumented capability) fully intact; the next agent would guess again, get a refusal
+   instead of a silent mis-send, and still not know the right form.
+
+Rejected: making the parser accept flags in either position. It looks friendlier and is
+worse — `MSG="$*"` means the parser cannot distinguish "a flag I should apply" from "a word
+of the message" without guessing, and a guess here silently rewrites what the user reads.
+Refusing is the only honest option.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+It holds blocking authority (the send is refused) on a deterministic glob over an
+argument — no model, no heuristic, no network, no threshold. It cannot drift or degrade,
+and it fails in the safe direction: it withholds a send rather than delivering a
+misleading one.
+
+It is also strictly *less* authority than it appears: it blocks nothing the caller cannot
+immediately re-issue correctly, and the message text itself is never inspected — only
+argument tokens.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No judgment point is introduced. The guard is a `case` glob. Notably it *removes* an
+implicit judgment: the old code silently decided that a flag-shaped token was message
+content, which is precisely the kind of unexamined call this standard exists to surface.
+
+## 5. Interactions
+
+- **stdin is structurally unaffected** — `$#` is 0 there, so the loop body never runs. This
+  is asserted by test, because "the primary path still works" is the claim most worth
+  checking.
+- **Correct-order invocations are unchanged** — asserted end-to-end: message body clean,
+  `metadata.toneAdvisoryAck` and `toneAdvisoryAckReason` both present.
+- **Pre-existing `Unknown flag` behaviour before the topic id is untouched** — asserted.
+- **Migration parity for the SCRIPT**: the pre-change SHA `a2cf0215…` is registered in
+  `TELEGRAM_REPLY_PRIOR_SHIPPED_SHAS`. Without that entry the SHA-history migrator leaves
+  the swallowing version in place with a `.new` beside it and every deployed agent keeps
+  mis-sending — the failure mode the entry above it in that list was added to prevent.
+- **Migration parity for the DOCS — the trap.** The tone-advisory CLAUDE.md block is
+  content-sniffed on `'Most checks are NUDGES you may override'`, a marker this change does
+  NOT alter. Appending guidance to that constant would therefore reach new installs ONLY;
+  every deployed agent short-circuits. Hence a second, independently-sniffed block. A test
+  simulates an agent that already carries the old section and proves it still receives the
+  new part — and I verified that test FAILS when the second block is disabled, so it cannot
+  become decorative.
+- **No route, config key, persisted state, or schema change.**
+
+## 6. External surfaces
+
+One user-visible change, and it is a removal of a bad one: a misplaced flag no longer
+appears in the user's chat as literal option text. Nothing else about delivery changes.
+
+## 6b. Operator-surface quality
+
+The refusal prints what was run, what the correct ordering is, and how to send the token
+literally if it really is message text. An error that only said "bad arguments" would have
+reproduced the original problem — a caller with no way to learn the right form — one level
+up.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Posture: `unified` by construction — no new state.** A shell-script argument guard plus
+two documentation blocks. No new field, file, route, or surface; nothing to replicate and
+no `machine-local-justification` marker applicable. The script is deployed per machine by
+the existing SHA-history migrator, which is the established path and unchanged here.
+
+## 8. Rollback cost
+
+Low and total: revert one commit. The guard disappears, the docs revert, and the
+shipped-SHA entry becomes a harmless extra allowlist member (never remove old SHAs — they
+remain valid migration sources). No data, no migration, no state to unwind.
+
+## Phase 5 — Second-pass review (independent reviewer subagent)
+
+**Disclosure, per Truthful Provenance:** no independent reviewer subagent was spawned — a
+standing instruction in this session prohibits it unless the operator requests it. The
+review lenses were applied by the author. That is **reduced independence**, recorded as
+such rather than presented as a concurring second pass.
+
+What author-applied review caught and changed:
+
+1. **The first version fixed only the script.** That would have left the actual root cause
+   untouched: the flags are documented nowhere, so the next agent guesses again — it would
+   just get a refusal instead of a silent mis-send. Verified the absence repo-wide before
+   claiming it (the flags appear only in the script itself, an old upgrade guide, and the
+   migrator). Docs are now part of the change, not a follow-up.
+2. **The CLAUDE.md content-sniff trap was nearly walked into.** Appending to the existing
+   constant looked sufficient and would have shipped a doc fix that reached new installs
+   only — the exact "works for new agents only" shape the Migration Parity Standard names as
+   a broken feature. Caught by asking who actually *receives* the edit.
+3. **The guard was nearly scoped to the eight known flag names**, which reads as more
+   precise and is weaker: a typo'd flag — the realistic mistake — would still be swallowed
+   silently. Widened to the shape, with the over-block cost stated in §1 rather than hidden.
+4. **The negative case was run, not assumed.** I disabled the second migration block and
+   confirmed the load-bearing test fails, because a migration-parity test that passes
+   whether or not the migration exists is worse than none.
+5. **The sibling scripts were checked and deliberately left alone** (§2) rather than swept
+   in for tidiness — each needs its own shipped-SHA registration and review.

package/upgrades/side-effects/raw-nul-bytes-hide-source-from-grep.md

@@ -0,0 +1,199 @@
+# Side-Effects Review — a raw NUL byte made 30 source files invisible to grep
+
+**Version / slug:** `raw-nul-bytes-hide-source-from-grep`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `author-applied lenses — see Phase 5 (reduced independence, disclosed)`
+
+## Summary of the change
+
+`grep` classifies a file as binary if it contains a NUL (0x00) byte, and on a binary
+file it emits **nothing** — not a match, not a `Binary file X matches` line, not even a
+`0` under `-c`. Thirty tracked text files each contained one or more raw NUL bytes, so
+every grep-based audit over `src/` silently skipped them and the empty result read as
+"absent".
+
+The bytes were never corruption. Each was a deliberate composite-key or hash separator
+written as a literal byte instead of the six-character escape:
+
+```ts
+const key = `${row.model}<literal 0x00>${row.framework}`;   // now: \u0000
+```
+
+The delimiter choice is correct — NUL cannot occur inside a model or framework name, so
+it is collision-proof. Writing it raw is the whole defect.
+
+**Measured:** 30 tracked files (22 under `src/`, 7 tests, 1 spec doc). Affected modules
+include `blockerSettleAuthority.ts` (the true-blocker settle gate), `SessionOwnership.ts`,
+`GreenPrAutoMerger.ts`, `PermissionPromptAutoResolver.ts` (an always-on safety floor),
+all three `ExternalHog*` modules, and `StandardsEnforcementAuditor.ts` — the module that
+audits whether standards carry structural guards was itself invisible to the standard
+search instrument.
+
+**Second consequence, worse in kind:** git applies the same rule but only sniffs the
+first 8000 bytes. For the **11 files** whose NUL fell inside that window, `git diff`
+rendered `Bin 5407 -> 5412 bytes` instead of a line diff — so pull requests touching
+safety-critical authority code were reviewed **without the reviewer being shown the
+changed lines**. For the other 19, git saw text while grep did not: the two instruments
+disagreed, which is precisely why this survived so long.
+
+Every raw byte is replaced with `\u0000` (identical runtime string; valid and unambiguous
+in string, template and regex contexts — unlike `\0`, a legacy octal escape when followed
+by a digit), and a new ratchet fails the build if one ever returns.
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| `containsRawNul(file)` | `invariant` | A byte is present or it is not. No judgment, no model, no competing signals. |
+| lint scope (extension allowlist) | `invariant` | Deterministic set of text-by-definition extensions. Binary fixtures are out of scope by construction, not by heuristic. |
+| control bytes other than 0x00 | `invariant` (deliberate exclusion) | Empirically verified not to cause grep-skip; see §2. |
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The lint rejects a raw 0x00 byte in a file with a text extension. There is **no
+legitimate case it blocks**, because there is no case that needs one: any runtime NUL a
+program wants is expressible as an escape, with an identical result. The lint therefore
+carries no exemption list — an exemption would only ever be used to reinstate the defect.
+
+The nearest real cost: a genuinely binary fixture that someone gives a `.json`/`.md`
+extension would be refused. That is a naming error the lint is right to surface, and no
+such file exists in the tree today (verified by the sweep).
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Other raw control bytes remain.** ESC (0x1b), BEL (0x07), 0x1f and 0x7f appear in a
+  handful of hostile-input test fixtures (`RevertDetector.ts`, `liveOutputStream.ts`,
+  `process-health-render.test.ts`, and others). These are **deliberately not covered**:
+  I verified empirically that a file containing ESC/BEL is still `ASCII text` to `file`
+  and still fully searchable by `grep` — only 0x00 triggers the skip. Escaping them would
+  be cosmetic. A lint should enforce exactly the failure it is named for. Recorded rather
+  than silently widened. (A separate concern does exist — a raw ESC in a file that gets
+  `cat`'d is a terminal-escape vector — but that is a different defect with a different
+  argument, and folding it in here would smuggle it past review.)
+- **Untracked and generated files are not scanned.** The lint walks `src`, `tests`,
+  `docs`, `scripts`, `.github`. Build output is excluded on purpose (it is regenerated
+  from the now-clean sources).
+- **This fixes one silent instrument, not the class.** Other tools can also fail
+  closed-mouthed. Nothing here establishes that no others remain — see §5.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes, and at two layers deliberately:
+
+1. **The data** — the bytes themselves are corrected at source, which is the only place
+   the fix can be complete. A tooling workaround (`grep -a` everywhere, a `.gitattributes`
+   override) would have left the files hostile to every *other* consumer, including
+   editors, reviewers, and any future agent's search.
+2. **The guard** — a repo-level test, matching the existing tree-scanning ratchets
+   (`no-empty-catch-blocks`, `no-silent-fallbacks`). It reads bytes with `readFileSync`
+   rather than shelling out to a search tool, so the lint cannot be blinded by the very
+   defect it detects.
+
+Notably a `.gitattributes` `*.ts text` entry was considered and **rejected**: it would
+have fixed git's rendering while leaving `grep` — the instrument that actually failed —
+just as blind, and would have converted a visible defect into a hidden one.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+It holds blocking authority (a failing test blocks a merge) on **maximally non-brittle**
+logic: the presence of one specific byte in a file. There is no model, no heuristic, no
+threshold, no parse. It cannot drift, cannot be rate-limited, and produces the same
+verdict on every machine.
+
+This is the correct place for hard authority — a deterministic, universally-checkable
+fact — and precisely the shape the standard reserves it for.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No judgment point is introduced. Every decision in the lint is a byte comparison or a
+set membership test. Nothing consults an LLM; nothing weighs competing signals.
+
+## 5. Interactions
+
+- **Runtime behaviour is unchanged.** `\u0000` denotes exactly the byte it replaces. The
+  lint asserts this explicitly (`JSON.parse` of the escape text `=== String.fromCharCode(0)`)
+  rather than leaving it as a claim in prose.
+- **Persisted data is unaffected.** Several sites feed these separators into hashes
+  (`relayContentDedup`, `blockerSettleAuthority`, `UnionReader`, `ExternalHogArmMarker`).
+  Because the string is identical, every hash is identical — **no migration, no cache
+  invalidation, no re-keying**. This was the primary risk and it is checked, not assumed.
+- **`git diff` becomes readable** for the 11 previously-binary files. A one-time
+  consequence: this PR shows them as `Bin` on the *old* side.
+- **The empty-catch ratchet** scans `src/` as text via `readFileSync`, so it was NOT
+  blinded — verified before assuming a shared failure. Grep-based *ad hoc* audits were the
+  affected consumers, not the file-reading lints.
+- **This session's own reasoning was affected.** A search for a retraction mechanism
+  across `src/` returned one unrelated subsystem, and I was one step from recording
+  "no such path exists" as a finding. That search had skipped 22 source files. The
+  correction is recorded in the run log rather than quietly dropped: **the finding I was
+  about to publish was manufactured by the defect this PR fixes.**
+
+## 6. External surfaces
+
+None. No route, no config key, no persisted state, no user-visible behaviour. This is a
+source-text and build-time change only.
+
+## 6b. Operator-surface quality
+
+Nothing reaches the operator. The one surface is the failing-test message, which names
+each offending file, states the consequence in plain terms ("INVISIBLE to grep — every
+grep-based audit silently skips them and reports 'not found'"), and gives the exact fix.
+A lint that only says "assertion failed" would have re-created the original problem at
+the level of the guard.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Posture: `unified` by construction — no state at all.** This change introduces no
+feature, no field, no file, no surface. It edits source text and adds a build-time check
+that runs identically wherever the repo is checked out. No replication path is required
+and no `machine-local-justification` marker applies, because there is nothing machine-local
+to justify.
+
+## 8. Rollback cost
+
+Trivial and total: one commit, 30 files, 33 single-line substitutions plus one new test
+file. Reverting restores the raw bytes — and with them the grep-invisibility of 22 source
+modules and the binary diffs on 11. There is no data to migrate back and no state to
+unwind.
+
+## Phase 5 — Second-pass review (independent reviewer subagent)
+
+**Disclosure, per Truthful Provenance:** no independent reviewer subagent was spawned — a
+standing instruction in this session prohibits it unless the operator requests it. The
+review lenses were applied by the author. That is **reduced independence**, recorded as
+such rather than presented as a concurring second pass.
+
+What author-applied review caught and changed:
+
+1. **The first draft of this very lint shipped five raw NUL bytes and hid itself from
+   grep.** I typed the escape inline; it was normalised into actual NUL bytes on write.
+   Caught only because I byte-checked the file I had just written instead of trusting it.
+   The lint now constructs both the raw byte and the escape *text* from char codes and
+   never types the escape inline — and the authoring hazard is documented in its header,
+   because the next author will hit exactly the same trap.
+2. **The scope was nearly widened to all control bytes** for tidiness. I tested the
+   assumption instead and found ESC/BEL do not cause the skip — so widening would have
+   added churn and noise while claiming safety it does not provide. Narrowed back, with
+   the empirical result recorded in §2.
+3. **A "scan is not silently empty" assertion was added.** Without it, a scan that walked
+   the wrong roots would find zero offenders and pass forever — the same absence-reads-as-
+   presence failure, reincarnated inside its own guard. The lint now asserts it examined
+   >500 files.
+4. **The hash-stability question was checked, not assumed.** Four sites feed these
+   separators into digests; had the substitution altered the string, persisted dedup keys
+   and arm markers would have silently changed meaning. Verified identical before
+   committing.
+5. **`.gitattributes` was rejected as the fix** (see §3) because it would have repaired
+   the *visible* symptom (git diffs) while leaving the *silent* one (grep) intact —
+   trading a detectable failure for an undetectable one.