bareloop 0.25.0 → 0.26.0

package/src/authoring.js

@@ -473,24 +473,42 @@ export function deniedCommandReason(cmd) {
 // ── 2. THE TYPES GENRE ───────────────────────────────────────────────────────
 
 /**
- * THE FROZEN TYPES GENRE TEMPLATE — prereg addendum 3's six policy points,
- * VERBATIM. The suite reads the prereg and compares BYTES, so a paraphrase here
- * fails the build rather than quietly changing what every future close is
- * authored against. It deliberately carries no repo-specific command, path, env
- * value or regex: round 2 measured that stating the LAW still leaves the model
- * to find the VALUE, and that is the axis the build must keep live.
+ * THE TYPES GENRE TEMPLATE — six policy points, VERBATIM against
+ * `docs/product/ITEM33-BUILD.md`'s own frozen block (PRD item 33 M3 piece 4,
+ * D6 = A ruling, 2026-09-14). This SUPERSEDES the original prereg-frozen
+ * version (`docs/logs/2026-08-08-close-authoring-gate2-poc-prereg.md`,
+ * addendum 3, the closed record — never edited): that version stated the
+ * WORK-stage skeleton (typecheck, typecheck-outside, tests-kept,
+ * suite-green) and the checker's STRICT form as UNCONDITIONAL law, which
+ * conflicted with ruling 6's "a genre never adds a check the goal did not
+ * ask for" — run mtv8jihy's unasked `tsc --strict` stage is the case this
+ * cures. Composing those stages/strictness only for a CONFIRMED check
+ * (never a code matcher over prose, same reasoning as the no-shell law) is
+ * enforced here, in the prompt; the GUARDS (changed-from-seed,
+ * no-suppressions) are enforced separately and structurally
+ * (`classGuards` + `validateDeclaration`'s `guards-absent` red), so making
+ * the WORK stages conditional here changes nothing about their own
+ * always-on status. The suite reads the SIGNED block and compares BYTES, so
+ * a paraphrase here fails the build rather than quietly changing what every
+ * future close is authored against. It deliberately carries no
+ * repo-specific command, path, env value or regex: round 2 measured that
+ * stating the LAW still leaves the model to find the VALUE, and that is the
+ * axis the build must keep live.
  */
-export const TYPES_GENRE_TEMPLATE = `1. The graded instrument is the STRICT form of the language's type checker, regardless of what
-   the repo's own scripts run. If the repo's script omits strictness, the close adds it.
+export const TYPES_GENRE_TEMPLATE = `1. The STRICT form of the language's type checker is used only when a confirmed check — or,
+   absent a confirm turn, the goal and interview answers — asks for strict typing; otherwise the
+   checker runs at whatever strictness the repo's own scripts already use.
 2. Tools are invoked so their binaries actually resolve — through the project's own package
    runner or language module runner, never a bare binary name.
-3. The stage skeleton, in first-red-wins order: changed-from-seed (guard) → typecheck (error
-   count IN the target scope, baseline 0, lower-is-better) → typecheck-outside (error count
-   OUTSIDE the target scope, baseline measured at seed, a ceiling — required whenever the job
-   scopes to a subset of the tree; omitted only for whole-tree jobs) → tests-kept (a floor on
-   tests that actually EXECUTED, baseline at seed, higher-is-better; a skipped or deselected
-   test did not run and must not count) → suite-green (the suite exits clean AND reports zero
-   failing tests — two assertions) → no-suppressions (guard).
+3. The WORK stages — typecheck (error count IN the target scope, baseline 0, lower-is-better),
+   typecheck-outside (error count OUTSIDE the target scope, baseline measured at seed, a
+   ceiling — required whenever a typecheck stage is scoped to a subset of the tree), tests-kept
+   (a floor on tests that actually EXECUTED, baseline at seed, higher-is-better; a skipped or
+   deselected test did not run and must not count), and suite-green (the suite exits clean AND
+   reports zero failing tests — two assertions) — are composed ONLY for the checks a confirmed
+   plan asked for (or, absent a confirm turn, the goal and interview answers). The GUARDS —
+   changed-from-seed and no-suppressions — are composed always, first-red-wins:
+   changed-from-seed before every WORK stage, no-suppressions last.
 4. One population per stage — two structurally different counts never share a stage.
 5. The checker must judge the PATIENT's own tree: if imports could resolve to an installed or
    editable copy elsewhere, the environment is set so they resolve inside the patient.

package/src/authorjob.js

@@ -109,7 +109,10 @@ import {
   GENRE_LANGUAGES, LOCKED_KINDS, TYPES_GENRE, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES,
   UNLISTED_CLASSES, MENU_CLASSES,
 } from './authoring.js';
-import { QUESTION_SETS, questionsFor, requiredAnswersFor, authorClose, makeCostBook } from './authorflow.js';
+import {
+  QUESTION_SETS, questionsFor, requiredAnswersFor, authorClose, makeCostBook,
+  runConfirmTurn, WORSE_THAN_BEFORE_FIELD, LANGUAGE_PICK_FIELD,
+} from './authorflow.js';
 import { runAuthorScout, buildSeedListing, SCOUT_ATTEMPTS } from './authorscout.js';
 import {
   DECLARED_GAP_PREFIX, DECLARED_GENRES, guardNames, isDeclaredClose, validateCloseDecl,
@@ -419,16 +422,24 @@ function composerRefusal(reds) {
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
- *   authorFn?: Function, authorOpts?: object,
- *   signerFix?: Function|any, proposeFn?: Function, compileOpts?: object}} o
+ *   authorFn?: Function, authorOpts?: object, writeScope?: string[]|null,
+ *   signerFix?: Function|any, proposeFn?: Function, compileOpts?: object,
+ *   ask?: ((step: {kind: string, [k: string]: any}) => Promise<string|null>)|null,
+ *   confirmGenerate?: Function|null, isRepo?: boolean,
+ *   langResult?: {kind: string, candidates?: string[], [k: string]: any}|null}} o
  * @returns {Promise<{ok: boolean, refusal: Refusal|null, verdictType: string|null,
  *   closeDecl: any, seedRef: string|null, authoring: any, judged: any, reds: Red[],
- *   stop: string|null, cost: any, interview: any}>}
+ *   stop: string|null, cost: any, interview: any, confirmed: any}>}
  */
 export async function authorCloseForJob({
   answers, repoPath = null, lang, verdictType = null, questions = null,
   generate, provider = null, seedRef = null, scout = null, listing = null,
   ceilingUsd = null,
+  // Q2 IS GONE from the numbered interview (PRD item 33 M3 piece 3) — the
+  // fence it used to describe in prose is now Destination's own proven
+  // `writeScope`, and this is what carries it into the composer prompt
+  // (`authorPrompt`'s `writeScopeBlock`) instead of letting it vanish.
+  writeScope = null,
   // THE JUDGE IDENTITY (PRD item 32.1), required only on the path that actually
   // composes a judged stage — the stored calibration set carries the judge that
   // certified it, and there is no library pin to fall back to. Absent on a purely
@@ -448,11 +459,30 @@ export async function authorCloseForJob({
   // signed as proposed, and `signJudgedArtifacts` records which of the two
   // happened rather than leaving a reader to guess.
   signerFix = null, proposeFn = proposeJudgedArtifacts, compileOpts = {},
+  // PRD item 33 M3 piece 4 — the confirm turn. ALL FOUR default to nothing so
+  // every existing caller runs byte-identical: `ask` absent means no confirm
+  // turn runs at all, exactly as before this piece existed.
+  //   ask            the ONE interactive seam (see `runConfirmTurn`'s own doc)
+  //                  — its ABSENCE is the switch that turns the whole confirm
+  //                  turn off, never a boolean flag next to it.
+  //   confirmGenerate a SEPARATE model boundary from `generate`: the authoring
+  //                  call is bound to AUTHOR_SYSTEM and the confirm call is
+  //                  bound to CONFIRM_SYSTEM — reusing `generate` would run the
+  //                  wrong system prompt silently.
+  //   isRepo         whether Source resolved to a repo (`looksLikeRepoSource`)
+  //                  — gates the repo-only "worse than before" $0 question and
+  //                  whether a confirm turn runs at all (M3 ruling 7: a
+  //                  plain-folder job's confirm turn is a LATER piece).
+  //   langResult     `src/detectlang.js`'s own result — only its `ambiguous`
+  //                  shape matters here (a $0 language pick before the scout,
+  //                  D7); every other kind leaves `lang` exactly as given.
+  ask = null, confirmGenerate = null, isRepo = false, langResult = null,
 }) {
   /** @type {any} */
   const base = {
     ok: false, refusal: null, verdictType: null, closeDecl: null, seedRef: null,
     authoring: null, judged: null, reds: [], stop: null, cost: null, interview: null,
+    confirmed: null,
   };
 
   const interview = runInterview({ answers, verdictType, repoPath, questions });
@@ -463,6 +493,27 @@ export async function authorCloseForJob({
   const workdir = /** @type {string} */ (interview.repoPath);
   const picked = /** @type {string} */ (interview.verdictType);
 
+  // ── THE CONFIRM TURN'S $0 HALF (PRD item 33 M3 piece 4, D7) ────────────────
+  // Entirely BEFORE the scout: a missing person here stops at $0, never after a
+  // paid survey. `ask` ABSENT is the whole confirm turn's off switch — every
+  // caller that predates this piece (or a caller that never wires an
+  // interactive seam) reaches the genre check below exactly as it always did.
+  let worseThanBefore = '';
+  if (ask) {
+    if (isRepo) {
+      onPhase('confirm-worse-than-before', {});
+      const wtb = await ask({ kind: 'worseThanBefore', field: WORSE_THAN_BEFORE_FIELD });
+      if (wtb === null) return { ...base, interview, reds: [], stop: 'confirm-abandoned' };
+      worseThanBefore = redactSecrets(String(wtb).trim());
+    }
+    if (langResult?.kind === 'ambiguous') {
+      onPhase('confirm-language-pick', { candidates: langResult.candidates });
+      const pick = await ask({ kind: 'language', field: LANGUAGE_PICK_FIELD, candidates: langResult.candidates });
+      if (pick === null) return { ...base, interview, reds: [], stop: 'confirm-abandoned' };
+      lang = String(pick);
+    }
+  }
+
   if (!GENRE_LANGUAGES.includes(lang)) {
     // THE GENRE REFUSAL, at the composer. This used to be a plain wiring red;
     // under v1.57 §2 the interview no longer asks the user to confirm a genre, so
@@ -537,6 +588,72 @@ export async function authorCloseForJob({
     // back with anything to author from.
     onPhase('scout-done', { state: survey?.state ?? null, facts: Object.keys(survey?.facts ?? {}).length });
   }
+
+  // ── THE CONFIRM TURN'S PAID HALF (PRD item 33 M3 piece 4) ──────────────────
+  // Slotted between the scout and the listing: it reuses the scout's own
+  // survey (ruling 4 — never a second read of the source) and needs nothing
+  // the listing would add. Runs ONLY when `ask` is wired AND this is a repo
+  // job AND the survey actually came back PRESENT — an ABSENT survey means
+  // `authorFn` below refuses at its own $0 preflight (`scout-absent` or its
+  // budget-stop variants) exactly as it always has; drafting a plan from
+  // facts that never arrived would be worse than that honest refusal, so the
+  // confirm turn is skipped rather than run against nothing. A plain-folder
+  // job's confirm turn (no survey at all, D5) is a LATER piece.
+  /** @type {any} */
+  let confirmed = null;
+  /** @type {any[]} */
+  let confirmPriorCalls = [];
+  /** @type {any[]} */
+  let confirmPriorRaws = [];
+  if (ask && isRepo && survey?.state === 'PRESENT') {
+    if (typeof confirmGenerate !== 'function') {
+      throw new Error('[authorjob] authorCloseForJob was given `ask` for a repo job but no `confirmGenerate` — the '
+        + 'confirm turn needs its OWN model boundary (bound to CONFIRM_SYSTEM), never the authoring `generate` '
+        + '(bound to AUTHOR_SYSTEM)');
+    }
+    const confirmBook = makeCostBook({ ceilingUsd, onCall });
+    // THE CEILING FOLDS IN PRIOR SPEND (the standing hard line's money form,
+    // F1). The scout is the FIRST paid stage — its calls are absorbed here,
+    // BEFORE `runConfirmTurn` ever asks `book.capStop()`, so a scout that
+    // already spent most (or all) of the ceiling is visible to the confirm
+    // turn's own pre-call check, and a scout call that came back unpriced
+    // (`costUsd: null`) taints `spendComplete` here too — "unpriced is never
+    // free" applies to the confirm turn's OWN calls exactly as it already
+    // does to the author call's. `absorb` never fires `onCall` (see
+    // `makeCostBook`'s own doc): these calls were already reported once, when
+    // the scout made them.
+    const scoutCallCount = (survey?.calls ?? []).length;
+    const scoutRawCount = (survey?.raws ?? []).length;
+    confirmBook.absorb(survey?.calls ?? [], survey?.raws ?? []);
+    onPhase('confirm', {});
+    const confirm = await runConfirmTurn({
+      verdictType: picked, answers: interview.answers, questions: questions ?? questionsFor(picked),
+      facts: survey.facts, listing: null, writeScope, isRepo, lang, worseThanBefore,
+      generate: confirmGenerate, book: confirmBook, ask, onPhase,
+    });
+    // DISTINCT from `runConfirmTurn`'s own per-round 'confirm-done' (fired once
+    // per round when a plan arrives) — this is the WRAPPER's own line, once,
+    // saying how the whole turn ended.
+    onPhase('confirm-turn-done', { ok: confirm.ok, stop: confirm.stop, rounds: confirm.rounds });
+    if (!confirm.ok) {
+      return {
+        ...base, interview, verdictType: picked, seedRef: seed,
+        reds: confirm.reds, stop: confirm.stop, cost: confirm.cost,
+      };
+    }
+    confirmed = confirm.accepted;
+    lang = confirmed.lang;
+    // ONLY the confirm turn's OWN new calls travel onward as `priorCalls` —
+    // never the scout entries this same book absorbed two lines above.
+    // `authorClose` (below, via `authorFn`) absorbs `scout.calls`/`scout.raws`
+    // itself; handing it the scout's calls a SECOND time (folded inside
+    // `confirmBook`'s own report) would double-count the scout's spend in the
+    // author call's own ceiling check — the exact bug this fix must not
+    // reintroduce while fixing the other one.
+    confirmPriorCalls = confirmBook.report().calls.slice(scoutCallCount);
+    confirmPriorRaws = confirmBook.raws().slice(scoutRawCount);
+  }
+
   /** @type {any} */
   let seeds = listing;
   if (seeds == null) {
@@ -558,7 +675,9 @@ export async function authorCloseForJob({
   const authored = await authorFn({
     workdir, seedRef: seed, lang, verdictType: picked,
     answers: interview.answers, questions: questions ?? questionsFor(picked),
-    scout: survey, listing: seeds, generate, ceilingUsd, onPhase, onCall, ...authorOpts,
+    scout: survey, listing: seeds, generate, ceilingUsd, onPhase, onCall, writeScope,
+    priorCalls: confirmPriorCalls, priorRaws: confirmPriorRaws, confirmed,
+    ...authorOpts,
   });
 
   if (!authored.ok) {
@@ -690,6 +809,7 @@ export async function authorCloseForJob({
       stop: authored.stop,
       cost: book.report(),
       interview,
+      confirmed,
     };
   }
 
@@ -705,6 +825,7 @@ export async function authorCloseForJob({
     stop: authored.stop,
     cost: authored.cost,
     interview,
+    confirmed,
   };
 }
 
@@ -727,6 +848,38 @@ export async function authorCloseForJob({
 // the same way one carrying a raw `close` array is.
 export const AUTHORED_SPEC_FIELDS = Object.freeze(['close', 'closeDecl', 'verdictType', 'sha256', 'closeTimeoutMs']);
 
+// `goal` IS DIFFERENT from the fields above, and deliberately kept in its own
+// list (PRD item 33 M3, ruling 5's 2026-09-13 addendum, D2 = option B). It is
+// NOT authored by anything in this file — `assembleSpec` above passes it
+// through from the draft untouched, exactly as it always has — so it is not
+// one of `AUTHORED_SPEC_FIELDS` and `assembleSpec` does not refuse a draft
+// that carries it. What changed is WHO writes it: `scripts/run-interview.mjs`
+// no longer asks a separate goal question (that question is GONE, step S5),
+// and `scripts/run-author.mjs` instead sets `draft.goal` from the confirm
+// turn's own accepted plan (`authored.confirmed.goal`, step S4) before
+// calling `assembleSpec`. A draft written by `run-interview.mjs` therefore
+// has NO `goal` field at all, and `validateJob`'s $0 pass over that draft
+// (the same pass that already filters `AUTHORED_SPEC_FIELDS`'s reds, since
+// that half does not exist yet either) would otherwise red `missing-required`
+// at `goal` for a field the interview never had a chance to fill. This is
+// the ONE library constant that filter reads for that field, so no caller
+// hand-types the field name `'goal'` a second time.
+export const CONFIRM_AUTHORED_FIELDS = Object.freeze(['goal']);
+
+// PRD item 33 M3 piece 4, step S6 (D5 = A: a plain-folder source runs no
+// scout, and its confirm turn ends in the honest "no checks yet" stop, M4).
+// `writeScope` is the signed fence for a REPO job (Destination's own proven
+// answer IS it); for a plain folder, Destination is an OUTPUT directory, not
+// a fence, and this build authors no close for that kind of job at all — so
+// `scripts/run-interview.mjs` writes no `writeScope` field for one. Named
+// here, separately from `CONFIRM_AUTHORED_FIELDS`, because nothing in THIS
+// build ever fills it in for a plain-folder draft (goal, above, IS always
+// filled in later, by the confirm turn) — it stays absent until M4 gives a
+// plain-folder job a fence of its own kind. Filtering it unconditionally in
+// the $0 validator pass is harmless for a repo draft, which always carries
+// one: there is never a `writeScope` red left to filter there.
+export const PLAIN_FOLDER_DEFERRED_FIELDS = Object.freeze(['writeScope']);
+
 /**
  * Fold an authored close into the OPERATOR's own half of the spec.
  *

package/src/cardauthor.js

@@ -3,13 +3,22 @@
 // plus the 2026-08-18 threshold addendum).
 //
 // Module 1 built the judged floor's core, module 2 wired the stage into a close,
-// module 3 opened the class and asked the two extra questions. Nothing compiled
-// their answers. This module does exactly that and nothing more:
+// module 3 opened the class and asked the extra question. Nothing compiled its
+// answer. This module does exactly that and nothing more:
 //
-//   Q6  → THE RUBRIC CARD      (§4.3) — the person's own pass/fail lines, as
-//                                ENUMERATED items over the arbiter's own rulebook.
-//   Q7  → THE CALIBRATION SET  (§4.4) — TEN cases, frozen, that the whole pipe
-//                                must grade before the close is signable.
+//   Judge Examples  → THE RUBRIC CARD      (§4.3) — the person's own pass/fail
+//                       lines, as ENUMERATED items over the arbiter's own
+//                       rulebook, compiled from the "why" half of their answer.
+//                   → THE CALIBRATION SET  (§4.4) — TEN cases, frozen, that the
+//                       whole pipe must grade before the close is signable.
+//
+// PRD item 33 M3 piece 3 (2026-09-13): the old Q6 ("what separates a pass from
+// a fail?") and Q7 ("give one you'd pass and one you'd fail, and say why")
+// merged into ONE form field, Judge Examples — Q7's wording, verbatim
+// (`SOFTGREEN_JUDGE_EXAMPLES_KEY`/`JUDGE_EXAMPLES_QUESTION`, `authorflow.js`).
+// Q6 is not lost: the "why" lines of a real pass/fail pair are what this
+// module already compiled a card FROM, and asking the differentiator twice —
+// once in the abstract, once against a real example — was the double-ask.
 //
 // ── THE D5 PATH, AND WHY IT IS THIS ONE ─────────────────────────────────────
 //
@@ -62,7 +71,7 @@
 import {
   JUDGE_RULE_IDS, JUDGE_RULES, CALIBRATION_SIZE, CASE_VERDICTS, validateJudgedArtifacts,
 } from './judged.js';
-import { askStructured, makeCostBook } from './authorflow.js';
+import { askStructured, makeCostBook, SOFTGREEN_JUDGE_EXAMPLES_KEY, JUDGE_EXAMPLES_QUESTION } from './authorflow.js';
 import { judgedStages } from './kinds.js';
 import { isObj, redactSecrets } from './validate.js';
 
@@ -204,8 +213,12 @@ export const COMPILE_SYSTEM = 'You compile a person\'s own words into a rubric a
   + 'is fixed and you select from it.';
 
 /**
- * The compile prompt. Q6's and Q7's answers travel VERBATIM — they are the whole
- * input, and paraphrasing a lay answer is how a rubric stops being the person's.
+ * The compile prompt. The Judge Examples answer travels VERBATIM — it is the
+ * whole input, and paraphrasing a lay answer is how a rubric stops being the
+ * person's. PRD item 33 M3 piece 3: this used to be two answers (Q6+Q7);
+ * `SOFTGREEN_JUDGE_EXAMPLES_KEY` is the ONE key both the interview and this
+ * compile now read, so a future renumbering of the form moves both readers
+ * together rather than drifting.
  *
  * The rulebook is rendered from `JUDGE_RULES` itself rather than restated, for
  * the reason the catalogue block is rendered from the catalogue: the prompt and
@@ -213,8 +226,8 @@ export const COMPILE_SYSTEM = 'You compile a person\'s own words into a rubric a
  * @param {{answers: Record<string|number, any>, questions?: Record<string|number, string>}} o
  */
 export function cardCasesPrompt({ answers, questions = {} }) {
-  const q6 = questions[6] ?? 'When you judge the result yourself, what separates a pass from a fail?';
-  const q7 = questions[7] ?? 'Give one example you\'d pass and one you\'d fail, and say why.';
+  const qKey = SOFTGREEN_JUDGE_EXAMPLES_KEY;
+  const q = questions[qKey] ?? JUDGE_EXAMPLES_QUESTION;
   const rules = JUDGE_RULE_IDS.map((id) => `- ${id}\n    the facts it reads: ${JUDGE_RULES[id].ask.trim().split('\n')[0].trim()}`);
 
   return `You are compiling ONE person's answers into the two artifacts a judged close is signed with.
@@ -222,13 +235,10 @@ export function cardCasesPrompt({ answers, questions = {} }) {
 They are not a software engineer. They described what they look for in their own words, and your whole job is to
 express that over the rulebook below — never to add a standard they did not state, and never to drop one they did.
 
-THEIR ANSWERS — verbatim, and the only input you have
-
-Q6. ${q6}
-A6. ${answers?.[6] ?? '(no answer given)'}
+THEIR ANSWER — verbatim, and the only input you have
 
-Q7. ${q7}
-A7. ${answers?.[7] ?? '(no answer given)'}
+Q${qKey}. ${q}
+A${qKey}. ${answers?.[qKey] ?? '(no answer given)'}
 
 ---
 
@@ -407,7 +417,7 @@ export function foldJudgedArtifacts(closeDecl, { card, cases, judgeModel }) {
 // ── 6. THE PAID SEAM ────────────────────────────────────────────────────────
 
 /**
- * ONE compile call: the person's Q6 and Q7 in, a proposal out.
+ * ONE compile call: the person's Judge Examples answer in, a proposal out.
  *
  * It buys ONE artifact through ONE channel, and the malformed-emission ladder is
  * the SHARED one (`askStructured`) rather than a second copy — a second ladder is

package/src/detectlang.js

@@ -0,0 +1,200 @@
+// LANGUAGE DETECTION (PRD item 33/M3, ruling 3 — `docs/product/ITEM33-BUILD.md`,
+// "Five detection points"): a code job's checks always run the repo's OWN
+// tools in the repo's own language, so language is a FACT of the repository,
+// never a question asked of the person. This module is that fact-finder —
+// $0, no provider, no model — and it replaces the `--lang` flag (default
+// `js`) `scripts/run-interview.mjs` and `scripts/run-author.mjs` used to
+// carry.
+//
+// ONE DATA TABLE (`MANIFEST_RULES`), not a code path per language: M3b's job
+// is to flip a language from "known but no genre data" to "known and
+// supported" by adding it to `GENRE_LANGUAGES` (`src/authoring.js`) — this
+// module never hardcodes the supported set a second time, it reads
+// `GENRE_LANGUAGES` live, so a language landing in M3b needs no edit here.
+//
+// FOUR OUTCOMES, discriminated by `kind`, never a throw for the ones a caller
+// must act on in the ordinary course of a run:
+//   - `resolved`             — a known, SUPPORTED manifest: 'js' or 'python'.
+//   - `language-unsupported` — a known manifest this catalogue has no genre
+//                               data for yet (go, rust, java, csharp, php...).
+//                               Never a silent fallback to js. Carries a
+//                               `refusal` shaped exactly like the `Refusal`
+//                               `src/authorjob.js` already returns for its own
+//                               language refusal (same `REFUSAL_LIB`,
+//                               `REFUSAL_CATEGORY`, `request-red` shape) —
+//                               reusing that pattern rather than inventing a
+//                               second one, so a caller with a spine can emit
+//                               it through the same `refusalEvents()` either
+//                               already imports.
+//   - `no-code-job`           — no manifest anywhere in the walk. NOT an
+//                               error: PRD item 33 M3 ruling 7 says a
+//                               plain-folder job gets the form and an honest
+//                               "no checks yet" stop later (M4), so this is a
+//                               normal reading, not a refusal.
+//   - `ambiguous`             — two DIFFERENT supported languages' manifests
+//                               at the same (nearest) directory level. The
+//                               confirm-turn UI that would ask a person to
+//                               pick is a later M3 piece; for now this is
+//                               reported so a caller can stop rather than
+//                               guess.
+
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { GENRE_LANGUAGES } from './authoring.js';
+import { GENRE, REFUSAL_CATEGORY, REFUSAL_LIB } from './authorjob.js';
+import { nearestGitAncestor } from './source.js';
+
+/** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
+/** @typedef {{kind: 'request-red', verb: string|null, path: string, detail: string,
+ *   options: string[], red: Red}} LangRefusal */
+
+/**
+ * THE MANIFEST TABLE, as data — the whole language vocabulary this module
+ * knows, one entry per manifest shape. `supported` is DERIVED from
+ * `GENRE_LANGUAGES` at lookup time (never stored), so a language M3b adds
+ * there flips from "unsupported stop" to "resolved" by that one edit, never
+ * by adding a new branch here.
+ * @type {ReadonlyArray<{kind: 'exact'|'ext', name?: string, ext?: string, language: string}>}
+ */
+const MANIFEST_RULES = Object.freeze([
+  Object.freeze({ kind: 'exact', name: 'package.json', language: 'js' }),
+  Object.freeze({ kind: 'exact', name: 'pyproject.toml', language: 'python' }),
+  Object.freeze({ kind: 'exact', name: 'setup.py', language: 'python' }),
+  Object.freeze({ kind: 'exact', name: 'go.mod', language: 'go' }),
+  Object.freeze({ kind: 'exact', name: 'Cargo.toml', language: 'rust' }),
+  Object.freeze({ kind: 'exact', name: 'pom.xml', language: 'java' }),
+  Object.freeze({ kind: 'exact', name: 'build.gradle', language: 'java' }),
+  Object.freeze({ kind: 'exact', name: 'build.gradle.kts', language: 'java' }),
+  Object.freeze({ kind: 'exact', name: 'composer.json', language: 'php' }),
+  Object.freeze({ kind: 'ext', ext: '.csproj', language: 'csharp' }),
+  Object.freeze({ kind: 'ext', ext: '.sln', language: 'csharp' }),
+]);
+
+/**
+ * A human label for a matched rule, for messages — `package.json` for an
+ * exact match, `*.csproj` for an extension match.
+ * @param {{kind: 'exact'|'ext', name?: string, ext?: string}} rule
+ * @returns {string}
+ */
+function ruleLabel(rule) {
+  return rule.kind === 'exact' ? /** @type {string} */ (rule.name) : `*${rule.ext}`;
+}
+
+/**
+ * The directory chain to walk, NEAREST first, stopping at the repo root (the
+ * nearest ancestor carrying a `.git` entry, directory OR file — a submodule's
+ * `.git` is a file). When no `.git` exists anywhere above `start`, the walk
+ * is exactly `[start]` — this module never reads above the folder it was
+ * asked about when there is no repo boundary to stop it honestly.
+ *
+ * The boundary itself is `nearestGitAncestor` (`src/source.js`) — the ONE
+ * walk-up-for-`.git` rule, shared with `looksLikeRepoSource`/`prepareSource`'s
+ * own repo-root routing (PRD item 33 M3 ruling 2 addendum) — this function
+ * only turns that single boundary into the full chain of directories a
+ * manifest search walks.
+ * @param {string} start
+ * @returns {string[]}
+ */
+function walkChain(start) {
+  /** @type {string[]} */
+  const chain = [];
+  let d = resolve(start);
+  for (;;) {
+    chain.push(d);
+    const parent = dirname(d);
+    if (parent === d) break; // filesystem root
+    d = parent;
+  }
+  const boundary = nearestGitAncestor(chain[0]);
+  const repoRootIdx = boundary === null ? -1 : chain.indexOf(boundary.dir);
+  return repoRootIdx === -1 ? [chain[0]] : chain.slice(0, repoRootIdx + 1);
+}
+
+/**
+ * Every manifest rule matched inside `dir`, reading its entries once.
+ * @param {string} dir
+ * @returns {{kind: 'exact'|'ext', name?: string, ext?: string, language: string}[]}
+ */
+function matchesIn(dir) {
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return []; // an unreadable directory has no manifest, not an error this module raises
+  }
+  return MANIFEST_RULES.filter((r) => (
+    r.kind === 'exact' ? entries.includes(/** @type {string} */ (r.name)) : entries.some((e) => e.endsWith(/** @type {string} */ (r.ext)))
+  ));
+}
+
+/**
+ * The `language-unsupported` refusal, shaped exactly like `src/authorjob.js`'s
+ * own `Refusal` — same `REFUSAL_LIB`, same `request-red` code, so a caller
+ * holding a spine can hand it straight to `refusalEvents()` without this
+ * module inventing a second recording shape.
+ * @param {string} language @param {string} manifest
+ * @returns {LangRefusal}
+ */
+function unsupportedRefusal(language, manifest) {
+  const detail = `We can't run this kind of job yet: the nearest manifest is ${manifest}, which names "${language}" `
+    + `as this repository's language. The catalogue only has ${GENRE} genre data for ${GENRE_LANGUAGES.join(' and ')} `
+    + `today — a language it has no data for must refuse rather than author a close without the guards it cannot `
+    + 'supply.';
+  return {
+    kind: 'request-red',
+    verb: 'language-unsupported',
+    path: 'lang',
+    detail,
+    options: [
+      `wait for a later build to add ${language} (PRD item 33 M3b)`,
+      `restate the job for ${GENRE_LANGUAGES.join(' or ')}, the languages this catalogue currently measures`,
+    ],
+    red: {
+      code: 'request-red', path: 'lang', detail, verb: 'language-unsupported', lib: REFUSAL_LIB, category: REFUSAL_CATEGORY,
+    },
+  };
+}
+
+/**
+ * Detect a code job's language from its repository, $0, no provider.
+ *
+ * @param {string} sourcePath the Source path (a folder, or a file inside one)
+ * @returns {{kind: 'resolved', lang: string, dir: string, manifest: string} | {kind: 'language-unsupported', language: string, dir: string, manifest: string, refusal: LangRefusal} | {kind: 'no-code-job'} | {kind: 'ambiguous', candidates: string[], dir: string}}
+ */
+export function detectLanguage(sourcePath) {
+  const st = statSync(sourcePath);
+  const start = st.isDirectory() ? sourcePath : dirname(sourcePath);
+  const chain = walkChain(start);
+
+  for (const dir of chain) {
+    const matched = matchesIn(dir);
+    if (!matched.length) continue;
+
+    const languages = [...new Set(matched.map((m) => m.language))];
+    if (languages.length > 1) {
+      // Ruling 3, point (3): two manifests at the same level. Named literally
+      // rather than the spec's minimal "two supported languages" example —
+      // ANY two different languages at the nearest level is an unresolved
+      // pick, listed rather than silently narrowed to the supported ones.
+      return { kind: 'ambiguous', candidates: languages.sort(), dir };
+    }
+
+    const language = languages[0];
+    const matchedRule = matched.find((m) => m.language === language);
+    // `matched` was just built from `languages`, so this find always succeeds —
+    // narrowed with a real runtime check rather than an `any`/`!` cast, so a
+    // future refactor that breaks the invariant reds loudly instead of typing
+    // past it.
+    if (!matchedRule) throw new Error(`unreachable: "${language}" matched from its own manifest list`);
+    const manifest = ruleLabel(matchedRule);
+    if (GENRE_LANGUAGES.includes(language)) {
+      return { kind: 'resolved', lang: language, dir, manifest };
+    }
+    return {
+      kind: 'language-unsupported', language, dir, manifest, refusal: unsupportedRefusal(language, manifest),
+    };
+  }
+
+  return { kind: 'no-code-job' };
+}