Skip to content

docs: fix all STE prose lint errors across the docs tree - #1047

Merged
0chroma merged 2 commits into
mainfrom
docs/ste-prose-lint
Jul 29, 2026
Merged

docs: fix all STE prose lint errors across the docs tree#1047
0chroma merged 2 commits into
mainfrom
docs/ste-prose-lint

Conversation

@0chroma

@0chroma 0chroma commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Summary

Why use many word when few word do trick?

Ran Vale with the ASD-STE100 ruleset against every markdown file in docs/. Fixed all 101 error-level violations across 24 files, then fixed all 37 em-dash warnings (en dashes in numeric ranges replaced with ASCII hyphens). Vale now reports 0 errors and 0 warnings.

What changed

Rule Fix Count
Contractions Expanded to full forms (don't to do not, can't to cannot, etc.) 15
BannedWords demonstrates to shows, begins to starts, additionally to also, ensure to make sure, acquire/obtain to get, begin to start 71
Nominalization Rephrased provide X patterns to plain verbs (define, produce, support) 8
MarketingAdjectives Removed seamlessly, battle-tested (to mature/tested), robust (to reliable) 6
PhrasalVerbs tear down to remove 1
EmDashes Replaced en dashes in numeric ranges with ASCII hyphens 37

Files touched

24 files across docs/concepts/, docs/guide/, docs/reference/, docs/internal/, docs/ci-strategy.md, docs/specs/, and docs/spikes/.

Verification

Ran Vale with the ASD-STE100 ruleset after all fixes. Result: 0 errors, 0 warnings.

Note

Fix STE prose lint errors across the docs tree

Applies Simplified Technical English (STE) lint fixes across all documentation. Changes are style-only with no semantic or technical content altered.

  • Expands contractions to formal equivalents (e.g. can'tcannot, don'tdo not)
  • Replaces en-dash ranges with hyphen-minus (e.g. 1–21-2) throughout specs and guides
  • Replaces informal verbs with STE-preferred alternatives (e.g. demonstratesshows, ensuresmakes sure, additionallyalso)

Macroscope summarized 240a137.

Summary by CodeRabbit

  • Documentation
    • Refined CI strategy documentation with clearer language around workflow-change review controls, fork security expectations, and minor formatting consistency in build/test pipeline tables.
    • Updated end-user guides and concepts for clearer phrasing around local-first builds, cached build state sharing, sandboxing expectations, stack inheritance, session cleanup, and verification messaging.
    • Standardized wording and formatting across references/specs/spikes (e.g., “ensures”→“makes sure”, “demonstrates”→“covers/shows”, and dash/line-wrapping tweaks) without changing meaning.

Ran Vale with the Microsoft Style Guide (STE) ruleset against every
markdown file in docs/. Fixed all 101 error-level violations across 24
files: expanded contractions, replaced banned words (demonstrates to
shows, begins to starts, additionally to also, ensure to make sure,
acquire/obtain to get), rephrased nominalizations (provide X patterns),
replaced a phrasal verb (tear down to remove), and removed marketing
adjectives (seamlessly, battle-tested, robust).

The 37 em-dash warnings are advisory and left as-is.
@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Documentation-only wording and formatting updates span CI guidance, user guides, references, technical specifications, architecture notes, and networking-related spikes. No implementation or public API changes are included.

Changes

Documentation refresh

Layer / File(s) Summary
CI, concepts, and guide wording
docs/ci-strategy.md, docs/concepts/*, docs/guide/*, docs/internal/*, docs/reference/*
Clarifies CI enforcement, sandboxing, cached state, installation output, CLI wording, and related documentation phrasing.
Minvmd proof wording
docs/specs/01-spec-minvmd-host-daemon/*, docs/specs/02-spec-minvmd-linux-kvm/*
Rephrases goals and proof-artifact descriptions while retaining the same commands, tests, and outcomes.
Networking specification wording
docs/specs/03-spec-networking/*
Updates proof descriptions, DNS/proxy explanations, sequencing language, and WireGuard terminology.
Installer and VM specification wording
docs/specs/04-*, docs/specs/05-*, docs/specs/06-*, docs/specs/07-*, docs/specs/08-*, docs/specs/09-*
Adjusts requirement wording, proof artifacts, references, and technical explanations without changing behavior.
Diagnostics specification wording
docs/specs/10-spec-diagnostics/*
Reformats and rephrases requirements, proof artifacts, verification tables, and redaction architecture text.
Technical spike wording
docs/spikes/*
Updates WireGuard and gvproxy terminology, diagram labels, and timing descriptions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

Suggested reviewers: twitchyliquid64

Poem

I’m a small rabbit, hopping through prose,
Trimming each hedge where the wording grows.
Proofs now show, and workflows are clear,
Specs softly straighten from ear to ear.
Nibble, commit—documentation is bright!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the STE lint fix across the docs tree and matches the change set.
Description check ✅ Passed The description includes summary, change details, and verification, but the template's checklist section is missing.

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md`:
- Around line 249-253: Update the surrounding numbered proof-artifact item to
remove tests/bridge_e2e.rs as an active test, or clearly label it as historical
coverage. Ensure tests/minimald_session_integration.rs is presented as the
authoritative current replacement.

In `@docs/specs/03-spec-networking/03-spec-networking.md`:
- Around line 296-299: Update the UC2a acceptance criterion in the networking
specification to describe the curl result as local HTTP/proxy access rather than
local browser access. Do not claim browser behavior unless the criterion adds a
genuine browser-level verification.
- Around line 443-445: Update the WireGuard implementation decision in this
networking specification to match the contract in architecture.md: select
boringtun for v1 and identify wireguard-go only as the escalation path. Replace
the language implying the choice remains open while preserving the existing
build-chain and maintenance context.
- Line 301: Update the changed proof descriptions in the networking
specification to spell “web server” consistently, including the occurrences near
the local host statement and the additional referenced descriptions. Preserve
the surrounding wording and formatting.

In `@docs/specs/03-spec-networking/architecture.md`:
- Line 123: Remove the stale unresolved-DNS design references from the
architecture document, including the “Unit 3 starts…” statement and the
corresponding assumption-ledger entry. Align the text with the selected
host-side egress proxy design and explicitly preserve that the host resolver is
never consulted.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md`:
- Around line 578-580: Update the sentence beginning “Note that there are
interesting options” to refer to “DNS hostnames” instead of “DNS hosts” and add
an explicit relative clause clarifying that these are the hostnames minimally
created for PTasks and VMs.

In `@docs/specs/05-spec-minvmd-gvproxy-pidfd/05-spec-minvmd-gvproxy-pidfd.md`:
- Around line 71-72: Update the atomic ordering terminology in the
`supervise_switch` documentation from “get/release” to “acquire/release,”
matching the `stopping.load(Ordering::Acquire)` and `store(Ordering::Release)`
behavior while preserving the intentional-versus-unexpected exit classification.

In `@docs/specs/10-spec-diagnostics/10-spec-diagnostics.md`:
- Line 688: In the diagnostics specification’s R6 requirements, move the
requirement labeled R6.6 to after R6.5, preserving its text and restoring
numerical ordering.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1ca0e5eb-6ab9-456d-8997-b74bb9bd6507

📥 Commits

Reviewing files that changed from the base of the PR and between c1d466c and f23f637.

📒 Files selected for processing (24)
  • docs/ci-strategy.md
  • docs/concepts/packages.md
  • docs/concepts/sandboxing.md
  • docs/concepts/stacks.md
  • docs/guide/building.md
  • docs/guide/dev-shell.md
  • docs/guide/getting-started.md
  • docs/guide/install.md
  • docs/internal/release-pipeline.md
  • docs/reference/cli-min.md
  • docs/reference/loadouts.md
  • docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md
  • docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md
  • docs/specs/03-spec-networking/03-spec-networking.md
  • docs/specs/03-spec-networking/architecture.md
  • docs/specs/03-spec-networking/networking-with-diagrams.md
  • docs/specs/05-spec-minvmd-gvproxy-pidfd/05-spec-minvmd-gvproxy-pidfd.md
  • docs/specs/07-spec-installer/07-spec-installer.md
  • docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md
  • docs/specs/09-spec-minvmd-resource-monitoring/architecture.md
  • docs/specs/10-spec-diagnostics/10-spec-diagnostics.md
  • docs/specs/10-spec-diagnostics/architecture.md
  • docs/spikes/2026-06-20-wireguard-implementation.md
  • docs/spikes/2026-06-21-gvproxy-attachment.md

Comment on lines +249 to 253
reads it back. All 5 succeed, shows libkrun-multiplexed
bidirectional bridging. (Removed in the auto-discovery migration: it
bridged the Stage-1 socat-echo stub that minimald-as-pid1 replaced
with a direct SSH session server; session coverage of the bridge is
now `tests/minimald_session_integration.rs`.)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not list the removed bridge test as an active proof artifact.

This paragraph says tests/bridge_e2e.rs was removed, but the surrounding numbered item still presents it as the current proof test. Relabel this as historical coverage or remove the obsolete test description so readers use tests/minimald_session_integration.rs as the authoritative replacement.

Suggested clarification
-1. **Test:** `tests/bridge_e2e.rs` (gated `MINVMD_E2E=1`, `#[ignore]`)
-   boots a VM whose guest listens on vsock `VSOCK_PORT`, opens 5
-   concurrent host UDS connections, each writes a distinct payload and
-   reads it back. All 5 succeed, shows libkrun-multiplexed
-   bidirectional bridging. (Removed in the auto-discovery migration: it
-   bridged the Stage-1 socat-echo stub that minimald-as-pid1 replaced
-   with a direct SSH session server; session coverage of the bridge is
-   now `tests/minimald_session_integration.rs`.)
+1. **Historical test:** `tests/bridge_e2e.rs` covered five concurrent
+   host UDS connections before the auto-discovery migration. It was
+   replaced by `tests/minimald_session_integration.rs`, which now
+   provides session coverage for the bridge.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
reads it back. All 5 succeed, shows libkrun-multiplexed
bidirectional bridging. (Removed in the auto-discovery migration: it
bridged the Stage-1 socat-echo stub that minimald-as-pid1 replaced
with a direct SSH session server; session coverage of the bridge is
now `tests/minimald_session_integration.rs`.)
1. **Historical test:** `tests/bridge_e2e.rs` covered five concurrent
host UDS connections before the auto-discovery migration. It was
replaced by `tests/minimald_session_integration.rs`, which now
provides session coverage for the bridge.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/01-spec-minvmd-host-daemon/01-spec-minvmd-host-daemon.md` around
lines 249 - 253, Update the surrounding numbered proof-artifact item to remove
tests/bridge_e2e.rs as an active test, or clearly label it as historical
coverage. Ensure tests/minimald_session_integration.rs is presented as the
authoritative current replacement.

Comment on lines +296 to +299
2. **CLI:** with an own-IP PTask that publishes a port (ingress `<external>:<internal>`,
R2.3), `curl -x http://127.0.0.1:7654 http://<session-name>.<host-id>.min.internal:<external>/`
from the local host returns HTTP 200 from a webserver running inside the PTask,
demonstrates UC2a local browser access (hostname → published loopback port).
shows UC2a local browser access (hostname → published loopback port).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not label a curl proof as browser access.

This artifact proves local HTTP/proxy access with curl, not browser behavior. Either call it local HTTP access or add an actual browser-level check.

🧰 Tools
🪛 LanguageTool

[grammar] ~298-~298: Ensure spelling is correct
Context: ... the local host returns HTTP 200 from a webserver running inside the PTask, shows UC2a...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/03-spec-networking.md` around lines 296 - 299,
Update the UC2a acceptance criterion in the networking specification to describe
the curl result as local HTTP/proxy access rather than local browser access. Do
not claim browser behavior unless the criterion adds a genuine browser-level
verification.

demonstrates UC2a local browser access (hostname → published loopback port).
shows UC2a local browser access (hostname → published loopback port).
3. **CLI:** `curl http://<session-name>.<host-id>.min.internal:<port>/` from the
local host returns HTTP 200 from a webserver running inside a `HostNet` PTask

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use “web server” consistently.

LanguageTool flags “webserver” in these changed proof descriptions; use the repository’s preferred spelling, likely “web server.”

Also applies to: 373-373, 377-377

🧰 Tools
🪛 LanguageTool

[grammar] ~301-~301: Ensure spelling is correct
Context: ...e local host returns HTTP 200 from a webserver running inside a HostNet PTask (ho...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/03-spec-networking.md` at line 301, Update the
changed proof descriptions in the networking specification to spell “web server”
consistently, including the occurrences near the local host statement and the
additional referenced descriptions. Preserve the surrounding wording and
formatting.

Source: Linters/SAST tools

Comment on lines +443 to 445
and produces a smaller binary. wireguard-go is more mature and is the
reference implementation used in Tailscale's production stack. The decision is
made during Unit 4 design, informed by build-chain and maintenance considerations.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Align the WireGuard decision across the specifications.

This section still says the implementation choice is open, while architecture.md states that boringtun is selected for v1 and wireguard-go is only the escalation path. Update one document so the implementation contract is unambiguous.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/03-spec-networking.md` around lines 443 - 445,
Update the WireGuard implementation decision in this networking specification to
match the contract in architecture.md: select boringtun for v1 and identify
wireguard-go only as the escalation path. Replace the language implying the
choice remains open while preserving the existing build-chain and maintenance
context.

perspective: `minimald` writes hostnames to either a local resolver
configuration or the system resolver stub at launch, and removes them on exit.
Unit 3 begins after the spike resolves this question.
Unit 3 starts after the spike resolves this question.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Remove the stale unresolved-DNS design.

These lines still describe resolver configuration as an open decision, but the networking specification and diagrams select a host-side egress proxy and explicitly state that the host resolver is never consulted. Align this architecture document and its assumption ledger with that decision.

Also applies to: 271-271

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/architecture.md` at line 123, Remove the stale
unresolved-DNS design references from the architecture document, including the
“Unit 3 starts…” statement and the corresponding assumption-ledger entry. Align
the text with the selected host-side egress proxy design and explicitly preserve
that the host resolver is never consulted.

Comment on lines 578 to +580
Note that there are interesting options like embedded an egress webproxy in the
gvproxy and using PAC file with MacOS's webproxy configuration to make it
work seamlessly with the DNS hosts minimal creates for PTasks and VMs.
work with the DNS hosts minimal creates for PTasks and VMs.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Clarify “DNS hosts.”

The sentence should refer to DNS hostnames, not DNS hosts, and needs an explicit relative clause.

Proposed wording
- work with the DNS hosts minimal creates for PTasks and VMs.
+ work with the DNS hostnames that minimal creates for PTasks and VMs.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Note that there are interesting options like embedded an egress webproxy in the
gvproxy and using PAC file with MacOS's webproxy configuration to make it
work seamlessly with the DNS hosts minimal creates for PTasks and VMs.
work with the DNS hosts minimal creates for PTasks and VMs.
Note that there are interesting options like embedded an egress webproxy in the
gvproxy and using PAC file with MacOS's webproxy configuration to make it
work with the DNS hostnames that minimal creates for PTasks and VMs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/03-spec-networking/networking-with-diagrams.md` around lines 578 -
580, Update the sentence beginning “Note that there are interesting options” to
refer to “DNS hostnames” instead of “DNS hosts” and add an explicit relative
clause clarifying that these are the hostnames minimally created for PTasks and
VMs.

Comment on lines +71 to 72
`stopping` atomic and its get/release ordering are unchanged, they continue
to classify exits as intentional vs. unexpected in `supervise_switch`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n -C2 'get/release|acquire/release|Ordering::(Acquire|Release)' docs crates

Repository: gominimal/minimal

Length of output: 2713


🏁 Script executed:

#!/bin/bash
sed -n '64,76p' docs/specs/05-spec-minvmd-gvproxy-pidfd/05-spec-minvmd-gvproxy-pidfd.md
sed -n '428,440p' crates/minvmd/src/net.rs

Repository: gominimal/minimal

Length of output: 1438


Restore the atomic ordering terminology.

get/release is not a valid Rust atomic ordering pair. Use acquire/release here to match the stopping.load(Ordering::Acquire) / store(Ordering::Release) behavior.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/05-spec-minvmd-gvproxy-pidfd/05-spec-minvmd-gvproxy-pidfd.md`
around lines 71 - 72, Update the atomic ordering terminology in the
`supervise_switch` documentation from “get/release” to “acquire/release,”
matching the `stopping.load(Ordering::Acquire)` and `store(Ordering::Release)`
behavior while preserving the intentional-versus-unexpected exit classification.

`comm` otherwise), raw `/proc/net` tables, and `disk.json` — finishing
with `manifest.json`.
- **R6.6**: The bundle shall additionally capture the guest-side incident
- **R6.6**: The bundle shall also capture the guest-side incident

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Restore the R6 requirements to numerical order.

R6.6 currently appears before R6.3R6.5, which makes cross-referencing the specification unnecessarily error-prone. Move this requirement after R6.5.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/10-spec-diagnostics/10-spec-diagnostics.md` at line 688, In the
diagnostics specification’s R6 requirements, move the requirement labeled R6.6
to after R6.5, preserving its text and restoring numerical ordering.

@0chroma

0chroma commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai 748

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Tip

For best results, initiate chat on the files or code changes.

@0chroma The Comment image shows a white-and-pale-blue poster that reads, “All Robot & Computers Must Shut The Hell Up,” above three red prohibition symbols over a cartoon robot, a desktop computer, and self-service kiosks. It continues: “To All Machines: You Do Not Speak Unless Spoken To” and “And I Will Never Speak To You,” followed by, “I Do Not Want To Hear ‘Thank You’ From A Kiosk … You Have No Right To Speak In My Holy Tongue.”

Understood—no unsolicited kiosk-style pleasantries from me. 🐰

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/ci-strategy.md (1)

449-455: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Scope this to the repo’s current protection setup. The repo currently uses pull_request only, so the fork-secrets claim fits today’s workflows. The “any PR is unmergeable” part still depends on branch-protection/ruleset settings, and it would need revisiting if a workflow ever moved to pull_request_target.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ci-strategy.md` around lines 449 - 455, Revise the CI strategy
documentation to scope the fork-secrets statement to the repository’s current
pull_request-only workflows, and clarify that requiring code-owner review
through branch protection or rulesets is what makes workflow-changing PRs
unmergeable without human approval. Note that this guidance must be revisited if
any workflow moves to pull_request_target.

Source: MCP tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/ci-strategy.md`:
- Around line 449-455: Revise the CI strategy documentation to scope the
fork-secrets statement to the repository’s current pull_request-only workflows,
and clarify that requiring code-owner review through branch protection or
rulesets is what makes workflow-changing PRs unmergeable without human approval.
Note that this guidance must be revisited if any workflow moves to
pull_request_target.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: befbf3e3-b6df-4fd9-9a5f-c2d81547958a

📥 Commits

Reviewing files that changed from the base of the PR and between f23f637 and a0a075f.

📒 Files selected for processing (8)
  • docs/ci-strategy.md
  • docs/specs/03-spec-networking/03-spec-networking.md
  • docs/specs/04-spec-ot-render-decoupling/04-spec-ot-render-decoupling.md
  • docs/specs/06-spec-ssh-host-key-in-beacon/06-spec-ssh-host-key-in-beacon.md
  • docs/specs/07-spec-installer/07-spec-installer.md
  • docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md
  • docs/specs/10-spec-diagnostics/10-spec-diagnostics.md
  • docs/spikes/2026-06-20-wireguard-implementation.md
🚧 Files skipped from review as they are similar to previous changes (5)
  • docs/specs/03-spec-networking/03-spec-networking.md
  • docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md
  • docs/specs/07-spec-installer/07-spec-installer.md
  • docs/spikes/2026-06-20-wireguard-implementation.md
  • docs/specs/10-spec-diagnostics/10-spec-diagnostics.md

@0chroma
0chroma force-pushed the docs/ste-prose-lint branch from a0a075f to bf76838 Compare July 29, 2026 17:11
The ASD-STE100 EmDashes rule flags en dashes (U+2013) used in numeric
ranges like "4-6 min", "DM1-DM5", and "Units 7-8". Replaced all 37
instances with ASCII hyphens. Vale now reports 0 errors and 0 warnings.
@0chroma
0chroma force-pushed the docs/ste-prose-lint branch from bf76838 to 240a137 Compare July 29, 2026 17:15
@0chroma
0chroma enabled auto-merge (squash) July 29, 2026 17:17

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md (1)

660-662: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Avoid claiming UUIDv7 collisions are impossible.

UUIDv7 makes collisions extraordinarily unlikely, but does not guarantee that none can occur. Because ProviderIndex keys directly on session IDs, document the probabilistic guarantee or describe an explicit collision check/handling strategy instead of stating that there is “no collision.”

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md` around lines 660
- 662, Revise the “Session UUIDv7” documentation to avoid asserting that
ProviderIndex session IDs cannot collide. Describe UUIDv7 uniqueness as
probabilistic and extraordinarily unlikely, or document an explicit collision
detection and handling strategy for ProviderIndex keys.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md`:
- Around line 660-662: Revise the “Session UUIDv7” documentation to avoid
asserting that ProviderIndex session IDs cannot collide. Describe UUIDv7
uniqueness as probabilistic and extraordinarily unlikely, or document an
explicit collision detection and handling strategy for ProviderIndex keys.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2e34de94-6696-4d28-8b34-7136e10ecdd9

📥 Commits

Reviewing files that changed from the base of the PR and between bf76838 and 240a137.

📒 Files selected for processing (9)
  • docs/ci-strategy.md
  • docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md
  • docs/specs/03-spec-networking/03-spec-networking.md
  • docs/specs/04-spec-ot-render-decoupling/04-spec-ot-render-decoupling.md
  • docs/specs/06-spec-ssh-host-key-in-beacon/06-spec-ssh-host-key-in-beacon.md
  • docs/specs/07-spec-installer/07-spec-installer.md
  • docs/specs/08-spec-vm-ext4-volume/08-spec-vm-ext4-volume.md
  • docs/specs/10-spec-diagnostics/10-spec-diagnostics.md
  • docs/spikes/2026-06-20-wireguard-implementation.md
🚧 Files skipped from review as they are similar to previous changes (7)
  • docs/specs/06-spec-ssh-host-key-in-beacon/06-spec-ssh-host-key-in-beacon.md
  • docs/specs/02-spec-minvmd-linux-kvm/02-spec-minvmd-linux-kvm.md
  • docs/specs/04-spec-ot-render-decoupling/04-spec-ot-render-decoupling.md
  • docs/spikes/2026-06-20-wireguard-implementation.md
  • docs/ci-strategy.md
  • docs/specs/07-spec-installer/07-spec-installer.md
  • docs/specs/10-spec-diagnostics/10-spec-diagnostics.md

@0chroma
0chroma merged commit 7e9735c into main Jul 29, 2026
29 checks passed
@0chroma
0chroma deleted the docs/ste-prose-lint branch July 29, 2026 17:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants