@cratis/pi 0.0.1 → 2.0.1

package/package/corpus/hooks/README.md

@@ -0,0 +1,434 @@
+# Hooks — enforcement, not persuasion
+
+Everything else in `.cratis/ai/` is text an agent may or may not follow. The files here are the part
+that runs. They convert the mechanically-checkable Cratis invariants into deterministic checks
+that fire whether or not the model remembered the rule.
+
+Three layers:
+
+| Layer | Event | Script | Cost | Effect |
+|---|---|---|---|---|
+| Pattern pass | `PostToolUse` on a write | `scripts/cratis-pattern-scan.sh` | zero tokens until a match | appends a one-line reminder to context, never blocks |
+| Hard block | `PreToolUse` on a write | `scripts/cratis-guard-writes.sh` | zero | exits **2** — the write does not happen |
+| Quality gate | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
+
+The Claude Code wiring that fires them is tracked here, in
+[`settings.template.json`](./settings.template.json). Claude reads `.claude/settings.json`, which is
+per-machine and gitignored, so activate the hooks by copying the template once:
+
+```bash
+cp .cratis/ai/hooks/settings.template.json .claude/settings.json
+```
+
+If you already have a `.claude/settings.json`, merge the template's `hooks` block into it rather
+than overwriting — the rest of that file is yours. Re-copy after the template changes; the copy is
+not a symlink, so it does not update itself. **Edit the template, never the copy**: `.cratis/ai/` is the
+source of truth (see [`../rules/managing-ai-rules.md`](../rules/managing-ai-rules.md)), and
+`scripts/validate-ai-setup.sh` checks the template against the script names this page documents.
+
+The markdown files in this folder (`agent-stop.md`, `pre-commit.md`) remain *lifecycle guidance* —
+they describe what a hook should do for tools that have no wiring yet.
+
+> Hooks are the one surface with no folder adapter: Claude reads `.claude/settings.json`,
+> Copilot would read `.github/hooks/*.json`. Only the Claude wiring exists today.
+
+## What is enforced
+
+Rule numbers refer to the numbered list in [`../rules/general.md`](../rules/general.md).
+
+**Blocked outright** (`PreToolUse`, exit 2):
+
+- Editing a file whose header marks it as Cratis-generated output — rule 15 `[contract]`
+- Writing content that opens with such a header (hand-authoring a "generated" proxy)
+- `Directory.Packages.props`, `global.json`, `NuGet.config`, `yarn.lock`, `package-lock.json`,
+  `pnpm-lock.yaml`, `packages.lock.json` — the Source-of-Truth Discipline rule
+- `.env`, `.env.*`, `*.env` — secrets
+
+The generated-file check is anchored: the marker must be a comment opener at the start of one of
+the first five lines. A rule file or a document that merely *mentions* the marker is not blocked.
+
+**Flagged** (`PostToolUse`, exit 0 + context):
+
+| Pattern id | Rule | Detects |
+|---|---|---|
+| `cratis-automap-call` | 10 `[contract]` | `.AutoMap()` in a file that never calls `.NoAutoMap()` |
+| `cratis-ieventlog-in-handle` | 14 `[contract]` | `IEventLog` in a `Handle(` signature, wrapping across up to 5 lines |
+| `cratis-nullable-event-property` | 6 `[contract]` | a nullable property inside a type declared with `[EventType]` |
+| `cratis-route-on-readmodel` | 12 `[contract]` | `[Route(` inside a type declared with `[ReadModel]` |
+| `cratis-controller-base` | 1 `[contract]` | `: ControllerBase` in a file that imports `Microsoft.AspNetCore.Mvc` |
+| `cratis-primereact-dialog-import` | 16 `[convention]` | `from 'primereact/dialog'` |
+
+The two `within_type_attribute` patterns are not line greps — the scanner tracks C# attribute
+blocks and type scope (positional record, multi-line declaration, or braced body), so a nullable
+property is only reported when it really sits inside an `[EventType]`.
+
+**Gated** (`Stop`, exit 2): the app-pinned commands from the Quality Gates table in
+`general.md` and the steps in [`agent-stop.md`](./agent-stop.md) — Debug build, specs, Release
+build (with `-p:CratisProxiesOutputPath=` per `general.md`, so the proxy generator does not
+re-run and touch already-correct generated files), frontend lint / compile / compile-specs /
+test, and `validate-ai-setup.sh` for corpus changes.
+
+## The corpus validator
+
+`scripts/validate-ai-setup.sh` sits outside the three layers: it validates `.cratis/ai/` itself, and both
+the `Stop` gate and the `ai-corpus` CI job run it. Structural, adapter and Codex checks are
+**fatal**; the content drift guards **warn**.
+
+### Package subpath existence — `scripts/validate-package-subpaths.sh` (warn)
+
+Every other drift guard asserts that a string should *not* appear. This one is the other direction,
+and the only guard that knows what a package is. It extracts each `@cratis/<pkg>/<subpath>` the
+corpus names — fenced blocks, inline spans and table cells alike — from `.cratis/ai/rules`, `.cratis/ai/skills`,
+`.cratis/ai/agents` and `.cratis/ai/prompts`, then resolves it against the `exports` map of the package installed
+in `node_modules`. The exports map is exact and machine-readable, so a miss is a genuine miss.
+`.cratis/ai/hooks` is deliberately *not* one of the default roots — this page names bogus subpaths as
+examples, and a guard that reports its own documentation is a guard people switch off.
+
+It exists because nothing in the repository could catch documenting
+`@cratis/components/Notifications` (a subpath that first ships in **3.0.0**) while the pin is
+**2.6.1**. A prose-pattern matcher has no notion of a package, a version, or an exports map; a
+developer following the corpus got a module-resolution failure.
+
+**Warn, never fail — the tradeoff.** The observation is exact but the conclusion is not: "the corpus
+names an API that does not exist" and "this repository is pinned behind the version the corpus
+documents" look identical from the exports map. This script propagates to every Cratis repository,
+and the `ai-corpus` CI job checks out the tree and installs nothing — so failing would be a
+permanent no-op in CI while turning repos red locally for their own dependency pin. The warning
+names the file, the line and the installed version, and leaves the judgement to a human.
+
+> **What this repository is.** `Cratis/AI` is a corpus of markdown, JSON and a little
+> JavaScript — it has no `Source/`, no `.slnx`, no `package.json` and no C# or TypeScript
+> project of its own. Every `.cs` / `.ts` / `Source/**` reference below describes what the
+> hooks do in a **consuming** repository. Here they are silent, which is the designed
+> behavior, not a broken setup.
+
+**Silent when it cannot judge.** No `jq`, no `node_modules`, a package this repository does not
+depend on, or a package published without an `exports` map: skipped without a word. "Not installed"
+is not a finding.
+
+**Version-qualified lines are not drift.** The corpus deliberately documents some 3.0.0+ APIs
+against a 2.x pin, marked inline as `(**≥ 3.0.0**)`. A reference is cleared when a line mentioning
+it in the same file also carries a version — a dotted number, an `N.x`, or either inequality
+spelling. Qualification is judged per *(file, reference)* rather than per line, because the corpus
+states a requirement once and then mentions the subpath again unqualified nearby; per-line matching
+would fire on exactly the lines someone had just fixed correctly. The check is deliberately generous
+in the same direction: it would rather miss a stale line than warn about a correct one.
+
+**What it deliberately does not check.** Named imports (`import { Toaster } from '…'`) are Tier 2's
+job, below; .NET types named in prose or in a C# type position are Tier 3's. This tier checks module
+specifiers, nothing else.
+
+Run it standalone, optionally over other roots, and add `CRATIS_HOOKS_SUBPATH_REPORT=1` to see every
+reference and how it resolved rather than only the failures. It invokes Tier 3 before its own gates
+and Tier 2 after its own work, over the same roots, so the single call site in
+`validate-ai-setup.sh` gets all three.
+
+### Named import existence — `scripts/validate-package-imports.sh` (warn)
+
+Tier 2, and the reason it exists is that Tier 1's answer is not the whole question: a subpath that
+resolves says nothing about the *names* imported through it. For every
+`import { A, B } from '@cratis/<pkg>/<subpath>'` in the corpus — single-line, brace-on-its-own-line,
+`import type`, `A as B` (the *imported* name is what has to exist), trailing `//` comments — it
+checks each identifier against the `.d.ts` closure of the installed package and warns about the ones
+that are not there. `Toaster`, `toastCommandResult`, `PasswordField`, `RatingField` and the rest are
+real APIs of `@cratis/components` **3.0.0** and absent from **2.6.1**; Tier 1 caught the three
+*subpaths* that moved with them, and the twelve *names* were found only by a human reading package
+internals.
+
+**Deliberately permissive, and here is the price.** A name passes when it appears as a *word
+anywhere* in the package's `.d.ts` closure — not only in an export position, not only behind the
+subpath it was imported from — and the closure follows `export … from '<other-package>'` re-exports
+one level out to another installed package. Intra-package barrels (`export * from './X'`) need no
+following, because the whole tree is read either way. That admits names the package merely
+*references* (an imported PrimeReact symbol, a name in a doc comment) and it will not notice a name
+imported from the wrong subpath of the right package. The trade is deliberate: a false warning
+trains people to ignore the guard, a missed one costs a stale line. Measured over the corpus's 85
+import statements / 134 bindings / 38 distinct *(package, name)* pairs plus a 36-pair all-valid
+probe: **zero false positives**, and it still flags all twelve of the 3.0.0 names above when they are
+written unqualified.
+
+**Same warn-only, same silence, same version rule as Tier 1.** No `jq`, no `node_modules`, a package
+this repository does not depend on, or a package that ships no `.d.ts`: skipped without a word. A
+name is cleared when any line in the same file that mentions it also carries a version — judged per
+*(file, name)*, for the same reason Tier 1 judges per *(file, reference)*.
+
+**What it deliberately does not check.** Identifiers that never appear inside an `import { … }`:
+prose mentions, JSX usages, and C# type positions are all invisible. It reads TypeScript import
+statements, nothing else.
+
+Run it standalone over any roots, and add `CRATIS_HOOKS_IMPORT_REPORT=1` to see every binding and how
+it resolved rather than only the failures.
+
+### .NET type existence — `scripts/validate-type-references.sh` (warn)
+
+Tier 3, and the only tier that reads .NET rather than TypeScript. Tiers 1 and 2 both start from an
+`import` statement, so a type the corpus names *only* in prose and in C# type positions is invisible
+to both. That is exactly how `ReactorSideEffect` survived: never a module specifier, never an import,
+told readers to return it from a reactor, shown with object-initializer syntax — and never a type in
+any Chronicle release. Someone following the corpus wrote code that does not compile.
+
+**The index.** Every `Cratis*` version pinned in `Directory.Packages.props` — or, in the corpus
+repository itself, in the tracked pin list `scripts/cratis-nuget-pins.txt`, which names the exact
+product versions the skills verify against — plus the Cratis packages those pull in (`Cratis` is a
+metapackage), resolved against the local NuGet cache. A pin moves only together with the skill
+whose verified version moved.
+
+**Exit codes.** `0` ran (warnings, if any, are on stderr); `1` a `--self-test` expectation failed;
+`2` could not run — no pin source, no NuGet cache, or an index that came up empty — with the reason
+on stderr. "Ran and found nothing" and "never looked" are different verdicts
+(`exit-codes-and-wrappers.md`), and this guard spent its first lifetime erasing that difference by
+exiting `0` at the `Directory.Packages.props` gate in a repository that has none (#287).
+
+**Self-test.** `--self-test` seeds the motivating fabrication (`ReactorSideEffect`, in prose, in
+attribute position, beside the real names it must be distinguished from) into a scratch corpus and
+fails unless the guard names it and keeps the real types silent. Run it after any change to the
+extraction rules, the pin list, or the allowlist — a guard that can pass vacuously is worse than no
+guard (`guards-and-fuses.md`). Each package's
+`lib/**/*.xml` carries `<member name="T:Full.Namespace.TypeName">` — a complete machine-readable type
+list — and every other identifier the docs mention is kept as a second, permissive accept list, in
+the same spirit as Tier 2's "a word anywhere in the `.d.ts` closure". Names the corpus itself
+declares, and names declared in the consuming repository's own `Source/**/*.cs`, are accepted too: a worked
+example that writes `public record AuthorRegistered(…)` before using it is not documenting a
+framework API. A curated allowlist covers the rest — see below.
+
+**Why it is narrow, and what that cost.** The naive version of this check is the reason the whole
+tier nearly did not ship. Of the **1279** distinct PascalCase names it reads across 151 corpus files,
+**599 — 47% — resolve nowhere**, because the corpus legitimately invents domain examples
+(`AuthorRegistered`, `IAuthorService`), placeholders and prose nouns. A guard that cries wolf 599
+times gets switched off, and then it protects nothing. So only two constructs are ever reported:
+
+| Construct | Why it is safe | Measured |
+|---|---|---|
+| **Attribute position** — `[Name]`, `[Name<T>]`, `[Name(…)]` inside an inline code span or a fenced `csharp` block | attribute brackets are unambiguous C#, and a markdown link cannot live inside a code span, so the syntax alone identifies an API reference; `Name` and `NameAttribute` both count | 686 occurrences, 61 distinct names |
+| **Framework-adjacent type token** — any other PascalCase token in a code span or a fenced `csharp` block that resolves nowhere **and** is a strict PascalCase-word-boundary *prefix* of a real Cratis type name | that is the fabrication signature: a half-remembered real family of names with a member coined that was never minted. `ReactorSideEffect` is a prefix of `ReactorSideEffectFailure`; `AuthorRegistered` is a prefix of nothing Cratis ships | takes the 599 unresolved down to **2** |
+
+Both remaining names — `ICommand` and `IQuery`, which do not exist — are cleared by the absence rule
+below, because the corpus's own point about them is exactly that. **Zero warnings on the real
+corpus.**
+
+**Constructs measured and rejected.** Each was extracted over the whole corpus and its unresolved
+names counted before being dropped: `new TypeName` in a fenced `csharp` block (**17** false positives —
+example events are constructed but never declared), `IInterfaceName` in a fenced `csharp` block (**17** —
+invented example services like `IOrderRepository`), the same in an inline code span (**23** —
+TypeScript interfaces and shouty prose such as `IMPORTANT`), and in bare prose (**2**, including the
+plural `IDs`). None of them survives the "precision over recall" test on its own. They are all still
+*read*; they simply have to earn a warning through framework-adjacency instead of through syntax.
+
+**Three structural exclusions, no allowlist needed.** A token is skipped when it is preceded by `.`
+(a member, not a type), when it is ALL-CAPS (`PII`, `IMPORTANT`), and when it is written as
+`<Placeholder>` — the corpus's `<Module>/<Feature>/<Slice>` idiom, distinguished from a generic
+argument list by the character before the `<`, which in C# is always an identifier character.
+
+**Same warn-only and same version rule as Tiers 1 and 2, plus one of its own.** A name is cleared
+when any line in the same file that mentions it carries a version, *or* says the thing does not
+exist — `does not exist`, `no longer`, `never use`, `removed`, `deprecated`, `there is no` and
+friends. Part of this corpus's job is naming APIs that are **not** real, and warning about a line
+whose entire point is that the type is fictional would be the most annoying false positive of all.
+The cost is stated plainly: reintroduce a fabrication into a sentence containing one of those
+phrases and the guard stays quiet.
+
+**Silent when it cannot judge.** No `Directory.Packages.props`, no local NuGet cache, or a cache
+holding none of the pinned versions: skipped without a word. It needs no `jq` and no `node_modules`,
+which is why Tier 1 invokes it *above* its own gates rather than beside the Tier 2 call — a backend-
+only repository must still get this check. It adds about 1.4 s to `validate-ai-setup.sh`.
+
+**The allowlist — `scripts/type-references-allowlist.txt`.** Thirteen entries, each with a written
+justification: ASP.NET Core and BCL attributes that live in ref packs (which ship no XML docs at
+all), Orleans and `Microsoft.Extensions.*` attributes from packages that ship none either, `[CliCommand]`
+/ `[CliExample]` from the separate `Cratis/cli` repository, the Chronicle **Kernel**'s `WellKnown`,
+and `@cratis/fundamentals`' TypeScript `JsonSerializer`. Every one was verified real before being
+listed. An entry is a small lie the guard tells itself, so prefer widening the index whenever that
+is possible, and never add a name you have not confirmed exists.
+
+**What it deliberately does not check.** TypeScript — that is Tiers 1 and 2. Members, methods and
+properties: `Provide()`, `.AutoMap()` and `EventStoreName.NotSet` are all invisible, and a fabricated
+*member* on a real type would pass. And a fabricated type that is not a prefix of any real Cratis
+name is invisible too — the adjacency filter is what buys the precision, and it is also the ceiling
+on the recall.
+
+Run it standalone over any roots, and add `CRATIS_HOOKS_TYPE_REPORT=1` to see every distinct name and
+how it resolved rather than only the failures.
+
+## Configuration is data, not code
+
+Neither the pattern list nor the gate commands live in a script. A consuming repository
+customises both without forking anything:
+
+| File | Purpose |
+|---|---|
+| `scripts/cratis-patterns.json` | shipped pattern set; its header `$comment` documents every field |
+| `scripts/cratis-patterns.local.json` | optional; merged over the above by `id` — add patterns, or set `"enabled": false` to silence one |
+| `scripts/quality-gates.json` | shipped gates; `changed` globs decide when a gate runs, `requires` and `workingDirectoryFrom` decide whether it *can* |
+
+A gate whose `requires.commands` are not on `PATH`, whose `requires.paths` do not exist, or whose
+`workingDirectoryFrom` matches nothing in the repository, is a **no-op with a message on stderr**
+rather than a failure — that is how a repository with no .NET solution or no frontend stays quiet.
+
+**No shipped gate names a product's file.** A default that did would activate in exactly one
+repository and silently no-op in every other, which is the worst of both: it looks configured and
+checks nothing. So the .NET and frontend gates state *what kind of project* they build and let the
+gate script find it — `workingDirectoryFrom: ["*.slnx", "*.sln", "**/*.slnx", "**/*.sln"]` runs
+`dotnet build` in whichever directory holds the repository's own solution, preferring one at the
+root because the globs are tried in order. The frontend gates discover `package.json` the same way.
+The same shipped file therefore activates in an application repository, activates in a framework
+repository, and stays quiet in a corpus-only repository like this one, which has no project at all.
+
+**Overriding it, in order of increasing force.** Set `workingDirectory` on a gate to pin one of
+several candidate projects; drop a `quality-gates.json` of your own in place of the shipped one; or
+point `CRATIS_HOOKS_GATES` at a file anywhere. None of them requires forking the script.
+
+**Profile note.** The C# patterns are application-profile and scoped to `Source/**/*.cs`, which is
+the application source root [`../rules/general.md`](../rules/general.md) documents — not a path in
+this repository, which has no C# at all. A framework-profile repository (Arc, Chronicle,
+Fundamentals, Components — see [`../rules/framework.md`](../rules/framework.md)) has no vertical
+slices and should disable them in its `cratis-patterns.local.json`; a repository whose application
+source root is not `Source/` re-scopes the `paths` globs there too.
+
+**One property gates the proxy generator.** The generator's MSBuild target is
+`Condition="'$(CratisProxiesOutputPath)' != ''"`, so clearing that property with
+`-p:CratisProxiesOutputPath=` is the *only* way to make it no-op. There is no
+`DisableProxyGenerator` property — MSBuild silently accepts unknown `-p:` names, so passing one
+looks like it works and changes nothing. A consuming repository's build workflow should split the
+two configurations the way the shipped gates do: Release clears the path, Debug does not, because
+`general.md` makes the Debug build the canonical trigger for regenerating the TypeScript proxies
+the frontend phase depends on.
+
+## Escape hatches
+
+Each is an explicit, auditable opt-out — none of them is a default.
+
+| Variable | Effect |
+|---|---|
+| `CRATIS_HOOKS_ALLOW_PROTECTED_WRITES=1` | allows one protected write; this is the "unless explicitly asked" case for dependency manifests |
+| `CRATIS_HOOKS_SKIP_SCAN=1` | disables the pattern pass |
+| `CRATIS_HOOKS_SKIP_GATE=1` | disables the quality gate |
+| `CRATIS_HOOKS_GATE_DRYRUN=1` | prints which gates would run, and why, then exits 0 |
+| `CRATIS_HOOKS_PATTERNS=<path>` | replaces the pattern file |
+| `CRATIS_HOOKS_GATES=<path>` | replaces the gate file |
+| `CRATIS_HOOKS_SUBPATH_REPORT=1` | prints every `@cratis/*` subpath reference and how it resolved, not only the failures |
+| `CRATIS_HOOKS_IMPORT_REPORT=1` | prints every `@cratis/*` named import binding and how it resolved, not only the failures |
+| `CRATIS_HOOKS_TYPE_REPORT=1` | prints every .NET type/attribute name the corpus mentions and how it resolved, not only the failures |
+
+## Design constraints
+
+- **POSIX-safe bash**, `set -euo pipefail`, quoted expansions, no `eval`. Verified on bash 3.2
+  (macOS system bash) — no `mapfile`, no associative arrays, no GNU-only flags, `LC_ALL=C` on
+  every sort and compare.
+- **Gate commands are an argv array**, executed directly. They never pass through a shell.
+- **`jq` is the only dependency.** Every script
+  degrades to a silent no-op when it is missing — a hook must never break a session.
+- **Fail safe.** Malformed config, empty stdin, a missing file, a binary file, a file over 2 MB:
+  all exit 0 silently.
+- **No secrets, no file dumps.** Gate output is capped at `maxOutputLines`; the pattern pass
+  prints a path, a line number and a fixed message — never file content.
+- **No re-entry.** The `Stop` hook returns immediately when `stop_hook_active` is true, so a
+  blocked turn cannot loop.
+- **Each pattern fires once per file per session**, tracked under
+  `${TMPDIR}/cratis-hooks/<session-id>/`, so a long edit loop cannot flood context.
+- **The gate never edits code.** It builds, tests and lints. The one side effect is that a Debug
+  build regenerates TypeScript proxies, which is the documented purpose of that build.
+
+## Verifying a change
+
+The scripts read hook JSON on stdin, so they are directly testable:
+
+The pattern pass and the gate both read the repository they are pointed at, so testing them means
+pointing them at a repository that *has* the thing under test. This corpus has no C# and no
+project, so run those two against a consuming checkout (or a scratch tree), and expect silence here.
+
+```bash
+# Pattern pass — expect exit 0, and JSON on stdout only when something matched.
+# Run from an application checkout; <Module>/<Feature>/<Slice> is the layout general.md documents.
+jq -nc '{session_id:"t", cwd:"'"$PWD"'", tool_name:"Edit",
+         tool_input:{file_path:"'"$PWD"'/Source/<Module>/<Feature>/<Slice>/<Slice>.cs"}}' \
+  | .cratis/ai/hooks/scripts/cratis-pattern-scan.sh; echo "exit=$?"
+
+# Hard block — expect exit 2
+jq -nc '{session_id:"t", cwd:"'"$PWD"'", tool_name:"Edit",
+         tool_input:{file_path:"'"$PWD"'/Directory.Packages.props", new_string:"x"}}' \
+  | .cratis/ai/hooks/scripts/cratis-guard-writes.sh; echo "exit=$?"
+
+# Quality gate — show the dispatch plan without running anything
+jq -nc '{session_id:"t", cwd:"'"$PWD"'", stop_hook_active:false}' \
+  | CRATIS_HOOKS_GATE_DRYRUN=1 .cratis/ai/hooks/scripts/cratis-quality-gate.sh
+```
+
+The subpath guard takes corpus roots as arguments, so it is testable in both directions without
+touching the corpus — point it at a scratch folder holding a known-bad reference, then at the real
+roots. A one-sided test passes vacuously; run both.
+
+```bash
+# Negative — expect a warning naming the file and line
+mkdir -p /tmp/scratch-corpus
+echo "import x from '@cratis/components/ThisDoesNotExist';" > /tmp/scratch-corpus/drift.md
+.cratis/ai/hooks/scripts/validate-package-subpaths.sh .cratis/ai/rules /tmp/scratch-corpus
+
+# Positive — expect silence, and the report to show every real reference resolving
+CRATIS_HOOKS_SUBPATH_REPORT=1 .cratis/ai/hooks/scripts/validate-package-subpaths.sh
+```
+
+Tier 2 is testable the same way, and wants a third run the subpath guard does not: a probe of names
+that all genuinely exist. A guard that warns on everything passes the negative test just as well as
+a correct one, so prove it stays quiet when it should.
+
+```bash
+# Negative — a fabricated name behind a subpath that resolves
+mkdir -p /tmp/scratch-corpus
+echo "import { CommandDialog, ThisNameDoesNotExist } from '@cratis/components/CommandDialog';" \
+  > /tmp/scratch-corpus/drift.md
+.cratis/ai/hooks/scripts/validate-package-imports.sh /tmp/scratch-corpus
+
+# Discrimination — every name real, expect silence
+echo "import { DataPage, MenuItem } from '@cratis/components/DataPage';" \
+  > /tmp/scratch-corpus/drift.md
+.cratis/ai/hooks/scripts/validate-package-imports.sh /tmp/scratch-corpus
+
+# Positive — the real corpus, with the report showing every binding resolving
+CRATIS_HOOKS_IMPORT_REPORT=1 .cratis/ai/hooks/scripts/validate-package-imports.sh
+```
+
+Tier 3 wants the same three runs, and its negative case is the one that motivated it. Put
+`ReactorSideEffect` back into a scratch corpus and the guard must name it; a design that misses its
+own motivating case is the wrong design.
+
+```bash
+# Negative — the confirmed fabrication, in prose and in object-initializer syntax
+mkdir -p /tmp/scratch-corpus
+printf 'A reactor may return a `ReactorSideEffect` to control where the event is appended.\n' \
+  > /tmp/scratch-corpus/drift.md
+.cratis/ai/hooks/scripts/validate-type-references.sh /tmp/scratch-corpus
+
+# Discrimination — every name real, expect silence
+printf 'Return `EventForEventSourceId`, or a `ReactorSideEffectFailure` from an `IReactor`.\n' \
+  > /tmp/scratch-corpus/drift.md
+.cratis/ai/hooks/scripts/validate-type-references.sh /tmp/scratch-corpus
+
+# Positive — the real corpus, expect silence, with the report showing how each name resolved
+CRATIS_HOOKS_TYPE_REPORT=1 .cratis/ai/hooks/scripts/validate-type-references.sh
+```
+
+Run `bash -n` on every script and `jq .` on every JSON file before committing. The hook scripts are
+kept at **zero** `shellcheck --external-sources --severity=style` findings by the **Lint the hook
+scripts** step of the `Verify AI Corpus` workflow (`.github/workflows/verify-ai-corpus.yml`), which
+fails the run on any finding at that severity or above. Run the same command before committing:
+
+```bash
+shellcheck --external-sources --severity=style .cratis/ai/hooks/scripts/*.sh
+```
+
+The CI step counts the scripts it checked and refuses to pass on an empty population, so a glob that
+stops matching is a failure rather than a silent green. A finding that is genuinely a false positive
+is silenced with a `# shellcheck disable=SC…` directive carrying a comment that says why — never by
+loosening the severity.
+
+The step uses whatever shellcheck the runner image ships, and prints its version first. Different
+versions genuinely disagree: 0.9.0 flags `A && B || C` (SC2015) where 0.11.0 does not, so a local
+run can be green while CI is red. The scripts are currently clean under **both** 0.9.0 and 0.11.0.
+If a runner image upgrade introduces a new finding, fix the script — the version line at the top of
+the step log says which version changed its mind.
+
+## Note on `.claude/settings.local.json`
+
+If that file carries `allow` entries for `Bash(git push *)` and `Bash(gh pr *)`, they win: local
+settings take precedence over project settings, so they override the `ask` entries the template
+puts in `.claude/settings.json`. Remove them there if you want the confirmation prompt back.

package/package/corpus/hooks/agent-stop.md

@@ -0,0 +1,49 @@
+---
+lifecycle: session-stop
+---
+
+# Agent Stop — Build, Specs, and Corpus Validation
+
+> **This is lifecycle guidance, not a wired tool hook.** Markdown is not a hook format for Copilot or Claude Code. To *enforce* it, wire it per tool to run the repo's build/test command — Claude Code: a `Stop` hook in `.claude/settings.json`; GitHub Copilot: a `sessionEnd` entry in a `.github/hooks/*.json` file. The steps below are what that hook (or the agent) should do.
+
+When the agent finishes a session, verify the work against **fresh signals** before stopping — never against self-assessment. Pick the path that matches the repository.
+
+## Pick the path for this repository
+
+- **AI corpus repo** — the changes are only under `.cratis/ai/`, `.github/`, or `.claude/` and there is no .NET solution or frontend to build (e.g. this `cratis/AI` repo). Run the AI-setup validator instead of a code build:
+  ```
+  .cratis/ai/hooks/scripts/validate-ai-setup.sh
+  ```
+  Stop only when it passes (symlinks/adapters healthy, frontmatter present, no broken cross-links). Skip the application gates below.
+
+- **Application repo** — there is a .NET solution and/or a frontend. Run the application gates below.
+
+## Application gates
+
+1. **Clean** from repository root:
+   ```
+   dotnet clean
+   ```
+2. **Build Debug** from repository root — validates `#if DEBUG` spec code and regenerates the TypeScript proxies:
+   ```
+   dotnet build
+   ```
+3. **Build Release** from repository root — build-only check; skip re-running proxy generation:
+   ```
+   dotnet build -c Release -p:CratisProxiesOutputPath=
+   ```
+4. **Run specs/tests for every affected project** — use the project's test command; if you cannot isolate the affected scope, run the repository-level test command.
+5. **Frontend** (when frontend files changed) — run lint, the type/build check, and frontend tests.
+
+## If any gate fails
+
+- Report the full output.
+- Fix all errors, warnings, and failing specs before considering the session complete.
+- Re-run the gate that failed and confirm it passes *this time*.
+
+## Rules
+
+- A session is not complete until both Debug and Release builds exit `0` with **zero** warnings, and the affected specs/tests exit `0`.
+- Treat Release-only warnings (nullable annotations, analyzer findings) as errors — fix them.
+- **Never** use `/clp:ErrorsOnly` or any flag that suppresses warning output — hidden warnings are warnings that never get fixed.
+- A green build is not behavioral correctness — exercise the affected behavior (specs, or the running UI) and state plainly anything you could not verify.

package/package/corpus/hooks/pre-commit.md

@@ -0,0 +1,47 @@
+---
+lifecycle: pre-commit
+---
+
+# Pre-commit — Run Specs
+
+> **This is lifecycle guidance, not a wired tool hook.** To *enforce* it, wire it per tool — Claude Code: a `PreToolUse` hook in `.claude/settings.json` with a matcher on `Bash` (or your terminal tool) gating `git commit` (and its rtk-rewritten `rtk git commit` form — see [rtk](../rules/rtk.md)); GitHub Copilot: a hook in a `.github/hooks/*.json` file. The steps below are what that hook (or the agent) should do.
+
+Before an explicitly authorized commit, verify the staged scope with proportional checks. Reuse fresh passing results only when they cover the exact unchanged staged inputs; otherwise run the relevant checks. Never stage unrelated edits.
+
+## When this guidance applies
+
+Apply before an authorized `git commit`, including `rtk git commit` or `rtk proxy git commit`. Do not interpret recognizing a command as authorization. History rewriting (`commit --amend`, rebase, squash, or force-push) remains prohibited.
+
+## Steps
+
+1. **Confirm authorization and scope** — this guidance does not authorize a commit or create executable hook wiring. Select documentation/corpus checks for rule-only edits; do not run application tests without affected application code.
+
+2. **Identify affected projects** from the staged changes:
+   ```
+   git diff --name-only --cached
+   ```
+   Collect unique affected project roots:
+   - `.cs` files → walk up to the nearest `.csproj`.
+   - `.ts` / `.tsx` files → walk up to the nearest `package.json` with a `"test"` script.
+
+3. **Run specs for each affected .NET project**:
+   ```
+   dotnet test <specs-project-path> --no-build
+   ```
+   Use `--no-build` only when matching build outputs are current; otherwise incrementally build the affected specs project first. If the owning specs project cannot be identified, inspect project references or report the uncertainty; do not default to a root-wide test run.
+
+4. **Run specs for each affected TypeScript project**:
+   ```
+   yarn test
+   ```
+   Run from the package root that owns the changed files.
+
+5. **If a relevant check fails** — diagnose within a bounded attempt, fix only in-scope causes, and re-run the failed gate. Report unrelated/environmental failures as blockers instead of repeated retries or broad edits. Do not claim completion or bypass required gates.
+
+6. **When relevant required checks pass** — proceed only with the originally authorized commit and staged scope. Report the exact verification and any checks not run.
+
+## Rules
+
+- Documentation/rule-only commits run relevant content, link, frontmatter, and corpus checks, not application builds/tests.
+- Code changes run affected-project incremental checks and targeted regression specs after coherent changes. Wider suites and clean/Release builds require cross-cutting scope or repository merge/release gates.
+- Do not bypass required failures, suppress diagnostics, or expand into unrelated cleanup. Missing prerequisites and pre-existing failures must be reported honestly.

package/package/corpus/hooks/scripts/cratis-guard-writes.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# PreToolUse hook — hard block on writes that must never happen.
+#
+# Exits 2 (block the tool call, stderr goes back to the model) for:
+#   1. Generated files      — anything whose header marks it as Cratis-generated output
+#                             (.cratis/ai/rules/general.md rule 15 [contract])
+#   2. Dependency manifests — Directory.Packages.props, global.json, lockfiles, NuGet config
+#   3. Environment files    — .env and friends (secrets)
+#
+# 2 and 3 come from the Source-of-Truth Discipline rule: "Don't change dependency manifests /
+# lockfiles / global.json / NuGet config unless explicitly asked."
+#
+# Escape hatch for the "unless explicitly asked" case — the user asks, you set it for the call:
+#   CRATIS_HOOKS_ALLOW_PROTECTED_WRITES=1
+set -euo pipefail
+
+# SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
+# against the current working directory, and these hooks are linted from wherever CI happens to run.
+# shellcheck source=SCRIPTDIR/hook-lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+
+[ "${CRATIS_HOOKS_ALLOW_PROTECTED_WRITES:-0}" = "1" ] && exit 0
+
+input="$(hook_read_stdin)"
+[ -n "$input" ] || exit 0
+hook_have jq || exit 0
+
+root="$(hook_repo_root)"
+cwd="$(hook_json "$input" '.cwd')"
+[ -n "$cwd" ] || cwd="$root"
+
+file="$(hook_json "$input" '.tool_input.file_path')"
+[ -n "$file" ] || file="$(hook_json "$input" '.tool_input.notebook_path')"
+[ -n "$file" ] || exit 0
+
+file="$(hook_abspath "$file" "$cwd")"
+rel="$(hook_relpath "$file" "$root")"
+base="$(basename "$file")"
+
+block() {
+    printf 'BLOCKED by cratis-guard-writes: %s\n\n%s\n\n%s\n' "$rel" "$1" "$2" >&2
+    exit 2
+}
+
+# ── 1. Generated files ────────────────────────────────────────────────────────
+# The marker must be a real header: a comment opener at the start of one of the first few lines.
+# Merely *mentioning* the string — documentation, a rule file, this corpus — is not a match.
+marker='^[[:space:]]*(//|/\*|#|<!--)[[:space:]]*@generated by Cratis'
+
+if [ -f "$file" ] \
+    && LC_ALL=C grep -Iq . "$file" 2>/dev/null \
+    && head -n 5 "$file" 2>/dev/null | LC_ALL=C grep -Eq "$marker"; then
+    block \
+        "This file is generated output (its header marks it as generated by Cratis). Rule 15 [contract] in .cratis/ai/rules/general.md: never edit a generated file — the next build overwrites it." \
+        "Instead: change the C# source it is generated from (the [Command] / [ReadModel] record) and rebuild with 'dotnet build -c Debug' to regenerate the proxy."
+fi
+
+# The same guard for authoring a *new* file that pretends to be generated output.
+new_content="$(hook_json "$input" '.tool_input.content')"
+[ -n "$new_content" ] || new_content="$(hook_json "$input" '.tool_input.new_string')"
+if [ -n "$new_content" ] \
+    && printf '%s\n' "$new_content" | head -n 5 | LC_ALL=C grep -Eq "$marker"; then
+    block \
+        "The content being written opens with a Cratis generated-file header. Proxies are produced by the Cratis proxy generator, never hand-written." \
+        "Instead: write the C# source and run 'dotnet build -c Debug' to generate the proxy."
+fi
+
+# ── 2. Dependency manifests, lockfiles, SDK and NuGet configuration ───────────
+case "$base" in
+    Directory.Packages.props | global.json | NuGet.config | NuGet.Config | nuget.config \
+        | yarn.lock | package-lock.json | pnpm-lock.yaml | packages.lock.json)
+        block \
+            "'$base' is a dependency manifest / lockfile / SDK or NuGet configuration file. .cratis/ai/rules/general.md (Source-of-Truth Discipline): don't change these unless explicitly asked." \
+            "If the user explicitly asked for this change, re-run the tool call with CRATIS_HOOKS_ALLOW_PROTECTED_WRITES=1 exported. Otherwise take the dependency as given and solve the problem in source."
+        ;;
+esac
+
+# ── 3. Environment files ──────────────────────────────────────────────────────
+case "$base" in
+    .env | .env.* | *.env)
+        block \
+            "'$base' is an environment file and normally holds secrets. Hooks block writing it so credentials are never authored, rewritten, or echoed by an agent." \
+            "Instead: tell the user exactly which variable to set and let them edit the file. If they explicitly asked you to write it, re-run with CRATIS_HOOKS_ALLOW_PROTECTED_WRITES=1 exported."
+        ;;
+esac
+
+exit 0

package/package/corpus/hooks/scripts/cratis-nuget-pins.txt

@@ -0,0 +1,11 @@
+# Cratis NuGet packages and exact versions the canonical corpus verifies against.
+# One `Id Version` pair per line; the type-reference guard's transitive walk expands
+# each into the full Cratis closure found in the local NuGet cache. Sources: the
+# "Verified product sources" sections of the skills under skills/.
+# Update a pin only together with the skill whose verified version moved.
+Cratis.Arc 22.10.4
+Cratis.Arc.Chronicle 22.10.4
+Cratis.Chronicle 16.45.2
+Cratis.Chronicle 17.0.1
+Cratis.Chronicle.CodeAnalysis 16.45.3
+Cratis.Fundamentals 7.18.2