@mrciphersmith/keryx 0.3.121 → 0.3.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.121",
+  "version": "0.3.123",
   "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": {
@@ -54,6 +54,7 @@
     "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",
+    "docs:check": "bun run check:doc-links && bun run check:retired-spellings && bun test src/cli-reference-coverage.test.ts src/standard/commands-by-task.test.ts src/standard/help-groups.test.ts",
     "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",

package/src/gdgraph/staleness.ts

@@ -2,7 +2,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";
+import { gitCmd, 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`
@@ -35,7 +35,7 @@ import { gitCmd, gitHead, readProvenance } from "../sync/provenance";
 // 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> {
+export 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"] });
@@ -258,7 +258,10 @@ async function committedChangedFiles(
  * The structured staleness check (AFC-10). Never throws — a git failure is
  * reported as `status: "unknown"` with a reason, not thrown and not "fresh".
  */
-export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck> {
+export async function checkGraphStaleness(
+  cwd: string,
+  statusObservation?: Promise<string | null>,
+): Promise<StalenessCheck> {
   const nodesStat = await stat(nodesJsonlPath(cwd)).catch(() => null);
   if (!nodesStat) {
     return { status: "stale", reasons: ["graph has not been built yet (no nodes.jsonl)"] };
@@ -303,19 +306,30 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
   // `unknown` (a weaker claim — "not verified", not "confirmed stale") rather
   // than staying silently fresh.
   let provenanceMissing = false;
-  const head = await gitHead(cwd);
+  // Independent local probes overlap. The shared status belongs to this call
+  // only; standalone checks always obtain a new observation.
+  const [commit, prefix, porcelain, provenance] = await Promise.all([
+    gitCmd(cwd, ["rev-parse", "HEAD"]),
+    gitCmd(cwd, ["rev-parse", "--show-prefix"]),
+    statusObservation ?? gitStatusPorcelain(cwd),
+    readProvenance(cwd, "gdgraph"),
+  ]);
+  const head = commit ? { commit } : null;
   // 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"])) ?? "") : "";
+  const rootPrefix = prefix ?? "";
+  if (prefix === null) {
+    gitFailed = true;
+    reasons.push("git rev-parse --show-prefix failed");
+  }
   if (head === null) {
     gitFailed = true;
     reasons.push("git rev-parse HEAD failed (not a git repository, or git is unavailable)");
   } else {
-    const provenance = await readProvenance(cwd, "gdgraph");
     if (provenance) {
       if (provenance.commit !== head.commit) {
         const changedFiles = await committedChangedFiles(cwd, provenance.commit, head.commit, rootPrefix);
@@ -343,7 +357,6 @@ export async function checkGraphStaleness(cwd: string): Promise<StalenessCheck>
   }
 
   // --- untracked / deleted / renamed / modified ------------------------------
-  const porcelain = await gitStatusPorcelain(cwd);
   if (porcelain === null) {
     gitFailed = true;
     reasons.push("git status failed");

package/src/gdskills/bundled/rules/core/skill-lifecycle.mdc

@@ -14,6 +14,15 @@ with context. It is NOT a git hook — the `gdskills` post-commit hook only runs
 `skills verify --all --dry-run` as an advisory staleness signal and never
 mutates.
 
+## Project rules — read first, then say so
+
+Before writing code or tests, run `keryx skills resolve-context --files <files>
+--for implement|test`. The `must_read` list puts project rules and project
+skills ahead of the bundled ones. Read every entry, then return
+`project_context_applied` with each path and its `sha256`. A missing entry is a
+warning by default and a refusal under `gdskills.projectContext.enforcement:
+block`.
+
 ## Verify — cheap, inline, before you trust a skill
 
 Whoever is about to rely on a project-skill verifies it first:

package/src/gdskills/bundled/rules/core/skills-storage-workflow.mdc

@@ -23,6 +23,12 @@ Before creating or editing a skill, ask and confirm:
   is an installed mirror, regenerated by `keryx init`/`keryx update` — never
   edit it directly, edits there are overwritten on the next run.
 - Project-local skill: `.metaproject/project-skills/<skill-name>/`.
+- Project rule: `.metaproject/rules/project/<rule>.mdc`, brought in with
+  `keryx skills import --rules <dir>` (`--link` reads a folder in place). Project
+  rules and project implementation skills are resolved first, bundled ones
+  second (`keryx skills resolve-context`). A project skill supplements the
+  built-in `task-implementer` and `tests-creator`; it never takes a bundled
+  skill's name.
 
 ## Required Source Layout
 - `SKILL.md` — canonical source of truth, the shared build used by every runtime

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

@@ -143,9 +143,8 @@ it already tried. The flow package does.
         or close the task (`keryx flow task done <id> <Tn>`). Re-dispatching
         over an unresolved attempt is how the same work gets done twice.
 
-      `keryx flow next` also lists every OTHER not-done task with an unresolved
-      attempt, under `unresolved`: parallel dispatches that never reported back.
-      Resolve them the same way before assuming the flow is idle.
+      `keryx flow next` also lists, under `unresolved`, every OTHER not-done task with an
+      unresolved attempt (parallel dispatches that never reported back); resolve them the same way.
 
    5. Before dispatching a worker for that task, record the attempt:
 
@@ -164,10 +163,8 @@ it already tried. The flow package does.
       keryx review loop --flow <id> --task <Tn>
       ```
 
-      A non-zero exit means the same finding has recurred or two consecutive
-      rounds produced identical output. Go straight to the re-planning step.
-      Do not spend the remaining attempts on the same approach because the
-      budget has some left — that is the failure this check exists to catch.
+      A non-zero exit means the same finding recurred or two consecutive rounds
+      produced identical output: go straight to the re-planning step, whatever budget is left.
    8. If the flow is `blocked`, read the blocking reason from `journal.md`,
       resolve or escalate it, then `keryx flow unblock <id>`.
 4. If the user wants a new flow, continue at 0.1.
@@ -323,6 +320,8 @@ auto-commit off (task-implementer's `automation.auto_commit: false`). A
 `subagent-dispatch` has no `automation` field, so the setting travels as the
 explicit constraint below — never as the worker's default, which is `true`.
 
+Before every `test`, `implement` and fix dispatch, run `keryx skills resolve-context --for test|implement --files <the task's target files, comma-joined> --task-type <type> --task-text '<the task's title and description>' --out .metaproject/flows/<dir>/resolved/<Tn>.<for>.json` (a fix dispatch re-resolves on the new head) and pass that path as `resolved_context_file`: a `context_refs` entry plus the constraint below. Write the text single-quoted (a `'` inside it becomes `'\''`): double quotes let the shell run any backtick or `$(...)` a task description contains. `--task-text` (the harness and MCP field is `task_text`) is what lets a keyword of a document declared in `references.json` match; without it only globs promote. A promoted entry comes back as `must_read` with reason `condition:glob:<g>` or `condition:keyword:<k>`, and its `project_context_applied` item must carry the `path`, the `sha256` of the whole file as pinned, the declared `anchor`, a `summary` (at least 40 characters, in the worker's own words, reusing at least three distinct words of five or more letters from the anchored section) and `how` `read` or `followed`, never `n/a`. Before accepting the reply, run `keryx skills contracts validate <result.json> --schema task-implementer-output|tests-creator-output --resolved <that file>`; under `gdskills.projectContext.enforcement: block` a miss is a refusal, under `warn` journal it.
+
 Dispatch payload, bound to the flow (map `target_skill` from the routing table):
 
 ```json
@@ -337,12 +336,14 @@ Dispatch payload, bound to the flow (map `target_skill` from the routing table):
   "context_refs": [
     { "path": ".metaproject/flows/<dir>/context.md", "kind": "context", "exists": true },
     { "path": ".metaproject/flows/<dir>/plan.md", "kind": "plan", "exists": true },
-    { "path": ".metaproject/flows/<dir>/acceptance-criteria.md", "kind": "custom", "exists": true }
+    { "path": ".metaproject/flows/<dir>/acceptance-criteria.md", "kind": "custom", "exists": true },
+    { "path": ".metaproject/flows/<dir>/resolved/<Tn>.<for>.json", "kind": "custom", "exists": true }
   ],
   "files_to_read": ["<only files gdgraph/gdctx narrowed to>"],
   "constraints": [
     "Never edit flow.json.",
     "Never edit frozen acceptance criteria.",
+    "resolved_context_file: .metaproject/flows/<dir>/resolved/<Tn>.<for>.json — read its must_read entries and cite each in project_context_applied; an entry promoted by a condition also needs its anchor and a summary.",
     "Return a subagent-result; first line must be STATUS:.",
     "Follow rules/core/git-concurrency.mdc: never git stash; never git add -A.",
     "Root: <worktree_path>. Before the first write run `cd <worktree_path> && pwd && git branch --show-current`; run every git command as `git -C <worktree_path>`.",
@@ -359,9 +360,8 @@ Dispatch payload, bound to the flow (map `target_skill` from the routing table):
 `DONE_WITH_CONCERNS`), then mark task progress. It commits exactly those
 `changed_files` from the worker's `subagent-result` that git still shows as
 changed, never `-A`/`--all`/`.` (`rules/core/git-concurrency.mdc` rule 4 and
-"Reporting Back"). It skips cleanly when none remain. That is expected, not an
-error, for a worker that reported no files (review, context, docs) or that
-committed on its own (tests-creator's stubs):
+"Reporting Back"). It skips cleanly when none remain (expected for a worker that
+reported no files or committed on its own, like tests-creator's stubs):
 
 ```bash
 set -- <each changed_files path, single-quoted: 'src/a.ts' 'docs/b c.md'>   # may be none; an unquoted path with a space splits and is skipped
@@ -526,7 +526,7 @@ the bound plus an escalation — never an unbounded loop.
 
 ### PR review/fix loop
 
-1. Each round — the first and every one after a fix — is `keryx review start` on the PR's current head, then `review-orchestrator` from that package. `review start` finds the previous round itself (local package, git history, the PR's round block, the flow package) and, when the previous reviewed head is an ancestor, reviews the delta: fix changes with a small roster (logic, regression, the findings' authors, the verifier) and the prior findings attached, new changes as round 1, unchanged code carried with its dispositions. Never pass a whole-branch range or `--all` per round; `<package>/round.json` records the round, its source and its mode.
+1. Each round — the first and every one after a fix — is `keryx review start` on the PR's current head, then `review-orchestrator` from that package. `review start` finds the previous round itself (local package, git history, the PR's round block, the flow package) and, when the previous reviewed head is an ancestor, reviews the delta: fix changes with a small roster (logic, regression, the findings' authors, security-code when a security finding is attached, the content roles of the fix lines themselves, the verifier) and the prior findings attached, new changes as round 1, unchanged code carried with its dispositions. Never pass a whole-branch range or `--all` per round; `<package>/round.json` records the round, its source and its mode.
 2. If findings (held ones aside: Phase 3 step 6) or required check failures remain, run a fix round under Phase 3 step 6 (flow fix task, `task-implementer`), push the fix, and run the next round as in step 1.
 
    **A required check failure is not automatically a fix task.** When `review.jev.ci_triage` is on, run `keryx review ci-triage --run <id> --json` on each failed run first: `top: flaky` (or a `deterministic` override) → rerun once (`gh run rerun --failed <id>`), record it in `journal.md`, and treat a second failure as `real-regression` regardless; `top: real-regression` → investigate and fix as usual; `top: infra` → report it in the completion notes and leave the code alone. The verdict is advisory only — never the sole reason to skip a fix task.

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

@@ -746,8 +746,10 @@ FOR wave_index, wave_tasks in enumerate(WAVES):
 
   keryx job step <job-name> tests-creator --status in-progress      # wave 1 only
   # Step A — tests-creator (MANDATORY, run first)
-  Dispatch one tests-creator per task in this wave, in a SINGLE turn (parallel).
-  Wait for ALL of them. Collect TEST_SPECS[task_id] from each response.
+  keryx skills resolve-context --for test --files <task target_files, comma-joined> --task-type <task_type> --task-text '<task title and description, each ' written as '\''>' --out <JOBS_ROOT>/<job-name>/results/<task_id>.test.resolved.json
+  Dispatch one tests-creator per task in this wave, in a SINGLE turn (parallel), each carrying resolved_context_file.
+  Wait for ALL of them. Collect TEST_SPECS[task_id] from each response, then per result:
+    keryx skills contracts validate <task_id>-tests.json --schema tests-creator-output --resolved <that resolved file>
   keryx job step <job-name> tests-creator --status completed         # last wave only
 
   # Parallel safety check, before Step B:
@@ -755,9 +757,10 @@ FOR wave_index, wave_tasks in enumerate(WAVES):
 
   keryx job step <job-name> implement --status in-progress           # wave 1 only
   # Step B — task-implementer (after all test stubs are committed)
+  keryx skills resolve-context --for implement ... --out <JOBS_ROOT>/<job-name>/results/<task_id>.implement.resolved.json
   Dispatch one task-implementer per task in this wave, in a SINGLE turn (parallel),
-  each carrying test_case_specs: TEST_SPECS[task_id].
-  Wait for ALL of them.
+  each carrying test_case_specs: TEST_SPECS[task_id] and resolved_context_file (an entry promoted by a declared condition, reason condition:glob:<g> or condition:keyword:<k>, needs its project_context_applied item to carry path, sha256 of the whole file, the declared anchor, a summary of 40+ characters in the worker's own words, and how read|followed, never n/a).
+  Wait for ALL of them; per result: keryx skills contracts validate <result.json> --schema task-implementer-output --resolved <that resolved file>
 
   Read each result's STATUS line:
     DONE / DONE_WITH_CONCERNS → accept it (record every concern)
@@ -789,6 +792,7 @@ Task({
     - package_manager:  <pm>
     - run_command:      <runner>
     - context_path:     <JOBS_ROOT>/<job-name>/ai/context.md
+    - resolved_context_file: <JOBS_ROOT>/<job-name>/results/<task_id>.test.resolved.json
 
     ## Required response
     Begin with STATUS: <STATUS>. Return the test_case_specs for this task and
@@ -819,6 +823,7 @@ Task({
     - issue_number:     <N>
     - job_name:         <job-name>
     - context_path:     <JOBS_ROOT>/<job-name>/ai/context.md
+    - resolved_context_file: <JOBS_ROOT>/<job-name>/results/<task_id>.implement.resolved.json
 
     ## Automation (task-implementer input `automation`)
     - auto_commit:      <implementer_settings.auto_commit>   # false: do not commit; report exact paths
@@ -1114,10 +1119,8 @@ keryx review tier --scope <scope> --diff-lines <n> --findings <n> [--security] [
 ```
 
 Paste the `model` block it prints into that dispatch. `model_strategy: "current"` is
-gone: it meant "do not switch models", which is exactly the behaviour this command
-replaced. The command names no model — it ranks what the provider reports at runtime
-and, when it cannot rank anything, prints `inherit: true`, which means the dispatch
-runs on the session model. That is a correct answer, not a failure.
+gone. The command names no model: it ranks what the provider reports at runtime and,
+when it cannot, prints `inherit: true` — the dispatch runs on the session model, a correct answer.
 
 **Step 6 — run `review-orchestrator` inline, in this main session.** Load
 `skills/gdskills/review/review-orchestrator/SKILL.md` yourself; do **not** wrap it in a
@@ -1159,10 +1162,9 @@ keryx review ingest --report <path/to/review-report.md> --ref <feature-branch> \
   --spent <usd-so-far> --outstanding <subagents in flight>
 ```
 
-An unrecognised option is **refused, not ignored** — a silently dropped flag writes
-nothing and still reports success. `--refuted` carries findings this round raised and
-then dismissed; without it the package keeps only the survivors of an unlogged triage.
-A first ingest without `--premises` holds nothing; a re-ingest carries earlier holds.
+An unrecognised option is **refused, not ignored**. `--refuted` carries findings this round
+raised and then dismissed; without it the package keeps only the survivors of an unlogged
+triage. A first ingest without `--premises` holds nothing; a re-ingest carries earlier holds.
 
 **Findings are the canonical shape.** One vocabulary, everywhere in this skill:
 
@@ -1278,15 +1280,11 @@ cumulative ever-correct is **0.847**
 ([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
-slowly" from "stuck", and an agent emitting the identical failing output three
-times spends the whole budget before anything notices.
+The bound is a ceiling, not a target. Repetition ends the loop earlier, **regardless of
+remaining iterations**: a counter cannot tell "converging slowly" from "stuck".
 
-**A finding leaves this loop by being dispositioned, never by being absent.** The
-previous version of this section recomputed "unresolved" as whatever the next round
-still reported — so a finding the next reviewer simply did not look at was recorded as
-fixed. That is absence-as-evidence, and the completion gate refuses it.
+**A finding leaves this loop by being dispositioned, never by being absent.** One the next
+reviewer did not look at is not fixed: absence-as-evidence, which the completion gate refuses.
 
 ```
 UNRESOLVED_FINDINGS = OPEN from step 2.6          # never a HELD finding (Classify, 2.6.1)
@@ -1306,9 +1304,10 @@ FOR iteration in [1, 2, 3]:
      previously_unresolved: <findings that were in UNRESOLVED_FINDINGS last iteration but still present>
          → Prefix: "These specific findings were NOT fixed in iteration <N-1>: [list]"
 
-  3. Launch task-implementer with the fix prompt (subagent_type: "general-purpose"),
+  3. Re-run `keryx skills resolve-context --for implement` on the fix files (with `--task-text '<fix task description, each ' written as '\''>'` and a fresh `--out`), then launch task-implementer
+     with the fix prompt and `resolved_context_file` (subagent_type: "general-purpose"),
      on the model `keryx review tier --fix-attempt <N> --findings <n> --json` computes
-  4. Run the sanity check (step 2.5.2 logic) — verify commits were made
+  4. Run the sanity check (step 2.5.2 logic) — verify commits were made — and `contracts validate --resolved` on the result
   5. Run the next managed round — the FULL 2.6.1 sequence, not a bare re-dispatch:
        keryx review budget  --spent <usd> --outstanding <n>
        keryx review plan    --target branch --ref <feature-branch> --head <new-head>

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

@@ -129,10 +129,18 @@ All subsequent operations ONLY in the worktree directory.
 WAVES = dependency_order from ANALYSIS_RESULT (already topologically sorted)
 
 FOR wave_index, wave_tasks in enumerate(WAVES):
-  1. Dispatch one tests-creator per task, in a SINGLE turn (parallel). Wait for all.
+  1. keryx skills resolve-context --for test --files <target_files> --task-type <type> --task-text '<task title and description, each ' written as '\''>' --out <JOBS_ROOT>/<job-name>/results/<task_id>.test.resolved.json
+     Dispatch one tests-creator per task, in a SINGLE turn (parallel), each carrying
+     resolved_context_file. Wait for all; per result run
+     keryx skills contracts validate <result.json> --schema tests-creator-output --resolved <that file>
      Load skill: skills/gdskills/quality/tests-creator/SKILL.md
   2. Parallel safety check: tasks sharing a target_file run sequentially.
-  3. Dispatch one task-implementer per task, in a SINGLE turn (parallel). Wait for all.
+  3. keryx skills resolve-context --for implement ... --out <...>/<task_id>.implement.resolved.json
+     A promoted entry (reason condition:glob:<g> or condition:keyword:<k>) needs path, sha256, the declared anchor, a summary
+     (40+ characters, own words) and how read|followed in the worker's project_context_applied; validate refuses it otherwise.
+     Dispatch one task-implementer per task, in a SINGLE turn (parallel), each carrying
+     resolved_context_file. Wait for all; per result run
+     keryx skills contracts validate <result.json> --schema task-implementer-output --resolved <that file>
      Load skill: skills/gdskills/orchestration/task-implementer/SKILL.md
   4. Read each STATUS line:
        all DONE               → next wave
@@ -177,8 +185,8 @@ ingest carrying a scope-B finding without it is refused. Severities are
 
 If `blocker` or `major` findings exist:
 1. Group by file
-2. Launch task-implementer (`task_type: "fix"`) with the findings
-3. Run the sanity check — verify commits were made
+2. Re-run `keryx skills resolve-context --for implement` on the fix files (with `--task-text '<fix task description, each ' written as '\''>'`), then launch task-implementer (`task_type: "fix"`) with the findings and `resolved_context_file`
+3. Run the sanity check — verify commits were made — and `contracts validate --resolved` on the result
 4. Run the NEXT managed round: `keryx review plan --target branch --ref <feature-branch> --head <new-head>` (or `review start`) on the new head, then review-orchestrator. The round, range and prior findings come from `round.json`: no own range, no `--all` per round, no whole-branch re-review.
 5. Disposition every finding of the previous round:
    ```bash

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

@@ -173,35 +173,34 @@ Before you rely on a project-skill's guidance, confirm it still matches the code
 - `keryx skills route <target_file>` — find the project-skill for this module/entity (if any).
 - If one exists: `keryx skills verify <module>/<skill>` — classifies it `fresh | stale | needs-review | blocked`.
 - If it is **not `fresh`**: do not follow it blindly. Verify each claim against the code you read in Phase 2, and note the drift in `notes` (Phase 6.1) so the orchestrator can trigger `skills learn`.
+- If it is **`fresh`**: apply it. Its rules, templates and conventions for the target are part of the task, not background reading, and they supplement this skill's phases: a project skill never replaces a phase, the TDD order or the output contract. Where it and a bundled rule disagree, the project skill wins; say so in `notes`.
 - If no skill exists for a non-trivial module you had to reverse-engineer, note that too — it's a candidate for `skills create`.
 
 This step is read-only and inline; do not spawn a subagent for it.
 
+**2.0c Resolve the project's standard (before 2.1):**
+- Use `workspace.resolved_context_file` when given; otherwise run `keryx skills resolve-context --for implement --files <target_files, comma-joined> --task-type <task_type> --task-text '<task.description, each ' written as '\''>' --out <project-relative path>` (`--task-text` lets a declared keyword promote a document).
+- Read every `must_read` entry in full, project entries first; read `on_demand` ones only when the work touches them. A project rule listed with `shadows` replaces the bundled one. An entry with `also_at` is one file under several paths: citing any of them, with the entry's sha256, counts.
+- An entry with reason `condition:glob:<g>` or `condition:keyword:<k>` was promoted by a declared condition and carries an `anchor`, a `description` and `section_bytes`: read the anchored section in full. Its `project_context_applied` item needs the `path`, the `sha256` of the whole file as pinned, the `anchor` exactly as declared, a `summary` and `how` `read` or `followed`, never `n/a`. Write the `summary` in your own words, at least 40 characters, naming at least three distinct words of five or more letters taken from the anchored section; `contracts validate --resolved` rejects a copied hash without it. Cite what you used in `project_context_applied` (6.1) with the resolver's `sha256`; `n/a` needs a reason in `notes`. Never edit a resolved file: `keryx skills contracts validate <result.json> --schema task-implementer-output --resolved <resolved.json>` fails on drift.
+
 **2.1 Read all target files:**
 - Read each file from `target_files` in full
 - If a file does not exist yet, note it as "new file to create"
 - Read the `context` field for additional type/signature info
 
 **2.2 Read existing tests and stories:**
-- `existing_tests` and `existing_stories` are arrays and default to `[]`
-  (`input-contract.schema.json`). Empty means none; the string `"none"` is not a
-  legal value and a request carrying it is refused by 1.4
+- `existing_tests` and `existing_stories` default to `[]`; the string `"none"` is not a legal value and 1.4 refuses it
 - Read each file listed in either array
 - Understand existing test patterns (describe/it structure, mocks, fixtures) and, for every file in `existing_stories`, the story patterns it uses (`Meta`/`StoryObj` shape, how variants are declared, how callbacks are stubbed) — 4.4 builds on what you record here
 
 **2.3 Read module neighbors:**
 - List sibling files in the same directory as each target file
 - Read 2-3 similar files to understand module patterns (naming, exports, structure)
-- Pay attention to:
-  - Import aliases used (e.g., `@components`, `@utils`)
-  - Export patterns (named vs default)
-  - TypeScript patterns (interfaces vs types, generics usage)
-  - Component patterns (observer wrapping, props interface naming)
-  - Store patterns (makeObservable(this), explicit decorators, private fields before public fields, thin public @action.bound UI actions, non-mutating public helpers, private API methods, runInAction inside private mutation blocks after await)
+- Pay attention to import aliases, named vs default exports, interfaces vs types, observer wrapping and props naming, and store patterns (makeObservable(this), explicit decorators, private fields before public, thin public @action.bound UI actions, non-mutating public helpers, private API methods, runInAction after await)
 
 **2.4 Load relevant rules (from `module_patterns` or by detection):**
 
-Based on what you're implementing, load and follow the relevant project rules.
+Rules `resolve-context` listed are already read (2.0c); load the rest by what you're implementing.
 
 **Always load (all task types):**
 - `tdd-workflow.mdc` — red-green-refactor, STATUS: DONE requires passing tests
@@ -224,8 +223,7 @@ Based on what you're implementing, load and follow the relevant project rules.
 - `async`/`await` or queue code → `async-patterns.mdc`
 - New architectural layers or modules → `clean-architecture.mdc`
 
-Rules live at `.metaproject/rules/core/<rule>.mdc` on every harness — that is the
-one tree `keryx init` installs and the one every build of this skill reads.
+Resolve every rule above project first, bundled second: read `.metaproject/rules/project/<rule>.mdc` when it exists, otherwise `.metaproject/rules/core/<rule>.mdc`. A project rule with the same name replaces the bundled one (never read both as if they agreed). `.metaproject/rules/core/` is the tree `keryx init` installs and `keryx update` overwrites, so a project's own rules live only in `rules/project/`.
 
 ### Phase 3: PLAN
 
@@ -427,6 +425,7 @@ Write full JSON to `<JOBS_ROOT>/<JOB_NAME>/results/<task_id>.json`:
   "story_result": "<pass|build error: details|not applicable>",
   "acceptance_criteria_met": "<all|partial: list of unmet criteria|none>",
   "skill_drift": "<none | stale: <module>/<skill> — <what diverged> | missing: <module> should have a project-skill>",
+  "project_context_applied": [{ "path": "<as the resolver printed it>", "sha256": "<resolver's sha256>", "how": "read|followed|n/a", "anchor": "<declared heading; promoted entries only>", "summary": "<own words, 40+ chars; promoted entries only>" }],
   "noticed_not_touched": [{ "what": "<problem>", "where": "<path|symbol>" }],
   "assumptions": ["<what you assumed where the task did not say>"],
   "behavior_changes": [{ "description": "<what now behaves differently>", "user_visible": true, "needs_operator": true, "alternatives": ["<option you did not take>"] }],

package/src/gdskills/bundled/skills/orchestration/task-implementer/input-contract.schema.json

@@ -134,6 +134,11 @@
         "context_path": {
           "type": "string",
           "description": "Job context document read at the start of Phase 2, e.g. .metaproject/jobs/<job_name>/ai/context.md"
+        },
+        "resolved_context_file": {
+          "type": "string",
+          "description": "Output of `keryx skills resolve-context --for implement --out <path>` for this task, made by the dispatcher. Present => Phase 2 reads its `must_read` entries instead of resolving again, and the result must carry `project_context_applied`. Absent => Phase 2 runs the resolver itself.",
+          "examples": [".metaproject/data/flows/461/task-1.resolved.json"]
         }
       }
     },

package/src/gdskills/bundled/skills/orchestration/task-implementer/output-contract.schema.json

@@ -97,6 +97,22 @@
         }
       }
     },
+    "project_context_applied": {
+      "type": "array",
+      "description": "Which of the files `keryx skills resolve-context` listed this run actually used, so a reader can subtract it from the resolver's `must_read` list. `how`: `read` - the file was opened and its text used; `followed` - its rules were applied through a skill or another file that already contains them; `n/a` - the file does not touch the task, with the reason in `notes`. `sha256` is the resolver's value for the file, not a fresh hash: `keryx skills contracts validate --resolved` compares the two.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256", "how"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1, "description": "Repo-relative path exactly as the resolver printed it" },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The resolver's sha256 of the file" },
+          "how": { "type": "string", "enum": ["read", "followed", "n/a"] },
+          "anchor": { "type": "string", "description": "Optional. The heading of the section read, exactly as the resolver printed it for an entry promoted by a declared condition (flow 462)" },
+          "summary": { "type": "string", "description": "Optional. What the section says, in the worker's own words; for a promoted entry `keryx skills contracts validate --resolved` checks it against the anchored section (flow 462)" }
+        }
+      }
+    },
     "notes": {
       "type": "string",
       "description": "Warnings, blockers, or additional context. The three fields above were carved out of this one: free text is where they went before they were declared, and anything that fits one of them belongs there instead."

package/src/gdskills/bundled/skills/quality/tests-creator/SKILL.md

@@ -90,9 +90,10 @@ not a hardcoded `cat`/`ls`/`find` invocation).
 - Fixture/factory patterns (how test data is created)
 - Before/after hook usage
 
+**1.2b Load test-convention rules, project first.** Read the testing rules the task touches (`testing-conventions`, `tdd-workflow`, and any rule the task names) in this order: `.metaproject/rules/project/<rule>.mdc` first, then `.metaproject/rules/core/<rule>.mdc`. A project rule with the same name replaces the bundled one; a project rule with a different name adds to it. Take the list from `workspace.resolved_context_file` when the task carries one, otherwise run `keryx skills resolve-context --for test --files <target_files, comma-joined> --task-text '<task description, each ' written as '\''>' --out <project-relative path>` (`--task-text` lets a declared keyword promote a document); read its `must_read` entries in full and record each in `project_context_applied` with the resolver's `sha256`. An entry with reason `condition:glob:<g>` or `condition:keyword:<k>` was promoted by a declared condition: read its anchored section, and its item needs the `path`, the `sha256` of the whole file as pinned, the `anchor` exactly as declared, a `summary` (at least 40 characters, in your own words, naming at least three distinct words of five or more letters from that section) and `how` `read` or `followed`, never `n/a`. Where a project test convention and a bundled one conflict, the project wins. A project skill only supplements these steps; it never replaces this skill.
+
 **1.3 Identify test file naming:**
-- Pattern: `<component>.test.ts`, `<service>.spec.ts`, `test_<module>.py`, etc.
-- Location: co-located with source or in `__tests__`/`tests/` directory
+- Pattern (`<component>.test.ts`, `<service>.spec.ts`, `test_<module>.py`) and location (co-located, or `__tests__`/`tests/`)
 
 **Output of Phase 1:**
 ```
@@ -200,7 +201,6 @@ The generated tests MUST:
   ```typescript
   // Use todo() for unimplemented tests
   it.todo('<test description>');
-  
   // OR use a stub assertion that fails
   it('<test description>', () => {
     expect(true).toBe(false); // RED: remove this when implementing
@@ -265,6 +265,8 @@ TEST_CASE_SPECS:
           type: happy_path | edge_case | error_path
           status: written  # test file exists, test is RED
 
+  project_context_applied: [{path: <rule path, project first>, sha256: <resolver's sha256>, how: read|followed|n/a, anchor: <declared heading, promoted entries only>, summary: <own words, 40+ chars, promoted entries only>}]
+
   run_command: "<command to run just these tests>"
   expected_result: "all failing (RED phase)"
   notes: "<any test design decisions or assumptions>"
@@ -285,12 +287,10 @@ all_criteria_covered: true | false (with explanation)
 
 When `task-implementer` receives a task that includes `test_case_specs`:
 
-1. Read the test files (already committed as RED)
-2. Run the tests — confirm they FAIL
-3. Implement code until all tests are GREEN
-4. Commit the implementation
-5. Re-run tests — confirm GREEN
-6. Report SUCCESS
+1. Read the test files (already committed as RED) and run them — confirm they FAIL
+2. Implement code until all tests are GREEN
+3. Commit the implementation, re-run tests — confirm GREEN
+4. Report SUCCESS
 
 This ensures the TDD cycle is maintained end-to-end.
 

package/src/gdskills/bundled/skills/quality/tests-creator/input-contract.schema.json

@@ -75,6 +75,10 @@
           "type": "integer",
           "minimum": 1,
           "description": "GitHub issue number for commit references"
+        },
+        "resolved_context_file": {
+          "type": "string",
+          "description": "Output of `keryx skills resolve-context --for test --out <path>` for this task, made by the dispatcher. Present => Phase 1 reads its `must_read` entries instead of resolving again, and the result must carry `project_context_applied`. Absent => Phase 1 runs the resolver itself."
         }
       }
     },

package/src/gdskills/bundled/skills/quality/tests-creator/output-contract.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "tests-creator-output-contract",
   "title": "Tests Creator Output Contract",
-  "description": "Output from tests-creator: test case specifications for task-implementer plus status report.",
+  "description": "Output from tests-creator: test case specifications for task-implementer plus status report. Registered as contract `tests-creator-output`: validate a result with `keryx skills contracts validate <result.json> --schema tests-creator-output`.",
   "type": "object",
   "required": ["test_case_specs", "status_report"],
   "properties": {
@@ -85,6 +85,22 @@
         }
       }
     },
+    "project_context_applied": {
+      "type": "array",
+      "description": "Which of the files `keryx skills resolve-context` listed this run actually used, so a reader can subtract it from the resolver's `must_read` list. `how`: `read` - the file was opened and its text used; `followed` - its rules were applied through a skill or another file that already contains them; `n/a` - the file does not touch the task, with the reason in `notes`. `sha256` is the resolver's value for the file, not a fresh hash: `keryx skills contracts validate --resolved` compares the two.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256", "how"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1, "description": "Repo-relative path exactly as the resolver printed it" },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The resolver's sha256 of the file" },
+          "how": { "type": "string", "enum": ["read", "followed", "n/a"] },
+          "anchor": { "type": "string", "description": "Optional. The heading of the section read, exactly as the resolver printed it for an entry promoted by a declared condition (flow 462)" },
+          "summary": { "type": "string", "description": "Optional. What the section says, in the worker's own words; for a promoted entry `keryx skills contracts validate --resolved` checks it against the anchored section (flow 462)" }
+        }
+      }
+    },
     "status_report": {
       "type": "object",
       "required": ["status", "tests_written", "all_criteria_covered"],

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

@@ -651,7 +651,7 @@ certifies the flow is the one that checked the least.
 
 ## Readiness — the checklist behind `completed` and behind publishing
 
-`keryx review readiness <review-id-or-path> [--json]` reads the package and prints eleven items, READY or NOT READY, each with the evidence and the command that repairs it. It writes nothing, and exits non-zero when the verdict is NOT READY. Only item 9 reaches GitHub (the PR's own file list); the TUI and `review status` read the package alone.
+`keryx review readiness <review-id-or-path> [--json]` reads the package and prints every readiness item, READY or NOT READY, each with the evidence and the command that repairs it. It writes nothing, and exits non-zero when the verdict is NOT READY. Only item 9 reaches GitHub (the PR's own file list); the TUI and `review status` read the package alone.
 
 1. `files-covered` — every changed file is in a wave or carries a recorded waiver.
 2. `blast-radius` — no file the blast radius cut is left unreviewed. A cut radius writes `chunks.json`; run `keryx review chunks plan`, `estimate`, `next`/`record`, `merge`. In an unattended run every wave runs without a question, up to the 25-pass ceiling; in an interactive run the operator is asked once: in keryx shell call `review_chunks_answer` (a card, never a terminal); elsewhere the operator runs `keryx review chunks estimate --package <dir> --answer yes --quote "<their words>"` in their terminal; unattended, record Not run.
@@ -664,6 +664,7 @@ certifies the flow is the one that checked the least.
 9. `pr-files` — the changed-file count equals the PR's own file list. A recount more than 3x the recorded scope is refused: it came from the wrong base. Recount with `keryx review blast-radius --package <ref> --changed <the PR's files>`.
 10. `memory-outside-stage` — the orchestrator read memory only in its memory stage ("Clean context" above). Outside keryx shell it reads "not observable on this host" unless this session's keryx calls carry the caller token `keryx review start` printed.
 11. `premise-decisions` — every finding `review-premise` held (`challenged` or `owner-decision`) has an operator decision: in keryx shell the card `review_decide_premise`; elsewhere the operator runs `keryx review decide-premise --package <dir> --finding <global_id> --answer uphold|dismiss --reason "<why>"` in their terminal (SKILL.md "Wave D"). Not waivable: each held finding needs its own answer, and `review_waive_readiness` / `--waive` refuse this item.
+12. `quotes-located` — every open finding whose quote `review ingest` could not place (absent from the file at the reviewed head, or in it more than once) has a disposition. Ingest keeps such a finding with no line, flagged `quote_unlocated` and listed in scope.md, instead of refusing the round. Re-quote one distinct line and re-ingest, record a disposition, or the operator waives the item.
 
 `keryx review complete` refuses status `completed` while any item fails. A failing item other than `premise-decisions` is waived only by the operator. In keryx shell call `review_waive_readiness` for the item: the operator answers it as a card, the waiver is recorded with the card text and the time, and then you run `keryx review complete`. Never send the operator to a terminal. Outside keryx shell the operator runs `keryx review complete --waive <item> "<their own words>"` in a terminal, repeatable. Unattended, record the item as Not run. `keryx review publish` is held by the same checklist. Publishing is the operator's decision too: in keryx shell call `review_publish` (a card shows the target and the body; never send the operator to a terminal). A not-ready package goes to GitHub only as a partial review (`review_publish` with `partial: true`, or `keryx review publish --partial`), which puts a "Partial review" header on the post and never approves. The shell guard stops a publish command that runs through the keryx shell; a publisher outside it (CI, another agent, a script file) is not stopped, and that limit is named, not hidden.
 
@@ -695,7 +696,7 @@ on lines no test could reach.
 | `mode` | `range` | Review |
 |---|---|---|
 | `first` | merge-base..head | A first round. `sourcesTried` records what was searched when nothing was found. |
-| `delta` | previous head..head | `fix` slices (a hunk that answers a prior finding): `review-logic`, `review-regression`, the authors of the attached findings and the verifier, each with its `prior_findings`. `new` slices: round 1, with the roles the slice names. Unchanged code: not re-reviewed. `carried` findings keep their dispositions. |
+| `delta` | previous head..head | `fix` slices (a hunk that answers a prior finding): `review-logic`, `review-regression`, the authors of the attached findings, `review-security-code` when one of them is a security finding, the roles the fix lines themselves route by content (e.g. `review-security-code` for a fix that spawns a process), and the verifier, each with its `prior_findings`. `new` slices: round 1, with the roles the slice names. Unchanged code: not re-reviewed. `carried` findings keep their dispositions. |
 | `fallback-first` | merge-base..head | The previous head is not an ancestor (force-push, rebase). Review the whole range with the prior findings attached. |
 
 A fix hunk still has a radius: enumerate what names the thing it changed (`review_context.scope.files`), as in any fix round. The attached findings are the contract: each leaves the round with a disposition, below.