Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions changelog.d/3585-scripts-sync-scaffold-sh-now-copies-the.md
Original file line number Diff line number Diff line change
@@ -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
18 changes: 18 additions & 0 deletions scripts/sync-scaffold-docs.txt
Original file line number Diff line number Diff line change
@@ -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
36 changes: 34 additions & 2 deletions scripts/sync-scaffold.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
46 changes: 46 additions & 0 deletions tests/sync_scaffold.bats
Original file line number Diff line number Diff line change
Expand Up @@ -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" ]
}
28 changes: 12 additions & 16 deletions tests/test_scaffold_data_in_sync.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading