diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 010d5bdf3..8921a5279 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -336,6 +336,12 @@ "section": "PRDs", "body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n|---|---|---|---|\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n" }, + { + "url": "/dev/prds/release-stream-and-commit-rules/", + "title": "One release stream, one page per version, and commit rules — decision", + "section": "PRDs", + "body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft from this document; `RELEASING.md` points at that\nrule beside the step it governs rather than restating it, because two statements of\none rule drift.\n\n## Commit rules and their enforcement\n\n- **Conventional commits**, with the scope taken from the package map.\n- **One logical change per commit.** A commit that does two things is two commits.\n- **The subject is imperative and short**; the body says why the change is right\n rather than restating the diff.\n- **A commit depends on the gate's exit status.** The gate and the commit run as one\n conditional chain, never as separate statements on one command line, where nothing\n reads the gate's status but the operator who typed it.\n- **Enforcement is a `commit-msg` hook** installed by one documented target, plus a\n check in CI over the pushed range, so the rule holds for a person who never\n installed the hook.\n- **Scopes are derived, not invented**, and an unknown scope fails loudly rather than\n being accepted.\n\n## Verification\n\n- One changelog file exists, the two component changelogs do not, and the generated\n pages match it.\n- A release prepared with `VERSION` alone writes its notes and tags, with no\n `GATEWAY` or `RUNTIME` input.\n- Every release URL published before this change resolves.\n- `release:tag` refuses after a review that reported at the level, and refuses when\n no review ran.\n- The `commit-msg` hook and the CI range check each refuse a non-conforming subject\n and an unknown scope, with the hook absent and present.\n" + }, { "url": "/dev/prds/review-calibration/", "title": "Review calibration -- decision", @@ -651,6 +657,10 @@ "title": "Public and development documentation -- design", "url": "/dev/prds/public-and-dev-docs/" }, + { + "title": "One release stream, one page per version, and commit rules — decision", + "url": "/dev/prds/release-stream-and-commit-rules/" + }, { "title": "Review calibration -- decision", "url": "/dev/prds/review-calibration/" diff --git a/docs/prds/release-stream-and-commit-rules.md b/docs/prds/release-stream-and-commit-rules.md new file mode 100644 index 000000000..008ebfd7b --- /dev/null +++ b/docs/prds/release-stream-and-commit-rules.md @@ -0,0 +1,102 @@ +# One release stream, one page per version, and commit rules — decision + +**Status:** Draft +**Date:** 2026-09-22 +**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the +commit rules it enforces, and `tools/newsgen` for the artifact shape. + +**Supersedes:** `docs/prds/news-and-releases.md`, sections "Source of truth" and +"Two components" — one changelog replaces two, and one page per version replaces +one page per component. Its remaining decisions stand. + +## Decision + +**A release is one version covering whatever changed.** One changelog holds every +release section, one generated page holds every version's notes, and an operator +cutting a release names one version. + +## One changelog + +Every release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md` +and `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to +them. The changelog is the only source of release prose, and tags are not a source: +CI and deployment check out shallow, so tags are absent from a site build while the +changelog is always present. + +## One version stream + +**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and +`release:tag` take one version, and `tools/release.sh` loses the two flags. + +They may stay as build-time stamps, because a binary must still report what it +contains. A release that must name three versions forces an operator to pass skip +values for components that did not change, and that ceremony is what this decision +removes — along with the drift it allows, where two components' tags fall a release +apart. + +**Per-component detail stays, as sections inside the release.** A reader still needs +to know whether `archied` or the agent changed; what goes away is the separate +numbers and the separate pages, not the information. + +**History is not re-tagged.** Existing tags keep their names, because tags are not a +source and nothing reads them to build a page. A future reader must not "fix" the +unified changelog by rewriting tags to match it. + +## One release page per version + +`docs/news/.md` replaces `docs/news//.md`, carrying the +release's per-component sections inside it. + +**Every release URL already published keeps working.** `/news/archied/` and +`/news/archie/` route to the unified page for that version. The generator +emits the redirect table beside the pages so it cannot drift from them; if the +renderer needs the table in its own repository, that is a change in that repository +rather than a hand-maintained list here. + +## The reviewer runs between prepare and tag + +Release notes are prose, and the review agent exists to review prose. **`release:tag` +refuses to tag when the review has not been run for that version, or when it reports +at the level.** + +The invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok` +and exits 0. `tl review --deadline --max-turns ` reports +`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on +`docs/news/archied/1.36.0.md`. + +**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation +without it cannot refuse anything and the step would be decorative. `--fail-on high` +is the level: a medium finding in a release note is worth acting on, and it should not +stop a release on its own. + +**The rule is stated once.** It belongs in the reviewer's own rule set, which +`tl rules --from-doc` can draft from this document; `RELEASING.md` points at that +rule beside the step it governs rather than restating it, because two statements of +one rule drift. + +## Commit rules and their enforcement + +- **Conventional commits**, with the scope taken from the package map. +- **One logical change per commit.** A commit that does two things is two commits. +- **The subject is imperative and short**; the body says why the change is right + rather than restating the diff. +- **A commit depends on the gate's exit status.** The gate and the commit run as one + conditional chain, never as separate statements on one command line, where nothing + reads the gate's status but the operator who typed it. +- **Enforcement is a `commit-msg` hook** installed by one documented target, plus a + check in CI over the pushed range, so the rule holds for a person who never + installed the hook. +- **Scopes are derived, not invented**, and an unknown scope fails loudly rather than + being accepted. + +## Verification + +- One changelog file exists, the two component changelogs do not, and the generated + pages match it. +- A release prepared with `VERSION` alone writes its notes and tags, with no + `GATEWAY` or `RUNTIME` input. +- Every release URL published before this change resolves. +- `release:tag` refuses after a review that reported at the level, and refuses when + no review ran. +- The `commit-msg` hook and the CI range check each refuse a non-conforming subject + and an unknown scope, with the hook absent and present.