118 lines
5.6 KiB
Markdown
118 lines
5.6 KiB
Markdown
# Harness-Free Quality and Security CI Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:executing-plans` to implement this
|
|
> plan task-by-task, `superpowers:test-driven-development` for executable drift controls, and
|
|
> `superpowers:verification-before-completion` before reporting. Git remains human-only: do not
|
|
> stage, commit, amend, or push.
|
|
|
|
**Goal:** Reconstruct a harness-free, repository-internal quality and dependency-security CI
|
|
control plane that is truthful to the current Gradle build and `main` branch.
|
|
|
|
**Architecture:** Canonical workflows live only under `.github/workflows`. A small YAML gate matrix
|
|
maps current controls to real Gradle tasks/plugins/tests and workflow jobs, while a portable Bash
|
|
verifier rejects drift; vulnerability policy is enforced by a platform-neutral Trivy filesystem
|
|
job with guarded GitHub-only complements.
|
|
|
|
**Tech Stack:** GitHub Actions-compatible YAML, Bash, Gradle 9 Groovy DSL, Java/Temurin 21, Trivy,
|
|
jq, lychee.
|
|
|
|
---
|
|
|
|
### Task 1: Capture missing-control RED
|
|
|
|
**Files:**
|
|
|
|
- Verify absent: `.trivyignore.yaml`
|
|
- Verify absent: `.github/ci-gate-matrix.yml`
|
|
- Verify absent: `.github/scripts/verify-gate-matrix.sh`
|
|
|
|
- [ ] Run `cd src && ./gradlew verifyTrivyignore --console=plain`.
|
|
- [ ] Confirm the failure names the missing repository-root `.trivyignore.yaml`.
|
|
- [ ] Confirm the matrix, verifier, and canonical workflows are absent.
|
|
|
|
### Task 2: Add repository baselines
|
|
|
|
**Files:**
|
|
|
|
- Create: `.tool-versions`
|
|
- Create: `.gitattributes`
|
|
- Create: `.trivyignore.yaml`
|
|
|
|
- [ ] Pin `java temurin-21.0.11+10`, matching candidate evidence and the local Gradle launcher JDK.
|
|
- [ ] Normalize source, YAML, Markdown, Gradle, and shell text to LF; keep `gradlew.bat` CRLF and
|
|
mark common binary formats `-text`.
|
|
- [ ] Add the four structured empty Trivy sections with suppression governance comments.
|
|
- [ ] Run `cd src && ./gradlew verifyTrivyignore --console=plain` and expect zero suppressions
|
|
validated.
|
|
|
|
### Task 3: Add quality governance and drift verification
|
|
|
|
**Files:**
|
|
|
|
- Create: `.github/CODEOWNERS`
|
|
- Create: `.github/pull_request_template.md`
|
|
- Create: `.github/ci-gate-matrix.yml`
|
|
- Create: `.github/scripts/verify-gate-matrix.sh`
|
|
- Create: `.github/workflows/ci-quality-gates.yml`
|
|
- Create: `.github/workflows/link-check.yml`
|
|
|
|
- [ ] Record only current Gradle/task/test/job mechanisms in the matrix.
|
|
- [ ] Implement repository-root-safe matrix parsing with schema, uniqueness, task/plugin/test, and
|
|
workflow-job checks.
|
|
- [x] Before Java/Gradle, fail unless `docs/security/public-paths-snapshot.txt` is committed and
|
|
non-empty; do not let the Gradle task create a first-run CI baseline.
|
|
- [ ] Have a human track and commit the canonical snapshot; agents do not stage or commit, and CI's
|
|
`git ls-files` precondition rejects an untracked worktree file.
|
|
- [ ] Add required `quality-gates`, `sample-off`, and `gate-matrix-lint` jobs plus the advisory
|
|
quarantine job.
|
|
- [ ] Make `release-gate` depend exactly on the three required jobs and fail unless all succeeded.
|
|
- [ ] Add path-scoped link checking for PR and `main` push.
|
|
- [ ] Pin every workflow `uses:` reference to a verified full commit SHA and retain its immutable
|
|
release label in an inline comment.
|
|
- [ ] Run Bash syntax and gate-matrix checks.
|
|
|
|
### Task 4: Add dependency-vulnerability controls
|
|
|
|
**Files:**
|
|
|
|
- Create: `.github/dependency-review-config.yml`
|
|
- Create: `.github/dependency-vulnerability-policy.md`
|
|
- Create: `.github/scripts/install-jq.sh`
|
|
- Create: `.github/workflows/dependency-vulnerability.yml`
|
|
|
|
- [ ] Configure PR dependency review to block new High/Critical runtime vulnerabilities and
|
|
forbidden strong/network-copyleft licenses without posting PR summary comments.
|
|
- [ ] Document High/Critical blocking, Medium/Low advisory, KEV fail-closed handling, suppression
|
|
review, GitHub/Gitea differences, egress, and mirror requirements.
|
|
- [ ] Install checksum-pinned jq and version-pinned Trivy under `${RUNNER_TEMP}`, adding them through
|
|
`${GITHUB_PATH}` without privileged writes.
|
|
- [ ] Guard GitHub-only review/submission and keep `trivy-fs` platform-neutral on all required
|
|
triggers.
|
|
- [ ] Pass `--ignorefile .trivyignore.yaml` to every Trivy invocation.
|
|
- [ ] Reject KEV catalogs with blank metadata, non-positive/non-integral or mismatched counts,
|
|
empty vulnerability arrays, invalid CVE identifiers, or duplicate identifiers before
|
|
intersection.
|
|
- [ ] Reject malformed or empty Trivy JSON before extracting candidate vulnerability identifiers.
|
|
|
|
### Task 5: Verify the reconstructed slice
|
|
|
|
**Files:**
|
|
|
|
- Verify: all files created by this plan
|
|
|
|
- [ ] Parse strict policy/matrix YAML with an available parser and document GitHub `on` parser
|
|
limitations if applicable.
|
|
- [ ] Prove only `main` is an active branch trigger and no active `master` remains.
|
|
- [ ] Prove every Trivy scan consumes the root ignore file.
|
|
- [ ] Prove the release fan-in is exact and excludes quarantine.
|
|
- [x] Prove the missing/empty/untracked snapshot precondition exits non-zero; the canonical
|
|
`/api/healthcheck` snapshot now exists in the worktree but still requires a human commit.
|
|
- [ ] Exercise the KEV predicate with empty/malformed/count/CVE/duplicate failures and a valid
|
|
synthetic catalog.
|
|
- [ ] Exercise the Trivy JSON predicate with malformed Results/Vulnerabilities/IDs and a realistic
|
|
valid Results array.
|
|
- [ ] Prove no harness call or `.gitea/workflows` shadow was introduced.
|
|
- [ ] Run `git diff --check` and `git status --short`.
|
|
- [ ] Capture the work in the required LLM Wiki branch note, including evidence and external
|
|
blockers, without claiming server Actions or full Phase A completion.
|