instar 1.3.947 → 1.3.948

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.947",
+  "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/ux-impact-lint.mjs

@@ -2,31 +2,49 @@
 // 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/'));
-  if (allowlisted.length === 0) { console.log('UX lint: out of scope'); process.exit(0); }
+  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 diff = execFileSync('git', ['diff', '--unified=0', `${base}...${head}`, '--', ...allowlisted], { encoding: 'utf8' });
   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-25T00:39:47.923Z",
-  "instarVersion": "1.3.947",
+  "generatedAt": "2026-07-25T01:11:00.882Z",
+  "instarVersion": "1.3.948",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

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-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.