instar 0.28.59 → 0.28.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.59",
+  "version": "0.28.60",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:push": "vitest run --config vitest.push.config.ts",
+    "test:smoke": "vitest run --config vitest.push.config.ts --changed origin/main",
     "test:flaky": "vitest run tests/unit/relationship-routes.test.ts tests/integration/messaging-routes.test.ts tests/integration/whatsapp-routes.test.ts tests/unit/server.test.ts tests/e2e/semantic-memory-lifecycle.test.ts tests/e2e/system-reviewer-e2e.test.ts tests/e2e/working-memory-lifecycle.test.ts tests/e2e/messaging-multi-agent.test.ts",
     "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-04-19T02:56:02.572Z",
-  "instarVersion": "0.28.59",
+  "generatedAt": "2026-04-19T05:19:43.879Z",
+  "instarVersion": "0.28.60",
   "entryCount": 186,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.60.md

@@ -0,0 +1,80 @@
+# Upgrade Guide — Pre-push smoke tier (fast local test gate)
+
+## What Changed
+
+The local pre-push test gate now runs only the tests affected by files
+you changed, instead of the full suite. On a typical small push this
+drops from ~10 minutes to tens of seconds. The full suite still runs in
+CI on the PR across 8 sharded runners, and CI is the authority for
+merge.
+
+### Before
+
+Every `git push` ran `npm run test:push` — the full suite minus the
+known-flaky exclude list — serially (no in-process parallelism because
+tests collide on ports, SQLite, npm). Wall-clock ~9–10 min on every
+push, including pushes that only touched docs or config.
+
+### After
+
+Every `git push` now runs `npm run test:smoke` — the same test set,
+gated by vitest's `--changed origin/main` mode, so only tests whose
+files (or their transitive imports) appear in your diff execute. The
+exclude list and `fileParallelism: false` are preserved; the change is
+which files are included, not how they run.
+
+Escape hatches, for the cases where you want the old behavior:
+
+| Variable | Effect |
+|----------|--------|
+| `INSTAR_PRE_PUSH_FULL=1 git push` | Run the full push suite locally (old behavior, ~10 min) |
+| `INSTAR_PRE_PUSH_SKIP=1 git push` | Skip pre-push tests entirely; CI is the only gate |
+
+The NEXT.md / version / side-effects pre-push gate still runs first on
+every push — that's independent of the test tier and stays as-is.
+
+## What to Tell Your User
+
+Pushing local changes now takes seconds instead of minutes in the
+common case. The exhaustive test run still happens on GitHub before
+anything merges, so you won't ship a broken change — you just won't
+wait for the full suite on your laptop.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Fast local pre-push gate | Nothing to do — `git push` now runs only tests touched by your diff |
+| Force full local suite | `INSTAR_PRE_PUSH_FULL=1 git push` |
+| Skip local tests entirely | `INSTAR_PRE_PUSH_SKIP=1 git push` (CI still runs the full suite) |
+
+## Evidence
+
+- Local run of `npm run test:smoke` on this change (which only touches
+  `.husky/pre-push` and `package.json` scripts) runs 0 tests — the
+  diff doesn't cover any source files, so `--changed` has no targets.
+  That's the intended fast-path.
+- Local run of `npm run test:push` unchanged — ~10 min as before, now
+  opt-in via `INSTAR_PRE_PUSH_FULL=1`.
+- CI's 8-shard matrix on `ci.yml` is unchanged and continues to run
+  the full push suite on every PR — that's the authority; pre-push is
+  a signal.
+
+Side-effects review:
+`upgrades/side-effects/pre-push-smoke-tier.md` — covers over/under-block,
+level-of-abstraction fit (signal-vs-authority: pre-push is a signal, CI
+is the authority), interactions with the NEXT.md gate and the retry
+loop, external surfaces, rollback cost.
+
+## Deployment Notes
+
+No operator action required on update. The change is to the
+contributor-side git hook, which is installed by `npm install` via
+husky. Contributors pick it up automatically on their next `npm ci`.
+
+## Rollback
+
+Revert this commit. `.husky/pre-push` returns to running
+`npm run test:push` (full suite) on every push, `test:smoke` script
+stays harmless in package.json until removed. No schema changes, no
+state-file changes, no API changes.

package/upgrades/side-effects/0.28.57.md

@@ -0,0 +1,33 @@
+# Side-Effects Review — 0.28.57 (release aggregate)
+
+**Version:** `0.28.57`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.57 bundles two changes that were each reviewed individually at merge time. The publish workflow's file-renamer skipped the corresponding `upgrades/side-effects/` artifact during the 0.28.57 finalization (it renames `upgrades/NEXT.md → upgrades/{version}.md` but not the side-effects counterpart), so this file is a minimal aggregator that points at the two component reviews already on disk. Captured as a follow-up in the pre-push gate: teach `publish.yml` or `check-upgrade-guide.js` to also rename the matching side-effects artifact so this backfill isn't needed on future releases.
+
+## Components
+
+### 1. TelegramLifeline sends auth on `/internal/*` forwards
+
+Landed via PR #64. Surgical fix in `src/lifeline/TelegramLifeline.ts` to add `Authorization: Bearer <authToken>` to `forwardToServer()` and `handleCallbackQuery()`. Reasoning: the 0.28.53 server-side tightening that required auth on `/internal/*` had no matching client-side update in the lifeline — every inbound Telegram message was 401ing.
+
+- No runtime decision points introduced; a signal-less, surface-narrow header addition.
+- Over-block / under-block: not applicable — no block/allow surface.
+- Level-of-abstraction: header is constructed exactly where the fetch is built; no new indirection.
+- Signal-vs-authority: not applicable — hard-invariant transport-layer auth.
+- Interactions: none with other gates; backwards-compatible on servers that don't require the header.
+- Rollback: revert the single file.
+
+### 2. Drop duplicate CI gate from `publish.yml` (PR #67)
+
+Full review: `upgrades/side-effects/publish-drop-duplicate-ci-gate.md` (in this directory). Summary: removed the `ci` job from `publish.yml` that duplicated `ci.yml` on the same `push: branches: [main]` event. Publish wall-clock measured 11m → 55s on the first post-merge run. Branch-protection-at-PR-time remains the actual authority.
+
+## Notes
+
+This aggregator file exists to satisfy the `pre-push-gate.js` requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content. The finer-grained artifacts for each component are the authoritative reviews; this file only provides the version-named pointer.
+
+Follow-up captured: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename.

package/upgrades/side-effects/0.28.58.md

@@ -0,0 +1,24 @@
+# Side-Effects Review — 0.28.58 (release aggregate)
+
+**Version:** `0.28.58`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.58 shipped the Initiative Tracker recovery merge (PR #68). The two component reviews exist in this directory under slug names because `publish.yml`'s finalization renames `upgrades/NEXT.md → upgrades/{version}.md` but does not rename the corresponding side-effects artifact. This file is a minimal aggregator that satisfies `pre-push-gate.js`'s requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content.
+
+## Components
+
+### Initiative Tracker — core and API
+
+Full review: `upgrades/side-effects/initiative-tracker-core-and-api.md`. Persisted multi-phase work tracker with phase / blocker / last-touched state; backed by a JSON store; 28 core tests + 15 route tests added.
+
+### Initiative Tracker — dashboard tab
+
+Full review: `upgrades/side-effects/initiative-tracker-dashboard-tab.md`. New "Initiatives" tab in the dashboard rendering the tracker state; 9 dashboard smoke tests added.
+
+## Notes
+
+Same follow-up as noted in `0.28.57.md` aggregator: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename. Until one of those lands, each release will need a backfill aggregator like this one.

package/upgrades/side-effects/0.28.59.md

@@ -0,0 +1,20 @@
+# Side-Effects Review — 0.28.59 (release aggregate)
+
+**Version:** `0.28.59`
+**Date:** `2026-04-19`
+**Author:** `echo` (backfill)
+**Second-pass reviewer:** `not required`
+
+## Summary
+
+Release 0.28.59 shipped the dashboard "Resume live output" scroll-reliability + always-visible control fix (PR #63). The component review exists in this directory under its slug name (`dashboard-resume-live-scroll.md`) because `publish.yml`'s finalization renames `upgrades/NEXT.md → upgrades/{version}.md` but does not rename the corresponding side-effects artifact. This file is a minimal aggregator that satisfies `pre-push-gate.js`'s requirement that `upgrades/side-effects/{version}.md` exists whenever `upgrades/{version}.md` exists and claims fix/feature content.
+
+## Components
+
+### Dashboard "Resume live output" reliability + always-visible control
+
+Full review: `upgrades/side-effects/dashboard-resume-live-scroll.md`. Pure UI timing + visibility fix — all three resume paths now use xterm's write-completion callback so `scrollToBottom()` runs after the buffer is populated; button visibility now mirrors `!userIsFollowing` from every code path that flips the flag. 10 regression tests added at `tests/unit/dashboard-resumeLive.test.ts`.
+
+## Notes
+
+Same follow-up as captured in `0.28.57.md` and `0.28.58.md` aggregators: either (a) teach `publish.yml` to also rename the matching side-effects artifact during NEXT → version finalization, or (b) relax `pre-push-gate.js` to accept any side-effects artifact dated within the release window rather than requiring a version-exact filename. Until one of those lands, each release will need a backfill aggregator like this one.

package/upgrades/side-effects/ci-shard-unit-tests.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Shard CI unit tests across 4 parallel runners
+
+**Version / slug:** `ci-shard-unit-tests`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`.github/workflows/ci.yml` unit-test job is extended to run the pre-push test suite across 4 vitest shards per Node version, using vitest's built-in `--shard=N/M` file-partitioning. The matrix changes from `{ node-version: [20, 22] }` (2 runners, each ~9½ min serial) to `{ node-version: [20, 22], shard: [1,2,3,4] }` (8 runners, each ~2½ min serial inside its shard). `fileParallelism: false` in `vitest.push.config.ts` stays untouched — each shard still runs its files one-at-a-time to preserve the port / SQLite / npm isolation that commit `002a463` established. `fail-fast: false` is added so one flaky shard doesn't kill the others. Expected impact on CI wall-clock: unit-test phase 9½ min → ~3 min, which pulls overall PR-CI time from ~12 min toward ~5-6 min (next bottleneck becomes integration/e2e). Only file touched: `.github/workflows/ci.yml`.
+
+## Decision-point inventory
+
+- `ci.yml.unit` — **modify** — job matrix gains a `shard` dimension; test runner invoked with `--shard=${{ matrix.shard }}/4`.
+
+No runtime / agent-behavior decision points touched.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface on message flow — over-block not applicable in the runtime sense.
+
+In the CI sense: the change runs *exactly the same* set of tests as before, just partitioned across 4 runners per Node version. Vitest's sharding is deterministic and disjoint — the union of `--shard=1/4 … 4/4` is the full include set. A commit that passed unsharded would pass sharded. No new rejection surface.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Same as before: anything `test:push` doesn't cover (the flaky-exclusion list in `vitest.push.config.ts` is unchanged — the same ~30 files that were excluded as flaky remain excluded; full suite still runs separately via `npm test` and is not part of CI gating). No new under-block introduced by this change.
+
+One theoretical concern: if the shard hash assignment is not stable across vitest versions, a file could disappear from all shards after a vitest upgrade. This is vanishingly unlikely in practice because vitest's shard algorithm is documented and stable; the union is enforced by the CLI. If we ever suspect it, a simple sanity check is to run with `--shard=` omitted and compare the test count.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. File-level parallelism was disabled in `vitest.push.config.ts` because tests spawn HTTP servers, SQLite DBs, and real npm operations that collide when running in the same process pool (see commit `002a463`). Sharding at the CI-runner level (one process per shard on its own VM) sidesteps that collision entirely — each shard has its own ports, own filesystem, own npm cache — without re-enabling in-process parallelism. This is the right layer: the isolation problem was resource-contention across a single machine's pool; moving to multiple machines solves the resource contention without touching the isolation invariant.
+
+Signal/authority lens: not applicable. CI test-pass is still an authority-grade signal computed over the same logical test set; we're just distributing the computation.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface on message flow or agent behavior.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+CI sharding is a runtime-distribution change. The test suite itself is unchanged — same authority (the full union of tests), same verdict logic (all must pass), just faster. Signal-vs-authority domain untouched.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** `unit` is a `needs:` target for `integration`, `e2e`, `contract`, and `build`. GitHub Actions' default behavior when a `needs:` target is a matrix is to wait for **all** combinations to succeed before downstream jobs run. With 8 combinations (2 node × 4 shard), downstream jobs now wait for all 8 instead of 2. This is a stricter gate, not weaker. No shadowing introduced.
+- **Double-fire:** n/a — the old 2-runner unit matrix was the only thing that ran tests. The new 8-runner matrix replaces it; total test-run count remains "once per Node × shard" (1 per runner).
+- **Races:** each shard runs in its own ephemeral GitHub-hosted runner VM. No shared filesystem, no shared ports, no shared npm cache across shards. No race surface.
+- **Feedback loops:** none. CI result feeds into PR-level required status checks, unchanged by this.
+
+One behavioral nuance worth noting: with `fail-fast: false`, a PR that has genuinely broken tests will now consume 8 runners (all reporting the same failure) instead of 2. Cost is small (GitHub-hosted free minutes; we're not anywhere near the cap), and the upside is clearer diagnostic signal — if only shard-3 fails, the problem is isolated; if all 8 fail, the problem is universal.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** no.
+- **Other users of the install base:** no runtime behavior change. The shipped package is identical byte-for-byte.
+- **External systems:** GitHub Actions runs more matrix combinations. Cost impact for public repos on GitHub-hosted free runners: negligible — Actions minutes are free for public repos. If a private fork is on a paid plan, the extra 6 runners per CI run will show up in billing; flag to callers who fork.
+- **Persistent state:** none touched.
+- **Status check names:** the job name becomes `Unit Tests (node 20, shard 1/4)` etc. instead of `Unit Tests (20)`. Only required status check in the branch ruleset today is `verify`; `Unit Tests` matrix jobs are **not** required checks (confirmed via `gh api repos/JKHeadley/instar/rules/branches/main` on 2026-04-19). So the rename does not break branch protection. If a watcher tool or dashboard specifically hardcoded `Unit Tests (20)` / `Unit Tests (22)` as an expected name, it would need updating — unlikely, but captured here.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. Revert the single `.github/workflows/ci.yml` change — restore the 2-runner matrix and the original `name:` / `run:` lines. No persistent state. No downstream code affected. Worst realistic "wrong" outcome: the shard hash algorithm has a pathological case that leaves one shard with most of the heavy tests, so the wall-clock win is smaller than projected. That's an optimization miss, not a correctness failure — still faster than pre-change, and the remediation is increasing shard count (6 or 8) rather than reverting. Full revert cost: one commit, no migration, no user impact.
+
+---
+
+## Conclusion
+
+Pure CI distribution change with no runtime surface, no decision-point surface, no signal/authority interaction. Preserves the isolation invariant from commit `002a463` by sharding at the runner level instead of re-enabling in-process parallelism. Expected wall-clock win on unit-test phase: 9½ min → ~3 min; overall CI: ~12 min → ~5-6 min (next bottleneck likely integration/e2e, captured as follow-up). Rollback is one revert. Cleared to ship.
+
+---
+
+## Evidence pointers
+
+- Root cause of current serial execution: commit `002a463` (2026-02-28) — "fix(test): disable file parallelism to prevent lock contention". Confirms the isolation problem is real and resource-contention-based; sharding at the VM level is the right remediation.
+- Shard algorithm: [vitest docs — CLI `--shard`](https://vitest.dev/guide/cli.html) — deterministic file-path hash distribution; union of all shards equals the full include set.
+- Required-check topology: `gh api repos/JKHeadley/instar/rules/branches/main` (2026-04-19) shows only `verify` as a required context. Unit-test matrix jobs are observed green on recent PRs but are not ruleset-required.

package/upgrades/side-effects/pre-push-smoke-tier.md

@@ -0,0 +1,235 @@
+# Side-Effects Review — Pre-push smoke tier (changed-files only)
+
+**Version / slug:** `pre-push-smoke-tier`
+**Date:** `2026-04-19`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`.husky/pre-push` now runs `npm run test:smoke` (new script:
+`vitest run --config vitest.push.config.ts --changed origin/main`) instead of
+`npm run test:push`. The new script executes the same excluded/included set
+and same `fileParallelism: false` isolation — the only difference is that
+vitest's `--changed origin/main` filter restricts the run to tests whose
+files (or transitive imports) are in the diff vs. origin/main. The
+pre-push gate (`scripts/pre-push-gate.js` — NEXT.md / version / side-effects
+artifact / contract-evidence / source-without-tests checks) runs first,
+unchanged. Two escape hatches: `INSTAR_PRE_PUSH_FULL=1` (run full push
+suite locally) and `INSTAR_PRE_PUSH_SKIP=1` (skip tests entirely; CI is
+the only gate). Full suite continues to run in CI across 8 sharded
+runners on every PR; CI remains the authority for merge.
+
+Files touched:
+
+- `package.json` — adds `test:smoke` script; bumps version 0.28.59 → 0.28.60.
+- `.husky/pre-push` — switches to `test:smoke` by default, adds env-var
+  escape hatches, keeps the 2-attempt retry loop and the pre-push gate
+  exactly as before.
+- `upgrades/NEXT.md` — upgrade guide (new file at release time).
+- `upgrades/side-effects/pre-push-smoke-tier.md` — this review.
+
+## Decision-point inventory
+
+- `.husky/pre-push` — **modify** — chooses which test script runs based on
+  env vars and falls back to smoke tier by default.
+- `package.json scripts.test:smoke` — **add** — new script, thin wrapper
+  over existing push config with `--changed origin/main`.
+
+No runtime / agent-behavior decision points touched. Strictly contributor-side
+git hook behavior.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+On the runtime / message surface: no block/allow change. The pre-push gate
+is a contributor-side hook, not a runtime gate, so over-block doesn't apply
+in the agent-behavior sense.
+
+On the contributor surface: the smoke tier runs *fewer* tests than the full
+push suite, so it will **accept pushes that the full suite would have
+rejected** — the opposite of over-blocking. See Under-block below.
+
+There is one narrow over-block possibility: if `origin/main` is stale (user
+hasn't fetched recently), the `--changed` diff may include files that are
+already merged, running more tests than strictly needed. We mitigate with
+`git fetch --quiet origin main` inside the hook. If the fetch fails (offline
+push), the diff falls back to whatever the local `origin/main` ref points
+at — worst case runs a few extra tests, still fast.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+This is the real surface to review. Moving from "full suite" to "tests
+affected by changed files" trades thoroughness for speed. Specifically:
+
+1. **Regression in unchanged code** — if your change to file A breaks
+   file B via some runtime-only coupling that vitest's module graph
+   doesn't see (e.g., a serialization format that both sides implement
+   independently), the smoke tier will miss it. CI's full suite on PR
+   will catch it before merge. Net risk: the contributor experiences
+   "passed locally, failed in CI" more often. Cost: one extra CI round
+   trip. Benefit: ~9 minutes saved per push across all pushes that don't
+   break anything (i.e., the vast majority).
+
+2. **Config/global-state files** — if a change touches a file imported by
+   most tests (e.g., a vitest global setup, a shared fixture builder),
+   `--changed` will correctly include the full test set. No extra risk
+   here; the mechanism is self-balancing.
+
+3. **No-change pushes** — pure doc or comment changes produce 0 tests,
+   which is correct. The pre-push gate still enforces NEXT.md presence
+   and side-effects artifact presence independently, so doc pushes that
+   claim a fix/feature still require the corresponding artifact.
+
+4. **Stale local `origin/main`** — if the user hasn't fetched for days,
+   the diff could be larger than reality, but never smaller. Under-block
+   is bounded: you cannot *miss* a file this way, only over-include.
+   We still proactively `git fetch --quiet origin main` inside the hook
+   to keep it tight.
+
+The accepted residual risk is (1). Mitigation: CI is the merge authority
+(per `docs/signal-vs-authority.md`); the pre-push gate is downgraded from
+"implicit authority" to "explicit signal" by this change, which matches
+the architectural principle.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The correct layer is the pre-push hook itself (the boundary where
+we trade speed for confidence on the contributor side). Alternatives:
+
+- **Change vitest.push.config.ts to be smaller** — wrong layer. That
+  config defines "the push suite"; the smoke tier is a *different use*
+  of that same config, selected per-push based on diff size. Keeping
+  two scripts that share one config is cleaner than two configs that
+  overlap.
+- **Change CI to run less** — wrong direction. CI is the authority; it
+  must remain exhaustive or the invariant breaks.
+- **Tag some tests as "smoke" and run only those** — brittle taxonomy
+  that humans would have to maintain. Vitest's `--changed` computes
+  affected tests from the module graph automatically; no taxonomy drift.
+
+Signal-vs-authority reference: `docs/signal-vs-authority.md`. The new
+pre-push hook is a signal consumed by the contributor (and, if they
+push anyway via `INSTAR_PRE_PUSH_SKIP=1`, CI is the binding authority).
+The old hook *was* acting as authority by blocking pushes that CI
+would have caught anyway — same verdict, earlier but slower. Moving
+the authority to CI and keeping a fast signal locally is the correct
+decomposition.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface on message flow or agent behavior.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The pre-push hook is now explicitly a *signal* — it fails the push fast
+when a clearly-affected test regressed, and otherwise lets CI act as
+authority. The `INSTAR_PRE_PUSH_SKIP=1` escape hatch formalizes this:
+contributors can bypass the signal; they cannot bypass CI on the PR.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Pre-push gate (NEXT.md / version / side-effects / contract evidence):**
+  runs *before* the test tier and is unchanged. Smoke tier substitution
+  happens after that gate passes. No interaction risk — orthogonal
+  concerns.
+- **Retry loop:** the 2-attempt retry is preserved, now wrapped around
+  `test:smoke`. Same behavior on flaky failures; just shorter because
+  the retry suite is smaller.
+- **CI (`ci.yml`):** unchanged. Still runs 8 sharded unit-test matrix +
+  integration + e2e + build + type-check on every PR. CI remains the
+  authority on merge-readiness.
+- **Shadowing:** does not exist. CI is not a `needs:` target of the
+  pre-push hook or vice versa; they operate on different events
+  (contributor push vs. GitHub Actions PR event).
+- **Double-fire:** if a contributor has the smoke tier pass and pushes,
+  CI re-runs the full suite — intentional double-gate (fast local
+  signal, authoritative remote). Not wasted work; that's the design.
+- **Races:** none. Contributor-side hook, synchronous, no shared state.
+- **Feedback loops:** if `origin/main` ref moves mid-push, the diff
+  window shifts but the push is a single event; the diff is snapshotted
+  at hook-start time.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** no. The git hook runs only in
+  the contributor's shell during `git push`.
+- **Other users of the install base:** no runtime change. The shipped
+  npm package is unchanged. Only the contributor-side hook installed
+  by `npm install` is affected, and only for people working *in* the
+  instar repo — not consumers of the `instar` package.
+- **External systems:** no.
+- **Persistent state:** none touched.
+- **CI minutes consumption:** unchanged — CI runs the same matrix.
+  If anything, fewer "contributor runs full suite locally, then CI
+  runs it again" iterations means slightly less duplicated load on
+  developer machines.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. Revert the commit that changes `.husky/pre-push` and
+`package.json`. `test:push` is unchanged, so the pre-push hook
+reverts to running the full suite exactly as it did before. No
+migration, no state cleanup, no user-visible impact (since the
+npm package is unaffected).
+
+Partial rollback also available without reverting: set the env var
+`INSTAR_PRE_PUSH_FULL=1` globally (e.g., in the user's shell rc) to
+restore the old blocking behavior without changing any code.
+
+---
+
+## Conclusion
+
+Moves the pre-push test gate from "implicit authority" (slow, exhaustive,
+blocks every push) to "fast signal" (runs only tests affected by the
+diff, CI remains the merge authority). Matches the signal-vs-authority
+architectural principle. Preserves the exclude list, the isolation
+invariant (`fileParallelism: false`), the NEXT.md / version / side-effects
+gate, the retry loop, and the full suite in CI — all authorities stay
+authoritative. Expected wall-clock on a typical small push: ~9 min → <1
+min. Escape hatches for the edge cases. Rollback is one revert. Cleared
+to ship.
+
+---
+
+## Evidence pointers
+
+- `docs/signal-vs-authority.md` — the architectural principle this change
+  aligns the hook with.
+- Vitest `--changed` mode docs:
+  <https://vitest.dev/guide/cli.html#changed> — deterministic, based on
+  module graph, safe to compose with `--config`.
+- CI authority chain: `.github/workflows/ci.yml` — 8-shard unit matrix
+  + integration + e2e + build + type-check; required by branch
+  protection on main (per the ruleset update landed with PR #69).