instar 1.3.875 → 1.3.877

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.875",
+  "version": "1.3.877",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-18T20:25:13.928Z",
-  "instarVersion": "1.3.875",
+  "generatedAt": "2026-07-18T22:29:29.128Z",
+  "instarVersion": "1.3.877",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.876.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added `docs/AI-EMPLOYEE-ROADMAP.md` — the program-level roadmap that maps the
+apprenticeship program onto instar's top-level goal: an agent that works as a
+fully engaged AI employee. It defines the three capabilities that make up that
+posture — multi-machine coherence (3–4 machines, one identity), first-class
+chat-platform citizenship (Telegram today, Slack as the primary workplace
+surface next), and multi-principal service (every staff member served by the
+same agent with no identity bleed) — and lays each out as a stage ladder
+(A1→A4, B1→B3, C1→C3) with an explicit, evidence-gated exit bar. The method is
+prove-it-on-the-apprentice-first: every capability is developed and de-risked
+on a prototype agent under observation, through the same user channels a human
+would use, before any production agent inherits the configuration. Graduation
+is serial and evidence-gated — recorded, artifact-backed acceptances, never a
+vibe.
+
+This is documentation only. No code, config, hook, job, template, or test
+changes; no runtime surface; no behavior change for any deployed agent.
+
+## What to Tell Your User
+
+Nothing changes in how your agent behaves. The project now carries a public
+roadmap document describing where the platform is headed — an agent that works
+like a real employee: present on several machines as one coherent identity, a
+well-mannered citizen of workplace chat (Slack next), and able to serve a whole
+team without mixing people up — and how each step gets proven on a supervised
+prototype before it ever reaches a production agent.
+
+## Summary of New Capabilities
+
+- None (documentation only). New artifact: `docs/AI-EMPLOYEE-ROADMAP.md`, the
+  program-level map from the apprenticeship program to the full AI-employee
+  posture, with evidence-gated graduation criteria per capability.
+
+## Evidence
+
+- `docs/AI-EMPLOYEE-ROADMAP.md` — the roadmap itself (deliberately
+  organization-agnostic for this public repo).
+- `docs/specs/ai-employee-roadmap.eli16.md` — plain-English explainer.
+- `upgrades/side-effects/ai-employee-roadmap.md` — side-effects review; every
+  question resolves to "documentation-only, no runtime surface";
+  multi-machine posture unified-via-git; rollback = revert the doc.
+- Sanity: the whole-tree stall-coverage CI ratchet
+  (`tests/unit/stall-coverage-ratchet.test.ts`) runs green on this tree —
+  the change coexists with the freshly-landed PR-A ratchet.

package/upgrades/1.3.877.md

@@ -0,0 +1,53 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added one section to `docs/apprenticeship/PROGRAM-CONCEPTS.md`: "The
+Hidden-Test Battery (regression tripwires)" — the durable, generic record of
+the mechanism the operator approved on 2026-07-18. The battery is a set of
+undisclosed scenarios that each detect the LOSS of an already-valued behavior:
+passing means nothing broke, never that growth was achieved (growth stays with
+the overseer's judgment). Scenarios stay undisclosed during a drive and are
+scored retrospectively (pass / fail / not-triggered, with evidence pointers)
+as ONE necessary-not-sufficient input to ladder promotions — a failure can
+block a rung, no quantity of passes can earn one. The mechanism itself is
+disclosed to the mentee once (results appear in drive reports the mentee can
+read); only the scenario list stays hidden. The battery is disposable (a
+performed-for scenario is retired; the operator reviews the list at every rung
+change) and guardrailed: never a leaderboard, never a mid-drive threat, never
+a gate on day-to-day work, never scenarios that can harm real users, data, or
+services. Scenarios are preferentially captured from naturally-arising
+situations, manufactured only as a last resort and never on production
+surfaces.
+
+This is documentation only. No code, config, hook, job, template, or test
+changes; no runtime surface; no behavior change for any deployed agent.
+
+## What to Tell Your User
+
+Nothing changes in how your agent behaves. The apprenticeship program's
+documentation now records how regression tripwires work: a small, undisclosed
+set of checks that only ever fire when a learning agent LOSES a good habit it
+already had — never a score to chase, never a leaderboard, never a gate on
+daily work — with results reviewed openly after each drive as one input to
+promotion decisions a human still makes.
+
+## Summary of New Capabilities
+
+- None (documentation only). New content: the "Hidden-Test Battery" section in
+  `docs/apprenticeship/PROGRAM-CONCEPTS.md`, recording the adopted
+  regression-tripwire discipline for the apprenticeship program.
+
+## Evidence
+
+- `docs/apprenticeship/PROGRAM-CONCEPTS.md` — the new section (mechanism only;
+  deliberately no scenario, agent, or organization content).
+- `docs/specs/hidden-test-battery-adoption.eli16.md` — plain-English explainer.
+- `upgrades/side-effects/hidden-test-battery-adoption.md` — side-effects
+  review; every question resolves to "documentation-only, no runtime surface";
+  multi-machine posture unified-via-git; rollback = revert the doc.
+- Sanity: the whole-tree stall-coverage CI ratchet
+  (`tests/unit/stall-coverage-ratchet.test.ts`) runs green on this tree.

package/upgrades/side-effects/ai-employee-roadmap.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — ai-employee-roadmap (docs-only)
+
+**Change:** adds `docs/AI-EMPLOYEE-ROADMAP.md` — the program-level roadmap from
+the apprenticeship program to a full AI-employee posture (multi-machine
+coherence, first-class Slack citizenship, multi-principal service), with
+per-capability stage ladders and evidence-gated exit bars. Plus the standard
+artifacts (this review, the ELI16, the release fragment). **No source, config,
+template, hook, job, or test files are touched.** Documentation-only, no
+runtime surface.
+
+## Phase 1 principle check (recorded)
+
+Does this change involve a decision point? **No.** The document describes a
+program and its graduation criteria; it ships no validator, gate, sentinel, or
+any code that evaluates anything. The graduation decisions it describes are
+explicitly human/overseer acceptances recorded as artifacts — and none of that
+machinery ships here. Signal-vs-authority is not implicated: nothing here can
+block, allow, or judge.
+
+## 1. Over-block
+
+Nothing can be over-blocked: documentation-only, no runtime surface. The change
+introduces no blocking surface of any kind — no CI check, no gate, no hook. The
+only "block" it could ever exert is social (a reader citing the roadmap), which
+is outside the runtime.
+
+## 2. Under-block
+
+Nothing can be under-blocked: documentation-only, no runtime surface. No
+enforcement is promised by this change, so there is no enforcement to be
+incomplete. The exit bars the document names are enforced (or not) by the
+machinery of their own workstreams, each with its own specs and reviews.
+
+## 3. Level-of-abstraction fit
+
+Right layer. A program-level roadmap belongs in `docs/` at the repo root
+(`docs/AI-EMPLOYEE-ROADMAP.md`), above the individual capability specs it
+references and below nothing — it is the map that points at the specs, not a
+duplicate of any of them. It deliberately contains no schedule and no
+organization-specific content (agent names, staffing, rollout order stay with
+the operator, outside this public repo).
+
+## 4. Signal vs authority compliance
+
+Compliant vacuously: documentation-only, no runtime surface. The change creates
+no authority (nothing blocks) and no signal (nothing observes). The document
+itself *describes* the signal→authority discipline of the apprenticeship
+(observe-only guards graduating to enforcing on evidence), which is consistent
+with `docs/signal-vs-authority.md`, but describing it is not implementing it.
+
+## 5. Interactions
+
+None at runtime: documentation-only, no runtime surface. No job, sentinel,
+route, or hook reads this file. Repo-level interactions are benign: it cites
+existing specs (e.g. the apprenticeship scaffold spec, framework stall-coverage
+work) by path; if those move, the references go stale — a docs-freshness
+concern (the cartographer sweep's domain), not a behavior risk.
+
+## 6. External surfaces
+
+None: documentation-only, no runtime surface. No API route, no config key, no
+message to any user, no notification, no npm-shipped runtime change (the file
+rides the package inertly as documentation). The document was deliberately
+written organization-agnostic for this public repo — it names no organization,
+person, or deployed agent.
+
+## 7. Multi-machine posture
+
+**Unified-via-git.** The document is a repo-tracked file; every machine sees
+the same content at the same SHA. No per-machine runtime state is created, so
+there is nothing to strand, sync, or reconcile.
+
+## 8. Rollback cost
+
+Revert the doc (one revert of this commit). No data migration, no agent state,
+no config, no deployed-behavior change to unwind. Cheapest possible rollback
+class.
+
+## Second-pass review
+
+**Not required.** The second-pass trigger is for changes that wire
+block/allow decisions, session-lifecycle, messaging, or dispatch behavior —
+this change wires nothing: documentation-only, no runtime surface, no decision
+point, no enforcement. There is no code for a second reviewer to contradict
+against the artifact; the only reviewable claim ("the doc says what the ELI16
+and fragment say it says") is verified by reading the three files side by side.

package/upgrades/side-effects/hidden-test-battery-adoption.md

@@ -0,0 +1,89 @@
+# Side-Effects Review — hidden-test-battery-adoption (docs-only)
+
+**Change:** appends one section — "The Hidden-Test Battery (regression
+tripwires)" — to `docs/apprenticeship/PROGRAM-CONCEPTS.md`, recording the
+operator-approved (2026-07-18) mechanism generically: undisclosed regression
+tripwires over already-valued behaviors, scored retrospectively as one
+necessary-not-sufficient input to ladder promotions, disposable, guardrailed.
+Plus the standard artifacts (this review, the ELI16, the release fragment).
+**No source, config, template, hook, job, or test files are touched.**
+Documentation-only, no runtime surface.
+
+## Phase 1 principle check (recorded)
+
+Does this change involve a decision point? **No.** The section describes an
+evaluation discipline whose verdicts are produced by humans (operator/overseer)
+in retrospective review; it ships no validator, gate, sentinel, scorer, or any
+code that evaluates anything. Signal-vs-authority is not implicated: nothing
+here can block, allow, or judge — and the described mechanism itself is
+explicitly bounded to "can block a rung, never earn one", a human-held
+authority outside this repo's runtime.
+
+## 1. Over-block
+
+Nothing can be over-blocked: documentation-only, no runtime surface. The change
+introduces no blocking surface of any kind — no CI check, no gate, no hook. The
+described discipline explicitly forbids gating day-to-day work on tripwire
+results, and even that prohibition is prose, not enforcement.
+
+## 2. Under-block
+
+Nothing can be under-blocked: documentation-only, no runtime surface. No
+enforcement is promised by this change, so there is no enforcement to be
+incomplete. If the battery discipline is ever mechanized (a scenario registry,
+a scoring surface), that work arrives with its own spec and its own review.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The mechanism is a program-level concept, and
+`docs/apprenticeship/PROGRAM-CONCEPTS.md` is exactly the canonical home for
+operator-ratified program framings (it already holds five). The section stays
+generic by design — no concrete scenario, no agent name, no organization
+specifics — because scenario content is operator-held and undisclosed by the
+mechanism's own rules; putting scenarios in a public repo doc would break the
+mechanism it documents.
+
+## 4. Signal vs authority compliance
+
+Compliant vacuously: documentation-only, no runtime surface. The change creates
+no authority (nothing blocks) and no signal (nothing observes). The documented
+mechanism is itself shaped by the signal-vs-authority principle — tripwire
+results are a signal into a human promotion decision, never an authority that
+gates work — but describing that shape is not implementing it.
+
+## 5. Interactions
+
+None at runtime: documentation-only, no runtime surface. No job, sentinel,
+route, or hook reads this file. Repo-level interactions are benign: the new
+section closes the "bounded adoption" left open by the same file's concept 5
+(evaluation cautions), and coexists with it — concept 5 records the caution,
+the new section records the adopted mechanism that satisfies it.
+
+## 6. External surfaces
+
+None: documentation-only, no runtime surface. No API route, no config key, no
+message to any user, no notification, no npm-shipped runtime change (the file
+rides the package inertly as documentation). The section was deliberately
+written mechanism-only for this public repo — it names no scenario, agent,
+person, or organization.
+
+## 7. Multi-machine posture
+
+**Unified-via-git.** The document is a repo-tracked file; every machine sees
+the same content at the same SHA. No per-machine runtime state is created, so
+there is nothing to strand, sync, or reconcile.
+
+## 8. Rollback cost
+
+Revert the doc (one revert of this commit). No data migration, no agent state,
+no config, no deployed-behavior change to unwind. Cheapest possible rollback
+class.
+
+## Second-pass review
+
+**Not required.** The second-pass trigger is for changes that wire block/allow
+decisions, session-lifecycle, messaging, or dispatch behavior — this change
+wires nothing: documentation-only, no runtime surface, no decision point, no
+enforcement. There is no code for a second reviewer to contradict against the
+artifact; the only reviewable claim ("the section says what the ELI16 and
+fragment say it says") is verified by reading the three files side by side.