chore(docs): track operator-checklist.md verbatim
Land the existing untracked file as a baseline commit so the "what existed" diff is legible and distinct from story 02's refresh.
This commit is contained in:
151
docs/guides/operator-checklist.md
Normal file
151
docs/guides/operator-checklist.md
Normal file
@@ -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 <owner>/template-vertical --source=. --private --push` (or `--public`)
|
||||
- Or push to an existing remote: `git remote add origin <url> && 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` →
|
||||
`@<sha>` 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 <name> --tier <feature|core> --target <path>`).
|
||||
|
||||
**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
|
||||
Reference in New Issue
Block a user