@cratis/pi 0.0.1 → 2.0.2

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

@@ -0,0 +1,138 @@
+---
+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.
+
+## Never rewrite history
+
+**Committed history is append-only. Never rewrite it — under any circumstances, on any branch, including your own.**
+
+These commands are **forbidden** unless the human explicitly asks for that specific command on that specific branch in that specific message:
+
+| Forbidden | Why |
+|---|---|
+| `git rebase` (any form, incl. `-i`, `--onto`, `--autosquash`) | rewrites every replayed commit; the originals become unreachable |
+| `git commit --amend` | replaces the tip commit; the original is unreachable immediately |
+| `git reset --hard`, `git reset` onto an earlier commit | discards commits and, with `--hard`, uncommitted work too |
+| `git push --force`, `git push --force-with-lease`, `git push -f` | destroys the remote's copy — the one backup that survives local loss |
+| `git branch -D` / `git branch -d` on a branch holding unmerged commits | strands those commits with no ref; `git gc` then deletes them |
+| `git checkout`/`git switch` away while another agent's commits sit only on this branch | the commits leave with the branch and the working tree silently reverts |
+| `git filter-branch`, `git filter-repo`, history-rewriting scripts | rewrites the entire history graph |
+| `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.
+
+**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.
+
+### 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.
+- **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.
+- **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.

package/package/corpus/rules/github-actions.md

@@ -0,0 +1,92 @@
+---
+applyTo: ".github/workflows/**"
+paths:
+  - ".github/workflows/**"
+---
+
+# GitHub Actions workflows: capacity, cost, and release discipline
+
+> **Why this rule exists.** On 2026-08-25 the organization's hosted runners starved for
+> most of a working day: every repository ran its scheduled jobs at the same minute,
+> hour-long jobs with no timeout occupied the shared concurrency pool, and a
+> comment-triggered assistant booted a runner for every comment in two repositories.
+> The remediation that followed is encoded here so it stays true.
+
+## The budget you are spending
+
+- The whole organization shares **one hosted-runner concurrency pool** (20 concurrent
+  jobs on the Free plan, 5 for macOS). Every queued job competes with every repository.
+- **Public repositories** run free on hosted runners; **private repositories bill every
+  minute** — Linux 1×, Windows 2×, macOS 10× — against a small monthly allowance.
+- The organization runs its own scale set (`cratis-arc`). Jobs there cost nothing and
+  do not touch the hosted pool.
+
+## Scheduling
+
+- **Never schedule on the top of the hour**, and never copy another repository's cron.
+  `0 6 * * *` in 36 repositories produced a 270-job stampede into 20 slots. Pick a
+  deterministic offset unique to the repository (minute 1–59, spread across 03:00–07:00 UTC).
+- A scheduled workflow that exists to keep coverage (nightly full matrix, health probe)
+  should run the *narrowest* thing that preserves the claim it exists to make.
+- **A scheduled workflow whose subject no longer exists is deleted, not left running.**
+  It still queues into the shared pool every day, and a scheduled no-op is the worst
+  kind: it never fails, so nothing ever draws attention to it. Deleting it is also the
+  only way to stop handing it whatever secrets it was passed — `Cratis/AI` ran a daily
+  package update against a repository with no package manifest of any kind, checking out
+  the full history under an organization-wide write PAT to find nothing to update.
+
+## Every job, always
+
+- **`timeout-minutes` on every job.** The default is 6 hours; one hung job holds a
+  pool slot for all of it. Tiers that work: quick checks 15, builds 30–45,
+  publish/release 60, integration/benchmarks 120.
+- **A `concurrency` group on every pull-request verification workflow** with
+  `cancel-in-progress: true`, keyed `${{ github.workflow }}-${{ github.ref }}`.
+  **Never** cancel-in-progress on publish, release, or deploy workflows — a cancelled
+  half-publish is worse than a queued one.
+
+## Matrices and operating systems
+
+- Run the full OS matrix on `schedule`/`workflow_dispatch`; run **Linux only on pull
+  request syncs**. Windows bills double and macOS ten-fold, and per-PR duplication has
+  to earn that cost with unique signal. (Measured before adopting this: 75 dual-OS runs
+  of one private repository, zero Windows-only failures.)
+- Skip the expensive job entirely for documentation-only changes: a cheap change-detection
+  job (`git diff --name-only HEAD^1 HEAD` on the merge commit) gating the build job.
+
+## Runners
+
+- Private-repository jobs belong on the organization scale set: `runs-on: cratis-arc`,
+  or a repository variable such as `${{ vars.<REPO>_RUNNER || 'ubuntu-latest' }}` so
+  routing changes without a code change.
+- On self-hosted runners, `actions/setup-dotnet` cannot write `/usr/share/dotnet`.
+  Set `DOTNET_INSTALL_DIR: ${{ runner.temp }}/dotnet` on the setup step.
+- **Never** route `pull_request`-triggered jobs of a *public* repository to self-hosted
+  runners — that hands code execution on our infrastructure to any fork.
+
+## Automation that writes back
+
+- A bot that pushes to a branch must **retry with `git pull --rebase`** — the branch
+  moves while the job runs, and a plain push loses the whole run to a non-fast-forward.
+- A bot's pre-push verification build must match the strictest configuration any CI in
+  the organization applies to the same commit (build `Release` when consumers enforce
+  analyzers there). Do not add `[skip ci]` to bot commits as a load optimization: the
+  downstream CI run is the only check that sees the merged result.
+- Comment-triggered agent workflows must gate on the trigger phrase in the job's `if:`
+  (for example `contains(github.event.comment.body, '@claude')`) so a runner only
+  starts when the agent is actually addressed.
+
+## Releases
+
+- A pull request that changes nothing outward-facing — workflow edits, CI configuration,
+  documentation — carries the **`no-release`** label, never `patch`. See
+  [`pull-requests.md`](./pull-requests.md). Merging config-only work under `patch` cut
+  four unintended releases on 2026-08-25.
+- Every repository's release-intent gate must accept `no-release`; a gate that only
+  accepts `major`/`minor`/`patch` forces exactly that mistake.
+
+## In this repository specifically
+
+- Keep one workflow that runs `Source/Verification`, checks harness adapters, and
+  uses `cratis/release-action` for semantic versioning and release decisions.
+- Do not add evidence, provenance, inventory, or generated-catalog gates.

package/package/corpus/rules/glossary.md

@@ -0,0 +1,61 @@
+---
+applyTo: "**/*"
+---
+
+# Cratis Glossary
+
+One precise line per load-bearing term, so the same word means the same thing everywhere. When a rule or skill uses one of these, this is the definition it intends.
+
+## Events & streams
+
+- **Event** — an immutable, past-tense **fact** that something happened; an `[EventType]` record. Never mutated; lives in the log forever.
+- **Event source** — the entity an event stream belongs to (the stream key); identified by an `EventSourceId<T>`.
+- **Event source id** — the strongly-typed identity of an event source (`EventSourceId<T>`). Implicit in the event context — **never** an event payload property.
+- **Event stream** — the ordered events for one event source within an event sequence.
+- **Event sequence** — a named, append-ordered log; `EventSequenceId` (the event **log**, **outbox**, **inbox**).
+- **Event log** — the default event sequence where domain events are appended.
+- **Outbox / inbox** — cross-service event sequences: a producer appends its public contract event to the outbox; a consumer observes the inbox.
+- **EventContext** — metadata traveling with an event (event source id, sequence number, occurred, causation/correlation, subject).
+
+## Read side
+
+- **Read model** — a `[ReadModel]` record holding queryable derived state, built by a projection or reducer; exposes `static` query methods.
+- **Projection** — declares how a read model is built by consuming **events** (model-bound attributes, or fluent `IProjectionFor<T>`); pure events→state, no side effects, never reads other read models.
+- **Reducer** — `IReducerFor<T>`; a "current state + event → next state" read-model builder; the last-resort escape hatch when projections can't express the transition.
+- **Reactor** — `IReactor`; observes events and produces **side effects** (notifications, commands, follow-up events). The "if this then that".
+- **Observer** — Chronicle's umbrella for anything consuming an event sequence (projection, reducer, reactor); carries subscription / replay / **quarantine** state.
+- **Sink** — where a read model is persisted (MongoDB, EF Core).
+- **AutoMap** — Chronicle's on-by-default mapping of matching event→read-model property names; **never call `.AutoMap()`**.
+- **Query** — a `static` method on a `[ReadModel]`; returns derived state, **snapshot** (one-shot) or **observable** (live).
+
+## Write side
+
+- **Command** — a `[Command]` record expressing an imperative **intent**; its public `Handle()` produces event(s) (or a response).
+- **Provide()** — the command method that fetches/computes data after validation/authorization and before `Handle()`; may short-circuit with a `ValidationResult`.
+- **Causation chain** — the ordered links saying how an append came about (root process → command → …), each carrying properties. A command records its **name and its property values** there, so an event says what the command was asked to do; the chain lives in the event log and is as permanent as the events.
+- **Constraint** — `IConstraint`; an **append-time** invariant (uniqueness / concurrency) enforced at the event-store level.
+- **DCB (Dynamic Consistency Boundary)** — enforcing a state-dependent rule **under concurrency** by injecting the read model into `Handle()` and returning `Result<TEvent, ValidationResult>`.
+- **Consistency boundary** — the scope within which an invariant holds atomically (an event source, or the read model a DCB rule inspects).
+- **EventForEventSourceId** — self-describing wrapper to append an event to a **specific** (cross-stream) event source, from a command `Handle()` or from a reactor handler (reactor support has shipped since Chronicle 15.35). It carries the event stream type and id, source type, subject, occurred time, tags and causation, so it is also how a reactor sets those explicitly.
+- **ReactorDelivery** — the identity of one delivery of one event to one reactor partition; declare it as a handler parameter and Chronicle passes it in. Stable across a replay and across recovering a failed partition, so a receipt kept under its `Id` is what makes a side effect survive re-delivery. An identity, not a guarantee — Chronicle does not know whether the effect ran.
+
+## Structure & types
+
+- **Slice** — the vertical unit of one behavior (command + events + projection + read model + component + specs), created/changed/deleted together.
+- **Slice types** — **State Change** (command → events), **State View** (events → read model), **Automation** (events → side effect), **Translation** (events → follow-up events).
+- **Concept** — a `ConceptAs<T>`, a strongly-typed wrapper over a primitive domain value (never raw `Guid`/`string`/`int`).
+- **EventSourceId<T>** — the strongly-typed event-source identity; derive entity identities from this, not `ConceptAs<Guid>`.
+- **Proxy** — the generated TypeScript command/query client, produced from C# on a **Debug** build; carries a `// @generated by Cratis` header and is never hand-edited.
+
+## Compliance & multi-tenancy
+
+- **Subject / `[Subject]`** — the natural person a piece of PII belongs to (for GDPR erasure); defaults to the `EventSourceId<T>` identity.
+- **`[PII]`** — marks an inherently personal value so Chronicle can manage/erase it.
+- **`[NotAudited]`** — an **Arc** marking (`Cratis.Arc.Chronicle.Commands`, not a Chronicle type) for a value that is secret but *not* personal data (password, token, API key), so it is never written to the causation chain. Withholds only; it does not encrypt or enroll the value in erasure the way Chronicle's `[PII]` does.
+- **`[OnceOnly]`** — marks a reactor handler (or the whole reactor class) as non-replayable: Chronicle skips it for every event arriving as part of a **replay** — observer rewind, redaction, revision. Replay-exclusion only, not exactly-once and not per-event-source deduplication; recovering a failed partition re-delivers the event as an ordinary observation and the handler runs again. Use a `ReactorDelivery` receipt for that case.
+- **Namespace / tenant** — Chronicle isolates tenants by **namespace**; each namespace has its own events, observers, and read models.
+
+## Profiles
+
+- **Application profile** — building an app *on* Cratis (event-sourced CQRS, vertical slices, MVVM frontend).
+- **Framework profile** — contributing to a Cratis framework repo *itself* (Arc, Chronicle, Fundamentals, Components — libraries). See `framework.md`.

package/package/corpus/rules/guards-and-fuses.md

@@ -0,0 +1,45 @@
+---
+applyTo: "**/*"
+---
+
+# Guards, scans and fuses
+
+A guard that cannot fail is worse than no guard: it converts "nobody looked" into a green
+check. Every line is tagged **[contract]** (binding) or **[convention]** (the house
+default) per the Three Levels of Authority in [`general.md`](./general.md).
+
+## Non-vacuity
+
+- **[contract] A scan over a possibly-empty population carries a non-vacuity check.**
+  Assert the subject count is what you expect before believing the result, and fail when
+  the population is unexpectedly empty.
+- **[contract] Report the count on success.** "Checked 0 files, found 0 problems" and
+  "checked 412 files, found 0 problems" are different verdicts and must read differently.
+- **[contract] A pattern that matches nothing is a defect in the pattern** until proven
+  otherwise. Prove a matcher still matches by planting a violation; see
+  [`exit-codes-and-wrappers.md`](./exit-codes-and-wrappers.md).
+
+## Allowlists
+
+- **[contract] Every allowlist entry records its reason** — why this subject is exempt,
+  and what would end the exemption.
+- **[contract] Every allowlist entry has a sibling check** that fails when the entry
+  becomes unnecessary, so the list shrinks instead of accumulating forever.
+- **[convention] Prefer an expiry to a permanent exemption.** An entry nobody revisits is
+  a rule quietly deleted.
+
+## Destructive passes
+
+- **[contract] Distinguish "subject set empty" from "qualifying set empty".** Finding no
+  candidates at all is a different situation from finding candidates that none qualified;
+  an unattended pass must refuse to proceed on the first.
+- **[contract] Every unattended destructive pass carries a per-pass fuse** — a maximum
+  number of subjects it may act on in one run, which stops the run rather than trimming
+  the work silently.
+- **[contract] Prepare the inverse before the forward action**, per the Interactive Agent
+  Mutation Protocol in [`general.md`](./general.md). If an exact inverse or a safe
+  compensation cannot be prepared, stop.
+- **[contract] Re-read preconditions immediately before each mutation and stop on drift.**
+  An authorization is for the state that was shown, not for whatever the state became.
+- **[convention] Dry-run output is the review artifact.** If a human cannot tell from the
+  dry run exactly what will change, the dry run is not finished.

package/package/corpus/rules/local-work-artifacts.md

@@ -0,0 +1,33 @@
+---
+applyTo: "**/*"
+---
+
+# Local AI work artifacts belong in `.ai-work/` only
+
+AI-assisted sessions produce working artifacts: plans, handover documents, session
+notes, continuation prompts, status boards, TODO and scratch analyses, research
+dumps, and similar coordination files. These are **work records, not documentation**.
+
+- Create every such artifact inside **`.ai-work/`** at the repository root — never at
+  the repository root itself, never under documentation folders, never anywhere else.
+- `.ai-work/` is listed in `.gitignore` and must stay untracked. Never commit anything
+  inside it, never `git add -f` anything inside it, and never remove the ignore entry.
+- These artifacts must never enter git history or reach GitHub — not on any branch.
+  If you find one tracked in git, move it into `.ai-work/` and remove it from
+  tracking in a dedicated commit.
+- A genuine follow-up that must survive the session is **not** a work record — suggest
+  opening a GitHub issue for it (or open one when asked) so future work is tracked
+  where everyone can see it, instead of leaving a planning file behind.
+- Knowledge that must outlive the session (real documentation, ADRs, operator
+  guides) is written deliberately into the repository's documentation structure
+  through normal review — not left behind as a work record.
+- **A decision log is not a work record.** A decision — a durable choice with a
+  decider and a date — is documentation: it lives in **`decisions/`** (or the
+  repository's documented decisions folder) and is reviewed like any other
+  documentation. A handover may summarize decisions; it never holds the only
+  copy. If a session produced a real decision, land the record in `decisions/`
+  before the session's `.ai-work/` files are discarded.
+- The record's shape (front matter, status and stage values, supersession
+  pointers) is defined by the decision-record skill and the shared vocabulary
+  once this repository carries them; until then use the repository's existing
+  decisions folder and keep decider and date explicit.

package/package/corpus/rules/managing-ai-rules.md

@@ -0,0 +1,40 @@
+---
+applyTo: ".cratis/ai/**,.claude/**,.github/**,.agents/**,.pi/**,.cursor/**,.opencode/**,Source/**"
+paths:
+  - ".cratis/ai/**"
+  - ".claude/**"
+  - ".github/**"
+  - ".agents/**"
+  - ".pi/**"
+  - ".cursor/**"
+  - ".opencode/**"
+  - "Source/**"
+---
+
+# Managing Cratis AI
+
+`.cratis/ai` is the only canonical corpus. Edit rules, agents, prompts, skills,
+hooks, and harness-specific source assets there.
+
+Harness folders are adapters, not copies:
+
+- Claude Code: `.claude`
+- Codex: `.agents` and `AGENTS.md`
+- GitHub Copilot: `.github`
+- Cursor: `.cursor`
+- OpenCode: `.opencode` and `AGENTS.md`
+- Pi: `.pi` and `AGENTS.md`
+
+Run `npm run setup --prefix Source/Harness.Setup` after adding or removing an
+agent, prompt, or harness asset. Run the same command with `-- --check` to verify
+that every adapter points to the canonical corpus.
+
+The managed consumer path is `cratis ai install`. It resolves
+`.cratis/ai.json`, installs selected content, records hashes in
+`.cratis/ai.manifest.json`, and configures every selected harness. Native plugins
+are independent single-harness integrations and do not provide that managed
+lifecycle.
+
+Do not add a second corpus, generated catalog tree, provenance ledger, or
+repository inventory. Quality comes from focused verification in
+`Source/Verification` and review of the source diff.

package/package/corpus/rules/orleans.md

@@ -0,0 +1,50 @@
+---
+applyTo: "**/*.cs"
+profile: framework
+paths:
+  - "**/*.cs"
+---
+
+# Orleans Conventions
+
+> **⚠️ APPLIES ONLY TO PROJECTS USING MICROSOFT ORLEANS**
+> If your project does not reference `Microsoft.Orleans` or any Orleans packages, **ignore this entire file**. These rules are irrelevant outside of Orleans contexts.
+
+These conventions apply to projects that use Microsoft Orleans for distributed grain-based actors.
+
+## General
+
+- Do **not** split Orleans grain interfaces into a separate project. Keep all grain types in the same project as their implementations.
+- Use localhost clustering for local development (`UseLocalhostClustering()`).
+- Do **not** add `[Alias]` attributes to grain interfaces or methods — rely on the default alias generated by Orleans.
+
+## Storage Providers
+
+- Centralize all storage provider names in a single `WellKnownStorageProviders` static class at the root of the project.
+- Reference provider names via the constants in `WellKnownStorageProviders` — never use magic strings.
+- Use `WellKnownStorageProviders.Default` as the name for the primary MongoDB-backed storage provider.
+
+```csharp
+public static class WellKnownStorageProviders
+{
+    public const string Default = "MongoDbGrainStorage";
+}
+```
+
+- Annotate grains with `[StorageProvider(ProviderName = WellKnownStorageProviders.Default)]` when they need persistent state.
+
+## MongoDB Grain Storage
+
+- The `MongoDbGrainStorage<TState>` implementation accepts `IMongoCollection<TState>` as its only dependency — no additional plumbing is required.
+- Register it as a keyed singleton in the Orleans silo builder:
+
+```csharp
+builder.Host.UseOrleans(siloBuilder =>
+{
+    siloBuilder.UseLocalhostClustering();
+    siloBuilder.Services.AddKeyedSingleton<IGrainStorage>(
+        WellKnownStorageProviders.Default,
+        (sp, _) => new MongoDbGrainStorage<MyState>(
+            sp.GetRequiredService<IMongoCollection<MyState>>()));
+});
+```

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

@@ -0,0 +1,78 @@
+---
+applyTo: "**/*"
+---
+
+# How to Do Pull Requests
+
+PR descriptions serve two purposes: they help reviewers understand the change *now*, and they become the release notes that users read *later*. Write them with both audiences in mind.
+
+## Description
+
+- Follow the repository's pull request template (`.github/pull_request_template.md`).
+- Focus on the **Added**, **Changed**, **Fixed**, **Removed**, **Security**, and **Deprecated** sections. Remove sections that are empty — don't leave blank headings.
+- Each bullet should be short, self-contained, and release-note ready.
+- **Write for users of the framework, not for internal developers.** Only include changes that have an impact on anyone using what we build — new APIs, changed behavior, fixed bugs, removed features. Do not list internal implementation details like storage changes, converter updates, gRPC contract internals, or spec additions. If a change is purely internal plumbing, it does not belong in the PR description.
+- Add the associated issue reference at the end of a bullet when there is a real GitHub issue for the change (e.g. `(#351)`). Keep it a bare reference — **no closing keywords** (`Closes #351`, `Fixes #351`) anywhere in the body, because the published release notes are the PR description verbatim. If there is no associated issue, omit the reference entirely. Never use a placeholder like `(#issue)` or leave the example number `(#123)` literally, and never invent a random issue number. **Always verify the issue number read-only using the accepted repository source — never guess or invent a number.** Issue comments and closure are separate notification/effect operations: prepare a bounded post-merge disposition, but do not perform either unless the repository has a current exact operation profile and authority.
+- Include a summary only if there is a cohesive theme across the changes. If you find yourself restating individual bullets in slightly different words, the summary adds no value — remove it.
+- Never include Copilot prompt content in the PR description. Remove any "Original prompt" / coding agent transcript blocks before publishing.
+
+## 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.
+
+## Labels
+
+Confirm the current repository workflow contract before selecting release intent. Label mutations, merge, and any resulting publication/release require separate explicit authorization for their exact effects; a descriptive label does not grant authority.
+
+**Release-intent labels can trigger publication.** Confirm the repository’s current workflows and declared effects; never assume an absent label prevents publication. A proposed semantic label describes impact, not permission to publish.
+
+- 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 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.
+
+### 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.
+
+**Before consolidating open PRs, review each PR’s release intent and workflow effects.** Integration may trigger completion/publication behavior on an absorbed PR. Propose supported non-release intent where appropriate; obtain separate explicit authorization before relabeling or merging exact targets. Never assume consolidation silently updates release intent or authorizes notifications.
+
+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.
+
+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.