@cratis/pi 7.22.0 → 7.24.0

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

@@ -207,8 +207,10 @@ skill):
 - Never use syntax the toolchain does not show compiling. Future-facing syntax only on request.
 - Constructs outside the narrower subset stay in the model as design-mode content; the gap is
   recorded and routed (P8: fallback with the model as contract).
-- Never remove `@pii`, `@sensitive`, authorization, date or state-dependent rules to reach V3 or
+- 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

@@ -131,6 +131,13 @@ down, rather than the one you get by forgetting."*
 language documents, but the grammar accepts any name — what scopes exist follows
 the identity model of whatever runs the document. A query declares at most one.
 
+At Screenplay 4.127.0, `scoped to` remains an opaque name, **not** a reference
+to a declared identity detail. An `identity` query source must be keyed and return
+one result (possibly optional), with a type compatible with the detail; its key
+uses only caller built-ins/claims/literals and its effective gate cannot depend
+on details (PLAY0641–0646). Source resolution is metadata, not runtime execution.
+See command-surface `references/context.md` for the full contract.
+
 Treat every `scoped to global` in a review as a question to answer, not a detail.
 
 ### `observable`
@@ -239,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

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md

@@ -27,8 +27,8 @@ Version pins live once in `cratis-screenplay-toolchain` `references/versions.md`
 | --- | --- | --- |
 | cratis CLI | `3.41.0` (`v3.41.0`) | `cratis render` options, exit codes, publication receipt, UI-profile rejection (`CLI-RENDER-007` to `CLI-RENDER-010`); tag pins Stage 4.51.3, Screenplay 4.114.0 and `Cratis.Arc.Screenplay` 22.54.0, with `cratis/stage:4.51.3` as the runtime image. UI-profile rejection and render-then-recover shipped in 3.41.0 (Cratis/cli#301). The screens release vector was verified on 3.40.7 (`af9f18e`) with `cratis/stage:4.51.1`. Reading baselines: 3.40.3, 3.39.0 and 3.28.3 (`8b43fef`) |
 | Stage | `4.51.3` (CLI 3.41.0 default) | admission (`STAGE-ESM-*`, and `PLAY0268` render refusals surfaced by the CLI), ownership manifest, `Customizations/` seams, Debug-only specifications, fail-closed guarded actions (`STAGE-SCENE-ACTION-001`) and interactions (`STAGE-SCENE-INTERACTION-001`). Older baselines: 4.49.5, 4.43.0 and `v4.24.2` (`32dcac4`) |
-| Screenplay | bundled `4.114.0`; standalone `4.125.0` | standalone compiler for V1 to V3; binding codes `PLAY0268` and the code-attachment rules, read at `v4.66.0`; claims made through `cratis` are 4.114.0 claims |
-| Rendered apps | Arc `22.25.0`, Chronicle `19.8.1`, Scene packages | `[ProtectedDecision]` (Arc 22.39.0 and later) is not available in code written into one; verify the generated package set before claiming exact Scene 4.14.0 runtime parity |
+| Screenplay | bundled `4.114.0`; standalone `4.127.0` | standalone compiler for V1 to V3; binding codes `PLAY0268` and the code-attachment rules, read at `v4.66.0`; claims made through `cratis` are 4.114.0 claims |
+| Rendered apps | Arc `22.50.5`, Chronicle `19.32.0`, Scene packages | Stage 4.51.3 scaffold; `[ProtectedDecision]` / `DecisionRead<T>` available to gap-fill, not emitted enforcement. Embedded reverse extraction disabled; verify generated packages before claiming exact Scene runtime parity |
 
 Facts were read at those tags and `cratis render` was run at 3.28.2 and 3.28.3 for the worked example
 (`references/worked-example.md`); with public CLI 3.40.7 it was run over the canonical
@@ -99,7 +99,7 @@ import-only root file.
    capability gap, tool skew or environment. Group by code and count; do not paste the list.
 3. **When admission fails** (case A) present the options, the user decides:
    (a) keep design mode and record the gaps; (b) narrow to renderable mode, where the modeler
-   changes the model for business reasons and **without** removing protection (`@pii`,
+   changes the model for business reasons and **without** removing protection (`pii`,
    authorization, rules); (c) deliver the non-renderable scope by hand (case C), with a ledger
    entry (`references/drift-and-ledger.md`). Partial render does not exist.
 4. **Publish.** The probe destination by default. Another destination needs the user's intent;
@@ -135,10 +135,11 @@ Adapters and non-renderable scope follow the contract rules of `cratis-applicati
   (`cratis-application-slice-conformance` `references/build-prompts.md`).
 - One ledger scope per `slice-implementer` brief; the brief carries addresses and paths, not contents.
 - Model-enforced rules realized in code (state-dependent rules) need a protected read or
-  concurrency scope; never claim them from prose. In a Stage-rendered app, Arc is 22.25.0.
+  concurrency scope; never claim them from prose. Stage 4.51.3 rendered apps have
+  Arc 22.50.5/Chronicle 19.32.0; API availability alone is not verified enforcement.
 - Adapters that call outside systems follow `cratis-engineering-effect-boundaries`; slice
   specifications follow `cratis-application-slice-specifications`.
-- Realization notes are the explicit realization requirements stated in a slice `description`
+- Realization notes are the explicit realization requirements stated in a slice `description` or `documentation`
   (definition: `cratis-application-slice-conformance`, `references/contract-and-precedence.md`).
   Executable parts (specifications, mappings, constraints) win over prose, and a contradicting description is a model defect to report.
 
@@ -153,7 +154,7 @@ Adapters and non-renderable scope follow the contract rules of `cratis-applicati
   unenforced there: ledger entry or target requirement, never "delivered".
 - The `cratis run` sandbox enforces neither validation nor authorization on its default engine; it
   is no evidence for denial behaviour.
-- Never remove `@pii`, `@sensitive`, authorization or rules to get a render through; report the gap.
+- Never remove `pii`, `secret`, authorization or rules to get a render through; report the gap.
 - Stop and ask only on a genuine contradiction between model, specs, descriptions and declared
   contracts, after reading the slice fully (`cratis-screenplay-modeling-lifecycle` `references/stop-or-assume.md`).
 - Commit set after a delivery the user accepts: the destination's `.cratis-render.json`,

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/drift-and-ledger.md

@@ -57,7 +57,7 @@ non-renderable scope:
 | fallback location | project and folder of the hand-written code |
 | spec mapping | `.play` specification to test name, one line each; missing tests listed |
 | field inventory | `n/n` command, event and read-model properties mapped; extras: none, or listed with reason |
-| realization requirements applied | explicit realization notes from slice descriptions applied, one line each; other description prose used as a hint is listed separately |
+| realization requirements applied | explicit realization notes from slice `description` or `documentation` applied, one line each; other description prose used as a hint is listed separately |
 | spec delta | at re-delivery: specifications added, changed or removed since `last verified`, each with test status |
 | divergences | where the code deliberately differs from the model, with reason and approver |
 | revisit trigger | issue and condition (for example "Stage#58 ships list queries") |

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/gap-fill-handoff.md

@@ -27,7 +27,7 @@ paths and addresses, not pasted contents:
   with the same name; never weaken, skip or delete one to pass. Do not edit managed files.
   Return a field inventory (command, event and read-model properties mapped to code locations)
   and list anything you added that the model does not state (expected: none). Explicit
-  realization requirements in the slice description bind adapters and fallback code, cannot
+  realization requirements in the slice `description` or `documentation` bind adapters and fallback code, cannot
   contradict executable parts and are never supplemented with inferred rules; descriptive prose
   that is not an explicit requirement is a hint. The repository's pattern wins over a
   generic template; report the mismatch. Stop on a contradiction and return an edit request.*
@@ -61,8 +61,8 @@ ambiguous addresses; contracts are never inferred from names.
 A rule that exists only in a description, or a state-dependent rule the model marks as not
 enforced, is unenforced in generated scope. List it in the ledger as a target requirement. In
 hand-written code it needs an atomic enforcement point: a protected read or a concurrency scope
-(in a Stage-rendered application Arc is 22.25.0, which has no `[ProtectedDecision]`; a
-hand-written application on a newer Arc may use it), or a Chronicle constraint. A stale view or
+(Stage 4.51.3 rendered apps have Arc 22.50.5/Chronicle 19.32.0: protected-read APIs
+are available to gap-fill, with projection/key admission and active enrollment), or a Chronicle constraint. A stale view or
 a caller-supplied status is not enforcement.
 
 ## Automation and Translate scope

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/renderability-gate.md

@@ -33,7 +33,7 @@ ESM). Only the probe answers renderability. `PLAY0270` entries are information,
 
 ## Triage rules
 - A capability gap never becomes a model fix by deleting meaning. Turning a list screen into a
-  keyed lookup, dropping `@pii`, removing authorization or a rule, or splitting a conditional
+  keyed lookup, dropping `pii`, removing authorization or a rule, or splitting a conditional
   outcome into separate commands is a **modeling decision** for the user and the modeler, made
   for business reasons, not to please the renderer.
 - A refusal never licenses dropping a specification, an event generation or a protection.

package/package/corpus/skills/cratis-screenplay-scenario-coverage/SKILL.md

@@ -27,9 +27,11 @@ language cannot express today are recorded, not faked. Grammar and outcome compa
 Screenplay v4.66.0 (`c89198b`) and v4.68.0 (`79801bf`, ESM v7 fixtures and `then returns`):
 `Documentation/screenplay/specifications.md` and the standalone compiler; `cratis` 3.28.2 and
 3.28.3 bundle Screenplay 4.66.0 (before 3.28.2 it bundled 4.60.1). The full pin table and the probes are in
-`cratis-screenplay-toolchain` `references/versions.md`. Specification obligations reported by
-the MCP (Screenplay#390) and multi-step storylines (Screenplay#394) are **not available**: the
-coverage matrix is built by hand and lifecycle families emulate storylines.
+`cratis-screenplay-toolchain` `references/versions.md`. At Screenplay v4.127.0,
+MCP `find-specification-obligations` derives SPEC001–SPEC008 from declarations;
+met means matching authored presence, not full coverage or passing execution.
+Use it to seed, never replace, the matrix. Multi-step storylines remain unavailable;
+lifecycle families emulate them.
 
 ## Interview phase
 **Skip if** the brief already states the coverage depth (rules, denials, state violations,
@@ -56,7 +58,9 @@ question is not four approvals.
    (Cannot lines, "only if", refusals, competition candidates, endings) as coverage seeds.
 3. **Inventory before drafting**: read commands, effective gates (own, feature, module), rules,
    constraints, productions, reactions, captures, read models and queries in scope; derive the
-   obligations from those declarations, not from specs already present.
+   obligations from those declarations, not from specs already present. Use scoped
+   `find-specification-obligations` and inspect unmet/message-specific obligations;
+   ambiguous references and opaque code are not inferred coverage.
 4. **Coverage matrix before any spec** (`references/coverage-matrix.md`). Rows: every command,
    reaction, capture, read model and gated query. Columns: the scenario types below. Each cell
    is `spec <Name>`, `n/a: <domain reason>`, `recorded: <why not expressible>`,
@@ -70,7 +74,12 @@ question is not four approvals.
    existing intentional fixtures (`references/scenario-catalogue.md` "Example data").
 7. **Draft commands**: happy path, each rule, denial, duplicates and retries, competing claims,
    state violations, alternative branches, compensation, external failure, evolution. In each
-   rejection vary only the value under test.
+   rejection vary only the value under test. Use typed `parameter`/named `case`
+   tables for a shared validation matrix, not for unrelated behaviors; rows are
+   cases, not typed fixture `example`s. `given caller as <Persona>` supplies one
+   authenticated policy witness for success/denial; use explicit callers for
+   anonymous/ownership or unsynthesizable personas. Syntax and complete model:
+   `cratis-screenplay-specifications` `references/persona-callers-and-cases.md`.
 8. **Separate view pass**: population, each update, accumulation, removal (with a surviving
    row), absence, ordering. Mark lifecycle branches as branches.
 9. **State-dependent rules**: `reads <View>` + `require <expr> message "..."` as stated intent,
@@ -97,9 +106,16 @@ question is not four approvals.
 | Ordering | Facts late or out of order? | view family with reordered givens; translation specs; else `recorded` |
 | External failure | The other system refuses, times out or answers twice? | outcome as a recorded fact (capture/translation), never a fake rejection |
 | Compensation | How is this undone, what does undoing free? | reversal command + spec showing the released claim or removed row |
-| Evolution | Do old facts still mean the same after a contract change? | spec on the new generation; compatibility note in `description` |
+| Evolution | Do old facts still mean the same after a contract change? | spec on the new generation; compatibility reasoning in `documentation` |
 | View | What does each screen show after each fact? | `given` events (`for`) -> `then query`; `when append` -> update/removal |
 
+For recovery intent, `when redelivered <Event> to <Reaction>` must select one
+definitely matching effective given and no undecided candidate. Name `stream`
+(with a complete id) or `no stream` when givens differ only by route; omitting it
+is a wildcard, not an unrouted selector. Redelivery remains authoring-only
+(PLAY0268), never evidence of an executed retry. Details:
+`cratis-screenplay-specifications` `references/examples-and-routes.md`.
+
 **Once, idempotent, exactly once are different claims.** A `unique event` constraint proves the
 *fact* occurs once per event source; it does not make *command handling* idempotent (a retry is
 rejected, not answered with success), and nothing in the model proves an *external effect* (an
@@ -112,7 +128,7 @@ target requirements.
 - `then` events are exact in count and order (`then events in any order` relaxes order only).
 - Command denial: `then denied` with no success or error outcome. Read-only query denial:
   `then query <Query>` with `arguments` and no `result`, then `then denied`. Every gated command
-  or query spec needs `given caller` (module and feature gates count); an authorized scenario
+  or query spec needs `given caller` or `given caller as <Persona>` (module and feature gates count); an authorized scenario
   gets no inferred fixture (PLAY0389). Unauthorized is never `then error`.
 - Duplicate and competing specs use `when <Command>`; `when append` is for projection and
   automation triggers, and for a constraint the command's own validation would reject first.
@@ -130,7 +146,7 @@ target requirements.
   never `n/a` automatically. This matches `cratis-screenplay-specifications`, which also
   requires one rejection spec per concept rule. Business rules get one rejection spec each.
 - Persona Cannot lines are intent: each needs an executable gate plus a `then denied` spec whose
-  caller carries that persona's roles and claims, else record a gap.
+  caller is a synthesized persona witness or an explicit gate fixture, else record a gap.
 - Descriptions are not rendered: a rule only in prose is unenforced in rendered scope; turn it
   into a rule layer, a spec or a recorded target requirement.
 - Prove projections with events (`given`/`when append`), not `given readmodel`; seed read models
@@ -149,7 +165,7 @@ target requirements.
 - Read models are a separate, equally mandatory pass: a model with dozens of command specs and no
   read-model spec is not scenario-complete. Population, then update or removal where an event
   supersedes a row.
-- The why behind each business rule is written down (slice `description`), not only the what.
+- The why behind each business rule is written down (slice `documentation`), not only the what.
 - Good and bad forms of givens, outcomes and rejections: `references/scenario-examples.md`.
 
 ### Review questions

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/coverage-matrix.md

@@ -9,7 +9,7 @@
 - Worked example (`berth-reservations.md`, design mode)
 
 Write it **before** drafting specs, keep it in `.ai-work/screenplay/<model-slug>/coverage.md` (or the
-`STATE.md` beside it), and update it with the specs. Reviewers check it against the model. The Screenplay MCP does not yet report which specifications a command, read model, policy or constraint still lacks (Screenplay#390, open, not available): the matrix is that report, built by hand from the declarations.
+`STATE.md` beside it), and update it with the specs. Reviewers check it against the model. Screenplay 4.127.0 MCP `find-specification-obligations` seeds the inventory (SPEC001–SPEC008), for command success, requirements, command/concept validation, effective authorization gates, value constraints, read models, projection removals and reaction outcomes. A met row proves matching authored presence, not full coverage or passing execution: the matrix still records domain judgments and scenario types the heuristic cannot infer.
 
 ## Cell values
 - `spec <Name>` - written; the name exists in the model.

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/invoicing-dues-design.md

@@ -13,6 +13,11 @@ Keep those lines: they state real intent and are never
 replaced by prose. The runnable counterpart, which holds no stored-state rule, is
 `invoicing-dues-example.md`; `scenario-examples.md` copies `ReversingAReceivedPayment` from here.
 
+The excerpt's Stage API-availability comment describes the historical Stage 4.24.x
+scaffold. Stage 4.51.3 pins Arc 22.50.5/Chronicle 19.32.0: protected-read APIs are
+available to gap-fill, not emitted protection or `.play` rule admission. The
+original compiled source is retained unchanged.
+
 ```screenplay
 // Scenario coverage design-mode example: stored-state rules of invoicing club dues (complete document).
 // Design mode: `reads` is PLAY0271 and `require` over a view is PLAY0268 at binding (the only

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/scenario-catalogue.md

@@ -80,9 +80,12 @@ name them as unfinished.
   (commands: no other outcome; read-only queries: `then query <Query>` with `arguments`, no
   `result`, then `then denied`; or `when query` + `then denied`). See `RefusingASkipper`.
   An empty `given caller` block is the anonymous caller.
-- Specs cannot name a persona: write the caller as the roles and claims that persona's
-  policies grant and name the spec after the persona. One denial per persona that can reach the
-  screen but may not act. Derive fixtures from the effective Boolean gate: AND - isolate each
+- Use `given caller as <Persona>` for one authenticated witness synthesized from
+  that persona's policies (4.127.0). Inspect the leftmost buildable `or` choice;
+  it does not represent every possible caller. Use explicit roles/claims for
+  anonymous or ownership fixtures, missing conjuncts, or refused synthesis.
+  One denial per persona that can reach the screen but may not act. Derive
+  fixtures from the effective Boolean gate: AND - isolate each
   missing conjunct; OR - a caller meeting any permitted alternative must succeed (a success
   spec, not `then denied`); denial only when the whole gate is false.
 - Ownership policies (`claim ... matches subject|<property>`): the denial gives the right role
@@ -184,7 +187,7 @@ name them as unfinished.
 ## 11. Evolution compatibility
 - Ask (when an event's contract changes): "Do facts already stored still mean the same?"
 - Compatible change (added property with a defined default): declare the new generation;
-  specify behaviour on the new generation; write the default for old facts in `description`
+  specify behaviour on the new generation; write the default and its reason for old facts in `documentation`
   (Screenplay does not express upcasters). Change of meaning: a new event, with its own specs.
 - Renaming a stored event keeps an `id "<OldName>"` pin. A rename the brief requests is done in
   this pass by the identity owner (`cratis-screenplay-modeling-lifecycle`); never leave it silently unapplied.

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/scenario-examples.md

@@ -29,7 +29,7 @@ Screenplay specifications.
 | Then (success) | every production with payload and `for` | "an event is produced" |
 | Then (refusal) | `then error "Invoice already settled"`, the rule's own message | `then error` with no message, or `then error ""` |
 | Then (denial) | `then denied` | `then error` for a caller who is not allowed |
-| Reason | the slice `description` says why the rule exists | the rule appears only in a spec title |
+| Reason | slice `documentation` says why the rule exists | the rule appears only in a spec title |
 
 ## 1. Command: success, rule rejection and denial
 One spec for the success, one per rule (varying only the value the rule checks), one denial.

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/scenario-workshop.md

@@ -75,7 +75,7 @@ survive; ask what a caller who may not look sees.
 - Do not perfect a scenario in the room. Capture it with its open question and move on.
 - Every "what if...?" from anyone becomes a named candidate at once.
 - Record why a rule behaves as it does when the room explains it; the modeler puts it in the
-  slice `description`.
+  slice `documentation`.
 
 ## Multi-role check (before leaving the room)
 - Domain expert: is this the right business behaviour and message?

package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/spec-forms-by-mode.md

@@ -4,7 +4,7 @@ The subsets themselves (what binds, what renders) are owned by `cratis-screenpla
 (its executable and renderable subset references); version facts by its `references/versions.md`. This file
 says what that means for writing specs. A form outside the chosen mode is never deleted from a
 design model: keep it and record the gap. The detailed Stage 4.24.x rows below
-retain historical admission evidence; current pins are Screenplay 4.125.0 / CLI
+retain historical admission evidence; current pins are Screenplay 4.127.0 / CLI
 3.41.0. Run actual target admission instead of assuming old restrictions carry over.
 Typed example/override forms: `cratis-screenplay-specifications`
 `references/examples-and-routes.md`.

package/package/corpus/skills/cratis-screenplay-scenario-coverage/verification.json

@@ -6,7 +6,7 @@
     { "kind": "skill-contains", "value": "Coverage matrix before any spec" },
     { "kind": "skill-contains", "value": "Once, idempotent, exactly once are different claims" },
     { "kind": "skill-contains", "value": "Unauthorized is never `then error`" },
-    { "kind": "skill-contains", "value": "Screenplay#390" },
+    { "kind": "skill-contains", "value": "find-specification-obligations" },
     { "kind": "skill-contains", "value": "v4.68.0" },
     { "kind": "skill-contains", "value": "false PLAY0285" },
     { "kind": "skill-contains", "value": "One behaviour per spec" },

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

@@ -31,7 +31,7 @@ Lifecycle, modes and hand-offs: `cratis-screenplay-modeling-lifecycle`.
 Skip if the request already names the command origins (screens, reactions, outside systems),
 the decision behind each shown field, and how fresh each view must be. Otherwise ask, in one
 batch, only what is missing. Unattended: assume visibly, record each assumption in the phase
-report and the slice `description`, and continue.
+report and slice `documentation`, and continue.
 
 1. **Origin of each action.** Is it (A) user-initiated only, (B) automated, (C) a mix, or
    started by a clock or outside system (schedule, webhook, feed)? Impact: separates screen
@@ -80,8 +80,8 @@ report and the slice `description`, and continue.
    standing in for a rule. Place each rule in its layer (`references/rule-layers.md`). A rule
    over stored state is written as `reads <View>` + `require ... message "..."` and marked
    **NOT enforced in the model today** in the slice `description`, with its target named (Arc
-   `[ProtectedDecision]` + `DecisionRead<T>` on Arc 22.39.0+, not available in Stage-rendered
-   apps; Chronicle DCB; or a constraint). Never copy state
+   `[ProtectedDecision]` + `DecisionRead<T>` on Arc 22.39.0+ (available to gap-fill
+   code with Stage 4.51.3's Arc 22.50.5/Chronicle 19.32.0); Chronicle DCB; or a constraint). Never copy state
    into the command as input or hide a rule in `handler` / hint prose; descriptions are not
    rendered (Stage#178). Fill the **refusal inventory**: success, each distinct refusal with
    layer and message, and the denied persona.
@@ -93,7 +93,16 @@ report and the slice `description`, and continue.
    `$context.occurred` or caller identity. No event-source id in the payload (it is the `for`);
    references to other instances are payload. No nullable property by default (a required value
    or a separate event). No PII on the identifier; one data subject per stream. Add a field only
-   when something downstream needs it.
+   when something downstream needs it. At 4.127.0 personal values use bare `pii`,
+   operational secrets `secret`; declare processing use/basis/retention in `purpose`,
+   not a reason. An event-property `subject` may identify a different person from
+   the stream but is report-only, not runtime propagation. See command-surface
+   `references/compliance.md`.
+   Trace caller details to claims or a keyed single-result identity-source query
+   (built-in/claim/literal key, detail-independent effective gate, compatible result).
+   The `identity` block is authoring metadata; executable `$identity.<detail>` reads
+   remain PLAY0268. `scoped to` is opaque, not a detail reference; see command-surface
+   `references/context.md`.
 5. **Events or views?** For each value someone needs: was it decided or supplied (event), or
    can it be worked out from facts already recorded (view)? Test, anti-patterns and where the
    outputs of an automation go: `references/read-model-design.md` *Events or views*. Decided calculations (a quoted
@@ -120,7 +129,7 @@ report and the slice `description`, and continue.
    actor sees each state change's result. Beyond Level 1: `cratis-screenplay-ui-composition`.
 8. **Lineage pass.** Build the matrix in `references/field-lineage.md` from the `.play` files
    (read them), not from memory or an earlier summary. For each read model, write one line per
-   contributing event in its StateView slice `description`: which fields it sets and why. An
+   contributing event in its StateView slice `documentation`: which fields it sets and why. An
    event with no reason does not belong in the view. A field without an origin is a gap: add
    the missing input or event field, or record an open question. Never invent a source.
 9. **Slice and continue** (`references/slicing.md`): state-transition table per entity; one
@@ -154,9 +163,14 @@ report and the slice `description`, and continue.
 
 - One command per `StateChange` slice (renderable: required, plus no `produces when`).
 - One business decision usually produces one event; a decision establishing several facts the
-  business recognises separately may produce several (say why in the `description`).
+  business recognises separately may produce several (say why in `documentation`).
 - Copy an identity into an event payload only when a consumer needs it as a value.
-- Keep durable design rationale in slice `description` text, not `//` comments.
+- Keep the one-line summary in `description`, including short status markers such as
+  **NOT enforced in the model today** (with its target) or **ASSUMED**; record durable
+  reasoning, assumptions, causes and rejected alternatives in fenced Markdown
+  `documentation` on the module, feature, slice, command, event, read model or reaction, not `//` comments or disconnected notes. These are report-only, not
+  enforcement. Read [model reasoning](references/model-reasoning.md) for owners,
+  syntax, folder merge and PLAY0558/0559.
 - Rule coverage: for each value carrying a rule, list every path that sets it
   (`references/slicing.md`). A constraint on a claim covers every event setting that claim;
   value invariants live in the concept so they travel; command-level conditions are reviewed
@@ -190,7 +204,7 @@ Slice design is done when these hold; otherwise report what is open.
       denied persona); every gated command and query has a `then denied` row.
 - [ ] Every event is past tense, a specific change, and consumed or justified.
 - [ ] Every read model has a consumer and, when the scope is executable, one unambiguous key (keyed queries all using the same `by` property).
-- [ ] Every StateView `description` gives a reason per contributing event; every read-model
+- [ ] Every StateView's `documentation` gives a reason per contributing event; every read-model
       field and screen field is traced; every `from` event sets a field.
 - [ ] No `screen` without `data` or `action`; every acting screen has `data` or a stated
       exemption.

package/package/corpus/skills/cratis-screenplay-slice-design/references/command-inventory.md

@@ -16,7 +16,7 @@ and each persona that must be denied becomes a `given caller` fixture. Build it
 ## Command card
 
 Fill one card per command before (or while) writing the slice. Keep it in the phase report;
-durable rationale goes in the slice `description`.
+durable rationale goes in fenced Markdown slice `documentation`.
 
 ```text
 Command:        <ImperativeBusinessName>  (one decision)
@@ -76,7 +76,8 @@ Rules for filling it:
   as a gap. Persona description text is intent only.
 - A refusal that depends on stored state is a row marked **NOT enforced in the model today**
   with its target (Arc `[ProtectedDecision]` + `DecisionRead<T>` where Arc 22.39.0 or later is
-  available, which Stage-rendered apps are not; Chronicle DCB, or a
+  available, including Stage 4.51.3's rendered package set for gap-fill, not emitted
+  protection; Chronicle DCB, or a
   constraint). It still gets a spec row, because the intended behaviour is the contract.
 - A decided refusal never goes to open questions: it goes here, then to scenarios.
 - A refusal message is a fact of the design; keep the wording identical in the rule, the
@@ -101,7 +102,7 @@ Rules for filling it:
 | AssignLocker | caller is not an attendant | `authorize IsAttendant` | denied: Customer | RefusingACustomerAssigningALocker |
 | AssignLocker | locker already has a request | constraint `OneRequestPerLocker` | "The locker is already assigned" | AppendingASecondAssignmentOfALocker (`when append`: the command's own `require` would reject first) |
 | AssignLocker | request already has a locker | constraint `OneLockerPerRequest` | "The request already has a locker" | gap |
-| AssignLocker | locker is not free | `reads` + `require`, NOT enforced today | "The locker is not free"; target: `[ProtectedDecision]` (Arc 22.39.0+; unavailable in Stage-rendered apps, so a capability gap there) or DCB on the locker stream | RejectingASecondAssignmentOfALocker (pins the message; blocked until the target exists) |
+| AssignLocker | locker is not free | `reads` + `require`, NOT enforced today | "The locker is not free"; target: `[ProtectedDecision]` (Arc 22.39.0+; available to Stage 4.51.3 gap-fill, not emitted protection) or DCB on the locker stream | RejectingASecondAssignmentOfALocker (pins the message; blocked until the target exists) |
 | AssignLocker | request is not waiting | `reads` + `require`, NOT enforced today | "The request is not waiting for a locker" | gap (same) |
 | LockerById, ListLockers | caller is anonymous | module `authorize IsAuthenticated` | denied: no caller | RefusingAnAnonymousLockerLookup, RefusingAnAnonymousLockerList |
 | RequestById | caller is anonymous | module `authorize IsAuthenticated` | denied: no caller | RefusingAnAnonymousRequestLookup |
@@ -124,4 +125,5 @@ not been asked the refusal questions.
 - Refusals recorded as prose in the `description` with no layer and no spec row.
 - Personal data or secrets as command input: values are by default recorded in the causation chain, so treat them as permanent
   (retention can be configured in newer Chronicle; verify it, never audit secrets).
-  Mark the concept `@pii` or record the need; never put `@pii` on the identifier's concept.
+  Mark concepts bare `pii` for personal data or `secret` for operational secrets,
+  never on the identifier; declare use/basis/retention in a purpose, not a reason.

package/package/corpus/skills/cratis-screenplay-slice-design/references/field-lineage.md

@@ -33,7 +33,7 @@ Those are the portable sources. The event-source id is the `for` value, not a pr
 an event field (same-named fields map automatically - AutoMap is on; its matching differs between flat and scoped projections, see `read-model-design.md` "Building it");
 `$eventSourceId` (the instance identity); a literal (status words); a counter or arithmetic;
 a join on another event stream; children for collections. A reducer is opaque: write its
-lineage in the slice `description`. A read model built by a query `performer` (no events)
+lineage in slice `documentation`. A read model built by a query `performer` (no events)
 has lineage outside the model; say where.
 
 **Screen field** - from the query result named in `data ... via query`. A screen showing a
@@ -74,7 +74,7 @@ Filled for `worked-example.md`:
 
 ## The reason line per contributing event
 
-The matrix is the audit; the durable record is the StateView slice `description`: one line per
+The matrix is the audit; the durable record is StateView slice `documentation`: one line per
 contributing event saying which fields it sets and why. Write it as a tagged text block in a
 real model (a bare fence warns with `PLAY0397`). `worked-example.md` uses one-string
 descriptions only so that it stays a single compiling fence.