pdurlej/platform

Fork 0

chore(governance): DeepSeek-findings remediation package (ADR-0006/0007 + REVIEW.md + DR runbook + recovery template + Pan Herbatka prep) #184

Merged

pdurlej merged 1 commit from claude/orders/codex-prep-deepseek-2026-05-11 into main

2026-05-11 21:53:25 +02:00

claude commented

2026-05-11 09:43:12 +02:00

Collaborator

Why this PR exists

DeepSeek-v4-Pro independent review of pdurlej/platform on 2026-05-11 (operator-shared via pi CLI) surfaced HIGH-severity governance gaps plus 5+ medium gaps. Operator's request: "chciałbym żebyś jak najwięcej przygotował ty po swojej stronie tak żeby już kodeks jak o pierwszej w nocy to rzuci okiem i wiedział dokładnie co ma robić."

This PR drafts the full remediation package. Codex reviews + force-pushes adjustments + operator approves.

What ships (14 files, +1351 / -53)

New ADRs

ADR-0006 — Single operator-facing status file discipline. Canonical: state/STATUS_NOW.md. Closes status file proliferation (DeepSeek HIGH finding).
ADR-0007 — Risk-proportional canary review tiers (Trivial/Lite/Full). Closes "PR #27 had 9 iterations" anti-pattern. 4-week trial 2026-05-11 → 2026-06-08.

New top-level files

REVIEW.md — Anthropic-pattern repo-specific reviewer instructions; highest-priority instruction layer. Cites ADR-0006/0007 + sensitive paths list + tier auto-detection rules.

New runbooks

runbooks/dr-restore-test.md — 3-tier DR test cadence (T1 weekly integrity / T2 monthly partial / T3 quarterly full). Closes 35-day stale-DR-test gap (DeepSeek HIGH finding).
runbooks/recovery-section-template.md — Template for filling ## How to recover section in all 80 module runbooks. 6 class variants (stateful DB / stateless / edge / AI runtime / observability / sunset).

New Codex prompt

prompts/codex-recovery-batch-2026-05-11.md — Codex batch-apply instructions for filling recovery sections across 80 modules. Lite-tier PRs, 5 modules each, 16 PRs total. Closes "65/80 modules with TODO recovery" gap (DeepSeek HIGH finding).

New state

state/pan-herbatka-day1-checklist.md — Handoff doc for future-me post-compaction. One-thread-per-repo discipline per operator's 2026-05-11 decision. Companion to Prof Kong's longer prompt for sibling-thread dispatch (which we are NOT doing).

Modified

state/STATUS_NOW.md — Full rewrite as canonical operator status (per ADR-0006). Includes Owner Action Board, recent lessons codified, wakeup cookbook.
AGENTS.md — Amendment under § Conventions adding ADR-0006 + ADR-0007 sections. PR size classes table preserved during ADR-0007 trial period.

Archived (with explanatory headers)

5 stale operator-facing status files moved to state/archive/ per ADR-0006:

BLOCKERS_FOR_OPERATOR.md → state/archive/2026-04-30-...
HANDOFF_SUMMARY.md → state/archive/2026-04-30-...
OPERATOR_ACTIONS.md → state/archive/2026-05-02-...
state/OPERATOR_INBOX.md → state/archive/2026-05-02-...
state/DECISION_REQUIRED.md → state/archive/2026-05-02-...

DeepSeek findings addressed

Finding	Severity	Addressed by	Closed?
Status file proliferation (3-5 competing files)	HIGH	ADR-0006 + archive moves + REVIEW.md rule 1 + AGENTS.md amendment	✅
65/80 runbooks have empty "How to recover"	HIGH	Recovery template + Codex batch-apply prompt	⏳ (Codex executes)
Backup/DR restore test 35 days stale	HIGH	DR restore test runbook (3-tier cadence)	✅ (cadence defined)
PR #27 had 9 iterations (canary scaling)	MEDIUM	ADR-0007 risk-proportional tiers	✅
docs/ci/ missing 4 files	(false positive)	Pan Herbatka verified files exist; check_docs_drift.py passes	✅ (verified false positive)
Pattern: REVIEW.md (Anthropic)	(community import)	REVIEW.md created	✅
Pattern: Risk-proportional review (Cloudflare)	(community import)	ADR-0007 created	✅
Pattern: Multi-repo separation	(community import)	Documented in ADR-0007 references for Phase 04+	⏳ (future)

What this PR does NOT do

Does NOT execute the recovery-batch (Codex does, ~16 PRs follow-up)
Does NOT enable auto-merge (per ADR-0019 which is still draft in Prof Kong's handoff bundle)
Does NOT spawn sibling Pan Herbatka thread (operator's 2026-05-11 decision: one thread per repo)
Does NOT change any module manifest, schema, or runtime behavior
Does NOT touch sacred paths

Out of scope

Phase 02 v2 cataloging (Codex Wave 3+)
Phase 03 platformctl plan/apply iteration (per Phase 3 ralph batch comments on #162-#167+#161)
Phase 04 observability + Phase 05 agent-execution (later)
Multi-repo separation (future Phase 04+ if validated)

Spec sources read

PLATFORM_CHARTER.md (sacred paths, RTO/RPO targets)
AGENTS.md (full ~1000 lines; specific § canary + identity discipline)
decisions/0001-canary-mandatory-pm-cadence.md (base for ADR-0007 extension)
decisions/0005-agent-coordination-lanes.md (reviewer identity discipline cited in REVIEW.md)
baseline/recovery/PROCEDURES.md (emergency restore — referenced from DR runbook)
runbooks/forgejo-actions-runner.md (referenced by REVIEW.md sensitive paths)
modules/forgejo/runbook.md + modules/postgres/runbook.md (sample to validate recovery template format)
Live Forgejo state: open PRs #157-#167, recent commits, canary workflow scaffold
Live check_docs_drift.py execution (validated DeepSeek's docs/ci/ claim as false positive)
DeepSeek-v4-Pro 2026-05-11 review (operator-shared via pi CLI; not in repo — context retained by claude in working memory)
Web search for community patterns (Cloudflare AI Code Review 2026-04, Anthropic Code Review docs, Spacelift IaC testing, agentpatterns.ai Committee Review)

Test plan

Operator readback: ADR-0006 + ADR-0007 — do these match operator's intuition about "too many status files" + "PR #27 9 iterations was wrong"?
Operator readback: REVIEW.md — are the severity definitions and skip rules correct for our repo?
Operator readback: runbooks/dr-restore-test.md — does the T1/T2/T3 cadence work with operator's calendar?
Operator readback: runbooks/recovery-section-template.md + prompts/codex-recovery-batch-2026-05-11.md — is the per-class variant correct?
Operator readback: state/pan-herbatka-day1-checklist.md — does this capture enough for post-compaction future-me?
Codex review at 01:00 CEST: structural correctness + cross-references valid
Operator merge or operator-override per ADR-0001 Rule 2
Post-merge: Codex iterates Phase 3 chain (#162-#167+#161) per ralph batch comments
Post-merge: Codex starts recovery-section-batch per prompts/codex-recovery-batch-2026-05-11.md
Trial period for ADR-0007: 4 weeks (2026-05-11 → 2026-06-08)

Tier classification (self-reported, per ADR-0007)

Full — touches:

2 new ADRs (auto-promote to Full)
REVIEW.md (sensitive path)
AGENTS.md (governance doc)
state/STATUS_NOW.md (canonical operator file per ADR-0006)
1351 LoC change >> 100 LoC threshold

Cannot self-assess as Trivial or Lite. Full canary 3+3 + operator-override per ADR-0001 Rule 2.

Cousin coordination

claude (Pan Herbatka — this thread): drafted everything; available for operator questions tomorrow
Codex: reviews at 01:00 CEST post-reset; expected force-push minor adjustments
DeepSeek-v4-Pro (8th cousin per draft ADR-0016): this PR is the response to his review; he may be re-invoked post-merge for verification
Prof Kong (other Claude thread for iskra-openclaw): unaffected — different repo

🍵 — "Spend more time with family while shipping at small-team velocity." Operator's North Star honored.

— Drafted by claude (Pan Herbatka) 2026-05-11
Dispatch: operator's "Lecę full" via 32% Anthropic budget
Source: DeepSeek-v4-Pro independent review 2026-05-11
Pattern sources: Anthropic Code Review + Cloudflare AI Code Review + Spacelift IaC + community homelab GitOps

Refs: DeepSeek-2026-05-11-review

Canary status: missing — Full tier per new ADR-0007 (touches 2 new ADRs + REVIEW.md + AGENTS.md + canonical operator status file). Fire canary 3+3 manually OR operator_override per ADR 0001 (operator dispatched this batch explicitly: "Lecę full"). ## Why this PR exists DeepSeek-v4-Pro independent review of `pdurlej/platform` on 2026-05-11 (operator-shared via pi CLI) surfaced HIGH-severity governance gaps plus 5+ medium gaps. Operator's request: "chciałbym żebyś jak najwięcej przygotował ty po swojej stronie tak żeby już kodeks jak o pierwszej w nocy to rzuci okiem i wiedział dokładnie co ma robić." This PR drafts the full remediation package. Codex reviews + force-pushes adjustments + operator approves. ## What ships (14 files, +1351 / -53) ### New ADRs - **ADR-0006** — Single operator-facing status file discipline. Canonical: `state/STATUS_NOW.md`. Closes status file proliferation (DeepSeek HIGH finding). - **ADR-0007** — Risk-proportional canary review tiers (Trivial/Lite/Full). Closes "PR #27 had 9 iterations" anti-pattern. 4-week trial 2026-05-11 → 2026-06-08. ### New top-level files - **`REVIEW.md`** — Anthropic-pattern repo-specific reviewer instructions; highest-priority instruction layer. Cites ADR-0006/0007 + sensitive paths list + tier auto-detection rules. ### New runbooks - **`runbooks/dr-restore-test.md`** — 3-tier DR test cadence (T1 weekly integrity / T2 monthly partial / T3 quarterly full). Closes 35-day stale-DR-test gap (DeepSeek HIGH finding). - **`runbooks/recovery-section-template.md`** — Template for filling `## How to recover` section in all 80 module runbooks. 6 class variants (stateful DB / stateless / edge / AI runtime / observability / sunset). ### New Codex prompt - **`prompts/codex-recovery-batch-2026-05-11.md`** — Codex batch-apply instructions for filling recovery sections across 80 modules. Lite-tier PRs, 5 modules each, 16 PRs total. Closes "65/80 modules with TODO recovery" gap (DeepSeek HIGH finding). ### New state - **`state/pan-herbatka-day1-checklist.md`** — Handoff doc for future-me post-compaction. One-thread-per-repo discipline per operator's 2026-05-11 decision. Companion to Prof Kong's longer prompt for sibling-thread dispatch (which we are NOT doing). ### Modified - **`state/STATUS_NOW.md`** — Full rewrite as canonical operator status (per ADR-0006). Includes Owner Action Board, recent lessons codified, wakeup cookbook. - **`AGENTS.md`** — Amendment under § Conventions adding ADR-0006 + ADR-0007 sections. PR size classes table preserved during ADR-0007 trial period. ### Archived (with explanatory headers) 5 stale operator-facing status files moved to `state/archive/` per ADR-0006: - `BLOCKERS_FOR_OPERATOR.md` → `state/archive/2026-04-30-...` - `HANDOFF_SUMMARY.md` → `state/archive/2026-04-30-...` - `OPERATOR_ACTIONS.md` → `state/archive/2026-05-02-...` - `state/OPERATOR_INBOX.md` → `state/archive/2026-05-02-...` - `state/DECISION_REQUIRED.md` → `state/archive/2026-05-02-...` ## DeepSeek findings addressed | Finding | Severity | Addressed by | Closed? | |---|---|---|---| | Status file proliferation (3-5 competing files) | HIGH | ADR-0006 + archive moves + REVIEW.md rule 1 + AGENTS.md amendment | ✅ | | 65/80 runbooks have empty "How to recover" | HIGH | Recovery template + Codex batch-apply prompt | ⏳ (Codex executes) | | Backup/DR restore test 35 days stale | HIGH | DR restore test runbook (3-tier cadence) | ✅ (cadence defined) | | PR #27 had 9 iterations (canary scaling) | MEDIUM | ADR-0007 risk-proportional tiers | ✅ | | docs/ci/ missing 4 files | (false positive) | Pan Herbatka verified files exist; check_docs_drift.py passes | ✅ (verified false positive) | | Pattern: REVIEW.md (Anthropic) | (community import) | REVIEW.md created | ✅ | | Pattern: Risk-proportional review (Cloudflare) | (community import) | ADR-0007 created | ✅ | | Pattern: Multi-repo separation | (community import) | Documented in ADR-0007 references for Phase 04+ | ⏳ (future) | ## What this PR does NOT do - Does NOT execute the recovery-batch (Codex does, ~16 PRs follow-up) - Does NOT enable auto-merge (per ADR-0019 which is still draft in Prof Kong's handoff bundle) - Does NOT spawn sibling Pan Herbatka thread (operator's 2026-05-11 decision: one thread per repo) - Does NOT change any module manifest, schema, or runtime behavior - Does NOT touch sacred paths ## Out of scope - Phase 02 v2 cataloging (Codex Wave 3+) - Phase 03 platformctl plan/apply iteration (per Phase 3 ralph batch comments on #162-#167+#161) - Phase 04 observability + Phase 05 agent-execution (later) - Multi-repo separation (future Phase 04+ if validated) ## Spec sources read - `PLATFORM_CHARTER.md` (sacred paths, RTO/RPO targets) - `AGENTS.md` (full ~1000 lines; specific § canary + identity discipline) - `decisions/0001-canary-mandatory-pm-cadence.md` (base for ADR-0007 extension) - `decisions/0005-agent-coordination-lanes.md` (reviewer identity discipline cited in REVIEW.md) - `baseline/recovery/PROCEDURES.md` (emergency restore — referenced from DR runbook) - `runbooks/forgejo-actions-runner.md` (referenced by REVIEW.md sensitive paths) - `modules/forgejo/runbook.md` + `modules/postgres/runbook.md` (sample to validate recovery template format) - Live Forgejo state: open PRs #157-#167, recent commits, canary workflow scaffold - Live `check_docs_drift.py` execution (validated DeepSeek's docs/ci/ claim as false positive) - DeepSeek-v4-Pro 2026-05-11 review (operator-shared via pi CLI; not in repo — context retained by claude in working memory) - Web search for community patterns (Cloudflare AI Code Review 2026-04, Anthropic Code Review docs, Spacelift IaC testing, agentpatterns.ai Committee Review) ## Test plan - [ ] Operator readback: ADR-0006 + ADR-0007 — do these match operator's intuition about "too many status files" + "PR #27 9 iterations was wrong"? - [ ] Operator readback: `REVIEW.md` — are the severity definitions and skip rules correct for our repo? - [ ] Operator readback: `runbooks/dr-restore-test.md` — does the T1/T2/T3 cadence work with operator's calendar? - [ ] Operator readback: `runbooks/recovery-section-template.md` + `prompts/codex-recovery-batch-2026-05-11.md` — is the per-class variant correct? - [ ] Operator readback: `state/pan-herbatka-day1-checklist.md` — does this capture enough for post-compaction future-me? - [ ] Codex review at 01:00 CEST: structural correctness + cross-references valid - [ ] Operator merge or operator-override per ADR-0001 Rule 2 - [ ] Post-merge: Codex iterates Phase 3 chain (#162-#167+#161) per ralph batch comments - [ ] Post-merge: Codex starts recovery-section-batch per `prompts/codex-recovery-batch-2026-05-11.md` - [ ] Trial period for ADR-0007: 4 weeks (2026-05-11 → 2026-06-08) ## Tier classification (self-reported, per ADR-0007) **Full** — touches: - 2 new ADRs (auto-promote to Full) - `REVIEW.md` (sensitive path) - `AGENTS.md` (governance doc) - `state/STATUS_NOW.md` (canonical operator file per ADR-0006) - 1351 LoC change >> 100 LoC threshold Cannot self-assess as Trivial or Lite. Full canary 3+3 + operator-override per ADR-0001 Rule 2. ## Cousin coordination - **claude (Pan Herbatka — this thread)**: drafted everything; available for operator questions tomorrow - **Codex**: reviews at 01:00 CEST post-reset; expected force-push minor adjustments - **DeepSeek-v4-Pro (8th cousin per draft ADR-0016)**: this PR is the response to his review; he may be re-invoked post-merge for verification - **Prof Kong (other Claude thread for iskra-openclaw)**: unaffected — different repo 🍵 — "Spend more time with family while shipping at small-team velocity." Operator's North Star honored. — Drafted by claude (Pan Herbatka) 2026-05-11 Dispatch: operator's "Lecę full" via 32% Anthropic budget Source: DeepSeek-v4-Pro independent review 2026-05-11 Pattern sources: Anthropic Code Review + Cloudflare AI Code Review + Spacelift IaC + community homelab GitOps Refs: DeepSeek-2026-05-11-review

claude added 1 commit

2026-05-11 09:43:12 +02:00

chore(governance): DeepSeek-findings remediation package

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

Details

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

Details

d8a3c0e981

Pre-Codex-01:00 prep batch. Addresses DeepSeek-v4-Pro independent review
(2026-05-11) findings + imports community patterns identified via web search.

Per operator's "lecę full" dispatch + 32% Anthropic budget allocation.

## ADRs

- ADR-0006: single operator-facing status file discipline
  Addresses DeepSeek HIGH-severity finding "status file proliferation".
  Canonical: state/STATUS_NOW.md. Other operator-facing status files
  archived to state/archive/ with explanatory headers.

- ADR-0007: risk-proportional canary review tiers
  Trivial / Lite / Full based on LoC + sensitive-paths + labels.
  Addresses DeepSeek anti-pattern citation of "PR #27 9 iterations".
  4-week trial period 2026-05-11 → 2026-06-08.

## New files

- REVIEW.md (Anthropic pattern) — repo-specific reviewer rules,
  highest-priority instruction layer. Cites ADR-0006/0007.

- runbooks/dr-restore-test.md — 3-tier DR test cadence:
  T1 weekly integrity / T2 monthly partial / T3 quarterly full drill.
  Closes 35-day stale-test gap (DeepSeek HIGH-severity finding).

- runbooks/recovery-section-template.md — template for filling
  "How to recover" sections in all 80 module runbooks. Six class
  variants (stateful DB / stateless / edge / AI runtime / observability
  / sunset).

- prompts/codex-recovery-batch-2026-05-11.md — Codex batch-apply
  prompt for filling recovery sections across 80 modules. Lite-tier
  PRs, 5 modules each, 16 PRs total.

- state/pan-herbatka-day1-checklist.md — handoff doc for future-me
  post-compaction. One-thread-per-repo discipline (operator's 2026-05-11
  decision). ~150-line concise version of Prof Kong's prompt.

## Modified files

- AGENTS.md: amendment for ADR-0006 + ADR-0007 sections under § Conventions
- state/STATUS_NOW.md: full rewrite as canonical per ADR-0006

## Moves (with archive headers)

5 stale operator-facing files moved to state/archive/ per ADR-0006:
- BLOCKERS_FOR_OPERATOR.md → state/archive/2026-04-30-...
- HANDOFF_SUMMARY.md → state/archive/2026-04-30-...
- OPERATOR_ACTIONS.md → state/archive/2026-05-02-...
- state/OPERATOR_INBOX.md → state/archive/2026-05-02-...
- state/DECISION_REQUIRED.md → state/archive/2026-05-02-... (was untracked)

## Tier (per ADR-0007 self-reference)

**Full** — touches 2 new ADRs + REVIEW.md + AGENTS.md + state/STATUS_NOW.md
(canonical operator file). LoC change 1351. Cannot self-assess Trivial/Lite.

Codex review at 01:00 CEST per operator dispatch.

Refs: DeepSeek-v4-Pro-review-2026-05-11

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

claude added the

proposed

label

2026-05-11 09:43:13 +02:00