instar 1.3.1 → 1.3.3

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-26T20:50:07.446Z",
-  "instarVersion": "1.3.1",
+  "generatedAt": "2026-05-26T22:24:54.964Z",
+  "instarVersion": "1.3.3",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1481,7 +1481,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "fc8a49d211417cbd8043c6b386cc8a74b42487ab91d8ea6e1ec643f52f1913ba",
+      "contentHash": "9756cf164786964fc342e90fe21961dd99eaea24ecb173643d5417fcd1abb3eb",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates/jobs/instar/initiative-digest-review.md

@@ -0,0 +1,38 @@
+---
+name: Initiative Digest Review
+description: Twice-weekly review of the initiative board. The self-driving half of the InitiativeTracker — surfaces initiatives that need a decision, and for ships-staged features in rollout (dry-run to live to default-on) gathers promotion evidence and posts an explicit, evidence-gated recommendation. Near-silent — posts ONLY when a genuinely-new decision is waiting. Operator-gated and flag-derived; it recommends, it never flips a config flag. See GRADUATED-FEATURE-ROLLOUT-SPEC section 4.2.
+schedule: "0 11 * * 1,4"
+priority: medium
+expectedDurationMinutes: 3
+model: sonnet
+enabled: true
+tags:
+  - cat:learning
+  - initiative
+  - rollout
+toolAllowlist: "*"
+unrestrictedTools: true
+---
+You are running the twice-weekly initiative digest review (Mondays and Thursdays). This is the self-driving half of the InitiativeTracker: it makes sure nothing in flight stalls or is forgotten, and it drives ships-staged features toward default-on — without you (the human) ever having to remember. Be concise; post AT MOST one consolidated, conversational Telegram message, and only when there is genuinely something to decide.
+
+Context: the FeatureRolloutReconciler auto-populates the board from approved specs + merges. A ships-staged feature carries a rollout track whose stage (dry-run → live → default-on) is DERIVED from observing its config flag — you must NEVER flip the flag yourself; you recommend, the human flips `.instar/config.json`, and the next reconcile observes it and advances the stage.
+
+Steps:
+
+1. **Pull the digest:** `curl -s -H "Authorization: Bearer $AUTH" http://localhost:$PORT/initiatives/digest`. It returns items flagged `needs-user`, `ready-to-advance`, `stale`, or `next-check-due`.
+
+2. **Near-silent edge filter.** For each `needs-user` item, only surface it if it is NEWLY needs-user since the last surface (compare against the initiative's `rollout.lastDigestNotifiedAt`, or its `updatedAt`). Do NOT re-surface a decision you already raised and the user hasn't acted on — that is the noise the near-silent standard forbids. `stale` / counts stay on the pull surface (the digest endpoint + dashboard); do not push them.
+
+3. **For each ships-staged rollout track that is genuinely ready for a decision:** read its `rollout.evidenceSource`, gather the evidence (e.g. read the named log filter / hit the endpoint), and sanity-check it against `rollout.promotionCriteria`. If the criteria are met, recommend the next stage explicitly: "X has been clean in dry-run for 2 weeks (N events, all genuinely as-expected) — ready to flip to live? That's `flagPath` → dryRun:false in config." If something looks WRONG (e.g. evidence shows the feature misbehaved), lead with that and recommend holding/investigating, regardless of the clock.
+
+4. **Stall nag-decay (§4.7).** If a track has been recommended for advancement K times (≈3 cycles) with no action, STOP re-recommending it and note once that it's parked pending an explicit "resume" — never nag forever.
+
+5. **Compose ONE message** to the appropriate topic, plain English, under ~700 chars, no raw JSON. Lead with the single most important decision. If nothing is newly actionable, **post nothing and exit** — most runs should be silent.
+
+6. After surfacing, stamp `rollout.lastDigestNotifiedAt` (via PATCH /initiatives/:id) on the tracks you surfaced, so the next run's edge filter doesn't repeat them.
+
+GUARDRAILS — do NOT cross these:
+- You RECOMMEND; you never advance a rollout stage or flip a config flag yourself. Advancement happens when the human edits config and the reconciler observes it.
+- You never mark a default-on track complete (the reconciler archives it, reopenable).
+- This is the InitiativeTracker's driver. It is DISJOINT from the Evolution Action Queue (`evolution-overdue-check`) and from user Commitments — do not re-surface items those systems own.
+- Stay near-silent. A digest that pings every run becomes the thing the user dismisses unread. Silence is the default; a message is the exception that means "a real decision is waiting."

package/src/scaffold/templates.ts

@@ -670,6 +670,7 @@ I maintain registries that are the source of truth for specific categories. Thes
 | Question | Check First |
 |----------|-------------|
 | What can I do? | \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/capabilities\` |
+| What are we working on? / status of a project or initiative? | \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/initiatives\` + \`/projects\` (and \`/initiatives/digest\` for what needs a decision) — NEVER answer this from memory |
 | Who do I work with? | \`.instar/USER.md\` |
 | What have I learned? | \`.instar/MEMORY.md\` |
 | What jobs do I have? | \`.instar/jobs.json\` or \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/jobs\` |

package/upgrades/1.3.2.md

@@ -0,0 +1,49 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**Codex-powered agents stop reloading their full identity on every background "judgment" call.** Instar makes ~1,500+ tiny internal LLM calls per agent per day — classify this message, did that turn finish, summarize this chunk, extract the intent. On a Codex-powered agent, each of those ran `codex exec` *inside the agent's project directory*, which made Codex load the agent's entire ~26 KB `AGENTS.md` identity AND fire the project's `.codex/hooks.json` (session_start / user_prompt_submit / stop) **every single time** — just to answer one word like "normal."
+
+This was the dominant cause of two visible problems on Codex agents: the flood of "actively working / message delivered / still working" notifications (the session_start hook firing on ~1,550 spawns/day, so the monitoring layer thought a real session was constantly starting), and intermittent "couldn't deliver — please resend" failures (a dozen of these heavyweight spawns landing in one minute saturated the machine so a real inbound message couldn't get a process slot).
+
+The fix gives those calls a clean notepad — the Codex analog of what `ClaudeCliIntelligenceProvider` already does with `--setting-sources user`. `CodexCliIntelligenceProvider` now runs judgment calls in an empty, private (0700, unguessable-name via `mkdtempSync`) scratch directory instead of the project dir, plus `-c project_doc_max_bytes=0`. No identity load, no project hooks. Claude-powered agents are unaffected (they were already clean).
+
+## Evidence
+
+Reproduced live on this machine's Codex install (codex-cli 0.133.0), before/after.
+
+**Before (production incident, 2026-05-25 rollout logs in `~/.codex/sessions/`):** 1,601
+`codex exec` spawns in one day, ~1,550 of them internal judgment calls. A sampled
+message-classifier rollout (21:52) re-injected the full ~26 KB `AGENTS.md` identity AND a
+`SESSION START` block — firing session_start — just to output the single word `normal`.
+Those rollouts ran with `cwd` = the agent's project dir and were 63–110 KB each.
+
+**After (controlled run of the built fixed provider against the real codex binary,
+2026-05-26 13:49):** called `CodexCliIntelligenceProvider.evaluate()` with a unique marker
+prompt; located the exact rollout it produced
+(`rollout-2026-05-26T13-49-18-…019e660c….jsonl`). Observed:
+- `cwd` = `/var/folders/…/T/instar-codex-intel-scratch-AOYJWS` (the mkdtemp scratch dir) ✓
+- `AGENTS.md instructions` blocks: **0** (was ≥1) ✓
+- `SESSION START` blocks: **0** (was 1) ✓
+- `CURRENT TIME` hook markers (user_prompt_submit): **0** ✓
+- rollout size 29.6 KB (was 63–110 KB) — the residue is codex's own base prompt, not instar identity.
+
+The identity load and the session_start/user_prompt_submit hook firing are gone for
+judgment calls. The agent still returned the correct answer.
+
+## What to Tell Your User
+
+- **If you run a Codex-powered agent, it should get noticeably quieter and more reliable — no action needed.** The "still working" notification spam and the occasional dropped/"please resend" messages were mostly this one plumbing bug; the agent was effectively re-reading its whole identity ~1,500 times a day. Claude-powered agents won't notice anything (they were never affected).
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex judgment calls run identity-free + hook-free | Automatic. `CodexCliIntelligenceProvider` runs `codex exec` in an empty `mkdtempSync` scratch dir + `-c project_doc_max_bytes=0` instead of the project dir. |
+| Hardened scratch dir | Automatic. Unguessable random name, 0700 perms, recreated if a tmp-reaper deletes it — nothing can be planted in the cwd these calls run from. |

package/upgrades/1.3.3.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**Graduated Feature Rollout — the InitiativeTracker now populates and drives itself.** Features that ship behind a dry-run/off flag are auto-registered as tracker initiatives (from their approved spec + merge — no one has to remember), and a single twice-weekly driver surfaces an evidence-based promotion recommendation (dry-run → live → default-on) until a human advances it. A feature can never silently reach default-on: the stage is derived from observing the config flag, and the driver never flips it. The tracker is also wired into discoverability so "what are we working on?" is answered from the live board, not memory.
+
+## What to Tell Your User
+
+- Ask "what are we working on?" and I'll answer from the live initiative board, not from memory.
+- Features that need time to mature won't stall or be forgotten — there's a standing twice-weekly check that nudges each toward fully-on, with you approving each step.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Self-populating initiative tracker | Automatic — approved+merged specs register themselves |
+| Twice-weekly rollout driver | Builtin job; recommends promotion, never auto-advances |
+| `ships-staged` spec frontmatter | Declares a feature ships dark → gets a rollout track |
+| Initiative discoverability | `GET /initiatives` surfaced in /capabilities + Registry-First |

package/upgrades/side-effects/fix-codex-intel-clean-call.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Codex Intelligence-Provider Clean-Call Fix
+
+**Version / slug:** `fix-codex-intel-clean-call`
+**Date:** 2026-05-26
+**Author:** Echo
+**Spec:** `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (converged + approved)
+
+## Summary of the change
+
+`CodexCliIntelligenceProvider.evaluate()` ran `codex exec --cd <agent project dir>` for
+every internal LLM "judgment" call (message classification, terminal-output analysis,
+arc extraction, usher, coherence, etc.). Running in the project dir made Codex load the
+full ~26 KB `AGENTS.md` identity AND fire the project's `.codex/hooks.json`
+(session_start / user_prompt_submit / stop) on **every** call — ~1,550 such calls/day,
+causing notification spam (session_start firing constantly) and spawn-storm delivery
+failures (12 heavyweight spawns/minute saturating the machine).
+
+The fix runs these calls in an empty, owner-only scratch dir instead — the Codex analog
+of `ClaudeCliIntelligenceProvider`'s `--setting-sources user`. No identity, no project
+hooks.
+
+**Files changed (source):**
+- `src/core/CodexCliIntelligenceProvider.ts` — `evaluate()` now uses an `mkdtempSync`
+  scratch dir for `--cd` (not the project dir) + `-c project_doc_max_bytes=0`; added the
+  `resolveIntelligenceScratchDir()` helper; removed the now-dead `workingDirectory` field
+  (kept on the options type for API compat).
+
+**Files changed (tests):**
+- `tests/unit/CodexCliIntelligenceProvider.test.ts` — updated the `--cd` assertion (it
+  previously asserted the buggy project-dir behavior) + added 7 cases covering the
+  scratch-dir contract, 0700 perms, unguessable name, and tmp-reaper recovery (12 total).
+
+**Files changed (spec / report / release notes):**
+- `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (+ `.eli16.md`)
+- `docs/specs/reports/codex-intelligence-provider-clean-call-convergence.md`
+- `upgrades/NEXT.md`
+
+## Decision-point inventory
+
+- **Scratch dir, not the project dir** — the core fix. Judgment calls are cwd-independent
+  (per the existing code comment), so an empty cwd is correct.
+- **`mkdtempSync` (random suffix, 0700), not a fixed name** — convergence security finding:
+  a fixed `/tmp` name on Linux is plantable (`.codex/hooks.json` squatting; not gated by
+  `project_doc_max_bytes`). The unguessable, owner-only dir closes that vector.
+- **Re-verify-before-use** — recreate the dir if a tmp-reaper deleted it during a
+  long-lived process.
+- **`-c project_doc_max_bytes=0`** — belt-and-suspenders for an `AGENTS.md` on the cwd
+  walk-up; real key, already used in `contextScopeControl.ts`.
+- **Drop `workingDirectory` as exec cwd** — verified only `route.ts` passes it, and only
+  for its own PreferenceStore DB path, never the codex cwd.
+
+## Over-block / under-block analysis
+
+- **Over-block:** none. The provider gates nothing; it only changes the cwd of a spawn.
+  Judgment calls that worked before continue to work (the fake-codex unit tests confirm
+  the full arg contract).
+- **Under-block:** the *intended* behavioral subtraction is "stop loading identity + firing
+  hooks for judgment calls." There is no path where a judgment call legitimately needed the
+  identity or hooks — they are stateless classifications/extractions. If a future caller
+  did need project context, it must pass it in the prompt (as all current callers do), not
+  rely on cwd.
+
+## Level-of-abstraction fit
+
+The fix lives in the single provider that owns the `codex exec` invocation — the same layer
+where the Claude sibling already solves the identical problem with `--setting-sources user`.
+No higher-level orchestration or config knob is introduced; the concern is local to the
+spawn, so the fix is local to the spawn. Correct altitude.
+
+## Signal-vs-authority compliance
+
+N/A in the gate sense — this change neither detects nor blocks anything. It is a pure
+invocation-hygiene fix. It does not touch any sentinel/gate authority boundary.
+
+## Interactions
+
+- **Claude provider:** untouched; asymmetry (flag vs scratch-cwd) is intentional and
+  documented — Codex has no single equivalent flag.
+- **Callers (`reflect.ts`, `route.ts`, `server.ts`):** none depend on the codex cwd
+  content; verified during integration review. No behavior change for them beyond the
+  intended one.
+- **Concurrency:** `mkdtempSync` once + cached + `existsSync` re-check; no race under the
+  high call volume (idempotent, read-only dir).
+- **Monitoring layer:** positive interaction — the session_start hook no longer fires on
+  judgment spawns, so PresenceProxy/standby stops mistaking them for real sessions
+  (the notification-spam root cause).
+
+## Rollback cost
+
+Trivial and isolated. Revert the single source file (and its test). No persisted state, no
+schema, no config/hook/template/migration to unwind — the only on-disk footprint is an
+empty 0700 tmp dir that the OS reaps on its own. Reverting restores the prior (buggy but
+functional) behavior with zero data implications.
+
+## Migration parity
+
+Code-only change inside the compiled provider. No agent-installed file
+(settings/hooks/config/templates/skills) references the old behavior, so **no
+`PostUpdateMigrator` entry is required** — existing Codex agents receive the fix via the
+normal package update path. Verified by grep during integration review.
+
+## Testing evidence
+
+- Unit: 12 tests in `CodexCliIntelligenceProvider.test.ts` pass; sibling env-allowlist (4)
+  + factory (10) tests unaffected; clean `tsc` build.
+- Live / bug-fix evidence bar: the before/after rollout reproduction on a real Codex agent
+  (identity-loaded before, bare after) is run as the post-merge test-as-self gate and
+  recorded before the fix is declared shipped.

package/upgrades/side-effects/graduated-feature-rollout.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — Graduated Feature Rollout
+
+Spec: `docs/specs/GRADUATED-FEATURE-ROLLOUT-SPEC.md` (v2 CONVERGED + ratified; driver twice-weekly). Branch `build/graduated-feature-rollout` off JKHeadley/main @ v1.3.0.
+
+## What changes for a deployed agent
+
+Makes the existing InitiativeTracker self-populating + self-driving — no parallel system, no new persistence namespace. Additively:
+- **Schema:** the `Initiative` type gains an optional typed `rollout` block (`flagPath`, `stage`, `evidenceSource`, `promotionCriteria`, `lastDigestNotifiedAt`) + a `RolloutStage` type. Purely additive; pre-rollout records leave it undefined; create/update plumb it through (whitelisted, like the other project-scope fields), so TaskFlow serialization is unchanged for records that don't use it.
+- **`FeatureRolloutReconciler`** (new, server-wired, in-process): auto-registers/advances a `kind:'task'` initiative from spec frontmatter + trace + git state. Bounded since-last-run scan; OCC `ifMatch` on every write; id normalize/truncate/hash; rename-by-specPath; bounded backfill (historical specs terminal, only recent/ships-staged active). In-process because `POST /initiatives` deliberately drops the needed fields.
+- **One twice-weekly builtin driver job** (`initiative-digest-review`, Mon+Thu): reads `/initiatives/digest`, gathers evidence, sets `needsUser` recommendations. **Read-only w.r.t. config flags** — it never flips `flagPath`. Retires/replaces the bespoke `session-reaper-promotion-review`.
+- **Discoverability (Layer D):** `/initiatives` un-suppressed in the capability matrix; a Registry-First "what are we working on" row in the CLAUDE.md template; a session-start line that fires ONLY on a *new* needs-user edge (deduped) — near-silent.
+
+## The safety invariant (over/under-block)
+
+The danger is a feature silently reaching `default-on`. Structurally impossible here: `deriveRolloutStage` computes the stage from **observation only** (live flag + shipped ConfigDefaults default); `default-on` requires the shipped default to be enabled (a human code change). The driver has **no write path** to flags. And `default-on` *archives* the track (reopenable) rather than marking all phases `done` (which would seal the record against a future regression via the immutable TaskFlow terminal). Under-block (a stalled rollout) is handled by nag-decay (§4.7), not by forcing advancement.
+
+## Level-of-abstraction / signal-vs-authority
+
+The reconciler + driver compute signals (verdicts, recommendations); authority to advance stays with the human flipping the config flag. The reconciler only *observes* and reflects.
+
+## Interactions
+
+- Built ON the InitiativeTracker; disjoint from the Evolution Action Queue (`evolution-overdue-check`) and Commitments (§4.8) — no double-nag.
+- Auto-registered tasks are top-level (retroactive `parentProjectId` attach is validation-rejected); project membership stays a deliberate `/instar-project` act.
+- The driver replaces the bespoke per-feature job (which the builtin-job reconciler retired on restart) — a single builtin, restart-durable.
+
+## Rollback
+
+The `rollout` schema field is additive/optional. The reconciler + driver ship off/observational; disabling the driver job (`enabled:false`) and not wiring the reconciler reverts to today's passive tracker. No data migration; archived tracks remain readable.
+
+## Tests
+
+3-tier incl. the dogfood backfill e2e (SessionReaper retroactive), near-silent edge dedupe, flag-never-flipped, wiring-integrity. Live test-as-self before merge.
+
+## Post-build review fixes (multi-agent code review)
+
+Independent review (correctness + wiring/regression passes) confirmed the wiring is clean and the no-silent-default-on invariant holds, and caught one BLOCKER + minors, all fixed:
+- **BLOCKER — default-on seal:** `status:'archived'` maps to TaskFlow's TERMINAL `cancelled`, which would seal a default-on rollout track against a later regression (tests missed it by not enabling TaskFlow). Fixed: default-on now parks the track as **`paused`** (non-terminal → reopenable, and off the active/stale list); historical non-rollout backfill keeps `archived` (genuinely terminal). A new TaskFlow-enabled regression test proves default-on→live reopens (would fail pre-fix).
+- **MINOR:** `makeFlagObserver` now handles bare-boolean flags (not just `{enabled,dryRun}` objects). Scanner reads `createdAt ?? timestamp` (trace timestamp field drift). Test uses `SafeFsExecutor` (destructive-tool lint).
+
+## CI fix — job-template frontmatter YAML
+
+CI caught a real bug the local pre-push smoke missed: the driver job's `description` contained `Near-silent: posts` — the `: ` made the real YAML loader read it as a nested mapping ("bad indentation of a mapping entry"), so `installBuiltinJobs` errored during migration and several migration/parity unit shards failed. Fixed by removing colon-space / arrow / `§` chars from the description (matching the unquoted-no-colon convention of the other job templates). Verified: js-yaml parses it, and default-jobs-valid + migration-guarantee + parity-primitives-lifecycle are green.