agentic-dev/docs/guides/operator-checklist.md

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):

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