instar 1.3.320 → 1.3.321

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T21:47:40.730Z",
-  "instarVersion": "1.3.320",
+  "generatedAt": "2026-06-05T22:14:45.187Z",
+  "instarVersion": "1.3.321",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-preflight": {
@@ -1010,7 +1010,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-ci-failures": {
@@ -1018,7 +1018,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-profile-node": {
@@ -1026,7 +1026,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/upgrades/1.3.321.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Instar now has a post-drive transcript auditor for operator-seat UX review. Given topic ids and a drive window, it reads the existing topic message history, classifies duplicate notices or deliveries, resend or retry asks, internal infrastructure noise, and content-free status updates, then files each finding into the framework issue ledger with a stable dedupe key.
+
+The framework issue ledger also now preserves related-spec citations when observations are recorded, so findings can keep their link to Observation Needs Structure and the UX-blindspot work instead of losing that context after the write.
+
+## What to Tell Your User
+
+I can now audit a supervised Telegram drive after it happens and turn visible friction into durable findings instead of leaving it buried in chat.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Post-drive transcript UX audit | Run the new developer audit command with topic ids and a time window. |
+| Framework issue citations | Automatic when an observation includes a parent-principle or related-spec citation. |
+
+## Evidence
+
+Live fixture verification used topics 2278 and 2271 for the 11:15-11:21 PDT window on 2026-06-05. Dry-run first reported one duplicate-delivery group and two content-free status-notice groups after the ACK false positive was removed. Filing mode then wrote three framework issue observations with stable dedupe keys; rerunning the command deduped them instead of creating duplicates. Targeted tests passed for 50 cases across the auditor and framework issue ledger suites, build passed, lint passed, and the Tier-1 dev gate accepted the ELI16 plus side-effects artifacts.

package/upgrades/side-effects/post-drive-transcript-audit.md

@@ -0,0 +1,64 @@
+# Side-Effects Review - post-drive transcript auditor
+
+**Version / slug:** `post-drive-transcript-audit`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds a standalone post-drive transcript auditor and CLI command. It reads existing topic message history for specified topics and a time window, classifies operator-seat UX antipatterns, prints a structured report, and writes each finding to the existing framework issue ledger. It also fixes the ledger so a `relatedSpec` citation passed to the write path is persisted on new issues or backfilled on later matching observations.
+
+## Decision-point inventory
+
+- `classifyTranscriptUx` - add - deterministic signal classifier for transcript messages.
+- `runPostDriveTranscriptAudit` - add - decides whether to file each classified finding, with dry-run support.
+- Framework issue ledger `recordObservation` - modify - preserves related-spec citation metadata; no new authority or route.
+
+## 1. Over-block
+
+No block/allow surface - over-block is not applicable. The auditor can produce false-positive findings, but those are ledger signals for review, not user-message blocks.
+
+The main false-positive risk is classifying a legitimate short status message as content-free. The live fixture dry-run exposed this for normal acknowledgements, so the heuristic was narrowed to repeated/status chatter such as "actively working", "still working", or "no terminal output", and repeated identical notices are grouped.
+
+## 2. Under-block
+
+The auditor still misses UX issues that require deeper conversational interpretation. For example, it will not detect a polite but confusing request unless it contains resend/retry/re-paste language, and it will not detect subtle infrastructure leakage unless it uses the configured infrastructure terms. That is acceptable for this slice because the output is a structured starting signal, not a mentor judgment loop.
+
+The message-history route currently returns a bounded recent history. A large topic with more than the cap between the drive window and audit time could under-report old messages. The command makes the limit explicit and clamps it to the existing server cap; a future slice can add a broader archival reader if needed.
+
+## 3. Level-of-abstraction fit
+
+This is intentionally a low-level detector. It belongs after a drive, not in the live send path, because it is looking for transcript evidence to file. It does not duplicate the tone gate or messaging authority; it feeds the framework issue ledger with evidence pointers so later human or process review has a durable artifact.
+
+The ledger citation fix is at the right layer because the route already accepted `relatedSpec`; losing it inside the storage layer meant callers could do the right thing and still end up with a blind record.
+
+## 4. Signal vs authority compliance
+
+- [x] No - this change produces a signal consumed by an existing ledger.
+- [ ] No - this change has no block/allow surface.
+- [ ] Yes - but the logic is a smart gate with full conversational context.
+- [ ] Yes, with brittle logic - STOP.
+
+The classifier is deliberately brittle and therefore holds no authority. It cannot block, retry, resend, escalate, or alter a transcript. Its only side effect is filing reviewable observations with stable dedupe keys.
+
+## 5. Interactions
+
+- **Shadowing:** no live messaging check is shadowed. The command runs manually after the drive and reads existing history.
+- **Double-fire:** repeated runs file the same canonical issue because the dedupe key includes topic, window, category, and message evidence. The live fixture was run twice; the second write deduped.
+- **Races:** the only shared state is the framework issue ledger. The ledger already owns SQLite write serialization and episode dedupe.
+- **Feedback loops:** there is no mentor judgment loop. Findings do not automatically alter future classifications or message behavior.
+
+## 6. External surfaces
+
+The command reads local server topic history and writes to the local framework issue ledger. That creates persistent state: open framework issue rows and observations. The live fixture run filed three observations for topics 2278 and 2271 in the 11:15-11:21 PDT window. Because the running server still had the pre-fix ledger code loaded, those three rows were updated directly with the related-spec citation after the code fix; future runs through this PR path persist it normally.
+
+No Telegram messages are sent by the command. No GitHub, Cloudflare, or third-party systems are called. The CLI output can include short excerpts, so operators should treat reports as local/private unless deliberately published.
+
+## 7. Rollback cost
+
+Code rollback is a normal revert. The command is additive, and removing it does not affect live messaging. The ledger citation change is backward-compatible: it only fills an existing nullable column. If a filed observation is wrong, the durable record can be closed, marked fixed, or superseded through the existing ledger workflow; no schema rollback is needed.
+
+## Conclusion
+
+This slice is clear to ship as Tier 1. It adds a narrow, post-drive observation tool; keeps classification signal-only; files findings through the existing ledger; and fixes the storage bug that would otherwise erase the parent-principle citation required by the UX-blindspot work.