@cratis/pi 7.103.7 → 7.105.0

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
@@ -31,7 +40,7 @@ pin updates use ordinary dependency maintenance; CI changes use the
 
 Execute [scripts/cratis-local-packages.sh](scripts/cratis-local-packages.sh), not
 an improvised replacement. Run `bash "$local" <command> --help` for inputs and
-errors. Requires bash and git; add dotnet for NuGet, node and Yarn for npm, Docker
+errors. Requires bash, git and node for package registry operations; add dotnet for NuGet, Yarn and npm for npm packages, Docker
 for images, or the selected language toolchain. Check availability first:
 
 ```bash
@@ -58,13 +67,14 @@ commands before choosing the build, regression spec and full gate commands.
 - [ ] 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.
+- [ ] Set a task ID (`--task ID` or `CRATIS_LOCAL_TASK`, convention `owner/repo#number`), activate the consumer overlay and select the local image.
+- [ ] Run `list` (or `list --json`) to inspect recorded producers, tasks and live consumers.
 - [ ] 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; 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.
+- [ ] Review `finish --task ID`, mark completed work with `--apply`, then review `clean --expired` (or explicit `--stamp`) targets before applying cleanup.
 
 ### 1. Stamp
 
@@ -78,6 +88,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).
 
@@ -99,7 +111,11 @@ separately. The package IDs a producer should ship are listed in
 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.
+`verify-pack` does. After successful packing, the helper atomically records package IDs,
+producer worktree, branch and HEAD in `FEED/stamps/STAMP/record.json` (mode `0600`).
+Pass `--task ID` to `pack-*` and `use-*`, or set `CRATIS_LOCAL_TASK`; without either,
+the recorded task is null. IDs match `^[A-Za-z0-9][A-Za-z0-9._#:/-]{0,127}$` and
+are JSON values, never paths. Prefer `owner/repo#number`.
 
 ### 3. Build an image when needed
 
@@ -126,9 +142,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:
@@ -181,18 +206,65 @@ build output, not pre-existing work.
 
 ### 8. Clean
 
+`list [--json] [--stamp STAMP]` is a lock-free, read-only inventory, including legacy
+artifacts without records. It shows producer ownership, task state, live/total consumers
+and age, plus recorded state. Invalid records appear as `invalid` rows (JSON includes
+`error`); listing continues and exits `1`. `use-*` records each consumer, including every
+composition member stamp. `restore` restores overlays first, then updates only those
+stamps' consumer entries; an invalid selected record warns with its path and exits `1`.
+A registry-write failure after activation warns and exits `1`, keeping the overlay for restoration.
+
+```bash
+bash "$local" list
+bash "$local" finish --task owner/repo#number
+bash "$local" finish --task owner/repo#number --apply
+```
+
+`finish` is dry-run by default, marks task completion only, and succeeds with a message
+if no record names the task and all records are valid. It warns and skips invalid records
+without rewriting them, continues with valid matches, and exits `1` if any were skipped.
+It never restores consumers or cleans packages automatically.
+
 ```bash
 bash "$local" clean "$consumer" --stamp "$stamp"
 # Review listed subjects and stop task-owned containers first.
 bash "$local" clean "$consumer" --stamp "$stamp" --apply
 ```
 
+`clean --stamp STAMP` validates only that stamp's record; default clean and `--all`
+validate all selected records. An invalid selected record refuses cleanup (`2`).
+
+Use `clean --expired` for retention-based cleanup, then add `--apply` after review.
+It keeps unrecorded stamps, active compositions and live manifest/overlay references
+(in registered sessions or recorded consumer worktrees). Otherwise, a stamp expires
+when every non-null producing task is finished (at least one required), all recorded
+consumers are gone (at least one required), or a real release at or above its base exists,
+in that order. Offline evidence is NuGet `.nupkg.metadata` in the shared or registered
+private caches; npm has no offline release check. `--online` opts into NuGet/npm
+registry checks with a 10-second timeout; failures provide no evidence. Each stamp
+prints `expired STAMP: REASON` or `kept STAMP: REASON`; kept stamps succeed (`0`).
+`list --json` reports the same offline decision in `expiry:{expired,reasons,kept}`.
+`--expired` cannot combine with `--stamp` or `--all`. It retains the same lock, fuse
+and dry-run default. Applying also prunes gone consumers and missing session registrations.
+
 Pass: expected subjects listed, then removed without force. Cleanup covers local
 feed packages, NuGet version folders, discoverable Yarn cache entries, local image
-tags and registered sessions; unresolved npm backups block it. Missing Docker/Yarn
+tags, stamp record directories 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.
+NuGet cleanup scans the active shared cache and every registered private cache.
+It removes only recognized local/train version folders. Missing or mismatched
+private-cache markers, symlinks and paths outside the consumer's Git directory
+refuse the entire request. `restore` keeps private caches. After restoring overlays
+and removing live stamps, use `clean "$consumer" --private-cache` to review whole-cache
+removal, then add `--apply` to remove the marked cache and its session registration.
+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 +275,9 @@ 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`; active cache scanned by `clean` |
+| `CRATIS_LOCAL_TASK` | Optional task ID, convention `owner/repo#number`; `--task ID` on pack/use/finish overrides it |
+| `CRATIS_LOCAL_PRIVATE_CACHE` | `0`; `1` opts `use-nuget` into a marked worktree cache, also available with `--private-cache` |
 | `CRATIS_LOCAL_CLEAN_MAX` | `500`; cleanup subject fuse |
 | `CRATIS_LOCAL_RUN` | Optional executable wrapper receiving `build <label> -- <command...>` |
 
@@ -216,7 +290,7 @@ doing read-only discovery.
 Helper exit codes: `0` success, `1` findings/failed operation, `2` cannot run or
 invalid input. Neither `1` nor `2` is a pass. After script changes, execute
 `bash "$local" --self-test`; pass requires printed passed/skipped counts and exit
-`0`. npm overlay/restore tests run when node is on the inherited PATH; real packing
+`0`. Registry tests require node; npm overlay/restore tests use the inherited PATH. Real packing
 is not exercised by this hermetic self-test. Report any unrun ecosystem checks.
 
 ## Why the local loop

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

@@ -3,6 +3,17 @@
 
 # .NET and NuGet
 
+## Contents
+
+- CPM overlay
+- Registry and list
+- 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 +25,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 +43,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.
@@ -40,6 +52,55 @@ an already-running IDE. A config overlay printed below must also reach IDE resto
 The `CRATIS_LOCAL_RUN` adapter applies to pack steps, not these restore/build
 commands; route each heavy command separately through the host's build queue.
 
+## Registry and list
+
+Package operations require node for the stamp registry. Successful `pack-nuget` and
+`pack-npm` calls record package IDs, producer repo/worktree, branch, HEAD and UTC time
+in `FEED/stamps/STAMP/record.json` (schema `1`, mode `0600`). `--task ID` on pack/use
+commands overrides `CRATIS_LOCAL_TASK`; otherwise task is null. Prefer `owner/repo#number`.
+IDs match `^[A-Za-z0-9][A-Za-z0-9._#:/-]{0,127}$`; they are JSON values, never paths.
+
+`list [--json] [--stamp STAMP]` joins feed artifacts with records without locking or
+writing. Legacy stamps appear with `recorded:false`. Text shows stamp, ecosystem,
+package count, producer `repo@branch`, task state, live/total consumers, age and recorded state. JSON
+has top-level `schema:1`, `feed` and `stamps`; each stamp includes packages, producers,
+tasks, consumer states (`live`, `restored`, `gone`), creation time and age in seconds.
+Its `expiry:{expired,reasons,kept}` uses the same offline decision as `clean --expired`:
+keep unrecorded stamps, active compositions and live manifest/overlay references first;
+otherwise expire finished producing tasks, all consumers gone, or a release at or above
+the stamp's base, in that order. A taskless pack alone never expires by task completion;
+a stamp without consumers never expires by consumers gone. Live references include
+registered sessions and recorded consumer worktrees, even after task completion.
+A live consumer must still be a Git root and retain an env, overlay, backup or composition.
+`use-*` records consumers after activation (every composition member stamp); `restore`
+restores overlays first, then marks only the session's stamps restored without erasing
+history. An invalid selected record prints a `WARNING:` naming its path and exits `1`;
+unrelated records are not read. A registry error after activation warns, exits `1` and
+leaves the overlay intact. Pack/use still refuse invalid target records (`2`); dry runs
+write no records. `list` keeps listing invalid records as `recorded:"invalid"` with an
+`error` string in JSON (text: `RECORDED` is `invalid`) and exits `1` if any are invalid.
+
+```bash
+bash "$local" list --json
+bash "$local" finish --task owner/repo#number
+bash "$local" finish --task owner/repo#number --apply
+```
+
+`finish` previews by default; `--apply` marks that task finished in every matching
+record. Invalid records are skipped with a `WARNING:` naming each path, never rewritten;
+valid matches are still marked, and any skipped record makes the exit code `1`. No match
+with all records valid is a successful no-op with a message. It does not restore overlays
+or delete packages. Stamp-scoped `clean --apply` reads only the selected record and removes
+its directory with its artifacts; invalid selected records refuse cleanup (`2`). Default
+clean and `--all` validate all selected records and fail closed (`2`) on any invalid one.
+Review the dry run first. For retention-based cleanup, run `clean --expired`, then
+`clean --expired --apply` after reviewing `expired STAMP: REASON` and `kept STAMP: REASON`.
+Kept stamps are success (`0`); invalid records or scan errors refuse cleanup (`2`).
+`--expired` is exclusive with `--stamp` and `--all`, uses the same lock and fuse, and
+never removes an unrecorded stamp. Apply also prunes gone consumers from remaining
+records and removes missing session directories' registrations. A consumer is gone
+when its worktree is missing/not a Git root or its session directory is missing.
+
 ## Source mapping
 
 If a tracked root NuGet config has `packageSourceMapping`, the helper prints an
@@ -59,11 +120,141 @@ 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.
+
+Opt into a private cache when a shared cached package could mask a same-version
+repack. `use-nuget --private-cache` creates a marked cache at
+`<absolute-git-dir>/cratis-local-nuget` and records it in the session's `nuget-cache`
+file. The printed env file exports `NUGET_PACKAGES`. This works with both stamps
+and `--composition`. Set `CRATIS_LOCAL_PRIVATE_CACHE=1` to opt in through configuration.
+Without either option, activation keeps its default behavior.
+
+```bash
+bash "$local" use-nuget "$consumer" "$stamp" --private-cache
+# Source the env path printed by use-nuget, then restore and verify.
+dotnet restore path/to/consumer.slnx
+bash "$local" restore "$consumer"
+# Remove any remaining live manifest references before cleanup.
+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 stamp-scoped cleanup before repacking. `clean` scans the active
+`NUGET_PACKAGES` (or `$HOME/.nuget/packages`) and every registered private cache,
+even after the env export is unset. It removes only recognized `-local`/`-train`
+version folders and keeps released versions. A missing or mismatched marker,
+symlink or cache path outside the consumer's Git directory stops the entire clean
+with exit `2`. Registered live references also refuse cleanup, even in dry-run.
+
+`restore` keeps the private cache. To remove it entirely, restore overlays and
+remove all live stamp references first. Review `clean "$consumer" --private-cache`,
+then add `--apply`. This removes the marked cache and its `nuget-cache` registration.
+Never remove an entire shared cache.
+
+`clean --expired` also scans `$HOME/.nuget/packages` when `NUGET_PACKAGES` is set.
+Offline release evidence is a non-prerelease `lowercase-id/X.Y.Z/.nupkg.metadata`
+at or above the record's base in the shared or any registered private cache, for
+any recorded NuGet ID. Released folders are evidence only, never cleanup targets.
+Add `--online` to opt into NuGet flat-container and npm registry release checks
+with a 10-second timeout; missing evidence and network failures simply keep that
+expiry reason from applying. `list` never checks online.
+
+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"
+```
+
+`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.
 
-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.
+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 +266,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"
 ```
 

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

@@ -14,6 +14,11 @@ stamp=$(bash "$local" stamp "$producer")
 bash "$local" pack-npm "$producer" "$stamp"
 ```
 
+Pass `--task ID` to pack/use, or set `CRATIS_LOCAL_TASK` (convention `owner/repo#number`),
+to associate the stamp with work. Successful packing records package IDs and producer
+HEAD; activation records the consumer after publication. See
+[Registry and list](dotnet-nuget.md#registry-and-list) for inventory and task completion.
+
 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. Tarballs are named `<scope>-<name>-<version>.tgz` (`@cratis/foo` becomes
@@ -78,3 +83,12 @@ consumer manifests. Reinstall released dependencies after restoration, then run
 Review `clean "$consumer" --stamp "$stamp"` before `--apply`. Passing the consumer
 allows Yarn cache discovery; no consumer or unavailable Yarn yields a reported
 skip. Unresolved backups block cleanup rather than silently losing recovery data.
+`restore` retains consumer history in the registry; stamp-scoped `clean --apply`
+removes the stamp's record directory together with its artifacts.
+Alternatively review `clean "$consumer" --expired`, then add `--apply`. Live manifest
+or overlay references and active compositions always retain the stamp; unrecorded
+stamps require explicit `--stamp`. Finished producing tasks or all consumers gone
+can expire npm stamps. npm has no offline release evidence: `--online` opts into
+registry release checks (10-second timeout); failed checks never remove a stamp.
+Kept stamps succeed (`0`). Applying also prunes gone consumers and missing sessions;
+`--expired` cannot combine with `--stamp` or `--all`.

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

@@ -32,6 +32,13 @@ sorts above the released pin like a local stamp does.
 
 ## Recording consumed versions
 
+`pack-*` and `use-*` accept `--task ID` (or `CRATIS_LOCAL_TASK`, convention
+`owner/repo#number`). Successful packs record producer HEADs and IDs in the stamp
+registry; use records consumers. `list [--json]` includes train stamps and their
+owners, tasks and consumers. `finish --task ID` previews completion; add `--apply`
+to mark the task finished without removing artifacts. See
+[Registry and list](dotnet-nuget.md#registry-and-list).
+
 `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
@@ -41,3 +48,12 @@ is unchanged, so a train tool can record the consumed versions without scraping
 
 `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`.
+Applying also removes `FEED/stamps/STAMP`, including its registry record.
+
+For retention-based cleanup of both local and train stamps, review `clean --expired`
+before adding `--apply`. Unrecorded stamps, active compositions and live references
+are kept; otherwise finished producing tasks, all consumers gone, or a real release
+at or above the base can expire a stamp. Offline evidence uses NuGet shared/private
+caches; `--online` opts into NuGet/npm registry checks with a 10-second timeout.
+Network failure is not evidence. Kept stamps succeed (`0`); apply also prunes gone
+consumers and missing sessions. `--expired` cannot combine with `--stamp` or `--all`.