@cratis/pi 7.85.0 → 7.87.0

package/package/corpus/harnesses/copilot/instructions/pull-requests.instructions.md

@@ -158,6 +158,8 @@ Do not open a pull request per task when the tasks belong to the same body of wo
 
 **Before consolidating open PRs, review each PR’s release intent and workflow effects.** Integration may trigger completion/publication behavior on an absorbed PR. Use supported non-release intent where appropriate. A direct request to consolidate the named pull requests authorizes the necessary relabeling and merge; it does not authorize unrelated notifications.
 
+Before a consolidation or a re-land of reverted work merges, prove it dropped nothing with `cratis-engineering-consolidation-guard`.
+
 Split into separate pull requests when the changes are genuinely unrelated, when one is urgent and the others are not, or when one is risky enough to want its own revert.
 
 ## Quality Gates

package/package/corpus/rules/pull-requests.md

@@ -157,6 +157,8 @@ Do not open a pull request per task when the tasks belong to the same body of wo
 
 **Before consolidating open PRs, review each PR’s release intent and workflow effects.** Integration may trigger completion/publication behavior on an absorbed PR. Use supported non-release intent where appropriate. A direct request to consolidate the named pull requests authorizes the necessary relabeling and merge; it does not authorize unrelated notifications.
 
+Before a consolidation or a re-land of reverted work merges, prove it dropped nothing with `cratis-engineering-consolidation-guard`.
+
 Split into separate pull requests when the changes are genuinely unrelated, when one is urgent and the others are not, or when one is risky enough to want its own revert.
 
 ## Quality Gates

package/package/corpus/skills/cratis-engineering-consolidation-guard/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-engineering-consolidation-guard/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: cratis-engineering-consolidation-guard
+description: Prove that a consolidation or re-land dropped nothing - compare the result with every original branch or commit, detect lost files that commit pairing cannot see, treat a merge resolution that reverts a file as a finding, ratchet the specification count, and enforce it as a required CI check. Use when folding several pull requests into one branch, re-landing reverted work, restoring commits by cherry-pick, or reviewing such a branch before it merges. Not for an ordinary merge of the base into a feature branch, for pull request descriptions or labels (follow the pull-requests rule), or for general code review (use cratis-code-review).
+license: LICENSE
+---
+
+# Consolidations and re-lands prove nothing was dropped
+
+A **consolidation** is any branch whose job is to carry changes authored somewhere
+else: several pull requests folded into one, reverted work brought back, commits
+restored from an abandoned branch. Its **sources** are those original branches
+and commits.
+
+The combined tree is built and specified before it merges, and that is exactly
+why loss goes unnoticed. A change deleted *by the merge itself* leaves nothing
+behind to fail: a deleted specification cannot go red, and a file a conflict
+resolution put back to its old content compiles fine. The guard compares the
+result with every source, path by path, and turns each loss into a finding.
+
+**A re-land is a consolidation.** Work that landed, was reverted and is landed
+again has one source, the original change, and loses files the same way. Run
+the same guard against that original change, not against the revert.
+
+## When the guard applies
+
+- Folding two or more pull requests onto one branch, as
+  [pull-requests.md](../../rules/pull-requests.md) asks for small related work.
+- Re-landing reverted work, whether by reverting the revert, cherry-picking the
+  original commits, or merging the original branch again.
+- Restoring commits by cherry-pick: from a deleted branch, a closed pull
+  request, or a backport.
+- Reviewing any of the above before it merges.
+
+It does not apply to merging the base branch into a feature branch (the base is
+not a source), or to a fresh implementation that shares no history with the
+work it replaces; there, specify the behavior instead.
+
+## Consolidate without rewriting history
+
+[git-commits.md](../../rules/git-commits.md) forbids rebase, squash and force.
+Each permitted way to consolidate also records its source in history, which is
+what lets CI find the sources without being told:
+
+| Situation | Default | Recorded as |
+| --- | --- | --- |
+| Fold a pull request | `git merge --no-ff pr631` | a merge whose second parent is the folded tip |
+| Restore commits | `git cherry-pick -x <sha>` | a `(cherry picked from commit <sha>)` line |
+| Re-land reverted work | `git revert <revert-sha>` | `This reverts commit <revert-sha>.` |
+
+Choose cherry-pick over reverting the revert when only some of the original
+commits come back; every change left out is then a finding that needs a
+disposition.
+
+## Name the sources
+
+A source is either a ref or a range `<from>..<ref>`. A bare ref means the change
+since `merge-base(<base>, <ref>)`; the range means the change since
+`merge-base(<from>, <ref>)`.
+
+| Source | Argument |
+| --- | --- |
+| A folded pull request | `git fetch origin "refs/pull/631/head:pr631"`, then `pr631` |
+| A merged pull request being re-landed, merge commit `M` | `M^1..M^2` |
+| A single commit `C`, or a pull request that landed as one commit | `C^..C` |
+| A branch commits were cherry-picked from | its head ref, or `C^..C` per commit |
+
+Fetch the pull request's own head ref rather than its branch: `refs/pull/<n>/head`
+survives the branch being deleted.
+
+Work that already landed needs the range form. Its commits are ancestors of the
+base, so `merge-base(<base>, <ref>)` is the tip itself and the comparison would
+be empty; the script refuses that with exit `2` rather than reporting a pass.
+
+Confirm a folded branch has not moved since it was fetched. When
+`gh pr view 631 --json headRefOid --jq .headRefOid` differs from
+`git rev-parse pr631`, fetch again and fold the new commits before verifying.
+
+## Run the guard
+
+Execute [scripts/verify-consolidation.sh](scripts/verify-consolidation.sh) inside
+the repository, with the consolidation ref first and every source after it.
+
+Requires git 2.28 or later (`git --version`); with an older git, run the three
+checks below by hand.
+
+```bash
+guard=<skill-directory>/scripts/verify-consolidation.sh
+git fetch origin
+for n in 631 640 652; do git fetch origin "refs/pull/$n/head:pr$n"; done
+"$guard" consolidate/backlog-filters pr631 pr640 pr652
+```
+
+A re-land of a merged pull request, given the original merge commit:
+
+```bash
+landed=<original-merge-sha>
+"$guard" reland/dashboard-counters "$landed^1..$landed^2"
+```
+
+Options: `--base <ref>` (default `origin/main`), `--spec-pattern <regex>` for a
+repository whose specifications are not `for_*`/`when_*` folders,
+`--allow-rewritten <sha>` and `--allow-spec-delta <n>` for dispositions, and
+`--creation-factor <n>` for `git range-diff` pairing.
+
+Before choosing sources by hand, list the ones history records and compare:
+
+```bash
+"$guard" --discover consolidate/backlog-filters
+```
+
+A source on one list and not the other is a finding of its own: either a fold
+that was not intended, or an intended one that never happened.
+
+**Pass:** exit `0` with `0 finding(s)` and a nonzero path count. Exit `1` lists
+findings. Exit `2` means it could not run (an unresolvable ref, or a source
+with nothing to compare); that is never a pass.
+After changing the script, run `"$guard" --self-test`;
+it plants each kind of loss in a scratch repository and passes only when every
+one is reported.
+
+## Why commit pairing is not enough
+
+`git range-diff` compares commits, not the resulting tree.
+
+- **After a true merge, every folded commit is an ancestor of the
+  consolidation** and pairs with itself, however much the merge resolution
+  threw away. A re-land is the same: the original commits are already in the
+  base's history.
+- **What matters is per path.** A file the source added must exist; a file it
+  modified must not still hold its pre-change content; a file it deleted must
+  not hold its pre-change content again. That content check is the one that sees
+  a resolution reverting a file.
+- **Pairing still matters when commits are copied.** After cherry-picks, a
+  source commit with no identical patch in the consolidation was dropped or
+  rewritten. The script matches by `git patch-id` first, because the `-x` line
+  alone makes `range-diff` report every cherry-pick as changed.
+- **Byte equality catches whole-file loss, not partial loss.** The script lists
+  every path that differs from the source tip as `review:`; read
+  `git diff <source-tip> <consolidation> -- <path>` for each one another source
+  or the base does not explain.
+
+The specification ratchet covers what the other checks share a blind spot for:
+the consolidation must carry at least as many specification files as the base
+plus each source's net addition. It is a count, so read the content findings
+first; they name the paths.
+
+## Disposition of every finding
+
+Each finding gets exactly one disposition before the merge:
+
+- **Restore it** in a new commit, for example
+  `git checkout pr631 -- src/Filters/ByOwner.cs`, then commit. Re-run the guard.
+- **Accept it in history** when a rewritten commit differs only by conflict
+  resolution (after reading its range-diff), or when two sources added the same
+  specification path. Commit the disposition as a trailer, so CI honors it and
+  the reviewer sees it; the guard prints each one as `disposition:`.
+
+  ```bash
+  git commit --allow-empty -m "Accept the conflict-resolved owner filter restoration" \
+      -m "Consolidation-Allow-Rewritten: <sha>"
+  ```
+
+  `Consolidation-Allow-Spec-Delta: <n>` works the same way. The
+  `--allow-rewritten` and `--allow-spec-delta` options are the local-only
+  equivalents.
+- **Remove it in its own pull request** when dropping part of a source is the
+  point. A consolidation carries its sources whole; the removal, made after it
+  merges, is then the reviewed change rather than a side effect of a merge.
+- **Stop the consolidation** when the loss cannot be explained.
+
+A merge resolution that reverts a file is a finding even when it was
+intentional, because nothing else records the intent. Never clear a finding by
+removing its source from the argument list. Explain each disposition in a pull
+request comment; the description is the release note and carries no
+verification notes.
+
+## Make it a required check
+
+A guard an agent can skip is a suggestion. Run it in CI on every pull request,
+discover the sources from history, fail on exit `1` and `2`, and add the job to
+the branch's required status checks with no bypass for the identity that
+merges. Read [references/ci-required-check.md](references/ci-required-check.md)
+when adding or reviewing that workflow.
+
+## Pitfalls
+
+- **Verifying against the revert.** A re-land's source is the original change;
+  the revert's own diff only proves the revert was undone.
+- **Passing the landed tip as a bare ref.** It is already in the base, so the
+  script exits `2` with `already contained`; use `M^1..M^2` or `C^..C`.
+- **Trusting a green build.** The specifications that would have failed are the
+  ones the merge deleted.
+- **Fixing a finding by force-pushing or squashing the branch.** That removes
+  the evidence and breaks [git-commits.md](../../rules/git-commits.md); restore
+  in a new commit.
+- **Folding from a branch name.** A deleted branch cannot be fetched again;
+  `refs/pull/<n>/head` can.

package/package/corpus/skills/cratis-engineering-consolidation-guard/references/ci-required-check.md

@@ -0,0 +1,131 @@
+# Consolidation guard as a required CI check
+
+## Contents
+
+- What makes it unskippable
+- Workflow
+- Make the check required
+- What discovery cannot see
+
+## What makes it unskippable
+
+An agent asked to "run the guard before merging" can forget, run it against the
+wrong sources, or read exit `2` as a pass. A required check removes all three:
+
+- **It runs on every pull request.** The job decides whether the branch is a
+  consolidation, so no one has to label it. A workflow-level `paths` filter
+  would leave the required check pending on unrelated pull requests; decide
+  inside the job instead.
+- **It discovers the sources from history.** `--discover` reads merge parents
+  the base does not contain, `cherry-pick -x` lines and reverts of reverts. The
+  author does not have to declare anything, and cannot leave a source out.
+- **It fails on `1` and on `2`.** A source that cannot be resolved or compared
+  fails the check; unknown is not pass. A `cherry-pick -x` of a commit that was
+  never pushed, or exists only on a fork, stays at `2`: push the source commit
+  so the job can fetch it. No trailer clears an unresolvable source.
+- **Dispositions live in history.** An accepted rewrite or specification delta
+  is a `Consolidation-Allow-Rewritten:` or `Consolidation-Allow-Spec-Delta:`
+  commit trailer, which the job honors and prints as `disposition:`. Accepting a
+  loss is therefore a reviewable commit, never a bypass. The job reads trailers
+  from every commit the consolidation adds, folded source commits included, so
+  a reviewer reads each `disposition:` line, not only the consolidation's own
+  commits.
+- **Merging requires it.** A red or missing required check blocks
+  `gh pr merge`. With no bypass actor, `gh pr merge --admin` cannot get past it
+  either.
+
+## Workflow
+
+Copy `scripts/verify-consolidation.sh` from this skill into the repository's
+own `scripts/` folder and commit it. A CI gate must not change underneath the
+repository when the shared corpus is updated, and a copy the repository owns
+changes only through its own pull requests. Run the copy's `--self-test` in the
+same job so a broken edit to it cannot pass silently.
+
+```yaml
+name: Consolidation guard
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  consolidation-guard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Fetch pull request heads
+        # Cherry-pick and revert sources can live only on deleted branches; their pull request refs remain.
+        run: git fetch --no-tags origin '+refs/pull/*/head:refs/remotes/origin/pull/*'
+
+      - name: Self-test the guard
+        run: scripts/verify-consolidation.sh --self-test
+
+      - name: Verify every folded and re-landed source survives
+        env:
+          BASE: origin/${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          sources="$(scripts/verify-consolidation.sh --discover --base "$BASE" HEAD)"
+          if [ -z "$sources" ]; then
+            echo "No folded, cherry-picked or re-landed sources between $BASE and HEAD; checked $(git rev-list --count "$BASE..HEAD") commits."
+            exit 0
+          fi
+          printf 'Sources:\n%s\n' "$sources"
+          # Word splitting is intended: one source per line.
+          # shellcheck disable=SC2086
+          scripts/verify-consolidation.sh --base "$BASE" HEAD $sources
+```
+
+Notes on the choices:
+
+- `ref: ${{ github.event.pull_request.head.sha }}` checks out the branch as
+  pushed. The default pull request checkout is GitHub's synthetic merge with the
+  base, whose own merge commit would be discovered as a fold.
+- `fetch-depth: 0` brings the full history and the base branch as
+  `origin/<base>`; discovery and merge-base need both.
+- Fetching every pull request head costs time in a large repository. Drop that
+  step only if the repository never restores from deleted branches; an
+  unresolvable source then fails the check with exit `2`, which is the safe
+  direction.
+- Keep this a `pull_request` job on a hosted runner in a public repository; it
+  needs only read access.
+- Repositories with specifications outside `for_*`/`when_*` folders pass
+  `--spec-pattern` to the verifying invocation.
+
+## Make the check required
+
+Add the job's check name, `consolidation-guard`, to the default branch's
+required status checks: a repository ruleset with **Require status checks to
+pass**, or classic branch protection with **Require status checks to pass
+before merging** and **Do not allow bypassing the above settings**. Leave the
+ruleset's bypass list empty, or at least without the identity agents merge as.
+
+Renaming the job changes the check name. The old required check then waits for
+a status that never arrives, which blocks every pull request; update the
+required check in the same change.
+
+## What discovery cannot see
+
+Discovery reads only what history records. Work restored by copying files,
+re-implemented by hand, or folded with a squash leaves no trace, which is one
+more reason [git-commits.md](../../../rules/git-commits.md) forbids squashing.
+For such a branch, run the guard locally with explicit sources and post the
+command and its result as a pull request comment, so the reviewer can repeat it.
+
+A file a source added and the consolidation deliberately removes has no
+trailer: the check stays red until the file is restored. Carry the source whole
+and remove the file in its own pull request after the consolidation merges, so
+the removal is reviewed as a change of its own.

package/package/corpus/skills/cratis-engineering-consolidation-guard/scripts/verify-consolidation.sh

@@ -0,0 +1,365 @@
+#!/usr/bin/env bash
+# Copyright (c) Cratis. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for full license information.
+#
+# Prove that a consolidation or re-land branch still carries every change it claims to carry.
+#
+# Usage:
+#   verify-consolidation.sh [options] <consolidation-ref> <source>...
+#   verify-consolidation.sh --discover [--base <ref>] <consolidation-ref>
+#   verify-consolidation.sh --self-test
+#
+# A <source> is one folded or re-landed change:
+#   <ref>          a folded branch or pull-request head; its change is everything since merge-base(<base>, <ref>)
+#   <from>..<ref>  the change <ref> made since merge-base(<from>, <ref>). Required for work that already
+#                  landed once: <merge>^1..<merge>^2 for a merged pull request, <commit>^..<commit> for one commit.
+#
+# Checks, each reported per source:
+#   A commits   source commits with no identical patch (git patch-id) in the consolidation's own commits;
+#               git range-diff then classifies each as dropped or rewritten. Skipped when the source tip is an
+#               ancestor of the consolidation, because every commit then pairs with itself whatever the
+#               merge resolution threw away.
+#   B content   every path the source touched: an added file must exist, a modified file must not still hold
+#               the pre-change blob, a deleted file must not still hold the pre-change blob. This is the check
+#               that sees a merge resolution reverting a file.
+#   C specs     the consolidation carries at least as many specification files as the base plus every
+#               source's net addition.
+#
+# Options:
+#   --base <ref>              mainline the consolidation targets (default: origin/main)
+#   --creation-factor <n>     git range-diff pairing aggressiveness, 0-100 (default: 90)
+#   --allow-rewritten <sha>   accept one commit reported as rewritten after reading its range-diff. Repeatable.
+#   --allow-spec-delta <n>    accept n fewer specification files than the ratchet expects (default: 0)
+#   --spec-pattern <regex>    extended regex selecting specification files
+#                             (default: (^|/)(for_|when_)[^/]*/.*\.(cs|ts|tsx)$)
+#   --discover                print the sources recorded in the consolidation's history, one per line
+#   --self-test               plant known defects in a scratch repository and require every one to be found
+#
+# Dispositions recorded in the consolidation's own commits count like the options, so CI honors them:
+#   Consolidation-Allow-Rewritten: <sha>     same as --allow-rewritten <sha>
+#   Consolidation-Allow-Spec-Delta: <n>      added to --allow-spec-delta
+#
+# Exit codes: 0 every source survives, 1 findings, 2 could not run (bad arguments, an unresolvable ref, or a
+# source with nothing to compare).
+set -euo pipefail
+
+BASE="origin/main"
+CREATION_FACTOR=90
+ALLOW_SPEC_DELTA=0
+ALLOWED_REWRITTEN=""
+SPEC_PATTERN='(^|/)(for_|when_)[^/]*/.*\.(cs|ts|tsx)$'
+MODE="verify"
+
+usage() { awk 'NR < 5 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' "$0"; }
+die() { printf 'ERROR %s\n' "$*" >&2; exit 2; }
+# A whole number in base 10 (so '08' is eight, not an octal error), or exit 2.
+whole_number() { case "$2" in ''|*[!0-9]*) die "$1 must be a whole number, found '$2'." ;; esac; printf '%s' "$((10#$2))"; }
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --base) [ $# -ge 2 ] || die "--base needs a value"; BASE="$2"; shift 2 ;;
+        --creation-factor) [ $# -ge 2 ] || die "--creation-factor needs a value"; CREATION_FACTOR="$(whole_number --creation-factor "$2")"; shift 2 ;;
+        --allow-rewritten) [ $# -ge 2 ] || die "--allow-rewritten needs a value"; ALLOWED_REWRITTEN="$ALLOWED_REWRITTEN $2"; shift 2 ;;
+        --allow-spec-delta) [ $# -ge 2 ] || die "--allow-spec-delta needs a value"; ALLOW_SPEC_DELTA="$(whole_number --allow-spec-delta "$2")"; shift 2 ;;
+        --spec-pattern) [ $# -ge 2 ] || die "--spec-pattern needs a value"; SPEC_PATTERN="$2"; shift 2 ;;
+        --discover) MODE="discover"; shift ;;
+        --self-test) MODE="self-test"; shift ;;
+        -h|--help) usage; exit 0 ;;
+        --) shift; break ;;
+        -*) die "unknown option: $1" ;;
+        *) break ;;
+    esac
+done
+
+commit_of() { git rev-parse --quiet --verify "$1^{commit}" 2>/dev/null || die "cannot resolve '$1' to a commit; fetch it first (a pull request: git fetch origin refs/pull/<n>/head:pr<n>)."; }
+blob_of() { git rev-parse --quiet --verify "$1:$2" 2>/dev/null || true; }
+is_ancestor() { git merge-base --is-ancestor "$1" "$2"; }
+# True when an allowed entry (at least 7 hex characters) is a prefix of the full commit SHA.
+is_allowed_rewrite() {
+    local allowed
+    for allowed in $ALLOWED_REWRITTEN; do
+        [ "${#allowed}" -ge 7 ] || continue
+        case "$1" in "$allowed"*) return 0 ;; esac
+    done
+    return 1
+}
+
+spec_count() {
+    local count
+    count="$(git ls-tree -r --name-only "$1" | grep -cE "$SPEC_PATTERN" || true)"
+    printf '%s' "${count:-0}"
+}
+
+patch_ids() {
+    # One line per non-merge commit with a diff: "<patch-id> <commit>".
+    git log --no-merges -p --no-color --format='commit %H' "$1" | git patch-id --stable
+}
+
+# ---------------------------------------------------------------------------------------------------------
+discover() {
+    [ $# -eq 1 ] || die "--discover takes exactly one consolidation ref"
+    local consolidation base_commit cons_base merge parent candidates="" reverted original parents
+    consolidation="$(commit_of "$1")"
+    base_commit="$(commit_of "$BASE")"
+    cons_base="$(git merge-base "$base_commit" "$consolidation")"
+
+    # Folded branches: every non-first parent of a merge that the base does not already contain.
+    for merge in $(git rev-list --merges "$cons_base..$consolidation"); do
+        for parent in $(git rev-list --parents -n 1 "$merge" | cut -d' ' -f3-); do
+            is_ancestor "$parent" "$base_commit" || candidates="$candidates $parent"
+        done
+    done
+    # A branch folded twice contributes each tip; an older tip is checked too, which only costs time.
+    for parent in $candidates; do printf '%s\n' "$parent"; done | awk '!seen[$0]++'
+
+    # Restorations recorded by git cherry-pick -x.
+    git log --format=%B "$cons_base..$consolidation" \
+        | sed -n 's/.*(cherry picked from commit \([0-9a-f]\{7,40\}\)).*/\1/p' \
+        | sort -u | while read -r original; do printf '%s^..%s\n' "$original" "$original"; done
+
+    # Re-lands recorded by git revert of a revert: the original change is what the reverted revert undid.
+    git log --format=%B "$cons_base..$consolidation" \
+        | sed -n 's/^This reverts commit \([0-9a-f]\{7,40\}\).*/\1/p' | sort -u \
+        | while read -r reverted; do
+            git rev-parse --quiet --verify "$reverted^{commit}" >/dev/null || die "a revert names $reverted, which is not in this clone; fetch it before discovering."
+            original="$(git log -1 --format=%B "$reverted" | sed -n 's/^This reverts commit \([0-9a-f]\{7,40\}\).*/\1/p' | head -n 1)"
+            [ -n "$original" ] || continue
+            parents="$(git rev-list --parents -n 1 "$original" | wc -w | tr -d ' ')"
+            if [ "$parents" -gt 2 ]; then printf '%s^1..%s^2\n' "$original" "$original"; else printf '%s^..%s\n' "$original" "$original"; fi
+        done
+}
+
+# ---------------------------------------------------------------------------------------------------------
+verify() {
+    [ $# -ge 2 ] || { usage >&2; exit 2; }
+    local consolidation base_commit cons_base source from to fork
+    consolidation="$(commit_of "$1")"; shift
+    base_commit="$(commit_of "$BASE")"
+    cons_base="$(git merge-base "$base_commit" "$consolidation")"
+
+    # Dispositions recorded as commit trailers in the consolidation's own history.
+    local trailer
+    for trailer in $(git log --format='%(trailers:key=Consolidation-Allow-Rewritten,valueonly)' "$cons_base..$consolidation"); do
+        printf 'disposition: Consolidation-Allow-Rewritten %s\n' "$trailer"
+        ALLOWED_REWRITTEN="$ALLOWED_REWRITTEN $trailer"
+    done
+    for trailer in $(git log --format='%(trailers:key=Consolidation-Allow-Spec-Delta,valueonly)' "$cons_base..$consolidation"); do
+        trailer="$(whole_number Consolidation-Allow-Spec-Delta "$trailer")"
+        printf 'disposition: Consolidation-Allow-Spec-Delta %s\n' "$trailer"
+        ALLOW_SPEC_DELTA=$((ALLOW_SPEC_DELTA + trailer))
+    done
+
+    # Resolve every source before checking any, so a bad argument cannot produce a partial verdict.
+    local resolved="" changed
+    for source in "$@"; do
+        case "$source" in
+            *..*) from="${source%%..*}"; to="${source#*..}" ;;
+            *) from="$BASE"; to="$source" ;;
+        esac
+        from="$(commit_of "$from")"; to="$(commit_of "$to")"
+        fork="$(git merge-base "$from" "$to")" || die "'$source' shares no history with its base."
+        if [ "$fork" = "$to" ]; then
+            die "'$source' is already contained in its base, so there is nothing to compare. A change that landed once needs the <from>..<ref> form, for example <merge>^1..<merge>^2."
+        fi
+        changed="$(git diff --name-only "$fork" "$to" | wc -l | tr -d ' ')"
+        [ "$changed" -gt 0 ] || die "'$source' changes no files relative to ${fork:0:12}; there is nothing to verify."
+        resolved="$resolved $source|$fork|$to"
+    done
+
+    local failures=0 paths=0 commits=0 entry left status subject cons_ids="" unmatched range_line abbrev
+    fail() { printf 'FAIL  %s\n' "$*"; failures=$((failures + 1)); }
+    note() { printf '      %s\n' "$*"; }
+
+    for entry in $resolved; do
+        source="${entry%%|*}"; entry="${entry#*|}"; fork="${entry%%|*}"; to="${entry#*|}"
+        printf '== %s (change since %s, tip %s)\n' "$source" "${fork:0:12}" "${to:0:12}"
+
+        # --- Check A: commits ----------------------------------------------------------------------------
+        if is_ancestor "$to" "$consolidation"; then
+            note "commits: tip is an ancestor of the consolidation, so commit pairing proves nothing; the content check decides."
+        else
+            [ -n "$cons_ids" ] || cons_ids="$(patch_ids "$cons_base..$consolidation" | cut -d' ' -f1)"
+            unmatched=""
+            while read -r patch_id left; do
+                [ -n "$patch_id" ] || continue
+                commits=$((commits + 1))
+                printf '%s\n' "$cons_ids" | grep -qxF "$patch_id" || unmatched="$unmatched $left"
+            done < <(patch_ids "$fork..$to")
+            for left in $unmatched; do
+                subject="$(git log -1 --format=%s "$left")"
+                status=""
+                while read -r range_line; do
+                    abbrev="$(printf '%s' "$range_line" | sed -E 's/^ *([0-9]+|-+): +([0-9a-f]+|-+) .*/\2/')"
+                    case "$left" in "$abbrev"*) status="$(printf '%s' "$range_line" | sed -E 's/^ *([0-9]+|-+): +([0-9a-f]+|-+) +([<>=!]) .*/\3/')"; break ;; esac
+                done < <(git range-diff --no-color --creation-factor="$CREATION_FACTOR" "$fork..$to" "$cons_base..$consolidation" | grep -E '^ *([0-9]+|-+): ')
+                if [ "$status" = "!" ]; then
+                    if is_allowed_rewrite "$left"; then
+                        note "allowed rewrite: ${left:0:12} ($subject)"
+                    else
+                        fail "$source: commit ${left:0:12} ($subject) survives with a different patch. Read 'git range-diff $fork..$to $cons_base..$consolidation'; if the difference is only conflict resolution, re-run with --allow-rewritten ${left:0:12}."
+                    fi
+                elif [ -z "$status" ] || [ "$status" = "<" ]; then
+                    fail "$source: commit ${left:0:12} ($subject) has no counterpart in the consolidation; it was dropped."
+                else
+                    fail "$source: commit ${left:0:12} ($subject) has no patch-identical counterpart, but range-diff pairs it ('$status'). Read 'git range-diff $fork..$to $cons_base..$consolidation' and decide."
+                fi
+            done
+        fi
+
+        # --- Check B: content ---------------------------------------------------------------------------
+        local kind path dest fork_blob tip_blob cons_blob
+        while IFS="$(printf '\t')" read -r kind path dest; do
+            paths=$((paths + 1))
+            case "$kind" in R*|C*) ;; *) dest="$path" ;; esac
+            fork_blob="$(blob_of "$fork" "$path")"
+            tip_blob="$(blob_of "$to" "$dest")"
+            cons_blob="$(blob_of "$consolidation" "$dest")"
+            case "$kind" in
+                A*|R*|C*)
+                    if [ -z "$cons_blob" ]; then fail "$source: added '$dest', which does not exist in the consolidation."
+                    elif [ "$cons_blob" != "$tip_blob" ]; then note "review: '$dest' differs from the source tip (git diff $to $consolidation -- '$dest')"; fi
+                    case "$kind" in R*) [ -z "$(blob_of "$consolidation" "$path")" ] || note "review: '$path' was renamed to '$dest' but still exists in the consolidation" ;; esac
+                    ;;
+                M*)
+                    if [ -z "$cons_blob" ]; then fail "$source: modified '$path', which does not exist in the consolidation."
+                    elif [ "$cons_blob" = "$fork_blob" ]; then fail "$source: modified '$path', but the consolidation still holds the pre-change version byte for byte; the change was lost."
+                    elif [ "$cons_blob" != "$tip_blob" ]; then note "review: '$path' differs from the source tip (git diff $to $consolidation -- '$path')"; fi
+                    ;;
+                D*)
+                    if [ -n "$cons_blob" ] && [ "$cons_blob" = "$fork_blob" ]; then fail "$source: deleted '$path', but the consolidation still holds the pre-change version; the deletion was lost."
+                    elif [ -n "$cons_blob" ]; then note "review: '$path' was deleted by the source but exists, changed, in the consolidation"; fi
+                    ;;
+                *) note "unclassified change '$kind' to '$path'" ;;
+            esac
+        done < <(git diff --name-status --find-renames "$fork" "$to")
+    done
+
+    # --- Check C: specification ratchet -----------------------------------------------------------------
+    local expected actual
+    # Count from where the consolidation left the base, not the base tip: specification files the base gained
+    # or lost since then are not the consolidation's to account for.
+    expected="$(spec_count "$cons_base")"
+    for entry in $resolved; do
+        entry="${entry#*|}"; fork="${entry%%|*}"; to="${entry#*|}"
+        expected=$(( expected + $(spec_count "$to") - $(spec_count "$fork") ))
+    done
+    actual="$(spec_count "$consolidation")"
+    printf '== specification files: consolidation has %s, base plus sources account for %s\n' "$actual" "$expected"
+    if [ "$actual" -lt $(( expected - ALLOW_SPEC_DELTA )) ]; then
+        fail "specification ratchet: the consolidation carries $actual specification files where $expected are accounted for. Find the deleted ones; if two sources added the same path, re-run with --allow-spec-delta $(( expected - actual ))."
+    fi
+
+    printf '\nChecked %s source(s), %s path(s), %s commit(s) compared; %s finding(s).\n' "$#" "$paths" "$commits" "$failures"
+    if [ "$failures" -ne 0 ]; then
+        printf 'Every finding needs a disposition before this merges.\n'
+        exit 1
+    fi
+}
+
+# ---------------------------------------------------------------------------------------------------------
+self_test() {
+    local self result=0 output status
+    self="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+    SCRATCH="$(mktemp -d)"
+    trap 'rm -rf "$SCRATCH"' EXIT
+    local scratch="$SCRATCH"
+    export HOME="$scratch" GIT_CONFIG_NOSYSTEM=1
+    export GIT_AUTHOR_NAME=self-test GIT_AUTHOR_EMAIL=self-test@example.com
+    export GIT_COMMITTER_NAME=self-test GIT_COMMITTER_EMAIL=self-test@example.com
+    cd "$scratch"
+    git init -q -b main
+    commit() { git add -A && git commit -q -m "$1"; }
+    mkdir -p src for_shared/when_used
+    printf 'one\n' > src/shared.txt; printf 'spec\n' > for_shared/when_used/spec.cs; printf 'old\n' > src/obsolete.txt
+    commit "Add base"
+
+    git checkout -q -b first main
+    printf 'first\n' > src/first.txt; mkdir -p for_first/when_added; printf 'spec\n' > for_first/when_added/spec.cs
+    commit "Add first feature"
+    printf 'one\nfirst\n' > src/shared.txt; git rm -q src/obsolete.txt
+    commit "Extend shared and remove obsolete"
+    git checkout -q -b second main
+    printf 'second\n' > src/second.txt
+    commit "Add second feature"
+
+    expect() {
+        local name="$1" code="$2" needle="$3"; shift 3
+        set +e; output="$(cd "$scratch" && bash "$self" --base main "$@" 2>&1)"; status=$?; set -e
+        if [ "$status" -ne "$code" ]; then
+            printf 'SELF-TEST FAIL %s: exit %s, expected %s\n%s\n' "$name" "$status" "$code" "$output"; result=1
+        elif [ -n "$needle" ] && ! printf '%s' "$output" | grep -qF -- "$needle"; then
+            printf 'SELF-TEST FAIL %s: output lacks "%s"\n%s\n' "$name" "$needle" "$output"; result=1
+        else
+            printf 'self-test pass: %s\n' "$name"
+        fi
+    }
+
+    # A clean consolidation by true merges.
+    git checkout -q -b clean main
+    git merge -q --no-ff -m "Fold first" first; git merge -q --no-ff -m "Fold second" second
+    expect "clean consolidation passes" 0 "0 finding(s)" clean first second
+
+    # The base moves on after the consolidation branched: its new specification files are not the consolidation's.
+    git checkout -q main
+    mkdir -p for_later/when_added; printf 'spec\n' > for_later/when_added/spec.cs
+    commit "Add a later spec on main"
+    expect "base gaining a spec after the branch point passes" 0 "0 finding(s)" clean first second
+    expect "non-numeric spec delta cannot run" 2 "whole number" --allow-spec-delta abc clean first second
+    expect "leading-zero spec delta is decimal" 0 "0 finding(s)" --allow-spec-delta 08 clean first second
+
+    # A merge resolution that throws away a file, a modification, a deletion and a spec.
+    git checkout -q -b lossy main
+    git merge -q --no-ff -m "Fold second" second
+    git merge -q --no-ff --no-commit first >/dev/null 2>&1
+    git checkout -q main -- src/shared.txt src/obsolete.txt
+    git rm -q --cached for_first/when_added/spec.cs; rm -f for_first/when_added/spec.cs
+    git commit -q -m "Fold first"
+    expect "lost added spec found" 1 "added 'for_first/when_added/spec.cs'" lossy first second
+    expect "reverted modification found" 1 "modified 'src/shared.txt'" lossy first second
+    expect "lost deletion found" 1 "deleted 'src/obsolete.txt'" lossy first second
+    expect "spec ratchet trips" 1 "specification ratchet" lossy first second
+
+    # A cherry-picked consolidation that leaves one commit behind.
+    git checkout -q -b picked main
+    git cherry-pick -x first~1 >/dev/null
+    expect "dropped commit found" 1 "has no counterpart" picked first
+
+    # A re-land: landed, reverted, restored by reverting the revert.
+    # A restoration whose cherry-pick needed a different patch, then accepted through a recorded disposition.
+    local first_commit; first_commit="$(git rev-parse first~1)"
+    git checkout -q -b rewritten main
+    git cherry-pick -n "$first_commit" >/dev/null
+    printf 'first, resolved\n' > src/first.txt
+    commit "Restore first feature"
+    expect "rewritten commit found" 1 "different patch" rewritten "$first_commit^..$first_commit"
+    git commit -q --allow-empty -m "Accept the resolved first feature" -m "Consolidation-Allow-Rewritten: ${first_commit:0:12}"
+    expect "recorded disposition accepts the rewrite" 0 "allowed rewrite" rewritten "$first_commit^..$first_commit"
+
+    git checkout -q main
+    git merge -q --no-ff -m "Land first" first
+    local landed; landed="$(git rev-parse HEAD)"
+    git revert -m 1 --no-edit "$landed" >/dev/null
+    local revert; revert="$(git rev-parse HEAD)"
+    git checkout -q -b reland main
+    git revert --no-edit "$revert" >/dev/null
+    expect "clean re-land passes" 0 "0 finding(s)" reland "$landed^1..$landed^2"
+    expect "landed source without a range cannot run" 2 "already contained" reland first
+    expect "discover finds the re-land" 0 "$landed^1..$landed^2" --discover reland
+    git checkout -q -b lossy-reland main
+    git revert --no-edit --no-commit "$revert"
+    git rm -q -r --cached for_first; rm -rf for_first
+    git commit -q -m "Re-land first"
+    expect "re-land that drops a spec found" 1 "added 'for_first/when_added/spec.cs'" lossy-reland "$landed^1..$landed^2"
+
+    expect "discover finds folded tips" 0 "$(git rev-parse second)" --discover clean
+    expect "unknown ref cannot run" 2 "cannot resolve" clean no-such-ref
+
+    if [ "$result" -ne 0 ]; then printf 'Self-test failed: a planted defect was not reported as expected.\n'; exit 1; fi
+    printf 'Self-test passed: every planted defect was found.\n'
+}
+
+case "$MODE" in
+    discover) discover "$@" ;;
+    self-test) self_test ;;
+    *) verify "$@" ;;
+esac

package/package/corpus/skills/cratis-screenplay-captures-and-reactions/references/record-capture-specifications.md

@@ -9,6 +9,11 @@ For `source api`, webhook, poll and other record sources, a first record of a ty
 
 This applies independently to each child identity in its parent's previous collection and each nested record: a missing/null previous nested value is new, and every child of a new parent is new. Expression guards still evaluate the mapped current record on first sight; maps and unguarded appends keep their meaning. These record fixtures are not valid for `source events`: use typed events instead (automations-and-translations [public event captures](../../cratis-screenplay-automations-and-translations/references/public-events-and-direction.md)).
 
+A capture **over events** carries a public event's list across the boundary two ways (decision 0098, no new ESM version): `lines = $.lines`
+copies the whole list into a list property of the same shape (matched by property name), and `children lines identified by sku` with an
+`append ... when added` makes one private event per element, so a repeated delivery appends nothing and one with an extra line appends only
+that line. `nested <object>` scopes into an object the same way.
+
 The complete model separates a new observation, an update and an unchanged repeat:
 
 ```screenplay

package/package/corpus/skills/cratis-screenplay-command-surface/references/constraints-produces-concurrency.md

@@ -68,8 +68,9 @@ to the routed scope. This does not make command `reads` protected.
   computed expressions parse but block binding (`PLAY0268`).
 - **`for <identifier>`** on an indented line names the event source the event is
   appended to. At most one per `produces`. To bind, it must name the command's
-  `identifier` property (`PLAY0273` otherwise; a `generated identifier` command, ESM v7, may name another required scalar property); fanning out to another event
-  source parses but does not run today.
+  `identifier` property (`PLAY0273` otherwise; a `generated identifier` command, ESM v7, may name another required scalar property). From ESM v30 (decision 0098)
+  a command may append to several event sources: each `produces` may name any required scalar command property, and the events of one accepted command are appended
+  together. Optional and collection properties still cannot be destinations. A model using it selects v30; state each destination with `for` on the matching `then` event.
 - **`tag`** lines apply literal tags to this append. Tags also exist on the
   `event` declaration, where they apply to every append of that type.
 - **Several unconditional `produces` blocks** are allowed — that is co-production,

package/package/corpus/skills/cratis-screenplay-command-surface/references/validate-rules.md

@@ -13,6 +13,7 @@
 | `matches "<regex>"` | Portable linear dialect; any substring unless anchored `^…$`; invalid syntax PLAY0367, refused constructs PLAY0699 |
 | `contains "<text>"` / `not contains "<text>"` | Ordinal substring presence/absence on scalar non-enum text |
 | `starts with "<text>"` / `ends with "<text>"` | Ordinal prefix/suffix; quoted literal operands, not conditions |
+| `decimals <= <n>` | `price decimals <= 2`; a `Decimal` property or concept only, `<n>` a whole number 0 to 28, trailing zeros do not count; ESM v29 (decision 0098) |
 | `all > <v>` / `all >= <v>` | `lines.quantity all > 0` |
 | `rule <Name>` | `orgNumber rule BeAValidOrganizationNumber` |
 | `checksum luhn|mod11|mod97` | String concept `validate checksum luhn`; validates supplied/stored values too |

package/package/corpus/skills/cratis-screenplay-projections/references/joins.md

@@ -35,7 +35,8 @@ A join cannot declare its own key or trigger removal — that is
 | `increment <prop>` | +1, expressing *modifying state* |
 | `decrement <prop>` | −1 |
 | `add <prop> by <expr>` | += expression |
-| `subtract <prop> by <expr>` | −= expression |
+| `add <prop> by <a> * <b>` | += the exact product of two values (ESM v29, decision 0098); only after `by`, one `*` |
+| `subtract <prop> by <expr>` | −= expression (also `by <a> * <b>`) |
 
 `count` and `increment` behave identically; the difference is intent. The target
 must be numeric.

package/package/corpus/skills/cratis-screenplay-specifications/references/generated-fixtures.md

@@ -66,6 +66,10 @@ specification RegistersWithPinnedValues
   differences in response field order. An absent optional source yields `Null`; arrays compare in order.
 - `then returns` counts as a success outcome but does not relax event comparison: a command specification with
   no expected events still asserts that no facts were produced.
+- A command that a **reaction** invokes takes its generated values from `given generated <Command>.<property> = <value>` lines
+  before the `when` (ESM v30, decision 0098). Each invocation takes the next value pinned for that
+  command and property in authored order; two invocations need two lines. The property must be `generated`; the value is a
+  concrete literal.
 - If execution reaches generation without every generated value supplied, the run is `Unsupported(IdentityAllocation)` and
   the specification never passes; nothing is invented. A denial or validation failure happens before generation and
   keeps its own outcome.

package/package/corpus/skills/cratis-screenplay-specifications/references/reactions-and-cascades.md

@@ -59,6 +59,13 @@ module Collections
   or mixed effects (`-037`). Single-hop reaction append specs render; deeper appends and
   command specs cascading into reactions remain `-011`. Keep refused scope as gap-fill against this contract: `cratis-screenplay-render-and-gap-fill`.
 
+### A command specification states the public event its slice publishes
+
+When an outbound Translate slice publishes an event from the private events a command produces, the command's specification
+lists the public event after the private ones (`then ProductPriceChanged` after `then ProductPriceSet`). `PLAY0285` follows the
+outbound projection (decision 0098); the accepted path is proven where the command is. An exact fact count
+fails without it.
+
 ### Version skew: cascades and the false `PLAY0285`
 
 `PLAY0285` (a specification's expected event contradicts every producer of its

package/package/corpus/skills/cratis-screenplay-toolchain/references/language-admission.md

@@ -16,6 +16,10 @@ exact language/semantic pairs; binding, reference execution and rendering are se
 | v26 | Chronological command Date/DateTime comparisons | Same-primitive `==`, `!=`, `>`, `>=`, `<`, `<=`; DateTime UTC ticks and pre-rule offset validation | v26 admitted; Host/executor run it; renderer supports admitted shapes with remaining STAGE-ESM-046 refusals; legacy engines refuse -046 |
 | v27 | A read model with two or more `key` marks | Untyped projection `key` blocks, equality-filter lists, single-instance `by` blocks, per-part fixtures | v27 admitted; Host runs it, renderer refuses STAGE-ESM-048/-047, executor refuses specs over it |
 | v28 | `==`/`!=` between Uuid values in command `require` and `produces when` | Uuid properties, Uuid concepts and identities, canonical literals; protected read paths in `require` only | v28 refused STAGE-ESM-016 |
+| v29 | `decimals <= N`; `add`/`subtract` by `a * b`; a concept mapped to another concept over the same primitive (decision 0098) | Decimal-places rule on a Decimal concept or property; the exact decimal product; the conversion is admitted only when the target declares no rule or compliance the source does not, never for enums, composites or optional into required | v29 refused until Stage admits it |
+| v30 | A command `produces ... for <required scalar property>` (several event sources); a specification `given generated <Command>.<property> = <value>` (decision 0098) | Several sources in one accepted command; pinned generated values for reaction-invoked commands, taken in authored order | v30 refused until Stage admits it |
+
+Constructs of decision 0098 with no executable-model content need no version: application-level toolbar buttons in the layout's `navigation topbar` region (`button <id> title "..." slice <Slice>` with an optional indented `authorize <Policy>`), a command specification that states the public event its outbound Translate slice publishes (no more false `PLAY0285`), and a capture over events that copies a list (`lines = $.lines`) or fans out with `children lines identified by sku`. Check `screenplay --version` against the release that admitted v29 and v30 before relying on them.
 
 Requires Screenplay 4.181.0 or later (`screenplay --version`) for atomic batches; older compilers cannot admit the preamble.
 

package/package/corpus/skills/cratis-screenplay-ui-composition/references/application-shell.md

@@ -166,6 +166,25 @@ own.
 - `item` entries (`action`, `navigate to`, `dialog`) stay valid beside buttons. Use `button` to start a slice, and
   `item ... navigate to` to go to a screen.
 
+### Application-level buttons
+
+A layout's `navigation topbar` region takes the same `button` line once for the whole application, so an action stays at hand
+whichever page the user is on. An indented `authorize <Policy>` line under a button limits who sees it. A module's
+`navigation topbar extends|overrides|inherits` governs the buttons as it does the items. A button in `navigation sidebar` is
+`PLAY0741`. The slice rules above (`PLAY0761`-`PLAY0765`) apply unchanged (decision 0098).
+
+```text
+layout AppShell
+  category application
+  topbar
+  navigation contributes Navigation
+  content
+  navigation topbar
+    item shop title "Shop" target Shop
+    button newProduct title "New product" slice Merchandising.Products.DraftProduct emphasis primary icon plus
+      authorize CanCurateCatalog
+```
+
 ⚠️ When a screen uses a `template`, put the `toolbar` inside a slot body (`body` above). Stage refuses a screen that
 mixes a top-level `template` directive with other top-level directives.
 

package/package/profile-catalog.json

@@ -982,6 +982,7 @@
       "id": "cratis/engineering/core",
       "availableTargets": [
         "cratis-documentation-writing",
+        "cratis-engineering-consolidation-guard",
         "cratis-engineering-decision-record",
         "cratis-engineering-docs-authoring",
         "cratis-engineering-effect-boundaries",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.85.0",
+  "version": "7.87.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [