@cratis/pi 7.120.0 → 7.122.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-components-accessibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-accessibility
-description: Apply the accessibility conventions Cratis Components 4 actually implements — dialog initial-focus discipline and the armed-Enter hazard, supplying every accessible name as a localizable prop or provider message, putting the accessible name on the focusable element rather than the wrapper, keeping decorative icons hidden, and customizing through parts without fighting the component's own ARIA. Use when building or reviewing a dialog, a form control, a data table, a toast, or any component whose accessible name is currently a hard-coded English string. Do not use as a general WCAG conformance guide.
+description: Use when fixing Cratis Components focus, keyboard submission, accessible names, field announcements or decorative icons. Not for claiming general WCAG conformance or choosing a visual theme.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-common-controls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-common-controls
-description: Choose and bind Cratis Components ComboBox, ToggleGroup, Tabs, TagGroup and Breadcrumbs with controlled values, query states, keyboard semantics and localizable names. Use for entity pickers, exclusive choices, panel tabs, tag inputs or navigation trails. Do not use for Arc generated command fields, data tables, canvas palettes or theming.
+description: Use when binding Cratis Components entity pickers, exclusive choices, panel tabs, tag inputs or breadcrumb trails. Not for generated Arc command fields, data tables, canvas palettes or theming.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-data-surfaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-data-surfaces
-description: Compose Cratis Components PivotViewer exploration, TimeMachine historical snapshots, Canvas pan/zoom boards and public Chat conversation/sidebar surfaces. Use when a table is not the right presentation, when supplying Pixi-backed content, or when binding host-owned chat data and actions. Do not use for DataPage lists, backend event replay, chat persistence, canvas tool palettes or Scene authoring.
+description: Use when a Cratis UI needs pivot exploration, historical snapshots, a pan/zoom board or host-owned chat views. Not for DataPage lists, event replay, chat persistence, tool palettes or Scene authoring.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-schema-editor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-schema-editor
-description: Use the Cratis Components schema editors — SchemaEditor for editing a JSON schema's property structure, and ObjectContentEditor for viewing and editing an object instance against a schema. Covers the exact props, the narrow JSON-schema subset they consume, how edits come back out, the type-format vocabulary, property-name validation, and the real editing limits. Use when building a UI that lets a user shape an event or payload schema, or inspect and edit a stored object. Do not use for a command form bound to a generated Arc command.
+description: Use when building a Cratis UI to edit a schema's structure or inspect and edit object data against a schema. Not for forms bound to generated Arc commands; use cratis-arc-react-page.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-stepper-command-dialog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-stepper-command-dialog
-description: Build a multi-step wizard dialog for a single Cratis Arc command with StepperCommandDialog and StepperPanel from Cratis Components — named steps, per-step validation, linear navigation, vertical or horizontal orientation, and pre-populated edit wizards. Use when one command gathers information across several stages or a form has too many fields to show at once. Do not use for an ordinary single-page command dialog or for a page shell.
+description: Use when one Arc command needs a multi-step wizard or a form has too many fields for one dialog page. Not for ordinary single-page command dialogs or a page shell; use cratis-arc-react-page.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-styling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-styling
-description: Style and theme an application built on Cratis Components 4 — the three stylesheet entries an app must import, the --cratis-* design-token seam, choosing between the baseline theme, a product theme and fully owned styling, dark mode, the typed pt parts and data-cratis-part selectors, the optional renderer adapters, and where Tailwind actually fits. Use when setting up a new Cratis frontend, changing colors or theming, fixing components that render unstyled, or styling one part of a component. Do not use for component API or page composition questions.
+description: Use when setting up Cratis Components styles, fixing unstyled components or changing themes, tokens and component parts. Not for component binding APIs or page composition.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-components-toolbar/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-components-toolbar
-description: Build a canvas-style icon toolbar with the Cratis Components Toolbar family — Toolbar, ToolbarButton, ToolbarSeparator, ToolbarGroup, ToolbarSection, ToolbarContext, ToolbarFanOutItem, ToolbarFolder, and the slot components that let a distant part of the tree contribute buttons. Use when building a drawing or diagram tool palette, a zoom or mode control strip, or any icon-button group with active state, context switching, or fan-out sub-panels. Do not use for a page action menu over a data table.
+description: Use when building a Cratis drawing or diagram tool palette, zoom strip or icon-button group with active modes and fan-out panels. Not for page actions over a data table; use cratis-arc-react-page.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-content-length/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-content-length
-description: Decide how long a piece of content should be, when to keep it short, when it earns more length, and where to split it, for feed posts, documents and carousels, video, social threads, community posts, blog articles, tutorials, newsletters and release notes. Use when planning, drafting or reviewing content length, or a batch whose lengths are all the same. Do not use for SEO scoring or authorship detection.
+description: Use when choosing a content piece's length, deciding where to split it or reviewing a batch with uniform lengths. Not for SEO scoring, authorship detection or distribution planning.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-developer-marketing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-developer-marketing
-description: Plan or review how developer-facing content earns real engagement and adoption - positioning with developers, choosing the canonical artifact and its channel-native entry points, community participation, founder and company voice, a cadence a small team can keep, and measurement that doesn't fake attribution. Use when planning a content program, a launch, a distribution plan, a channel choice, a measurement plan or a repurposing plan. Do not use for drafting a specific feed post (use cratis-social-feed-post), voice review (cratis-writing-voice-and-cadence), length decisions (cratis-content-length), release notes (cratis-release-notes) or code examples (cratis-technical-examples).
+description: Use when planning developer-content distribution, a launch, channel selection, repurposing or adoption measurement. Not for drafting individual posts, voice edits, content length, release notes or code examples.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-discoverability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-discoverability
-description: Check Cratis content before publishing for search and AI answers without sacrificing readability. Use when reviewing discoverability, SEO, AEO or GEO; writing fact blocks or download claims; editing package/repo metadata; checking docs titles, descriptions or LLM export budgets; or reviewing founder/company JSON-LD and member profile indexing. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
+description: Use when checking Cratis search discoverability, metadata, adoption claims, structured data or indexing before publication. Not for page voice, export architecture, distribution strategy or content length.
 license: MIT
 ---
 

package/package/corpus/skills/cratis-documentation-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-documentation-writing
-description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
+description: Use when planning a Cratis documentation reader journey, choosing a page's purpose or reviewing its structure. Not for example execution, release notes or publication; use the corresponding specialist.
 license: MIT
 metadata:
   cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"

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

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-ci-gates
-description: Run CI-matched local gates and watch exact workflow runs without polling or wasting checks. Use when choosing a local gate or tier, deciding how to wait for CI, starting a blocking watch, or deciding which superseded runs to cancel. Not for grouping deliveries (use cratis-engineering-release-trains), review iterations (use cratis-engineering-review-rounds), or editing workflows for speed (use cratis-ci-pipeline-performance).
+description: Use when choosing CI-matched local gates, waiting for exact workflow runs or considering cancellation of owned superseded checks. Not for delivery grouping, review rounds or optimizing workflow design.
 license: LICENSE
 compatibility: Requires git and the GitHub CLI (gh).
 ---
@@ -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-consolidation-guard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-consolidation-guard
-description: Prove that a consolidation or re-land dropped nothing - compare the result with every original branch or commit, detect lost files that commit pairing cannot see, treat a merge resolution that reverts a file as a finding, ratchet the specification count, and enforce it as a required CI check. Use when folding several pull requests into one branch, re-landing reverted work, restoring commits by cherry-pick, or reviewing such a branch before it merges. Not for an ordinary merge of the base into a feature branch, for pull request descriptions or labels (follow the pull-requests rule), or for general code review (use cratis-code-review).
+description: Use when consolidating branches, re-landing reverted work or checking restored commits for lost changes. Not for ordinary base merges, pull request descriptions or general code review.
 license: LICENSE
 ---
 

package/package/corpus/skills/cratis-engineering-csharp-conventions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-csharp-conventions
-description: Apply the Cratis C# house conventions when writing or reviewing C# in a Cratis repository - formatting, naming, records and primary constructors, nullable handling, XML documentation, custom exceptions, structured logging, dependency injection, and service lifetimes. Use for any "how should this be written" C# style question; defer product API decisions and specification authoring to their focused workflows.
+description: Use when writing or reviewing C# house style in a Cratis repository, including naming, formatting and service lifetimes. Not for product API behavior or specification authoring.
 license: LICENSE
 ---
 

package/package/corpus/skills/cratis-engineering-decision-record/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-decision-record
-description: Consult, author, accept, and supersede decision records in a Cratis repository's decisions/ folder (or the folder in `.cratis/ai.json` `process.decisions.path`). Use before an architectural, contract, scope, or cross-cutting change, when a ruling has been made that later work must obey, or when an accepted decision has to be replaced. Defer product documentation, session handovers, and work-item status to their own workflows.
+description: Use before a significant architectural, contract or cross-cutting change, or when recording or replacing a durable decision. Not for routine implementation approvals, product docs, session handovers or issue status.
 license: LICENSE
 ---
 

package/package/corpus/skills/cratis-engineering-docs-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-docs-authoring
-description: Draft accurate Cratis product or engineering documentation once the reader's goal, owning source, and product evidence are known. Use for tutorials, how-to guides, explanations, and references; use the owning repository's navigation and visual QA workflows for placement and rendering.
+description: Use when drafting a Cratis tutorial, how-to, explanation or reference after its reader, owning page and product evidence are known. Not for locating pages, wiring navigation or visual QA.
 license: LICENSE
 metadata:
   cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"

package/package/corpus/skills/cratis-engineering-effect-boundaries/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-effect-boundaries
-description: Apply the Cratis effect-boundary contract when writing or reviewing code that publishes, persists, generates, propagates, or releases. On those boundaries partial success is failure - no catch-and-continue, no defaulting to success on an unknown outcome. Use when a degraded run could still report success; defer style questions and specification authoring to their own workflows.
+description: Use when publication, persistence, generation or propagation could partially fail while reporting success. Not for ordinary style questions or specification authoring.
 license: LICENSE
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-issue-hygiene
-description: Keep GitHub issues current and reduce unfinished work with a single-writer status block and reasoned disposition. Use when maintaining an issue status block, deciding who may claim an issue, whether to close completed work, or whether to file a necessary follow-up. Not for grouping deliveries (use cratis-engineering-release-trains), review iterations (use cratis-engineering-review-rounds), workflow optimization (use cratis-ci-pipeline-performance), or CI operations (use cratis-engineering-ci-gates).
+description: Use when claiming an issue, maintaining its status block or deciding an authorized closure or necessary follow-up. Not for delivery grouping, review rounds or CI operations.
 license: LICENSE
 compatibility: Requires git and the GitHub CLI (gh).
 ---
@@ -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-engineering-local-cross-repo-verification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-local-cross-repo-verification
-description: Proves lower-layer Cratis fixes in downstream repositories using local packages and images. Use when a lower-layer fix must be proven in a consumer, before the producer PR for a consumer bug, before requesting or waiting on a release, or when reproducing a consumer bug against lower-layer main. Not for single-repo changes, released-version pin bumps, CI changes, or shipping; use the ship-changes prompt for shipping and cratis-release-notes for release text.
+description: Use when a lower-layer Cratis fix needs proof in a downstream consumer before its producer PR or release. Not for single-repository checks, released-version pin bumps or shipping.
 license: LICENSE
 compatibility: Bash and git on macOS or Linux; Windows through WSL. Requires the ecosystem tools used by the selected recipe.
 ---

package/package/corpus/skills/cratis-engineering-regression-cluster/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-regression-cluster
-description: Stop fixing instances when one surface keeps breaking - name the failure class, add the gate that owns it, prove the gate fails, then fix the instance. Use when a third bug, regression, revert or review finding lands on the same screen, endpoint, command, workflow or module, when the same kind of fix keeps being reapplied, or when asked why something keeps breaking. Not for a first or isolated bug (fix it with a regression specification), for proving a consolidation dropped nothing (use cratis-engineering-consolidation-guard), or for a boundary that reports success after failing (use cratis-engineering-effect-boundaries).
+description: Use when a third regression hits the same surface, a fix keeps being reapplied or recurring failures need a shared cause. Not for isolated bugs, consolidation loss checks or false-success effect boundaries.
 license: LICENSE
 ---
 

package/package/corpus/skills/cratis-engineering-release-trains/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-engineering-release-trains
-description: Group related deliveries into one release candidate, fold superseded pull requests, and apply a ship bar before publishing the assembled change. Use when asked to group finished branches, join an open PR, fold superseded PRs, size a candidate, or decide whether the ship bar is met. Not for waiting on checks (use cratis-engineering-ci-gates), planning review rounds (use cratis-engineering-review-rounds), or optimizing workflow performance (use cratis-ci-pipeline-performance).
+description: Use when grouping finished branches into a release candidate, folding superseded PRs or checking the assembled ship bar. Not for CI waiting, review-round scheduling or workflow optimization.
 license: LICENSE
 compatibility: Requires git and the GitHub CLI (gh).
 ---

package/package/corpus/skills/cratis-engineering-review-rounds/NOTICE

@@ -0,0 +1,31 @@
+Cratis portable review-round protocol adaptation
+
+Source: https://github.com/t3dotgg/tstack
+Pinned commit: 7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd
+Adapted portion: skills/sol-loop/SKILL.md review/writer separation, independent
+verification of feedback, explicit completion/cancellation, and delta finding continuity.
+Local modifications: host-neutral provider resolution, existing Cratis report envelopes,
+three-round hard cap, publication authority and full-gate requirements retained.
+The existing Cratis skill and its other content remain under the repository license.
+
+MIT License
+
+Copyright (c) 2026 Theo Browne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.