instar 1.3.2 → 1.3.3

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-26T21:00:08.875Z",
-  "instarVersion": "1.3.2",
+  "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.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/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.