docs(adr): compress to 5 records in the domain-modeling format - #74
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites
docs/adr/from 7 records (~2,570 words) to 5 (~780 words), one paragraph each, in the shapeADR-FORMAT.mdasks 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.
_settings.pyalready carries the rule in the comment on_blank_default_branch_is_unset. No survivor depends on it.assert_neverargument survives; the restatement of 0001's test collapses to one clause.v-prefix deferral is the real edge of the decision, so it is folded in rather than left as a trigger.action.yml.Citations
docs/adr/0004-outcome-renderings-stay-split.mdcited[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.mdlisted0002-blank-settings-values-normalize-to-unset.mdin its file-structure example; it now lists0002-outcome-renderings-stay-split.md. ItsADR-0001 (forge providers not unified)example is still correct and unchanged.tests/test_adr_citations.pypasses, and the repo-wide sweep finds no reference to an old or dropped number.Stale claims corrected
fetch-depth: 0footgun, becauseactions/checkoutdefaults to depth 1 and "misses the tag-relative history". This is not true of the current code:semvertag/contains nosubprocess, no git library and no working-tree access at all, andGitHubProviderreads the head commit and the tag history over the REST API. 0005 now says the tool never touches the working tree and imposes nofetch-depthrequirement of its own.README.mdanddocs/providers/github.mdstill tell usersfetch-depth: 0matters, which looks wrong for the same reason; that is left alone here as a docs change of its own.semvertag/providers/_rest.py; it is_rest.collect_link_pages, with the Link-header parsing itself insemvertag/_link_pagination.py. 0001 now names the function.CheckResultinsemvertag/_types.pyand the fourcheck_*stubs intests/unit/test_use_case.pyare leftovers from the removeddoctorsubsystem. TheProviderprotocol itself no longer carries them, which is what 0004 asserts.Gates
uv run --no-sync pytest -q tests/test_adr_citations.pyuv run --no-sync pytest -qtests/integration/needs no external service: it drives the CLI againsthttpx2mock transports, so nothing was skipped.uv run --no-sync ruff format --checkuv run --no-sync ruff check --no-fixuv run --no-sync eof-fixer . --checklychee --offline --no-progressover the five records,docs/agents/domain.md,CONTEXT.md,AGENTS.mdNo Python changed, so
ruffran over the tree unchanged rather than over a touched file.