Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Pipeline Design 39

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.mdcore-scripts and test-suites tables
    • .ai-standards/generated/copilot-instructions.mdcore-scripts and test-suites tables
    • .ai-standards/generated/codex-instructions.mdcore-scripts and test-suites tables
    • .github/copilot-instructions.mdcore-scripts and test-suites tables
    • AGENTS.mdcore-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

AltStyle によって変換されたページ (->オリジナル) /