@cratis/pi 7.103.7 → 7.104.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
@@ -78,6 +87,8 @@ Format: `<next-patch>-local.<12-digit-UTC-minute>.g<sha7>`, based on the highest
 downgrades. Confirm tags cover the consumer's released constraints. With no tag,
 the helper warns and falls back to a base that must be checked before proceeding.
 The `g` prefix keeps even an all-digit SHA nonnumeric in SemVer.
+On `release/5.0`, use `stamp --base-version 5.0.0 "$producer"` (also with `--train`);
+the strict SemVer core overrides tag discovery verbatim. Ensure it meets consumer minima.
 Use the identical stamp for packages and images. A changed build needs a distinct
 stamp; do not overwrite a cached version (the minute and commit determine it).
 
@@ -126,9 +137,18 @@ export CHRONICLE_KERNEL_VERSION="$stamp" # Studio integration specs, if used
 ```
 
 Pass: the helper reports overridden IDs and restore resolves them to local
-artifacts. Follow any printed `--configfile` instruction. Run Yarn install after
+artifacts. To isolate NuGet downloads per worktree, set the optional
+`NUGET_PACKAGES` export printed by `use-nuget` before restore and keep it set through
+`clean`; see [versions and cache](references/dotnet-nuget.md#versions-and-cache).
+Follow any printed `--configfile` instruction. Run Yarn install after
 `use-npm`; it adds file-tarball resolutions, not links to source folders.
 
+For independent NuGet producer versions, explicitly opt in with
+`verify-pack --composition FILE`, `use-nuget CONSUMER --composition FILE
+[--pin-transitive]`, then `verify-assets CONSUMER --composition FILE`. See the
+[manifest and native-validation workflow](references/dotnet-nuget.md#mixed-version-compositions-opt-in).
+No producer is rebuilt; restore before changing a composition or an active legacy overlay.
+
 ### 5. Build and exercise the consumer
 
 From the consumer root, with the printed NuGet environment sourced:
@@ -192,7 +212,13 @@ feed packages, NuGet version folders, discoverable Yarn cache entries, local ima
 tags and registered sessions; unresolved npm backups block it. Missing Docker/Yarn
 probes are reported as skipped cleanup, not proof those stores are empty. Default
 fuse: 500 subjects; investigate an unexpectedly large list instead of raising it.
-Prefer `--stamp` to `--all` on shared machines.
+Prefer `--stamp` to `--all`. Legacy cleanup refuses the entire request (exit `2`,
+also in dry-run) for registered live overlay/manifest references; it reports kept
+stamps and paths. Restore/remove references, then retry. This is not an ownership
+registry; unregistered consumers need manual review. To retire a hand-rolled
+`-local.N` feed, restore released pins/sources and switch to helper stamps; review
+old artifacts separately because `clean` does not recognize them. See
+[migration](references/dotnet-nuget.md#retire-a-hand-rolled-feed).
 
 ## Configuration and results
 
@@ -203,7 +229,7 @@ is sourced before defaults. Do not put credentials in it. Environment settings:
 | --- | --- |
 | `CRATIS_LOCAL_FEED` | `${XDG_CACHE_HOME:-$HOME/.cache}/cratis/local-feed`; outside tracked files |
 | `CRATIS_LOCAL_SESSION_DIR` | `<absolute-git-dir>/cratis-local`; per-worktree overlays/backups |
-| `NUGET_PACKAGES` | `$HOME/.nuget/packages`; shared cache, unique version folders |
+| `NUGET_PACKAGES` | `$HOME/.nuget/packages`; opt-in per-worktree cache via `use-nuget` hint |
 | `CRATIS_LOCAL_CLEAN_MAX` | `500`; cleanup subject fuse |
 | `CRATIS_LOCAL_RUN` | Optional executable wrapper receiving `build <label> -- <command...>` |
 

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

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