instar 1.3.1048 → 1.3.1049

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

@@ -2,5 +2,5 @@
   "sha256": "b75c147afd1f5a9843ca4eac372159f3623f24731fe63b2f59e48043ae488af9",
   "articleCount": 82,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1048"
+  "packageVersion": "1.3.1049"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1048",
+  "version": "1.3.1049",
   "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/instar-dev-precommit.js

@@ -34,6 +34,7 @@ import { classifyTier, decideRequirementSet } from './lib/classify-tier.mjs';
 import { recognizeConvergence } from './lib/convergence-recognition.mjs';
 import { isOperatorSurfaceFile, artifactAddressesOperatorSurfaceQuality, isAuthorizationSurfaceFile, artifactAddressesAgentProposesApproves, operatorSurfaceRequiresRawInput } from './lib/operator-surface.mjs';
 import { selfActionDeclarationVerdict } from './lib/self-action-detect.mjs';
+import { isKnownInlineCodeEnumReference } from './lib/markdown-code-identifier.mjs';
 import { validateAuditReport, parseFrontmatter } from './write-audit-convergence.mjs';
 import { scanForSecrets } from './audit-secret-patterns.mjs';
 
@@ -843,9 +844,13 @@ if (staged.includes(spec) && !staged.includes(eli16Rel)) {
 // `deferrals-tracked` field). Override via INSTAR_DEV_ALLOW_ORPHAN_DEFERRALS=1
 // (logged for visibility).
 //
-// Detector patterns intentionally conservative — false-positives are cheaper
-// than false-negatives here. The author can either link a tracker or rephrase
-// the sentence to not promise a deferral.
+// Detector patterns intentionally remain conservative over the complete
+// document: headings, callouts, indented text, and standalone inline-code words
+// can all carry real scope decisions. The one structural exclusion is a
+// reference list for the shipped MigrationPerEntryAction CLOSED ENUM. A lone
+// `deferred-in-flight` remains visible; the exemption requires another known
+// enum member on the same line. This validates structured input rather than
+// inferring meaning from Markdown or identifier shape.
 // Patterns: { regex, requireUnnegated } — when requireUnnegated is true,
 // we skip the match if the immediately-preceding chars contain "no ", "non-",
 // "non ", "non", or "un" (so "no deferrals" / "non-deferred" / "undeferred"
@@ -883,6 +888,7 @@ function findOrphanDeferrals(content) {
     let m;
     while ((m = regex.exec(content)) !== null) {
       const start = m.index;
+      if (isKnownInlineCodeEnumReference(content, start, start + m[0].length)) continue;
       if (requireUnnegated) {
         // Look at up to 8 chars immediately before the match. Treat
         // matches preceded by "no ", "non-", "non ", "un" as legitimate

package/scripts/lib/markdown-code-identifier.mjs

@@ -0,0 +1,130 @@
+/** The shipped MigrationPerEntryAction closed enum from MigrationLedger.ts. */
+export const MIGRATION_LEDGER_ACTION_VALUES = Object.freeze([
+  'migrated',
+  'forked',
+  'renamed',
+  'skipped',
+  'failed',
+  'deferred-in-flight',
+]);
+
+/**
+ * Return true only when a candidate range is a reference to the shipped
+ * MigrationPerEntryAction enum: it must sit inside an inline-code span whose
+ * complete value is in the closed enum, and the same line must enumerate at
+ * least one other closed-enum member in its own inline-code span.
+ *
+ * A lone `deferred-in-flight` may still be an authorial disposition and remains
+ * visible to the caller. Fenced blocks, headings, blockquotes, indented text,
+ * standalone inline-code words, escaped backticks, and unknown identifiers also
+ * remain visible. This validates already-structured input against a fixed enum;
+ * it does not infer intent from identifier shape.
+ */
+export function isKnownInlineCodeEnumReference(markdown, candidateStart, candidateEnd) {
+  if (
+    typeof markdown !== 'string'
+    || !Number.isInteger(candidateStart)
+    || !Number.isInteger(candidateEnd)
+    || candidateStart < 0
+    || candidateEnd <= candidateStart
+    || candidateEnd > markdown.length
+  ) {
+    return false;
+  }
+
+  const isEscaped = (index) => {
+    let slashes = 0;
+    for (let i = index - 1; i >= 0 && markdown[i] === '\\'; i -= 1) slashes += 1;
+    return slashes % 2 === 1;
+  };
+
+  const fencedRanges = [];
+  let fence = null;
+  let lineStart = 0;
+  while (lineStart < markdown.length) {
+    const newline = markdown.indexOf('\n', lineStart);
+    const lineEnd = newline >= 0 ? newline + 1 : markdown.length;
+    const line = markdown.slice(lineStart, newline >= 0 ? newline : markdown.length).replace(/\r$/, '');
+    let fenceLine = line;
+    // CommonMark permits fences inside blockquote and list containers. Strip
+    // only the structural prefix used to introduce a fence; the recorded byte
+    // range still covers the untouched source.
+    for (;;) {
+      const quote = fenceLine.match(/^ {0,3}>[ \t]?/);
+      if (quote) {
+        fenceLine = fenceLine.slice(quote[0].length);
+        continue;
+      }
+      const list = fenceLine.match(/^ {0,3}(?:[-+*]|\d{1,9}[.)])[ \t]+/);
+      if (list) {
+        fenceLine = fenceLine.slice(list[0].length);
+        continue;
+      }
+      break;
+    }
+    if (!fence) {
+      const open = fenceLine.match(/^ {0,3}(`{3,}|~{3,})/);
+      if (open) fence = { char: open[1][0], length: open[1].length, start: lineStart };
+    } else {
+      const close = fenceLine.match(/^ {0,3}(`+|~+)[ \t]*$/);
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) {
+        fencedRanges.push({ start: fence.start, end: lineEnd });
+        fence = null;
+      }
+    }
+    lineStart = lineEnd;
+  }
+  if (fence) fencedRanges.push({ start: fence.start, end: markdown.length });
+
+  const spans = [];
+  for (let i = 0; i < markdown.length;) {
+    const fenced = fencedRanges.find((range) => i >= range.start && i < range.end);
+    if (fenced) {
+      i = fenced.end;
+      continue;
+    }
+    if (markdown[i] !== '`' || isEscaped(i)) {
+      i += 1;
+      continue;
+    }
+
+    let runLength = 1;
+    while (markdown[i + runLength] === '`') runLength += 1;
+    const lineStart = markdown.lastIndexOf('\n', i - 1) + 1;
+
+    const contentStart = i + runLength;
+    let close = contentStart;
+    while (close < markdown.length) {
+      if (markdown[close] !== '`' || isEscaped(close)) {
+        close += 1;
+        continue;
+      }
+      let closeLength = 1;
+      while (markdown[close + closeLength] === '`') closeLength += 1;
+      if (closeLength === runLength) break;
+      close += closeLength;
+    }
+
+    if (close >= markdown.length) break;
+    const lineEndIndex = markdown.indexOf('\n', close);
+    spans.push({
+      start: contentStart,
+      end: close,
+      value: markdown.slice(contentStart, close).trim(),
+      lineStart,
+      lineEnd: lineEndIndex >= 0 ? lineEndIndex : markdown.length,
+    });
+    i = close + runLength;
+  }
+
+  const target = spans.find((span) => candidateStart >= span.start && candidateEnd <= span.end);
+  if (!target || !MIGRATION_LEDGER_ACTION_VALUES.includes(target.value)) return false;
+
+  const referencedValues = new Set(
+    spans
+      .filter((span) => span.lineStart === target.lineStart && span.lineEnd === target.lineEnd)
+      .map((span) => span.value)
+      .filter((value) => MIGRATION_LEDGER_ACTION_VALUES.includes(value)),
+  );
+  return referencedValues.size >= 2;
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-29T09:19:22.136Z",
-  "instarVersion": "1.3.1048",
+  "generatedAt": "2026-07-29T10:16:28.309Z",
+  "instarVersion": "1.3.1049",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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

@@ -2,5 +2,5 @@
   "sha256": "b75c147afd1f5a9843ca4eac372159f3623f24731fe63b2f59e48043ae488af9",
   "articleCount": 82,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1048"
+  "packageVersion": "1.3.1049"
 }

package/upgrades/1.3.1049.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The development specification check now recognizes a reference list for a
+shipped, closed telemetry enum instead of reading one member as postponed work.
+Headings, callouts, fenced blocks, lone values, and standalone status words
+remain checked.
+
+## What to Tell Your User
+
+Technical state names in specifications no longer trigger an irrelevant
+unfinished-work warning, while real scope decisions are still checked.
+
+## Summary of New Capabilities
+
+- Closed-enum reference recognition in the development specification gate.
+
+## Evidence
+
+- The live telemetry-enum regression now passes without an override.
+- Real scope-decision forms and fenced examples remain blocked.
+- The recognized value list is pinned to the shipped enum declaration.
+- Removing the enum-list distinction makes the regression test fail.
+- Focused tests and the repository typecheck pass.

package/upgrades/eli16/keyword-gate-authorial-context.md

@@ -0,0 +1,37 @@
+# Keyword gates now distinguish an enum value from a prose decision
+
+The development gate that checks technical specifications for unfinished work
+used to read every occurrence of the word “deferred” as a decision to postpone
+something. That is usually a useful warning, but it also caught a telemetry
+value such as `deferred-in-flight`. The value names a state in software; it does
+not say that implementation work is being postponed. Because the check blocks a
+commit, the only escape was an audited override even though there was no work to
+track.
+
+This change adds one deliberately narrow distinction. It knows the actual
+closed list of migration telemetry outcomes shipped by the code. A match is
+treated as an enum reference only when the complete inline-code value belongs
+to that list and at least one other member of the same closed list appears in
+inline code on the same line. A lone `deferred-in-flight` still triggers the
+gate because it could be an authorial status. The exact same words in ordinary
+prose also trigger it, as do headings, blockquotes, callouts, indented list
+text, fenced blocks, standalone `deferred`, unknown identifiers, and escaped
+backticks. Those places can all carry genuine scope decisions, so the
+implementation does not infer intent from Markdown or hyphen count.
+
+The new parser preserves the existing tracker lookup, diagnostics, override,
+and block behavior. It supports matching single- or multi-backtick inline-code
+spans, refuses fenced blocks and malformed ranges, and has a parity test that
+pins its local closed set to the shipped type declaration. Tests prove both
+sides: the telemetry enum list passes, while real scope-decision forms remain
+blocked. A mutation test removed the new distinction and the enum regression
+failed immediately.
+
+The same investigation also records the broader failure class in the defect
+registry: a literal keyword is given authority without enough context to know
+what it means. That class remains unconfirmed and open because the other named
+systems do not share one safe mechanical fix. The outbound convergence check is
+separately tracked for removal from blocking authority; the recall change is
+owned elsewhere; and raw shell-input safety needs enforcement at the relay
+boundary, not another text carve-out. This PR therefore fixes the live enum
+false positive without pretending it closes those different problems.

package/upgrades/side-effects/keyword-gate-authorial-context.md

@@ -0,0 +1,157 @@
+# Side-Effects Review — Keyword-gate authorial context
+
+**Version / slug:** `keyword-gate-authorial-context`
+**Date:** `2026-07-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `Euler`
+
+## Summary of the change
+
+The instar-dev orphan-deferral blocker now excludes only a reference list for
+the shipped MigrationPerEntryAction closed enum. The matched inline-code value
+must belong to that enum and share a line with another enum member. It does not
+remove headings, quotations, callouts, indented text, fenced content, lone enum
+values, unknown identifiers, or standalone inline-code words from inspection.
+A new pure helper owns the parse, and refusal-first tests cover the live enum
+regression plus genuine decision shapes. The broader failure class is recorded
+as an unconfirmed registry entry. ACT-1519 owns its confirmation/refinement;
+ACT-1520 owns enforcement at the relay boundary.
+
+## Decision-point inventory
+
+- `findOrphanDeferrals` — modified — skips one structurally qualified artifact
+  reference before applying the unchanged negation/tracker/block policy.
+- `isKnownInlineCodeEnumReference` — added — validates equal-backtick
+  inline-code spans against the real closed enum and requires a same-line
+  sibling member; it has no authority outside the existing caller.
+- Orphan-deferral commit block — pass-through — patterns, nearby-tracker
+  requirement, override, diagnostics, and exit behavior are unchanged.
+- Defect-class registry — modified — names the broader cross-gate class as
+  unconfirmed; it grants no runtime authority.
+
+## 1. Over-block
+
+Enum values shown alone, values rendered outside inline code, and unknown
+identifier values still reach the existing blocker. This is intentional
+conservatism: a lone `deferred-in-flight` may itself be an authorial
+disposition. Historical quotations and fenced examples also still require a
+tracker or the existing audited override.
+
+The reported heading `## §8 — Out of scope (deliberate)` already passes current
+main because none of the configured phrases matches it. A test pins that fact;
+this change does not claim a heading fix that the current source cannot
+reproduce.
+
+## 2. Under-block
+
+An author could place a genuine decision inside a line that also enumerates
+multiple real migration outcomes. That is the remaining narrow ambiguity.
+Lone enum values, unknown multi-segment identifiers, standalone
+`` `deferred` ``, headings, blockquotes/callouts, indented prose, fenced blocks,
+escaped backticks, and the same enum token in prose all remain blocked and are
+refusal-tested.
+
+The broader keyword-authority class is not closed here. ACT-1519 already tracks
+the Signal-vs-Authority correction and class refinement. ACT-1520 is the
+tracked enforcement gap: move outbound checks to the relay/send boundary, where
+quoting, variables, aliases, and wrappers do not decide what gets inspected.
+
+## 3. Level-of-abstraction fit
+
+The helper answers a structured question at the structured boundary: “is this
+match one member of the shipped closed enum being listed beside another
+member?” It does not infer meaning from identifier shape or decide whether a
+whole heading, quotation, code block, or paragraph is authorial. Two broader
+implementations attempted those shortcuts; the required independent review
+rejected them, and both designs were removed completely.
+
+The other named gates are not forced through this helper. ACT-1519 owns moving
+the outbound convergence regex out of blocking authority; recall has a
+semantic-index design owned elsewhere; dangerous shell input needs
+command-boundary enforcement.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+This change adds no new blocking authority and does not promote a new keyword.
+It narrows the evidence entering an existing blocker by validating an actual
+closed enum reference. The existing blocker still uses literal language with commit authority,
+so the broader constitutional concern is recorded honestly rather than called
+closed: `brittle-keyword-authority`, unconfirmed, with `closure: gap` tied to
+ACT-1520. ACT-1519 separately owns confirmation/refinement of the class.
+
+## 4b. Judgment-point check
+
+No new static heuristic chooses among competing live signals. The helper
+validates already-structured input against the shipped closed enum, with a
+source-parity test. It cannot turn a non-match into a block; it can only remove
+the demonstrated enum-list false positive from an existing candidate list.
+
+## 5. Interactions
+
+- **Shadowing:** The identifier check runs before existing negation and nearby
+  tracker checks only for that candidate. All other candidates follow the
+  byte-identical path.
+- **Double-fire:** None. The helper returns one boolean to the existing single
+  scan.
+- **Races:** None. Parsing is pure and local to one staged document.
+- **Feedback loops:** Fewer invalid blocks should reduce override use. The
+  override log and decision audit are otherwise unchanged.
+
+## 6. External surfaces
+
+Instar contributors can commit specs that reference the closed telemetry enum
+as a list without an audited override. Real unfinished-work language still receives the
+same blocking diagnostic. No APIs, user messages, persistent runtime state,
+external services, timing assumptions, or operator-facing actions change.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Git-replicated source behavior. Every machine running the same source revision
+gets the same pure classification; no machine-local state is added. The change
+emits no user notice, holds no durable state, and generates no URLs.
+
+## 8. Rollback cost
+
+Pure code and registry rollback. Reverting the helper import and exclusion
+restores the previous over-block immediately. No data migration or agent-state
+repair is required.
+
+## Conclusion
+
+Clear to ship after the independent re-review. Two overly broad syntax
+heuristics were rejected and removed; the final change binds only to the real
+shipped enum, proves the nearby under-block boundaries, and records the larger
+class without claiming to have solved unrelated gates.
+
+## Second-pass review
+
+**Reviewer:** Euler
+**Independent read of the artifact: approved after three blocking passes.**
+The first two designs exempted broad Markdown/identifier shapes and were
+removed. The final pass verified closed-enum parity, lone/prose/status refusal,
+and top-level, blockquoted, and list-nested fenced ranges. It also verified that
+ACT-1519 owns class refinement and ACT-1520 owns relay-boundary enforcement.
+There are no remaining blocking findings.
+
+## Evidence pointers
+
+- `tests/unit/instar-dev-precommit-deferrals.test.ts`
+- `tests/unit/markdown-code-identifier.test.ts`
+- `tests/unit/class-closure-registry.test.ts`
+- Mutation proof: removing the identifier exclusion makes the enum test fail.
+- `npx tsc --noEmit`
+- `git diff --check`
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: brittle-keyword-authority`, `closure: gap`, `gapItem: ACT-1520`.
+The class is new and unconfirmed; the current PR closes the reproduced enum
+instance but does not claim that a local lexical exclusion ends the broader
+raw-input and natural-language authority class. ACT-1519 owns class
+confirmation/refinement; ACT-1520 owns the missing relay-boundary enforcement.