instar 1.0.10 → 1.0.12

package/upgrades/side-effects/feat-portability-framework-gate.md

@@ -0,0 +1,62 @@
+# Side-effects review — Real enabledFrameworks field + framework gate (Gap 5)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER (and inert) — no working way to skip Claude-only steps for a
+Codex install. After: precisely targeted. Default config → `['claude-code']`
+→ zero skips → byte-identical to today for every existing/dual install. Only
+an explicit `enabledFrameworks: ['codex-cli']` causes `migrateSettings` to
+skip — exactly the intended case. No over-block.
+
+## 2. Level-of-abstraction fit
+
+Framework resolution is now one private helper (`getEnabledFrameworks`) — the
+single source of truth. The previously-duplicated inline logic in
+`migrateParityRenderings` was refactored to call it, removing drift risk.
+
+## 3. Signal vs Authority compliance
+
+`enabledFrameworks` (persisted config) is the SIGNAL of operator intent;
+`getEnabledFrameworks()` is the one AUTHORITY that resolves it with a safe
+default. No brittle inline re-derivation remains.
+
+## 4. Interactions with adjacent systems
+
+- **migrateParityRenderings** — behavior preserved; the 11 existing
+  parity-renderings tests pass unchanged after the DRY refactor.
+- **FrameworkParitySentinel.enabledFrameworks** — separate config object
+  (sentinel's own interface); this PR adds the *persisted InstarConfig*
+  field the migrator reads. Names intentionally mirror; no shared mutable
+  state, no coupling introduced.
+- **migrateSettings** — only new behavior is the early skip for non-Claude;
+  all downstream `.claude/settings.json` logic is untouched for the default
+  path.
+- **Remaining 48 `.claude/` refs** — unchanged; they can adopt
+  `getEnabledFrameworks()` incrementally. Not touching them now is a
+  deliberate regression-risk decision, not an oversight.
+
+## 5. Rollback cost
+
+Low. One new optional type field + one helper + one DRY refactor + one early
+return + one test file. `git revert` restores prior behavior. The new config
+field is optional and ignored by older code, so a mixed-version fleet is safe.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible: optional field, safe default. Older instar
+versions ignore an `enabledFrameworks` they don't know about. Drift surface
+*reduced* — the duplicate inline framework logic is now a single helper.
+
+## 7. Authorization / Trust posture
+
+No new authority. The helper only reads config and returns a string array.
+The gate only *prevents* writes for non-Claude installs — it never grants a
+new write. Unreadable config fails safe to `['claude-code']` (status quo).
+
+## Outcome
+
+Ship. Corrects an inert audit finding into a real, reachable, tested gate;
+default-safe; drift-reducing; trivial rollback. Fifth of the v1.0.9–v1.0.14
+hardening series.

package/upgrades/side-effects/feat-portability-session-store.md

@@ -0,0 +1,62 @@
+# Side-effects review — FrameworkSessionStore (Gap 3)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — flush/resume silently no-op for Codex. After: no over-block.
+Claude path is byte-identical (default framework = claude-code, same encoding
+empirically confirmed against ~/.claude/projects/). Codex path returns '' when
+no file (same safe no-op the callers already handle). No new over-block.
+
+## 2. Level-of-abstraction fit
+
+Path resolution extracted into one pure module (`FrameworkSessionStore`).
+Consumers delegate. Correct altitude — resolution logic in one tested unit,
+orchestration unchanged in the consumers.
+
+## 3. Signal vs Authority compliance
+
+`framework` (dep) is the SIGNAL of which runtime produced the session; the
+resolver is the single AUTHORITY for the path. Missing/unknown framework
+fails safe to claude-code (status quo).
+
+## 4. Interactions with adjacent systems
+
+- **PreCompactionFlush** — only `resolveTranscriptPath` changed; tail-read,
+  flush, audit logic untouched. 35 regression tests (with ResumeValidator)
+  green.
+- **ResumeValidator** — delegates; the `readSessionJsonl` test override path
+  is unchanged (still wins when provided). Latent slash-only encoding bug
+  fixed (see §6).
+- **CompactionSentinel / other transcript readers** — not touched; they can
+  adopt the resolver incrementally. No behavior change for them.
+- **Codex sessions dir** — read-only globbing; no writes, no mutation.
+
+## 5. Rollback cost
+
+Low. One new module + two delegating edits + one new test. `git revert`
+restores prior behavior. The new optional deps are ignored by callers that
+don't set them.
+
+## 6. Backwards compatibility / drift surface
+
+Claude-code: byte-identical path for slash-only project dirs; for dirs
+containing a dot, ResumeValidator now produces the CORRECT path (the real
+~/.claude/projects/ naming replaces `.` too) — this fixes a pre-existing
+latent failure rather than introducing one. PreCompactionFlush already used
+the `[\/.]` encoding, so it is unchanged. This correctness delta is
+documented, not silent. Drift surface: reduced — one resolver instead of two
+divergent inline encodings.
+
+## 7. Authorization / Trust posture
+
+No new authority. Pure read-only path resolution + fs.existsSync/readdir.
+Cannot write, cannot escalate. Unreadable/missing Codex tree → '' (safe
+no-op).
+
+## Outcome
+
+Ship. Empirically grounded (no fabrication), both consumers wired, a latent
+correctness bug fixed transparently, trivial rollback. Fourth shipped of the
+v1.0.9–v1.0.14 hardening series (1.0.12).