instar 1.3.242 → 1.3.244

package/upgrades/side-effects/apprenticeship-manual-cycle-write-path.md

@@ -0,0 +1,52 @@
+# Side-Effects Review - Apprenticeship manual cycle write path
+
+**Version / slug:** `apprenticeship-manual-cycle-write-path`
+**Date:** 2026-06-03
+**Author:** codey
+
+## Summary of the change
+
+Current `JKHeadley/main` already had `POST /apprenticeship/cycles`, so this change does not add a second route. It finishes the manual/overseer write path around that existing route:
+
+- `src/server/routes.ts` now validates that manual cycle POST bodies are objects and that `channel`, when present, is one of the four store-supported values.
+- `src/server/CapabilityIndex.ts` now surfaces the apprenticeship cycle endpoints in `/capabilities`.
+- `src/scaffold/templates.ts` adds a CLAUDE.md awareness blurb for manual cycle recording.
+- `src/core/PostUpdateMigrator.ts` mirrors that blurb for existing agents that do not yet have the Apprenticeship Program section.
+- `src/data/builtin-manifest.json` is regenerated after the route/source changes.
+- `upgrades/next/apprenticeship-manual-cycle-write-path.md` records the release-note fragment required by the publish gate.
+- Route and capability tests cover strict channel validation, channel persistence, manual overseer cycle capture, and discovery.
+
+## Side effects and blast radius
+
+The only behavior change on the write path is stricter HTTP validation. A malformed manual request with an unknown channel now receives HTTP 400 instead of being written as `unknown`. The lower-level `ApprenticeshipCycleStore.record()` behavior is unchanged, so legacy rows and automated/non-HTTP callers still normalize invalid or missing channels to `unknown`.
+
+The route remains persistence-only. It does not mutate apprenticeship instance status, does not run lifecycle gates, and does not decide whether a cycle was good. It only writes the row to the cycle store, and existing role-coverage logic interprets those rows afterward.
+
+Capability discovery changes only metadata returned by `/capabilities`; no new auth surface or prefix classification is introduced. `/apprenticeship` was already a public capability prefix, so no `INTERNAL_PREFIXES` entry is needed or appropriate.
+
+The template and migrator changes alter generated/updated CLAUDE.md guidance text. They do not execute operational work. Existing installs that already have an Apprenticeship Program section are still protected by the current idempotency marker and will not be double-patched by this migration.
+
+## Risks considered
+
+- **Breaking automated mentor ticks:** low. The automated call site writes through the store, not the HTTP route, and does not provide a channel today. Store defaulting remains unchanged.
+- **Rejecting useful manual records because of a typo:** intentional. Manual/overseer HTTP writes should fail loudly when the channel is not one of the program-defined channels.
+- **Capability configured status drift:** low. The capability now reports configured when either the instance program or cycle store is wired, matching the fact that cycle routes can be alive independently of the instance object in tests and boot wiring.
+- **Template guidance becoming stale:** medium over time. This is mitigated by listing the same enum values exported by the store today and keeping the text concise.
+
+## Test evidence
+
+Focused verification:
+
+- `npx vitest run tests/integration/apprenticeship-routes.test.ts tests/unit/CapabilityIndex.test.ts tests/e2e/apprenticeship-lifecycle.test.ts`
+- Result: 3 files passed, 31 tests passed.
+
+Planned final checks before push:
+
+- `pnpm lint`
+- `pnpm build`
+- `node dist/cli.js dev:preflight`
+- `pnpm test:smoke`
+
+## Rollback cost
+
+Rollback is a normal code revert. Reverting restores the previous permissive HTTP behavior, removes the capability endpoint entries, and removes the new generated/migrated awareness line. No database migration is introduced, and no existing cycle rows need transformation.

package/upgrades/side-effects/telegram-auth-id-type-tolerant.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — Telegram authorizedUserIds type-tolerant comparison
+
+**Version / slug:** `telegram-auth-id-type-tolerant`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The legacy (non-shared-AuthGate) Telegram auth path used
+`authorizedUserIds.includes(userId)` where `userId` is a `number` but the config
+field, though typed `number[]`, is untyped JSON at runtime and may hold the id as
+a string. `Array.prototype.includes` uses SameValueZero (no coercion), so a
+string-configured id silently failed to match and the authorized user was treated
+as unknown. The fix compares as strings (`authorized.some(id => String(id) ===
+String(userId))`), mirroring the shared-AuthGate path which is already string-based.
+The mini-onboarding auto-add (`server.ts`) is given the same loose membership check
+so it does not append a duplicate when the list already holds the id as a string.
+
+## Decision-point inventory
+
+One decision point: `isAuthorized(userId)` returns true/false (authorized vs gated).
+The change only affects WHICH equal-by-value ids match; it does not change the
+empty-list semantics (still "accept all" on the legacy path) or any other branch.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** None. The change only makes the
+comparison match MORE inputs that were always intended to match (an id equal by
+value, regardless of number-vs-string representation). No id that previously
+authorized stops authorizing: `String(n) === String(n)` holds for every number that
+`includes` would have matched. The empty/absent-list "accept all" path is untouched.
+
+## 2. Under-block
+
+**What does this still miss?** It does not change the fail-open vs fail-closed
+posture of the legacy path (empty list still accepts all — unchanged, out of scope).
+It does not touch the shared-AuthGate path (already string-based) or the Slack/
+WhatsApp/iMessage adapters (separate code, their own typing). It compares by exact
+string equality after coercion, so it intentionally does NOT treat e.g. leading-zero
+or whitespace-padded ids as equal — Telegram ids are canonical integers, so this is
+correct.
+
+## 3. Blast radius
+
+Two callsites: `TelegramAdapter.isAuthorized` (the auth gate) and the `server.ts`
+mini-onboarding auto-add. Both are Telegram-only. No schema, config-shape, or API
+change — existing configs (number ids, string ids, or mixed) all keep working, and
+configs that already worked are unaffected. Behavior strictly widens recognition to
+match the documented intent.
+
+## 4. Reversibility
+
+Fully reversible: revert the two edits. No state migration, no persisted format
+change. Config files are not rewritten by this change (the mini-onboarding still
+pushes a numeric id as before; it just no longer duplicates an existing string id).