@mrciphersmith/keryx 0.2.70 → 0.2.72

package/docs/README.md

@@ -0,0 +1,54 @@
+# Documentation
+
+This directory separates documentation by purpose so current behavior, product
+intent, implementation plans, and release evidence do not get mixed together.
+
+## Current behavior
+
+- [Developer documentation](docs/README.md) — entry point for setup,
+  architecture, modules, CLI behavior, and workspace lifecycle.
+- [Complete setup and agent workflows](docs/complete-setup-and-agent-workflows.md)
+  — global installation, project configuration, command reference, scripts, and
+  copy-ready agent prompts.
+- [Agent installation playbook](docs/agent-installation-playbook.md) — autonomous
+  Gherkin scenarios for complete setup, validation, repair, and handoff.
+- [Documentation index](docs/index.md) — compact navigation for the generated
+  current-behavior reference.
+
+## Product intent
+
+- [Requirements roadmap](requirements/roadmap.md) — requirements packages and
+  their verified implementation state.
+- [Managed Review Feedback Loop](requirements/managed-review-feedback-loop/README.md)
+  — requirements and contracts for managed review packages.
+- [Keryx Memory Reliability](requirements/keryx-memory-reliability/README.md)
+  — corrective requirements and implementation tracking for side-effect-free
+  recall, accepted-only agent influence, durable lifecycle, and generated data.
+
+## Plans and reports
+
+- [Shared Agent Context Improvements Program](requirements/shared-agent-context-improvements-program/README.md)
+  — dependency-ordered implementation waves for twelve SAC improvement
+  packages, with copy-ready phase prompts, evidence gates, rollback, and a
+  live progress/statistics dashboard.
+- [Keryx Improvements 1 — SAC, memory, and orchestration analysis](analysis/keryx-improvements-1/2026-08-14/report/en/report.md)
+  — integrated audit of Shared Agent Context and its Context Operations, Flow,
+  Harness/session, MCP, Security, knowledge-owner, worktree, and policy seams;
+  includes twelve independently deliverable future requirement packages.
+- [Implementation plans](plans/) — bounded plans that may become cleanup
+  candidates after their acceptance criteria are implemented and verified.
+- [Release readiness — 2026-07-10](report/release-readiness-2026-07-10/release-readiness.md)
+  — verification results, release blockers, and the prioritized cleanup plan.
+- [Implementation spec](report/release-readiness-2026-07-10/implementation-spec.md)
+  — approved scope and acceptance criteria for this documentation pass.
+
+## Documentation policy
+
+- Repository documentation is English-only.
+- `docs/docs/` describes current behavior and must be verified against source or
+  live CLI help.
+- `docs/requirements/` describes intended behavior and must label implementation
+  status explicitly.
+- Generated `.metaproject` artifacts are refreshed through the project CLI; raw
+  and reproducible outputs remain ignored according to the managed `.gitignore`
+  policy.

package/docs/requirements/shared-agent-context/README.md

@@ -0,0 +1,104 @@
+# Keryx Shared Agent Context
+Version: 1.5.0
+
+## Назначение
+
+Этот пакет описывает **текущий** local-first слой совместного контекста Keryx
+(`src/sac/`, CLI `keryx workspace`, MCP `sac.*`, harness `workspace_*`).
+Он даёт человеку и агенту воспроизводимый вход в работу от workspace, компонента
+или flow: небольшой проверяемый обзор, адресное чтение деталей и безопасное
+предложение нового знания по завершении работы.
+
+## Статус
+
+`implemented` (механизмы 0–5), плюс фаза 6, разбитая на две части: **6a** —
+runtime-guard opt-in (`resolvePolicySelection`), реализована и проверена
+(AC1–AC6, вся SAC-сюита 88/88 зелёная); **6b** — операторский процесс готовности
+для реальных данных, частично (read-only `keryx workspace policy-readiness` и
+playbook; runtime re-ingestion сырых receipts/outcomes остаётся). Фазы 0–5 и 6a
+влиты в `main` и выпущены в `v0.2.32`; код lifecycle/CLI/MCP/harness с тех пор
+расширен на `main` (в т.ч. `v0.2.35`). Точный статус и evidence приведены в
+[Implementation plan](implementation-plan.md).
+
+**Документационная правда (1.5.0):** более ранние versioned-заголовки этого
+пакета помечали CLI/MCP/schema-enforcement как `future/planned` и прямо писали,
+что runtime «не реализует SAC contracts». Это устарело относительно `src/sac/`
+(~4.3k строк production + тесты: propose/review/accept, guarded owner-writers
+wiki/memory/skill, receipt-integrity, access-receipt ledger; плюс
+`src/commands/workspace.ts`, MCP `sac.*`, harness `workspace_*`). Норматив
+этого пакета теперь —
+как устроено **сейчас**. Спутниковые пакеты RP-01…RP-12 остаются future /
+spec-ready и **не** отменяют этот runtime. Валидатор, который сверяется с
+заголовками `future` в старых ревизиях или в RP-пакетах, получит ложный drift.
+
+Важно: Phase 5 (policy experiment) сейчас подтверждает корректность механизма на
+synthetic offline evidence и по умолчанию не включает production эффектов.
+
+## Модель FWK
+
+- **Facts** — evidence-linked, task-local и freshness-bound утверждения о
+  текущей работе. Fact не становится источником долгосрочного знания.
+- **Work** — read-only проекция существующего Flow: выполненное, следующее,
+  блокировки и verification evidence. SAC никогда не создаёт второй tracker.
+- **Know-how** — reviewed и reusable knowledge из memory, wiki и skills.
+  Необработанные транскрипты и скрытые рассуждения не являются Know-how.
+
+## Документы
+
+- [PRD](prd.md) — проблема, пользователи, требования, риски и результаты.
+- [Specification](specification.md) — границы, функциональная surface,
+  интеграции и acceptance criteria.
+- [Agent protocol](agent-protocol.md) — обязательное поведение агента при
+  read, wrap-up и proposal lifecycle.
+- [Artifact lifecycle](artifact-lifecycle.md) — источники истины, freshness,
+  retention, supersession и deletion policy.
+- [Metrics and validation](metrics-and-validation.md) — baseline, evals,
+  rollout/rollback и измеримые gates.
+- [Implementation plan](implementation-plan.md) — delivery status фаз 0–6b
+  и исторические exit criteria.
+- [Phase execution prompts](phase-execution-prompts.md) — утверждённые промты
+  для запуска и delivery-protocol каждой implementation phase.
+- [Phase 4 usability report](phase-4-usability-report.md) — contract-only
+  walkthrough evidence.
+- [Phase 5 policy experiment report](phase-5-policy-experiment-report.md) —
+  synthetic offline experiment evidence.
+- [Phase 6 readiness](phase-6-real-opt-in-readiness.md) — 6a/6b split and
+  remaining real-data work.
+- [Phase 6b operator playbook](phase-6b-operator-playbook.md) — operator
+  readiness process.
+- [Design rationale](design-rationale.md) — решения и ограничения модели FWK.
+- [Schemas](schemas/README.md) — JSON Schema, semantic-validation boundary и
+  полный positive/negative/replay fixture corpus.
+
+## Scope
+
+- Локальный workspace registry со ссылками на компоненты, repositories, flows,
+  evidence и approved knowledge; исходные артефакты не копируются.
+- Bounded FWK overview и progressive retrieval через **существующие** CLI
+  (`keryx workspace overview|read`), MCP (`sac.overview`/`sac.read`, только
+  local stdio) и harness-tools (`workspace_overview`/`workspace_read`);
+  hash-chained access-receipt ledger.
+- Evidence-linked session wrap-up, proposal queue, human review и guarded
+  promotion в существующие wiki/memory paths.
+- Freshness, least disclosure, trusted ActorContext, local roles, redaction и
+  audit trail; proposal может быть принят только после проверяемого,
+  append-only review transition.
+
+## Non-goals
+
+- Новый task manager, дубликат Flow или новый primary store для wiki/memory.
+- Хранение raw transcripts, secrets, PII, hidden reasoning или unrestricted
+  environment snapshots как knowledge.
+- Обязательная облачная база, multi-tenant service, SSO или внешний catalog.
+- UI/IDE/terminal shell как prerequisite первой поставки.
+- Обучаемая или self-modifying access policy до воспроизводимых offline evals.
+
+## Связанные модули
+
+- [Keryx Context Operations](../keryx-context-operations/2026-07-12/README.md)
+  — владелец context assembly, retrieval trace и feedback lifecycle.
+- [Keryx Project Agent Harness](../keryx-project-agent-harness/README.md) —
+  владелец сессий, approvals, worktrees и execution runtime.
+- `src/flow`, `src/memory`, `src/wiki`, `src/gdgraph`, `src/mcp`,
+  `src/security`, `src/ctx`, `src/harness` — существующие интеграционные
+  границы; изменения в них требуют отдельных implementation flows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.70",
+  "version": "0.2.72",
   "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": {
@@ -41,6 +41,7 @@
     "test": "bun test",
     "check": "tsc --noEmit && bun test",
     "check:doc-links": "bun scripts/check-doc-links.ts",
+    "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
     "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts"
   },
   "files": [
@@ -72,4 +73,4 @@
     "protobufjs",
     "sharp"
   ]
-}
+}

package/src/gdskills/bundled/rules/core/code-review-learned-profile.mdc

@@ -0,0 +1,81 @@
+---
+description: "Learned review profile: a review checklist this project built from its own pull-request comments, not a style shipped with the tool."
+alwaysApply: false
+---
+
+# Learned Review Profile
+
+## What This Rule Is
+
+This is a **dynamic rule**. It carries no conventions of its own, and it ships
+empty of them on purpose.
+
+Every other review rule in `rules/core/` states what to flag. This one states
+**where the things to flag come from**: the pull-request comments left on this
+project, by the people this project named, applied to this project's own code.
+Nothing here describes a reviewer, a team, or a stack — because a rule that
+described one would be wrong for the next project that installed it.
+
+The checklist a reader wants lives in the project, in a project skill under
+`.metaproject/project-skills/<module>/<skill>/SKILL.md`. That file is written by
+`keryx review learn` proposing and `keryx skills learn apply` applying, and it
+never travels back into the tool.
+
+## Where The Content Comes From
+
+```
+keryx review comments collect   →  the durable record: who commented, and what they said
+keryx review learn              →  keeps the configured authors, writes a proposal
+keryx skills learn apply        →  writes the lesson into the project skill, bumps its version
+```
+
+`.metaproject/review-learning.config.json` names the three things the join needs:
+the local skill to teach, the repository to read, and the comment authors whose
+text counts. A project without that file does not learn — that is a supported
+state, not an error.
+
+`keryx review learn` reads the record `collect` already wrote; it does not talk
+to GitHub. An author the config does not name contributes nothing: their text
+reaches no proposal and no `SKILL.md`.
+
+## Two Boundaries That Are Enforced In Code, Not Advised Here
+
+- **Proposing never writes.** `keryx review learn` writes a proposal under
+  `.metaproject/data/gdskills/proposals/` and changes no skill. `keryx skills
+  learn apply` is the only writer, it refuses a proposal it has already applied,
+  and it records what it did in `skill-changelog.md`.
+- **Learned content cannot leave the project.** `applyLearningProposal` resolves
+  the target and refuses any path outside `.metaproject/project-skills/`. A
+  project that misconfigures its skill path cannot write into the shipped
+  templates under `src/gdskills/bundled/`; the apply fails instead.
+
+Both are assertions about code that exists. Neither is a request to be careful.
+
+## When To Apply
+
+Apply when the project has a learned review skill and the reader wants that
+project's accumulated review conventions rather than a generic pass. If the
+project has no learned skill yet, prefer `review-orchestrator` and its
+domain reviewers — an empty learned profile has nothing to say and should say
+nothing.
+
+## Response Format
+
+1. Verdict in one line — the canonical verdict vocabulary (same set as
+   `core/code-review-ai-assistant.mdc`):
+   - `APPROVE` — no blocking issues; changes accepted as-is
+   - `APPROVE WITH SUGGESTIONS` — accepted but improvements noted for follow-up
+   - `REQUEST CHANGES` — has issues that must be fixed before merge
+   - `COMMENT` — informational findings only; no blocking action required
+2. Top 1-3 blocking findings, each traceable to a line in the learned skill.
+3. Concrete replacement/fix path.
+
+## Guardrails
+
+- Cite the learned lesson a finding rests on. A finding with no line behind it in
+  the project skill is a generic review finding and belongs to the reviewer that
+  owns it.
+- Do not restate a lesson as a rule about people. The record says a comment was
+  left; it does not license a claim about who is usually right.
+- No personal attacks. No empty nitpicks. Keep recommendations lint-safe and
+  scoped.

package/src/gdskills/bundled/rules/core/jobs-documentation.mdc

@@ -112,7 +112,7 @@ The README is the entry point for both humans and AI agents. It MUST contain:
 1. [x] Analyze issue (issue-analyzer)
 2. [ ] Prepare feature branch
 3. [ ] Implement tasks (task-implementer)
-4. [ ] Review (code-ai-review, code-boss-review, code-style-review)
+4. [ ] Review (code-ai-review, code-learned-review, code-style-review)
 5. [ ] Fix review findings
 6. [ ] Final checks
 7. [ ] Generate report

package/src/gdskills/bundled/rules/core/model-selection.mdc

@@ -1,53 +1,206 @@
 ---
-description: "Model selection workflow for sub-agents. Detects available models and allows user to choose."
+description: "Adaptive model selection for sub-agent dispatches. Skills declare a tier; the tier is resolved against the models the active provider actually reports at runtime, without asking."
 alwaysApply: false
 ---
 
 # Model Selection for Sub-Agents
 
 ## Purpose
-When launching a sub-agent or skill, detect available models in the current environment and allow the user to choose.
 
-## Trigger
-When you need to launch a sub-agent/skill and want to use a different model than the current one.
+Match the model to the work. A reviewer scanning a twelve-line diff and a
+regression reviewer reasoning across a forty-file blast radius should not run on
+the same model: the cheap work pays flagship prices, and the hard work gets no
+more capability than the trivial.
 
-## Available Models Detection
+## Tiers, not model names
 
-Run to detect available models:
+A skill declares a **tier**. It never declares a model.
+
+A model name in a skill is wrong the day the provider changes and unusable for
+anyone on a different provider. There are three tiers:
+
+| Tier | For |
+|---|---|
+| `light` | mechanical, verifiable work — pre-filter, `class_scope` existence checks, comment collection, formatting a reply |
+| `standard` | ordinary reviewing and implementation — the default |
+| `deep` | genuinely hard reasoning — regression review across the blast radius, a strategy change after a failed loop, synthesis across many findings |
+
+Declared in SKILL.md frontmatter:
+
+```yaml
+---
+name: review-architecture
+model_tier: deep
+---
+```
+
+An undeclared skill runs at `standard`. A skill that writes a model name into
+`model_tier` fails the guard in `src/gdskills/model-tier.test.ts`.
+
+## Resolving a tier: discover, rank, fall back
+
+There is **no table of models** anywhere in the resolution, and there must not
+be. A fixed list of model ids is stale the day a provider ships anything, and it
+is wrong for every operator whose environment differs from the one it was written
+in. The candidate set is discovered at runtime.
+
+`src/commands/select.ts` already detects providers and every `DetectedProvider`
+carries `models: string[]`. That list — for the **session's own provider**, so a
+child never resolves onto a provider the parent holds no grant for — is the whole
+candidate set. `src/gdskills/model-tier.ts` then:
+
+1. **discovers** the candidates (passed in, never looked up: the module reads no
+   network, no filesystem, no environment);
+2. **ranks** them by size markers in their names — `MODEL_RANK_HINTS`;
+3. **places the tiers relative to the session's own model**:
+
+| Tier | Resolves to |
+|---|---|
+| `standard` | the session's model, always |
+| `deep` | the highest-ranked discovered model **strictly above** the session's, else the session's |
+| `light` | the lowest-ranked discovered model **strictly below** the session's, else the session's |
+
+Anchoring on the session model is what makes "never a downgrade" checkable
+rather than hoped for: a tier can only move away from the session model in the
+direction its own name points, and a candidate at the session's own rank is a
+lateral move and never taken.
+
+## What the hints are, and what they are not
+
+Capability cannot be derived from a bare string — `haiku` is smaller than `opus`
+and nothing about the two strings says so. `MODEL_RANK_HINTS` is that irreducible
+residue, and it is kept in the smallest shape that works:
+
+- it names **size words** (`mini`, `lite`, `flash`, `haiku`, `pro`, `opus`,
+  `max`, `ultra`, …), never models, so it claims nothing about what exists and
+  cannot go stale;
+- it is applied to whatever detection reported, so an unfamiliar vendor is still
+  ranked if its names use those words;
+- a model matching **no** hint is *unranked*, which is not the same as ranked
+  zero — it is simply not placed;
+- it is one array, overridable per call.
+
+A model whose name is a codename carrying no size is unrankable by design. That
+is the honest outcome, not a gap to be patched with folklore.
+
+## Falling back
+
+Ranking is **refused**, and every tier keeps the session's provider and model,
+when:
+
+- nothing was discovered, or the session's provider is absent from the catalogue
+  (an external CLI runtime, or detection that has not run);
+- the provider reported no models;
+- the hints cannot place the **session's own** model — with no anchor, no
+  candidate can be called larger or smaller.
+
+A refusal **never** fails a dispatch and **never** causes a silent downgrade.
+Degrading capability because discovery failed is the worst of the three outcomes.
+
+Do not "fix" a fallback by adding model ids to the code. Add a size word to the
+hints if one genuinely applies, or leave it: running on the session's model is a
+correct answer.
+
+## Where this actually runs
+
+Two places, and they are not the same shape:
+
+- **`spawn_subagent`** (`src/harness/tool/builtin/spawn-subagent-tool.ts`) takes an
+  optional `model_tier` input and does the rest in code: it builds the tier map
+  with `buildTierMap` from its host's detection result, hands it to
+  `resolveChildModel`, and records the outcome on the dispatch's run trace.
+  Omitting `model_tier` inherits the parent's model, exactly as before the field
+  existed.
+- **An orchestrator authoring a dispatch document** *runs a command*:
+  `keryx review tier`. It takes the signals below as flags and prints the `model`
+  block ready to paste — the tier, the ordered rule ids that produced it, the
+  resolved provider/model, `tier_resolution` and `model_discovery`. `--json`
+  prints the block alone.
+
+That second bullet used to say the orchestrator "calls `decideDispatchModel`".
+An orchestrator is an agent following prose and **cannot call a TypeScript
+function**, so what actually happened was a model reading a table of signals and
+doing the arithmetic in its head — the exact mechanical work this programme moves
+out of skills and into the code that consumes them. `keryx review tier` is that
+code's entry point; `decideDispatchModel` is what it calls.
+
+Nothing reads a recorded resolution back and checks it. These fields explain a
+finished run; they do not gate one.
+
+## Choosing the tier
+
+The tier is **computed, not judged**. Run:
 
 ```bash
-.metaproject/scripts/detect-models.sh
+keryx review tier --scope blast-radius --findings 12 --diff-lines 340 \
+                  --verifier execution --fix-attempt 2 --security \
+                  --forced-strategy-change --json
 ```
 
-## Current Environment Models
+Every flag is a signal the orchestrator already holds before it dispatches: the
+round's scope, its own attempt counter, the diff it computed, the findings it is
+holding, the verification method it is about to ask for. None of them is a
+model's self-report — no model is ever asked to rate its own difficulty.
+
+The rules `assignTier` applies, in the order it applies them:
+
+| Signal | Flag | Effect |
+|---|---|---|
+| scope is `blast-radius` | `--scope blast-radius` | at least `deep` |
+| fix attempt >= 2 on the same finding | `--fix-attempt <n>` | raise one tier |
+| forced strategy change after the loop cap | `--forced-strategy-change` | `deep` |
+| finding count <= 3 **and** diff <= 50 lines | `--findings <n> --diff-lines <n>` | allow `light` |
+| verification method is `execution` or `site-check` | `--verifier <method>` | `light` — the evidence comes from running something, not from reasoning |
+| any security finding in scope | `--security` | never below `standard` |
+
+Floors are applied after downgrades, so "at least `deep`" means at least: a
+blast-radius round over a twelve-line diff is still a blast-radius round.
+
+The session's provider/model come from the selection `keryx shell` persisted, and
+the candidate set from live provider detection. A caller that already holds
+either passes `--session-provider`/`--session-model` and `--catalog` instead of
+paying for the lookup. **There is no `--tier` flag, and there will not be**:
+accepting a hand-written tier would put the arithmetic straight back in the
+caller's head.
 
-### Codex
-- `gpt-5.2-codex` - Frontier agentic coding model (recommended)
-- `gpt-5.3-codex` - Latest frontier agentic coding model
-- `gpt-5.1-codex-max` - Codex-optimized flagship for deep reasoning
-- `gpt-5.1-codex-mini` - Cheaper, faster, less capable
-- `gpt-5.2` - Latest frontier model
+When nothing can be worked out — no persisted session, an unrankable catalogue,
+an unrankable session model — the block says `inherit: true` and the dispatch
+runs on the **caller's own model**. Exit status is still 0: a fallback is an
+answer, not a failure.
 
-### Cursor
-Uses OpenAI models (GPT-4, GPT-4o, etc.)
+## Recording the decision
 
-### Antigravity
-Check configuration in `~/.antigravity/`
+The dispatch carries the tier, the ordered rule ids that produced it, which of
+the three outcomes occurred, and what was on the table when it did —
+`model.tier`, `model.tier_reasons`, `model.tier_resolution` and
+`model.model_discovery` in
+`.metaproject/core/gdskills/contracts/subagent-dispatch.schema.json`.
 
-### OpenCode
-Check configuration in `~/.config/opencode/`
+`tier_resolution` distinguishes three facts that must not be flattened:
 
-### Zed
-Uses AI models configured in Zed settings
+| Value | Means |
+|---|---|
+| `discovered` | a discovered model was assigned to this tier |
+| `session-ranked` | ranking worked and placed the tier at the session's model |
+| `session-fallback` | ranking was refused; the session's model is kept |
 
-## Workflow
+"Fell back to the session model" and "assigned the session model because it
+ranked there" are different facts. A run that cannot be explained afterwards is
+what these fields exist to prevent. Record them on every dispatch that resolves
+a tier — `keryx review tier` prints all four together as one pasteable block, so
+recording them is one copy rather than four decisions.
 
-1. **Detect available models** - Run `detect-models.sh` or check known configurations
-2. **Present options** - Show user available models with descriptions
-3. **Get confirmation** - Ask user which model to use
-4. **Launch sub-agent** - Use selected model for the sub-agent
+## Mandatory behavior
 
-## Mandatory Behavior
-- Always ask user before changing model for sub-agents
-- Show model descriptions to help user decide
-- Default to current model unless user explicitly chooses otherwise
+- Declare a tier in the skill; resolve the model at dispatch time.
+- **Run `keryx review tier` — do not work the tier out by hand.** Assigning it
+  from the table above by reading is the mechanical step this rule exists to
+  remove.
+- **Do not ask the operator which model to use per dispatch.** Asking every time
+  is what made adaptive selection impossible.
+- Never write a concrete model name into a skill, a rule, a dispatch template, or
+  the resolution code.
+- Take the candidate set from runtime detection. Never from a literal list of
+  what exists.
+- When the candidates cannot be ranked, keep the session model. Never substitute
+  a cheaper one.

package/src/gdskills/bundled/rules/core/review-strict-profile.mdc

@@ -1,15 +1,19 @@
 ---
-description: "boss-style review profile: direct, strict, architecture-first feedback with concrete fixes."
+description: "Strict review profile: direct, architecture-first feedback with concrete fixes."
 alwaysApply: false
 ---
 
-# boss Review Profile
+# Strict Review Profile
 
 ## Purpose
-Replicate the boss review style for requested reviews.
+Apply a strict, architecture-first pass: name the defect, name where the logic
+belongs, and give the replacement.
 
 ## When To Apply
-Apply when user explicitly asks for review in boss style.
+Apply when the caller explicitly asks for a strict review. For a checklist this
+project learned from its own pull-request comments, use
+`core/code-review-learned-profile.mdc` instead — that one carries no conventions
+of its own and reads them from the project.
 
 ## Style Profile
 - Direct and concise.

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

@@ -29,6 +29,42 @@ Before creating or editing a skill, ask and confirm:
 
 `SKILL.md` is always required. Platform variants are optional — if absent, `keryx update` installs `SKILL.md` as fallback.
 
+## Frontmatter Fields (Agent Skills spec alignment)
+
+`SKILL.md` frontmatter follows the published Agent Skills specification
+(agentskills.io — the format Zed adopted when it dropped its own Rules
+Library), with two deliberate additions. Flow 203 removed two accidental
+divergences that had crept in; keep both fixes intact when authoring or
+editing a skill:
+
+- **`version` lives in `metadata.version` only.** The spec has no top-level
+  `version` field — its own example nests it under `metadata`. Do not
+  reintroduce a top-level `version:` key; nothing in this codebase reads one.
+- **`compatibility` carries the spec's meaning, not ours.** The spec defines
+  `compatibility` as environment requirements written in prose (e.g. "Requires
+  git, docker, jq, and access to the internet"). Our machine-readable CSV of
+  supported harnesses (`cursor,codex,zed,opencode,claude`) lives instead at
+  `metadata.compatible_harnesses`. Do not put a harness CSV back into
+  `compatibility` — if a skill genuinely needs to declare environment
+  requirements, write them there as prose, per the spec.
+
+Two divergences are deliberate and stay — a later pass must not "fix" them
+back toward the spec:
+
+- **`triggers`** — a list of trigger phrases. Not in the spec, and absent from
+  every skill collection surveyed while building this convention; the spec's
+  only discovery mechanism is semantic matching on `description`. `triggers`
+  gives the router a cheap, deterministic first-pass match before falling back
+  to semantic matching. It is additive and costs nothing as long as
+  `description` stays self-sufficient on its own — never let `triggers` carry
+  meaning `description` lacks.
+- **Per-skill `input-contract.schema.json` / `output-contract.schema.json`**
+  (sibling files, not frontmatter keys) — genuinely unique to this codebase.
+  Nothing in the spec or any surveyed collection defines one, because the spec
+  assumes a single agent reading a single skill file. This project dispatches
+  typed payloads to subagent workers instead, which the spec does not attempt
+  to address.
+
 ## 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`

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.codex.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: code-verifier
+model_tier: light
 description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report."
 triggers:
   - "Run verification"
@@ -13,8 +14,8 @@ metadata:
   version: "1.0.0"
   category: "verification"
   agent_worthy: true
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.opencode.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.zed.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier