@cratis/pi 7.21.0 → 7.23.0

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

@@ -23,25 +23,13 @@ contract is in `cratis-screenplay-ui-composition`.
 
 ## Verified product sources
 
-| Package | Version | Purpose |
-| --- | --- | --- |
-| `Cratis.Screenplay` / `Cratis.Screenplay.Tool` | `4.68.0` (`79801bf`) | Current compiler; admits ESM v7 (generated values and responses, decision 0026); examples compiled with `--warnaserror` and their specifications run |
-| `Cratis.Screenplay` / `Cratis.Screenplay.Tool` | `4.66.0` (`c89198b`) | MCP (29/30 tools), roots fix; the MCP behaviour below was probed on it |
-| `Cratis.Screenplay` | main `fd18129` | Inline events, repairs, rename/extraction and `optional` |
-| `Cratis.Screenplay` | `4.31.0` | Original compiler, ESM and workspace evidence |
-| `cratis` CLI | `3.28.3` | Bundles Screenplay 4.66.0 (no ESM v7) and Stage 4.24.2 (3.28.2 bundled 4.24.1; before 3.28.2: 4.60.1, ESM v5 at most, roots bug) |
-
-Facts about the MCP connection, source-map, `whenAppendedEvent`, identity
-persistence and the syntax-only constructs were read at tag `v4.66.0`
-(`Documentation/screenplay/mcp/{reference,install,edit}.md`,
-`Source/DotNET/Screenplay.Mcp/`) and probed against the 4.66.0 tool (persona,
-trigger, `@pii`, generated values, operations, streams, automation binding).
-Repair and refactoring guidance follows main `fd18129` (`commands.md`,
-`events.md`, `types.md`, `diagnostics.md`, `mcp/authoring-tools.md`, `vscode.md`,
-decision 0023); the `v4.31.0` documents (`ast-authoring`, `mcp`, `mcp-authoring`,
-`printing`, `file-references`, `diagnostics`) and release notes v4.17.0 to v4.31.0
-established the original baseline. When checking compiler, CLI or MCP compatibility, read the full version table in
-`cratis-screenplay-toolchain` (`references/versions.md`).
+Current authoring/MCP guidance follows Screenplay v4.127.0
+`Documentation/screenplay/mcp/`, `ast-authoring.md`, `folders.md`, `vscode.md`.
+Discover installed tools and schemas; CLI bundles can differ from the standalone
+tool. Pins are in `cratis-screenplay-toolchain` `references/versions.md`.
+Historical connection/binding probes below remain labeled 4.66.0; the complete
+registration example was compiled/tested at 4.68.0, not reclassified as a current
+execution probe. Earlier source attribution is in `references/provenance.md`.
 
 ## Locate and connect
 
@@ -54,17 +42,16 @@ directory when it holds `.play` files). Only when it answers that no root was gi
 or that several roots are offered, pass `path`: the folder holding the project's `.play` files, otherwise the
 folder the user names. Without a project, the server works in `Documents/Screenplay`
 in the user's home folder, so do not invent a location. A root fixed at launch
-cannot be switched: another `path` returns `RootChangeRefused`.
+can switch only to the corresponding model folder in a registered Git worktree
+of the same repository. Pass the worktree checkout or exact model directory as
+`path`; unrelated roots return `RootChangeRefused`. Switching clears proposals
+and uses the destination's own identity state and journal; nothing migrates.
+Submodules and `--separate-git-dir` checkouts require another connection.
 
-**Prefer a fixed root.** Screenplay up to 4.63.1 (so Cratis CLI before 3.28.2; fixed in
-4.63.2, so not in CLI 3.28.2 or later, probed) fails a
-dynamic-root server right after `notifications/initialized` when the client
-advertises roots; real hosts then drop the connection, and `open-workspace.path`
-cannot prevent it. Start `screenplay mcp <model-folder>` or `cratis screenplay mcp`
-in a project (it locates the model: the project's `.play` files, else `Source/` or `src/`, else `Screenplay/`).
-Send `initialize` and `notifications/initialized` before any tool call;
-`tools/list` returns 29 tools (30 on MCP-Apps hosts). Read `references/mcp-loop.md` when connecting, coordinating connection ownership, or handling proposal and recovery failures. Details:
-[MCP loop](references/mcp-loop.md).
+Prefer a fixed root; the historical dynamic-roots bug and connection procedure
+are in [MCP loop](references/mcp-loop.md). Send `initialize` and
+`notifications/initialized` before any tool call, then discover `tools/list`
+schemas rather than relying on a remembered count.
 
 
 Look first for the project's existing `.play` files: the folder holding them is the
@@ -100,10 +87,14 @@ can keep that entry point; use the project's supported installation channel.
    of `.play` files is one application, not independent files.
 2. Use `search-declarations`, `declaration-details`, `find-references` and
    `dependencies` to locate the owning declaration and affected references.
-3. Read diagnostics and coverage limitations. Unknown or ambiguous bindings are
-   not an empty, successful dependency graph.
-4. Use `find-fixtures` for value occurrences and `find-assertion-gaps` for authored
-   assertion gaps. These tools do not execute specifications or prove coverage.
+3. Read diagnostics and coverage limitations. Use `dependency-graph` for container
+   edges, declared-dependency coverage, cycles and advisory order; the board's
+   dependency-map toggle exposes this evidence visually. Unknown or ambiguous
+   bindings are not an empty, successful dependency graph.
+4. Use `find-fixtures` for value occurrences (including example/override origins
+   and event routes) and `find-assertion-gaps` for authored assertion gaps. Neither
+   executes specifications. `diagnostics` accepts `scope` and opt-in `checks`;
+   skipped completeness checks are not passes. Details: `references/mcp-tools.md`.
 5. Echo `sourceRevision` on subsequent pages. Restart the query after drift;
    never combine pages from different snapshots.
 6. For screens, also discover the template, form, toolbar, package/icon and
@@ -187,21 +178,30 @@ each lost comment (`PLAY0288` also reports their count and lines). Untouched
 documents retain exact bytes. A printer that loses requested structural fields
 rejects the plan.
 
+`identityMigrationIssues`: read the [MCP loop](references/mcp-loop.md).
+
 ## Repair or extract before rewriting
 
 Read `read-workspace` with `view: "diagnostics"`, then `view: "repairs"` at the
 same revision. Pass the returned `diagnosticCode`, `subject`, required formatting
 and both revisions to `propose-repair`; preview with `read-proposal`, then `apply`.
 Only verified repairs are listed, and the selected repair gets a fresh transaction.
+For PLAY0166/PLAY0478, use the evidence-pinned loop in `references/mcp-tools.md`:
+`pinRepairEvidence` plus `expectedRepairEvidenceRevision` prevent attachment drift
+from silently changing the reviewed candidate.
 
 - `PLAY0166` declares a missing produced event; `PLAY0478` is a routing decision
-  (identifier destination); `PLAY0471` removes a redundant name-equal event pin.
+  (identifier destination, never fix-all); `PLAY0471` removes a redundant name-equal event pin.
+- `PLAY0516` repairs presentation order by moving a sibling or import, or pinning
+  a producer before a glob. It preserves semantics/identities and introduces no
+  new timeline findings; evidence pinning is unsupported for this repair.
 - `PLAY0469` removes an inline identifier payload copy: it **changes the event
   contract**, refuses consumer/opaque impact, has no fix-all, and the catalog does
   not prove events were persisted, so ask about stored contracts first.
   No automatic generation-evolution repair ships.
 - `PLAY0479`: migrate optionality spelling with `PreserveTrivia`; document scope
   migrates all occurrences together. Keep the `query Q => observable?` exception.
+- Compliance repairs PLAY0565/0653: [MCP tool guide](references/mcp-tools.md).
 
 Use `propose-extract-inline-event` on the inline `EventSyntax` handle before adding
 a generation (canonical formatting consent; refuses comment loss; no reverse
@@ -226,9 +226,10 @@ module and its features, each feature importing its folder
 (`import "Orders/*.play"`); a slice file holds only its `slice`, because the
 import places it in its feature. When you write or reorganize files yourself,
 do not restate `module`/`feature` in a slice file, and do not leave a barrel
-that declares a scope but imports nothing. `expand-layout` still writes that
-older merge-only layout; it compiles as a folder, and you can compose it with
-imports afterwards. When choosing file placement, read the
+that declares a scope but imports nothing. At 4.125.0 `expand-layout` writes
+import barrels and slice-only leaves, preserving sibling and interleaved member
+order. It refuses a proposal that would change that order; without an ordering
+root its review discloses the path-order fallback. When choosing file placement, read the
 [language reference](references/language-reference.md) for placement rules.
 
 Parent scaffolding carries no duplicated module forms or contributions. Compile
@@ -243,6 +244,11 @@ a model only ever text-edited has none. A restart must not silently mint new IDs
 do not delete or overwrite conflicting identity state to get a green result, and do
 not text-rename identity-affecting declarations in a model that has it.
 
+Default root discovery preserves ancestor identity state and journals. Inspect
+`rootBindingConflict` in `open-workspace`/`workspace-state` when several state roots
+compete; do not delete state or mint replacement identities. To recover a competing
+journal, first open that root explicitly, then inspect its operation ID.
+
 A pending journal blocks normal work. Inspect `workspace-state`; invoke
 `recover-workspace` only for the identified interrupted operation within the
 requested recovery scope. Unexpected external edits block rollback. Preserve
@@ -278,10 +284,9 @@ that the code compiles or behaves. Read `references/mcp-tools.md#code-attachment
   it defines them and maps them onto V1 to V5. `screenplay --warnaserror` checks
   syntax plus the consistency rules (`PLAY0282`-`PLAY0294`) but never binds, so a
   clean run is not a bound or executable result.
-- Personas are report-only, operations and event sources/streams are authorable but
-  not executable (not admitted by any supported ESM version), and `generated`/`returns`
-  bind only from standalone 4.68.0 (ESM v7; not on the cratis 3.28.x bundle, not rendered by
-  Stage 4.24.2): none is a reason to drop or stub the construct.
+- Operations/exact numbers remain unadmitted; source/stream routes bind as ESM v8,
+  and generated values/responses as v7. CLI 3.41.0 render passes v7 to Stage but
+  refuses newer versions. A source contract is never dropped or stubbed to bind.
 - Distinguish authoring acceptance from `executableReady`; unsupported backend
   capabilities are not a reason to drop source constructs or invent stubs.
 - If execution is intended, validate with the owning downstream runtime as well.
@@ -301,7 +306,7 @@ a generated app that silently drops authored UI. Use the Screenplay-owned canoni
 corpus fixture path when it exists instead of copying `.play` examples into this
 repository.
 
-Repair and refactoring guidance follows Screenplay main `fd18129`. The Cratis
+Repair and refactoring guidance follows Screenplay v4.127.0. The Cratis
 CLI bundles its own Screenplay version, so check the installed `tools/list`
 schemas before relying on a view or argument named here (for example
 `dropped-comments` or `implementation-requirements`). Do not invent a command,

package/package/corpus/skills/cratis-screenplay-model-authoring/references/language-reference.md

@@ -6,6 +6,8 @@
 ## Contents
 
 - Accepted constructs
+- Caller, subject and stream nodes
+- Container dependencies and exact numbers
 - Complete model
 - Source validity is not execution
 - Not in the language yet
@@ -20,8 +22,8 @@ repository is the full list; this page is the authoring summary.
 ## Accepted constructs
 
 **Top level:** `domain`, `import`, `concept`, `type`, `policy`, `persona`,
-`authentication`, `trigger`, `theme`, `layout`, `ui profile`, `behavior`,
-`module`, `seed`, and the syntax-only `system` and `eventsource` (with its `stream`s).
+`authentication`, `identity`, `purpose`, `trigger`, `theme`, `layout`, `ui profile`, `behavior`,
+`module`, `seed`, authoring-only `system`, and admitted `eventsource` with its `stream`s (ESM v8).
 
 **Inside a module:** `description`, `authorize`, `import "<glob>"`,
 `screen`/`dialog` templates, `form`, `contribute`, `on`/`uses` behavior
@@ -58,13 +60,66 @@ compiling the entire document set.
 
 Concept primitives are `Uuid`, `String`, `Int`, `Decimal`, `Bool`, `Date` and
 `DateTime`; `Enum` is a separate concept kind whose members are indented below
-it. Concepts can carry `@pii`, `@sensitive`, reasons and validation.
+it. Concepts carry bare `pii` (`personal` alias), `secret`, reasons, personal-data
+qualifiers, secret scopes and validation. Legacy markers report PLAY0565 information;
+repeated header markers report PLAY0653 warning. Purposes declare the use/basis/retention
+separately; see command-surface `references/compliance.md`.
 
 Projections and captures use their dedicated sub-grammars. Inline code uses a
 tagged fence (` ```csharp `); the older language-line form still parses with
 warning `PLAY0397`. Query the MCP's `syntax-schema` instead of inventing JSON
 members or translating names from memory.
 
+## Caller, subject and stream nodes
+
+At v4.127.0 the typed syntax includes `IdentityExpressionSyntax` (`$identity`),
+`IdentitySyntax`, `IdentityDetailSyntax`, `ClaimIdentitySourceSyntax`,
+`QueryIdentitySourceSyntax`, `CodeIdentitySourceSyntax`, `FileIdentitySourceSyntax`.
+`ApplicationSyntax.Identity` carries the block; query schemas before editing JSON.
+Built-in caller paths are aliases of `$context.identity`; declared detail reads
+are authoring-only and refuse executable binding (PLAY0268), while the block alone
+does not block readiness. Claim/query sources have exactly one source and no body.
+See command-surface `references/context.md` for key/type/gate restrictions.
+
+`PropertySyntax.isSubject` marks an event's required unprotected scalar subject,
+omitted from structural JSON when false. It is lineage metadata (PLAY0270), not
+runtime subject propagation or generated C# `[Subject]`. Read-model marks are
+unsupported. `ReactionSyntax.RunsAs` / `ReactionIdentitySyntax` carry the system
+actor (ESM v10); MCP `declaration-details` includes `runsAs`.
+
+`EventStreamIdPartSyntax` and `streamIdParts` describe a composite stream-id schema;
+route mappings cover all named parts. Current routes are admitted as v8, not an
+old PLAY0268 gap. Never infer composite parts by splitting legacy scalar ids.
+
+## Container dependencies and exact numbers
+
+At Screenplay 4.125.0, modules and features accept `depends on <Name>`, one
+per line. Bare targets resolve inside out (siblings, ancestor siblings, root
+modules); qualified targets match an unambiguous trailing address. Merged files
+accumulate each owner's declarations in file-path order; imports affect board
+order, not accumulation. Dependencies are optional authoring metadata, not runtime
+or implementation order. See `cratis-screenplay-slice-design` `references/slicing.md`
+for coverage diagnostics and MCP `dependency-graph` `declarations` evidence.
+
+A top-level `numbers exact` preamble opts each file into bounded decimal source
+literals without Double rounding. All files/import barrels must agree on mode
+(PLAY0508–PLAY0513 diagnose directive/range/mode errors). Exact mode is authorable,
+not admitted by any supported ESM version (`PLAY0268`). Do not confuse this with
+ESM v7 generated values and responses.
+
+Typed roots (`ApplicationSyntax`, `ProjectionSyntax`, `CaptureSyntax`,
+`SpecificationSyntax`) carry `sourceOptions: {"numericMode":"exact"}`. Missing
+options default independently to Legacy, including nested roots; null/unknown
+options and conflicting modes reject. Exact literal slots use
+`{"literalType":"ExactNumber","value":"9007199254740993"}`: a canonical fixed-point
+string, not a JSON number/JavaScript Number. Plain numbers, legacy envelopes and
+noncanonical/out-of-range strings reject in Exact trees. An ExactNumber tag does
+not opt a Legacy root in. Change mode as a whole-tree edit (leaves and all root
+options), not just a flag; fragment printing keeps the owner's mode without a
+nested preamble.
+
+Sources: v4.125.0 `slices.md`, `folders.md`, `ast-authoring.md`, `grammar.md`.
+
 ## Complete model
 
 This registration model uses an inline event and context identity rather than
@@ -121,13 +176,20 @@ module Projects
 
 ## Source validity is not execution
 
+The table and binding inventory below retain their historical 4.66.0/4.68.0
+probe labels; do not use them as current tool admission evidence. At 4.125.0,
+`screenplay test` and MCP `run-specifications` expose reference execution,
+and sources/streams/routes bind as ESM v8. Operations and exact numeric mode
+still refuse binding. Use the installed tool and the version table in
+`cratis-screenplay-toolchain` for current verdicts, not an older negative probe.
+
 A construct can be in one of four states. Say which one you checked.
 
 | State | What establishes it | What it does not prove |
 | --- | --- | --- |
 | **Parsed** | `screenplay <folder> --warnaserror` or MCP authoring diagnostics: syntax plus the model-consistency checks (`PLAY0282`-`PLAY0294`, for example a specification event that no producer can emit, `PLAY0285`) | Binding, execution, or anything about attached code. It never binds, so it cannot report `PLAY0268`, and the tool never reads `file` attachments |
 | **Bound** | Semantic binding to the executable semantic model (ESM): MCP `executableReady`, executable diagnostics | That the reference execution plan admits the model, or that any specification passes |
-| **Reference-executed** | The reference runner passes the specification (library only: no MCP tool and no `screenplay` command runs it) | Target behavior; opaque code never runs here |
+| **Reference-executed** | `screenplay test` or MCP `run-specifications` passes the selected specification | Target behavior; opaque code and external services never run here |
 | **Target-executed** | Stage or a rendered application runs it with the implementations supplied | Nothing further in Screenplay |
 
 Map the states onto the verdicts of `cratis-screenplay-modeling-lifecycle`:
@@ -185,13 +247,14 @@ Screenplay 4.66.0 (before 3.28.2, Screenplay 4.60.1, differ where stated).
 | --- | --- |
 | Binds and runs in the reference runner | `StateChange`/`StateView` slices; `produces` including `when` conditions over command properties and literal tags; the portable validation rules, `matches email`, quoted `matches` patterns and `require` over command properties; declarative policies and `authorize` on modules, features, commands and keyed queries; `unique` constraints; projections as Chronicle lowers them, including variants, except the projection constructs in the next row; specifications, including `given caller`, `then denied` and `when append` |
 | Binds, but the reference execution plan refuses it | A projection-level `remove via join`; `all` beside removals, `children` or `nested`; a `join`, `children` or `remove via join` inside `nested`; any event-context value other than the event source identity in a projection mapping or key, such as `$eventContext.occurred`, `$eventContext.sequenceNumber` or `$eventContext.causedBy.subject` (`$eventSourceId` and `$eventContext.eventSourceId` run) |
-| Binds as ESM v6 on Screenplay 4.66.0, standalone and Cratis CLI 3.28.2 (probed); `PLAY0268` on Cratis CLI before 3.28.2 | `Automation` and `Translate` slices, reactions that produce or invoke, captures, top-level `trigger`, clock, trigger and capture specifications. The library reference runner evaluates them (v6 actions); no `screenplay` command or MCP tool runs it, and Stage 4.24.2 renders none of them (the whole automation is gap-fill) |
+| Binds as ESM v6 on Screenplay 4.66.0, standalone and Cratis CLI 3.28.2 (probed); `PLAY0268` on Cratis CLI before 3.28.2 | `Automation` and `Translate` slices, reactions that produce or invoke, captures, top-level `trigger`, clock, trigger and capture specifications. The current standalone `screenplay test`/MCP reference route evaluates admitted v6 actions; the historical Stage 4.24.2 probe rendered none of them (the whole automation is gap-fill) |
 | Reaction with trigger `reads` | Direct-producing (or code-bodied) reaction with `reads`: `PLAY0268` ("ESM v6 cannot protect that decision dependency", decision 0006), non-executable. Invokes-only reaction with `reads`: information only; the invoked command must declare and protect its own decision reads. Keep the `reads`; never remove them to obtain binding |
 | Binds as opaque code (v3); reference runner reports unsupported | Bodied reducers, bodied named rules, fenced `validate` blocks, code or file policies. A pure reducer body is the only attachment Stage 4.24.0 admits |
 | Information only, never blocks (probed) | `persona` (report-only: `PLAY0270`, the policies it lists must exist), `authentication`, `domain`, `seed`, descriptions and `file` provenance. A persona does not block binding and does not change behavior, so state persona scope in a description or a policy the model uses |
 | Binds as ESM v7 on standalone Screenplay 4.68.0 (source and release notes; `PLAY0268` on the 4.66.0 in Cratis CLI 3.28.x, probed) | `generated` properties and `returns` responses, generated fixtures and `then returns`: bound and executed by the reference runner; a policy, rule or requirement that references a generated value is `PLAY0273`, and a generated property on a concept with validation rules is `PLAY0268`. Stage 4.24.2 does not render them (`STAGE-ESM-016`, tracked in Stage#201): gap-fill |
-| Authorable, not executable (`PLAY0268`, probed) | `system` and `operation`, `eventsource` and `stream` (not admitted by any supported ESM version; see `cratis-screenplay-toolchain` `references/sources-and-streams.md`). The MCP reads and edits them (`declaration-details`, `find-fixtures`, `read-workspace` views `event-sources`/`event-streams`/`command-routes`) with `executionAvailable: false`. Keep them in the model as intent; do not strip them to make the model bind, and do not call the model executable |
-| Blocks binding (`PLAY0268`) | `@pii`/`@sensitive` concepts (probed: "compliance attributes require portable data-subject semantics"), command `handler` (never binds; a command cannot declare both `produces` and `handler`, `PLAY0035`), bare `rule <Name>`, `require` or conditions over read-model paths, dates and `today` in comparisons, `$context.tenant`/claims/roles/causation in `produces`, `$env` conditions, `file` constraints, unquoted `import` of an external contract, a read model whose keyed queries in its own slice do not share one `by` property (none, or two different properties; several queries over the same property bind), any query other than `=> <ReadModel> optional` with one caller-supplied `by` argument (so also observable, filtered, scoped and performer-backed queries), `$causedBy` and templates in projections |
+| Authorable, not executable (PLAY0268) | Systems/operations, exact numbers and refusal/redelivery remain unadmitted |
+| Current routing and actor admission | Sources/streams and command/specification routes bind and reference-execute as v8; reaction `runs as system role` supplies the invocation actor as v10 on 4.125.0. Whole-workspace binding determines executable availability; CLI/Stage realization remains separate |
+| Blocks binding (`PLAY0268`) | `pii`/`secret` concepts (also legacy spellings; historical probe: "compliance attributes require portable data-subject semantics"), command `handler` (never binds; a command cannot declare both `produces` and `handler`, `PLAY0035`), bare `rule <Name>`, `require` or conditions over read-model paths, dates and `today` in comparisons, `$context.tenant`/claims/roles/causation in `produces`, `$env` conditions, `file` constraints, unquoted `import` of an external contract, a read model whose keyed queries in its own slice do not share one `by` property (none, or two different properties; several queries over the same property bind), any query other than `=> <ReadModel> optional` with one caller-supplied `by` argument (so also observable, filtered, scoped and performer-backed queries), `$causedBy` and templates in projections |
 | Blocks binding (`PLAY0271`, legacy meaning) | Command `reads` and `concurrency` |
 | Deferred (`PLAY0269`, information) | Screens, layouts, templates, forms, contributions, UI profiles, themes, behaviors and `on`/`uses` |
 | Metadata only (`PLAY0270`, information) | `domain`, `seed`, `persona`, trigger and other descriptions, and `file` provenance on declarations |
@@ -220,16 +283,17 @@ full historical shapes, not deployed-schema immutability or a working migrator.
 Code attachment/source-map support likewise does not prove code round-trip
 execution equivalence.
 
-Decision 0023's operations and named event sources/streams are **authorable** at
-v4.68.0 (syntax only, see the table above and `operations.md`, `event-sources.md` in
-the Screenplay documentation): write them, but binding reports `PLAY0268` and nothing
-executes them, because no supported ESM version admits them (a number is assigned only
-at a release-ready admission, decision 0025). Do not drop them for the sake of a green bind.
+Operations remain authorable/unadmitted (PLAY0268). Named event sources/streams
+and routes bind and reference-execute as v8 on 4.125.0; reaction identity as v10.
+Use standalone `screenplay test` or MCP `run-specifications` for a reference
+verdict, and independently check CLI/Stage admission. Never drop a contract to bind.
 Generated values and `returns` are no longer in this group: they bind from 4.68.0 (ESM v7).
 Protected reads and `derive`/`provide` (not admitted by any supported ESM version) have no documented
-syntax at v4.68.0: do not teach or invent one. Affected-instance declarations, per-event data
-subjects, external event origin and query paging/sorting/change-set delivery also
-remain unavailable here.
+syntax at v4.68.0: do not teach or invent one. Affected-instance declarations and query paging/sorting/change-set delivery
+remain unavailable here. Event `subject` is report-only authoring metadata at
+4.127.0; public events/origin are admitted as ESM v9 (not provider realization).
+Purpose declarations, references and processing records are authoring metadata,
+not retention or lawful-processing enforcement.
 
 `Type optional` is canonical for admitted type references; `Type?` remains
 compatible with information `PLAY0479`. The modifier follows `[]` for an optional

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

@@ -9,6 +9,7 @@
 - Who owns the connection
 - The loop
 - One edit strategy
+- Self-describing identity migration refusals
 - Identity state (`.screenplay/identities.json`)
 - Read-only views worth knowing
 - Failures (use `failureKind`, never message text)
@@ -35,12 +36,17 @@ Cratis CLI before 3.28.2 bundled 4.60.1, whose tool set and views differ: read `
    notifications/initialized before using tools".
 3. Pass a physical path. Symbolic links and reparse points are refused, including
    `.screenplay` metadata.
-4. `tools/list` returns **29 tools**, or **30 on hosts that advertise the MCP-Apps
-   UI extension** (the extra tool is `visualize-model`). Read the schemas once per
-   connection; never hard-code a count or an argument list.
-5. A root given at startup is fixed for the connection: `open-workspace.path` may
-   name the same directory, anything else returns `RootChangeRefused`. Start a
-   separately authorized connection to model another application.
+4. Read `tools/list` schemas once per connection; never hard-code counts or
+   argument lists. MCP-Apps hosts also expose `visualize-model`.
+5. At 4.125.0 a startup root may switch to the same relative model folder in a
+   registered Git worktree of its repository. `open-workspace.path` accepts the
+   checkout or exact model folder. Shared Git directory and registration
+   back-pointer must agree physically; unrelated/malformed/unregistered roots,
+   submodules and `--separate-git-dir` checkouts refuse (`RootChangeRefused`).
+   Switching clears proposals and cached state, then uses that worktree's own
+   identities/journal. A pending journal blocks only its root. If an opened
+   worktree is removed, explicitly return to the startup root; if the startup
+   root is removed, start a new connection. No simultaneous named workspaces.
 
 ### Roots bug and the workaround
 
@@ -93,7 +99,9 @@ the server sends `roots/list` and serves `tools/list` after the reply).
 
 1. `tools/list` once per connection.
 2. Orient cheaply: `describe-application` summary, `diagnostics`, then scoped
-   `search-declarations`, `declaration-details`, `dependencies`. Paging with
+   `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`.
 3. `open-workspace` and keep `revision` and `catalogRevision`. Opening writes
    nothing. With `identityPersistence: "root-local-on-apply"` the identities file
@@ -111,8 +119,8 @@ the server sends `roots/list` and serves `tools/list` after the reply).
    Proposed, and its `sketch` argument previews a what-if of whole documents
    without writing. An
    unintended executable regression is discarded (`discard-proposal`) and
-   re-proposed. Intent the user has accepted that does not run yet (`system`/`operation`, `eventsource`/`stream`, and `generated`/
-   `returns` on a tool older than 4.68.0; `PLAY0268` by design)
+   re-proposed. Intent the user has accepted that does not run yet (operations,
+   exact numbers or refusal/redelivery; PLAY0268 by design)
    may be applied from a reviewed `Authoring` proposal: disclose the new
    diagnostics, report V3 as not binding-ready, and never drop or stub the
    construct. The server's own guidance is to apply such a proposal only when
@@ -154,10 +162,24 @@ 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` (and recipe-only `0397`) | `propose-repair` with `formatting` |
+| 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 |
 | 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 |
-| Syntax-only constructs | `system`/`operation`, `eventsource`/`stream` (and `generated`/`returns` before 4.68.0) | typed `propose-ast` edits; no automatic rename or routing repair exists |
+| Unadmitted constructs | systems/operations, exact numbers, refusal/redelivery | reviewed Authoring `propose-ast`; 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
+
+At Screenplay 4.127.0, read `identityMigrationIssues` on rejected proposals
+(conflict `InvalidIdentityMigration`). Each entry names typed `address.kind` and
+`address.parts`, and the input `arguments` it belongs in: `semanticRenames`,
+`eventRenames`, `retiredSemanticAddresses`, `retiredEventAddresses`. Stale renames
+name both endpoints; missing continuity lists rename/retirement alternatives,
+not an instruction to retire. Include both event-contract and semantic assignments
+and all assigned descendants. Rename/apply messages name the same offending addresses.
+Supply exactly the entries required for the intended change instead of retrying
+by trial and error. Re-read actual revisions when stale; never clear the catalog.
+Authority: v4.127.0 `mcp/reference.md`, `mcp/authoring-tools.md`.
 
 ## Identity state (`.screenplay/identities.json`)
 
@@ -175,6 +197,22 @@ the server sends `roots/list` and serves `tools/list` after the reply).
   "semantics"` returns identity assignments, not a model summary.
 - See "Make one coherent proposal" in SKILL.md for the exclusive-write prerequisite of `apply`.
 
+### Root discovery conflicts
+
+At Screenplay 4.125.0 default discovery preserves `.screenplay/identities.json`
+or `pending.json` on the ancestor-or-self path from the offered project to the
+discovered model. Empty metadata folders/backups do not count. With several
+state roots, the nearest the offered project wins. `rootBindingConflict` in
+`open-workspace`/`workspace-state` contains `kind: "WorkspaceRootConflict"`,
+`boundRoot`, ordered `stateRoots` and `pendingRoots`; it is omitted without a
+conflict. A journal anywhere on that path blocks bound-root reads/writes too.
+
+To recover a competing journal, explicitly `open-workspace` on its root (which
+may return `PendingOperation`), inspect `workspace-state` there, then recover
+that operation within the approved scope. Recovery at the outer root cannot
+recover a nested journal. Never delete metadata, migrate identities implicitly
+or create a fallback folder to bypass the conflict.
+
 ## Read-only views worth knowing
 
 - **`source-map`** (`read-workspace`): the compiler's semantic entries ordered by