@mrciphersmith/keryx 0.3.82 → 0.3.84

package/dist/cli.js

@@ -17288,7 +17288,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
-    "review/review-orchestrator": 1723,
+    "review/review-orchestrator": 1712,
     "review/review-performance": 374,
     "review/review-pr-feedback": 895,
     "review/review-regression": 216,
@@ -21098,7 +21098,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.82",
+    version: "0.3.84",
     description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
     private: false,
     publishConfig: {
@@ -180440,7 +180440,7 @@ var init_project_reviewers = __esm(() => {
 });
 
 // src/gdskills/import-skills.ts
-import { readdir as readdir57, readFile as readFile178, stat as stat37 } from "fs/promises";
+import { lstat as lstat19, readdir as readdir57, readFile as readFile178, stat as stat37 } from "fs/promises";
 import { homedir as homedir15 } from "os";
 import path342 from "path";
 function emptyOnlyError(label) {
@@ -180469,10 +180469,18 @@ async function importProjectSkills(options) {
   const existingFlags = await projectReviewerFlags(options.projectRoot);
   const plans = await Promise.all(sources.map((source) => planOne(options, source)));
   const refusedPackages = new Set(plans.flatMap((plan) => ("row" in plan) && isRefusedStatus(plan.row.status) ? [plan.row.name] : []));
-  const ruleDecisions = await decideReferencedRules(options, sources.filter((source) => !skippedAsDeprecated(source)).filter((source) => options.force === true || !BUNDLED_NAMES.has(source.name)), refusedPackages);
+  const candidates = sources.filter((source) => !skippedAsDeprecated(source)).filter((source) => options.force === true || !BUNDLED_NAMES.has(source.name));
+  const ruleDecisions = await decideReferencedRules(options, candidates, refusedPackages);
+  const templatePlans = [];
+  for (const source of candidates) {
+    if (source.sourcePath === undefined || refusedPackages.has(source.name))
+      continue;
+    templatePlans.push(...await planTemplates(options, { module: source.module, name: source.name, sourcePath: source.sourcePath }, options.force === true));
+  }
   await refuseUncontainedWrites(label, options.projectRoot, [
     ...plans.flatMap((plan) => ("write" in plan) ? projectSkillWritePaths(plan.write.module, plan.write.name, "single") : []),
-    ...ruleDecisions.flatMap((decision) => ("placement" in decision) ? [decision.placement.target] : [])
+    ...ruleDecisions.flatMap((decision) => ("placement" in decision) ? [decision.placement.target] : []),
+    ...templatePlans.flatMap((plan) => ("write" in plan) ? [plan.write.target] : [])
   ]);
   const imported = [];
   for (const plan of plans) {
@@ -180483,11 +180491,13 @@ async function importProjectSkills(options) {
   for (const decision of ruleDecisions) {
     rules.push("row" in decision ? decision.row : options.dryRun ? unwrittenRow(decision.placement, [decision.dryRunReason, ...gateNotes(decision.gate, true)].filter(isString4).join(" \u2014 ") || undefined, decision.gate.security) : await writePlacedRule(options, decision.placement, decision.gate));
   }
+  const templates = await writeTemplates(options, templatePlans);
   return {
     from: options.from,
     only: options.only ?? [],
     imported,
     rules,
+    templates,
     dryRun: options.dryRun === true,
     force: options.force === true
   };
@@ -180517,18 +180527,29 @@ async function updateProjectSkills(options) {
   for (const entry of selected) {
     plans.push(await planUpdate(options, entry));
   }
-  await refuseUncontainedWrites("keryx skills update", options.projectRoot, plans.flatMap((plan) => ("content" in plan) ? projectSkillWritePaths(projectSkillSlug(plan.entry.module), projectSkillSlug(plan.entry.name), "single") : []));
+  const templatePlans = [];
+  for (const plan of plans) {
+    if (!("content" in plan) || plan.sourcePath === undefined)
+      continue;
+    templatePlans.push(...await planTemplates(options, { module: projectSkillSlug(plan.entry.module), name: projectSkillSlug(plan.entry.name), sourcePath: plan.sourcePath }, true));
+  }
+  await refuseUncontainedWrites("keryx skills update", options.projectRoot, [
+    ...plans.flatMap((plan) => ("content" in plan) ? projectSkillWritePaths(projectSkillSlug(plan.entry.module), projectSkillSlug(plan.entry.name), "single") : []),
+    ...templatePlans.flatMap((plan) => ("write" in plan) ? [plan.write.target] : [])
+  ]);
   const existingFlags = await projectReviewerFlags(options.projectRoot);
   const imported = [];
   for (const plan of plans) {
     imported.push("row" in plan ? plan.row : await writeUpdate(options, plan));
   }
   addFlagWarnings(imported, plans.map((plan) => ("content" in plan) ? plan : undefined), existingFlags);
+  const templates = await writeTemplates(options, templatePlans);
   return {
     from: options.from ?? "(each skill Origin)",
     only: [],
     imported,
     rules: [],
+    templates,
     dryRun: options.dryRun === true,
     force: true
   };
@@ -180566,9 +180587,10 @@ function renderImportProjectSkillsMarkdown(result) {
   if (result.imported.some((row) => row.status === "skipped" && row.reason === DEPRECATED_REASON)) {
     lines.push("A package whose frontmatter says `deprecated: true` is skipped in a tree import. To import one anyway, pass its own directory as --from.", "");
   }
-  if (result.imported.some((row) => isRefusedStatus(row.status)) || result.rules.some((rule) => isRefusedStatus(rule.status))) {
+  if (result.imported.some((row) => isRefusedStatus(row.status)) || result.rules.some((rule) => isRefusedStatus(rule.status)) || result.templates.some((template) => isRefusedStatus(template.status))) {
     lines.push(refusedNote(result), "");
   }
+  lines.push(...renderTemplateLines(result.templates));
   if (result.rules.length > 0) {
     lines.push("## rules the skills cite", "");
     for (const rule of result.rules) {
@@ -180620,9 +180642,10 @@ function renderUpdateProjectSkillsMarkdown(result) {
     }
   }
   lines.push("");
-  if (result.imported.some((row) => isRefusedStatus(row.status))) {
+  if (result.imported.some((row) => isRefusedStatus(row.status)) || result.templates.some((template) => isRefusedStatus(template.status))) {
     lines.push(refusedNote(result), "");
   }
+  lines.push(...renderTemplateLines(result.templates));
   if (result.imported.some((row) => row.module === PROJECT_REVIEWER_MODULE && isWrittenRow(row))) {
     lines.push(`Reviewers: \`keryx review reviewers\` must list every updated ${PROJECT_REVIEWER_MODULE}/* name. That is the same call review-orchestrator makes.`);
   }
@@ -180927,12 +180950,12 @@ function isRefusedStatus(status) {
   return status === "refused" || status === "would-refuse";
 }
 function refusedNote(result) {
-  const refused = [...result.imported, ...result.rules].filter((row) => isRefusedStatus(row.status));
+  const refused = [...result.imported, ...result.rules, ...result.templates].filter((row) => isRefusedStatus(row.status));
   const overridable = refused.some((row) => row.security?.findings.some((finding) => finding.policyId.startsWith("prompt-injection.")));
   return overridable ? `${REFUSED_NOTE} ${ALLOW_FLAGGED_HINT}` : REFUSED_NOTE;
 }
 function exitNonZeroOnRefusal(result) {
-  if ([...result.imported, ...result.rules].some((row) => row.status === "refused")) {
+  if ([...result.imported, ...result.rules, ...result.templates].some((row) => row.status === "refused")) {
     process.exitCode = 1;
   }
 }
@@ -181131,6 +181154,7 @@ async function planUpdate(options, entry) {
     return skippedRow("no Origin recorded", "");
   }
   let content;
+  let sourcePath;
   if (isHttpsSkillUrl(origin)) {
     const fetcher = options.fetcher ?? DEFAULT_FETCHER;
     const response = await fetcher(githubBlobToRaw(origin));
@@ -181144,6 +181168,7 @@ async function planUpdate(options, entry) {
       return skippedRow("origin file can no longer be read", origin);
     }
     content = await readFile178(resolved, "utf8");
+    sourcePath = resolved;
     origin = portableOriginRef(resolved, options.projectRoot);
   }
   const verdict = await gateText(options.projectRoot, plannedSkillText(content, { name: entry.name, module: entry.module, origin }), toPosix(path342.join(entry.path, "SKILL.md")), options.allowFlagged === true);
@@ -181152,7 +181177,7 @@ async function planUpdate(options, entry) {
       row: refusedSkillRow({ name: entry.name, module: entry.module, path: entry.path, origin }, verdict, options.dryRun === true)
     };
   }
-  return { entry, origin, content, gate: verdict };
+  return { entry, origin, content, gate: verdict, ...sourcePath !== undefined ? { sourcePath } : {} };
 }
 async function writeUpdate(options, { entry, origin, content, gate }) {
   const notes = reviewNotes(content, entry.module);
@@ -181394,6 +181419,106 @@ async function decideReferencedRules(options, sources, refusedPackages) {
   }
   return decisions;
 }
+async function listTemplateFiles(sourcePath) {
+  const root = path342.join(path342.dirname(sourcePath), TEMPLATES_DIR);
+  try {
+    if (!(await lstat19(root)).isDirectory())
+      return [];
+  } catch {
+    return [];
+  }
+  const files = [];
+  const walk = async (dir, prefix) => {
+    const entries = (await readdir57(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory())
+        await walk(path342.join(dir, entry.name), rel);
+      else if (entry.isFile())
+        files.push(rel);
+    }
+  };
+  await walk(root, "");
+  return files;
+}
+async function planTemplates(options, pkg, replace) {
+  const plans = [];
+  const packageKey = `${pkg.module}/${pkg.name}`;
+  const packagePath = projectSkillPackagePath(pkg.module, pkg.name);
+  for (const file of await listTemplateFiles(pkg.sourcePath)) {
+    const target = `${packagePath}/${TEMPLATES_DIR}/${file}`;
+    const base = { package: packageKey, file, path: target };
+    const bytes = await readFile178(path342.join(path342.dirname(pkg.sourcePath), TEMPLATES_DIR, file));
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes)) {
+      plans.push({ row: { ...base, status: "skipped", reason: "not UTF-8 text; the importer copies text templates only" } });
+      continue;
+    }
+    const targetAbs = path342.join(options.projectRoot, target);
+    const exists = await pathExists(targetAbs);
+    if (exists && !await isRegularFile(targetAbs)) {
+      plans.push({ row: { ...base, status: "skipped", reason: `${target} is not a regular file; nothing was written there` } });
+      continue;
+    }
+    const existing = exists ? await readFile178(targetAbs, "utf8") : undefined;
+    if (existing === text) {
+      plans.push({ row: { ...base, status: "unchanged" } });
+      continue;
+    }
+    const verdict = await gateText(options.projectRoot, text, target, options.allowFlagged === true);
+    if (verdict.kind === "write" && existing === verdict.content) {
+      plans.push({ row: { ...base, status: "unchanged" } });
+      continue;
+    }
+    if (existing !== undefined && !replace) {
+      plans.push({ row: { ...base, status: "differs", reason: "left as it is; pass --force to replace it with the package's" } });
+      continue;
+    }
+    if (verdict.kind !== "write") {
+      plans.push({
+        row: {
+          ...base,
+          status: options.dryRun ? "would-refuse" : "refused",
+          reason: verdict.kind === "blocked" ? `blocked by the security gate: ${verdict.reason}` : verdict.reason,
+          ...verdict.kind === "refuse" ? { security: verdict.security } : {}
+        }
+      });
+      continue;
+    }
+    plans.push({ write: { row: base, target, exists: existing !== undefined, gate: verdict } });
+  }
+  return plans;
+}
+async function writeTemplates(options, plans) {
+  const rows = [];
+  for (const plan of plans) {
+    if ("row" in plan) {
+      rows.push(plan.row);
+      continue;
+    }
+    const { row, target, exists, gate } = plan.write;
+    const parts = gateRowParts(gate, options.dryRun === true);
+    if (options.dryRun !== true)
+      await writeContained(options.projectRoot, target, gate.content);
+    rows.push({
+      ...row,
+      status: options.dryRun === true ? exists ? "would-overwrite" : "would-import" : exists ? "overwritten" : "imported",
+      ...parts.reason !== undefined ? { reason: parts.reason } : {},
+      ...parts.security !== undefined ? { security: parts.security } : {}
+    });
+  }
+  return rows;
+}
+function renderTemplateLines(templates) {
+  if (templates.length === 0)
+    return [];
+  const lines = ["## templates the packages ship", ""];
+  for (const template of templates) {
+    lines.push(`- ${template.package} ${TEMPLATES_DIR}/${template.file}: ${template.status}${template.reason ? ` \u2014 ${template.reason}` : ""}`);
+  }
+  lines.push("");
+  return lines;
+}
 function inferNameFromPath(filePath, content) {
   const fromFrontmatter = frontmatterName(content);
   if (fromFrontmatter)
@@ -181577,7 +181702,7 @@ A package directory, or a SKILL.md or URL name, with no letter or digit is
 refused: it has no name to be written under.
 
 Before anything is written, every destination \u2014 the package, the registry in
-.metaproject/metaproject.json, the catalog and each rule \u2014 is checked for a
+.metaproject/metaproject.json, the catalog, each rule and each template \u2014 is checked for a
 symlink on the way that resolves outside the project. One is refused, and the
 import writes nothing; --dry-run refuses it the same way.
 
@@ -181588,6 +181713,18 @@ name, the copy goes to .metaproject/rules/project/<dir>/<name>.mdc, which a
 reviewer's reference resolves to first; an existing copy there that differs is
 replaced only with --force.
 
+A package's templates/ directory (a report overlay, say) is copied, with its
+subdirectories, to .metaproject/project-skills/<module>/<name>/templates/, byte
+for byte, so the skill reads it from the project and not from the repository it
+was imported from. Only regular text files are copied; a symlink or a non-UTF-8
+file is not. Each file gets a row: imported (would-import on a dry run),
+unchanged when the project has it, differs when the project's copy is another
+file \u2014 left as it is, and replaced only with --force. Templates go through the
+same security gate as SKILL.md. A package that is already in the project still
+gets its templates, as it gets its rules. A URL source has none.
+\`keryx skills update\` re-reads them with SKILL.md; \`keryx skills remove\` deletes
+them with the package.
+
 Examples:
   keryx skills import --from ./overlays --module review --only 'review-house-*'
   keryx skills import --from ./overlays/skills/review-house-api --module review
@@ -181599,6 +181736,8 @@ function printSkillsUpdateHelp() {
   console.log(`keryx skills update
 
 Re-read a project-skill's Origin and overwrite SKILL.md when the source moved on.
+The templates/ directory beside a local Origin is re-read with it, and each
+file in it replaces the project's copy.
 
 Usage:
   keryx skills update <module>/<name> [--from <new-origin>] [--dry-run] [--allow-flagged] [--json]
@@ -181618,7 +181757,7 @@ Examples:
 var BUNDLED_NAMES, PATHS_NONE_WARNING = 'paths: none \u2014 dispatched on every round. Declare `metadata.paths: "<glob>, <glob>"` in its frontmatter to gate it on the diff.', DEFAULT_FETCHER = async (url) => {
   const response = await fetch(url);
   return { ok: response.ok, status: response.status, text: await response.text() };
-}, DEPRECATED_REASON = "deprecated", KNOWN_CATEGORIES, isString4 = (value) => value !== undefined, REFUSED_NOTE = "A refused file was not written.", ALLOW_FLAGGED_HINT = "A prompt-injection refusal can be overridden after you read the file: run the command again with --allow-flagged.", IMPORT_HEADER_LABELS, IMPORT_HEADER_LINE, BYTE_ORDER_MARK = 65279, ALLOW_FLAGGED_FLAG = "--allow-flagged", SECURITY_GATE_HELP = `Security gate: a SKILL.md or rule is written as the gate returns it, so a secret is
+}, DEPRECATED_REASON = "deprecated", KNOWN_CATEGORIES, isString4 = (value) => value !== undefined, REFUSED_NOTE = "A refused file was not written.", ALLOW_FLAGGED_HINT = "A prompt-injection refusal can be overridden after you read the file: run the command again with --allow-flagged.", IMPORT_HEADER_LABELS, IMPORT_HEADER_LINE, BYTE_ORDER_MARK = 65279, TEMPLATES_DIR = "templates", ALLOW_FLAGGED_FLAG = "--allow-flagged", SECURITY_GATE_HELP = `Security gate: a SKILL.md or rule is written as the gate returns it, so a secret is
 masked and the row says it was redacted, and any other finding is reported on the
 row. Text with a prompt-injection finding is refused in every security mode: the
 row is \`refused\` (\`would-refuse\` on a dry run) with the gate's own summary,
@@ -181660,7 +181799,7 @@ var init_import_skills = __esm(() => {
 });
 
 // src/gdskills/remove-skill.ts
-import { lstat as lstat19, readdir as readdir58, readFile as readFile179, realpath as realpath23 } from "fs/promises";
+import { lstat as lstat20, readdir as readdir58, readFile as readFile179, realpath as realpath23 } from "fs/promises";
 import path343 from "path";
 async function removeProjectSkill(projectRoot, options) {
   if (!await pathExists(path343.join(projectRoot, ".metaproject"))) {
@@ -181855,7 +181994,7 @@ function normalizeSkillKey(input) {
 }
 async function lstatOrMissing(target) {
   try {
-    return await lstat19(target);
+    return await lstat20(target);
   } catch (error) {
     if (isMissingPathError(error))
       return;
@@ -181920,7 +182059,7 @@ async function locateRewritable(root, relativePath) {
   if (absolute === root || !isPathInside(root, absolute)) {
     throw new Error(`${LABEL}: ${relativePath} resolves to ${absolute}, outside the project. Refusing to rewrite a file the project does not own. ${UNCHANGED}`);
   }
-  if (!(await lstat19(absolute)).isFile()) {
+  if (!(await lstat20(absolute)).isFile()) {
     throw new Error(`${LABEL}: ${relativePath} is not a regular file. ${UNCHANGED}`);
   }
   const resolvedPath = toPosix(path343.relative(root, absolute));
@@ -195636,7 +195775,7 @@ var init_tools3 = __esm(() => {
 
 // src/mcp/resources.ts
 import path364 from "path";
-import { lstat as lstat20, readdir as readdir66, realpath as realpath25, stat as stat39 } from "fs/promises";
+import { lstat as lstat21, readdir as readdir66, realpath as realpath25, stat as stat39 } from "fs/promises";
 function mimeForPath(filePath) {
   if (filePath.endsWith(".json") || filePath.endsWith(".jsonl")) {
     return "application/json";
@@ -195659,7 +195798,7 @@ async function walkFiles(root, ownerRoot = root, ancestors = new Set) {
   if (!await pathExists(root)) {
     return [];
   }
-  const ownerInfo = await lstat20(ownerRoot).catch(() => null);
+  const ownerInfo = await lstat21(ownerRoot).catch(() => null);
   if (!ownerInfo || !ownerInfo.isDirectory() || ownerInfo.isSymbolicLink())
     return [];
   const ownerReal = await realpath25(ownerRoot).catch(() => null);
@@ -218207,7 +218346,7 @@ var init_types13 = __esm(() => {
 });
 
 // src/bundle/paths.ts
-import { lstat as lstat21, readFile as readFile200 } from "fs/promises";
+import { lstat as lstat22, readFile as readFile200 } from "fs/promises";
 import path391 from "path";
 function scopeRoot(scope, ctx) {
   if (scope === "user") {
@@ -218401,7 +218540,7 @@ async function resolveContainedPathForWrite(root, relPath) {
 async function refuseSymlinkChain(root, relPath) {
   const rootResolved = path391.resolve(root);
   try {
-    const rootStat = await lstat21(rootResolved);
+    const rootStat = await lstat22(rootResolved);
     if (rootStat.isSymbolicLink()) {
       return {
         ok: false,
@@ -218414,7 +218553,7 @@ async function refuseSymlinkChain(root, relPath) {
   for (const segment of segments) {
     current = path391.join(current, segment);
     try {
-      const stat = await lstat21(current);
+      const stat = await lstat22(current);
       if (stat.isSymbolicLink()) {
         return {
           ok: false,
@@ -218464,7 +218603,7 @@ var init_paths5 = __esm(() => {
 });
 
 // src/bundle/archive.ts
-import { readdir as readdir69, readFile as readFile201, lstat as lstat22 } from "fs/promises";
+import { readdir as readdir69, readFile as readFile201, lstat as lstat23 } from "fs/promises";
 import path392 from "path";
 import { gzipSync, gunzipSync } from "zlib";
 function resolveLimits(limits) {
@@ -218672,7 +218811,7 @@ async function openBundle(bundlePath, limits) {
   const resolved = resolveLimits(limits);
   let stat;
   try {
-    stat = await lstat22(bundlePath);
+    stat = await lstat23(bundlePath);
   } catch {
     return { ok: false, refusal: { reason: BUNDLE_REFUSAL.notABundle, message: `no such path: ${bundlePath}` } };
   }
@@ -218686,7 +218825,7 @@ async function openBundle(bundlePath, limits) {
       for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
         const abs = path392.join(dir, entry.name);
         const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
-        const entryStat = await lstat22(abs);
+        const entryStat = await lstat23(abs);
         if (entryStat.isSymbolicLink()) {
           return { reason: BUNDLE_REFUSAL.symlinkRefused, path: rel, message: `${rel} is a symlink; bundles may not contain symlinks` };
         }
@@ -219561,7 +219700,7 @@ var init_learned_pattern_schema = __esm(() => {
 
 // src/bundle/export.ts
 import { execFileSync as execFileSync3 } from "child_process";
-import { mkdir as mkdir81, readdir as readdir70, readFile as readFile202, writeFile as writeFile57, lstat as lstat23 } from "fs/promises";
+import { mkdir as mkdir81, readdir as readdir70, readFile as readFile202, writeFile as writeFile57, lstat as lstat24 } from "fs/promises";
 import { existsSync as existsSync60 } from "fs";
 import path393 from "path";
 function globToRegExp5(glob) {
@@ -219648,7 +219787,7 @@ async function walkFiles2(dir, relPrefix, out, skipped) {
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     const abs = path393.join(dir, entry.name);
     const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
-    const st = await lstat23(abs);
+    const st = await lstat24(abs);
     if (st.isSymbolicLink()) {
       skipped.push({ path: rel, reason: "symlink" });
       continue;
@@ -219696,7 +219835,7 @@ async function collectAgents(root, skipped) {
   const candidates = [];
   for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     const abs = path393.join(base, entry.name);
-    const st = await lstat23(abs);
+    const st = await lstat24(abs);
     if (st.isSymbolicLink()) {
       skipped.push({ path: `agents/${entry.name}`, reason: "symlink" });
       continue;
@@ -219721,7 +219860,7 @@ async function collectMemory(root, skipped) {
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       const abs = path393.join(base, entry.name);
-      const st = await lstat23(abs);
+      const st = await lstat24(abs);
       if (st.isSymbolicLink()) {
         skipped.push({ path: `memory/${folder}/${entry.name}`, reason: "symlink" });
         continue;
@@ -219737,7 +219876,7 @@ async function collectHookConfig(root) {
   const abs = path393.join(root, "hooks.json");
   if (!existsSync60(abs))
     return [];
-  const st = await lstat23(abs);
+  const st = await lstat24(abs);
   if (st.isSymbolicLink() || !st.isFile())
     return [];
   return [{ bundlePath: "hooks.json", kind: "hook-config", absolutePath: abs }];
@@ -220118,7 +220257,7 @@ var init_applied_state = __esm(() => {
 });
 
 // src/lib/private-dir.ts
-import { lstat as lstat24, mkdir as mkdir82, open as open11, readFile as readFile204 } from "fs/promises";
+import { lstat as lstat25, mkdir as mkdir82, open as open11, readFile as readFile204 } from "fs/promises";
 import path395 from "path";
 async function checkPrivateDirGitignore(dir, root) {
   if (root !== undefined) {
@@ -220137,7 +220276,7 @@ async function checkPrivateDirGitignore(dir, root) {
   }
   let dirStats;
   try {
-    dirStats = await lstat24(dir);
+    dirStats = await lstat25(dir);
   } catch (error) {
     if (isNotFound(error)) {
       return { ok: true, action: "create" };
@@ -220158,7 +220297,7 @@ async function checkPrivateDirGitignore(dir, root) {
   const gitignorePath = path395.join(dir, ".gitignore");
   let stats;
   try {
-    stats = await lstat24(gitignorePath);
+    stats = await lstat25(gitignorePath);
   } catch (error) {
     if (isNotFound(error)) {
       return { ok: true, action: "create" };

package/dist/core.js

@@ -10853,7 +10853,7 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
-    "review/review-orchestrator": 1723,
+    "review/review-orchestrator": 1712,
     "review/review-performance": 374,
     "review/review-pr-feedback": 895,
     "review/review-regression": 216,

package/package.json

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

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -1203,25 +1203,25 @@ Ask unless automation settings explicitly set `publish_pr_review_report`:
 ```text
 Publish the review report to the PR?
 
-  A) Concise PR comment only
-  B) Concise PR comment + detailed AI markdown artifact (recommended for follow-up fixes)
+  A) Concise PR review only
+  B) Concise PR review + detailed AI markdown artifact (recommended for follow-up fixes)
   C) Do not publish
 
 > pick a letter (default: C)
 ```
 
 **Rules:**
-- The PR comment and AI artifact must be written in English only, regardless of the chat language or reviewer output language.
+- The PR review and AI artifact must be written in English only, regardless of the chat language or reviewer output language.
 - Default is C. Never publish to a PR without explicit user confirmation or `publish_pr_review_report: comment`, `publish_pr_review_report: comment-and-ai-artifact`.
-- If the user chooses A, delegate concise comment formatting to `review-orchestrator`'s PR Review Report Publication contract.
+- If the user chooses A, delegate concise review formatting to `review-orchestrator`'s PR Review Report Publication contract.
 - If the user chooses B, also generate `.metaproject/jobs/<job-name>/review-ai-report.md` using `review-orchestrator`'s Detailed AI Markdown Artifact contract, and include in the comment's `Meta` section both an `AI artifact` path and an `AI artifact description` row explaining that the file carries detailed findings, fix guidance, patch guidance, regression coverage, validation plan, and follow-up agent context.
 - **If no PR exists yet**, do not ask now and do not stash a pending decision — nothing persists one. Ask this question again after the PR step (2.10) creates the PR, when the answer can actually be acted on.
 - The decision is acted on immediately or not at all. There is no `publication_plan` field in `state.json`; what was published is stated in the 2.9 report.
 
 **Automation values:**
 - `publish_pr_review_report: ask` -> ask the question above.
-- `publish_pr_review_report: comment` -> publish the concise PR comment only.
-- `publish_pr_review_report: comment-and-ai-artifact` -> publish the concise PR comment and create the detailed AI markdown artifact.
+- `publish_pr_review_report: comment` -> publish the concise PR review only.
+- `publish_pr_review_report: comment-and-ai-artifact` -> publish the concise PR review and create the detailed AI markdown artifact.
 - `publish_pr_review_report: none` -> do not publish.
 
 #### 2.6.3 Post-Review Checkpoint

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

@@ -1564,15 +1564,18 @@ in `templates/review-report.md`: `Changes requested` or `No blockers, merge-read
 Render the human report from that file. Do not invent a second skeleton here.
 
 ```markdown
-**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** Reviewed `<head>` against `<base>` (round N). <what holds, and where the risk is.>
+<!-- slot:pre-verdict -->
+**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** <what holds, and where the risk is.>
+Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del> · CI <state>.
+<!-- slot:after-verdict -->
 
 ### Blocker
-**F-001. <one-sentence claim>.** `path/to/file.ts:line`, in the diff.
+**F-001. <one-sentence claim>.** [`path/to/file.ts:line`](<blob link at head>), in the diff.
 <proof: traced path, probe, or failing scenario>
 Fix: <concrete>
 
 ### Major
-**F-002. <one-sentence claim>.** `path/to/file.ts:line`, pre-existing — render under Pre-existing instead when location_class says so.
+**F-002. <one-sentence claim>.** [`path/to/file.ts:line`](<blob link at head>), in the diff.
 
 ### Minor
 - **F-010. <claim>.** `path:line`, in the diff — <proof and fix, one to three sentences>.
@@ -1580,21 +1583,7 @@ Fix: <concrete>
 ### Questions
 1. <an info finding that needs an author answer; other info is not published>
 
-### Pre-existing (not blocking)
-- **F-020. <claim>.** `path:line` — <why it is out of this diff>
-
-### Verified clean
-- <what was checked> — <how>
-
-### How this review was run
-- **Workflow:** `review-orchestrator`
-- **Scope:** `<base>..<head>`, round N, PR #N
-- **Models:** <actual models and reviewers, or not recorded>
-- **Tools:** <tools actually invoked, or not recorded>
-- **Skills:** <skills actually used, or not recorded>
-- **Subagents:** <dispatched reviewers and models, or none when confirmed; otherwise not recorded>
-- **Not run:** <reviewer — reason>
-- **Verification:** <mode>; confirmed N, refuted N, unverifiable N, unverified N
+<details> Pre-existing (not blocking) · Verified clean <!-- slot:verified-clean --> · How this review was run — **Workflow:**, **Scope:**, **Models:**, **Tools:**, **Skills:**, **Subagents:**, **Not run:**, **Verification:** <!-- slot:how-run --> </details>
 ```
 
 Pick the domain file the same way reviewers are picked: frontend scope, or a
@@ -1650,8 +1639,8 @@ the report exists, unless `publish_pr_review_report` is already set:
 ```text
 Publish this review report to the PR?
 
-  A) PR comment only
-  B) PR comment + follow-up file (recommended when a fix round will follow)
+  A) PR review only
+  B) PR review + follow-up file (recommended when a fix round will follow)
   C) Do not publish
 
 > pick a letter (default: C)
@@ -1659,15 +1648,15 @@ Publish this review report to the PR?
 
 Automation values, names unchanged:
 
-- `comment` or legacy `true` -> the PR comment only.
-- `comment-and-ai-artifact` -> the PR comment plus the follow-up file.
+- `comment` or legacy `true` -> the PR review only.
+- `comment-and-ai-artifact` -> the PR review plus the follow-up file.
 - `none` or legacy `false` -> do not publish.
 
 Default is do not publish. No resolvable PR number means skip and say so.
 
-The comment is the report rendered from `templates/review-report.md`, English, with the domain file chosen above (`templates/pr-comment-frontend.md` / `templates/pr-comment-backend.md`) — never a summary written freehand. It does not use a tool heading, a finding table, or a meta table. It does not carry a co-author line, a `Generated with` trailer, or any sentence that names a vendor or a product as the author. Name the workflow and reviewers that actually ran, with models, tools, skills and subagents. Never identify the operator from `gh auth status`, git config or a credential; do not sign the comment as a person, reviewer or model.
+The review body is the report rendered from `templates/review-report.md`, English, with the domain file chosen above (`templates/pr-comment-frontend.md` / `templates/pr-comment-backend.md`) — never a summary written freehand. It does not use a tool heading, a finding table, or a meta table. It does not carry a co-author line, a `Generated with` trailer, or any sentence that names a vendor or a product as the author. Name the workflow and reviewers that actually ran, with models, tools, skills and subagents. Never identify the operator from `gh auth status`, git config or a credential; do not sign the review as a person, reviewer or model. A project overlay adds content only through the template's overlay slots.
 
-The follow-up file path and the metadata rules (real model names, Run vs Not run, no `adaptive` in the model slot) live in that same template. Write the body to a temp file and post with `gh pr comment <n> --body-file <file>`.
+The follow-up file path and the metadata rules (real model names, Run vs Not run, no `adaptive` in the model slot) live in that same template. Write the body to a temp file and post it as one formal review whose state follows *Where it is posted* in the template: `gh pr review <n> --request-changes|--approve|--comment --body-file <file>`. On a merged or closed PR, post it as `gh pr comment <n> --body-file <file>` instead.
 
 **No GitHub write without an approved draft.** Before ANY write — the comment, a thread reply, `keryx review comments reply`, a review — show the user the rendered body and wait for explicit approval of that body.
 Picking A or B above chooses *whether* to publish, not *what*; a comment is public and cannot be unsent. With no user to answer (a dispatched run), do not write: hand the rendered body back to the caller.

package/src/gdskills/bundled/skills/review/review-orchestrator/templates/review-report.md

@@ -1,15 +1,56 @@
 # Review report (render)
 
 The shape of the report a human reads at the end of a round, and of the PR
-comment when one is published. Machine contracts are unchanged: severity stays
+review when one is published. Machine contracts are unchanged: severity stays
 `blocker | major | minor | info`, the output verdict stays
 `APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES`, and the `keryx:findings`
-block still rides after the prose. This file says how that record is *shown*.
+block still rides after the prose in the ingested copy. This file says how that
+record is *shown*.
 
 Read `templates/pr-comment-frontend.md` or `templates/pr-comment-backend.md`
-for the domain checklist. This file is the skeleton both share.
+for the domain checklist. This file is the skeleton both share, and the slots a
+project overlay may fill.
 
-## How the visible verdict is chosen
+## Where it is posted
+
+On a pull request the report is the **body of one formal review**, so it
+counts as a review and not as a comment stream:
+
+| Machine `verdict` | Review state |
+|---|---|
+| `REQUEST_CHANGES` | Request changes, if the reviewer may; on the reviewer's own PR GitHub rejects it, so Comment |
+| `APPROVE` / `APPROVE_WITH_SUGGESTIONS` | Approve, if the reviewer may approve; else Comment |
+| PR already merged or closed | a plain PR comment — a review state no longer gates anything |
+
+One report per round, posted once. The `keryx:findings` block is never posted;
+it lives in the copy `keryx review ingest` reads. If the body would exceed
+GitHub's 65,536-character limit, post the visible part and link the follow-up
+file for the rest.
+
+## The skeleton
+
+Sections in this order. Omit a heading that has no content. The visible part is
+what a reader must act on; everything else is folded.
+
+```markdown
+<!-- slot:pre-verdict -->
+**Changes requested — 1 Blocker, 2 Major, 4 Minor, 1 question.** <what holds, and where the risk is — one sentence.>
+Reviewed `<head>` against `<base>` · round N · <files> files, +<add>/−<del> · CI <green | red: check names>.
+<!-- slot:after-verdict -->
+
+### Prior findings            (fix rounds only)
+### Blocker
+### Major
+### Minor
+### Questions
+
+<details><summary><b>Pre-existing (not blocking)</b></summary> … </details>
+<details><summary><b>Scope</b></summary> … </details>          (only when a pr-process note exists)
+<details><summary><b>Verified clean</b></summary> … <!-- slot:verified-clean --> </details>
+<details><summary><b>How this review was run</b></summary> … <!-- slot:how-run --> </details>
+```
+
+### The verdict line
 
 Map the machine verdict, do not invent a fourth one:
 
@@ -19,60 +60,71 @@ Map the machine verdict, do not invent a fourth one:
 | `APPROVE` | `**No blockers, merge-ready.**` |
 | `APPROVE_WITH_SUGGESTIONS` | `**No blockers, merge-ready — N Minor, N questions.**` |
 
-`N` is the count of findings **in the changed code** at that severity. A
-`location_class: pre-existing` finding is not in that count and does not flip
-the verdict. Omit a zero Blocker count. A question is an `info` finding that
-needs an author answer, rendered under Questions, not as a finding.
-
-Then one sentence: what holds, and where the risk is. Name the commits
-reviewed: `Reviewed <head> against <base> (round N).` If head moved during the
-round, name the commits not checked.
+`N` counts findings **in the changed code** at that severity. A
+`location_class: pre-existing` finding is not counted and does not flip the
+verdict. Omit a zero count. A question is an `info` finding that needs an
+author answer, rendered under Questions, not as a finding.
 
-## Section order
-
-1. Verdict line.
-2. Blocker, then Major. Omit a heading that has no findings.
-3. Minor.
-4. Questions.
-5. Pre-existing (not blocking). Omit if empty.
-6. Scope — only when a process note exists (`location_class: pr-process`).
-7. Verified clean. Required. Not a list of compliments.
-8. How this review was run.
-9. The `keryx:findings` fence, after the prose, unchanged.
-
-No `## AI Review Report`, `# AI Review Report`, `## AI Summary`, `## Positive
-Notes`, or any heading that names the tool instead of the subject. No
-`Generated with`, no bot signature, no co-author trailer. A model name appears
-only in **How this review was run**, as the model that ran, never as an author.
+The second line is the context line: head, base, round, size, CI. If head moved
+during the round, add `· unchecked: <commits>`.
 
 ## One finding
 
-Blocker and Major, as a paragraph:
+Blocker and Major as a paragraph, visible:
 
 ```markdown
-**F-012. The guard is not called on the save path.** `src/store.ts:88`, in the diff.
-`save()` awaits `api.put` and then writes the form with no `runInAction`. A response that lands after unmount still mutates the store.
+**F-012. The guard is not called on the save path.** [`src/store.ts:88`](https://github.com/<owner>/<repo>/blob/<head>/src/store.ts#L88), in the diff.
+`save()` awaits `api.put` and then writes the form with no `runInAction`. A response that lands after unmount still mutates the store. Probe: <what was run, and what it printed>.
+Also at: `src/other.ts:12`, `src/third.ts:40`.
 Fix: wrap the write in `runInAction`, and ignore the response when `disposed` is set.
 ```
 
-Minor, as one list item, proof and fix in one to three sentences:
+Minor as one list item, proof and fix in one to three sentences:
 
 ```markdown
-- **F-019. Icon button has no accessible name.** `src/Toolbar.tsx:14`, in the diff — the control is an icon with no `aria-label`, so a screen reader announces nothing. Fix: add an `aria-label` from `t()`.
+- **F-019. Icon button has no accessible name.** [`src/Toolbar.tsx:14`](…), in the diff — the control is an icon with no `aria-label`, so a screen reader announces nothing. Fix: add an `aria-label` from `t()`.
 ```
 
 Rules:
 
 - Bold first line is the claim, one sentence. Then `file:line` and the location
   class: `in the diff`, `pre-existing`, or `pr-process`.
-- Proof is a traced path, a probe that was run, or a concrete failing scenario.
-  Not "this looks wrong".
+- `file:line` links to the blob at the **reviewed head SHA**, not to a branch,
+  so the link still points at the reviewed line after the author pushes.
+- Proof is a traced path, a probe that was run (with what it printed), or a
+  concrete failing scenario. Not "this looks wrong".
+- A class with several sites is one finding with an `Also at:` line, never one
+  finding per site.
 - `Fix:` is concrete. A suggested fix is unchecked code: do not publish a fix
-  you have not checked the same way you checked the finding.
+  you have not checked the same way you checked the finding. A GitHub
+  `suggestion` block is allowed only for a fix that was checked.
+- Finding ids (`F-NNN`) are stable across rounds: a re-raised finding keeps its
+  id, a new one takes the next free number.
 - No finding table. A table is allowed only for short cells: ids, `file:line`,
   counts, statuses, before/after, pass/fail. A cell longer than about ten words
   is not a table cell.
 
+When there are more than five Minor findings, wrap the Minor list in
+`<details open><summary><b>Minor (N)</b></summary>` so the page stays scannable.
+
+## Prior findings (fix rounds)
+
+On a round with `is_fix_round: true`, the disposition of every prior finding
+comes before the new ones, as a short table:
+
+```markdown
+### Prior findings
+| Id | Finding | Status | Evidence |
+|---|---|---|---|
+| F-003 | Delete frame dropped on cache miss | closed | probe at `<head>`: handler fires |
+| F-007 | Pending key built by hand | partial | 2 of 4 sites |
+```
+
+Statuses: `closed`, `open`, `partial`, `regressed`, `withdrawn`. A withdrawn
+finding names what made it wrong, in one sentence, and is listed first. A defect
+a fix introduced is a new finding, rendered under its severity with
+`regressed from F-NNN`.
+
 ## Questions and pre-existing
 
 `info` is not published as a finding. If it needs an author answer, render it
@@ -88,7 +140,6 @@ One line per check that was actually run and held: what was checked, and how.
 Do not list a checklist item that was not checked. Do not praise.
 
 ```markdown
-### Verified clean
 - MobX write after `await` — every `await` in the diff is followed by `runInAction` or an early return on `disposed`.
 - i18n — `t()` appears only in render; no `defaultValue`.
 ```
@@ -101,7 +152,6 @@ git config, a credential or a PR author. Use `not recorded` when evidence for
 a tool, skill or model is unavailable; use `none` only when the run proves none.
 
 ```markdown
-### How this review was run
 - **Workflow:** `review-orchestrator`; severity and lanes per the repository review rules, else the canonical rubric in this skill.
 - **Scope:** `<base>..<head>`, round N, PR #N. Unchecked commits: <list or none>.
 - **Models:** <actual model names and the reviewers that ran on each; or not recorded>.
@@ -118,7 +168,7 @@ a tool, skill or model is unavailable; use `none` only when the run proves none.
 - **Reviewed at:** <UTC timestamp>
 ```
 
-Model rules, unchanged from the old metadata table:
+Model rules:
 
 - Name the model that actually ran. Never write `adaptive`, `inherit`,
   `unsupported`, or `current-session` in the model slot.
@@ -128,17 +178,50 @@ Model rules, unchanged from the old metadata table:
 - Keep **Run** complete. If Not run is long, group it with counts and notable
   names; the full list belongs in the follow-up file.
 
+## Formatting rules
+
+- Lead with the conclusion. Nothing above the verdict except a `pre-verdict`
+  slot an overlay fills.
+- Visible part: verdict, context line, prior findings, Blocker, Major, Minor,
+  Questions. Everything else is inside `<details>`.
+- Leave a blank line after every `<summary>…</summary>` and before
+  `</details>`; GitHub renders the Markdown inside only then.
+- Code, paths, flags and identifiers in backticks. No screenshots of code.
+- No `## AI Review Report`, `# AI Review Report`, `## AI Summary`,
+  `## Positive Notes`, or any heading that names the tool instead of the
+  subject. No `Generated with`, no bot signature, no co-author trailer. A model
+  name appears only in **How this review was run**, as the model that ran,
+  never as an author.
+
+## Overlay slots
+
+A project overlay (for example a repository facade over this engine) extends the
+report **only** by filling these slots. It may not reorder, rename or remove a
+base section, add a severity level, or change the verdict mapping.
+
+| Slot | Where | Typical content |
+|---|---|---|
+| `pre-verdict` | above the verdict line | a scope verdict that comes before severity, e.g. "Mis-scoped: split" |
+| `after-verdict` | right after the context line | round status, round cap, review-state rationale, a table of other reviewers' open items |
+| `verified-clean` | end of Verified clean | the project's mandatory checks, each with how it was checked |
+| `how-run` | end of How this review was run | project orchestrator name, overlays selected and skipped, project packages applied, rule files read |
+
+An overlay may also map the review state more strictly (for example "any Major
+→ Request changes"), never more loosely than the table in *Where it is posted*.
+An empty slot leaves no trace in the output. The `<!-- slot:… -->` markers are
+rendering guides and are not posted.
+
 ## Follow-up file
 
 When publication is `comment-and-ai-artifact`, write the long form beside the
-job, not into the PR comment:
+job, not into the PR review:
 
 ```text
 jobs/reviews/pr-<number>/review-report.md
 .metaproject/jobs/<job-name>/ai/review-report.md
 ```
 
-Same section order as the comment. YAML front matter may keep the machine
+Same section order as the review. YAML front matter may keep the machine
 verdict (`APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES`) because ingest
 reads it. The visible title is the subject of the change, never a tool name.
 No co-author line in the file either.