@mrciphersmith/keryx 0.3.122 → 0.3.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.122",
+  "version": "0.3.124",
   "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

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

@@ -383,7 +383,7 @@ A review must be reproducible from its package: the same inputs give the same co
 
 **One memory read, and the log.** The stage query is `keryx memory search "<changed modules and the concepts they touch>" --status accepted`, once. Pass the same text to `keryx review start … --memory-query "<query>"` so the manifest's `cleanContext` block holds it next to the start time. keryx writes the orchestrator log, `<package>/tool-calls/orchestrator.jsonl`, on its own: `keryx review start` and `keryx review attach` mark the package active, and every `keryx memory` command and every MCP memory tool (`memory_search`, `memory_handoff`, `memory_propose`) appends one line naming its caller. You do not write that file and must not edit it; a hand-written line is a forgery the readiness item cannot tell apart from a record. A call by a `spawn_subagent` child is recorded under the child's reviewer id and is not judged by item 10. A call from a host that names no caller is recorded as `unattributed`: it warns in the item's detail line and never blocks. Reviewer logs stay in their own files.
 
-Item 10, `memory-outside-stage`, reads that log. Outside the stage is: a memory search with a different query, a search without `--status accepted`, any other memory command or MCP memory tool, and a stage call stamped before the round started. The same query repeated is the stage. Repair is to rerun from a session whose only memory read is the stage; only the operator's waiver lifts it: in keryx shell call `review_waive_readiness` (the operator answers a card, never a terminal), then run `keryx review complete <package>`; outside keryx shell `keryx review complete <package> --waive memory-outside-stage "<operator quote>"` in a terminal; unattended, record Not run. With no orchestrator log the item passes and its evidence says it could not see your reads; with a log that holds no memory call it passes and says so. Outside keryx shell, `keryx review start` prints a caller token (`export KERYX_REVIEW_CALLER_TOKEN=…`): export it on this session's keryx calls so they are attributed to you; without it the item reads "not observable on this host" rather than a clean pass. Only calls that go through keryx are visible: a read through a tool keryx does not wrap is not in the log.
+Item 10, `memory-outside-stage`, reads that log. Outside the stage is: a memory search with a different query, a search without `--status accepted`, any other memory command or MCP memory tool, and a stage call stamped before the round started. The same query repeated is the stage. Repair is to rerun from a session whose only memory read is the stage; only the operator's waiver lifts it: in keryx shell call `review_waive_readiness` (the operator answers a card, never a terminal), then call `review_complete`; outside keryx shell `keryx review complete <package> --waive memory-outside-stage "<operator quote>"` in a terminal; unattended, record Not run. With no orchestrator log the item passes and its evidence says it could not see your reads; with a log that holds no memory call it passes and says so. Outside keryx shell, `keryx review start` prints a caller token (`export KERYX_REVIEW_CALLER_TOKEN=…`): export it on this session's keryx calls so they are attributed to you; without it the item reads "not observable on this host" rather than a clean pass. Only calls that go through keryx are visible: a read through a tool keryx does not wrap is not in the log.
 
 **Open questions.** One general rule, replacing per-fork wording: the answer is in this skill or `SKILL.detail.md`, or it is the user's. Interactive: one `AskUserQuestion`. Unattended: the whole output is one line, `STATUS: BLOCKED question — <the question>`, and you stop. A guess and a recollection are both wrong answers.
 
@@ -666,7 +666,7 @@ certifies the flow is the one that checked the least.
 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.
+`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 call the `review_complete` card (the operator answers it in the shell or in the Telegram topic). An agent completes a review only through that card; `keryx review complete` is for a human in a terminal. 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.
 
 ## Fix rounds — dispositions, regressions, withdrawal
 
@@ -863,7 +863,7 @@ minute 119, and the PR merged first; the other re-dispatched a finished wave and
 
 As soon as every reviewer result and the verifier's are on disk, save each verifier pass to `research-evidence/verifications.json` first (without it a refuted finding still counts), then run `keryx review verdict <id|path> [--json]`: it reads `<package>/raw`, where every host keeps the round's results (`--raw <dir>` only for results kept elsewhere; the shared `.metaproject/data/review/raw` mixes in other rounds' replies). It prints the interim verdict and writes `verdict-interim.md` into the package. Give the operator that verdict in the same message; do not hold it for the mutation pass, the ledger or `complete`.
 
-The tail keeps running after it: the mutation pass (`keryx review mutate`), `ledger build`, `ingest`, `readiness` and `keryx review complete`. Every managed round finishes them. The round is **not done** until `complete`: the verdict you gave is interim, and the report says so and names what the tail may still change (a surviving mutant, a verifier refutation, a late reviewer result). A light round has no mutation pass: its tail is `ledger build`, `ingest`, `readiness`, `complete`.
+The tail keeps running after it: the mutation pass (`keryx review mutate`), `ledger build`, `ingest`, `readiness` and the `review_complete` card (`keryx review complete` for a human at a terminal). Every managed round finishes them. The round is **not done** until `complete`: the verdict you gave is interim, and the report says so and names what the tail may still change (a surviving mutant, a verifier refutation, a late reviewer result). A light round has no mutation pass: its tail is `ledger build`, `ingest`, `readiness`, `complete`.
 
 ## Early verifier — start on the first blocker or major