# Architecture decisions

This directory records the product decisions whose reversal has meaningful
cost, whose rationale would otherwise be surprising, and which involve real
alternatives.

* [Separate standards authorship from adoption execution](https://repo-standards.com/docs/decisions/0001-separate-authorship-from-adoption/):
  standards repositories supply profiles and content, while the product owns
  resolution and one adoption procedure for every author.
* [Finish authoring at a validated local standards source](https://repo-standards.com/docs/decisions/0002-finish-authoring-at-a-validated-source/):
  the authoring skill ends at a reviewed, validated local source and hands off
  publication and adoption.
* [Use agent discovery with confirmed concrete scope](https://repo-standards.com/docs/decisions/0003-use-agent-discovery-with-confirmed-concrete-scope/):
  agents propose evidence-backed file paths from author discovery guidance;
  amended by ADR 0017, adopters review the proposal with the inspection and no
  longer confirm it; superseded in part by ADR 0019, which allows discovery
  scripts; amended by ADR 0024, an update reuses a scope whose discovery
  evidence is unchanged.
* [Amend scope without redefining installed ownership](https://repo-standards.com/docs/decisions/0004-amend-scope-without-redefining-installed-ownership/):
  superseded by ADR 0009; an active run accepted confirmed additions to its
  discovered scope while keeping its selection and installed expectations.
* [Retain work evidence as identities and deltas](https://repo-standards.com/docs/decisions/0005-retain-work-evidence-as-identities-and-deltas/):
  committed state keeps each work interval as observation identities and the
  delta between them.
* [Gate standards selection with the author range only](https://repo-standards.com/docs/decisions/0006-gate-selection-with-the-author-range-only/):
  the author's CLI range is checked only when a standards version is selected
  from its source.
* [Write and read one evidence format, as identities and deltas](https://repo-standards.com/docs/decisions/0007-write-and-read-one-evidence-format/):
  every report and record carries identities and deltas in exactly one format,
  and retired formats are not read; amended by ADR 0024, an update also reads
  the previous release's durable state and scope evidence.
* [Bind confirmation identity to what the run reads](https://repo-standards.com/docs/decisions/0008-bind-confirmation-identity-to-what-the-run-reads/):
  confirmation binds the content a run reads rather than Git HEAD, the index,
  or status.
* [Correct scope by adopting again, not by amending a run](https://repo-standards.com/docs/decisions/0009-correct-scope-by-adopting-again/):
  a mistaken confirmed scope is corrected by a new run with a new scope;
  amended by ADR 0022, that run replaces the stopped one in place instead of
  needing it abandoned and resolved by hand.
* [Replace tracked content; block only untracked](https://repo-standards.com/docs/decisions/0010-replace-tracked-content-block-only-untracked/):
  the product replaces or removes tracked content at any installation target,
  lists each overwrite that discards edits in the inspection, and
  blocks only untracked content.
* [Retain only the current run](https://repo-standards.com/docs/decisions/0011-retain-only-the-current-run/):
  committed state and scope evidence hold the current run only, with its scope
  change against the previous run, so they do not grow from run to run.
* [Bind content, not location](https://repo-standards.com/docs/decisions/0012-bind-content-not-location/):
  identities and committed evidence bind the content a run reads, never the
  project root or another machine-local location; the run records the project
  root for provenance only.
* [Expose installed skills through skill links](https://repo-standards.com/docs/decisions/0013-expose-installed-skills-through-skill-links/):
  each installed skill stays in `.agents/skills`, and a product-owned link
  exposes it at `.claude/skills` for Claude Code.
* [Leave available updates to the maintainer](https://repo-standards.com/docs/decisions/0014-leave-available-updates-to-the-maintainer/):
  a product system skill reports available updates, and no standards source
  routes them; the agent starts an update only on the maintainer's instruction;
  superseded by ADR 0026 for adopters who opt in to the update action.
* [Leave delivery to standards sources](https://repo-standards.com/docs/decisions/0015-leave-delivery-to-standards-sources/):
  there is no product-owned `deliver` skill; a source that defines a
  contribution workflow ships its own, and the product offers on-demand checks.
* [Keep edited content that leaves the selection](https://repo-standards.com/docs/decisions/0016-keep-edited-content-that-leaves-the-selection/):
  an update removes a target that leaves the selection only when it matches its
  installed baseline; an edited one stays and becomes project-owned.
* [Confirm only confirmation-required changes](https://repo-standards.com/docs/decisions/0017-confirm-only-confirmation-required-changes/):
  asking to adopt is the maintainer's consent; `start` requires confirmation
  only when the inspection reports discarded edits, and a fix's overwrite of a
  chosen setting is confirmed through `resume --confirmed`.
* [Add a private Astro site workspace](https://repo-standards.com/docs/decisions/0018-add-a-private-astro-site-workspace/):
  a static website shares repository tooling and deploys independently to
  GitHub Pages from `main`; amended by ADR 0033, the Astro trial passed for
  content and static sites.
* [Run declared discovery scripts read-only during inspection](https://repo-standards.com/docs/decisions/0019-run-declared-discovery-scripts-read-only/):
  a discovery declaration may name a script, declared and bounded like a check,
  that inspection runs in a copy of the project to draft a scope proposal and
  its open questions; it never decides scope.
* [Read repository-wide rules at the start of any work](https://repo-standards.com/docs/decisions/0020-read-repository-wide-rules-at-the-start-of-work/):
  the `repository-standards` skill runs `rules` with no path at the start of
  any work, so rules that govern work changing no file reach the agent.
* [Let agents decide what Git can undo](https://repo-standards.com/docs/decisions/0021-let-agents-decide-what-git-can-undo/):
  agents decide reversible adoption choices and confirm discarded edits after
  review; remote setting overwrites remain the maintainer's decision; amended
  by ADR 0024, an update reuses a remote setup deferral while its probe still
  reports it not ready.
* [Replace a stopped run in place](https://repo-standards.com/docs/decisions/0022-replace-a-stopped-run-in-place/):
  a changed scope answer, or adopting after abandonment, starts a new run over
  the stopped run's recorded changes, whose change set covers both; a declined
  overwrite defers its fix, and abandonment exits 0.
* [Let an optional discovery declaration have no scope](https://repo-standards.com/docs/decisions/0023-let-an-optional-discovery-declaration-have-no-scope/):
  an author marks a discovery declaration optional, and a scope proposal may
  then give it no scope, which installs none of its rules and runs none of its
  operations while both scope reviews still judge it.
* [Reuse recorded answers that are provably unchanged](https://repo-standards.com/docs/decisions/0024-reuse-recorded-answers-that-are-provably-unchanged/):
  an update gives a recorded scope answer, remote setup deferral or assessment
  again without asking when what it was about is unchanged, proposes the rest
  for review, never replays a confirmation, and records every reused answer.
* [Start when nothing is open](https://repo-standards.com/docs/decisions/0025-start-when-nothing-is-open/):
  `adopt` starts the run in the invocation whose fresh inspection needs no
  confirmation, has no blocker, and leaves no question open, binding the
  identity it computed; a terminal still asks first.
* [Propose updates through one rolling pull request for adopters who opt in](https://repo-standards.com/docs/decisions/0026-propose-updates-through-one-rolling-pull-request/):
  a published GitHub action, installed by the adopter's caller workflow, runs
  the newest CLI's headless update and keeps one rolling pull request or issue
  current; the CLI still never commits.
* [Choose the platform inside each profile](https://repo-standards.com/docs/decisions/0027-choose-the-platform-inside-each-profile/):
  a profile declares the hosting platforms it supports and its
  platform-specific declarations, the project selects its platform separately
  as part of the selection, and release-source reads go through Postern.
* [Keep generated shadcn source read-only](https://repo-standards.com/docs/decisions/0028-keep-generated-shadcn-source-read-only/):
  the website's shadcn components are pinned registry output guarded by
  checksums, pages import them through `components/app/`, and shared styling
  targets their `data-slot` instead of editing them.
* [Leave archived run/v6 reports unread](https://repo-standards.com/docs/decisions/0029-leave-archived-run-v6-reports-unread/):
  run reports CLI 9.0.0 archived in Git's directory are skipped by every reader,
  never moved or converted, so they no longer block an update.
* [Localize the website through MessageFormat 2 catalogs](https://repo-standards.com/docs/decisions/0030-localize-the-site-through-mf2-catalogs/):
  the site's strings are MF2 messages in per-area catalogs and per-locale prose
  behind one `format()`, with no runtime fallback, a parity and staleness check,
  English at the root and other locales under their own prefix, while agent
  surfaces, the CLI and `/docs/` stay English.
* [Give every site page one nav shaped like the docs' header](https://repo-standards.com/docs/decisions/0031-give-every-site-page-one-nav/):
  one shared nav on every page outside the docs, a full-width bar like
  Starlight's header with the same plate, its items ordered from near to far
  with Support the one emphasized control, and on a phone the plate, Support
  and one menu; amended by ADR 0032, that menu opens as a sheet under the
  header.
* [Open the phone nav as a sheet under the header](https://repo-standards.com/docs/decisions/0032-open-the-phone-nav-as-a-sheet-under-the-header/):
  on a phone, the nav's menu button opens a sheet of links under the header,
  with one language selector and the theme icon in a row below them, over the
  dimmed page, as a disclosure navigation rather than a menu.
* [Keep Astro for content and static sites](https://repo-standards.com/docs/decisions/0033-keep-astro-for-content-and-static-sites/):
  the Astro trial passed for content and static sites, which use Astro, while
  client-side apps use Vite with React; `site/` is in Repo Canon's
  `typescript-astro` stack.
* [Select check location beside platform](https://repo-standards.com/docs/decisions/0034-select-check-location-beside-platform/):
  profiles offer one independent check-location choice and declarations filter
  on it before scope, preserving legacy GitHub behavior.
* [Keep one copy of installed exact content](https://repo-standards.com/docs/decisions/0036-keep-one-copy-of-installed-exact-content/):
  retained inputs record installed exact files' and skills' hashes, fall back
  to the verified source snapshot for an edited target, and keep copies only
  for files that checks, fixes, probes or discovery scripts run or read.
