@mrciphersmith/keryx 0.3.112 → 0.3.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.112",
+  "version": "0.3.113",
   "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": {
@@ -53,6 +53,7 @@
     "test:client": "bun run test:client:terminal && bun run test:client:streaming && bun run test:client:cancel-resume && bun run test:client:runtime",
     "check": "bun run lint && bun run typecheck && bun run typecheck:scripts && bun test",
     "check:core": "bun run lint && bun run typecheck && bun run typecheck:scripts && bun run test:core",
+    "docs:build": "mkdocs build --strict",
     "check:doc-links": "bun scripts/check-doc-links.ts",
     "check:retired-spellings": "bun scripts/check-retired-cli-spellings.ts",
     "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
@@ -67,6 +68,7 @@
     "src/gdskills/contracts",
     "!src/**/*.test.ts",
     "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
     "README.md",
     "package.json"
   ],

package/src/gdgraph/affected-report.ts

@@ -25,6 +25,10 @@ import { explainAbsentGraphTarget, loadDeletionTrail } from "../forgetting/servi
 export interface AffectedReportOptions {
   depth?: number;
   ranked?: boolean;
+  /** Read this gdgraph data directory (a review package's graph) instead of the project's own. */
+  dataDir?: string;
+  /** Freshness to report for a `dataDir` graph; the project graph's own staleness check says nothing about it. */
+  freshness?: StalenessCheck;
 }
 
 export interface AffectedReport {
@@ -58,7 +62,13 @@ export async function buildAffectedReport(
   const depth = opts.depth !== undefined && Number.isFinite(opts.depth) ? opts.depth : config.affected.defaultDepth;
   const ranked = opts.ranked ?? true;
 
-  const graph = await loadGraph(root);
+  const graph = await loadGraph(root, opts.dataDir);
+  const freshnessOf = (): Promise<StalenessCheck> =>
+    opts.dataDir === undefined
+      ? checkGraphStaleness(root)
+      : Promise.resolve(
+          opts.freshness ?? { status: "unknown", reasons: ["package graph: freshness is recorded in layers.json"] },
+        );
 
   // Symbol-aware: if the target isn't a known file but names a symbol,
   // resolve it to its owning file — mirrors `runAffected`'s own resolution.
@@ -83,7 +93,7 @@ export async function buildAffectedReport(
       "the graph index holds no file nodes — it was never built here, or its storage is unreadable. " +
         "No claim is being made about whether this target exists.",
     );
-    const freshness = await checkGraphStaleness(root);
+    const freshness = await freshnessOf();
     return {
       exitCode: 1,
       resolutionNote,
@@ -108,7 +118,7 @@ export async function buildAffectedReport(
       `gdgraph: "${target}" is not a node in the built graph (never indexed, or the ` +
       `path/symbol does not exist) — this is not the same as an indexed target with ` +
       `zero edges. Run \`keryx gdgraph build\` if the file is new, or double-check the path.`;
-    const freshness = await checkGraphStaleness(root);
+    const freshness = await freshnessOf();
     return {
       exitCode: 1,
       resolutionNote,
@@ -132,7 +142,7 @@ export async function buildAffectedReport(
     };
   }
 
-  const freshness: StalenessCheck = await checkGraphStaleness(root);
+  const freshness: StalenessCheck = await freshnessOf();
   return {
     exitCode: 0,
     resolutionNote,

package/src/gdgraph/build.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
+import { gdgraphArtifactsDir, gdgraphStorageDir } from "./data-dir";
 import type { GraphData, GraphEdge, GraphNode, ImportKind, TranspilerImportKind } from "./types";
 import { TYPE_ONLY_IMPORT_KIND, UNKNOWN_IMPORT_KIND } from "./types";
 
@@ -100,7 +101,8 @@ type ResolverSet = {
   python: ImportResolver;
 };
 
-export async function buildGraph(projectRoot: string): Promise<BuildResult> {
+export async function buildGraph(projectRoot: string, options: { dataDir?: string } = {}): Promise<BuildResult> {
+  const { dataDir } = options;
   const collection = await collectSourceFiles(projectRoot);
   const files = collection.files;
   const fileSet = new Set(files);
@@ -157,8 +159,8 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
   }
 
   const graph = { nodes: [...nodes, ...assetNodes.values()].sort((a, b) => a.path.localeCompare(b.path)), edges };
-  await writeGraph(projectRoot, graph);
-  const summaryPath = await writeSummary(projectRoot, graph, collection);
+  await writeGraph(projectRoot, graph, dataDir);
+  const summaryPath = await writeSummary(projectRoot, graph, collection, dataDir);
 
   // B1: after the UNCHANGED file-level build, optionally enrich with the
   // tree-sitter symbol layer behind the Block 0 capability seam. Loaded
@@ -168,7 +170,7 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
   // artifacts stay byte-identical (the golden rule, B-1/C0-7/F-3).
   try {
     const { enrichBuildWithSymbols } = await import("./enrich");
-    await enrichBuildWithSymbols(projectRoot, fileRecords);
+    await enrichBuildWithSymbols(projectRoot, fileRecords, undefined, dataDir);
   } catch {
     // Enrichment module or seam unavailable ⇒ file-level graph only.
   }
@@ -180,7 +182,7 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
   // `edges.jsonl` written above are never revisited (AC13).
   try {
     const { enrichBuildWithWikiLayer } = await import("./wiki-layer");
-    await enrichBuildWithWikiLayer({ projectRoot, graph, fileRecords });
+    await enrichBuildWithWikiLayer({ projectRoot, graph, fileRecords, ...(dataDir === undefined ? {} : { dataDir }) });
   } catch {
     // Wiki absent, unreadable, or the layer module unavailable ⇒ no layer.
   }
@@ -887,9 +889,9 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function writeGraph(projectRoot: string, graph: GraphData): Promise<void> {
-  const storageDir = path.join(projectRoot, ".metaproject", "data", "gdgraph", "storage");
-  const artifactsDir = path.join(projectRoot, ".metaproject", "data", "gdgraph", "artifacts");
+async function writeGraph(projectRoot: string, graph: GraphData, dataDir?: string): Promise<void> {
+  const storageDir = gdgraphStorageDir(projectRoot, dataDir);
+  const artifactsDir = gdgraphArtifactsDir(projectRoot, dataDir);
   await mkdir(storageDir, { recursive: true });
   await mkdir(artifactsDir, { recursive: true });
 
@@ -914,8 +916,9 @@ async function writeSummary(
   projectRoot: string,
   graph: GraphData,
   collection: SourceCollection,
+  dataDir?: string,
 ): Promise<string> {
-  const artifactsDir = path.join(projectRoot, ".metaproject", "data", "gdgraph", "artifacts");
+  const artifactsDir = gdgraphArtifactsDir(projectRoot, dataDir);
   await mkdir(artifactsDir, { recursive: true });
 
   const unresolved = graph.edges.filter((edge) => edge.kind === "unresolved");

package/src/gdgraph/core-sources.ts

@@ -14,6 +14,7 @@
 // instead of a stranger's first five minutes.
 export const GDGRAPH_CORE_SOURCES: readonly string[] = [
   "build.ts",
+  "data-dir.ts",
   "query.ts",
   "target.ts",
   "types.ts",

package/src/gdgraph/data-dir.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+
+/** The gdgraph data directory (holds `storage/` and `artifacts/`): the project's own unless a caller names another. */
+export function gdgraphDataDir(projectRoot: string, dataDir?: string): string {
+  return dataDir ?? path.join(projectRoot, ".metaproject", "data", "gdgraph");
+}
+
+export function gdgraphStorageDir(projectRoot: string, dataDir?: string): string {
+  return path.join(gdgraphDataDir(projectRoot, dataDir), "storage");
+}
+
+export function gdgraphArtifactsDir(projectRoot: string, dataDir?: string): string {
+  return path.join(gdgraphDataDir(projectRoot, dataDir), "artifacts");
+}

package/src/gdgraph/enrich.ts

@@ -17,6 +17,7 @@ import {
   type CapabilitySpec,
 } from "../capability/seam";
 import { loadGdgraphConfig } from "./config";
+import { gdgraphStorageDir } from "./data-dir";
 import {
   createTreesitterSpec,
   resolveTreesitterCapability,
@@ -45,6 +46,7 @@ export async function enrichBuildWithSymbols(
   // `resolveTreesitterCapability`; tests pass an explicit `CapabilityResolver`
   // (e.g. a mock adapter, or the raw seam) to bypass it.
   resolve?: CapabilityResolver,
+  dataDir?: string,
 ): Promise<EnrichResult> {
   const config = await loadGdgraphConfig(cwd);
   const treesitterConfig = {
@@ -76,12 +78,12 @@ export async function enrichBuildWithSymbols(
     () => ({ symbols: [], calls: [] }),
   );
 
-  await writeSymbolLayer(cwd, layer);
+  await writeSymbolLayer(cwd, layer, dataDir);
   return { enriched: true, symbols: layer.symbols.length, calls: layer.calls.length };
 }
 
-async function writeSymbolLayer(cwd: string, layer: SymbolLayer): Promise<void> {
-  const storageDir = path.join(cwd, ".metaproject", "data", "gdgraph", "storage");
+async function writeSymbolLayer(cwd: string, layer: SymbolLayer, dataDir?: string): Promise<void> {
+  const storageDir = gdgraphStorageDir(cwd, dataDir);
   await mkdir(storageDir, { recursive: true });
   await writeFile(
     path.join(storageDir, "symbols.jsonl"),

package/src/gdgraph/query.ts

@@ -10,10 +10,11 @@ import type {
   WikiPageNode,
 } from "./types";
 import { TYPE_ONLY_IMPORT_KIND } from "./types";
+import { gdgraphStorageDir } from "./data-dir";
 import { resolveGraphTarget } from "./target";
 
-export async function loadGraph(projectRoot: string): Promise<GraphData> {
-  const storageDir = path.join(projectRoot, ".metaproject", "data", "gdgraph", "storage");
+export async function loadGraph(projectRoot: string, dataDir?: string): Promise<GraphData> {
+  const storageDir = gdgraphStorageDir(projectRoot, dataDir);
   const nodes = await readJsonl<GraphNode>(path.join(storageDir, "nodes.jsonl"));
   const edges = await readJsonl<GraphEdge>(path.join(storageDir, "edges.jsonl"));
   // B1 symbol layer: loaded ONLY if present. Missing files ⇒ empty/omitted layer

package/src/gdgraph/staleness.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { revisionOperand } from "../lib/git-revision";
 import { gitCmd, gitHead, readProvenance } from "../sync/provenance";
 
 // W7 AC4 follow-up (flow 304 T8) — a real, previously-latent defect found
@@ -237,7 +238,13 @@ async function committedChangedFiles(
   // "HEAD moved" reason. `--name-only -z` lists only the destination path per
   // entry even for a rename (unlike `git status -z`, which pairs it with an
   // orig-path field), so this stays a plain NUL-split with no pairing logic.
-  const diff = await gitCmd(cwd, ["diff", "--name-only", "-z", fromCommit, toCommit]);
+  let diff: string | null;
+  try {
+    diff = await gitCmd(cwd, ["diff", "--name-only", "-z", ...revisionOperand(fromCommit), toCommit]);
+  } catch {
+    // A provenance commit that reads as an option is refused by revisionOperand; this check never throws.
+    return [];
+  }
   if (diff === null) {
     return [];
   }

package/src/gdgraph/wiki-layer.ts

@@ -15,6 +15,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { gdgraphStorageDir } from "./data-dir";
 import { collectPages } from "../wiki/collect";
 import { computeModuleKeyFiles } from "../wiki/collect";
 import { resolveDescribeSet } from "../wiki/describes";
@@ -25,8 +26,8 @@ export const WIKI_PAGES_FILE = "wiki-pages.jsonl";
 export const DESCRIBES_FILE = "describes.jsonl";
 export const BUILD_MANIFEST_FILE = "build-manifest.json";
 
-function storageDir(projectRoot: string): string {
-  return path.join(projectRoot, ".metaproject", "data", "gdgraph", "storage");
+function storageDir(projectRoot: string, dataDir?: string): string {
+  return gdgraphStorageDir(projectRoot, dataDir);
 }
 
 /**
@@ -181,8 +182,10 @@ export async function enrichBuildWithWikiLayer(input: {
   /** Injected in tests; defaults to the real `validModuleNames`. */
   validModules?: Set<string> | undefined;
   loadValidModules?: (projectRoot: string) => Promise<Set<string> | undefined>;
+  /** A gdgraph data directory other than the project's own (a review package's graph). */
+  dataDir?: string;
 }): Promise<WikiLayer> {
-  const dir = storageDir(input.projectRoot);
+  const dir = storageDir(input.projectRoot, input.dataDir);
   await mkdir(dir, { recursive: true });
 
   const mtimes = new Map<string, number>();
@@ -205,7 +208,7 @@ export async function enrichBuildWithWikiLayer(input: {
   const validModules =
     input.validModules !== undefined
       ? input.validModules
-      : await (input.loadValidModules ?? defaultLoadValidModules)(input.projectRoot);
+      : await (input.loadValidModules ?? ((root) => defaultLoadValidModules(root, input.dataDir)))(input.projectRoot);
 
   const wikiPages = await collectPages(input.projectRoot);
   const contents = new Map<string, string>();
@@ -236,9 +239,9 @@ export async function enrichBuildWithWikiLayer(input: {
   return layer;
 }
 
-async function defaultLoadValidModules(projectRoot: string): Promise<Set<string> | undefined> {
+async function defaultLoadValidModules(projectRoot: string, dataDir?: string): Promise<Set<string> | undefined> {
   // Dynamic so `gdgraph` keeps no static dependency on `wiki/service`, which
   // reads the graph itself — the same cycle-avoidance the symbol layer uses.
   const { validModuleNames } = await import("../wiki/service");
-  return validModuleNames(projectRoot);
+  return validModuleNames(projectRoot, dataDir);
 }

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

@@ -23,7 +23,7 @@ license: "MIT"
 
 ## Preflight
 
-Run in the main session: this skill dispatches workers. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+Run in the main session: this skill dispatches workers. Without a subagent-spawn tool (`Agent`, `spawn_subagent` or the host's equivalent), or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
 
 ## Purpose
 
@@ -560,7 +560,7 @@ the bound plus an escalation — never an unbounded loop.
    **0.820 -> 0.673** across two forced revisions while cumulative ever-correct
    is **0.847** ([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)) — the
    agent finds the fix and then destroys it, throwing away ~15 points by not
-   stopping. Aider hardcodes `max_reflections = 3`; OpenHands' critic uses 3.
+   stopping. Other agent tools hardcode the same bound (`max_reflections = 3`).
    Rounds four through six of a self-fix loop were not buying convergence; they
    were buying regressions. Review rounds are the exception, as stated above.
 
@@ -690,5 +690,5 @@ Stop and re-read this skill if you are thinking:
 | "Tests pass and the review is clean, so I'll open the PR and complete the flow." | Phase 4 stops and asks the user how the flow should end; not every flow wants a PR. And completion requires a confirmed merge into the base branch captured at creation — not a green local run. |
 | "The worker returned BLOCKED twice — faster if I implement this task myself." | The implementer never self-accepts and the orchestrator never implements. Block the flow, escalate one concise question, then unblock and re-dispatch. Doing the work here erases the boundary the whole flow model rests on. |
 | "Verification is described in the plan, so it will happen." | A verification step in the plan is a task, not a sentence. If it is not a task with a status, nothing records whether it ran, and the flow reaches `implemented` with an unrun gate. |
-| "The review fan-out is cheap, so the budget check can wait." | `keryx review budget --spent … --outstanding …` gates the fan-out, and `review-orchestrator` nests under this skill where keryx cannot see the in-flight subagents. Skipping the check means the cap bounds nothing. |
+| "The review fan-out is cheap, so the budget check can wait." | `keryx review budget --spent … --outstanding …` gates the fan-out, and `review-orchestrator` runs inline in this same main session, where keryx cannot see the in-flight subagents; declare them with `--outstanding`. Skipping the check means the cap bounds nothing. |
 | "I'll set the verification kind later." | An `unclassified` criterion cannot become data afterwards without a recorded rewrite: `keryx flow ac update <id> --criterion ACn --text "…" --reason "<why>"`. Put the `[verify: …]` marker on every criterion before `flow freeze`. |

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

@@ -26,7 +26,7 @@ license: "MIT"
 
 ## Preflight
 
-Run in the main session: this skill dispatches sub-agents. Without the `Agent` tool, or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
+Run in the main session: this skill dispatches sub-agents. Without a subagent-spawn tool (`Agent`, `spawn_subagent` or the host's equivalent), or with the depth budget spent (Claude Code nests at most 3 deep), the whole output is this line, with no tool calls and no work of your own: `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`
 
 ## Purpose
 
@@ -1262,8 +1262,8 @@ Three is the self-fix bound `task-implementer` and this skill share
 most achievable gains"* ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197));
 correctness falls **0.820 -> 0.673** across two forced revisions while
 cumulative ever-correct is **0.847**
-([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Aider hardcodes
-`max_reflections = 3`; OpenHands' critic uses 3.
+([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)). Other agent tools
+hardcode the same bound (`max_reflections = 3`).
 
 The bound is a ceiling, not a target. Repetition ends the loop earlier and
 **regardless of remaining iterations** — a counter cannot tell "converging

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

@@ -22,7 +22,7 @@ Phase 2: Execute plan, bracketing every step with keryx job step:
      ├─ git worktree add → feature branch (NEVER git checkout -b)
      ├─ FOR EACH wave → [tests-creator × tasks] then [task-implementer × tasks]
      ├─ [code-verifier sub-agent] → quality gate
-     ├─ keryx review start → [review-orchestrator sub-agent] → keryx review ingest
+     ├─ keryx review start → [review-orchestrator, inline] → keryx review ingest
      ├─ IF blocker/major → [task-implementer (fix)] → next managed round (max 3)
      ├─ keryx review complete --finding … --disposition … --evidence …
      └─ keryx job document → each step's artifact recorded in the package
@@ -162,7 +162,7 @@ keryx review scope        --ref "$BASE_SHA" --json > scope.json
 keryx review blast-radius --ref "$BASE_SHA" --json > blast-radius.json    # KEEP BOTH
 keryx review stack --json                                                # which reviewers apply
 keryx review tier  --scope <scope> --diff-lines <n> --json                # model per dispatch
-# dispatch review-orchestrator (skills/gdskills/review/review-orchestrator/SKILL.md);
+# run review-orchestrator inline (skills/gdskills/review/review-orchestrator/SKILL.md);
 # it runs review-verifier in Wave C and emits the ```json keryx:findings``` block
 keryx review ingest --report <report.md> --ref <feature-branch> --head <sha> \
   --scope scope.json --blast-radius blast-radius.json \

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.md

@@ -368,8 +368,8 @@ account for most achievable gains"*
 ([arXiv:2607.05197](https://arxiv.org/abs/2607.05197)); correctness falls
 **0.820 -> 0.673** across two forced revisions while cumulative ever-correct is
 **0.847** ([arXiv:2607.24604](https://arxiv.org/abs/2607.24604)) — the agent
-finds the fix and then destroys it. Aider hardcodes `max_reflections = 3`;
-OpenHands' critic uses 3.
+finds the fix and then destroys it. Other agent tools hardcode the same bound
+(`max_reflections = 3`).
 
 **Stop earlier on repetition, whatever the count says.** If an attempt produces
 the same failure output as the previous attempt — the same failing test with the
@@ -435,8 +435,8 @@ Write full JSON to `<JOBS_ROOT>/<JOB_NAME>/results/<task_id>.json`:
 Set `skill_drift` from Phase 2.0b: if the project-skill you used was not `fresh`, or the code you wrote diverged from what a skill documents, name the skill and the divergence. The orchestrator uses this to decide whether to trigger `skills learn` (do NOT run `learn` yourself — it is a mutating step the orchestrator dispatches; see `rules/core/skill-lifecycle.mdc`).
 
 Three of those fields have a bar, and a field that collects noise trains the
-reader to skim all three. Omit one rather than pad it. The trio is adapted (MIT)
-from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) as contract fields rather than a free-text template; the bars below are ours.
+reader to skim all three. Omit one rather than pad it. The trio is adapted (MIT;
+see THIRD_PARTY_NOTICES.md) as contract fields rather than a free-text template; the bars below are ours.
 
 - `assumptions` — what you assumed where the task was silent AND acted on. If
   the assumption being wrong would not change a line you wrote, it is a hedge,

package/src/gdskills/bundled/skills/planning/autodoc-orchestrator/SKILL.md

@@ -20,7 +20,7 @@ metadata:
   version: 1.0.0
 ---
 
-**Preflight:** run in the main session. Without the `Agent` tool or depth budget, output only `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`, with no tool calls.
+**Preflight:** run in the main session. Without a subagent-spawn tool (`Agent`, `spawn_subagent` or the host's equivalent) or depth budget, output only `STATUS: BLOCKED nested_dispatch_unavailable — run this skill in the main session`, with no tool calls.
 
 # autodoc-orchestrator
 

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.md

@@ -93,8 +93,8 @@ Before the first question, check whether a host can show it: the `ask_user` tool
 
 - **Host present:** ask every question through `ask_user`, one per call, with the A/B/C/D options as its options.
 - **No host:** ask NO question, not even in plain text; nobody is there to answer it. Return `status: "NEEDS_CONTEXT"` with the `assumptions` you would have asked about (question, assumption, `confidence: "assumption"`), `ready_to_proceed: false`. The caller decides.
-- A cancelled or empty `ask_user` answer is not an answer: record it as an assumption and stop asking.
-- Each `ask_user` question is recorded in the recommendation journal by the tool itself (source, arm, recommendation, answer); you do not record it. `src/decisions/interviewer-path.test.ts` pins this path through the agent's real tool roster.
+- A "No one was asked", cancelled or empty `ask_user` answer is not an answer: record it as an assumption and stop asking.
+- Each `ask_user` question a person answers is recorded in the recommendation journal by the tool itself (source, arm, recommendation, answer); you do not record it. A question the model answered itself under `/mode auto` never reached a person and is not journaled: treat its answer as an assumption, not a decision. `src/decisions/interviewer-path.test.ts` pins this path through the agent's real tool roster.
 
 ## Question Bank by Goal Type
 
@@ -110,7 +110,7 @@ Stop and re-read this skill if you are thinking:
 |---|---|
 | "These three questions are related, so I'll ask them in one message to save time." | One question at a time is the rule, and it is not politeness. A batch gets one answer to the easiest item and silence on the rest, which you then record as if it had been answered. |
 | "The answer was vague, but I understood the gist, so `ready_to_proceed: true`." | A gist is an assumption. Either ask the follow-up, or record the item in `blockers` with `confidence: "assumption"` and leave `ready_to_proceed` false. Proceeding on a gist is exactly the wasted work this gate exists to prevent. |
-| "They said 'sure, that sounds about right', so that is a yes and `ready_to_proceed: true`." | A hedge is not a refusal and it is not approval. This is not the vague-answer case above — you understood the answer perfectly, and it committed the user to nothing. Name the hedge back ("that is a 'probably' — is it a yes?") and ask the question that forces one. If no commitment comes, the item is recorded as `confidence: "assumption"`, never as confirmation. (That a hedged agreement is not approval is adapted (MIT) from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills); naming the hedge back and the confidence enum are ours.) |
+| "They said 'sure, that sounds about right', so that is a yes and `ready_to_proceed: true`." | A hedge is not a refusal and it is not approval. This is not the vague-answer case above — you understood the answer perfectly, and it committed the user to nothing. Name the hedge back ("that is a 'probably' — is it a yes?") and ask the question that forces one. If no commitment comes, the item is recorded as `confidence: "assumption"`, never as confirmation. (That a hedged agreement is not approval is adapted (MIT; see THIRD_PARTY_NOTICES.md); naming the hedge back and the confidence enum are ours.) |
 | "I inferred the answer from the codebase, so I can mark it `certain`." | `certain` means the user said it. An inference is `assumption`, even a good one — the confidence field is the only signal downstream skills have about which parts of `derived_context` are load-bearing guesses. |
 | "I've hit the 8-question limit and still don't know, so I'll pick the likely answer." | The limit is a stop rule, not a licence to invent. Remaining unknowns go into `blockers`, `ready_to_proceed` goes false, and the caller decides. |
 | "Context-collector already ran, so anything still missing must not matter." | Collected context answers what the codebase knows, not what the user intends. Scope, priority and what must NOT change are never in the codebase, and those are the answers that change the approach. |

package/src/gdskills/bundled/skills/quality/api-truth/SKILL.md

@@ -221,6 +221,6 @@ Do not report the work as done until all of these hold:
   upgrade decision for the dependency's owner, and no version was bumped inside
   this change to obtain it.
 
-Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
-(MIT) is where the pairing comes from — check the dependency before calling it,
+Credit: an MIT-licensed skills library (see THIRD_PARTY_NOTICES.md) is where
+the pairing comes from — check the dependency before calling it,
 and mark what went out unchecked. The ranks and the version rule are ours.

package/src/gdskills/bundled/skills/quality/deprecation-path/SKILL.md

@@ -263,6 +263,6 @@ Do not report the work as done until all of these hold:
   — a guess dressed as a schedule is neither — and the caller has the
   before-and-after to migrate unaided, under behaviour unchanged under them.
 
-Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
-(MIT) is why this set carries a deprecation skill at all; the five stages and
-the notice rule were measured from keryx's own CLI, not taken from there.
+Credit: an MIT-licensed skills library (see THIRD_PARTY_NOTICES.md) is why this
+set carries a deprecation skill at all; the five stages and the notice rule
+were measured from keryx's own CLI, not taken from there.

package/src/gdskills/bundled/skills/quality/fresh-eyes/SKILL.md

@@ -185,6 +185,6 @@ A cycle is complete only when all of these hold:
 - If the cycle found nothing, it says so plainly, with what was checked and what
   was left unreached. `STATUS: NO FINDINGS` is a pass, not an incomplete run.
 
-Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
-(MIT) is where the in-flight doubt pass comes from: a reader gets the artifact
+Credit: an MIT-licensed skills library (see THIRD_PARTY_NOTICES.md) is where
+the in-flight doubt pass comes from: a reader gets the artifact
 and the contract, never the author's reasoning. The bar and the bound are ours.

package/src/gdskills/bundled/skills/quality/perf-check/SKILL.md

@@ -77,7 +77,7 @@ Flag heavy dependencies:
 ## Rules
 
 - Don't make changes — only analyze and report
-- An optimisation that measures neutral is reported with revert as its recommended fix, not as harmless. The burden is on keeping it, never on dropping it: it leaves the code more complicated than it found it, and it survives review precisely because nothing is wrong with it. This rule and the ledger two bullets down are adapted (MIT) from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills); the noise definition and the groundwork exception are ours
+- An optimisation that measures neutral is reported with revert as its recommended fix, not as harmless. The burden is on keeping it, never on dropping it: it leaves the code more complicated than it found it, and it survives review precisely because nothing is wrong with it. This rule and the ledger two bullets down are adapted (MIT; see THIRD_PARTY_NOTICES.md); the noise definition and the groundwork exception are ours
 - Neutral is a delta that does not clear the noise. Take the before reading three times on one named workload and keep the spread; any after-delta inside that spread is neutral. Indistinguishable from zero is the same verdict as zero, not a smaller win — say which it was, and how many runs said so
 - Record the attempt in the flow journal (`.metaproject/flows/<flow>/journal.md`), in the same change as the revert: what was tried, the before and after with the command and the workload that produced them, and why it did not help *here*. "Tried caching, didn't help" is worse than no entry — it forecloses the idea for the next agent and leaves them nothing to overturn it with
 - Groundwork is the only exception: a neutral change survives when the change it is a prerequisite for is in the same branch and the two measure a win together. A payoff promised for later is not a measurement — revert, and record what the pair would have to show

package/src/gdskills/bundled/skills/quality/root-cause/SKILL.md

@@ -199,6 +199,6 @@ Report the defect fixed only when all of these hold:
   the evidence and its class, the surviving hypotheses with their killing
   observations, and the instrumentation that would settle it.
 
-Credit: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)
-(MIT) is why this set carries a debugging skill at all; the step order, the
+Credit: an MIT-licensed skills library (see THIRD_PARTY_NOTICES.md) is why
+this set carries a debugging skill at all; the step order, the
 evidence classes and the non-reproduction protocol were written here, not taken.

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

@@ -348,21 +348,7 @@ STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 
 ## Job Context Awareness
 
-When dispatched by `review-orchestrator` or `job-orchestrator`, the prompt MAY include:
-
-```
-JOB_NAME:     <job-name>
-CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md
-```
-
-If provided and the file exists, read the context document **before** reviewing the diff.
-Use it to:
-- Understand which architectural patterns and layers were intentionally chosen
-- Avoid flagging deliberate deviations from the default layer model as violations
-- Identify framework and library choices that affect what counts as a valid pattern
-
-If absent, proceed normally — context is optional and non-blocking.
-When in doubt about whether a pattern was intentional, use `info` severity and note the uncertainty.
+When dispatched by `review-orchestrator` or `job-orchestrator`, the prompt MAY carry `JOB_NAME` and `CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md`. If given and the file exists, read it before you start; use it for intentional design decisions (do not flag correct library usage), acceptance criteria when there is no `issue_url`, and the severity of edge cases the team accepted. If absent, proceed normally: context is optional and non-blocking.
 
 ---
 
@@ -377,3 +363,16 @@ When in doubt about whether a pattern was intentional, use `info` severity and n
 | "The team probably didn't intend this pattern" | Unless the context doc or a clear rule says otherwise, assume intentional; use `info` if unsure |
 | "NestJS global module is always wrong" | `@Global()` is a violation only when used for non-global concerns; framework-provided globals are fine |
 | "I can't determine if this is wrong without knowing the full architecture" | Use `NEEDS_CONTEXT` status and ask one specific question |
+
+<!-- keryx:layers-block:start -->
+## Project layers: graph, tests, wiki, memory
+
+Your payload may carry a `layers` block for your files: the files the graph says are affected, symbol neighbours, related tests, the wiki pages that describe the files and the memory entries for their module. It is bounded, and `truncated` names what was cut and the command that fetches the rest. When the diff alone does not settle a question, ask the project. Each command below is read-only and calls no model.
+
+- `keryx gdgraph affected <file>`: who depends on the file. Use it before you call a change contained, and whenever a changed export, signature or behaviour may have callers outside your files.
+- `keryx test related <file>`: the tests that cover the file. Use it before you say a behaviour is untested, and to judge whether a test would fail if the code broke.
+- `keryx wiki ask "<q>"`: what the project wiki says a module is for and which rules bind it. Use it when the intent of the code is unclear and the diff does not state it.
+- `keryx memory search "<q>"`: recorded lessons, decisions and known mistakes. Use it before you report a pattern the project may already have decided on, and when a failure looks like one it has seen.
+
+In a review package, `keryx gdgraph affected <file> --data-dir <package>/layers/graph` reads the graph built at the PR head; the tracked graph may be from another commit. A finding still rests on the code you read: what a layer says is a lead, not evidence. If a layer is empty or a command fails, say so in the report instead of guessing.
+<!-- keryx:layers-block:end -->

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

@@ -338,20 +338,7 @@ STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 
 ## Job Context Awareness
 
-When dispatched by `job-orchestrator` or called with an explicit context path, the prompt MAY include:
-
-```
-JOB_NAME:     <job-name>
-CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md
-```
-
-If provided and the file exists, read the context document **before** running scope detection.
-Use it to understand:
-- Which ORM, validation library, or guard strategy was intentionally chosen
-- Project-level architectural decisions (e.g., no repository pattern by design)
-- Acceptance criteria to verify spec compliance
-
-If absent, proceed normally — context is optional and non-blocking.
+When dispatched by `review-orchestrator` or `job-orchestrator`, the prompt MAY carry `JOB_NAME` and `CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md`. If given and the file exists, read it before you start; use it for intentional design decisions (do not flag correct library usage), acceptance criteria when there is no `issue_url`, and the severity of edge cases the team accepted. If absent, proceed normally: context is optional and non-blocking.
 
 ---
 
@@ -364,3 +351,16 @@ If absent, proceed normally — context is optional and non-blocking.
 | "The controller has some logic but it's minor" | The line is binary — logic in controller = untestable without HTTP stack |
 | "Stack trace in response only shows in dev" | Config can be wrong in prod; treat it as blocker always |
 | "I'll skip the migration check — it's just a column rename" | Column renames without fallback break zero-downtime deploys |
+
+<!-- keryx:layers-block:start -->
+## Project layers: graph, tests, wiki, memory
+
+Your payload may carry a `layers` block for your files: the files the graph says are affected, symbol neighbours, related tests, the wiki pages that describe the files and the memory entries for their module. It is bounded, and `truncated` names what was cut and the command that fetches the rest. When the diff alone does not settle a question, ask the project. Each command below is read-only and calls no model.
+
+- `keryx gdgraph affected <file>`: who depends on the file. Use it before you call a change contained, and whenever a changed export, signature or behaviour may have callers outside your files.
+- `keryx test related <file>`: the tests that cover the file. Use it before you say a behaviour is untested, and to judge whether a test would fail if the code broke.
+- `keryx wiki ask "<q>"`: what the project wiki says a module is for and which rules bind it. Use it when the intent of the code is unclear and the diff does not state it.
+- `keryx memory search "<q>"`: recorded lessons, decisions and known mistakes. Use it before you report a pattern the project may already have decided on, and when a failure looks like one it has seen.
+
+In a review package, `keryx gdgraph affected <file> --data-dir <package>/layers/graph` reads the graph built at the PR head; the tracked graph may be from another commit. A finding still rests on the code you read: what a layer says is a lead, not evidence. If a layer is empty or a command fails, say so in the report instead of guessing.
+<!-- keryx:layers-block:end -->

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

@@ -594,22 +594,7 @@ Stop and re-read these rules if you are thinking:
 
 ## Job Context Awareness
 
-When dispatched by `job-orchestrator` or `review-orchestrator` as part of a job pipeline, the prompt MAY include:
-
-```
-JOB_NAME:     <job-name>
-CONTEXT_PATH: <JOBS_ROOT>/<job-name>/ai/context.md
-```
-
-If provided and the file exists, read the context document before starting the review. Use it to:
-- Understand which MobX version and decorator configuration the project uses (legacy decorators vs. `makeObservable`)
-- Identify custom base store classes or lifecycle conventions that differ from defaults
-- Understand which accessibility standard the project targets (WCAG 2.1 AA vs. custom)
-- Identify intentional patterns that appear to violate rules but are documented exceptions
-- Validate findings against documented project-specific conventions
-
-If the file does not exist or is not provided, proceed normally — context is optional and non-blocking.
-
+When dispatched by `review-orchestrator` or `job-orchestrator`, the prompt MAY carry `JOB_NAME` and `CONTEXT_PATH: .metaproject/jobs/<job-name>/ai/context.md`. If given and the file exists, read it before you start; use it for intentional design decisions (do not flag correct library usage), acceptance criteria when there is no `issue_url`, and the severity of edge cases the team accepted. If absent, proceed normally: context is optional and non-blocking.
 
 ## Orchestrated Review Contract
 
@@ -617,3 +602,15 @@ When dispatched by `review-orchestrator`, follow the provided `reviewer-input.sc
 
 ---
 
+<!-- keryx:layers-block:start -->
+## Project layers: graph, tests, wiki, memory
+
+Your payload may carry a `layers` block for your files: the files the graph says are affected, symbol neighbours, related tests, the wiki pages that describe the files and the memory entries for their module. It is bounded, and `truncated` names what was cut and the command that fetches the rest. When the diff alone does not settle a question, ask the project. Each command below is read-only and calls no model.
+
+- `keryx gdgraph affected <file>`: who depends on the file. Use it before you call a change contained, and whenever a changed export, signature or behaviour may have callers outside your files.
+- `keryx test related <file>`: the tests that cover the file. Use it before you say a behaviour is untested, and to judge whether a test would fail if the code broke.
+- `keryx wiki ask "<q>"`: what the project wiki says a module is for and which rules bind it. Use it when the intent of the code is unclear and the diff does not state it.
+- `keryx memory search "<q>"`: recorded lessons, decisions and known mistakes. Use it before you report a pattern the project may already have decided on, and when a failure looks like one it has seen.
+
+In a review package, `keryx gdgraph affected <file> --data-dir <package>/layers/graph` reads the graph built at the PR head; the tracked graph may be from another commit. A finding still rests on the code you read: what a layer says is a lead, not evidence. If a layer is empty or a command fails, say so in the report instead of guessing.
+<!-- keryx:layers-block:end -->