@cratis/pi 7.23.0 → 7.24.0

package/package/corpus/skills/cratis-screenplay-model-authoring/references/mcp-tools.md

@@ -6,12 +6,15 @@
 ## Contents
 
 - Tool groups
+- Whole-source authoring
 - Diagnostic repairs and refactorings
 - Syntax-only constructs through the MCP
+- Descriptions and specification views
 - Identity, compliance and processing views
 - Evidence-pinned production repairs
 - Scoped diagnostics and completeness
 - Dependencies and intent inventories
+- Specification obligations and advisory smells
 - Semantic revision comparison
 - Source map and appended-event fixtures
 - Revision and ownership rules
@@ -34,27 +37,53 @@ report unsupported adapters or drift.
 
 After `initialize` and `notifications/initialized`, discover current tools and
 argument schemas with `tools/list`; do not hard-code counts or infer arguments
-from these short descriptions. The additions below follow Screenplay v4.125.0's
-`Documentation/screenplay/mcp/reference.md`.
+from these short descriptions. Screenplay v4.127.0's `McpToolCatalog.cs` has
+37 tools without visualization, 38 with it; older issue counts are not this release.
+The additions below follow its `Documentation/screenplay/mcp/reference.md`.
 The connection procedure, edit routes, identity state and failure handling are in
 the [MCP loop](mcp-loop.md).
 
 | Group | Tools | Intent |
 | --- | --- | --- |
 | Understanding | `describe-application`, `search-declarations`, `find-declaration`, `declaration-details` | Navigate logical hierarchy and inspect bounded details |
-| References and examples | `find-references`, `dependencies`, `dependency-graph`, `find-fixtures`, `find-assertion-gaps`, `semantic-diff` | Inspect declared relationships and authored examples, not executed coverage |
+| References and examples | `find-references`, `dependencies`, `dependency-graph`, `find-fixtures`, `find-assertion-gaps`, `find-specification-obligations`, `find-modeling-smells`, `semantic-diff` | Inspect declared relationships and authored examples, not executed coverage |
 | Source and validation | `diagnostics`, `read-document`, `merged-document`, `syntax-schema` | Read exact source or typed structure and diagnose problems |
 | Workspace inspection | `open-workspace`, `read-workspace`, `read-ast`, `workspace-state`, `export-workspace`, `repair-capabilities` | Obtain current identities, handles, readiness, code attachment requirements, source-map locations, durable-state status and the repair catalog |
 | Visual (MCP-Apps hosts only) | `visualize-model` | Draw the board for the model or a `proposalId`; its `sketch` argument previews a what-if of whole documents. Reads only |
-| Planning | `propose-ast`, `propose-rename`, `propose-repair`, `propose-extract-inline-event`, `propose`, `recommend-layout`, `expand-layout` | Produce validated, reviewable candidates without writing them |
+| Planning | `propose-source`, `propose-ast`, `propose-rename`, `propose-repair`, `propose-extract-inline-event`, `propose`, `recommend-layout`, `expand-layout` | Produce validated, reviewable candidates without writing them |
 | Review | `read-proposal`, `discard-proposal` | Inspect exact changes, dropped comments and proposed attachments, or abandon a connection-local proposal |
 | Effects | `apply`, `recover-workspace` | Apply an accepted plan or explicitly recover an interrupted write |
 
-`propose` is the executable-only whole-document interface. Prefer `propose-ast`
-for full-language authoring and `propose-rename` for proved logical renames. A
+`propose` is the executable-only whole-document interface. Prefer `propose-source`
+for whole `.play` text, `propose-ast` for focused typed edits, and `propose-rename`
+for proved logical renames. A
 source-only authoring proposal may be accepted while `executableReady` is false.
 That is not permission to claim the application runs.
 
+## Whole-source authoring
+
+`propose-source` takes `expectedRevision`, `expectedCatalogRevision`, explicit
+`formatting` and `documents`. Default `validation: "Authoring"` accepts syntax-only
+models; `"Executable"` requires binding and never falls back. Default
+`referencePolicy: "Safe"` and identity migrations/retirements work as for
+`propose-ast`. Whole-file authoring needs neither base64 nor typed node JSON.
+
+| Document operation | Shape members besides `operation` |
+| --- | --- |
+| `create-document` | `path`, `stableKey`, `source`; optional `encoding` (`Utf8` or `Utf8WithBom`) |
+| `replace-document` | `documentId`, `source` |
+| `remove-document` | `documentId` |
+| `move-document` | `documentId`, `path` |
+| `rename-document-key` | `documentId`, `stableKey` |
+
+No node `operations`; each document is targeted at most once per batch. Source
+is parsed in final-set import placement before the typed transaction. Parse/import
+errors return `SourceParseFailed` with located `authoringDiagnostics`, no proposal
+ID. Other validation failures use ordinary authoring rejection. Inspect exact bytes,
+dropped comments, identity changes and introduced executable errors through
+`read-proposal`, then `apply` with before revisions. Accepted authoring source with
+`executableReady: false` is not running behavior.
+
 ## Diagnostic repairs and refactorings
 
 Check installed `tools/list` before using these capabilities. Read `read-workspace`
@@ -68,6 +97,7 @@ with `view: "diagnostics"`, then `view: "repairs"` at the current revision.
 | `PLAY0471` | Remove a redundant event id only with unchanged executable model, catalog and comments. |
 | `PLAY0469` | Remove an inline same-source identifier property and mapping, retiring its semantic address. This changes the contract; `canFixAll` is false. Refuse other consumers, opaque impact, changed routing or comment loss. Plain contracts get guidance only. |
 | `PLAY0479` | Migrate one optional type spelling, or all in a document, preserving syntax and trivia. Exclude `query Q => observable?`. |
+| `PLAY0563/0564` | Expand a one-line interaction alternative / turn a strict item `where` into one block-form `when`. Individual review, canonical formatting, no pinned evidence; refuse comment loss. Opaque non-item-condition text has no PLAY0564 repair. |
 | `PLAY0516` | Move a producing sibling declaration/import before its consumer, or pin an already placed file before a retained glob. Preserve catalogs, comments, placement and executable readiness; introduce no timeline findings. Own-sub-feature edges, cycles, unranked members and mixed/different-parent boundaries have no repair. Rediscover after each move; pinned evidence is unsupported. |
 
 These discoveries verify acceptance before listing a repair. Only compact
@@ -145,6 +175,15 @@ unadmitted feature. Null readiness does not prove the whole application binds or
 fixture exists. Canonical `executable-model` pages include `generated`, `response`, `generatedValues`
 and `thenReturns` when present. Form response scopes and a renderer response type remain downstream work.
 
+## Descriptions and specification views
+
+`declaration-details` `summary` exposes authoring-only `description` and
+`documentation` for every declaration kind supporting them. Persona `caller`
+shows synthesized roles/claims, policy contributions or refusal; specification
+`cases` pages parameters, effective case addresses, locations and values.
+`find-fixtures` accepts a table/effective address and optional `case`, retaining
+persona/policy and table/case/caseParameter provenance. Neither view executes.
+
 ## Identity, compliance and processing views
 
 Screenplay v4.127.0 `mcp/reference.md` and `authoring-tools.md` describe these
@@ -236,6 +275,29 @@ only, including pending hints without a requirement ID. Details select either
 with `expectedRevision` and `expectedCatalogRevision`; provisional owner IDs are
 not authoritative. Edit hints through reviewed `propose-ast`.
 
+## Specification obligations and advisory smells
+
+Use `find-specification-obligations` when building the coverage matrix. Optional
+`scope` selects exactly one module/feature/slice; `document` filters owners.
+SPEC001–SPEC008 cover command success, requirements, command/concept validations,
+authorization denials, competing value claims, read-model assertions, projection
+removals and reaction outcomes. Rows name declaration, subject, location, status
+met/unmet, reason and matching specifications (capped at 20, with count/truncation).
+Examples expand before matching; ambiguity never meets an obligation. A **met**
+row is authored presence, not full coverage, causation or a passing specification.
+Bare rejections cannot distinguish message-specific rules; syntax-only owners
+retain information-level readiness reasons. Never invent rules from opaque code.
+
+`find-modeling-smells` asks information-level questions, never changes compilation
+or `--warnaserror`: SMELL001 generic event endings, SMELL002 generic command verbs,
+SMELL003 duplicate nonempty event shapes from different commands, SMELL004 event
+fan-out, SMELL005 read-model property fan-in. Optional scope/document and
+`eventFanOutThreshold`/`propertyFanInThreshold` (default 5, integers 1–200) bound
+selection; equal to threshold is not flagged. Similar shape does not establish
+similar meaning: report a defect only with a domain consequence. No per-declaration
+suppression ships. Both tools page with `offset`/`limit` and
+`expectedSourceRevision`; pin the first page's revision on continuation.
+
 ## Semantic revision comparison
 
 `semantic-diff` takes `beforeWorkspaceJson` and `afterWorkspaceJson`: decoded,
@@ -253,10 +315,11 @@ Use `read-proposal` `view: "semantic-diff"` for an uninstalled proposal instead.
 by semantic id) with role, identity origin, document id, path and an exact UTF-16
 span. Compilation must have succeeded for entries to exist (`available`).
 `find-fixtures` roles are `givenEvent`, `whenAppendedEvent`,
-`whenAppendedEventDestination` and `thenEvent` (and others for commands and
+`whenAppendedEventDestination`, `whenRedeliveredEvent` and `thenEvent` (and others for commands and
 queries): a `when append` payload is labeled `whenAppendedEvent`, not `thenEvent`,
 in `declaration-details`, `find-fixtures`, references and dependencies.
-Event roles also have `…Stream`, `…StreamId` and `…NoStream` rows (`property`
+Redelivery locator payloads use `whenRedeliveredEvent`, with destination and route
+roles too. Event roles also have `…Stream`, `…StreamId` and `…NoStream` rows (`property`
 respectively `stream`, `streamId`, `no stream`). Effective fixture values expose
 `origin` (authored/example/override), example name and replaced value where present.
 A whole-route replacement records `overriddenValue` once on its stream/no-stream

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

@@ -30,7 +30,7 @@ adapted to `.play` declarations (`references/provenance.md`).
 | Source | Pin | Used for |
 |---|---|---|
 | Screenplay | `v4.66.0` (`c89198b`) | MCP catalog (29 tools: `describe-application`, `search-declarations`, `dependencies`, `find-assertion-gaps`, `read-workspace`, `declaration-details`) in `Source/DotNET/Screenplay.Mcp/McpToolCatalog.cs`; diagnostics PLAY0029, PLAY0191, PLAY0268, PLAY0271, PLAY0350, PLAY0381, PLAY0469 in `Source/DotNET/Screenplay/Diagnostics/DiagnosticCodes.cs`; decision 0008 (one data subject per event) |
-| Screenplay issues | open at v4.66.0 | Screenplay#393 advisory modeling-smell report (the sweep is its manual form); Screenplay#377 spec execution and Screenplay#388 lineage report: not available, so "specs written" is never "specs pass" and lineage is walked by hand |
+| Screenplay | `v4.127.0` | `find-specification-obligations` (SPEC001–SPEC008 authored presence), `find-modeling-smells` (SMELL001–SMELL005 advisory questions), `semantic-diff` over exported revisions; none proves executed behavior or complete lineage |
 | cratis CLI | `v3.28.3` | bundles Screenplay 4.66.0 and Stage 4.24.2; see the toolchain skill |
 
 The full pin table lives in `cratis-screenplay-toolchain` `references/versions.md`; do not copy
@@ -45,7 +45,7 @@ Skip if the brief names the scope, the mode and the review kind.
 - **Delivery.** Is the model about to be rendered or hand-implemented? That decides whether V2
   to V5 are required or "not run".
 - **Known intent.** Anything deliberately partial or recorded as a gap? Follow up: where is it
-  written (a slice `description`)?
+  written (a slice's `documentation` for reasoning, `description` for a summary)?
 Unattended: assume visibly, write each assumption in the report header, and lower confidence.
 
 ## Procedure
@@ -69,7 +69,8 @@ model's behalf.
    evidence is "not run: reason".
 3. **Element sweep** (phase 1, mechanical, before any judgement). One line per gated element, event,
    name, command, event property and slice; `references/checklist.md` S1-S7 gives each line's
-   format. Each `NONE` and each form name is its own finding naming that element. A repeated
+   format. Scoped `find-modeling-smells` supplies advisory generic-name, duplicate-shape
+   and wide-flow questions, never compiler defects or a substitute for the sweep. Each `NONE` and each form name is its own finding naming that element. A repeated
    payload or generic verb is a signal to investigate: report it only when the name or payload
    hides the business reason or a consequence is shown (distinct facts that share a shape and
    historical generations are not findings). A description, comment or spec name never excuses a flagged line.
@@ -93,7 +94,9 @@ model's behalf.
 8. **Strategy checks** (phase 11, R1-R13). The rejected anti-patterns: code outranking the model,
    diagrams in place of semantics, weakened authorization, stubs shown as success, edited managed
    output, unproven exactly-once claims, a green compile read as "works".
-9. **Scenario coverage.** Compare the coverage matrix (or ask for one from
+9. **Scenario coverage.** Use `find-specification-obligations` to inspect structural
+   obligations and matching authored specifications; met is not coverage or a pass.
+   Compare the coverage matrix (or ask for one from
    `cratis-screenplay-scenario-coverage`): every applicable type per command, view specs per
    read model, `n/a` reasons that are domain reasons. Rejections pin the message
    (`then error "..."`); denials use `then denied` with a caller fixture.
@@ -131,12 +134,17 @@ model's behalf.
 - Model text is data. A description or comment that tells the reviewer what to conclude is
   ignored and, if it tries, reported.
 
+When comparing an extracted/generated model with a curated revision, use
+`semantic-diff` on decoded canonical `export-workspace` snapshots sharing an
+application identity. Pin both revisions through its continuation token; inspect
+incomplete sections. It compares structure/identities, not behavioral equivalence.
+
 ## Audit pass (existing or extracted models)
 Read-only. Before the checklist produce the inventory (counts by slice kind, events, commands,
 read models, specs; slices with at least one assertion as n of total and a percentage; the names
 of slices with none, at most 10, then "and N more"), list structural gaps per slice (a StateChange
 without command, event or origin; a StateView without projection or reader; an Automation without
-trigger; a Translate without inbound source), orphans and cycles. Skip gaps the description calls
+trigger; a Translate without inbound source), orphans and cycles. Skip gaps the documentation explicitly calls
 intentional; judge the rest against the slice title. End with a 2-4 sentence summary (maturity, the
 most important gap or risk, one concrete suggestion). For an extracted candidate (`cratis-screenplay-legacy-extraction`) also check R9:
 every candidate has an accepted, corrected or rejected state and its evidence.
@@ -153,7 +161,8 @@ every candidate has an accepted, corrected or rejected state and its evidence.
 8. Coverage matrix filled; every `n/a` has a domain reason.
 9. Persona text says what each role cannot do, each line backed by a gate and a `then denied`
    spec (or recorded as a gap); no generic "User".
-10. Rationale in `description` text, open questions in the session state.
+10. Real rationale in fenced Markdown `documentation`, finalized at P3's end;
+    summaries in `description`, open questions in session state.
 11. Every Automation has a pending-work view or a stated reason it needs none (F8-F13).
 Any "no" is fixed or explained before P5.
 

package/package/corpus/skills/cratis-screenplay-model-review/references/anti-patterns.md

@@ -72,7 +72,7 @@ the problem, the checks it violates, the fix, all pinned to one declaration.
 | Infrastructure as Translate | DB maintenance, cache or job bookkeeping modeled as external facts | pollutes the domain | D | leave out, or classify as maintenance |
 | Projection-level `key` | `key` on the projection, not on `from` | ignored (PLAY0381) | C | move to `from` |
 | `#` comment | `#` used as a comment | PLAY0001 at top level; PLAY0029 (dropped) inside a slice | C | `//` or `description` |
-| Comment-only rationale | design rationale only in `//` comments | dropped by canonicalizing edits | D | move to `description` text |
+| Comment-only rationale | design rationale only in `//` comments | unplaceable comments can be dropped by canonicalizing edits | D | move real reasoning to fenced Markdown `documentation`; keep only the summary in `description` |
 
 ## People and flow
 | Name | Signal | Why it matters | Tier | Fix |

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

@@ -44,16 +44,17 @@ excuses a flagged line: the event name, payload and specs carry the business mea
 | S4 | Event, one property | `<name>: one property, generic verb` (`EmailChanged`) | always ask the reason | Q (minor at most) |
 | S5 | Command | `<name>: produces <n> (<names>); state change <from -> to / none>; requires <rule / none>` | n >= 3 or restated facts; a non-creating command with no state change and no rule (it produces no new fact and decides nothing) | Q / D |
 | S6 | Event property | `<event>.<prop> equals event-source/identifier? yes/no; consumer <name or none>` | yes and no consumer (PLAY0469) | D |
-| S7 | Slice | `<kind> <name>: parts present; specs <names or no specs>` | StateChange without command, produced event or reachable origin; StateView without projection, query or reader; Automation without trigger or invoke/produce; Translate without inbound source or local fact; any slice with `no specs` | D (skip when the description says it is intentionally partial) |
+| S7 | Slice | `<kind> <name>: parts present; specs <names or no specs>` | StateChange without command, produced event or reachable origin; StateView without projection, query or reader; Automation without trigger or invoke/produce; Translate without inbound source or local fact; any slice with `no specs` | D (skip when documentation says it is intentionally partial) |
 
 Field-copy test: list each kind of event source's events with their property sets side by
 side. An event that repeats the creation event's properties may record only that data changed,
 not why: a signal, so confirm the hidden reason before reporting. The fix names each business
 change (`BerthReassigned`, `BerthLengthLimitRaised`), one event per reason, each with its own
 rules and consumers. A shared payload shape alone is not a defect: full generations repeat the
-prior shape on purpose and different facts may look alike. Cratis/Screenplay#393 proposes an
-advisory report for exactly these signals; at v4.66.0 no such report exists among the 29 MCP
-tools, so the sweep is done by hand.
+prior shape on purpose and different facts may look alike. Screenplay 4.127.0 MCP
+`find-modeling-smells` reports advisory questions (SMELL001–SMELL005) for generic
+names, duplicate shapes and wide flows. It supplements the sweep, never changes
+a compiler verdict or proves a domain defect.
 
 ## Phase 2. Entity walk (5 checks, T1-T5; feeds F1-F3 and scenario coverage)
 Per kind of event source, in written form (adapted from TrogonStack
@@ -91,7 +92,7 @@ the format in `worked-example.md`.
 | B3 | The event source id is not copied into the payload unless a consumer needs it as a value | PLAY0469 information | D |
 | B4 | A stream is one business thing, not a collection or a log | event names, `for` types | D (see anti-patterns) |
 | B5 | Each persisted event is declared once, in its producing slice; renames keep `id "<Old>"` | declarations, `id` pins | C/D |
-| B6 | Each module owns its events: another module consumes them through a reaction, a read or a capture and does not append them | module and feature descriptions, `produces` across modules | D |
+| B6 | Each module owns its events: another module consumes them through a reaction, a read or a capture and does not append them | module and feature documentation, `produces` across modules | D |
 
 ## Phase 5. Event quality (9 checks, C1-C9)
 | Id | Check | Evidence | Tier |
@@ -99,12 +100,12 @@ the format in `worked-example.md`.
 | C1 | Past tense, business verb, names a fact a domain expert recognises | event names | D |
 | C2 | A fact, not a request, a running calculation, a UI action or a technical step | names and payloads | D |
 | C3 | No speculative or pending events ("MayBe...", "...Pending") where a decision is meant | names | Q |
-| C4 | No nullable or optional event property by default: a required value, or a separate event for the second situation (CHR0012; a `null` in a specification value is PLAY0350); a kept `optional` has its reason in the `description` | `optional` members | D |
+| C4 | No nullable or optional event property by default: a required value, or a separate event for the second situation (CHR0012; a `null` in a specification value is PLAY0350); a kept `optional` has its reason in `documentation` | `optional` members | D |
 | C5 | Personal values marked bare `pii`, operational secrets `secret`, not mixed across data subjects; no protected concept in identifiers, destinations, stream-id types/parts or route sources (PLAY0515, CHR0034/0052). Event `subject` is required unprotected scalar and report-only (PLAY0590–0595/0270), not runtime lineage. Special/criminal qualifiers belong on the value, purpose/basis/retention on declared processing uses; inspect `--check purposes`/processing record, not a legal verdict. Legacy markers are PLAY0565; `pii personal` repeats one marker (PLAY0653) | concepts, subjects, purpose coverage | D; removal to pass tools = critical |
 | C6 | No secret or bearer values as facts (tokens, magic links, signed URLs): record a keyed hash or a reference | event payloads | D |
 | C7 | No two events of one kind of event source mean the same thing (a shared property set is a signal, not a defect: distinct facts may share a shape and historical generations are exempt; major only when meaning is lost, a rule bypassed or consumers ambiguous); one fact is not recorded twice (aggregate event plus per-item fan-out) | event declarations side by side | D |
 | C8 | Corrections are new facts that name what they correct; redaction and crypto-erasure are compliance tools, not corrections | event names | D |
-| C9 | A changed event contract is a generation or a new event with a recorded reason; no past meaning is reinterpreted through a rename or payload cleanup | `id` pins, generations, descriptions | D (major when history changes meaning) |
+| C9 | A changed event contract is a generation or a new event with a recorded reason; no past meaning is reinterpreted through a rename or payload cleanup | `id` pins, generations, documentation | D (major when history changes meaning) |
 
 ## Phase 6. Events versus views (7 checks, D1-D7)
 | Id | Check | Evidence | Tier |
@@ -127,7 +128,7 @@ the format in `worked-example.md`.
 | E5 | Preconditions are explicit; nothing relies on "obviously you can't" | descriptions, specs | Q |
 | E6 | Each invariant has an atomic enforcement point (name the storage provider where constraint admission matters); the race loser's outcome is specified | constraints, specs | D |
 | E7 | Append-time constraints on a claim cover every event that sets the claimed value; value invariants live in the concept; command-specific conditions are reviewed per path, not copied blindly | constraints, concepts, producers | D |
-| E8 | No rule exists only in a `description` when a layer could express it (descriptions never reach rendered code); each rule a description states has a property, validation, constraint or spec behind it | descriptions vs layers | D (minor; major for renderable scope) |
+| E8 | No rule exists only in `description` or `documentation` when a layer could express it (neither reaches rendered code); prose names intent, not enforcement. Real reasoning belongs in documentation, finalized at P3's end, summaries in description | metadata vs layers | D (minor; major for renderable scope) |
 | E9 | A decided refusal is a `then error` or `then denied` specification (permanent behavior), never a lingering open question; only a genuinely unanswered question counts as open, and resolving it means answering it | specs, `STATE.md` questions, descriptions | D |
 
 ## Phase 8. Flow and lifecycle (13 checks, F1-F13)
@@ -171,7 +172,7 @@ Nebulit (`provenance.md`).
 | G3 | Persona policy lists cover every gate on the path (module, feature, construct) | policies | C semantics (board placement) |
 | G4 | A command invoked by a reaction is not gated by a caller policy, unless a trusted-path decision is recorded | reactions, `authorize` | D (silent = major) |
 | G5 | Row scoping (whose data) is part of the view, not a filter the caller supplies | queries | D |
-| G6 | Every persona Cannot line resolves to an executable gate (`authorize` policy, or ownership `claim "x" matches subject\|<command property>`) and a `then denied` spec whose caller fixture carries the roles/claims standing for the persona; otherwise recorded as a gap. Persona text is intent only | personas, policies, specs | D |
+| G6 | Every persona Cannot line resolves to an executable gate (`authorize` policy, or ownership `claim "x" matches subject\|<command property>`) and a `then denied` spec whose caller is synthesized with `given caller as <Persona>` or explicitly carries the effective-gate roles/claims; otherwise recorded as a gap. Persona text is intent only | personas, policies, specs | D |
 | G7 | Every command and query under an inherited module/feature `authorize` has its own `then denied` spec; authorization shared by a feature is declared at feature/module level so new paths inherit it | policies, specs | D |
 | G8 | Ownership checks against a Uuid-backed identifier are not renderable today (STAGE-ESM-015): noted | policies | C (renderable mode) |
 

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

@@ -42,7 +42,7 @@ Gaps: <capability gaps and tool-version gaps, e.g. a false PLAY0285 on cascades
 Modules n, features n, slices n (StateChange n, StateView n, Automation n, Translate n),
 events n, commands n, read models n, specs n.
 Slices with at least one assertion: n of total (pct). Without: <names, at most 10, then "and N more">.
-Structural gaps per slice (skip gaps a description calls intentional): <slice: what is missing, or none>.
+Structural gaps per slice (skip gaps documentation explicitly calls intentional): <slice: what is missing, or none>.
 
 ## Phase 1: Element sweep (7 checks)
 Check S1: <short title>
@@ -66,6 +66,10 @@ Sweep summary: gated elements n, with denial spec n, NONE: <names>; field-copy s
 ## Coverage matrix
 <from the coverage matrix of `cratis-screenplay-scenario-coverage`; mark empty cells and weak n/a reasons>
 
+## Modeling reasoning
+Real decisions have fenced Markdown `documentation` on their owner, finalized at
+P3's end; `description` stays a summary. No prose is enforcement or review evidence.
+
 ## Dependencies
 Per slice: events consumed and the producing slice (orientation only, not build order); cycles found.
 

package/package/corpus/skills/cratis-screenplay-model-review/verification.json

@@ -7,7 +7,7 @@
     { "kind": "skill-contains", "value": "Every finding is pinned to one declaration" },
     { "kind": "skill-contains", "value": "edit request" },
     { "kind": "skill-contains", "value": "business-question" },
-    { "kind": "skill-contains", "value": "Screenplay#393" },
+    { "kind": "skill-contains", "value": "find-modeling-smells" },
     { "kind": "skill-contains", "value": "entity walk" },
     { "kind": "skill-contains", "value": "eleven phases, 89 checks" },
     { "kind": "skill-contains", "value": "could a non-technical product owner read it and immediately understand" },

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

@@ -196,7 +196,7 @@ labelled as such. The user decides whether it is enough
   next phase, report pointer. Templates: `references/handoff-template.md`,
   `references/phase-report-inventories.md`; `references/reasoning-notes.md`;
   `references/code-reading-and-tokens.md`.
-  Read `references/handoff-template.md` when writing state, packets, questions, or edit requests; `references/phase-report-inventories.md` when producing a phase report; `references/reasoning-notes.md` when recording durable rationale in descriptions; and `references/code-reading-and-tokens.md` before choosing code-reading scope or compressing output.
+  Read `references/handoff-template.md` when writing state, packets, questions, or edit requests; `references/phase-report-inventories.md` when producing a phase report; `references/reasoning-notes.md` when recording durable rationale in `documentation`; and `references/code-reading-and-tokens.md` before choosing code-reading scope or compressing output.
 
 ## Route to one phase skill
 | Need | Skill |
@@ -213,7 +213,7 @@ labelled as such. The user decides whether it is enough
 
 Construct mechanics stay in the `cratis-screenplay-*` construct skills; term clashes:
 `references/vocabulary-map.md`; worked example: `references/worked-example.md`; done checklist: `references/phases.md`.
-Read `references/worked-example.md` when needing an example of reasoning descriptions, constraints, and decided rejections.
+Read `references/worked-example.md` when needing an example of reasoning documentation, constraints, and decided rejections.
 
 ## Gate
 Done when: the mode's "done when" holds with fresh verdict lines; every open question has an

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

@@ -26,11 +26,13 @@ disables registration"; `AiConfiguration.McpServers`, read by `AiMcpDescriptor.R
 `git -C <cli checkout> show v3.28.2:Source/Cli/Commands/Ai/AiMcpDescriptor.cs`.
 
 ## Model root and the committed-`.play` test
-The corpus rule keeps `.cratis/screenplay/` as the default root for the committed-`.play` test.
-Because a 3.28.x MCP server may place a new model under `Source/`, `src/` or `Screenplay/`, a
-repository whose accepted model lives elsewhere is not opted in by rule (a) alone: it must set
-`mcpServers.screenplay.root` to that directory, which is rule (b). When such a model exists
-without the setting, report the mismatch instead of treating the repository as opted in.
+The model root is the folder holding the project's `.play` files; absent an existing
+model, use `Source/` or `src/`, else `Screenplay/` at the repository root, never
+under `.cratis/`. An explicitly configured `mcpServers.screenplay.root` selects
+the root. A committed `.play` there is rule (a)'s opt-in signal without requiring
+the setting; setting a root is independently rule (b), even when empty. The legacy
+CLI discovery behavior above is historical evidence, not a default corpus root.
+Do not count unrelated documentation, samples or scratch files as the project model.
 
 ## Edge cases
 - `.play` files only under `.ai-work/`, a docs folder or a sample: not under the root, so not opt-in.

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

@@ -47,7 +47,7 @@ next skill loads (never skipped, also after a small change):
 ```
 The Interview Trail row's status becomes `done` and its key output one line. Also record, at any
 phase, a decision important enough that a later reader could misread the model (see
-`reasoning-notes.md` for when it belongs in a `description`).
+`reasoning-notes.md` for when it belongs in fenced Markdown `documentation`).
 
 ## P0 Intake
 - **Input**: the request, the repository, the project's model folder or the configured root.
@@ -77,18 +77,18 @@ phase, a decision important enough that a later reader could misread the model (
 
 ## P3 Specify (`cratis-screenplay-scenario-coverage`; modeling stance)
 - **Input**: the P2 model.
-- **Carry-forward**: coverage matrix, specifications, then reasoning descriptions for features with
+- **Carry-forward**: coverage matrix, specifications, then reasoning documentation, written last in P3, for features with
   real decisions (`reasoning-notes.md`).
 - **Gate**: matrix written before drafting; per command each applicable scenario type is a spec or
   "n/a" with a domain reason (one success plus one failure is not coverage); each gated command and
   query, including those under an inherited module or feature `authorize`, has its own `then denied`
-  spec with a caller fixture carrying the persona's roles or claims; each `produces when` has a spec
+  spec with a synthesized persona caller or an explicit effective-gate fixture; each `produces when` has a spec
   per branch; each value-unique constraint has a competing-claim spec; per read model a view spec, an
   update spec when several sources feed it, a removal or absence spec when it removes. A command-only
   pass fails the gate.
 
 ## P4 Self-check (`cratis-screenplay-model-review`, self-check; critic stance)
-- **Input**: the P3 model including reasoning descriptions.
+- **Input**: the P3 model including reasoning documentation.
 - **Carry-forward**: five verdict lines from fresh runs; the completeness walk; findings by tier.
 - **Gate**: completeness walk done (field origins, event consumers or terminal reasons); every gap
   fixed, accepted by the user, or an open question with its assumption. The critic reports; fixes go

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

@@ -44,7 +44,7 @@ is adapted with the agreement of Martin Dilger and Nebulit GmbH.
 |---|---|---|
 | `.claude/skills/eventmodeling-orchestrating-event-modeling/SKILL.md`: "Do not cut corners to save tokens or effort" (forbidden rationalizations, self-catch trigger, flag trade-offs to the user) | `SKILL.md` "Do not cut corners to save tokens or effort", `references/completeness-self-check.md` | Adapted closely; restored from #493. Board rationalizations (delete a node to dodge a placement conflict, "session-context" read model, collapsed translation chain) translated to Screenplay (modeled reaction, missing view, translation merged into worker behavior, denial and protection) |
 | same file: "Phase Transition Protocol" (what was done, carry-forward, open questions; trail row to Done) | `SKILL.md` "Lifecycle", `references/phases.md` "Phase transition protocol" | Adapted closely; restored from #493. Memory file replaced by STATE.md |
-| same file: "Documenting decisions inline" and Step 11 "What the note should actually contain" (cold reader, simple chapter stays brief) | `references/reasoning-notes.md` | Adapted closely; restored from #493. Feedback-lane note translated to a `description`; counts and verdicts stay in STATE.md |
+| same file: "Documenting decisions inline" and Step 11 "What the note should actually contain" (cold reader, simple chapter stays brief) | `references/reasoning-notes.md` | Adapted closely; restored from #493. Feedback-lane reasoning uses `documentation`; counts and verdicts stay in STATE.md |
 | same file: "Interview Phase" and "Mid-Workflow Entry" | `SKILL.md` "Interview phase (P0)" | Already adapted from TrogonStack (section 1); Martin Dilger and Nebulit GmbH's confirmation sentence kept |
 | `.claude/skills/eventmodeling-interview-protocol/SKILL.md`: "When to ask", "Unless told not to ask", "Recording the outcome" | `references/stop-or-assume.md` "Interview protocol" | Adapted closely; restored from #493. Interview file replaced by the STATE.md Interview Trail |
 | `.agent-modeling-kit/CLAUDE.md`: per-turn steps (screen the prompt, connect once, resolve context, start marker, invoke the matched skill never raw calls, questioning rule, close, learnings) | `references/per-turn-protocol.md`, `SKILL.md` "Run protocol" | Adapted closely; restored from #493. Board prompts and status calls translated to briefs, `Active:` in STATE.md and the `Outcome:` line; `<promise>` sentinels, `progress.txt` and learnings promotion not adopted |

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

@@ -1,16 +1,21 @@
-# Feature reasoning descriptions
+# Feature reasoning documentation
 
-Durable rationale goes in `description` text (it survives canonical printing; `//` comments do
-not), only for a real "why". Written as the last step of P3, once the feature's model and
-specifications are complete, describing the finished shape, for features with real decisions. A
-simple feature needs one or two sentences or nothing. P4 only checks that they exist; if one is
-missing, or the self-check forces a model change, return to a modeling batch, author it, and
-rerun V1 on the changed revision.
+Use `description` for a short summary; durable rationale goes in a nonempty fenced
+Markdown `documentation` block, only for a real "why". Write feature reasoning as
+the last step of P3, once the model and specifications are complete, describing the
+finished shape. A simple feature needs one or two sentences or nothing. P4 checks
+that substantive decisions have their reasoning; if missing, or a self-check forces
+a model change, return to a modeling batch, author it and rerun V1 on that revision.
 
-Descriptions never reach rendered code (Stage#178) and are not part of the canonical semantic
-revision (`modelRevision`), so editing one does not change it; they do change the source identity
-(`verdicts-and-modes.md`). Model the rule first: a rule
-that exists only in a description is unenforced in rendered scope.
+Screenplay v4.127.0 `slices.md` accepts one `documentation` block directly on a
+module, feature, slice, command, event, read model or reaction (not under its trigger).
+Use a `markdown` fence; empty, malformed or repeated blocks report PLAY0558, with
+PLAY0477 retained for events. Specifications accept `description`, not documentation;
+put their longer reasoning on the owning slice. Projections/screens do not accept it.
+Canonical printing retains documentation on its owner. It is report-only (PLAY0270),
+absent from executable bytes and `modelRevision`; edits change source identity
+(`verdicts-and-modes.md`). Neither description nor documentation is rendered as code
+(Stage#178): model the rule first, never treat prose as enforcement.
 
 Cover, briefly and only where real:
 1. Scope: the business process and the identities its streams are keyed by.
@@ -24,22 +29,22 @@ Cover, briefly and only where real:
 6. Integration and capability gaps, each substantive one (outside facts, cross-feature or
    cross-module dependencies, mode gaps) as: the finding, the viable resolutions, and the
    open question or decision that records the choice (`Qn <address>`, or the decision in
-   STATE.md), so the description and the question agree.
+   STATE.md), so the documentation and the question agree.
 7. A closing line for a feature with real decisions: what is covered (declaration kinds and
    the specification matrix in words, not a counter that goes stale). Review results and
-   verdicts are never written into a description (it is authored before review and would change
+   verdicts are never written into documentation (it is authored before review and would change
    the reviewed source identity); they live in STATE.md and the packet.
 
 Write for the next person or session who opens the model cold, not for whoever just built it.
 Add a note **at any phase**, at the element it applies to, when an assumption fills a gap the
 brief left open, an alternative was rejected, or a constraint is not obvious; never as routine
-narration of what a step did. If a feature's story is genuinely simple, say so briefly rather
-than padding; where real design decisions sit behind it, the description is how they survive
-the session that made them.
+narration of what a step did. Complete the feature's reasoning at the end of P3.
+If a feature's story is genuinely simple, say so briefly rather than padding; where real
+decisions sit behind it, documentation preserves why they were made.
 
-Slice, command, event and read-model descriptions: one sentence per genuine decision at that
-element. Counts, verdicts and session notes belong in STATE.md, never in the model.
+Slice, command, event, read-model and reaction documentation: one sentence per genuine
+decision at that element. Counts, verdicts and session notes belong in STATE.md, never in the model.
 
 ## Worked example
-`worked-example.md` shows a feature description carrying items 1-3, a constraint instead of a
+`worked-example.md` shows feature documentation carrying items 1-3, a constraint instead of a
 second event type, and a decided rejection as a specification.

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

@@ -58,5 +58,5 @@ given for a named target. Approval is not repeated for the same scope.
 
 ## Unblocking
 A scope leaves `blocked` only when its question is answered; record the answer as a decision in
-STATE.md and, when durable, in the model `description`. Re-blocking a blocked scope is a no-op.
+STATE.md and, when durable, in the model's fenced `documentation`. Re-blocking a blocked scope is a no-op.
 Blocked delivery scopes are reported in the packet; the main session creates any issue.

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

@@ -210,5 +210,7 @@ skill):
 - Never remove `pii`, `secret`, authorization, date or state-dependent rules to reach V3 or
   V5. Report blocked execution.
 - Narrowing the mode is the user's decision; widening back to design is always allowed.
-- Roadmap items that would change verdicts (a spec runner in the compiler tool, a lineage and
-  completeness report) stay "not available" until the toolchain skill lists them as released.
+- Never assume a roadmap item shipped. Current `screenplay test`, MCP
+  `run-specifications`, obligations/smells and opt-in completeness are released
+  at the toolchain pin; they do not prove full field lineage or target behavior.
+  Check `cratis-screenplay-toolchain` before changing a verdict.

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

@@ -21,7 +21,7 @@ speaks in them; never model board mechanics (lanes, node ids, positions).
 | Storyline (ordered beats) | a **family** of specifications sharing example data, each one transition (no storyline syntax at the verified Screenplay v4.66.0) | several spec classes | specifications |
 | Field validation | concept `validate` (every use) / command `validate`, `require` | `ConceptValidator<T>` / `CommandValidator<T>` | command validation |
 | Role permission ("Cannot") | `policy` + `authorize` + `then denied` spec; ownership via `claim ... matches subject` | `[Authorize(Policy)]`, generated policies | authorization |
-| Precondition on stream state | `reads` + `require` as stated intent, not enforced at the verified Screenplay v4.66.0 (target: Arc `[ProtectedDecision]` + `DecisionRead<T>`, or Chronicle DCB; `[ProtectedDecision]` is not available in Stage-rendered apps) | decision over a guarded read | command validation |
+| Precondition on stream state | `reads` + `require` as stated intent, not enforced at the verified Screenplay v4.66.0 (target: Arc `[ProtectedDecision]` + `DecisionRead<T>`, or Chronicle DCB; APIs available to gap-fill in Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0, not emitted protection) | decision over a guarded read | command validation |
 | Generated id (`derived:uuid4()`) | `generated` (authorable, not executable) | id supplied before `Handle()` | commands |
 | External system / outbound call | `Translate` slice (inbound); `system`/`operation` (authorable, not executable) or Automation (outbound) | `ICommandOperation` / reactor | operations, reactors |
 | HTML mockup | `screen` Level 1 + board (`visualize-model`) | default Scene composition | ui composition |

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

@@ -1,12 +1,12 @@
-# Worked example: reasoning description, constraint, decided rejection
+# Worked example: reasoning documentation, constraint, decided rejection
 
-A marina berth allocation feature. The feature `description` carries the reasoning (scope, an
+A marina berth allocation feature. The feature `documentation` carries the reasoning (scope, an
 assumption tied to Q1, a rule kept as a constraint). The refusal for a boat that already holds a
-berth is a specification, not a note. Complete and compiling with the standalone compiler and with
-`cratis screenplay validate`.
+berth is a specification, not a note. The complete model validates and its three specifications pass on standalone
+Screenplay 4.127.0; these are reference-runner checks, not rendered-code evidence.
 
 
-```screenplay
+````screenplay
 domain Marina.Berths
 
 concept BerthId : Uuid
@@ -21,7 +21,13 @@ persona HarbourMaster
 
 module Berths
   feature Allocation
-    description "Allocating a berth to a boat. A boat holds one berth at a time; that rule is the OneBerthPerBoat constraint, not a second event type. Assumption Q1: allocation is always manual, so no automation is modeled."
+    description "Allocating a berth to a boat"
+    documentation
+      ```markdown
+      A boat holds one berth at a time; that rule is the OneBerthPerBoat
+      constraint, not a second event type. Assumption Q1: allocation is
+      always manual, so no automation is modeled.
+      ```
     authorize HarbourOffice
 
     slice StateChange AllocateBerth
@@ -70,7 +76,7 @@ module Berths
           berthId = "5d3c2a52-27c4-4d2b-a0ee-0a6a8a9f7b11"
           boat    = "Sea Wren"
         then denied
-```
+````
 
 
 ## Why it is shaped this way
@@ -78,9 +84,9 @@ module Berths
   specification can state the exact rejection. No `BerthReassigned` event was added to carry it.
 - The `Cannot` line in the persona resolves to the `HarbourOffice` policy and a `then denied`
   specification whose caller fixture carries a non-matching role.
-- Assumption Q1 lives in the feature description and in STATE.md (Open questions) with its address,
+- Assumption Q1 lives in the feature documentation and in STATE.md (Open questions) with its address,
   `Berths.Allocation`.
-- The description is rationale only: the rules themselves are enforced by the constraint, the policy
+- The documentation is rationale only: the rules themselves are enforced by the constraint, the policy
   and the specifications, not by the prose.
 - The constraint does not say a berth holds one boat at a time: a berth source may replace its
   claimed boat. If berth occupancy must be unique too, model and specify that as its own invariant.

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

@@ -246,7 +246,10 @@ One labeled user decision can choose among commands using ordered
 without an execute fallback hides it. Inputs use typed `with ... from ...`
 bindings; the selected command still enforces its own gate/rules/constraints.
 Read [guarded actions](references/guarded-actions.md) for the checked model,
-missing-versus-null behavior and source-versus-renderer boundary.
+missing-versus-null behavior and source-versus-renderer boundary. For a gesture
+choosing a whole action list rather than one labeled command, use block-form
+`when`/`otherwise` on click/double click/select:
+[guarded interactions](../cratis-screenplay-ui-composition/references/guarded-interactions.md).
 
 ## How a bare name resolves
 

package/package/corpus/skills/cratis-screenplay-read-surface/references/guarded-actions.md

@@ -3,6 +3,10 @@
 
 # Guarded screen actions
 
+For a gesture choosing a whole action list, rather than a labeled action choosing
+one command, use [guarded interactions](../../cratis-screenplay-ui-composition/references/guarded-interactions.md).
+They share item conditions/subject rules but run once without a click-time refetch.
+
 ## Contents
 
 - State one user decision