instar 1.3.1148 → 1.3.1149

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1148",
+  "packageVersion": "1.3.1149",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "c4fb233de8c00b924323e7e9b167a5832162a35740c6445ccb7200c863ee9686",
+  "sha256": "1ed8f5bd6959a002ef362c9be5f88a382b0956d4992b16879350851ce3711ac9",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1148"
+  "packageVersion": "1.3.1149"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1148"
+  "packageVersion": "1.3.1149"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1148",
+  "version": "1.3.1149",
   "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/scripts/lint-dev-agent-dark-gate.js

@@ -72,6 +72,49 @@ const FUNNEL_ALLOWLIST = new Set([
 // in the spec's Layer-1 "misses" row.)
 const HANDROLLED_GATE =
   /\?\?\s*(?:!{1,2}\s*|Boolean\s*\(\s*)?[A-Za-z_$][\w$.?]*(?:\.developmentAgent\b|\[\s*['"]developmentAgent['"]\s*\])/;
+
+// ── 2026-08-14: the gate value does not have to be spelled at the `??`. ──
+// The matcher above requires `.developmentAgent` LITERALLY after the `??`, so
+// lifting it into a local const first walks past it while resolving the gate by
+// hand exactly as before:
+//     const da = config.developmentAgent;
+//     return enabled ?? !!da;              // exit 0 against the old matcher
+// The header's declared limit ("cannot catch arbitrary aliases/wrapper helpers")
+// was honest; this closes the LOCAL-CONST half of it, which is the shape a
+// rename-defeat audit actually reproduced.
+//
+// Deliberately NOT closed, so it stays stated rather than implied: wrapper
+// helpers (`isDevAgent(config)`), cross-module aliases, and any value that needs
+// dataflow to resolve. Guessing at those would over-match, and this lint fails
+// builds — flagging correct code is the more expensive error here.
+//
+// Scope-bounded on purpose: an alias binds only within its own file, so the map
+// is rebuilt per file and never leaks between them.
+const ALIAS_DECL =
+  /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::\s*[^=]+?)?=\s*[A-Za-z_$][\w$.?]*(?:\.developmentAgent\b|\[\s*['"]developmentAgent['"]\s*\])/;
+
+/**
+ * Local identifiers bound to `<expr>.developmentAgent` in THIS file.
+ * `config.developmentAgentName` does not qualify — the `\b` keeps the boundary
+ * through the alias exactly as it holds at the direct callsite.
+ */
+function collectDevAgentAliases(lines) {
+  const names = new Set();
+  for (const line of lines) {
+    const code = codeOnly(line);
+    if (code === null) continue;
+    const m = ALIAS_DECL.exec(code);
+    if (m) names.add(m[1]);
+  }
+  return names;
+}
+
+/** `?? [!! | Boolean(] <alias>` — the aliased spelling of the same hand-rolled gate. */
+function aliasGateMatcher(names) {
+  if (names.size === 0) return null;
+  const alts = [...names].join('|');
+  return new RegExp(`\\?\\?\\s*(?:!{1,2}\\s*|Boolean\\s*\\(\\s*)?(?:${alts})\\b`);
+}
 // A comment referencing the gate convention (for assertion B).
 const GATE_MARKER = /developmentAgent/i;
 const GATE_MARKER_QUALIFIER = /\b(dark|gate)\b/i;
@@ -171,10 +214,11 @@ for (const file of resolveTargets()) {
 
   // ── Assertion A: funnel ──
   if (!FUNNEL_ALLOWLIST.has(rel)) {
+    const aliasGate = aliasGateMatcher(collectDevAgentAliases(lines));
     lines.forEach((line, i) => {
       const code = codeOnly(line);
       if (code === null) return;
-      if (HANDROLLED_GATE.test(code)) {
+      if (HANDROLLED_GATE.test(code) || (aliasGate !== null && aliasGate.test(code))) {
         violations.push({
           file: rel, line: i + 1, kind: 'A: hand-rolled gate',
           text: line.trim(),

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-14T23:20:47.847Z",
-  "instarVersion": "1.3.1148",
+  "generatedAt": "2026-08-15T00:08:31.593Z",
+  "instarVersion": "1.3.1149",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1148",
+  "packageVersion": "1.3.1149",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "c4fb233de8c00b924323e7e9b167a5832162a35740c6445ccb7200c863ee9686",
+  "sha256": "1ed8f5bd6959a002ef362c9be5f88a382b0956d4992b16879350851ce3711ac9",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1148"
+  "packageVersion": "1.3.1149"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1148"
+  "packageVersion": "1.3.1149"
 }

package/upgrades/1.3.1149.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-dev-agent-dark-gate.js` assertion A bans hand-rolled dev-agent gate resolution outside
+`resolveDevAgentGate`. The matcher required `.developmentAgent` **literally after the `??`**, so lifting the
+value into a local const first walked past it while resolving the gate by hand exactly as before:
+
+```ts
+const da = config.developmentAgent;
+return enabled ?? !!da;          // exit 0 against the shipped lint
+```
+
+instar-codey reproduced this while auditing rename-defeatable checks and pre-scoped the remedy ("low FP for
+simple local alias folding around `developmentAgent` feeding `??`"). That is the scope implemented: local
+`const`/`let`/`var` aliases, collected per file, matched at `?? [!!|Boolean(] <alias>`.
+
+The lint's header already declared this limit ("cannot catch arbitrary aliases/wrapper helpers"). It is
+closed for the shape that actually occurs; the declaration was honest, not wrong.
+
+Four controls keep it from failing correct builds, each with a test: only a `developmentAgent` binding
+counts; matching is whole-word so `developmentAgentName` is untouched; an alias never used at a `??` is
+legal (reading the flag is fine — hand-rolling the fallback is what is banned); and a commented-out
+declaration binds nothing.
+
+Still not caught, stated in the source: wrapper helpers, cross-module aliases, and anything needing
+dataflow. Guessing at those would over-match a build-failing lint.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/lint-dev-agent-dark-gate.test.ts` — **31/31 green** (24 existing + 7 added).
+- Negative control: tests written BEFORE the fix, run against the shipped lint — **3 of 31 fail** (const
+  alias, bracket-access alias, `Boolean(alias)`). The other 28 pass both ways.
+- Reproduced by hand first with a positive control: direct form exits 1, aliased form exits 0.
+- Real-tree verdict: `node scripts/lint-dev-agent-dark-gate.js` → exit 0, no new flags.
+- Full `npm run lint` chain green.
+- Side-effects: `upgrades/side-effects/dev-agent-gate-alias.md` · ELI16: `docs/specs/dev-agent-gate-alias.eli16.md`.

package/upgrades/side-effects/dev-agent-gate-alias.md

@@ -0,0 +1,104 @@
+# Side-Effects Review — dev-agent gate check follows a local alias
+
+**Version / slug:** `dev-agent-gate-alias`
+**Date:** `2026-08-14`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (CI-only lint script; no runtime path). The rule is unchanged; the check now recognises one more spelling of the thing it already forbids.`
+
+## Summary of the change
+
+`scripts/lint-dev-agent-dark-gate.js` assertion A bans hand-rolled dev-agent gate resolution — anything
+resolving `enabled ?? !!<x>.developmentAgent` outside `resolveDevAgentGate`. The matcher required
+`.developmentAgent` (or `['developmentAgent']`) **literally after the `??`**, so lifting the value into a
+local const first walked past it while resolving the gate by hand exactly as before:
+
+```ts
+const da = config.developmentAgent;
+return enabled ?? !!da;          // exit 0 against the shipped lint
+```
+
+instar-codey reproduced this while auditing rename-defeatable checks and scoped the remedy: *"low for
+simple local alias folding around `developmentAgent` feeding `??`."* That is the scope implemented — local
+`const`/`let`/`var` aliases only, rebuilt per file.
+
+The lint's header **already declared this limit** ("cannot catch arbitrary aliases/wrapper helpers"). Like
+the journal-actuation ban earlier today, it is closed because the declared gap is cheap to close for the
+shape that actually occurs, not because the declaration was dishonest.
+
+## Decision-point inventory
+
+- `collectDevAgentAliases(lines)` — ADD — per-file identifiers bound to `<expr>.developmentAgent`.
+- `aliasGateMatcher(names)` — ADD — `?? [!!|Boolean(] <alias>`; returns null when there are no aliases, so
+  a file without one is byte-identical to before.
+- Assertion A predicate — WIDEN — `HANDROLLED_GATE || aliasGate`.
+- Assertions B and C, the funnel allowlist, the comment-stripping (`codeOnly`), and the marker logic are
+  untouched.
+- No runtime block/allow decision added or modified. CI-time only.
+
+## 1. Over-block
+
+The failure that matters: this lint fails builds, so flagging correct code costs more than missing a case.
+Four controls, each with a test:
+
+- **An alias of something else** (`config.somethingElse`) is not flagged — only `developmentAgent` binds.
+- **A look-alike name** (`config.developmentAgentName`) is not flagged: the `\b` holds through the alias
+  exactly as it holds at the direct callsite.
+- **An alias never used at a `??`** is not flagged. *Reading* the flag is legal; resolving the GATE by hand
+  is what is banned, and that distinction is preserved.
+- **A comment describing the aliased pattern** is not flagged — `codeOnly` already strips comments and the
+  alias collector runs on the same stripped lines, so a commented-out declaration binds nothing.
+
+Scope is per-file by construction: aliases cannot leak between files.
+
+Verified against the real tree: exit 0 — the widened check introduces **no new flags on existing code**.
+
+## 2. Under-block
+
+Stated in the source rather than implied:
+
+- **Wrapper helpers** (`isDevAgent(config)`) — still invisible.
+- **Cross-module aliases** — an alias exported from another file is not followed.
+- **Anything needing dataflow** to resolve.
+
+Guessing at those would over-match. The header's original claim is narrowed, not erased: it now cannot
+catch *arbitrary* aliases, having gained the local-const case.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — line-oriented regex over comment-stripped source, no AST, no type
+information, no new dependency. The alias map is the minimum needed to answer "what value is at this
+`??`?" without climbing to a parser.
+
+## 4. Signal vs authority compliance
+
+Unchanged. A CI guard, not a runtime authority. It pushes callers toward `resolveDevAgentGate`; the funnel
+allowlist still exempts the funnel itself.
+
+## 5. Interactions
+
+- `npm run lint` chain — position unchanged; full chain green.
+- Assertions B/C unaffected; their env-fixture tests pass untouched.
+- No source module, route, config key, or state file touched.
+
+## 6. External surfaces
+
+None. Developer tooling, not an agent capability; the Agent Awareness Standard does not apply.
+
+## 7. Rollback cost
+
+`git revert` of one script plus the appended tests. No migration, no state, no deployed artifact.
+
+## Conclusion
+
+Ship. One evasion closed at the scope a peer's audit recommended, four anti-over-block controls added, real
+tree verified clean.
+
+## Evidence pointers
+
+- `tests/unit/lint-dev-agent-dark-gate.test.ts` — **31/31 green** (24 existing + 7 added).
+- Negative control: tests written BEFORE the fix and run against the shipped lint — **3 of 31 fail** (const
+  alias, bracket-access alias, `Boolean(alias)`); the four new controls and all 24 existing tests pass both
+  ways, which is what makes them controls.
+- Reproduced by hand first, with a positive control: the direct form exits 1, the aliased form exits 0.
+- Real-tree verdict: `node scripts/lint-dev-agent-dark-gate.js` → exit 0.
+- Full `npm run lint` chain green.