instar 1.3.198 → 1.3.200

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/session-clock-step1.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Session Clock Step 1 (SessionClock + GET /session/clock)
+
+**Slug:** `session-clock-step1`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Tier:** 2 (driven by the converged + approved spec `ROBUST-SESSION-TIME-AWARENESS-SPEC.md`)
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` (review-convergence iteration 3, approved)
+
+## Summary of the change
+
+Step 1 of the time-awareness fix: the compute + query surface.
+- `src/core/SessionClock.ts` — pure tier0 module: `computeSessionClock(input, nowMs)` (elapsed/remaining with clock-skew clamping + the status matrix), `deriveLabel(goal)` (the sanitized, cap-80, control-char/angle-bracket-stripped label that is the ONLY task text ever injected/served), `humanizeDuration`.
+- `src/core/SessionClockReader.ts` — read-only I/O layer: maps ACTIVE autonomous-state records → computed clocks, with optional topic binding. Reuses `AutonomousSessions.activeAutonomousJobs()`.
+- `src/core/AutonomousSessions.ts` — `AutonomousJobSummary` gains `durationSeconds` (parsed from the existing `duration_seconds` front-matter field). Additive.
+- `src/server/routes.ts` — new read-only `GET /session/clock` (optional `?topic=N`). Bearer-gated (inherits app-wide auth). Leak-bounded: returns the computed clock + sanitized `label` only, never the raw `goal`.
+- `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` — CLAUDE.md "Session Clock" awareness (template for new agents; content-sniffed `migrateClaudeMd` block for existing agents).
+
+## Decision-point inventory
+- route exposure: read vs write → read-only (GET only; POST → 404). No gate, no mutation.
+- label: inject raw goal vs derived → derived + sanitized + capped. The raw goal never leaves the record.
+- record field: `end_at` vs `started_at`+`duration_seconds` → the latter (canonical, matches the stop-hook + setup-autonomous.sh schema); `endsAt` is derived.
+
+## 1. Over-correction risk
+None — purely additive observability. No existing behavior changes. A healthy agent with no time-boxed record gets `{ sessions: [] }`.
+
+## 2. Under-correction risk
+Step 1 is the QUERY surface only; the per-turn INJECTION (the higher-impact fix for the incident) is Step 2 (emit-session-clock.sh + hooks), a separate PR. Documented in the spec sequencing.
+
+## 3. Level-of-abstraction fit
+Compute is pure (SessionClock.ts, no I/O, fully unit-tested both sides of every boundary); I/O is isolated (SessionClockReader.ts); the route is a thin reader. The record-enumeration reuses the existing AutonomousSessions module rather than duplicating frontmatter parsing.
+
+## 4. Signal vs Authority
+Tier0, deterministic, no LLM, no gate. Pure computation + a read route. Appropriate.
+
+## 5. External surfaces
+One new read-only HTTP route (`GET /session/clock`), Bearer-gated like `/tokens/summary`. **Leak-bound:** the response carries the sanitized `label` only — never the raw `goal`/task text (verified by integration + E2E assertions). No config/schema change.
+
+## 6. Interactions with existing primitives
+`AutonomousJobSummary.durationSeconds` is additive (existing consumers unaffected — AutonomousSessions unit tests still green). The route composes with the existing auth middleware. No change to the autonomous-state writer or the stop-hook.
+
+## 7. Rollback cost
+Trivial: remove the route + the two new modules + the additive `durationSeconds` field + the CLAUDE.md block. No persistent state, no migration of data.
+
+## Migration parity
+- New agents: the route ships in code; the CLAUDE.md template carries the awareness.
+- Existing agents: the route reaches them on the normal dist update (code); `migrateClaudeMd` content-sniffs `/session/clock` and appends the awareness block (idempotent).
+
+## Tests (all three tiers)
+- Unit: `SessionClock` (14 — full status matrix, clock-skew clamp, label derivation/sanitization incl. `<promise>`-token stripping + cap-80) + `SessionClockReader` (6 — record parsing, topic binding, goal→label end-to-end, missing dir).
+- Integration: `session-clock-route` (4 — 200 with computed fields, `{sessions:[]}` when none, topic filter, leak-bound: raw goal never in the response).
+- E2E: `session-clock-lifecycle` (4 — real AgentServer boot, route alive 200 not 503, leak-bound, Bearer required, read-only POST→404).
+- No regressions: AutonomousSessions (13) + migrateClaudeMd (3) still green; `tsc --noEmit` clean.