Skip to content

Commit 1825f1d

Browse files
committed
docs(design): fix Claude-bot follow-ups from #701 review
Three issues from the @claude review of PR #701: 1. **Anchor link target now resolves**. The accepted gemini suggestion added `[follow-ups](#out-of-scope-follow-ups)` to the P1 status-table row, but the target was a plain-text paragraph — GitHub only auto-generates anchors for headings, so the link silently scrolled to the top of the document. Promoted "Out-of-scope follow-ups" to a `### ` heading and moved the parenthetical caption onto its own italicised line below it. Anchor `#out-of-scope-follow-ups` now actually resolves. 2. **Stale subsection pointer in safety-net doc**. The 2026_04_28_proposed_admin_delete_bucket_safety_net.md Background section pointed at "Out-of-scope follow-ups" for the TOCTOU description, but after the rename the TOCTOU is no longer in that section — it's resolved (described in the implementation-status block at the top of the implemented doc, line 23). Updated the prose to say "resolved by this design and recorded in the implementation-status block of …" so the cross-link points where the TOCTOU is actually discussed in the renamed doc. 3. **Stale link description in admin_deployment.md**. The final cross-references list called the design doc's third bullet "outstanding items" — that is the `_partial_`-era wording. Renamed to "out-of-scope follow-ups" to match the promoted doc's actual section heading. Also reordered the implementation-status block: TOCTOU resolution paragraph now precedes the Out-of-scope section so the doc reads "what shipped → how the late-breaking issue was fixed → what was deliberately deferred". Previously the TOCTOU paragraph sat after the deferred-items bullet list which read awkwardly. No content changes other than the three fixes above and the section reorder.
1 parent e2ed240 commit 1825f1d

3 files changed

Lines changed: 10 additions & 8 deletions

File tree

docs/admin_deployment.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -403,7 +403,7 @@ mean the cluster has lost quorum.
403403
- [`docs/admin.md`](admin.md) — per-flag configuration reference,
404404
audit log shapes, troubleshooting catalogue.
405405
- [`docs/design/2026_04_24_implemented_admin_dashboard.md`](design/2026_04_24_implemented_admin_dashboard.md)
406-
design rationale, acceptance criteria, outstanding items.
406+
design rationale, acceptance criteria, out-of-scope follow-ups.
407407
- [`scripts/rolling-update.sh`](../scripts/rolling-update.sh)
408408
the rollout driver this doc references throughout.
409409
- [`scripts/rolling-update.env.example`](../scripts/rolling-update.env.example)

docs/design/2026_04_24_implemented_admin_dashboard.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,16 @@
1414
| **P3** — React SPA + embed | ✅ shipped | #649, #650 |
1515
| **P4** — TLS, read-only role, CSRF, `docs/admin.md`, deployment runbook + `scripts/rolling-update.sh` admin support | ✅ shipped | TLS / role / CSRF live in P1; operator doc + runbook + script wiring in #674 / #669 / #678 |
1616

17-
Out-of-scope follow-ups (recorded so future readers know what was deliberately deferred):
17+
The AdminDeleteBucket TOCTOU is fully resolved: see [`2026_04_28_proposed_admin_delete_bucket_safety_net.md`](2026_04_28_proposed_admin_delete_bucket_safety_net.md) for the safety-net design and [`docs/admin_deployment.md`](../admin_deployment.md) §4.6 for the operator-side contract (a `PutObject` 200-OK landing during the race window can be swept by the concurrent admin delete; pause writes before delete to retain in-flight writes).
18+
19+
### Out-of-scope follow-ups
20+
21+
_Recorded so future readers know what was deliberately deferred._
1822

1923
- **AdminForward acceptance criterion 5** — rolling-upgrade compatibility flag (`admin.leader_forward_v2`). Deferred at design time behind a cluster-version bump that does not exist yet; not blocking dashboard usability today because every node forwards through the same `pb.AdminOperation` enum.
2024
- **S3 object browser** — explicitly called out as "next phase" in §2.2 Non-goals; no work item yet.
2125
- **Operator-visible TLS cert reload** — out of scope; restart-to-rotate is the documented model in `docs/admin.md`.
2226

23-
The AdminDeleteBucket TOCTOU is fully resolved: see [`2026_04_28_proposed_admin_delete_bucket_safety_net.md`](2026_04_28_proposed_admin_delete_bucket_safety_net.md) for the safety-net design and [`docs/admin_deployment.md`](../admin_deployment.md) §4.6 for the operator-side contract (a `PutObject` 200-OK landing during the race window can be swept by the concurrent admin delete; pause writes before delete to retain in-flight writes).
24-
2527
---
2628

2729
## 1. Background and Motivation

docs/design/2026_04_28_proposed_admin_delete_bucket_safety_net.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
## 1. Background
88

99
`AdminDeleteBucket` and the SigV4 `s3.go:deleteBucket` share a known
10-
TOCTOU race documented in
11-
[`docs/design/2026_04_24_implemented_admin_dashboard.md`](2026_04_24_implemented_admin_dashboard.md)
12-
under Out-of-scope follow-ups. coderabbitai 🔴/🟠 flagged it during PR
13-
#669 review.
10+
TOCTOU race resolved by this design and recorded in the
11+
implementation-status block of
12+
[`docs/design/2026_04_24_implemented_admin_dashboard.md`](2026_04_24_implemented_admin_dashboard.md).
13+
coderabbitai 🔴/🟠 flagged it during PR #669 review.
1414

1515
The current shape:
1616

0 commit comments

Comments
 (0)