instar 1.3.946 → 1.3.948

package/dist/messaging/detectors/assertUserVisible.d.ts

@@ -0,0 +1,11 @@
+/** Deterministic UX assertions for Tier-3 user-surface tests. */
+/** Reject internal identifiers, paths, config keys, and known implementation jargon. */
+export declare function assertPlainEnglish(text: unknown): asserts text is string;
+/** Every failure must explain what happened and give the user a next action. */
+export declare function assertHonestFailure(state: unknown): asserts state is {
+    message: string;
+    actionable: boolean;
+};
+/** A queue must not contain an expired/stale entry that can be redelivered. */
+export declare function assertNoZombie(queue: unknown): asserts queue is Array<Record<string, unknown>>;
+//# sourceMappingURL=assertUserVisible.d.ts.map

package/dist/messaging/detectors/assertUserVisible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertUserVisible.d.ts","sourceRoot":"","sources":["../../../src/messaging/detectors/assertUserVisible.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAWjE,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAKxE;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAO7G;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAa9F"}

package/dist/messaging/detectors/assertUserVisible.js

@@ -0,0 +1,47 @@
+/** Deterministic UX assertions for Tier-3 user-surface tests. */
+const INTERNAL_ID = /\b(?:CMT|ACT|PR)[-_#]?\d+\b/i;
+const FILE_PATH = /(?:^|\s)(?:\/|\.\.\/|src\/|tests\/)[^\s]+/;
+const CONFIG_KEY = /\b[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*){2,}\b/;
+const JARGON_CLASSES = [/\b(?:hydration|idempotency|backpressure|fan[- ]?out|reconciliation)\b/i];
+function requireText(text, label) {
+    if (typeof text !== 'string' || text.trim().length === 0)
+        throw new Error(`${label} must be plain user-visible text`);
+}
+/** Reject internal identifiers, paths, config keys, and known implementation jargon. */
+export function assertPlainEnglish(text) {
+    requireText(text, 'text');
+    if (INTERNAL_ID.test(text) || FILE_PATH.test(text) || CONFIG_KEY.test(text) || JARGON_CLASSES.some((p) => p.test(text))) {
+        throw new Error('text contains implementation detail or jargon');
+    }
+}
+/** Every failure must explain what happened and give the user a next action. */
+export function assertHonestFailure(state) {
+    if (!state || typeof state !== 'object')
+        throw new Error('failure state is missing');
+    const candidate = state;
+    requireText(candidate.message, 'failure message');
+    if (candidate.ok === true)
+        throw new Error('success state cannot be asserted as a failure');
+    if (candidate.actionable !== true)
+        throw new Error('failure message must include an actionable next step');
+    assertPlainEnglish(candidate.message);
+}
+/** A queue must not contain an expired/stale entry that can be redelivered. */
+export function assertNoZombie(queue) {
+    if (!Array.isArray(queue))
+        throw new Error('queue must be an array');
+    for (const item of queue) {
+        if (!item || typeof item !== 'object')
+            throw new Error('queue contains an invalid entry');
+        const row = item;
+        if (row.status === 'queued' && row.expiresAt && Date.parse(String(row.expiresAt)) <= Date.now()) {
+            throw new Error('queue contains an expired queued entry');
+        }
+        if (row.status === 'queued' && row.nextAttemptAt && Date.parse(String(row.nextAttemptAt)) > Date.now())
+            continue;
+        if (row.status === 'queued' && row.createdAt && Date.now() - Date.parse(String(row.createdAt)) > 24 * 60 * 60 * 1000) {
+            throw new Error('queue contains a stale queued entry');
+        }
+    }
+}
+//# sourceMappingURL=assertUserVisible.js.map

package/dist/messaging/detectors/assertUserVisible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertUserVisible.js","sourceRoot":"","sources":["../../../src/messaging/detectors/assertUserVisible.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.946",
+  "version": "1.3.948",
   "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/eli16-overview-check.mjs

@@ -29,7 +29,11 @@ export const MIN_ELI16_CHARS = 800;
 export function resolveEli16Path(specPath, specFm) {
   const specDir = path.dirname(specPath);
   const specBase = path.basename(specPath, '.md');
-  const siblingPath = path.join(specDir, `${specBase}.eli16.md`);
+  // Specs already named *.eli16.md use a readable overview sibling; never
+  // manufacture the historical *.eli16.eli16.md suffix.
+  const siblingPath = specBase.endsWith('.eli16')
+    ? path.join(specDir, `${specBase.slice(0, -'.eli16'.length)}.overview.md`)
+    : path.join(specDir, `${specBase}.eli16.md`);
   const fmMatch = specFm.match(/^\s*eli16-overview\s*:\s*["']?([^"'\n]+)/m);
   if (fmMatch) {
     const declared = fmMatch[1].trim().replace(/["']/g, '');

package/scripts/gh-ruleset-install.mjs

@@ -77,6 +77,7 @@ const branchRuleset = {
         strict_required_status_checks_policy: true,
         required_status_checks: [
           { context: 'worktree-trailer-sig-check / verify' },
+          { context: 'UX impact declaration' },
         ],
       },
     },

package/scripts/ux-impact-lint.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// safe-git-allow: read-only base-ref diff inspection for pull-request lint
+/** L1 UX-impact declaration lint. Exit 0=pass/out-of-scope, 1=violation, 2=internal error. */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+
+function arg(name) { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : ''; }
+const base = arg('--base');
+const head = arg('--head') || 'HEAD';
+const body = arg('--body') || '';
+const scope = (arg('--scope') || '').split(',').map((v) => v.trim().toLowerCase()).filter(Boolean);
+const pusher = (arg('--pusher') || '').trim().toLowerCase();
+const reportPath = arg('--report');
+if (process.env.INSTAR_UX_LINT === 'off') { console.log('UX lint disabled by literal kill switch'); process.exit(0); }
+if (!base) { console.error('::error::UX lint requires a base ref'); process.exit(2); }
+try {
+  const names = execFileSync('git', ['diff', '--name-only', `${base}...${head}`], { encoding: 'utf8' }).trim().split('\n').filter(Boolean);
+  const commits = execFileSync('git', ['log', '--format=%an <%ae>%n%cn <%ce>', `${base}..${head}`], { encoding: 'utf8' }).toLowerCase();
+  const authorInScope = scope.length === 0
+    || (Boolean(pusher) && scope.includes(pusher))
+    || scope.some((token) => commits.includes(token));
+  const report = { version: 1, base, head, authorInScope, scope, allowlistedPaths: [], exempt: false, internalError: false };
+  const writeReport = () => { if (reportPath) writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`); };
+  if (!authorInScope) { report.outOfScopeAuthor = true; await writeReport(); console.log('UX lint: out-of-scope author'); process.exit(0); }
+  const allowlisted = names.filter((p) => p === 'src/server/routes.ts' || p === 'src/commands/server.ts' || p.startsWith('src/messaging/') || p.startsWith('src/dashboard/') || p.startsWith('src/templates/'));
+  report.allowlistedPaths = allowlisted;
+  if (allowlisted.length === 0) { await writeReport(); console.log('UX lint: out of scope'); process.exit(0); }
+  const diff = execFileSync('git', ['diff', '--unified=0', `${base}...${head}`, '--', ...allowlisted], { encoding: 'utf8' });
+  const added = diff.split('\n').filter((line) => line.startsWith('+') && !line.startsWith('+++')).join('\n');
+  const refactorOnly = !allowlisted.some((p) => p.startsWith('src/templates/') || p === 'src/server/routes.ts' || p === 'src/commands/server.ts')
+    && !/(?:^|\s)[`'\"](?:[^`'\"]+)[`'\"]/.test(added);
+  const section = body.match(/^## UX Impact\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/im)?.[1]?.trim() || '';
+  if (/UX-Impact:\s*refactor-only/i.test(section) && refactorOnly) { report.exempt = true; report.exemption = 'refactor-only'; await writeReport(); console.log('UX lint PASS: deterministic refactor-only exemption'); process.exit(0); }
+  if (!section) { console.error('::error::UX Impact section is required for user-facing paths'); process.exit(1); }
+  if (/UX-Impact:\s*none/i.test(section)) { console.error('::error::UX-Impact: none is not allowed for allowlisted paths'); process.exit(1); }
+  if (!/who\s+sees|what\s+(?:the\s+)?user|first[- ]contact|user[- ]visible/i.test(section)) {
+    console.error('::error::UX Impact must describe audience, visible behavior, and first contact'); process.exit(1);
+  }
+  const quoted = [...section.matchAll(/[`'"“]([^`'"”]+)[`'"”]/g)].map((m) => m[1]);
+  if (!quoted.some((q) => q.length > 2 && diff.includes(q))) {
+    console.error('::error::UX Impact must quote a concrete string from the diff'); process.exit(1);
+  }
+  await writeReport();
+  console.log(`UX lint PASS: ${allowlisted.length} allowlisted path(s)`);
+  process.exit(0);
+} catch (error) {
+  if (reportPath) writeFileSync(reportPath, `${JSON.stringify({ version: 1, internalError: true, message: error instanceof Error ? error.message : String(error) })}\n`);
+  console.error(`::error::UX lint internal error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(2);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-24T23:49:53.588Z",
-  "instarVersion": "1.3.946",
+  "generatedAt": "2026-07-25T01:11:00.882Z",
+  "instarVersion": "1.3.948",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.947.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Pull requests touching messaging and other user-facing surfaces now receive a
+separate UX-impact declaration check. The messaging E2E suite also exercises
+plain-language, honest-failure, and zombie-queue assertions.
+
+## What to Tell Your User
+
+Changes that affect people must explain the visible experience in the PR, and
+CI now checks that explanation alongside a real messaging scenario.
+
+## Summary of New Capabilities
+
+- Base-ref UX-impact PR lint with literal kill switch and separate error classes.
+- `assertPlainEnglish`, `assertHonestFailure`, and `assertNoZombie` helpers.
+- CI wiring for the assertions in `messaging-multi-agent.test.ts`.

package/upgrades/1.3.948.md

@@ -0,0 +1,18 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The UX PR gate now scopes enforcement to commit authors/committers and the branch pusher, verifies refactor-only exemptions deterministically, publishes an exemption-rate artifact, and blocks merge safety on internal lint errors. ELI16 companion generation no longer creates `.eli16.eli16.md` duplicates.
+
+## What to Tell Your User
+
+Pull requests now show whether a UX lint decision was in scope, whether a refactor exemption was proven, and whether the result was safe to auto-merge. Internal uncertainty stops auto-merge instead of being silently accepted.
+
+## Summary of New Capabilities
+
+- Author-scope union and deterministic refactor-only verification for UX lint.
+- Per-run exemption-rate artifact for the weekly retro.
+- Internal-error merge-safety gate and corrected ELI16 companion naming.

package/upgrades/side-effects/ux-first-enforcement-inc1.md

@@ -0,0 +1,9 @@
+# Side-effects review: UX-first enforcement increment 1
+
+- Adds a separate pull-request workflow and path allowlist; it reads the base-ref diff and PR body only.
+- A missing or shallow UX declaration is a deterministic violation; unexpected tool failure is a distinct fail-open internal error with a loud annotation.
+- Adds three pure assertions with no network, subprocess, or LLM dependency and wires them into the real messaging E2E scenario.
+- `assertTimely` and content-sniff/ownership annotation work remain explicitly deferred to Increment 2.
+- Rollback is removing the workflow/script/helper imports; no durable migration is required.
+- The substance-floor matcher accepts single-, double-, and backtick-quoted diff strings so normal source quoting cannot create a false negative.
+- The workflow also runs the messaging E2E in CI, making the three deterministic assertions an enforced, visible check.

package/upgrades/side-effects/ux-first-enforcement-inc2.md

@@ -0,0 +1,7 @@
+# Side-effects review: UX-first enforcement increment 2
+
+- Extends the deterministic PR lint with author/committer plus pusher scope, a verified refactor-only exemption, and a per-run exemption-rate artifact.
+- Internal lint errors remain distinct and now make the merge-safety job fail, so native auto-merge cannot arm on an uncertain verdict.
+- Fixes ELI16 companion resolution so an existing `.eli16.md` spec is never given a double suffix; historical duplicate companions are removed.
+- No runtime user-facing behavior changes; proof is the real GitHub PR workflow and its uploaded artifact.
+- The configured author scope is literal and reviewed alongside the kill switch; a pusher outside it is out of scope.