@cratis/pi 7.119.1 → 7.121.0

package/package/corpus/rules/git-commits.md

@@ -4,7 +4,9 @@ applyTo: "**/*"
 
 # How to Write Git Commits
 
-Commits are the permanent record of how the codebase evolved. Each commit should tell a clear story: *what* changed and *why*. A reviewer reading `git log --oneline` should understand the arc of the work without opening any diffs.
+**Before writing any commit message, committing, pushing, or creating/editing a PR, read the `cratis-commits-and-pull-requests` skill.** It holds the commit format, grouping, staging and when-to-commit procedure. This rule keeps the history contract that must hold even before the skill is read.
+
+Commits are the permanent record of how the codebase evolved. Each commit is a single logical unit of work: *what* changed and *why*, in an imperative subject of at most 72 characters, never WIP, never uncompilable. Stage specific files, never `git add .`.
 
 ## Never rewrite history
 
@@ -24,115 +26,20 @@ These commands are **forbidden** unless the human explicitly asks for that speci
 | `git gc --prune=now`, `git reflog expire` | destroys the recovery path for anything already stranded |
 | `git merge --squash`, `gh pr merge --squash`, `--rebase`, the **Squash and merge** / **Rebase and merge** buttons | collapses or replays the branch's commits into new ones; every original commit becomes unreachable and the branch's real history is destroyed at the moment of merge |
 
-**Merging is part of this rule, and it is the easiest place to get it wrong.** A squash merge feels
-like an integration step rather than a rewrite, which is exactly why it slips past: the branch is
-deleted straight afterwards, so the commits it collapsed have no ref left and `gc` eventually takes
-them. **Always merge with a true merge commit** — `git merge --no-ff`, or `gh pr merge --merge`.
-Never `--squash`, never `--rebase`, and never the equivalent buttons in the GitHub UI.
-
-If a repository's settings only allow squash or rebase merges, that is a **setting to raise with the
-owner, not a licence to squash.** Stop and ask.
+**Merging is part of this rule, and it is the easiest place to get it wrong.** A squash merge feels like an integration step rather than a rewrite, which is exactly why it slips past: the branch is deleted straight afterwards, so the commits it collapsed have no ref left and `gc` eventually takes them. **Always merge with a true merge commit** — `git merge --no-ff`, or `gh pr merge --merge`. Never `--squash`, never `--rebase`, and never the equivalent buttons in the GitHub UI.
 
-**This is not stylistic.** A commit can exist as an object (`git cat-file -t <sha>` succeeds) while being absent from every branch *and* from the working tree — reachable only through `git reflog`, and only until `gc` runs. Work has already been lost in this repository exactly this way: a branch checkout carried another session's commit away, the branch was deleted, and the file changes silently reverted in the tree. It was recovered from the reflog by luck, because someone asked the right question in time.
+If a repository's settings only allow squash or rebase merges, that is a **setting to raise with the owner, not a licence to squash.** Stop and ask.
 
 ### What to do instead
 
-- **Made a mistake in the last commit?** Add a new commit that corrects it. The wrong state stays in history, and that is fine — history is a record of what happened, not a curated story of what you wish had happened.
+- **Made a mistake in the last commit?** Add a new commit that corrects it.
 - **Need to undo a commit?** `git revert <sha>` — it records the undo as a new commit and loses nothing.
-- **Messy commits before a PR?** Leave them. A reviewer reading a coherent series of small commits is better served than by one squashed blob, and the project does not require a linear history.
-- **Landing a PR?** `gh pr merge --merge` (a real merge commit). **Not `--squash`, not `--rebase`.** The commits on the branch are the record of how the change was actually built; squashing throws that away permanently in exchange for a tidier `main`, which is not a trade this project makes.
+- **Messy commits before a PR?** Leave them; the project does not require a linear history.
+- **Landing a PR?** `gh pr merge --merge` (a real merge commit). **Not `--squash`, not `--rebase`.**
 - **Need someone else's changes?** `git merge`, never `git rebase`.
 - **Need to move a commit to another branch?** `git cherry-pick` — it copies, leaving the original reachable.
 - **Working alongside another agent or session?** Use `git worktree add` so each has its own checkout and branch. Never two sessions committing in one working tree.
 
 ### Before you finish
 
-Verify your own commits are still reachable on the branch **and** that their content is still in the working tree — those are two different things. `git log --oneline -5` plus a `grep` for something the commit introduced. If a commit has gone missing, `git reflog` is the recovery tool: find the SHA, `git tag` it immediately so `gc` cannot take it, then `git cherry-pick` it back.
-
-## Logical Grouping
-
-Every commit must be a **single logical unit of work**. Group related changes together; separate unrelated changes into distinct commits.
-
-### What belongs in one commit
-
-- A bug fix and the spec that proves it.
-- A new file and the changes to existing files needed to integrate it (imports, registrations, wiring).
-- A refactor that moves or renames code — only the mechanical transformation, nothing else.
-- An interface change together with all implementation updates required to compile.
-
-### What does NOT belong in one commit
-
-- A bug fix mixed with an unrelated feature.
-- Source code changes mixed with unrelated spec additions for a different area.
-- Formatting or style cleanups bundled with behavioral changes.
-- Multiple independent fixes or features squashed into a single commit.
-
-### Deciding where to split
-
-Ask: "If I needed to revert this commit, would I lose exactly one coherent change?" If reverting would undo two unrelated things, it should be two commits.
-
-Common split points:
-
-1. **Infrastructure / plumbing first** — interface additions, new types, or schema changes that later commits build on.
-2. **Core logic second** — the behavioral change that uses the new infrastructure.
-3. **Specs / tests third** — the specs that prove the behavioral change works. Specs may also be combined with the core logic commit when they are tightly coupled (e.g., a TDD red-green cycle or a bug fix with its regression test).
-4. **Integration or wiring last** — connecting the new behavior to the rest of the system (DI registration, routing, UI hookup).
-
-When a task produces both source fixes and new integration specs, prefer separate commits for the source changes and the specs — unless the specs are inseparable from the fix (e.g., a single bug fix + its regression test).
-
-## Commit Messages
-
-### Format
-
-```text
-<imperative summary of what this commit does>
-
-<optional body — why the change was made, context, trade-offs>
-```
-
-- **Subject line**: imperative mood, present tense. Start with a verb: `Add`, `Fix`, `Remove`, `Rename`, `Extract`, `Update`, `Support`.
-- **No period** at the end of the subject line.
-- **72-character limit** on the subject line. If you cannot describe the change in 72 characters, the commit is probably too large — split it.
-- **Body**: separated from the subject by a blank line. Explain *why*, not *what* (the diff shows the what). Use bullet points for multi-part changes.
-
-### Good examples
-
-```text
-Fix duplicate key crash in IdentityStorage.Populate
-
-The upsert used InsertOne which threw on existing identities.
-Replace with ReplaceOne using upsert: true.
-```
-
-```text
-Add type-safe event migration API with expression-based builders
-
-Introduce EventTypeMigration<TUpgrade, TPrevious> base class with
-typed property builders for Split, Join, Rename, and DefaultValue
-operations. Migrators are discovered automatically by convention.
-```
-
-```text
-Add integration specs for observer replay on redaction
-```
-
-### Bad examples
-
-- `Fix stuff` — meaningless.
-- `WIP` — never commit work-in-progress; stage and commit when the unit is complete.
-- `Add files` — says nothing about what or why.
-- `Fix bug and add new feature and update docs` — three unrelated things.
-- `Changed Observer.Handling.cs` — describes a file, not a behavior.
-
-## When to Commit
-
-- **After each logical unit passes the build** — `dotnet build` with zero errors and zero warnings, or `yarn compile` with zero errors.
-- **Before starting a different kind of work** — about to switch from fixing a bug to adding a feature? Commit the bug fix first.
-- **After completing specs for a change** — if the specs are a separate commit from the source change.
-- **Never commit code that does not compile.** Every commit must be a buildable, working state of the codebase.
-
-## Staging Discipline
-
-- Use `git add <specific files>` rather than `git add .` or `git add -A`. Only stage files that belong to the current logical unit.
-- Review `git diff --cached` before committing to verify nothing unrelated was staged.
-- If you realize mid-commit that unrelated changes are mixed in, unstage them and commit only the related subset.
+Verify your own commits are still reachable on the branch **and** that their content is still in the working tree: `git log --oneline -5` plus a `grep` for something the commit introduced. If a commit has gone missing, recover it from `git reflog`, `git tag` it immediately, then `git cherry-pick` it back.

package/package/corpus/rules/glossary.md

@@ -1,5 +1,18 @@
 ---
-applyTo: "**/*"
+applyTo: "**/*.cs,**/*.ts,**/*.tsx,**/*.go,**/*.kt,**/*.kts,**/*.java,**/*.ex,**/*.exs,**/*.play,**/Documentation/**/*.md,**/Documentation/**/*.mdx"
+paths:
+  - "**/*.cs"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.go"
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/*.java"
+  - "**/*.ex"
+  - "**/*.exs"
+  - "**/*.play"
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
 ---
 
 # Cratis Glossary

package/package/corpus/rules/issue-assignment.md

@@ -4,29 +4,9 @@ profile: cratis/engineering
 
 # Claim the issue you start work on
 
-When an agent starts work on a GitHub issue, the issue says who is on it. Nobody can
-tell from an unassigned issue that work has begun, so two people (or two agents) pick it
-up, or it looks abandoned while it is being done.
-
-- **Applies when** the work is tied to an issue with a number in a known repository: the
-  user named it (`#123`, `Cratis/Repo#123`, an issue URL), or the branch, task or handover
-  names it. Work with no issue, or an issue whose repository you cannot determine, is
-  outside this rule; never guess a number or a repository.
-- **Read the assignees first**, in the issue's own repository:
-  `gh issue view <n> --repo <owner>/<repo> --json assignees,state`.
-- **Assign only when nobody is assigned.** Run
-  `gh issue edit <n> --repo <owner>/<repo> --add-assignee @me` so the current `gh` user is
-  the assignee. `@me` resolves to whoever is authenticated, so it is the user the agent
-  works for, not a name you invent.
-- **Never replace or add to an existing assignment.** Someone already on the issue means
-  it is claimed; leave it, and mention it if it affects the work.
-- **Do it once, at the start,** before the first edit. Do not re-check on every turn.
-- **Skip a closed issue** and say so; do not reopen or assign it.
-- **If assigning fails** (no permission, `gh` not authenticated, the issue is in a
-  repository you cannot write to), say so in one line and continue with the work. A missing
-  assignee is never a reason to stop.
-
-The user's request to work on the issue is the authority for this assignment; do not ask
-before doing it. It authorizes assigning the issue and nothing else: commenting, labeling
-or closing still follow [pull-requests.md](./pull-requests.md) and the user's request.
-- **After claiming,** keep the issue current per `cratis-engineering-issue-hygiene`.
+Before editing issue-linked work, read **cratis-engineering-issue-hygiene**.
+Claim once at start: read state and assignees, assign `@me` only if open and
+unassigned. Never guess an issue/repository, replace an assignee or reopen a
+closed issue. Report assignment failures and continue. The request to work on
+the issue authorizes this claim only, not comments, labels or closure; follow
+[pull-requests.md](./pull-requests.md) and the user's request for those.

package/package/corpus/rules/pull-requests.md

@@ -4,184 +4,32 @@ applyTo: "**/*"
 
 # How to Do Pull Requests
 
-## The description is the release note
-
-**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `policy / verify` check enforces it on release-bound PRs into the default branch carrying `major`/`minor`/`patch` (it re-runs when the label is added); its release-note step warns on `no-release` and unlabelled PRs, which must still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, and `release-action` removes them before publishing, so a `(#n)` only inside a comment closes nothing; the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code, and the comment is not published.
+**Before writing any commit message, committing, pushing, or creating/editing a PR, read the `cratis-commits-and-pull-requests` skill.** It holds the allowed description shape, the forbidden list, worked examples, label procedure, grouping and release-action windows. This rule keeps the contract that must hold even before the skill is read. Commit rules are in [git-commits.md](./git-commits.md).
 
-**A change to a hook script or its wiring (`.cratis/ai/hooks/**`) needs a release-note line that tells consumers to run `cratis ai update`; a hook fix does not reach a repository until they do.**
+## The description is the release note
 
-### Allowed shape
+**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up.
 
-- Follow the repository's pull request template (`.github/pull_request_template.md`) within this contract.
-- An optional summary, first, only when one cohesive theme spans the bullets: **either** a `## Summary` section (short, user-facing prose) **or** one unheaded lead paragraph (1–3 sentences), never both. `Summary` is a level-2 heading; `# Summary` is the wrong level. No bullets before the first section.
-- Then only these `##` sections, each at most once, in this order after any `## Summary`: `## Added`, `## Changed`, `## Fixed`, `## Removed`, `## Security`, `## Deprecated`. Keep only the sections that have bullets: a section holding only prose, a code example or `None.` fails the check, so delete it. `###` sub-headings inside a section are fine unless they use a forbidden name; inside a section even `### Added` is only a sub-heading, and a section itself is always level 2.
-- A `major`/`minor`/`patch` PR needs at least one bullet under an allowed section.
-- Bullets are short, self-contained and user-facing: what a consumer compiles against, runs or observes. A user-visible fix may add one sentence of root cause or regression guard, stated as observable behavior. Credit an external contributor by name or handle, unless they asked not to be named.
-- Breaking changes and upgrade actions are bullets in `## Changed` or `## Removed` that state the action. A longer migration story goes in the docs, linked by absolute URL.
-- Do not list internal plumbing (storage, converters, gRPC internals, specs, file lists, refactor narration).
+- Follow the repository's pull request template within this contract: an optional summary first, then only `## Added`, `## Changed`, `## Fixed`, `## Removed`, `## Security`, `## Deprecated`, each with short, user-facing bullets and none empty.
+- Never put review, verification, test or CI results, provenance, merge or deploy instructions, internal state, relative links or placeholders in the description. **Reviewer-facing information goes in a PR comment** posted right after creating the PR (`gh pr comment <n> --body-file .ai-work/pr-notes.md`), even when the PR is labelled `no-release`.
+- A change to a hook script or its wiring (`.cratis/ai/hooks/**`) needs a release-note line that tells consumers to run `cratis ai update`; a hook fix does not reach a repository until they do.
 
 ### Issue references
 
-| Write | Meaning |
-| --- | --- |
-| `(#351)` at the **end of the bullet that delivers it** | Delivered: in a repository released by `cratis/release-action`, it closes it at release |
-| `(part of #351)` or prose `see #351` | Related, partial or follow-up: never closes |
-| `Cratis/Repo#351` | Other repository: never closed |
-| one `(#351)` per issue, never `(#351, #352)` | `(#351, #352)` closes nothing: write `(#351) (#352)` |
-
-- Nothing but more issue references (also `(part of #n)`, `(see #n)` and `(Cratis/Repo#n)`), closing emphasis, `<br>` and sentence punctuation (a `:` may introduce nested bullets) may follow the delivering `(#n)`. Write one `(#n)` per issue: release-action only matches `(#n)`, so `(#56, #57)` closes nothing; write `(#56) (#57)`.
-- Never use a linking or closing keyword before a number, anywhere: `Close`, `Closes`, `Closed`, `Fix`, `Fixes`, `Fixed`, `Resolve`, `Resolves`, `Resolved`, `Refs`, `Ref`, `References`, also as `Keyword: #n`, with `owner/repo#n`, followed by an issue URL, and wrapped in bold, italics or a link (`**Closes** #n`, `Closes [#n](url)`, `[Closes #n](url)`, and `[Closes](url)` where the link starts a clause). A `Refs #93` line closes nothing and is not a delivery marker: write `(#93)` at the end of the delivering bullet, or `(part of #93)` if it must stay open.
-- Comment on or close an issue when the user's request includes that effect; otherwise prepare a bounded post-merge disposition without performing it. In repositories released by `cratis/release-action`, a delivered `(#n)` is closed by release-action at release, so do not close it by hand; for a `no-release` PR release-action does not run, so any disposition follows this same rule. Elsewhere, follow the repository's own release and issue-closing process.
-- Use a bare `(#n)` only for an issue this PR fully delivers. No issue means no reference. Never use a placeholder such as `(#issue)` or the template's `(#123)`, and verify every number exists in the right repository; never guess.
-
-### Forbidden anywhere outside code
-
-- **Headings** (any level, also written as HTML `<h2>`, `<b>`, `<i>` or a possibly multi-line `<summary>`, or as an `*italic*` line; a heading line is checked like any other, so a keyword, relative link or `(#n)` in one fails too) other than a first `## Summary`, such as Overview, Description, What, Why, How, Context, Changes, What changed, Test plan, Testing, Tests, Verification, Verified, Validation, Quality, Review, Notes, Notes for reviewers, Limitations, Known follow-up, Acceptance, Details, and any `#`/`##` heading not in the allowed list.
-- **Review, verification, testing and provenance notes**: `Review:`, `Reviewed:`, a stand-alone `Reviewed by` line, `Verification:`, `Tested:`, `Testing:`, `Validation:` lines that stand alone or report a result (`Tests: 400 passed`, `Review: approved`); same-provider, cross-provider, Opus-only or Anthropic-only review remarks; the review workflow having passed, returned or run; CI or gate results (`CI green`, `all tests passed`); and a line stating which agent or model wrote the description (`Generated with Claude Code`, `Co-Authored-By:`). A bullet that describes a product change and only mentions review, validation, tests or an AI model (`- Validation: rules now apply to commands (#3)`, `- Reviewed by status is now shown on the dashboard (#4)`) is fine: inside a bullet, a summary or the lead paragraph the check reads a note only when it ends the clause (`- Cross-provider review pending`).
-- **Verification and scope notes**: how or where something was checked (`verified by building …`, `verified in Storybook`, `tested locally`, `Storybook only`), what was not checked (`not yet verified`, `Not verified against a real kernel`), and results (`492/492`, `9 of 9 runs`, `Tier 1 PASS`, `0 warnings, 0 errors`, a `Local:`, `CI:`, `Checks:` or `Checked locally:` line).
-- **Reviewer, merge and deploy instructions**: `Stacked on #207`, `retarget to main once #207 merges`, `This PR should be deployed separately`, `Draft:`, `do not merge`, merge or deploy order. If a consumer must upgrade in a set order, write that as an upgrade bullet ("Upgrade the Chronicle kernel to 19.25 before this client").
-- **Provenance**: which branch, commit or build something was checked against (`verified against Arc.TypeScript main (v0.34.0)`). If compatibility matters to the reader, state it as a fact about the release: "Requires `@cratis/arc` 0.34 or later."
-- **Internal state** that is not a consumer change (for example "npm publication remains disabled").
-- **Relative links** (`](Documentation/x.md)`, `](./x)`, `](Source/...)`): they 404 on the release page. Use `https://github.com/Cratis/<Repo>/blob/main/<path>`, a `#anchor` or `mailto:`.
-- **Placeholders and transcripts**: template text, empty sections, Copilot "Original prompt" blocks, agent transcripts.
-
-Reviewer-facing information (test plan, verification, what was not verified, review provenance, stacking, merge or deploy order) goes in a **PR comment** posted right after creating the PR: `gh pr comment <n> --body-file .ai-work/pr-notes.md`. Never put it in the description, even when the PR is labelled `no-release`.
-
-### Keep the note true to the diff
-
-After merging or rebasing the base branch, and before every body edit, run `git diff --stat origin/main...HEAD`. Delete each bullet whose change is now on main through another PR, or was dropped in conflict resolution. Check every version, package name and registry against the diff and the current `.github/workflows/publish*.yml`; never name a registry the publish workflow does not push to.
-
-### Bad to good
-
-Bad (Cratis/Arc.TypeScript v0.48.0 as first published, bullets abridged):
-
-```markdown
-Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview. npm publication remains disabled.
-
-## Added
-
-- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... (#93)
-
-See [Activate reactors and reducers in Arc scopes](Documentation/chronicle/reactors/scoped-activation.md).
-
-Review: Opus-only (same-provider) review.
-
-Refs #93
-```
-
-Good (as corrected):
-
-```markdown
-Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview.
-
-## Added
-
-- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... See [Activate reactors and reducers in Arc scopes](https://github.com/Cratis/Arc.TypeScript/blob/main/Documentation/chronicle/reactors/scoped-activation.md). (part of #93)
-```
-
-"npm publication remains disabled" is internal status, the link was relative (it 404s on the release page), the review line is provenance for reviewers, and `Refs #93` is a keyword line. #93 was only partly delivered by this release, so its bullets say `(part of #93)`; `(#93)` would have closed it.
-
-### Before you create or edit a PR
-
-1. Run `node .cratis/ai/hooks/scripts/cratis-check-pr.mjs --body-file <file> --label <intent>`. It runs the exact `policy / verify` release-note rules plus the label and diff checks, and the Bash hook runs it on `gh pr create` and `gh pr edit`.
-2. Read the body against the forbidden list and the issue table above; delete every hit and verify every issue number.
-3. Sections in order, none empty, at most one summary form; every bullet user-facing.
-4. Test plan, verification and review notes are in a PR comment.
-
-If the release-note rules fail, fix the description, not the code.
-
-## Commits
-
-See the full [Git Commits guide](./git-commits.md) for rules on logical grouping, message format, and staging discipline.
-
-Quick reminders:
-
-- Imperative mood: "Add author registration" not "Added author registration".
-- Each commit = one logical unit of work. No WIP commits in the final PR.
-- Never mix unrelated changes in a single commit.
+- `(#n)` at the end of the bullet that delivers it closes the issue at release: use it **only** for an issue this PR fully delivers. One `(#n)` per issue: `(#351, #352)` closes nothing, write `(#351) (#352)`.
+- `(part of #n)`, prose `see #n` or `Cratis/Repo#n` relate without closing. No issue means no reference; never use a placeholder or guess a number.
+- Never use a linking or closing keyword before a number, anywhere (`Close`, `Closes`, `Fix`, `Fixes`, `Resolve`, `Resolves`, `Refs`, `References`, in any form). `Refs #n` closes nothing: write `(#n)` or `(part of #n)`.
+- Comment on or close an issue only when the user's request includes that effect. A delivered `(#n)` in a repository released by `cratis/release-action` is closed at release; do not close it by hand.
 
 ## Labels
 
-Confirm the current repository workflow contract before selecting release intent because release-intent labels can trigger publication. A direct request to ship with a named label authorizes applying that label and completing the repository's standard pull-request workflow, including the release it normally triggers. Do not ask for separate authorization at each step. If the user did not request shipping or publication, a proposed semantic label describes impact but does not grant authority.
-
-- Exactly one of `major`/`minor`/`patch`/`no-release`, set in the creating command (`gh pr create --label patch`), in every repository, including samples, docs and tooling repositories (`no-release` when nothing is shipped). To change intent, swap labels in one command: `gh pr edit <n> --remove-label minor --add-label patch`. Never add a second: with more than one of them, release-action releases nothing and reports `reason=error`. Re-running a `pull_request` workflow replays the original label payload, so fix a label mistake by editing the PR or pushing; a `workflow_dispatch` run needs an explicit `version` and the PR description as `release-notes`, and without notes it closes no issues.
-- Dependabot PRs carry only `no-release`. release-action never releases them, and the `major`/`minor`/`patch` Dependabot adds describe the dependency's version, not this product's.
-- Label the PR according to semantic versioning impact:
-  - **major** — breaking changes to public APIs
-  - **minor** — new features, new slices, non-breaking additions
-  - **patch** — bug fixes, refactoring with identical behavior
-
-### A major release needs a human's explicit go-ahead
-
-A `major` label is the one release-intent label a ship request does not, by
-itself, authorize through to merge. Breaking a public API is the most
-consequential and hardest-to-reverse thing a release does — every downstream
-consumer eventually has to act on it — so it gets a checkpoint the other two
-intents do not.
-
-- Prepare the branch, commits, push, and PR carrying the `major` label exactly
-  as any other ship request would.
-- Before merging, stop and ask a human to confirm the major bump specifically:
-  name the exact breaking change(s), who is affected and how, and the
-  resulting version number. A generic "ready to ship?" is not this checkpoint —
-  say plainly that this release breaks compatibility and needs a yes.
-- A human merges a `major` PR, after answering that question with an explicit
-  yes. An agent never merges it, even after the confirmation. A prior general
-  instruction to "ship" or "land this" does not answer it, even when it named
-  `major` as the intended label.
-- This checkpoint is per release, not per conversation — a human confirming
-  one major release does not pre-authorize the next one.
-
-This narrows the general ship-changes authorization in
-[`ship-changes.prompt.md`](../prompts/ship-changes.prompt.md) for exactly this
-label; every other step of that workflow proceeds under its existing
-authority.
-
-### A pull request that changes nothing outward-facing carries `no-release`
-
-**If nothing in the PR can change what a consumer compiles against, runs, or observes, propose repository-supported non-release intent, ordinarily `no-release`** — not `patch`. Confirm that the current workflow supports the label, requires exactly one release-intent label, and suppresses publication as intended before applying it with authorization.
-
-Where the repository requires release intent, `no-release` is a decision, not an omission. Missing required labels are blockers, not a reason to bypass the check.
-
-This covers, whenever the PR touches *only* these:
-
-- **Documentation** — anything under `Documentation/**`, READMEs, the `.cratis/ai/` corpus.
-- **CI and repository automation** — `.github/workflows/**`, `.github/scripts/**`, `.github/CODEOWNERS`, issue/PR templates.
-- **Tests and specs** — `*.Specs/**`, `when_*/**`, `for_*/**`, `Integration/**`, and test-only fixtures.
-- **Build and tooling configuration** that produces no shipped artifact difference — lint config, editor config, local scripts.
-
-The test is **outward-facing effect, not file location**. A change under `Source/**` that only touches specs is not shippable; a one-line change to a published package's behavior is, however small. If a consumer could not tell the difference by upgrading, there is nothing to version. When genuinely unsure, ask rather than defaulting to `patch` — an unnecessary release is not free: it burns a version number, ships release notes describing nothing, and buries the releases that matter.
-
-A non-release pull request must satisfy the relevant required checks like any other. Confirm label acceptance and publication suppression against the current workflow contract; do not assume external CI or API state.
-
-### Release-action windows and workflow drift
-
-Batching is opt-in; success with `batched` or `nothing-pending` is not publication.
-Read **cratis-release-notes** before configuring windows, handling a pending-major
-hotfix, or recovering a workflow-drift 403. Major confirmation remains required;
-a workflow-drift recovery differs from the concurrent-tag retry above.
-
-### Group small related changes into one pull request
-
-Do not open a pull request per task when the tasks belong to the same body of work. Several small merged PRs become several releases, and a stream of near-empty patch releases makes the release history useless for the people it is written for. Collect related work — a set of CI gates, a group of fixes in one area, the steps of one refactor — onto **one branch, as separate commits**, and open **one** pull request. Commits stay one-logical-unit-each; the pull request is the release boundary, and the release boundary should be a coherent, describable change. Joining an open candidate, folding superseded PRs and the cut are in `cratis-engineering-release-trains`.
-
-**Before consolidating open PRs, review each PR’s release intent and workflow effects.** Integration may trigger completion/publication behavior on an absorbed PR. Use supported non-release intent where appropriate. A direct request to consolidate the named pull requests authorizes the necessary relabeling and merge; it does not authorize unrelated notifications.
-
-Before a consolidation or a re-land of reverted work merges, prove it dropped nothing with `cratis-engineering-consolidation-guard`.
-
-Split into separate pull requests when the changes are genuinely unrelated, when one is urgent and the others are not, or when one is risky enough to want its own revert.
-
-## Quality Gates
-
-Documentation-only changes use repository-supported non-release intent, ordinarily `no-release`; confirm the workflow contract rather than assuming a label or API state. Run relevant content, link, frontmatter, and corpus checks instead of unrelated application builds, and satisfy every repository-required check, including release-intent checks where supported. Documentation is never a blanket exemption from red CI.
-
-**`no-release` does not otherwise excuse a PR from this section.** A CI, tooling, or spec-only pull request ships nothing, but it is exactly the kind of change that can break the build or the pipeline for everyone else — a broken workflow or a deleted spec does its damage without ever being released. Hold it to every gate below.
+- **Exactly one** of `major`/`minor`/`patch`/`no-release`, set in the creating command (`gh pr create --label patch`), in every repository. Never add a second: release-action then releases nothing. Swap in one command with `gh pr edit --remove-label … --add-label …`. Dependabot PRs carry only `no-release`.
+- Confirm the repository workflow before choosing, because the label can trigger publication. A direct request to ship with a named label authorizes applying it and the standard workflow; without a ship request a proposed label describes impact but grants no authority.
+- **A major release needs a human's explicit go-ahead, and a human merges it.** Prepare the branch and PR with `major`, then stop and ask a human to confirm the major bump: name the breaking changes, who is affected and the resulting version. A general "ship" instruction does not answer it. An agent never merges a `major` PR, even after confirmation; the checkpoint is per release.
+- **If nothing in the PR can change what a consumer compiles against, runs or observes, use `no-release`**, not `patch`: documentation, CI and automation, tests and specs, tooling configuration. The test is outward-facing effect, not file location. When unsure, ask rather than defaulting to `patch`.
 
-Before marking code/automation work ready, select the affected-project gates that apply from the following list; run wider checks for cross-cutting changes and repository-required merge/release gates:
+## Before you create or edit a PR
 
-- `dotnet build` — zero errors, zero warnings
-- `dotnet test` — all specs pass
-- `yarn lint` — zero errors
-- `npx tsc -b` — zero TypeScript errors
-- Code follows all project coding standards and conventions
-- **Required CI checks pass.** After an authorized push, inspect checks and failure logs. Diagnose within a bounded attempt, fix in-scope causes, and re-run relevant gates after each fix. Report unrelated/environmental failures and missing authority as blockers rather than retrying indefinitely or silently waiving required checks. Waiting, cancelling and tiered local gates are in `cratis-engineering-ci-gates`. If a release job fails after a concurrent merge (the release for the tag exists for another commit), re-run it: it releases under the next version (release-action v1.4.2 fails the job rather than reporting success).
+- Run `node .cratis/ai/hooks/scripts/cratis-check-pr.mjs --body-file <file> --label <intent>`; it applies the exact `policy / verify` release-note rules and the Bash hook runs it on `gh pr create` and `gh pr edit`. If it fails, fix the description, not the code. Before every body edit, run `git diff --stat origin/main...HEAD` and delete bullets the diff no longer supports.
+- Run the affected-project gates before marking work ready (`dotnet build`/`dotnet test` with zero warnings, `yarn lint`, `npx tsc -b`), and the repository's required CI checks after an authorized push. `no-release` and documentation-only PRs still satisfy every required check; none is a blanket exemption from red CI.
+- Group small related changes into one branch and one PR; see the skill for consolidation and the release-action windows.

package/package/corpus/rules/rtk.md

@@ -1,47 +1,12 @@
 ---
 applyTo: "**/*"
-description: "Use when running any shell command, reading files, or searching code. Route commands through rtk for human-readable output (a hook auto-rewrites Bash commands; prefix rtk yourself where it does not); use raw output when the result is parsed, compared exactly, or drives another operation."
+description: "Choose command wrappers without losing exact output or exit codes."
 ---
 
 # Using rtk (Token-Optimized Commands)
 
-[rtk](https://github.com/rtk-ai/rtk) (Rust Token Killer) is a CLI proxy that filters and compresses command output *before it reaches the model* — typically **60–90% fewer tokens** on common dev commands, with no loss of the signal you actually need. The default in this corpus is to **run every command rtk supports through rtk**. The savings are real and compound across a session: build, test, lint, git, search, and file-read output are exactly the high-volume, low-signal outputs rtk trims.
-
-## How it works — let the hook do its job
-
-A `PreToolUse` hook **auto-rewrites Bash commands** to their `rtk` equivalent transparently and at zero token overhead (`git status` → `rtk git status`). For any supported command you do **nothing special** — run it normally and the hook wraps it. Where no hook is configured, prefix the command yourself — including each command in an `&&` chain: `rtk git add . && rtk git commit -m "msg"`.
-
-- **Audit coverage** with `rtk gain` (savings so far) and `rtk discover` (commands that slipped past rtk — missed opportunities to close).
-
-## When to use raw output instead
-
-rtk output is a summary for a reader. It is never evidence of exact file contents, paths, Git state, or command semantics, and a filter can drop the line you needed. Use the raw command — `rtk proxy <cmd>`, or the plain command where nothing rewrites it — whenever:
-
-- the output is parsed by a script, compared exactly, or fed to another command;
-- the output is the evidence for a claim about content, paths, or Git state;
-- the command's exit code or exact diagnostics decide what happens next (security checks, structured JSON, machine-readable diagnostics);
-- a wrapped command failed. Read the actual error and retry through `rtk proxy` before concluding the tool, path, or repository is missing.
-
-Do not add `rtk` to scripts, hooks, or CI steps that deliberately use native commands; their raw output is the point. Exit codes are never traded for token savings — see [`exit-codes-and-wrappers.md`](./exit-codes-and-wrappers.md).
-
-## What rtk supports (route these through rtk)
-
-- **Files** — `ls`, `tree`, `read`, `find`, `grep`, `diff`
-- **Git & GitHub** — `git status/log/diff/add/commit/push/pull`, `gh pr/issue/run …`
-- **Tests** — `dotnet test`, Jest, Vitest, Playwright, pytest, Go, Cargo, RSpec
-- **Build & lint** — `dotnet build`, `tsc`, ESLint, Biome, Prettier, Cargo Clippy, Ruff, golangci-lint, Rubocop
-- **Package managers** — pnpm/npm/yarn, pip, Bundler, Prisma
-- **Cloud & containers** — AWS CLI, Docker, Kubernetes, OpenShift
-
-In practice this means the Cratis **quality-gate commands** — `dotnet build`, `dotnet test`, `yarn lint`, `npx tsc -b`, `git`, `gh` — all flow through rtk automatically. Just run them.
-
-## The one gap — built-in tools bypass the hook
-
-The hook only sees **Bash** commands. Claude Code's built-in `Read`, `Grep`, and `Glob` tools (and the Copilot equivalents) do **not** pass through it, so they are **not** auto-rewritten — and those are some of the most token-heavy operations in a session.
-
-- For **bulk reads and broad searches** where output volume is large, call **`rtk read` / `rtk grep` / `rtk find`** from the terminal so the savings are captured. This is a deliberate override of the usual "prefer the built-in file tools" default.
-- Keep the **built-in** `Read`/`Grep`/`Glob` for **small, targeted reads** and when you need exact line references for an edit — rtk filters output, so it serves exploration and volume, not the precise content an `Edit` must match verbatim.
-
-## Availability
-
-This assumes the `rtk` binary is installed and the hook configured (`rtk init -g`). If `rtk` is **not** on `PATH`, ignore this rule and use the normal tools — never block work on rtk being present.
+Read **cratis-rtk** before choosing wrappers. The Bash hook rewrites supported
+commands; built-in tools bypass it. Exact output and real exit codes win:
+use `rtk proxy <cmd>` for parsed output, diagnostics and evidence driving an
+operation, including wrapped failures. Never use summaries as gate evidence.
+If rtk is absent, use normal tools. Keep scripts, hooks and CI native.

package/package/corpus/skills/cratis-commits-and-pull-requests/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/package/corpus/skills/cratis-commits-and-pull-requests/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: cratis-commits-and-pull-requests
+description: Prepare coherent commits and release-note pull requests with the right release-intent label. Use when writing a commit message, staging commits, pushing, creating or editing a PR description, choosing major/minor/patch/no-release, or checking issue references in release notes. Not for assembling release candidates (use cratis-engineering-release-trains), issue status updates (use cratis-engineering-issue-hygiene), or batching release windows (use cratis-release-notes).
+license: LICENSE
+compatibility: Requires git and the GitHub CLI (gh).
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Commits and pull requests
+
+Read [git-commits.md](../../rules/git-commits.md) and
+[pull-requests.md](../../rules/pull-requests.md) before acting. Their always-on
+contracts govern history, release notes, labels, authority and required gates.
+Loading this skill grants no permission to push, publish, merge or mutate issues.
+
+1. Inspect the diff and the repository's workflow before choosing the logical
+   commit boundaries and release intent. Read [references/commits.md](references/commits.md)
+   when staging, writing a message or deciding when to commit. Stage specific
+   files and inspect `git diff --cached`; never commit an unbuildable unit.
+2. Read [references/pr-description.md](references/pr-description.md) when writing
+   or editing a PR or manual release note. Write consumer-facing bullets, not a
+   work report. Only fully delivered issues get a closing delivery reference.
+3. Read [references/pr-labels-and-release.md](references/pr-labels-and-release.md)
+   when choosing or swapping a label, grouping related work, checking gates or
+   handling a release-action window. Confirm publication effects before applying
+   the single label. A human confirms and merges a major release.
+4. Run affected-project gates, then the repository-required checks. Before each
+   body edit, compare `git diff --stat origin/main...HEAD` and remove unsupported
+   bullets. Validate the description with
+   `node .cratis/ai/hooks/scripts/cratis-check-pr.mjs --body-file <file> --label <intent>`.
+   A zero exit status is the pass signal; fix the description on failure.
+5. Create or edit only when authorized. Put verification, review and deployment
+   notes in a PR comment, not the published release note. Confirm the applied
+   label and body after writing. Never replace history for a tidier PR.
+
+Minimal description for a delivered consumer fix without an issue reference:
+
+```markdown
+## Fixed
+
+- Preserve command validation messages when a request is retried.
+```
+
+If the diff only changes non-outward documentation or tooling, choose
+`no-release` rather than manufacturing a patch release. If the workflow or
+impact is unclear, ask about that specific choice rather than guessing.