@cratis/pi 7.104.0 → 7.105.1

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

@@ -40,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
@@ -67,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
 
@@ -110,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
 
@@ -201,17 +206,58 @@ 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.
+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
@@ -229,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`; opt-in per-worktree cache via `use-nuget` hint |
+| `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...>` |
 
@@ -242,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

@@ -6,6 +6,7 @@
 ## Contents
 
 - CPM overlay
+- Registry and list
 - Source mapping
 - Versions and cache
 - Retire a hand-rolled feed
@@ -51,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
@@ -75,26 +125,44 @@ On a major-version branch, use `bash "$local" stamp --base-version 5.0.0 "$produ
 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:
+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
-export NUGET_PACKAGES="$(git -C "$consumer" rev-parse --absolute-git-dir)/cratis-local-nuget"
+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
-# After restoring overlays/removing live local references, keep this export for:
+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 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.
+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;

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