@cratis/pi 7.37.0 → 7.38.0

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

@@ -5,6 +5,7 @@
 - Finding fields
 - Root causes
 - Defect or business question?
+- Question notes
 - Verdict rules
 - Findings across a re-review
 - Wording
@@ -143,6 +144,31 @@ constraint or projection).
 - An open question is genuinely unanswered. A refusal the business already decided is a
   `then error` or `then denied` specification, not a question (E9).
 
+## Question notes
+
+On Screenplay 4.144.0, inspect `list-model-notes` with scope and `state: "all"`,
+including `view: "findings"`. `model-note.open-question` is an info MCP/CLI-only
+finding, no PLAY code and no V1 failure. List orphaned questions explicitly;
+review `orphanedNotes` on source proposals, and treat null/unreadable as unknown.
+A read-only reviewer never writes notes: return a `question` note request for the
+owning session, anchored to the element with consequence and assumption. Existing
+questions should be cited by note ID; new questions must not live only in chat,
+session state or `description` text. Never put secrets or personal data in note
+text, authors, references or resolutions.
+
+Read model-authoring [model notes](../../cratis-screenplay-model-authoring/references/model-notes.md)
+when preparing that request or judging resolution evidence. Cite the project's
+own decisions with `refs: [{ "id": "D123" }]`; the owner resolves with
+`by: "external-decision"` and required `ref: { "id": "D123" }` when D123 answers
+it. Verify the answer became a specification, a description or a project-owned
+decision record; a resolved note is not behavioral proof. Ask the owner to reanchor
+or resolve affected notes before source apply; resolution alone leaves an orphan.
+
+The optional `--open-questions fail` gate is in standalone Screenplay 4.144.0,
+not Cratis CLI 3.53.1. Report it separately from V1–V5. Evidence: Screenplay
+`v4.144.0:Documentation/screenplay/model-notes.md:12-77,93-121`,
+`Documentation/screenplay/mcp/reference.md:457-520`; source lines in the linked guide.
+
 ## Verdict rules
 - **FAIL**: any critical finding, or a verdict line the mode requires fails.
 - **PASS WITH WARNINGS**: no critical; one or more major or minor findings, or open business

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

@@ -5,6 +5,13 @@
   "assertions": [
     { "kind": "skill-contains", "value": "all *known* producers", "file": "references/public-keys-and-routes.md" },
     { "kind": "play-compiles" },
+    { "kind": "skill-contains", "value": "A read-only reviewer returns `question` note requests" },
+    { "kind": "skill-contains", "value": "`state: \"all\"`", "file": "references/report-template.md" },
+    { "kind": "skill-contains", "value": "`model-note.open-question`", "file": "references/report-template.md" },
+    { "kind": "skill-contains", "value": "`orphanedNotes`", "file": "references/report-template.md" },
+    { "kind": "skill-contains", "value": "`by: \"external-decision\"`", "file": "references/report-template.md" },
+    { "kind": "skill-contains", "value": "Verify the answer became a specification", "file": "references/report-template.md" },
+    { "kind": "skill-contains", "value": "Never put secrets or personal data", "file": "references/report-template.md" },
     { "kind": "skill-contains", "value": "PASS WITH WARNINGS" },
     { "kind": "skill-contains", "value": "Every finding is pinned to one declaration" },
     { "kind": "skill-contains", "value": "edit request" },

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

@@ -64,10 +64,15 @@ STATE.md); a real trade-off is flagged to the user, never resolved by cutting th
 (`references/completeness-self-check.md`).
 
 Three unresolved things, never conflated: an **open question** (business meaning nobody decided:
-record it against a declaration address with the assumption in use; it closes when answered, never
-by deletion), a **decided rejection** (a known refusal: a specification, `then denied` or
+record it as a `question` note anchored to the element, with the assumption in use;
+not just chat, STATE.md or `description` text; it closes when answered, never by deletion),
+a **decided rejection** (a known refusal: a specification, `then denied` or
 `then error`, never a note) and a **contradiction** (model, specs and an agreed fact disagree:
 stop that scope and report). Finding tiers: `references/principles.md`.
+Read [question notes](references/stop-or-assume.md#durable-question-notes) when
+recording or answering an open question: cite decisions in `refs`, resolve with
+`by: "external-decision"`, then realize the answer. Never put secrets or personal
+data in note text.
 
 ## Modes (state the mode in the first output line)
 | Mode | Use | Done when |
@@ -108,18 +113,9 @@ After each phase write a phase summary (done, carry-forward, open questions) to
 the next skill loads (`references/phases.md`). Legacy: `cratis-screenplay-legacy-extraction`.
 
 ## Interview phase (P0)
-**Skip if** the request already states the domain, the source, the goal and the constraints.
-Otherwise ask only what is missing:
-1. **Domain**: what business process, in two or three sentences?
-2. **Source**: requirements, ideas, an existing system (legacy entry), a `.play` (change entry)?
-3. **Goal**: learning, documentation, validation, executable behavior, generated code (the mode)?
-4. **Constraints**: outside systems, data sensitivity, who can answer, target stack.
-5. **Starting point**: from scratch, or which phase outputs exist?
-
-Confirm in one sentence only when something was inferred: "So we model <domain>, goal <goal>,
-mode <mode>, starting at <phase>. Right?" Unattended: assume visibly and record asked versus
-assumed in STATE.md (`references/stop-or-assume.md`). Mid-workflow entry: ask which phases are
-done; never rerun a completed one, start at the first incomplete.
+Skip if domain, source, goal and constraints are stated. Otherwise read
+[intake](references/intake.md) when entering P0: ask only for missing context,
+assume visibly unattended and never rerun completed phases.
 
 ## Run protocol: stop or assume
 1. **Start**: read STATE.md; check the source identity; load the phase skill before authoring
@@ -214,7 +210,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 documentation, constraints, and decided rejections.
+Read `references/worked-example.md` when needing reasoning, constraint and rejection examples.
 Read `references/core-rules-digest.md` when you need the one-page card of element names, causality, open-question-versus-decided-failure and the anti-patterns to reject early.
 
 ## Gate
@@ -223,7 +219,9 @@ address and assumption; every decided rejection is a specification; no protectio
 the packet opens with `Outcome:`; STATE.md is current.
 
 ## Verified product sources
-Full pin table: `cratis-screenplay-toolchain/references/versions.md`. Read `cratis-screenplay-toolchain/references/versions.md` when selecting or reverifying tool versions. Current pins (Stage 4.73.1, cratis CLI 3.53.1 and the rest) are in that file. Older source reads used here: Screenplay
+Model notes: Screenplay `v4.144.0:Documentation/screenplay/model-notes.md:12-77`,
+`decisions/0045-model-notes-sidecar.md:40-79`; exact tool sources in model-authoring
+`references/model-notes.md`. Full pin table: `cratis-screenplay-toolchain/references/versions.md`. Read `cratis-screenplay-toolchain/references/versions.md` when selecting or reverifying tool versions. Current pins (Stage 4.73.1, cratis CLI 3.53.1 and the rest) are in that file. Older source reads used here: Screenplay
 `v4.66.0` (`c89198b`): `Source/DotNET/Tool/Program.cs` (`--warnaserror`, folder mode),
 `Source/DotNET/Screenplay/Semantics/SemanticModelBinder.cs:209-216` (personas are report-only),
 `Documentation/screenplay/{constraints,specifications}.md`, `mcp/reference.md` (`modelRevision`);

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/core-rules-digest.md

@@ -77,8 +77,13 @@ matters, a destination. A field with no origin is a gap to resolve, not a detail
 See `cratis-screenplay-slice-design` `references/field-lineage.md`.
 
 ## Open question versus decided failure
-- **Open question.** Genuinely undecided. It goes in session state (`STATE.md`) or the review
-  report and stays open until someone answers it. Resolving means answering.
+- **Open question.** Genuinely undecided. Record an anchored `question` note in
+  committed `.screenplay/notes.json`; STATE.md/reports carry its note ID and
+  assumption. Not only chat or `description` text. Resolving means answering:
+  cite project decisions in `refs` and resolve by `external-decision` when they
+  supply the answer, then realize it as a specification, description or decision
+  record. Read `stop-or-assume.md` "Durable question notes" when doing this.
+  Never put secrets or personal data in notes.
 - **Decided failure.** A rejection or error whose behavior is already decided ("payment fails,
   refuse, no event"). Model it as a `specification` with `then error` or `then denied`. It is
   permanent specified behavior, not a note waiting on an answer.
@@ -125,7 +130,7 @@ for modelers. The full signal, consequence and fix per shape is in
 - [ ] Every process starts at a screen or form action, a reaction, a clock or application trigger, or a capture.
 - [ ] No two state changes are chained without a trigger between them.
 - [ ] Every persona has a Cannot line backed by a gate and a denial specification, or a recorded gap.
-- [ ] Every decided failure is a specification; every open question is in session state.
+- [ ] Every decided failure is a specification; every open question is an anchored note with its ID in session state.
 
 This is the fast pass; the full audit is `cratis-screenplay-model-review`
 `references/checklist.md`, and the closing quality checklist is in `references/phases.md`.

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

@@ -48,7 +48,7 @@ V5 delivery: ...
 - <phase>: <skip condition met>
 
 ## Open questions (business)
-- Q3 <address>: <question> - matters because <...> - assumption in use: <...> | blocked scope
+- Q3 [<note_id>] <address>: <question> - matters because <...> - assumption in use: <...> | blocked scope
 
 ## Capability and tool-version gaps
 - <construct> blocked in <mode> (<code>) - kept in model; route: <fallback or issue>
@@ -123,7 +123,10 @@ Expected impact: diagnostics <...>; identity <preserved via rename or pin>; spec
 ## 4. Cold-readable questions
 A question sent to a person is anchored to an address and understandable without opening the
 model: `Qn <address>: <gap> - matters because <consequence> - <assumption in use>`. Put one
-question per line; group by address.
+question per line; group by address. These packet rows point to committed `question`
+notes, not a competing question register. Include the returned note ID; if note
+tools are unavailable, explicitly return a note request to the owning session.
+Read `stop-or-assume.md` "Durable question notes" when recording or resolving one.
 
 ## 5. Who records the model used
 Each agent writes the model it ran on into the packet when the harness exposes it, else

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

@@ -0,0 +1,21 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Interview phase (P0)
+
+**Skip if** the request already states the domain, the source, the goal and the constraints.
+Otherwise ask only what is missing:
+1. **Domain**: what business process, in two or three sentences?
+2. **Source**: requirements, ideas, an existing system (legacy entry), a `.play` (change entry)?
+3. **Goal**: learning, documentation, validation, executable behavior, generated code (the mode)?
+4. **Constraints**: outside systems, data sensitivity, who can answer, target stack.
+5. **Starting point**: from scratch, or which phase outputs exist?
+
+Confirm in one sentence only when something was inferred: "So we model <domain>, goal <goal>,
+mode <mode>, starting at <phase>. Right?" Unattended: assume visibly and record asked versus
+assumed in STATE.md (`stop-or-assume.md`). Mid-workflow entry: ask which phases are
+done; never rerun a completed one, start at the first incomplete.
+
+Open business questions become anchored `question` notes, with their note IDs in
+STATE.md. Read [durable questions](stop-or-assume.md#durable-question-notes) when
+recording an assumption or awaiting an answer.

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

@@ -19,7 +19,8 @@ comments (Stage#178 closed): model the rule first, never treat prose as enforcem
 
 Cover, briefly and only where real:
 1. Scope: the business process and the identities its streams are keyed by.
-2. Assumptions beyond the brief, and why (each also listed in STATE.md).
+2. Working assumptions beyond the brief and why, linked to an anchored `question`
+   note when unsettled; STATE.md carries the note ID.
 3. Rules kept as constraints or specifications rather than events, so a missing event is not read
    as an oversight; state-dependent rules marked NOT enforced in the model today, with the named
    target enforcement.
@@ -28,17 +29,20 @@ Cover, briefly and only where real:
    deliberate omission ("this view drops cancelled bookings").
 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 documentation and the question agree.
+   anchored question note ID or project-owned decision that records the choice,
+   so documentation and the question agree. Use `refs` for decision identifiers;
+   the question itself is not tracked in prose.
 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 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. Complete the feature's reasoning at the end of P3.
+At any phase, record unresolved assumptions as `question` model notes; use
+`documentation` for settled alternatives or non-obvious constraints, never routine
+step narration. Read `stop-or-assume.md` "Durable question notes" when using refs,
+resolving by external decisions or realizing an answer. Never put secrets or
+personal data in note text. 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.
 

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

@@ -28,6 +28,35 @@ user can accept, and approvals not yet given always stop.
 - One closed outcome per run. A run that neither progressed nor closed is a failure to report:
   say what blocked it and which question would unblock it.
 
+## Durable question notes
+
+Record each open modeling choice as a `question` note on its element in committed
+`.screenplay/notes.json`, not only chat/STATE.md or `description` text. Include the
+question, consequence and assumption in use (or blocked scope). Keep its returned
+note ID and address in STATE.md/packets; before an element exists, anchor to the
+application or nearest identified container and name the intended element in text.
+Never put secrets or personal data in note text, authors, refs or resolutions.
+
+Read model-authoring [model notes](../../cratis-screenplay-model-authoring/references/model-notes.md)
+when recording or answering questions: discover tools, list with pinned notes
+revision, `propose-model-notes`, review `read-proposal view=notes`, then authorized
+`apply`. If the installed bundle lacks notes, report the capability gap and carry
+an explicit note request to the owner; do not pretend a chat/description is a note.
+
+Cite the project's own decisions with `refs: [{ "id": "D123" }]`. When D123 is
+the answer, resolve with `by: "external-decision"` and required
+`ref: { "id": "D123" }`, explanatory text and a team-role author. The URL is
+optional and never fetched. Realize a resolved question as a specification for
+behavior, a description for meaning, or a project-owned decision record for
+consequential policy. Resolving is not implementation; a known refusal still
+needs `then error` or `then denied`. Reopen when the evidence ceases to answer it.
+
+Question gating is separate from V1: standalone Screenplay 4.144.0 has
+`--open-questions fail`; Cratis CLI 3.53.1 does not. Read toolchain
+`references/versions.md` "Model notes gate" when a phase requires no open questions.
+Product evidence: Screenplay `v4.144.0:Documentation/screenplay/model-notes.md:12-77,93-121`,
+`decisions/0045-model-notes-sidecar.md:40-79` and the model-authoring source table.
+
 ## Question format (STATE.md, packets, edit requests)
 `Qn <declaration address>: <what is missing or contradictory, one sentence> - matters because
 <consequence> - <assumption in use | blocked scope>`. Write it so a reader who has not opened
@@ -58,5 +87,7 @@ 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's fenced `documentation`. Re-blocking a blocked scope is a no-op.
+STATE.md with its note ID, resolve the question note by evidence, and realize the
+answer in the model or decision record. Settled rationale may also go in 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/worked-example.md

@@ -84,8 +84,11 @@ 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 documentation and in STATE.md (Open questions) with its address,
-  `Berths.Allocation`.
+- On Screenplay 4.144.0, record Q1 as a `question` note on `Berths.Allocation`:
+  "Is allocation always manual? Assuming manual allocation; an automatic route
+  would need an automation." The documentation carries the working assumption;
+  STATE.md carries the returned note ID. Read `stop-or-assume.md` "Durable
+  question notes" when recording or resolving it.
 - 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

package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/verification.json

@@ -4,6 +4,11 @@
   "fixtures": [],
   "assertions": [
     { "kind": "play-compiles" },
+    { "kind": "skill-contains", "value": "record it as a `question` note anchored to the element" },
+    { "kind": "skill-contains", "value": "`refs: [{ \"id\": \"D123\" }]`", "file": "references/stop-or-assume.md" },
+    { "kind": "skill-contains", "value": "`by: \"external-decision\"`", "file": "references/stop-or-assume.md" },
+    { "kind": "skill-contains", "value": "Realize a resolved question as a specification", "file": "references/stop-or-assume.md" },
+    { "kind": "skill-contains", "value": "Never put secrets or personal data", "file": "references/stop-or-assume.md" },
     { "kind": "skill-contains", "value": "Model first" },
     { "kind": "skill-contains", "value": "`Outcome:`" },
     { "kind": "skill-contains", "value": "V3 binding-ready" },

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

@@ -206,6 +206,10 @@ reason; blocked verdicts list codes and keep the protection they blocked on.
 - [ ] Any new example fence compiles with the standalone tool; unmarked fences also pass
       `cratis screenplay validate --warnings-as-errors`.
 
+Read [model notes gate](references/versions.md#model-notes-gate) when checking
+unresolved questions: standalone 4.144.0 has `--open-questions fail`; Cratis CLI
+3.53.1 does not. It is separate from compilation and `--warnaserror`.
+
 ## Route near misses
 
 - What to model, phases, gates: `cratis-screenplay-modeling-lifecycle`.