docs: changelog entries told the whole story where one sentence would do

RELEASE.md

@@ -26,10 +26,38 @@ changie new
 ```
 
 You are prompted for a **kind** (`Added`, `Changed`, `Deprecated`, `Removed`,
-`Fixed`, `Security`, `Documentation`), a one-line **body**, and the **issue
-number**. It writes a small YAML file under `changes/unreleased/` — commit it
-alongside your code. Prefer `changie new` over hand-writing the YAML: it enforces
-the issue number, and a fragment without one renders as a dead link.
+`Fixed`, `Security`, `Documentation`), a **body**, and the **issue number**. It
+writes a small YAML file under `changes/unreleased/` — commit it alongside your
+code. Prefer `changie new` over hand-writing the YAML: it enforces the issue
+number, and a fragment without one renders as a dead link.
+
+### One sentence. Two at most.
+
+The changelog is a scan surface, not a design document — the reader is deciding
+whether this release affects them. Root cause, mechanism, measurements and
+rejected alternatives belong in the linked issue and PR, which every entry
+already points at.
+
+- **One sentence** — what changed, and what it means for someone using DevCloud.
+- **A second only if a reader must not miss it** — a limit, a behaviour change
+  they have to act on, or the one figure that makes the entry meaningful.
+- **Never a third.** If it needs one, it is either two changes (write two
+  fragments) or a story that belongs in the issue.
+
+```yaml
+# too long — the root cause, the mechanism and the evidence all belong in #142
+body: 'S3 Control requests were served by S3. `s3control` signs with S3''s own
+  signing name, so every call fell through to the REST-XML default and the S3
+  provider parsed it as a bucket and key — `CreateAccessPoint` returned 200 and
+  left an object in a bucket named `v20180820`. S3 Control is now split off by its
+  `/v20180820/` path prefix, and its unserved operations return a clean AWS error
+  instead of a fabricated success'
+
+# right length
+body: 'S3 Control requests were served by S3, which answered `CreateAccessPoint`
+  with a fabricated 200. It is now split off by its `/v20180820/` path prefix, and
+  its unserved operations return a clean AWS error'
+```
 
 Config: [`.changie.yaml`](.changie.yaml).
 
@@ -52,6 +80,9 @@ rather than from a failed tag. The rest are only caught here.
       `grep -L 'Issue: "[0-9]' changes/unreleased/*.yaml` prints nothing.
 - [ ] **`changes/unreleased/` is not empty.** No fragments means either nothing
       shipped or someone forgot one.
+- [ ] **Every fragment body is one sentence, two at most.** A third sentence is
+      either a second change that needs its own fragment or detail that belongs in
+      the issue.
 - [ ] **Deprecation review.** If this release *removes* anything previously
       deprecated — a config key, an env var, an admin route — confirm it shipped
       for at least one release with a warning first. Removing without that overlap

changes/unreleased/Documentation-20260906-185423.yaml

@@ -0,0 +1,5 @@
+kind: Documentation
+body: Changelog fragments are capped at one sentence, two at most, with the rule and a worked example in RELEASE.md and a line for it in the pre-flight checklist. Every entry already in the changelog is rewritten to that limit, and the v1.1.0 and v1.0.0 release notes are republished from their fragment files
+time: 2026-09-06T18:54:23.073014+09:00
+custom:
+    Issue: "152"

changes/unreleased/Documentation-20260906-234500.yaml

@@ -1,5 +1,5 @@
 kind: Documentation
-body: 'The documentation no longer publishes the same figure at five different values. Six numbers were restated across pages and no two agreed: 205/148/101 registered services, 12,407/9,030/7,475 known operations, 992/1,144/775 compatibility tests, 11/12 services without a Smithy model, and 46 engine-wired services against a measured 155. Only docs/coverage.md, README.md and docs/README.md are gated against the binary by cmd/devcloud/coverage_test.go, so those were right and every restatement had rotted; coverage.md now owns the numbers and the other pages link to it. Three statements did not match the code and are corrected: docs/troubleshooting.md pointed at a GET /devcloud/api/health route that internal/admin/api.go does not register, and blamed a failed Lambda invoke on Docker when lambda/runtime.go is a stub that always returns a placeholder; docs/contributing.md listed interface.go, serializer.go and deserializer.go as codegen output when no template emits them. docs/crud-engine.md contradicted itself, serving five protocols in one table and claiming JSON-only across 46 services two screens later. docs/compatibility-policy.md said 193 model-backed services and 12 without, where manifest_gen.go holds 194 and 11. Eighteen files are shorter overall — 3,564 lines to 2,501 — with the 285-row demand.md evidence table and the per-service pages left intact'
+body: 'The documentation no longer publishes the same figure at five different values: six numbers were restated across pages with no two agreeing, so docs/coverage.md now owns them and every other page links to it. Three statements that did not match the code are corrected — a GET /devcloud/api/health route that is not registered, a failed Lambda invoke blamed on Docker when the runtime is a stub, and codegen output files no template emits — and eighteen files are 1,063 lines shorter'
 time: 2026-09-06T23:45:00.000000+09:00
 custom:
     Issue: "151"

changes/v1.0.0.md

@@ -31,11 +31,11 @@
 * Restored CloudWatch's 17 CRUD-engine operations. The gateway picks the protocol from the request, not from the provider, so CloudWatch reaches the engine whenever a client speaks JSON — filtering the registry by the provider's declared protocol had removed that coverage outright ([#126](https://github.com/skyoo2003/devcloud/issues/126))
 * EventBridge rule ARNs now name their event bus, as AWS does. A rule name is unique per bus, so same-named rules on two custom buses previously shared one ARN — and with it, one tag set, where tagging one rule changed the other's and deleting one wiped the survivor's ([#126](https://github.com/skyoo2003/devcloud/issues/126))
 * CloudWatch now drops an alarm's tags when the alarm is deleted, so recreating an alarm under the same name no longer inherits the old one's tags ([#126](https://github.com/skyoo2003/devcloud/issues/126))
-* Downloadable binaries now start. Releases were built with CGO_ENABLED=0 while the SQLite driver required cgo, so every tar.gz/zip binary, the Homebrew formula and the versioned `*-alpine` images exited at startup with "go-sqlite3 requires cgo to work. This is a stub" — only the rolling `latest` image, built separately with cgo, worked. The driver is now pure Go, so no build needs a C toolchain or SQLite headers ([#128](https://github.com/skyoo2003/devcloud/issues/128))
-* Service selection now matches what the docs promise. An empty `services` block is still a block, so it starts nothing rather than every registered service; and `DEVCLOUD_SERVICES` names the running set outright rather than intersecting with the `services` block, so it starts a service the block omits and overrides a block entry the file disabled. Previously `DEVCLOUD_SERVICES=sqs` alongside a block listing only `s3` started nothing at all ([#129](https://github.com/skyoo2003/devcloud/issues/129))
-* CloudFront no longer fabricates a success for operations it does not implement. Its dispatch fallback answered HTTP 200 with an empty XML document, which boto3 parses as a successful empty result, on all 122 CloudFront operations the fidelity manifest classifies as `unimplemented` — including `GetPublicKey`. It now returns `NotImplemented` (HTTP 501), matching the other 32 providers that decline from their own dispatch default. It was the only provider in the tree that answered an unimplemented call with a success ([#129](https://github.com/skyoo2003/devcloud/issues/129))
-* Generated routers now honour route patterns that constrain the query string, so operations distinguished only by a query parameter are reachable. `matchURI` split the whole pattern into path segments, which made `/2020-05-31/tagging?Operation=Tag` unable to match the path segment `tagging` — CloudFront `TagResource` and `UntagResource` were implemented but unroutable, and answered as unimplemented. A pattern's constraint must now be satisfied by the request query, and query-constrained routes are tried ahead of unconstrained ones so a bare path cannot shadow a more specific route ([#129](https://github.com/skyoo2003/devcloud/issues/129))
-* Released binaries now register their services. GoReleaser built `cmd/devcloud/main.go` rather than the package, which drops `imports.go` — the only place the 104 services blank-import themselves into the registry. `main.go` references nothing from it, so the build succeeded and the binary exited at startup with `unknown service: s3`. Every archive, the Homebrew formula and the container images were affected; the boto3 suite missed it because the release gate compiled the package instead of what GoReleaser ships, and that gate now builds with GoReleaser ([#131](https://github.com/skyoo2003/devcloud/issues/131))
+* Downloadable binaries now start, where releases built with `CGO_ENABLED=0` against a SQLite driver that required cgo exited at startup — every tar.gz/zip binary, the Homebrew formula and the versioned `*-alpine` images. The driver is now pure Go, so no build needs a C toolchain or SQLite headers ([#128](https://github.com/skyoo2003/devcloud/issues/128))
+* Service selection now matches what the docs promise: an empty `services` block starts nothing rather than every registered service, and `DEVCLOUD_SERVICES` names the running set outright instead of intersecting with the block. Previously `DEVCLOUD_SERVICES=sqs` alongside a block listing only `s3` started nothing at all ([#129](https://github.com/skyoo2003/devcloud/issues/129))
+* CloudFront no longer fabricates a success for the 122 operations the fidelity manifest classifies as `unimplemented`, where its dispatch fallback answered HTTP 200 with an empty XML document that boto3 parses as a successful empty result. It now returns `NotImplemented` (HTTP 501), matching the other 32 providers that decline from their own dispatch default ([#129](https://github.com/skyoo2003/devcloud/issues/129))
+* Generated routers now honour route patterns that constrain the query string, so operations distinguished only by a query parameter are reachable — `matchURI` split the whole pattern into path segments, leaving CloudFront `TagResource` and `UntagResource` implemented but unroutable. Query-constrained routes are tried ahead of unconstrained ones, so a bare path cannot shadow a more specific route ([#129](https://github.com/skyoo2003/devcloud/issues/129))
+* Released binaries now register their services, where GoReleaser built `cmd/devcloud/main.go` rather than the package and dropped the `imports.go` that blank-imports all 104 services — every archive, the Homebrew formula and the container images exited at startup with `unknown service: s3`. The release gate now builds with GoReleaser instead of compiling the package, which is why the boto3 suite missed it ([#131](https://github.com/skyoo2003/devcloud/issues/131))
 ### Documentation
-* Corrected what the fidelity manifest says an `unimplemented` operation returns. It claimed JSON and Query services answer `InvalidAction` (HTTP 400), but only the 46 providers that fall through to the CRUD engine do; 32 answer `NotImplemented` (HTTP 501) from their own dispatch default, several use their own vocabulary, and `sqs` differs by protocol. Only the failure itself is stable — the specific code and status are documented, not guaranteed ([#129](https://github.com/skyoo2003/devcloud/issues/129))
+* Corrected what the fidelity manifest says an `unimplemented` operation returns: it claimed JSON and Query services answer `InvalidAction` (HTTP 400), where only the 46 providers falling through to the CRUD engine do and 32 answer `NotImplemented` (HTTP 501) from their own dispatch default. Only the failure itself is stable — the specific code and status are documented, not guaranteed ([#129](https://github.com/skyoo2003/devcloud/issues/129))
 * The roadmap, architecture and governance docs no longer describe DevCloud as pre-1.0. All three ship inside the release archive, so a v1.0 download would have carried a roadmap listing its own release as pending, an architecture overview naming Phase 1 as current, and a governance doc calling the API unstable — contradicting the compatibility policy packaged beside them ([#130](https://github.com/skyoo2003/devcloud/issues/130))