Skip to content

Pipeline Design 39

Jump to bottom
ezigus edited this page Mar 1, 2026 · 2 revisions

Design: Stale documentation detected

Context

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).

Decision

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.

Alternatives Considered

  1. 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.

  2. Pre-commit hook to auto-sync on every commit — Pros: Prevents staleness entirely. / Cons: Adds latency to every commit; sw-docs sync scans all scripts (~100 files) which is slow for a hook; the existing GitHub Actions workflow + daemon patrol already catches drift on a reasonable cadence.

  3. 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.sh sync logic across all section generators.

Implementation Plan

  • Files to create: none
  • Files to modify (already modified and staged):
    • .ai-standards/generated/claude-instructions.md — core-scripts and test-suites tables
    • .ai-standards/generated/copilot-instructions.md — core-scripts and test-suites tables
    • .ai-standards/generated/codex-instructions.md — core-scripts and test-suites tables
    • .github/copilot-instructions.md — core-scripts and test-suites tables
    • AGENTS.md — core-scripts and test-suites tables
  • 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 sync after merge.

Validation Criteria

  • shipwright docs check exits 0 (all sections fresh)
  • Line counts for sw-loop.sh (3395), sw-pipeline.sh (2875), and sw-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 main and passes CI

Clone this wiki locally