instar 1.3.325 → 1.3.326

package/src/scaffold/templates.ts

@@ -527,7 +527,7 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Create an instance: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/apprenticeship/instances -H 'Content-Type: application/json' -d '{"id":"codey-to-gemini","instanceType":"mentorship","overseer":"echo","mentor":"codey","mentee":"gemini","framework":"gemini-cli","priorInstanceId":null}'\` (id/overseer/mentor/mentee/framework are charset-clamped to \`^[a-z0-9-]+$\`; dup id rejected; harvestFrom=mentor / harvestTo=mentee).
 - Transition status (the ONLY way it changes — runs the gate): \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/apprenticeship/instances/:id/transition -H 'Content-Type: application/json' -d '{"to":"active"}'\` (refused with a reason + 409 on a failed gate or illegal transition; \`complete\` is terminal).
 - Preview a gate without mutating: \`POST /apprenticeship/instances/:id/can-start\` · \`.../can-complete\`.
-- Record a manual cycle: \`POST /apprenticeship/cycles\` with \`instanceId\`, positive \`cycleNumber\`, \`task\`, \`menteeOutput\`, optional \`mentorFlagged\` / \`overseerDifferential\` / \`coaching\` / \`infraItems\`, \`kind\` (\`mentor-mentee-differential\`, \`overseer-apprentice-devreview\`, \`overseer-mentee-direct\`), and \`channel\` (\`telegram-playwright\`, \`threadline-backup\`, \`direct-shortcut\`, \`unknown\`). Use this when the overseer or manual loop found a differential outside the automated mentor tick.
+- Record a manual cycle: \`POST /apprenticeship/cycles\` with \`instanceId\`, positive \`cycleNumber\`, \`task\`, \`menteeOutput\`, optional \`mentorFlagged\` / \`overseerDifferential\` / \`coaching\` / \`infraItems\`, \`kind\` (\`mentor-mentee-differential\`, \`overseer-apprentice-devreview\`, \`overseer-mentee-direct\`), and \`channel\` (\`telegram-playwright\`, \`threadline-backup\`, \`direct-shortcut\`, \`unknown\`). A \`telegram-playwright\` cycle additionally REQUIRES a \`transcriptAudit\` block — \`{ topicIds, window: {start,end}, summary, findingDedupKeys, generatedAt, ledger: 'local'|'remote'|'dry-run'|'failed' }\` — built from \`instar dev:post-drive-transcript-audit\` run over the drive window (use \`--history-base-url\` when the transcript lives on the mentee's server; \`ledger:'local'\` claims are cross-checked against the real framework ledger). Use this when the overseer or manual loop found a differential outside the automated mentor tick.
 - **When to use** (PROACTIVE): when starting or closing a mentorship/apprenticeship instance, drive it through the registry + transitions so the retro-harvest is reviewed before the next instance starts and the lessons are captured before this one closes — never track an instance's lifecycle by memory.
 
 **Failure-Learning Loop** — Dev-process failure forensics (instar self-hosting). When something you built breaks later, it's captured and traced back to the spec/initiative/project AND the dev toolchain that produced it; the analyzer surfaces process-gap patterns and opens human-approved tracked fixes, then verifies whether each fix actually reduced that failure class. Ships OFF (\`monitoring.failureLearning.enabled\`); registers itself on the initiative board.

package/upgrades/1.3.326.md

@@ -0,0 +1,58 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Closes the loop on the UX-blindspot arc: the post-drive transcript auditor
+(PR #864) is no longer optional on the channel it was built for. An
+apprenticeship cycle recorded with `channel: 'telegram-playwright'` — the
+dogfooded drive through the mentee's real Telegram UX — now structurally
+REFUSES to exist without a `transcriptAudit` block proving the objective
+audit ran:
+
+- `POST /apprenticeship/cycles` requires `transcriptAudit: { topicIds, window:
+  {start,end}, summary, findingDedupKeys, generatedAt, ledger:
+  'local'|'remote'|'dry-run'|'failed', notes? }` on telegram-playwright cycles
+  (optional-but-validated on other channels). The refusal error teaches the
+  exact CLI that produces the artifact.
+- **Anti-fabrication tooth**: a block declaring `ledger:'local'` with filed
+  findings is cross-checked against the REAL framework ledger — if none of the
+  claimed dedup keys exist, the record is refused. Honest declarations
+  (`remote`/`dry-run`/`failed`) are accepted as declared and stay queryable.
+- `instar dev:post-drive-transcript-audit` gains `--history-base-url` (+
+  `INSTAR_HISTORY_AUTH_TOKEN`): read the drive transcript from the MENTEE's
+  server (where the Playwright drive actually lands) while filing findings
+  into your OWN ledger. The local token is never sent to the remote server.
+- Mentor standing orders, the CLAUDE.md template, and a targeted
+  PostUpdateMigrator line-rewrite all teach the new shape — deployed agents
+  learn it on update instead of hitting mystery 400s.
+
+Why: "Observation Needs Structure" (PR #861) — an observation tool nobody is
+forced to run is the same prose-wish the article bans, one level up. #856
+gated the subjective half (mentor seat-counts); this gates the objective half.
+
+## What to Tell Your User
+
+Nothing user-visible changes day to day. Under the hood, the apprenticeship
+program's drive records now require proof that the objective transcript audit
+ran — so UX friction caught on a drive can no longer be silently skipped, and
+fabricated audit claims are refused against the real findings ledger.
+
+## Summary of New Capabilities
+
+- `transcriptAudit` block on `POST /apprenticeship/cycles` — required for
+  telegram-playwright cycles, validated everywhere, ledger-verified for
+  `local` claims.
+- `FrameworkIssueLedger.hasDedupKey(key)` — read-only existence probe.
+- `instar dev:post-drive-transcript-audit --history-base-url <url>` — split
+  read/write servers for the cross-agent mentor flow.
+
+## Evidence
+
+All three test tiers green: store unit (21), auditor CLI unit (8, incl. the
+token-isolation case), routes integration (21, incl. both sides of the
+anti-fabrication boundary), e2e lifecycle (7, incl. the feature-alive gate
+case through AgentServer). Migration test (4) covers rewrite, idempotency,
+and no-double-fire. `tsc --noEmit` clean.

package/upgrades/side-effects/apprenticeship-transcript-audit-gate.md

@@ -0,0 +1,53 @@
+# Side-Effects Review - apprenticeship transcript-audit gate
+
+**Version / slug:** `apprenticeship-transcript-audit-gate`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Makes the post-drive transcript audit (PR #864) structurally unskippable on the channel it was built for: `telegram-playwright` apprenticeship cycles now refuse to record without a validated `transcriptAudit` block. Adds a route-level anti-fabrication cross-check for `ledger:'local'` claims, a `--history-base-url` split on the auditor CLI so the cross-agent flow (read mentee's transcript, file to own ledger) actually works, and updates every teaching surface (mentor standing orders, CLAUDE.md template, targeted migrator line-rewrite).
+
+## Decision-point inventory
+
+- `validateTranscriptAudit` (store) - add - refuses telegram-playwright cycles without the artifact; validates shape on any channel when supplied.
+- `POST /apprenticeship/cycles` (route) - modify - cross-checks `ledger:'local'` claimed dedup keys against the real FrameworkIssueLedger; refuses fabricated claims.
+- `FrameworkIssueLedger.hasDedupKey` - add - read-only existence probe, no new write authority.
+- `runPostDriveTranscriptAuditCli` - modify - splits history reads (possibly remote) from ledger writes (always local).
+- `PostUpdateMigrator` cycle-line rewrite - add - idempotent CLAUDE.md text patch.
+
+## 1. Over-block
+
+The gate refuses telegram-playwright cycle records lacking the audit block. Risk: a mentor who genuinely CANNOT run the audit (mentee server down, history route unavailable) is blocked from recording the cycle. Mitigation: the `ledger:'failed'` declaration exists precisely for this — run the auditor, let it fail, declare `failed` with the reason in `notes`, and the record is accepted honestly. The refusal message teaches the producing CLI including the cross-agent flag. The cross-check can also over-block if an agent files findings locally and the ledger write genuinely succeeded but into a DIFFERENT framework value — the check is framework-agnostic (any framework's dedup key counts), which minimizes this.
+
+## 2. Under-block
+
+Fabrication remains possible for `remote` / `dry-run` / `failed` declarations — the route cannot verify another server's ledger without cross-agent auth machinery (out of scope for this slice). Accepted deliberately: the declaration is durably recorded and queryable, so a pattern of suspicious declarations is itself visible to meta-analysis. The operatorSeatUx block has the same trust model. A future slice can verify `remote` claims over Threadline.
+
+## 3. Level-of-abstraction fit
+
+The shape gate lives in the store (single writer, same place as the operatorSeatUx gate — the two halves of the same observation record). The ledger cross-check lives in the route because only the route has the FrameworkIssueLedger dependency; the store stays persistence-only. The CLI split is read-side only; the write path is untouched.
+
+## 4. Blast radius
+
+- New column `transcript_audit_json` via the established idempotent ALTER pattern; legacy rows read as null. No data rewrite.
+- One existing caller class affected: mentor sessions recording telegram-playwright cycles over HTTP. They get a teaching 400 until they supply the block — this is the designed behavior (same rollout shape as #856, which the mentor loop absorbed same-day). Standing orders updated in the same PR so newly-spawned mentor sessions know before they hit it.
+- Non-telegram-playwright callers: zero behavior change unless they supply a malformed block (which previously would have been silently ignored — now validated).
+- The CLI defaults preserve #864 single-server behavior byte-for-byte when `--history-base-url` is omitted.
+
+## 5. Failure modes
+
+- Remote history server unreachable → auditor CLI errors per-topic read; mentor declares `ledger:'failed'`. No silent skip.
+- No FrameworkIssueLedger on the recording server → cross-check skipped (declaration recorded); shape still validated. Documented in tests.
+- Corrupt stored audit JSON (hand-edited row) → reads as null via the lenient parse path with `@silent-fallback-ok` justification, mirroring operatorSeatUx.
+
+## 6. Security
+
+The local auth token is never sent to a remote history server: remote reads use `--history-auth-token` / `INSTAR_HISTORY_AUTH_TOKEN` or no header at all. Token-via-flag is discouraged in the help text (ps visibility); the env var is the documented path.
+
+## 7. Migration parity
+
+- New agents: template teaches the new POST shape.
+- Existing agents: targeted PostUpdateMigrator line-rewrite (idempotent, content-sniffed on old-line-present + new-marker-absent) updates the apprenticeship section they already carry.
+- Mentor loop: standing orders (buildAutoloopGoal step 5) teach audit-then-record including the cross-agent read.