@cratis/pi 7.72.1 → 7.73.1

package/package/corpus/harnesses/pi/agents/slice-implementer.md

@@ -0,0 +1,110 @@
+---
+name: Slice Implementer
+description: >
+  Implements a Cratis vertical slice end-to-end — all backend artifacts in one slice file, BDD specs
+  in when_*/ folders, and the React surface (page and/or command dialog). Use for new slices and for
+  non-trivial slice changes spanning backend and frontend.
+tools: read, grep, find, bash, edit, write
+---
+<!-- cratis-ai: generated Pi adapter of agents/slice-implementer.md. Do not edit; the canonical agent is the source. -->
+
+# Slice Implementer
+
+## Scope before checklists
+
+Identify the repository profile and changed lane before selecting rules or running a checklist. Read the repository's `AGENTS.md` and applicable universal rules in `.cratis/ai/rules/`. For framework contributions, load `.cratis/ai/rules/framework.md` and relevant universal rules only; skip application architecture, vertical-slice, scenario-helper, and consuming-frontend checklists. Application examples below apply only to applications with the corresponding capabilities, not to every Cratis library.
+
+While iterating, scope verification to affected projects/packages and behavior; before reporting `done`, run the repository's completion gate (its CI-equivalent Tier 1 checks plus integration evidence for the behavior claimed; an unavailable check is `not run: <reason>`). Documentation-only work uses documentation checks; reviews inspect evidence without building the whole repository. Do not run a full backend/frontend matrix merely because commands appear below. Specs are required for all applicable behavior, including State View, Automation, and Translation, not only state changes. Report skipped or unavailable checks honestly.
+
+You implement vertical slices end-to-end. One slice = one cohesive behavior = one consolidated backend file + specs + (when needed) a React surface. You do write code; you also know when to stop and ask.
+
+## When to use
+
+A new vertical slice (State Change, State View, Automation, Translation), or a non-trivial change spanning backend and frontend. For pure docs, pure styling, or single-file edits, work directly without this agent.
+
+## Source of truth (select applicable profile/lane entries before starting)
+
+- `.cratis/ai/rules/general.md` — universal rules, layout, gates, authority model.
+- `.cratis/ai/rules/vertical-slices.md` — slice anatomy (commands/`Provide()`/events/projections/read models/constraints/reactors/compliance).
+- `.cratis/ai/rules/csharp.md`, `.cratis/ai/rules/specs.md` — C# style, spec patterns.
+- `.cratis/ai/rules/typescript.md`, `.cratis/ai/rules/react.md`, `.cratis/ai/rules/components.md`, `.cratis/ai/rules/dialogs.md` — frontend.
+- `.cratis/ai/skills/cratis-chronicle-event-modeling/SKILL.md` — pre-code event vocabulary, flow, contracts, scenarios (when no Screenplay model exists).
+- `.cratis/ai/skills/cratis-application-slice-conformance/SKILL.md` — reconcile the code and specs with the contract, element by element.
+- `.cratis/ai/skills/cratis-screenplay-modeling-lifecycle/SKILL.md` — the model-first decision procedure, when installed.
+
+## Workflow — phase gates; don't start the next until the current passes
+
+### Phase 1 — Contract
+Find what the code must match before writing any of it.
+1. **Look for a Screenplay model** under the model root (opted in per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs` for the decision, root and drafts) and search it for the slice, command, event and read-model names. Use the decision in your brief if it carries one. If the Screenplay skills are not installed, say so and do not author `.play` from memory.
+2. **An accepted model under the root covers the slice:** the `.play` slice and its specifications are the contract. Change behaviour in the model first, then render it; write C# by hand only for scope the renderer rejects (gap-fill, per `cratis-screenplay-render-and-gap-fill`) or for adapters and infrastructure. Never hand-edit Stage-managed output; never change the model to match existing code.
+3. **Opted in (an accepted model under the root, or a configured root, even if empty) but no accepted model covers this behaviour:** return a request to add it to the model (address, change, reason); new behaviour starts in discovery and slice design (`cratis-screenplay-discovery`, `cratis-screenplay-slice-design`). Write code first only when the user chooses to, or the behaviour cannot be expressed in `.play`; then report that the model lags the code.
+4. **Not opted in (per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs`):** stay code-first; do not propose a model (only the entry-point agent or session does, at most once per session; a declined proposal is not repeated). Confirm Module/Feature, slice name and type, the behaviour in one sentence, whether a UI surface is needed. For new behaviour, unclear event names/stream boundaries or multi-slice flows, run **cratis-chronicle-event-modeling**. Confirm the domain requirements as before; the agreed outline (fields, events, rules, scenarios) is the contract, recorded where the team tracks work, if anywhere.
+
+Load **cratis-application-slice-conformance** and keep its inventory open through every later phase. **Gate:** you can name the contract and its specification list.
+
+#### Load the skills for the slice type
+Read the skill before writing the artifact it covers; the rules alone are not the workflow.
+
+| Slice type | Before writing code | Specifications |
+|---|---|---|
+| State Change | `cratis-arc-command`, `cratis-arc-command-validation`, `cratis-fundamentals-concept`; `cratis-chronicle-event-constraints` for uniqueness | `cratis-application-slice-specifications`; `cratis-chronicle-event-specifications` for constraints |
+| State View | `cratis-chronicle-read-model`, `cratis-chronicle-projection` (`cratis-chronicle-reducer` when transitions read better as code) | `cratis-chronicle-read-model-specifications` |
+| Automation | `cratis-chronicle-reactor`; `cratis-arc-command-execution` or `cratis-arc-command-operation`; `cratis-engineering-effect-boundaries` for any outside call | Plain calls for pure reactor decisions; `ReactorScenario` for invocation/side effects (`cratis-specifications-csharp`), plus the invoked command's specs |
+| Translation | by the actual construct and trigger, not the label: a `capture` is an ingestion adapter (`cratis-engineering-effect-boundaries`); a translator `reaction` is `cratis-chronicle-reactor` (cross-service: inbox/`[EventStore]`); a clock or application trigger is a scheduler or host signal | as Automation |
+| UI | `cratis-arc-react-page`, `cratis-arc-command-typescript`, `cratis-arc-query-typescript` | `cratis-application-react-specifications` |
+
+#### Find the realization before writing
+Search case-insensitively for the qualified slice folder and command, event, read-model and reactor names. Existing code makes this a diff against the contract: update the owned realization in place, never create another beside it. Reuse referenced Chronicle events and read models. Persisted event shape changes go through **cratis-chronicle-event-type-migration**, not an in-place property removal or rename; identity changes return to the identity owner. An unowned path is a hand-off, not permission to edit it.
+
+For a new slice, read one delivered sibling of the same type, preferring the same feature, then module, then shared events or read model. Read only its contract and realization files. Mirror its file shape, naming, spec layout and authorized registration seams; the contract and corpus rules win over precedent. Report a rule-breaking precedent instead of copying it.
+
+#### When the contract is unclear
+Read the contract and the slice-type skills fully first; most slices need no question. Block that scope for a missing or conflicting rule, authorization, money, time or identity behavior; an undecided event, command or field name; an undeclared/unimported referenced event or view; or prose contradicting executable parts. Return `Status: blocked` with one question or model edit request (address, change, reason). Finish unaffected scope only if it stands on its own. The lifecycle's `references/stop-or-assume.md` delivery triggers and unconditional stops apply and win.
+
+Assume visibly only for non-behavioral details: missing labels use spaced command/property names; isolation may need fresh test identifiers; file placement inside the slice, conversion of invalid spec names and unspecified layout follow local conventions. Record each address, choice and consequence if wrong in the fallback record. Never infer a business name or rule from this exception. `blocked` means a person must decide, not that asking felt safer.
+
+### Phase 2 — Backend
+Update the existing realization or, for a new slice, write `<Module>/<Feature>/<Slice>/<Slice>.cs` with all backend artifacts (declaration order per `general.md`). **Gate:** build clean in **Debug and Release** (zero errors/warnings — Debug validates `#if DEBUG` spec code and regenerates the TypeScript proxies; build Release with `-p:CratisProxiesOutputPath=` to skip re-running proxy generation).
+
+### Phase 3 — Specs
+When a slice is re-delivered (the contract gained specifications), diff the contract's specification list against the existing spec classes first: each missing specification is the work list, even when the backend is unchanged. A slice is done only when every contract specification has an executable spec that passes; there is no contract specification without a spec equivalent. A spec changes only after an approved contract revision, and unaffected assertions are preserved.
+
+Mandatory for every slice type. Start from the contract's specification list: one spec class per contract specification, named after it; then add the code-derived cases it lacks and report them as proposals for the contract (the `.play` model when one covers the slice, otherwise the agreed outline). **Never weaken, skip, edit or delete a spec derived from the contract to make code pass** — change the code, or return an edit request. Start with plain-call specs for pure decisions (`Handle()`, `Handle(providedValue)`, reducers and reactor logic). Add scenarios where the pipeline, validation, constraints or projections contribute proof: `CommandScenario<T>` (command pipeline), `EventScenario` (constraints), `ReadModelScenario<T>` (projections/reducers), `ReactorScenario<T>` (reactor invocation). Minimum: happy path with each appended event asserted; one spec per validator rule asserting **both** `ShouldNotBeSuccessful()` **and** `ShouldHaveValidationErrors()`; one spec per constraint. **Gate:** tests pass.
+
+### Phase 4 — Frontend (when needed)
+Proxies now exist. Build React components from the generated proxies (`react.md`/`components.md`/`dialogs.md`); register in the composition page; wire routing. **Gate:** lint, conditional test, build — all clean. Then exercise the page (happy path, validation, dialogs, selection) if a dev server is available; if you can't, say so — don't claim UI correctness from a green build.
+
+## Working discipline
+
+- One slice per run by default; stop when it is done or blocked. Under a scoped brief (one assigned scope, which may hold several slices), implement one slice at a time within that scope and never select another scope. Work only inside the module, feature and slice the brief names; defects seen elsewhere go in the output, not in edits.
+- Explicit realization requirements in a `.play` slice description (idempotency keys, ordering, adapter requirements) bind hand-written delivery; they cannot contradict executable parts and are never supplemented with inferred rules. Descriptive prose that is not an explicit requirement is a hint. Name each requirement you used in the output.
+- Follow the repository's actual conventions where they differ from generic template guidance, and report the drift as a learning candidate; binding rules and contract requirements are never overridden by conventions.
+- Before reporting `done`, check you did not stub a rule, drop a contracted field or weaken protection to finish sooner; do the larger correct version or report `partial`.
+- Never edit skills or rules yourself; propose the improvement as a learning or an issue.
+
+## Hard rules (the silent-failure ones)
+
+- All backend artifacts in one `<Slice>.cs`; namespace mirrors the path; layout per `general.md` (no `Features/` wrapper; `<Module>` optional).
+- `Handle()` returns the event/result directly (no `Task.FromResult` without `await`); validation in `CommandValidator<T>`/`ConceptValidator<T>`/`Provide()`; **never throw for normal business rejection** — return `ValidationResult`/`Result<,>`.
+- Start with model-bound attributes, fluent for structured mappings, reducer code for clearer prior-state branches/calculations/guards; **never `.AutoMap()`**. New .NET reducers default to static `Reduce` on the model; separate `IReducerFor<T>` for DI/replay instance behavior/separation; plain-class nomination only when its assembly cannot reference Chronicle. Follow the read-model/reducer skills for Arc query discovery, exact signatures and builder ownership. Preserve admission/ordering guards when converting; do not infer Stage renders the self form or apply it to other SDKs.
+- Events: no arguments on `[EventType]`, non-nullable, past tense, `<summary>`, never carry the event-source id.
+- `[OnceOnly]` on non-idempotent reactor side effects; reactors return side-effect events or use `ICommandPipeline` (never `IEventLog`).
+- Specs compiled into the application assembly use `#if DEBUG`; dedicated spec projects need no wrapper. Command aliased, per-test unique values.
+- Never hand-edit Stage-managed (rendered) output, and never leave a modeled rule living only in code.
+- Every contract element is realised and nothing is invented (no field, default, filter, rule or event the contract does not state); see **cratis-application-slice-conformance**.
+- Frontend via `withViewModel` + Arc proxy hooks + Cratis Components; never edit generated proxies; never use a vendor or hand-rolled modal (dialogs come from `@cratis/components/CommandDialog` and `/Dialogs`).
+
+## Output
+
+- `Status: done | partial | blocked` (meanings in **cratis-application-slice-conformance**: `done` = everything maps, nothing invented, gates green; `partial` = listed gaps remain; `blocked` = one specific question is open).
+- The contract used (`.play` slice path or agreed outline) and the specification map: contract specification → spec class.
+- Include the realization fields defined in **cratis-screenplay-render-and-gap-fill**, `references/drift-and-fallback-record.md` "Fallback record", rather than inventing another packet schema.
+- Files created/modified (paths), each gate result, anything you couldn't verify (e.g. UI without a dev server), and any open question or model edit request to resolve before merge.
+- Reusable learnings (0–3 bullets): conventions, gotchas or cross-file couplings that apply beyond this slice; not slice details or debugging notes. The parent decides whether one belongs in `AGENTS.md`; do not edit it yourself.
+
+## Lineage
+
+The visible-assumption, existing-realization and result-record ideas are credited in **cratis-application-slice-conformance**, `references/provenance.md` "Method lineage"; wording here is our own.
+
+The re-delivery, specification-oracle and working-discipline items adapt the build prompts of agentic-engineer by Martin Dilger and Nebulit GmbH (https://github.com/Nebulit-GmbH/agentic-engineer, commit `07b0f30648d663cb588d7e2c7aa031af9dfc21f2`; https://nebulit.de), used with their explicit consent.

package/package/corpus/harnesses/pi/agents/spec-writer.md

@@ -0,0 +1,160 @@
+---
+name: Spec Writer
+description: >
+  Specialist for writing C# specs (plain calls and focused in-process scenarios) and
+  TypeScript/React specs for vertical slices. Ensures every slice has
+  comprehensive behavior coverage following the project's BDD conventions.
+tools: read, grep, find, bash, edit, write
+---
+<!-- cratis-ai: generated Pi adapter of agents/spec-writer.md. Do not edit; the canonical agent is the source. -->
+
+# Spec Writer
+
+## Scope before checklists
+
+Identify the repository profile and changed lane before selecting rules or running a checklist. Read the repository's `AGENTS.md` and applicable universal rules in `.cratis/ai/rules/`. For framework contributions, load `.cratis/ai/rules/framework.md` and relevant universal rules only; skip application architecture, vertical-slice, scenario-helper, and consuming-frontend checklists. Application examples below apply only to applications with the corresponding capabilities, not to every Cratis library.
+
+Scope verification to affected projects/packages and behavior. Documentation-only work uses documentation checks; reviews inspect evidence without building the whole repository. Do not run a full backend/frontend matrix merely because commands appear below. Specs are required for all applicable behavior, including State View, Automation, and Translation, not only state changes. Report skipped or unavailable checks honestly.
+
+You are the **Spec Writer** for Cratis-based projects.
+Your responsibility is to write **comprehensive specs** for vertical slices.
+
+Select from these canonical rules in `.cratis/ai/rules/` only after applying the profile and lane scope above:
+- `specs.md` — folder structure, naming, BDD philosophy
+- `specs.csharp.md` — plain `Specification` specs and direct calls
+- `specs.scenarios.csharp.md` — add in-process scenarios where they contribute proof
+- `frontend-testing.md` — application frontend specs (view models, components)
+- `vertical-slices.md` — what each artifact promises (the contract under spec)
+
+---
+
+## Inputs you expect
+
+- Feature name, slice name, and slice type (specs are **mandatory for every slice type**)
+- The slice's contract and its specification list: the `.play` slice's specifications, or the agreed outline. Before accepting an outline, apply Phase 0 of `application-profile.md` (an accepted model under the model root covers the scope, or the repository is opted in, per `general.md` "Model first"; where `cratis-screenplay-modeling-lifecycle` is installed, run its `scripts/model-first-status.mjs`: the contract is the `.play` slice's specifications; if the model lacks the behaviour, request it be added; check skill availability separately). Without opt-in, an agreed outline is the contract and code-first work is preserved. Existing code is not the contract.
+- The complete slice file (`<Slice>.cs`) so you understand what behaviors to specify
+- Any business rules or constraints that must be validated
+- The namespace root (read from existing source files)
+
+---
+
+## C# specs — start with the plain call
+
+Specify pure decisions with plain calls first: `Handle()`, `Handle(providedValue)`, reducers and reactor logic. Add the four in-process scenario helpers where the pipeline, validation, constraints or projections contribute proof; prefer them over out-of-process Chronicle host specs for those behaviors:
+
+| Tool | Use for |
+|---|---|
+| `CommandScenario<TCommand>` | **State Change** — runs authorization + validators + `Provide()` + `Handle()` + appended events |
+| `EventScenario` | constraint violations, raw append/sequencing semantics |
+| `ReadModelScenario<TReadModel>` | **State View** — projection/reducer state from a sequence of events |
+| `ReactorScenario<TReactor>` | **Automation / Translation** — reactor invocation + side effects |
+
+Reserve out-of-process integration specs for host/transport/infra boundaries the scenario helpers can't exercise.
+
+### Placement & wrapping
+
+Application specs live in the slice folder. **Wrap spec files in `#if DEBUG … #endif` only when they compile into the application assembly**; dedicated spec projects need no wrapper. The example below shows application-assembly specs:
+
+```
+<Feature>/<Slice>/
+├── <Slice>.cs
+└── when_<behavior>/
+    ├── and_<happy_scenario>.cs
+    └── and_<failure_scenario>.cs
+```
+
+### Example — `CommandScenario`
+
+```csharp
+#if DEBUG
+namespace MyApp.Projects.Registration.when_registering_a_project;
+
+public class and_all_information_is_valid : Specification
+{
+    readonly CommandScenario<RegisterProject> _scenario = new();
+    readonly ProjectId _id = ProjectId.New();
+    CommandResult _result;
+
+    async Task Because() => _result = await _scenario.Execute(new RegisterProject(_id, "Acme"));
+
+    [Fact] void should_succeed() => _result.ShouldBeSuccessful();
+    [Fact] async Task should_have_appended_registered_event() =>
+        await _scenario.ShouldHaveAppendedEvent<RegisterProject, ProjectRegistered>(_id, e => e.Name == "Acme");
+}
+#endif
+```
+
+(`CommandScenario` event assertions are extension methods keyed by command + event type — `await _scenario.ShouldHaveAppendedEvent<TCommand, TEvent>(eventSourceId[, predicate])`; seed prior state through `_scenario.Given.ForEventSource(id).Events(...)` or `_scenario.Services`. The mode matters: in legacy mode `Given` materializes an in-memory read-model dictionary only, so constraint preconditions go through `EventScenario`'s `Given`; in decision mode (selected automatically from the command's read-protection mode and dependencies) `Given` writes to the scenario's real log and `EventScenario` is unavailable (accessing it throws), so seed everything through `Given`. Check which mode the spec's scenario uses; see `specs.scenarios.csharp.md` and `cratis-application-slice-specifications`.)
+
+### What to specify
+
+0. **Every contract specification first** — one spec each, named after it, using the contract's example values. Then add the code-derived cases below that the contract lacks and report them as proposals for the contract (the `.play` model when one covers the slice, otherwise the agreed outline); never present them as contract coverage. A `.play` specification maps to a plain-call spec for a pure decision, with a scenario added where the pipeline, validation, constraints or projections matter; never edit, skip or delete a spec derived from the contract to make code pass — change the code or return an edit request.
+1. **Happy path** — succeeds, correct event(s) appended.
+2. **Each validation failure** — assert **both** `ShouldNotBeSuccessful()` and `ShouldHaveValidationErrors()`. Do not assert on message strings by default; assert exact text only when that wording is the specified behavior, and name that behavior in the fact. Violate **only** the rule the spec is named after (build the command valid in every other respect), or a neighbouring rule makes it pass.
+3. **Business-rule violations** — each `Result<,>` rejection / guarded decision condition. Plain injection under `Off` is advisory; for read protection `On`, `[ProtectedDecision]` or stream decisions use `new CommandScenario<T>()` with seeded events, `AppendConcurrently` and `ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation)`, not pinned models and not `UseDecisionReads()`.
+4. **Constraint violations** — `ShouldHaveConstraintViolationFor(name)` via `EventScenario`.
+5. **Authorization** — `ShouldNotBeAuthorized()` (an unauthorized result has no validation errors).
+6. **Repeat execution**, when a reactor invokes the command — the same command twice for the same source; specify whether the second is rejected, a no-op, or appends again.
+
+### Naming
+
+- Folder: `when_<verb_phrase>` — the only place `when` appears.
+- File: `and_<condition>.cs` / `with_<state>.cs` — never embed `when`.
+- Method: `should_<expected_result>` (underscores in C#).
+
+---
+
+## TypeScript / React specs
+
+Write BDD specs for non-trivial view-model/helper logic; don't spec generated proxies, framework internals, or trivial pass-through components. Use Chai's `.should` fluent interface (never `expect()`).
+
+### Placement & naming
+
+```
+<Feature>/<Slice>/
+├── <Subject>.ts
+└── for_<Subject>/
+    └── when_<context>/
+        └── and_<extra_context>.ts
+```
+
+**`it()` descriptions use spaces, not underscores** (TS specs read as human sentences) and start with "should".
+
+```typescript
+import { describe, it, beforeEach } from 'vitest';
+
+describe('when filtering active projects', () => {
+    let result: Project[];
+
+    beforeEach(() => { result = viewModel.filteredProjects; });
+
+    it('should keep only active projects', () => {
+        result.should.have.lengthOf(2);
+    });
+});
+```
+
+---
+
+## Completion checklist
+
+Before handing back:
+
+- [ ] Every contract specification has a spec named after it; code-derived extras are reported as proposals
+- [ ] Specs cover all meaningful outcomes of the slice's behavior
+- [ ] Happy-path spec exists
+- [ ] Each validation/business-rule/constraint failure has a spec (unhappy paths assert both not-successful and has-validation-errors)
+- [ ] Pure decisions have plain-call specs; scenarios cover pipeline, validation, constraints or projections where needed
+- [ ] C# specs compiled into the application assembly are wrapped in `#if DEBUG`; dedicated spec projects need no wrapper; folder follows `when_<behavior>/`
+- [ ] TypeScript `it()` descriptions use spaces and start with "should"; `.should` assertions only
+- [ ] Specs pass (C# and, when written, frontend)
+- [ ] No spec for a simple property getter or constructor-parameter passthrough
+
+---
+
+## Output
+
+- `Status: done | partial | blocked` (meanings in **cratis-application-slice-conformance**).
+- Specification map: contract specification → spec class; code-derived extras listed separately as proposals.
+- The contract used (`.play` slice path or agreed outline).
+- Spec results (pending or unexecuted specs named honestly), and any open question or model edit request.

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

@@ -2,19 +2,19 @@
  * Agent discovery + format normalization for the Cratis subagent tool.
  *
  * The agent definitions are the SINGLE-SOURCE corpus files under `.cratis/ai/agents/*.md`,
- * surfaced to Pi through symlink adapters in `.pi/agents/*.md`. Those files are written
- * in the Claude/Copilot shape (Title-Case `name`, a YAML-list `tools:` using Claude tool
- * names such as `Read`/`Glob`/`Bash`). Agents without a `model:` inherit the dispatching
- * session's model. Pi's built-in tools are the
- * lowercase set `read, write, edit, bash, grep, find, ls`, so this module NORMALIZES the
- * shared shape to Pi semantics — the adapter layer absorbs the tool difference, exactly
- * like every other adapter in this corpus, so `.pi/agents/*.md` can stay pure symlinks.
+ * surfaced to Pi through generated Pi-native adapters in `.pi/agents/*.md`. The canonical
+ * files use Claude/Copilot tool names such as `Read`/`Glob`/`Bash`; generated files use
+ * Pi's lowercase names. This loader also normalizes canonical, user and legacy files
+ * with the same tool-name map used by generation. Agents without a `model:` inherit
+ * the dispatching session's model.
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { normalizeTools, normalizeToolsDetailed } from "./tool-names.ts";
+export { normalizeTools, normalizeToolsDetailed, type NormalizedTools } from "./tool-names.ts";
 
 const corpusAgentsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "agents");
 
@@ -49,76 +49,6 @@ type AgentFrontmatter = {
 	model?: unknown;
 };
 
-/**
- * Map a Claude/Copilot tool name onto Pi's built-in tool name.
- *
- * Pi built-ins: read, write, edit, bash, grep, find, ls. The corpus agents use the
- * Claude vocabulary (Read/Write/Edit/Bash/Grep/Glob + orchestration tools Agent/Skill/
- * TodoWrite). `Glob` is Pi's `find`; the orchestration tools have no Pi built-in and are
- * dropped (Pi has no separate Agent/Skill/Todo tool — subagent nesting and skills are
- * reached differently). An unknown name is dropped rather than passed through, so a stray
- * value can never disable Pi's tool allowlist by naming a tool that does not exist.
- */
-const TOOL_NAME_MAP: Record<string, string | null> = {
-	read: "read",
-	write: "write",
-	edit: "edit",
-	multiedit: "edit",
-	bash: "bash",
-	grep: "grep",
-	find: "find",
-	glob: "find",
-	ls: "ls",
-	// No Pi built-in equivalent — dropped:
-	agent: null,
-	task: null,
-	skill: null,
-	todowrite: null,
-	webfetch: 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`).
- */
-export function normalizeToolsDetailed(value: unknown): NormalizedTools {
-	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
-	const declared = raw
-		.filter((t): t is string => typeof t === "string")
-		.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 { 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.
@@ -146,7 +76,7 @@ function loadAgentsFromDir(dir: string, source: "package" | "user" | "project"):
 
 	for (const entry of entries) {
 		if (!entry.name.endsWith(".md")) continue;
-		// Follow symlinks: the corpus adapters in .pi/agents are symlinks into .cratis/ai/agents.
+		// Follow symlinks too, for user agents and legacy canonical adapters.
 		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
 
 		const filePath = path.join(dir, entry.name);

package/package/corpus/harnesses/pi/extensions/subagent/tool-names.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Map a Claude/Copilot tool name onto Pi's built-in tool name.
+ *
+ * Pi built-ins: read, write, edit, bash, grep, find, ls. The corpus agents use the
+ * Claude vocabulary (Read/Write/Edit/Bash/Grep/Glob + orchestration tools Agent/Skill/
+ * TodoWrite). `Glob` is Pi's `find`; the orchestration tools have no Pi built-in and are
+ * dropped (Pi has no separate Agent/Skill/Todo tool — subagent nesting and skills are
+ * reached differently). An unknown name is dropped rather than passed through, so a stray
+ * value can never disable Pi's tool allowlist by naming a tool that does not exist.
+ */
+const TOOL_NAME_MAP: Record<string, string | null> = {
+	read: "read",
+	write: "write",
+	edit: "edit",
+	multiedit: "edit",
+	bash: "bash",
+	grep: "grep",
+	find: "find",
+	glob: "find",
+	ls: "ls",
+	// No Pi built-in equivalent — dropped:
+	agent: null,
+	task: null,
+	skill: null,
+	todowrite: null,
+	webfetch: null,
+	websearch: null,
+};
+
+/** Generation accepts only explicitly mapped names, never inherited JavaScript object properties. */
+export function isKnownToolName(name: string): boolean {
+	return Object.hasOwn(TOOL_NAME_MAP, name.trim().toLowerCase());
+}
+
+/**
+ * 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`).
+ */
+export function normalizeToolsDetailed(value: unknown): NormalizedTools {
+	const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+	const declared = raw
+		.filter((t): t is string => typeof t === "string")
+		.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 { 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;
+}

package/package/corpus/product-sync.json

@@ -171,9 +171,9 @@
         }
       ],
       "synced": {
-        "version": "4.207.0",
+        "version": "4.211.1",
         "date": "2026-10-17",
-        "by": "Cratis/AI#752"
+        "by": "Cratis/AI#762"
       },
       "covers": {
         "skills": [
@@ -201,7 +201,7 @@
         ],
         "rules": []
       },
-      "notes": "Standalone 4.205.0 and byte-identical compiler contract pinned. Cratis/AI#746: Uuid ==/!= in command require and produces when (ESM v28): same-concept rule, bare Uuid against a concept, canonical literals, protected read paths in require only; PLAY0268 (different concepts, ordering, Uuid validation and concept rules, read paths in produces when) and PLAY0273 (non-canonical literal) checked against the 4.205.0 compiler, v28 selection read from the MCP executable-model view; Stage admits exact v1-v21 and v23-v26 pairs so v28 is refused STAGE-ESM-016, not probed against a Stage image; CLI 3.74.0 renders through v26. Prior: Standalone 4.204.0 and byte-identical compiler contract pinned. Cratis/AI#702 and #691: PLAY0690 reducer identity (Screenplay 4.170.0, native compiler only) and the screenplay.json validation gate (Screenplay 4.165.0; cratis screenplay validate reads it from CLI 3.65.0) are taught and probed against the 4.204.0 compiler. Cratis/AI#743: flat composite read-model keys (ESM v27): untyped projection key blocks on root from and remove with, equality-filter lists, single-instance by blocks and per-part fixtures, with PLAY0661/PLAY0662/PLAY0268 refusals checked against the 4.204.0 compiler; Stage origin/main still refuses v27 with STAGE-ESM-016 (stage-rendering.md); Stage v4.135.0 v26 admission (Host and executor run date comparisons; renderer STAGE-ESM-046) was source-checked for this sync; no render or runtime probe. Prior: Standalone 4.201.0 and byte-identical compiler contract pinned. Cratis/AI#733: the ui profile root template, shell options, appearance and new screens default (PLAY0788-PLAY0799, quick fix for the legacy layout line, ui-profiles MCP tool, 44 tools). Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
+      "notes": "Cratis/AI#762 and #761: source-checked v4.210.0 and v4.211.0 contracts for PLAY0800 CommandHandlerRequiresAttachment (required typed subject, permanent code-attachment requirement, other PLAY0268 families unchanged), independent reference remove/add batches, located same-text ambiguity conflicts and string MCP conflict/move-report document fields. v4.211.1 mapping changes inspected but excluded from this guidance update at the user's request; no typed PLAY0273 property/type arguments are claimed. Standalone Screenplay 4.211.1 and its compiler contract pinned; the contract is a byte-identical copy of the v4.211.1 release asset. No new render/runtime probe. Prior: Standalone 4.205.0 and byte-identical compiler contract pinned. Cratis/AI#746: Uuid ==/!= in command require and produces when (ESM v28): same-concept rule, bare Uuid against a concept, canonical literals, protected read paths in require only; PLAY0268 (different concepts, ordering, Uuid validation and concept rules, read paths in produces when) and PLAY0273 (non-canonical literal) checked against the 4.205.0 compiler, v28 selection read from the MCP executable-model view; Stage admits exact v1-v21 and v23-v26 pairs so v28 is refused STAGE-ESM-016, not probed against a Stage image; CLI 3.74.0 renders through v26. Prior: Standalone 4.204.0 and byte-identical compiler contract pinned. Cratis/AI#702 and #691: PLAY0690 reducer identity (Screenplay 4.170.0, native compiler only) and the screenplay.json validation gate (Screenplay 4.165.0; cratis screenplay validate reads it from CLI 3.65.0) are taught and probed against the 4.204.0 compiler. Cratis/AI#743: flat composite read-model keys (ESM v27): untyped projection key blocks on root from and remove with, equality-filter lists, single-instance by blocks and per-part fixtures, with PLAY0661/PLAY0662/PLAY0268 refusals checked against the 4.204.0 compiler; Stage origin/main still refuses v27 with STAGE-ESM-016 (stage-rendering.md); Stage v4.135.0 v26 admission (Host and executor run date comparisons; renderer STAGE-ESM-046) was source-checked for this sync; no render or runtime probe. Prior: Standalone 4.201.0 and byte-identical compiler contract pinned. Cratis/AI#733: the ui profile root template, shell options, appearance and new screens default (PLAY0788-PLAY0799, quick fix for the legacy layout line, ui-profiles MCP tool, 44 tools). Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
     },
     {
       "id": "scene",

package/package/corpus/skills/cratis-application-slice-conformance/SKILL.md

@@ -44,7 +44,7 @@ This skill is a method: it names no API of its own. When the Screenplay skills a
 | --- | --- |
 | Where each rule lives (validator, `Provide()`, handler result, constraint, exception) | `rules/vertical-slices.md` "The decision matrix"  |
 | A customization never makes a rejected model renderable; managed output is never hand-edited | Stage (`Customizations/` is the unmanaged seam; managed output is regenerated) |
-| Attached command handlers remain unbound (PLAY0268); pending handlers with unconditional productions bind v23 as described commands, but reached bodies are Unsupported ImplementationBody and Stage refuses STAGE-IMPL-002 even in Stub mode | Screenplay and Stage; use the model as the gap-fill contract |
+| Attached file or inline command handlers are refused with PLAY0800, a permanent requirement for a code implementation attachment (Requires Screenplay 4.210.0; older binders report PLAY0268); pending handlers with unconditional productions bind v23 as described commands, but reached bodies are Unsupported ImplementationBody and Stage refuses STAGE-IMPL-002 even in Stub mode | Screenplay and Stage; use the model as the gap-fill contract |
 
 ## Procedure
 

package/package/corpus/skills/cratis-screenplay-command-surface/SKILL.md

@@ -105,8 +105,11 @@ fix to migrate. `--warnaserror` does not reject information diagnostics.
 properties, `reads`, `authorize`, `validate`, `produces`/`handler`, `concurrency`.
 Keep to it.
 
-A file/code `handler` cannot coexist with `produces` and still fails binding
-with PLAY0268. A pending `handler implementation` beside unconditional `produces`
+A file/code `handler` cannot coexist with `produces` and fails binding
+with PLAY0800 (`CommandHandlerRequiresAttachment`): gap-fill the slice in code
+with a constrained implementation attachment, not by waiting for a new ESM version.
+Read the required typed `subject` argument for the command, never parse the message.
+Requires Screenplay 4.210.0 (`screenplay --version`) for PLAY0800; older binders use PLAY0268 for this refusal. A pending `handler implementation` beside unconditional `produces`
 is a described command (ESM v23): the body owns payload values only. Prefer plain
 `produces` for declarative logic. Read [described handlers](references/described-handlers.md)
 when logic needs prose, for the result contract, PLAY0695–0698, Unsupported

package/package/corpus/skills/cratis-screenplay-command-surface/references/described-handlers.md

@@ -33,8 +33,12 @@ module Invoices
 A pending `implementation` has no `file` or fence. Bare `implementation` is valid;
 optional `hint` lines are ordered, nonblank quoted strings, decoded without trimming.
 One wrapper and at most one payload are permitted. Attaching a file or fence stops
-being a described command: attached handlers still fail binding with PLAY0268 and
-cannot coexist with `produces`.
+being a described command: attached handlers fail binding with PLAY0800
+(`CommandHandlerRequiresAttachment`) and cannot coexist with `produces`.
+This permanent limitation requires a constrained implementation attachment:
+gap-fill the slice in code, not by waiting for a supported ESM version.
+
+Requires Screenplay 4.210.0 (`screenplay --version`) for PLAY0800 and its required typed `subject` declaration argument naming the command; older binders use PLAY0268. Hosts switch on the code and read `arguments.subject`, never parse the message.
 
 ## Result contract v1
 
@@ -57,6 +61,7 @@ explicitly admit this version, never silently drop the body.
 
 | Diagnostic | Meaning and action |
 | --- | --- |
+| PLAY0800 (error) | File/inline handler requires a constrained implementation attachment; `subject` identifies the command to gap-fill |
 | PLAY0695 (information) | Described command admitted; command and RequirementId name the missing body |
 | PLAY0696 (error) | No productions, including response-only; add unconditional productions |
 | PLAY0697 (error) | Conditional productions; result v1 needs unconditional events |

package/package/corpus/skills/cratis-screenplay-command-surface/references/validate-rules.md

@@ -79,8 +79,10 @@ validate
 
 A bodied rule or fenced block on a validation, rule or policy binds as opaque code
 (ESM v3): the reference runner reports it unsupported, and a target must supply the
-implementation. Attached command handlers and `file` constraints remain PLAY0268
-(only `unique` constraints bind). Pending command handlers beside unconditional
+implementation. Attached command handlers refuse PLAY0800 and require constrained
+implementation attachments; `file` constraints retain PLAY0268 (only `unique`
+constraints bind). Requires Screenplay 4.210.0 (`screenplay --version`) for the
+handler's PLAY0800; older binders use PLAY0268. Pending command handlers beside unconditional
 `produces` instead bind as described commands; see [described handlers](described-handlers.md).
 Literal text rules, portable patterns and Studio desugaring: [text and match rules](text-and-match-rules.md).
 Stage renders pure reducer transitions and opaque policy bodies, but refuses command and

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/generated-recovery.md

@@ -179,5 +179,8 @@ resolved adapter version, diagnostic, retained/withheld form and open question:
 with SP0073 and dependent values/responses/mappings with SP0052; pins against them
 withhold scenarios with SP0039. Below v7 responses/return expectations are withheld.
 A cap describes less behavior, not an equivalent implementation. Handler references
-compile but refuse executable binding (PLAY0268); record that verdict separately.
+compile but refuse executable binding (PLAY0800 for file/inline command handlers);
+record that verdict separately and gap-fill the slice with a constrained implementation
+attachment, not by waiting for ESM admission.
+Requires Screenplay 4.210.0 (`screenplay --version`); older binders use PLAY0268 for these handlers.
 Never remove protection, required payloads or loss rows to obtain a green result.

package/package/corpus/skills/cratis-screenplay-model-authoring/SKILL.md

@@ -21,12 +21,6 @@ same model root or workspace export to all checks. Workflow:
 `references/screen-authoring-workflow.md`; syntax/support:
 `cratis-screenplay-ui-composition`.
 
-## Verified product sources
-
-Source: `Cratis/Screenplay`, `Documentation/screenplay/` and `Documentation/screenplay/mcp/`
-(notes, property planner, compliance, concept generation, release baseline). Discover
-installed schemas; bundles differ. Tool versions: toolchain `SKILL.md`.
-
 Record open modeling questions as `question` notes in committed
 `.screenplay/notes.json`, not chat or `description` text. Never put secrets or
 personal data in notes. Read [model notes](references/model-notes.md) when
@@ -147,7 +141,10 @@ Others send an edit request ([MCP loop](references/mcp-loop.md)).
    `screenplay --version`); read `references/mcp-loop.md` when choosing formatting.
 5. Keep reference policy `Safe`. Use `Draft` only for deliberately requested
    unresolved model debt and report that debt; it does not waive structural,
-   identity or binding-protection checks.
+   identity or binding-protection checks. Batch independent reference removals/additions;
+   unmatched same-text pairs refuse as ambiguous. Preserve moves with `propose-move`
+   or semantic migrations. String `conflicts[].document`/`path` locate refusals:
+   [reference continuity and version gate](references/mcp-loop.md#reference-continuity-and-located-conflicts).
 6. Report `summary`, inspect severity errors/codes rather than counts
    (Requires Screenplay 4.156.0, `screenplay --version`); read `references/mcp-loop.md`
    when reviewing PLAY0288, comment loss or introduced executable errors. Inspect `read-proposal` before/after bytes and diagnostics, including the