@cratis/pi 2.22.0 → 2.23.1

package/package/corpus/harnesses/pi/extensions/subagent/agents.ts

@@ -23,6 +23,13 @@ export interface AgentConfig {
 	name: string;
 	description: string;
 	tools?: string[];
+	/**
+	 * Set when the agent declared a non-empty `tools` list of which nothing maps to a Pi tool. Such an
+	 * agent must not launch: dropping the whole list would hand a deliberately restricted agent (a
+	 * read-only reviewer) Pi's full default toolset. Mirrors Claude Code, which refuses to launch a
+	 * subagent whose `tools` list resolves to no tool.
+	 */
+	toolsError?: string;
 	model?: string;
 	systemPrompt: string;
 	source: "package" | "user" | "project";
@@ -70,22 +77,59 @@ const TOOL_NAME_MAP: Record<string, string | null> = {
 	websearch: null,
 };
 
+/**
+ * The outcome of normalizing a frontmatter `tools` value.
+ *
+ * `tools` is the de-duplicated Pi allowlist, or `undefined` when the agent declared no tools at
+ * all (it then inherits Pi's full default toolset, exactly like an omitted `tools:` in Claude Code).
+ * `unresolved` lists every declared name that is neither a Pi built-in nor a known orchestration
+ * tool, so a caller can tell "nothing declared" apart from "declared, but nothing resolved".
+ */
+export interface NormalizedTools {
+	tools?: string[];
+	unresolved: string[];
+}
+
 /**
  * Normalize a frontmatter `tools` value to a de-duplicated list of Pi tool names.
  * Accepts both YAML spellings in use (`tools: [Read, Bash]` and `tools: Read, Bash`).
- * Returns `undefined` when nothing maps, so the subagent inherits Pi's full default
- * toolset rather than being launched with an empty allowlist.
  */
-export function normalizeTools(value: unknown): string[] | undefined {
+export function normalizeToolsDetailed(value: unknown): NormalizedTools {
 	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
-	const mapped = raw
+	const declared = raw
 		.filter((t): t is string => typeof t === "string")
-		.map((t) => t.trim().toLowerCase())
-		.filter(Boolean)
+		.map((t) => t.trim())
+		.filter(Boolean);
+	const mapped = declared
+		.map((t) => t.toLowerCase())
 		.map((t) => (t in TOOL_NAME_MAP ? TOOL_NAME_MAP[t] : null))
 		.filter((t): t is string => typeof t === "string");
+	const unresolved = declared.filter((t) => !(t.toLowerCase() in TOOL_NAME_MAP));
 	const deduped = Array.from(new Set(mapped));
-	return deduped.length > 0 ? deduped : undefined;
+	return { tools: deduped.length > 0 ? deduped : undefined, unresolved };
+}
+
+/**
+ * Normalize a frontmatter `tools` value to a de-duplicated list of Pi tool names, or `undefined`
+ * when nothing maps. Prefer {@link normalizeToolsDetailed} where the difference between an omitted
+ * list and an unresolvable one matters — it always does when the result gates a launch.
+ */
+export function normalizeTools(value: unknown): string[] | undefined {
+	return normalizeToolsDetailed(value).tools;
+}
+
+/**
+ * The launch error for an agent whose declared tools resolve to nothing, or `undefined` when the
+ * agent either declared no tools or at least one of them resolved.
+ */
+export function toolsErrorFor(name: string, value: unknown): string | undefined {
+	const { tools, unresolved } = normalizeToolsDetailed(value);
+	if (tools !== undefined || unresolved.length === 0) return undefined;
+	return (
+		`Agent "${name}" declares tools that resolve to no Pi tool: ${unresolved.join(", ")}. ` +
+		`It would launch with every tool instead of the restriction it declares, so it is not launched. ` +
+		`Declare Pi-resolvable names (Read, Write, Edit, Bash, Grep, Glob, ls) in its frontmatter.`
+	);
 }
 
 function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"): AgentConfig[] {
@@ -119,6 +163,7 @@ function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"):
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: normalizeTools(frontmatter.tools),
+			toolsError: toolsErrorFor(frontmatter.name, frontmatter.tools),
 			model: typeof frontmatter.model === "string" ? frontmatter.model.trim() : undefined,
 			systemPrompt: body,
 			source,

package/package/corpus/harnesses/pi/extensions/subagent/index.ts

@@ -96,6 +96,20 @@ async function runSingleAgent(
 		};
 	}
 
+	// A restricted agent whose restriction cannot be expressed in Pi is not launched at all: launching it
+	// with the full toolset would be the opposite of what its author declared (see AgentConfig.toolsError).
+	if (agent.toolsError) {
+		return {
+			agent: agentName,
+			agentSource: agent.source,
+			task,
+			exitCode: 1,
+			finalText: "",
+			stderr: agent.toolsError,
+			step,
+		};
+	}
+
 	// An agent that pins no model inherits the dispatching session's model + thinking level.
 	const model = agent.model ?? dispatch.model;
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];

package/package/corpus/hooks/README.md

@@ -13,24 +13,27 @@ Three layers:
 | 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:
+[`settings.template.json`](./settings.template.json). Claude reads `.claude/settings.json`. In a
+repository set up with `cratis ai install`, that file is a **symlink** to this template and follows
+every `cratis ai update`; there is nothing to copy. Where the corpus is present without the CLI,
+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 the [corpus README](../README.md)), and
-`scripts/validate-ai-setup.sh` checks the template against the script names this page documents.
+If you already have a `.claude/settings.json` of your own, merge the template's `hooks` block into it
+rather than overwriting — the rest of that file is yours — and re-copy after the template changes.
+**Edit the template, never the copy or the managed file**: `.cratis/ai/` is the source of truth (see the
+[corpus README](../README.md)), and `cratis ai status` reports a hand-edited managed file as drift.
 
 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.
+> Hooks are the one surface with no folder adapter: Claude Code reads `.claude/settings.json`;
+> the Pi harness bridges the same three scripts to its own events through the `cratis-hooks`
+> extension under `../harnesses/pi/extensions/`; Copilot would read `.github/hooks/*.json`, and no
+> Copilot wiring ships yet.
 
 ## What is enforced
 
@@ -83,13 +86,16 @@ the managed gates running unchanged.
 `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.
+test.
 
-## The corpus validator
+## The package drift guards
 
-`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**.
+Three scripts sit outside the three layers and are not bound to a hook event: run
+`scripts/validate-package-subpaths.sh` directly and it chains `validate-type-references.sh` and
+`validate-package-imports.sh` over the same roots. They check the corpus text against the packages a
+repository actually has installed, so they are meaningful only where `node_modules` or a NuGet cache
+exists. The corpus's own structure, catalog and adapters are verified in the `Cratis/AI` repository
+before anything is published; a consuming repository checks its installed copy with `cratis ai status`.
 
 ### Package subpath existence — `scripts/validate-package-subpaths.sh` (warn)
 
@@ -113,11 +119,9 @@ and the `ai-corpus` CI job checks out the tree and installs nothing — so faili
 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.
+> Every `.cs` / `.ts` / `Source/**` reference below describes what the hooks do in a repository
+> that has such a project. Where there is none — a documentation or corpus-only repository — the
+> hooks 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"
@@ -137,8 +141,7 @@ 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.
+and Tier 2 after its own work, over the same roots, so one call gets all three.
 
 ### Named import existence — `scripts/validate-package-imports.sh` (warn)
 
@@ -247,7 +250,7 @@ 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`.
+only repository must still get this check. It adds about 1.4 s to the chained run.
 
 **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
@@ -288,15 +291,15 @@ gate script find it — `workingDirectoryFrom: ["*.slnx", "*.sln", "**/*.slnx",
 `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.
+repository, and stays quiet in a repository that 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,
+the application source root [`../rules/general.md`](../rules/general.md) documents. 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.
@@ -350,8 +353,7 @@ Each is an explicit, auditable opt-out — none of them is a default.
 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.
+pointing them at a repository that *has* the thing under test; where it is absent, expect silence.
 
 ```bash
 # Pattern pass — expect exit 0, and JSON on stdout only when something matched.

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

@@ -10,11 +10,7 @@ When the agent finishes a session, verify the work against **fresh signals** bef
 
 ## 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.
+- **No .NET solution or frontend** — a documentation or corpus-only repository. Run that repository's own documentation and corpus checks instead of a code build, and `cratis ai status` when the change touched the installed AI corpus or its adapters (a hand-edited managed file is reported as drift). Skip the application gates below.
 
 - **Application repo** — there is a .NET solution and/or a frontend. Run the application gates below.
 

package/package/corpus/hooks/scripts/cratis-patterns.json

@@ -78,7 +78,7 @@
             "pattern": "from[[:space:]]+['\"]primereact/dialog['\"]",
             "paths": ["**/*.ts", "**/*.tsx"],
             "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/wwwroot/**", "**/obj/**", "**/bin/**"],
-            "message": "Never import `Dialog` from `primereact/dialog` — use `CommandDialog` / `Dialog` from `@cratis/components`."
+            "message": "Cratis Components 4 has no PrimeReact underneath — a `primereact/dialog` import is a leftover from Components 3. Use `CommandDialog` from `@cratis/components/CommandDialog` or `Dialog` from `@cratis/components/Dialogs`."
         }
     ]
 }

package/package/corpus/hooks/scripts/validate-package-subpaths.sh

@@ -113,8 +113,7 @@ done
 
 # Tier 2 over the same roots: a subpath that resolves says nothing about the *names* imported
 # through it. Kept in its own script — a different question, a different corpus extraction and a
-# different report variable — and invoked from here so the single call site in validate-ai-setup.sh
-# gets both. Tested with -f, not -x, and run through `bash`: a checkout that lost the exec bit must
+# different report variable — and invoked from here so one call to this script gets both. Tested with -f, not -x, and run through `bash`: a checkout that lost the exec bit must
 # not silently drop the guard.
 imports="$(dirname "${BASH_SOURCE[0]}")/validate-package-imports.sh"
 if [[ -f "$imports" ]]; then bash "$imports" "$@" || true; fi

package/package/corpus/prompts/ship-changes.prompt.md

@@ -21,3 +21,7 @@ Invoking this prompt is direct authority for the standard branch, commit, push,
 requested-label, merge, and branch-cleanup effects. Do not pause to ask for separate approval at
 each step. Follow the repository's Git commit and pull-request rules, use a true merge commit,
 and verify required checks before merging.
+
+This prompt is for an explicit request to ship or land. If the user asked only to commit, only to
+push, or only to open a PR, stop after that step: the narrower request does not become authority
+for the rest of the chain because this prompt happens to be loaded.

package/package/corpus/prompts/verify-ai-setup.prompt.md

@@ -1,19 +1,29 @@
 ---
 agent: agent
-description: Validate AI framework setup integrity, canonical source conventions, and symlink health.
+description: Check the installed Cratis AI corpus for drift, conflicts, and healthy harness adapters.
 ---
 
 # Verify AI Setup
 
-Validate the repository AI setup by running:
+Check the repository's installed Cratis AI setup by running:
 
 ```bash
-bash .cratis/ai/hooks/scripts/validate-ai-setup.sh
+cratis ai status
 ```
 
-If anything fails:
+It reports the configured harnesses, profiles and languages, the installed corpus revision against the
+available one (`updateAvailable`), and every managed file that was modified locally — exiting non-zero
+when there is any. (A user-owned path that collides with a managed one is reported and refused by
+`cratis ai install` / `cratis ai update`, not by `status`.) Then confirm
+the harness adapters this repository uses (`.claude/`, `.agents/`, `.github/`, `.pi/`, `.cursor/`,
+`.opencode/` as applicable) still resolve into `.cratis/ai/` — a broken or dangling symlink is a setup
+fault, not corpus drift.
 
-1. List every failure with the exact file path.
-2. Explain whether the issue is canonical-source drift, missing metadata, or broken links.
-3. Propose the smallest safe fix.
+If anything is reported:
+
+1. List every finding with the exact file path.
+2. Explain whether it is a hand-edited managed file, a pending update, or a broken adapter.
+3. Propose the smallest safe fix. A managed file is never patched by hand — `cratis ai update`
+   replaces it (with `--force` only for content already recorded as Cratis-managed); a user-owned
+   file is the repository's and stays.
 4. Apply fixes if requested.

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

@@ -0,0 +1,60 @@
+---
+applyTo: "**/.cratis/**"
+paths:
+  - "**/.cratis/**"
+---
+
+# Shared AI Distribution
+
+How the shared Cratis AI corpus reaches a repository, and what a consuming
+repository must and must not do with it. The always-loaded instructions keep only
+the two invariants; this rule carries the mechanics.
+
+Do not copy or synchronize shared `.cratis/ai`, `.agents`, `.claude`, `.github`, or
+`.pi` trees from one Cratis repository to another. A consuming repository must
+never become an accidental source that republishes its local AI corpus.
+
+Shared Cratis capabilities are authored and reviewed in `Cratis/AI` and reach a
+repository through one of three channels, each with its own version semantics:
+
+- **`cratis ai install` / `cratis ai update`** copy the corpus into `.cratis/ai/`
+  from the current `main` of `Cratis/AI` (or an explicit `--source` path), record
+  the source commit and every installed file's hash in `.cratis/ai.manifest.json`,
+  and create native harness adapters as symlinks into that managed copy. There is
+  no version pin on this channel: an update takes whatever `main` holds. Agents,
+  prompts, and hooks are always installed; rules are filtered by profile and
+  language; skills by the profile catalog; `harnesses/<harness>/` only for the
+  harnesses selected.
+- **`@cratis/pi`** is the one versioned channel: an npm package cut per release,
+  pinned and rolled back by package version. It yields to a managed install when
+  `.cratis/ai.manifest.json` exists.
+- **Native plugin marketplaces** (Claude Code, Codex, Copilot, Cursor) expose the
+  skills only, from the unpinned GitHub source.
+
+Keep existing repository-local AI files in place while a replacement corpus is
+under canary; do not restart legacy all-to-all propagation and do not delete
+legacy adapters before reviewed retirement evidence exists.
+
+Shared public product and `engineering-*` packages contain only public-safe
+Cratis behavior. The `engineering-` prefix identifies the maintainer audience;
+it does not imply confidential package contents or a private registry.
+
+The consuming repository owns its project facts, confidential behavior, local
+skills, and minimal host bootstraps. Use repository-owned documentation as canonical
+project context when that migration is active, `.agents/skills/` for private or
+repository-specific local workflows, and repository-owned documentation only as the
+documented legacy context fallback. Never merge, overwrite, or remove these
+local files as a side effect of installing, updating, rolling back, or
+uninstalling shared AI capabilities.
+
+Keep confidential and repository-specific behavior local. Generalize and remove
+private facts before proposing a reusable improvement to `Cratis/AI`; never
+reverse-sync a private repository's AI tree or generated adapters.
+
+Update shared AI through the channel's own mechanism (`cratis ai update`, or the
+`@cratis/pi` package version). Canary the change, observe its behavior and gates,
+and roll back the same way — by package version where one exists, otherwise by
+reinstalling from a known-good source commit with `--source`. Never patch managed
+files under `.cratis/ai/`, generated adapters, or marketplace wrappers by hand;
+`cratis ai status` reports such drift and `update` refuses it without `--force`.
+

package/package/corpus/rules/application-profile.md

@@ -0,0 +1,73 @@
+---
+applyTo: "**/*"
+profile: application
+---
+
+# Application profile
+
+> The following — **Project Layout, Slice Types, Slice Naming, the Rules, and the Implementation Workflow** — applies when **building an application on Cratis**. If you are contributing to a Cratis framework repo, skip to **Framework profile** below and follow [framework.md](./framework.md).
+
+## Project Layout (Cratis Application convention)
+
+The framework discovers commands and read models by attributes and static methods — **the folder shape is a convention, not a requirement.** The house default: the domain hierarchy lives directly under the app source root (**no top-level `Features/` wrapper**), cross-cutting concerns (`Common/` concepts, `Identity/`, shared components) at the top level, and one folder per behavior — `<Module>/<Feature>/<Slice>/` holding `<Slice>.cs`, the slice's `.tsx`, and its `when_*/` specs. **The slice is the invariant unit** — created, renamed, and deleted as one. Namespace mirrors the path under the source root, dropping any level that isn't present. The full tree and the split rules are in [vertical-slices.md](./vertical-slices.md).
+
+## Slice Types
+
+Pick exactly one type per slice folder — determined by what the slice *does*.
+
+| Type | What it does | Contents |
+| --- | --- | --- |
+| **State Change** | Accepts a command, appends events | Command + validator + event(s); optional `[Passive]` read model for command-side decisions |
+| **State View** | Projects events into a queryable read model | `[ReadModel]` + model-bound projection + static query method(s) |
+| **Automation** | Reacts to events, calls external systems / `ICommandPipeline` | Reactor only |
+| **Translation** | Reacts to events and appends follow-up events to another stream | Reactor only |
+
+## Slice Naming (convention)
+
+Commands are imperative intents (`Register`, `Create`); the slice folder is the action only, never repeating a noun the Feature already establishes. **`[EventType]` records are past-tense facts** and must be self-describing (`AuthorRegistered`, never `Created`) — this past-tense, one-purpose naming is a Chronicle framework recommendation. Static query methods are descriptive reads (`AllAuthors`, `AuthorById`, `AuthorsByName`).
+
+## Rules
+
+Tagged **[contract]** (framework-enforced) or **[convention]** (house default). Mechanics and examples live in `vertical-slices.md`.
+
+1. **[contract] Model-bound — no controllers.** Commands are `[Command]` records with a public instance `Handle()` (Arc analyzers enforce this); queries are `static` methods on `[ReadModel]` records; projections/constraints/authorization use attributes. Arc generates the HTTP surface. Drop to fluent (`IProjectionFor<T>`, `IConstraint`) only when model-bound can't express the rule.
+2. **[contract] Command validation & data flow.** Put command rejection in `CommandValidator<T>`, global value invariants in `ConceptValidator<T>`, and fetched/computed handler data in **`Provide()`** (runs after validation/authorization; may short-circuit with `ValidationResult.Error` / `Result<TProvided, ValidationResult>`). Keep `Handle()` focused on event construction. For a state-dependent rule that must hold **under concurrency**, inject the read model into `Handle()` and return a typed error via `Result<TEvent, ValidationResult>`. **Throwing from `Provide()`/`Handle()` is an exception (HTTP 500), not a validation rejection** — throw only for genuinely exceptional conditions, never for normal business rejection.
+3. **[contract] Event-source id resolution:** `ICanProvideEventSourceId` first; else the first qualifying property in declaration order — an `EventSourceId`/`EventSourceId<T>`-derived value *or* a `[Key]` property (no priority between them; two candidates is `ARCCHR0002`); else Arc generates one. A value actually used as a Chronicle stream identity derives from `EventSourceId<T>` with the underlying `IComparable` primitive — never `ConceptAs<Guid>` for that stream identity. `NotSet`, `New()`, and primitive→derived-id operators are optional domain/API conveniences, not Chronicle requirements; typed empty/zero values are real specified stream IDs, not `EventSourceId.Unspecified`.
+4. **[contract] Events never carry the event-source id** — it is implicit in the event context.
+5. **[contract] `[Key]` / `[Subject]` are distinct.** `[Key]` is for event-source/read-model/projection key resolution; `[Subject]` is compliance identity only. Don't put either on an `EventSourceId<T>` value (it already is both); use them only for non-`EventSourceId<T>` values.
+6. **[contract] Avoid nullable event properties** — Chronicle's analyzer warns on them. Model optional facts as a separate event; resolve nullable command inputs to a non-null sentinel before constructing the event.
+7. **[contract] `[EventType]` takes no arguments for new events** — the type name is the identifier. Use `generation:`/id only when evolving an existing contract; schema changes get a new generation + an `EventTypeMigration<TUpgrade,TPrevious>` (never edit stored-event semantics silently). An enum that only gains a member, or has one renamed, is the exception — Chronicle accepts that in place; a *removed* or *renumbered* member still needs a generation, plus a value map saying what the old values became.
+8. **[convention] Every `[EventType]` has an XML `<summary>`** — a Cratis C# documentation convention (not a Chronicle rule); events live in the log forever, so record why they exist.
+9. **[convention] `[ReadModel]` properties carry no default values** except semantically meaningful enum initial states and `[SetValue<T>]`-driven `bool` flags. False defaults hide missing projection wiring.
+10. **[contract] AutoMap is on by default — never call `.AutoMap()`.** Match property names so AutoMap wires them; diverge with `[SetFrom<T>]` / fluent `.Set().To()` only for genuine name differences. Re-enable `.AutoMap()` only inside a scope where it was disabled with `.NoAutoMap()`.
+11. **[contract] Projections consume events and event context — never other read models.** Default to model-bound attributes; use fluent `IProjectionFor<T>` for joins/nested/context/transforms; use a reducer when the model is "current state + event → next state" (a valid style, not a failure mode).
+12. **[contract] Model-bound query custom paths use `[Path("...")]`** (`PathAttribute`), not ASP.NET `[Route]`. Reserve `[Route]` for controller-based endpoints (which this convention avoids).
+13. **[convention] Cross-slice access is read-only through Chronicle** — inject another slice's read model or reference its events; never instantiate or DI another slice's command/handler/service.
+14. **[contract] Never inject `IEventLog` into `Handle()`** — express appends through return types (`IEnumerable<object>` with `EventForEventSourceId` wrappers for cross-stream). In application reactors, return side-effect events or commands (or use `ICommandPipeline` and inspect the result); don't reach for `IEventLog` directly.
+15. **[contract] Never edit a generated file** — proxies carry a `// @generated by Cratis` header. Fix the C# source and rebuild.
+16. **[convention] Use the Cratis dialogs** — `CommandDialog` from `@cratis/components/CommandDialog`, `Dialog` from `@cratis/components/Dialogs`; never a vendor or hand-rolled modal. The default frontend stack is Cratis Components **4.x** (Components-owned markup, `--cratis-*` tokens, `pt`/`data-cratis-part` parts; no PrimeReact dependency) — **not** Tailwind (Tailwind is one supported way to write the token-mapping CSS, not the generic default).
+17. **[convention] One slice is one unit** — creating/renaming/moving/deleting a slice means doing the same to every artifact (the `.cs`, every `when_*/`, every `.tsx`, the composition import/JSX, the route).
+
+## Implementation Workflow
+
+- **Phase 0 — Model.** Confirm Module/Feature, slice name, slice type, domain rules; for new behavior or unclear event vocabulary run the **event-modeling** skill first.
+- **Phase 1 — Backend.** Implement a coherent slice change. **Gate:** incremental Debug build of the affected project (regenerates proxies, compiles `#if DEBUG` spec code).
+- **Phase 2 — Specs.** Mandatory for every slice type, in-process scenario family first (`CommandScenario<T>`, `EventScenario`, `ReadModelScenario<T>`, `ReactorScenario<T>`). **Gate:** tests pass.
+- **Phase 3 — Frontend.** Build from the generated proxies, register in the composition page, wire routing. **Gate:** lint, conditional test, build.
+
+**Backend before frontend, always** — the frontend depends on proxies that exist only after a successful build. Generate proxies from the **Debug** build (house convention); verify Release without re-running the generator: `dotnet build -c Release -p:CratisProxiesOutputPath=`. Why that property, and what to do when nothing is generated: the **cratis-arc-command** skill's proxy-generation reference.
+
+## Quality Gates
+
+| Phase | Command (app-pinned) | Pass criteria |
+| --- | --- | --- |
+| Backend | build (Debug) | zero errors, zero warnings — validates `#if DEBUG` spec code and regenerates proxies |
+| Backend | build (Release) | zero errors, zero warnings — build-only check; pass `-p:CratisProxiesOutputPath=` to skip re-running proxy generation |
+| Specs | test | zero failures |
+| Frontend | lint | zero errors |
+| Frontend | test | zero failures when frontend specs/behavior changed |
+| Frontend | build | zero errors |
+
+Run affected-project incremental checks after a coherent change, then targeted regression tests for the changed behavior. Re-run a failed gate after a relevant fix. Reserve wider matrices and clean/Release builds for cross-cutting changes, demonstrated stale outputs, or required merge/release gates. Documentation/rule-only edits need relevant Markdown, frontmatter, link, and corpus checks, not an application build. Diagnose unrelated or environmental failures within a bounded attempt; report the evidence and blocker instead of broadening scope or retrying indefinitely. Required gates remain blocking until satisfied; never silently waive red CI.
+
+Documentation-only changes carry non-release intent and run the documentation checks, never a blanket exemption from red CI — see [pull-requests.md](./pull-requests.md).