instar 1.3.455 → 1.3.457

package/upgrades/1.3.457.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added Slice 2 of the dev-agent dark-gate conformance guard: a
+`DEV_GATED_FEATURES` registry (`src/core/devGatedFeatures.ts`) and a both-sides
+wiring test that applies the REAL config defaults and asserts each registered
+dev-gated feature resolves LIVE under a `developmentAgent: true` config and DARK
+under a fleet config. This catches the half of the #1001 bug that Slice 1's lint
+can't see — a feature whose shipped default hardcodes `enabled: false` (so
+`applyDefaults` injects it) now fails the build, because the feature would be dark
+on dev agents. Seven features are registered; two (`mcpProcessReaper`,
+`resourceLedger`) are deliberately excluded with documented reasons (intentionally
+not dark-on-fleet).
+
+## What to Tell Your User
+
+Nothing user-facing — internal developer/CI tooling (audience: agent-only). No
+runtime behavior changes; it only adds a test that guards the dev-gate convention.
+
+## Summary of New Capabilities
+
+- `DEV_GATED_FEATURES` registry + `getConfigByPath` (`src/core/devGatedFeatures.ts`).
+- `tests/unit/devGatedFeatures-wiring.test.ts` — both-sides wiring test (+ a teeth
+  test proving it catches a planted `enabled: false` regression).
+- Honest limit: Slice 3 (spec-intent cross-check) still catches the
+  forgot-the-gate-entirely case; tracked as CMT-1253. <!-- tracked: CMT-1253 -->
+
+## Evidence
+
+This is a preventive CI guard, not a runtime bug fix — so "evidence" is a
+demonstration that the guard has teeth on the #1001 mechanism:
+- **Before (no guard):** a dev-gated feature whose shipped default hardcodes
+  `enabled: false` ships dark on dev agents undetected — exactly #1001, which was
+  caught only by operator review.
+- **Reproduction (guard fires):** copied `src/config/ConfigDefaults.ts`, injected
+  `enabled: false` as the first field of the real `growthAnalyst` block, and ran
+  the both-sides test → the live-on-dev assertion **FAILS** (red). A baked-in
+  `enabled: true` would fail the dark-on-fleet assertion instead.
+- **After (clean tree):** the unmodified tree → **16/16 green** (no registered
+  feature currently hardcodes a default). So the guard fires on the regression and
+  stays quiet otherwise.

package/upgrades/side-effects/dev-agent-dark-gate-lint.md

@@ -0,0 +1,104 @@
+# Side-Effects Review — Dev-Agent Dark-Gate Conformance Guard (Slice 1)
+
+**Change:** Add a structural guard for the `developmentAgent` dark-feature gate
+so a feature can't ship dark on dev agents by hand-rolling/forgetting the gate
+(the PR #1001 miss). Slice 1:
+- `src/core/devAgentGate.ts` — `resolveDevAgentGate(explicit, config)` funnel
+  (`explicit ?? !!config?.developmentAgent`).
+- `scripts/lint-dev-agent-dark-gate.js` — assertion A (no hand-rolled
+  `?? !!<x>.developmentAgent` outside the funnel) + assertion B (no hardcoded
+  `enabled: false` under a dev-gate marker comment in `ConfigDefaults.ts`).
+  Wired into the `lint` npm script (Repo Invariants CI).
+- Migrated the 11 existing hand-rolled sites in `src/server/AgentServer.ts`,
+  `src/commands/server.ts`, and `src/server/routes.ts` to the funnel
+  (behavior-identical). Assertion B is brace-matched on the config block (not a
+  fixed line window) — the fix for the convergence-review finding that a long
+  marker comment hid the growthAnalyst block from the original window.
+
+**Files:**
+- `src/core/devAgentGate.ts` (new), `tests/unit/devAgentGate.test.ts` (new, 8).
+- `scripts/lint-dev-agent-dark-gate.js` (new), `tests/unit/lint-dev-agent-dark-gate.test.ts` (new, 7).
+- `src/server/AgentServer.ts`, `src/commands/server.ts`, `src/server/routes.ts` — 11 call sites + imports.
+- `scripts/lint-no-direct-destructive.js` — allowlist the new lint (reads
+  `git diff --cached` for `--staged`, same as its siblings).
+- `package.json` — `lint` script + two convenience scripts.
+- `tests/unit/growth-analyst-gate-wiring.test.ts`, `tests/unit/resource-sampler-wiring.test.ts`
+  — source-pattern assertions updated to the funnel form.
+- `docs/specs/DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC.md` (the design).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+Assertion A bans `?? !!<x>.developmentAgent` everywhere but the funnel. A future
+legitimate need to read `config.developmentAgent` for a non-gate purpose (e.g.
+logging which agent kind it is) would trip it. Mitigation: the regex requires the
+`?? ` nullish-coalesce immediately before `.developmentAgent`, so a bare
+`config.developmentAgent` read does NOT match — only the gate-resolution shape
+does. Assertion B only fires on `enabled: false` in *code* lines within 8 lines
+of a dev-gate marker comment in `ConfigDefaults.ts`; `enabled: true` (fleet-flip)
+and comment prose are deliberately not flagged. Verified clean on the real tree
+(the convention's own documentation does not trip it).
+
+## 2. Under-block — what failure modes does this still miss?
+The honest, central limit (named in the spec's layer table): **a feature that
+should be dev-gated but omits the gate entirely** is invisible to both
+assertions — there is no `?? developmentAgent` to flag and no marker comment to
+anchor on. That is exactly the #1001 *shape* (it had a hardcoded `enabled: false`
+default and a `=== true` construction with no gate). Assertion B catches the
+`enabled: false`-under-marker variant, but not a gate-less feature with no
+marker. The layer that truly catches forgot-entirely is the both-sides wiring
+test over a dev-gated-feature registry (Slice 2) and the spec-intent cross-check
+(Slice 3) — explicitly deferred and tracked (CMT-1253), not silently skipped.
+
+## 3. Level-of-abstraction fit — right layer?
+Yes. The funnel mirrors the established single-funnel pattern (SafeFsExecutor,
+SafeGitExecutor); the lint joins the existing `lint-*` family run in Repo
+Invariants. The guard lives in CI (the same layer that already enforces
+no-direct-destructive, no-unfunneled-topic-creation, etc.), not in a prompt.
+
+## 4. Signal vs authority compliance (docs/signal-vs-authority.md)
+The lint is AUTHORITY (it fails CI / blocks a commit) — appropriate, identical to
+its lint siblings: a deterministic, mechanical invariant with a clear fix
+message, not a judgment call. The runtime helper is pure and behavior-identical
+to the code it replaces, so it holds no new authority over runtime behavior.
+
+## 5. Interactions — shadowing, double-fire, races?
+None. The helper is a pure function with no state. The lint reads files only. The
+migration is a mechanical rewrite (`X ?? !!c.developmentAgent` →
+`resolveDevAgentGate(X, c)`) that `tsc --noEmit` confirms type-identical;
+`resolveDevAgentGate` returns exactly `X ?? !!c?.developmentAgent`, so every
+migrated gate resolves to the same boolean as before for all inputs.
+
+## 6. External surfaces — visible to other agents/users/systems?
+None. No routes, no config, no agent-installed files, no Telegram. Purely
+repo-internal source + CI. No Migration Parity entry needed (the spec's Migration
+Parity section says so explicitly).
+
+## 7. Rollback cost — back-out if wrong?
+Trivial and low-blast-radius. Revert the lint line in `package.json` to disable
+the CI gate instantly; revert the migration commits to restore the hand-rolled
+sites (behavior was never changed, so a revert is a no-op at runtime). No data,
+no state, no deployed artifact to unwind.
+
+## No deferrals
+Slices 2 (registry + both-sides wiring test) and 3 (spec-intent cross-check) are
+NOT deferrals of this slice's scope — they are the explicitly-scoped follow-on
+layers named in the spec and tracked as commitment CMT-1253, so the gap is
+visible and re-surfaced, not dropped.
+
+## Second-pass review (independent)
+**Done — via /spec-converge (5 internal reviewers, 2 iterations; report at
+docs/specs/reports/dev-agent-dark-gate-conformance-convergence.md).** The
+independent pass found three material issues that this change now fixes:
+1. **Assertion B silently no-op'd on its origin case.** The original fixed 8-line
+   window missed the real growthAnalyst block (its ~10-line marker comment pushed
+   the fields out of range) — empirically, an injected `enabled: false` reported
+   "clean." Fixed by brace-matching the block; re-tested: now caught, real tree
+   still clean.
+2. **An 11th un-migrated site + regex blind spot.** `routes.ts` used
+   `?? Boolean(ctx.config.developmentAgent)` — missed by the `!!`-only first pass
+   and unmatched by the lint. Migrated; regex broadened to `!!`/`Boolean(`/bracket.
+3. **Spec overclaim.** Softened "catches #1001 directly" → "when gate-marked" and
+   "only legal path" → "for the realistic spellings"; layer table now names the
+   alias/wrapper and markerless misses.
+Round 2 (lessons-aware + adversarial) returned CONVERGED — no material findings.
+Security and scalability reviewers found nothing material (fails safe toward
+dark-on-fleet; ~0.3s scan, no regex backtracking).

package/upgrades/side-effects/dev-gated-features-registry.md

@@ -0,0 +1,70 @@
+# Side-Effects Review — Dev-Gated-Feature Registry + Both-Sides Wiring Test (Slice 2)
+
+**Change:** Slice 2 of DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC (the converged +
+operator-approved spec). Adds the layer that catches a dev-gated feature wired to
+resolve **dark on a dev agent** — the gap Slice 1's lint cannot see.
+
+- `src/core/devGatedFeatures.ts` (new) — `DEV_GATED_FEATURES` registry (name +
+  config path + description) and a `getConfigByPath` reader.
+- `tests/unit/devGatedFeatures-wiring.test.ts` (new) — for each registered
+  feature, applies the REAL `getMigrationDefaults` and asserts
+  `resolveDevAgentGate(<configPath>)` is **true** under a `developmentAgent: true`
+  config and **false** under a fleet config, plus a "teeth" test confirming an
+  injected `enabled: false` default fails the live-on-dev assertion (the literal
+  #1001 mechanism).
+
+**Registry membership (the design decision in this slice):** only features whose
+intent is "dark fleet / LIVE on dev" are included (growthAnalyst, coherenceJournal,
+warmSessionA2A, secretSync, geminiLoopDriver, respawnBuildContext,
+selfKnowledgeSessionContext — verified to omit `enabled` in defaults). Deliberately
+EXCLUDED, with reasons in code: `monitoring.mcpProcessReaper` (destructive — ships
+OFF + dry-run for everyone incl. dev by design) and `monitoring.resourceLedger`
+(ledger defaults `enabled: true`; only sampling rides the gate off the same key).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+The test asserts every registered feature is live-on-dev / dark-on-fleet. A
+feature that legitimately ships dark-everywhere or live-everywhere would fail if
+wrongly added to the registry — but membership is a deliberate, reviewed choice
+(the two non-conforming features are explicitly excluded with documented reasons),
+so the test only constrains features that genuinely follow the convention.
+
+## 2. Under-block — what failure modes does this still miss?
+Catches the hardcoded-default half of the #1001 shape (a `false` baked into the
+feature's default → `applyDefaults` injects it → live-on-dev assertion fails) for
+**registered** features. Still misses: (a) a dev-gated feature never added to the
+registry; (b) the construction-side half where a site reads `enabled === true`
+without any gate (no default to catch) — that is Slice 3's spec-intent cross-check.
+Both limits are named in the spec's layer table.
+
+## 3. Level-of-abstraction fit — right layer?
+Yes — a unit test over the real config-default assembly (`applyDefaults` +
+`getMigrationDefaults`), the same path PostUpdateMigrator uses. It exercises the
+actual default→gate resolution, not a source regex, so it catches the mechanism
+rather than a spelling.
+
+## 4. Signal vs authority compliance
+The test is CI authority (fails the build) over a deterministic, mechanical
+property — same posture as the rest of the suite. The registry is inert data; it
+holds no runtime authority (Slice 3 consumes it read-only).
+
+## 5. Interactions — shadowing, double-fire, races?
+None. `devGatedFeatures.ts` is pure data + a pure path reader; the test builds
+throwaway config objects. No shared state, no runtime wiring in this slice.
+
+## 6. External surfaces — visible to other agents/users/systems?
+None. No routes, no config, no agent-installed files. Repo-internal source + test.
+No Migration Parity entry needed.
+
+## 7. Rollback cost — back-out if wrong?
+Trivial — delete the two files. No runtime behavior, no state, no deployed artifact.
+
+## No deferrals
+Slice 3 (spec-intent cross-check) is the next slice of the same approved spec,
+tracked under CMT-1253 — not a deferral of this slice's scope. <!-- tracked: CMT-1253 -->
+
+## Second-pass review (independent)
+The registry membership was derived by auditing each `resolveDevAgentGate` site's
+default against the convention: the 7 included features verified to omit `enabled`
+(test green on all = no hidden hardcoded default); the 2 excluded features
+(mcpProcessReaper, resourceLedger) inspected and confirmed intentionally NOT
+dark-on-fleet. The teeth test confirms the guard fires on a planted regression.