@mrciphersmith/keryx 0.2.163 → 0.3.0

package/src/gdgraph/staleness.ts

@@ -1,7 +1,61 @@
+import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { gitCmd, gitHead, readProvenance } from "../sync/provenance";
 
+// W7 AC4 follow-up (flow 304 T8) — a real, previously-latent defect found
+// while wiring up the `modified` bucket below: `gitCmd`/`gitCmdResult`
+// (`../sync/provenance.ts`) both call `.trim()` on the ENTIRE stdout blob,
+// not per line. `git status --porcelain=v1`'s status code for an unstaged
+// content-only edit is TWO CHARACTERS WIDE, and the first is a literal space
+// (" M"); when that line is the first line of the output, the whole-string
+// trim silently eats that leading space — shifting every following character
+// left by one, corrupting BOTH the status-letter read (`line[0]`/`line[1]`)
+// and the reported path (`line.slice(3)`) for whichever file happens to sort
+// first. This was invisible before this task because nothing previously
+// asserted the SPECIFIC path a trigger named (only "some reason fired" —
+// `line[0]` after the shift often still happened to equal the status letter
+// being tested for `added`/`deleted`/`renamed`, purely by coincidence of
+// which letter shifted into position 0). `gitCmd` is shared by several other
+// callers and is out of this task's lane (`src/gdgraph/**`,
+// `src/commands/gdgraph*.ts` only) to change; this module instead spawns
+// `git status` itself and strips only the single trailing newline git always
+// terminates the last line with, never the leading byte of the first one.
+// F9 (fix round 1): with `core.quotePath` at its (default, on) setting, `git
+// status --porcelain` octal-escapes and double-quotes any path holding a
+// non-ASCII or otherwise "unusual" byte — e.g. `src/café.ts` prints as
+// `"src/caf\303\251.ts"`. The line-oriented parser below used to read that
+// quoted, escaped text as the literal path, so every `stat()` against it
+// missed (the real file on disk has no quotes or octal escapes in its name)
+// and the edit went unreported. `-z` (NUL-separated) output is never quoted
+// or escaped — git prints exact bytes — which sidesteps the whole unquoting
+// problem instead of implementing octal-unescaping here. It also removes the
+// newline-vs-content ambiguity `-z` output has no other use for line
+// splitting: an ordinary entry is `XY PATH\0`, but a rename/copy (X or Y is
+// `R`/`C`) is `XY PATH\0ORIG_PATH\0` — TWO NUL-terminated fields, not one —
+// which `categorizeStatusEntries` below accounts for.
+function gitStatusPorcelain(cwd: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    try {
+      const child = spawn("git", ["status", "--porcelain=v1", "-z"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+      let out = "";
+      child.stdout?.on("data", (chunk) => {
+        out += String(chunk);
+      });
+      child.on("error", () => resolve(null));
+      child.on("close", (code) => {
+        if (code !== 0) {
+          resolve(null);
+          return;
+        }
+        resolve(out.endsWith("\0") ? out.slice(0, -1) : out);
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
 // AFC-10 (flow 234, phase 2, frozen AC3): "a new commit, untracked, delete,
 // rename and config change invalidate the snapshot; an unknown target differs
 // from indexed/no-edges; a git error never becomes fresh."
@@ -25,14 +79,13 @@ import { gitCmd, gitHead, readProvenance } from "../sync/provenance";
 //                             on every commit/checkout/branch-switch, unlike
 //                             `.git/HEAD`'s own — when no provenance was
 //                             recorded for this build).
-//   - untracked/delete/rename: `git status --porcelain=v1`, categorized by
-//                             status letter. A plain in-place content edit
-//                             (` M`/`M `) is deliberately NOT a trigger here —
-//                             the module contract (`modules/gdgraph.md`,
-//                             "Freshness & Refresh") only promises the
-//                             file-level graph goes stale when the file SET
-//                             moves; an edit with an unchanged import set
-//                             leaves the file-level graph correct.
+//   - untracked/delete/rename/modify: `git status --porcelain=v1`, categorized
+//                             by status letter. A plain in-place content edit
+//                             (` M`/`M `) IS a trigger (W7 AC4 follow-up, flow
+//                             304 T8) — but only when the file's own mtime
+//                             postdates the build, so an edit already on disk
+//                             when `gdgraph build` ran (already reflected in
+//                             the graph) does not false-stale it.
 //   - config change:          `.metaproject/gdgraph.config.json`'s mtime vs
 //                             `nodes.jsonl`'s. No separate baseline write is
 //                             needed for this: the config file only *has* a
@@ -62,7 +115,8 @@ function gdgraphConfigPath(cwd: string): string {
 // Categorize `git status --porcelain=v1` lines. Each line is exactly two
 // status characters (index status, worktree status) followed by a space and
 // the path (renames add " -> newPath"). A pure content modify (` M`/`M `/`MM`)
-// intentionally does not set any of these three — see the module doc above.
+// goes into its own `modified` bucket — see the module doc above and the
+// caller's mtime gate.
 //
 // Lines under `.metaproject/` are skipped entirely: that tree holds gdgraph's
 // OWN generated bookkeeping (`.provenance.json`, `artifacts/*`), which the
@@ -79,39 +133,118 @@ function gdgraphConfigPath(cwd: string): string {
 // project root IS the git root; `rootPrefix` (from `git rev-parse
 // --show-prefix`, empty at the git root) is prepended so the same exclusion
 // matches at both.
-function categorizeStatusLines(
-  porcelain: string,
+// W7 AC4 ("a reason naming the changed file"): the trigger buckets carry the
+// actual paths that tripped them, not just a boolean — a reader gets "which
+// file", not only "some file". `nameFiles` below turns a bucket into the
+// reason string, bounded the same way this codebase bounds every other
+// unbounded listing (a handful named, "+N more" beyond that).
+//
+// W7 AC4 follow-up (flow 304 T8): a pure content edit (` M`/`M `/`MM`) is now
+// its OWN bucket (`modified`) instead of being dropped — see the caller,
+// which promotes it to a trigger only when the file's mtime postdates the
+// build (a content edit already present at build time is already reflected
+// in the graph and must not false-stale it).
+//
+// F9 (fix round 1): entries come in NUL-separated (`-z`) from
+// `gitStatusPorcelain`, never quoted/escaped, so there is no quote-stripping
+// left to do here — the previous `.replace(/^"|"$/g, "")` existed only to
+// undo the quoting `-z` never produces in the first place. A rename/copy
+// entry (X or Y is `R`/`C`) is TWO consecutive NUL-terminated fields — the
+// new path, then the original path — not one "old -> new" line; `entries[i +
+// 1]` below consumes that second field so it is never misread as its own
+// unrelated status entry.
+function categorizeStatusEntries(
+  entries: string[],
   rootPrefix: string,
-): { added: boolean; deleted: boolean; renamed: boolean } {
-  const lines = porcelain.split("\n").filter((line) => line.length >= 2);
+): { added: string[]; deleted: string[]; renamed: string[]; modified: string[] } {
   const metaprojectPrefix = `${rootPrefix}.metaproject/`;
-  let added = false;
-  let deleted = false;
-  let renamed = false;
-  for (const line of lines) {
-    const indexStatus = line[0];
-    const worktreeStatus = line[1];
-    const rawPath = line.slice(3);
-    // For a rename, porcelain prints "old -> new"; check the side(s) that
-    // matter for the metaproject exclusion (either is enough to skip a pure
-    // internal-bookkeeping rename, which does not occur in practice anyway).
-    const isMetaprojectPath = rawPath
-      .split(" -> ")
-      .some((candidate) => candidate.replace(/^"|"$/g, "").startsWith(metaprojectPrefix));
+  const added: string[] = [];
+  const deleted: string[] = [];
+  const renamed: string[] = [];
+  const modified: string[] = [];
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i] ?? "";
+    if (entry.length < 2) {
+      continue;
+    }
+    const indexStatus = entry[0];
+    const worktreeStatus = entry[1];
+    const rawPath = entry.slice(3);
+    // Renames AND copies (X or Y is `R`/`C`) both carry a second, orig-path
+    // field in `-z` output — it must be consumed here regardless of which
+    // bucket (if any) the entry itself lands in below, or the next loop
+    // iteration would misparse that orig-path field as its own status entry.
+    const hasOrigPathField =
+      indexStatus === "R" || worktreeStatus === "R" || indexStatus === "C" || worktreeStatus === "C";
+    const origPath = hasOrigPathField ? entries[i + 1] ?? null : null;
+    if (hasOrigPathField) {
+      i += 1;
+    }
+    const isMetaprojectPath = [rawPath, origPath]
+      .filter((candidate): candidate is string => candidate !== null)
+      .some((candidate) => candidate.startsWith(metaprojectPrefix));
     if (isMetaprojectPath) {
       continue;
     }
     if (indexStatus === "?" || worktreeStatus === "?" || indexStatus === "A") {
-      added = true;
+      added.push(rawPath);
+      continue;
     }
     if (indexStatus === "D" || worktreeStatus === "D") {
-      deleted = true;
+      deleted.push(rawPath);
+      continue;
     }
     if (indexStatus === "R" || worktreeStatus === "R") {
-      renamed = true;
+      renamed.push(rawPath);
+      continue;
+    }
+    if (indexStatus === "M" || worktreeStatus === "M") {
+      modified.push(rawPath);
     }
   }
-  return { added, deleted, renamed };
+  return { added, deleted, renamed, modified };
+}
+
+const REASON_FILE_DISPLAY_LIMIT = 5;
+
+function nameFiles(message: string, files: string[]): string {
+  if (files.length === 0) {
+    return message;
+  }
+  const shown = files.slice(0, REASON_FILE_DISPLAY_LIMIT).join(", ");
+  const overflow = files.length > REASON_FILE_DISPLAY_LIMIT
+    ? ` (+${files.length - REASON_FILE_DISPLAY_LIMIT} more)`
+    : "";
+  return `${message}: ${shown}${overflow}`;
+}
+
+// W7 AC4 follow-up: when `provenance.commit !== head.commit`, name which
+// file(s) actually moved between the two, the same way the working-tree
+// triggers already do — a caller told "HEAD moved" without knowing which
+// files still has to run a full diff itself to find out. One extra git call,
+// gated behind the already-uncommon "commit moved" branch (never on the
+// common clean/fresh path), so this stays within the module's own
+// cheap-probe budget.
+async function committedChangedFiles(
+  cwd: string,
+  fromCommit: string,
+  toCommit: string,
+  rootPrefix: string,
+): Promise<string[]> {
+  // F9: `-z` here too — `--name-only` quotes/octal-escapes an unusual path
+  // (e.g. `src/café.ts` → `"src/caf\303\251.ts"`) exactly like `git status`
+  // does, which fed a mismatched, unstat-able path into `nameFiles` for the
+  // "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]);
+  if (diff === null) {
+    return [];
+  }
+  const metaprojectPrefix = `${rootPrefix}.metaproject/`;
+  return diff
+    .split("\0")
+    .filter((entry) => entry.length > 0 && !entry.startsWith(metaprojectPrefix));
 }
 
 /**
@@ -149,7 +282,28 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
   // provenance is honestly advanced, an ADVANCING mismatch here really does
   // mean the graph predates HEAD, and this is exactly the check the wiki gate
   // (`../wiki/staleness.ts`) needs to keep trusting for that.
+  // W7 AC4 (PART A item 3): a graph that DID record provenance and then had
+  // `.provenance.json` deleted (or one that was never recorded at all) has no
+  // reliable "did the commit move" signal any more — only the best-effort
+  // `.git/logs/HEAD` mtime fallback below, which is silent whenever the build
+  // happened to run after the last commit (the common, unremarkable case).
+  // Before this fix, that silence made the whole check return `fresh` with no
+  // trace that the one strong freshness signal (a recorded baseline commit)
+  // was missing — exactly the "silently reads as confirmed-current" outcome
+  // this module's own contract says a check must never produce. `provenanceMissing`
+  // is set whenever there is nothing to compare HEAD against; if nothing else
+  // below turns up a concrete reason, the result downgrades from `fresh` to
+  // `unknown` (a weaker claim — "not verified", not "confirmed stale") rather
+  // than staying silently fresh.
+  let provenanceMissing = false;
   const head = await gitHead(cwd);
+  // T19 finding 3: `--show-prefix` is the project root's path relative to the
+  // git root (empty string AT the git root) — needed both here (to scope a
+  // commit-range diff to real source, excluding the graph's own bookkeeping)
+  // and below (the working-tree `.metaproject/` exclusion). Fetched once and
+  // reused, so this stays within the module's stated "one or two git calls"
+  // budget rather than asking twice.
+  const rootPrefix = head !== null ? ((await gitCmd(cwd, ["rev-parse", "--show-prefix"])) ?? "") : "";
   if (head === null) {
     gitFailed = true;
     reasons.push("git rev-parse HEAD failed (not a git repository, or git is unavailable)");
@@ -157,11 +311,16 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
     const provenance = await readProvenance(cwd, "gdgraph");
     if (provenance) {
       if (provenance.commit !== head.commit) {
+        const changedFiles = await committedChangedFiles(cwd, provenance.commit, head.commit, rootPrefix);
         reasons.push(
-          `HEAD moved since the graph was built (built at ${provenance.commit.slice(0, 12)}, now ${head.commit.slice(0, 12)})`,
+          nameFiles(
+            `HEAD moved since the graph was built (built at ${provenance.commit.slice(0, 12)}, now ${head.commit.slice(0, 12)})`,
+            changedFiles,
+          ),
         );
       }
     } else {
+      provenanceMissing = true;
       // No recorded build provenance for this graph. Fall back to the
       // reflog's mtime: unlike `.git/HEAD` (a symbolic ref whose content is
       // usually just "ref: refs/heads/<branch>" and does not change on an
@@ -176,24 +335,57 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
     }
   }
 
-  // --- untracked / deleted / renamed ----------------------------------------
-  const porcelain = await gitCmd(cwd, ["status", "--porcelain=v1"]);
+  // --- untracked / deleted / renamed / modified ------------------------------
+  const porcelain = await gitStatusPorcelain(cwd);
   if (porcelain === null) {
     gitFailed = true;
     reasons.push("git status failed");
   } else {
-    // T19 finding 3: `--show-prefix` is the project root's path relative to
-    // the git root (empty string AT the git root, "packages/proj/" style
-    // below it) — exactly the prefix `git status --porcelain`'s repo-root-
+    // `rootPrefix` (fetched once, above) is the project root's path relative
+    // to the git root — exactly what `git status --porcelain`'s repo-root-
     // relative paths need for the `.metaproject/` exclusion to match
-    // regardless of where the project root sits. A failed/non-git lookup
-    // (already caught above by the HEAD/status checks) falls back to "",
-    // preserving today's at-the-root behavior rather than under-excluding.
-    const rootPrefix = (await gitCmd(cwd, ["rev-parse", "--show-prefix"])) ?? "";
-    const { added, deleted, renamed } = categorizeStatusLines(porcelain, rootPrefix);
-    if (added) reasons.push("an untracked or newly added file exists in the working tree");
-    if (deleted) reasons.push("a tracked file was deleted in the working tree");
-    if (renamed) reasons.push("a file was renamed (staged) in the working tree");
+    // regardless of where the project root sits (T19 finding 3).
+    // `-z` output is NUL-separated (never newline-separated, and a filename
+    // can itself contain "\n"), so entries are split on "\0", not "\n".
+    const entries = porcelain.split("\0").filter((entry) => entry.length > 0);
+    const { added, deleted, renamed, modified } = categorizeStatusEntries(entries, rootPrefix);
+    if (added.length > 0) {
+      reasons.push(nameFiles("an untracked or newly added file exists in the working tree", added));
+    }
+    if (deleted.length > 0) {
+      reasons.push(nameFiles("a tracked file was deleted in the working tree", deleted));
+    }
+    if (renamed.length > 0) {
+      reasons.push(nameFiles("a file was renamed (staged) in the working tree", renamed));
+    }
+    // W7 AC4 follow-up (flow 304 T8): a pure content edit is a trigger too,
+    // but ONLY when the file's own mtime postdates the graph's build — an
+    // edit already on disk when `gdgraph build` ran is already reflected in
+    // the graph; re-flagging it would false-stale every build whose source
+    // tree was not pristine (i.e. nearly all of them). `nodesStat.mtimeMs` is
+    // this module's existing build-time proxy (already used for the config-
+    // change check below), reused here rather than introducing a second
+    // "when was it built" concept.
+    if (modified.length > 0) {
+      const postBuildEdits: string[] = [];
+      for (const displayPath of modified) {
+        const projectRelative = rootPrefix && displayPath.startsWith(rootPrefix)
+          ? displayPath.slice(rootPrefix.length)
+          : rootPrefix
+            ? null // outside this project's subtree in the repo — not ours to report
+            : displayPath;
+        if (projectRelative === null) {
+          continue;
+        }
+        const fileStat = await stat(path.join(cwd, projectRelative)).catch(() => null);
+        if (fileStat && fileStat.mtimeMs > nodesStat.mtimeMs) {
+          postBuildEdits.push(displayPath);
+        }
+      }
+      if (postBuildEdits.length > 0) {
+        reasons.push(nameFiles("a tracked file was modified since the graph was built", postBuildEdits));
+      }
+    }
   }
 
   // --- config changed ---------------------------------------------------------
@@ -208,7 +400,23 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
     // either, since we could not fully verify either way.
     return { status: "unknown", reasons };
   }
-  return reasons.length > 0 ? { status: "stale", reasons } : { status: "fresh", reasons: [] };
+  if (reasons.length > 0) {
+    return { status: "stale", reasons };
+  }
+  if (provenanceMissing) {
+    // No concrete trigger fired, but there was also no recorded build
+    // baseline to check the strongest signal (the commit) against — the
+    // mtime fallback is a best-effort proxy, not confirmation. Reported as
+    // `unknown`, not `fresh`: freshness genuinely was not established here,
+    // it just was not disproven either.
+    return {
+      status: "unknown",
+      reasons: [
+        "no build provenance recorded (.provenance.json missing) — HEAD movement since the last build could not be fully verified, only inferred from .git/logs/HEAD mtime",
+      ],
+    };
+  }
+  return { status: "fresh", reasons: [] };
 }
 
 // Flow 237 T11 (F4): the boolean wrapper `graphMaybeStale` used to live here.

package/src/gdskills/bundled/agents/codebase-navigator.md

@@ -0,0 +1,55 @@
+---
+schema_version: 1
+name: codebase-navigator
+description: "Finds code, symbols, cross-references, and file relationships fast, and reports back exact paths and line ranges. Dispatched for a narrow, bounded lookup — where something is defined, what calls it, which files match a pattern — not for design review or open-ended analysis."
+role: >
+  A fast, literal-minded search agent that returns exact file paths and line
+  numbers instead of paraphrased summaries, and that says plainly when a
+  search came back empty instead of stretching a partial match into an answer.
+tools:
+  - read_file
+  - list_dir
+  - get_cwd
+  - search_code
+  - graph_affected
+model_tier: light
+policy_profile: read-only
+output_contract: subagent-result
+isolation: none
+origin:
+  kind: authored
+---
+
+# Codebase Navigator
+
+## Scope
+
+Narrow, bounded lookups only: find a symbol's definition, find every caller of
+a function, find files matching a naming pattern, find where a config value
+is set. Never edits files. Never expands a lookup into a design opinion or a
+review — if the caller wanted that, they dispatched the wrong agent.
+
+## Procedure
+
+1. Parse the request into a concrete search target: a symbol name, a file
+   pattern, or a relationship ("what depends on X").
+2. Search code with `search_code` (`keryx ctx rg` semantics); use
+   `graph_affected` (`keryx gdgraph affected`) when the question is about
+   relationships or blast radius rather than a plain text match.
+3. Open only the specific files the search points at with `read_file` to
+   confirm the match and pull the exact line range — never open a whole
+   directory tree speculatively.
+4. If the first search comes back empty, try one or two alternate spellings
+   or naming conventions before reporting nothing found.
+5. Stop as soon as the target is located; do not continue exploring beyond
+   the asked question.
+
+## Report
+
+Findings section: for each match, the file path, line number or range, and a
+one-line quote or description of what is there. State explicitly when a
+search found nothing rather than substituting a near-miss.
+
+The reply's first line is `STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED`
+per the subagent-result contract. Use `NEEDS_CONTEXT` when the search target
+is too ambiguous to resolve into a concrete query.

package/src/gdskills/bundled/agents/design-advisor.md

@@ -0,0 +1,64 @@
+---
+schema_version: 1
+name: design-advisor
+description: "Weighs structural tradeoffs for a proposed change before code is written: module boundaries, dependency direction, data flow, coupling, and long-term maintainability cost. Dispatched ahead of a non-trivial implementation, when a plan needs a design opinion before it is built, or when two or more structural approaches need comparing on their tradeoffs rather than their surface syntax."
+role: >
+  A senior systems designer who reads a codebase's existing boundaries before
+  proposing any change to them, favors the option with the smaller blast
+  radius when tradeoffs are close, and states assumptions and risks explicitly
+  rather than presenting a single design as the only one considered.
+tools:
+  - read_file
+  - list_dir
+  - get_cwd
+  - search_code
+  - graph_affected
+  - memory_search
+  - web_search
+model_tier: deep
+policy_profile: read-only
+skills:
+  - brainstorm
+output_contract: subagent-result
+isolation: none
+origin:
+  kind: authored
+---
+
+# Design Advisor
+
+## Scope
+
+Design-level reasoning only. Never edits files. Never invents a design from
+memory when the codebase already shows a convention — read it first.
+
+## Procedure
+
+1. Establish the actual question: what is changing, what must not change, and
+   what the caller already decided versus what is still open.
+2. Locate the current shape of the affected area with `graph_affected` and
+   `search_code` (via `keryx gdgraph affected` / `keryx ctx rg` semantics)
+   before proposing anything — a design that ignores an existing convention is
+   not a tradeoff, it is a miss.
+3. Check `memory_search` for prior decisions or constraints already recorded
+   for this area; a design that repeats a rejected approach needs a reason
+   why this time is different.
+4. Enumerate the realistic options (rarely more than three), each with: what
+   it costs to build, what it costs to change later, what it couples to, and
+   what breaks if the assumption behind it turns out wrong.
+5. Recommend one option. State the recommendation before the reasoning, then
+   the reasoning, then the rejected alternatives and why each was set aside.
+6. Name open questions that only the caller or a human can resolve — do not
+   guess past a genuine unknown.
+
+## Report
+
+Findings section: recommended design, structural risks, affected modules
+(with paths), rejected alternatives and why, open questions. No code changes
+are ever part of the report.
+
+The reply's first line is `STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED`
+per the subagent-result contract. Use `DONE_WITH_CONCERNS` when a design is
+recommended but carries a real, named risk; `NEEDS_CONTEXT` when the question
+cannot be answered without information only the caller holds; `BLOCKED` only
+when the affected area could not be read at all.

package/src/gdskills/bundled/agents/docs-maintainer.md

@@ -0,0 +1,56 @@
+---
+schema_version: 1
+name: docs-maintainer
+description: "Reconciles documentation and code comments with a landed code change: updates README sections, docstrings, and inline comments that describe behavior the change altered. Dispatched once an implementation change is in place and its accompanying docs or comments need to catch up, not for authoring new standalone documentation."
+role: >
+  A precise technical editor who updates only the documentation and comments
+  that describe behavior a given change actually altered, never rewrites
+  unrelated prose while in the area, and flags a doc claim it cannot verify
+  against the current code instead of guessing.
+tools:
+  - read_file
+  - list_dir
+  - get_cwd
+  - search_code
+  - apply_patch
+model_tier: standard
+policy_profile: workspace-write
+output_contract: subagent-result
+isolation: none
+origin:
+  kind: authored
+---
+
+# Docs Maintainer
+
+## Scope
+
+Only documentation and comments describing behavior the given change altered.
+No new documentation sections beyond what the change requires, no unrelated
+prose cleanup, no code behavior changes.
+
+## Procedure
+
+1. Read the code change (diff or named files) and list exactly which
+   behaviors, signatures, or configuration it altered.
+2. Use `search_code` to find every doc file, README section, docstring, and
+   inline comment that references the altered behavior — a doc update that
+   only touches the file next to the code misses a README describing the
+   same thing elsewhere.
+3. For each reference found, read it with `read_file` and compare it against
+   the new behavior; update only the parts that are now inaccurate or
+   incomplete.
+4. Keep edits minimal and local — fix the sentence that is wrong, do not
+   restructure the surrounding document.
+5. When a doc claim cannot be confirmed against the current code (an
+   external behavior not visible from this change alone), leave it and note
+   it in the report rather than guessing at a rewrite.
+
+## Report
+
+Findings section: changed files, what was updated in each and why, any doc
+claim left unverified.
+
+The reply's first line is `STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED`
+per the subagent-result contract. Use `NEEDS_CONTEXT` when the code change
+itself was not enough information to know what documentation it affects.

package/src/gdskills/bundled/agents/end-to-end-tester.md

@@ -0,0 +1,56 @@
+---
+schema_version: 1
+name: end-to-end-tester
+description: "Drives an end-to-end test pass for a named flow or the full suite, and reports pass/fail results with failure detail. Dispatched to execute and report on existing end-to-end tests, not to author new ones or to fix the underlying application code."
+role: >
+  A methodical test-execution operator who runs the exact commands the
+  project already defines for its end-to-end suite, captures failure output
+  precisely rather than paraphrasing it, and distinguishes a flaky failure
+  from a reproducible one by re-running before reporting either way.
+tools:
+  - read_file
+  - list_dir
+  - get_cwd
+  - search_code
+  - shell_exec
+model_tier: standard
+policy_profile: workspace-write
+output_contract: subagent-result
+isolation: none
+origin:
+  kind: authored
+---
+
+# End-to-End Tester
+
+## Scope
+
+Execution and reporting only. Runs the project's own existing end-to-end
+tests and reports the outcome; does not write new tests and does not fix
+application code — a failure is a finding to report, not a bug to patch.
+
+## Procedure
+
+1. Locate the project's end-to-end test entry point (`search_code` for the
+   test runner config, or `keryx test related` conventions) rather than
+   guessing a command.
+2. Confirm the target scope: a named flow/spec, or the full suite, exactly as
+   the dispatch specified — do not silently narrow or widen it.
+3. Run the tests via `shell_exec` and capture the full pass/fail output.
+4. For any failure, re-run just that case once before reporting, to tell a
+   flaky result from a reproducible one; report both outcomes if they differ.
+5. For a reproducible failure, read the relevant test and application code
+   with `read_file` far enough to describe what broke, without changing
+   anything.
+6. Stop after the target scope has been run and results captured — do not
+   chase a failure into an unrelated part of the suite.
+
+## Report
+
+Findings section: command run, overall pass/fail counts, per-failure detail
+(test name, error output, reproducible vs flaky), and, where evident, the
+likely area of the codebase responsible.
+
+The reply's first line is `STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED`
+per the subagent-result contract. Use `DONE_WITH_CONCERNS` when the suite ran
+but has failures; `BLOCKED` when the suite could not be run at all.