pdurlej/platform

Fork 0

docs(runbooks): add template and pilot modules #784

Merged

pdurlej merged 2 commits from codex/issues/770-runbook-template into main

2026-06-17 23:10:53 +02:00

codex commented

2026-06-10 23:51:54 +02:00

Collaborator

Canary status: missing - fire canary 3+3 manually before merge

Canary Context Pack

Product story

Future agents should be able to open a module runbook and find the same operational shape every time: purpose, runtime location, health/smoke, restore boundary, rollback, known gotchas, recovery, related modules, and owner.

What changed

Added docs/templates/runbook-template.md.
Applied the template to three pilot modules only:
- honcho-api as core/platform active service.
- np-memos as public user-app with stateful/private data concerns.
- agaria-api as custom-prefix parked module where the correct action is not reactivation.

Why it changed

Issue #770 identified runbook format drift as recurring agent-token burn. This gives a reusable target and three examples across different recovery postures.

Files touched

docs/templates/runbook-template.md
modules/honcho-api/runbook.md
modules/np-memos/runbook.md
modules/agaria-api/runbook.md

Relevant context

Issue #770 spec sources: honcho-api, traefik, several existing runbooks, AGENTS.md, and PLATFORM_CHARTER.md repo layout.
AntiGravity/Gemini readability pass returned PASS and suggested tightening parked-module commands. Applied: agaria-api smoke is N/A while parked, container check handles absence, and template now tells authors to prefer no-op/read-only checks for parked/sunset modules.

Runtime evidence

Docs-only. No live runtime access and no host mutation.

Known constraints

Follow-up issues for remaining modules were not filed because the batch assumptions explicitly keep Forgejo/API mutation out of scope beyond opening this PR.
This PR is a template and three pilots, not a repo-wide runbook migration.

Explicit out-of-scope

No runtime commands, restarts, deploys, restore, or smoke execution.
No broad runbook migration beyond the three pilot modules.
No Forgejo follow-up issue creation in this batch.

Requested decision

Approve the template shape and three pilot conversions.

Merge blockers

Template missing required sections.
Pilot runbooks encouraging destructive restore without operator approval.
agaria-api parked runbook encouraging reactivation or smoke as default.

Spec sources read

Issue #770 body from Forgejo.
modules/honcho-api/runbook.md and modules/traefik/runbook.md as reference runbooks.
modules/forgejo/runbook.md, modules/np-memos/runbook.md, modules/agaria-api/runbook.md for pattern diversity.
modules/honcho-api/module.yaml, modules/np-memos/module.yaml, modules/agaria-api/module.yaml for runtime/lifecycle/statefulness fields.
PLATFORM_CHARTER.md § repo layout.

Verification

agy --sandbox ... AntiGravity/Gemini readability pass -> PASS; tightening suggestions applied.
rg -n "^## (Purpose|Runtime Location|Healthcheck & Smoke|Backup & Restore|Rollback Procedure|Known Issues / Gotchas|Recovery Procedures|Related Modules|Owner)$" docs/templates/runbook-template.md modules/honcho-api/runbook.md modules/np-memos/runbook.md modules/agaria-api/runbook.md -> all sections present in all four files.
git diff --check origin/main...HEAD -> passed.

Closes #770

Canary status: missing - fire canary 3+3 manually before merge ## Canary Context Pack ### Product story Future agents should be able to open a module runbook and find the same operational shape every time: purpose, runtime location, health/smoke, restore boundary, rollback, known gotchas, recovery, related modules, and owner. ### What changed - Added `docs/templates/runbook-template.md`. - Applied the template to three pilot modules only: - `honcho-api` as core/platform active service. - `np-memos` as public user-app with stateful/private data concerns. - `agaria-api` as custom-prefix parked module where the correct action is not reactivation. ### Why it changed Issue #770 identified runbook format drift as recurring agent-token burn. This gives a reusable target and three examples across different recovery postures. ### Files touched - `docs/templates/runbook-template.md` - `modules/honcho-api/runbook.md` - `modules/np-memos/runbook.md` - `modules/agaria-api/runbook.md` ### Relevant context - Issue #770 spec sources: `honcho-api`, `traefik`, several existing runbooks, `AGENTS.md`, and `PLATFORM_CHARTER.md` repo layout. - AntiGravity/Gemini readability pass returned PASS and suggested tightening parked-module commands. Applied: `agaria-api` smoke is N/A while parked, container check handles absence, and template now tells authors to prefer no-op/read-only checks for parked/sunset modules. ### Runtime evidence Docs-only. No live runtime access and no host mutation. ### Known constraints - Follow-up issues for remaining modules were not filed because the batch assumptions explicitly keep Forgejo/API mutation out of scope beyond opening this PR. - This PR is a template and three pilots, not a repo-wide runbook migration. ### Explicit out-of-scope - No runtime commands, restarts, deploys, restore, or smoke execution. - No broad runbook migration beyond the three pilot modules. - No Forgejo follow-up issue creation in this batch. ### Requested decision Approve the template shape and three pilot conversions. ### Merge blockers - Template missing required sections. - Pilot runbooks encouraging destructive restore without operator approval. - `agaria-api` parked runbook encouraging reactivation or smoke as default. ## Spec sources read - Issue #770 body from Forgejo. - `modules/honcho-api/runbook.md` and `modules/traefik/runbook.md` as reference runbooks. - `modules/forgejo/runbook.md`, `modules/np-memos/runbook.md`, `modules/agaria-api/runbook.md` for pattern diversity. - `modules/honcho-api/module.yaml`, `modules/np-memos/module.yaml`, `modules/agaria-api/module.yaml` for runtime/lifecycle/statefulness fields. - `PLATFORM_CHARTER.md` § repo layout. ## Verification - `agy --sandbox ...` AntiGravity/Gemini readability pass -> PASS; tightening suggestions applied. - `rg -n "^## (Purpose|Runtime Location|Healthcheck & Smoke|Backup & Restore|Rollback Procedure|Known Issues / Gotchas|Recovery Procedures|Related Modules|Owner)$" docs/templates/runbook-template.md modules/honcho-api/runbook.md modules/np-memos/runbook.md modules/agaria-api/runbook.md` -> all sections present in all four files. - `git diff --check origin/main...HEAD` -> passed. Closes #770

codex added 1 commit

2026-06-10 23:51:54 +02:00

docs(runbooks): add template and pilot modules

base-is-main / guard (pull_request) Successful in 2s

Details

canary-required / collect-diff (pull_request) Successful in 5s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 5s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 5s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 20s

Details

canary-required / canary (pull_request) Successful in 13s

Details

patchwarden-client-dry-run / dry-run (pull_request) Failing after 18s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 2m53s

Details

10bd2d4e3b

patchwarden commented

2026-06-11 00:18:16 +02:00

First-time contributor

Patchwarden PR sanity

Status: eligible_sanity_clean
PR: 784
Commit: 26c2d3eb7ea58dd0e51f72ccd9f54604d930d183
Security-sensitive label: missing
Authority: advisory model review plus deterministic blockers only
3+3 canary: still alive; this does not replace it

Deterministic findings

No deterministic findings.

Model reviewers

`global-glm` / `glm-5.1:cloud`

Status: ok
Verdict: OK
Findings: none

`global-deepseek` / `deepseek-v4-pro:cloud`

Status: ok
Verdict: OK
Findings: none

`redteam` / `kimi-k2.6:cloud`

Status: ok
Verdict: OK
Findings: none

Policy notes

GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot.
Optional red-team model is enabled only when PLATFORMCTL_PR_SANITY_REDTEAM_MODEL is configured.
Auto-merge is not enabled here.

# Patchwarden PR sanity - Status: `eligible_sanity_clean` - PR: `784` - Commit: `26c2d3eb7ea58dd0e51f72ccd9f54604d930d183` - Security-sensitive label: `missing` - Authority: advisory model review plus deterministic blockers only - 3+3 canary: still alive; this does not replace it ## Deterministic findings No deterministic findings. ## Model reviewers ### `global-glm` / `glm-5.1:cloud` - Status: `ok` - Verdict: `OK` - Findings: none ### `global-deepseek` / `deepseek-v4-pro:cloud` - Status: `ok` - Verdict: `OK` - Findings: none ### `redteam` / `kimi-k2.6:cloud` - Status: `ok` - Verdict: `OK` - Findings: none ## Policy notes - GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot. - Optional red-team model is enabled only when `PLATFORMCTL_PR_SANITY_REDTEAM_MODEL` is configured. - Auto-merge is not enabled here.

ollama added 1 commit

2026-06-11 00:20:29 +02:00

Merge remote-tracking branch 'origin/main' into codex/issues/770-runbook-template-refresh

canary-required / collect-diff (pull_request) Successful in 5s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 20s

Details

canary-required / canary (pull_request) Successful in 13s

Details

base-is-main / guard (pull_request) Successful in 2s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / sanity (pull_request) Failing after 1m56s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

patchwarden-client-dry-run / dry-run (pull_request) Failing after 20s

Details

26c2d3eb7e

codex referenced this pull request

2026-06-11 00:52:42 +02:00

ci(patchwarden): soft-fail advisory review failures #789

codex added the

labels

2026-06-11 08:14:24 +02:00

pdurlej commented

2026-06-17 23:10:39 +02:00

Owner

operator_override / PR-zero queue collapse evidence for #784.

I rechecked the docs-only runbook template PR after the current main merges:

git diff --check origin/main...HEAD passed.
Secret-pattern scan over the four touched runbook/template files returned no findings.
All required template sections are present in the template and three pilot runbooks.
Parked agaria-api remains read-only/no-op by default; no reactivation/restart path is introduced.

This is aligned with the live queue-collapse scope and safe to merge despite pending/stale CI checks.

operator_override / PR-zero queue collapse evidence for #784. I rechecked the docs-only runbook template PR after the current main merges: - `git diff --check origin/main...HEAD` passed. - Secret-pattern scan over the four touched runbook/template files returned no findings. - All required template sections are present in the template and three pilot runbooks. - Parked `agaria-api` remains read-only/no-op by default; no reactivation/restart path is introduced. This is aligned with the live queue-collapse scope and safe to merge despite pending/stale CI checks.

pdurlej merged commit d7acd102b8 into main

2026-06-17 23:10:53 +02:00

pdurlej referenced this pull request from a commit

2026-06-17 23:10:54 +02:00

Merge pull request #784 from codex/issues/770-runbook-template