@cratis/pi 7.103.4 → 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/README.md

@@ -128,6 +128,22 @@ ignored records. Other ignored files (`node_modules`, build output) go with a de
   `--include-work-records` only after preserving any records you still need: it permits deleting
   `.ai-work/` content, but never overrides locks or other safety checks. Hook mode ignores this flag;
   automatic hooks never opt in.
+- **GitHub lookups.** The complete worktree and branch sweep is planned before any removal. Git
+  ancestry is checked first; only a plan needing more evidence triggers the single REST batch. It
+  reads the latest 100 closed pull requests, so older merged branches absent from that page are simply
+  kept. Only merged entries with the exact branch and head commit qualify. Hook runs share an atomic
+  stamp and cache under the Git common directory, with at most one request per repository every
+  15 minutes, including failed attempts. A fresh successful cache is reused. A failed request, invalid
+  response, or unavailable lock without a fresh successful cache aborts **all** removals in that sweep,
+  including ancestry-proven worktrees and branches, with a one-line notice. Failed attempts are marked
+  for the full window: later plans needing GitHub also abort all removals without retrying, while plans
+  needing only ancestry evidence proceed without GitHub. Locks older than 15 minutes can be reclaimed.
+  Manual runs are not throttled, but also use at most one request per run and abort all removals if
+  that request fails.
+- **Disable GitHub only.** Set `CRATIS_CLEANUP_NO_GH=1` to avoid all GitHub lookups while keeping
+  cleanup based on Git ancestry enabled. Missing `gh` or `jq`, a non-GitHub origin, or an invalid
+  repository slug also select ancestry-only cleanup before planning: unproven items are kept, with
+  no GitHub call, abort, or failed-attempt marker.
 - **Pin a long-lived worktree.** Use `git worktree lock <path>` to keep it out of cleanup; release the
   pin with `git worktree unlock <path>` when ready.
 - **Self-test.** `--self-test` plants delivered, dirty, unmerged, brand-new, work-record and locked cases

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

@@ -139,34 +139,128 @@ REMOVED=(); KEPT=(); FREED_KB=0
 note_removed() { REMOVED+=("$1"); }
 note_kept() { KEPT+=("$1"); }
 
-# delivered <sha> <branch|""> <upstream-track>  → prints the evidence, returns 0 when delivered
-delivered() {
-    local sha="$1" br="$2" track="$3"
-    if git merge-base --is-ancestor "$sha" "$default" 2>/dev/null; then
-        if ! grep -qx "$sha" "$firstparent"; then echo "merged into $default"; return 0; fi
-        if [ "$track" = "[gone]" ]; then echo "merged into $default, upstream gone"; return 0; fi
+# The cache is available only after a successful, valid batch. Failed attempts also stamp the window.
+GH_PULLS=''
+valid_pulls() {
+    jq -e -s 'length == 1 and (.[0] | type == "array" and all(.[];
+        type == "object" and has("merged_at") and (.merged_at == null or (.merged_at | type == "string")) and
+        (.head | type == "object" and (.ref | type == "string") and (.sha | type == "string"))))' "$1" >/dev/null 2>&1
+}
+lock_stat() { stat -c '%i %Y' "$1" 2>/dev/null || stat -f '%i %m' "$1" 2>/dev/null; }
+fresh_stamp() {
+    local stamp
+    stamp=$(cat "$state/stamp" 2>/dev/null || true)
+    [[ "$stamp" =~ ^[0-9]+$ ]] && [ "$now" -lt "$((stamp + 900))" ]
+}
+cached_pulls() {
+    fresh_stamp && [ ! -e "$state/failed" ] && valid_pulls "$state/pulls.json" || return 1
+    cat "$state/pulls.json"
+}
+take_lock() {
+    mkdir "$state/lock" 2>/dev/null && return 0
+    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
-    if [ -n "$br" ] && [ "${CRATIS_CLEANUP_NO_GH:-}" != 1 ] && command -v gh >/dev/null 2>&1; then
-        if gh pr list --head "$br" --state merged --json headRefOid -q '.[].headRefOid' 2>/dev/null | grep -qx "$sha"; then
-            echo "pull request merged at this commit"; return 0
-        fi
+    acquired=1
+    mkdir "$state/lock" 2>/dev/null && acquired=0
+    rm -rf "$retired"
+    return "$acquired"
+}
+hook_pulls() (
+    local repo="$1" common state now temporary lock_inode current
+    common=$(git rev-parse --git-common-dir) || exit 1
+    state="$common/cratis-cleanup-gh/$repo"
+    now=$(date +%s)
+    mkdir -p "$state" 2>/dev/null || exit 1
+    if ! take_lock; then cached_pulls; exit $?; fi
+    read -r lock_inode _ < <(lock_stat "$state/lock")
+    temporary=''
+    # A retired owner must never remove its replacement's lock.
+    trap '[[ -z "$temporary" ]] || rm -f "$temporary"; read -r current _ < <(lock_stat "$state/lock"); [ "$current" != "$lock_inode" ] || rmdir "$state/lock" 2>/dev/null' EXIT
+    if fresh_stamp; then cached_pulls; exit $?; fi
+    temporary=$(mktemp "$state/pulls.XXXXXX") || exit 1
+    printf '%s\n' "$now" > "$temporary" && mv "$temporary" "$state/failed" || exit 1
+    printf '%s\n' "$now" > "$temporary" && mv "$temporary" "$state/stamp" || exit 1
+    read -r current _ < <(lock_stat "$state/lock")
+    [ "$current" = "$lock_inode" ] || exit 1
+    # Only the latest 100 closed PRs are searched; older merged branches are simply kept.
+    if gh api "repos/$repo/pulls?state=closed&per_page=100" > "$temporary" 2>/dev/null && valid_pulls "$temporary"; then
+        read -r current _ < <(lock_stat "$state/lock")
+        [ "$current" = "$lock_inode" ] || exit 1
+        mv "$temporary" "$state/pulls.json" && rm -f "$state/failed" || exit 1
+        cat "$state/pulls.json"
+    else exit 1; fi
+)
+GH_POSSIBLE=0; GH_REPO=''
+configure_github() {
+    [ "${CRATIS_CLEANUP_NO_GH:-}" != 1 ] || return 0
+    command -v gh >/dev/null 2>&1 && command -v jq >/dev/null 2>&1 || return 0
+    local remote repo
+    remote=$(git remote get-url origin 2>/dev/null) || return 0
+    case "$remote" in
+        https://github.com/*) repo=${remote#https://github.com/} ;;
+        git@github.com:*) repo=${remote#git@github.com:} ;;
+        ssh://git@github.com/*) repo=${remote#ssh://git@github.com/} ;;
+        *) return 0 ;;
+    esac
+    repo=${repo%.git}
+    [[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || return 0
+    GH_REPO=$repo; GH_POSSIBLE=1
+}
+configure_github
+load_pulls() {
+    if [ "$HOOK" = 1 ]; then GH_PULLS=$(hook_pulls "$GH_REPO") || return 1
+    else GH_PULLS=$(gh api "repos/$GH_REPO/pulls?state=closed&per_page=100" 2>/dev/null) || return 1; fi
+    printf '%s' "$GH_PULLS" | valid_pulls /dev/stdin
+}
+
+# Ancestry evidence is resolved during planning; GitHub evidence only after the complete plan exists.
+ancestry_delivered() {
+    local sha="$1" track="$3"
+    if git merge-base --is-ancestor "$sha" "$default" 2>/dev/null; then
+        if ! grep -qx "$sha" "$firstparent"; then EVIDENCE="merged into $default"; return 0; fi
+        if [ "$track" = "[gone]" ]; then EVIDENCE="merged into $default, upstream gone"; return 0; fi
     fi
     return 1
 }
+github_delivered() {
+    printf '%s' "$GH_PULLS" | jq -e --arg br "$1" --arg sha "$2" \
+        'any(.[]; .merged_at != null and .head.ref == $br and .head.sha == $sha)' >/dev/null 2>&1
+}
+PLAN_KIND=(); PLAN_PATH=(); PLAN_SHA=(); PLAN_BRANCH=(); PLAN_EVIDENCE=(); NEEDS_GH=0
+plan_item() {
+    local kind="$1" path="$2" tip="$3" branch="$4" evidence=''
+    if ancestry_delivered "$tip" "$branch" "$([ -n "$branch" ] && track_of "$branch")"; then evidence=$EVIDENCE
+    elif [ -n "$branch" ] && [ "$GH_POSSIBLE" = 1 ]; then NEEDS_GH=1; fi
+    PLAN_KIND+=("$kind"); PLAN_PATH+=("$path"); PLAN_SHA+=("$tip")
+    PLAN_BRANCH+=("$branch"); PLAN_EVIDENCE+=("$evidence")
+}
 track_of() { git for-each-ref --format='%(upstream:track)' "refs/heads/$1" 2>/dev/null; }
 
-# ── Worktrees ─────────────────────────────────────────────────────────────────
-git worktree prune >/dev/null 2>&1
+# ── Plan the entire sweep without removing worktrees or branches ──────────────
 wt=""; sha=""; br=""; locked=0; first=1
 process_worktree() {
     [ -n "$wt" ] || return 0
     if [ "$first" = 1 ]; then first=0; return 0; fi        # the main worktree is never removed
-    local name="${br:-detached}" ev
+    local name="${br:-detached}"
     if [ "$locked" = 1 ]; then note_kept "worktree $wt ($name): locked"; return 0; fi
     case "$here/" in "$wt"/*) note_kept "worktree $wt ($name): it is the current directory - run the sweep from the main checkout"; return 0 ;; esac
-    if ! ev=$(delivered "$sha" "$br" "$([ -n "$br" ] && track_of "$br")"); then
-        note_kept "worktree $wt ($name): work not delivered to $default"; return 0
-    fi
+    plan_item worktree "$wt" "$sha" "$br"
+}
+execute_worktree() {
+    local name="${br:-detached}" ev="$1" current
+    current=$(git -C "$wt" rev-parse HEAD 2>/dev/null) || return 0
+    [ "$current" = "$sha" ] || { note_kept "worktree $wt ($name): tip changed since planning"; return 0; }
     if [ "$INCLUDE_WORK_RECORDS" = 0 ] && [ -d "$wt/.ai-work" ]; then
         local records
         if ! records=$(find "$wt/.ai-work/." -mindepth 1 -maxdepth 1 -print -quit); then
@@ -191,20 +285,50 @@ while IFS= read -r line; do
 done < <(git worktree list --porcelain; echo)
 process_worktree
 
-# ── Local branches ────────────────────────────────────────────────────────────
 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
-    printf '%s\n' "$in_use" | grep -qx "$b" && continue
-    if ev=$(delivered "$bsha" "$b" "$(track_of "$b")"); then
-        if [ "$DRY" = 1 ]; then note_removed "branch $b: would delete, $ev"
-        elif git branch -D "$b" >/dev/null 2>&1; then note_removed "branch $b: $ev"
-        else note_kept "branch $b: git refused to delete it"; fi
-    else
-        note_kept "branch $b: work not delivered to $default"
+    # 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 -x "$b" >/dev/null || continue
     fi
+    plan_item branch "$b" "$bsha" "$b"
 done < <(git for-each-ref --format='%(refname:short)|%(objectname)' refs/heads)
 
+abort_sweep() {
+    echo "cratis-cleanup-worktrees: GitHub evidence unavailable; 0 removed, keeping the entire sweep" >&2
+    exit 0
+}
+# Resolve every item's evidence before any deletion, including ancestry-proven items.
+if [ "$NEEDS_GH" = 1 ] && ! load_pulls; then abort_sweep; fi
+for ((i=0; i<${#PLAN_KIND[@]}; i++)); do
+    if [ -z "${PLAN_EVIDENCE[i]}" ] && [ -n "${PLAN_BRANCH[i]}" ] && [ -n "$GH_PULLS" ]; then
+        if github_delivered "${PLAN_BRANCH[i]}" "${PLAN_SHA[i]}"; then PLAN_EVIDENCE[i]="pull request merged at this commit"
+        else result=$?; [ "$result" = 1 ] || abort_sweep; fi
+    fi
+done
+
+# ── Execute the resolved plan, rechecking tips and worktree safety ─────────────
+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 -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"
+        else note_kept "branch $br: work not delivered to $default"; fi
+        continue
+    fi
+    if [ "$kind" = worktree ]; then wt=$path; execute_worktree "$ev"; continue; fi
+    [ "$(git rev-parse -q --verify "refs/heads/$br")" = "$sha" ] || { note_kept "branch $br: tip changed since planning"; continue; }
+    if [ "$DRY" = 1 ]; then note_removed "branch $br: would delete, $ev"
+    elif git branch -D "$br" >/dev/null 2>&1; then note_removed "branch $br: $ev"
+    else note_kept "branch $br: git refused to delete it"; fi
+done
+
 # ── Report ────────────────────────────────────────────────────────────────────
 summary="cratis-cleanup-worktrees: ${#REMOVED[@]} removed, ${#KEPT[@]} kept"
 [ "$FREED_KB" -gt 0 ] && summary="$summary, $((FREED_KB / 1024)) MB freed"

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

@@ -55,12 +55,14 @@ commands before choosing the build, regression spec and full gate commands.
 ## Copy this checklist
 
 - [ ] Reproduce the consumer bug and select its regression spec/app action.
-- [ ] Generate one stamp; build and pack the producer's full dependency closure.
+- [ ] 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.
-- [ ] Run `check` before every consumer commit and push, and on the producer.
+- [ ] Run `check` before every consumer commit and push, and on the producer; it must report 0 leaks.
+- [ ] Upstream first: a downstream ships only after the upstream has released and its pin is bumped to the released version.
 - [ ] Restore overlays, unset environment overrides, and run `check` again.
 - [ ] Review stamp-scoped `clean` dry-run targets, then apply cleanup.
 
@@ -92,7 +94,12 @@ For npm, complete the repository build before
 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. A successful pack alone does not prove dependency closure.
+separately. The package IDs a producer should ship are listed in
+[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
 
@@ -237,7 +244,8 @@ minutes, instead of after a release and a pin bump.
 - Read [references/npm-yarn.md](references/npm-yarn.md) when packing frontend libraries or restoring Yarn overlays.
 - 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 or Components → Studio.
+- 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

@@ -0,0 +1,76 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Dependency map
+
+`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` 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
+
+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. `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 |
+
+`eco` is `nuget`, `npm` or `image`. For npm, `.` means the repository root.
+
+## Using it
+
+- Find every `uses` row whose producer is the repository you changed; those consumers
+  pin its packages. A consumer may also reach the producer through another repository
+  (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 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
+
+- Arc and Chronicle depend on each other. Arc's Chronicle-facing packages are built against
+  a released Chronicle, and Chronicle's clients against a released Arc. The same holds for
+  Chronicle and Orleans. Record the nuspec dependencies and do not break the cycle.
+- Image and package pins are coupled. A consumer that builds `FROM` a producer image may
+  derive the tag from the producer's NuGet pin; check its publish workflow before tagging a
+  local image.
+- 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; `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
+
+Add `pack` rows only from the producer's publish workflow on the default branch, not a
+stale clone. Add `ids` for every package a consumer must resolve. Add one `uses` row per
+consumer manifest that pins the producer.

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`.