@cratis/pi 7.23.0 → 7.25.0

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/loss-report-template.md

@@ -31,7 +31,7 @@ and the question raised.
 One line per rule, named individually (never one generic platform caveat): the rule, its
 evidence row, the invariant and consistency risk, and the target enforcement. State-dependent
 checks are written as `reads` + `require` and marked NOT enforced in the slice description;
-date rules and opaque policies that no declaration can state stay in `description` and here.
+date rules and opaque policies that no declaration can state stay in the slice `documentation` and here.
 
 ## Unknowns and undecided target decisions
 | Row/question | What is unknown | Who can answer | Candidate assumption |

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/rule-modeling.md

@@ -4,19 +4,19 @@
 - Input or constraint rejection: declarative `validate`, `require` or constraint, plus a
   `then error "<exact legacy message>"` specification.
 - Authorization refusal: `authorize` with a policy (role, claim, authenticated, or an
-  ownership policy) plus `then denied`, with caller fixtures carrying the roles or claims.
+  ownership policy) plus `then denied`, with a synthesized persona caller or an explicit effective-gate fixture.
   Every command and query under an inherited module or feature `authorize` gets its own
   `then denied` spec. A role gate with no executable form is a recorded gap.
 - Legacy HTTP status and check order (for example 409 before 403) are facts about the old
-  system: record them in the slice description and the evidence row, not in the model logic.
+  system: record them in slice `documentation` and the evidence row, not in the model logic.
 
 ## State-dependent rules
 A rule that depends on stored state (current status, existing records, balances) is written
 as `reads <View>` + `require <expr> message "…"` and the slice description says it is **NOT
 enforced in the model today** (PLAY0268/0271 at binding are expected in design mode;
 Screenplay#129/#209). Name the invariant, the race it leaves open, and the target:
-`[ProtectedDecision]` + `DecisionRead<T>` (Arc 22.39.0 and later; hand-written code only,
-not available in Stage-rendered applications, which pin Arc 22.25.0), or a Chronicle
+`[ProtectedDecision]` + `DecisionRead<T>` (Arc 22.39.0 and later; available to gap-fill
+in Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0 package set, not automatically emitted), or a Chronicle
 `concurrency` scope on the event source or stream, or a constraint where one fits. Forbidden: caller-supplied copies of state
 in `require`, boolean inputs standing in for a rule (`confirmsX == true`), and rules hidden in
 `handler`/`implementation hint` prose. Descriptions are not rendered (Stage#178), so a rule

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/signal-to-intent.md

@@ -14,7 +14,7 @@ who decided it?* If nobody can answer, classify the row `unknown` and ask.
 |---|---|---|---|
 | One request writes several tables | one decision; one table carries the fact, the others are consequences | one event per table (`CheckinCreated`, `HookUpdated`) | one event named for the decision (`CoatTakenIn`); consequences become projections |
 | Generic update route (`PUT /members/{id}`) | several intents hidden behind one form | one `MemberUpdated` event | split by which columns change together and why (address change, suspension, renewal); ask experts. No `Update/Edit/Save<Noun>` command and no `<Noun>Updated/Changed` event; a full-payload `*Updated` event is the default generator output and a review signal |
-| Request with no table write and a 4xx status | a rejected attempt; evidence of a rule | Prologue models it like a success (status codes are ignored) and the merge can strip properties | `validate`/`require`/constraint plus a `then error` spec with the exact message from code (authorization refusals are `then denied`); legacy HTTP code and check order go in the slice description |
+| Request with no table write and a 4xx status | a rejected attempt; evidence of a rule | Prologue models it like a success (status codes are ignored) and the merge can strip properties | `validate`/`require`/constraint plus a `then error` spec with the exact message from code (authorization refusals are `then denied`); legacy HTTP code and check order go in slice `documentation` |
 | 2xx with no table write | read, idempotent no-op, or external side effect | treated as a command | check code; classify |
 | Single-column unique index | a business uniqueness rule, or a technical key | every unique index becomes a constraint, or a clear business rule is dropped to a bare `rule` | when the meaning is clear, `unique <prop> on <every event that sets it>` plus `released by <removal event>`; list collation, case and reuse questions. Fall back to a bare `rule` only when no constraint form fits, and record that as a loss. A purely technical key stays out |
 | Foreign key | an identity relation between streams or read models | copying the parent id into every event | keep ids only where a consumer needs the value |

package/package/corpus/skills/cratis-screenplay-legacy-extraction/verification.json

@@ -3,6 +3,7 @@
   "input": "We inherited a legacy ASP.NET application with a SQL Server database and no documentation. Help us turn it into a Screenplay model before we modernize it.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     {
       "kind": "skill-contains",
       "value": "loss report"

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

@@ -130,9 +130,9 @@ and applies; others send an edit request ([MCP loop](references/mcp-loop.md)).
 3. Prefer `propose-rename` for supported logical renames: it coordinates fragments,
    repairs proven references and preserves assigned identities. Never substitute
    global string replacement for an explicit refusal.
-4. Use `propose-ast` for typed additions, replacements, removals and moves. Group
-   related cross-file changes in one batch so no broken intermediate state lands.
-   Parser-invalid source can be repaired by typed whole-document replacement.
+4. Use `propose-source` for whole text or `propose-ast` for typed edits
+   (Authoring defaults); `propose` is executable-only. Batch changes;
+   details: `references/mcp-tools.md`.
 5. Keep reference policy `Safe`. Use `Draft` only for deliberately requested
    unresolved model debt and report that debt; it does not waive structural,
    identity or binding-protection checks.
@@ -261,7 +261,8 @@ target or consequence expands.
 Readiness has two verdicts: `readiness.authoringAccepted` says the source is valid
 Screenplay; `executableReady` describes only the current executable subset. Do not
 call a model broken because it is not executable, and prefer `propose-ast` for
-full-language authoring. A rejected proposal lists its diagnostics: fix those, do not
+focused full-language edits, or `propose-source` for whole documents. A rejected
+proposal lists its diagnostics: fix those, do not
 retry the same input.
 
 ## Code attachments

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

@@ -102,14 +102,18 @@ the server sends `roots/list` and serves `tools/list` after the reply).
    `search-declarations`, `declaration-details`, `dependencies`/`dependency-graph`.
    Diagnostics `scope` includes descendants and direct dependents; `checks` opts
    into completeness warnings (skipped on whole-source errors). Paging with
-   `offset > 0` requires `expectedSourceRevision`.
+   `offset > 0` requires `expectedSourceRevision`. Seed coverage with
+   `find-specification-obligations` (presence, not execution), use
+   `find-modeling-smells` as questions needing a domain consequence, and compare
+   generated/curated exported snapshots with `semantic-diff`.
 3. `open-workspace` and keep `revision` and `catalogRevision`. Opening writes
    nothing. With `identityPersistence: "root-local-on-apply"` the identities file
    is written only by `apply`.
 4. Choose the edit route (next section). For typed edits: `syntax-schema` for the
    node kind, then `read-ast` with `includeContent` for revision-bound handles.
    Never invent a handle.
-5. Propose one coherent change (a slice works best): `propose-ast` with
+5. Propose one coherent change (a slice works best): `propose-source` for whole
+   `.play` text, `propose-ast` for focused typed edits, with
    `validation: "Authoring"`, `referencePolicy: "Safe"` (`Draft` only for
    deliberate, reported gaps), `formatting: "PreserveTrivia"` for value and mapping
    patches, otherwise `CanonicalizeTouchedDocuments` (reprints the touched files).
@@ -140,7 +144,11 @@ the server sends `roots/list` and serves `tools/list` after the reply).
 2. **Prefer typed, identity-preserving operations**: `propose-rename` for renames
    (keeps `id` pins and assigned identities, refuses on ambiguity),
    `propose-repair`, `propose-extract-inline-event`, `propose-ast` for additions,
-   replacements, removals and moves.
+   replacements, removals and moves. Use `propose-source` when authoring whole
+   documents as UTF-8 text, not base64 or typed node JSON; `propose` remains the
+   executable-only exact-byte interface. Both authoring routes require revisions,
+   formatting consent and identity continuity. `SourceParseFailed` returns located
+   `authoringDiagnostics` without a proposal. Details: `mcp-tools.md`.
 3. **Bounded text edits** are fine only where no catalog address changes (table below). With
    `.screenplay/identities.json`, adding, removing or renaming a declaration, a property of a
    command, event, read model, composite type or trigger, a query, a query argument or a
@@ -162,10 +170,10 @@ the server sends `roots/list` and serves `tools/list` after the reply).
 | --- | --- | --- |
 | Address-preserving | descriptions; bodies of rules and expressions; mappings between members that already exist; any edit that adds, removes or renames no addressed element. Also every edit in a model with no `.screenplay/identities.json` except persisted names | bounded text edit of the `.play` file, then compile the folder; or `propose-ast` |
 | Catalog-changing (identity file present) | add, remove or rename a declaration (slice, command, event, read model, projection, ...), a property of a command, event, read model, composite type or trigger, a query, a query argument or a specification; create, delete, rename or move a mapped `.play` document (McpState refuses reopening with `IdentityMappingConflict`; use document operations in `propose-ast`); rename, remove or move an event, command, read model, constraint, module, feature or slice; move declarations between files; contract evolution of a persisted event (new generation, property added, removed or retyped) | `propose-rename` or a reviewed `propose-ast`; never a blind text rename. Renaming a constraint resets its uniqueness index: ask first unless the request names it, then report the reset. A persisted event rename needs `id "OldName"` (added by default) |
-| Repair | `PLAY0166`, `0478`, `0469`, `0471`, `0479`, `0516`, `0565`, `0653` (and recipe-only `0397`) | `propose-repair` with `formatting`; PLAY0166/0478 may pin attachment evidence (`pinRepairEvidence` and `expectedRepairEvidenceRevision`), never fix-all PLAY0478 |
+| Repair | `PLAY0166`, `0478`, `0469`, `0471`, `0479`, `0516`, `0563`, `0564`, `0565`, `0614`, `0653` (and recipe-only `0397`) | `propose-repair` with `formatting`; PLAY0166/0478 may pin attachment evidence (`pinRepairEvidence` and `expectedRepairEvidenceRevision`), never fix-all PLAY0478 |
 | Inline event extraction | `produces event ...` to a declared event | `propose-extract-inline-event` |
-| Parser-invalid document | no editable handles | `propose-ast` `replace-document` with a whole typed document, or fix the text |
-| Unadmitted constructs | systems/operations, exact numbers, refusal/redelivery | reviewed Authoring `propose-ast`; preserve intent and report PLAY0268 |
+| Parser-invalid document | no editable handles | `propose-source` `replace-document` with corrected source, or typed `propose-ast` document replacement |
+| Unadmitted constructs | systems/operations, exact numbers, refusal/redelivery | reviewed Authoring `propose-source` (whole documents) or `propose-ast` (typed edits); preserve intent and report PLAY0268 |
 | Admitted source/stream routing | ESM v8 at 4.125.0 | typed `propose-ast`; `propose-rename` repairs proven route references; target admission separate |
 
 ## Self-describing identity migration refusals

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-authoring/verification.json

@@ -3,6 +3,7 @@
   "input": "Author and organize a Screenplay model in a repository.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     {
       "kind": "skill-contains",
       "value": "Screenplay v4.127.0"

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

@@ -3,11 +3,12 @@
   "input": "Review the marina berth .play model before we accept it: check the model and report findings, do not change anything.",
   "fixtures": [],
   "assertions": [
+    { "kind": "play-compiles" },
     { "kind": "skill-contains", "value": "PASS WITH WARNINGS" },
     { "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 |