@golden-frijoles/kit 0.12.1 → 0.14.0

package/dist/jev-eval.mjs

@@ -27,15 +27,26 @@
 // wording of intent-match's questions on labelled items, and there is no regex to compare it with, no mode and no
 // threshold. Its report adds how many answers were DECIDED (P ≤ 0.2 or ≥ 0.8) and how many of those were right.
 //
+// The `lint` rail (semantic-lint D8) is reported the same way — its selector picks candidates but has no verdict to
+// compare with — and "decided" means raised or cleared at the rail's own threshold. Its question is project data, so a
+// recording pins the wording's hash, and the fixtures live in the project's own jev-eval.lint.fixtures.json.
+//
 // Zero deps — Node 18+.
 
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readSection } from './lib/config.mjs';
 import { loadJevConfig, parseJevConfig, RAILS, readApiKey, repoRoot } from './lib/jev.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const FIXTURES_PATH = join(__dirname, 'jev-eval.fixtures.json');
+/**
+ * The `lint` set's fixtures are PROJECT data, like the rules they measure (semantic-lint D8, fresh review of #200):
+ * this repo's rule-1 labels shipped in the shared file would fail any consumer whose own rule reused the id, and fail
+ * every consumer with a rule but no such fixtures. So they live beside the script in a file the template never has.
+ */
+export const LINT_FIXTURES_PATH = join(__dirname, 'jev-eval.lint.fixtures.json');
 
 /** Shadow is a short, expiring measurement: at most this many days out, ever. */
 export const MAX_SHADOW_DAYS = 21;
@@ -74,6 +85,11 @@ export function expiredShadowRails(config, today) {
 export function coverageFailures(fixtures, rails) {
   const out = [];
   for (const name of EVAL_SETS) {
+    // A set that knows its own coverage rule (lint: per configured rule) answers for itself.
+    if (rails[name]?.coverage) {
+      out.push(...rails[name].coverage(fixtures[name] ?? []));
+      continue;
+    }
     const n = (fixtures[name] ?? []).length;
     if (!rails[name] && n)
       out.push(`${name}: ${n} fixture(s) but no judge to replay them — was the judge renamed?`);
@@ -132,7 +148,7 @@ const sortedCodes = (findings) =>
  * The rails this harness can evaluate. Each judge is looked up by name so a rail whose judge has not
  * landed yet is SKIPPED loudly instead of failing the import.
  */
-export async function loadRails() {
+export async function loadRails({ lintRules = [] } = {}) {
   const rails = {};
   const review = await import('./lib/review-guard.mjs');
   if (typeof review.judgeReviewOutput === 'function')
@@ -161,6 +177,43 @@ export async function loadRails() {
       expected: (fx) => fx.label,
       summary: (d) => ({ value: d.value, p: d.p, decider: d.decider }),
     };
+  // semantic-lint D8. The QUESTION is the project's own data (`lint.rules`), so a fixture is replayed against the
+  // rule this project has; one whose rule it lacks (the template's own run) is skipped and counted, never scored.
+  const lint = await import('./semantic-lint.mjs');
+  if (typeof lint.judgeCandidate === 'function') {
+    const byId = new Map(lintRules.map((r) => [r.id, r]));
+    rails.lint = {
+      // Never replayed (there is no question to replay it against) — and `coverage` below fails it, so a renamed or
+      // removed rule cannot go green by skipping every fixture it had (fresh review of #200).
+      skip: (fx) => (byId.has(fx.rule) ? null : `no rule "${fx.rule}" in this project's lint config`),
+      coverage: (cases) => [
+        ...[...new Set(cases.filter((fx) => !byId.has(fx.rule)).map((fx) => fx.rule))].map(
+          (id) => `lint: fixtures for "${id}", which this project's lint config does not define — renamed or removed?`
+        ),
+        ...[...byId.keys()]
+          .map((id) => [id, cases.filter((fx) => fx.rule === id).length])
+          .filter(([, n]) => n < MIN_FIXTURES)
+          .map(([id, n]) => `lint/${id}: only ${n} labelled fixture(s); a rule needs ≥${MIN_FIXTURES}`),
+      ],
+      // A recording answers the wording that produced it: an edited question replaying green would prove nothing.
+      stale: (fx) =>
+        fx.recorded?.questionHash === lint.questionHash(byId.get(fx.rule))
+          ? null
+          : `recorded against another wording of ${fx.rule}'s question — run --live`,
+      recordExtra: (fx) => ({ questionHash: lint.questionHash(byId.get(fx.rule)) }),
+      run: (fx, deps) =>
+        lint.judgeCandidate(
+          { rule: byId.get(fx.rule), file: fx.file, hunk: fx.hunk },
+          { ask: deps.ask, threshold: lint.thresholdFor(deps.config.rails.lint, fx.rule) }
+        ),
+      regex: null, // the selector only picks candidates; it has no verdict of its own to compare with
+      predicted: (d) => (d.outcome === 'raise' ? true : d.outcome === 'clear' ? false : null),
+      expected: (fx) => fx.label,
+      // Decided = raised or cleared at THIS rail's threshold, not intent's fixed margin.
+      decided: (d) => d.outcome === 'raise' || d.outcome === 'clear',
+      summary: (d) => ({ outcome: d.outcome, p: d.p }),
+    };
+  }
   return rails;
 }
 
@@ -215,6 +268,13 @@ export async function evaluate({
     const tally = { n: cases.length, jevRight: 0, regexRight: 0, disagreements: 0, families: {} };
     if (!rail.regex) Object.assign(tally, { regexRight: null, disagreements: null, decided: 0, decidedRight: 0 });
     for (const fx of cases) {
+      const skip = rail.skip?.(fx);
+      if (skip) {
+        tally.n--;
+        tally.skipped = (tally.skipped ?? 0) + 1;
+        tally.skipWhy = skip;
+        continue;
+      }
       const sink = { answers: {}, model: null, errors: [] };
       const deps = {
         config: cfg,
@@ -230,6 +290,11 @@ export async function evaluate({
         );
         continue;
       }
+      const stale = live ? null : rail.stale?.(fx);
+      if (stale) {
+        failures.push(`${name}/${fx.id}: ${stale}`);
+        continue;
+      }
       const decision = await rail.run(fx, deps);
       const summary = rail.summary(decision);
       if (live && sink.errors.length) {
@@ -242,7 +307,7 @@ export async function evaluate({
       if (live) {
         // A draft the judge needed no answers for (e.g. a heading-only unit, which is never asked about) is
         // recorded as answered by the pinned model with no answers — replaying it asks nothing.
-        fx.recorded = { model: sink.model ?? cfg.model, answers: sink.answers };
+        fx.recorded = { model: sink.model ?? cfg.model, answers: sink.answers, ...(rail.recordExtra?.(fx) ?? {}) };
         fx.decision = summary;
       } else if (!same(summary, fx.decision)) {
         failures.push(
@@ -253,7 +318,10 @@ export async function evaluate({
       const jevRight = same(rail.predicted(decision), expected);
       tally.jevRight += jevRight;
       if (!rail.regex) {
-        if (typeof decision.p === 'number' && Math.abs(decision.p - 0.5) >= DECIDED_MARGIN) {
+        const decided = rail.decided
+          ? rail.decided(decision)
+          : typeof decision.p === 'number' && Math.abs(decision.p - 0.5) >= DECIDED_MARGIN;
+        if (decided) {
           tally.decided++;
           tally.decidedRight += jevRight;
         }
@@ -283,7 +351,8 @@ export function formatReport(report) {
   for (const [rail, t] of Object.entries(report)) {
     if (t.regexRight === null) {
       lines.push(
-        `${rail}: ${t.n} labelled · jev ${pct(t.jevRight, t.n)} · decided ${t.decided}/${t.n}, ${t.decidedRight} right · no deterministic rule`
+        `${rail}: ${t.n} labelled · jev ${pct(t.jevRight, t.n)} · decided ${t.decided}/${t.n}, ${t.decidedRight} right · no deterministic rule` +
+          (t.skipped ? ` · ${t.skipped} skipped (${t.skipWhy})` : '')
       );
       continue;
     }
@@ -378,14 +447,22 @@ export async function run(argv, io = {}) {
 async function main() {
   const root = repoRoot();
   const { askJev } = await import('./lib/jev.mjs');
+  const { parseLintRules } = await import('./semantic-lint.mjs');
   const code = await run(process.argv.slice(2), {
     root,
     config: loadJevConfig({ root }),
-    fixtures: JSON.parse(readFileSync(FIXTURES_PATH, 'utf8')),
-    rails: await loadRails(),
+    fixtures: {
+      ...JSON.parse(readFileSync(FIXTURES_PATH, 'utf8')),
+      lint: existsSync(LINT_FIXTURES_PATH) ? JSON.parse(readFileSync(LINT_FIXTURES_PATH, 'utf8')) : [],
+    },
+    // A malformed lint section throws here: CI must go red on it, not replay against no rules.
+    rails: await loadRails({ lintRules: parseLintRules(readSection('lint', { root }).raw) }),
     key: () => readApiKey({ root }),
     makeAsk: ({ key, model }) => (req) => askJev(req, { key, model }),
-    writeFixtures: (fx) => writeFileSync(FIXTURES_PATH, `${JSON.stringify(fx, null, 2)}\n`),
+    writeFixtures: ({ lint, ...shared }) => {
+      writeFileSync(FIXTURES_PATH, `${JSON.stringify(shared, null, 2)}\n`);
+      if (lint.length) writeFileSync(LINT_FIXTURES_PATH, `${JSON.stringify(lint, null, 2)}\n`);
+    },
     stdout: (t) => process.stdout.write(t),
     stderr: (t) => process.stderr.write(t),
     today: new Date().toISOString().slice(0, 10),

package/dist/lib/config-registry.mjs

@@ -152,6 +152,16 @@ export const REGISTRY = Object.freeze([
     choices: ['off', 'on'],
     question: 'At the architecture lock, ask one other model family (codex, agy or vibe) to read the pitch and score whether it would build the same thing? Off by default; any failure is skipped.',
   },
+  {
+    // semantic-lint D4: the rules the lint rail's selectors run (id, globs, allowlist, patterns, question). never-yet,
+    // like `routines`: it declares the section so `config get/set` accept it, and `gf doctor` (which skips never-yet
+    // rows and prints one line per MODULE) never reports Build unconfigured because a project has no lint rules.
+    key: 'lint.rules',
+    module: 'Build',
+    askWhen: 'never-yet',
+    default: null,
+    question: 'Which rules should semantic-lint check on every push (selectors plus one question each for Jev)?',
+  },
   {
     key: 'spend.telemetry',
     module: 'Spend',

package/dist/lib/config.mjs

@@ -44,6 +44,7 @@ export const SECTIONS = Object.freeze([
   'spend',
   'routines',
   'intent',
+  'lint',
 ]);
 
 /**

package/dist/lib/cross-agent-cli.mjs

@@ -53,10 +53,10 @@ export const AGENT_BIN = {
 // Harmless here since AGY_MODEL/AGY_FALLBACK_MODEL below are always valid, listed model names (checked via
 // `agy models`), but it means a future typo in either constant would silently review with the WRONG model
 // instead of failing loud — watch for that if either constant is ever edited.
-// agy-doctor: last verified 2026-09-29 against 1.2.13.
+// agy-doctor: last verified 2026-09-30 against 1.2.14.
 //   ^ machine-managed marker — `node scripts/cross-agent-doctor.mjs agy --fix` rewrites it (with the constant
 //   below) after a green live contract probe. Don't hand-edit the marker's shape.
-export const AGY_PINNED = '1.2.13';
+export const AGY_PINNED = '1.2.14';
 
 // agy's `--print` mode prints NOTHING unless `--model` names a model — and, crucially, it ALSO prints
 // nothing (exit 0, empty stdout — the error lands only in agy's log, see --log-file) when the model is

package/dist/lib/jev.mjs

@@ -34,7 +34,7 @@ import { needSetting, readSection } from './config.mjs';
 export const JEV_ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 export const DEFAULT_MODEL = 'jev-1.13.0';
 export const MODES = ['off', 'shadow', 'jev'];
-export const RAILS = ['review', 'prose'];
+export const RAILS = ['review', 'prose', 'lint'];
 
 /** 32k tokens covers state + the longest question. ~4 chars/token, with headroom for the question. */
 export const STATE_CHAR_BUDGET = 110_000;
@@ -53,11 +53,19 @@ export const DEFAULT_CONFIG = Object.freeze({
     // thresholds are the MEASURED ones (jev-semantic-guards S5.2, sprint-5.md), not the pitch's starting guesses.
     review: { mode: 'off', thresholds: { real: 0.85, notReal: 0.3 }, shadowExpires: null },
     prose: { mode: 'off', thresholds: { claim: 0.8 }, shadowExpires: null },
+    // semantic-lint D3: `default` plus one optional key per rule id (see LINT_THRESHOLD_KEY below).
+    lint: { mode: 'off', thresholds: { default: 0.8 }, shadowExpires: null },
   },
 });
 
 export class JevConfigError extends Error {}
 
+/**
+ * The lint rail's threshold keys are OPEN — `default` or any rule id — because rules are data (semantic-lint D3/D4):
+ * a new rule must not need a code change here to get its own threshold. Every other rail's keys stay a closed set.
+ */
+export const LINT_THRESHOLD_KEY = /^[a-z0-9][a-z0-9-]*$/;
+
 const isUnit = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1;
 
 /**
@@ -105,10 +113,21 @@ export function parseJevConfig(json) {
       throw new JevConfigError(`jev.config.json: rails.${name}.mode must be one of ${MODES.join(' | ')}`);
     if (r.thresholds !== undefined && !isObj(r.thresholds))
       throw new JevConfigError(`jev.config.json: rails.${name}.thresholds must be an object`);
-    refuseUnknown(r.thresholds ?? {}, Object.keys(d.thresholds), `rails.${name}.thresholds`);
+    if (name === 'lint') {
+      const bad = Object.keys(r.thresholds ?? {}).filter((k) => !LINT_THRESHOLD_KEY.test(k));
+      if (bad.length)
+        throw new JevConfigError(
+          `jev.config.json: rails.lint.thresholds: ${bad.join(', ')} is not \`default\` or a rule id (a-z, 0-9, -)`
+        );
+    } else refuseUnknown(r.thresholds ?? {}, Object.keys(d.thresholds), `rails.${name}.thresholds`);
     const thresholds = { ...d.thresholds, ...(r.thresholds ?? {}) };
     for (const [k, v] of Object.entries(thresholds))
       if (!isUnit(v)) throw new JevConfigError(`jev.config.json: rails.${name}.thresholds.${k} must be 0…1`);
+    // lint raises at p ≥ t and clears at p ≤ 1 − t (semantic-lint D2): below 0.5 those bands overlap, and one
+    // answer would be both a finding and a pass.
+    if (name === 'lint')
+      for (const [k, v] of Object.entries(thresholds))
+        if (v < 0.5) throw new JevConfigError(`jev.config.json: rails.lint.thresholds.${k} must be 0.5…1`);
     if (name === 'review' && thresholds.notReal >= thresholds.real)
       throw new JevConfigError('jev.config.json: rails.review.thresholds.notReal must be below .real');
     const shadowExpires = r.shadowExpires ?? null;

package/dist/semantic-lint.mjs

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+// semantic-lint.mjs — deterministic selectors pick candidate hunks, Jev judges only those (semantic-lint D1–D9).
+//
+//   node scripts/semantic-lint.mjs                          the branch against @{upstream}, else origin/main
+//   node scripts/semantic-lint.mjs --range <base>...<head>  what the pre-push hook passes, once per pushed ref
+//
+// Some rules cannot be a regex: "no parallel telemetry pipeline" (AGENTS rule 1) is broken by a usage table under
+// another name, an analytics route or a vendor SDK call — paraphrases a regex either misses or flags on every read.
+// So the regex only SELECTS (globs + added-line patterns − an allowlist, all data in `lint.rules`), and one Noul per
+// selected hunk asks whether it actually breaks the rule. Most pushes select nothing and make no call at all.
+//
+// Four outcomes, never two (D2): raise, clear, uncertain, and NOT CHECKED — no key, egress off, a timeout, a malformed
+// answer, an oversized hunk, past the candidate cap or the time budget. "Could not look" is printed and logged, and is
+// never counted as clear.
+//
+// Raise-only: this adds findings; it never clears another check's finding, and it never blocks. v1 runs in `shadow`
+// from the advisory pre-push hook: it logs every decision to .jev/decisions.jsonl as `lint:<rule id>` and prints one
+// line per rule. Exit 0 always, except 2 for bad usage or a malformed config — a lint that cannot run must say so, and
+// the hook still ignores the code.
+//
+// Zero deps — Node 18+.
+
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readSection } from './lib/config.mjs';
+import { jevContext, LINT_THRESHOLD_KEY, loadJevConfig, repoRoot, textHash } from './lib/jev.mjs';
+import { globToRegExp } from './lib/review-guard.mjs';
+
+export const QUESTION_ID = 'violates';
+export const SEVERITIES = ['blocking', 'should-fix', 'nit'];
+/** A hunk this long is not sent (D2/D6): it is rarely one decision, and it is the most code to send off the machine. */
+export const HUNK_CHAR_LIMIT = 6_000;
+/** A push selecting more than this is a refactor, not a telemetry change; the rest are not checked, and say so. */
+export const MAX_CANDIDATES = 20;
+/** A git hook must stay a hook: nothing new starts after this, and what is left is not checked. */
+export const TIME_BUDGET_MS = 60_000;
+const CONCURRENCY = 4;
+
+export class LintConfigError extends Error {}
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isUnit = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1;
+const RULE_KEYS = ['id', 'source', 'severity', 'globs', 'allowlist', 'patterns', 'question'];
+
+/**
+ * The `lint` section → rules with their selectors compiled. Pure; throws LintConfigError naming the problem, because a
+ * typo in a glob or a pattern would otherwise select nothing and read as a clean push (CODE-QUALITY §7).
+ * `null` (no section anywhere) is no rules.
+ */
+export function parseLintRules(raw) {
+  if (raw === null || raw === undefined) return [];
+  const fail = (m) => {
+    throw new LintConfigError(`lint: ${m}`);
+  };
+  if (!isObj(raw)) fail('the section must be an object');
+  const extra = Object.keys(raw).filter((k) => k !== 'rules' && !k.startsWith('$'));
+  if (extra.length) fail(`unknown key(s): ${extra.join(', ')}`);
+  if (raw.rules === undefined) return [];
+  if (!Array.isArray(raw.rules)) fail('rules must be an array');
+  const seen = new Set();
+  const strings = (v, where, { nonEmpty }) => {
+    if (!Array.isArray(v) || v.some((x) => typeof x !== 'string' || !x))
+      fail(`${where} must be an array of strings`);
+    if (nonEmpty && !v.length) fail(`${where} must not be empty`);
+    return v;
+  };
+  return raw.rules.map((r, i) => {
+    if (!isObj(r)) fail(`rules[${i}] must be an object`);
+    const at = `rules[${i}]${typeof r.id === 'string' ? ` (${r.id})` : ''}`;
+    const unknown = Object.keys(r).filter((k) => !RULE_KEYS.includes(k) && !k.startsWith('$'));
+    if (unknown.length) fail(`${at}: unknown key(s): ${unknown.join(', ')}`);
+    // The id is also a threshold key in jev.config.json (rails.lint.thresholds.<id>), so it obeys that key's shape.
+    if (typeof r.id !== 'string' || !LINT_THRESHOLD_KEY.test(r.id) || r.id === 'default')
+      fail(`${at}: id must be lowercase a-z, 0-9 and -, and not "default"`);
+    if (seen.has(r.id)) fail(`${at}: duplicate id`);
+    seen.add(r.id);
+    if (typeof r.source !== 'string' || !r.source) fail(`${at}: source must name the rule it enforces`);
+    if (!SEVERITIES.includes(r.severity)) fail(`${at}: severity must be one of ${SEVERITIES.join(' | ')}`);
+    const globs = strings(r.globs, `${at}.globs`, { nonEmpty: true });
+    const allowlist = strings(r.allowlist ?? [], `${at}.allowlist`, { nonEmpty: false });
+    const patterns = strings(r.patterns, `${at}.patterns`, { nonEmpty: true }).map((p) => {
+      try {
+        return new RegExp(p, 'i');
+      } catch (e) {
+        return fail(`${at}.patterns: ${JSON.stringify(p)} is not a valid RegExp (${e.message})`);
+      }
+    });
+    const q = r.question;
+    if (
+      !isObj(q) ||
+      typeof q.instructions !== 'string' ||
+      !q.instructions ||
+      !isObj(q.criteria) ||
+      typeof q.criteria.true !== 'string' ||
+      typeof q.criteria.false !== 'string'
+    )
+      fail(`${at}.question must be { instructions, criteria: { true, false } }, all strings`);
+    return {
+      id: r.id,
+      source: r.source,
+      severity: r.severity,
+      question: {
+        instructions: q.instructions,
+        criteria: { true: q.criteria.true, false: q.criteria.false },
+      },
+      match: { globs: globs.map(globToRegExp), allow: allowlist.map(globToRegExp), patterns },
+    };
+  });
+}
+
+/** The one Noul a rule asks, in the shape askJev sends. */
+export const questionsFor = (rule) => ({ [QUESTION_ID]: { type: 'noul', ...rule.question } });
+
+/** Pins a recording to the wording that produced it: an edited question must be re-measured, not replayed (D8). */
+export const questionHash = (rule) =>
+  // `source` is sent in the state beside the question, so it is part of what was measured (fresh review of #200).
+  textHash(JSON.stringify({ questions: questionsFor(rule), source: rule.source }));
+
+/**
+ * `git diff` text → [{ file, hunks: [{ header, lines: [diff line], added: [line] }] }]. Pure. `lines` keep their +/-/space
+ * prefix, as the diff shows them.
+ */
+export function parseDiff(diffText) {
+  const files = [];
+  let file = null;
+  let hunk = null;
+  for (const line of String(diffText).split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      file = null;
+      hunk = null;
+      continue;
+    }
+    // Only a header before the first `@@` is a file header: inside a hunk, an added line whose content starts with
+    // `++ ` also reads `+++ …`, and taking it for a new file would drop the rest of the hunk.
+    if (!hunk && line.startsWith('+++ ')) {
+      // `+++ /dev/null` is a deletion: it adds nothing, so it selects nothing.
+      const path = line.slice(4).replace(/\t.*$/, '');
+      file = path === '/dev/null' ? null : { file: path.replace(/^b\//, ''), hunks: [] };
+      if (file) files.push(file);
+      hunk = null;
+      continue;
+    }
+    if (!file) continue;
+    if (line.startsWith('@@')) {
+      hunk = { header: line, lines: [], added: [] };
+      file.hunks.push(hunk);
+      continue;
+    }
+    if (!hunk) continue;
+    if (line.startsWith('+')) hunk.added.push(line.slice(1));
+    if (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) hunk.lines.push(line);
+  }
+  return files;
+}
+
+/** Lines of a hunk kept around each matching added line. */
+export const WINDOW = 15;
+
+/**
+ * What is sent for one candidate (D1/D6): the hunk's `@@` header and a window of WINDOW lines either side of each
+ * matching added line, overlapping windows merged, gaps marked `…`. Not the whole hunk: a new file is ONE hunk, and
+ * measured on 220 commits of this repo's history, 33 of 60 candidate hunks were over HUNK_CHAR_LIMIT — nearly every
+ * new route and migration would have been "not checked". Pure.
+ */
+export function candidateText(hunk, isHit) {
+  const keep = new Set();
+  hunk.lines.forEach((l, i) => {
+    if (!l.startsWith('+') || !isHit(l.slice(1))) return;
+    for (let j = Math.max(0, i - WINDOW); j <= Math.min(hunk.lines.length - 1, i + WINDOW); j++) keep.add(j);
+  });
+  const out = [hunk.header];
+  let prev = -1;
+  for (const i of [...keep].sort((a, b) => a - b)) {
+    if (i !== prev + 1) out.push('…');
+    out.push(hunk.lines[i]);
+    prev = i;
+  }
+  if (prev < hunk.lines.length - 1) out.push('…');
+  return out.join('\n');
+}
+
+/**
+ * The deterministic half (D1): every hunk, per rule, in a file its globs match and its allowlist does not, with at
+ * least one ADDED line a pattern matches. Removed and context lines never select — deleting a vendor call is not a
+ * reason to ask. Duplicates (the same hunk reached through two pushed refs) collapse. Pure.
+ */
+export function selectCandidates(files, rules) {
+  const out = [];
+  const seen = new Set();
+  for (const rule of rules)
+    for (const { file, hunks } of files) {
+      if (!rule.match.globs.some((re) => re.test(file))) continue;
+      if (rule.match.allow.some((re) => re.test(file))) continue;
+      for (const h of hunks) {
+        const hits = rule.match.patterns
+          .filter((re) => h.added.some((l) => re.test(l)))
+          .map((re) => re.source);
+        if (!hits.length) continue;
+        const text = candidateText(h, (l) => rule.match.patterns.some((re) => re.test(l)));
+        const key = `${rule.id}\0${file}\0${textHash(text)}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ rule, file, hunk: text, hits });
+      }
+    }
+  return out;
+}
+
+/** D2 — one statistic per rule. Only a probability in [0,1] is a verdict (LEARNINGS: `Number(true)` once passed). */
+export function outcomeOf(p, threshold) {
+  if (!isUnit(p)) return null;
+  if (p >= threshold) return 'raise';
+  // `1 - p >= t`, not `p <= 1 - t`: 1 - 0.8 is 0.19999…, which put p = 0.2 in the uncertain band.
+  if (1 - p >= threshold) return 'clear';
+  return 'uncertain';
+}
+
+/** A rule's threshold: its own key in rails.lint.thresholds, else `default`. */
+export const thresholdFor = (rail, ruleId) => rail.thresholds[ruleId] ?? rail.thresholds.default;
+
+/**
+ * Ask about one candidate. Never throws (askJev does not, and a non-probability is not-checked).
+ * Returns { outcome: raise|clear|uncertain|not-checked, p, error }.
+ */
+export async function judgeCandidate(c, { ask, threshold }) {
+  const res = await ask({
+    state: { rule: c.rule.id, source: c.rule.source, file: c.file, hunk: c.hunk },
+    questions: questionsFor(c.rule),
+  });
+  if (!res?.ok) return { outcome: 'not-checked', p: null, error: res?.error ?? 'no response' };
+  const raw = res.answers?.[QUESTION_ID]?.noul;
+  const outcome = outcomeOf(raw, threshold);
+  if (!outcome) return { outcome: 'not-checked', p: null, error: `invalid noul (${JSON.stringify(raw)})` };
+  return { outcome, p: Math.round(raw * 1000) / 1000, error: null };
+}
+
+/** The reason a person reads. `no key` is the words the smoke walkthrough and the hook's users look for. */
+const reasonFor = (why) => (why === 'no TYPESAFE_API_KEY' ? 'no key' : why);
+
+/**
+ * Judge every candidate under the caps and the budget (D2), log each decision (D7). Returns the results in candidate
+ * order. `notChecked` (a reason) short-circuits every call: Jev could not legitimately be asked at all.
+ */
+export async function judgeAll(
+  candidates,
+  { ask, log, rail, mode, sha, notChecked = null, now = Date.now, budgetMs = TIME_BUDGET_MS }
+) {
+  const deadline = now() + budgetMs;
+  const results = new Array(candidates.length);
+  const judgeOne = async (i) => {
+    const c = candidates[i];
+    let r;
+    if (notChecked) r = { outcome: 'not-checked', p: null, error: notChecked };
+    else if (i >= MAX_CANDIDATES)
+      r = { outcome: 'not-checked', p: null, error: `over the ${MAX_CANDIDATES}-candidate cap` };
+    else if (c.hunk.length > HUNK_CHAR_LIMIT)
+      r = { outcome: 'not-checked', p: null, error: `hunk over ${HUNK_CHAR_LIMIT} chars (${c.hunk.length})` };
+    else if (now() >= deadline)
+      r = { outcome: 'not-checked', p: null, error: `time budget (${budgetMs / 1000}s) spent` };
+    else r = await judgeCandidate(c, { ask, threshold: thresholdFor(rail, c.rule.id) });
+    results[i] = r;
+    log({
+      rail: `lint:${c.rule.id}`,
+      mode,
+      decider: r.outcome === 'not-checked' ? 'not-checked' : 'jev',
+      regex: null,
+      jev: r.outcome === 'not-checked' ? null : r.outcome === 'raise',
+      confidence: r.p,
+      text: c.hunk,
+      source: `${c.file}@${sha ?? 'unknown'}`,
+      evidence: { file: c.file, outcome: r.outcome, hits: c.hits },
+      error: r.error,
+    });
+  };
+  let next = 0;
+  const worker = async () => {
+    while (next < candidates.length) await judgeOne(next++);
+  };
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, candidates.length) }, worker));
+  return results;
+}
+
+/** D9 — one line per rule, plus one finding line per raise in `jev` mode. Pure. */
+export function summarize(candidates, results, { mode }) {
+  const lines = [];
+  const byRule = new Map();
+  candidates.forEach((c, i) => {
+    if (!byRule.has(c.rule.id)) byRule.set(c.rule.id, []);
+    byRule.get(c.rule.id).push({ c, r: results[i] });
+  });
+  for (const [id, rows] of byRule) {
+    const of = (o) => rows.filter((x) => x.r.outcome === o);
+    const raised = of('raise');
+    const nc = of('not-checked');
+    if (nc.length === rows.length) {
+      const reasons = [...new Set(nc.map((x) => reasonFor(x.r.error)))];
+      lines.push(
+        `semantic-lint: not checked (${reasons.join('; ')}) — lint:${id}, ${rows.length} candidate(s) logged, none judged`
+      );
+      continue;
+    }
+    const parts = [];
+    if (raised.length)
+      parts.push(
+        `${raised.length} ${mode === 'jev' ? 'raised' : 'would raise'} (${raised.map((x) => `p=${x.r.p} ${x.c.file}`).join(', ')})`
+      );
+    for (const o of ['uncertain', 'clear']) if (of(o).length) parts.push(`${of(o).length} ${o}`);
+    if (nc.length)
+      parts.push(
+        `${nc.length} not checked (${[...new Set(nc.map((x) => reasonFor(x.r.error)))].join('; ')})`
+      );
+    const tail = mode === 'jev' ? 'logged' : 'logged, not shown as findings';
+    lines.push(
+      `semantic-lint (${mode}): lint:${id} — ${rows.length} candidate(s): ${parts.join(', ')} · ${tail}`
+    );
+    if (mode === 'jev')
+      for (const { c, r } of raised)
+        lines.push(`  [${c.rule.severity}] ${c.file}: p=${r.p} — may break ${c.rule.source}`);
+  }
+  return lines;
+}
+
+const USAGE = 'usage: node scripts/semantic-lint.mjs [--range <base>...<head>]…';
+
+/** Pure — `--range` values, or { error }. */
+export function parseArgs(argv) {
+  const ranges = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--range' && argv[i + 1] && !argv[i + 1].startsWith('--')) ranges.push(argv[++i]);
+    else return { error: `unexpected argument ${JSON.stringify(argv[i])}` };
+  }
+  return { ranges };
+}
+
+/**
+ * The CLI with every side effect injected (specs never touch git, the network or the real log). Returns the exit code.
+ * io: { root, jevConfig(), lintSection(), defaultRange(), diff(range), headSha(range), context(config), stdout, stderr }
+ */
+export async function run(argv, io) {
+  const args = parseArgs(argv);
+  if (args.error) {
+    io.stderr(`semantic-lint: ${args.error}\n${USAGE}\n`);
+    return 2;
+  }
+  let config;
+  let rules;
+  try {
+    config = io.jevConfig();
+    // Off exits before anything else — before the rules are read and, above all, before jevContext, whose unanswered-
+    // egress ask must never fire on a stranger's push for a rail they never turned on (D6).
+    if (config.rails.lint.mode === 'off') {
+      io.stdout('semantic-lint: off (jev.rails.lint.mode)\n');
+      return 0;
+    }
+    rules = parseLintRules(io.lintSection());
+  } catch (e) {
+    io.stderr(`semantic-lint: not run — ${e.message}\n`);
+    return 2;
+  }
+  if (!rules.length) {
+    io.stdout('semantic-lint: no rules (lint.rules is empty)\n');
+    return 0;
+  }
+  const ranges = args.ranges.length ? args.ranges : [io.defaultRange()];
+  let files = [];
+  try {
+    for (const range of ranges) files = files.concat(parseDiff(io.diff(range)));
+  } catch (e) {
+    // Could not look is never a pass: say it, even though there is nothing to log per candidate.
+    io.stdout(`semantic-lint: not checked (could not read the diff: ${String(e.message).split('\n')[0]})\n`);
+    return 0;
+  }
+  const candidates = selectCandidates(files, rules);
+  const mode = config.rails.lint.mode;
+  if (!candidates.length) {
+    io.stdout(`semantic-lint (${mode}): nothing to judge — no added line matched a rule's selector\n`);
+    return 0;
+  }
+  const ctx = io.context(config);
+  const results = await judgeAll(candidates, {
+    ask: ctx.ask,
+    log: ctx.log,
+    rail: config.rails.lint,
+    mode,
+    sha: io.headSha(ranges[ranges.length - 1]),
+    notChecked: ctx.mode === 'off' ? ctx.why : null,
+  });
+  for (const line of summarize(candidates, results, { mode })) io.stdout(`${line}\n`);
+  return 0;
+}
+
+const git = (root, args) =>
+  execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+async function main() {
+  const root = repoRoot();
+  const code = await run(process.argv.slice(2), {
+    jevConfig: () => loadJevConfig({ root }),
+    lintSection: () => readSection('lint', { root }).raw,
+    defaultRange: () => {
+      try {
+        git(root, ['rev-parse', '--verify', '--quiet', '@{upstream}']);
+        return '@{upstream}...HEAD';
+      } catch {
+        return 'origin/main...HEAD';
+      }
+    },
+    diff: (range) =>
+      // Pinned, not inherited from the person's git config: the default core.quotePath turns a non-ASCII path into
+      // "b/…\303\261.ts", and a custom diff.dstPrefix changes `b/` — either one made a real candidate match no glob
+      // and read as "nothing to judge" (fresh review of #200).
+      git(root, [
+        '-c',
+        'core.quotePath=false',
+        'diff',
+        '--src-prefix=a/',
+        '--dst-prefix=b/',
+        '-U3',
+        '--no-color',
+        '--no-ext-diff',
+        '--diff-filter=d',
+        range,
+      ]),
+    headSha: (range) => {
+      try {
+        return git(root, ['rev-parse', '--short=12', range.split('...').pop() || 'HEAD']).trim();
+      } catch {
+        return null;
+      }
+    },
+    context: (config) => jevContext('lint', { root, config }),
+    stdout: (t) => process.stdout.write(t),
+    stderr: (t) => process.stderr.write(t),
+  });
+  process.exitCode = code;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain)
+  main().catch((e) => {
+    // A hook caller ignores the code, but a person running it by hand must see a crash as one.
+    process.stderr.write(`semantic-lint: ${e?.stack || e}\n`);
+    process.exitCode = 2;
+  });

package/dist/skeleton/Roadmap/LEARNINGS.md

@@ -159,6 +159,9 @@ one-liner + why + date shape.
   non-state-mutating and lock that with a test.
 
 ## Working efficiently
-- **Running a whole multi-sprint epic in one session is the main context-cost driver.** The durable
-  state (the plan file, sprint docs, team memory) makes re-entry cheap by design — compact at each
-  sprint/PR boundary, and for big epics consider a fresh session per sprint.
+- **Session length is set by a measured line, not a stamina rule.** A whole epic in one session is the
+  main context-cost driver, and the durable state (the plan file, sprint docs, team memory) makes
+  re-entry cheap by design — so checkpoint or hand off when the budget line says so (its thresholds
+  live in one table, `THRESHOLDS` in groom's `session-budget.mjs`), not per sprint. Groom's twin rule is "one deep ask
+  per approval gate". *(Sharpened 2026-09-30, session-budget: "fresh session per sprint" was set for
+  earlier models.)*

package/dist/skeleton/Roadmap/WAYS-OF-WORKING.md

@@ -224,8 +224,10 @@ derived views. **`Roadmap/bets/`** holds one file per wave; **`tasks/`** is the
   degrade gracefully.
 - **Worker death is a normal case.** Each builder on its own worktree; a killed worker's uncommitted tree
   is evidence, not garbage; **verify by re-deriving repo state, never by trusting a completion report** —
-  a rate-limited subagent still returns a plausible-sounding result. Compact at sprint/PR boundaries; for a
-  big epic consider a fresh session per sprint.
+  a rate-limited subagent still returns a plausible-sounding result. Checkpoint and hand
+  off when the budget line says so (Claude Code: under the prompt; groom: at each approval gate) —
+  not by sprint count. Where no line shows (function hooks off, or no figure yet), compact at
+  sprint/PR boundaries.
 - Commit messages end with the `Co-Authored-By: Claude` trailer.
 - **Language.** Docs, comments and PR descriptions are in **English**. **TEMPLATE FILL-IN:** if your user-facing copy has its own policy (a default plus a bilingual allow-list), state it here and in `AGENTS.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "The scripts the Golden Frijoles skills run, packaged so they work in any repo: planning, build-order, reporting and verification rails. Zero dependencies.",
   "type": "module",
   "bin": {