-
Notifications
You must be signed in to change notification settings - Fork 0
Pipeline Design 39
Shipwright embeds auto-generated documentation tables (line counts, file purposes) inside 5 instruction files using <!-- AUTO:section-id --> markers. Three scripts changed since the last sync:
| Script | Old Lines | New Lines | Delta |
|---|---|---|---|
scripts/sw-loop.sh |
3361 | 3395 | +34 |
scripts/sw-pipeline.sh |
2877 | 2875 | -2 |
scripts/sw-lib-pipeline-detection-test.sh |
598 | 604 | +6 |
This caused 10 AUTO sections (core-scripts ×ばつ 5 files + test-suites ×ばつ 5 files) to report stale data. The existing shipwright docs sync mechanism regenerates these sections by scanning scripts/ and updating the markdown tables in-place.
Constraints:
- No code logic changes — purely documentation freshness.
- The sync tooling (
scripts/sw-docs.sh) already handles regeneration; no new tooling is needed. - All 5 target files are checked into the repo and consumed by different AI agents (Claude, Codex, Copilot).
Run the existing shipwright docs sync command (already done — 30/30 sections now fresh), commit the regenerated files, and open a PR against main. No new infrastructure, no new scripts, no architectural changes.
The fix is mechanical: the AUTO section parser reads script headers and wc -l output, then overwrites the markdown table between the <!-- AUTO:... --> comment pairs. This is the designed workflow — the staleness is expected after any script edit and is resolved by the periodic sync.
-
Manual line-count edits in each file — Pros: No tooling dependency, surgical changes. / Cons: Error-prone across 5 files ×ばつ 2 sections each; defeats the purpose of the AUTO system; risks introducing inconsistencies between files.
-
Pre-commit hook to auto-sync on every commit — Pros: Prevents staleness entirely. / Cons: Adds latency to every commit;
sw-docs syncscans all scripts (~100 files) which is slow for a hook; the existing GitHub Actions workflow + daemon patrol already catches drift on a reasonable cadence. -
Remove line counts from documentation tables — Pros: Eliminates the most common source of staleness. / Cons: Line counts provide useful signal about script complexity and growth over time; would require updating
sw-docs.shsync logic across all section generators.
- Files to create: none
- Files to modify (already modified and staged):
-
.ai-standards/generated/claude-instructions.md—core-scriptsandtest-suitestables -
.ai-standards/generated/copilot-instructions.md—core-scriptsandtest-suitestables -
.ai-standards/generated/codex-instructions.md—core-scriptsandtest-suitestables -
.github/copilot-instructions.md—core-scriptsandtest-suitestables -
AGENTS.md—core-scriptsandtest-suitestables
-
- Dependencies: none
- Risk areas: Effectively zero — these are documentation-only changes to auto-generated tables. No runtime behavior is affected. The only risk is a merge conflict if another PR modifies the same AUTO sections concurrently, which is resolved by re-running
shipwright docs syncafter merge.
-
shipwright docs checkexits 0 (all sections fresh) - Line counts for
sw-loop.sh(3395),sw-pipeline.sh(2875), andsw-lib-pipeline-detection-test.sh(604) are correct in all 5 files - No unrelated changes are included in the diff (only AUTO section content between markers)
- PR targets
mainand passes CI