@cratis/pi 7.103.5 → 7.103.6

package/package/corpus/harnesses/copilot/instructions/local-work-artifacts.instructions.md

@@ -17,8 +17,9 @@ dumps, and similar coordination files. These are **work records, not documentati
   If you find one tracked in git, move it into `.ai-work/` and remove it from
   tracking in a dedicated commit.
 - A genuine follow-up that must survive the session is **not** a work record — suggest
-  opening a GitHub issue for it (or open one when asked) so future work is tracked
-  where everyone can see it, instead of leaving a planning file behind.
+  opening a GitHub issue for it so future work is tracked
+  where everyone can see it, instead of leaving a planning file behind. A follow-up
+  issue includes an `## Acceptance criteria` section of concrete, testable bullets.
 - Knowledge that must outlive the session (real documentation, ADRs, operator
   guides) is written deliberately into the repository's documentation structure
   through normal review — not left behind as a work record.
@@ -37,16 +38,15 @@ dumps, and similar coordination files. These are **work records, not documentati
   replace the prompt.
 - **A worktree is a work record too.** Create it outside the repository tree, for
   example in a sibling `../.worktrees/` directory. A nested worktree inherits the
-  parent's `.globalconfig` alongside its own, causing .NET's `MultipleGlobalAnalyzerKeys`
+  parent's `.globalconfig`, causing .NET's `MultipleGlobalAnalyzerKeys`
   errors or silently changing analyzer severities. **Delivered work is cleaned up by
   `.cratis/ai/hooks/scripts/cratis-cleanup-worktrees.sh`, not by memory:** run it from the
   main checkout when a pull request merges or you finish a task (hooks also run it after
   `gh pr merge` and at session start where the harness supports them, and **ship-changes**
   ends with it). It removes a worktree and its branch only on evidence the work reached the
-  default branch — pushed is not merged — and never forces. Worktrees with non-empty `.ai-work/`
-  directories are kept by default as "has untracked work records (.ai-work/)". Manual
-  `--include-work-records` permits deleting those records after you preserve what you need;
-  automatic hooks never opt in. Pin a long-lived worktree with `git worktree lock <path>`;
+  default branch — pushed is not merged — and never forces. It keeps worktrees with non-empty
+  `.ai-work/` directories; manual `--include-work-records` deletes those records after you
+  preserve what you need, and automatic hooks never opt in. Pin a long-lived worktree with `git worktree lock <path>`;
   locked worktrees are always kept, even with opt-in. Other ignored files such as `.env` files
   and local databases can still be deleted with a removed worktree, so move anything you
   still need out first. Do not hand-remove worktrees or `git branch -D` a delivered branch

package/package/corpus/harnesses/copilot/instructions/specs.csharp.instructions.md

@@ -18,9 +18,9 @@ Extends the base [specs.md](./specs.instructions.md) (folder structure, naming,
 
 ## Frameworks
 
-- [xUnit](https://xunit.net/) **2.x** for execution (not v3).
-- Reference `Cratis.Specifications.XUnit` **4.1.1** for the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`, not the base or assertions.
-- 4.x targets net8.0/net9.0/net10.0; net48 requires 3.x. `Cratis.Specifications.NUnit` is an alternative with `[Test]` and public test methods; xUnit remains the house default.
+- [xUnit v3](https://xunit.net/docs/getting-started/v3/migration) is the house default for new and migrated spec projects: reference `Cratis.Specifications.XUnit.v3` **5.0** with `xunit.v3.mtp-off`, `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio`, and set `<OutputType>Exe</OutputType>` in the project. The package supplies the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`.
+- 5.0 targets `net10.0` only. A spec project that must stay on net8.0/net9.0 stays on 4.x, and net48 on 3.x. A project that stays on xUnit v2 uses `Cratis.Specifications.XUnit`, with the same base and conventions.
+- `.NUnit`/`.NUnit5`, `.TUnit` and the experimental `.Runner` are alternatives for repositories already built on them.
 - [NSubstitute](https://nsubstitute.github.io/) for mocking collaborators.
 - Spec projects are named `<Source>.Specs`.
 
@@ -48,9 +48,11 @@ public class when_combining_parts : Specification
 | `[Fact] void should_*()` | one assertion per fact | use the `ShouldXxx()` extension methods |
 | `void Destroy()` | teardown after each fact by default | once per eligible class with shared lifecycle opt-in |
 
-Shared lifecycle is optional (4.1.0+): add `[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", "Cratis.Specifications.XUnit")]`. Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Other classes keep per-fact execution. Keep the stock lifecycle by default; details are in the **cratis-specifications-csharp** skill's shared-lifecycle reference.
+The shared lifecycle is the default on xUnit v2 and v3 since 5.0; the package registers the framework, so delete any hand-written `[assembly: Xunit.TestFramework(...)]` (it fails with `CS0579`). Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Theories and `ITestOutputHelper` constructors keep per-fact execution; `[PerFactSpecificationLifecycle]` opts a class out. `CRSPEC0008` (a fact modifies the shared context) is an error by default: move the change into `Establish` or `Because`. See the **cratis-specifications-csharp** skill's shared-lifecycle reference.
 
-CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, and `.NUnit` 4.0.0+. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
+Run specifications as the built executable, not `dotnet test`: restore and build once, then run `bin/<Config>/net10.0/<Project>.Specs`. In a solution that mixes Microsoft.Testing.Platform and VSTest projects, run each project on its own; `dotnet test` on the whole solution does not work there. Filters and the 4.x → 5.0 checklist are in the **cratis-specifications-csharp** skill's [running-specs reference](../../../skills/cratis-specifications-csharp/references/running-specs.md).
+
+CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, `.XUnit.v3`, and `.NUnit`. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
 
 ## Reusable layered contexts
 

package/package/corpus/hooks/scripts/cratis-cleanup-worktrees.sh

@@ -158,12 +158,19 @@ cached_pulls() {
 }
 take_lock() {
     mkdir "$state/lock" 2>/dev/null && return 0
-    local modified retired acquired
-    read -r _ modified < <(lock_stat "$state/lock")
+    local inode modified retired acquired current
+    read -r inode modified < <(lock_stat "$state/lock")
     [[ "$modified" =~ ^[0-9]+$ ]] && [ "$now" -ge "$((modified + 900))" ] || return 1
     # Rename atomically: a killed reclaimer can leave only a retired directory, never a blocking marker.
     retired="$state/lock.stale.$$.$RANDOM"
     mv "$state/lock" "$retired" 2>/dev/null || return 1
+    read -r current _ < <(lock_stat "$retired")
+    if [ "$current" != "$inode" ]; then
+        # Another reclaimer replaced the stale directory. Restore its lock if possible;
+        # never acquire or delete a directory that was not the stale one we inspected.
+        [ -e "$state/lock" ] || mv "$retired" "$state/lock" 2>/dev/null
+        return 1
+    fi
     acquired=1
     mkdir "$state/lock" 2>/dev/null && acquired=0
     rm -rf "$retired"
@@ -282,9 +289,10 @@ in_use=$(git worktree list --porcelain | sed -n 's#^branch refs/heads/##p')
 planned_branches=$(printf '%s\n' "${PLAN_BRANCH[@]+"${PLAN_BRANCH[@]}"}")
 while IFS='|' read -r b bsha; do
     if [ -z "$b" ] || [ "$b" = "$default_local" ]; then continue; fi
-    if printf '%s\n' "$in_use" | grep -qx "$b"; then
+    # Drain producers under pipefail: grep -q can turn a match into a SIGPIPE failure.
+    if printf '%s\n' "$in_use" | grep -x "$b" >/dev/null; then
         [ "$DRY" = 0 ] || continue
-        printf '%s\n' "$planned_branches" | grep -qx "$b" || continue
+        printf '%s\n' "$planned_branches" | grep -x "$b" >/dev/null || continue
     fi
     plan_item branch "$b" "$bsha" "$b"
 done < <(git for-each-ref --format='%(refname:short)|%(objectname)' refs/heads)
@@ -307,7 +315,7 @@ git worktree prune >/dev/null 2>&1
 for ((i=0; i<${#PLAN_KIND[@]}; i++)); do
     kind=${PLAN_KIND[i]}; path=${PLAN_PATH[i]}; sha=${PLAN_SHA[i]}; br=${PLAN_BRANCH[i]}; ev=${PLAN_EVIDENCE[i]}
     if [ "$kind" = branch ]; then
-        git worktree list --porcelain | sed -n 's#^branch refs/heads/##p' | grep -qx "$br" && continue
+        git worktree list --porcelain | sed -n 's#^branch refs/heads/##p' | grep -x "$br" >/dev/null && continue
     fi
     if [ -z "$ev" ]; then
         if [ "$kind" = worktree ]; then note_kept "worktree $path (${br:-detached}): work not delivered to $default"

package/package/corpus/rules/local-work-artifacts.md

@@ -16,8 +16,9 @@ dumps, and similar coordination files. These are **work records, not documentati
   If you find one tracked in git, move it into `.ai-work/` and remove it from
   tracking in a dedicated commit.
 - A genuine follow-up that must survive the session is **not** a work record — suggest
-  opening a GitHub issue for it (or open one when asked) so future work is tracked
-  where everyone can see it, instead of leaving a planning file behind.
+  opening a GitHub issue for it so future work is tracked
+  where everyone can see it, instead of leaving a planning file behind. A follow-up
+  issue includes an `## Acceptance criteria` section of concrete, testable bullets.
 - Knowledge that must outlive the session (real documentation, ADRs, operator
   guides) is written deliberately into the repository's documentation structure
   through normal review — not left behind as a work record.
@@ -36,16 +37,15 @@ dumps, and similar coordination files. These are **work records, not documentati
   replace the prompt.
 - **A worktree is a work record too.** Create it outside the repository tree, for
   example in a sibling `../.worktrees/` directory. A nested worktree inherits the
-  parent's `.globalconfig` alongside its own, causing .NET's `MultipleGlobalAnalyzerKeys`
+  parent's `.globalconfig`, causing .NET's `MultipleGlobalAnalyzerKeys`
   errors or silently changing analyzer severities. **Delivered work is cleaned up by
   `.cratis/ai/hooks/scripts/cratis-cleanup-worktrees.sh`, not by memory:** run it from the
   main checkout when a pull request merges or you finish a task (hooks also run it after
   `gh pr merge` and at session start where the harness supports them, and **ship-changes**
   ends with it). It removes a worktree and its branch only on evidence the work reached the
-  default branch — pushed is not merged — and never forces. Worktrees with non-empty `.ai-work/`
-  directories are kept by default as "has untracked work records (.ai-work/)". Manual
-  `--include-work-records` permits deleting those records after you preserve what you need;
-  automatic hooks never opt in. Pin a long-lived worktree with `git worktree lock <path>`;
+  default branch — pushed is not merged — and never forces. It keeps worktrees with non-empty
+  `.ai-work/` directories; manual `--include-work-records` deletes those records after you
+  preserve what you need, and automatic hooks never opt in. Pin a long-lived worktree with `git worktree lock <path>`;
   locked worktrees are always kept, even with opt-in. Other ignored files such as `.env` files
   and local databases can still be deleted with a removed worktree, so move anything you
   still need out first. Do not hand-remove worktrees or `git branch -D` a delivered branch

package/package/corpus/rules/specs.csharp.md

@@ -17,9 +17,9 @@ Extends the base [specs.md](./specs.md) (folder structure, naming, philosophy) w
 
 ## Frameworks
 
-- [xUnit](https://xunit.net/) **2.x** for execution (not v3).
-- Reference `Cratis.Specifications.XUnit` **4.1.1** for the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`, not the base or assertions.
-- 4.x targets net8.0/net9.0/net10.0; net48 requires 3.x. `Cratis.Specifications.NUnit` is an alternative with `[Test]` and public test methods; xUnit remains the house default.
+- [xUnit v3](https://xunit.net/docs/getting-started/v3/migration) is the house default for new and migrated spec projects: reference `Cratis.Specifications.XUnit.v3` **5.0** with `xunit.v3.mtp-off`, `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio`, and set `<OutputType>Exe</OutputType>` in the project. The package supplies the `Specification` base, convention lifecycle and `ShouldXxx` assertions; the namespace remains `Cratis.Specifications`. Its `Cratis.Specifications` dependency supplies `Catch` and `SpecificationMethods`.
+- 5.0 targets `net10.0` only. A spec project that must stay on net8.0/net9.0 stays on 4.x, and net48 on 3.x. A project that stays on xUnit v2 uses `Cratis.Specifications.XUnit`, with the same base and conventions.
+- `.NUnit`/`.NUnit5`, `.TUnit` and the experimental `.Runner` are alternatives for repositories already built on them.
 - [NSubstitute](https://nsubstitute.github.io/) for mocking collaborators.
 - Spec projects are named `<Source>.Specs`.
 
@@ -47,9 +47,11 @@ public class when_combining_parts : Specification
 | `[Fact] void should_*()` | one assertion per fact | use the `ShouldXxx()` extension methods |
 | `void Destroy()` | teardown after each fact by default | once per eligible class with shared lifecycle opt-in |
 
-Shared lifecycle is optional (4.1.0+): add `[assembly: Xunit.TestFramework("Cratis.Specifications.SpecificationTestFramework", "Cratis.Specifications.XUnit")]`. Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Other classes keep per-fact execution. Keep the stock lifecycle by default; details are in the **cratis-specifications-csharp** skill's shared-lifecycle reference.
+The shared lifecycle is the default on xUnit v2 and v3 since 5.0; the package registers the framework, so delete any hand-written `[assembly: Xunit.TestFramework(...)]` (it fails with `CS0579`). Eligible classes derive from `Specification`, have one public parameterless constructor, do not implement `IDisposable`, and contain only plain facts. Construction, Establish/Because and Destroy run once; all facts share the instance and must not mutate it. Initialization failure fails every fact. Theories and `ITestOutputHelper` constructors keep per-fact execution; `[PerFactSpecificationLifecycle]` opts a class out. `CRSPEC0008` (a fact modifies the shared context) is an error by default: move the change into `Establish` or `Because`. See the **cratis-specifications-csharp** skill's shared-lifecycle reference.
 
-CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, and `.NUnit` 4.0.0+. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
+Run specifications as the built executable, not `dotnet test`: restore and build once, then run `bin/<Config>/net10.0/<Project>.Specs`. In a solution that mixes Microsoft.Testing.Platform and VSTest projects, run each project on its own; `dotnet test` on the whole solution does not work there. Filters and the 4.x → 5.0 checklist are in the **cratis-specifications-csharp** skill's [running-specs reference](../skills/cratis-specifications-csharp/references/running-specs.md).
+
+CRSPEC0001–CRSPEC0007 are warnings bundled in `.Specifications`, `.XUnit`, `.XUnit.v3`, and `.NUnit`. With warnings as errors, a non-`should_` fact, multiple specs per file (given contexts exempt), a fact on a given context, a `should_` without a test attribute, explicit base lifecycle calls, non-public specs with facts, or `Because` on a given context fail the build. Follow **cratis-specification-by-example**; do not suppress these diagnostics.
 
 ## Reusable layered contexts
 

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

@@ -57,6 +57,7 @@ commands before choosing the build, regression spec and full gate commands.
 - [ ] Reproduce the consumer bug and select its regression spec/app action.
 - [ ] Read [references/dependency-map.md](references/dependency-map.md) for the chain between the named repositories, generate one stamp, then pack each producer in upstream order.
 - [ ] If needed, publish the kernel and assets, then build a matching local image.
+- [ ] Run `closure` for the consumer and producers, follow the printed commands, and run its one `verify-pack` after the last pack.
 - [ ] Activate the consumer overlay and select the local image.
 - [ ] Build the consumer, run its regression specs/app action and required gates.
 - [ ] On failure, diagnose, fix the producer, create a distinct stamp and repeat.
@@ -94,9 +95,11 @@ exit `0`. Inspect package dependencies: every locally changed dependency ID must
 resolve to the stamp, not a published fallback. Chronicle's client solution filter
 can omit `Cratis.Chronicle.CodeAnalysis`; pack its code-analysis package project
 separately. The package IDs a producer should ship are listed in
-[dependency-map.tsv](scripts/dependency-map.tsv) (a reference, see
-[references/dependency-map.md](references/dependency-map.md)); compare them with the feed by hand.
-A successful pack alone does not prove dependency closure.
+[dependency-map.tsv](scripts/dependency-map.tsv); `closure CONSUMER=PATH PRODUCER=PATH...` prints
+the stamp, every overlay, one `pack-*` command per map row (with its `--property` arguments) and
+ONE `verify-pack` for the whole plan (see [references/dependency-map.md](references/dependency-map.md)).
+Run the printed commands in order. A successful pack alone does not prove dependency closure;
+`verify-pack` does.
 
 ### 3. Build an image when needed
 
@@ -242,6 +245,7 @@ minutes, instead of after a release and a pin bump.
 - Read [references/docker-images.md](references/docker-images.md) when publishing a kernel or selecting images in a consumer.
 - Read [references/go-jvm-python-elixir.md](references/go-jvm-python-elixir.md) when the boundary uses another language toolchain.
 - Read [references/worked-examples.md](references/worked-examples.md) when following Chronicle → Studio, Fundamentals → Arc, Components → Studio, Chronicle → Direct, Screenplay → Stage and Studio, Arc → Chronicle, or Fundamentals → Arc → Chronicle.
+- Read [references/train-mode.md](references/train-mode.md) when verifying a downstream repository against a local release train (`stamp --train`).
 - Read [references/other-environments.md](references/other-environments.md) when running on another developer machine or an agent host.
 
 Read `scripts/npm-restore-check.cjs` when inspecting the read-only npm restoration

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/dependency-map.md

@@ -5,9 +5,10 @@
 
 `scripts/dependency-map.tsv` is a reference table of the producer-to-consumer edges between
 Cratis repositories, the pack targets of each producer and the package IDs each ships.
-`cratis-local-packages.sh` does not read it: use it to decide which repositories to pack,
-in which order, and which IDs to expect in the feed. It holds no versions; read pins live
-from the consumer manifests (`Directory.Packages.props`, `package.json`, `Dockerfile`).
+`cratis-local-packages.sh` reads it (or the file in `CRATIS_LOCAL_MAP`, or `--map FILE`) to derive
+one plan: which repositories to pack, in which order, and which IDs the feed must hold. It holds
+no versions; read pins live from the consumer manifests (`Directory.Packages.props`,
+`package.json`, `Dockerfile`).
 
 ## Rows
 
@@ -15,7 +16,7 @@ Tab-separated, `#` starts a comment.
 
 | Row | Fields | Meaning |
 | --- | --- | --- |
-| `pack` | repo, eco, target, `PROP=VAL,...` | A pack target; the optional MSBuild properties are the `-p:` arguments the producer's own publish workflow passes |
+| `pack` | repo, eco, target, `PROP=VAL,...` | A pack target; the optional MSBuild properties are the `-p:` arguments the producer's own publish workflow passes. `closure` prints each as one `--property NAME=VALUE` argument of that row's `pack-nuget` command |
 | `ids` | repo, eco, comma-separated IDs | The packages the producer ships in that ecosystem |
 | `uses` | consumer, producer, eco, manifest | An edge; the manifest is the pin file, or the Yarn project directory for npm |
 | `image` | repo, dockerfile, tag suffix | A producer image a consumer builds on |
@@ -29,15 +30,30 @@ Tab-separated, `#` starts a comment.
   (Fundamentals reaches Chronicle through Arc as well as directly).
 - Pack upstream first. Overlay the earlier producer into the next repository with
   `use-nuget`, pack that, then `restore` it. Use one stamp for the whole chain: `stamp`
-  takes one producer, so generate it once and reuse the string.
-- Pack properties from a `pack` row are not accepted by `pack-nuget`. When a row has them,
-  run `dotnet pack TARGET -c Release -p:PackageVersion=$stamp -p:Version=$stamp -p:PROP=VAL
-  -o "$CRATIS_LOCAL_FEED/nuget"` yourself, with the properties as `-p:` arguments and never
-  as exported environment variables (an exported `IsPackaging=true` reaches Chronicle's
-  nested `dotnet run` code generator and fails with a multi-target error).
-- After packing, list the feed for the stamp and compare it with the `ids` row; a missing ID
-  is a silent partial overlay. Open the nuspec of each packed ID and check that every locally
-  changed dependency is at the stamp.
+  takes several producers, so generate it once and reuse the string.
+- Read the closure: `closure [--train] CONSUMER=PATH PRODUCER=PATH...` (producers in dependency
+  order) prints the commands to run, in order, from the plan; `plan CONSUMER PRODUCER...` prints
+  the plan rows alone. Both exit 2 and print nothing when the plan is invalid.
+- Pack properties are `pack-nuget --property NAME=VALUE` arguments, one per `-p:` of that command
+  only; never export them (an exported `IsPackaging=true` reaches Chronicle's nested `dotnet run`
+  code generator and fails with a multi-target error).
+- `--train` prints the train stamp (see [train-mode.md](train-mode.md)) instead of a local stamp.
+
+## Pack plan and verification scope
+
+The plan is a set of `(producer, ecosystem)` pack rows, overlay rows (a producer and the upstream
+producers it consumes) and consume rows (the consumer's own edges), derived from the `uses` rows
+for the names you list. It is rejected (exit 2) for an unknown or repeated name, no edge, a wrong
+order, or a planned pack without `ids` or `pack` rows.
+
+- Run `verify-pack STAMP --consumer C --producer P...` once, after the last pack. It checks the
+  planned IDs exist at exactly STAMP and each planned NuGet dependency is exactly STAMP, [STAMP] or [STAMP, ) (an unreadable dependency element fails).
+- After `use-*` and restore, `verify-assets CONSUMER-PATH STAMP --consumer C --producer P...`
+  checks the same plan inside the consumer: no planned ID resolved at another version, and no
+  producer the consumer uses left unconsumed. `--json` lists the resolved IDs only.
+- Each command derives and checks the plan itself and keeps no state between runs.
+- `verify-pack STAMP NAME...` and `verify-assets CONSUMER STAMP` without a plan are manual and
+  weaker: they check the named repositories' IDs, or every stamped package the consumer resolves.
 
 ## Facts about the chains
 
@@ -50,7 +66,8 @@ Tab-separated, `#` starts a comment.
 - A repository you did not name keeps its released version: Stage reaches Arc, Chronicle
   reaches Orleans. A binary break through that hop is a finding about the consumer's pins.
 - The current Screenplay rows list only npm IDs although Stage and Studio consume its NuGet
-  packages; read the IDs from the producer's publish workflow.
+  packages; `closure` exits 2 for them until the map has the Screenplay NuGet `ids`. Read the
+  IDs from the producer's publish workflow and add them first.
 
 ## Extend it
 

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

@@ -28,6 +28,9 @@ dotnet restore path/to/consumer.slnx
 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 `-p:` properties explicitly to its build. Verify restore uses the

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/npm-yarn.md

@@ -5,8 +5,9 @@
 
 ## Pack the package, not a link
 
-Requires node, tar and Yarn 4. Run the producer's normal build first. The helper does
-not run a separate build; Yarn's normal pack lifecycle hooks still run.
+Requires node, npm and Yarn 4. Run the producer's normal build first. The helper does
+not build or run lifecycle scripts: it packs with `npm pack --ignore-scripts`, the publish
+workflows' tool, so the tarball matches the published one.
 
 ```bash
 stamp=$(bash "$local" stamp "$producer")
@@ -15,8 +16,9 @@ bash "$local" pack-npm "$producer" "$stamp"
 
 It requires clean tracked workspace manifests, temporarily changes all non-private
 workspace versions and packs actual tarballs. It restores those manifests on
-success and failure; inspect diffs for other lifecycle-generated output. Yarn's
-`%s-%v.tgz` output slugifies a scoped name (`@cratis/foo` becomes `@cratis-foo`).
+success and failure. Tarballs are named `<scope>-<name>-<version>.tgz` (`@cratis/foo` becomes
+`cratis-foo-<version>.tgz`). `verify-assets --npm [--dir REL]` reads installed copies under
+`node_modules`, or under `REL` when the consumer's Yarn project is a subfolder.
 Inspect dependency ranges in packed manifests: the helper changes versions, not
 arbitrary inter-package dependency constraints. Include every required workspace
 and verify the consumer resolves the intended tarballs.

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/train-mode.md

@@ -0,0 +1,43 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Train mode
+
+A local release train combines several branches into one pull request, one CI run and one
+release. Verify a downstream repository against the upstream train's packages, not against
+per-branch packages.
+
+## Stamp
+
+`stamp --train PRODUCER...` prints `X.Y.Z-train.g<sha7>`. X.Y.Z is the highest next patch over the
+producers' latest reachable tags, so no stamped package sorts below a released pin. sha7 is the first
+seven hex characters of the SHA-1 of the sorted `<repository> <full HEAD sha>` lines of every
+producer (the repository is its origin's last path part, else its folder name). There is no minute: one
+combined code state yields one stamp, a change in any producer changes it, and the order of the
+producers does not matter. The grammar is fixed so tools can rely on it. Every command that takes a
+stamp accepts it: `pack-*`, `use-*`, `verify-*`, `check` and `clean --stamp`. A train stamp
+sorts above the released pin like a local stamp does.
+
+## Rules
+
+- One stamp per train state. The train tool records it in the train manifest; read it from there
+  instead of recomputing it for a different HEAD.
+- A fold into the upstream train changes the upstream HEAD and so the stamp. Downstream
+  verification against the old stamp is stale: pack again, overlay the new stamp, rebuild and
+  re-verify. Do not carry a pass over a fold.
+- Train versions are as local as local stamps. `check` reports `-train.g<sha7>` in changed
+  tracked, staged and untracked files, so a train version never reaches a commit or pull request.
+- Upstream first. The downstream ships only after the upstream has released and the downstream pin
+  is bumped to the released version; run `check` (0 leaks) before the downstream push.
+
+## Recording consumed versions
+
+`verify-pack STAMP --consumer C --producer P... --json` and
+`verify-assets CONSUMER STAMP [--npm] [--consumer C --producer P...] --json` print one line:
+`{"stamp":"...","packages":[{"id":"...","version":"..."}]}`. Findings go to stderr and the exit status
+is unchanged, so a train tool can record the consumed versions without scraping text.
+
+## Clean
+
+`clean --stamp STAMP` lists and removes the feed files, cache folders and Yarn cache entries of
+that one train stamp; a local stamp is not matched. Review the dry run before `--apply`.

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/references/worked-examples.md

@@ -162,6 +162,10 @@ bash "$local" use-nuget "$stage" "$stamp"; bash "$local" use-nuget "$studio" "$s
 bash "$local" use-npm "$studio" "$stamp"       # at the workspace root, not the nested app
 ```
 
+`closure` exits 2 for this chain until `dependency-map.tsv` has the Screenplay NuGet `ids` (it lists
+only npm IDs); add them from the publish workflow first, then use the printed commands and its one
+`verify-pack`.
+
 Gates: Stage's frontend `npm ci`, test and build, then `dotnet build` in Debug and the repository's
 own spec-shard helper; skip probes that need a live kernel or database and say so. Studio:
 `dotnet build` of its solution in Debug with warnings as errors, then the frontend `yarn ci` and
@@ -171,7 +175,7 @@ own spec-shard helper; skip probes that need a live kernel or database and say s
 - Pitfall: a repository without a committed lockfile fails `yarn install --immutable`; use plain
   `yarn install` there.
 - Pitfall: yarn hoists to the root `node_modules`; check and install at the root.
-- Pitfall: the packed language tarball must contain its built bundles. `pack-npm` uses `yarn pack`;
+- Pitfall: the packed language tarball must contain its built bundles. `pack-npm` uses `npm pack`;
   a package whose `files` lists a gitignored folder can ship only part of it. Compare the
   tarball file list with the package's `dist` folder.
 - Pitfall: multi-hop. Studio keeps its released Stage; a binary break is a finding.