karajan-code 4.70.4 → 5.0.0

package/src/review/third-party-review.js

@@ -14,8 +14,14 @@ import { isGenerated } from "./loc-budget.js";
 import { prSecurityChecks } from "./pr-security.js";
 import { sonarCheck } from "./pr-sonar.js";
 import { batchDiff, splitByFile } from "./diff-batches.js";
+import { ceilingOf, isTooLarge, measureCode, tooLargeSummary } from "./third-party-size.js";
 import { lensTask } from "./review-lens.js";
-import { thirdPartyTask } from "./untrusted-context.js";
+import { thirdPartyTask, THIRD_PARTY_INSTRUCTION } from "./untrusted-context.js";
+import { baseOf, readRepoDocs, repoDocsTask } from "./repo-docs.js";
+import { detectStack } from "./repo-stack.js";
+import { thirdPartySkills } from "./third-party-skills.js";
+import { hasAtrilStore } from "../skills/atril-skills.js";
+import { MAX_SKILLS } from "../skills/role-skills.js";
 import { readTaskFile } from "../utils/task-file.js";
 import { DIFF_CLIP_CHARS } from "../prompts/diff-clip.js";
 import { assertCrossFamily, verifyFindings } from "./run-verifier.js";
@@ -37,13 +43,13 @@ const finding = (i) => ({
 });
 
 /** The review as data: verdict, findings, suggestions, security checks and, apart, the house requirements. */
-export async function thirdPartyReview({ range, config, projectDir, logger, task = null, gitDiff = gitDiffOf, run = runOneShotReview, requirements = prRequirementChecks, security = prSecurityChecks, sonar = sonarCheck, limit = DIFF_CLIP_CHARS, maxBatches = MAX_REVIEW_BATCHES, sizeLimit = null, verifier = null, verifierModel = null, verify = verifyFindings, reviewers = null }) {
-  // KJC-TSK-1195: a verifier of the reviewer's own family is refused before any token is spent.
-  const reviewerRole = resolveRole(config, "reviewer");
-  if (verifier) assertCrossFamily({ reviewer: reviewerRole.provider, reviewerModel: reviewerRole.model, verifier, verifierModel, logger });
-  // KJC-TSK-1248 (#2623): two reviewers of the same family would share their blind spots.
-  if (reviewers) assertCrossFamily({ reviewer: reviewers[0].provider, reviewerModel: reviewers[0].model, verifier: reviewers[1].provider, verifierModel: reviewers[1].model, logger, flag: "--reviewers" });
+export async function thirdPartyReview({ range, config, projectDir, logger, task = null, gitDiff = gitDiffOf, run = runOneShotReview, requirements = prRequirementChecks, security = prSecurityChecks, sonar = sonarCheck, limit = DIFF_CLIP_CHARS, maxBatches = MAX_REVIEW_BATCHES, sizeLimit = null, verifier = null, verifierModel = null, verify = verifyFindings, reviewers = null, repoDocs = readRepoDocs, hasStore = hasAtrilStore, stackOf = detectStack, skillsFor = thirdPartySkills }) {
+  const reviewerRole = assertPanel({ config, verifier, verifierModel, reviewers, logger });
   const diff = await gitDiff(projectDir, range);
+  const budget = () => sizeLimit ?? prSizeLimit({ projectDir, config }).limit;
+  // KJC-TSK-1356 (#3027): past the ceiling, no reviewer runs: the size, the ceiling and the split.
+  const tooLarge = sizeVerdict({ diff, config, range, budget });
+  if (tooLarge) return tooLarge;
   // KJC-TSK-1076/1077: the PR's requirements and its security, with no tokens; they never stop the review.
   // KJC-BUG-0379 (#2263): the house requirements (size, commits, attribution, tests) travel apart:
   // on another repo with other conventions they must not read as findings next to security.
@@ -54,34 +60,87 @@ export async function thirdPartyReview({ range, config, projectDir, logger, task
   const provider = reviewerRole.provider || null;
   const { batches, coverage } = batchDiff(diff, { limit, maxBatches });
   if (coverage.files.total === 0) throw new Error(`nothing to review — ${range} has no file changes`);
+  // KJC-TSK-1266 (#2753): the repo's own docs at the base, fenced as untrusted, and named in the output.
+  const { repoContext, reviewTask } = await withRepoDocs({ repoDocs, projectDir, range, task, logger });
+  // KJC-TSK-1272 (#2753): a repo with no atril store gets skills for its stack; the temporary store goes after the review.
+  const stackSkills = await gatherStackSkills({ projectDir, range, config, logger, hasStore, stackOf, skillsFor });
+  repoContext.skills = stackSkills.report;
   const reviewWith = async (who, cfg) => {
     const recs = [];
-    for (const batch of batches) recs.push(await run({ diff: batch.text, task, config: cfg, logger, projectDir, reviewerOverride: who, persist: false }));
+    for (const batch of batches) recs.push(await run({ diff: batch.text, task: reviewTask, config: cfg, logger, projectDir, reviewerOverride: who, persist: false, skills: stackSkills.block }));
     return recs;
   };
-  if (reviewers) {
-    const dual = await dualReview({ reviewers, reviewWith, verify, diff, coverage, config, logger });
-    return { mode: "third-party", range, ...dual, checks, policyChecks, advice: adviceFor(diff, sizeLimit ?? prSizeLimit({ projectDir, config }).limit) };
+  const advice = () => adviceFor(diff, budget());
+  try {
+    const review = reviewers
+      ? await dualReview({ reviewers, reviewWith, verify, diff, coverage, config, logger })
+      : await singleReview({ provider, reviewWith, verifier, verifierModel, verify, diff, coverage, config, logger });
+    return { mode: "third-party", range, ...review, checks, policyChecks, repoContext, advice: advice() };
+  } finally {
+    stackSkills.cleanup();
   }
+}
+
+// Panel checks before any token is spent; returns the configured reviewer role.
+function assertPanel({ config, verifier, verifierModel, reviewers, logger }) {
+  // KJC-TSK-1195: a verifier of the reviewer's own family is refused before any token is spent.
+  const reviewerRole = resolveRole(config, "reviewer");
+  if (verifier) assertCrossFamily({ reviewer: reviewerRole.provider, reviewerModel: reviewerRole.model, verifier, verifierModel, logger });
+  // KJC-TSK-1248 (#2623): two reviewers of the same family would share their blind spots.
+  if (reviewers) assertCrossFamily({ reviewer: reviewers[0].provider, reviewerModel: reviewers[0].model, verifier: reviewers[1].provider, verifierModel: reviewers[1].model, logger, flag: "--reviewers" });
+  return reviewerRole;
+}
+
+// KJC-TSK-1266 (#2753): the repo's own docs at the base, fenced as untrusted, and named in the output.
+async function withRepoDocs({ repoDocs, projectDir, range, task, logger }) {
+  const docs = await repoDocs({ projectDir, base: baseOf(range) });
+  if (docs.error) logger.warn?.(docs.error);
+  return {
+    repoContext: { files: docs.files, omitted: docs.omitted, ...(docs.error && { error: docs.error }) },
+    reviewTask: docs.text ? repoDocsTask(task ?? THIRD_PARTY_INSTRUCTION, docs) : task,
+  };
+}
+
+async function singleReview({ provider, reviewWith, verifier, verifierModel, verify, diff, coverage, config, logger }) {
   const records = await reviewWith(provider, config);
   const findings = records.flatMap((r) => (r.issues ?? []).map(finding));
   // KJC-TSK-1195 (#2369): with a verifier, the findings are the verified ones and the block says what changed.
   const verified = verifier ? await verify({ findings, diff, verifier, model: verifierModel, config, logger }) : null;
   return {
-    mode: "third-party",
-    range,
     reviewer: records[0]?.reviewer ?? provider,
     verdict: verdictOf(records, coverage),
     coverage,
     findings: verified ? verified.findings : findings,
     ...(verified && { verification: verified.verification }),
     suggestions: records.flatMap((r) => r.suggestions ?? []),
-    checks,
-    policyChecks,
-    advice: adviceFor(diff, sizeLimit ?? prSizeLimit({ projectDir, config }).limit),
   };
 }
 
+/**
+ * KJC-TSK-1272 (#2753): the skills for the reviewed repo's stack, the prompt block that carries
+ * them, what to report and how to remove the temporary store. A repo with its own atril store
+ * keeps the usual path; a failure is reported and the review goes on without them.
+ */
+async function gatherStackSkills({ projectDir, range, config, logger, hasStore, stackOf, skillsFor }) {
+  const none = { block: null, cleanup: () => {} };
+  if (projectDir && hasStore(projectDir)) return { ...none, report: { source: "the reviewed repo's atril store" } };
+  try {
+    if (!projectDir) throw new Error("no project directory to read the stack from");
+    const stack = await stackOf({ projectDir, base: baseOf(range) });
+    const max = config?.skills?.max_per_role ?? MAX_SKILLS;
+    const found = await skillsFor({ stack, max, catalogs: config?.review?.third_party?.catalogs ?? [] });
+    return {
+      block: found.skills.length ? { skills: found.skills, dropped: found.dropped, limit: max } : null,
+      report: { stack, used: found.skills.map((s) => s.name), installed: found.installed, dropped: found.dropped, ...(found.reason && { reason: found.reason }) },
+      cleanup: found.cleanup,
+    };
+  } catch (e) {
+    const error = `the stack's skills could not be gathered: ${e.message}`;
+    logger.warn?.(error);
+    return { ...none, report: { error } };
+  }
+}
+
 /**
  * KJC-TSK-1248 (#2623): both reviewers review the whole range on their own, in parallel, each
  * with its model; each one's findings are verified by the other family; one reconciled result.
@@ -99,6 +158,21 @@ async function dualReview({ reviewers, reviewWith, verify, diff, coverage, confi
   return { reviewer: reviewers.map((r) => r.provider).join("+"), ...reconciled, suggestions: records.flat().flatMap((r) => r.suggestions ?? []) };
 }
 
+/** KJC-TSK-1356 (#3027): the too_large result, or null when the PR is within the ceiling. */
+function sizeVerdict({ diff, config, range, budget }) {
+  const ceiling = ceilingOf(config);
+  const files = splitByFile(diff);
+  const size = measureCode(files);
+  if (!isTooLarge(size, ceiling)) return null;
+  const limit = budget();
+  return {
+    mode: "third-party", range,
+    verdict: { status: "too_large", approved: false, summary: tooLargeSummary(size, ceiling, limit) },
+    size, threshold: ceiling, findings: [], suggestions: [],
+    advice: { split: splitAdvice(files.filter((f) => !isGenerated(f.file)), { limit }) },
+  };
+}
+
 /** KJC-TSK-1101: over the size budget, how to split the PR; advice only, never a finding. */
 function adviceFor(diff, budget) {
   const files = splitByFile(diff).filter((f) => !isGenerated(f.file));

package/src/review/third-party-size.js

@@ -0,0 +1,43 @@
+// KJC-TSK-1356 (#3027): how big a third-party PR is, in CODE, and whether it is past the exceptional
+// ceiling past which kj does not review it. Karajan's norm is atomic PRs (the split advice aims at
+// the repo's PR budget); the ceiling is the exception, not the target.
+import { isGenerated } from "./loc-budget.js";
+
+export const MAX_CODE_LINES = 800;
+export const MAX_CODE_FILES = 20;
+
+// Markdown, docs and JSON never count, nor anything generated (lockfiles, build output...).
+const NOT_CODE = /\.(md|mdx|markdown|txt|rst|adoc|json|jsonc)$/i;
+
+/** @param {string} file */
+export const countsAsCode = (file) => Boolean(file) && !isGenerated(file) && !NOT_CODE.test(file);
+
+const positive = (value, key) => {
+  if (value === undefined) return null;
+  if (!Number.isInteger(value) || value <= 0) throw new Error(`review.third_party.${key} must be a positive integer, got ${JSON.stringify(value)}`);
+  return value;
+};
+
+/** The ceiling: review.third_party.max_lines / max_files, or 800 lines / 20 files. */
+export function ceilingOf(config) {
+  const t = config?.review?.third_party ?? {};
+  return {
+    maxLines: positive(t.max_lines, "max_lines") ?? MAX_CODE_LINES,
+    maxFiles: positive(t.max_files, "max_files") ?? MAX_CODE_FILES,
+  };
+}
+
+/** @param {Array<{file: string, changed: number}>} files from splitByFile */
+export function measureCode(files) {
+  const code = files.filter((f) => countsAsCode(f.file));
+  return { codeLines: code.reduce((n, f) => n + f.changed, 0), codeFiles: code.length, otherFiles: files.length - code.length };
+}
+
+export const isTooLarge = (size, ceiling) => size.codeLines > ceiling.maxLines || size.codeFiles > ceiling.maxFiles;
+
+/** What the consumer posts instead of a review. */
+export function tooLargeSummary(size, ceiling, budget) {
+  return `Too large to review well: ${size.codeLines} lines of code in ${size.codeFiles} files `
+    + `(ceiling ${ceiling.maxLines} lines / ${ceiling.maxFiles} files, an exception, never the norm). `
+    + `Karajan recommends atomic PRs of about ${budget} lines of code, one purpose each: split it as advised.`;
+}

package/src/review/third-party-skills.js

@@ -0,0 +1,54 @@
+/**
+ * KJC-TSK-1271 (#2753): a third-party repo has no atril store, so its reviewer
+ * gets skills the way a store-backed project does, through atril's public API,
+ * from a temporary store outside the reviewed repo: atril resolves the reviewer's
+ * skill for the detected stack (the reviewer's own store, ~/.atril, counts), and
+ * when nothing installed fits, the best catalog skill is installed in the
+ * temporary store first. The maintainer's choice (2026-10-29): catalogs too,
+ * installed in a temporary folder. Nothing is written in the reviewed repo.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { catalogSync, installFromCatalog, resolve, search } from "@karajan-family/atril";
+import { atrilRoleSkills } from "../skills/atril-skills.js";
+
+const ROOT = ".atril";
+const defaultAtril = { resolve, search, installFromCatalog, catalogSync };
+
+/**
+ * @param {{ stack: {languages: string[], frameworks: string[]}, max: number, catalogs?: string[], atril?: typeof defaultAtril }} opts
+ *   catalogs: absolute paths of catalog folders or source files, as in atril.json
+ * @returns {Promise<{skills: object[], others: object[], dropped: string[], installed: string[], reason?: string, cleanup: () => void}>}
+ *   cleanup() removes the temporary store once the review has read the skills
+ */
+export async function thirdPartySkills({ stack, max, catalogs = [], atril = defaultAtril }) {
+  const relative = catalogs.find((ref) => !isAbsolute(ref));
+  if (relative) throw new Error(`catalog "${relative}" must be an absolute path: it would resolve against a temporary folder`);
+  const terms = [...stack.frameworks, ...stack.languages];
+  if (terms.length === 0) return { skills: [], others: [], dropped: [], installed: [], reason: "no stack detected in the reviewed repo", cleanup: () => {} };
+  const dir = mkdtempSync(join(tmpdir(), "kj-3p-skills-"));
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  try {
+    const opts = { projectDir: dir, root: ROOT };
+    mkdirSync(join(dir, ROOT), { recursive: true });
+    writeFileSync(join(dir, ROOT, "atril.json"), `${JSON.stringify({ catalogs })}\n`);
+    if (catalogs.length) atril.catalogSync(opts);
+    const task = `${terms.join(" ")} code review`;
+    const resolveSkills = () => atrilRoleSkills({ role: "reviewer", task, projectDir: dir, root: ROOT, max, resolveFn: atril.resolve });
+    let found = resolveSkills();
+    const installed = [];
+    if (found.skills.length === 0) {
+      const pick = atril.search(task, { ...opts, kind: "skill", plugins: false }).find((hit) => !hit.installed);
+      if (pick) {
+        atril.installFromCatalog(`skill:${pick.name}`, opts);
+        installed.push(pick.name);
+        found = resolveSkills();
+      }
+    }
+    return { ...found, installed, cleanup };
+  } catch (e) {
+    cleanup();
+    throw e;
+  }
+}

package/src/review/verify-pr.js

@@ -10,7 +10,7 @@ import { diffHash } from "./verdict-store.js";
 import { MARKER, TRUSTED } from "./publish-pr.js";
 import { isCleanMerge } from "./clean-merge.js";
 import { verifiedSupervisorFiles } from "../policy/supervisor-verify.js";
-import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
+import { isSealCommit } from "./seal-commit.js";
 
 // The marker of a kj review for any head: what MARKER writes up to the head itself.
 const MARKER_PREFIX = MARKER("\0").split("\0")[0];
@@ -39,29 +39,6 @@ async function hashesOf(projectDir, sha, run) {
   return hashes;
 }
 
-// KJC-BUG-0388: kj harden --commit is the human's act, signed from the phone, and no AI
-// reviews it. The proof is the signature, never the message: a commit that only touches
-// files the roster-signed seal vouches for at the head is that act.
-async function isSealCommit(projectDir, sha, run, sealed) {
-  if (sealed.signed !== true) return false;
-  const res = await run("git", ["-C", projectDir, "diff", "--name-only", `${sha}^`, sha]);
-  if (res.exitCode !== 0) throw new Error(`git diff --name-only ${sha.slice(0, 7)} failed: ${(res.stderr || "").trim()}`);
-  const files = (res.stdout || "").split("\n").filter(Boolean);
-  // KJC-BUG-0438: the seal act writes the signed provenance; a commit without it only touched files.
-  if (!files.includes(PROVENANCE_FILE)) return false;
-  if (!files.every((f) => sealed.files.has(f) || (f === PROVENANCE_FILE && sealed.complete === true))) return false;
-  // What the commit leaves is byte for byte what the signed seal vouches for at the head: a
-  // precursor whose provenance or hooks a later commit replaced is not the seal act.
-  for (const f of files) if ((await blobAt(projectDir, sha, f, run)) !== (await blobAt(projectDir, "HEAD", f, run))) return false;
-  return true;
-}
-
-/** The blob id of a file at a revision, or null when the file is absent there. */
-async function blobAt(projectDir, rev, file, run) {
-  const res = await run("git", ["-C", projectDir, "rev-parse", "--verify", "--quiet", `${rev}:${file}`]);
-  return res.exitCode === 0 ? String(res.stdout || "").trim() : null;
-}
-
 /**
  * @returns {Promise<{ok: boolean, commits: number, problems: string[], sealCommits?: string[]}>}
  */

package/src/roles/audit-role.js

@@ -13,6 +13,7 @@ import { collectWebPerfInput } from "../audit/webperf-input.js";
 import { collectOsvFindings } from "../audit/osv-findings.js";
 import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectInfraFindings } from "../audit/infra-findings.js";
+import { collectNpmSignatures } from "../audit/npm-signatures.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
@@ -38,6 +39,86 @@ function buildSummary(parsed) {
   return `Overall health: ${summary.overallHealth}. ${summary.totalFindings} findings (${findingsStr})`;
 }
 
+/** A deterministic collector's result, or null when it fails: every section is best-effort. */
+async function bestEffort(collect) {
+  try { return await collect(); } catch { return null; }
+}
+
+/** Basal cost and its growth against the last audit; a failure on the way leaves what was measured. */
+async function basalWithGrowth(projectDir) {
+  let basalCost = null;
+  let growthDelta = null;
+  try {
+    basalCost = await measureBasalCost(projectDir);
+    const previous = await loadPreviousAudit(projectDir);
+    growthDelta = computeGrowthDelta(basalCost, previous);
+  } catch { /* basal cost is best-effort */ }
+  return { basalCost, growthDelta };
+}
+
+/**
+ * Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
+ * package.json. Best-effort: any failure returns available:false and
+ * the audit continues without the section.
+ * AC8 (KJC-TSK-0794): the report leads with the derivative — hand the
+ * block its previous measurement, if one was ever recorded.
+ */
+async function deadExportsWithPrevious(projectDir, stack, config, logger) {
+  const deadExports = await collectDeadExports(projectDir, stack, config, logger);
+  if (deadExports?.available) {
+    try {
+      const prev = await loadPreviousAudit(projectDir);
+      deadExports.previous = prev?.knipDeadExports ? { ...prev.knipDeadExports, timestamp: prev.timestamp || null } : null;
+    } catch { /* the findings stand without their previous measurement */ }
+  }
+  return deadExports;
+}
+
+/**
+ * STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
+ * at, so the Steward can age it — GREBLA went 79 days with "never".
+ */
+function recordSecurityAudit(projectDir, securityOnly) {
+  try {
+    mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
+    writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
+  } catch { /* recording is best-effort — the audit itself already ran */ }
+}
+
+/** The LLM phase's input, from a task string or the options object. */
+function auditInput(input, fallbackTask) {
+  if (typeof input === "string") return { task: input, onOutput: null, dimensions: null, context: null };
+  const rawDimensions = input?.dimensions || null;
+  return {
+    task: input?.task || fallbackTask,
+    onOutput: input?.onOutput || null,
+    dimensions: typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions,
+    context: input?.context || null,
+  };
+}
+
+const ifAvailable = (section) => (section?.available ? section : undefined);
+
+/** The structured result: the parsed audit plus every deterministic section that ran. */
+function structuredResult(parsed, ctx, provider) {
+  const { basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, envKeys } = ctx;
+  return {
+    summary: parsed.summary, dimensions: parsed.dimensions,
+    topRecommendations: parsed.topRecommendations,
+    textSummary: parsed.textSummary || undefined,
+    basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
+    stack: stack || undefined,
+    sonarFindings: ifAvailable(sonarFindings),
+    webperf: ifAvailable(webperf),
+    osvFindings: ifAvailable(osvFindings),
+    semgrepFindings: ifAvailable(semgrepFindings),
+    circularDeps: ifAvailable(circularDeps),
+    deadExports: ifAvailable(deadExports),
+    envKeys: ifAvailable(envKeys),
+    provider,
+  };
+}
+
 export class AuditRole extends AgentRole {
   constructor(opts) {
     super({ ...opts, name: "audit" });
@@ -56,123 +137,47 @@ export class AuditRole extends AgentRole {
    *   execute() would gather internally)
    */
   async collectDeterministic(input) {
+    const opts = (typeof input === "object" && input) || {};
     // KJC-TSK-0695: securityOnly = the focused pass an agent self-invokes
     // when a task touches sensitive surface. Only the security collectors
     // run (sonar, osv, semgrep, injection) — zero tokens, fast.
-    const securityOnly = typeof input === "object" ? Boolean(input?.securityOnly) : false;
-    const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
-    const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
-    const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
-    const noMadge = (typeof input === "object" ? Boolean(input?.noMadge) : false) || securityOnly;
-    const noKnip = (typeof input === "object" ? Boolean(input?.noKnip) : false) || securityOnly;
-    const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
-    const noInfraScan = typeof input === "object" ? Boolean(input?.noInfraScan) : false;
-    const noAiSlop = (typeof input === "object" ? Boolean(input?.noAiSlop) : false) || securityOnly;
+    const securityOnly = Boolean(opts.securityOnly);
+    const skip = (flag) => Boolean(opts[flag]);
     const projectDir = this.config?.projectDir || process.cwd();
-    let basalCost = null;
-    let growthDelta = null;
-    let stack = null;
-    let sonarFindings = null;
-    let webperf = null;
-    let osvFindings = null;
-    let semgrepFindings = null;
-    let circularDeps = null;
-    let deadExports = null;
-    let injectionFindings = null;
-    let infraFindings = null;
-    let aiSlop = null;
-    let envKeys = null;
-    if (!securityOnly) {
-      try {
-        basalCost = await measureBasalCost(projectDir);
-        const previous = await loadPreviousAudit(projectDir);
-        growthDelta = computeGrowthDelta(basalCost, previous);
-      } catch { /* basal cost is best-effort */ }
-    }
-    try {
-      stack = await detectProjectStack(projectDir);
-    } catch { /* stack detect is best-effort */ }
-    if (!noSonar) {
-      try {
-        sonarFindings = await collectSonarFindings(this.config, this.logger);
-      } catch { /* sonar fetch is best-effort */ }
-    }
-    if (!securityOnly) {
-      try {
-        webperf = collectWebPerfInput(stack, this.config);
-      } catch { /* webperf input is best-effort */ }
-    }
+    const { config, logger } = this;
+    // KJC-TSK-1257: every collector is best-effort — a failure leaves its section out (null).
+    const { basalCost, growthDelta } = securityOnly ? { basalCost: null, growthDelta: null } : await basalWithGrowth(projectDir);
+    const stack = await bestEffort(() => detectProjectStack(projectDir));
+    const sonarFindings = skip("noSonar") ? null : await bestEffort(() => collectSonarFindings(config, logger));
+    const webperf = securityOnly ? null : await bestEffort(() => collectWebPerfInput(stack, config));
     // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
     // osv-scanner binary returns available:false and the audit
     // continues without the section.
-    if (!noOsv) {
-      try {
-        osvFindings = await collectOsvFindings(projectDir, this.logger);
-      } catch { /* osv-scanner is best-effort */ }
-    }
+    const osvFindings = skip("noOsv") ? null : await bestEffort(() => collectOsvFindings(projectDir, logger));
     // Semgrep SAST — KJC-TSK-0366. Best-effort: missing semgrep binary
     // returns available:false and the audit continues without the section.
-    if (!noSemgrep) {
-      try {
-        semgrepFindings = await collectSemgrepFindings(projectDir, this.logger);
-      } catch { /* semgrep is best-effort */ }
-    }
+    const semgrepFindings = skip("noSemgrep") ? null : await bestEffort(() => collectSemgrepFindings(projectDir, logger));
     // Madge circular-import deps — KJC-TSK v2.17. Stack-aware: skipped for
     // non-JS/TS projects. Best-effort: any failure returns available:false
     // and the audit continues without the section.
-    if (!noMadge) {
-      try {
-        circularDeps = await collectCircularDeps(projectDir, stack, this.config, this.logger);
-      } catch { /* madge is best-effort */ }
-    }
-    // Knip dead-exports — KJC-TSK v2.17. Stack-aware, JS/TS only, needs
-    // package.json. Best-effort: any failure returns available:false and
-    // the audit continues without the section.
-    if (!noKnip) {
-      try {
-        deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
-        // AC8 (KJC-TSK-0794): the report leads with the derivative — hand the
-        // block its previous measurement, if one was ever recorded.
-        if (deadExports?.available) {
-          const prev = await loadPreviousAudit(projectDir);
-          deadExports.previous = prev?.knipDeadExports ? { ...prev.knipDeadExports, timestamp: prev.timestamp || null } : null;
-        }
-      } catch { /* knip is best-effort */ }
-    }
-    if (!noInjectionScan) {
-      try {
-        injectionFindings = await collectInjectionFindings(projectDir, this.logger);
-      } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
-    }
+    const circularDeps = skip("noMadge") || securityOnly ? null : await bestEffort(() => collectCircularDeps(projectDir, stack, config, logger));
+    const deadExports = skip("noKnip") || securityOnly ? null : await bestEffort(() => deadExportsWithPrevious(projectDir, stack, config, logger));
+    const injectionFindings = skip("noInjectionScan") ? null : await bestEffort(() => collectInjectionFindings(projectDir, logger));
     // Checkov infra misconfigs — INF-C (KJC-TSK-0760). Security surface, so
     // it ALSO runs in securityOnly. Best-effort: no infra markers or missing
     // checkov return available:false declaring why.
-    if (!noInfraScan) {
-      try {
-        infraFindings = await collectInfraFindings(projectDir, this.logger);
-      } catch { /* checkov is best-effort */ }
-    }
+    const infraFindings = skip("noInfraScan") ? null : await bestEffort(() => collectInfraFindings(projectDir, logger));
+    // KJC-TSK-1253: npm registry signatures and provenance. Supply-chain security, so it
+    // also runs in securityOnly; the collector says when it does not apply or cannot run.
+    const npmSignatures = skip("noNpmSignatures") ? null : await bestEffort(() => collectNpmSignatures(projectDir, logger));
     // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
     // Local equivalent of Deslopify-style review. Best-effort.
-    if (!noAiSlop) {
-      try {
-        aiSlop = await collectAiSlop(projectDir);
-      } catch { /* ai-slop scan is best-effort */ }
-    }
+    const aiSlop = skip("noAiSlop") || securityOnly ? null : await bestEffort(() => collectAiSlop(projectDir));
     // KJC-TSK-0845: one key, two resolution rules = a migration left half-way
     // (KJ_HOME → KARAJAN_HOME). Deterministic, offline, best-effort.
-    if (!securityOnly) {
-      try {
-        envKeys = await collectEnvKeyFindings(projectDir);
-      } catch { /* env-key scan is best-effort */ }
-    }
-    // STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
-    // at, so the Steward can age it — GREBLA went 79 days with "never".
-    try {
-      mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
-      writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
-    } catch { /* recording is best-effort — the audit itself already ran */ }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop, envKeys };
+    const envKeys = securityOnly ? null : await bestEffort(() => collectEnvKeyFindings(projectDir));
+    recordSecurityAudit(projectDir, securityOnly);
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, npmSignatures, aiSlop, envKeys };
   }
 
   /**
@@ -182,13 +187,8 @@ export class AuditRole extends AgentRole {
    * call this if the user wants to spend tokens.
    */
   async executeWithDeterministic(input, deterministicCtx) {
-    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-    const rawDimensions = typeof input === "object" ? input?.dimensions || null : null;
-    const context = typeof input === "object" ? input?.context || null : null;
-    const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
-
-    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, envKeys } = deterministicCtx;
+    const { task, onOutput, dimensions, context } = auditInput(input, this.context?.task || "");
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
@@ -238,26 +238,7 @@ export class AuditRole extends AgentRole {
         try { await saveAuditSnapshot(projectDir, { ...basalCost, knipDeadExports }); } catch { /* best-effort */ }
       }
 
-      return {
-        ok: true,
-        result: {
-          summary: parsed.summary, dimensions: parsed.dimensions,
-          topRecommendations: parsed.topRecommendations,
-          textSummary: parsed.textSummary || undefined,
-          basalCost: basalCost || undefined, growthDelta: growthDelta || undefined,
-          stack: stack || undefined,
-          sonarFindings: sonarFindings?.available ? sonarFindings : undefined,
-          webperf: webperf?.available ? webperf : undefined,
-          osvFindings: osvFindings?.available ? osvFindings : undefined,
-          semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
-          circularDeps: circularDeps?.available ? circularDeps : undefined,
-          deadExports: deadExports?.available ? deadExports : undefined,
-          envKeys: envKeys?.available ? envKeys : undefined,
-          provider
-        },
-        summary: buildSummary(parsed),
-        usage
-      };
+      return { ok: true, result: structuredResult(parsed, deterministicCtx, provider), summary: buildSummary(parsed), usage };
     } catch {
       return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
     }

package/src/skills/atril-skills.js

@@ -10,10 +10,11 @@ import { join } from "node:path";
 import { resolve as atrilResolve } from "@karajan-family/atril";
 
 export const ATRIL_ROOT = ".karajan";
-const KIND_DIRS = ["skills", "commands", "agents"];
-
-/** A project has a store when any kind directory exists under `.karajan/`. */
-export const hasAtrilStore = (projectDir, root = ATRIL_ROOT) => KIND_DIRS.some((dir) => existsSync(join(projectDir, root, dir)));
+/**
+ * The roles ask atril for their skills once the store holds skills: Karajan's own commands
+ * (installed there by kj init, step 15d) must not switch the roles off their usual skills.
+ */
+export const hasAtrilStore = (projectDir, root = ATRIL_ROOT) => existsSync(join(projectDir, root, "skills"));
 
 /**
  * The block atril resolves for this role and task, in the shape the prompts