@cratis/pi 0.0.1

package/skills/cratis-security-review/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: cratis-security-review
+description: Perform a focused security review of changed code in a Cratis application — injection, authentication and authorization, data exposure, secrets, event-sourcing-specific exposure, and the frontend — and report findings by risk. Use when asked for a security review or audit. Do not use to implement authentication and do not report a policy preference as a framework contract.
+license: MIT
+---
+
+# Cratis security review
+
+Event sourcing changes the shape of a security review. A mistake in an ordinary
+application is a bug you fix; a secret written into an append is a fact that
+lives in the log forever and cannot be edited out. The event-sourcing section
+below is the one that is specific to this stack, and it is the one worth reading
+first.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Arc.Chronicle` | `22.10.4` | `[NotAudited]` in `Cratis.Arc.Chronicle.Commands`; the `ARCCHR0009` analyzer |
+| `Cratis.Chronicle` | `16.45.2` | `[PII]`, `[Subject]`, redaction, namespace isolation |
+| `Cratis.Arc.Core` | `22.10.4` | Authorization filters, `CommandResult.Unauthorized` |
+
+Reverify against the owning product repository before asserting a framework
+guarantee this file does not already state.
+
+## Route near misses
+
+- General correctness and maintainability: use `cratis-code-review`.
+- Scalability and resource use: use `cratis-performance-review`.
+- Implementing authentication, authorization or identity: use
+  `cratis-arc-authentication-authorization-and-identity`. This skill reviews;
+  it does not build.
+- Compliance mechanics — `[PII]`, subject resolution, erasure, redaction: use
+  `cratis-chronicle-compliance`.
+
+## Step 1 — Event sourcing: the permanent-record checks
+
+- **Every `[Command]` property holding a secret is marked `[NotAudited]`.** A
+  command's property values are written to the causation of every event it
+  appends, and causation is as permanent as the events. Prefer the marking on
+  the concept type so it travels everywhere the value appears.
+  `ARCCHR0009` catches properties whose *names* read as secrets — so read the
+  properties whose names do not say what they hold, because the analyzer cannot.
+- **Personal data is `[PII]`, not `[NotAudited]`.** They are different
+  mechanisms with different consequences: `[NotAudited]` withholds a value from
+  the causation chain; `[PII]` enrolls it in per-subject encryption and erasure.
+  A password is `[NotAudited]`. An email address is `[PII]`. Neither substitutes
+  for the other.
+- No secret, token, API key or password in an event property or a read model.
+- Event-source ids are generated server-side, never accepted from an untrusted
+  client where the id grants access to a stream.
+- Upcasting and event-type migration logic cannot introduce a property the
+  original contract did not carry.
+- Uniqueness cannot be bypassed by concurrent writes — it is enforced by a
+  Chronicle constraint, not by a read-model pre-check.
+- Cross-tenant writes cannot bypass a constraint that is scoped per namespace.
+
+## Step 2 — Input validation and injection
+
+- Every command property is validated before use — null, empty, range, format.
+- No raw SQL concatenation; parameterized queries or EF Core only.
+- No user-supplied value reaches `Path.Combine`, a `File.*` call, a shell
+  command, or process arguments.
+- No user-supplied value becomes an event-store key without sanitization.
+
+## Step 3 — Authentication and authorization
+
+- Every exposed endpoint is either authorized or explicitly anonymous with a
+  stated reason.
+- Authorization is expressed at the boundary — an attribute, a policy, a command
+  filter — never as an `if` on roles inside `Handle()`.
+- Tenant isolation holds: no cross-namespace data is reachable without
+  authorization.
+- Claims are verified before acting on identity-dependent command data. A client
+  must not be able to assert who it is through a command property.
+- Note that an unauthorized command result maps to HTTP **403**, not 401 — a
+  reviewer reading logs for 401s will miss authorization failures.
+
+## Step 4 — Data exposure
+
+- No personal data is returned to a caller that did not supply it.
+- Query results are scoped to the requesting tenant and user. A query that can
+  return all-tenant data is a finding even when no current caller reaches it.
+- Response payloads carry only fields the client uses. Over-fetching is an
+  exposure surface, not only a performance one.
+- A managed read-model document holds one subject's personal data. Mixing
+  several people's data in one document breaks erasure.
+
+## Step 5 — Secrets and configuration
+
+- No secret in source, in a configuration file, or in a specification fixture.
+- Secrets come from environment variables or a secrets manager.
+- No hard-coded connection string outside test code.
+
+## Step 6 — Frontend
+
+- No user-supplied value in `dangerouslySetInnerHTML`.
+- No token or secret in `localStorage` — use an `httpOnly` cookie or in-memory
+  state.
+- Command payloads carry only the minimum required fields.
+- No client-side access control that is not also enforced server-side. A
+  disabled button is a usability affordance, never a control.
+
+## Step 7 — Report
+
+Open with one line:
+
+> **Security review: No issues / Low-risk findings / Blocking issues found**
+
+Group findings by the section that produced them, and classify each:
+
+| Risk | Meaning |
+| --- | --- |
+| **Critical** | Must be fixed before merge |
+| **Medium** | Should be fixed soon; state what makes it not-critical |
+| **Low** | Fix when convenient |
+
+Close with a per-section summary table, and **name what you did not review** —
+the paths, the surfaces, and the axes out of scope. A security report listing
+only findings reads as a clean bill of health for everything it never opened.
+
+## What breaks
+
+- **A finding is a policy preference in framework clothing.** Which roles exist,
+  which data is sensitive, and which retention applies are the product's calls,
+  not the framework's. State them as policy questions for the owner, not as
+  contracts.
+- **`[NotAudited]` is used for personal data.** The value stays out of causation
+  but is never encrypted and never enrolled in erasure — the opposite of what a
+  subject-rights request needs.
+- **The review assumes the analyzer covered the secrets.** `ARCCHR0009` matches
+  names. A property called `Value` holding an API key passes it silently.
+- **A missing check is reported as "verified".** Unknown is not pass. If a
+  surface could not be reached, say so as `indeterminate` rather than omitting
+  it.
+
+## How it is proven
+
+The build and specifications are green before the report is written; each
+finding cites the file and line; and the report states explicitly which
+surfaces were and were not examined.

package/skills/cratis-specification-by-example/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/skills/cratis-specification-by-example/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: cratis-specification-by-example
+description: Structure and name executable specifications the Cratis way — one behavior per specification, a for_/when_/and_ path that reads as an English sentence, layered given/ contexts, and an explicit decision about what is not worth specifying. Use when deciding how to organize, name, or scope specifications in any language. Do not use for language mechanics; route to the C# or TypeScript specification skill for those.
+license: MIT
+---
+
+# Cratis specification by example
+
+Cratis calls automated tests **specifications**. That is not a vocabulary
+preference — it changes what you write. A test asks "does this code still do
+what it did yesterday?". A specification states what the software promises, in
+the language of the domain, in a form a machine can check. The folder tree is
+the table of contents; the file names are the sentences; the assertions are the
+promises.
+
+This skill is the language-agnostic layer. It settles the questions that are the
+same in C#, TypeScript, and anything else: what to specify, how to name it,
+where to put it, and when to stop.
+
+## Verified product sources
+
+| Source | Version | What it grounds |
+| --- | --- | --- |
+| `Cratis.Specifications` analyzers | `CRSPEC0001`–`CRSPEC0007` | The naming and structure rules below are machine-enforced in C#, not taste |
+
+The seven diagnostics are declared in `Cratis.Specifications.CodeAnalysis.DiagnosticIds`:
+
+| Id | Rule |
+| --- | --- |
+| `CRSPEC0001` | A test method inside a specification must be named `should_*` |
+| `CRSPEC0002` | A file declares at most one specification |
+| `CRSPEC0003` | A test method must not sit on a reusable `given/` context |
+| `CRSPEC0004` | A `should_*` method without a test attribute never runs |
+| `CRSPEC0005` | A lifecycle method must not call its base implementation |
+| `CRSPEC0006` | A specification declaring test methods must be public so the runner finds it |
+| `CRSPEC0007` | The action under test must not sit on a reusable `given/` context |
+
+In a language without those analyzers the same rules hold; the reviewer enforces
+them instead of the compiler. Reverify against the owning product repository
+before claiming behavior for another version.
+
+## Route near misses
+
+- Writing the C# mechanics — the `Specification` base, `Establish`/`Because`,
+  substitutes, assertions: use `cratis-specifications-csharp`.
+- Writing the TypeScript mechanics — `describe`/`it`, Sinon, the Chai `should`
+  interface: use `cratis-specifications-typescript`.
+- Specifying an event-sourced application slice with the in-process scenario
+  family: use `cratis-application-slice-specifications`.
+- Deciding what a command, projection, reducer, or reactor *should do*: that is
+  a modeling question. Settle the behavior first; a specification records a
+  decision, it does not make one.
+
+## Step 1 — State the behavior as a sentence
+
+Before creating a file, say the specification out loud as one English sentence:
+
+> **for** the changeset, **when** adding changes, **and** there are differences,
+> it **should** record them.
+
+Every clause becomes one level of the path. If the sentence does not survive
+being spoken, the specification is not focused enough yet — that is the signal
+to split it, not to write a longer name.
+
+## Step 2 — Build the path from the sentence
+
+```
+for_<SubjectUnderTest>/
+├── given/
+│   ├── all_dependencies            ← substitutes every collaborator
+│   └── a_<subject>                 ← builds the subject, layered on the above
+├── when_<behavior>/                ← a behavior with several outcomes
+│   ├── and_<condition>
+│   ├── with_<state>
+│   └── without_<requirement>
+└── when_<simple_behavior>          ← a single outcome is a single file
+```
+
+- **`for_<Subject>`** names the thing being specified.
+- **`when_<behavior>`** names the action. This is the only place the word
+  **`when`** may appear.
+- **Outcome names** use one of five prepositions: `and_`, `with_`, `without_`,
+  `having_`, `given_`.
+
+**Two `when`s in one path is always wrong.** A file named
+`with_a_registered_migration_when_appending_a_generation_1_event` is two
+sentences pretending to be one. Fold the context into the `when_` folder and let
+the outcomes be flat files:
+
+```
+# Wrong
+when_appending_event_with_migrations/
+└── with_a_registered_migration_when_appending_a_generation_1_event
+
+# Also wrong — a folder level that holds a single file
+when_appending_event_with_migrations/
+└── and_event_is_generation_1/
+    └── with_a_registered_migration
+
+# Correct
+when_appending_event_with_registered_migration/
+├── and_event_is_generation_1
+├── and_event_is_generation_2
+└── and_event_has_default_value
+```
+
+Add a sub-folder under `when_` only when that condition has its own several
+outcomes. One outcome is one flat file.
+
+## Step 3 — One behavior, one specification
+
+Each distinct outcome is its own file. When a specification fails you should
+know from its name alone which promise broke, without reading the diff.
+
+- A file that specifies a whole class is not a specification; it is a test suite
+  wearing the name.
+- Assertions inside one file all describe the *same* outcome from different
+  angles. A second setup means a second file.
+- Optimize for readability over removing duplication. Repeating three lines of
+  setup so a specification is self-contained is a good trade; a shared helper
+  the reader must go and open is not.
+
+## Step 4 — Put the world in `given/`, the action in the specification
+
+A context captures the world *before* the action. Layer them:
+`all_dependencies` substitutes the collaborators, `a_<subject>` builds the
+subject on top of it, and the concrete specification adds only what is unique to
+its case.
+
+- Name a context `a_` or `an_` so it reads as "given an observer, when
+  handling".
+- **The action under test never appears in a context** (`CRSPEC0007`) and
+  **assertions never appear in a context** (`CRSPEC0003`). A context that acts is
+  a specification that several files silently share, and the failure it produces
+  names the wrong subject.
+- Contexts build in layers: `all_dependencies` → `a_reactor_handler` →
+  `when_handling`.
+
+## Step 5 — Decide what not to specify
+
+Specify decisions, transformations, branching rules, and coordination between
+collaborators — the places defects live. Leave alone:
+
+- Auto-properties and properties that return a constructor parameter.
+- Simple delegation that forwards to a collaborator and adds nothing.
+- Logging. It is fragile to specify and worth nothing when it passes.
+- Trivial null checks the type system already enforces.
+
+A name beginning `when_getting_` or `when_returning_` is the tell: that is a
+getter, not a behavior. Delete it rather than maintaining it.
+
+## Step 6 — Make the outcome observable
+
+A specification is only as good as the signal it reads.
+
+- **Assert on the outcome, not the message.** A presentation string is copy;
+  it changes for reasons that have nothing to do with the behavior. Assert on
+  the identity of what failed — an error code, a constraint name, a typed
+  result — never on the sentence shown to a user.
+- **Never wait on the clock.** A sleep before an assertion passes because the
+  machine happened to be fast, and writes today's latency into the suite. Await
+  a completion signal, under a deadline. A timeout turns a hang into a named
+  failure; a sleep turns a race into a coin flip.
+- **Nothing ambient.** The real clock, a random value, the network, shared
+  storage, or an ambient culture makes the outcome depend on something the
+  specification never stated. Inject it.
+- **A specification that cannot fail proves nothing.** If you cannot describe
+  the change that would make it red, it is not specifying anything yet.
+
+## Step 7 — Say what the specification did not cover
+
+Finishing a behavior means naming its unspecified edges, not claiming the
+behavior is proven. A suite that lists only what passed reads as if everything
+was checked. Record the cases you deliberately left out and why — an untested
+edge someone chose is a different thing from one nobody saw.
+
+## Verify
+
+- Every path reads as one English sentence, and `when` appears only in a
+  `when_<behavior>` folder name.
+- Every outcome file name starts with `and_`, `with_`, `without_`, `having_`, or
+  `given_`.
+- One specification per file; one outcome per specification.
+- No action and no assertion sits on a `given/` context.
+- Nothing trivial, delegated, or compiler-verified is specified.
+- No assertion reads a presentation message string.
+- No sleep, bare delay, or poll loop stands in for a completion signal.
+- The suite runs green, and the report names what was not covered.

package/skills/cratis-specifications-csharp/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/skills/cratis-specifications-csharp/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: cratis-specifications-csharp
+description: Write C# specifications with Cratis.Specifications using the Establish/Because/should_ pattern and the for_/when_/and_ folder hierarchy. Use when adding or restructuring C# specs in any Cratis repository, choosing between an isolated unit spec and an in-process scenario spec, or building reusable given/ contexts. Do not use for TypeScript or React specs, and do not use it to decide what a command, projection, or reactor should do.
+license: MIT
+---
+
+# Cratis C# specifications
+
+Specifications are executable documentation. The folder tree reads like a table
+of contents, and each file states one setup, one action, and one or more
+focused assertions.
+
+## Verified product sources
+
+This skill is verified against these exact public releases:
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Specifications` | `4.1.0` | `Specification` base, `Catch.Exception`, `ShouldXxx` assertions |
+| `Cratis.Arc.Testing` | `22.10.4` | `CommandScenario<TCommand>` and `CommandResult` assertions |
+| `Cratis.Chronicle.Testing` | `17.0.0` | `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>` |
+
+Reverify against the owning product repository before claiming support for
+another version. Never translate an assertion or helper name from memory.
+
+## Route near misses
+
+- The specification is TypeScript, React, or a view model: use
+  `cratis-specifications-typescript` instead.
+- The question is what a command, projection, reducer, or reactor *should do*:
+  resolve the behavior first; this skill only specifies already decided
+  behavior.
+- The repository builds a Cratis library rather than an application: stay on the
+  plain `Specification` base in this file and do not reach for the scenario
+  family except to test the very engine that repository provides.
+
+## Step 1 — Choose the specification surface
+
+| Situation | Surface |
+| --- | --- |
+| Isolated class, collaborators can be substituted | `Specification` + NSubstitute |
+| Arc command pipeline (validators, `Provide()`, `Handle()`, appended events) | `CommandScenario<TCommand>` |
+| Chronicle append semantics, constraints, concurrency | `EventScenario` |
+| Projection or reducer state from a sequence of events | `ReadModelScenario<TReadModel>` |
+| Reactor invocation and its side effects | `ReactorScenario<TReactor>` |
+| Host, transport, or real-infrastructure boundary | Out-of-process Chronicle integration specification |
+| Setup shared by many specifications | Reusable context under `given/` |
+
+The plain `Specification` base is the universal foundation and the dominant mode
+in library and framework code. The four scenario helpers are the default for
+event-sourced *application* behavior; read
+[application-scenarios.md](references/application-scenarios.md) before using
+one. Out-of-process integration specifications are an advanced case reserved for
+boundaries the scenario helpers cannot reach — see
+[integration-specs.md](references/integration-specs.md).
+
+Specification projects are named `<Source>.Specs` and run on xUnit.
+
+## Step 2 — Create the folder structure
+
+```
+for_<ClassName>/
+├── given/
+│   ├── all_dependencies.cs       ← substitutes every collaborator
+│   └── a_<system_under_test>.cs  ← builds the SUT, inherits all_dependencies
+├── when_<behavior>/              ← a behavior with multiple outcomes
+│   ├── and_<condition>.cs
+│   └── with_<state>.cs
+└── when_<simple_behavior>.cs     ← a single outcome is a single file
+```
+
+Paths read as English sentences: `for_AuthorService / when_registering /
+and_name_already_exists`. Allowed outcome prefixes are `and_`, `with_`,
+`without_`, `having_`, and `given_`.
+
+**`when` belongs only in a `when_<behavior>` folder name.** A specification file,
+class, or non-`when_` folder must never contain the word `when`. Two "whens" in
+one path is always wrong — fold the context into the `when_` folder name and use
+preposition files for the outcomes.
+
+```
+# Wrong — two whens in the sentence path
+when_appending_event_with_migrations/
+└── with_a_registered_migration_when_appending_a_generation_1_event.cs
+
+# Correct — context in the folder, outcomes are flat files
+when_appending_event_with_registered_migration/
+├── and_event_is_generation_1.cs
+└── and_event_is_generation_2.cs
+```
+
+Add a sub-folder under `when_` only when that condition has its own multiple
+outcomes.
+
+## Step 3 — Write the specification
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace <RootNamespace>.for_<ClassName>;
+
+public class when_<behavior> : Specification
+{
+    <CollaboratorType> _<collaborator>;
+    <ResultType> _result;
+
+    void Establish() => _<collaborator> = <setup>;
+
+    void Because() => _result = <the single action under test>;
+
+    [Fact] void should_<expected_outcome>() => _result.ShouldEqual(<expected>);
+    [Fact] void should_<other_expected_outcome>() => _result.ShouldNotBeEmpty();
+}
+```
+
+- `void Establish()` sets up the world. Each class in an inheritance chain has
+  its own and they run base-first. Never call `base.Establish()`.
+- `void Because()` performs **one** action. It belongs only in a concrete
+  specification, never in a reusable context.
+- `[Fact] void should_*()` carries one assertion. Use expression-body form and
+  leave no blank line between `should_` methods.
+- Fields are `private` in a concrete specification and `protected` in a `given/`
+  context, named `_camelCase`.
+- Any phase may be `async Task`. `void Destroy()` is the optional teardown.
+
+`Cratis.Specifications` discovers `Establish`, `Because`, and `Destroy` by
+convention — there are no attributes on them.
+
+## Step 4 — Extract a reusable context
+
+When several specifications share setup, layer it under `given/`:
+`all_dependencies` substitutes the collaborators, the next context builds the
+system under test, and each specification adds only what is unique.
+
+```csharp
+// for_<ClassName>/given/all_dependencies.cs
+namespace <RootNamespace>.for_<ClassName>.given;
+
+public class all_dependencies : Specification
+{
+    protected <CollaboratorType> _<collaborator>;
+
+    void Establish() => _<collaborator> = Substitute.For<<CollaboratorType>>();
+}
+```
+
+```csharp
+// for_<ClassName>/given/a_<system_under_test>.cs
+namespace <RootNamespace>.for_<ClassName>.given;
+
+public class a_<system_under_test> : all_dependencies
+{
+    protected <ClassName> _<sut>;
+
+    void Establish() => _<sut> = new(_<collaborator>);
+}
+```
+
+Name a context `a_` or `an_` so it reads as "given an observer, when handling".
+Full substitution, assertion, and exception-catching patterns are in
+[csharp-patterns.md](references/csharp-patterns.md).
+
+## Step 5 — Never wait on the clock
+
+A specification never sleeps to let the system under test catch up.
+`Thread.Sleep`, a bare `Task.Delay`, or a `SpinWait` before an assertion passes
+because the machine happened to be fast enough and writes today's latency into
+the suite. Await a signal instead:
+
+| Waiting for | Await |
+| --- | --- |
+| Observers to catch up with an append | `appendResult.WaitForCompletion()` |
+| Client artifacts registered with the kernel | `eventStore.WaitForRegistration()` |
+| An observer's state or position | `WaitTillActive`, `WaitTillSubscribed`, `WaitTillReachesEventSequenceNumber`, `WaitForState` |
+| Anything without a helper | A `SemaphoreSlim` or `TaskCompletionSource` released by the code that observes the event, awaited under a timeout |
+
+A **deadline** is not a sleep: every helper takes a timeout, and a timeout turns
+a hang into a named failure. Sleeping *between* re-checks is a sleep — a poll
+loop is a completion signal that has not been built yet.
+
+Three delays are not waits and stay allowed. Say which one it is in a comment: a
+test double that is slow on purpose so the specification can observe it
+mid-flight, an infrastructure readiness backoff between connect retries, and a
+`Task.Delay(1)` or `Task.Yield()` that widens an interleaving window in a
+concurrency specification.
+
+## Step 6 — Apply the C# conventions
+
+- Common usings come from `GlobalUsings.Specs.cs` (`Xunit`, `NSubstitute`,
+  `Cratis.Specifications`). Do not duplicate them and do not add a using for the
+  namespace of the system under test.
+- Order usings with non-aliased namespaces first, a blank line, then
+  `using <alias> = …` sorted by alias name. Alias a type whose short name
+  collides with a namespace segment, using a domain-meaningful alias rather than
+  a technical `Command`/`Event` suffix.
+- Prefer a concept's own sentinel — `NotSet`, `Empty`, `New()` — over a raw
+  `string.Empty`, `Guid.Empty`, or `0` that implicitly converts. It states intent
+  and survives a sentinel change. Reserve raw primitives for genuinely
+  non-concept values.
+- Every file carries the repository license header.
+
+## What not to specify
+
+- Simple auto-properties and properties that return a constructor parameter.
+- Simple delegation such as `public IEnumerable<Author> All => _list;`.
+- Logging calls and trivial null checks.
+- Anything a specification name starting with `when_getting_` or
+  `when_returning_` would describe — that is a getter, not a behavior.
+
+Specify decisions, transformations, branching business rules, and coordination
+between collaborators. That is where defects hide.
+
+## Verify
+
+- Every specification file states one `Establish`, one `Because`, and one or
+  more `should_` facts.
+- `Because()` appears only in concrete specifications, never in a `given/`
+  context.
+- No path contains `when` outside a `when_<behavior>` folder name.
+- Outcome files use an allowed preposition prefix.
+- Field access modifiers and `_camelCase` naming match the surface.
+- No `Thread.Sleep`, bare `Task.Delay`, or poll loop stands in for a signal; any
+  remaining delay carries a comment naming which allowed case it is.
+- Assertions use the `ShouldXxx` extension methods and never assert on a
+  presentation message string.
+- Nothing trivial or compiler-verified is specified.
+- The file carries the repository license header.
+- The specification project builds and its specifications pass against the
+  verified package versions.