Skip to content

docs(adr): compress to 5 records in the domain-modeling format - #74

Merged
lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Rewrites docs/adr/ from 7 records (~2,570 words) to 5 (~780 words), one paragraph each, in the shape ADR-FORMAT.md asks for. Survivors are renumbered 0001-0005 in their original order and every citation moves with them.

Evaluation

Each record was tested against the admission test: hard to reverse, surprising without context, the result of a real trade-off.

Old Outcome New Reason
0001 forge providers not unified kept 0001 Architectural shape, an explicit no to a proposed unification, and the test the later records reuse.
0002 blank settings values normalize to unset dropped - A one-line field validator is not hard to reverse, and _settings.py already carries the rule in the comment on _blank_default_branch_is_unset. No survivor depends on it.
0003 error translators not tabled merged into 0001 0001 The same false-seam ruling at the same forge-provider boundary; the old record opened by citing 0001's test and applying it verbatim. Now one clause plus the transport-translator counter-example.
0004 outcome renderings stay split kept 0002 A different boundary: the frozen JSON wire contract against mutable human phrasing. The assert_never argument survives; the restatement of 0001's test collapses to one clause.
0005 semver-form tags only kept 0003 Changes what every managed repo is tagged with, and the v-prefix deferral is the real edge of the decision, so it is folded in rather than left as a trigger.
0006 no doctor preflight command kept 0004 An explicit no to a subsystem that shipped and was withdrawn; without it the proposal comes back.
0007 composite action does not check out kept 0005 Adding a checkout to a published composite is a behaviour change for every consumer, and the reasoning is invisible from action.yml.

Citations

  • docs/adr/0004-outcome-renderings-stay-split.md cited [ADR-0001](0001-forge-providers-not-unified.md) and [ADR-0003](0003-error-translators-not-tabled.md); as 0002 it no longer links out, since 0003's content is now inside 0001 and the shared test is stated in one clause.
  • docs/agents/domain.md listed 0002-blank-settings-values-normalize-to-unset.md in its file-structure example; it now lists 0002-outcome-renderings-stay-split.md. Its ADR-0001 (forge providers not unified) example is still correct and unchanged.
  • No Python, TOML or workflow file cites an ADR. tests/test_adr_citations.py passes, and the repo-wide sweep finds no reference to an old or dropped number.

Stale claims corrected

  • Old 0007 said the accepted cost of not checking out is the fetch-depth: 0 footgun, because actions/checkout defaults to depth 1 and "misses the tag-relative history". This is not true of the current code: semvertag/ contains no subprocess, no git library and no working-tree access at all, and GitHubProvider reads the head commit and the tag history over the REST API. 0005 now says the tool never touches the working tree and imposes no fetch-depth requirement of its own. README.md and docs/providers/github.md still tell users fetch-depth: 0 matters, which looks wrong for the same reason; that is left alone here as a docs change of its own.
  • Old 0001 described the shared pagination loop as living in semvertag/providers/_rest.py; it is _rest.collect_link_pages, with the Link-header parsing itself in semvertag/_link_pagination.py. 0001 now names the function.
  • Old 0001 called GitHub's REST API "v4". GitHub's REST API is v3 and v4 is its GraphQL API, so the version numbers are dropped rather than repeated.
  • Residue worth noting but out of scope for a docs PR: CheckResult in semvertag/_types.py and the four check_* stubs in tests/unit/test_use_case.py are leftovers from the removed doctor subsystem. The Provider protocol itself no longer carries them, which is what 0004 asserts.

Gates

Gate Result
uv run --no-sync pytest -q tests/test_adr_citations.py 7 passed
uv run --no-sync pytest -q 481 passed. tests/integration/ needs no external service: it drives the CLI against httpx2 mock transports, so nothing was skipped.
uv run --no-sync ruff format --check 70 files already formatted
uv run --no-sync ruff check --no-fix All checks passed
uv run --no-sync eof-fixer . --check clean, exit 0
lychee --offline --no-progress over the five records, docs/agents/domain.md, CONTEXT.md, AGENTS.md 3 links, 3 OK, 0 errors

No Python changed, so ruff ran over the tree unchanged rather than over a touched file.

Rewrites docs/adr/ from 7 records to 5, one paragraph each, renumbered
0001-0005 in their original order.

Dropped: 0002 blank settings values normalize to unset (reversible in one
line, and the rule is already carried by the field validator's comment in
_settings.py).

Merged: 0003 error translators not tabled into 0001, the same false-seam
ruling at the same forge-provider boundary.

Corrects a stale claim in the old 0007: semvertag reads the head commit and
tag history over the forge API and never touches the working tree, so it
imposes no fetch-depth requirement of its own.
@lesnik512
lesnik512 merged commit 2721e2d into main Sep 19, 2026
9 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:26
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.

1 participant