@cratis/pi 7.120.0 → 7.121.0

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

@@ -0,0 +1,110 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# How to write commits
+
+## Contents
+
+- Why history is never rewritten
+- Logical grouping
+- Commit messages
+- When to commit
+- Staging discipline
+
+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.
+
+The history rules (append-only history, the forbidden commands, merge commits only) stay always-on in [git-commits.md](../../../rules/git-commits.md). This reference holds the procedure.
+
+## Why history is never rewritten
+
+**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 can be lost exactly this way: a branch checkout carries another session's commit away, the branch is deleted, and the file changes silently revert in the tree. Recovery from the reflog is luck, not process.
+
+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 (for example 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 (for example a single bug fix plus 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.

package/package/corpus/skills/cratis-commits-and-pull-requests/references/pr-description.md

@@ -0,0 +1,90 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# The pull request description
+
+The contract (the description is the release note, the issue-reference rules, the reviewer-note rule) stays always-on in [pull-requests.md](../../../rules/pull-requests.md). This reference holds the detailed shape, the forbidden list and a worked example.
+
+**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 example issue references are inline code, and the comment is not published.
+
+**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.**
+
+## Allowed shape
+
+- 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).
+
+## Issue references
+
+| Write | Meaning |
+| --- | --- |
+| `(#n)` 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 #n)` or prose `see #n` | Same issue, related, partial or follow-up: never closes |
+| `Cratis/Repo#n` | Other repository: never closed |
+| one `(#n)` per issue, never `(#n, #m)` | For distinct issues, `(#n, #m)` closes nothing: write `(#n) (#m)` |
+
+- 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 `(#n, #m)` closes nothing; write `(#n) (#m)`.
+- 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 #n` line closes nothing and is not a delivery marker: write `(#n)` at the end of the delivering bullet, or `(part of #n)` 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 example issue number, 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 (#n)`, `- Reviewed by status is now shown on the dashboard (#m)`) 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 #n`, `retarget to main once #n 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 (a published release note, 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 #n` is a keyword line. The example issue was only partly delivered by this release, so its bullets use the `(part of #n)` form; `(#n)` 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.

package/package/corpus/skills/cratis-commits-and-pull-requests/references/pr-labels-and-release.md

@@ -0,0 +1,82 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Labels, release intent, grouping and quality gates
+
+The contract (exactly one release-intent label, the major go-ahead, `no-release` for non-outward changes, required gates) stays always-on in [pull-requests.md](../../../rules/pull-requests.md). This reference holds the procedure and detail.
+
+## Commits in a PR
+
+See [commits.md](./commits.md) for logical grouping, message format and staging discipline.
+
+- Imperative mood: "Add author registration", not "Added author registration".
+- Each commit is one logical unit of work. No WIP commits in the final PR.
+- Never mix unrelated changes in a single commit.
+
+## 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 in the quality gates below.
+
+## 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 these gates.** 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.
+
+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:
+
+- `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 fails the job rather than reporting success).

package/package/corpus/skills/cratis-commits-and-pull-requests/verification.json

@@ -0,0 +1,11 @@
+{
+  "skill": "cratis-commits-and-pull-requests",
+  "input": "Prepare a commit and a release-note pull request without rewriting history or publishing reviewer notes.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "../../rules/git-commits.md" },
+    { "kind": "skill-contains", "value": "../../rules/pull-requests.md" },
+    { "kind": "skill-contains", "value": "cratis-check-pr.mjs --body-file <file> --label <intent>" },
+    { "kind": "skill-contains", "value": "A human confirms and merges a major release." }
+  ]
+}

package/package/corpus/skills/cratis-engineering-ci-gates/SKILL.md

@@ -13,7 +13,7 @@ compatibility: Requires git and the GitHub CLI (gh).
 Operate checks; do not redesign workflows here. Read
 [verification-discipline.md](../../rules/verification-discipline.md) for phase
 budgets and exit-status handling, and
-[pull-requests.md](../../rules/pull-requests.md#quality-gates) for required checks.
+[pull-requests.md](../cratis-commits-and-pull-requests/references/pr-labels-and-release.md#quality-gates) for required checks.
 Read [capability-is-not-authority.md](../../rules/capability-is-not-authority.md)
 before an external effect. A request to verify does not authorize a push.
 

package/package/corpus/skills/cratis-engineering-issue-hygiene/SKILL.md

@@ -24,9 +24,23 @@ body edits are not conditional writes; a last-minute reread alone cannot prevent
 two writers from overwriting each other.
 
 Before starting, read the issue, comments, assignees and any status block. Follow
-[issue-assignment.md](../../rules/issue-assignment.md) to claim it. Do not replace
-an existing assignment. If another writer is already active, coordinate rather
-than starting a parallel edit. A failed assignment is not a blocker to the work.
+[issue-assignment.md](../../rules/issue-assignment.md) and this claiming procedure:
+
+- Applies when the user, branch, task or handover names an issue number in a
+  known repository. No known repository or issue means no guessed assignment.
+- Read assignees and state in that issue's repository:
+  `gh issue view <n> --repo <owner>/<repo> --json assignees,state`.
+- If open and unassigned, run
+  `gh issue edit <n> --repo <owner>/<repo> --add-assignee @me`.
+  `@me` means the authenticated user, not an invented identity.
+- Never replace or add to an existing assignment. Skip a closed issue; say so
+  without reopening or assigning it.
+- Do this once, at the start before the first edit, not on every turn. If it
+  fails (permissions or authentication), report it and continue with the work.
+
+The request to work on the issue authorizes this assignment only, not comments,
+labels or closure. If another writer is active, coordinate rather than starting
+a parallel edit. Delegated workers do not claim or mutate the issue.
 
 When the request covers maintaining the issue, set the status block to
 **In progress** before coding. Keep it true as work moves: **In review** for the

package/package/corpus/skills/cratis-engineering-issue-hygiene/verification.json

@@ -0,0 +1,11 @@
+{
+  "skill": "cratis-engineering-issue-hygiene",
+  "input": "Claim a known issue at work start without replacing an assignee or expanding authority.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "gh issue view <n> --repo <owner>/<repo> --json assignees,state" },
+    { "kind": "skill-contains", "value": "gh issue edit <n> --repo <owner>/<repo> --add-assignee @me" },
+    { "kind": "skill-contains", "value": "Never replace or add to an existing assignment" },
+    { "kind": "skill-contains", "value": "authorizes this assignment only" }
+  ]
+}

package/package/corpus/skills/cratis-rtk/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-rtk/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: cratis-rtk
+description: Route human-readable command output through rtk without losing exact diagnostics or exit codes. Use before choosing wrappers for git, searches, builds, tests, lint or package-manager commands, and when a wrapped command fails or a script needs raw output. Not for granting execution authority, choosing CI gates, or changing repository scripts to use rtk.
+license: LICENSE
+compatibility: Local shell; rtk is optional and must already be installed.
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Token-optimized commands
+
+Follow [rtk.md](../../rules/rtk.md): exact output and real exit codes win over
+compression. A wrapper is not verification and never expands authority.
+
+1. If `rtk` is not on `PATH`, use normal tools; do not install it or block work.
+2. For human-readable output, let the configured PreToolUse hook rewrite Bash
+   commands (for example `git status` → `rtk git status`). Without that hook,
+   prefix each supported command, including each command in an `&&` chain.
+3. For parsed output, exact paths/content/Git state, structured diagnostics or
+   output that decides the next action, use `rtk proxy <cmd>` (or the plain
+   command when no hook rewrites it). Never sacrifice the producer's exit status.
+4. If a wrapped command fails, read the actual error and retry through
+   `rtk proxy` before concluding the tool, path or repository is missing.
+5. Keep native commands in scripts, hooks and CI; do not add rtk to them.
+
+Examples:
+
+```sh
+rtk git status
+rtk proxy git diff --cached
+rtk proxy git status --porcelain
+```
+
+For builds, lint and specs use the repository's authorized gate command. Do not
+pipe a build or test into `grep`, `sort`, `head` or `tail` as gate evidence.
+A filtered zero-error summary is not a successful check.
+
+## Supported output families
+
+- Files: `ls`, `tree`, `read`, `find`, `grep`, `diff`.
+- Git and GitHub: `git status/log/diff/add/commit/push/pull`, `gh pr/issue/run …`.
+- Tests: `dotnet test`, Jest, Vitest, Playwright, pytest, Go, Cargo, RSpec.
+- Build and lint: `dotnet build`, `tsc`, ESLint, Biome, Prettier, Cargo Clippy,
+  Ruff, golangci-lint, Rubocop.
+- Package managers: pnpm/npm/yarn, pip, Bundler, Prisma.
+- Cloud and containers: AWS CLI, Docker, Kubernetes, OpenShift.
+
+## Built-in tools and audits
+
+Bash hooks do not wrap built-in Read/Grep/Glob tools. For broad exploration use
+`rtk read`, `rtk grep` or `rtk find` in the terminal to reduce output. For small,
+precise reads and exact replacement text, use the built-in file tools: rtk can
+filter away the line needed for an edit. Raw output remains mandatory whenever
+it drives an operation.
+
+Use `rtk gain` to inspect savings and `rtk discover` to find commands that missed
+compression. These are optimization aids, not quality-gate evidence. The rtk
+project is at https://github.com/rtk-ai/rtk; setup is a human's responsibility.

package/package/corpus/skills/cratis-rtk/verification.json

@@ -0,0 +1,11 @@
+{
+  "skill": "cratis-rtk",
+  "input": "Choose wrappers for human-readable status and exact parsed gate diagnostics without losing exit codes.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "rtk proxy <cmd>" },
+    { "kind": "skill-contains", "value": "do not install it or block work" },
+    { "kind": "skill-contains", "value": "Keep native commands in scripts, hooks and CI" },
+    { "kind": "skill-contains", "value": "Never sacrifice the producer's exit status" }
+  ]
+}