instar 1.3.984 → 1.3.985

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.984",
+  "version": "1.3.985",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-26T08:47:20.129Z",
-  "instarVersion": "1.3.984",
+  "generatedAt": "2026-07-26T17:59:55.648Z",
+  "instarVersion": "1.3.985",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1242,7 +1242,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/telegram-reply.sh",
-      "contentHash": "a2cf02154a6023725f15480a575f54a5231278c70396cd12051b7d7055b72d98",
+      "contentHash": "4464581188f5c736a62edac5e6a2edecfcfcd365557a18e514b741731bed6e0b",
       "since": "2025-01-01"
     },
     "template:whatsapp-reply.sh": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "0c703f879feac72668890b6db759ed3da3ecd33035f1d2896ccbf7e1ac59c7b5",
+      "contentHash": "59f279be8e27e1d3f4a19c810f39645b9d63dacfbba3b1cc800a4ffeec67d57d",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/scripts/telegram-reply.sh

@@ -4,6 +4,12 @@
 # Usage:
 #   ./telegram-reply.sh TOPIC_ID "message text"
 #   ./telegram-reply.sh --format markdown TOPIC_ID "**bold**"
+#
+#   EVERY FLAG GOES BEFORE THE TOPIC ID. Flag parsing stops at the topic id, so
+#   anything after it is message text. A flag in the wrong position used to be
+#   sent to the user as literal text with its effect silently dropped; it is now
+#   refused. Correct:
+#     ./telegram-reply.sh --tone-ack B2_FILE_PATH --tone-reason "why" TOPIC_ID "msg"
 #   echo "message text" | ./telegram-reply.sh TOPIC_ID
 #   cat <<'EOF' | ./telegram-reply.sh TOPIC_ID
 #   Multi-line message here
@@ -25,6 +31,24 @@
 #                     a blanket pre-ack that silently disables the inform
 #                     layer; spec outbound-jargon-filepath-gap §2.4(4)).
 #
+#   Tone-gate advisory reactions (answering a 422 `tone-gate-advisory`). BOTH
+#   forms are recorded as evidence that tunes the gate; neither is optional
+#   once you have been handed a decisionRef.
+#   --tone-complied <RULE>     You agreed with the nudge and revised the text.
+#                              Grades the check `right`.
+#   --tone-ack <RULE>          You disagree and are sending unchanged. Grades
+#                              the check `wrong`. REQUIRES --tone-reason: a
+#                              reasonless ack is refused and nothing sends,
+#                              because that reason IS the tuning evidence.
+#   --tone-reason "<why>"      Why the nudge is wrong in this case.
+#   --tone-decision-ref <REF>  The decisionRef from the 422, so the reaction
+#                              joins the verdict it answers.
+#
+#   Example (note the ordering — flags first, topic id last):
+#     ./telegram-reply.sh --tone-ack B2_FILE_PATH \
+#       --tone-reason "the operator asked for the path explicitly" \
+#       --tone-decision-ref DQ-1234 29723 "the message"
+#
 # Outbound advisory preflight (inform-only — spec outbound-jargon-filepath-gap §2.4):
 #   When this send comes from an automated LLM job session (the scheduler
 #   stamps INSTAR_MESSAGE_KIND=automated + INSTAR_SENDER_CLASS=llm-session
@@ -133,6 +157,43 @@ if [ -z "$TOPIC_ID" ]; then
   exit 1
 fi
 
+# A flag placed AFTER the topic id was silently swallowed into the message.
+#
+# The parse loop above stops at the first non-flag argument (the topic id), so
+# everything from there on becomes message text via `MSG="$*"` below. A
+# misplaced `--tone-ack` was therefore SENT TO THE USER as visible message body
+# while the override it was meant to carry never reached the server — and,
+# because the flags never applied, the tone gate re-reviewed the send and its
+# verdict was then misread as absurd. That is how a CORRECT check came to be
+# graded `wrong` in the decision-quality data on 2026-07-26. The record is
+# durable; the cause was two characters of argument order.
+#
+# The asymmetry is the defect: a flag-shaped token BEFORE the topic id is fatal
+# ("Unknown flag", above), but after it the script was maximally permissive.
+# Refuse flag-shaped tokens in both positions. This also catches a TYPO'd flag
+# (`--tone-akc`), which is the realistic case and was equally silent.
+#
+# Deliberately strict: any `--*` argument. A message that genuinely needs such a
+# token as literal text goes through stdin, which is the documented primary path
+# and is unaffected by this check ($# is 0 there).
+for _arg in "$@"; do
+  case "$_arg" in
+    --*)
+      echo "Refused: '$_arg' appears AFTER the topic id." >&2
+      echo "" >&2
+      echo "Flags are only parsed BEFORE the topic id. Placed here it would have been" >&2
+      echo "sent to the user as literal message text, and its effect silently dropped." >&2
+      echo "" >&2
+      echo "  Correct:  telegram-reply.sh --tone-ack RULE --tone-reason \"why\" $TOPIC_ID \"message\"" >&2
+      echo "  You ran:  telegram-reply.sh $TOPIC_ID ... $_arg ..." >&2
+      echo "" >&2
+      echo "If '$_arg' is genuinely part of the message text, pipe the message on stdin:" >&2
+      echo "  cat <<'EOF' | telegram-reply.sh $TOPIC_ID" >&2
+      exit 1
+      ;;
+  esac
+done
+
 # Read message from args or stdin
 if [ $# -gt 0 ]; then
   MSG="$*"

package/upgrades/1.3.985.md

@@ -0,0 +1,109 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**A flag placed after the topic id was sent to the user as literal message text, and the
+setting it carried was silently dropped.**
+
+`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"` sent the user the literal text
+`--tone-ack B15 --tone-reason why`, while the tone-advisory override never reached the
+server. Both failures were silent; the script exited 0.
+
+This is measured, not inferred. The pre-fix template is captured verbatim as a test fixture
+(at the same SHA now registered in the migrator's shipped-SHA allowlist) and run against a
+stub of the reply route: exit 0, received text containing `--tone-ack`, and no
+`toneAdvisoryAck` in the metadata.
+
+**The cost was a corrupted measurement.** Because the override never applied, the tone gate
+re-reviewed the send as an ordinary message whose text now began with option noise. The
+verdict looked absurd, was read as a malfunction, and a **correct** check was graded `wrong`
+in the decision-quality data — the data used to decide which checks to trust. That record is
+durable and is not retracted by this change.
+
+**The root cause was not the script.** These flags were documented nowhere agent-facing:
+not in the script's own usage header (which covers `--format` and `--stdin-base64`), and not
+in the agent instructions, which document the HTTP `metadata.*` fields 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 guessed — and the script accepted the guess
+without complaint. A capability shipped without instructions, plus a tool that stayed silent
+on the only usage an uninstructed caller would try.
+
+An inconsistency underneath made the fix obvious once seen: the script **already** treated an
+unrecognised flag-shaped token as fatal when it appeared *before* the topic id. It was strict
+about nonsense in one position and fully permissive about a real flag in the other. Both
+positions are now treated the same.
+
+Three parts, because the chain had three links:
+
+1. **The script refuses** a `--*` argument after the topic id, printing the correct ordering
+   and the corrected command. Nothing is sent.
+2. **A typo'd flag is caught too** (`--tone-akc`) — the realistic mistake, and equally silent
+   before. The guard matches the *shape*, not a list of known names, which is what makes it
+   useful rather than decorative.
+3. **The flags are documented** — in the script's usage header and in the agent instructions,
+   with a worked example showing flags before the topic id.
+
+**What this does not do:** it does not retract the false grade from 2026-07-26. Whether a
+mistaken grade can be corrected at all — and whether correcting one erases the evidence that
+it was ever made, which would be the opposite defect — is a separate open question, and is
+deliberately not answered here. It also fixes only this script; `slack-reply.sh` and
+`whatsapp-reply.sh` share the parse-then-break shape but carry no tone flags today, so they
+are named rather than swept in.
+
+## What to Tell Your User
+
+If a stray double-dash option ever appeared in the middle of one of my messages to you, that
+was this: a setting that belonged in the plumbing ended up in the text, and whatever it was
+supposed to do quietly didn't happen. It can't reach you as text any more — the send is
+refused and corrected instead.
+
+The part worth knowing: one of those settings is how I record that I disagree with one of my
+own safety checks. When it silently failed to apply, I misread the result and marked a check
+as faulty when it had actually been right. So this wasn't only cosmetic — it put a wrong
+entry in the records used to judge whether those checks are any good. That entry is still
+there; this stops more from being created.
+
+## Summary of New Capabilities
+
+- A flag placed after the topic id is refused with an actionable message naming the correct
+  ordering, instead of being sent to the user as literal text with its effect dropped.
+- A misspelled flag after the topic id is caught by the same guard.
+- The tone-advisory reaction flags (`--tone-ack`, `--tone-reason`, `--tone-complied`,
+  `--tone-decision-ref`) are documented in the script's usage header and in the agent
+  instructions, with a worked example.
+- Existing agents receive both the new script and the new documentation — the doc block is
+  sniffed on its own marker so an agent that already carries the surrounding section is not
+  skipped.
+
+## Evidence
+
+**Reproduction (before),** the pre-fix template against a stub reply route:
+
+| invocation | exit | text received by the user | override applied |
+|---|---|---|---|
+| `… 4242 --tone-ack B15 --tone-reason because` | `0` | `--tone-ack B15 --tone-reason because` | no |
+
+**Observed after,** same stub:
+
+| invocation | before | after |
+|---|---|---|
+| flag after the topic id | sent as message text, exit 0 | refused, exit 1, **zero requests sent** |
+| typo'd flag after the topic id | sent as message text, exit 0 | refused, exit 1, zero requests |
+| flags before the topic id | worked | works — text clean, `toneAdvisoryAck` + reason present |
+| message on stdin containing a flag-shaped token | sent verbatim | sent verbatim (stdin is not inspected) |
+| unknown flag before the topic id | `Unknown flag`, exit 1 | unchanged |
+
+**Tests:** `tests/integration/telegram-reply-misplaced-flag.test.ts` (6) runs the real
+template — and the pre-fix fixture — against a stub route, so "was it sent as text?" is
+answered by the received payload rather than by reading the script.
+`tests/unit/PostUpdateMigrator-toneAdvisoryFlagPosition.test.ts` (3) covers migration parity,
+including the load-bearing case: an agent that already carries the tone-advisory section must
+still receive the invocation guidance. That test was verified to FAIL when the second
+migration block is disabled, so it cannot pass whether or not the migration exists. The full
+telegram-reply and template-SHA surface (10 files, 51 tests) passes unchanged;
+`npx tsc --noEmit` clean.

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.