@sdd-method/sdd-cli 0.110.2 → 0.111.0

package/scripts/README.md

@@ -1,10 +1,17 @@
 # Bundled upstream scripts
 
-Frozen copies of bash scripts from
-[`sdd-method`](https://github.com/tomfosteruk/sdd-method) that
-`sdd-cli` either shells out to (`validate-*`) or retains as a regression
-oracle (`sync-method-baseline.sh`, which is superseded by native TypeScript
-sync in v0.2.0 but kept so `tests/parity/` can keep catching drift).
+Copies of bash scripts from
+[`sdd-method`](https://github.com/tomfosteruk/sdd-method) that `sdd-cli` shells
+out to at runtime (`validate-*`). These SHIP in the npm package, because the
+`sdd-cli validate` dispatcher spawns them.
+
+⚠ `sync-method-baseline.sh` is no longer here. It was never shelled out to — it is
+a parity oracle — and it now lives at `tests/parity/fixtures/`, which is where its
+only consumer is and, crucially, is not published. While it sat in this directory it
+shipped to adopters, and it had drifted 386 lines behind upstream: it wrote a lock
+with a single bundle entry, which would have dropped every other bundle's entry on
+the 97-of-105 adopter locks that are multi-bundle. Adopters receive the
+authoritative script in `platform-baseline`; nothing needed a copy here.
 
 Files in this directory are **byte-identical** to their upstream source. Do
 not edit here — edit upstream, then run the refresh procedure below to copy
@@ -15,7 +22,6 @@ signal.
 
 | File | Upstream path | Pinned to |
 |---|---|---|
-| `sync-method-baseline.sh` | `orchestration/scripts/sync-method-baseline.sh` | `4d80826` |
 | `validate-app-docs.sh` | `orchestration/scripts/validate-app-docs.sh` | `db4cb25` |
 | `validate-app-dependencies.sh` | `orchestration/scripts/validate-app-dependencies.sh` | `db4cb25` |
 | `validate-integration-docs.sh` | `orchestration/scripts/validate-integration-docs.sh` | `db4cb25` |
@@ -34,14 +40,24 @@ cp ../sdd-method/orchestration/scripts/<script>.sh scripts/
 # Then update the SHA in this README and commit both together.
 ```
 
-Automation (pre-build sync step) is a later milestone. Refresh is currently
-manual and visible.
+Still manual for the validators. ⚠ **Manual-and-visible turned out to be
+manual-and-invisible**: this README mandated byte-identity ("do not edit here …
+byte-identity keeps `diff` usable as a drift-detection signal") while its Lifecycle
+section simultaneously described the sync oracle as "frozen at 4a8cd05" — and the
+provenance table pinned a *different* commit. Either reading was defensible, so a
+386-line drift looked intentional to anyone who checked. The parity oracle now has
+the automation this section called "a later milestone":
+`scripts/sync-vendored-script.sh` plus `tests/parity/vendored-script-drift.test.ts`,
+which fails with a re-sync instruction when the copies differ. The validators here
+still have no such guard.
 
 ## Lifecycle
 
-The `sync-method-baseline.sh` oracle is frozen at 4a8cd05 and stays for
-regression testing — the native TS sync is tested against it in
-`tests/parity/`.
+The `sync-method-baseline.sh` oracle stays for regression testing — the native TS
+sync is compared against it in `tests/parity/` — but it is tracked at upstream HEAD,
+not frozen. Frozen was the wrong model: parity against a frozen oracle stops testing
+the CLI against what adopters run and starts testing it against history, which is how
+a real functional gap (the CLI not applying ADR transitions) stayed invisible.
 
 The `validate-*.sh` scripts are what `sdd-cli validate` spawns. Native TS
 reimplementation of individual validators is v0.3.0+, smallest-first

package/scripts/sync-vendored-script.sh

@@ -3,12 +3,13 @@
 # vendored copy. Mirrors scripts/sync-canonical-schema.sh: direction of truth is
 # one-way, sdd-method -> vendored, and the vendored copy is never hand-edited.
 #
-# The vendored copy matters twice over: the parity suite compares sdd-cli against
-# it, and it ships in the npm package (`files` includes `scripts`), so an adopter
-# can invoke it from node_modules. It once fell 386 lines behind and, among other
-# losses, wrote a lock with a single bundle entry — dropping every other bundle's
-# entry, on an estate where 97 of 105 locks are multi-bundle. Because parity
-# compared against the stale copy, nothing caught it.
+# The fixture lives under tests/parity/fixtures/ because that is its only purpose.
+# It used to sit in scripts/, which ships in the npm package, so an adopter could
+# invoke a stale sync script from node_modules — and it had fallen 386 lines behind,
+# writing a lock with a single bundle entry and dropping every other bundle's, on an
+# estate where 97 of 105 locks are multi-bundle. Because parity compared against that
+# stale copy, nothing caught it. Adopters receive the authoritative script in
+# platform-baseline; nothing needs a copy here except the parity comparison.
 #
 # Usage:
 #   scripts/sync-vendored-script.sh                     # from $SDD_METHOD_PATH or ~/Projects/method/sdd-method
@@ -21,7 +22,7 @@ set -euo pipefail
 
 SDD_METHOD_PATH="${1:-${SDD_METHOD_PATH:-$HOME/Projects/method/sdd-method}}"
 SOURCE="$SDD_METHOD_PATH/orchestration/scripts/sync-method-baseline.sh"
-DEST="$(dirname "$0")/sync-method-baseline.sh"
+DEST="$(dirname "$0")/../tests/parity/fixtures/sync-method-baseline.sh"
 
 if [[ ! -f "$SOURCE" ]]; then
   echo "ERROR: authoritative script not found at $SOURCE" >&2