@golden-frijoles/kit 0.27.0 → 0.27.2

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

@@ -22,6 +22,7 @@ import { spawnSync } from 'node:child_process';
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { assertReviewOutput } from './review-shape.mjs';
 
 // label per agent. Drives both the CLI dispatch and the human-readable header.
 export const AGENTS = {
@@ -551,6 +552,52 @@ export function isTransientAgyError(stderr) {
   );
 }
 
+// WHICH transient failure, because the two that matter mean opposite things to the person reading the error
+// (probed live, agy 1.2.16, 2026-10-04 — it now exits 3 and says why on stderr):
+//   quota     "RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in 155h5m1s." Every Gemini tier
+//             shares one pool, and it is a weekly window: waiting a minute does nothing.
+//   capacity  "UNAVAILABLE (code 503): No capacity available for model gpt-oss-120b-medium" / "high traffic,
+//             please try again in a minute". The SAME call answered fine 14 s later.
+// Both used to end in one message that said "quota", so agents reported agy capped while it worked on their
+// next task. Returns 'quota' | 'capacity' | null; a null on a transient error is some other blip.
+export function agyFailureKind(output) {
+  const text = output || '';
+  if (/RESOURCE_EXHAUSTED|quota (?:reached|exceeded|exhausted)/i.test(text)) return 'quota';
+  if (/no capacity|high traffic|UNAVAILABLE \(code 503\)|overloaded/i.test(text)) return 'capacity';
+  return null;
+}
+
+function agyQuotaReset(output) {
+  return /Resets in ([0-9hms]+)/i.exec(output || '')?.[1] ?? null;
+}
+
+// How often, and how long apart, a 'capacity' answer is retried on the same model before moving on.
+export const AGY_CAPACITY_RETRIES = Number(process.env.AGY_CAPACITY_RETRIES ?? 2);
+export const AGY_CAPACITY_WAIT_MS = Number(process.env.AGY_CAPACITY_WAIT_MS ?? 30_000);
+
+// The reason behind an EMPTY answer. agy can still exit 0 with nothing on stdout, and then the only record of why
+// is its own log (seen on PR #267's security lens, 2026-10-04, which answered on the re-run). The last real error
+// line, skipping the side calls that fail without costing the answer (telemetry, conversation-title generation).
+export function agyLogError(log) {
+  const errors = String(log || '')
+    .split('\n')
+    .filter((l) => /^E\d{4} /.test(l) && !/telemetry|title generation|recordTrajectory/i.test(l));
+  const last = errors.pop();
+  return last ? last.replace(/^E\S+ \S+\s+\d+ \S+\] /, '').slice(0, 240) : null;
+}
+
+function readOrNull(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 export function isContextWindowOverflow(output) {
   // ['’] covers both a straight and a "smart"/curly apostrophe — CLIs are inconsistent about which they emit.
   return /ran out of room in the model['’]?s context window/i.test(output || '');
@@ -884,8 +931,8 @@ export function agyArgs(fullArgv, model = AGY_MODEL) {
 // One `agy -p "<prompt>" --model "<MODEL>"` invocation. The prompt+framed context ride in `fullArgv` (stdin is
 // NOT the prompt and must be at EOF — input:'' gives an immediate EOF or print mode blocks forever). Returns
 // the raw spawn result; the caller classifies status/stdout.
-function execAgy(fullArgv, model, spawn) {
-  return spawn('agy', agyArgs(fullArgv, model), {
+function execAgy(fullArgv, model, spawn, logFile) {
+  return spawn('agy', [...agyArgs(fullArgv, model), ...(logFile ? ['--log-file', logFile] : [])], {
     input: '',
     encoding: 'utf8',
     maxBuffer: 64 * 1024 * 1024,
@@ -1106,7 +1153,7 @@ export function renderFileContext({ attached, omitted }) {
 // separate quota pool) so a Gemini quota exhaustion degrades to GPT-OSS instead of silently blanking the review.
 // We enforce the argv size cap up front (clear message, not an opaque E2BIG). `deps.spawn` is injectable for tests.
 export function runAntigravity(fullArgv, opts = {}, deps = {}) {
-  const { spawn = spawnSync, warn = (m) => process.stderr.write(`${m}\n`) } = deps;
+  const { spawn = spawnSync, warn = (m) => process.stderr.write(`${m}\n`), sleep = sleepSync } = deps;
   if (Buffer.byteLength(fullArgv, 'utf8') > AGY_ARG_LIMIT) {
     return fail(
       opts.soft,
@@ -1124,47 +1171,76 @@ export function runAntigravity(fullArgv, opts = {}, deps = {}) {
       ? [AGY_MODEL]
       : [AGY_MODEL, AGY_FALLBACK_MODEL];
   const tried = [];
-  for (const model of modelPair) {
-    const r = execAgy(fullArgv, model, spawn);
-    if (r.status !== 0) {
-      const last = (r.stderr || '').trim().split('\n').filter(Boolean).pop() || 'unknown error';
-      // A non-zero exit is USUALLY a real agy error (bad flags, crash) — surface those directly
-      // rather than burning the fallback on them.
-      //
-      // But not always, and this cost a real run to learn (2026-07-25, commit-report's first live
-      // use after merge): `gpt-oss-120b-medium` answered "Our servers are experiencing high traffic
-      // right now, please try again in a minute" with a NON-ZERO exit. That is precisely the
-      // situation the second model exists for — a different provider with a separate capacity pool
-      // — and the old branch refused to try it, because the fallback was wired only to the
-      // EMPTY-output signal. Same transient condition, different exit code, no fallback.
-      // Classify on the FULL output, not on `last`. `last` is only the final non-empty stderr line,
-      // chosen because it makes the best human-readable message — but agy can emit the transient
-      // notice followed by a stack trace or a trailing status line, which would push the phrase we
-      // match on out of view and abort instead of falling back (cross-review, PR #29). Both streams
-      // are checked because agy is already known to split diagnostics across them inconsistently —
-      // the same reason isContextWindowOverflow is called on stdout and stderr above.
-      const failureOutput = `${r.stderr || ''}\n${r.stdout || ''}`;
-      if (isTransientAgyError(failureOutput) && model !== modelPair[modelPair.length - 1]) {
-        warn(`⚠ agy "${model}" is temporarily unavailable (${last}) → trying the fallback model.`);
-        tried.push(model);
-        continue;
+  const causes = []; // one plain line per model that did not answer, for the final message
+  const logDir = mkdtempSync(join(tmpdir(), 'agy-log-'));
+  try {
+    for (const model of modelPair) {
+      const logFile = join(logDir, `${model}.log`);
+      let r = execAgy(fullArgv, model, spawn, logFile);
+      for (let retry = 1; retry <= AGY_CAPACITY_RETRIES; retry += 1) {
+        if (r.status === 0 || agyFailureKind(`${r.stderr || ''}\n${r.stdout || ''}`) !== 'capacity') break;
+        warn(
+          `⚠ agy "${model}" has no capacity right now (not quota) → retry ${retry}/${AGY_CAPACITY_RETRIES} in ${Math.round(AGY_CAPACITY_WAIT_MS / 1000)}s.`
+        );
+        sleep(AGY_CAPACITY_WAIT_MS);
+        r = execAgy(fullArgv, model, spawn, logFile);
       }
-      return fail(opts.soft, `agy -p failed (model "${model}"): ${last}`);
-    }
-    const out = (r.stdout || '').trim();
-    if (out) {
-      if (model !== modelPair[0])
-        warn(`⚠ agy "${modelPair[0]}" returned no output (quota/unavailable?) → used "${model}".`);
-      // Tell the caller WHICH model answered. Added because the prose rail's footer said "agy",
-      // which cannot distinguish the primary from the fallback — so a silent switch between two
-      // models with very different registers was unattributable in the channel, and that is exactly
-      // the confusion that took a human to notice. Optional and side-effect-only, so every existing
-      // caller keeps its byte-identical string return.
-      opts.onModel?.(model);
-      return out;
+      if (r.status !== 0) {
+        const last = (r.stderr || '').trim().split('\n').filter(Boolean).pop() || 'unknown error';
+        // A non-zero exit is USUALLY a real agy error (bad flags, crash) — surface those directly
+        // rather than burning the fallback on them.
+        //
+        // But not always, and this cost a real run to learn (2026-07-25, commit-report's first live
+        // use after merge): `gpt-oss-120b-medium` answered "Our servers are experiencing high traffic
+        // right now, please try again in a minute" with a NON-ZERO exit. That is precisely the
+        // situation the second model exists for — a different provider with a separate capacity pool
+        // — and the old branch refused to try it, because the fallback was wired only to the
+        // EMPTY-output signal. Same transient condition, different exit code, no fallback.
+        // Classify on the FULL output, not on `last`. `last` is only the final non-empty stderr line,
+        // chosen because it makes the best human-readable message — but agy can emit the transient
+        // notice followed by a stack trace or a trailing status line, which would push the phrase we
+        // match on out of view and abort instead of falling back (cross-review, PR #29). Both streams
+        // are checked because agy is already known to split diagnostics across them inconsistently —
+        // the same reason isContextWindowOverflow is called on stdout and stderr above.
+        const failureOutput = `${r.stderr || ''}\n${r.stdout || ''}`;
+        const kind = agyFailureKind(failureOutput);
+        const cause =
+          kind === 'quota'
+            ? `quota reached${agyQuotaReset(failureOutput) ? `, resets in ${agyQuotaReset(failureOutput)}` : ''}`
+            : kind === 'capacity'
+              ? `no capacity after ${AGY_CAPACITY_RETRIES + 1} tries (transient, NOT quota; re-run in a few minutes)`
+              : last;
+        causes.push(`"${model}": ${cause}`);
+        if (isTransientAgyError(failureOutput) && model !== modelPair[modelPair.length - 1]) {
+          warn(`⚠ agy "${model}" is unavailable (${cause}) → trying the fallback model.`);
+          tried.push(model);
+          continue;
+        }
+        return fail(opts.soft, `agy -p failed — ${causes.join('; ')}`);
+      }
+      const out = (r.stdout || '').trim();
+      if (out) {
+        if (model !== modelPair[0])
+          warn(`⚠ agy "${modelPair[0]}" did not answer (${causes[0]}) → used "${model}".`);
+        // Tell the caller WHICH model answered. Added because the prose rail's footer said "agy",
+        // which cannot distinguish the primary from the fallback — so a silent switch between two
+        // models with very different registers was unattributable in the channel, and that is exactly
+        // the confusion that took a human to notice. Optional and side-effect-only, so every existing
+        // caller keeps its byte-identical string return.
+        opts.onModel?.(model);
+        return out;
+      }
+      const why = agyLogError(readOrNull(logFile));
+      causes.push(
+        `"${model}": empty output${why ? ` — agy's log says: ${why}` : ' and no error in its log'}`
+      );
+      tried.push(model);
     }
-    tried.push(model);
+  } finally {
+    rmSync(logDir, { recursive: true, force: true });
   }
+  if (causes.some((c) => c.includes("agy's log says")))
+    return fail(opts.soft, `agy returned no review — ${causes.join('; ')}`);
   return fail(
     opts.soft,
     `agy returned no output for ${tried.map((m) => `"${m}"`).join(' and ')} — likely a quota cap ` +
@@ -1338,14 +1414,18 @@ export function runVibe(fullArgv, opts = {}, deps = {}) {
  * Two signals, both cheap and neither dependent on the model's wording:
  *   1. the output STARTS with a tool call (`read_file{…}`, `grep {…}`) — the literal shape vibe emits
  *      when it is cut off between turns, or when it asks for a tool that is disabled;
- *   2. it never mentions Blocking / Should-fix / Nit, which the review prompt requires.
+ *   2. it is not a review by review-guard's own test: no severity heading and no clean verdict.
+ *
+ * (2) used to be its own list — Blocking / Should-fix / Nit only — so `Clean.`, the one-line verdict the
+ * prompt asks for on a clean diff, failed here as "truncated" before review-guard ever saw it. Every clean
+ * vibe review died that way (reproduced on PR #265, 2026-10-04). One definition of "a review" now.
  *
  * Exported for the unit layer: this is the guard whose absence let a non-review reach a PR.
  */
 export function isTruncatedReview(out) {
   const text = String(out || '').trim();
   if (/^\w+\s*\{/.test(text)) return true;
-  return !/\b(blocking|should-fix|nit)\b/i.test(text);
+  return !assertReviewOutput(text).ok;
 }
 
 // One `claude -p "<prompt>"` invocation with the context piped on stdin (same shape as codex, which is why

package/dist/lib/log-branch.mjs

@@ -12,6 +12,12 @@
 
 import { spawnSync } from 'node:child_process';
 
+// Every log commit also carries this vercel.json. A log branch is an orphan with no package.json, and a
+// repo whose Vercel project builds every pushed branch tried to build it as a preview and failed on each
+// write ("No Next.js version detected", claude/session-journal, 2026-10-04). Vercel reads vercel.json from
+// the commit it is about to build, so the branch itself has to say "don't".
+export const LOG_BRANCH_VERCEL_JSON = `${JSON.stringify({ git: { deploymentEnabled: false } }, null, 2)}\n`;
+
 function git(args, opts = {}) {
   return spawnSync('git', args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...opts });
 }
@@ -34,7 +40,7 @@ export function readLogFromBranch({ cwd, branch, path }) {
 }
 
 // Writes `content` to `path` on `branch`, creating the branch if it doesn't exist yet. Pure plumbing:
-// hash-object (write a blob) → mktree (a single-file tree) → commit-tree (parented on the branch's
+// hash-object (write a blob) → mktree (the file plus LOG_BRANCH_VERCEL_JSON) → commit-tree (parented on the branch's
 // current tip, if any) → push the new commit straight to the branch ref. Returns true on success.
 //
 // `path` MUST be a flat filename (no `/`) — `git mktree` builds a single-level tree, and a slash needs a
@@ -58,7 +64,17 @@ export function writeLogToBranch({ cwd, branch, path, content, message }) {
   }
   const blobSha = hashObj.stdout.trim();
 
-  const mktree = git(['mktree'], { cwd, input: `100644 blob ${blobSha}\t${path}\n` });
+  let tree = `100644 blob ${blobSha}\t${path}\n`;
+  if (path !== 'vercel.json') {
+    const vercelObj = git(['hash-object', '-w', '--stdin'], { cwd, input: LOG_BRANCH_VERCEL_JSON });
+    if (vercelObj.status !== 0) {
+      console.error(`log-branch: git hash-object (vercel.json) failed: ${(vercelObj.stderr || '').trim()}`);
+      return false;
+    }
+    tree += `100644 blob ${vercelObj.stdout.trim()}\tvercel.json\n`;
+  }
+
+  const mktree = git(['mktree'], { cwd, input: tree });
   if (mktree.status !== 0) {
     console.error(`log-branch: git mktree failed: ${(mktree.stderr || '').trim()}`);
     return false;

package/dist/lib/review-guard.mjs

@@ -38,39 +38,13 @@
 import { spawnSync } from 'node:child_process';
 import { jevContext } from './jev.mjs';
 import { loadQuestions, wireQuestion } from './jev-questions.mjs';
+import { TOOL_TRANSCRIPT, assertReviewOutput } from './review-shape.mjs';
+
+export { assertReviewOutput };
 
 /** Codex CLI version last observed producing a real, structured review. Bump after a verified run. */
 export const CODEX_VERIFIED = '0.154.0';
 
-const SEVERITY_HEADING =
-  /^\s{0,3}(?:[-*+]\s+|\d+\.\s+|>\s*|\|\s*)?(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:🔴|🟠|🟡|⚪)?\s*(?:blocking|should[- ]fix|nits?|important|critical|findings?|correctness(?:\s*(?:&|and)\s*architecture)?|security(?: review)? findings?)\b/im;
-/^\s{0,3}(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:🔴|🟠|🟡|⚪)?\s*(?:blocking|should[- ]fix|nits?|important|critical)\b/im;
-const CLEAN_VERDICT =
-  /(?:^\s{0,3}(?:[-*+]\s+)?(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:clean|none)\b|\bassessment:\s*(?:\*\*)?\s*clean\b|\bno\s+(?:\*\*)?(?:blocking|security|should[- ]fix|nit)\b[^.\n]{0,80}\b(?:findings|issues|problems)\b|\bno (?:findings|issues|problems)\b|\bnothing (?:to report|found|blocking)\b|\blooks clean\b|\bdiff (?:is|looks) clean\b|\bno concerns\b)/im;
-/(?:^\s{0,3}(?:#{1,6}\s*)?(?:\*\*|__)?\s*clean\b|\bassessment:\s*(?:\*\*)?\s*clean\b|\bno (?:blocking |security )?(?:findings|issues|problems)\b|\bnothing (?:to report|found|blocking)\b|\blooks clean\b|\bdiff (?:is|looks) clean\b|\bno concerns\b)/im;
-// A reviewer that emitted a raw tool call instead of a review — observed twice from vibe on real PRs
-// (`read_file{"path": …}`, `write_file…{"file_path": …}`). Its JSON can CONTAIN review-shaped words, so
-// this is checked first and wins.
-const TOOL_TRANSCRIPT = /^\s*[a-z_]+\S*\s*\{\s*"/i;
-
-/**
- * THE GUARD. Pure. Returns { ok, reason }.
- * ok when the reply has a severity heading or an explicit clean verdict; fails on empty, whitespace,
- * or prose with neither (a CLI banner, an error page, a truncated tool transcript).
- */
-export function assertReviewOutput(text) {
-  const t = String(text ?? '').trim();
-  if (!t) return { ok: false, reason: 'the reviewer returned no output' };
-  if (TOOL_TRANSCRIPT.test(t))
-    return { ok: false, reason: `the reviewer emitted a raw tool call, not a review ("${t.slice(0, 80)}")` };
-  if (SEVERITY_HEADING.test(t)) return { ok: true, reason: 'severity-structured findings' };
-  if (CLEAN_VERDICT.test(t)) return { ok: true, reason: 'explicit clean verdict' };
-  return {
-    ok: false,
-    reason: `the reviewer's reply has no severity heading and no clean verdict — not a review (first line: "${t.split('\n')[0].slice(0, 120)}")`,
-  };
-}
-
 /** Minimal glob → RegExp: `**` any depth, `*` within a segment, `?` one char. Anchored, case-sensitive. */
 export function globToRegExp(glob) {
   let re = '';
@@ -289,7 +263,7 @@ export const RE_REVIEW_NOTE =
   '\n\n## RE-REVIEW\nA previous pass already reviewed this PR and the author has pushed changes since. Report **Blocking and Should-fix findings only** — no nits, and do not repeat a finding the author has already fixed or answered on the PR.\n';
 
 // ── 4. Jev decides the SEMANTIC question (jev-semantic-guards D4/D5) ────────────────────────────────
-// `assertReviewOutput` above is a regex asking a language question — "did the reviewer actually review?" —
+// `assertReviewOutput` (review-shape.mjs) is a regex asking a language question — "did the reviewer actually review?" —
 // and on 2026-09-19 it answered it wrong in both directions: it REJECTED a real finding written as plain
 // prose, and ACCEPTED `## Findings` followed by "(reviewer timed out before completing analysis)". Jev
 // (TypeSafe's calibrated typed-judgement model) got both right. So the judge below asks Jev, by

package/dist/lib/review-shape.mjs

@@ -0,0 +1,30 @@
+// review-shape.mjs — "is this text a review at all?", with no dependencies, so a runner can ask it without
+// pulling review-guard's Jev machinery into its closure. review-guard re-exports assertReviewOutput and uses it as
+// the offline fallback; cross-agent-cli's isTruncatedReview asks the same function, so there is one definition.
+
+const SEVERITY_HEADING =
+  /^\s{0,3}(?:[-*+]\s+|\d+\.\s+|>\s*|\|\s*)?(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:🔴|🟠|🟡|⚪)?\s*(?:blocking|should[- ]fix|nits?|important|critical|findings?|correctness(?:\s*(?:&|and)\s*architecture)?|security(?: review)? findings?)\b/im;
+const CLEAN_VERDICT =
+  /(?:^\s{0,3}(?:[-*+]\s+)?(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:clean|none)\b|\bassessment:\s*(?:\*\*)?\s*clean\b|\bno\s+(?:\*\*)?(?:blocking|security|should[- ]fix|nit)\b[^.\n]{0,80}\b(?:findings|issues|problems)\b|\bno (?:findings|issues|problems)\b|\bnothing (?:to report|found|blocking)\b|\blooks clean\b|\bdiff (?:is|looks) clean\b|\bno concerns\b)/im;
+// A reviewer that emitted a raw tool call instead of a review — observed twice from vibe on real PRs
+// (`read_file{"path": …}`, `write_file…{"file_path": …}`). Its JSON can CONTAIN review-shaped words, so
+// this is checked first and wins.
+export const TOOL_TRANSCRIPT = /^\s*[a-z_]+\S*\s*\{\s*"/i;
+
+/**
+ * THE GUARD. Pure. Returns { ok, reason }.
+ * ok when the reply has a severity heading or an explicit clean verdict; fails on empty, whitespace,
+ * or prose with neither (a CLI banner, an error page, a truncated tool transcript).
+ */
+export function assertReviewOutput(text) {
+  const t = String(text ?? '').trim();
+  if (!t) return { ok: false, reason: 'the reviewer returned no output' };
+  if (TOOL_TRANSCRIPT.test(t))
+    return { ok: false, reason: `the reviewer emitted a raw tool call, not a review ("${t.slice(0, 80)}")` };
+  if (SEVERITY_HEADING.test(t)) return { ok: true, reason: 'severity-structured findings' };
+  if (CLEAN_VERDICT.test(t)) return { ok: true, reason: 'explicit clean verdict' };
+  return {
+    ok: false,
+    reason: `the reviewer's reply has no severity heading and no clean verdict — not a review (first line: "${t.split('\n')[0].slice(0, 120)}")`,
+  };
+}

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

@@ -64,8 +64,10 @@ outcome genuinely changes the next one's scope). Six things make it work, and th
 4. **Merges are pre-authorized on green** in a named run: that removes the round-trip, not the gate or the
    review layers, and never extends to a new category of production mutation (TLS/IAM/secrets, money or
    entitlement writes, a new external dependency) — name those in one focused question.
-5. **Generate the kickoff, don't compose it** — `node skills/groom/emit-epic-kickoff.mjs --epic <slug>`
-   (the `groom` skill) reads the epic README and every sprint file and prints the orchestrator prompt.
+5. **Generate the kickoff, don't compose it** — `/build <slug>` in Claude Code with the plugin's mod; anywhere
+   else, from the project root, `npx -y @golden-frijoles/kit emit-epic-kickoff --epic <slug>` (if the
+   project has its own `scripts/emit-epic-kickoff.mjs`, run that instead). It reads the epic README and every sprint
+   file and prints the orchestrator prompt.
    Hand-composing it is how the architecture lock gets summarised away and the review policy silently
    reverts to whatever the composing agent remembered.
 6. **Derive state, journal intent** — at session start run `node scripts/session-resume.mjs` (it ships in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golden-frijoles/kit",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "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": {