diff --git a/changelog.d/3585-scripts-sync-scaffold-sh-now-copies-the.md b/changelog.d/3585-scripts-sync-scaffold-sh-now-copies-the.md new file mode 100644 index 00000000..efa02887 --- /dev/null +++ b/changelog.d/3585-scripts-sync-scaffold-sh-now-copies-the.md @@ -0,0 +1,5 @@ +--- +class: fixed +trace: #3585 +--- +`scripts/sync-scaffold.sh` now copies the packaged docs into `specfuse/loop/data/docs/`; the docs list lives in `scripts/sync-scaffold-docs.txt`, which the drift test reads too, so editing a doc and running the sync clears the drift guard diff --git a/scripts/sync-scaffold-docs.txt b/scripts/sync-scaffold-docs.txt new file mode 100644 index 00000000..d9ba59f3 --- /dev/null +++ b/scripts/sync-scaffold-docs.txt @@ -0,0 +1,18 @@ +# Repo docs/ files shipped as packaged copies under specfuse/loop/data/docs/ +# (#3585). One path per line, relative to the repository root; `#` lines and +# blank lines are ignored. scripts/sync-scaffold.sh copies each one, and +# tests/test_scaffold_data_in_sync.py byte-checks each one, both from this +# list, so a doc added here is synced and guarded with no second edit. +docs/glossary.md +docs/getting-started.md +docs/methodology.md +docs/skills.md +docs/concepts/ralph-lineage.md +docs/concepts/architecture-addendum-gates-and-iterative-planning.md +docs/concepts/autonomy-stop-classes.md +docs/concepts/adopting-auto-mode.md +docs/concepts/monitoring-to-fix.md +docs/concepts/monitoring-schema.md +docs/concepts/monitoring-runners.md +docs/lifecycles.md +docs/flows.html diff --git a/scripts/sync-scaffold.sh b/scripts/sync-scaffold.sh index 971b7fcb..a0d3a10a 100755 --- a/scripts/sync-scaffold.sh +++ b/scripts/sync-scaffold.sh @@ -25,7 +25,8 @@ # plugins/specfuse/ is the single source of truth. Guarded by # tests/test_skills_vendored_in_sync.py. # 3. Package-sync: specfuse/loop/data/ is a byte-for-byte copy of the canonical -# .specfuse/ sources. Run this after editing any canonical source, then +# .specfuse/ sources, plus the repo docs/ files listed in +# scripts/sync-scaffold-docs.txt (copied to specfuse/loop/data/docs/). Run this after editing any canonical source, then # commit and run the drift-guard test (tests/test_scaffold_data_in_sync.py). # # Usage: scripts/sync-scaffold.sh @@ -353,9 +354,40 @@ for f in "${FILES[@]}"; do sync_file "$f" done +# Docs: repo docs/ is canonical for the packaged docs/ copies (#3585). The list +# lives in sync-scaffold-docs.txt beside this script, which the drift guard +# (tests/test_scaffold_data_in_sync.py) reads too. A tree with no docs/ (a test +# fixture) skips the stage; a listed doc missing from docs/ is an error. +DOCS_MANIFEST="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/sync-scaffold-docs.txt" +docs_checked=0 +echo +echo "Syncing docs:" +if [[ -d "$REPO_ROOT/docs" ]]; then + while IFS= read -r rel || [[ -n "$rel" ]]; do + [[ -z "$rel" || "$rel" == \#* ]] && continue + src_path="$REPO_ROOT/$rel" + dest_path="$DEST/$rel" + if [[ ! -f "$src_path" ]]; then + echo "error: canonical doc missing: $rel (listed in $DOCS_MANIFEST)" >&2 + exit 1 + fi + mkdir -p "$(dirname "$dest_path")" + docs_checked=$((docs_checked + 1)) + if cmp -s "$src_path" "$dest_path" 2>/dev/null; then + echo " unchanged: $rel" + else + cp "$src_path" "$dest_path" + echo " synced: $rel" + synced=$((synced + 1)) + fi + done < "$DOCS_MANIFEST" +else + echo " no docs/ at $REPO_ROOT — skipping." +fi + echo if [[ "$synced" -eq 0 ]]; then - echo "Scaffold data already in sync (${#FILES[@]} files checked)." + echo "Scaffold data already in sync ($((${#FILES[@]} + docs_checked)) files checked)." else echo "$synced file(s) updated." fi diff --git a/tests/sync_scaffold.bats b/tests/sync_scaffold.bats index db7d9e8e..0356a8e6 100644 --- a/tests/sync_scaffold.bats +++ b/tests/sync_scaffold.bats @@ -310,3 +310,49 @@ git_core_pushed() { # core is a git work tree with an upstream, fully pushed [ "$status" -eq 0 ] [[ "$(cat "$TESTDIR/.specfuse/rules/verification-discipline.md")" == *"verifdisc"* ]] } + +# #3585: repo docs/ files listed in scripts/sync-scaffold-docs.txt are copied +# into specfuse/loop/data/docs/, so editing a doc and running the sync is +# enough to clear the drift guard. +DOCS_MANIFEST="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/scripts/sync-scaffold-docs.txt" + +seed_docs() { + while IFS= read -r rel; do + [[ -z "$rel" || "$rel" == \#* ]] && continue + mkdir -p "$TESTDIR/$(dirname "$rel")" + printf 'doc %s\n' "$rel" > "$TESTDIR/$rel" + done < "$DOCS_MANIFEST" +} + +@test "sync copies every listed doc into specfuse/loop/data/docs/" { + seed_docs + REPO_ROOT="$TESTDIR" run bash "$SCRIPT" + [ "$status" -eq 0 ] + while IFS= read -r rel; do + [[ -z "$rel" || "$rel" == \#* ]] && continue + cmp -s "$TESTDIR/$rel" "$TESTDIR/specfuse/loop/data/$rel" + done < "$DOCS_MANIFEST" +} + +@test "sync updates a stale packaged doc" { + seed_docs + mkdir -p "$TESTDIR/specfuse/loop/data/docs/concepts" + printf 'stale\n' > "$TESTDIR/specfuse/loop/data/docs/concepts/monitoring-schema.md" + REPO_ROOT="$TESTDIR" run bash "$SCRIPT" + [ "$status" -eq 0 ] + [ "$(cat "$TESTDIR/specfuse/loop/data/docs/concepts/monitoring-schema.md")" = "doc docs/concepts/monitoring-schema.md" ] +} + +@test "a listed doc missing from docs/ fails the sync" { + seed_docs + rm "$TESTDIR/docs/flows.html" + REPO_ROOT="$TESTDIR" run bash "$SCRIPT" + [ "$status" -ne 0 ] + [[ "$output" == *"docs/flows.html"* ]] +} + +@test "a tree with no docs/ directory skips the docs stage" { + REPO_ROOT="$TESTDIR" run bash "$SCRIPT" + [ "$status" -eq 0 ] + [ ! -d "$TESTDIR/specfuse/loop/data/docs" ] +} diff --git a/tests/test_scaffold_data_in_sync.py b/tests/test_scaffold_data_in_sync.py index cf936bc6..ae77b97b 100644 --- a/tests/test_scaffold_data_in_sync.py +++ b/tests/test_scaffold_data_in_sync.py @@ -47,22 +47,18 @@ "schemas/events/spec_issue_routed.schema.json", } -# Docs manifest — canonical source is repo docs/, not .specfuse/. -DOCS_TRACKED = { - "docs/glossary.md", - "docs/getting-started.md", - "docs/methodology.md", - "docs/skills.md", - "docs/concepts/ralph-lineage.md", - "docs/concepts/architecture-addendum-gates-and-iterative-planning.md", - "docs/concepts/autonomy-stop-classes.md", - "docs/concepts/adopting-auto-mode.md", - "docs/concepts/monitoring-to-fix.md", - "docs/concepts/monitoring-schema.md", - "docs/concepts/monitoring-runners.md", - "docs/lifecycles.md", - "docs/flows.html", -} +# Docs manifest — canonical source is repo docs/, not .specfuse/. Read from +# the same list scripts/sync-scaffold.sh copies from (#3585), so the sync and +# this guard cannot disagree about which docs are packaged. +DOCS_MANIFEST = REPO_ROOT / "scripts" / "sync-scaffold-docs.txt" + + +def _read_docs_manifest() -> set: + lines = DOCS_MANIFEST.read_text(encoding="utf-8").splitlines() + return {line.strip() for line in lines if line.strip() and not line.lstrip().startswith("#")} + + +DOCS_TRACKED = _read_docs_manifest() # Unmirrored manifest — files authored directly under specfuse/loop/data/ # with no canonical .specfuse/ or docs/ counterpart to byte-match against.