@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/findings.js

@@ -61,6 +61,23 @@ export const LEGAL_TRANSITIONS = Object.freeze({
     expired: [],
     amended: [],
 });
+/**
+ * The `finding_status` values a waiver can actually be granted from — read off
+ * the table above rather than restated beside it. `transition()` enforces
+ * LEGAL_TRANSITIONS, so a hand-kept roster of the same fact can only agree
+ * with it or be wrong about it, and being wrong is silent: a status the roster
+ * has not caught up with is never reconciled to `waived` and never counted as
+ * awaiting the operator.
+ *
+ * It lives here, not in waivers.ts, because this module owns the table — and
+ * because waivers.ts is already in an import cycle with this one, where a
+ * top-level read of `LEGAL_TRANSITIONS` from over there would be a temporal
+ * dead zone away from throwing, depending only on which module node reaches
+ * first.
+ */
+export const WAIVABLE_STATUSES = Object.entries(LEGAL_TRANSITIONS)
+    .filter(([, next]) => next.includes('waived'))
+    .map(([status]) => status);
 /** The status an amendment puts a cited spec finding into; `amended` is what discharges it. */
 export const AMEND_PENDING_STATUS = 'amend-pending';
 /** Terminal: the amendment's task ids landed. Reachable only from AMEND_PENDING_STATUS. */
@@ -74,11 +91,31 @@ export const AMENDED_STATUS = 'amended';
  */
 const AMENDMENT_STATUSES = [AMEND_PENDING_STATUS, AMENDED_STATUS];
 /**
- * A finding still awaiting something. Derived from LEGAL_TRANSITIONS above by
- * reading, not by code: these are exactly the statuses with a non-empty
- * outgoing edge set that are not themselves a decision. `waived` has outgoing
- * edges too (a denial can reopen it) but is closed until one arrives, so it
- * belongs with `refuted`/`expired`/`fix-verified`/`amended` on the other side.
+ * The one status the table gives outgoing edges to that is closed anyway.
+ * D-180 gave `waived` a way back so a revoked grant can reopen it, but it is a
+ * decision until that denial arrives, and until then it belongs with
+ * `refuted`/`expired`/`fix-verified`/`amended` on the closed side.
+ *
+ * Declared rather than read off the table because "this status is a decision"
+ * is a judgement about what the status MEANS. The table knows an edge exists;
+ * it cannot tell a way back from a way onward.
+ */
+const CLOSED_DESPITE_A_WAY_BACK = ['waived'];
+/**
+ * A finding still awaiting something: read off LEGAL_TRANSITIONS rather than
+ * restated beside it, exactly as WAIVABLE_STATUSES above is. A finding is
+ * awaiting something precisely while the table still has somewhere to take it,
+ * so this is the statuses with a non-empty outgoing edge set, less the
+ * decision above.
+ *
+ * It was a hand-written list until a probe showed what that costs. Nothing
+ * held the list to the table, and the drift ran in the dangerous direction: a
+ * status the list had not caught up with was absent from it, and absent reads
+ * as CLOSED, so the epic gate closes over a finding still in flight and nobody
+ * ever sees a blocker for it. That is not hypothetical -- it is D-127, which
+ * happened exactly this way when `amend-pending` reached the table and not the
+ * list. Derived, the default inverts: a status nobody has classified yet is
+ * open, which blocks a close rather than waving one through.
  *
  * `amend-pending` is in it for D-127 Part B: that finding is open the same way
  * `fix-pending` is, carrying an assigned discharge condition (amends_task_ids
@@ -95,13 +132,74 @@ const AMENDMENT_STATUSES = [AMEND_PENDING_STATUS, AMENDED_STATUS];
  * corroborate"). A second copy would drift the moment taxonomy.yml grows a
  * status.
  */
-export const OPEN_FINDING_STATUSES = new Set([
-    'raised',
-    'confirmed',
+export const OPEN_FINDING_STATUSES = new Set(Object.entries(LEGAL_TRANSITIONS)
+    .filter(([status, next]) => next.length > 0 && !CLOSED_DESPITE_A_WAY_BACK.includes(status))
+    .map(([status]) => status));
+/**
+ * Open, but already somebody's assignment: the statuses whose finding is
+ * waiting on work that has a named owner and a named discharge condition.
+ *
+ * Declared rather than read off the table, for the same reason
+ * CLOSED_DESPITE_A_WAY_BACK above is: "somebody already owns this" is a
+ * judgement about what a status MEANS, and the table cannot tell an
+ * assignment from a plain next step.
+ *
+ * Which way the default falls is the whole design. Declared, a status nobody
+ * has classified yet is dispatchable, and the cost of being wrong is a coder
+ * told about work someone else is doing -- which the injected block itself
+ * labels context, never scope, and which a reviewer catches as an unrequested
+ * change. Subtracted from a declared dispatchable side, the cost of being
+ * wrong is a finding open against the files a coder is about to edit that
+ * never reaches them, and no gate, review or transcript says a word about it.
+ */
+export const OPEN_BUT_ALREADY_ASSIGNED = [
     'fix-pending',
     'fix-landed',
     AMEND_PENDING_STATUS,
-]);
+];
+/**
+ * The open statuses a dispatch may hand a coder as context (P9-15): open, and
+ * not already on somebody's plate.
+ *
+ * Derived from OPEN_FINDING_STATUSES rather than typed beside it, for the
+ * reason that constant is derived from the table -- and this one was typed,
+ * in findingContext.ts, as `['raised', 'confirmed']` with nothing anywhere
+ * holding it to anything. A probe that added an eleventh finding status to
+ * taxonomy.yml, architecture §8 and LEGAL_TRANSITIONS drove the findings
+ * suite green while a finding parked at it was invisible to every dispatch.
+ *
+ * Lives here rather than beside its one reader, because it is the same
+ * lifecycle question about the same vocabulary the two constants above ask.
+ */
+export const OPEN_FOR_DISPATCH = [...OPEN_FINDING_STATUSES].filter((status) => !OPEN_BUT_ALREADY_ASSIGNED.includes(status));
+/**
+ * Closed by SHOWING rather than by deciding: the fix was verified, the claim
+ * was refuted, or the window it applied to is gone. Declared rather than read
+ * off the table, for the reason CLOSED_DESPITE_A_WAY_BACK and
+ * OPEN_BUT_ALREADY_ASSIGNED above are: "this closure was earned" is a
+ * judgement about what a status MEANS, and the table only knows an edge is
+ * absent.
+ */
+const EARNED_CLOSED_STATUSES = ['refuted', 'fix-verified', 'expired'];
+/**
+ * Statuses that close a finding by DECIDING rather than by showing a fix
+ * (D-120): closed, and not earned. Disjoint from OPEN_FINDING_STATUSES by
+ * construction — and this file is now what constructs it. epic.ts typed the
+ * pair `{waived, amended}` beside a docblock claiming exactly that, with
+ * nothing anywhere holding it to the table.
+ *
+ * Which way the default falls is the whole design, and here it falls the
+ * visible way. Derived as the remainder, a closed status nobody has
+ * classified yet is discretionary: the judge is told about a closure it may
+ * decide needs no second thought, and the close event records one waiver too
+ * many. Typed instead, the cost of being wrong is a finding closed by a
+ * person's decision that the gate does not block on, the judge is never
+ * shown, and the close event's `discretionary_findings` omits — so "was this
+ * epic closed on decisions?" answers "no", permanently and wrongly. The gate
+ * does not block on these, which is precisely why the judge is told: what
+ * nothing blocks on is what nobody re-reads.
+ */
+export const DISCRETIONARY_FINDING_STATUSES = new Set(Object.keys(LEGAL_TRANSITIONS).filter((status) => !OPEN_FINDING_STATUSES.has(status) && !EARNED_CLOSED_STATUSES.includes(status)));
 /**
  * D-21 Part 4. Appended by `repairObligation` to correct a malformed
  * `amends_task_ids` entry on a finding parked at `amend-pending` — never a
@@ -152,7 +250,9 @@ function escapeRegExp(text) {
  * forms) — never a bare `:digits` anywhere in the text. A blanket
  * `:\d+` strip is wrong: free-text like "debug endpoint exposed on :8080"
  * would collide with an unrelated ":9090" finding (reproduced regression,
- * reviewer finding #3).
+ * reviewer finding #3). The line number may itself be a range
+ * (`Widget.tsx:1549-1576`), which a re-review reports as often as a single
+ * line (issue #178).
  */
 function stripPathLineRef(summary, filePath) {
     const forwardSlashPath = filePath.replace(/\\/g, '/');
@@ -161,16 +261,37 @@ function stripPathLineRef(summary, filePath) {
     for (const candidate of candidates) {
         if (!candidate)
             continue;
-        const pattern = new RegExp(`${escapeRegExp(candidate)}:\\d+(?::\\d+)?`, 'g');
+        const pattern = new RegExp(`${escapeRegExp(candidate)}:\\d+(?:[-–—]\\d+)?(?::\\d+)?`, 'g');
         result = result.replace(pattern, candidate);
     }
     return result;
 }
+/**
+ * A `lines N-M` / `lines N–M` (en dash) / `line N to line M` range — the
+ * shape a judge describing a large component actually writes, and the one
+ * the original single `line N` strip below never covered (issue #178).
+ * Anchored on the word "line"/"lines" immediately before the numbers, so
+ * free-text numerics elsewhere in the sentence are never touched.
+ */
+const LINE_SPAN_RE = /\blines?\s+\d[\d,]*\s*(?:[-–—]|to(?:\s+lines?)?)\s*\d[\d,]*\b/g;
+/**
+ * `~5,050-line` / `6,720-line` — a size given as a hyphenated adjective
+ * before "line"/"component"/"file"/etc, approximate or exact. Only the
+ * `<number>-line` token is removed; the noun it modifies is untouched, and
+ * a hyphenated count before any OTHER noun (`3-day`, `5-retry`) is left
+ * alone — it is not a line reference.
+ */
+const LINE_COUNT_RE = /~?\d[\d,]*-line\b/g;
+/** `L1549-L6600` — a GitHub-style permalink line range, bare or after `#`. */
+const GITHUB_LINE_RANGE_RE = /\bl\d+-l\d+\b/g;
 /** lowercase, whitespace collapsed (spec wording; path-anchored line refs stripped by the caller). */
 function normalizeSummary(summary) {
     return summary
         .toLowerCase()
+        .replace(LINE_SPAN_RE, '')
         .replace(/\bline\s+\d+\b/g, '')
+        .replace(LINE_COUNT_RE, '')
+        .replace(GITHUB_LINE_RANGE_RE, '')
         .replace(/\s+/g, ' ')
         .trim();
 }

package/factory/orchestrator/dist/gh.js

@@ -49,9 +49,12 @@ export function slugFromRemoteUrl(url) {
 }
 /**
  * Which repository the git checkout at `dir` belongs to. Classifies a
- * `GitCommandError` from `readOriginUrl` into `not-a-repo` or `no-origin`
- * before handing a resolved URL to `slugFromRemoteUrl`; any other error is
- * a programming or environment fault and is rethrown, not mis-filed.
+ * `GitCommandError` from `readOriginUrl` by POSITIVE match only:
+ * `not a git repository` is `not-a-repo`; `No such remote` is `no-origin`;
+ * every other git failure -- never spawned, or spawned and failed for a
+ * different reason -- is `git-failed`, with `detail` carrying git's own
+ * words. Any other error is a programming or environment fault and is
+ * rethrown, not mis-filed.
  */
 export function resolveRepoAtDir(dir) {
     let url;
@@ -63,7 +66,10 @@ export function resolveRepoAtDir(dir) {
             if (/not a git repository/i.test(err.stderr)) {
                 return { reason: 'not-a-repo', detail: `${dir} is not a git repository` };
             }
-            return { reason: 'no-origin', detail: `${dir} has no "origin" remote` };
+            if (/No such remote/i.test(err.stderr)) {
+                return { reason: 'no-origin', detail: `${dir} has no "origin" remote` };
+            }
+            return { reason: 'git-failed', detail: err.message };
         }
         throw err;
     }
@@ -135,9 +141,26 @@ function writeBodyFile(body) {
 export function buildCreateIssueArgv(repo, title, body) {
     return ['issue', 'create', '--repo', repo, '--title', title, '--body-file', writeBodyFile(body)];
 }
-/** Pure builder: the argv for `gh issue list` restricted to open issues matching `query`. */
+/**
+ * Pure builder: the argv for `gh issue list` restricted to open issues
+ * matching `query`. Without --json, gh prints a human-readable table that
+ * parseSearchResult can never parse as JSON, folding a real search into a
+ * generic failure indistinguishable from an actual nonzero exit. The fields
+ * requested here are exactly the ones parseSearchResult reads off each item.
+ */
 export function buildSearchIssuesArgv(repo, query) {
-    return ['issue', 'list', '--repo', repo, '--state', 'open', '--search', query];
+    return [
+        'issue',
+        'list',
+        '--repo',
+        repo,
+        '--state',
+        'open',
+        '--json',
+        'number,body,url',
+        '--search',
+        query,
+    ];
 }
 /** Pure builder: the argv for `gh issue comment`. Spawns nothing. */
 export function buildCommentArgv(repo, issueNumber, body) {

package/factory/orchestrator/dist/git.js

@@ -44,7 +44,11 @@ export function redactCredentials(text) {
         return colon === -1 ? `${scheme}***@` : `${scheme}${userinfo.slice(0, colon)}:***@`;
     });
 }
-function exec(cwd, args) {
+/**
+ * `onConflict`, when given, reads what git said from stdout on exit 1 — for
+ * the commands (merge-tree) that report a conflict there, not on stderr.
+ */
+function exec(cwd, args, onConflict) {
     try {
         return execFileSync('git', args, {
             cwd,
@@ -57,7 +61,9 @@ function exec(cwd, args) {
         // A child that never spawned has no exit code; `code` carries the errno
         // string instead, and that is the only thing worth reporting.
         const status = typeof e.status === 'number' ? e.status : null;
-        const said = e.stderr ?? (typeof e.code === 'string' ? `git could not be run (${e.code})` : '');
+        const said = onConflict !== undefined && status === 1
+            ? onConflict(e.stdout ?? '')
+            : (e.stderr ?? (typeof e.code === 'string' ? `git could not be run (${e.code})` : ''));
         throw new GitCommandError(cwd, args, status, redactCredentials(said));
     }
 }
@@ -72,6 +78,18 @@ export function runGit(cwd, args) {
 export function runGitRaw(cwd, args) {
     return exec(cwd, args);
 }
+/**
+ * `git merge-tree --write-tree` of two commits: the merged tree's id, with no
+ * working tree or index touched. A conflict (exit 1) throws GitCommandError
+ * carrying the conflicted paths and git's CONFLICT messages, which merge-tree
+ * prints on stdout rather than stderr.
+ */
+export function writeMergeTree(cwd, base, head) {
+    const args = ['merge-tree', '--write-tree', '--name-only', base, head];
+    // stdout on a conflict is the would-be tree id, then what conflicted.
+    const out = exec(cwd, args, (stdout) => stdout.split('\n').slice(1).join('\n'));
+    return out.split('\n')[0];
+}
 /**
  * The `origin` remote's URL, exactly as git reports it — credentials and
  * all, since redaction happens only on the error path inside `exec`. Throws

package/factory/orchestrator/dist/harness.js

@@ -4,7 +4,7 @@ import { parse as parseYaml } from 'yaml';
 import { loadBudgetPolicy } from './budgets.js';
 import { SmithError } from './errors.js';
 import { AGENTS_DIR, HARNESS_POLICY_PATH, REPO_ROOT } from './paths.js';
-import { loadGuardrailPolicy } from './policy.js';
+import { INSPECTED_FILE_TOOLS, loadGuardrailPolicy } from './policy.js';
 import { loadTaxonomy } from './taxonomy.js';
 /**
  * The worker harness port: *how* a turn runs, named at last.
@@ -81,11 +81,15 @@ import { loadTaxonomy } from './taxonomy.js';
  * weaker promise than the in-process path's sandbox lease — it is a
  * differently-shaped one. An in-process judge runs under guard.sh with a
  * Bash tool in hand, and the lease is what stops it from writing; a cli judge
- * with `judge_args` set never has the ability to write at all, which a lease
- * revocation cannot improve on. Rule 6's fingerprint-before-and-after still
- * runs either way, because a read-only flag is what the harness promises, not
- * what this factory has watched happen. An empty `judge_args` means the
- * harness makes no such promise, and the refusal stands as before.
+ * whose `judge_args` this factory has read as read-only never has the ability
+ * to write at all, which a lease revocation cannot improve on. Rule 6's
+ * fingerprint-before-and-after still runs either way, because a read-only
+ * flag is what the harness promises, not what this factory has watched
+ * happen. `judge_args` that do not read as read-only — absent, or present
+ * and spent on something else — mean the harness makes no such promise, and
+ * the refusal stands as before. Which flags read that way, for which
+ * program, is declared at `judgeReadOnly` below; it is the one thing about
+ * this escape valve that must not be taken on trust.
  *
  * `schema_args` is a smaller instance of the same shape: arguments appended
  * only when the request resolved a schema, so a turn that validates nothing
@@ -365,6 +369,82 @@ function substitute(template, values, harness) {
         return value;
     });
 }
+/** `--flag value` or `--flag=value`. The last occurrence wins, as an argv does. */
+function flagValue(args, names) {
+    let found = null;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        for (const name of names) {
+            if (arg === name) {
+                const next = args[i + 1];
+                if (next !== undefined)
+                    found = next;
+            }
+            else if (arg.startsWith(`${name}=`)) {
+                found = arg.slice(name.length + 1);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * A Map rather than an object literal on purpose: the key is a program name
+ * read off a policy file, and `Object.prototype` answers to several of them.
+ */
+const READ_ONLY_JUDGE_FLAGS = new Map([
+    // codex brings its own sandbox: `read-only` is enforced by the OS, so the
+    // worktree path the process holds is a path it can only read.
+    [
+        'codex',
+        (args) => {
+            const sandbox = flagValue(args, ['-s', '--sandbox']);
+            if (sandbox === 'read-only')
+                return { promised: true, flag: '-s read-only' };
+            return {
+                promised: false,
+                reason: sandbox === null
+                    ? 'its judge_args name no `-s read-only`'
+                    : `its judge_args ask for the \`${sandbox}\` sandbox, which is not read-only`,
+            };
+        },
+    ],
+    // claude has no filesystem sandbox to ask for; it has the tools it is
+    // given. Denying every tool that writes a file is the same promise by a
+    // different mechanism — and which tools those are is policy.ts's roster,
+    // read from there rather than typed again here.
+    [
+        'claude',
+        (args) => {
+            const denied = flagValue(args, ['--disallowedTools']);
+            if (denied === null) {
+                return { promised: false, reason: 'its judge_args name no `--disallowedTools`' };
+            }
+            const names = new Set(denied.split(',').map((name) => name.trim()));
+            const left = INSPECTED_FILE_TOOLS.filter((tool) => !names.has(tool));
+            if (left.length === 0)
+                return { promised: true, flag: `--disallowedTools ${denied}` };
+            return {
+                promised: false,
+                reason: `its judge_args leave ${left.join(', ')} in the judge's hands`,
+            };
+        },
+    ],
+]);
+function judgeReadOnly(harness) {
+    if (harness.judgeArgs.length === 0) {
+        return { promised: false, reason: 'it declares no judge_args at all' };
+    }
+    const program = harness.command === null ? '' : path.basename(harness.command);
+    const recognise = READ_ONLY_JUDGE_FLAGS.get(program);
+    if (recognise === undefined) {
+        const known = [...READ_ONLY_JUDGE_FLAGS.keys()].join(' and ');
+        return {
+            promised: false,
+            reason: `this factory cannot read a read-only flag for \`${program}\` (it reads ${known})`,
+        };
+    }
+    return recognise(harness.judgeArgs);
+}
 /**
  * Describe the process that would run this turn. Start nothing.
  *
@@ -433,12 +513,14 @@ export function planWorkerTurn(request, options = {}) {
             template: templateRelative,
         };
     }
-    if (access === 'judge' && worktree !== null && harness.judgeArgs.length === 0) {
+    const readOnly = access === 'judge' && worktree !== null ? judgeReadOnly(harness) : null;
+    if (readOnly !== null && !readOnly.promised) {
         // §18 rule 5, one step out from providers/types.ts. An external process
         // holding a worktree path holds write access to it; no lease this side of
         // the boundary can take that back — unless the harness's own policy entry
-        // declares judge_args that make the program read-only. See the header.
-        throw new HarnessError('harness.judge-worktree', `Harness "${harness.name}" runs a separate program, and ${role} is a judge role. A judge outside this process gets the prompt and nothing else — a worktree path it holds is write access no sandbox lease can revoke (architecture §18 rule 5). ${harness.name} could still serve ${role} a worktree if its policy entry were to declare judge_args that make the program read-only.`, { harness: harness.name, role });
+        // declares judge_args that are read-only and not merely present. See the
+        // header.
+        throw new HarnessError('harness.judge-worktree', `Harness "${harness.name}" runs a separate program, and ${role} is a judge role. A judge outside this process gets the prompt and nothing else — a worktree path it holds is write access no sandbox lease can revoke (architecture §18 rule 5). ${harness.name} could still serve ${role} a worktree if its policy entry declared judge_args that make the program read-only, but ${readOnly.reason}.`, { harness: harness.name, role, reason: readOnly.reason });
     }
     const tier = request.tier ?? tierFromTemplate(template.file);
     const model = tier !== null ? (harness.models[tier] ?? null) : null;
@@ -503,7 +585,7 @@ export function summarizeHarnesses(options = {}) {
                 if (!templateFor(role, agentsDir).exists)
                     return false;
                 if (roleAccess(role, guardrails) === 'judge') {
-                    return harness.kind === 'in-process' || harness.judgeArgs.length > 0;
+                    return harness.kind === 'in-process' || judgeReadOnly(harness).promised;
                 }
                 return true;
             }),