Upgrade CMK standard ceremony and skill wording quality

.gitignore

@@ -60,3 +60,4 @@ docker-compose.override.yml
 **/evals-workspace/**/with_skill/
 **/evals-workspace/**/without_skill/
 **/evals-workspace/**/benchmark.json
+.skills/

docs/ai/skills/conventions.md

@@ -7,15 +7,15 @@ Every skill under [`skills/`](../../../skills/) follows the same packaging shape
 Frontmatter declares three fields the host (Claude Code or OpenCode) reads to discover and trigger the skill, plus one optional fourth field for user-invoked skills:
 
 - `name` — `cmk:<short-name>`, used as the slash command and skill ID.
-- `description` — natural-language trigger phrases plus what the skill does. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line.
-- `version` — `0.4.0` on `cmk:design` and `cmk:delivery-pipeline` (phase 3b); `0.3.0` on `cmk:adr`, `cmk:docs`, and `cmk:requirements` (guidance revision) and `cmk:local-stack` (Modes revision); `0.2.1` on `cmk:cicd` (speedup-misattribution trap); `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`.
+- `description` — opens in the second person (`Use when…` / `Use whenever…`) with trigger phrases plus an **outcome noun** (the deliverable), not a workflow step list. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line.
+- `version` — `0.6.x` on `cmk:design`; `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:requirements` (Standard elicitation: close package, scope band, guards); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.1` on `cmk:cicd` (speedup-misattribution trap); `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`.
 - `disable-model-invocation: true` — optional, fourth field only. Present on `cmk:interpret`. The closer is still `---`.
 
 No skill file references outside its own package by relative path — the rule binds a package's own references, not content it emits into a target repo; a skill that needs a target-repo artifact names it repo-root-relative, and a skill that needs another skill cites it by `cmk:` name — see `cmk:agent-vendors`.
 
 Docs-family skills (`adr`, `codebase-docs`, `design`, `docs`, `glossary`, `learn`, `requirements`, `rule`) mostly expose two phases — `Workflow: Create` and `Workflow: Iterate` — and offload long-form guidance, templates, and placement rules into `references/*.md` so the SKILL body stays scannable (`cmk:glossary` is compact enough to carry its rules inline and ships no `references/` folder). The `references/` files are loaded on demand via "Read `references/<file>.md`" lines. `cmk:requirements` and `cmk:design` pair a conventions file (placement) with a guidance file (a shaping directive rather than a fixed form) — the former fixed-form templates were retired in favor of the guidance files plus the baseline scaffold templates under `docs/templates/`.
 
-Three docs-family skills break the create/iterate pattern: `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses `Bootstrap workflow` / `Update workflow`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds a third phase, `Workflow: Promote`.
+Three docs-family skills break the create/iterate pattern: `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses Bootstrap/Update entry points with workflows behind `references/`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds Audit/Gate modes (bodies in `references/`) and Promote.
 
 Setup-family skills (`agent-instructions`, `agent-vendors`, `cicd`, `infra`, `local-stack`, `mcp-config`, `project-layout`, `repo-setup`, `rust`, `sync`, `test-resources`, `testcontainers`, `toolchain`) don't follow create/iterate at all — every one exposes a `## Modes` section (Init/Update/Verify, or the skill's equivalents such as sync's baseline/sync/contribute) for standing up or auditing its facet, and every one ends in a report-only `## Verify` section a caller (human or `cmk:repo-setup`) can run to assess whether a target repo satisfies the facet. Verify never mutates.
 
@@ -27,7 +27,7 @@ Knowledge-family skills (`sui-sdk`, `sui-devstack`) are domain reference packs s
 
 ## Where
 - Frontmatter, on every skill: open any `skills/<name>/SKILL.md` and read lines 1–5 (1–6 when `disable-model-invocation: true` is present).
-- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/codebase-docs/`, `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
+- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`.
 - Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`. No delivery-family or knowledge-family skill ships one.
 - The shared docs-family workflow shape: grep for `^## Workflow: Create` and `^## Workflow: Iterate` across `skills/*/SKILL.md`.
 - The shared setup-family Verify contract: grep for the exact heading `^## Verify$` across `skills/*/SKILL.md` — every hit is a setup-family skill. `skills/delivery-review/SKILL.md` has a similarly named but distinct `## Verify before acting` section (adversarial verification of review findings, not a report-only facet check) — match on the exact heading, not the prefix, to tell them apart.

docs/ai/skills/requirements.md

@@ -1,11 +1,13 @@
 # cmk:requirements
 
 ## What
-Skill that drafts and iterates requirements documents — the upstream "what and why" before any technical design, speaking technically where the product itself is technical. Synthesizes from conversations, research notes, Notion/Google Doc links, and `docs/knowledge/` entries; interviews first (one question at a time) when the input is an idea rather than settled requirements.
+Skill that drafts and iterates requirements documents — the upstream "what and why" before any technical design, speaking technically where the product itself is technical. Synthesizes from conversations, research notes, Notion/Google Doc links, and `docs/knowledge/` entries. When input is thin or solution-shaped, runs elicitation (scope band, problem lock, cards, **close package + explicit yes**) before writing `docs/requirements/`; Iterate adds `SHALL CONTINUE TO` guards when existing behavior must keep working.
 
 ## Where
-- Skill body: `skills/requirements/SKILL.md` — sections `Input`, `Elicitation`, `Workflow: Create`, `Workflow: Iterate`, `Output`, `Links`.
+- Skill body: `skills/requirements/SKILL.md` — sections `Input`, `Elicitation` (HARD-GATE), `Workflow: Create`, `Workflow: Iterate`, `Output`, `Red Flags`, `Rationalizations`, `Links`.
+- Elicitation protocol: `skills/requirements/references/elicitation-protocol.md` — scope band, problem lock, cards, close package provenance.
 - Placement rules: `skills/requirements/references/requirements-conventions.md`.
-- Shaping directive (not a fixed form): `skills/requirements/references/requirements-guidance.md` — normative vocabulary, locked-decision registers, progressive disclosure, coherence.
+- Shaping directive (not a fixed form): `skills/requirements/references/requirements-guidance.md` — criteria contract, **guarding existing behavior**, locked-decision registers, progressive disclosure, coherence.
+- Test evidence: `skills/requirements/TESTS.md`; `skills/requirements/eval.json`.
 - Output template (baseline scaffold shape): `docs/templates/requirements.md`.
 - Default placement: `docs/requirements/<topic>.md` — see `docs/requirements/README.md`. Shared vocabulary lives in the glossary (`cmk:glossary`).

docs/guides/README.md

@@ -13,6 +13,12 @@ thing in this repository.
   [`../design/`](../design/); how to operate it belongs in
   [`../runbooks/`](../runbooks/).
 
+## Index
+
+| Guide | When |
+|---|---|
+| [`on-ramps.md`](./on-ramps.md) | Unsure which `cmk:*` skill starts the situation |
+
 ## When to read
 
 When you know what you need to do and want the established way to do it.

docs/guides/on-ramps.md

@@ -0,0 +1,31 @@
+# On-ramps
+
+**One home** for which `cmk:*` skill starts a situation. Root agent instructions
+point here; they do not restate this table.
+
+| Situation | Start here |
+|---|---|
+| Brand-new / adopt / verify repo facets | `cmk:repo-setup` |
+| Docs tree missing or drifted | `cmk:docs` |
+| Save / draft product requirements; close package; AC + guards | `cmk:requirements` |
+| How to build it (mechanism, architecture) | `cmk:design` |
+| Record a hard-to-reverse decision | `cmk:adr` |
+| Lock a term / vocabulary drift | `cmk:glossary` |
+| Capture a gotcha | `cmk:learn` → promote with `cmk:rule` when it must be enforced |
+| AI navigation map under `docs/ai/` | `cmk:codebase-docs` |
+| Uncertain body of work → issue set | `cmk:discover-efforts` |
+| Start / pick up a tracker issue | `cmk:delivery-intake` (or `cmk:delivery-pipeline` end-to-end) |
+| Spec + plan for a ticket | `cmk:delivery-spec-plan` |
+| Review diff / PR | `cmk:delivery-review` |
+| Open PR / close ticket with evidence | `cmk:delivery-ship` |
+| Handoff to another agent | `cmk:delivery-handoff` |
+| Vendor skills / sync upstream | `cmk:agent-vendors` / `cmk:sync` |
+| CI / local stack / MCP / toolchain alone | matching setup facet (`cmk:cicd`, `cmk:local-stack`, …) |
+
+Rules of thumb:
+
+> Never draft `docs/requirements/` from a bare label — close package first (`cmk:requirements`).
+
+> State **scope band** before implement; meet **docs-ready** (`cmk:delivery-workflow`).
+
+> When two skills both seem to apply, the delivery / process skill wins; it will call the docs skill.

docs/reports/2026-08-28-author-skills-wording-pass.md

@@ -0,0 +1,47 @@
+# 2026-08-28 — author-skills wording & quality pass (CMK skills)
+
+Immutable point-in-time record of the pack-wide remediation against
+`author-skills` (Ship checklist + Vocabulary + Influence).
+
+## Scope
+
+All 34 skills under `skills/`, on branch `upgrade/cmk-standard-ceremony`.
+Subagent model roster: **grok-4.5 only**.
+
+## What landed
+
+1. **skill-lint green** — fixed oversized `delivery-pipeline` /
+   `delivery-review` / `delivery-spec-plan`; fixed dangling
+   `delivery-pipeline` attribution of `scope-band.md` (owned by
+   `delivery-workflow`); extracted review lenses to
+   `skills/delivery-review/references/lenses.md`.
+2. **Description house form** — 33 model-invocable skills now open with
+   `Use when…` (was `This skill should be used when…`). `cmk:interpret`
+   remains one plain human-facing line (`disable-model-invocation: true`).
+   Trimmed outcome-heavy descriptions on `requirements`, `delivery-simplify`,
+   `delivery-spec-plan`, `repo-setup`. Documented the opener in
+   `docs/ai/skills/conventions.md`.
+3. **Reference TOC** — `## Contents` added to 12 refs over ~100 lines
+   (cicd ×3, delivery-pipeline ×2, discover-efforts, docs scaffold-manifest,
+   local-stack ×2, requirements ×2, toolchain).
+4. **Hierarchy** — `codebase-docs` slimmed to pointers +
+   `references/{bootstrap,update,doc-shape,working-example,failure-modes}`;
+   `rule` Audit/Gate moved to `references/audit.md` + `references/gate.md`.
+5. **Gate wording + evidence (priority three)** — RED baselines on grok-4.5
+   failed without the skill for `delivery-ship`, `delivery-review`,
+   `sui-sdk`; GREEN wording added Red Flags / rationalization rows named
+   from those failures; `TESTS.md` recorded under each skill.
+
+## Explicitly still open
+
+- Most skills still lack `TESTS.md` / `eval.json` (Iron Law evidence).
+- Pack-wide verb-first renaming (`design` → verb, etc.) not done — topic
+  names remain CMK packaging convention.
+- Full RED→GREEN for every gate skill beyond the three priority ones.
+- Description trigger micro-tests not re-run pack-wide after the opener
+  rewrite (mechanical opener change; spot-checked via existing
+  `requirements` routing notes + gate GREEN runs).
+
+## Lint
+
+`./scripts/skill-lint.sh` — OK after this pass.

skills/adr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:adr
-description: This skill should be used when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern.
-version: 0.3.1
+description: Use when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern.
+version: 0.3.2
 ---
 
 # ADR

skills/agent-instructions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:agent-instructions
-description: This skill should be used when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/.
-version: 0.2.2
+description: Use when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/.
+version: 0.3.2
 ---
 
 # Agent Instructions
@@ -99,3 +99,6 @@ Report-only — never mutate:
   still referenced from `CLAUDE.md`.
 - Every conditional pointer in `CLAUDE.md` resolves to a file that exists.
 - The `.local/tmp/` scratch line is present in `CLAUDE.md`.
+- If `CLAUDE.md` points at `docs/guides/on-ramps.md`, that file exists (Init/
+  Update may seed it from the kit's `docs/guides/on-ramps.md`; Verify only
+  reports).

skills/agent-instructions/references/claude-md-template.md

@@ -51,6 +51,9 @@ any row above whose file was not seeded]
 Start at `docs/README.md` for how the rest of the documentation tree is
 organized and when to read each part of it.
 
+When the entry skill is unclear, read `docs/guides/on-ramps.md` — one table
+from situation → `cmk:*` skill. Do not invent a second router.
+
 ## Scratch
 
 Agent scratch and temporary files go under `.local/tmp/`, never a system

skills/agent-vendors/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:agent-vendors
-description: This skill should be used when the user asks to "vendor the kit's skills into this repo", "set up agent adapters", "add a coding-agent vendor", "wire skills for Claude Code / Codex / OpenCode / Grok Build / Cursor", or whenever a repo needs one canonical skill set discoverable by multiple coding agents.
-version: 0.2.0
+description: Use when the user asks to "vendor the kit's skills into this repo", "set up agent adapters", "add a coding-agent vendor", "wire skills for Claude Code / Codex / OpenCode / Grok Build / Cursor", or whenever a repo needs one canonical skill set discoverable by multiple coding agents.
+version: 0.2.1
 ---
 
 # Agent Vendors

skills/cicd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: cmk:cicd
-description: This skill should be used when the user asks to "set up CI", "speed up CI", "add a deploy workflow", "structure GitHub Actions", "self-hosted runners", "run CI locally", "JIT runner", "protect the main branch", or needs to structure CI, deployment, and policy automation as composable host-runnable scripts that GitHub Actions only automates.
-version: 0.3.3
+description: Use when the user asks to "set up CI", "speed up CI", "add a deploy workflow", "structure GitHub Actions", "self-hosted runners", "run CI locally", "JIT runner", "protect the main branch", or needs to structure CI, deployment, and policy automation as composable host-runnable scripts that GitHub Actions only automates.
+version: 0.3.4
 ---
 
 # CI/CD

skills/cicd/references/ci-structure.md

@@ -3,6 +3,15 @@
 Mechanics for the single validation pipeline in `SKILL.md`'s CI structure
 facet.
 
+## Contents
+
+- [One pipeline, many gated area jobs](#one-pipeline-many-gated-area-jobs)
+- [Speed structure](#speed-structure)
+- [Tiered runners are configuration, not a workflow edit](#tiered-runners-are-configuration-not-a-workflow-edit)
+- [Cold-cache isolation is a trap, not a given](#cold-cache-isolation-is-a-trap-not-a-given)
+- [CI self-contract tests](#ci-self-contract-tests)
+- [Label-gated diagnostic jobs](#label-gated-diagnostic-jobs)
+
 ## One pipeline, many gated area jobs
 
 A single workflow validates every push and PR. A `changes` job runs first,

skills/cicd/references/deploy-and-release.md

@@ -3,6 +3,14 @@
 Mechanics for the deploy-and-release facet in `SKILL.md`, and the GitHub ↔ IaC
 contract it specifies on behalf of `cmk:infra`.
 
+## Contents
+
+- [Validation and deployment are separate workflows](#validation-and-deployment-are-separate-workflows)
+- [Dispatch-against-ref, not branch-triggered promotion](#dispatch-against-ref-not-branch-triggered-promotion)
+- [The GitHub ↔ IaC contract, specified](#the-github-iac-contract-specified)
+- [Deploy orchestrator plus legs](#deploy-orchestrator-plus-legs)
+- [Release integrity](#release-integrity)
+
 ## Validation and deployment are separate workflows
 
 The CI workflow validates; it never deploys. Each deployable thing gets its

skills/cicd/references/host-runnable.md

@@ -3,6 +3,16 @@
 Mechanics for treating CI, deploy, and operator steps as scripts that
 any host can run. The YAML (or other remote CI file) only composes them.
 
+## Contents
+
+- [Scripts are the workflow](#scripts-are-the-workflow)
+- [Language](#language)
+- [Composer-contract drift](#composer-contract-drift)
+- [Mutate gate](#mutate-gate)
+- [Host matrix](#host-matrix)
+- [Debug on the host that ran the step](#debug-on-the-host-that-ran-the-step)
+- [When a remote job fails](#when-a-remote-job-fails)
+
 ## Scripts are the workflow
 
 Each step is independently invocable on a machine. A step that only