@evoclock/pi-agentic-driver 0.4.3

package/lib/adapters/diff-scope.mjs

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// diff-scope adapter — changed-range extraction for code-phage.
+//
+// Concept provenance: pi-simplify v0.2.3 (MIT, MattDevy/pi-extensions,
+// commit 8fcf9b1) changed-file and changed-line extraction, adapted and
+// extended: explicit added/deleted/renamed classification, both-side line
+// ranges from `git diff --unified=0`, bounded output, and no prompt-based
+// enforcement. This adapter performs read-only Git queries only; it never
+// mutates the repository or stages anything.
+import { spawnSync } from "node:child_process";
+
+const MAX_DIFF_BYTES = 2_000_000;
+const MAX_FILES = 512;
+const MAX_HUNKS_PER_FILE = 512;
+
+const GIT_ENV = { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+
+function git(root, args) {
+  const result = spawnSync("git", ["-C", root, ...args], {
+    encoding: "utf8",
+    maxBuffer: MAX_DIFF_BYTES,
+    env: GIT_ENV,
+  });
+  if (result.error || result.status !== 0) {
+    return { ok: false, stdout: "", stderr: result.stderr || String(result.error || "git failed") };
+  }
+  return { ok: true, stdout: result.stdout, stderr: result.stderr };
+}
+
+function parseNameStatus(stdout) {
+  // --name-status -M output: "XY\tpath" or "XY\told -> new".
+  const files = [];
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line) continue;
+    const parts = line.split("\t");
+    if (parts.length < 2) continue;
+    const status = parts[0];
+    const raw = parts.length > 2 ? parts.at(-1) : parts[1];
+    const oldPath = parts.length > 2 ? parts[1] : undefined;
+    files.push({
+      status: status.startsWith("R") ? "renamed" : status,
+      path: raw,
+      oldPath,
+    });
+  }
+  return files;
+}
+
+function parseRange(spec) {
+  // "start,count" | "start" ; treat "0,0" as absent (no lines on that side).
+  if (!spec) return null;
+  const [startText, countText] = spec.split(",");
+  const start = Number(startText);
+  const count = countText === undefined ? 1 : Number(countText);
+  if (!Number.isInteger(start) || !Number.isInteger(count) || count <= 0) return null;
+  return { start, end: start + count - 1 };
+}
+
+function parseHunks(stdout) {
+  // Map path -> { added: [ranges], removed: [ranges] } from -U0 output.
+  // Each hunk contributes its range once, not once per changed line.
+  const byFile = new Map();
+  let currentPath = undefined;
+  let current = undefined;
+  for (const line of stdout.split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      const match = line.match(/^diff --git (?:"?a\/(.+?)) (?:"?b\/(.+?)"?)$/);
+      currentPath = match ? match[2] : undefined;
+      current = undefined;
+      if (currentPath && !byFile.has(currentPath)) byFile.set(currentPath, { added: [], removed: [] });
+      continue;
+    }
+    const hunk = line.match(/^@@ -(\d+(?:,\d+)?) \+(\d+(?:,\d+)?) @@/);
+    if (hunk) {
+      if (!currentPath) continue;
+      const entry = byFile.get(currentPath);
+      if (!entry) continue;
+      const added = parseRange(hunk[2]);
+      const removed = parseRange(hunk[1]);
+      if (added && !entry.added.some((r) => r.start === added.start && r.end === added.end)) entry.added.push(added);
+      if (removed && !entry.removed.some((r) => r.start === removed.start && r.end === removed.end)) entry.removed.push(removed);
+      current = { added, removed };
+      continue;
+    }
+    if (!current || !currentPath) continue;
+  }
+  return byFile;
+}
+
+function capRanges(ranges, limitations, path, side) {
+  if (ranges.length > MAX_HUNKS_PER_FILE) {
+    limitations.push(`truncated ${side} ranges for ${path} at ${MAX_HUNKS_PER_FILE}`);
+    return ranges.slice(0, MAX_HUNKS_PER_FILE);
+  }
+  return ranges;
+}
+
+export function changedRanges(root, ref = "HEAD") {
+  const limitations = [];
+  const names = git(root, ["diff", "--name-status", "-M", ref]);
+  if (!names.ok) {
+    return { status: "git-unavailable", files: [], limitations: ["git diff --name-status was unavailable; no changed-file scope was inferred."], ref };
+  }
+  // `git diff` never reports untracked files; discover them separately.
+  const untracked = git(root, ["ls-files", "--others", "--exclude-standard"]);
+  const rawPaths = parseNameStatus(names.stdout).map((file) => ({ ...file, untracked: false }));
+  let untrackedPaths = [];
+  if (untracked.ok) {
+    untrackedPaths = untracked.stdout.split(/\r?\n/).filter(Boolean).map((path) => ({ status: "A", path, untracked: true }));
+  } else {
+    limitations.push("untracked-file discovery failed; untracked additions may be missing from the changed scope.");
+  }
+  const files = [...rawPaths, ...untrackedPaths];
+  const totalFiles = files.length;
+  const boundedFiles = files.slice(0, MAX_FILES);
+  if (totalFiles > MAX_FILES) limitations.push(`truncated changed files at ${MAX_FILES}; ${totalFiles - MAX_FILES} file(s) are outside the bounded scope.`);
+  const hunks = git(root, ["diff", "--unified=0", ref]);
+  if (!hunks.ok) limitations.push("hunk-range query failed; added/removed line ranges may be incomplete for modified files.");
+  const rangeMap = hunks.ok ? parseHunks(hunks.stdout) : new Map();
+  const result = [];
+  for (const file of boundedFiles) {
+    const ranges = rangeMap.get(file.path) || { added: [], removed: [] };
+    if (file.status === "A") {
+      result.push({ ...file, classification: "added-file", added: [], removed: [], wholeCurrentFile: true });
+    } else if (file.status === "D") {
+      result.push({ ...file, classification: "deleted-file", added: [], removed: [], wholeCurrentFile: false, deleted: true });
+    } else if (file.status === "renamed") {
+      result.push({
+        ...file,
+        classification: "renamed",
+        added: capRanges(ranges.added, limitations, file.path, "added"),
+        removed: capRanges(ranges.removed, limitations, file.path, "removed"),
+        wholeCurrentFile: false,
+      });
+    } else {
+      result.push({
+        ...file,
+        classification: "modified",
+        added: capRanges(ranges.added, limitations, file.path, "added"),
+        removed: capRanges(ranges.removed, limitations, file.path, "removed"),
+        wholeCurrentFile: false,
+      });
+    }
+  }
+  return { status: "observed", files: result, limitations, ref };
+}

package/lib/adapters/evidence.mjs

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// evidence adapter — content-bound source anchors for code-phage.
+//
+// Concept provenance: review-craft v0.7.1 (MIT, bigKING67/review-craft,
+// commit cfd74b9) content-bound source/span SHA-256 anchors, the
+// candidate → finding → decision separation, and advisory complexity
+// ceilings with human-owned decisions. Adapted, not copied: this adapter
+// is a pure function over in-memory source text; it creates no ledger,
+// no files, and no authority. Agentic Driver remains the canonical
+// evidence owner.
+import { createHash } from "node:crypto";
+
+// Advisory review ceilings per callable. They are diagnostic signals for
+// human review, never automatic rejection thresholds.
+export const ADVISORY_CEILINGS = Object.freeze({
+  cognitiveComplexity: 15,
+  cyclomaticComplexity: 10,
+  maxNesting: 4,
+});
+
+function sha256(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function sourceLines(source) {
+  return source.split(/\r?\n/);
+}
+
+// Build one content-bound anchor for a callable span. The span text is the
+// exact raw source lines [line, endLine]; the digest changes whenever the
+// span content changes.
+export function spanAnchor(source, callable) {
+  const lines = sourceLines(source);
+  const start = Math.max(1, Number(callable.line) || 1);
+  const end = Math.min(lines.length, Math.max(start, Number(callable.endLine) || start));
+  const spanText = lines.slice(start - 1, end).join("\n");
+  return {
+    line: start,
+    endLine: end,
+    lineCount: end - start + 1,
+    spanSha256: sha256(spanText),
+  };
+}
+
+// Build the full evidence record for one analyzed file: a source-level
+// digest plus per-callable span anchors. Deleted files have no current
+// source side; their evidence stays path-level only.
+export function buildEvidence(source, analysis) {
+  if (typeof source !== "string" || !analysis || analysis.status !== "parsed") {
+    return { status: "unavailable", sourceSha256: undefined, anchors: [] };
+  }
+  const byLine = new Map(
+    (analysis.callables || []).map((callable) => [Number(callable.line) || 0, callable]),
+  );
+  const anchors = [];
+  const lines = sourceLines(source);
+  // Walk callables in source order; nested callables share parent spans.
+  const ordered = [...(analysis.callables || [])].sort((a, b) => (Number(a.line) || 0) - (Number(b.line) || 0));
+  const covered = [];
+  for (const callable of ordered) {
+    const anchor = spanAnchor(source, callable);
+    covered.push({ start: anchor.line, end: anchor.endLine, name: callable.name });
+    anchors.push({
+      name: callable.name,
+      kind: callable.kind,
+      ...anchor,
+      cyclomaticComplexity: callable.cyclomaticComplexity,
+      cognitiveComplexity: callable.cognitiveComplexity,
+      overCeiling: {
+        cognitiveComplexity: (Number(callable.cognitiveComplexity) || 0) > ADVISORY_CEILINGS.cognitiveComplexity,
+        cyclomaticComplexity: (Number(callable.cyclomaticComplexity) || 0) > ADVISORY_CEILINGS.cyclomaticComplexity,
+        maxNesting: (Number(callable.maxNesting) || 0) > ADVISORY_CEILINGS.maxNesting,
+      },
+    });
+  }
+  return {
+    status: "anchored",
+    sourceSha256: sha256(source),
+    lineCount: lines.length,
+    anchors,
+    ceilings: ADVISORY_CEILINGS,
+  };
+}
+
+// Map a changeClassification onto an advisory candidate outcome.
+// This is a heuristic signal for human review; the decision owner is
+// always the human reviewer, and no outcome is applied automatically.
+// Outcome terms are this project's own vocabulary, adapted from the
+// review-craft evidence model (see README provenance).
+function suggestedOutcome(classification, anchor) {
+  if (anchor.overCeiling.cognitiveComplexity || anchor.overCeiling.cyclomaticComplexity) {
+    return {
+      outcome: "PROFILE",
+      rationale: "callable exceeds an advisory complexity ceiling; measure against the acceptance checks before deciding",
+    };
+  }
+  if (anchor.overCeiling.maxNesting) {
+    return {
+      outcome: "TIDY",
+      rationale: "nesting exceeds the advisory ceiling; consider flattening without behavior change",
+    };
+  }
+  if (classification === "removed-lines") {
+    return {
+      outcome: "HOLD",
+      rationale: "only removed lines touch this callable; confirm surrendered behavior before further change",
+    };
+  }
+  if (classification === "whole-file") {
+    return {
+      outcome: "DESCRIBE",
+      rationale: "new file-level unit; document intent and the deletion test before review closes",
+    };
+  }
+  return {
+    outcome: "RETAIN",
+    rationale: "changed lines stay within advisory limits; confirm the deletion test still holds",
+  };
+}
+
+// Candidate findings for one changed file. Candidates are not decisions:
+// review-craft's separation is preserved, and rejected candidates remain
+// visible to the human reviewer rather than disappearing.
+export function buildCandidates(path, changedFile, evidence) {
+  if (!evidence || evidence.status !== "anchored" || !changedFile) return [];
+  const classificationFor = (name) => {
+    if (changedFile.wholeCurrentFile) return "whole-file";
+    const touched = changedFile.touched;
+    if (!Array.isArray(touched)) return undefined;
+    const record = touched.find((item) => item.name === name);
+    return record?.changeClassification;
+  };
+  return evidence.anchors.map((anchor) => {
+    const classification = classificationFor(anchor.name) || "untouched";
+    const suggestion = suggestedOutcome(classification, anchor);
+    return {
+      path,
+      callable: anchor.name,
+      line: anchor.line,
+      endLine: anchor.endLine,
+      spanSha256: anchor.spanSha256,
+      changeClassification: classification,
+      suggestedOutcome: suggestion.outcome,
+      rationale: suggestion.rationale,
+      decisionOwner: "human",
+      advisoryOnly: true,
+    };
+  });
+}

package/lib/adapters/narrative.mjs

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// narrative adapter — structured, concern-grouped review narrative.
+//
+// Concept provenance: semantic-review v0.3.0 (MIT, mikker/semantic-review,
+// commit f77e5c8) groups review guidance as a short narrative with
+// schema-validated structured output, stable hunk references, and levels
+// from summary to full walkthrough. Adapted here without any model
+// backend or network: the narrative is derived deterministically from
+// code-phage results, grouped by concern rather than file order, and
+// every reference resolves to a review-feedback item or a content-bound
+// candidate span. The narrative is an isolated advisory artifact; it
+// never triggers edits, submissions, or remote calls.
+export const NARRATIVE_SCHEMA = "agentic-driver.code-phage-narrative.v1";
+
+const SECTION_TITLES = {
+  amend: "EDIT POINTS",
+  consult: "OPEN QUESTIONS",
+  removed: "SURRENDERED BEHAVIOR",
+  ceilings: "MEASUREMENT SIGNALS",
+};
+
+// Narrative summary wording uses this project's outcome vocabulary;
+// see the evidence adapter provenance in README.md.
+
+const VALID_DIGEST = /^[0-9a-f]{64}$/;
+
+function candidateRef(candidate) {
+  if (!candidate || typeof candidate.spanSha256 !== "string" || !VALID_DIGEST.test(candidate.spanSha256)) return null;
+  return `CAND:${candidate.path}#${candidate.callable}#${candidate.spanSha256.slice(0, 12)}`;
+}
+
+function buildSections(result) {
+  const sections = [];
+  const reviewFeedback = Array.isArray(result.reviewFeedback) ? result.reviewFeedback : [];
+  const amendItems = reviewFeedback.filter((item) => item.intent === "AMEND");
+  if (amendItems.length) {
+    sections.push({
+      id: "amend",
+      title: SECTION_TITLES.amend,
+      items: amendItems.map((item) => ({
+        ref: `RF:${item.id}`,
+        path: item.path,
+        callable: item.callable,
+        lineStart: item.lineStart,
+        lineEnd: item.lineEnd,
+        message: item.message,
+      })),
+    });
+  }
+  const consultItems = reviewFeedback.filter((item) => item.intent === "CONSULT");
+  if (consultItems.length) {
+    sections.push({
+      id: "consult",
+      title: SECTION_TITLES.consult,
+      items: consultItems.map((item) => ({
+        ref: `RF:${item.id}`,
+        path: item.path,
+        callable: item.callable,
+        lineStart: item.lineStart,
+        lineEnd: item.lineEnd,
+        message: item.message,
+      })),
+    });
+  }
+  const deletedPaths = result.changedScope?.deletedPaths || [];
+  if (deletedPaths.length) {
+    sections.push({
+      id: "removed",
+      title: SECTION_TITLES.removed,
+      items: deletedPaths.map((path) => ({
+        ref: `DEL:${path}`,
+        path,
+        callable: undefined,
+        message: `Confirm the consumer map and surrendered behavior for the deleted unit ${path} before review closes.`,
+      })),
+    });
+  }
+  const overCeiling = [];
+  for (const entry of result.changedCallables || []) {
+    for (const anchor of entry.evidence?.anchors || []) {
+      if (!anchor || typeof anchor.spanSha256 !== "string" || !VALID_DIGEST.test(anchor.spanSha256)) continue;
+      if (Object.values(anchor.overCeiling || {}).some(Boolean)) {
+        overCeiling.push({
+          ref: `CAND:${entry.path}#${anchor.name}#${anchor.spanSha256.slice(0, 12)}`,
+          path: entry.path,
+          callable: anchor.name,
+          lineStart: anchor.line,
+          lineEnd: anchor.endLine,
+          message: `${anchor.name} exceeds an advisory ceiling; measure against the acceptance checks.`,
+        });
+      }
+    }
+  }
+  if (overCeiling.length) {
+    sections.push({
+      id: "ceilings",
+      title: SECTION_TITLES.ceilings,
+      items: overCeiling,
+    });
+  }
+  return sections;
+}
+
+// Validate one narrative value against the schema. Fails closed: any
+// missing field, unknown level, or unresolvable reference returns errors
+// instead of a pass.
+export function validateNarrative(narrative) {
+  const errors = [];
+  if (!narrative || typeof narrative !== "object") return { valid: false, errors: ["narrative must be an object"] };
+  if (narrative.schema !== NARRATIVE_SCHEMA) errors.push("schema mismatch");
+  if (!["summary", "walkthrough"].includes(narrative.level)) errors.push("level must be summary or walkthrough");
+  if (typeof narrative.summary !== "string" || !narrative.summary.trim()) errors.push("summary must be non-empty text");
+  if (!Array.isArray(narrative.sections)) errors.push("sections must be an array");
+  const VALID_DIGEST = /^[0-9a-f]{64}$/;
+  const knownRefs = new Set(Object.keys(narrative.referenceIndex || {}));
+  for (const [ref, digest] of Object.entries(narrative.referenceIndex || {})) {
+    if (digest !== null && (typeof digest !== "string" || !VALID_DIGEST.test(digest))) {
+      errors.push(`reference ${ref} is not bound to a valid span digest`);
+    }
+  }
+  for (const section of narrative.sections || []) {
+    if (!section.id || !section.title || !Array.isArray(section.items)) {
+      errors.push(`section ${section.id || "<missing-id>"} is malformed`);
+      continue;
+    }
+    for (const item of section.items) {
+      if (!item.ref || !item.message) errors.push(`item in ${section.id} lacks ref or message`);
+      if (!knownRefs.has(item.ref)) errors.push(`unresolvable reference ${item.ref}`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// Build the narrative plus its reference index. The reference index maps
+// every stable ref to its span digest so narrative guidance stays
+// content-bound across session restarts and compaction.
+export function buildNarrative(result, level = "walkthrough") {
+  if (!result || result.schema !== "agentic-driver.code-phage.v1") {
+    return { schema: NARRATIVE_SCHEMA, level, valid: false, errors: ["input is not a code-phage result"], sections: [], referenceIndex: {} };
+  }
+  const sections = buildSections(result);
+  const referenceIndex = {};
+  for (const item of result.reviewFeedback || []) referenceIndex[`RF:${item.id}`] = item.spanSha256;
+  for (const candidate of result.candidates || []) {
+    const ref = candidateRef(candidate);
+    if (ref) referenceIndex[ref] = candidate.spanSha256;
+  }
+  for (const path of result.changedScope?.deletedPaths || []) referenceIndex[`DEL:${path}`] = null;
+  const counts = result.summary?.reviewFeedback || {};
+  const summary = [
+    `${result.changedScope?.changedFiles ?? 0} changed file(s) reviewed;`,
+    `${result.changedScope?.touchedCallables ?? 0} callable(s) touched;`,
+    `${counts.AMEND || 0} AMEND point(s), ${counts.CONSULT || 0} CONSULT question(s);`,
+    `${result.summary?.deletedFiles ?? 0} deleted unit(s).`,
+    "All findings are advisory; decisions remain with the human reviewer.",
+  ].join(" ");
+  const narrative = {
+    schema: NARRATIVE_SCHEMA,
+    level,
+    isolated: true,
+    modelBackend: "none",
+    networkAccess: false,
+    summary,
+    sections,
+    referenceIndex,
+  };
+  const validation = validateNarrative(narrative);
+  return { ...narrative, valid: validation.valid, errors: validation.errors };
+}

package/lib/adapters/review-feedback.mjs

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// review-feedback adapter — two-intent review items for code-phage.
+//
+// Concept provenance: pi-slopchop v0.10.1 (MIT, robzolkos/pi-slopchop,
+// commit f2cae88) separates edit-intent comments from prose-intent
+// comments so reviewers never conflate "change this" with "explain
+// this". Adapted here under different terms: AMEND marks a concrete
+// edit point a human may choose to act on; CONSULT marks a question
+// that must be answered in prose and never becomes a code change.
+// Items are advisory, content-bound, and rendered for human submission;
+// no intent is ever applied autonomously and no Pi editor or TUI is
+// touched.
+import { createHash } from "node:crypto";
+
+export const REVIEW_INTENT_VOCABULARY = Object.freeze(["AMEND", "CONSULT"]);
+
+// Candidate outcomes that point at a concrete edit are AMEND material;
+// everything else is a prose question. Outcome terms use this project's
+// own vocabulary (see evidence adapter provenance).
+const AMEND_OUTCOMES = new Set(["TIDY", "PROFILE"]);
+const CONSULT_OUTCOMES = new Set(["RETAIN", "HOLD", "DESCRIBE"]);
+
+function shortId(path, callable, spanSha256) {
+  return createHash("sha256").update(`${path}#${callable}#${spanSha256}`, "utf8").digest("hex").slice(0, 12);
+}
+
+function amendMessage(candidate) {
+  if (candidate.suggestedOutcome === "PROFILE") {
+    return `Measure ${candidate.callable} against the acceptance checks; it exceeds an advisory complexity ceiling.`;
+  }
+  return `Consider flattening ${candidate.callable}; nesting exceeds the advisory ceiling without behavior change.`;
+}
+
+function consultMessage(candidate) {
+  switch (candidate.suggestedOutcome) {
+    case "HOLD":
+      return `Which accepted behavior does ${candidate.callable} still owe after its removed lines? Confirm surrendered behavior before further change.`;
+    case "DESCRIBE":
+      return `Document the intent and deletion test for ${candidate.callable} before this review closes.`;
+    default:
+      return `Confirm the deletion test still holds for ${candidate.callable} after these changes.`;
+  }
+}
+
+const VALID_DIGEST = /^[0-9a-f]{64}$/;
+
+// Build stable review items from evidence candidates. Candidates must
+// carry a valid 64-hex content-bound span digest; malformed candidates
+// are skipped so they can never silently shape an ID.
+export function buildReviewFeedback(candidates) {
+  if (!Array.isArray(candidates)) return [];
+  const items = [];
+  for (const candidate of candidates) {
+    if (!candidate || candidate.decisionOwner !== "human" || candidate.advisoryOnly !== true) continue;
+    if (typeof candidate.spanSha256 !== "string" || !VALID_DIGEST.test(candidate.spanSha256)) continue;
+    const isAmend = AMEND_OUTCOMES.has(candidate.suggestedOutcome);
+    const isConsult = CONSULT_OUTCOMES.has(candidate.suggestedOutcome);
+    if (!isAmend && !isConsult) continue;
+    items.push({
+      id: shortId(candidate.path, candidate.callable, candidate.spanSha256),
+      intent: isAmend ? "AMEND" : "CONSULT",
+      path: candidate.path,
+      callable: candidate.callable,
+      targetSide: candidate.changeClassification === "removed-lines" ? "old-side" : "new-side",
+      lineStart: candidate.line,
+      lineEnd: candidate.endLine,
+      spanSha256: candidate.spanSha256,
+      suggestedOutcome: candidate.suggestedOutcome,
+      message: isAmend ? amendMessage(candidate) : consultMessage(candidate),
+      requiresHumanSubmission: true,
+      autonomousEditAllowed: false,
+    });
+  }
+  return items.sort((a, b) => a.path.localeCompare(b.path) || a.lineStart - b.lineStart);
+}