@cratis/pi 7.103.6 → 7.104.0

package/package/corpus/agents/screenplay-modeler.md

@@ -33,6 +33,7 @@ After reading these instructions, read each file listed under `process.agents.sc
 
 ## Method
 
+- Reuse existing model/workspace roots. Code-only `Source/` or `src/` is not a model root; absent model/workspace state, use repository-root `Screenplay/`, never `.cratis/`. Read model-authoring's MCP root-selection/version guidance before switching roots.
 - Load `cratis-screenplay-modeling-lifecycle`, then exactly one phase skill per step: discovery, slice design, streams and consistency, automations and translations, scenario coverage. A legacy system enters through `cratis-screenplay-legacy-extraction` instead of discovery and modeling; later runs re-enter by recorded source identity, widen the candidate in layered passes, and promote locators, decisions and open questions into notes and `documentation` before acceptance (`references/re-entry-and-passes.md` there). Syntax, versions and verdict commands: `cratis-screenplay-toolchain`. Load the phase skill before authoring a construct family.
 - For a change to an existing model, start from an impact walkthrough (`cratis-screenplay-model-review` `references/walkthrough.md`) so the brief names every affected slice.
 - Write declarations in story order, one slice after another, never batched by kind. After each batch read `PLAY0516` and `PLAY0517` and repair, or record why the order stays (`cratis-screenplay-slice-design` `references/slicing.md`).

package/package/corpus/harnesses/copilot/instructions/profiles.instructions.md

@@ -313,8 +313,12 @@ The profile also selects the corpus-owned Screenplay MCP declaration from
 `mcp-servers.json`. The Cratis CLI hosts the server as `cratis screenplay mcp`
 and registers a scoped entry for supported clients without replacing their other
 servers. Inspect install/status results for adapter support or configuration
-conflicts. The model is wherever the project keeps its `.play` files, else under `Source/` or
-`src/`, else in a `Screenplay/` folder at the repository root; never under `.cratis/`.
+conflicts. Reuse the project's existing model/workspace root. A code-only `Source/`
+or `src/` is not a model root; without model/workspace state use repository-root
+`Screenplay/`, never `.cratis/`. Requires Cratis CLI 3.93.1 (`cratis --version`) for
+CLI discovery and Screenplay 4.236.1 (`screenplay --version`) for standalone MCP
+discovery; older versions can choose code-only folders. Fixed-root sibling admission
+is narrowly scoped, not an arbitrary switch: see [root selection](../../../skills/cratis-screenplay-event-modeling/references/file-layout.md#locate-the-model).
 Project-owned configuration can name a root explicitly.
 
 Like `allowDependencyManifestWrites`, `modelFirst` (`frozen`, `reason`) and `process` (`decisions`, `workItems`, `acceptance`, `agents`) are project-owned keys in `.cratis/ai.json` that install and update preserve. Only `modelFirst.frozen` is read by code; the lifecycle skill's `references/project-process.md` defines the keys, defaults and routing.

package/package/corpus/harnesses/pi/agents/screenplay-modeler.md

@@ -28,6 +28,7 @@ After reading these instructions, read each file listed under `process.agents.sc
 
 ## Method
 
+- Reuse existing model/workspace roots. Code-only `Source/` or `src/` is not a model root; absent model/workspace state, use repository-root `Screenplay/`, never `.cratis/`. Read model-authoring's MCP root-selection/version guidance before switching roots.
 - Load `cratis-screenplay-modeling-lifecycle`, then exactly one phase skill per step: discovery, slice design, streams and consistency, automations and translations, scenario coverage. A legacy system enters through `cratis-screenplay-legacy-extraction` instead of discovery and modeling; later runs re-enter by recorded source identity, widen the candidate in layered passes, and promote locators, decisions and open questions into notes and `documentation` before acceptance (`references/re-entry-and-passes.md` there). Syntax, versions and verdict commands: `cratis-screenplay-toolchain`. Load the phase skill before authoring a construct family.
 - For a change to an existing model, start from an impact walkthrough (`cratis-screenplay-model-review` `references/walkthrough.md`) so the brief names every affected slice.
 - Write declarations in story order, one slice after another, never batched by kind. After each batch read `PLAY0516` and `PLAY0517` and repair, or record why the order stays (`cratis-screenplay-slice-design` `references/slicing.md`).

package/package/corpus/harnesses/pi/extensions/cratis-mcp/ServerBridge.ts

@@ -44,22 +44,24 @@ export function createServerBridge(pi: ExtensionAPI, corpus: string, connect: (p
         connections.clear();
         deactivate();
     };
-    interface Started { server: CorpusServer; connection: StdioConnection; catalog?: ServerCatalog; messages: string[] }
+    interface Started { server: CorpusServer; connection?: StdioConnection; catalog?: ServerCatalog; messages: string[] }
     /** Connect and discover only; registration happens afterwards in selection order so name claims are deterministic. */
     const start = async (context: ExtensionContext, server: CorpusServer): Promise<Started> => {
-        const connection = connect(context.cwd, server);
-        connections.set(server.id, connection);
+        let connection: StdioConnection | undefined;
         try {
+            connection = connect(context.cwd, server);
+            connections.set(server.id, connection);
             const catalog = await withDeadline(discoverServer(connection, server.id), deadlineMilliseconds, server.id);
             if (connections.get(server.id) !== connection || connection.stopped) throw new Error(`MCP server '${server.id}' session ended during discovery.`);
             return { server, connection, catalog, messages: [...catalog.messages] };
         } catch (error) {
-            connection.dispose();
-            if (connections.get(server.id) === connection) connections.delete(server.id);
+            connection?.dispose();
+            if (connection && connections.get(server.id) === connection) connections.delete(server.id);
             return { server, connection, messages: [`MCP server '${server.id}' is unavailable: ${error instanceof Error ? error.message : String(error)}`] };
         }
     };
     const register = ({ server, connection, catalog, messages }: Started, claimed: Set<string>): void => {
+        if (!connection) return;
         const existing = new Set(pi.getAllTools().map(tool => tool.name));
         for (const tool of catalog?.tools ?? []) {
             if (claimed.has(tool.nativeName) || (existing.has(tool.nativeName) && !registered.has(tool.nativeName))) {

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { execFile, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import type { CorpusServer } from './CorpusServer.ts';
 import { StdioConnection } from './StdioConnection.ts';
 
@@ -45,9 +47,19 @@ export function startConnection(project: string, launch: typeof spawn = spawn):
     }));
 }
 
-/** Launch a corpus server verbatim (no shell, no interpolation): the default environment plus its declared literal env only. */
-export function startServer(project: string, server: CorpusServer, launch: typeof spawn = spawn): StdioConnection {
-    return new StdioConnection(launch(server.command, server.args, {
+/** Launch a corpus server without a shell or interpolation; Windows npx uses npm's JavaScript entry point. */
+export function startServer(project: string, server: CorpusServer, launch: typeof spawn = spawn, platform: NodeJS.Platform = process.platform, fileExists: (path: string) => boolean = existsSync): StdioConnection {
+    let command = server.command;
+    let args = server.args;
+    if (platform === 'win32' && /^npx(?:\.cmd)?$/i.test(command)) {
+        const entryPoint = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npx-cli.js');
+        if (!fileExists(entryPoint)) {
+            throw new Error(`MCP server '${server.id}' requires npm's npx-cli.js at '${entryPoint}'. Install Node.js with npm; Windows command shims cannot be launched without a shell.`);
+        }
+        command = process.execPath;
+        args = [entryPoint, ...args];
+    }
+    return new StdioConnection(launch(command, args, {
         cwd: project,
         env: { ...childEnvironment(), ...server.env },
         shell: false,

package/package/corpus/rules/profiles.md

@@ -312,8 +312,12 @@ The profile also selects the corpus-owned Screenplay MCP declaration from
 `mcp-servers.json`. The Cratis CLI hosts the server as `cratis screenplay mcp`
 and registers a scoped entry for supported clients without replacing their other
 servers. Inspect install/status results for adapter support or configuration
-conflicts. The model is wherever the project keeps its `.play` files, else under `Source/` or
-`src/`, else in a `Screenplay/` folder at the repository root; never under `.cratis/`.
+conflicts. Reuse the project's existing model/workspace root. A code-only `Source/`
+or `src/` is not a model root; without model/workspace state use repository-root
+`Screenplay/`, never `.cratis/`. Requires Cratis CLI 3.93.1 (`cratis --version`) for
+CLI discovery and Screenplay 4.236.1 (`screenplay --version`) for standalone MCP
+discovery; older versions can choose code-only folders. Fixed-root sibling admission
+is narrowly scoped, not an arbitrary switch: see [root selection](../skills/cratis-screenplay-event-modeling/references/file-layout.md#locate-the-model).
 Project-owned configuration can name a root explicitly.
 
 Like `allowDependencyManifestWrites`, `modelFirst` (`frozen`, `reason`) and `process` (`decisions`, `workItems`, `acceptance`, `agents`) are project-owned keys in `.cratis/ai.json` that install and update preserve. Only `modelFirst.frozen` is read by code; the lifecycle skill's `references/project-process.md` defines the keys, defaults and routing.

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/SKILL.md

@@ -16,7 +16,16 @@ Use real locally built packages to prove a producer fix at its consumer's packag
 boundary. A **producer** builds the changed library or image; a **consumer** is the
 downstream repository that reproduces the bug. Start before opening the producer
 PR whose purpose is that consumer bug, rather than publishing just to find out.
-Also use this loop to compare the consumer against lower-layer main.
+Also use this loop for:
+
+- Consumer-blocking fixes, dependency features, and breaking-change trials.
+- Release candidates in their main consumer (Specifications in Fundamentals).
+- Cross-repository bisects and build/test timing comparisons against lower-layer main.
+- Chained upgrades (Specifications → Fundamentals → Arc/Chronicle) without releasing each hop.
+- Release blockers: trying Specifications in Fundamentals can expose a generator bug before publishing.
+
+Prefer a release/preview for trivial changes, external consumers unable to use
+the local feed, or CI-only behavior this loop cannot reproduce.
 
 **Local verification replaces waiting, not shipping.** After local proof, release
 the producer through the normal authorized workflow and bump the consumer to the
@@ -78,6 +87,8 @@ Format: `<next-patch>-local.<12-digit-UTC-minute>.g<sha7>`, based on the highest
 downgrades. Confirm tags cover the consumer's released constraints. With no tag,
 the helper warns and falls back to a base that must be checked before proceeding.
 The `g` prefix keeps even an all-digit SHA nonnumeric in SemVer.
+On `release/5.0`, use `stamp --base-version 5.0.0 "$producer"` (also with `--train`);
+the strict SemVer core overrides tag discovery verbatim. Ensure it meets consumer minima.
 Use the identical stamp for packages and images. A changed build needs a distinct
 stamp; do not overwrite a cached version (the minute and commit determine it).
 
@@ -126,9 +137,18 @@ export CHRONICLE_KERNEL_VERSION="$stamp" # Studio integration specs, if used
 ```
 
 Pass: the helper reports overridden IDs and restore resolves them to local
-artifacts. Follow any printed `--configfile` instruction. Run Yarn install after
+artifacts. To isolate NuGet downloads per worktree, set the optional
+`NUGET_PACKAGES` export printed by `use-nuget` before restore and keep it set through
+`clean`; see [versions and cache](references/dotnet-nuget.md#versions-and-cache).
+Follow any printed `--configfile` instruction. Run Yarn install after
 `use-npm`; it adds file-tarball resolutions, not links to source folders.
 
+For independent NuGet producer versions, explicitly opt in with
+`verify-pack --composition FILE`, `use-nuget CONSUMER --composition FILE
+[--pin-transitive]`, then `verify-assets CONSUMER --composition FILE`. See the
+[manifest and native-validation workflow](references/dotnet-nuget.md#mixed-version-compositions-opt-in).
+No producer is rebuilt; restore before changing a composition or an active legacy overlay.
+
 ### 5. Build and exercise the consumer
 
 From the consumer root, with the printed NuGet environment sourced:
@@ -192,7 +212,13 @@ feed packages, NuGet version folders, discoverable Yarn cache entries, local ima
 tags and registered sessions; unresolved npm backups block it. Missing Docker/Yarn
 probes are reported as skipped cleanup, not proof those stores are empty. Default
 fuse: 500 subjects; investigate an unexpectedly large list instead of raising it.
-Prefer `--stamp` to `--all` on shared machines.
+Prefer `--stamp` to `--all`. Legacy cleanup refuses the entire request (exit `2`,
+also in dry-run) for registered live overlay/manifest references; it reports kept
+stamps and paths. Restore/remove references, then retry. This is not an ownership
+registry; unregistered consumers need manual review. To retire a hand-rolled
+`-local.N` feed, restore released pins/sources and switch to helper stamps; review
+old artifacts separately because `clean` does not recognize them. See
+[migration](references/dotnet-nuget.md#retire-a-hand-rolled-feed).
 
 ## Configuration and results
 
@@ -203,7 +229,7 @@ is sourced before defaults. Do not put credentials in it. Environment settings:
 | --- | --- |
 | `CRATIS_LOCAL_FEED` | `${XDG_CACHE_HOME:-$HOME/.cache}/cratis/local-feed`; outside tracked files |
 | `CRATIS_LOCAL_SESSION_DIR` | `<absolute-git-dir>/cratis-local`; per-worktree overlays/backups |
-| `NUGET_PACKAGES` | `$HOME/.nuget/packages`; shared cache, unique version folders |
+| `NUGET_PACKAGES` | `$HOME/.nuget/packages`; opt-in per-worktree cache via `use-nuget` hint |
 | `CRATIS_LOCAL_CLEAN_MAX` | `500`; cleanup subject fuse |
 | `CRATIS_LOCAL_RUN` | Optional executable wrapper receiving `build <label> -- <command...>` |
 

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/dotnet-nuget.md

@@ -3,6 +3,16 @@
 
 # .NET and NuGet
 
+## Contents
+
+- CPM overlay
+- Source mapping
+- Versions and cache
+- Retire a hand-rolled feed
+- Mixed-version compositions (opt-in)
+- Non-CPM escape
+- Restoration and drift
+
 ## CPM overlay
 
 Execute the helper from the entry point. `pack-nuget PRODUCER STAMP TARGET...`
@@ -14,10 +24,11 @@ them from an accidental published fallback.
 `use-nuget CONSUMER STAMP [ID...]` requires a root `Directory.Packages.props`.
 Without IDs it selects every package with `<id>.<stamp>.nupkg` in the feed,
 including transitive dependencies absent from the consumer props. The generated
-overlay imports the consumer's real props, uses `PackageVersion Update` for IDs
-already pinned there and `PackageVersion Include` for the others, and enables
-`CentralPackageTransitivePinningEnabled` so the added IDs pin transitive packages.
-An `Update` alone cannot add an absent ID. It does not copy or edit the props in git.
+overlay imports each project's nearest `Directory.Packages.props` and replaces
+owned `PackageVersion` items only when CPM is enabled, honoring nested props files.
+CPM opt-out projects get owned versions through late `PackageReference Update`
+items in `CustomAfterMicrosoftCommonTargets`, chaining any existing targets import;
+consumer files are never edited.
 
 ```bash
 bash "$local" use-nuget "$consumer" "$stamp" Cratis.Chronicle Cratis.Chronicle.CodeAnalysis
@@ -31,8 +42,8 @@ dotnet build path/to/consumer.slnx -c Release --no-restore -warnaserror
 Transitive pinning stays as the consumer sets it; `--pin-transitive` forces it on so stamped IDs the
 consumer does not pin still take effect (it can raise NU1109 floors).
 
-The printed properties are `DirectoryPackagesPropsPath` and
-`RestoreAdditionalProjectSources`. For an IDE, launch it from that shell, or pass
+The printed properties include `DirectoryPackagesPropsPath`,
+`RestoreAdditionalProjectSources` and `CustomAfterMicrosoftCommonTargets`. For an IDE, launch it from that shell, or pass
 the printed `-p:` properties explicitly to its build. Verify restore uses the
 stamp in `obj/project.assets.json`; shell environment changes do not reconfigure
 an already-running IDE. A config overlay printed below must also reach IDE restore.
@@ -59,11 +70,123 @@ A stale highest tag or dependency with a newer minimum needs investigation, not
 warning suppression. The suffix is `-local.<12-digit-UTC-minute>.g<sha7>`; the `g` prefix makes an
 all-digit SHA unambiguously nonnumeric in SemVer. Dirty edits are not encoded.
 Wait for a distinct UTC minute or commit before repacking changed contents.
+On a major-version branch, use `bash "$local" stamp --base-version 5.0.0 "$producer"`
+(also with `--train`). It accepts only a SemVer core without leading zeros,
+prerelease or metadata and uses it verbatim; no patch increment is added.
+An explicit base still must meet the consumer's minimum.
+
+Prefer a private cache per consumer worktree so another checkout's cached package
+cannot mask a same-version repack. The optional `use-nuget` hint uses a sibling of
+the session directory, not a tracked path:
+
+```bash
+export NUGET_PACKAGES="$(git -C "$consumer" rev-parse --absolute-git-dir)/cratis-local-nuget"
+dotnet restore path/to/consumer.slnx
+# After restoring overlays/removing live local references, keep this export for:
+bash "$local" clean "$consumer" --stamp "$stamp"
+bash "$local" clean "$consumer" --stamp "$stamp" --apply
+unset NUGET_PACKAGES
+```
+
+A private cache still reuses its own downloads: changed bits need a distinct stamp,
+or reviewed cleanup of that stamp before repacking. It does not make same-version
+repacking safe. `clean` honors the active `NUGET_PACKAGES`, touches only recognized
+`-local`/`-train` version folders there, and leaves released versions alone. With
+no export, it uses the shared `$HOME/.nuget/packages` cache; never clear that whole
+cache. Restore local overlays and remove live manifest references before cleanup;
+registered live references refuse the entire request even in dry-run.
+
+The helper uses a folder feed, so NuGet's HTTP cache is not involved. When diagnosing
+an HTTP feed instead, `dotnet restore --no-http-cache` bypasses its HTTP cache only;
+it does not bypass packages already in `NUGET_PACKAGES`. Use a fresh worktree cache
+or review stamp-scoped cleanup too, and preserve any required `--configfile` option.
+
+## Retire a hand-rolled feed
+
+Stop packing new `-local.N` versions. Restore consumers' released pins and sources,
+then use helper-generated stamps and overlays for the next trial. Confirm restore
+resolves the helper stamp and run `check` before committing. Inventory the old
+feed separately: `clean` recognizes only its local/train grammar, not `-local.N`.
+Remove old artifacts only after checking all their consumers and reviewing exact
+targets; never rename old packages into a helper stamp or clear a whole shared cache.
+
+## Mixed-version compositions (opt-in)
+
+Use a composition when products have independent local versions. It never packs
+or rebuilds producers. Write a tab-separated manifest under `.ai-work/`:
+
+```text
+# Separate fields with literal tabs.
+producer	Chronicle	22.138.1-local.202610240544.gd1ad215	/absolute/worktree/Chronicle
+producer	Screenplay	0.2.2-local.202610240544.g91916a3	/absolute/worktree/Screenplay
+producer	Stage	0.1.18-local.202610240544.g524bdce	/absolute/worktree/Stage
+package	Chronicle	Cratis.Chronicle.InProcess
+package	Screenplay	Cratis.Screenplay
+package	Stage	Cratis.Stage
+```
+
+Each producer needs a valid local/train stamp, an existing absolute Git worktree
+root and at least one package. Paths declare provenance, not cryptographic artifact
+authenticity. Package IDs have one owner, case-insensitively.
+Declare the complete local dependency closure. Only blank lines and lines starting
+with `#` are ignored. No npm rows or implicit merging with an active overlay.
+
+```bash
+bash "$local" verify-pack --composition .ai-work/composition.tsv --json
+bash "$local" use-nuget "$consumer" --composition .ai-work/composition.tsv --pin-transitive
+# Source the printed env; use the printed --configfile for consumer restore.
+# Run the consumer's own restore/build/specs, then:
+bash "$local" verify-assets "$consumer" --composition .ai-work/composition.tsv --json
+bash "$local" restore "$consumer"
+```
 
-The existing global cache is shared safely only because local versions have
-unique directories. Do not repack changed bits under the same version. Use
-`clean --stamp "$stamp"` to list that stamp's version folders, then `--apply`
-after review; do not delete the entire NuGet cache.
+`verify-assets` reads every `obj/project.assets.json` under the consumer and fails
+closed on any project that resolved an owned ID at another version, including stale
+assets from an earlier restore. Restore every project under the consumer with the
+printed config, or remove the `obj` folders of projects outside the build, before
+running it.
+
+Transitive pinning is optional. The overlay imports the consumer's CPM file and
+removes/re-includes owned IDs at exact producer versions. Its generated NuGet
+config gives local IDs exclusive exact source mappings, removes conflicting remote
+exact mappings and preserves unrelated sources/mappings/settings. Remote wildcards
+remain less specific. Always pass the printed config during restore. Consumer
+files are never edited. Ambiguous or inherited-only source configuration fails
+closed instead of guessing.
+
+Validation requires Node, `unzip` and the selected .NET SDK. A scratch MSBuild task
+loads its `NuGet.Versioning.dll`: `NuGetVersion.TryParse`, `VersionRange.TryParse`
+and `VersionRange.Satisfies` supply native semantics, never a range approximation.
+Its `NuGet.Frameworks.dll` supplies `NuGetFramework.Parse` and
+`FrameworkReducer.GetNearest` for selecting the applicable dependency group.
+Nuspec XML is parsed structurally, across dependency groups. For example,
+`[22.136.4,23.0.0)` admits the selected Chronicle prerelease above. Missing/corrupt
+packages, mismatched metadata, malformed/incompatible ranges and undeclared local
+dependencies fail. Nothing is rebuilt to make a range pass.
+
+Assets verification examines every `obj/project.assets.json` and target, checks
+package versions against `libraries`, and validates dependency edges against their
+resolved target. The nearest native framework group must have its owned dependencies
+consumed and represented by target edges. Owned IDs must resolve at their producer's exact version. Unused
+declared IDs need not appear, but at least one owned ID must be consumed. Malformed
+or failed-restore assets, missing dependency nodes and undeclared local packages fail.
+A range violation on an edge where neither end is an owned ID is NuGet's own NU1608
+case and exists without the overlay too, so it is printed as a `WARNING:` on stderr
+(and listed under `warnings` with `--json`) instead of refusing the composition.
+Any violation on an edge to or from an owned ID still fails.
+
+Activation stages the normalized manifest, props, config and env together. A shared
+mutation lock and journal protect publication and registration. The next mutation
+rolls back incomplete work or finishes committed work after interruption. Changed
+files, unknown ownership and live locks are preserved and refused: inspect rather
+than deleting a lock by age. Identical activation is a no-op; restore before changing
+a composition. Incompatible legacy NuGet/npm sessions are refused with backups
+untouched. Active compositions retain member artifacts against `clean`; restore
+before cleaning any member. Repeated restore is safe and never edits consumer files.
+
+Exit codes: `0` success; `1` findings; `2` invalid input, unavailable native validation
+or unsafe state. Composition JSON is `{"packages":[{"id":...,"version":...,"producer":...}]}`,
+with no global `stamp`. Legacy JSON and uniform-stamp commands remain unchanged.
 
 ## Non-CPM escape
 
@@ -75,12 +198,14 @@ graph. Never edit versions intended to ship merely to make local proof work.
 
 ## Restoration and drift
 
-`restore` removes session props, generated config and env files, then runs `check`.
+`restore` removes session props, targets, generated config and env files, then runs `check`.
 It cannot unset variables in the calling shell:
 
 ```bash
 bash "$local" restore "$consumer"
 unset DirectoryPackagesPropsPath RestoreAdditionalProjectSources
+export CustomAfterMicrosoftCommonTargets="${_CratisLocalPreviousAfterMicrosoftCommonTargets:-}"
+unset _CratisLocalPreviousAfterMicrosoftCommonTargets
 bash "$local" check "$consumer"
 ```