fix: make payload drift checks read-only

what:
- separate read-only CI drift detection from normal payload synchronization
- cover canonical reference changes in CI and add a regression test
- document the hybrid source-ownership boundary

why:
- the previous --ci path overwrote drift before reporting success, allowing stale payloads to pass

Author: CodeSigils

.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
       - "README.md"
       - "CITATION.cff"
       - "SECURITY.md"
+      - "references/**"
       - "scripts/**"
       - "skills/**"
   pull_request:
@@ -19,6 +20,7 @@ on:
       - "README.md"
       - "CITATION.cff"
       - "SECURITY.md"
+      - "references/**"
       - "scripts/**"
       - "skills/**"
   schedule:
@@ -59,8 +61,11 @@ jobs:
       - name: Verify referenced URLs
         run: python3 scripts/verify-urls.py
 
+      - name: Test payload sync behavior
+        run: python3 scripts/test-sync-payload.py
+
       - name: Payload sync check
         run: bash scripts/sync-payload.sh --ci
 
       - name: Ruff check scripts
-        run: python3 -m ruff check scripts
+        run: python3 -m ruff check scripts

README.md

@@ -120,6 +120,8 @@ references in any shipped skill file or reference.
 python3 .github/scripts/check-portability.py
 python3 scripts/validate.py
 python3 scripts/verify-urls.py
+python3 scripts/test-sync-payload.py
+bash scripts/sync-payload.sh --ci
 python3 -m ruff check scripts
 ```
 
@@ -139,6 +141,9 @@ python-project-workflow/
 │   ├── workflows/ci.yml
 │   └── scripts/check-portability.py
 ├── scripts/
+│   ├── payload-manifest.json
+│   ├── sync-payload.sh
+│   ├── test-sync-payload.py
 │   ├── validate.py
 │   └── verify-urls.py
 └── skills/
@@ -150,11 +155,15 @@ python-project-workflow/
             ├── core-footguns.md
             ├── safe-editing.md
             ├── mature-repo-preservation.md
-            └── eval-benchmark-hardening.md
+            ├── eval-benchmark-hardening.md
+            └── drift-classes.md
 ```
 
-Shipping boundary: `skills/python-project-workflow/` is the runtime payload and
-source of truth. Everything else is repository-only development infrastructure.
+Shipping boundary: `skills/python-project-workflow/` is the runtime payload.
+Its `SKILL.md` is authored in place, while root `references/` is the canonical
+source for mirrored payload references. `scripts/payload-manifest.json` declares
+what is mirrored, and `scripts/sync-payload.sh --ci` verifies the boundary without
+modifying it. Everything else is repository-only development infrastructure.
 
 ## References
 
@@ -166,6 +175,7 @@ source of truth. Everything else is repository-only development infrastructure.
 | `safe-editing.md` | Safe edit workflow for backslash-heavy content |
 | `mature-repo-preservation.md` | Preservation-first workflow for established repos |
 | `eval-benchmark-hardening.md` | Benchmark and eval hardening guidance |
+| `drift-classes.md` | Payload drift and installed-mirror staleness detection and remediation |
 
 The Orientation Checklist is now inlined in SKILL.md § Orientation Checklist.
 

scripts/sync-payload.sh

@@ -14,6 +14,36 @@ CI_MODE=false
 
 echo "Syncing skill payload..."
 DRIFT=false
+CHANGED=false
+SYNC_ERROR=false
+
+sync_file() {
+    local source="$1"
+    local target="$2"
+    local label="$3"
+    local mode="${4:-644}"
+
+    if [ ! -f "$source" ]; then
+        echo "  MISSING source: $label"
+        DRIFT=true
+        SYNC_ERROR=true
+        return
+    fi
+
+    if $CI_MODE; then
+        if [ ! -f "$target" ] || ! cmp -s "$source" "$target"; then
+            echo "  DRIFTED: $label"
+            DRIFT=true
+        fi
+        return
+    fi
+
+    if [ ! -f "$target" ] || ! cmp -s "$source" "$target"; then
+        CHANGED=true
+    fi
+    mkdir -p "$(dirname "$target")"
+    install -m "$mode" "$source" "$target"
+}
 
 is_covered() {
     local rel="$1"
@@ -30,7 +60,9 @@ is_covered() {
     local ref_mode
     ref_mode=$(python3 -c "import json; d=json.load(open('$MANIFEST')); r=d.get('references',''); print(r if isinstance(r,str) else '')" 2>/dev/null)
     if [ "$ref_mode" = "*" ]; then
-        case "$rel" in references/*) return 0 ;; esac
+        case "$rel" in
+            references/*) [ -f "$ROOT/$rel" ] && return 0 ;;
+        esac
     fi
     return 1
 }
@@ -39,47 +71,62 @@ is_covered() {
 for f in $(python3 -c "import json; d=json.load(open('$MANIFEST')); print('\n'.join(str(x) for x in d.get('files',[])))" 2>/dev/null); do
     source="$ROOT/$f"
     target="$PAYLOAD_DIR/$f"
-    if [ ! -f "$source" ]; then echo "  MISSING source: $f"; DRIFT=true; continue; fi
-    mkdir -p "$(dirname "$target")"
-    install -m 644 "$source" "$target"
+    sync_file "$source" "$target" "$f"
 done
 
 # Scripts
 for s in $(python3 -c "import json; d=json.load(open('$MANIFEST')); print('\n'.join(str(x) for x in d.get('scripts',[])))" 2>/dev/null); do
     source="$ROOT/scripts/$s"
     target="$PAYLOAD_DIR/scripts/$s"
-    if [ ! -f "$source" ]; then echo "  MISSING source: scripts/$s"; DRIFT=true; continue; fi
-    mkdir -p "$(dirname "$target")"
-    if [ -x "$source" ]; then install -m 755 "$source" "$target"; else install -m 644 "$source" "$target"; fi
+    mode=644
+    [ -x "$source" ] && mode=755
+    sync_file "$source" "$target" "scripts/$s" "$mode"
 done
 
 # References (mirror)
 ref_mode=$(python3 -c "import json; d=json.load(open('$MANIFEST')); r=d.get('references',''); print(r if isinstance(r,str) else '')" 2>/dev/null)
 if [ "$ref_mode" = "*" ]; then
-    mkdir -p "$PAYLOAD_DIR/references"
-    find "$PAYLOAD_DIR/references" -type f -delete 2>/dev/null || true
-    cp "$ROOT/references/"*.md "$PAYLOAD_DIR/references/"
+    for source in "$ROOT/references/"*.md; do
+        if [ ! -f "$source" ]; then
+            echo "  MISSING source: references/*.md"
+            DRIFT=true
+            SYNC_ERROR=true
+            break
+        fi
+        name="$(basename "$source")"
+        sync_file "$source" "$PAYLOAD_DIR/references/$name" "references/$name"
+    done
 fi
 
 # Orphan cleanup
-orphans=0
 while IFS= read -r -d '' f; do
     relpath="$f"
     # shellcheck disable=SC2295
     rel="${relpath#$PAYLOAD_DIR/}"
     if ! is_covered "$rel"; then
         echo "  ORPHANED: $rel"
-        rm -f "$f"
-        orphans=$((orphans + 1))
+        if ! $CI_MODE; then
+            rm -f "$f"
+            CHANGED=true
+        else
+            DRIFT=true
+        fi
     fi
 done < <(find "$PAYLOAD_DIR" -type f -print0)
-find "$PAYLOAD_DIR" -type d -empty -delete 2>/dev/null || true
+if ! $CI_MODE; then
+    find "$PAYLOAD_DIR" -type d -empty -delete 2>/dev/null || true
+fi
 
-[ "$orphans" -gt 0 ] && DRIFT=true
-if $DRIFT; then
+if $SYNC_ERROR; then
+    echo ""
+    echo "SYNC FAILED"
+    exit 1
+elif $DRIFT; then
     echo ""
     echo "DRIFT DETECTED"
-    $CI_MODE && exit 1
+    exit 1
+elif $CHANGED; then
+    echo "Payload synchronized"
 else
     echo "Payload in sync"
-fi
+fi

scripts/test-sync-payload.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Regression tests for read-only payload drift detection."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+REFERENCE = Path("skills/python-project-workflow/references/core-footguns.md")
+ORPHAN = Path("skills/python-project-workflow/references/orphan.md")
+
+
+def run_sync(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["bash", "scripts/sync-payload.sh", *args],
+        cwd=root,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="python-project-workflow-sync-") as tmp:
+        fixture = Path(tmp) / "repo"
+        shutil.copytree(
+            ROOT,
+            fixture,
+            ignore=shutil.ignore_patterns(".git", ".ruff_cache", "__pycache__"),
+        )
+
+        target = fixture / REFERENCE
+        target.write_text(
+            target.read_text(encoding="utf-8") + "\nintentional drift\n",
+            encoding="utf-8",
+        )
+        orphan = fixture / ORPHAN
+        orphan.write_text("orphan\n", encoding="utf-8")
+        before = target.read_bytes()
+
+        check = run_sync(fixture, "--ci")
+        if check.returncode == 0:
+            raise AssertionError(f"--ci accepted payload drift:\n{check.stdout}")
+        if target.read_bytes() != before:
+            raise AssertionError("--ci modified a drifted payload file")
+        if not orphan.exists():
+            raise AssertionError("--ci removed an orphaned payload file")
+        if "DRIFTED: references/core-footguns.md" not in check.stdout:
+            raise AssertionError(f"--ci did not report content drift:\n{check.stdout}")
+        if "ORPHANED: references/orphan.md" not in check.stdout:
+            raise AssertionError(f"--ci did not report the orphan:\n{check.stdout}")
+
+        sync = run_sync(fixture)
+        if sync.returncode != 0:
+            raise AssertionError(f"normal sync failed:\n{sync.stdout}")
+        source = fixture / "references/core-footguns.md"
+        if target.read_bytes() != source.read_bytes():
+            raise AssertionError("normal sync did not repair payload drift")
+        if orphan.exists():
+            raise AssertionError("normal sync did not remove the orphan")
+
+        final_check = run_sync(fixture, "--ci")
+        if final_check.returncode != 0:
+            raise AssertionError(f"repaired payload failed --ci:\n{final_check.stdout}")
+
+    print("PASS: payload CI mode detects drift without modifying files")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())