BOHICA-LABS / BOHICA-LABS/vsdd-factory

enhancement(cicd-setup): auto-generate §Jobs table from ci.yml to eliminate two-place drift

Open
#218 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.