Enforce canonical Markdown formatting.

.github/AGENTS.md

@@ -5,8 +5,8 @@ changes under `.github/`.
 
 ## Code Review Rules
 
-- Grant the smallest explicit token permissions and pin every external Action
-  to a full commit SHA.
+- Grant the smallest explicit token permissions and pin every external Action to
+  a full commit SHA.
 - Never expose repository secrets or write-capable tokens to untrusted pull
   request code. A `pull_request_target` workflow must not check out, source,
   evaluate, or execute the pull-request head or interpolate untrusted text into

.github/workflows/test.yml

@@ -18,6 +18,7 @@ env:
   GOLANGCI_LINT_VERSION: v2.12.2
   GOVULNCHECK_VERSION: v1.6.0
   MARKDOWNLINT_VERSION: 0.23.2
+  PRETTIER_VERSION: 3.9.9
   STATICCHECK_VERSION: v0.7.0
 
 jobs:
@@ -138,13 +139,14 @@ jobs:
           golangci-lint run --config .golangci.yml ./...
       - name: Run test-code lint
         run: golangci-lint run --config .golangci.tests.yml ./...
-      - name: Lint tracked Markdown
+      - name: Check tracked Markdown formatting and lint
         shell: bash
         run: |
           markdown_files=()
           while IFS= read -r -d '' file; do
             markdown_files+=("$file")
           done < <(git ls-files -z '*.md')
+          npx --yes "prettier@${PRETTIER_VERSION}" --check "${markdown_files[@]}"
           npx --yes "markdownlint-cli2@${MARKDOWNLINT_VERSION}" -- "${markdown_files[@]}"
       - name: Test Codex review signal
         run: bash .github/scripts/codex-review-signal_test.sh

.markdownlint-cli2.yaml

@@ -1,6 +1,7 @@
 config:
   MD013:
     line_length: 80
+    stern: true
     code_blocks: false
     tables: false
   MD041: false

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 80,
+  "proseWrap": "always",
+  "embeddedLanguageFormatting": "off",
+  "endOfLine": "lf"
+}

AGENTS.md

@@ -1,7 +1,7 @@
 # AI Agent Guidelines
 
-This file applies to coding agents enhancing Ostiole itself. Before changing
-the repository, read and follow [`CONTRIBUTING.md`](CONTRIBUTING.md); its
+This file applies to coding agents enhancing Ostiole itself. Before changing the
+repository, read and follow [`CONTRIBUTING.md`](CONTRIBUTING.md); its
 contribution, style, testing, documentation, commit, and pull-request rules
 apply equally to humans and agents.
 
@@ -14,16 +14,16 @@ downstream compositions.
 
 - Start by reading `docs/architecture.md` and `docs/capabilities.md` before
   adding or changing a public package, composition, example, or command.
-- Work only within the approved task. Record useful discoveries for later
-  rather than implementing unrelated changes.
-- Work test-first at every behavioral layer: add a test, run it and observe
-  the intended failure, implement the smallest change that makes it pass, and
-  then refactor while the test remains green.
+- Work only within the approved task. Record useful discoveries for later rather
+  than implementing unrelated changes.
+- Work test-first at every behavioral layer: add a test, run it and observe the
+  intended failure, implement the smallest change that makes it pass, and then
+  refactor while the test remains green.
 - Prefer deterministic behavioral fakes over canned protocol transcripts when
   testing hardware-independent behavior.
-- Treat substantial example or command code as evidence that a reusable
-  library boundary may be missing. Add and test the smallest appropriate
-  public API before composing it into an executable.
+- Treat substantial example or command code as evidence that a reusable library
+  boundary may be missing. Add and test the smallest appropriate public API
+  before composing it into an executable.
 - Never bypass an existing library layer by reproducing its USB, adapter,
   wire-protocol, DAP, or target framing in a test or application.
 - Keep private plans, donor history, agent activity, and unimplemented
@@ -32,30 +32,29 @@ downstream compositions.
 
 ## Commit-size checkpoint
 
-Approximately 200 added lines of non-test Go is the normal upper target for
-one commit. Before forming each commit:
+Approximately 200 added lines of non-test Go is the normal upper target for one
+commit. Before forming each commit:
 
-1. Format declarations and calls naturally, measure the proposed added
-   non-test Go, and report the count to the maintainer.
+1. Format declarations and calls naturally, measure the proposed added non-test
+   Go, and report the count to the maintainer.
 2. Above 200 lines, pause and present credible splits at independently useful
-   capability boundaries, including the approximate count and usefulness of
-   each resulting commit.
-3. Keep each behavior together with its error handling, tests, and
-   documentation so the commit remains coherent, tested, documented, and
-   bisectable.
+   capability boundaries, including the approximate count and usefulness of each
+   resulting commit.
+3. Keep each behavior together with its error handling, tests, and documentation
+   so the commit remains coherent, tested, documented, and bisectable.
 4. Do not form a commit above 300 lines without explicit maintainer approval of
    the proposed unsplit boundary before the commit is created. A later handoff
    or pull-request explanation is not approval.
 5. An exception request must identify the concrete coupling which prevents a
    coherent split. “The feature is cohesive” is not enough.
 
-Do not manipulate formatting, create dead private seams, separate error
-handling from the behavior it protects, or use mechanical movement to disguise
-the count. Call out pure movement, generated code, and other unusual cases and
-judge them by their review burden; none is an automatic exemption. Repeated
-300–1,500-line exceptions indicate inadequate decomposition, not ordinary use
-of the exception. In the final handoff, list every commit's added non-test Go
-count and any approved exception.
+Do not manipulate formatting, create dead private seams, separate error handling
+from the behavior it protects, or use mechanical movement to disguise the count.
+Call out pure movement, generated code, and other unusual cases and judge them
+by their review burden; none is an automatic exemption. Repeated 300–1,500-line
+exceptions indicate inadequate decomposition, not ordinary use of the exception.
+In the final handoff, list every commit's added non-test Go count and any
+approved exception.
 
 ## Code Review Rules
 
@@ -64,12 +63,12 @@ count and any approved exception.
 - Report concrete, consequential defects rather than general praise or style
   preferences. Explain the failure mode and point to the narrowest relevant
   code.
-- Check behavior, error paths, bounds, timeouts, cancellation, concurrency,
-  and cleanup. Trace resource ownership from USB through adapters, wire
-  protocols, DAP, targets, examples, and commands.
-- Ensure deadlines and cancellation cover blocking host and protocol
-  operations without preventing bounded cleanup; cleanup must not depend on
-  an operation context that is already canceled.
+- Check behavior, error paths, bounds, timeouts, cancellation, concurrency, and
+  cleanup. Trace resource ownership from USB through adapters, wire protocols,
+  DAP, targets, examples, and commands.
+- Ensure deadlines and cancellation cover blocking host and protocol operations
+  without preventing bounded cleanup; cleanup must not depend on an operation
+  context that is already canceled.
 - Flag leaks, double ownership, discarded primary or cleanup errors, unsafe
   effects, and restoration that cannot be retried. Cleanup that may be retried
   must retain enough state to do so safely.
@@ -87,12 +86,12 @@ count and any approved exception.
   control flow; do not suggest formatting tricks that influence lint or line
   counts.
 - Require focused deterministic tests for success, failure, cleanup, and retry
-  behavior at the owning package boundary. Keep production packages
-  independent of simulators and command-internal policy.
+  behavior at the owning package boundary. Keep production packages independent
+  of simulators and command-internal policy.
 - For integration tests, require the `integration` build tag, skip absent or
   ambiguous hardware before selection, open a selected adapter exactly once,
-  gate effectful operations explicitly, and restore volatile state with
-  bounded cleanup.
+  gate effectful operations explicitly, and restore volatile state with bounded
+  cleanup.
 
 When a change affects a public package, render and review its complete exported
 API rather than reading only the diff. Check whether distinct operations can
@@ -107,30 +106,30 @@ traffic or cleanup, or bad input reaches hardware before it is rejected.
   Distinguish ordinary tests, behavioral simulation, CI compilation, and
   physical HIL; none is evidence for another.
 - Keep architecture ownership, cleanup, safety effects, composition guidance,
-  examples, commands, and capability tables consistent with code. For
-  Markdown changes, verify relative links, headings, commands, package names,
-  examples, and stated limitations against the current tree.
+  examples, commands, and capability tables consistent with code. For Markdown
+  changes, verify relative links, headings, commands, package names, examples,
+  and stated limitations against the current tree.
 - Require documentation in the same commit as exported API, ownership,
   lifecycle, safety, platform, composition, or validation-claim changes.
-- Reject a pull request which adds an API without representative calls in
-  its opening description. When an API changes, require representative calls
-  before and after the change. Verify that every example preserves the real
-  ownership, cleanup, and safety rules and shows the actual migration.
+- Reject a pull request which adds an API without representative calls in its
+  opening description. When an API changes, require representative calls before
+  and after the change. Verify that every example preserves the real ownership,
+  cleanup, and safety rules and shows the actual migration.
 - Reject pull-request prose paragraphs which are hard-wrapped in the Markdown
   source. Let GitHub wrap paragraphs for display; use source line breaks for
   lists, headings, and naturally formatted code blocks.
 - Keep routine checks which GitHub reports independently out of pull-request
   prose. They remain required publication guards, not evidence to advertise.
 - Require physical HIL claims to identify the exercised path and bench.
 - When commit context is available, reject a nontrivial commit whose message
-  leaves the reviewer to reconstruct its purpose from the diff. The subject
-  must describe the resulting change. The body must say what was wrong or
-  missing beforehand, what the commit changes, and any important design or
-  safety choice which is not evident from the code.
+  leaves the reviewer to reconstruct its purpose from the diff. The subject must
+  describe the resulting change. The body must say what was wrong or missing
+  beforehand, what the commit changes, and any important design or safety choice
+  which is not evident from the code.
 - Judge each message against that commit, not the pull request as a whole. A
-  file inventory, list of implementation steps or tests, or review history
-  does not explain why a commit belongs in the history.
+  file inventory, list of implementation steps or tests, or review history does
+  not explain why a commit belongs in the history.
 - Flag unrelated changes, non-bisectable commits, missing same-commit tests or
   documentation, and artificial splits made only to influence line counts.
-- Treat changes to contribution rules, agent review guidance, CODEOWNERS,
-  policy tooling, or workflows as security-sensitive review-policy changes.
+- Treat changes to contribution rules, agent review guidance, CODEOWNERS, policy
+  tooling, or workflows as security-sensitive review-policy changes.

CODE_OF_CONDUCT.md

@@ -1,16 +1,16 @@
 # Code of Conduct
 
-Ostiole should be a friendly place to build careful hardware tools together.
-Be respectful, assume good faith, and give people room to learn. Disagree with
+Ostiole should be a friendly place to build careful hardware tools together. Be
+respectful, assume good faith, and give people room to learn. Disagree with
 ideas and code without attacking the person behind them.
 
 Harassment, threats, discrimination, deliberate humiliation, and sustained
 disruptive behavior are not welcome. Neither is using technical correctness as
 an excuse to be cruel. Please use common sense; this is a community standard,
 not a checklist whose gaps are loopholes.
 
-If a conversation goes wrong, step back or contact
-[Jon](mailto:jon@jon.dev) privately. Jon makes the final call about whether
-conduct fits this project and may edit or remove comments, close a discussion,
-reject a contribution, or limit participation when needed. Context and intent
-matter, but maintaining a respectful community comes first.
+If a conversation goes wrong, step back or contact [Jon](mailto:jon@jon.dev)
+privately. Jon makes the final call about whether conduct fits this project and
+may edit or remove comments, close a discussion, reject a contribution, or limit
+participation when needed. Context and intent matter, but maintaining a
+respectful community comes first.