instar 1.3.197 → 1.3.199

package/upgrades/side-effects/APPRENTICESHIP-STEP1-PROGRAM-SCAFFOLD-SPEC.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Apprenticeship Step 1: Program Scaffold
+
+**Version / slug:** `APPRENTICESHIP-STEP1-PROGRAM-SCAFFOLD-SPEC`
+**Date:** `2026-06-01`
+**Author:** `echo`
+**Second-pass reviewer:** `not required` (converged: 5 internal reviewers + codex gpt-5.5, 3 rounds)
+
+## Summary of the change
+
+Builds Step 1 of the Apprenticeship Program (Tier-3 umbrella #675). Adds the minimal program
+scaffold: an instance-as-project registry + two lifecycle gates (the **retro-gate** = a new
+instance can't transition `pending→active` until the prior instance's retro-harvest validates;
+the **doc-gate** = an instance can't transition `active→complete` until its required artifacts are
+verified present from live state) + the role model. Relocates the Step-0 validator's pure logic to
+`src/core/retroHarvestValidator.ts` (so it's an in-process typed import — the `src`→`scripts/.mjs`
+import the convergence caught couldn't compile).
+
+## Decision-point inventory
+
+Two structural gates (`evaluateStartGate`, `evaluateCompletionGate`) + the status transition table.
+Per Signal vs Authority / The Body and the Mind (spec §3.6), these are **structural preconditions on
+OBJECTIVE artifacts** (does a validated harvest exist? is there an instance-scoped ledger entry?) —
+NOT quality judgments. The *quality* call (did the mentor internalize the lessons / was the audit
+real) stays with the overseer. Every gate verdict is appended to `logs/apprenticeship-decisions.jsonl`.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** A `pending→active` transition with no valid prior/bootstrap
+harvest; an `active→complete` with a missing required artifact; an illegal status transition; a
+duplicate or bad-charset instance id; a `partial-accepted` harvest with no acceptance metadata. All
+are genuine preconditions. The gates are scoped to the program's own instance lifecycle — they never
+block a global action.
+
+## 2. Under-block
+
+**What does this still miss?** The retro-gate enforces *structural* validity only — it trusts the
+harvest's recorded `fidelityReview` stamp (Step 0's independent review was the authority); a forged
+stamp is not re-caught here (stated, §3.3). The doc-gate verifies artifact *presence* from live state,
+not artifact *quality*. `requiredArtifacts` is the checklist definition; truth is always re-derived
+from injected deps, never a stored boolean.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. `ApprenticeshipProgram` is a `src/core` module over a file-based JSON store
+(the `CommitmentTracker` atomic-write + CAS pattern), gates are pure + unit-tested, routes are a
+nullable `RouteContext` field with the standard 503-guard, wired in `AgentServer`. The validator
+relocation matches the `BackfillCore` precedent (pure logic in `src/`, the `.mjs` re-exports for CLI).
+
+## 4. Testing
+
+- **Unit** (`tests/unit/apprenticeship-program.test.ts`, 29): both gates both sides; the status table
+  (legal/illegal/`complete`-terminal); charset clamp + dup-reject; path-confinement (a traversal
+  `harvestRef` is ignored, canonical path used); wiring-integrity (injected deps real, not no-ops);
+  `partial-accepted` with/without acceptance. Plus the validator's 33 cases (repointed to the TS source).
+- **Integration** (`tests/integration/apprenticeship-routes.test.ts`, 10): the routes incl.
+  auth-negative (no/wrong token → 401/403), create→transition gating, the decision-audit line.
+- **E2E** (`tests/e2e/apprenticeship-lifecycle.test.ts`, 3): Phase-1 "feature is alive" —
+  `/apprenticeship/instances` returns 200 through the production `AgentServer` init path.
+- Verified independently: `tsc --noEmit` clean; 62 unit + 15 integration + 3 e2e green; `pnpm build` ok.
+
+## 5. Migration Parity + Agent-Awareness
+
+- **Agent-Awareness:** added to **both** `generateClaudeMd()` (new agents) AND a `migrateClaudeMd()`
+  content-sniff entry in `PostUpdateMigrator` (existing agents) — idempotent, shares the
+  `**Apprenticeship Program**` marker so freshly-init agents aren't double-patched.
+- **Migration Parity:** `.instar/apprenticeship/instances.json` is runtime state (no migration). No
+  config flag (the scaffold is additive + passive + actively needed this run — decided, not conditional).
+- **Bootstrap harvest:** `acceptedBy: justin` + `acceptedAt` added to `echo-to-codey-mentorship.md`
+  (Justin approved Step 0 which contained it) so the retro-gate's `partial-accepted` rule passes; still
+  validates.
+- **Publish:** touches `src/core` + `src/server` + `src/scaffold` → a `NEXT.md` publish fragment is
+  added (`upgrades/next/apprenticeship-step1-program-scaffold.md`, minor bump).
+
+## 6. Rollback
+Revert the commit; `.instar/apprenticeship/instances.json` is runtime state with no migration to undo;
+the validator relocation is behavior-preserving (Step-0 tests pass against the relocated logic).
+
+## 7. Follow-up (CI fix)
+The `capabilities-discoverability` lint requires every new route prefix to be classified. The
+`/apprenticeship` prefix is **agent-facing**, so it is added to `CAPABILITY_INDEX` in
+`src/server/CapabilityIndex.ts` (surfaces in `/capabilities`) rather than `INTERNAL_PREFIXES`. No
+new behavior — classification metadata + the endpoint list for discovery.

package/upgrades/side-effects/fix-bootwrapper-install-path.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Boot-wrapper reinstall: put node on PATH for native postinstalls
+
+**Version / slug:** `fix-bootwrapper-install-path`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 1 (small, well-understood bugfix; ELI16 + side-effects, no converged spec) — but HIGH blast radius (boot shim), reviewed accordingly
+**Parent principle:** Cross-Machine Coherence / Bootstrap Robustness — an agent must be able to self-heal its own install
+
+## Summary of the change
+
+The boot wrapper (`instar-boot.cjs` / `instar-boot.sh`, generated by `installBootWrapper`
+in `src/commands/setup.ts`) self-heals a missing shadow install by running `npm install`.
+That `npm install` was spawned with **no `env` / no PATH augmentation**, so native
+postinstall scripts (e.g. `sharp`: `sh -c "node install/check.js || npm run build"`) ran in
+a subshell whose PATH — under a launchd-spawned boot child — has no `node`/`npm`, dying with
+`command not found`. The reinstall then aborts and the shadow install never heals.
+
+**Observed live (2026-06-02):** a throwaway mini agent could not start — `instar-boot`
+looped on "Shadow install missing", and a manual reinstall reproduced it: it failed on
+`sharp`'s postinstall (`sh: node: command not found`). Re-running with `node` on PATH
+succeeded immediately.
+
+### What changed
+- `src/commands/setup.ts` — `installBootWrapper`:
+  - **`.cjs` (jsWrapper):** the reinstall `execFileSync(nodeBin, [npmCli, 'install', …])` now
+    passes `env: installEnv` where `installEnv` prepends `path.dirname(nodeBin)` to `PATH` and
+    sets `npm_config_scripts_prepend_node_path: 'true'`.
+  - **`.sh` (bashWrapper):** the reinstall now runs with
+    `PATH="$(dirname "$NODE_BIN"):$PATH" npm_config_scripts_prepend_node_path=true` prefixed.
+- `src/core/PostUpdateMigrator.ts` — `migrateBootWrapperAbiCheck`: the "already current" guard
+  now ALSO requires the `npm_config_scripts_prepend_node_path` marker, so existing agents whose
+  wrapper predates this fix are regenerated on update (Migration Parity).
+
+## Decision-point inventory
+- reinstall env: augment vs inherit → augment (prepend node dir + npm flag). Inheriting the
+  launchd PATH is the bug.
+- migration: add a 3rd required marker vs leave 2 → add the marker (otherwise deployed agents
+  with the 2 prior markers never regenerate and never get the fix).
+- auto-re-port / auto-anything else: none — purely the reinstall env.
+
+## 1. Over-correction risk
+The env only AUGMENTS PATH (prepends node dir; keeps the rest) and sets one npm flag. A healthy
+agent never enters the reinstall branch at all (`if (!fs.existsSync(SHADOW))`), so the change is
+inert unless the shadow install is actually missing. `npm_config_scripts_prepend_node_path` is
+npm's own documented option for exactly this case.
+
+## 2. Under-correction risk
+The migration regenerates only wrappers missing the new marker; agents already regenerated stay
+put (idempotent). The `.sh` variant is for manual/Linux use; the launchd-critical path is `.cjs`.
+
+## 3. Level-of-abstraction fit
+The fix lives in the single boot-wrapper generator (`installBootWrapper`) that both `init` and the
+migration call — one source, both consumers. No scattering.
+
+## 4. Signal vs Authority
+Pure deterministic env construction (no LLM/heuristic). Appropriate.
+
+## 5. External surfaces
+None. No route/config-schema change. The generated wrapper gains an env on one spawn.
+
+## 6. Interactions with existing primitives
+The reinstall's debounce marker, the ABI-aware node self-heal, and the version-managed-node
+candidate discovery are all unchanged; this only adds an env to the npm spawn and a 3rd marker
+to the migration's idempotency sniff (composes with the existing two).
+
+## 7. Rollback cost
+Trivial: drop the `env`/PATH additions and the 3rd marker clause. No persistent state.
+
+## Migration parity
+- New agents: `installBootWrapper` (via `init`) writes the fixed wrapper.
+- Existing agents: `migrateBootWrapperAbiCheck` regenerates `instar-boot.cjs` because the new
+  `npm_config_scripts_prepend_node_path` marker is absent. Idempotent — re-running skips once the
+  marker is present.
+
+## Tests
+`tsc --noEmit` clean. `PostUpdateMigrator-bootWrapperAbiCheck` extended to 8 tests (all green):
+the "skip" idempotency case now requires all THREE markers; a new regen case for a wrapper with
+the two prior markers but missing the install-path marker; a generated-content test asserting the
+`.cjs` reinstall passes `env: installEnv` with `npm_config_scripts_prepend_node_path` + the PATH
+prepend AND that the generated `.cjs` passes `node --check` (guards against template-escaping
+bricking the boot shim); a `.sh` generated-content test. 30 sibling boot-wrapper tests
+(`bootWrapperCjs`, `plist-coherence`, `lifeline-shadow-install-self-heal`, `init-join-launchd-handoff`)
+all still green — no regressions.