@mrciphersmith/keryx 0.2.97 → 0.2.99

package/src/gdskills/bundled/rules/core/git-concurrency.mdc

@@ -0,0 +1,101 @@
+---
+description: "Git concurrency rules: no git stash in a shared tree, explicit pathspecs instead of git add -A, git -C <absolute path> in worktrees, commit at task boundaries. Use when multiple agents or sessions share one checkout or work in parallel git worktrees."
+alwaysApply: false
+---
+
+# Git Concurrency
+
+## Purpose
+Prevent one agent's git operation from destroying or corrupting another agent's or session's in-flight work when multiple sessions or subagents share a checkout, a stash stack, or run in parallel git worktrees.
+
+## When To Apply
+Apply whenever more than one agent session or subagent may be active against the same repository — parallel `task-implementer` waves, concurrent flow workers, or any dispatch that runs inside a worktree cut for a specific task. Cited by `flow-orchestrator`, `job-orchestrator`, and `task-implementer`.
+
+---
+
+## Rules
+
+### 1. Never `git stash`, in any form, in a shared tree
+The stash stack is a single list shared by the main checkout and every worktree cut from it. A "scoped" `git stash push -- <file>` still resets that file to its last commit and pushes the diff onto the shared stack — another lane's `git stash pop` can then restore your entry over its own uncommitted work, or vice versa. This happened here: a worker's scoped `git stash push -- <file>` reset the file and briefly wiped another task's uncommitted work.
+
+BAD:
+```bash
+git stash push -- src/foo.ts   # resets the file now; the diff joins a stack every worktree can pop
+```
+
+GOOD — need a temporary revert to test a hypothesis:
+```bash
+# Make the change with the Edit tool; to undo it, edit it back the same way.
+# If you need to keep a copy while you experiment, copy the file out instead:
+cp src/foo.ts /path/to/scratch/foo.ts.bak
+```
+Never reach for `git stash` — scoped or not — to get there and back.
+
+### 2. Explicit pathspecs, never `git add -A` / `--all` / `.`
+An unscoped add stages every changed file in the tree, including another lane's in-flight edits, into a commit that has nothing to do with them. This happened here: `git add -A` staged another lane's in-flight files into an unrelated commit.
+
+BAD:
+```bash
+git add -A && git commit -m "..."
+```
+
+GOOD:
+```bash
+git add src/foo.ts src/foo.test.ts
+git commit -m "..."
+```
+
+### 3. `git -C <absolute-worktree-path>` for every git command in a worktree
+A bare `git` command runs against whatever the shell's cwd happens to be. Across a session's tool calls that cwd can silently persist from a previous command or reset out of the worktree — a bare `git restore` or `git add -A && git commit && git push` then hits the wrong tree. This happened here: it once pushed another session's work to `main`.
+
+BAD:
+```bash
+cd /path/to/worktree
+# ...several tool calls later, the cwd assumption has drifted...
+git commit -am "fix"
+```
+
+GOOD:
+```bash
+git -C /absolute/path/to/worktree status
+git -C /absolute/path/to/worktree add src/foo.ts
+git -C /absolute/path/to/worktree commit -m "fix(foo): ..."
+```
+
+### 4. Commit at every task boundary
+Uncommitted work handed between workers — "the next task can build on my uncommitted edit" — has been destroyed here by a concurrent checkout running in another lane. A task is not done until its diff is committed; leaving it uncommitted is leaving it deletable by someone else's git command.
+
+This holds whether or not the worker itself commits. When auto-commit is enabled, the worker commits its own diff before reporting. When it is disabled, the worker does not commit — but the task is still not done until the diff is committed, so it reports its exact changed-file list (see "Reporting Back" below) and the orchestrator stages and commits those paths at the task boundary. Either way, the task's diff is committed at the boundary by whoever owns commits — never left uncommitted for a later step to inherit.
+
+---
+
+## Pinning A Dispatch To Its Worktree
+
+Every dispatch into a multi-task or multi-agent run MUST pin the exact worktree before its first write:
+
+1. State the absolute worktree root in the dispatch prompt — never a relative path or "the current directory".
+2. The dispatched agent's first action is:
+   ```bash
+   cd <absolute-worktree-root> && pwd && git branch --show-current
+   ```
+   and confirms the printed path and branch match what the dispatch specified.
+3. Re-run that check immediately before the first write, not only at the start — a long-running dispatch can have its cwd reset by an unrelated tool call in between.
+4. Every git command after that uses `git -C <absolute-worktree-root>`, never a bare `git`.
+
+## Reporting Back
+
+A worker reports its **exact file list** — the paths it actually changed, nothing inferred — so "the orchestrator stages those paths only". An orchestrator that runs `git add -A` on the strength of a worker's prose summary has recreated Rule 2 at one level up; the reported file list is what makes an explicit-pathspec `git add` possible at the orchestrator level too.
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "It's a scoped stash, I'll pop it right away" | The stash stack is shared by every worktree; "right away" does not stop another lane's `pop` from landing between your push and your pop |
+| "`git add -A` is fine, I only touched my files" | `git add -A` stages whatever is dirty in the tree, not what you touched — another lane's dirty files get staged too, silently |
+| "cwd is still the worktree" | Confirm it, don't assume it — `pwd` costs nothing, and a wrong assumption here ships to the wrong branch |
+| "I'll commit everything at the end in one big commit" | Uncommitted work is exactly what a concurrent stash, add, or checkout destroys; commit at each boundary, not at the end |
+| "This repo isn't shared right now, so it's fine just this once" | The failure mode is a race: correct 99 times and destructive the 100th is still destructive, and nothing here can tell you which run you're on |
+
+**IRON LAW: NEVER `git stash` OR `git add -A`/`--all`/`.` IN A TREE ANOTHER SESSION MIGHT BE TOUCHING, AND NEVER RUN A GIT COMMAND WITHOUT PINNING IT TO AN ABSOLUTE WORKTREE PATH FIRST.**

package/src/gdskills/bundled/rules/core/implementation-plans.mdc

@@ -1,24 +1,34 @@
 ---
-description: "Rules for creating implementation plans in date-stamped requirement folders."
+description: "Rules for creating implementation plans as part of a requirements package. Layout follows requirements-package-standard.mdc."
 alwaysApply: false
 ---
 
 # Implementation Plans Rules
 
 ## Purpose
-Define structure and storage for implementation plans.
+Define structure and storage for an implementation plan that belongs to a
+requirements package.
 
 ## When To Apply
-Apply when creating or updating an implementation plan document.
+Apply when creating or updating an implementation plan document that lives
+inside a requirements package (`docs/requirements/<name>/`). Two other
+locations are outside this rule's scope and are governed by
+`documentation-management.mdc` instead:
+- A standalone plan not tied to a requirements package: `docs/plans/<name>/`.
+- A feature/branch analysis plan written by the `feature-analyzer` skill:
+  `docs/analysis/<feature>/implementation-plan.md`.
 
 ## Location
-`<DOCS_ROOT>/requirements/<requirement-name>/<YYYY-MM-DD>/`
+`implementation-plan.md` for a requirements-package plan lives inside that
+package, per `requirements-package-standard.mdc`:
+`docs/requirements/<requirement-name>/implementation-plan.md`. No date
+folder — the plan is versioned in place alongside README/prd/specification.
+For the standalone and analysis locations, see `documentation-management.mdc`.
 
 ## Mandatory Behavior
-1. Ask for target location and folder name before creation.
-2. If requirement folder does not exist, create requirements first.
-3. Use a new date folder for every new plan iteration.
-4. Generate and keep synchronized language variants: `ru`, `en`, `ai`.
+1. Ask for target location and folder name before creation, if not already established.
+2. If the plan belongs inside a requirements package and that package does not exist yet, create it first (README, prd, specification) before adding the plan.
+3. Update `implementation-plan.md` in place for each new iteration and bump its `Version` field instead of forking a new folder.
 
 ## Required Plan Structure
 1. High-level plan
@@ -28,22 +38,24 @@ Apply when creating or updating an implementation plan document.
 ## Output Contract
 - Plan files MUST be Markdown (`.md`).
 - Code or command examples MUST be fenced code blocks.
+- Include the `Version: x.y.z` field directly under the H1, per `requirements-package-standard.mdc`.
 
 ## Red Flags — Stop and re-read this rule if you are thinking:
 
 | Rationalization | Why it's wrong |
 |---|---|
 | "The plan is in my head, I don't need to write it down" | An unwritten plan cannot be reviewed, versioned, or handed to another agent |
-| "I'll use the existing folder instead of creating a new date folder" | Date folders are the audit trail — overwriting one erases the iteration history |
+| "I'll start a new folder instead of updating the package in place" | The package is the single source of truth; forking a parallel copy is exactly what `requirements-package-standard.mdc` forbids |
 | "The user knows what we discussed, I'll skip asking for the folder name" | The location question is a confirmation gate, not a convenience; skipping it causes misplaced files |
-| "I'll write the plan in English only since that's what the user spoke" | All three variants (ru/en/ai) are required — omitting one breaks downstream tooling |
 
-**IRON LAW: ALWAYS ASK FOR TARGET LOCATION AND FOLDER NAME BEFORE CREATING ANY PLAN FILE, AND GENERATE ALL THREE LANGUAGE VARIANTS.**
+**IRON LAW: ALWAYS ASK FOR TARGET LOCATION AND FOLDER NAME BEFORE CREATING A REQUIREMENTS-PACKAGE PLAN FILE, AND KEEP IT INSIDE ITS REQUIREMENTS PACKAGE. FOR A STANDALONE OR FEATURE-ANALYSIS PLAN, USE `documentation-management.mdc` INSTEAD.**
 
 ## Template
 ```markdown
 # <Plan Name>
 
+Version: 0.1.0
+
 ## 1. High-Level Plan
 - Objective:
 - Scope:

package/src/gdskills/bundled/rules/core/mobx-store-template.mdc

@@ -3,6 +3,7 @@ description: "Reference template and checklist for MobX store structure and asyn
 alwaysApply: false
 globs:
   - "**/*store*.ts"
+stack_requires: "mobx"
 ---
 
 # MobX Store Template

package/src/gdskills/bundled/rules/core/nestjs-dto.mdc

@@ -4,6 +4,7 @@ alwaysApply: false
 globs:
   - "**/*dto*.ts"
   - "**/dto/**/*.ts"
+stack_requires: "nestjs"
 ---
 
 # NestJS DTO Rules

package/src/gdskills/bundled/rules/core/playwright-testing.mdc

@@ -5,6 +5,7 @@ globs:
   - "e2e/**"
   - "**/*.spec.ts"
   - "playwright.config.ts"
+stack_requires: "playwright"
 ---
 
 # Playwright E2E Testing Guidelines

package/src/gdskills/bundled/rules/core/requirements-management.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Rules for creating and updating requirement documents with multilingual outputs."
+description: "Rules for creating and updating requirement documents. Layout and versioning follow requirements-package-standard.mdc."
 alwaysApply: false
 ---
 
@@ -11,15 +11,20 @@ Standardize how requirement sets are created and maintained.
 ## When To Apply
 Apply when creating or updating requirement documents.
 
-## Location
-`<DOCS_ROOT>/requirements/<requirement-name>/<YYYY-MM-DD>/`
+## Location & Layout
+Follow `requirements-package-standard.mdc` for the package layout
+(`docs/requirements/<name>/{README,prd,specification}.md` plus optional
+files), the `Version: x.y.z` field, and the verification/review contracts. Do
+not restate that layout here, and do not date-stamp the folder or fork
+`ru`/`en`/`ai` copies — one set of documents, versioned in place, is the
+standard.
 
 ## Mandatory Behavior
 1. Ask for target location and requirement folder name before writing.
 2. Confirm naming convention before creation.
-3. Always create a new date-stamped subfolder; do not overwrite old sets.
-4. Generate synchronized `ru`, `en`, and `ai` versions.
-5. Document assumptions and open questions explicitly.
+3. Reuse the existing package folder for the topic; update documents in place
+   and bump their `Version` field rather than creating a parallel copy.
+4. Document assumptions and open questions explicitly.
 
 ## Output Contract
 - Use Markdown (`.md`) only.
@@ -28,8 +33,7 @@ Apply when creating or updating requirement documents.
 
 ## Workflow
 1. Capture request.
-2. Clarify folder/location.
-3. Create folder structure.
-4. Create all required language files.
-5. Validate synchronization.
-6. Ask whether to apply changes.
+2. Clarify folder/location under `docs/requirements/<name>/`.
+3. Create or update the package per `requirements-package-standard.mdc`.
+4. Document assumptions and open questions.
+5. Ask whether to apply changes.

package/src/gdskills/bundled/rules/core/rule-management-workflow.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Workflow for adding or editing rules in the AGENTS.mdc + rules/core structure."
+description: "Workflow for adding or editing rules in the AGENTS.md + rules/core structure."
 alwaysApply: false
 ---
 
@@ -12,10 +12,19 @@ Define a deterministic workflow for adding, editing, and syncing rules.
 Apply when user asks to create, update, move, reorganize, or sync rules.
 
 ## Source of Truth
-- Repository source: `.metaproject/rules`
-- Root always-on file (plain): `AGENTS.md`
-- Root always-on file (Cursor): `AGENTS.mdc` (frontmatter wrapper around AGENTS.md)
-- Thematic files: `.metaproject/rules/core/*.mdc`
+- Keryx's own shipped rules: `src/gdskills/bundled/rules/core/*.mdc` in the
+  keryx repository — installed into `.metaproject/rules/core/*.mdc` by `keryx
+  init`/`keryx update` (the installed copy is regenerated wholesale on every
+  run; edit the source, not the installed copy). There is no `keryx install`
+  command.
+- A project's own instructions: the project's root `AGENTS.md`/`CLAUDE.md`.
+  Edit those files directly, then run `keryx rules sync` (or `keryx rules
+  distill` for a large entrypoint) to import them into
+  `.metaproject/rules/<name>.md` (e.g. `agents-md.md`, `claude-md.md`) and
+  refresh the routing index. A project-owned rule never lives under
+  `.metaproject/rules/core/` — that tree mirrors only keryx's own shipped
+  rules and is overwritten wholesale by `keryx init`/`keryx update`.
+- Root always-on file: `AGENTS.md`
 
 ## Mandatory Clarification Step
 Before creating or editing any rule, the agent MUST ask and confirm:
@@ -25,24 +34,30 @@ Before creating or editing any rule, the agent MUST ask and confirm:
 4. Rule scope and trigger conditions
 
 ## Mandatory Behavior
-1. Update or create thematic rule files only under `rules/core`.
+1. Update or create keryx's shipped thematic rule files only under
+   `src/gdskills/bundled/rules/core/` (installed to `.metaproject/rules/core/`).
+   A project's own instructions belong in its root `AGENTS.md`/`CLAUDE.md`,
+   imported via `keryx rules sync`/`keryx rules distill`.
 2. Keep all rule files in English.
 3. Keep frontmatter valid YAML.
-4. If core files changed, update `AGENTS.md` catalog (and keep AGENTS.mdc in sync).
+4. If core files changed, keep `AGENTS.md` consistent and re-run synchronization.
 5. Run synchronization only after source files are updated.
 
 ## How to Run Synchronization
-After editing rules under `.metaproject/rules/` or `AGENTS.md`, sync to all targets:
+After editing rules under `src/gdskills/bundled/rules/`, run `keryx update`
+(or `keryx init` on a fresh project) to regenerate the installed copy at
+`.metaproject/rules/`. This stays inside the project — it never writes to a
+home-directory (`~`) location.
+
+After editing the project's own root `AGENTS.md`/`CLAUDE.md`, run:
 
 ```bash
-keryx update
+keryx rules sync
 ```
 
-### Sync Targets
-- `~/.cursor/rules/AGENTS.md` — Cursor global rules
-- `~/.codex/AGENTS.md` — Codex global rules
-- `~/.config/zed/AGENTS.md` — Zed global rules
-- `~/.config/opencode/AGENTS.md` — OpenCode global rules
+This imports the root `AGENTS.md`/`CLAUDE.md` into `.metaproject/rules/` and
+refreshes the routing index. It is also project-local and writes no
+home-directory (`~`) path.
 
 ## Rule File Standard
 Every core rule MUST include:

package/src/gdskills/bundled/rules/core/shared-definitions.mdc

@@ -69,7 +69,7 @@ Two modules must recognise the same terminal prompt.
 ```ts
 // Wrong — a claim, unchecked. Four attempts to restate this rule from a
 // reading of the other module each got it wrong in a different way.
-/** Same signals scripts/watchdog.ts uses. */
+/** Same signals the watchdog script uses. */
 const SIGNAL = /do you want to proceed\?/i;
 ```
 

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

@@ -20,7 +20,9 @@ Whoever is about to rely on a project-skill verifies it first:
 - Find it: `keryx skills route <target>`.
 - Check freshness: `keryx skills verify <module>/<skill>` (or
   `skill-verify-skill`). It classifies the skill `fresh | stale | needs-review |
-  blocked` against current code, graph, wiki, health, memory, and tests.
+  blocked` from its required files, metadata, manifest registration, target
+  path, and evidence artifacts (graph, ctx, wiki, health, memory). It does not
+  read the skill's claims or compare them with the code.
 - If not `fresh`: do NOT follow it blindly — verify each claim against the code
   and record the drift so it feeds the learn step below.
 
@@ -43,10 +45,12 @@ Flow:
    (version bump + `skill-changelog.md` with provenance, respects manual
    sections, file-locked).
 
-`learn` is bounded, mechanical synthesis. **Dispatch it as a subagent; if a
-cheaper / non-flagship model is available in this environment, use it
-(see `model-selection.mdc`), otherwise use the session model.** The flagship's
-only job here is to review the proposal before apply.
+`learn` is bounded, mechanical synthesis. **Dispatch it as a subagent at
+`model_tier: light`, resolved via `keryx review tier --findings 1 --diff-lines 0`
+per `model-selection.mdc` — do not pick a model by hand, and do not substitute
+a different `review tier` invocation (e.g. `--scope narrow`, which resolves
+heavier than `light`).** The flagship's only job here is to review the
+proposal before apply.
 
 ## Never
 

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

@@ -18,16 +18,49 @@ Before creating or editing a skill, ask and confirm:
 3. Agent profile scope (`Cursor`, `Codex`, `Zed`, `OpenCode`, or all)
 
 ## Source of Truth
-`.metaproject/skills/gdskills/<skill-name>/`
+- Shipped skill: `src/gdskills/bundled/skills/<category>/<skill-name>/` in the
+  keryx repository. `.metaproject/skills/gdskills/<category>/<skill-name>/`
+  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>/`.
 
 ## 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)
 
@@ -65,27 +98,86 @@ 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
-- `SKILL.cursor.md` (or `SKILL.md`) → `~/.cursor/skills/<skill-name>/SKILL.md`
-- `SKILL.codex.md` (or `SKILL.md`) → `${CODEX_HOME:-~/.codex}/skills/<skill-name>/SKILL.md`
-- `SKILL.antigravity.md` (or `SKILL.md`) → `~/.antigravity/skills/<skill-name>/SKILL.md`
-- `SKILL.zed.md` (or `SKILL.md`) → `~/.config/zed/skills/<skill-name>/SKILL.md`
-- `SKILL.opencode.md` (or `SKILL.md`) → `~/.config/opencode/skills/<skill-name>/SKILL.md`
+Global sync only ever reaches a **project-local skill**
+(`.metaproject/project-skills/<skill-name>/`) that has first been exported for
+that runtime with `keryx skills export <skill-name> --runtime <runtime>`
+(this writes `.metaproject/runtime/skills/<runtime>/<module>-<skill-name>/`).
+A **shipped** skill (`src/gdskills/bundled/skills/<category>/<skill-name>/`)
+cannot be exported — `keryx skills export` resolves project skills only and
+reports `Project skill not found for: <name>` for a shipped one — so it has no
+global-sync route today. A shipped skill reaches a runtime only through the
+project-local installed mirror (`.metaproject/skills/gdskills/<category>/<skill-name>/`,
+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` 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
+effect of `keryx update`/`keryx init`. `claude` and `plugin` have no global
+destination; use `keryx skills sync --runtime <runtime> --target <dir>` for
+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.
-3. Validate skills before sync.
-4. Sync both global destinations after source update.
-5. Ensure `agents/openai.yaml` exists where required by the target agent UI.
-6. For create/update/sync workflows, produce a machine-readable final result for orchestrators.
+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`).
+6. Ensure `agents/openai.yaml` exists where required by the target agent UI.
+7. For create/update/sync workflows, produce a machine-readable final result for orchestrators.
 
 ## Machine-Readable Contract
-Use canonical schema:
-- `.metaproject/rules/schemas/skill-workflow-result.schema.json`
-
-Contract requirements:
+No canonical schema file exists for this result yet. Contract requirements:
 - One top-level JSON object only.
 - Stable required keys.
 - Closed objects (`additionalProperties: false`).
@@ -105,12 +197,27 @@ Run before syncing skills:
 keryx skills verify --all
 ```
 
-Then run sync:
+Then regenerate the project-local installed mirror
+(`.metaproject/skills/gdskills/<category>/<skill-name>/`) from the bundled
+source:
 
 ```bash
 keryx update
 ```
 
+`keryx update` never writes outside the project, and it is the only route a
+**shipped** skill has to reach a runtime — a shipped skill cannot be exported
+and has no global-sync destination.
+
+To push a **project-local** skill (`.metaproject/project-skills/<skill-name>/`)
+to a harness's own global directory (opt-in, outside the project), export it
+for that runtime first, then sync:
+
+```bash
+keryx skills export <skill-name> --runtime <runtime>
+keryx skills sync --runtime <runtime> --global
+```
+
 If validation fails, do not sync.
 
 ## Naming
@@ -120,5 +227,31 @@ 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
-Changes under `.metaproject/skills/gdskills/*` should be synced to tool directories using `keryx update`.
+Edit skills under `src/gdskills/bundled/skills/<category>/<skill-name>/`
+(shipped) or `.metaproject/project-skills/<skill-name>/` (project-local).
+`keryx init`/`keryx update` regenerate the installed mirror at
+`.metaproject/skills/gdskills/<category>/<skill-name>/` — this stays inside
+the project, and is the only way a shipped skill reaches a runtime. For a
+project-local skill only, run `keryx skills export <skill-name> --runtime
+<runtime>` then `keryx skills sync --runtime <runtime> --global` separately to
+push it to a harness's own global directory outside the project; shipped
+skills cannot be exported (`keryx skills export` resolves project skills
+only) and have no global-sync route.

package/src/gdskills/bundled/rules/core/storybook-guidelines.mdc

@@ -4,6 +4,7 @@ alwaysApply: false
 globs:
   - ".storybook/**"
   - "**/*.stories.tsx"
+stack_requires: "react"
 ---
 
 # Storybook Guidelines

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.