[freeqaz]

Problem

The 2026-10-24 notice "OpenShell Sandbox policy settings are checked at startup" (#3499) says that, apart from a slash-only readOnly path, none of the newly refused settings could deploy an Agent. That is wrong for an unknown policy.filesystem key. Before #3499, filesystemPolicy read only readOnly, readWrite and includeWorkdir and ignored every other key. So a typo such as {readOnly: [...], readwrite: [/data]} started and deployed Agents. After the upgrade, the schema's additionalProperties: false refuses that key at startup, which stops a working controller from starting. The notice told that operator they were not affected.

Change

• The notice's "Apart from" exception now also names an unknown policy.filesystem key such as a readwrite typo, which earlier builds ignored.
• breaking-changes.md was at 2492 of its 2500 words. Following docs: align startup, breaking changes and backend examples with credential proxy #3265's pattern, its 2026-10-22 and 2026-10-16 notices move unchanged to a new page, breaking-changes-before-2026-10-23.md. The intro link list on every notice page now includes the new page, and docs/docs.json gets a nav entry for it.
• No other page links to an anchor of the moved notices.

Verification

• node scripts/docs-site/word-count.mjs: passes. breaking-changes.md is now 2110 words, and the other notice pages are all under 2420.
• node scripts/docs-site/build.mjs --check: 291 pages and 4583 links validated.
• node scripts/check-specs.mjs: passes.
• node --test tests/docs/docs-length.test.mjs tests/docs/docs-site.test.mjs: 20/20 pass.

Risks

Docs only. Bookmarked links to the two moved notices on breaking-changes.md now land at the top of the page, and the intro links to the new page.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

This PR identifies unknown filesystem keys as an upgrade-breaking setting and moves two older notices into a linked archive page.

Example: An Installation contains policy.filesystem.readwrite: ["/data"].

• Before: The notice incorrectly implies that this Installation could never have deployed an Agent.
• After: The notice explains that earlier builds ignored the unknown key, so a previously working Installation can fail startup after upgrading.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, source-backed documentation correction with passing exact-head checks and no actionable findings; rendered output was not independently inspected.
Proof confidence	🐚 platinum hermit (4/6)	Documentation-only changes were checked against the current schema, predecessor implementation, existing integration scenario, and introduced diff; no runtime proof is required.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Operators with an ignored filesystem-key typo are incorrectly told that their previously working Installation is outside the upgrade's affected population.
Reason: The collaborator-authored direction fixes a verified documentation error and uses the existing archive convention to stay within the page budget.

Merge readiness

✅ Ready for maintainer review

Keep this PR open for maintainer triage: it corrects inaccurate upgrade guidance still present on main, with no actionable findings in the introduced changes.

Priority: P3
Reviewed head: cff0cd1e4ce64da9ac1aced73e35d0e8fd8c3f66

Before merge

None.

Findings

None.

Agent review details

How this fits together

The deployment guides help operators interpret Installation validation failures and prepare upgrades; the documentation navigation and archive links expose older notices.

flowchart TB
  A[Operator planning upgrade] --> B[Breaking changes guide]
  B --> C[Current startup notice]
  B --> D[Dated archive page]
  E[Documentation navigation] --> B
  E --> D

Loading

Technical review

Best possible solution:

Land the focused notice correction and established archive rotation without changing runtime behavior.

Do we have a high-confidence way to reproduce the issue?

Source and history establish the documentation error: unknown filesystem keys were ignored before the strict startup schema, while main still says those settings could not deploy.

Is this the best way to solve the issue?

The patch corrects the existing notice and follows the established date-based archive convention while preserving the moved notice bodies.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 7f966e976c08.

Provenance checked

• Startup notice affected population changes intended behavior with a stated reason (4a03195: Move invalid Sandbox policy settings to startup validation and explain the resulting upgrade refusal; the affected-population statement overlooked formerly ignored keys.)
• Date-based notice archives keeps the original intent (c742f82: Move older notices unchanged into date-based pages so current notices remain within the documentation word limit.)

Security

None.

Evidence

What I checked:

• Current main still needs the correction: Main still excludes unknown filesystem keys from the settings that could previously deploy, despite listing those keys among startup refusals. (docs/guides/deploy/breaking-changes.md:71, 7f966e976c08)
• Correction matches implementation history: The merged startup-validation change adds a filesystem schema with additionalProperties: false; its predecessor's filesystemPolicy reads only readOnly, readWrite and includeWorkdir. The existing integration scenario explicitly expects readwrite to produce UNKNOWN_FIELD. (apps/controller/src/drivers/sandbox/openshell.ts:2348, 4a03195d9f34)
• Archive content and navigation preserved: The pinned introduced diff moves both notice bodies unchanged, adds the new page to navigation, and links it from every existing notice page; the repository search found no incoming links to the moved headings. (docs/guides/deploy/breaking-changes-before-2026-10-23.md:10, cff0cd1e4ce6)
• Established archive convention and accepted bookmark tradeoff: The date-based rotation follows docs(deploy): split the breaking-changes archive to make room #2276 and docs: align startup, breaking changes and backend examples with credential proxy #3265. The collaborator-authored PR explicitly accepts that external bookmarks to moved notices land at the original page top. The longer notice pages retain a coherent dated-upgrade scope. (docs/guides/deploy/breaking-changes-archive.md:10, c742f82db78b)
• Exact-head checks pass: CI Required and Suite Audit and Static Checks succeeded for the reviewed head; no failing check was reported. No build, test, formatter, or target code was run during this review. (cff0cd1e4ce6)
• Repository policy applied: Read the complete root instructions, technical-writing guidance, and architecture implementation status. No nested documentation AGENTS.md, maintainer-notes directory, or pr-simplify skill was present. The checkout remains clean; no additional reviewer or autoreview helper ran. (AGENTS.md, cff0cd1e4ce6)

Likely related people:

• Free Wortley: Raw commit 4a03195 adds docs/guides/deploy/breaking-changes.md:30 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 4a03195d9f34; files: docs/guides/deploy/breaking-changes.md)

Labels

Label changes:

• add P3: This is a source-backed documentation correction and archive maintenance with no runtime change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: This is a source-backed documentation correction and archive maintenance with no runtime change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 24, 2026, 4:07 PM ET / 20:07 UTC.