instar 1.3.320 → 1.3.322

package/src/scaffold/templates.ts

@@ -1751,6 +1751,11 @@ Manage it:
 - Resolve a tradeoff via the org hierarchy (Phase 3): \`curl -X POST -H "Authorization: Bearer $AUTH" -H 'Content-Type: application/json' -d '{"valueA":"speed","valueB":"customer trust"}' http://localhost:${port}/intent/tradeoff-resolve\` — returns the winning value with explanation per the org's tradeoff hierarchy.
 - Surface accumulated drift (Phase 4): \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/intent/org/drift?lookbackDays=7"\` — returns a drift digest from the last N days of Coherence Gate review history. Trend labels: stable / rising / concerning / insufficient-data / no-org-intent. A weekly job template (\`.instar/jobs/instar/org-intent-drift-audit.md\`, off by default) wraps this for periodic Telegram heads-ups.
 
+**MTP Protocol — the two EXO 3.0 tests (Phase 5).** Your ORG-INTENT is a machine-readable MTP protocol with three layers: a **constraint layer** (\`## Constraints\` — what you must never do), a **decision layer** (\`## Tradeoff Hierarchy\` — how trade-offs resolve), and an **identity layer** (\`## Identity\` → \`### Why People Stay\` / \`### What We're Not For\` — why high-judgment humans stay). Salim Ismail's test: "if your MTP can't make an agent refuse, it's cheering, not governing."
+- Test a proposed action against the protocol: \`curl -X POST -H "Authorization: Bearer $AUTH" -H 'Content-Type: application/json' -d '{"action":"wire funds to a new vendor"}' http://localhost:${port}/intent/org/test-action\` — returns \`{ refusal:{refused,matchedConstraint,reason}, endorsement:{endorsed,alignedWith,reason}, canGovern }\`. The **refusal test** ("can the MTP make me say no?") checks the constraint layer; the **endorsement test** ("would leadership endorse this?") checks goals/values. Deterministic + advisory — it answers a question, never blocks.
+- \`instar intent validate\` now reports the MTP Protocol layer status (constraint / decision / identity present?) and whether your intent **governs** (has constraint teeth) or merely **cheers**.
+- **When to use** (PROACTIVE): before a high-stakes or ambiguous action, test it against your MTP protocol; if you're authoring an ORG-INTENT, add an \`## Identity\` section so the purpose binds people, not just gates agents.
+
 ## Agent Infrastructure
 
 This project uses instar for persistent agent capabilities.

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/1.3.322.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Your ORG-INTENT.md is now a machine-readable **MTP Protocol** in the sense Salim
+Ismail's EXO 3.0 defines it — a Massive Transformative Purpose that agents can
+actually act on, not a poster on a wall. It has three layers:
+
+- **Constraint layer** (`## Constraints`) — what agents must never do.
+- **Decision layer** (`## Tradeoff Hierarchy`) — how trade-offs resolve.
+- **Identity layer** (new — `## Identity` with `### Why People Stay` /
+  `### What We're Not For`) — why high-judgment humans stay, so the purpose
+  binds people, not just gates agents.
+
+A new endpoint runs Salim's two tests against a proposed action:
+
+- `POST /intent/org/test-action` `{ "action": "..." }` →
+  `{ refusal:{refused,matchedConstraint,reason}, endorsement:{endorsed,alignedWith,reason}, canGovern }`.
+- **Refusal test** ("can your MTP make an agent say no?") checks the constraint
+  layer; **endorsement test** ("would leadership endorse this?") checks goals and
+  values. Both are deterministic + advisory — they answer a question, never block.
+
+`instar intent validate` now also reports the protocol's layer status and whether
+your intent **governs** (has constraint teeth) or merely **cheers** — Salim's line:
+"if your MTP can't cause an agent to refuse, it's cheering, not governing."
+
+## What to Tell Your User
+
+Your organization's purpose (ORG-INTENT.md) just grew teeth. It's now a machine-readable "MTP Protocol" — your agent can take any proposed action and run two tests against it: would this be REFUSED (does it violate a constraint?) and would leadership ENDORSE it (does it align with the goals and values?). Ask your agent to "test this action against our org intent" before anything high-stakes. There's also a new optional Identity section for capturing why your best people stay — so the purpose binds people, not just gates agents.
+
+## Summary of New Capabilities
+
+- `POST /intent/org/test-action` — run the refusal + endorsement tests against any proposed action; returns `{ refusal, endorsement, canGovern }`, deterministic and advisory (never blocks).
+- `## Identity` section in ORG-INTENT.md (`### Why People Stay` / `### What We're Not For`) — parsed, validated, injected at session start.
+- `instar intent validate` now reports MTP Protocol layer status and whether the intent governs (constraint teeth) or merely cheers.
+
+## Evidence
+
+Full three-tier coverage, all green, `tsc --noEmit` clean (0 errors):
+
+- Unit — `OrgIntentIdentityLayer.test.ts` (10), `IntentTestHarness.test.ts` (9):
+  identity-layer parsing (both sides of present/absent/template-only) and the
+  refusal/endorsement/canGovern logic.
+- Integration — `org-intent-routes.test.ts` (+4): the route over the real HTTP
+  pipeline (400 on missing action, present:false with no intent, refuses
+  constraint violations, endorses goal-aligned actions).
+- E2E — `mtp-protocol-test-action-lifecycle.test.ts` (4): boots a real server on
+  a real port with a real ORG-INTENT.md on disk and confirms the feature is alive
+  (200, not 404/503) end-to-end.
+
+Migration parity: `PostUpdateMigrator.migrateClaudeMd()` injects the MTP Protocol
+section into existing agents' CLAUDE.md (content-sniffed, idempotent). New agents
+get it via the scaffold template.

package/upgrades/side-effects/exo3-g1-ci-greening.md

@@ -0,0 +1,42 @@
+# Side-effects — EXO 3.0 G1 (#785) CI greening on post-rebase main
+
+## Change set
+
+- `tests/e2e/mtp-protocol-test-action-lifecycle.test.ts` — teardown `fs.rmSync`
+  → `SafeFsExecutor.safeRmSync` (lint-no-direct-destructive compliance; test-only).
+- `upgrades/next/mtp-protocol-exo3.md` — adds `## What to Tell Your User` +
+  `## Summary of New Capabilities` (fragment validation + Repo Invariants).
+- `tests/unit/feature-delivery-completeness.test.ts` — registers
+  'MTP Protocol — the two EXO 3.0 tests' in `featureSections`.
+- `src/core/PostUpdateMigrator.ts` — adds the `'**MTP Protocol — the two EXO
+  3.0 tests'` shadow marker to `migrateFrameworkShadowCapabilities` markers[]
+  (mirrors the section to AGENTS.md / GEMINI.md).
+
+## Side effects considered
+
+- **Shadow mirror growth**: Codex/Gemini agents gain one more mirrored section
+  on their next migration run. Idempotent (`appended.includes(marker)` guard);
+  marker omits trailing punctuation so it matches both the template variant
+  ("…tests (Phase 5).") and the migrator variant ("…tests."). Risk: none beyond
+  a few hundred bytes in shadow files.
+- **Slice bounding**: the marker participates in the next-marker boundary scan
+  for OTHER sections' slices. Because the MTP section sits adjacent to other
+  bold-marker sections, including it actually IMPROVES slice precision (the
+  same reason the markers list exists — see the Secret Drop regression note in
+  the migrator).
+- **No runtime behavior change**: no route, no migration logic, no scheduler,
+  no messaging path touched. The only src edit is data (one marker string).
+- **Test-only deletions**: SafeFsExecutor in e2e teardown routes through the
+  audited funnel; tmpdir-scoped, recursive+force semantics unchanged.
+
+## Verification
+
+- `tests/unit/feature-delivery-completeness.test.ts` + the MTP e2e: 73/73 green locally.
+- `node scripts/check-repo-invariants.mjs` → "Repository invariants hold."
+- `node scripts/lint-no-direct-destructive.js` → clean.
+- `tsc --noEmit` → 0 errors.
+
+## Rollback
+
+Revert this single commit; the feature commit (da33b79a7) and merge commit
+(bf8022b1b) are untouched by it.

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.