Skip to content

docs: rewrite runbooks as verified steps and correct stale ADR facts - #36

Merged
ttncode merged 2 commits into
mainfrom
docs/runbooks-and-adrs
Sep 17, 2026
Merged

ttncode merged 2 commits into
mainfrom
docs/runbooks-and-adrs

Conversation

@ttncode

@ttncode ttncode commented Sep 17, 2026

Copy link
Copy Markdown
Owner

What this changes

  • Runbooks rewritten as When / numbered Steps with exact commands / Verify / If it fails. first-project-walkthrough.md 351 → 162 lines; it installs scaffold on PATH (a symlink is unsupported).
  • Wrong runbook instructions corrected, for example: rotating a database password by editing .env alone locks the apps out (the images read it only on an empty volume), so the runbook now changes it inside the database first; ci-is-red described CI as one contract task per step (it runs ci-unit per config root); the provenance check compares files to the pinned commit rather than detecting upstream movement.
  • New runbooks, since none covered them: update-a-project.md (embeds the update diagram) and publish-a-project.md; both linked from docs/README.md.
  • ADRs: 10 of 24 had facts the code has moved past (e.g. three release assets, six reusable workflows, the optional release GitHub App). The original text stays; each fix is a dated > **Amended 2026-09-17.** note. ADR-0010 and ADR-0014 gain a "Superseded in part" status pointing at the ADRs that changed them.
  • docs/PROVENANCE.md: prose and three Notes cells corrected; parsed columns untouched.

How it was verified

  • Every runbook command, error string and function checked against scaffold, lib/*.sh, common/ and the reusable workflows; commands needing GitHub or Docker checked by --help and code, not run. An independent review re-checked them and found one dropped operator warning (edits to a deployed compose.yaml are overwritten by install.sh), now restored.
  • scripts/check-provenance.sh: 1 ok, 0 drifted. bats tests/documentation.bats 5/5. mise run test-unit 204/204. mise run lint clean.

Checklist

  • mise run lint passes
  • mise run test-runner passes — docs only; CI runs it
  • New behaviour has a test that fails without the change — docs only, no behaviour change
  • Docs that describe changed behaviour were updated in the same commit
  • No unrelated changes

@ttncode
ttncode merged commit 024a681 into main Sep 17, 2026
21 checks passed
@ttncode
ttncode deleted the docs/runbooks-and-adrs branch September 17, 2026 10:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant