@cratis/pi 2.23.0 → 2.23.1

package/package/corpus/harnesses/pi/extensions/cratis-rules/index.ts

@@ -1,27 +1,250 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 
 const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
 
-/** Loads every rule from the managed corpus, including general guidance when AGENTS.md is project-owned. */
-export function managedRules(cwd: string): string {
+type AiConfiguration = { profiles?: string[] };
+
+export interface ManagedRule {
+    /** Path relative to the rules root, e.g. `code-quality-csharp.md` or `project/running-the-local-stack.md`. */
+    name: string;
+    /** Full file content, frontmatter included, exactly as the other harnesses receive it. */
+    content: string;
+    /** `application`, `framework`, or undefined when the rule is not profile-specific. */
+    profile?: string;
+    /** Globs from `applyTo` and `paths`. Empty means the rule applies to every file. */
+    globs: string[];
+}
+
+const universalGlobs = new Set(['**', '**/*', '*']);
+
+function unquote(value: string): string {
+    return value.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
+ * `  - item` lines. Anything richer is not used by the rules and is deliberately not supported.
+ */
+function frontmatter(content: string): Map<string, string[]> {
+    const fields = new Map<string, string[]>();
+    if (!content.startsWith('---\n')) return fields;
+    const end = content.indexOf('\n---\n', 4);
+    if (end < 0) return fields;
+    let current: string | undefined;
+    for (const line of content.slice(4, end).split('\n')) {
+        const item = /^\s+-\s+(.*)$/.exec(line);
+        if (item && current) {
+            fields.get(current)!.push(unquote(item[1]));
+            continue;
+        }
+        const scalar = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+        if (!scalar) continue;
+        current = scalar[1];
+        const value = unquote(scalar[2]);
+        fields.set(current, value ? value.split(',').map(unquote).filter(Boolean) : []);
+    }
+    return fields;
+}
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+
+/** Converts the glob dialect used by `applyTo` (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+    let pattern = '';
+    for (let index = 0; index < glob.length; index++) {
+        const character = glob[index];
+        if (character === '*') {
+            if (glob[index + 1] === '*') {
+                if (glob[index + 2] === '/') {
+                    pattern += '(?:.*/)?';
+                    index += 2;
+                } else {
+                    pattern += '.*';
+                    index += 1;
+                }
+            } else {
+                pattern += '[^/]*';
+            }
+        } else if (character === '?') {
+            pattern += '[^/]';
+        } else if (character === '{') {
+            const close = glob.indexOf('}', index);
+            if (close > index) {
+                pattern += `(?:${glob.slice(index + 1, close).split(',').map(part => escapeRegExp(part.trim())).join('|')})`;
+                index = close;
+            } else {
+                pattern += '\\{';
+            }
+        } else {
+            pattern += escapeRegExp(character);
+        }
+    }
+    return new RegExp(`^${pattern}$`);
+}
+
+function rulesRoot(cwd: string): string {
     const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
-    const rulesRoot = existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
-    return readdirSync(rulesRoot, { recursive: true, encoding: 'utf8' })
+    return existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
+}
+
+function configuration(cwd: string): AiConfiguration | undefined {
+    const path = join(cwd, '.cratis', 'ai.json');
+    if (!existsSync(path)) return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8')) as AiConfiguration;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * A profile-specific rule is kept only when the repository selects that profile. Repositories without
+ * a `.cratis/ai.json` keep every rule, matching the `@cratis/pi` package.
+ */
+function matchesProfile(rule: ManagedRule, selected: AiConfiguration | undefined): boolean {
+    if (!rule.profile || !selected) return true;
+    const profiles = selected.profiles ?? [];
+    if (rule.profile === 'application') return profiles.some(profile => profile.startsWith('cratis/application'));
+    if (rule.profile === 'framework') return profiles.some(profile => profile.startsWith('cratis/engineering'));
+    return true;
+}
+
+/** Loads every managed rule with its frontmatter interpreted, filtered to the repository's profiles. */
+export function managedRules(cwd: string): ManagedRule[] {
+    const root = rulesRoot(cwd);
+    const selected = configuration(cwd);
+    return readdirSync(root, { recursive: true, encoding: 'utf8' })
         .filter((entry): entry is string => entry.endsWith('.md'))
         .sort()
-        .map(entry => readFileSync(join(rulesRoot, entry), 'utf8'))
-        .join('\n\n');
+        .map(entry => {
+            const content = readFileSync(join(root, entry), 'utf8');
+            const fields = frontmatter(content);
+            return {
+                name: entry.split(sep).join('/'),
+                content,
+                profile: fields.get('profile')?.[0],
+                globs: [...(fields.get('applyTo') ?? []), ...(fields.get('paths') ?? [])],
+            } satisfies ManagedRule;
+        })
+        .filter(rule => matchesProfile(rule, selected));
+}
+
+/** Rules that apply to every file. These belong in the system prompt. */
+export function universalRules(cwd: string): ManagedRule[] {
+    return managedRules(cwd).filter(rule => rule.globs.length === 0 || rule.globs.some(glob => universalGlobs.has(glob)));
+}
+
+/** Rules whose `applyTo`/`paths` match a repository-relative path. These are delivered when that file is touched. */
+export function rulesForPath(cwd: string, relativePath: string): ManagedRule[] {
+    const normalized = relativePath.split(sep).join('/');
+    return managedRules(cwd).filter(rule =>
+        rule.globs.length > 0 &&
+        !rule.globs.some(glob => universalGlobs.has(glob)) &&
+        rule.globs.some(glob => globToRegExp(glob).test(normalized)));
 }
 
-/** Adds every managed Cratis rule to Pi without requiring the @cratis/pi package. */
+/** Upper bound on files considered from one bash command, so a wide command cannot deliver the corpus. */
+const maxPathsPerCommand = 10;
+
+/**
+ * Extracts file paths a bash command refers to. `rtk.md` tells agents to run `rtk read`, `rtk grep`
+ * and `rtk find` from the terminal for bulk reads, so file access frequently arrives as a bash
+ * command rather than the read tool; without this, a session that follows that rule would never
+ * receive a path-scoped rule. A token counts only when it resolves to a file that exists inside the
+ * working directory, which keeps a filename mentioned inside a commit message from matching.
+ */
+function pathsFromCommand(command: string, cwd: string): string[] {
+    const found: string[] = [];
+    for (const raw of command.split(/[\s;|&()<>]+/)) {
+        if (found.length >= maxPathsPerCommand) break;
+        const token = raw.replace(/^['"]+|['"]+$/g, '').replace(/[,:]+$/, '');
+        if (!token || token.startsWith('-') || !/[./]/.test(token)) continue;
+        try {
+            if (statSync(resolve(cwd, token)).isFile()) found.push(token);
+        } catch {
+            /* not a path we can see; ignore */
+        }
+    }
+    return found;
+}
+
+function touchedPaths(toolName: string, input: unknown, cwd: string): string[] {
+    if (toolName === 'bash' || toolName === 'powershell') {
+        const command = (input as { command?: unknown } | undefined)?.command;
+        return typeof command === 'string' ? pathsFromCommand(command, cwd) : [];
+    }
+    if (toolName !== 'read' && toolName !== 'write' && toolName !== 'edit') return [];
+    const candidate = (input as { path?: unknown; file_path?: unknown } | undefined);
+    const value = candidate?.path ?? candidate?.file_path;
+    return typeof value === 'string' && value.length > 0 ? [value] : [];
+}
+
+/**
+ * Gives Pi the same rule semantics as the other harnesses: universal rules in the system prompt, and
+ * path-scoped rules attached the first time a matching file is touched in the session. Without this,
+ * every rule was concatenated into every turn regardless of `applyTo`, `paths`, or `profile`.
+ *
+ * Delivery happens on `tool_result`, so a rule arrives after the call that first touched its file.
+ * `ToolCallEventResult` carries only `block`/`reason`/`terminate`, so there is no supported way to add
+ * context before a tool runs. In practice a file is read before it is edited, and reads through both
+ * the read tool and bash are covered, so the rule is present before the edit; a file created blind by
+ * `write` is the residual case, and it receives the rule with that result.
+ *
+ * A delivered rule lives in the conversation rather than the system prompt, so anything that rewrites
+ * or replaces the conversation can remove it. The delivery record is therefore reset whenever that
+ * happens, and the rule is delivered again the next time one of its files is touched.
+ */
 export default function (pi: ExtensionAPI): void {
+    const delivered = new Set<string>();
+
+    // Compaction summarizes the conversation, which can drop an injected rule while leaving the
+    // delivery record claiming it is present; a switch replaces the conversation outright. Without
+    // this reset a long session would silently lose its scoped rules and never see them again.
+    const reset = () => {
+        delivered.clear();
+    };
+    pi.on('session_start', reset);
+    pi.on('session_compact', reset);
+    pi.on('session_before_switch', reset);
+
     pi.on('before_agent_start', (event, context) => ({
-        systemPrompt: `${event.systemPrompt}\n\n${managedRules(context.cwd)}`,
+        systemPrompt: `${event.systemPrompt}\n\n${universalRules(context.cwd).map(rule => rule.content).join('\n\n')}`,
     }));
+
+    pi.on('tool_result', (event, context) => {
+        if (event.isError) return;
+        const paths = touchedPaths(event.toolName, (event as { input?: unknown }).input, context.cwd);
+        if (paths.length === 0) return;
+        const pending: ManagedRule[] = [];
+        const matched: string[] = [];
+        for (const path of paths) {
+            const relativePath = relative(context.cwd, resolve(context.cwd, path));
+            if (!relativePath || relativePath.startsWith('..')) continue;
+            for (const rule of rulesForPath(context.cwd, relativePath)) {
+                if (delivered.has(rule.name) || pending.some(candidate => candidate.name === rule.name)) continue;
+                pending.push(rule);
+                if (!matched.includes(relativePath)) matched.push(relativePath);
+            }
+        }
+        if (pending.length === 0) return;
+        pending.forEach(rule => delivered.add(rule.name));
+        const existing = Array.isArray(event.content) ? event.content : [];
+        return {
+            content: [
+                ...existing,
+                {
+                    type: 'text',
+                    text: `\n\n[cratis-rules] Rules that apply to ${matched.map(path => path.split(sep).join('/')).join(', ')}:\n\n${pending.map(rule => rule.content).join('\n\n')}`,
+                },
+            ],
+        };
+    });
 }

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/rules/ai-distribution.md

@@ -1,5 +1,7 @@
 ---
-applyTo: "**/*"
+applyTo: "**/.cratis/**"
+paths:
+  - "**/.cratis/**"
 ---
 
 # Shared AI Distribution

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).

package/package/corpus/rules/general.md

@@ -95,78 +95,13 @@ A claim is only as good as the signal behind it — a build result, a test run,
 - **Confirm "done"/"fixed"/"correct" against a fresh signal — never self-assessment.** Run the relevant gate and observe it pass *this time*.
 - **After a fix, re-run the gate that failed.** Don't argue yourself to green.
 - **A green build is not behavioral correctness.** Compilation proves it builds, not that the slice does the right thing — that's what specs and exercising the UI are for.
-- **Report with inspectable evidence, and name what you didn't verify.**
+- **Report the conclusion and what you didn't verify, in a line or two.** Show the output when asked, when a claim is contested, or when the check failed — see [verification-discipline.md](./verification-discipline.md).
 
 ---
 
 # 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).
+> **Building an application on Cratis?** Project layout, slice types, slice naming, the seventeen slice rules, the implementation workflow and the application quality gates are in [application-profile.md](./application-profile.md), which loads only for repositories that select an application profile. If you are contributing to a Cratis framework repo, see **Framework profile** below.
 
 ---
 
@@ -220,7 +155,7 @@ Documentation-only changes carry non-release intent and run the documentation ch
 - **Skills and rules are the authoritative answer.** If not answered there, ask. Don't infer Cratis behavior from package internals.
 - Only make high-confidence suggestions.
 - Don't change dependency manifests / lockfiles / `global.json` / NuGet config unless explicitly asked.
-- When asked to commit, push, create a PR, ship, or land changes, use the **ship-changes** prompt (`.cratis/ai/prompts/ship-changes.prompt.md`).
+- When asked to **ship** or **land** changes, use the **ship-changes** prompt (`.cratis/ai/prompts/ship-changes.prompt.md`); invoking it is what authorizes the branch → commits → push → PR → merge → cleanup chain it describes. A request to only commit, only push, or only open a PR authorizes exactly that step, under [Git commits](./git-commits.md) and [Pull requests](./pull-requests.md) — do not route it through ship-changes and do not add the later steps.
 
 ## General
 

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

@@ -8,6 +8,11 @@ A guard that cannot fail is worse than no guard: it converts "nobody looked" int
 check. Every line is tagged **[contract]** (binding) or **[convention]** (the house
 default) per the Three Levels of Authority in [`general.md`](./general.md).
 
+**Scope.** This rule governs two situations: *authoring* a scanner, guard, allowlist or
+checker, and *running a pass* that mutates a computed set of subjects rather than the
+targets the request named. An ordinary edit, review, fix, or a change to the one file the
+user pointed at is outside it and carries none of the machinery below.
+
 ## Non-vacuity
 
 - **[contract] A scan over a possibly-empty population carries a non-vacuity check.**
@@ -28,19 +33,28 @@ default) per the Three Levels of Authority in [`general.md`](./general.md).
 - **[convention] Prefer an expiry to a permanent exemption.** An entry nobody revisits is
   a rule quietly deleted.
 
-## Destructive passes
+## Bulk and irreversible passes
+
+These contracts are keyed to the *risk class* of the effect — bulk deletion, history
+rewriting, cross-repository migration, anything irreversible or high-fanout — not to
+whether a person is watching. An autonomous session runs them exactly as an interactive
+one does.
 
 - **[contract] Distinguish "subject set empty" from "qualifying set empty".** Finding no
   candidates at all is a different situation from finding candidates that none qualified;
-  an unattended pass must refuse to proceed on the first.
-- **[contract] Every unattended destructive pass carries a per-pass fuse** — a maximum
-  number of subjects it may act on in one run, which stops the run rather than trimming
-  the work silently.
-- **[contract] Prepare the inverse before the forward action.** If an exact inverse or a
-  safe compensation cannot be prepared, stop.
+  a pass must refuse to proceed on the first.
+- **[contract] Every pass carries a per-pass fuse** — a maximum number of subjects it may
+  act on in one run, which stops the run rather than trimming the work silently.
+- **[contract] Know the recovery before the forward action.** For a reversible effect,
+  know how it is undone. For an irreversible one, preserve what the recovery needs first —
+  a backup ref, a copy under `.ai-work/keep/`, the list of targets — and stop if nothing
+  can be preserved and the request did not name the targets. Do not demand an exact
+  inverse where none can exist.
 - **[contract] Re-read preconditions immediately before each mutation and stop when drift
   invalidates the authorized scope, safety assumptions, or recovery plan.** Benign drift
   within an already authorized bounded pass does not require another confirmation.
-- **[convention] Dry-run output is the review artifact for a destructive pass whose exact
-  targets were not already established in the conversation.** A user who has reviewed
-  and authorized those targets is not asked to approve the same pass again.
+- **[convention] When the targets were not already established in the conversation, show
+  the dry-run list and act on it once the user has answered.** A user who has reviewed
+  and authorized those targets is not asked to approve the same pass again. The list is a
+  message in the conversation, not a retained artifact: do not write receipts, ledgers,
+  snapshots or escrow copies of it.

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

@@ -21,6 +21,12 @@ dumps, and similar coordination files. These are **work records, not documentati
 - Knowledge that must outlive the session (real documentation, ADRs, operator
   guides) is written deliberately into the repository's documentation structure
   through normal review — not left behind as a work record.
+- **A worktree is a work record too.** Remove the worktree you created for a task
+  once its branch is merged to the default branch — pushed is not merged. Do it from
+  the parent checkout, after `git status --ignored` in the worktree, because a nested
+  `.ai-work/`, `.env` files and local databases are ignored and are deleted with it.
+  If the branch must outlive the task unmerged, leave the worktree and say so in the
+  handoff. Never `--force` a removal; a refusal means look, not push harder.
 - **A decision log is not a work record.** A decision — a durable choice with a
   decider and a date — is documentation: it lives in **`decisions/`** (or the
   repository's documented decisions folder) and is reviewed like any other

package/package/corpus/rules/profiles.md

@@ -1,3 +1,9 @@
+---
+applyTo: "**/.cratis/**"
+paths:
+  - "**/.cratis/**"
+---
+
 # AI Corpus Profiles
 
 Profiles determine which rules and skills apply to your work. They define the scope of the AI corpus and which documentation, conventions, and skills are available.

package/package/corpus/rules/rtk.md

@@ -1,6 +1,6 @@
 ---
 applyTo: "**/*"
-description: "Use when running any shell command, reading files, or searching code. Route every command rtk supports through rtk (a hook auto-rewrites Bash commands); call rtk read/grep/find directly because the built-in Read/Grep/Glob tools bypass that hook."
+description: "Use when running any shell command, reading files, or searching code. Route commands through rtk for human-readable output (a hook auto-rewrites Bash commands; prefix rtk yourself where it does not); use raw output when the result is parsed, compared exactly, or drives another operation."
 ---
 
 # Using rtk (Token-Optimized Commands)
@@ -9,11 +9,21 @@ description: "Use when running any shell command, reading files, or searching co
 
 ## How it works — let the hook do its job
 
-A `PreToolUse` hook **auto-rewrites Bash commands** to their `rtk` equivalent transparently and at zero token overhead (`git status` → `rtk git status`). For any supported command you do **nothing special** — run it normally and the hook wraps it.
+A `PreToolUse` hook **auto-rewrites Bash commands** to their `rtk` equivalent transparently and at zero token overhead (`git status` → `rtk git status`). For any supported command you do **nothing special** — run it normally and the hook wraps it. Where no hook is configured, prefix the command yourself — including each command in an `&&` chain: `rtk git add . && rtk git commit -m "msg"`.
 
-- **Never bypass it.** Don't disable the hook, and reserve `rtk proxy <cmd>` for the rare case where you genuinely need the raw, unfiltered output (e.g. debugging what a filter dropped).
 - **Audit coverage** with `rtk gain` (savings so far) and `rtk discover` (commands that slipped past rtk — missed opportunities to close).
 
+## When to use raw output instead
+
+rtk output is a summary for a reader. It is never evidence of exact file contents, paths, Git state, or command semantics, and a filter can drop the line you needed. Use the raw command — `rtk proxy <cmd>`, or the plain command where nothing rewrites it — whenever:
+
+- the output is parsed by a script, compared exactly, or fed to another command;
+- the output is the evidence for a claim about content, paths, or Git state;
+- the command's exit code or exact diagnostics decide what happens next (security checks, structured JSON, machine-readable diagnostics);
+- a wrapped command failed. Read the actual error and retry through `rtk proxy` before concluding the tool, path, or repository is missing.
+
+Do not add `rtk` to scripts, hooks, or CI steps that deliberately use native commands; their raw output is the point. Exit codes are never traded for token savings — see [`exit-codes-and-wrappers.md`](./exit-codes-and-wrappers.md).
+
 ## What rtk supports (route these through rtk)
 
 - **Files** — `ls`, `tree`, `read`, `find`, `grep`, `diff`

package/package/corpus/rules/verification-discipline.md

@@ -14,4 +14,10 @@ authored a file or preserve a chain of evidence about how it arrived.
 - Keep each check deterministic and runnable locally and in CI.
 - Never replace a real behavior check with a checksum, inventory, generated
   receipt, or provenance record.
-- Report failures and skipped checks honestly.
+- Documentary evidence — a receipt, ledger, attestation, hash inventory,
+  snapshot, escrow copy, or ad-hoc `verify-*` script — is not verification and
+  is not produced unless a repository workflow (such as a governed release) or
+  the user asks for it. The check's own output is the evidence.
+- Report the conclusion and any real uncertainty in a line or two, not the
+  audit trail. Show the output when asked, when a claim is contested, or when
+  the check failed. Report failures and skipped checks honestly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "2.23.0",
+  "version": "2.23.1",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [

package/package/corpus/rules/terminal-commands.md

@@ -1,19 +0,0 @@
----
-applyTo: "**/*"
-description: "Use when running any terminal command. Prefix every command with rtk -- including each command in an && chain -- so token-heavy output is filtered."
----
-
-# RTK (Rust Token Killer) - Token-Optimized Commands
-
-## Golden Rule
-
-**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
-
-**Important**: Even in command chains with `&&`, use `rtk`:
-```bash
-# ❌ Wrong
-git add . && git commit -m "msg" && git push
-
-# ✅ Correct
-rtk git add . && rtk git commit -m "msg" && rtk git push
-```