@cratis/pi 0.0.1

package/skills/cratis-specifications-csharp/references/application-scenarios.md

@@ -0,0 +1,191 @@
+# In-process scenario specifications
+
+The four scenario helpers exercise the real Arc and Chronicle pipelines
+in-process. They are the default for event-sourced *application* behavior. A
+library or framework repository reaches for one only to test the very engine it
+provides.
+
+Verified against `Cratis.Arc.Testing` `22.10.4` and `Cratis.Chronicle.Testing`
+`17.0.0`.
+
+| Helper | Exercises | Use for |
+| --- | --- | --- |
+| `CommandScenario<TCommand>` | Authorization, validators, `Provide()`, `Handle()`, appended events | State Change behavior |
+| `EventScenario` | Chronicle append semantics without the command pipeline | Constraints, raw sequencing, concurrency |
+| `ReadModelScenario<TReadModel>` | Projection or reducer state from a sequence of events | State View behavior |
+| `ReactorScenario<TReactor>` | Reactor invocation and its side effects | Automation and Translation behavior |
+
+Wrap every scenario specification file in `#if DEBUG … #endif` so specification
+code compiles only in Debug.
+
+## `CommandScenario<TCommand>`
+
+```csharp
+#if DEBUG
+namespace <RootNamespace>.<Feature>.when_<behavior>;
+
+public class and_<condition> : Specification
+{
+    readonly CommandScenario<<CommandType>> _scenario = new();
+    readonly <IdentityType> _id = <IdentityType>.New();
+    CommandResult _result;
+
+    async Task Because() =>
+        _result = await _scenario.Execute(new <CommandType>(_id, <arguments>));
+
+    [Fact] void should_succeed() => _result.ShouldBeSuccessful();
+
+    [Fact] async Task should_append_<event>() =>
+        await _scenario.ShouldHaveAppendedEvent<<CommandType>, <EventType>>(
+            _id, appended => appended.<Property> == <expected>);
+}
+#endif
+```
+
+`CommandScenario<TCommand>` itself exposes exactly `Services`, `Context`,
+`Execute`, and `Validate`. Everything else — seeding, the event log, and the
+assertions — arrives as extension members from `Cratis.Arc.Chronicle.Testing`.
+
+- **Event assertions** are extension methods keyed by command *and* event type:
+  `ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId)`, its
+  `(eventSourceId, Func<TEvent, bool> predicate)` overload, and
+  `ShouldHaveTailSequenceNumber<TCommand>(…)`. They return `Task`, so the fact is
+  `async Task`.
+- **`CommandResult` assertions** come from `Cratis.Arc.Testing.Commands` and
+  throw `CommandResultAssertionException` on failure: `ShouldBeSuccessful()`
+  (authorized, valid, no exceptions), `ShouldNotBeSuccessful()`,
+  `ShouldBeValid()` (validation only — it does not check authorization or
+  exceptions), `ShouldHaveValidationErrors()`,
+  `ShouldHaveValidationErrorFor(message)`, `ShouldBeAuthorized()`,
+  `ShouldNotBeAuthorized()`, `ShouldHaveExceptions()`,
+  `ShouldNotHaveExceptions()`.
+- **Seed prior state through `Given`.** With `Cratis.Arc.Chronicle.Testing`
+  referenced, a command scenario carries a Chronicle-backed `Given` builder as an
+  extension member, alongside `EventScenario`, `EventLog`, `EventSequence` and
+  `AppendedEvents`. `Given.ForEventSource(id).Events(…)` seeds the events an
+  injected read model is then materialized from by its own projection or
+  reducer; `Given.ForEventSource(id).ReadModel(instance)` pins a specific
+  read-model value instead. Both return `void`. Prefer seeding events — it
+  exercises the projection production depends on, so the specification cannot
+  pass against a read-model shape the projection never produces.
+- **Validator and `Provide()` dependencies** are registered in
+  `_scenario.Services`; the concrete validator is discovered automatically.
+
+### Unhappy paths assert twice
+
+```csharp
+[Fact] void should_not_succeed() => _result.ShouldNotBeSuccessful();
+[Fact] void should_have_validation_errors() => _result.ShouldHaveValidationErrors();
+```
+
+`ShouldNotBeSuccessful()` alone cannot distinguish a validation rejection from
+an unhandled exception, so both facts are required. Authorization failures are
+different: an unauthorized result carries **no** validation errors, so assert
+`ShouldNotBeAuthorized()` instead. Adding an authorization attribute to an
+existing command therefore breaks both its happy-path and its validation-failure
+specifications — switch those assertions rather than patching around them.
+
+Never assert on a message string.
+
+> **Validator state can be order-sensitive.** The command-scenario pipeline can
+> cache enough state that injected-validator branches depend on execution order
+> when xUnit runs classes in parallel. Use `CommandScenario` for the valid path,
+> test rejected state variants by instantiating the validator directly, and only
+> for that case put the command's specifications in a small xUnit `[Collection]`.
+
+## `EventScenario`
+
+```csharp
+readonly EventScenario _scenario = new();
+IAppendResult _result;
+
+async Task Establish() =>
+    await _scenario.Given.ForEventSource(<IdentityType>.New())
+        .Events(new <EventType>(<arguments>));
+
+async Task Because() =>
+    _result = await _scenario.EventLog.Append(
+        <IdentityType>.New(), new <EventType>(<arguments>));
+
+[Fact] void should_fail() => _result.ShouldBeFailed();
+
+[Fact] void should_violate_<constraint>() =>
+    _result.ShouldHaveConstraintViolationFor(<ConstraintNames>.<Name>);
+```
+
+`IAppendResult` assertions throw `AppendResultAssertionException`:
+`ShouldBeSuccessful()`, `ShouldBeFailed()`, `ShouldHaveConstraintViolations()`
+and `ShouldNotHaveConstraintViolations()`,
+`ShouldHaveConstraintViolationFor(name)`,
+`ShouldHaveConcurrencyViolations()` and its negation, `ShouldHaveErrors()` and
+its negation. Assert the constraint **name**, never the message.
+
+⚠️ `EventScenario` wires a no-op concurrency-scope strategy, so a concurrency
+violation can never occur inside it. `ShouldHaveConcurrencyViolations()` cannot
+pass there and its negation passes vacuously — specify concurrency against the
+real kernel with an out-of-process integration specification instead.
+
+## `ReadModelScenario<TReadModel>`
+
+```csharp
+ReadModelScenario<<ReadModelType>> _scenario = null!;
+
+void Establish() => _scenario = new();
+
+async Task Because() =>
+    await _scenario.Given.ForEventSource(_id)
+        .Events(new <EventType>(<arguments>), new <OtherEventType>());
+
+[Fact] void should_<expected_state>() =>
+    Assert.True(_scenario.Instance!.<Property>);
+```
+
+The helper auto-detects a model-bound projection, a fluent projection, or a
+reducer. Use the named-parameter constructor when services or initial state are
+needed: `new ReadModelScenario<<ReadModelType>>(initialState: null,
+serviceProvider: services)`. Pre-seed a keyed read model with
+`Given.ForEventSourceId(id).ReadModel(instance)` for code that calls
+`IReadModels.GetInstanceById`. Cross-stream projections are supported — seed each
+contributing stream with its own `Given.ForEventSource(…)`.
+
+To bridge read models into a command scenario, build a focused
+`ReadModelScenario<T>`, seed it, then register its read models into the command
+scenario with `_scenario.Services.AddSingleton(readModelScenario.ReadModels)`.
+For non-key searches, register a lookup double in the scenario services instead.
+
+Do not pre-emptively skip a read-model assertion. Assume scalar concept, enum,
+and identifier properties populate; if one does not, investigate the projection.
+Skip only on a reproduced harness gap, and put the specific reason in the skip
+message.
+
+## `ReactorScenario<TReactor>`
+
+```csharp
+void Establish()
+{
+    _<collaborator> = Substitute.For<<CollaboratorType>>();
+    _scenario = new(new ServiceCollection()
+        .AddSingleton(_<collaborator>)
+        .BuildServiceProvider());
+}
+
+async Task Because() =>
+    await _scenario.Given.ForEventSource(_id).Events(new <EventType>(<arguments>));
+
+[Fact] async Task should_<side_effect>() =>
+    await _<collaborator>.Received(1).<Method>(<expected>);
+```
+
+Construct with an `IServiceProvider` of substituted collaborators and assert on
+those substitutes after `Given` fires the events.
+
+## Application conventions
+
+- **Use a per-specification value for anything under a uniqueness check** — a
+  fresh `Guid`, or a truncated `Guid.NewGuid().ToString("N")[..9]`. Hardcoded
+  values cause order-dependent flakes. Do not add `[Collection(…)]` to work
+  around a collision; that is the wrong fix here.
+- **Sequence numbers are zero-based.** The first event is `0`, the tail of two
+  events is `1`. The tail after a single append is `0`, never `1`.
+- A behavior covering several subjects groups its specifications under
+  `<Slice>/for_<Subject>/when_<behavior>/`.

package/skills/cratis-specifications-csharp/references/csharp-patterns.md

@@ -0,0 +1,142 @@
+# C# specification patterns
+
+Detail for the plain `Cratis.Specifications` surface: phases, substitution,
+assertions, and exception capture. Verified against `Cratis.Specifications`
+`4.1.0` and NSubstitute as consumed by that package.
+
+## Phases
+
+| Method | Purpose | Notes |
+| --- | --- | --- |
+| `void Establish()` | Setup, before `Because()` | One per class in the chain, run base-first. Never call `base.Establish()` |
+| `void Because()` | The single action under test | Only in a concrete specification, never in a `given/` context |
+| `[Fact] void should_*()` | One assertion per fact | Expression-body form, no blank lines between facts |
+| `void Destroy()` | Teardown after each specification | Optional |
+
+Every phase may be `async Task`.
+
+## Layered contexts
+
+```csharp
+// given/all_dependencies.cs — substitute every collaborator
+public class all_dependencies : Specification
+{
+    protected <CollaboratorType> _<collaborator>;
+    protected <OtherCollaboratorType> _<otherCollaborator>;
+
+    void Establish()
+    {
+        _<collaborator> = Substitute.For<<CollaboratorType>>();
+        _<otherCollaborator> = Substitute.For<<OtherCollaboratorType>>();
+    }
+}
+
+// given/a_<system_under_test>.cs — build the system under test
+public class a_<system_under_test> : all_dependencies
+{
+    protected <ClassName> _<sut>;
+
+    void Establish() => _<sut> = new(_<collaborator>, _<otherCollaborator>);
+}
+
+// when_<behavior>/and_<condition>.cs — the concrete specification
+public class and_<condition> : given.a_<system_under_test>
+{
+    void Because() => _<sut>.<Action>(<input>);
+
+    [Fact] void should_<expected_outcome>() =>
+        _<collaborator>.Received(1).<Method>(Arg.Any<<ArgumentType>>());
+}
+```
+
+A context captures the world as it exists *before* the action. It never
+contains the action itself.
+
+## Substitution patterns
+
+```csharp
+// Create
+_<collaborator> = Substitute.For<<CollaboratorType>>();
+
+// Return values
+_<collaborator>.<Method>(Arg.Any<string>()).Returns(<value>);
+_<collaborator>.<AsyncMethod>(Arg.Any<int>()).Returns(Task.FromResult(<value>));
+
+// Argument matchers
+Arg.Is<<RequestType>>(request => request.Id == _expectedId)
+
+// Verify
+_<collaborator>.Received(1).<Method>(Arg.Any<string>());
+_<collaborator>.DidNotReceive().<OtherMethod>(Arg.Any<int>());
+
+// Capture an argument
+_<collaborator>
+    .When(collaborator => collaborator.<Method>(Arg.Any<<ArgumentType>>()))
+    .Do(call => _captured = call.Arg<<ArgumentType>>());
+
+// Throw from a substitute
+_<collaborator>.<Method>(Arg.Any<<ArgumentType>>())
+    .Throws(new <ExceptionType>());
+```
+
+## Assertion extension methods
+
+From `Cratis.Specifications`:
+
+| Method | Example |
+| --- | --- |
+| `.ShouldEqual(expected)` | `_result.ShouldEqual(<expected>)` |
+| `.ShouldBeTrue()` / `.ShouldBeFalse()` | `_flag.ShouldBeTrue()` |
+| `.ShouldBeNull()` / `.ShouldNotBeNull()` | `_error.ShouldBeNull()` |
+| `.ShouldBeEmpty()` / `.ShouldNotBeEmpty()` | `_items.ShouldBeEmpty()` |
+| `.ShouldContain(item)` / `.ShouldNotContain(item)` | `_items.ShouldContain(<expected>)` |
+| `.ShouldContainOnly(items)` | `_items.ShouldContainOnly(<expectedItems>)` |
+| `.ShouldBeOfExactType<T>()` | `_event.ShouldBeOfExactType<<EventType>>()` |
+| `.ShouldBeGreaterThan(n)` / `.ShouldBeLessThan(n)` | `_count.ShouldBeGreaterThan(0)` |
+
+Assert on values and types. Never assert on a presentation message string — it
+is text, not behavior.
+
+## Catching exceptions
+
+```csharp
+Exception? _error;
+
+async Task Because() => _error = await Catch.Exception(_<sut>.<Action>);
+
+[Fact] void should_fail() => _error.ShouldNotBeNull();
+[Fact] void should_fail_with_<reason>() =>
+    _error.ShouldBeOfExactType<<ExceptionType>>();
+```
+
+Use `Catch.Exception` rather than a `try`/`catch` in `Because()`; the captured
+exception is the outcome the facts assert on.
+
+## Usings
+
+`GlobalUsings.Specs.cs` supplies `Xunit`, `NSubstitute`, and
+`Cratis.Specifications`. Do not repeat them per file, and do not add a using for
+the namespace of the system under test.
+
+Order non-aliased namespaces first, then a blank line, then
+`using <alias> = …` sorted by alias name. Alias a type whose short name collides
+with a namespace segment, choosing a domain-meaningful alias rather than a
+technical `Command`, `Event`, or `Component` suffix.
+
+## One outcome per file
+
+```
+# Single outcome — one file
+for_<ClassName>/when_<behavior>.cs
+
+# Multiple outcomes — a folder
+for_<ClassName>/when_<behavior>/
+    and_<condition>.cs
+    and_<other_condition>.cs
+    with_<state>.cs
+    without_<requirement>.cs
+```
+
+Allowed prefixes: `and_`, `with_`, `without_`, `having_`, `given_`. Each
+distinct outcome is its own file, so a failure names the outcome that broke
+without reading a multi-assertion file.

package/skills/cratis-specifications-csharp/references/integration-specs.md

@@ -0,0 +1,126 @@
+# Out-of-process Chronicle integration specifications
+
+Reserve these for the host, transport, serialization, or real-infrastructure
+boundary the in-process scenario helpers cannot reach. They exercise a complete
+behavior — HTTP request through command handling, append, constraint checking,
+and projection — against a real Chronicle event store.
+
+They live under `when_<behavior>/` **inside the behavior's own folder**, not in a
+`for_<Type>/` unit folder: there is no isolated unit, the whole slice is under
+test. Never mix unit and integration specifications in one folder.
+
+Verified against `Cratis.Chronicle.Testing` `17.0.0`.
+
+## Structure
+
+```csharp
+using context = <RootNamespace>.<Feature>.when_<behavior>.and_<condition>.context;
+
+namespace <RootNamespace>.<Feature>.when_<behavior>;
+
+[Collection(ChronicleCollection.Name)]
+public class and_<condition>(context context) : Given<context>(context)
+{
+    public class context(ChronicleOutOfProcessFixture fixture)
+        : given.an_http_client(fixture)
+    {
+        public CommandResult<<ResponseType>>? Result;
+
+        async Task Because() =>
+            Result = await Client.ExecuteCommand<<CommandType>, <ResponseType>>(
+                "<route>", new <CommandType>(<arguments>));
+    }
+
+    [Fact] void should_succeed() => Context.Result!.IsSuccess.ShouldBeTrue();
+
+    [Fact] void should_append_one_event() =>
+        Context.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
+
+    [Fact] void should_append_<event>() =>
+        Context.ShouldHaveAppendedEvent<<EventType>>(
+            EventSequenceNumber.First,
+            Context.Result!.Response,
+            appended => appended.<Property>.Value.ShouldEqual(<expected>));
+}
+```
+
+## Seeding preconditions
+
+Append events in `async Task Establish()` before `Because()` runs:
+
+```csharp
+public class context(ChronicleOutOfProcessFixture fixture)
+    : given.an_http_client(fixture)
+{
+    public const string <ExistingValue> = "<value>";
+    public CommandResult<object>? Result;
+
+    async Task Establish() =>
+        await EventStore.EventLog.Append(
+            <IdentityType>.New(), new <EventType>(<ExistingValue>));
+
+    async Task Because() =>
+        Result = await Client.ExecuteCommand<<CommandType>>(
+            "<route>", new <CommandType>(<ExistingValue>));
+}
+```
+
+```csharp
+[Fact] void should_not_succeed() => Context.Result!.IsSuccess.ShouldBeFalse();
+
+[Fact] void should_not_append_further_events() =>
+    Context.ShouldHaveTailSequenceNumber(EventSequenceNumber.First);
+```
+
+## Command execution overloads
+
+```csharp
+// No typed response — returns CommandResult<object>?
+Result = await Client.ExecuteCommand<<CommandType>>(route, command);
+
+// Typed response — returns CommandResult<TResult>?
+Result = await Client.ExecuteCommand<<CommandType>, <ResponseType>>(route, command);
+```
+
+## Assertion helpers
+
+| Helper | Verifies |
+| --- | --- |
+| `Context.Result!.IsSuccess.ShouldBeTrue()` | The command succeeded |
+| `Context.Result!.IsSuccess.ShouldBeFalse()` | The command failed |
+| `Context.ShouldHaveTailSequenceNumber(EventSequenceNumber.First)` | The log holds exactly one event |
+| `Context.ShouldHaveTailSequenceNumber(n)` | The log tail is at sequence `n` |
+| `Context.ShouldHaveAppendedEvent<TEvent>(seq, eventSourceId, validator)` | A specific event was appended with the expected values |
+
+Sequence numbers are zero-based: `EventSequenceNumber.First` is `0`, so the tail
+after a single append is `0`.
+
+## Asynchronous follow-ups
+
+When a reactor fires after the command and appends further events, collect them
+rather than sleeping. Start the collector **before** the triggering action:
+
+```csharp
+_collector = StartCollectingAppends();
+// … perform the action …
+await _collector.WaitForCount(2, TimeSpan.FromSeconds(10));
+
+[Fact] void should_append_<event>() =>
+    _collector.ShouldHaveEvent<<EventType>>(appended => appended.<Property> == <expected>);
+
+void Destroy() => _collector.Dispose();
+```
+
+`IEventAppendCollection` is part of the Chronicle testing API. The timeout is a
+deadline, not a sleep — it turns a hang into a named failure.
+
+## Rules
+
+- `context` is an inner `public class` inheriting `given.an_http_client(fixture)`.
+- Add the `using context = <full.namespace>.context;` alias at the top of the
+  file.
+- `[Collection(ChronicleCollection.Name)]` goes on the outer class and is
+  required for isolation.
+- `Establish` seeds preconditions; `Because` performs the action under test.
+- Declare `Result` nullable.
+- The outer class receives `context` through xUnit constructor injection.

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

@@ -0,0 +1,202 @@
+---
+name: cratis-specifications-typescript
+description: Write TypeScript specifications in the Cratis BDD style using the given() helper, reusable context classes, Sinon stubbing, and the Chai .should fluent interface. Use when adding or restructuring TypeScript specifications, building a given/ context class, or laying out a for_/when_ specification folder. Do not use for C# specifications, and do not use it to decide what the code under specification should do.
+license: MIT
+---
+
+# Cratis TypeScript specifications
+
+Specifications describe behavior, not implementation. The `given()` helper and
+its context class are the TypeScript counterpart of the C# `Specification`
+base: setup is separated from the action, and each `it()` verifies one outcome.
+
+## Verified product sources
+
+This skill is verified against the frameworks these specifications run on:
+
+| Framework | Role |
+| --- | --- |
+| Vitest | Test runner (`yarn test` from the package root) |
+| Mocha-style structure | `describe`, `it`, `beforeEach`, `afterEach` |
+| Chai | Assertions, always through the `.should` fluent interface |
+| Sinon | Stubbing and call verification |
+
+The `given()` helper is supplied by the Cratis TypeScript package under
+specification and is imported from that package root. Reverify the helper's
+location and signature against the owning repository before relying on a
+different import path.
+
+## Route near misses
+
+- The specification is C#: use `cratis-specifications-csharp` instead.
+- The subject is an application view model or React component rather than a
+  Cratis TypeScript package: the plain `describe`/`beforeEach` frontend style
+  applies, not the `given()` helper in this skill.
+- The question is what the code under specification *should do*: resolve the
+  behavior first; this skill only specifies already decided behavior.
+
+## Step 1 — Create the folder structure
+
+Specifications live alongside the source they describe:
+
+```
+for_<ClassName>/
+├── given/
+│   └── a_<system_under_test>.ts   ← reusable context class
+├── when_<behavior>/               ← a behavior with multiple outcomes
+│   ├── with_<condition>.ts
+│   ├── without_<condition>.ts
+│   └── and_<condition>.ts
+└── when_<simple_behavior>.ts      ← a single outcome is a single file
+```
+
+Paths read as English sentences. Allowed outcome prefixes are `and_`, `with_`,
+`without_`, `having_`, and `given_`.
+
+**`when` belongs only in a `when_<behavior>` folder name.** A specification file
+or non-`when_` folder must never contain the word `when`. Fold the context into
+the `when_` folder name and use preposition files for the outcomes. Add a
+sub-folder under `when_` only when that condition has its own multiple outcomes.
+
+## Step 2 — Write a reusable context class
+
+```ts
+// for_<ClassName>/given/a_<system_under_test>.ts
+import sinon from 'sinon';
+import { <ClassName> } from '../../../<ClassName>';
+
+export class a_<system_under_test> {
+    <collaborator>: sinon.StubbedInstance<<CollaboratorType>>;
+    <sut>: <ClassName>;
+
+    constructor() {
+        this.<collaborator> = sinon.createStubInstance(<CollaboratorClass>);
+        this.<collaborator>.<method>.returns(<default>);
+        this.<sut> = new <ClassName>(this.<collaborator>);
+    }
+}
+```
+
+Context properties are **public** — the specification reads them through the
+`context` parameter. This differs from C#, where `given/` fields are
+`protected`. Name the class `a_` or `an_` so it reads as "given a service, when
+registering".
+
+A context captures the world as it exists *before* the action. Never put the
+action under specification in a context.
+
+## Step 3 — Write the specification
+
+```ts
+// for_<ClassName>/when_<behavior>/with_<condition>.ts
+import { a_<system_under_test> } from '../given/a_<system_under_test>';
+import { given } from '../../given';
+
+describe('when <behavior> with <condition>', given(a_<system_under_test>, context => {
+    let result: <ResultType>;
+
+    beforeEach(async () => {
+        result = await context.<sut>.<action>(<input>);
+    });
+
+    it('should <expected outcome>', () => {
+        result.should.equal(<expected>);
+    });
+
+    it('should <other expected outcome>', () => {
+        context.<collaborator>.<method>.calledOnce.should.be.true;
+    });
+}));
+```
+
+`given()` instantiates the context class per specification so setup stays
+isolated. `beforeEach` performs the single action under specification; each
+`it()` asserts one outcome.
+
+## Step 4 — Skip the context when nothing is shared
+
+A behavior with no shared setup needs no context class:
+
+```ts
+describe('when <behavior>', () => {
+    let result: <ResultType>;
+
+    beforeEach(() => {
+        result = <TypeUnderSpecification>.<action>(<input>);
+    });
+
+    it('should <expected outcome>', () => {
+        result.<property>.should.equal(<expected>);
+    });
+});
+```
+
+## Step 5 — Assert with the `.should` fluent interface
+
+**Always use `.should`. Never use `expect()`.** The fluent style reads as a
+sentence and matches the rest of the corpus.
+
+```ts
+value.should.equal(<expected>);
+value.should.deep.equal(<expectedObject>);
+flag.should.be.true;
+value.should.be.null;
+value.should.not.be.undefined;
+items.should.contain(<expected>);
+items.should.have.lengthOf(<count>);
+items.should.be.empty;
+value.should.be.instanceOf(<Type>);
+(() => <throwingCall>()).should.throw(<ErrorType>);
+```
+
+Full Sinon and Chai detail is in
+[typescript-patterns.md](references/typescript-patterns.md).
+
+## Step 6 — Apply the naming conventions
+
+| Element | Convention | Example |
+| --- | --- | --- |
+| `describe()` text | Natural-language sentence | `'when registering with a valid name'` |
+| `it()` text | Starts with "should", **uses spaces** | `'should append an event'` |
+| Context class | `a_` or `an_` prefix | `an_author_service` |
+| Specification file | Preposition prefix | `with_valid_name.ts` |
+
+Use spaces in `it()` descriptions, never underscores — they appear in runner
+output as human-readable sentences. This is the deliberate difference from the C#
+`should_` method naming.
+
+## Step 7 — Keep one behavior per file
+
+Do not mix orthogonal behaviors in one specification. Separate folders per
+behavior keep failures precise:
+
+```
+when_items_are_added_as_delta/and_item_is_identified_by_a_guid.ts
+when_items_are_removed_as_delta/and_item_is_identified_by_a_guid.ts
+```
+
+A single file validating both add-delta and remove-delta behavior tangles
+unrelated outcomes and hides which one broke.
+
+## What not to specify
+
+- Simple property getters and setters.
+- Properties that return a constructor parameter directly.
+- Trivial delegation.
+- Anything a `describe` beginning "when getting" or "when returning" would
+  describe — that is a getter, not a behavior.
+
+## Verify
+
+- Each specification file states one `describe`, one action in `beforeEach`, and
+  one or more single-outcome `it()` assertions.
+- No path contains `when` outside a `when_<behavior>` folder name.
+- Outcome files use an allowed preposition prefix.
+- Context classes carry public properties, are named `a_`/`an_`, and contain no
+  action under specification.
+- Every assertion uses `.should`; no `expect()` appears.
+- `it()` descriptions start with "should" and use spaces.
+- Stubs are restored between specifications where Sinon state would otherwise
+  leak.
+- Nothing trivial is specified.
+- `yarn test` passes from the package root.