BOHICA-LABS / BOHICA-LABS/vsdd-factory
enhancement(cicd-setup): auto-generate §Jobs table from ci.yml to eliminate two-place drift
- Dominant language
- Rust
- Stars
- 2
- Forks
- 1
- Avg merge
- 6h 43m
- Merged PRs (30d)
- 29
Description
## Summary
Every CI lint addition requires synchronized edits in two places:
1. `.github/workflows/ci.yml` — adds the job definition.
2. `.factory/specs/architecture/cicd-setup.md` §Jobs table — adds a documentation row for the job.
These two sources drift. Observed drift during the ftc-blue Phase 1d cycle:
- Pass-8 G-3: `cicd-setup.md` §Jobs table had a duplicate row for `lint-nfr-label-references` (one full description from the initial add, one shorter paraphrase from a later edit).
- Pass-8 M-5: `cicd-setup.md` was missing 3 lint job rows that existed in `ci.yml`.
Both are pure documentation drift — `cicd-setup.md` is a human-maintained mirror of `ci.yml`, and the mirror keeps falling behind. Every lint addition this cycle (14 of them) required the two-place edit; the burden falls on the devops agent.
## Proposed change
Make `cicd-setup.md` §Jobs table auto-generated from `ci.yml`. Concretely:
1. Add a script `scripts/generate-cicd-jobs-table.sh` that:
- Parses `.github/workflows/ci.yml` for the `spec-lint` matrix (or whichever job-set is the documented one).
- Extracts: job name, trigger condition, purpose (from a structured comment or a frontmatter-like header), exit-on-fail behavior.
- Generates the `## Jobs` table in `cicd-setup.md` deterministically.
- Marks the table with `` / `` delimiters so manual edits can coexist with regeneration.
2. Add a CI step that re-runs the generator and fails if `cicd-setup.md` would change — i.e., enforces the mirror is in sync.
3. Optionally: add a pre-commit hook locally.
Bonus: this also lets `cicd-setup.md` have richer documentation prose around the table (manual sections above and below) while the table itself stays mechanical.
## Applies to
- New script: `scripts/generate-cicd-jobs-table.sh`
- `.github/workflows/ci.yml` — possibly add structured comments or YAML metadata for purpose/description
- `.factory/specs/architecture/cicd-setup.md` — mark §Jobs table with autogen delimiters
- New CI job: `verify-cicd-setup-in-sync`
## Acceptance criteria
- [ ] Single source of truth for jobs: `ci.yml`
- [ ] `cicd-setup.md` §Jobs table regenerable from ci.yml
- [ ] CI fails on drift between the two
- [ ] Documentation explains the workflow (when to edit ci.yml vs cicd-setup.md)
## Found during
ftc-blue Phase 1d adversarial cycle (2026-06-23, vsdd-factory@1.0.0-rc.21). Multiple findings (pass-8 G-3, pass-8 M-5) attributable to manual mirror drift.
## Notes
This is a small / good-first-issue improvement that pays back every time a new lint is added.
Contributor guide
Assessment
This issue has not been assessed yet.