instar 1.3.288 → 1.3.290

package/upgrades/1.3.289.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The migration readiness checker gained the piece that makes its data-integrity
+condition achievable: an end-to-end import runner, plus a safe "rehearsal" mode.
+Until now the readiness surface could only WAIT for an import integrity report
+that nothing could produce. Agents can now trigger a server-side rehearsal that
+fetches the real live data, imports it into a throwaway in-memory copy exactly
+as the real migration would, and verifies every row survived bit-for-bit —
+without writing anything durable. The rehearsal's verdict is visible in the
+readiness status, clearly separated from the real thing: only the REAL import
+(still credentials-gated) can ever satisfy the readiness condition.
+
+Also closed a small logging gap found live: a timed-out page download that
+aborted while reading the response body now produces the same clear "page N
+timed out" failure as one that aborted while connecting.
+
+## What to Tell Your User
+
+If your agent is driving a data migration, it can now prove the import pipeline
+works against today's real data — a full rehearsal with zero risk — before
+anyone flips anything. The readiness status shows the rehearsal result
+separately from the real import, so "ready" still means exactly what it meant.
+
+## Summary of New Capabilities
+
+- `POST /cutover-readiness/import-dryrun` — trigger a server-side import
+  rehearsal (live fetch → in-memory AS-IS import → per-row integrity gate);
+  zero durable data writes; never greens the canonical integrity condition.
+- `GET /cutover-readiness/import-dryrun` — the last rehearsal's verdict.
+- `GET /cutover-readiness` now includes an informational `importDryRun` leg.
+- Maturity: stable for the rehearsal path; the REAL import awaits the
+  credentials-gated database adapter (it reuses this same runner).
+
+## Evidence
+
+The runner's verification is observation-based: the integrity gate runs over
+what the target READS BACK, not what was sent — unit tests prove a target that
+silently mangles, drops, or invents rows is caught (checksum-differs /
+missing-in-target / extra-in-target respectively). The readiness-honesty rule is
+structural, not conventional: the constructor refuses wiring the rehearsal
+report onto the canonical integrity path, and a passing rehearsal leaves
+`ready: false` with the canonical report absent (asserted at unit, integration,
+and E2E tiers — 35 new tests, all green). The body-read classification gap was
+reproduced from a live failure log (2026-06-05 11:01Z: raw "operation was
+aborted" with no page context) and is covered by a dedicated unit test.

package/upgrades/1.3.290.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`writeDecisionAudit` in `scripts/instar-dev-precommit.js` writes one file per decision instead of appending a line to one shared JSONL. Two PRs each ADDING a distinct path can never merge-conflict; appending to the same file's tail always did. Same payload, same best-effort/never-block semantics, collision-suffixed filenames.
+
+## What to Tell Your User
+
+Nothing user-visible — this is contributor infrastructure. Pull requests no longer fail to merge over the development decision-audit log.
+
+## Summary of New Capabilities
+
+- Each gated commit's decision-audit record is now its own file under `.instar/instar-dev-decisions/<timestamp>-<slug>.json` (chronological by filename), staged so it still rides the commit it describes.
+- The legacy `.instar/instar-dev-decisions.jsonl` is frozen history — no new appends.
+
+## Evidence
+
+Live failure this fixes (2026-06-05): PR #824 passed all 19 CI checks, then `gh pr merge --squash --admin` failed with "Pull Request has merge conflicts" — `git merge` against main showed exactly ONE conflicted file, `.instar/instar-dev-decisions.jsonl`, because sibling PRs had appended their own audit lines to the same tail while #824 was in CI. Unblocked manually by union-resolving; this change removes the class. Pinned by `tests/unit/instar-dev-precommit-audit-staging.test.ts`: the gate-blocked commit still stages its entry file (the #814 property preserved), two evaluations produce two DISTINCT paths (the conflict-immunity property), and the frozen legacy JSONL is not appended to; the deferrals suite's audit-shape test re-pinned to the per-entry record (riskFloor number, belowFloor, suggestedTier, reasons array). 16/16 tests green.

package/upgrades/decisions-per-entry.eli16.md

@@ -0,0 +1,5 @@
+# Parallel PRs stop colliding on the decision-audit log
+
+Every gated commit records a small audit note (what tier was declared, what the risk classifier suggested). A recent fix made that note ride along inside the commit itself — which solved one problem (notes were evaporating with temporary build folders) but quietly created another: all the notes went into ONE shared file, each commit appending a line at the end. Git can't merge two different "last lines" of the same file, so whenever two pull requests were in flight at the same time — which is now the normal state with three agents shipping in parallel — the second one to merge hit a conflict on that file. This actually happened within hours: a PR passed every check and then failed to merge over nothing but the audit log.
+
+The fix: each decision now gets its own tiny file (named by timestamp and change name) inside a decisions folder, instead of a line appended to a shared file. Two PRs each ADDING a different file never conflict — git and GitHub merge that trivially. Nothing about the audit content changes, the note still rides the commit it describes, and the old log file stays in place as frozen history. The chronological order you used to get from reading the file top-to-bottom now comes from sorting filenames, which start with the timestamp.

package/upgrades/side-effects/decisions-per-entry.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — per-entry decision-audit files (task #80)
+
+**Version / slug:** `decisions-per-entry`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; the audit-continuity question (does the trail survive the format change?) addressed below`
+
+## Summary of the change
+
+`writeDecisionAudit` in the pre-commit gate writes each decision as its own file `.instar/instar-dev-decisions/<ts>-<slug>.json` (staged immediately, preserving #814's ride-the-commit property) instead of appending one line to the shared `.instar/instar-dev-decisions.jsonl`. Distinct paths per PR cannot merge-conflict — including GitHub's server-side merge, which does not honor custom merge drivers. The legacy JSONL freezes in place as history.
+
+## Decision-point inventory
+
+- `writeDecisionAudit` — modified — per-entry file write + stage; same payload fields (ts/slug/tiers/riskFloor/reasons/belowFloor/files/loc); collision-suffix counter for same-ms-same-slug; returns the entry path (used by the belowFloor console message).
+- `DECISIONS_LOG` const — removed (legacy path noted in comment); `DECISIONS_DIR` added.
+- Tests — `instar-dev-precommit-audit-staging.test.ts` re-pinned to the per-entry contract + a NEW conflict-immunity test (two evaluations → two distinct paths) + asserts the legacy JSONL is NOT created; `instar-dev-precommit-deferrals.test.ts` audit-shape test re-pinned.
+
+## 1. Direction-of-failure analysis
+
+- **Old failure (live, PR #824):** CI-green PR fails admin-merge on the audit file tail — recurring at parallel-PR cadence, blocks every second merge, requires manual union resolution each time.
+- **New worst case:** the writer remains best-effort (try/catch, never blocks the gate) — an audit I/O failure loses ONE entry, exactly as before. Filename collision (same ms + same slug) is suffix-countered, pinned by test.
+- **Audit continuity:** the legacy file is untouched history; new entries are chronologically sortable by filename (`ls` order = time order). Readers: only tests read the trail today (grep-verified); both updated.
+- **In-flight PRs written under the old scheme:** once main's shared file stops growing, their single appended line vs main's unchanged tail merges CLEANLY — landing this fix un-jams the conflict class for already-open PRs too (the conflict needed BOTH sides appending).
+
+## 2. Over-permit
+
+None — the gate's blocking logic is untouched; only where the audit record lands.
+
+## 3. Scope deliberately NOT taken
+
+- No migration of legacy JSONL lines into per-entry files — history stays where it was written; a reader that wants the full trail reads both (documented in the script comment).
+- No `.gitattributes merge=union` belt for the legacy file — GitHub's server-side merge ignores it, and with the file frozen the local-rebase benefit is moot.
+
+## 4. Migration parity
+
+None needed — the gate script lives in the repo (`scripts/`), not in agent-installed files; every checkout gets it with the commit. `.instar/instar-dev-decisions/` is created on demand by the writer.
+
+## 5. Token/cost impact
+
+None — same write volume, one file create vs one append per gated commit.
+
+## 6. Rollback
+
+Revert the commit; the writer returns to appending the shared JSONL (and the conflict class returns with it).

package/upgrades/side-effects/import-runner.md

@@ -0,0 +1,66 @@
+# Side-effects review — feedback import runner + dry-run rehearsal route
+
+The cutover-readiness checker (G2.4) composes two conditions; one of them —
+`integrity-gate-pass` — reads a persisted import IntegrityReport that NOTHING in
+the codebase could produce: the integrity-gate core shipped as pure functions
+(#778) with no end-to-end runner wired to live data. This builds the runner and a
+zero-durable-writes REHEARSAL route, so the import pipeline is provable on real
+production data today and the real import is one adapter away when the
+creds-gated cloud DB (G1.4) lands.
+
+## 1. The change
+
+- `migration/importRunner.ts` (new): `runImport(source, target)` — pre-import
+  fingerprint-uniqueness scan (aborts BEFORE any write on a collision),
+  parent-before-child AS-IS import through the new `ImportTarget` seam, then the
+  full integrity gate over what the target READS BACK (intent is never trusted
+  over observation). `InMemoryImportTarget` (deep-copy isolation, duplicate-PK
+  refusal) is the dry-run/test implementation; the real Prisma adapter is a thin
+  future shim over the same seam. Status-equivalence checks CLUSTER statuses only
+  (feedback rows carry their own processing-state domain).
+- `HttpParitySource`: opt-in `captureRaw` keeps cluster + feedback rows VERBATIM
+  for the import read (parity mode unchanged); plus a live-found classification
+  gap closed — an abort during the page BODY read now maps to the same classified
+  504 naming the page/budgets (was: raw "operation was aborted", observed live
+  2026-06-05 11:01Z).
+- `CutoverReadiness`: `runImportDryRunPass()` persists the rehearsal envelope to
+  a SEPARATE `feedback-import-dryrun.json` path; `importDryRunStatus()` surfaces
+  it as `importDryRun` in `status()`. **Readiness honesty is structural**: the
+  constructor REFUSES wiring the dry-run path onto the canonical integrity path,
+  and `ready` composes integrity + parity only — a green rehearsal can never
+  green the gate.
+- Routes: `POST /cutover-readiness/import-dryrun` (server computes, agent only
+  triggers — T7; same always-logged-outcome contract and same 360s per-path
+  timeout as parity-pass) + `GET /cutover-readiness/import-dryrun` (read-only).
+- Awareness: CapabilityIndex, site reference/api.md, CLAUDE.md template + an
+  idempotent PostUpdateMigrator splice for agents already carrying the Cutover
+  Readiness section (Migration Parity Standard).
+
+## 2. Blast radius
+
+Additive. No existing route's behavior changes; `GET /cutover-readiness` gains
+the informational `importDryRun` field. The rehearsal writes ONE new state file
+(`state/feedback-import-dryrun.json`) and nothing else durable. The mandate
+conditions (`integrity-gate-pass`, `parity-zero-divergence`) are untouched — the
+rehearsal cannot reach either. No config migration needed (no new config keys;
+the runner reuses `feedbackMigration.paritySource`). The real import stays
+creds-gated and unbuilt at the adapter layer by design.
+
+## 3. Test coverage
+
+- Unit (18 new, import-runner.test.ts): AS-IS preservation incl. unknown fields,
+  collision abort writes NOTHING, mangling/dropping/inventing targets each caught
+  by the readback gate, dangling-FK, unknown-status divergence, full v1 legacy
+  vocabulary accepted, adapter-supplied schema honored, sequence planning,
+  duplicate-PK refusal, deep-copy isolation, snake_case ids.
+- Unit (6 new, http-parity-source.test.ts): raw capture verbatim, cross-page
+  accumulation + dedup, raw reads refuse without captureRaw/prepare, body-read
+  abort → classified 504, non-abort body parse failure propagates.
+- Unit (6 new, cutover-readiness.test.ts): dry-run records to the separate path
+  and `ready` stays false; failed check records nothing; no-source refusal;
+  pre-import abort surfaced; the same-path wiring REFUSED; torn envelope reads
+  never-ran.
+- Integration (4 new): POST rehearsal over the full HTTP pipeline with a hostile
+  body contributing nothing; GET verdict; 409-records-nothing; 503 when absent.
+- E2E (1 new): import-dryrun routes ALIVE on the production init path
+  (Bearer-gated, 409-not-404 without a source, composed status carries the leg).