@cratis/pi 7.67.0 → 7.68.1

package/package/corpus/hooks/scripts/cratis-check-pr.mjs

@@ -4,9 +4,9 @@
 
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { Script } from 'node:vm';
 import { fileURLToPath } from 'node:url';
@@ -16,6 +16,7 @@ const commandTimeout = 15_000;
 const reviewedRulesRef = '40125b4fcae388e62ed9471edfffd0e991422f0a';
 const hookMode = process.argv[2] === '--hook';
 let claudeHook = false;
+let invocation = {};
 const hookWarnings = [];
 const warningLine = line => /^(::warning\b|::notice title=Release notes (?:drift )?not checked|Warning:)/.test(line);
 const warning = message => {
@@ -25,6 +26,23 @@ const warning = message => {
 const run = (command, args, options = {}) => spawnSync(command, args, {
     encoding: 'utf8', timeout: commandTimeout, maxBuffer: 32 * 1024 * 1024, ...options,
 });
+// A bare ENOENT cannot be told apart from a path resolved against the wrong directory, a copy of this
+// checker from another checkout, or a file that is not there yet. Naming all of those lets the next
+// occurrence be diagnosed instead of retried.
+function readBodyFile(value) {
+    const resolved = resolve(value);
+    try {
+        return readFileSync(resolved, 'utf8');
+    } catch (error) {
+        const parent = dirname(resolved);
+        const details = [`--body-file value: ${value}`, `path tried: ${resolved}`,
+            `parent directory exists: ${existsSync(parent)}`, `file exists now: ${existsSync(resolved)}`,
+            `checker working directory: ${process.cwd()}`,
+            ...Object.entries(invocation).map(([name, detail]) => `${name}: ${detail}`),
+            `checker script: ${fileURLToPath(import.meta.url)}`];
+        throw new Error(`cannot read the pull-request body file (${error.code || error.message}); ${details.join('; ')}`, { cause: error });
+    }
+}
 const gh = (args, options = {}) => {
     const result = run('gh', args, options);
     if (result.error || result.status !== 0) throw new Error(`gh ${args[0]} failed: ${result.stderr?.trim() || result.error?.message || result.status}`);
@@ -156,7 +174,7 @@ function check(argv, repositoryCallers, lookupOptions) {
     for (const label of split(values['add-label'])) labels.add(label);
     const intent = intents.filter(label => labels.has(label));
     if (intent.length !== 1) throw new Error(`Exactly one release-intent label is required (major/minor/patch/no-release); found ${intent.join(', ') || 'none'}.`);
-    const body = values['body-file'] ? readFileSync(resolve(values['body-file']), 'utf8') : pull.body || '';
+    const body = values['body-file'] ? readBodyFile(values['body-file']) : pull.body || '';
     let repository = values.repo;
     let defaultBranch = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']).replace(/^origin\//, '') || 'main';
     try {
@@ -324,6 +342,7 @@ function hook() {
     if (typeof text !== 'string' || !/\bgh\s+pr\s+(create|edit)\b/.test(text.replace(/\\\r?\n/g, ''))) return 0;
     // Match each simple command, never the same text inside an echo/grep argument.
     let cwd = payload.cwd || process.cwd();
+    invocation = { 'hook payload directory': payload.cwd || '(none)' };
     let knownDirectory = true;
     let parsed;
     try { parsed = commands(text); } catch (error) { if (!optedIn(cwd)) return 0; throw error; }
@@ -386,6 +405,7 @@ function hook() {
         if (targetedRepository) lookupEnvironment.GH_REPO = targetedRepository;
         else delete lookupEnvironment.GH_REPO;
         process.chdir(cwd);
+        invocation['command directory'] = cwd;
         const code = check(args, repositoryCallers, { env: lookupEnvironment });
         if (code !== 0 && code !== 3) throw new Error('The pull-request body or release intent failed cratis-check-pr. Fix the reported violations before retrying.');
     }

package/package/corpus/product-sync.json

@@ -201,7 +201,7 @@
         ],
         "rules": []
       },
-      "notes": "Standalone 4.204.0 and byte-identical compiler contract pinned. 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": "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-screenplay-model-authoring/references/state-and-recovery.md

@@ -4,6 +4,7 @@ This reference holds identity-state, journal and recovery rules and the readines
 
 ## Preserve state and recover explicitly
 
+`.screenplay/` is tool-owned; the only authored file beside it is `screenplay.json`, the validation gate, which no MCP operation writes.
 Commit `.screenplay/identities.json` with the model. Only `apply` writes it;
 `open-workspace` never creates it; text-only models have none. Never delete or
 overwrite conflicting identity state, silently mint IDs on restart, or text-rename

package/package/corpus/skills/cratis-screenplay-model-review/references/report-template.md

@@ -167,8 +167,8 @@ it. Verify the answer became a specification, a description or a project-owned
 decision record; a resolved note is not behavioral proof. Ask the owner to reanchor
 or resolve affected notes before source apply; resolution alone leaves an orphan.
 
-The optional `--open-questions fail` gate is a standalone `screenplay` option; the
-CLI-bundled compiler can lack it. Report it separately from V1–V5. Evidence: Screenplay
+The optional `--open-questions fail` gate exists on the standalone `screenplay` tool and on
+`cratis screenplay validate` (CLI 3.60.0 or later). Report it separately from V1–V5. Evidence: Screenplay
 `Documentation/screenplay/model-notes.md`,
 `Documentation/screenplay/mcp/reference.md`; source lines in the linked guide.
 

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/SKILL.md

@@ -75,7 +75,7 @@ or **critic** (P4-P5: strict, report first, fix in a separate batch).
 ## Verdicts (independent evidence, not a ladder)
 | Verdict | Meaning | Does not prove |
 |---|---|---|
-| V1 authorable | compiles, warnings as errors | meaning, binding |
+| V1 authorable | compiles, warnings as errors (declared gate) | meaning, binding |
 | V2 executable diagnostics | the executable model produces none | that specs run |
 | V3 binding-ready | the model binds | that any spec passes |
 | V4 reference specs run | engine, expected vs discovered | rendering or build health |

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/phases.md

@@ -109,7 +109,7 @@ phase, a decision important enough that a later reader could misread the model (
 ## P6 Accept (the user)
 - **Input**: the reviewed source identity.
 - **Carry-forward**: the accepted **source identity** (`verdicts-and-modes.md`).
-- **Commit at P6**: the accepted `.play` files and `.screenplay/identities.json` when present.
+- **Commit at P6**: the accepted `.play` files, `screenplay.json` (the authored validation gate) when the repository has one, and `.screenplay/identities.json` when present.
   The user commits, or explicitly authorizes the owning session to commit; the modeler never
   commits on its own. Run `cratis-screenplay-modeling-lifecycle`'s `scripts/model-first-status.mjs` to check acceptance, drafts and model changes in progress.
 - **Gate**: explicit acceptance and the model commit before P7-P9. After committing, recompute

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/stop-or-assume.md

@@ -64,7 +64,7 @@ consequential policy. Resolving is not implementation; a known refusal still
 needs `then error` or `then denied`. Reopen when the evidence ceases to answer it.
 
 Question gating is separate from V1: standalone Screenplay 4.144.0 has
-`--open-questions fail`; Cratis CLI 3.53.1 does not. Read toolchain
+`--open-questions fail`, and `cratis screenplay validate` has it from CLI 3.60.0. Read toolchain
 `references/verdicts.md` "Model notes gate" when a phase requires no open questions.
 Product evidence: Screenplay `Documentation/screenplay/model-notes.md`,
 `decisions/0045-model-notes-sidecar.md` and the model-authoring source table.

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/verdicts-and-modes.md

@@ -48,6 +48,11 @@ V5 rules:
 ## Commands (enough to check without loading the toolchain skill)
 - V1, preferred: `screenplay <model-folder> --warnaserror --no-color` (check "N file(s) compiled").
 - V1, fallback: `cratis screenplay validate <model-folder> --warnings-as-errors`.
+- The repository's gate file: V1 runs through a `screenplay.json` at the model root when one exists
+  (checks, warnings as errors, scope, open questions), so it is part of the verification contract.
+  Read the effective gate with `screenplay <model-folder> --print-gate`, name it on the V1 line, and
+  never bypass it with `--no-gate-file` without saying so. A refused file is `V1 not run: gate file
+  refused`, not a pass. Commands and precedence: toolchain `references/verdicts.md`.
 - V2, V3: the MCP workspace readiness and executable diagnostics.
 - Name tool and version on each line. A tool older than the model's constructs reports false
   failures; see the toolchain skill.
@@ -56,7 +61,7 @@ V5 rules:
 
 ```text
 Mode: executable   Source: <commit+digest from the source-identity helper> / ws <revision> cat <catalogRevision>
-V1 authorable:   pass (N files)                      | fail: PLAYnnnn at file:line - meaning
+V1 authorable:   pass (N files, gate: <screenplay.json or flags>) | fail: PLAYnnnn at file:line - meaning | not run: gate file refused
 V2 diagnostics:  none (executable model)             | n diagnostics | not run: <reason>
 V3 binding:      ready                               | blocked: PLAYnnnn ... | not run: design mode
 V4 specs:        12 expected / 12 discovered, 11 passed, 1 unsupported (route) | not run: no route

package/package/corpus/skills/cratis-screenplay-projections/SKILL.md

@@ -261,7 +261,9 @@ What the executable model does with it (ESM v3):
   rules is `PLAY0398`; two rules for one event is `PLAY0399`; a reducer with no
   bodies is rejected with a hint to write a projection.
 - The key is **always the event source id** — a reducer cannot route by an event
-  property. State starts at null; returning null deletes the instance.
+  property. State starts at null; returning null deletes the instance. A query
+  `by` another identity type warns `PLAY0690`; use a projection keyed on each `from`
+  or a join ([reducer identity](references/reducer-identity.md)).
 - The body is an opaque attachment identified by a content hash, never compiled
   or run by Screenplay. The reference runner cannot compute reducer state, so a
   specification that reads a reducer-built read model reports unsupported and

package/package/corpus/skills/cratis-screenplay-projections/references/reducer-identity.md

@@ -0,0 +1,88 @@
+# Reducer instance identity (PLAY0690)
+
+A reducer instance is keyed by the **event-source id** of the event it reduces. A reducer cannot be re-keyed by a payload value, a read-model `key` or a stream partition. A view that must be looked up by anything other than that event-source identity needs a projection.
+
+Requires Screenplay 4.170.0 or later (`screenplay --version`) for PLAY0690; an older compiler does not report it, so a clean run there does not clear the mismatch.
+
+## What PLAY0690 reports
+
+A warning (it fails `--warnaserror`) in two cases:
+
+- A reducer-backed query returns one instance `by` a scalar whose nominal type differs from the identity type of an observed event whose producers are all known, for example `by month Month` while the events live on `ResourceId` streams.
+- The producers of one reducer's events use several different nominal identity types, so no single identity can key the instances. One reducer warning replaces the repeated query warnings.
+
+This example reports PLAY0690 on `ByMonth`: the instances follow `ResourceId`, not `Month`.
+
+```screenplay expect PLAY0690
+concept ResourceId : String
+concept Month : String
+module Work
+  feature Reporting
+    slice StateView Totals
+      event Recorded
+        month Month
+        hours Decimal
+      readmodel Totals
+        month Month key
+        hours Decimal
+      reducer Fold => Totals
+        on Recorded
+          ```csharp
+          return context.State is null
+              ? new(context.Event.month, context.Event.hours)
+              : context.State with { hours = context.State.hours + context.Event.hours };
+          ```
+      query ByMonth => Totals optional
+        by month Month
+    slice StateChange Record
+      command Record
+        resource ResourceId identifier
+        month Month
+        hours Decimal
+        produces Recorded
+          for resource
+          month = month
+          hours = hours
+```
+
+## Fix
+
+To aggregate by a payload value, replace the reducer with a projection that declares a property key on each `from`. The read-model `key` and the `from` key then agree, and the warning is gone:
+
+```screenplay
+concept ResourceId : String
+concept Month : String
+module Work
+  feature Reporting
+    slice StateView Totals
+      event Recorded
+        month Month
+        hours Decimal
+      readmodel Totals
+        month Month key
+        hours Decimal
+      projection Fold => Totals
+        from Recorded key month
+          add hours by hours
+      query ByMonth => Totals optional
+        by month Month
+    slice StateChange Record
+      command Record
+        resource ResourceId identifier
+        month Month
+        hours Decimal
+        produces Recorded
+          for resource
+          month = month
+          hours = hours
+```
+
+When instances already exist under their own identity and another event only enriches them, use a [join](joins.md) instead: it updates the existing instances and never creates one. There is no automatic repair from a reducer to a projection.
+
+## What the check compares
+
+- It compares declared **nominal** identity types (`Month` and `ResourceId` differ even though both wrap text), never property names, primitive backing, stream ids or fixture values. Equal types do not prove equal runtime ids, and distinct concepts can hold equal values, so a finding is a likely modeling mistake rather than proof.
+- It compares only where the producer is known: a command production with `for`, an implicit or generated command identifier, and a reaction production with an explicit `for`. All producers across the application count, after source and stream filters and production-route overrides.
+- Not compared (unknown provenance): a plain `produces` without `for` (it lands on an identity the request allocates), a reaction without `for`, captures, seeds and code. An unknown producer suppresses the query comparison for that event.
+- Collection queries, performer-served or unbuilt views, projection-backed views and public-event reducer targets do not trigger it.
+- It is a native C# compiler diagnostic: the standalone tool, `cratis screenplay validate` (when its bundled compiler is new enough) and MCP diagnostics report it. The TypeScript compiler and editors only pass through findings the host supplies, so a clean editor is not evidence.

package/package/corpus/skills/cratis-screenplay-projections/verification.json

@@ -16,6 +16,7 @@
     { "kind": "skill-contains", "value": "**routes nothing** (`PLAY0381`)" },
     { "kind": "skill-contains", "value": "The key is **always the event source id**" },
     { "kind": "skill-contains", "value": "**A join never creates an" },
-    { "kind": "skill-contains", "value": "Inline code uses a tagged fence" }
+    { "kind": "skill-contains", "value": "Inline code uses a tagged fence" },
+    { "kind": "skill-contains", "value": "PLAY0690", "file": "references/reducer-identity.md" }
   ]
 }

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

@@ -186,6 +186,10 @@ Specs pass `by` and filters by name (PLAY0468 for unknown, repeated or missing
 required arguments); collection results match by read model/key regardless of
 row order. Details and renderer limits: [equality filters](references/equality-filters.md).
 
+A reducer-built view is keyed by event-source id, so a single-instance `by` of another
+nominal type warns `PLAY0690`. Rebuild it as a projection keyed on each `from`: projections
+[reducer identity](../cratis-screenplay-projections/references/reducer-identity.md).
+
 ## `screen` — three levels
 
 The examples below are excerpts: each screen sits in a slice, and the queries,
@@ -303,6 +307,7 @@ binding failures are errors.
 - [ ] Every authorized query has a specification with `given caller`, including a
       `then denied` case.
 - [ ] Each read model has exactly one builder and every field traces to an event.
+- [ ] A reducer-built view's `by` type matches its events' event-source identity (`PLAY0690`).
 - [ ] No screen reference is left ambiguous or unresolved.
 - [ ] Every UI binding that consumes screen data (component context, toolbar
       parameter, dialog input, outlet route) has a source in the screen contract

package/package/corpus/skills/cratis-screenplay-slice-design/SKILL.md

@@ -38,8 +38,7 @@ Ask the batch below only for what the request leaves open: (1) origin of each ac
 ## Procedure
 
 1. **Fix the mode** for the scope (`cratis-screenplay-modeling-lifecycle`): design, executable
-   or renderable. It decides which shapes you may use (steps 6, 9). Read the existing model
-   before adding to it.
+   or renderable. It decides which shapes you may use (steps 6, 9). Read the existing model first.
 2. **Find each event's origin.** For every event ask who or what makes it happen and through
    which path: a persona's screen `action` or form, a reaction's `invokes`, a capture. The
    origin must be **reachable** (some screen, form, reaction or integration leads to the
@@ -54,8 +53,7 @@ Ask the batch below only for what the request leaves open: (1) origin of each ac
    separate reasons change these values, then split (`references/slicing.md` *Generic edits*).
    One input per thing the caller decides or supplies; `identifier` on the property naming the
    instance (omit only for allocation); inline `produces event <Name>` (no `for`) when the command owns the event; plain `produces <Name>` needs `for <identifier>`. Trace each input
-   (`references/field-lineage.md`) and list the values each rule reads: input, state or context
-   (`references/command-inventory.md`). A conditional input is a granularity question: two
+   (`references/field-lineage.md`) and list the values each rule reads: input, state or context. A conditional input is a granularity question: two
    decisions are two commands; one decision with a dependent rule is an implication
    (`require a == false or b > c`). Never a boolean attestation input (`confirmsX == true`)
    standing in for a rule. Place each rule in its layer (`references/rule-layers.md`). A rule
@@ -89,7 +87,7 @@ Ask the batch below only for what the request leaves open: (1) origin of each ac
 6. **Design the read side** (`references/read-model-design.md`). Enumerate every screen and
    automation first: one read model per screen component or automation need; the typical
    slice is `read model -> screen -> command -> event`. Pick the builder (declarative projection first, reducer when
-   guards cannot be expressed). The query follows the business view: a list where people scan a
+   guards cannot be expressed; a lookup `by` another identity type warns `PLAY0690`). The query follows the business view: a list where people scan a
    list, a keyed lookup where they open one thing. For **executable or renderable scope**, every
    read model needs one unambiguous identity: explicit trailing `key` first. Read `references/read-model-design.md` ("Executable identity of a read model") for the fallback order, the key decision table and the Stage rule.
 

package/package/corpus/skills/cratis-screenplay-slice-design/references/read-model-design.md

@@ -130,7 +130,10 @@ Observable delivery does not make a materialized projection decision-consistent;
 decision needs a guarded read (`rule-layers.md`, `cratis-screenplay-streams-and-consistency`). Prefer a
 declarative projection (mappings, event joins, counters, bounded children, removals); a join
 consumes event facts, not another read model. Use a reducer when prior-state, attempt or
-ordering guards cannot be expressed declaratively. Review every writer of a property: AutoMap
+ordering guards cannot be expressed declaratively, and the view is only ever looked up by the
+event-source identity: a reducer cannot be re-keyed, so a query `by` another identity type warns
+`PLAY0690`; aggregate by a payload value with a projection keyed on each `from`, or a join
+(projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md)). Review every writer of a property: AutoMap
 can introduce updates from other events. Use variants only when lifecycle stages have different
 shapes. Keep growing histories in a separate view; never combine several people's PII under
 one read-model instance (compose queries across person-scoped views instead).

package/package/corpus/skills/cratis-screenplay-toolchain/SKILL.md

@@ -39,6 +39,10 @@ superseded statement needs context; exceptions do not change the contract.
 2. **Check the folder, warnings as errors.** `screenplay <folder> --warnaserror` or
    `cratis screenplay validate <folder> --warnings-as-errors`. Warnings hide defects:
    PLAY0029 (a misspelt keyword or a `type` inside a slice) drops a construct silently.
+   A committed `screenplay.json` at the model root declares the repository's gate (checks, warnings
+   as errors, scope, open questions): run without repeating those flags (confirm with
+   `--print-gate` before dropping `--warnaserror`), read it with
+   `--print-gate`, and treat a refused file as "could not run" (`references/verdicts.md`).
 3. **Pick the compiler deliberately and name it.** Standalone `screenplay` for
    language checks and reference specifications; `cratis` for rendering
    and generation. Report both tool and version, rather than transferring a verdict across
@@ -63,6 +67,7 @@ superseded statement needs context; exceptions do not change the contract.
 | --- | --- | --- |
 | Check root | `screenplay <root> --warnaserror --no-color` | `cratis screenplay validate <root> --warnings-as-errors -o json-compact` |
 | Scope/checks | `--scope <address>`, `--check <names>`; a scoped pass is not whole-application success | `validate --executable` (bundled binder, no write), `--check <names>`, `--scope`; `render --scope`/`--check`; `cratis screenplay conform` |
+| Declared gate | `screenplay <root> --print-gate`, `--format json`, `--no-gate-file` | `validate <root> --print-gate`, `--no-gate-file`; the same `screenplay.json` |
 | Reference execution | `screenplay test <root>` or MCP `run-specifications` | Discover bundled MCP capability; target tests are not V4 |
 | MCP | `screenplay mcp <root>`; discover schemas | `cratis screenplay mcp [root]`; registered by `cratis ai install` |
 | Render boundary | Binder admission is not Stage admission | The CLI renders only ESM versions it knows; a newer bound model gets `CLI-RENDER-004` |

package/package/corpus/skills/cratis-screenplay-toolchain/references/cheat-sheet.md

@@ -2,6 +2,7 @@
 
 ## Contents
 
+- Validation commands and the gate file
 - Samples and preview fixtures
 - Lexical and structural rules
 - Exact numeric source mode
@@ -57,6 +58,20 @@ by `for_Documentation/when_comparing_the_grammar_against_the_parsers.cs`),
 Screenplay CI (`when_compiling_every_example.cs`) against repository main: the standalone
 compiler; the compiler bundled in `cratis` can be older and lack the newest ESM versions.
 
+## Validation commands and the gate file
+
+```shell
+screenplay <root> --warnaserror --no-color      # V1; also reads <root>/screenplay.json
+screenplay <root> --print-gate                  # effective gate and each value's source, no compile
+screenplay <root> --format json                 # one JSON report: diagnostics, gate, exitCode
+screenplay <root> --no-gate-file --check all    # bypass the file for one run
+screenplay test <root>                          # V4
+```
+
+`screenplay.json` (authored, beside `.screenplay/`) holds `validation.checks`, `warningsAsErrors`, `scope`
+and `openQuestions`; unknown keys or check names are refused (exit 2), never ignored. Details and
+precedence: [verdicts](verdicts.md).
+
 ## Samples and preview fixtures
 
 Invoicing is a warning-free syntax showcase, not a runnable whole-language proof.

package/package/corpus/skills/cratis-screenplay-toolchain/references/diagnostics.md

@@ -8,6 +8,7 @@
 - Explicit enum member numbers
 - Reserved stored names and event pins
 - Named keys, production routes and observer filters
+- Reducer instance identity (PLAY0690)
 - Caller identity, compliance and routes
 - Specification metadata, callers, cases and locators
 - Guarded interaction diagnostics
@@ -146,6 +147,16 @@ Overrides/filters select released ESM v10; malformed routes also use PLAY0504.
 Read read-surface `references/named-keys.md` and
 [production routes and filters](production-routes-and-filters.md).
 
+## Reducer instance identity (PLAY0690)
+
+| Code | Severity | Meaning / fix |
+| --- | --- | --- |
+| PLAY0690 | W | A reducer instance is keyed by the event-source id, so a reducer-backed scalar query `by` another nominal type, or a reducer whose complete producers use several identity types, warns. Reducers cannot be re-keyed: use a projection with a property key on each `from`, or a join for existing instances |
+
+Fails `--warnaserror`. Compares declared nominal types only where producers are known (command `for`, implicit or generated identifiers, reaction `for`); plain `produces` without `for`, reactions without `for`, captures, seeds and code are not compared. Native C# only: a clean editor proves nothing. Example and limits: projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md).
+
+Requires Screenplay 4.170.0 or later (`screenplay --version`); an older compiler does not report it, and `cratis screenplay validate` reports it only when its bundled compiler is that new.
+
 ## Caller identity, compliance and routes
 
 | Code | Severity | Meaning / fix |
@@ -309,8 +320,8 @@ identity details (0633–0646), compliance/subject checks, reaction identity
 A shared catalog code is not proof that a check is implemented in both compilers.
 
 C# CLI/MCP owns whole-application scoped diagnostics, opt-in completeness
-(including PLAY0530–0537, PLAY0602–0606 and PLAY0652), bound reaction gate
-checks PLAY0650/0651, semantic binding and PLAY0546 (a negated claim targets optional,
+(including PLAY0530–0537, PLAY0602–0606 and PLAY0652), reducer identity
+PLAY0690, bound reaction gate checks PLAY0650/0651, semantic binding and PLAY0546 (a negated claim targets optional,
 unavailable-subject or non-text data). The VS Code repair bridge is not a general
 C# validator. A clean editor is not V1 for the complete application, V3 binding
 or V4 execution. Run the CLI or MCP for those verdicts.

package/package/corpus/skills/cratis-screenplay-toolchain/references/traps.md

@@ -69,3 +69,4 @@ Traps 39 to 44 are tool traps.
 42. A symlinked model path is refused by the MCP server (macOS `/tmp` is a symlink); pass the physical path. Proposals are connection-local (at most 16); `apply` persists identities to `.screenplay/identities.json` and is not crash-atomic across files; never retry `apply` after `ApplyOutcomeUnknown`.
 43. `modelRevision` is canonical semantic (line positions and descriptions do not change it; a file move only if it changes logical placement or application identity) and, without `identities.json`, changes with the root folder name; it is not comparable with a render's `semanticRevision`. Source identity for verdicts is the commit plus the digest from the source-identity helper (`cratis-screenplay-modeling-lifecycle` `references/verdicts-and-modes.md` "Source identity").
 44. `cratis render` neither builds nor tests; `--name` is required for plain source; `.cratis-render/` is control state and is never staged; rendered apps pin their own Arc and Chronicle versions (`[ProtectedDecision]` is available to gap-fill, not automatically emitted). `cratis` file mode versus folder mode (trap 6) and a stale `cratis` on `PATH` (`which -a cratis`) both silently change what a verdict means.
+45. A reducer cannot be re-keyed: its instances follow the event-source id, so a query `by` another identity type warns PLAY0690 (`--warnaserror` fails it; editors only show it when the host supplies native findings). Aggregate by a payload value with a projection keyed on each `from`, or a join: projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md).

package/package/corpus/skills/cratis-screenplay-toolchain/references/verdicts.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - V1: authorable
+- Declared validation gate (`screenplay.json`)
 - Release-baseline gate (independent of V1–V5)
 - V2: executable diagnostics
 - V3: binding-ready
@@ -51,8 +52,67 @@ render, V1 and V5 from the CLIs. Read installed versions with `screenplay --vers
 - Warnings are failures here. PLAY0029 (a construct dropped silently) and the unresolved-name
   warnings are the defects this verdict exists to catch.
 - Syntax and consistency checks (PLAY0282 to PLAY0294) run; binding does not.
+- A `screenplay.json` at the model root supplies checks, warnings-as-errors, scope and open-questions
+  mode to both commands above, so they need not repeat those flags; drop `--warnaserror` only when
+  `--print-gate` shows `warningsAsErrors: true`. Read the effective gate before
+  reporting (next section).
 - Report: `V1 pass (screenplay <version>, 3 files)`, `V1 fail: PLAY0029 in a.play, line 12`.
 
+## Declared validation gate (`screenplay.json`)
+
+A repository declares its V1 gate once, in an authored `screenplay.json` at the model root,
+beside the tool-owned `.screenplay/`. Prefer it to repeating `--check`, `--warnaserror`,
+`--scope` and `--open-questions` in every script: every run then enforces the same gate.
+`screenplay.json` is the only file there people write; no tool creates or edits it.
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/Cratis/Screenplay/main/Documentation/screenplay/screenplay-v1.schema.json",
+  "validation": {
+    "checks": ["field-origins", "query-keys", "navigation"],
+    "warningsAsErrors": true,
+    "scope": "Workspaces.Tracking",
+    "openQuestions": "fail"
+  }
+}
+```
+
+- Every member is optional. A `checks` item is one check name, diagnostic code or `all`
+  (never a comma list); `all` expands to every check the running tool supports, so an upgrade can
+  strengthen the gate, while an explicit list pins it. `openQuestions` is `report` or `fail`;
+  omitted means notes are not evaluated.
+- The model root is the nearest folder at or above the target (a file's parent) that holds
+  `screenplay.json` or `.screenplay/`. The search includes but never crosses the first folder with
+  `.git`; with no match the target folder is the root and the defaults apply. Nested models keep
+  their own gates; imports never affect the search.
+- A command-line option replaces only its own setting. Omitting `--warnaserror` keeps
+  `warningsAsErrors: true`, and any `--check` replaces the file's whole list. `--no-gate-file`
+  ignores the file, even an invalid one; a relaxed run is not the repository's gate, so say so.
+
+| Need | Standalone | `cratis screenplay validate` |
+| --- | --- | --- |
+| Effective gate and the source of each value, no compile (exit 0 unless the file is refused) | `screenplay <root> --print-gate` (text) | `--print-gate` (text, or the gate object under `-o json`) |
+| Machine-readable verdict | `--format json`: one document with `diagnostics`, `openQuestions`, `refusal`, `exitCode`, `gate` | `-o json-compact`: the summary carries `gate` |
+| Ignore the file | `--no-gate-file` | `--no-gate-file` |
+
+Each gate value reports `commandLine`, `file` or `default` as its source. Report the gate with
+the verdict: `V1 pass (screenplay <version>, gate screenplay.json: field-origins, query-keys,
+warnings as errors, 3 files)`.
+
+**A refused gate file is "could not run", never a pass or a fail.** Malformed JSON, a duplicate
+member, an unknown key, an unknown check name or a wrong type is refused as invalid, and a
+directory, symlink or unreadable file is refused as unreadable; neither is ignored or repaired. The
+standalone tool exits **2** and the CLI exits **1**, each with `path:line:column`. Report
+`V1 not run: gate file refused (<path:line:column>)`, fix the file and rerun.
+A scope declared in the file combined with `cratis screenplay validate --executable` also exits 1:
+check binding separately or pass `--no-gate-file` and name it.
+
+Requires Screenplay 4.165.0 or later (`screenplay --version`) for `screenplay.json`, `--format`,
+`--print-gate` and `--no-gate-file`; an older tool does not read the file and runs without the
+gate, so a clean result there says nothing about it. `cratis screenplay validate` reads the file
+from Cratis CLI 3.65.0 or later (`cratis --version`); an older CLI ignores it, so use the standalone
+tool for the gate.
+
 ## Release-baseline gate (independent of V1–V5)
 
 Run `screenplay baseline check <model-root>` before accepting edits to released event
@@ -180,9 +240,10 @@ What Stage admits: `renderable-subset.md`.
 
 | Layer | Route | Result |
 | --- | --- | --- |
-| Source validation | `screenplay <root> --warnaserror --no-color` | 0 clean; 1 reported defects; 2 could not run or invalid arguments or input. `--scope` limits the reported set, not compilation |
+| Source validation | `screenplay <root> --warnaserror --no-color` | 0 clean; 1 reported defects; 2 could not run or invalid arguments or input, including a refused `screenplay.json`. `--scope` limits the reported set, not compilation |
+| Declared gate | `screenplay <root> --print-gate`; `--format json`; `--no-gate-file` | Reads `screenplay.json`; `--print-gate` exits 0 without compiling unless the file is refused; a gate-promoted warning or an open question in `fail` mode exits 1 |
 | Completeness | add `--check <name>[,<name>]` (repeatable) or `--check all` | Opt-in warnings; whole-source errors skip checks, not pass them |
-| CLI source validation | `cratis screenplay validate <root> --warnings-as-errors -o json-compact` | Read the producer exit and the JSON errors, warnings and file count |
+| CLI source validation | `cratis screenplay validate <root> --warnings-as-errors -o json-compact` | Read the producer exit and the JSON errors, warnings and file count; 5 validation error (including gate-promoted warnings), 1 invalid input (including a refused `screenplay.json`) |
 | Binding | MCP workspace readiness and `executable-diagnostics` | V2 reads diagnostics; V3 requires binding with no blocking diagnostics |
 | Reference specifications | `screenplay test <root> [--filter <address>] [--format text\|json]`, or MCP `run-specifications` (`specification`, `scope`, `offset`, `limit`, `expectedSourceRevision`, `proposalId`) | 0 all selected passed; 1 failed; 2 invalid arguments, input, selection or IO; 3 unsupported or unbound. Counts of zero do not prove coverage |
 | Release baseline | `screenplay baseline admit <root> --release <label>`; `screenplay baseline check <root>` | 0 success; 1 changed or missing revision; 2 unavailable, unreadable or invalid input or write failure |
@@ -221,7 +282,7 @@ change ESM or V1–V5 verdicts. Read model-authoring
 [model notes](../../cratis-screenplay-model-authoring/references/model-notes.md) when
 recording, resolving, paging or reviewing orphan impact.
 
-Requires Screenplay 4.144.0 or later (`screenplay --version`) for `--open-questions`; `cratis screenplay validate` has no such option, so use the standalone tool for this gate.
+Requires Screenplay 4.144.0 or later (`screenplay --version`) for `--open-questions`. `cratis screenplay validate` accepts the same option from Cratis CLI 3.60.0 or later (exit 5 when a question remains in `fail` mode, 1 when notes are unreadable); with an older CLI use the standalone tool. `validation.openQuestions` in `screenplay.json` selects the mode without the flag.
 
 ## Revisions and descriptions
 

package/package/corpus/skills/cratis-screenplay-toolchain/verification.json

@@ -16,7 +16,13 @@
     { "kind": "skill-contains", "value": "the **whole source, stream and stream id**", "file": "references/production-routes-and-filters.md" },
     { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "Requires Screenplay 4.144.0", "file": "references/verdicts.md" },
-    { "kind": "skill-contains", "value": "`cratis screenplay validate` has no such option", "file": "references/verdicts.md" },
+    { "kind": "skill-contains", "value": "accepts the same option from Cratis CLI 3.60.0", "file": "references/verdicts.md" },
+    { "kind": "skill-contains", "value": "A refused gate file is \"could not run\"", "file": "references/verdicts.md" },
+    { "kind": "skill-contains", "value": "Requires Screenplay 4.165.0 or later", "file": "references/verdicts.md" },
+    { "kind": "skill-contains", "value": "Cratis CLI 3.65.0 or later", "file": "references/verdicts.md" },
+    { "kind": "skill-contains", "value": "--print-gate", "file": "references/cheat-sheet.md" },
+    { "kind": "skill-contains", "value": "PLAY0690", "file": "references/diagnostics.md" },
+    { "kind": "skill-contains", "value": "Requires Screenplay 4.170.0 or later", "file": "references/diagnostics.md" },
     { "kind": "skill-contains", "value": "--open-questions fail", "file": "references/verdicts.md" },
     { "kind": "skill-contains", "value": "unreadable notes exit **2**", "file": "references/verdicts.md" },
     { "kind": "skill-contains", "value": "MCP/CLI only, **no PLAY code**", "file": "references/verdicts.md" },

package/package.json

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