diff --git a/docs/guides/operator-checklist.md b/docs/guides/operator-checklist.md new file mode 100644 index 0000000..0e72e19 --- /dev/null +++ b/docs/guides/operator-checklist.md @@ -0,0 +1,151 @@ +# Operator checklist + +The decisions and code that make this template's security + supply-chain +stack work are landed in code (ADR-022, ADR-023, the library-evaluation +epic, the CI-security epic). This doc covers the **human-side actions** +required to put it into operation in a real GitHub-hosted repo. Read top +to bottom on first adoption; revisit the "Ongoing" section weekly. + +The biggest leverage move is **#1 (push to a remote)** — until that +happens, the entire `.github/workflows/` surface is inert. Everything +else cascades from there. + +--- + +## Right now (unblocks everything else) + +**1. Push to a GitHub remote.** No remote is configured by default on a +fresh template clone, which means CI doesn't run anywhere. Either: + +- `gh repo create /template-vertical --source=. --private --push` (or `--public`) +- Or push to an existing remote: `git remote add origin && git push -u origin main` + +**Decision attached:** public vs private. Public → CodeQL is free, Socket +free tier just works. Private → CodeQL needs GitHub Pro/Team/Enterprise +plan (workflow runs unconditionally but GitHub gates execution). + +--- + +## During the dispatch loop (the agent drives this; you watch) + +**2. Continue the in-flight library-evaluation epic.** Run +`pnpm work dispatch --execute`. The dispatcher picks up the next unticked +bullet and marches through. + +Refresh `~/.claude/.credentials.json` from the macOS keychain when +sandcastle returns 401 (the keychain one-liner; happens ~every 30 days): + +```bash +security find-generic-password -s "Claude Code-credentials" -a "$USER" -w \ + > ~/.claude/.credentials.json +chmod 600 ~/.claude/.credentials.json +``` + +**3. After library-evaluation epic completes**, the CI-security epic +unblocks. `pnpm work dispatch --execute` picks up its story 01 +automatically. + +--- + +## After all implementation lands (one-time setup, ~30 minutes total) + +**4. Install GitHub Apps** (one click each, free tier): + +- **Renovate** → `https://github.com/apps/renovate` → grant repo access. + After install, Renovate opens an onboarding PR — merge it to enable. + **First real PR is the Action SHA-pin sweep** (rewrites `@v4` → + `@` across all workflows). Merge that too. +- **Socket Security** → `https://github.com/apps/socket-security` → + grant repo access. PR comments start appearing on the next + `package.json` diff. + +**5. Toggle GitHub repo settings** (Settings → Code security and +analysis): + +- ✅ Dependabot **alerts** (server-side vuln scan) — your passive + monitoring surface +- ✅ Dependabot **security updates** — OFF (Renovate handles bumps; + alerts stay on for visibility) +- ✅ Secret scanning + **push protection** — blocks known token + patterns at the GitHub edge +- ✅ CodeQL alerts (auto-enabled by the workflow) + +**6. Configure branch protection on `main`** (Settings → Branches → +main): + +- Require status checks: `validate`, `socket-security`, `CodeQL` +- Require linear history (matches release-please's expectations) +- Do **not** add `library-policy/re-evaluation` as a blocker — ADR-023 + explicitly decided against gating main on revalidation issues + +**7. Add `TURBO_TOKEN` + `TURBO_TEAM`** as repo secrets/variables for +Turborepo remote caching (already documented in `ci.yml`'s comment +block). + +**8. Sentry DSNs** if you want production observability per ADR-014 / +ADR-017 (`WEB_NEXT_SENTRY_DSN`, `CMS_SENTRY_DSN`, etc.) — set as repo +secrets for the apps you actually deploy. + +--- + +## Ongoing (per-decision, weekly cadence) + +**9. Renovate's weekly PR stream.** + +- **Minor + patch** bumps auto-merge if green. Nothing to do. +- **Major** bumps block until `evaluate-library` re-runs and refreshes + the trace's `last-revalidated`. The dispatch loop can pick these up + via story-style task — or you walk the skill manually + (`/evaluate-library --tier --target `). + +**10. Weekly trace-revalidation cron fires** every Monday 06:30 UTC. + +- Soft divergence → appended to the rolling `library-policy/dashboard` + issue. Skim weekly; mostly no-action. +- Hard divergence → fresh `library-policy/re-evaluation` issue per + affected dep. **Human triage required** (ADR-023 §3, no + auto-dispatch). Decide: re-walk evaluate-library, accept-with- + allowlist, or migrate off the library. Add the issue to the dispatch + queue if the re-walk is mechanical. + +**11. CVE accepted-risk decisions.** When `pnpm audit` flags something +with no patch available, add `accepted-cves: [CVE-XXXX-YYYY]` to the +relevant trace's frontmatter with a note explaining why the risk is +accepted. + +**12. License-allowlist requests.** ADR-022 names +`MIT/Apache-2.0/BSD/ISC/MPL-2.0` as allowlisted. If a real need surfaces +(e.g. a `GPL-3.0-with-classpath-exception` library), you decide whether +to extend — and the decision becomes an ADR-022 amendment in a new ADR. + +--- + +## Read once the docs land + +- `docs/guides/adding-a-library.md` (library-evaluation epic story 05) + — human reading-room for the 9 filters + 3 prompts +- `docs/guides/ci-security.md` (CI-security epic story 09) — human + reading-room for the four pillars + failure-mode hierarchy table + +--- + +## Cleanup notes + +- **Untracked files in repo root** — `check-shas-cjs.js`, + `check-shas.mjs`, `check-shas2.mjs`, `check-shas3.mjs`. These appeared + during SHA-experimentation work and aren't part of any commit. Decide + whether to delete or `.gitignore`. +- **`apps/*/tsconfig.tsbuildinfo`** continues to churn on every + typecheck. A `chore: gitignore tsbuildinfo` commit would stop that + drift. + +--- + +## Related + +- ADR-022 — Library evaluation policy +- ADR-023 — CI security + supply-chain enforcement stack +- `docs/guides/runbook.md` — first-time template setup (Postgres, dev + servers, sandcastle auth) +- `docs/guides/adding-a-library.md` — adding a runtime dep +- `docs/guides/ci-security.md` — security stack reference