docs: enforce current documentation lifecycle - #1107
Conversation
|
🦞👀 Pull request received. I will update this pull request when review starts. |
b5b6176 to
f2715f1
Compare
clawsweeper
Bot
added
P3
|
Codex review: needs maintainer review before merge. Reviewed August 10, 2026, 3:40 PM ET / 19:40 UTC. ClawSweeper reviewWhat this changesThis PR makes a documentation lifecycle manifest control generated-site discovery, labels retained historical pages as noncanonical, and checks dashboard-health documentation against runtime constants and fields. Merge readinessKeep open: current main lacks this lifecycle manifest and its generator/checker integration, while the final head resolves the prior field-contract finding and has sufficient exact-head behavior proof. No actionable patch defect was found; this remains a draft awaiting normal maintainer review. Priority: P2 Review scores
Verification
How this fits togetherThe documentation generator turns repository Markdown and a lifecycle manifest into the public site’s navigation, sitemap, and agent-facing index. The documentation checker validates those classifications and selected dashboard-health claims against the runtime contract. flowchart LR
A[Repository documentation] --> B[Lifecycle manifest]
B --> C[Documentation generator]
C --> D[Navigation sitemap and agent index]
A --> E[Documentation checker]
F[Dashboard health contract] --> E
E --> G[Drift findings]
Before merge
Agent review detailsSecurityNone. Review metrics
Root-cause clusterRelationship: Members:
Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything. Merge-risk optionsMaintainer options:
Technical reviewBest possible solution: After confirming the manifest’s canonical set, land this focused lifecycle foundation first, then retarget the dependent operator-contract work in #1108. Do we have a high-confidence way to reproduce the issue? Not applicable: this is a documentation and generator change, and the PR provides an exact-head generated-output proof rather than a bug reproduction. Is this the best way to solve the issue? Yes: one manifest drives canonical discovery while retained evidence pages stay reachable but visibly noncanonical, and the checker guards both lifecycle and health-contract drift. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against e13791786799. LabelsLabel changes:
Label justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (5 earlier review cycles)
|
|
@clawsweeper review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
clawsweeper
Bot
added
merge-risk: 🚨 automation
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
2c5e8ed to
3df1b25
Compare
clawsweeper
Bot
added
status: 📣 needs proof
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
clawsweeper
Bot
removed
the
status: 📣 needs proof
clawsweeper
Bot
added
proof: sufficient
|
@clawsweeper re-review |
|
🦞🧹 I asked ClawSweeper to review this item again. Re-review progress:
|
clawsweeper
Bot
added
rating: 🐚 platinum hermit
1 participant
Summary
What Problem This Solves
The CSW-122 audit found that the generated site's
llms.txtcalled immutable proof and an unapproved queue-split proposal “Canonical documentation.” Those pages were also rendered without lifecycle warnings. Separately, the active dashboard runbook still said every queued run older than 30 minutes degrades health, while #1101 excludes runs older than 24 hours as separately reported zombies.These conflicts can make agents follow historical or proposed material and can make operators misread a healthy dashboard snapshot.
Why This Change Was Made
config/documentation-site.jsonis now the exhaustive lifecycle source for the public docs build. The generator derives navigation, search, sitemap, andllms.txtfrom the active allowlist. Historical proof, the historical containment handoff, and the unapproved queue-split proposal keep their stable generated URLs, but receive visible lifecycle banners,noindex, follow, and no canonical discovery entry.check:docsrejects unclassified or multiply classified pages and ties the documented operational-health thresholds/fields todashboard/operational-health.ts.User Impact
Readers and agents see only current documentation in canonical discovery. Preserved evidence remains linkable but cannot be mistaken for current operator guidance. Dashboard operators now see the exact 30-minute-to-24-hour queue window, >24-hour zombie behavior, approval-gated counters, and 150-minute running threshold.
Validation
node --test test/check-docs.test.ts test/docs-site-theme.test.ts— 17/17 passedpnpm run check:docs— passedpnpm run check:limits— passedpnpm run build:all— passedpnpm run check:active-surface— passedpnpm run check:dashboard-queue-boundary— passedoxfmt --check— passedgit diff --check— passedorigin/main— no actionable findingsreview --local-rangeagainstorigin/main—keep_open, high confidence, no GitHub mutationReal Behavior Proof
Claim: The real generated documentation output preserves non-current pages while excluding them from canonical discovery, labels them visibly and with
noindex, and retains active current pages. The health documentation remains tied to the runtime constants and public field names.Exercised surface: Exact pushed head
f6fcd47d3736ffcbf527680a17dfdfd9a883d536; the production docs generator; Pages path trigger; generated navigation, sitemap,llms.txt, proposal/historical/proof HTML;check:docs; focused checker/site tests.Scenario: A clean GitHub clone of the pushed branch was built inside Docker-backed Crabbox. The proof asserted that
live-dashboard.htmlremains canonical; queue split, containment history, and proof URLs are absent from canonical discovery; preserved pages containnoindex, followand lifecycle banners; all focused negative and positive tests pass.Command/environment: Crabbox
0.40.0, explicit repository-requiredprovider=local-container, imagenode:24-bookworm,--no-hydrate --no-sync; the script cloned the exact pushed public branch because two normal sync attempts failed before execution with rsync protocol code 12.Observed result:
CSW122_PR1_HEAD=f6fcd47d3736ffcbf527680a17dfdfd9a883d536, 17/17 tests passed,Documentation checks passed, manifest path trigger present,CSW122_PR1_PROOF=PASS, exit 0.Artifact/trace: Lease
cbx_cf906987454d(pearl-hermit), providerlocal-container, imagenode:24-bookworm,runStatus=succeeded, command 18.302s, lease stopped. Local harness:C:\clawsweeper-work\notes\csw-122-pr1-proof.sh.Review disposition: Accepted the Pages-trigger finding, the inclusive 30/150-minute wording finding, the request to pin
oldest_approval_gated_minutes, and the request to bind all four documented health fields to the exported runtime type with a removed-field negative test. All are implemented at this head; no finding was rejected.Limits: This proves exact-head generation and lifecycle/contract assertions in a real Linux container. It does not deploy the site, mutate Cloudflare, change runtime health classification, or test search-engine recrawl timing.
OpenClaw Bay Impact
No Bay runtime, data contract, artwork, or controls change. The dashboard documentation now explains status fields already emitted by #1101. Bay remains observer-only.
Risks and Rollback
Non-goals
Stack / Order
This is PR 1 of the CSW-122 remediation. PR 2 will stack on this lifecycle manifest and will avoid the current #1105 limits/scheduler/target-dispatcher overlap. Merge this PR first.
Related