@bendyline/gezel-sdk 1.0.6 → 1.0.7

package/dist/checks.d.ts

@@ -1,4 +1,4 @@
-import { G as GateScriptResult } from './types-cYfcp6_8.js';
+import { G as GateScriptResult } from './types-DCBb1goX.js';
 
 /**
  * ─ Shared deliverable checks ─────────────────────────────────────────
@@ -42,6 +42,33 @@ interface CheckResult {
     detail: string;
 }
 
+/**
+ * Existence oracle for cited workspace paths — the shared spine of the
+ * anti-fabrication checks (`citationsResolve`, `securityReport`,
+ * `codebaseReviewReport`).
+ *
+ * `list()` is only a FAST PATH here, never ground truth. The real surface
+ * behind it walks the workspace breadth-first under an entry cap (500 on
+ * the service side) and skips dotfiles, so in any repo bigger than the cap
+ * a truthful citation (`packages/core/src/paths.ts`, `.gitignore`) is
+ * simply absent from the listing. Treating that absence as fabrication
+ * made the gates unsatisfiable by honest citation and pressured models
+ * toward exactly the shallow or invented paths the gates exist to catch
+ * (task gezel/8, 2026-08-23: a 3,843-file repo where only the first 500
+ * entries counted as "real"). A listing miss therefore falls back to a
+ * per-path `read()` probe before any path may be called fabricated.
+ */
+declare function createCitedPathChecker(ws: WorkspaceLike): (cited: string) => Promise<boolean>;
+/**
+ * Strip citation decoration down to a workspace-relative path: backticks,
+ * a `:line` / `#anchor` suffix, leading `./` or `/`, and a `workspace/`
+ * prefix. Case is preserved — the probe read needs the real path on
+ * case-sensitive filesystems; only the listing key lowercases.
+ */
+declare function cleanCitedPath(p: string): string;
+/** Case-insensitive membership key for listing entries and citations alike. */
+declare function citedPathKey(p: string): string;
+
 /**
  * HTML deliverable checks: truncation detection, inline-script
  * extraction, V8 syntax validation, and the two content sniffs the
@@ -327,19 +354,36 @@ interface CitationsResult extends CheckResult {
     unresolved: string[];
     /** Cited URLs (not checked offline unless a corpus allowlist is given). */
     urls: string[];
+    /** Unresolvable cited paths forgiven as task metadata (see `knownPaths`). */
+    forgiven?: string[];
 }
 /**
  * Every source `file` cites must exist. File-path citations are resolved
  * against the workspace listing (tolerant of leading `./`, `/`, and
- * `workspace/`, case-insensitive). URLs cannot be fetched offline, so
+ * `workspace/`, case-insensitive), with a per-path read probe for listing
+ * misses — the listing is capped and dotfile-blind, see
+ * `createCitedPathChecker`. URLs cannot be fetched offline, so
  * they pass unless `corpus` is supplied, in which case every cited path
  * AND URL must be a member of the allowlist. The anti-fabrication gate.
+ *
+ * `knownPaths` are paths the surrounding task itself supplied — invocation
+ * parameters, the step prompt's own path tokens, the artifact working
+ * folder. A cited path matching one of these that does NOT resolve is
+ * FORGIVEN (dropped from the citation set — it counts toward neither the
+ * minimum nor the fabrication verdict): transcribing the run's own
+ * metadata into a packet is bookkeeping, not sourcing. A knownPath that
+ * DOES resolve stays an ordinary resolved citation. Wild-caught: the
+ * powerpoint-deck research step requires sources.md to record the
+ * invocation inputs, and the backticked `tasks/8` / `powerpoint/task-8/
+ * deck.pptx` tokens — directory handles and a future output — read as six
+ * fabricated citations, failing the gate's honest no-research path.
  */
 declare function citationsResolve(ws: WorkspaceLike, file: string, opts?: {
     pattern?: string;
     flags?: string;
     minCitations?: number;
     corpus?: string[];
+    knownPaths?: readonly string[];
 }): Promise<CitationsResult>;
 /** Spec for {@link valuesSubsetOf}. */
 interface ValuesSubsetSpec {
@@ -394,6 +438,25 @@ interface SecurityReportResult extends CheckResult {
 }
 declare function securityReport(ws: WorkspaceLike, reportFile: string, opts?: SecurityReportOptions): Promise<SecurityReportResult>;
 
+interface CodebaseReviewReportOptions {
+    /** Path (in `reports`) to the machine-readable findings JSON. */
+    findings?: string;
+    /** Section headings the report must contain. */
+    requiredSections?: string[];
+    /** Minimum systemic themes required once findings ≥ themeThreshold. */
+    minThemes?: number;
+    /** Findings count at/above which systemic-theme synthesis is required. */
+    themeThreshold?: number;
+    /** Minimum data rows the Scorecard table must carry. */
+    minScorecardRows?: number;
+}
+interface CodebaseReviewReportResult extends CheckResult {
+    findingCount: number;
+    /** Cited files that don't exist in the workspace, for logs/facts. */
+    fabricated: string[];
+}
+declare function codebaseReviewReport(reports: WorkspaceLike, workspace: WorkspaceLike, reportFile: string, opts?: CodebaseReviewReportOptions): Promise<CodebaseReviewReportResult>;
+
 /** ISO yyyy-mm-dd AND a real calendar date (ported from data-wrangle). */
 declare function isRealIsoDate(value: string): boolean;
 /**
@@ -692,6 +755,42 @@ interface PlanStructureResult {
 }
 declare function planStructure(text: string, spec?: PlanStructureSpec): PlanStructureResult;
 
+interface CorpusCoverageShardInput {
+    path: string;
+    content: string;
+}
+interface CorpusCoverageLedger {
+    pullRequest?: number;
+    reviewedFiles: string[];
+    reviewedRecords: string[];
+    sources: Array<{
+        batchNumber: number;
+        shard: string;
+    }>;
+    complete: boolean;
+}
+interface CorpusCoverageMergeResult extends CheckResult {
+    ledger?: CorpusCoverageLedger;
+    content?: string;
+    expectedBatches: number;
+    mergedBatches: number;
+    missingBatches: number[];
+}
+/**
+ * Deterministically merge bounded corpus-coverage shards.
+ *
+ * The published batch manifest is the authority. Every accepted shard must
+ * name exactly one batch and reproduce that batch's path and record arrays in
+ * order; a parent cannot manufacture full-run coverage by copying paths that
+ * no child shard reported. Missing shards may be merged for an in-progress
+ * ledger, but malformed or out-of-scope shards always fail closed.
+ */
+declare function mergeCorpusCoverageShards(batchesContent: string, shards: readonly CorpusCoverageShardInput[], opts?: {
+    pullRequest?: number;
+    requireComplete?: boolean;
+    batchesFile?: string;
+}): CorpusCoverageMergeResult;
+
 /**
  * `@bendyline/gezel-sdk/checks` — the shared deliverable-check predicates,
  * re-exported for use INSIDE sandboxed scripts.
@@ -730,4 +829,4 @@ declare function workspaceFromGezel(g: {
     };
 }): WorkspaceLike;
 
-export { type CellType, type CheckResult, type CitationsResult, type CsvShapeResult, type CsvShapeSpec, type EntitiesResult, type EntitySpec, type ExplainableSniff, GateScriptResult, type GroundingFact, type GroundingResult, IMG_EXT, type ImageRefsReport, type InlineScript, type JsonPathEqualsResult, type JsonScalar, type JudgeVerdict, MIN_INLINE_JS_BYTES, MIN_JUDGE_EVIDENCE_SUBSTRING, type MarkdownHeadingsMatchResult, type ParsedTable, type PlanRow, type PlanStructureResult, type PlanStructureSpec, type ReadingLevelResult, type RecordFieldSpec, type RecordSchemaResult, type RecordSchemaSpec, type ScriptValidation, type SecurityReportOptions, type SecurityReportResult, type TableShapeResult, type TableShapeSpec, type UnsupportedClaimPattern, type UnsupportedClaimViolation, type UnsupportedClaimsResult, type ValuesSubsetResult, type ValuesSubsetSpec, type WordBandResult, type WorkspaceLike, buildJudgePrompt, citationsResolve, containsPattern, countDistinctMatches, cssMinBytes, csvShape, dataTableSniff, detectTypeScriptOnlySyntax, detectUnclosedScript, esmImports, explainSniff, extractInlineScripts, fileCountByExt, fileMinBytes, fileMinLines, findImageRefs, gateResult, grepMatches, htmlCompleteSniff, htmlGameSniff, imageRefsResolve, inlineJsBytes, isRealIsoDate, jsonPathEquals, jsonValid, markdownHeadingsMatch, namedEntitiesConsistent, normalizeDigitGroups, notContainsPattern, parseCsv, parseJudgeVerdict, parseMarkdownTable, planStructure, readingLevel, recordSchema, requireOrderedSections, resolveRelative, securityReport, standaloneJsParses, tableShape, totalMinBytes, unsupportedClaims, validateJudgeEvidence, validateScriptSyntax, valueGrounding, valuesSubsetOf, wordBand, workspaceFromGezel, wrapperReturnHint };
+export { type CellType, type CheckResult, type CitationsResult, type CodebaseReviewReportOptions, type CodebaseReviewReportResult, type CorpusCoverageLedger, type CorpusCoverageMergeResult, type CorpusCoverageShardInput, type CsvShapeResult, type CsvShapeSpec, type EntitiesResult, type EntitySpec, type ExplainableSniff, GateScriptResult, type GroundingFact, type GroundingResult, IMG_EXT, type ImageRefsReport, type InlineScript, type JsonPathEqualsResult, type JsonScalar, type JudgeVerdict, MIN_INLINE_JS_BYTES, MIN_JUDGE_EVIDENCE_SUBSTRING, type MarkdownHeadingsMatchResult, type ParsedTable, type PlanRow, type PlanStructureResult, type PlanStructureSpec, type ReadingLevelResult, type RecordFieldSpec, type RecordSchemaResult, type RecordSchemaSpec, type ScriptValidation, type SecurityReportOptions, type SecurityReportResult, type TableShapeResult, type TableShapeSpec, type UnsupportedClaimPattern, type UnsupportedClaimViolation, type UnsupportedClaimsResult, type ValuesSubsetResult, type ValuesSubsetSpec, type WordBandResult, type WorkspaceLike, buildJudgePrompt, citationsResolve, citedPathKey, cleanCitedPath, codebaseReviewReport, containsPattern, countDistinctMatches, createCitedPathChecker, cssMinBytes, csvShape, dataTableSniff, detectTypeScriptOnlySyntax, detectUnclosedScript, esmImports, explainSniff, extractInlineScripts, fileCountByExt, fileMinBytes, fileMinLines, findImageRefs, gateResult, grepMatches, htmlCompleteSniff, htmlGameSniff, imageRefsResolve, inlineJsBytes, isRealIsoDate, jsonPathEquals, jsonValid, markdownHeadingsMatch, mergeCorpusCoverageShards, namedEntitiesConsistent, normalizeDigitGroups, notContainsPattern, parseCsv, parseJudgeVerdict, parseMarkdownTable, planStructure, readingLevel, recordSchema, requireOrderedSections, resolveRelative, securityReport, standaloneJsParses, tableShape, totalMinBytes, unsupportedClaims, validateJudgeEvidence, validateScriptSyntax, valueGrounding, valuesSubsetOf, wordBand, workspaceFromGezel, wrapperReturnHint };

package/dist/checks.js

@@ -1,3 +1,33 @@
+// ../core/src/checks/workspace-exists.ts
+function createCitedPathChecker(ws) {
+  let listing = null;
+  const probes = /* @__PURE__ */ new Map();
+  const loadListing = () => {
+    listing ??= ws.list().then((files) => new Set(files.map((f) => citedPathKey(f))));
+    return listing;
+  };
+  return async (cited) => {
+    const probe = cleanCitedPath(cited);
+    if (!probe) return false;
+    if ((await loadListing()).has(probe.toLowerCase())) return true;
+    let hit = probes.get(probe);
+    if (!hit) {
+      hit = ws.read(probe).then(
+        (content) => content !== null,
+        () => false
+      );
+      probes.set(probe, hit);
+    }
+    return hit;
+  };
+}
+function cleanCitedPath(p) {
+  return p.trim().replace(/^`+|`+$/g, "").replace(/[:#].*$/, "").replace(/^\.\//, "").replace(/^\/+/, "").replace(/^workspace\//i, "");
+}
+function citedPathKey(p) {
+  return cleanCitedPath(p).toLowerCase();
+}
+
 // ../core/src/checks/html.ts
 var MIN_INLINE_JS_BYTES = 2048;
 var SCRIPT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
@@ -536,12 +566,24 @@ function valueGrounding(text, facts, opts = {}) {
     decoysDetected
   };
 }
-var DEFAULT_CITATION_RE = /\(source:\s*([^)\s]+)(?:\s+\[[^\]]*\])*\s*\)|\]\(\s*(?!#)([^)\s]+?)\s*\)|`([^`]*\/[^`]+)`/gi;
+var DEFAULT_CITATION_RE = (
+  // The inline-path form excludes newlines AND spaces on purpose: a path
+  // contains neither, and without the exclusions two failure families
+  // appear (both wild-caught). An UNBALANCED backtick lets the span swallow
+  // sentences until the next stray backtick; and even with balanced spans,
+  // the CLOSER of one legitimate span pairs with the OPENER of the next, so
+  // the prose BETWEEN two `code` spans — which mentions a path — became one
+  // giant unresolvable "citation" and honest work read as fabricated.
+  /\(source:\s*([^)\s]+)(?:\s+\[[^\]]*\])*\s*\)|\]\(\s*(?!#)([^)\s]+?)\s*\)|`([^`\s]*\/[^`\s]+)`/gi
+);
+function stripFencedBlocks(text) {
+  return text.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]*\1[ \t]*$/gm, "").replace(/^[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*$/m, "");
+}
 function extractCitations(text, re) {
   const flags = re.flags.includes("g") ? re.flags : `${re.flags}g`;
   const global = new RegExp(re.source, flags);
   const out = [];
-  for (const m of text.matchAll(global)) {
+  for (const m of stripFencedBlocks(text).matchAll(global)) {
     const cap = m.slice(1).find((x) => x !== void 0) ?? m[0];
     if (cap) out.push(cap);
   }
@@ -550,8 +592,8 @@ function extractCitations(text, re) {
 function cleanCitation(raw) {
   return raw.trim().replace(/^[<'"`(]+/, "").replace(/[>'"`).,;:]+$/, "");
 }
-function normalizePath(p) {
-  return p.trim().toLowerCase().replace(/^\.?\//, "").replace(/^workspace\//, "");
+function normalizeForKnownMatch(p) {
+  return p.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\//, "").replace(/^workspace\//i, "").replace(/\/+$/, "").toLowerCase();
 }
 async function citationsResolve(ws, file, opts = {}) {
   const content = await ws.read(file);
@@ -574,38 +616,54 @@ async function citationsResolve(ws, file, opts = {}) {
       urls: []
     };
   }
-  const cites = [...new Set(extractCitations(content, re).map(cleanCitation).filter(Boolean))];
+  const cites = [
+    ...new Set(
+      extractCitations(content, re).map(cleanCitation).filter(
+        (citation) => citation && (/^[a-z][\w+.-]*:\/\//i.test(citation) || !/[\\/]$/.test(citation))
+      )
+    )
+  ];
   const min = opts.minCitations ?? 1;
-  const listing = new Set((await ws.list()).map(normalizePath));
+  const citedPathExists = createCitedPathChecker(ws);
   const corpus = opts.corpus ? new Set(opts.corpus.map((c) => c.toLowerCase())) : null;
+  const known = new Set((opts.knownPaths ?? []).map(normalizeForKnownMatch).filter(Boolean));
   const resolved = [];
   const unresolved = [];
   const urls = [];
+  const forgiven = [];
   for (const c of cites) {
     if (/^[a-z][\w+.-]*:\/\//i.test(c) || c.startsWith("mailto:")) {
       urls.push(c);
       if (corpus && !corpus.has(c.toLowerCase())) unresolved.push(c);
       continue;
     }
-    if (listing.has(normalizePath(c)) || corpus?.has(c.toLowerCase())) resolved.push(c);
+    if (corpus?.has(c.toLowerCase()) || await citedPathExists(c)) resolved.push(c);
+    else if (known.has(normalizeForKnownMatch(c))) forgiven.push(c);
     else unresolved.push(c);
   }
-  if (cites.length < min) {
+  if (cites.length - forgiven.length < min) {
     return {
       ok: false,
-      detail: `${file} has ${cites.length} citation(s), need \u2265 ${min} \u2014 cite the source path/URL for each claim.`,
+      // Name the accepted FORMS, not just the rule: a model that wrote the
+      // right paths as plain prose ("File: src/pricing.js, line 8") reads
+      // "cite the source" as already satisfied and rewrites content instead
+      // of adding markup, looping to gate exhaustion (wild-caught:
+      // deepseek-v4 with a flawless diagnosis, three identical rejections).
+      detail: `${file} has ${cites.length - forgiven.length} recognizable citation(s), need \u2265 ${min}. Only these forms count as citations: a backticked path like \`src/file.js\`, a markdown link like [name](src/file.js), or (source: src/file.js). Plain prose paths are not counted \u2014 wrap each cited file path in backticks.`,
       resolved,
       unresolved,
-      urls
+      urls,
+      ...forgiven.length > 0 ? { forgiven } : {}
     };
   }
   if (unresolved.length > 0) {
     return {
       ok: false,
-      detail: `${file} cites ${unresolved.length} source(s) that do not exist: ${unresolved.slice(0, 5).join(", ")} \u2014 every cited path must resolve to a real file in the workspace${corpus ? "/corpus" : ""} (no fabricated citations).`,
+      detail: `${file} cites ${unresolved.length} source(s) that do not exist: ${unresolved.slice(0, 5).join(", ")}${unresolved.length > 5 ? ", \u2026" : ""} \u2014 every cited path must resolve to a real file in the workspace${corpus ? "/corpus" : ""} (no fabricated citations).`,
       resolved,
       unresolved,
-      urls
+      urls,
+      ...forgiven.length > 0 ? { forgiven } : {}
     };
   }
   return {
@@ -613,7 +671,8 @@ async function citationsResolve(ws, file, opts = {}) {
     detail: `${file} cites ${resolved.length} resolvable source(s)${urls.length ? ` (+${urls.length} URL(s) not checked offline)` : ""}`,
     resolved,
     unresolved,
-    urls
+    urls,
+    ...forgiven.length > 0 ? { forgiven } : {}
   };
 }
 function valuesSubsetOf(outputText, sourceTexts, spec) {
@@ -682,9 +741,6 @@ var VALID_SEVERITIES = /* @__PURE__ */ new Set(["critical", "high", "medium", "l
 function str(x) {
   return typeof x === "string" ? x.trim() : "";
 }
-function normalizePath2(p) {
-  return p.trim().replace(/^`+|`+$/g, "").replace(/[:#].*$/, "").replace(/^\.\//, "").replace(/^\/+/, "").replace(/^workspace\//i, "").toLowerCase();
-}
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -740,12 +796,12 @@ async function securityReport(ws, reportFile, opts = {}) {
   if (!arr) {
     return fail(`${findingsPath} must be a JSON array of findings (or { "findings": [...] }).`);
   }
-  const listing = new Set((await ws.list()).map(normalizePath2));
+  const citedPathExists = createCitedPathChecker(ws);
   const problems = [];
   const fabricated = [];
   let critHigh = 0;
-  arr.forEach((raw2, i) => {
-    const f = raw2 ?? {};
+  for (const [i, rawFinding] of arr.entries()) {
+    const f = rawFinding ?? {};
     const file = str(f.file ?? f.path);
     const sev = str(f.severity).toLowerCase();
     const remediation = str(f.remediation ?? f.fix ?? f.recommendation);
@@ -753,13 +809,13 @@ async function securityReport(ws, reportFile, opts = {}) {
     const line = f.line ?? f.lineStart;
     const label = file || `#${i + 1}`;
     if (!file) problems.push(`finding #${i + 1} has no file`);
-    else if (!listing.has(normalizePath2(file))) fabricated.push(file);
+    else if (!await citedPathExists(file)) fabricated.push(file);
     if (!VALID_SEVERITIES.has(sev)) problems.push(`${label} has an invalid severity "${sev}"`);
     if (!remediation) problems.push(`${label} has no remediation`);
     if (!title) problems.push(`${label} has no title/description`);
     if (typeof line !== "number") problems.push(`${label} is not pinned to a line`);
     if (sev === "critical" || sev === "high") critHigh++;
-  });
+  }
   if (fabricated.length > 0) {
     return fail(
       `findings cite ${fabricated.length} file(s) that don't exist in the workspace: ${uniq(fabricated).slice(0, 5).join(", ")} \u2014 every finding must point at a real file:line (no fabricated citations).`,
@@ -818,6 +874,191 @@ async function securityReport(ws, reportFile, opts = {}) {
   };
 }
 
+// ../core/src/checks/codebase-review-report.ts
+var DEFAULT_SECTIONS2 = [
+  "Executive summary",
+  "Scorecard",
+  "Index coverage and method",
+  "Systemic themes",
+  "Findings",
+  "Quick wins",
+  "Strategic recommendations",
+  "Verified sound",
+  "Not assessed",
+  "Suggested deeper reviews"
+];
+var VALID_SEVERITIES2 = /* @__PURE__ */ new Set(["critical", "high", "medium", "low", "info"]);
+function str2(x) {
+  return typeof x === "string" ? x.trim() : "";
+}
+function escapeRe2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasSection2(content, name) {
+  return new RegExp(`^#{1,4}\\s+${escapeRe2(name)}\\b`, "im").test(content);
+}
+function sectionBody2(content, name) {
+  const m = new RegExp(`^(#{1,4})\\s+${escapeRe2(name)}\\b`, "im").exec(content);
+  if (!m) return "";
+  const level = m[1].length;
+  const start = m.index + m[0].length;
+  const rest = content.slice(start);
+  const next = new RegExp(`^#{1,${level}}\\s+\\S`, "m").exec(rest);
+  return next ? rest.slice(0, next.index) : rest;
+}
+function countThemeItems2(section) {
+  let n = 0;
+  for (const line of section.split(/\r?\n/)) {
+    if (/^\s*(#{3,4}\s+\S|[-*]\s+\S|\d+\.\s+\S|\*\*[^*]+\*\*)/.test(line)) n++;
+  }
+  return n;
+}
+function scorecardRows(section) {
+  const lines = section.split(/\r?\n/);
+  let headerAt = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*\|/.test(line) && /dimension/i.test(line) && /(grade|rating|score|health)/i.test(line)) {
+      headerAt = i;
+      break;
+    }
+  }
+  if (headerAt < 0) return -1;
+  let rows = 0;
+  for (let i = headerAt + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/^\s*\|/.test(line)) break;
+    if (/^\s*\|[\s:|-]+\|?\s*$/.test(line)) continue;
+    if (line.replace(/[|\s]/g, "").length === 0) continue;
+    rows++;
+  }
+  return rows;
+}
+function uniq2(xs) {
+  return [...new Set(xs)];
+}
+async function codebaseReviewReport(reports, workspace, reportFile, opts = {}) {
+  const fail = (detail, count = 0, fabricated2 = []) => ({
+    ok: false,
+    detail,
+    findingCount: count,
+    fabricated: fabricated2
+  });
+  const content = await reports.read(reportFile);
+  if (content === null) {
+    return fail(`${reportFile} not found \u2014 write the codebase review report before advancing.`);
+  }
+  const findingsPath = opts.findings ?? "codebase-review-findings.json";
+  const raw = await reports.read(findingsPath);
+  if (raw === null) {
+    return fail(
+      `${findingsPath} not found \u2014 emit a machine-readable findings JSON alongside the report.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return fail(
+      `${findingsPath} is not valid JSON (${e instanceof Error ? e.message : "parse error"}). Emit a JSON array of findings.`
+    );
+  }
+  const arr = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.findings) ? parsed.findings : null;
+  if (!arr) {
+    return fail(`${findingsPath} must be a JSON array of findings (or { "findings": [...] }).`);
+  }
+  const citedPathExists = createCitedPathChecker(workspace);
+  const problems = [];
+  const fabricated = [];
+  let critHigh = 0;
+  for (const [i, rawFinding] of arr.entries()) {
+    const f = rawFinding ?? {};
+    const file = str2(f.file ?? f.path);
+    const sev = str2(f.severity).toLowerCase();
+    const remediation = str2(f.remediation ?? f.fix ?? f.recommendation);
+    const title = str2(f.title ?? f.description ?? f.summary);
+    const line = f.line ?? f.lineStart;
+    const label = file || `#${i + 1}`;
+    if (!file) problems.push(`finding #${i + 1} has no file`);
+    else if (!await citedPathExists(file)) fabricated.push(file);
+    if (!VALID_SEVERITIES2.has(sev)) problems.push(`${label} has an invalid severity "${sev}"`);
+    if (!remediation) problems.push(`${label} has no remediation`);
+    if (!title) problems.push(`${label} has no title/description`);
+    if ((sev === "critical" || sev === "high") && typeof line !== "number") {
+      problems.push(`${label} is ${sev} but not pinned to a line`);
+    }
+    if (sev === "critical" || sev === "high") critHigh++;
+  }
+  if (fabricated.length > 0) {
+    return fail(
+      `findings cite ${fabricated.length} file(s) that don't exist in the workspace: ${uniq2(fabricated).slice(0, 5).join(", ")} \u2014 every finding must point at a real file (no fabricated citations).`,
+      arr.length,
+      uniq2(fabricated)
+    );
+  }
+  if (problems.length > 0) {
+    return fail(
+      `${problems.length} finding(s) are incomplete: ${problems.slice(0, 4).join("; ")} \u2014 every finding needs a real file, a severity, a title, and a concrete remediation (critical/high pinned to a line).`,
+      arr.length
+    );
+  }
+  const requiredSections = opts.requiredSections ?? DEFAULT_SECTIONS2;
+  const missing = requiredSections.filter((s) => !hasSection2(content, s));
+  if (missing.length > 0) {
+    return fail(
+      `the report is missing required section(s): ${missing.map((s) => `## ${s}`).join(", ")}.`,
+      arr.length
+    );
+  }
+  const minRows = opts.minScorecardRows ?? 4;
+  const rows = scorecardRows(sectionBody2(content, "Scorecard"));
+  if (rows < 0) {
+    return fail(
+      'the "Scorecard" section has no per-dimension table \u2014 add a markdown table with Dimension and Grade columns.',
+      arr.length
+    );
+  }
+  if (rows < minRows) {
+    return fail(
+      `the Scorecard table has ${rows} dimension row(s); grade at least ${minRows} dimensions (e.g. architecture, code quality, hygiene, security, tests).`,
+      arr.length
+    );
+  }
+  const themeThreshold = opts.themeThreshold ?? 3;
+  const minThemes = opts.minThemes ?? 2;
+  if (arr.length >= themeThreshold) {
+    const themes = sectionBody2(content, "Systemic themes");
+    const items = countThemeItems2(themes);
+    if (items < minThemes) {
+      return fail(
+        `the "Systemic themes" section lists ${items} theme(s); a review with ${arr.length} findings needs \u2265 ${minThemes}, each naming a root cause and its blast radius.`,
+        arr.length
+      );
+    }
+    if (!/root[\s-]?cause/i.test(themes) || !/(blast[\s-]?radius|impact|scope|reach)/i.test(themes)) {
+      return fail(
+        `the "Systemic themes" section must analyze each theme's root cause and blast radius \u2014 that analysis is absent.`,
+        arr.length
+      );
+    }
+  }
+  const summary = sectionBody2(content, "Executive summary").toLowerCase();
+  if (critHigh > 0 && /(excellent (health|shape|condition)|no (significant |material )?(issues|problems|findings)|nothing to fix|clean bill of health)/.test(
+    summary
+  ) && !/(critical|high|however|but |concern|risk)/.test(summary)) {
+    return fail(
+      `the executive summary reads clean but there ${critHigh === 1 ? "is" : "are"} ${critHigh} critical/high finding(s) \u2014 the summary must reflect the open severity.`,
+      arr.length
+    );
+  }
+  return {
+    ok: true,
+    detail: `codebase review OK: ${arr.length} finding(s), all cite real files, ${rows} scorecard dimension(s), required sections present${arr.length >= themeThreshold ? ", systemic themes analyzed" : ""}.`,
+    findingCount: arr.length,
+    fabricated: []
+  };
+}
+
 // ../core/src/checks/records.ts
 var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 function isRealIsoDate(value) {
@@ -1804,6 +2045,172 @@ function findCycle(rows) {
   return cycle;
 }
 
+// ../core/src/checks/corpus-coverage.ts
+function failure(detail) {
+  return {
+    ok: false,
+    detail,
+    expectedBatches: 0,
+    mergedBatches: 0,
+    missingBatches: []
+  };
+}
+function parseStringArray(value) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item === "")) {
+    return null;
+  }
+  return value;
+}
+function firstMismatch(actual, expected) {
+  if (actual.length !== expected.length) return Math.min(actual.length, expected.length);
+  for (let index = 0; index < expected.length; index += 1) {
+    if (actual[index] !== expected[index]) return index;
+  }
+  return null;
+}
+function mergeCorpusCoverageShards(batchesContent, shards, opts = {}) {
+  const batchesFile = opts.batchesFile ?? "batches.json";
+  let batchesRaw;
+  try {
+    batchesRaw = JSON.parse(batchesContent);
+  } catch (err) {
+    return failure(
+      `${batchesFile} is not valid JSON (${err instanceof Error ? err.message : String(err)}).`
+    );
+  }
+  if (!Array.isArray(batchesRaw) || batchesRaw.length === 0) {
+    return failure(`${batchesFile} must contain a non-empty batch array.`);
+  }
+  const batches = [];
+  const allPaths = /* @__PURE__ */ new Set();
+  const allRecords = /* @__PURE__ */ new Set();
+  for (let index = 0; index < batchesRaw.length; index += 1) {
+    const raw = batchesRaw[index];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      return failure(`${batchesFile}[${index}] must be an object.`);
+    }
+    const fields = raw;
+    const batchNumber = fields.batchNumber;
+    const paths = parseStringArray(fields.paths);
+    const records = parseStringArray(fields.records);
+    if (!Number.isInteger(batchNumber) || batchNumber !== index + 1) {
+      return failure(
+        `${batchesFile}[${index}] must have batchNumber ${index + 1}; found ${JSON.stringify(batchNumber)}.`
+      );
+    }
+    if (!paths || paths.length === 0) {
+      return failure(`${batchesFile}[${index}].paths must be a non-empty string array.`);
+    }
+    if (!records || records.length !== paths.length) {
+      return failure(
+        `${batchesFile}[${index}].records must contain one exact record path per changed path.`
+      );
+    }
+    for (const path of paths) {
+      if (allPaths.has(path))
+        return failure(`${batchesFile} assigns '${path}' to multiple batches.`);
+      allPaths.add(path);
+    }
+    for (const record of records) {
+      if (allRecords.has(record)) {
+        return failure(`${batchesFile} assigns record '${record}' to multiple batches.`);
+      }
+      allRecords.add(record);
+    }
+    batches.push({ batchNumber, paths, records });
+  }
+  const shardByBatch = /* @__PURE__ */ new Map();
+  for (const shard of shards) {
+    const normalized = shard.path.replace(/\\/g, "/");
+    const match = /(?:^|\/)coverage-(\d+)\.json$/.exec(normalized);
+    if (!match) continue;
+    const batchNumber = Number(match[1]);
+    if (batchNumber < 1 || batchNumber > batches.length) {
+      return failure(
+        `${shard.path} claims batch ${batchNumber}, but ${batchesFile} has batches 1-${batches.length}.`
+      );
+    }
+    if (shardByBatch.has(batchNumber)) {
+      return failure(`More than one coverage shard claims batch ${batchNumber}.`);
+    }
+    shardByBatch.set(batchNumber, shard);
+  }
+  const reviewedFiles = [];
+  const reviewedRecords = [];
+  const sources = [];
+  for (const batch of batches) {
+    const shard = shardByBatch.get(batch.batchNumber);
+    if (!shard) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(shard.content);
+    } catch (err) {
+      return failure(
+        `${shard.path} is not valid JSON (${err instanceof Error ? err.message : String(err)}).`
+      );
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return failure(`${shard.path} must contain a JSON object.`);
+    }
+    const fields = parsed;
+    if (fields.batchNumber !== batch.batchNumber) {
+      return failure(
+        `${shard.path} must declare batchNumber ${batch.batchNumber}; found ${JSON.stringify(fields.batchNumber)}.`
+      );
+    }
+    const files = parseStringArray(fields.reviewedFiles);
+    const records = parseStringArray(fields.reviewedRecords);
+    if (!files || !records) {
+      return failure(`${shard.path} must contain reviewedFiles and reviewedRecords string arrays.`);
+    }
+    const fileMismatch = firstMismatch(files, batch.paths);
+    if (fileMismatch !== null) {
+      return failure(
+        `${shard.path} does not exactly match batch ${batch.batchNumber}'s changed paths at position ${fileMismatch + 1}; coverage may only come from that batch's shard.`
+      );
+    }
+    const recordMismatch = firstMismatch(records, batch.records);
+    if (recordMismatch !== null) {
+      return failure(
+        `${shard.path} does not exactly match batch ${batch.batchNumber}'s artifact records at position ${recordMismatch + 1}.`
+      );
+    }
+    reviewedFiles.push(...files);
+    reviewedRecords.push(...records);
+    sources.push({
+      batchNumber: batch.batchNumber,
+      shard: shard.path.replace(/\\/g, "/")
+    });
+  }
+  const missingBatches = batches.map((batch) => batch.batchNumber).filter((batchNumber) => !shardByBatch.has(batchNumber));
+  if (opts.requireComplete && missingBatches.length > 0) {
+    return {
+      ok: false,
+      detail: `Coverage shards are still missing for batch${missingBatches.length === 1 ? "" : "es"} ${missingBatches.join(", ")}.`,
+      expectedBatches: batches.length,
+      mergedBatches: sources.length,
+      missingBatches
+    };
+  }
+  const ledger = {
+    ...opts.pullRequest !== void 0 ? { pullRequest: opts.pullRequest } : {},
+    reviewedFiles,
+    reviewedRecords,
+    sources,
+    complete: missingBatches.length === 0
+  };
+  return {
+    ok: true,
+    detail: missingBatches.length === 0 ? `Coverage is provenance-complete across all ${batches.length} batches and ${reviewedFiles.length} changed paths.` : `Merged ${sources.length}/${batches.length} coverage shards; waiting for batches ${missingBatches.join(", ")}.`,
+    ledger,
+    content: `${JSON.stringify(ledger, null, 2)}
+`,
+    expectedBatches: batches.length,
+    mergedBatches: sources.length,
+    missingBatches
+  };
+}
+
 // src/checks.ts
 function gateResult(ok, detail) {
   return ok ? { decision: "approve", message: detail } : { decision: "reject", message: detail };
@@ -1826,8 +2233,12 @@ export {
   MIN_JUDGE_EVIDENCE_SUBSTRING,
   buildJudgePrompt,
   citationsResolve,
+  citedPathKey,
+  cleanCitedPath,
+  codebaseReviewReport,
   containsPattern,
   countDistinctMatches,
+  createCitedPathChecker,
   cssMinBytes,
   csvShape,
   dataTableSniff,
@@ -1850,6 +2261,7 @@ export {
   jsonPathEquals,
   jsonValid,
   markdownHeadingsMatch,
+  mergeCorpusCoverageShards,
   namedEntitiesConsistent,
   normalizeDigitGroups,
   notContainsPattern,

package/dist/index.d.ts

@@ -1,5 +1,96 @@
-import { S as ScriptMeta, I as InferInput, a as InferOutput, b as ScriptInputs, c as ScriptOutputs } from './types-cYfcp6_8.js';
-export { G as GateScriptResult, d as ScriptArrayOutput, e as ScriptBooleanInput, f as ScriptBooleanOutput, g as ScriptCapability, h as ScriptChoiceInput, i as ScriptChoiceOption, j as ScriptInputField, k as ScriptJsonInput, l as ScriptJsonOutput, m as ScriptNumberInput, n as ScriptNumberOutput, o as ScriptObjectOutput, p as ScriptOutputField, q as ScriptRefInput, r as ScriptStringInput, s as ScriptStringOutput } from './types-cYfcp6_8.js';
+import { S as ScriptMeta, I as InferInput, a as InferOutput, b as ScriptInputs, c as ScriptOutputs } from './types-DCBb1goX.js';
+export { G as GateScriptResult, d as ScriptArrayOutput, e as ScriptBooleanInput, f as ScriptBooleanOutput, g as ScriptCapability, h as ScriptChoiceInput, i as ScriptChoiceOption, j as ScriptInputField, k as ScriptJsonInput, l as ScriptJsonOutput, m as ScriptNumberInput, n as ScriptNumberOutput, o as ScriptObjectOutput, p as ScriptOutputField, q as ScriptRefInput, r as ScriptStringInput, s as ScriptStringOutput } from './types-DCBb1goX.js';
+
+/**
+ * Script-SDK wire types for workspace-index status and readiness.
+ *
+ * These deliberately live in the self-contained SDK instead of importing
+ * the Zod-inferred core types. Script sandboxes and Monaco receive only the
+ * SDK declaration files, so an external type import would make that surface
+ * depend on another package. The parity test beside this file keeps these
+ * structural copies aligned with the canonical core schemas.
+ */
+interface WorkspaceIndexStatus {
+    state: 'fresh' | 'stale' | 'indexing' | 'never' | 'disabled';
+    embeddings?: {
+        status: 'cold' | 'warming' | 'ready' | 'disabled' | 'unavailable';
+        reason?: string;
+    };
+    meta?: {
+        version: number;
+        scannedAt: string;
+        root: string;
+        durationMs: number;
+        fileCount: number;
+        commandCount: number;
+        shapeCount?: number;
+    };
+    aiScanPending?: boolean;
+    aiDrive?: 'background' | 'full';
+    enrichment?: {
+        eligible: number;
+        summarized: number;
+        embedded: number;
+        searchReady?: number;
+        pending: number;
+        skipped?: number;
+        skippedFiles?: Array<{
+            path: string;
+            attempts: number;
+            reason?: string;
+        }>;
+        shadowsPending?: number;
+        embedOnlyPending?: number;
+        embedModel?: string;
+        vectorsAvailable?: boolean;
+        reviews?: {
+            eligible: number;
+            reviewed: number;
+            stale: number;
+            pending: number;
+        };
+    };
+}
+interface IndexReadinessReport {
+    version: 1;
+    projectId: string;
+    generatedAt: string;
+    indexingEnabled: boolean;
+    staticState: 'fresh' | 'stale' | 'indexing' | 'never' | 'disabled';
+    fileCount?: number;
+    scannedAt?: string;
+    search: {
+        ready: boolean;
+        eligible?: number;
+        embedded?: number;
+        pendingEmbedOnly?: number;
+        embedModel?: string;
+        vectorsAvailable?: boolean;
+    };
+    aiTier: {
+        staffed: boolean;
+        paused: boolean;
+        achievable: boolean;
+        summariesEligible?: number;
+        summarized?: number;
+        summariesPending?: number;
+        shadowsPending?: number;
+        skipped?: number;
+        reviews?: {
+            eligible: number;
+            reviewed: number;
+            stale: number;
+            pending: number;
+        };
+    };
+    wait: {
+        budgetMs: number;
+        waitedMs: number;
+        drained: boolean;
+        driveStillRunning: boolean;
+    };
+    notes: string[];
+}
 
 /**
  * `@bendyline/gezel-sdk` — imported by TypeScript scripts running in the
@@ -556,6 +647,33 @@ interface GezelSDK<TInput = Record<string, unknown>> {
          */
         authed(url: string, opts: AuthedHttpOpts): Promise<AuthedHttpResponse>;
     };
+    /**
+     * The project's **workspace index** — status of the static scan and the
+     * AI tiers, plus a bounded "make it fresh" ensure. Requires `index.read`
+     * for {@link GezelSDK.index.status | status} and `index.refresh` for
+     * {@link GezelSDK.index.ensureFresh | ensureFresh}.
+     */
+    index: {
+        /** Current index status (static state + enrichment/review coverage). */
+        status(): Promise<WorkspaceIndexStatus>;
+        /**
+         * Make the index as fresh as it can get within an awake-time budget:
+         * awaited static re-scan, then an AI-tier catch-up drive raced against
+         * the budget. Always resolves with an honest readiness report — on a
+         * crew with no Boekwachter the AI tiers are reported unachievable
+         * rather than awaited, and an expired budget leaves the drive running
+         * in the background.
+         *
+         * @param opts.waitBudgetMs - Awake-time wait budget (default 180s,
+         *   capped at 240s to stay inside the script run timeout).
+         * @param opts.reviews - Also wait for the per-file AI review tier
+         *   (default true).
+         */
+        ensureFresh(opts?: {
+            waitBudgetMs?: number;
+            reviews?: boolean;
+        }): Promise<IndexReadinessReport>;
+    };
     /**
      * **Nested scripts** — run another script in the same project and get
      * its stamped output back. No capability is required to call, but the
@@ -592,4 +710,4 @@ declare const gezel: GezelSDK;
 type InferredInput<M> = M extends ScriptMeta<infer I, infer _O> ? InferInput<I> : never;
 type InferredOutput<M> = M extends ScriptMeta<infer _I, infer O> ? InferOutput<O> : never;
 
-export { type ArtifactEntry, type AuthedHttpOpts, type AuthedHttpResponse, type DocumentEntry, type FsEntry, type FsStat, type GezelSDK, type HttpRequestOpts, type HttpResponse, InferInput, InferOutput, type InferredInput, type InferredOutput, type OneShotOpts, ScriptInputs, ScriptMeta, ScriptOutputs, type ScriptResult, type TaskNote, type TaskNoteAuthor, type TaskStep, defineScript, gezel };
+export { type ArtifactEntry, type AuthedHttpOpts, type AuthedHttpResponse, type DocumentEntry, type FsEntry, type FsStat, type GezelSDK, type HttpRequestOpts, type HttpResponse, type IndexReadinessReport, InferInput, InferOutput, type InferredInput, type InferredOutput, type OneShotOpts, ScriptInputs, ScriptMeta, ScriptOutputs, type ScriptResult, type TaskNote, type TaskNoteAuthor, type TaskStep, type WorkspaceIndexStatus, defineScript, gezel };

package/dist/index.js

@@ -8,6 +8,11 @@ var DEFAULT_INIT = {
   engagementMode: "off",
   engagementFlags: { llmAllowed: false }
 };
+var WRITE_BACKPRESSURE_RETRY_MS = 1;
+var WRITE_BACKPRESSURE_TIMEOUT_MS = 3e4;
+var WRITE_BACKPRESSURE_SIGNAL = new Int32Array(
+  new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)
+);
 function readInitSync() {
   if (process.env.GEZEL_SCRIPT_RUNTIME !== "1") {
     return DEFAULT_INIT;
@@ -132,8 +137,27 @@ var RpcClient = class {
 function writeFrame(payload) {
   const buf = Buffer.from(payload, "utf8");
   let offset = 0;
+  const startedAt = Date.now();
   while (offset < buf.length) {
-    offset += writeSync(3, buf, offset, buf.length - offset);
+    try {
+      const written = writeSync(3, buf, offset, buf.length - offset);
+      if (written > 0) {
+        offset += written;
+        continue;
+      }
+    } catch (error) {
+      const code = error.code;
+      if (code === "EINTR") continue;
+      if (code !== "EAGAIN" && code !== "EWOULDBLOCK") throw error;
+    }
+    if (Date.now() - startedAt >= WRITE_BACKPRESSURE_TIMEOUT_MS) {
+      const error = new Error(
+        `script RPC channel remained backpressured after writing ${offset} of ${buf.length} bytes`
+      );
+      error.code = "ETIMEDOUT";
+      throw error;
+    }
+    Atomics.wait(WRITE_BACKPRESSURE_SIGNAL, 0, 0, WRITE_BACKPRESSURE_RETRY_MS);
   }
 }
 
@@ -208,6 +232,13 @@ var gezel = {
   mcp: {
     call: (tool, args) => rpc.call("mcp.call", { tool, args })
   },
+  index: {
+    status: () => rpc.call("index.status"),
+    ensureFresh: (opts) => rpc.call("index.ensureFresh", {
+      ...opts?.waitBudgetMs !== void 0 ? { waitBudgetMs: opts.waitBudgetMs } : {},
+      ...opts?.reviews !== void 0 ? { reviews: opts.reviews } : {}
+    })
+  },
   http: {
     request: (url, opts) => rpc.call("http.request", {
       url,

package/dist/page.d.ts

@@ -19,6 +19,11 @@
  *  - `browser` — an "Open in browser" tab with no embedding parent. Data
  *    reads fall back to same-origin capability fetches; `tools.invoke`
  *    rejects with code `'unavailable'`; `refresh()` reloads the page.
+ *  - `serve` — the page is a shareable mini-site served by the daemon's
+ *    app-serve head (`gezel app serve`). Nothing degrades: `tools.invoke`
+ *    and `data.*` travel as same-origin fetches against the head API under
+ *    the visitor's cookie; `data.watch` polls; `refresh()` reloads. The
+ *    page still never sees a credential.
  *  - `demo` — a raw file opened outside gezel entirely. The real shim is
  *    never present there; gilde ships a paste-in stub that defines
  *    `window.gezel` only when the real one is absent.
@@ -35,7 +40,7 @@ declare const GEZEL_PAGE_API_VERSION: 1;
  */
 type GezelPageReadSource = 'workspace' | 'artifacts';
 /** How the page is being viewed; see the module doc for what each mode degrades. */
-type GezelPageMode = 'embedded' | 'browser' | 'demo';
+type GezelPageMode = 'embedded' | 'browser' | 'serve' | 'demo';
 /** Error codes a rejected page-API call carries (`GezelPageError.code`). */
 type GezelPageErrorCode = 'not-allowed' | 'invalid-input' | 'script-error' | 'timeout' | 'unavailable' | 'rate-limited';
 /**

package/dist/{types-cYfcp6_8.d.ts → types-DCBb1goX.d.ts}

@@ -21,7 +21,7 @@
  * `gezel.http.authed` additionally needs a `credential:<name>` entry
  * (declared as a raw string in `requires`) naming each credential it uses.
  */
-type ScriptCapability = 'llm' | 'network' | 'workspace.read' | 'workspace.write' | 'artifacts.read' | 'artifacts.write' | 'documents.read' | 'documents.write' | 'tasks.read' | 'tasks.write' | 'memory.read' | 'memory.write';
+type ScriptCapability = 'llm' | 'network' | 'workspace.read' | 'workspace.write' | 'artifacts.read' | 'artifacts.write' | 'documents.read' | 'documents.write' | 'tasks.read' | 'tasks.write' | 'memory.read' | 'memory.write' | 'index.read' | 'index.refresh';
 /** A free-text string input field. */
 interface ScriptStringInput {
     type: 'string';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/gezel-sdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "SDK imported by scripts running in the Gezel sandbox. Exposes the `gezel` object and `defineScript` helper.",
   "license": "MIT",
   "keywords": [
@@ -59,7 +59,7 @@
     "!dist/**/*.map"
   ],
   "devDependencies": {
-    "@bendyline/gezel": "1.0.6",
+    "@bendyline/gezel": "1.0.7",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"