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

```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