@mrciphersmith/keryx 0.2.106 → 0.2.107

package/README.md

@@ -325,7 +325,12 @@ Grouped by what you are trying to do, not by internal module layout.
   trends.
 - **review** — managed review packages, standalone under `.metaproject/reviews/`
   or inside the flow package when attached to a flow, so review findings become
-  durable project artifacts.
+  durable project artifacts. A finding points at the code it **quotes**: the
+  line is derived by locating that quote at the commit the round records, not
+  taken on the reviewer's word, and a quote that cannot be found is marked
+  unlocatable rather than carrying a number nobody checked. Each round also
+  states its price — estimated before dispatch, recorded after, and divided by
+  the findings that survived it.
 
 **Operate agents**
 

package/dist/cli.js

@@ -48579,7 +48579,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.106",
+  version: "0.2.107",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -62741,7 +62741,7 @@ ${learningSourceLessons(selection).map((lesson) => `- ${lesson}
 
 // src/review/managed.ts
 init_validator();
-import { mkdir as mkdir53, readFile as readFile86, readdir as readdir28, rm as rm11 } from "fs/promises";
+import { mkdir as mkdir53, readFile as readFile86, readdir as readdir28, realpath as realpath8, rm as rm11, stat as stat16 } from "fs/promises";
 import path153 from "path";
 init_fs();
 init_store2();
@@ -64692,6 +64692,163 @@ function renderFilterStatsLine(stats) {
   return `filter_stats: total=${show(stats.total)} prefilter=${show(stats.dropped_prefilter)} low_confidence=${show(stats.dropped_low_confidence)} refuted=${show(stats.dropped_refuted)} scope_b=${show(stats.dropped_scope_b)} findings_cap=${show(stats.dropped_findings_cap)} dismissed_by_round=${show(stats.dismissed_by_round)} retained=${show(stats.retained)}`;
 }
 
+// src/review/locate.ts
+var MAX_QUOTE_LINES = 200;
+var MAX_LOCATE_FILE_LINES = 50000;
+var MAX_LOCATE_FILE_BYTES = 4000000;
+function quoteLines(quote) {
+  const lines = quote.replace(/\r\n/g, `
+`).split(`
+`);
+  while (lines.length > 0 && lines[0].trim() === "") {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") {
+    lines.pop();
+  }
+  if (lines.length === 0) {
+    return [];
+  }
+  const indents = lines.filter((line) => line.trim() !== "").map((line) => (line.match(/^[ \t]*/)?.[0] ?? "").length);
+  const common = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(common));
+}
+function normalise(line) {
+  return line.trim().replace(/\s+/g, " ");
+}
+function deindent(lines) {
+  const indents = lines.filter((line) => line.trim() !== "").map((line) => (line.match(/^[ \t]*/)?.[0] ?? "").length);
+  const common = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(common));
+}
+var MAX_HITS = 2;
+function findRuns(haystack, needle, shape) {
+  const hits = [];
+  if (needle.length === 0 || needle.length > haystack.length) {
+    return hits;
+  }
+  for (let start = 0;start + needle.length <= haystack.length; start += 1) {
+    const window = shape(haystack.slice(start, start + needle.length));
+    if (window.every((line, offset) => line === needle[offset])) {
+      hits.push(start + 1);
+      if (hits.length >= MAX_HITS) {
+        return hits;
+      }
+    }
+  }
+  return hits;
+}
+function ambiguity(hits, pass) {
+  return {
+    state: "unlocatable",
+    reason: `the quote matches at least ${hits.length} places${pass}(lines ${hits.join(", ")}, and the scan stopped there); an anchor chosen among them would be a guess`
+  };
+}
+function locateQuote(fileText, quote) {
+  const needle = quoteLines(quote);
+  if (needle.length === 0) {
+    return { state: "unlocatable", reason: "the quote is empty" };
+  }
+  if (needle.length > MAX_QUOTE_LINES) {
+    return {
+      state: "unlocatable",
+      reason: `the quote is ${needle.length} lines, past the ${MAX_QUOTE_LINES}-line bound; quote the few lines the finding is about`
+    };
+  }
+  const haystack = fileText.replace(/\r\n/g, `
+`).split(`
+`);
+  if (haystack.length > MAX_LOCATE_FILE_LINES) {
+    return {
+      state: "unlocatable",
+      reason: `the file is ${haystack.length} lines, past the ${MAX_LOCATE_FILE_LINES}-line bound for locating`
+    };
+  }
+  const exact = findRuns(haystack, deindent(needle).map((line) => line.trimEnd()), (window) => deindent(window).map((line) => line.trimEnd()));
+  if (exact.length === 1) {
+    return { state: "derived", method: "exact", line: exact[0] };
+  }
+  if (exact.length > 1) {
+    return ambiguity(exact, " in the file ");
+  }
+  const loose = findRuns(haystack, needle.map(normalise), (window) => window.map(normalise));
+  if (loose.length === 1) {
+    return { state: "derived", method: "whitespace-normalised", line: loose[0] };
+  }
+  if (loose.length > 1) {
+    return ambiguity(loose, " once whitespace is normalised ");
+  }
+  return { state: "unlocatable", reason: "the quote does not appear in the file" };
+}
+async function locateFinding(finding, readFile) {
+  const quote = typeof finding.quote === "string" ? finding.quote : "";
+  if (quote.trim() === "") {
+    return;
+  }
+  const reported = typeof finding.line === "number" ? finding.line : null;
+  const file = typeof finding.file === "string" ? finding.file : "";
+  if (file === "") {
+    return { state: "unlocatable", reason: "the finding quotes code but names no file", reported_line: reported };
+  }
+  const text = await readFile(file);
+  if (text === null) {
+    return { state: "unlocatable", reason: `no such file at this round's head: ${file}`, reported_line: reported };
+  }
+  const outcome = locateQuote(text, quote);
+  return outcome.state === "derived" ? { state: "derived", method: outcome.method, line: outcome.line, reported_line: reported } : { state: "unlocatable", reason: outcome.reason, reported_line: reported };
+}
+
+// src/review/repair.ts
+var REPAIRABLE = new Set(["id", "problem"]);
+function isBlank(value) {
+  return typeof value !== "string" || value.trim() === "";
+}
+function mintId(index, taken) {
+  let n = index + 1;
+  let candidate = `F-${String(n).padStart(3, "0")}`;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `F-${String(n).padStart(3, "0")}`;
+  }
+  return candidate;
+}
+function acceptRepair(before, after) {
+  if (before.length !== after.length) {
+    throw new Error(`Refusing a repair that changed the number of findings: ${before.length} in, ${after.length} out. A repair may fill fields in; it may never add or drop a finding.`);
+  }
+  for (const [index, finding] of after.entries()) {
+    const had = before[index];
+    const keys = new Set(Object.keys(finding));
+    const illegal = [...keys].filter((key) => !had.has(key) && !REPAIRABLE.has(key));
+    if (illegal.length > 0) {
+      throw new Error(`Refusing a repair that wrote ${illegal.join(", ")} onto finding ${index + 1}: only ${[...REPAIRABLE].join(" and ")} may be filled in. Everything else is a claim the reviewer has to make.`);
+    }
+    const removed = [...had].filter((key) => !keys.has(key));
+    if (removed.length > 0) {
+      throw new Error(`Refusing a repair that removed ${removed.join(", ")} from finding ${index + 1}: a repair may fill a field in; it may never clear one.`);
+    }
+  }
+}
+function repairMechanicalOmissions(findings) {
+  const before = findings.map((finding) => new Set(Object.keys(finding)));
+  const taken = new Set(findings.map((finding) => finding.id).filter((id) => !isBlank(id)));
+  const repairs = [];
+  for (const [index, finding] of findings.entries()) {
+    if (isBlank(finding.id)) {
+      const minted = mintId(index, taken);
+      taken.add(minted);
+      finding.id = minted;
+      repairs.push({ finding: minted, field: "id", source: `position ${index + 1} in the report` });
+    }
+    if (isBlank(finding.problem) && !isBlank(finding["title"])) {
+      finding.problem = String(finding["title"]).trim();
+      repairs.push({ finding: finding.id, field: "problem", source: "the finding's own title" });
+    }
+  }
+  acceptRepair(before, findings);
+  return repairs;
+}
+
 // src/review/managed.ts
 init_review_notes();
 init_types3();
@@ -64761,6 +64918,9 @@ async function createManagedReviewPackage(input) {
     source: input.findings,
     reviewers
   });
+  const repairs = repairMechanicalOmissions(reported);
+  const head = await resolveTargetHead(input);
+  await anchorFindings(reported, input, head);
   assignGlobalIds(reported, reviewId);
   const merged = mergeVerifications(reported, input.verifications ?? [], {
     mode: input.verificationMode ?? DEFAULT_VERIFICATION_MODE
@@ -64796,7 +64956,6 @@ async function createManagedReviewPackage(input) {
     externalRetained: scoped.external.length,
     ...input.refuted === undefined ? {} : { roundDismissed: roundDismissed.length }
   });
-  const head = await resolveTargetHead(input);
   const manifest = buildManifest2({
     input,
     target: targetWithHead(input.target, head),
@@ -64805,7 +64964,8 @@ async function createManagedReviewPackage(input) {
     flowMatch,
     coverage,
     at,
-    filterStats
+    filterStats,
+    repairs
   });
   const validation = await validateManagedReviewManifest(input.cwd, manifest);
   if (!validation.valid) {
@@ -65067,6 +65227,8 @@ function buildManifest2(args) {
     },
     coverage: args.coverage,
     filter_stats: args.filterStats,
+    ...args.repairs.length === 0 ? {} : { repairs: args.repairs },
+    ...args.input.cost === undefined ? {} : { cost: args.input.cost },
     ...crossFamily === undefined ? {} : { cross_family_review: crossFamily },
     createdAt: args.at,
     updatedAt: args.at
@@ -65132,6 +65294,80 @@ function triage(findings, args) {
     return triaged;
   });
 }
+async function anchorFindings(findings, input, head) {
+  const read = input.readTreeFile ?? (head === null ? readFromWorkingTree(input) : async (relative) => {
+    const contained = await containedRelativePath(input.cwd, relative);
+    return contained === null ? null : readFileAtCommit(input.cwd, head, contained);
+  });
+  for (const finding of findings) {
+    const locator = await locateFinding(finding, read);
+    if (locator === undefined) {
+      delete finding.locator;
+      continue;
+    }
+    if (locator.state === "derived") {
+      finding.line = locator.line;
+      finding.locator = {
+        state: "derived",
+        method: locator.method,
+        ...locator.reported_line === undefined ? {} : { reported_line: locator.reported_line }
+      };
+      continue;
+    }
+    finding.line = null;
+    finding.locator = {
+      state: "unlocatable",
+      reason: locator.reason,
+      ...locator.reported_line === undefined ? {} : { reported_line: locator.reported_line }
+    };
+  }
+}
+async function containedRelativePath(cwd, relative) {
+  const root = await realpath8(cwd).catch(() => path153.resolve(cwd));
+  const resolved = path153.resolve(root, relative);
+  const real = await realpath8(resolved).catch(() => null);
+  if (real === null || real !== root && !real.startsWith(`${root}${path153.sep}`)) {
+    return null;
+  }
+  return real;
+}
+async function readFileAtCommit(cwd, commit, absolute) {
+  const relative = path153.relative(await realpath8(cwd).catch(() => path153.resolve(cwd)), absolute);
+  try {
+    const proc = Bun.spawn(["git", "show", `${commit}:${relative}`], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore"
+    });
+    const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    if (exitCode !== 0 || stdout.length > MAX_LOCATE_FILE_BYTES) {
+      return null;
+    }
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+function readFromWorkingTree(input) {
+  return async (relative) => {
+    const root = await realpath8(input.cwd).catch(() => path153.resolve(input.cwd));
+    const resolved = path153.resolve(root, relative);
+    const real = await realpath8(resolved).catch(() => null);
+    if (real === null || real !== root && !real.startsWith(`${root}${path153.sep}`)) {
+      return null;
+    }
+    try {
+      const info = await stat16(real);
+      if (!info.isFile() || info.size > MAX_LOCATE_FILE_BYTES) {
+        return null;
+      }
+      return await readFile86(real, "utf8");
+    } catch {
+      return null;
+    }
+  };
+}
 function toContractFinding(finding) {
   const record = {
     id: finding.id,
@@ -65149,6 +65385,12 @@ function toContractFinding(finding) {
   if (finding.line !== undefined) {
     record.line = finding.line;
   }
+  if (finding.quote !== undefined) {
+    record.quote = finding.quote;
+  }
+  if (finding.locator !== undefined) {
+    record.locator = finding.locator;
+  }
   if (finding.symbol !== undefined) {
     record.symbol = finding.symbol;
   }
@@ -65801,6 +66043,73 @@ async function loadDocpackSchema(cwd) {
   return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
 }
 
+// src/review/cost.ts
+function estimateTokens2(text) {
+  return Math.ceil(text.length / 4);
+}
+function grouped(value) {
+  return value.toLocaleString("en-US");
+}
+function renderScopeEstimate(scopedDiff, reviewers) {
+  const per = estimateTokens2(scopedDiff);
+  const lines = [
+    `### Estimated cost`,
+    "",
+    `- \u2248 ${grouped(per)} prompt tokens of scoped diff per reviewer (characters \xF7 4 \u2014 an estimate, not a measurement)`
+  ];
+  if (reviewers > 0) {
+    lines.push(`- \u2248 ${grouped(per * reviewers)} across ${reviewers} reviewer${reviewers === 1 ? "" : "s"}, before their own prompts, tools and any verifier wave`);
+  } else {
+    lines.push("- reviewer count not supplied, so the fan-out is not multiplied in \u2014 pass `--reviewers a,b` to see the round's total");
+  }
+  return lines.join(`
+`);
+}
+function costFrom(input) {
+  const cost = {};
+  if (typeof input.inputTokens === "number") {
+    cost.input_tokens = input.inputTokens;
+  }
+  if (typeof input.outputTokens === "number") {
+    cost.output_tokens = input.outputTokens;
+  }
+  if (typeof input.spentUsd === "number") {
+    cost.spent_usd = input.spentUsd;
+  }
+  return Object.keys(cost).length === 0 ? undefined : cost;
+}
+function renderCostPerFinding(cost, retained) {
+  if (cost === undefined) {
+    return [
+      "cost: not recorded",
+      "  Nothing reported what this round used. That is NOT zero: pass --tokens-in/--tokens-out",
+      "  or --spent at ingest so the price of a round is a number somebody can weigh."
+    ];
+  }
+  const tokens = cost.input_tokens === undefined && cost.output_tokens === undefined ? undefined : (cost.input_tokens ?? 0) + (cost.output_tokens ?? 0);
+  const lines = [];
+  if (tokens !== undefined) {
+    lines.push(`tokens: ${grouped(tokens)}`);
+  }
+  if (cost.spent_usd !== undefined) {
+    lines.push(`spent: ${cost.spent_usd} USD`);
+  }
+  lines.push(`retained findings: ${retained}`);
+  if (retained === 0) {
+    lines.push("  Nothing was retained, so there is no per-finding figure \u2014 only the bill.");
+    return lines;
+  }
+  if (tokens !== undefined) {
+    const per = tokens / retained;
+    lines.push(per > 0 && Math.round(per) === 0 ? "per retained finding: < 1 token" : `per retained finding: ${grouped(Math.round(per))} tokens`);
+  }
+  if (cost.spent_usd !== undefined) {
+    const per = cost.spent_usd / retained;
+    lines.push(per > 0 && Number(per.toFixed(4)) === 0 ? "per retained finding: < 0.0001 USD" : `per retained finding: ${per.toFixed(4)} USD`);
+  }
+  return lines;
+}
+
 // src/review/reviewers.ts
 init_project_skills();
 import { readFile as readFile87, readdir as readdir29 } from "fs/promises";
@@ -66977,6 +67286,8 @@ var CREATE_FLAGS = [
   "--max-findings",
   "--spent",
   "--spend-ceiling",
+  "--tokens-in",
+  "--tokens-out",
   "--parallel",
   "--outstanding"
 ];
@@ -67017,8 +67328,12 @@ var SCOPE_FLAGS = [
   "--base",
   "--json",
   "--scoped-diff",
-  "--append"
+  "--append",
+  "--reviewers"
 ];
+function reviewerList(args) {
+  return (optionValue(args, "--reviewers") ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
 var FLOOR_FLAGS = ["--ref", "--base", "--diff", "--context", "--json", "--report-only"];
 var FLOOR_VALUE_FLAGS = ["--ref", "--base", "--diff", "--context"];
 function rejectValuelessOptions(args, valueFlags, usage) {
@@ -67196,7 +67511,12 @@ async function runCreate(mode, args) {
     maxFindingsPerReviewer: parseNonNegativeInteger(optionValue(args, "--max-findings"), "--max-findings"),
     spend: parseMoney(optionValue(args, "--spent"), "--spent"),
     spendCeiling: parseMoney(optionValue(args, "--spend-ceiling"), "--spend-ceiling"),
-    concurrency: parseConcurrency(args)
+    concurrency: parseConcurrency(args),
+    cost: costFrom({
+      inputTokens: parseNonNegativeInteger(optionValue(args, "--tokens-in"), "--tokens-in"),
+      outputTokens: parseNonNegativeInteger(optionValue(args, "--tokens-out"), "--tokens-out"),
+      spentUsd: parseMoney(optionValue(args, "--spent"), "--spent")
+    })
   };
   const result = await createManagedReviewPackage(input);
   console.log(`# managed review: ${result.reviewId}`);
@@ -67861,6 +68181,8 @@ async function runScope(args) {
     console.log(renderScopedDiff(scope));
   } else {
     console.log(renderReviewScopeMarkdown(scope));
+    console.log("");
+    console.log(renderScopeEstimate(renderScopedDiff(scope), reviewerList(args).length));
   }
   const append = optionValue(args, "--append");
   if (append !== undefined) {
@@ -68116,6 +68438,9 @@ async function runComplete3(args) {
   console.log(`# managed review complete: ${manifest.reviewId}`);
   console.log(`status: ${manifest.status}`);
   console.log(`dispositions recorded: ${dispositions.length}`);
+  for (const line of renderCostPerFinding(manifest.cost, manifest.filter_stats?.retained ?? 0)) {
+    console.log(line);
+  }
   for (const note of reviewNotes.written) {
     console.log(`review-note: ${note.finding} -> ${note.path} (attested by ${note.attestation})`);
   }
@@ -75053,7 +75378,7 @@ init_workspace_service();
 init_store2();
 init_fs();
 import { createHash as createHash35, randomUUID as randomUUID17 } from "crypto";
-import { appendFile as appendFile7, mkdir as mkdir58, open as open2, readFile as readFile94, rename as rename7, rm as rm12, stat as stat16, writeFile as writeFile50 } from "fs/promises";
+import { appendFile as appendFile7, mkdir as mkdir58, open as open2, readFile as readFile94, rename as rename7, rm as rm12, stat as stat17, writeFile as writeFile50 } from "fs/promises";
 import path172 from "path";
 
 // src/sac/policy-experiment.ts
@@ -75230,7 +75555,7 @@ var ledgerDigestChunkBytes = 64 * 1024;
 var isMissing = (error) => error instanceof Error && error.code === "ENOENT";
 var checkpointHash = (body) => createHash35("sha256").update(JSON.stringify(body), "utf8").digest("hex");
 async function ledgerByteLength(ledger) {
-  const value = await stat16(ledger, { bigint: true });
+  const value = await stat17(ledger, { bigint: true });
   if (value.size > BigInt(Number.MAX_SAFE_INTEGER))
     throw new Error("invalid access receipt ledger: ledger-too-large");
   return Number(value.size);
@@ -76654,7 +76979,7 @@ function buildToolRegistry() {
 init_fs();
 init_contained_read();
 import path175 from "path";
-import { lstat as lstat5, readdir as readdir34, realpath as realpath8, stat as stat17 } from "fs/promises";
+import { lstat as lstat5, readdir as readdir34, realpath as realpath9, stat as stat18 } from "fs/promises";
 var URI_PREFIX = "metaproject://";
 function mimeForPath(filePath) {
   if (filePath.endsWith(".json") || filePath.endsWith(".jsonl")) {
@@ -76682,10 +77007,10 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   const ownerInfo = await lstat5(ownerRoot).catch(() => null);
   if (!ownerInfo || !ownerInfo.isDirectory() || ownerInfo.isSymbolicLink())
     return [];
-  const ownerReal = await realpath8(ownerRoot).catch(() => null);
+  const ownerReal = await realpath9(ownerRoot).catch(() => null);
   if (!ownerReal)
     return [];
-  const canonical = await realpath8(root).catch(() => null);
+  const canonical = await realpath9(root).catch(() => null);
   if (!canonical || !isPathInside(ownerReal, canonical) || ancestors.has(canonical))
     return [];
   const nextAncestors = new Set(ancestors);
@@ -76699,8 +77024,8 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   }
   for (const entry of entries) {
     const full = path175.join(root, entry.name);
-    const info = await stat17(full).catch(() => null);
-    if (!info || !isPathInside(ownerReal, await realpath8(full).catch(() => "")))
+    const info = await stat18(full).catch(() => null);
+    if (!info || !isPathInside(ownerReal, await realpath9(full).catch(() => "")))
       continue;
     if (info.isDirectory()) {
       out.push(...await walkFiles(full, ownerRoot, nextAncestors));
@@ -76812,7 +77137,7 @@ async function readResource(cwd, roots, uri) {
   if (!resolved) {
     throw new Error(`Resource path is outside its root (rejected): ${uri}`);
   }
-  const info = await stat17(resolved.absolute).catch(() => null);
+  const info = await stat18(resolved.absolute).catch(() => null);
   if (!info || !info.isFile()) {
     throw new Error(`Resource not found: ${uri}`);
   }
@@ -86652,7 +86977,7 @@ init_store3();
 init_proposal_lifecycle();
 init_workspace_service();
 import { randomUUID as randomUUID27 } from "crypto";
-import { readdir as readdir36, stat as stat18 } from "fs/promises";
+import { readdir as readdir36, stat as stat19 } from "fs/promises";
 import path190 from "path";
 
 // src/sac/lifecycle-flag.ts
@@ -86912,7 +87237,7 @@ async function collectReceiptTargets(cwd, owner) {
 async function attributeToSession(absolutePath, sessionsNewestFirst) {
   let mtimeMs;
   try {
-    mtimeMs = (await stat18(absolutePath)).mtimeMs;
+    mtimeMs = (await stat19(absolutePath)).mtimeMs;
   } catch {
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.106",
+  "version": "0.2.107",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/skills/review/review-layout/SKILL.md

@@ -227,7 +227,7 @@ Report done only once all of these hold:
 - The measurement was taken at the worst real case — the longest translation in
   the catalog, the narrowest supported host, the state where the sibling is
   absent — not at the convenient one.
-- Every finding names `file:line` on the component that renders the box.
+- Every finding names the `file` of the component that renders the box and `quote`s the code it is about; `line` is derived at ingest from that quote, never counted.
 - Every `blocker` and `major` carries `class_scope` with `sites` and an
   `enumeration_method` naming the search that derived the set of elements sharing
   the sizing shape.

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -1350,10 +1350,10 @@ Each reviewer must return a `REVIEW_RESULT` object matching `.metaproject/skills
 
 Before consolidation, validate every reviewer result:
 - Required status: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
-- Required finding fields: id, severity, file, line (nullable only for repo-wide findings), problem, impact, suggested_fix, evidence, confidence, reviewer.
+- Required finding fields: id, severity, file, `quote`, problem, impact, suggested_fix, evidence, confidence, reviewer. **`quote`, not `line`:** copy the code the finding is about verbatim out of `file` and do not count lines — `keryx review ingest` locates the quote at the round's head and derives `line` from where it matched, so a number reported here is overwritten. A model is poor at counting lines and good at repeating text it has just read; this asks only for the second. Quote enough to be unambiguous: a snippet appearing twice in the file is recorded `unlocatable` rather than anchored to the first hit. A finding about the round rather than a site carries neither.
 - Every blocker must include evidence and a concrete suggested fix.
 - Findings without evidence are downgraded to `info` or returned to the reviewer for clarification.
-- Duplicate findings are merged by `dedupe_key` or by `(file, line, problem)`.
+- Duplicate findings are merged by `dedupe_key` or by `(file, quote, problem)`.
 - `NEEDS_CONTEXT` triggers one targeted context refill. If still unresolved, keep it as an explicit open question, not as a blocker.
 - If a reviewer exceeds `max_findings`, keep blockers/majors first and summarize lower severity findings.
 

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-finding.schema.json

@@ -74,12 +74,20 @@
             ]
           },
           "line": {
+            "description": "Do not count lines. Quote the code in `quote` instead and leave this null: `keryx review ingest` finds the quote in `file` and writes the line the match started on, overwriting anything reported here. A model is poor at counting lines and good at repeating text it has just read, and this asks it only for the second. Kept in the contract because a finding with nothing to quote — one about the round rather than a site — still has nowhere else to point.",
             "type": [
               "integer",
               "null"
             ],
             "minimum": 1
           },
+          "quote": {
+            "description": "The code this finding is about, copied verbatim out of `file`. A few lines is enough — it is matched against the file at the round's head, exactly first and then with whitespace collapsed. A quote that appears in more than one place is recorded as `unlocatable` rather than anchored to the first hit, so quote enough to be unambiguous.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
           "problem": {
             "type": "string"
           },

package/src/gdskills/contracts/review-finding.schema.json

@@ -100,7 +100,40 @@
       "description": "Which repository `file` and `line` are in. Null, the default, means the repository under review. A cross-repo claim names the producer here and pins the ref it was read at in `evidence`; without this field a finding about another service's behaviour could not say where its evidence lived, so the rule that such a claim is `info` unless it has a `file:line` at a pinned ref could not be checked by anything but the reviewer's word. Declared in BOTH this schema and skills/review/review-orchestrator/reviewer-finding.schema.json: this one is additionalProperties:false, so a finding carrying `repo` is rejected here if only the reviewer-side schema knows about it."
     },
     "file": { "type": ["string", "null"] },
-    "line": { "type": ["integer", "null"], "minimum": 1 },
+    "line": {
+      "title": "Where the finding points — DERIVED when the finding quotes code",
+      "description": "Reported by the reviewer only when there is nothing to quote. When `quote` is present this field is OUTPUT: `review ingest` finds the quote in `file` at the round's head and writes the line the match started on, overwriting whatever the reviewer said and recording both in `locator`. The reason is the failure it replaces — nothing compared a reported line to anything, so a number that had drifted travelled into findings.json, into the report, and into the disposition recorded against it. On a fix round the file has moved under the finding by construction, which is when the reported number is least trustworthy and most acted upon.",
+      "type": ["integer", "null"],
+      "minimum": 1
+    },
+    "quote": {
+      "title": "The code this finding is about, copied verbatim out of `file`",
+      "description": "What replaces asking the model for a line number: a model is poor at counting lines and good at repeating text it has just read. The quote is matched against `file` at the round's head — exactly first, then with whitespace collapsed, then not at all. A quote that matches in more than one place is `unlocatable` rather than anchored to the first hit, because choosing among them would be a guess wearing a line number. Absent for a finding that is about the round rather than a site.",
+      "type": ["string", "null"]
+    },
+    "locator": {
+      "title": "How `line` was arrived at",
+      "description": "Present exactly when the finding carries a quote. `derived` means the quote was found and `line` is where; `unlocatable` means it was not, and then `line` is null rather than a number nobody checked. `reported_line` keeps what the reviewer said, so a round can measure how far the claims drifted from the code — which is the only way to know whether deriving them repaired anything or is insurance.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": { "type": "string", "enum": ["derived", "unlocatable"] },
+        "method": { "type": "string", "enum": ["exact", "whitespace-normalised"] },
+        "reason": { "type": ["string", "null"] },
+        "reported_line": { "type": ["integer", "null"], "minimum": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "derived" } }, "required": ["state"] },
+          "then": { "required": ["method"] }
+        },
+        {
+          "if": { "properties": { "state": { "const": "unlocatable" } }, "required": ["state"] },
+          "then": { "required": ["reason"] }
+        }
+      ]
+    },
     "symbol": { "type": ["string", "null"] },
     "problem": { "type": "string" },
     "impact": { "type": "string" },