@mrciphersmith/keryx 0.2.98 → 0.2.99

package/dist/core.js

@@ -3225,6 +3225,39 @@ function countDigits(value) {
 function containsCalendarDate(value) {
   return CALENDAR_DATE.test(value);
 }
+function enclosingToken(content, start, end) {
+  let from = start;
+  const floor = Math.max(0, start - TOKEN_SCAN_LIMIT);
+  while (from > floor && IDENTIFIER_CHAR.test(content[from - 1])) {
+    from -= 1;
+  }
+  let to = end;
+  const ceiling = Math.min(content.length, end + TOKEN_SCAN_LIMIT);
+  while (to < ceiling && IDENTIFIER_CHAR.test(content[to])) {
+    to += 1;
+  }
+  const truncated = from === floor && from > 0 && IDENTIFIER_CHAR.test(content[from - 1]) || to === ceiling && to < content.length && IDENTIFIER_CHAR.test(content[to]);
+  return { text: content.slice(from, to), truncated };
+}
+function isHexIdentifierRun(segment) {
+  return segment.length >= 8 && /^[0-9A-Fa-f]+$/.test(segment) && /[A-Fa-f]/.test(segment);
+}
+function isIdentifierFragment(content, matchStart, matchEnd) {
+  const { text: token, truncated } = enclosingToken(content, matchStart, matchEnd);
+  if (truncated) {
+    return false;
+  }
+  if (token.length === matchEnd - matchStart) {
+    return false;
+  }
+  if (UUID_TOKEN.test(token)) {
+    return true;
+  }
+  const match = content.slice(matchStart, matchEnd);
+  const before = token.slice(0, token.indexOf(match));
+  const after = token.slice(token.indexOf(match) + match.length);
+  return [...before.split(/[-_]/), ...after.split(/[-_]/)].some(isHexIdentifierRun);
+}
 function hasPhoneSeparatorShape(value) {
   if (/\s{2,}/.test(value)) {
     return false;
@@ -3262,6 +3295,9 @@ function detectPii(content) {
         if (containsCalendarDate(value)) {
           continue;
         }
+        if (isIdentifierFragment(content, m.index, m.index + m[0].length)) {
+          continue;
+        }
       }
       if (rule.validate && !rule.validate(value)) {
         continue;
@@ -3285,7 +3321,7 @@ function detectPii(content) {
   }
   return matches;
 }
-var RULES, CALENDAR_DATE;
+var RULES, CALENDAR_DATE, IDENTIFIER_CHAR, TOKEN_SCAN_LIMIT = 64, UUID_TOKEN;
 var init_pii = __esm(() => {
   RULES = [
     {
@@ -3352,6 +3388,8 @@ var init_pii = __esm(() => {
     }
   ];
   CALENDAR_DATE = /(?:19|20)\d{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])/;
+  IDENTIFIER_CHAR = /[0-9A-Za-z_-]/;
+  UUID_TOKEN = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
 });
 
 // src/security/detect/secrets.ts

package/package.json

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

package/src/gdskills/bundled/rules/core/cli-interface-design.mdc

@@ -0,0 +1,237 @@
+---
+description: "CLI surface rules: what an exit code means (0 clean, 1 found something, 2 cannot tell), machine-readable output on stdout and diagnostics on stderr, versioned --json shapes, and renaming a flag by aliasing it with a notice rather than removing it. Use when adding, changing, or retiring a command, subcommand, flag, or --json payload that people already run."
+alwaysApply: false
+---
+
+# CLI Interface Design
+
+## Purpose
+A command-line surface is a contract the moment somebody scripts it. Once a
+script reads an exit code, pipes stdout, or parses a `--json` payload, every
+later edit is either compatible or a silent breakage in someone else's CI. This
+rule fixes what those three channels mean and how a flag leaves the surface.
+
+## When To Apply
+Apply when adding a command or subcommand, adding or renaming a flag, changing
+what a command exits with, or changing the shape of anything it prints for a
+machine. It governs keryx's own CLI (`src/cli.ts` and `src/commands/**`);
+`rules/core/api-contracts.mdc` governs HTTP surfaces, and the versioning
+discipline there is the same discipline stated for a different transport.
+
+---
+
+## Rules
+
+### 1. Three exit codes, and they mean three different things
+
+keryx already runs a three-value convention, stated where it was first needed —
+`src/commands/wiki.ts:561-570`, `keryx wiki sections resolve`:
+
+- **0** — the command ran and the answer is clean.
+- **1** — the command ran and found something the caller should act on: a
+  broken link, a failing gate, a finding, a refusal.
+- **2** — the command could not tell. The registry was unreadable; the store
+  could not be opened; the input was not parseable.
+
+The reason 2 exists is written into that code: *"a script that treats 1 as
+'gone' would otherwise read an unreadable registry as a deletion."*
+`keryx memory search` adopted it deliberately and says so
+(`src/commands/memory.ts:182-196`), calling it *"reserved for 'cannot tell',
+distinct from both a completed search and a validation error."*
+
+**Two shipped commands do not honour it, and converging them is this rule's
+reason to exist:**
+
+- `keryx health run` folds `incomplete` — *"a required check that is missing,
+  skipped, unparsed or unfinished"* — into **1**, the same code as an
+  established threshold violation (`src/commands/health.ts:120-132`, with the
+  justification at `:103-112`). "Nobody ran eslint" and "eslint found 40
+  errors" are indistinguishable to a caller reading the code.
+- `keryx review` goes the other way and exits **0** on the same class of
+  answer: `reportCrossFamilyReviewProblems` and `reportFilterStatsProblems`
+  (both in `src/commands/review.ts`; cited by name because that file moves
+  under every review change, and a line number here has already gone stale
+  once) filter `not-recorded` out before failing, on the stated grounds that an
+  absence is honest. It is honest — and it is still not a pass.
+
+Three commands, one binary, three answers to "I could not tell". A new command
+uses 0/1/2 as defined above. An existing one moves toward it only with its
+consumers named, because narrowing 1 into 1-or-2 is itself a breaking change.
+
+Two settled corollaries, both worth keeping:
+
+- **A checker that reports defects and exits 0 is a checker nothing can gate
+  on** (`src/commands/skills.ts:927-951`). That code also exits non-zero on an
+  *empty* denominator — `findings: 0` over zero skills evaluated is not a pass.
+- **A wrapper forwards its child's code unchanged.** `keryx ctx run` sets
+  `process.exitCode = result.exitCode` (`src/commands/ctx.ts:210`); a wrapper
+  that collapsed every child failure to 1 would make the wrapped command
+  unusable under `set -e`.
+
+### 2. stdout is the answer, stderr is everything else
+
+The canonical statement is `src/commands/mcp.ts:78-92`: the deprecation notice
+goes to stderr *"because a bare `keryx mcp` IS the stdio MCP server: stdout
+carries JSON-RPC frames there, and a notice written to it corrupts every client
+session rather than informing anyone."* The same file routes every consumer
+diagnostic to stderr for that reason (`:41-44`).
+
+The discipline, applied:
+
+- Structured output — `--json` payloads, rendered reports, the thing a pipe is
+  for — goes to **stdout**, alone. `keryx skills verify --bundled --json`
+  writes parseable JSON to stdout and its diagnostic to stderr, and still exits
+  1 (`src/commands/skills.ts:934-947`). Verified: stdout parses, stderr is
+  empty on the clean path.
+- Progress, warnings, deprecation notices, usage errors go to **stderr**.
+- Under `--json`, a failure is *data on stdout*, not prose on stderr:
+  `keryx memory search --json` emits `{ outcome: "store-unreadable", … }` on
+  stdout and exits 2, where the plain mode prints to stderr
+  (`src/commands/memory.ts:190-195`). A machine reader gets a discriminated
+  result either way.
+- **Where this is broken today:** an unrecognised command prints its one-line
+  diagnostic to stderr and then dumps the full help to **stdout**
+  (`src/cli.ts:147-149`, `printHelp` at `:152`). Measured: `keryx bogusverb`
+  writes 9,503 bytes of help to stdout; `keryx wiki check --bogus` writes
+  4,150. Both numbers are the help text's own size and move whenever a command
+  is added — a later reading that differs is growth, not a correction to this
+  paragraph. A caller piping stdout for JSON receives a help screen instead, and
+  only the exit code says otherwise. **Help printed because of an error belongs
+  on stderr. Help printed because `--help` was asked for belongs on stdout.**
+
+### 3. A `--json` shape is versioned, deterministic, and pinned
+
+`keryx skills export` is the worked example. Removing one boolean from its
+manifest moved the version, and the code says why
+(`src/gdskills/export.ts:167-193`): *"Removing a field is a breaking change for
+anything parsing this file, so the version moves with it: a reader that still
+expects the boolean sees `schemaVersion: 2` and knows why it is absent instead
+of reading `undefined` as `false`."* The plugin manifest is a different shape
+and stays at its own `schemaVersion: 1` (`src/gdskills/export-plugin.ts:153`) —
+versions are per-shape, not per-repo. A test pins the number
+(`src/gdskills/export-runtime-builds.test.ts:108`).
+
+`keryx modules status --json` carries the other half: a `schemaVersion`, a
+deterministic key order sorted independently of authoring order *"which is what
+makes it safe to diff and to consume from a harness"*
+(`src/commands/modules.ts:197-210`), and a test that pins the version
+(`src/commands/modules.test.ts:26`).
+
+So the standard for any new machine-readable payload is:
+
+1. A top-level **object** with a `schemaVersion`. Not an array — an array
+   cannot grow a field. `rules/core/skills-storage-workflow.mdc` has said "One
+   top-level JSON object only" since it was written.
+2. Deterministic ordering, so two runs of an unchanged tree are byte-identical.
+3. A test that asserts the version and the required keys, in the same change.
+4. Adding an optional field is compatible. **Removing or renaming one bumps the
+   version**, in the same commit as the removal.
+
+**Where this is inconsistent today:** `keryx skills` serialises internal
+TypeScript objects straight to stdout at eleven call sites
+(`src/commands/skills.ts:222`, `:288`, `:398`, `:693`, `:735`, `:785`, `:822`,
+`:883`, `:935`, `:989`, `:1101`). Three of the eleven print a type that
+declares one — `LearningProposal` (`src/gdskills/learn.ts:17`, set at `:100`)
+at `:785`, and `ProjectSkillVerificationReport` (`src/gdskills/verify.ts:25`,
+set at `:96`) at `:883` and `:989`. The other eight carry no version at all.
+
+**The gap is the envelope, and it is the worse half.** `verify --bundled
+--json` emits an unversioned object (`root`, `skills`, `documents`,
+`skillNames`, `findings`); `verify --all --json` emits a bare array — `[]` when
+the registry is empty (`:973`), a list of reports otherwise (`:989`). So
+`keryx skills verify --all --json` ships `[{ "schemaVersion": 1, … }]`: each
+element versioned, the payload a caller actually parses not. That is standard 1
+failing in the direction it warns about — an array cannot grow a field, so the
+envelope can never be versioned later without the breaking change the version
+existed to avoid, however carefully each element inside it is versioned. One
+test pins one field of one of them
+(`src/commands/skills.bundled-verify.test.ts:58` asserts `findings` is `[]`). A
+rename inside any of the eight unversioned types is a CLI breaking change that
+nothing in the repository would catch.
+
+### 4. An unknown flag is refused, never ignored
+
+`rejectUnknownFlags` (`src/commands/review.ts:307-318`) is the standard, and
+its message is the argument: *"Refused rather than ignored — a flag that is
+silently dropped writes nothing and reports success."* (`:315`) It names the
+offending flag, lists what is accepted, and refuses. Every `keryx review`
+subcommand calls it.
+
+The same rule applies to a flag's **value**, not just its name. An unknown
+`--verifier` is refused because *"an unrecognised method would silently leave
+the tier at its default"* (`src/commands/review.ts:754`), and an unknown
+`--deny-tools` name is refused with the deniable names listed, because
+*"`--deny-tools web_serch` must not leave the session with web search and a
+clear conscience"* (`src/commands/interactive-agent-tools.ts:140-156`,
+`src/commands/shell.ts:1797-1798`).
+
+**Where this is inconsistent today:** the guard is per-command, and two
+implementations exist — `rejectUnknownFlags` and `rejectUnknownOptions`
+(`src/commands/workspace.ts:296-300`). Most commands have neither. Measured on
+this tree: `keryx review scope --bogus` exits 1 with a named refusal, while
+`keryx modules status --bogus --json` and `keryx skills verify --bundled
+--bogus` both exit **0** and ignore the flag. The same binary answers the same
+typo two different ways.
+
+A new command validates its flags. A flag that takes a fixed set of values
+validates the value too.
+
+### 5. A flag is renamed by aliasing it, and removed by refusing it out loud
+
+keryx has never deleted a spelling. Three patterns, all shipped, all correct:
+
+- **Rename → alias + one notice.** `keryx mcp install|uninstall` became
+  `keryx integrate` and the old spelling still works: one module translates the
+  old argument shape and calls the new implementation, so there is *"one
+  implementation and nothing to drift"* (`src/commands/mcp.ts:1-14`). It prints
+  exactly one line, on stderr, per invocation — *"A line a reader sees three
+  times in one command is a line they learn to skip, which is how deprecation
+  notices stop working at all"* (`:78-92`). A contract test asserts the retired
+  spellings still work, still write the same files, and name the replacement
+  **once** (`src/commands/mcp-naming.test.ts:453`, `:470`, `:490`).
+- **Removal → refuse by name, with the reason.** `keryx workspace handoff
+  --from` was removed because a caller could not be allowed to state it. It is
+  refused by name rather than as a generic unknown option, *"so anyone who
+  scripted it learns why it is gone instead of reading it as a typo"*
+  (`src/commands/workspace.ts:221-231`).
+- **A wrapper's own flag is consumed, not forwarded.** `keryx ctx rg --json` is
+  keryx's flag, stripped before the child command is built, because `rg --json`
+  means something else (`src/commands/ctx.ts:213-219`). Check the namespace
+  before claiming a flag name a wrapped tool already owns.
+
+**Where this is inconsistent today:** `keryx review` accepts both `--ref` and
+`--target-ref` for the same value, `--ref` winning
+(`src/commands/review.ts:147`, `:409`). There is no notice, and `--target-ref`
+appears nowhere in `keryx review --help`. An unannounced, undocumented alias is
+indistinguishable from an accidental duplicate: nothing tells a caller to
+migrate, so nothing will ever justify retiring it.
+
+A rename therefore ships four things in one change: the new spelling, the old
+one still working through the same implementation, one stderr notice naming the
+replacement, and a test that asserts both.
+
+---
+
+## The three that are not negotiable
+
+A nonzero exit never means "I could not tell" in a command that also uses
+nonzero to mean "I found something" — pick 2 for the first. A `--json` payload
+never loses or renames a field without a `schemaVersion` bump in the same
+commit. An old flag spelling is never deleted: it is aliased with a notice, or
+refused by name with the reason.
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Exit 1 is fine, the message explains which kind of failure it was" | Messages are for people; scripts read the code. `keryx health run` cannot distinguish "eslint was skipped" from "eslint failed" today, and that is the gap, not a style preference |
+| "Nobody parses this `--json` yet, so I can change the shape freely" | You cannot observe who parses a published CLI's output. The version field costs one line and is the only thing that lets a reader tell absence from a downgrade |
+| "I'll print the warning to stdout, it's more visible there" | stdout is the pipe. A warning there corrupts every consumer that expected data — which is why `keryx mcp` routes its notice to stderr instead |
+| "The old flag is unused, I'll just delete it" | "Unused" means "no usage you can see". Alias it with a notice, or refuse it by name with the reason — both cost less than a silent breakage in someone's CI |
+| "An unrecognised flag is harmless, the command still does the right thing" | It does less than the operator asked and reports success. That is the failure `rejectUnknownFlags` was written for |
+| "It's just a help screen on stdout, who cares" | Nine kilobytes of it, where the caller expected JSON. Error output is error output regardless of how friendly it reads |
+| "I'll add the schemaVersion when the shape actually changes" | The first change is the one that needs it, and by then the unversioned readers already exist |
+
+**IRON LAW: ONCE A COMMAND IS PUBLISHED, ITS EXIT CODE, ITS STDOUT, AND ITS `--json` SHAPE ARE A CONTRACT — CHANGE THEM THE WAY YOU WOULD CHANGE AN API, OR NOT AT ALL.**

package/src/gdskills/bundled/rules/core/definition-of-done.mdc

@@ -0,0 +1,116 @@
+---
+description: "The single standing bar for calling a change done: evidence per criterion, gates that actually ran after the last edit, nothing disabled to go green, the diff committed. Use when reporting a task complete, accepting a worker's result, or deciding whether remaining work may be deferred."
+alwaysApply: false
+---
+
+# Definition Of Done
+
+## Purpose
+State, once, the bar a change must clear before any agent calls it done — so
+that "done" means the same thing to the worker that reports it and the
+orchestrator that accepts it. Six rules and two skills each state a piece of
+this bar today; this rule is the join, and it names which document owns which
+piece so the pieces cannot drift apart.
+
+## When To Apply
+Apply at the moment of reporting: before a worker writes its `STATUS:` line,
+before an orchestrator accepts a worker's result, and before a flow's
+acceptance criteria are confirmed. It applies to every change that ships —
+code, rule, skill, schema or document — not only to code with tests.
+
+---
+
+## The Bar
+
+A change is done when all five hold. Each is a fact about this working tree
+that can be checked by reading output, not a judgement about how the work felt.
+
+1. **Every acceptance criterion has named evidence.** For each criterion: the
+   command that demonstrates it, and that command's actual result. A criterion
+   whose evidence is "implemented" or "verified" has no evidence.
+2. **Every gate that applies to the changed files ran to completion, after the
+   last edit, in this tree, and passed** — lint, type-check, tests. Ran *after
+   the last edit*: a green result captured before the final change is not a
+   result about the change being reported.
+3. **A gate that did not run is not a pass.** A missing binary, a filtered
+   suite, a skipped file — each is `skipped`, never `pass`. Zero tests executed
+   is not zero failures.
+4. **Nothing was disabled to get there.** No test deleted, `.skip`ped or
+   `.only`d; no assertion removed; no threshold lowered; no suppression,
+   `eslint-disable` or `@ts-expect-error` added, unless that suppression *is*
+   the change and is stated as such in the report.
+5. **The diff is committed** at the task boundary, by whoever owns commits.
+
+If any of the five fails, the status is not `DONE`. Not `DONE` with the gap in
+a note; not `DONE_WITH_CONCERNS` with the gap as a concern. Report `BLOCKED`,
+or finish the work.
+
+---
+
+## What Each Document Owns
+
+This rule does not restate these; it points at them. When one of them changes,
+this list is what says whether the bar moved.
+
+| Document | Owns |
+|---|---|
+| `rules/core/tdd-workflow.mdc` | Clause 2 for tests specifically: the red-green-refactor sequence, and the invariant that `STATUS: DONE` requires a green suite (its Iron Law 1, and Iron Law 3 forbidding deletion of tests to get there — clause 4's test case). |
+| `.metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md` | Clause 3: the gate decision, and the ruling that a check which did not run reports `status: skipped`, never `pass`. It also owns the distinction between the gate's result and the skill's own `STATUS:`. |
+| `rules/core/implementation-doc-mandate.mdc` | The shape of the evidence for clauses 1 and 2 — the Verification Gate block, the Acceptance Criteria Met list, and its Iron Law 3: the numbers must come from an independent verifier, not from self-assessment. |
+| `rules/core/subagent-status-protocol.md` | How the result is reported: `STATUS:` on line one, the five statuses, and the verification block every `DONE` response carries. |
+| `rules/core/git-concurrency.mdc` | Clause 5: a task is not done until its diff is committed, whether the worker or the orchestrator commits it. |
+| `.metaproject/skills/gdskills/orchestration/task-implementer/SKILL.md` | The worker-side reading of clause 3: skipped verification is a failed verification, and partial is not done. |
+| `rules/core/gproject-contracts.mdc` | The gproject return payload only. It is silent on clauses 2-5; that silence is not an exemption, and a gproject subagent reporting `DONE` still owes the verification block from `rules/core/subagent-status-protocol.md`. |
+| `rules/core/requirements-package-standard.mdc` | Clause 2 for a documentation package, where the gates are structural (required files, versions, links, honest status) rather than lint and tests. |
+
+Two readings of `DONE_WITH_CONCERNS` are in circulation, and this rule settles
+them: it is for information the orchestrator needs about work that **cleared
+all five clauses** — an interpretation made, a workaround for something
+non-blocking, a warning worth seeing. It is not a lower bar. An unmet
+acceptance criterion, a suite that was not run, or an uncommitted diff is not a
+concern attached to a completed task; it is an incomplete task.
+
+---
+
+## The Standing Bar And A Flow's Frozen Acceptance Criteria
+
+They are conjunctive. Neither overrides the other, and the question "which
+wins" has a definite answer in each direction:
+
+- **The frozen criteria fix the scope.** They say what must be true *of this
+  change* — and only the flow can say that. The bar cannot add a criterion, and
+  satisfying the bar does not satisfy a criterion the work never touched.
+- **The bar fixes the evidence, and is not waivable by silence.** Criteria that
+  say nothing about tests, lint or committing do not thereby excuse them. A
+  flow cannot lower the standing bar by omitting it, because the criteria were
+  frozen to stop scope drifting — not to enumerate the baseline every change
+  already owes.
+
+So: **a change that meets every frozen criterion but fails a clause of the bar
+is not done**, and a change that clears the bar while a criterion is unmet is
+not done either.
+
+When a frozen criterion genuinely conflicts with the bar — it asks for
+something that cannot be delivered without failing a clause — the criterion is
+not quietly reworded to match what was built. It changes through
+`keryx flow ac update <id> --reason "<why>"`, with the conflict as the reason,
+per `.metaproject/skills/gdskills/orchestration/flow-orchestrator/SKILL.md`.
+Rewriting a criterion to describe the work is how a flow loses the only record
+of what it set out to do.
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Everything passed, I'll just make the last small edit and report" | Clause 2 is about *this* tree after *this* edit. A result captured before the final change is evidence about a tree that no longer exists |
+| "The test command printed no failures, so it's green" | No failures and no tests are the same output. Read the count: zero executed is clause 3, not a pass |
+| "It's done except for the one flaky test / the docs / the commit" | "Done except for" is the phrase this rule exists to delete. The exception is the part that is not done, and it decides the status |
+| "I'll report DONE_WITH_CONCERNS and name the unmet criterion as a concern" | `DONE_WITH_CONCERNS` is for information about completed work. An unmet criterion is incomplete work wearing a success status |
+| "The lint binary isn't installed here, so there is nothing to fail" | A check that cannot run has told you nothing. Say it was skipped and which one; do not convert absence of a result into a result |
+| "The orchestrator will run the gates anyway, so I don't have to" | Two agents each assuming the other verified is how a change reaches review with nothing ever having run against it |
+| "The acceptance criterion doesn't mention lint, so lint isn't in scope" | The criteria bound the scope of the work, not the evidence every change owes. Silence is not an exemption |
+
+**IRON LAW: A STEP THAT WAS SKIPPED IS A STEP THAT FAILED. "DONE EXCEPT FOR X"
+IS NOT DONE — IT IS BLOCKED ON X.**

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

@@ -25,13 +25,42 @@ Before creating or editing a skill, ask and confirm:
 - Project-local skill: `.metaproject/project-skills/<skill-name>/`.
 
 ## Required Source Layout
-- `SKILL.md` — canonical source of truth
-- `SKILL.cursor.md` — Cursor-specific variant (optional; falls back to SKILL.md)
-- `SKILL.codex.md` — Codex-specific variant (optional; falls back to SKILL.md)
-- `SKILL.zed.md` — Zed-specific variant (optional; falls back to SKILL.md)
-- `SKILL.opencode.md` — OpenCode-specific variant (optional; falls back to SKILL.md)
+- `SKILL.md` — canonical source of truth, the shared build used by every runtime
+- `SKILL.cursor.md` — Cursor-specific variant, present only where Cursor's build genuinely differs from `SKILL.md` (falls back to `SKILL.md` otherwise)
+- `SKILL.codex.md` — Codex-specific variant, present only where Codex's build genuinely differs from `SKILL.md` (falls back to `SKILL.md` otherwise)
+- `SKILL.zed.md` — Zed-specific variant, present only where Zed's build genuinely differs from `SKILL.md` (falls back to `SKILL.md` otherwise)
+- `SKILL.opencode.md` — OpenCode-specific variant, present only where OpenCode's build genuinely differs from `SKILL.md` (falls back to `SKILL.md` otherwise)
 
-`SKILL.md` is always required. Platform variants are optional — if absent, `keryx update` installs `SKILL.md` as fallback.
+`SKILL.md` is always required. A `SKILL.<runtime>.md` variant is the
+exception, not the norm: create one only when that runtime's build genuinely
+differs from `SKILL.md`, and never add one as an identical copy. Falling
+back to `SKILL.md` is the normal case for every runtime without a variant —
+for `keryx update`/`keryx init` (installed mirror) and for `keryx skills
+export`/`keryx skills sync` (global destinations) alike — not a degraded
+path.
+
+"Genuinely differs" covers two cases, and only two:
+
+1. **Different instructions.** The runtime needs prose `SKILL.md` does not
+   carry, or must not carry.
+2. **A different `metadata.compatible_harnesses`.** That field is the
+   machine-readable CSV of supported harnesses, so its correct value is
+   per-build by construction — a build cannot share a harness list that
+   excludes the harness reading it. This is the only field in the tree of
+   which that is true.
+
+Case 2 is why fourteen shipped builds differ from their `SKILL.md` by exactly
+one line: the seven `gproject-*` subagent skills under `planning/`
+(`project-discovery`, `problem-definer`, `patterns-researcher`, `planner`,
+`consistency-checker`, `spec-writer`, `stack-advisor`) each ship a
+`SKILL.codex.md` and a `SKILL.cursor.md` that add
+`compatible_harnesses: "cursor,codex,zed,opencode"`. Their `SKILL.md` declares
+no harness list, because it is the Claude build and cannot carry one that
+excludes Claude. These builds are NOT identical copies and must not be deleted
+as such; `src/gdskills/build-parity.test.ts` exempts this one hunk, by name,
+for these seven skills only, and its allow-list is where any widening has to be
+argued. Every other difference between a build and its `SKILL.md` is drift and
+gets reconciled.
 
 ## Frontmatter Fields (Agent Skills spec alignment)
 
@@ -69,6 +98,50 @@ back toward the spec:
   typed payloads to subagent workers instead, which the spec does not attempt
   to address.
 
+## Length Ceilings
+
+Every shipped skill has a line-count ceiling recorded in
+`src/gdskills/skill-length-ceilings.ts`, set to the skill's length on the day
+the file was introduced; a skill with no entry is bounded by the default (500
+lines, the point at which a skill should be split). `keryx skills verify
+--bundled` reports `anatomy:length` when a skill passes its ceiling.
+
+A ceiling **moves down**, never up:
+
+- trimming a skill — moving reference material into a sibling document, cutting
+  a section that no longer changes behaviour — lowers the ceiling to the new
+  count in the same change;
+- a skill that needs more room than its ceiling allows is split, or its
+  reference material moves out. Raising the number to clear the finding is the
+  one edit this rule forbids: it converts a measured limit into a record of
+  whatever the file grew to.
+
+`keryx skills verify --bundled` states the same remedy in the same words, and
+cites this section by name, so the finding and the rule cannot drift apart. The
+`anatomy:length` message reads, after the count:
+
+> Split the skill, or move reference material into a sibling document, and lower
+> the ceiling to the new count in the same change. A ceiling only ever moves
+> DOWN: raising it is the one edit rules/core/skills-storage-workflow.mdc
+> ("Length Ceilings") forbids, because it converts a measured limit into a record
+> of whatever the file grew to.
+
+Changing either text without the other is the drift this quotation exists to
+prevent; `src/gdskills/bundled-eval.ts` is where the message lives.
+
+A ceiling is not a statement that the skill's current size is right — several
+shipped skills are far past the default and were recorded as they stood. It
+bounds unnoticed growth, which is the part no other check can see.
+
+Editing a skill is therefore a two-file change. Every recorded ceiling equals
+that skill's current count today, so adding a sentence needs a compensating
+deletion or a split: recount the file (`wc -l SKILL.md`) and write that number
+to the skill's key in `src/gdskills/skill-length-ceilings.ts` in the SAME
+commit. A new skill needs a new entry; a deleted skill needs its entry removed.
+`keryx skills verify --bundled` only reports `lines > ceiling`, so a TRIM that
+leaves the old, higher number behind passes locally and fails the
+ceiling-equals-count check in CI.
+
 ## Global Sync Mapping
 Global sync only ever reaches a **project-local skill**
 (`.metaproject/project-skills/<skill-name>/`) that has first been exported for
@@ -83,10 +156,10 @@ written by `keryx init`/`keryx update`), which stays inside the project.
 
 Once a project skill is exported for a runtime, `keryx skills sync --runtime
 <runtime> --global` copies it from `.metaproject/runtime/skills/<runtime>/` to:
-- `cursor` → `~/.cursor/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.cursor.md`, or `SKILL.md` as fallback)
-- `codex` → `${CODEX_HOME:-~/.codex}/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.codex.md`, or `SKILL.md` as fallback)
-- `zed` → `~/.config/zed/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.zed.md`, or `SKILL.md` as fallback)
-- `opencode` → `~/.config/opencode/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.opencode.md`, or `SKILL.md` as fallback)
+- `cursor` → `~/.cursor/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.cursor.md` when the skill ships one, otherwise `SKILL.md`)
+- `codex` → `${CODEX_HOME:-~/.codex}/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.codex.md` when the skill ships one, otherwise `SKILL.md`)
+- `zed` → `~/.config/zed/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.zed.md` when the skill ships one, otherwise `SKILL.md`)
+- `opencode` → `~/.config/opencode/skills/<module>-<skill-name>/SKILL.md` (built from `SKILL.opencode.md` when the skill ships one, otherwise `SKILL.md`)
 
 These four global destinations are written only by the explicit, opt-in
 `keryx skills sync --runtime <runtime> --global` command — never as a side
@@ -96,7 +169,7 @@ those instead.
 
 ## Mandatory Behavior
 1. Always create/update `SKILL.md` as the canonical source.
-2. Create platform variants only when platform-specific adaptations are needed; otherwise `SKILL.md` serves all platforms via fallback.
+2. Create a `SKILL.<runtime>.md` only when that runtime's build genuinely differs from `SKILL.md` — either in its instructions or in its `metadata.compatible_harnesses`, the two cases named under Required Source Layout — never as an identical copy. Otherwise `SKILL.md` serves that runtime via fallback; that fallback is the normal case, not an exception.
 3. Keep all profiles aligned in structure and intent.
 4. Validate skills before sync.
 5. For a **project-local** skill only: export it per runtime first (`keryx skills export <skill-name> --runtime <runtime>`), then sync every global destination that applies (`cursor`, `codex`, `zed`, `opencode` — four in total) with `keryx skills sync --runtime <runtime> --global`, run once per runtime that needs it. A shipped skill cannot be exported and has no global-sync route — it reaches a runtime only via the project-local installed mirror (`keryx update`/`keryx init`).
@@ -154,6 +227,23 @@ If validation fails, do not sync.
 ## Forbidden
 - Do not create skills in `~/.cursor/skills-cursor/`.
 
+## Rejected Changes
+Scope: keryx's own bundled skills and rules
+(`src/gdskills/bundled/**` in the keryx repository) only. This rule ships to
+every project via `keryx init`/`keryx update`, but the ledger below exists
+only in the keryx source repo — this section does not apply to
+project-local skills (`.metaproject/project-skills/<skill-name>/`).
+
+- Before proposing a change to a shipped skill or rule, search
+  `docs/skills/rejected-skill-changes.md` in the keryx repository for that
+  skill and that idea.
+- When a change to a shipped skill or rule is rejected (review, a
+  routing/behaviour-eval regression, or a user/maintainer decision), append a
+  row to that ledger — in the same change, on the default branch (`main`) —
+  recording what was tried, why it was rejected, and the evidence (e.g. a
+  routing-eval rank or behaviour-eval number, before → after). Never edit or
+  delete an existing row.
+
 ## Apply Changes Workflow
 Edit skills under `src/gdskills/bundled/skills/<category>/<skill-name>/`
 (shipped) or `.metaproject/project-skills/<skill-name>/` (project-local).

package/src/gdskills/bundled/rules/core/subagent-status-protocol.md

@@ -44,6 +44,12 @@ Task fully complete. All acceptance criteria met. Orchestrator can continue the
 ### `DONE_WITH_CONCERNS`
 Task complete, but the orchestrator should know something before continuing. This is NOT a failure — it is a completed task that carries information the orchestrator needs to make a good decision.
 
+"Complete" here means the bar in `rules/core/definition-of-done.mdc`, which owns
+what `DONE` costs and is not restated here. `DONE_WITH_CONCERNS` reports
+information *about work that cleared that bar*; it is never a lower bar. If a
+clause of the bar fails — an unmet acceptance criterion, a gate that did not
+run, an uncommitted diff — the status is `BLOCKED`, not this one.
+
 Use when:
 - Implementation required a meaningful interpretation of ambiguous criteria
 - A workaround was used for a non-blocking issue
@@ -58,6 +64,7 @@ Use when:
 - Two valid approaches exist with significantly different tradeoffs and the subagent cannot choose alone
 - A command failed in a way that requires orchestrator-level intervention (not a self-fixable error)
 - The task scope needs to be clarified before proceeding
+- An acceptance criterion is unmet, or another clause of `rules/core/definition-of-done.mdc` fails, and you cannot close it yourself
 
 Do NOT use `BLOCKED` for errors you can fix yourself. Self-fix first (up to your retry limit), then report `BLOCKED` if still stuck.
 
@@ -186,10 +193,10 @@ The following thoughts indicate a subagent is about to violate the protocol. Rej
 
 - **"I'll add a note at the end instead of BLOCKED"** — Notes at the end are invisible to automated orchestrators. If you are blocked, the status must be `BLOCKED`. The note goes in the `## Reason` field.
 
-- **"It's mostly done, DONE_WITH_CONCERNS feels like admitting failure"** — `DONE_WITH_CONCERNS` is not a failure status. It is a success status with an attached signal. Use it freely when something is worth the orchestrator knowing.
+- **"It's mostly done, DONE_WITH_CONCERNS feels like admitting failure"** — `DONE_WITH_CONCERNS` is not a failure status. It is a success status with an attached signal, for work that already cleared the bar in `rules/core/definition-of-done.mdc`. Use it freely when something is worth the orchestrator knowing — and not at all when the bar was not cleared.
 
 - **"NEEDS_CONTEXT would slow things down, I'll just guess"** — Guessing propagates errors downstream. One `NEEDS_CONTEXT` and a re-dispatch is cheaper than four tasks built on a wrong assumption.
 
-- **"I didn't meet one criterion but I'll say DONE and mention it in notes"** — If an acceptance criterion is not met, the status is not `DONE`. Use `DONE_WITH_CONCERNS` and name the unmet criterion in the concerns section.
+- **"I didn't meet one criterion but I'll say DONE and mention it in notes"** — If an acceptance criterion is not met, the status is not `DONE` — and it is not `DONE_WITH_CONCERNS` either. An unmet criterion is incomplete work, not information about complete work: report `BLOCKED`, name the criterion in `## Reason`, and say in `## What I need from orchestrator` what would let you meet it. Per `rules/core/definition-of-done.mdc`, which owns that ruling.
 
 - **"The orchestrator will figure it out from my explanation"** — The orchestrator reads `STATUS:` on line 1. Everything else is secondary. Do not make the orchestrator parse free text to determine the outcome.