# Adoption run reference

This page is the contract for `adopt` and the adoption run it drives: its
command line, answers file, results, lower-level commands, durable state,
completion and recovery. The [adoption guide](https://repo-standards.com/docs/guides/adopt/) and the
[update guide](https://repo-standards.com/docs/guides/update/) walk through the same steps as tasks.

`adopt` drives [inspection](https://repo-standards.com/docs/reference/inspection/), [inspect and start](https://repo-standards.com/docs/reference/adoption-run/#inspect-and-start),
and [resume](https://repo-standards.com/docs/reference/adoption-run/#recover-or-abandon-an-interrupted-run). These remain available
for callers that need the lower-level adoption run interface described below.
The [script protocol](https://repo-standards.com/docs/reference/script-protocol/) defines author operations; the
[assessment protocol](https://repo-standards.com/docs/reference/assessment-protocol/) defines contextual work evidence.
Neither protocol needs to be read to start with `adopt`.

## The `adopt` command

The full form is `adopt [<GitHub URL>] [--standards-version <tag>] [--profile <name>] [--platform <name>] [--checks <value>] [--answers <file>] [--project <directory>] [--json]`. In an
adopted project, `adopt` without a source updates the current selection. When
the source cannot be reached, it proposes the current version and profile and
applies them again from the retained standards, as `inspect` and `start` do
without source flags; its report says so next to the selection. When GitHub
refuses to list the source's releases because the API quota is exhausted or it
rejected the token in `GH_TOKEN` or `GITHUB_TOKEN`, `adopt` fails with
`QUOTA_EXHAUSTED` or `SOURCE_UNAVAILABLE` and writes nothing instead. To apply
the current version again on purpose, pass it with
`--standards-version <current version>`, which still applies it from the
retained standards when the source cannot be read.

Run with a terminal as its input and output, and without `--answers` or
`--json`, `adopt` asks a person its questions; see [In a terminal](https://repo-standards.com/docs/guides/adopt/#in-a-terminal).
Otherwise, with or without an answers file, `adopt` inspects the selection it
proposes, running what inspection runs: remote setup readiness probes and, when
discovery is required, declared discovery scripts. It starts the run in that
same invocation, bound to the inspection it just computed, once all of these
hold:

* The inspection requires no confirmation.
* Nothing [blocks](https://repo-standards.com/docs/reference/inspection/#report-and-inspection-identity) the start, and
  no `remote-setup` answer is `resolve`.
* No question is open. The answers file answers a question, a
  [reused answer](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) does, and so does a default `adopt` proposes
  as the answer: the version, the profile, and a
  [platform](https://repo-standards.com/docs/reference/adoption-run/#choose-the-hosting-platform) carried forward or detected. A
  scope draft, or a recorded
  answer proposed for review, stays open until an answers file carries it
  back, with or without an answers file.

Otherwise `adopt` prints its questions as an answers-file template, with the
inspection and the next steps, and changes nothing, or reports the blocker as
`blocked`. The agent saves the template outside the project, records its
decisions, and runs `adopt --answers <file>`. Project files stay unedited until
the run starts; files implied by answers are written during contextual work.
With a filled answers file, `adopt` names each missing answer, asks the
questions that follow from the answers, and starts the run once none remain and
nothing blocks it. A question that depends on an answer appears once that
answer is given: the profile's questions follow the profile, and remote setup
readiness follows a complete scope, since inspection probes only an unblocked
selection. The report of a run started this way carries the inspection it
carried out, so the agent summarizes it in the handoff afterwards; Git can undo
its uncommitted result. To preview an adoption without starting it, use
[`inspect`](https://repo-standards.com/docs/reference/adoption-run/#inspect-and-start). When the inspection requires confirmation,
the run starts only when the answers file names its identity in `confirmation`
and in `inspection`; a stale identity stays missing, and the agent reviews the
current inspection before starting.

`adopt` installs the exact CLI that ran it into the project's
[runtime](https://repo-standards.com/docs/reference/adoption-run/#durable-and-local-state) and records it as the CLI pin. Ordinary
projects need no external installation. Before a run, its next steps name the
same exact CLI through `npx`, except for the
[product checkout collision](https://repo-standards.com/docs/guides/adopt/#adopting-in-the-product-checkout); once a run has installed the pinned runtime,
`.repo-standards/runtime/node_modules/.bin/repo-standards`, they continue and
recover the run with it. With an active run,
`adopt --answers <file>` continues it, advancing it by at most one step: a
confirmed fix, or submitted assessments. A source, version, profile, or
platform or check location that differs from the active run's selection fails with `ACTIVE_RUN`.

### Choose the hosting platform

A profile names the hosting platforms it supports, and the project selects its
platform separately from its profile; see
[platforms](https://repo-standards.com/docs/reference/author-format/#platforms). The selected platform decides which
platform-specific declarations the profile adopts. GitHub is the only platform
this CLI supports, so every profile supports `github` alone today, and
published files stay GitHub-shaped.

* A profile that supports one platform selects it without asking and without
  looking at the project's remote. A project without a remote, or with one on
  another host, adopts as before, and no `platform` question appears.
* A profile that supports several platforms asks the `platform` question. An
  answer or `--platform` chooses it, and must be one of the profile's
  platforms, or `adopt` fails with `UNKNOWN_PLATFORM`. Without one, the
  platform the project recorded is carried forward while the profile still
  supports it. Otherwise the `origin` remote's URL proposes the platform it is
  hosted on, which answers the question in an answers file or template and
  which a terminal asks the person to confirm or override. Without an `origin`
  remote, or with one no supported platform serves or the profile does not
  support, the question stays missing until it is answered, and its
  `details` say why.

The platform is part of the selection: the lock and `selection.yaml` record
it, the inspection's identity binds it, and changing it in an update is a
changed selection component that replaces the previous platform's
declarations. An inspection or confirmation of another platform does not start
a run. A selection recorded before platforms existed is read as `github`, and
the next run records it.

### Choose the check location

Select exactly one offered [check location](https://repo-standards.com/docs/reference/author-format/#check-locations)
with `--checks github|runner|self-reported` or the answers-file `checks`
question. These are alternatives: pass one value, not the pipe-separated list.
A sole offered value needs no question; otherwise a supported recorded choice
carries forward, and without one `adopt` asks. A terminal presents the same
choice. Hosting platform detection never chooses a check location.
An explicit unknown or unoffered value fails with `UNKNOWN_CHECK_LOCATION`
before adoption writes; flag/answer conflicts fail under the ordinary selection
answer validation. Omitting the profile's offer means `github` alone.

The selection, lock, inspection identity, run, status, retained inputs and
script requests carry `checks`. A supported previous selection without it
means `github`, and the next completed run writes it explicitly. Retained and
offline adoption preserve it. An inspection or confirmation for one location
cannot start another; an active run cannot change it. A deliberate update
re-resolves declarations, reports `checks` as a changed component and reports
the resulting additions and removals under ordinary target ownership.

A headless update keeps the recorded check location while supported; otherwise
it stops for an explicit `checks` answer before writes, even when the new
profile offers only one location. It rejects `--checks`, just as it rejects
`--platform`. Continue the report's answers file with ordinary `adopt`.

### Reused answers

An update carries the last complete adoption's recorded answers forward
([ADR 0024](https://github.com/lutzseverino/repo-standards/blob/main/docs/adr/0024-reuse-recorded-answers-that-are-provably-unchanged.md)).
Inspection, discovery scripts and readiness probes still run fresh, and each
recorded answer is reused without asking only when what it was about is
provably unchanged:

* A `scope:<declaration>` answer, when the declaration's discovery guidance and
  rules are hash-identical to the recorded ones, its discovery script's fresh
  draft equals the draft the recorded entry was decided from, and every
  candidate and evidence path the entry names still exists, with evidence for
  every candidate. A declaration
  without a discovery script has no draft. Both readable scope-evidence formats
  retain the drafts. The inspection binds a reused entry as it binds any scope
  answer.
* The `remote-setup` answer `defer`, when every remote setup that is not ready
  was deferred as remote setup and its probe, with an unchanged script,
  arguments, resources and prerequisite, still reports it not ready. The run
  records the deferral with the fresh reason. When any of them was deferred
  but not all are eligible, `defer` is proposed for review instead.
* An `assessment:<declaration>` answer, when the declaration's rules, or its
  adoption guidance when it has no rules, and the files in its scope are
  unchanged since the last complete adoption, judged after the run's fixes, so
  a fix that changes a scoped file makes it ineligible. The older readable `state/v7` proves this only by the whole project's work
  snapshot. When every assessment is reused, the run goes straight to its
  checks.

The report lists each reused answer in `reused`, with what made it eligible,
and its question's `details.reused` holds the same evidence. Every other
recorded answer comes back prefilled for review: its question's context names
what changed and its `details.changed` lists it; a scope question's
`details.draft` holds the fresh draft. It stays missing until the answers file
carries it back, which needs no other confirmation. A `confirmation`, a `fix:`
overwrite answer, and a fix deferred because the maintainer declined its
overwrite are never reused, and `version` and `profile` keep their proposals.
An answer of your own replaces a reused one and is not listed as reused; an
answer equal to the reused one keeps it reused. The run record, durable state,
`status`, and the adoption record list every reused answer.

### Update headlessly

`adopt --headless` updates an established adoption without asking anybody,
even at a terminal, so that a scheduled job or other unattended caller can run
it:

```sh
.repo-standards/runtime/node_modules/.bin/repo-standards adopt --headless --json
```

It keeps the recorded source, profile and
[platform](https://repo-standards.com/docs/reference/adoption-run/#choose-the-hosting-platform) and takes the newest stable standards
release, or the tag `--standards-version` names; the CLI pin is the CLI that
runs it, as for any `adopt`. It takes no source, `--profile`, `--platform`, or
`--answers`,
and rejects them as invalid usage. In a project with no established adoption
it fails before changing anything, naming the initial `adopt <source>`. It
fails when the source's releases cannot be read, rather than applying the
current version again.

Its only answers are the [reused answers](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) and the defaults a
template proposes. It never accepts an answer proposed for review, never
answers `confirmation`, and never answers a `fix:` question. It defers every
[remote setup](https://repo-standards.com/docs/reference/adoption-run/#remote-setup), ready or not: the run runs neither the fix nor
its prerequisite probe, and records the deferral with a reason that says a
headless update never writes to the hosting platform and the next local
`adopt` applies it once its probe is ready. A deferral of remote setup whose
probe was ready is not reused later, because reuse needs the probe to still
report it not ready. The CLI makes no commit, push, branch, pull request, or
issue, and uses the network only for the source and release reads and the
npm runtime acquisition that every `adopt` makes, with `GH_TOKEN` or
`GITHUB_TOKEN` as [GitHub requests and tokens](https://repo-standards.com/docs/reference/github-requests/) describes.

With every answer reused, nothing blocking, and no confirmation required, it
completes in one invocation and exits 0, with its changes uncommitted and
unstaged and `status` reporting them ready to commit. Otherwise it exits 1 with
the `adopt` report, as JSON with `--json`, whose `outcome`, `missing`,
`blockers`, `answers`, including answers proposed for review, and `contextual`
are its open questions. The report carries `headless: true` and lists the
remote setup it defers in `deferred`. It stops:

* Before writing anything, leaving the working tree, HEAD, and index
  unchanged, when a confirmation-required change, an answer proposed for
  review, a profile the source no longer offers, a platform the profile no
  longer supports, or a start blocker is open.
* With the run active, when the run reaches contextual work whose assessments
  are not reused, or a fix returns `confirmation-required`.

To finish it, save the report's answers file outside the project, answer its
open questions, and run `adopt --answers <file>` in the same checkout, as its
next steps describe; an agent or a person can do this. A run it left active
keeps deferring its remote setup. Before a run, that `adopt` starts an ordinary
run, which applies each remote setup whose probe is ready. `adopt --headless`
over an active run only reports it.

## Answers file

The answers file, `repo-standards/answers/v2`, is the JSON object `adopt`
prints: `format`, the `source` URL, and `questions`. Each question has an `id`,
the `question` to ask, its `context`, optional `choices` and `details`, and an
`answer`, which is `null` until answered. `adopt` reads only each question's
`id` and `answer`, and ignores the answer to a question it does not ask at
that stage, such as one for a declaration of another profile. It rejects other
fields, an ID of no question kind below, a repeated ID, and an answer of the
wrong kind with `ANSWERS_FORMAT`, and an answers file inside the project with
`ANSWERS_LOCATION`. A file of at most 2 MiB is read.

| `id`                       | Asked when                                                                                   | `answer`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`                  | Always; the template proposes the newest stable release.                                     | A stable tag from `choices`, the source's stable releases newest first.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `profile`                  | Always; proposed for an update or a single profile.                                          | A profile `name` from `choices`, each with its `description`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `platform`                 | Once a profile that supports several platforms is chosen.                                    | A platform from `choices`, the profile's platforms. The recorded platform is carried forward while the profile supports it, and otherwise the `origin` remote's platform is proposed, with `details.detected`; without either, `details.reason` is `no-remote` or `unsupported`. See [Choose the hosting platform](https://repo-standards.com/docs/reference/adoption-run/#choose-the-hosting-platform).                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scope:<declaration>`      | For each active discovery declaration, and while a run is stopped for its scope.             | Its [scope entry](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope) without `id`: `coverage`, `candidates`, and `unresolved`, and `noScope` for [no scope](https://repo-standards.com/docs/reference/inspection/#no-scope), which an optional declaration's question offers with `details.optional`. A discovery script's draft is proposed, and it stays missing in every mode, the template included, while it has open questions or until an answers file carries it back. In an update, a [reused](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) recorded entry is answered, and one proposed for review stays missing until carried back. A stopped run proposes its confirmed entry, and a changed one [replaces the run in place](https://repo-standards.com/docs/reference/adoption-run/#adopt-again-in-place). |
| `checks`                   | When the profile offers several locations, or a headless update loses its recorded location. | One offered location: `github`, `runner` or `self-reported`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `remote-setup`             | When a remote setup probe is not ready.                                                      | `defer` to complete adoption without it, or `resolve` to stop, writing nothing. In an update, a [reused](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) deferral is answered `defer`, and a recorded deferral whose probe changed, or beside remote setup it never deferred, is proposed as `defer` and stays missing until carried back.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `confirmation`             | When the inspection requires confirmation.                                                   | The inspection identity confirmed after reviewing discarded edits, by the agent or a person at a terminal. `details` names the identity and the discarded edits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `inspection`               | Once inspected; the template carries the identity.                                           | The identity of the inspection the answers file was written against. When the inspection requires confirmation, a run starts only when it names the current inspection, and a new or changed inspection is printed again for review first. Otherwise it is never missing: the run binds the fresh inspection, whatever identity the answer names. A terminal always asks before starting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `fix:<declaration>/<fix>`  | When a fix stopped the run for confirmation.                                                 | One of `choices`: the run's inspection identity, once the maintainer confirms the overwrite its `context` names, or `defer`, once they decline it, which [defers the fix](https://repo-standards.com/docs/reference/adoption-run/#defer-a-declined-overwrite).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `assessment:<declaration>` | For each declaration of contextual work.                                                     | Its [assessment](https://repo-standards.com/docs/reference/assessment-protocol/#assessment-submission) judgment without `id`: `status`, `explanation`, `evidence`, and `scopeValidity` for a discovered declaration. `details.noScope` marks a declaration with no scope, which allows no edit. A [reused](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) recorded judgment is answered; one proposed for review stays missing until the answers file carries an answer.                                                                                                                                                                                                                                                                                                                                                                                     |

The question's ID names the declaration of a `scope:` or `assessment:`
answer; an `id` inside the answer is ignored. An answers file confirms a
confirmation-required change only by naming the identity the agent reviewed for
discarded edits, or the maintainer confirmed for a remote setting overwrite. An answer naming another identity, such as
one confirmed before the inspection changed, stays missing, and the run does
not start or continue. Without a confirmation-required change, the run starts
whatever identity `inspection` names. Version, profile and platform flags must
agree with the answers file, and so must a source given with it.

## Stages and results

`adopt` prints Markdown for the agent: what it needs, the selection, missing
answers, blockers, the inspection summary with each discarded edit's diff, or what replaces a skill or skill link it has none for, the
discovery and adoption guidance of discovery declarations, the run and its
failed checks, each contextual declaration's installed rules and adoption
guidance, the reused answers, the answers file, and the next steps. `--json`
prints the same as a `repo-standards/adopt/v3` report, whose `reused` lists
each [reused answer](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) by question `id`, `kind`, and the
`evidence` that made it eligible. A [headless update's](https://repo-standards.com/docs/reference/adoption-run/#update-headlessly)
report also carries `headless: true` and `deferred`, each fix its run defers,
or before a run would defer, by `declaration`, fix `id`, and `reason`. Its
`outcome` is one of:

| `outcome`          | Meaning                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `answers-required` | Questions in `missing` need answers, including a fix's confirmation or deferral in an active run; before a run, nothing was changed.                                                                                            |
| `blocked`          | Inspection `blockers`, a `resolve` remote setup answer, or a start that stopped before writing anything, with its `run.reason`.                                                                                                 |
| `contextual`       | The run waits for contextual work: `contextual` lists each declaration's allowed targets, rules, and adoption guidance, and `failedChecks` each failure of the latest check round, which cites its rules in the run's `reason`. |
| `complete`         | The run completed; its changes are uncommitted.                                                                                                                                                                                 |
| `incomplete`       | The run needs recovery, such as a repeat-safe retry or a changed scope answer that replaces it in place, or the maintainer's decision about abandonment.                                                                        |

For contextual work, the agent edits the allowed targets, answers each
`assessment:<declaration>`, and runs `adopt --answers <file>` with the pinned
runtime. It refreshes the work request at the current project, submits the
assessments, and runs the checks. A run that has just reached contextual work
asks for new assessments, except those it reuses, which are answered with the
recorded judgment; after failed checks, the answers just submitted are carried
for renewal. A reused assessment whose scoped files the contextual work changes
is proposed for review again instead of submitted. Without a terminal, `adopt` never retries or abandons a
run itself: its next steps name the pinned `resume --retry`, which the agent
runs without asking because its operations are repeat-safe, and `abandon`,
which needs the maintainer's instruction. A run stopped for its scope carries
its `scope:<declaration>` questions, answered with its confirmed scope; a
changed answer [replaces the run in place](https://repo-standards.com/docs/reference/adoption-run/#adopt-again-in-place).

Exit status is 0 for a complete run and for a template printed without an
answers file because a question is open, 1 for every other result or rejection, including every
headless update that stops, 2 for invalid usage, and
130 for a terminal session the person interrupted.
Rejections use the common `valid: false` / `errors` diagnostic format with
`--json`.

## Inspect and start

[`adopt`](https://repo-standards.com/docs/guides/adopt/#adopt-with-one-command) drives these commands and needs no CLI
installed outside the project. To run them yourself, use Node.js 24 or 26, npm, Git,
and an [externally installed exact CLI](https://repo-standards.com/docs/reference/inspection/#keep-the-disclosed-cli-for-start-and-recovery).
First inspect the public GitHub selection:

```sh
repo-standards inspect --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.2.3 --profile work --json
```

The report lists the pins, proposed replacements and the edits they discard,
matching files and skills, whole-skill inventories, guidance, declared fixes and
checks, prerequisites, and blockers. Use the same CLI version and selection to
start, passing the report's `identity` verbatim:

```sh
repo-standards start --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.2.3 --profile work \
  --identity 'sha256:INSPECTION_HASH' --json
```

For discovery-backed initial adoption, follow the [two-pass inspection](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope), then pass the same `--scope <file>` proposal with the complete inspection's identity to `start`. Missing, invalid, unresolved or stale scope blocks mutation.

Both commands accept `--project <directory>` and default to the current Git
working tree. Store inspection reports outside the project to keep it clean.

### Confirmation-required changes

Asking to adopt or update a selection is the maintainer's consent, so most runs
start with the identity alone. An agent reviews and confirms discarded edits
recoverable from Git; a fix's remote setting overwrite waits for the maintainer
because Git cannot restore that state. Inspection finds the discarded edits: the
report's [`confirmation`](https://repo-standards.com/docs/reference/inspection/#report-and-inspection-identity) says
whether the run discards any, with one reason for each target in
`discardedEdits`, at an initial adoption as at an update. Breaking source changes, scope proposals,
removing retired product state, and removing unedited installed content need
no confirmation.

When `confirmation.required` is true, `start` without `--confirmed` fails with
`CONFIRMATION_REQUIRED`, naming each discarded edit, and changes nothing. After
the discarded edits have been reviewed and confirmed, start the same inspection with
`--confirmed` added:

```sh
repo-standards start --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.2.3 --profile work \
  --identity 'sha256:INSPECTION_HASH' --confirmed --json
```

`start` accepts `--confirmed` only when the inspection requires it, and fails
with `CONFIRMATION_NOT_REQUIRED` otherwise. For discarded edits, the agent
confirms after reviewing what Git can restore; a person using the terminal
confirms their own review. The CLI enforces the identity, but cannot verify
that review occurred. The identity binds every start,
confirmed or not: a project that changed since inspection fails with
`STALE_INSPECTION` either way.

Inspection runs no fix, so it cannot see the settings a fix would
overwrite. A fix that would change or remove an existing setting holding a
different value instead returns `confirmation-required`, having changed
nothing, with a message naming the setting and both values; creating a missing
setting needs no confirmation. The [script protocol](https://repo-standards.com/docs/reference/script-protocol/#overwriting-a-setting)
defines the result. The run stops there, resumably: it stays incomplete in the
`fixes` phase, with a `reason` starting `CONFIRMATION_REQUIRED:` that names the
fix and its message, the fix's result in `operations`, and a `nextAction`
naming `resume --confirmed`. After the maintainer confirms that overwrite,
continue the run:

```sh
repo-standards resume --confirmed --json
```

It reruns that fix with `overwriteAllowed: true`, then the fixes after it,
which may each stop for their own confirmation, and continues as the run
would have, to contextual work or checks and completion. Fixes accepted before
the stop are not run again. Without confirmation the run stays stopped: plain
`resume` and `resume --assessment` fail with `CONFIRMATION_REQUIRED` and change
nothing, `resume --retry` repeats the fixes and stops at the same fix again,
and `abandon` ends the run as it ends any other. `resume --confirmed` is
accepted only by a run stopped for a fix's confirmation, failing with
`CONFIRMATION_NOT_REQUIRED` otherwise, and cannot be combined with `--retry` or
`--assessment`.

### Defer a declined overwrite

When the maintainer declines the overwrite, defer the fix instead of ending
the run:

```sh
repo-standards resume --defer --json
```

`adopt` does the same for the answer `defer` to the fix's `fix:<declaration>/<id>`
question, and its terminal for the choice `defer`. The run records the whole
fix as deferred, never as a script result, with the reason
`The maintainer declined the overwrite:` followed by the fix's message, which
names each declined setting. It then continues with the fixes after it, to
contextual work or checks and completion, as a confirmed fix would. A retry
of the same run skips the deferred fix. At completion, durable state keeps the
deferral in `deferred`, which `status --json` reports and the adoption record's
Operations table lists with the result `deferred`, as it lists
[deferred remote setup](https://repo-standards.com/docs/reference/adoption-run/#remote-setup). Every later run runs the fix again and
stops again for confirmation while the setting still differs. `resume --defer`
is accepted only by a run stopped for a fix's confirmation, failing with
`CONFIRMATION_NOT_REQUIRED` otherwise, and cannot be combined with `--retry`,
`--assessment`, or `--confirmed`. A fix applies whole or not at all: no run
creates a fix's missing settings while skipping its overwrites.

### Remote setup

A fix that changes the hosting platform's settings, such as its labels or merge
rules, can declare itself [remote setup](https://repo-standards.com/docs/reference/author-format/#remote-setup), with a
readiness probe. Inspection runs every remote setup probe before anything is
written and reports each one in
[`remoteSetup`](https://repo-standards.com/docs/reference/inspection/#remote-setup-readiness) as ready, or not ready
with the probe's reason, such as a missing tool, remote, sign-in, or role.

When every remote setup is ready, the run applies each one as it applies any
fix. When one is not ready, `start` fails with `REMOTE_SETUP_NOT_READY`, naming
each such fix and its reason, and writes nothing, not even a run record.
Resolve the reason and inspect again, or defer remote setup and complete
adoption locally:

```sh
repo-standards start --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.2.3 --profile work \
  --identity 'sha256:INSPECTION_HASH' --defer-remote-setup --json
```

`--defer-remote-setup` defers each remote setup that is not ready and changes
nothing for one that is ready. A deferred remote setup runs neither its fix nor
its fix's prerequisite probe. The CLI records it as deferred, not as a script
result, with the probe's reason: in the run's `deferred`, and at completion in
durable state, where `status --json` reports it as `deferred` and the adoption
record's Operations table lists it with the result `deferred`; see
[summarize status](https://repo-standards.com/docs/reference/adoption-run/#summarize-status). A
[headless update](https://repo-standards.com/docs/reference/adoption-run/#update-headlessly) defers every remote setup, ready or not,
in the same way, with a reason saying that it never writes to the hosting
platform and the next local `adopt` applies it. Retry and recovery keep the deferral its
start chose. A retry of a start interrupted before installation repeats the
inspection, probes included, and its identity check, so a probe whose answer
changed since inspection makes it stale like any other change; nothing was
installed yet, so abandon the run and inspect again.

Every later run, an update or the unchanged selection applied again, probes
every remote setup again, including deferred ones. A ready one runs as any fix
does, and the completion that follows records no deferral for it. One still
not ready stops the run again unless it is deferred again; `adopt`
[reuses](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) the recorded deferral while the same probe still
reports it not ready. Remote setup names no platform; the probe decides
readiness.

## Update the selection

An update is one inspected run from the current selection to a
candidate selection. The candidate can change the CLI pin, the standards pin,
the source, the profile, the platform, the check location, any combination of them, or none of them. The
inspection report lists every changed component together with the previous
selection. `adopt` drives the same inspect and start sequence, with
[confirmation](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes) only when the report requires it.
The report also states whether the update is an exact update, which changes
only exact content, skills, or the selection, or a contextual update, which
changes guidance, a contextual declaration's rules, discovery guidance,
operations, retired declarations, or confirmed scope; see [update class](https://repo-standards.com/docs/reference/inspection/#report-and-inspection-identity).
`inspect --summary` renders the report as a [Markdown proposal](https://repo-standards.com/docs/reference/inspection/#markdown-summary).

An update that keeps the CLI pin requires its installed runtime dependencies,
including when reapplying the retained selection. In a fresh clone, run
`npm ci --ignore-scripts --prefix .repo-standards/runtime` from the project root
before starting. Otherwise inspection reports `RUNTIME_MISSING`, and `adopt`
and lower-level `start` stop without starting a run or installing source material.
After restoration, rerun adoption with the matching project-pinned CLI and the
same requested selection and answers. This prerequisite does not replace the
runtime integrity checks of an already-started run.

To select a standards version, source, or profile, pass all three source flags,
and `--platform <name>` to select a platform of a profile that supports
several. With the currently pinned CLI:

```sh
.repo-standards/runtime/node_modules/.bin/repo-standards inspect \
  --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.3.0 --profile work --json
.repo-standards/runtime/node_modules/.bin/repo-standards start \
  --source https://github.com/OWNER/STANDARDS \
  --standards-version v1.3.0 --profile work \
  --identity 'sha256:INSPECTION_HASH' --json
```

To change the CLI pin, obtain the candidate exact CLI outside the project and
run it in place of the pinned executable. Omit the source flags to keep the
retained standards, or pass them to change the standards version, source, or
profile in the same run:

```sh
candidate_dir="$HOME/.local/share/repo-standards/cli-10.0.0"
mkdir -p "$candidate_dir"
(cd "$candidate_dir" && npm install --prefix "$candidate_dir" \
  --ignore-scripts --save-exact --no-audit --no-fund \
  @lutzseverino/repo-standards@10.0.0)
"$candidate_dir/node_modules/.bin/repo-standards" inspect --json
```

Keep that directory outside the adopting project. Start with the same
candidate executable and flags:

```sh
"$candidate_dir/node_modules/.bin/repo-standards" start \
  --identity 'sha256:INSPECTION_HASH' --json
```

The bootstrap provides temporary inspection only. Keep the external candidate
available for retry if installation interrupts before the project runtime is
usable. Once adoption completes, use the new project-pinned CLI normally.

To apply the unchanged selection again, for example after the repository gains
content its standards should cover, run the pinned CLI without source flags:

```sh
.repo-standards/runtime/node_modules/.bin/repo-standards inspect --json
.repo-standards/runtime/node_modules/.bin/repo-standards start \
  --identity 'sha256:INSPECTION_HASH' --json
```

Without source flags, inspection and start resolve the selection from retained
inputs, so the original standards repository can be unavailable. Selecting a
standards version, source, or profile requires its public source. The author's
`requires.repo-standards` range is checked only when a standards version is
selected from its source. Retained inputs are validated against the running
CLI's supported source formats, so a CLI update from retained inputs succeeds
even when the retained range excludes the candidate version.

When the candidate profile has active discovery declarations, including an
unchanged selection, the first inspection requires fresh project evidence.
Build a new `--scope` proposal and pass it to both the complete inspection and
its start; `adopt` builds it from the recorded entries it
[reuses](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) and the answers it asks for. The report lists discovered-scope additions and removals
relative to the prior complete adoption; removed scope ends governance without
deleting that project-owned content.

Every update applies inspection freshness, confirmation, Git-state, prerequisite,
compatibility, and ownership checks before mutation, then uses the normal
fixes, contextual assessment, checks, integrity verification, recovery, and
abandonment behavior. It replaces the retained inputs and still-declared exact
content and whole skills, including removal of obsolete skill resources.
Retired and excluded declarations, including those a changed source or profile
no longer declares, leave the new baselines and no longer contribute
operations. The run removes each of their installed targets that still matches
its installed baseline. An edited one stays in place and the project owns it:
the inspection lists it in `kept`, durable state no longer records it, and
later runs neither track nor remove it. A skill with any edited file stays
whole, with its link. An installed target
within contextual scope, as a contextual target or inside or containing one, is
not removed and stays in place as project content. Only a changed CLI pin
replaces the isolated runtime manifests, npm lock, dependencies, and matching
product-owned system skills; otherwise the existing runtime remains, and each
system skill is matched, created, or replaced with the one the pinned CLI
packages.
Project dependency manifests and package-manager choices remain outside that
runtime. An incomplete run retains the prior last-complete evidence.

Tracked content at an installation target never blocks: the run replaces it, or
removes it when the selection no longer installs the target and the project
has not edited it, and the
inspection lists each replacement or removal that discards content other than
the target's installed baseline, each one a
[confirmation-required change](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes). Git keeps what
it discards. Only ignored or
untracked content, which Git cannot recover, blocks with
`UNTRACKED_REPLACEMENT`. There is no universal rollback. Only a
complete run advances last-complete state and new baselines. Every update
leaves HEAD unchanged and its actual changes uncommitted for the project's
normal workflow.

Start requires the same content-derived inspection identity, an existing
commit, clean index and working tree, no non-ignored untracked files, safe targets,
and recoverable replacement content. Git flags
that hide changes block start. Submodules outside adoption targets are allowed
only when initialized, recursively clean, and at each immediate parent's
recorded gitlink commit. Uninitialized submodules require manual initialization;
dirty, mismatched, unsafe or unreadable nested state blocks with its path.
Observation disables hooks, filters and fsmonitor, makes no network request,
and writes no index refresh or lock files. The CLI never initializes, fetches,
resets or cleans submodules. Discovery excludes their contents; targets at,
inside, or containing a gitlink, and targets changing `.gitmodules`, are rejected,
including replacement and removal targets without checkout metadata. Inspection
rechecks recursive state before returning, and start freshly revalidates before
project writes, including when an older inspection was eligible. These checks
do not bind every clean submodule commit to the content-derived identity.
See the [inspection submodule policy](https://repo-standards.com/docs/reference/inspection/#inspect-with-an-already-installed-exact-cli)
for the state matrix and safety boundary; standards-source submodules remain
unsupported. Existing
exact files and skill directories whose complete inventory, bytes, and
executable state match the supplied content are matched without rewriting and
recorded in the new baselines. This includes a system skill when it matches
the skill packaged with this exact CLI. A differing tracked file or skill,
including a system skill, is replaced and listed among the discarded
edits; unrelated and excluded content remains outside the selection.

The identity binds what the run reads, not Git HEAD or where the project is
checked out: a commit between inspection and start that touches no affected
file, retained input, or durable product state leaves the identity valid,
and an inspection made in another clone of the same content starts a run in
this one. The run records the project root and HEAD at start in its `root` and
`head` fields for provenance, and completion records only HEAD, in the state's
`lastComplete.head`; the root is never committed. HEAD and the index must then
stay unchanged until the run completes. Inspection and run reports carry hash
inventories and diffs rather than file bytes; start acquires the source again
and installs only bytes that match the inspected hashes. See
[the inspection report](https://repo-standards.com/docs/reference/inspection/#report-and-inspection-identity).

Before installation, start probes every declared prerequisite using its literal
version arguments from the project root. It reports all missing executables,
failed probes, unreadable versions, and incompatible versions without installing
prerequisites. Inspection itself never probes them. The trusted script contract
and detailed failure behavior are documented in [Script protocol](https://repo-standards.com/docs/reference/script-protocol/).

The CLI prepares the exact runtime outside the project with npm lifecycle
scripts disabled. The project's dependency manifest, package manager, and
`.npmrc` do not govern this installation. The configured external npm cache is
reused, including for offline acquisition of cached packages. As with the
bootstrap, content-cache symlinks are rejected and logs stay in temporary
storage so cache settings cannot redirect acquisition into the project.
After acquisition, start reacquires
the immutable source and repeats all freshness and safety checks under an
exclusive run lock. Each write checks target ancestors again. Failed preflight
or acquisition leaves project content untouched.

## Skill links

Every installed skill lives once, in `.agents/skills/<skill>/`, which Codex and
most agents read. Claude Code reads only `.claude/skills/`, so for each skill a
run installs, system or author, the run also installs a skill link at
`.claude/skills/<skill>`: a relative symbolic link whose text is
`../../.agents/skills/<skill>`
([ADR 0013](https://github.com/lutzseverino/repo-standards/blob/main/docs/adr/0013-expose-installed-skills-through-skill-links.md)).
Standards authors declare nothing for it.

A skill link is an ordinary installation target. A link with the same text is
matched, a missing one is created, and tracked content of any other kind, such
as a hand-made copy of the skill, is replaced and listed among the discarded
edits. Untracked content at the path blocks with `UNTRACKED_REPLACEMENT` and
is left alone. A `.claude` or `.claude/skills` that is itself a symbolic link,
or a link at the path with any other text, blocks with `UNSAFE_TARGET`; the
product never writes through a link it did not create. The inspection lists
each link with its skill and action, its identity binds the link without
following it, and durable state records each link's text. A link changed after
inspection makes `start` fail as stale.

The product links only the skills it installs and never writes
`.claude/skills` as a whole: a skill the project wrote itself under
`.agents/skills/` gets no link, and other content in `.claude/skills/` stays
untouched. A retired skill's link is removed with the skill, and stays with it
when an edited skill is kept. A link the maintainer edited on its own, such as
one replaced by a committed file, is kept even when its unedited skill is
removed. Links are exact
content, so they never make an update contextual. Git records each link as a
symbolic link; a checkout with `core.symlinks=false` has a small text file
there instead, and Claude Code does not see that skill. Commit the links with
the run's other changes; a link that Git ignores fails completion with
`IGNORED_OUTPUT`, like any other adoption output.

## Durable and local state

Review and commit these files through the adopting project's normal workflow:

| Path                                                        | Recorded material                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.repo-standards/selection.yaml`                            | Exact CLI package/version, canonical source URL, stable tag, commit SHA, profile, platform, and check location (`checks`).                                                                                                                                                 |
| `.repo-standards/lock.json`                                 | Inspection identity, immutable source and CLI pins, SHA-256 hashes and executable state for exact and retained material, runtime manifests, and last-complete state.                                                                                                       |
| `.repo-standards/state.json`                                | Last-complete run, HEAD at start, completion time, exact baselines, full skill file inventories, skill links, check and assessment evidence bound to the selection and project snapshot, and compact work evidence for this run only.                                      |
| `.repo-standards/inputs/`                                   | Normalized metadata, the resolved selection, a normalized single-profile manifest, selected source files/trees, and root license material. Other profiles and unrelated source material are omitted.                                                                       |
| `.repo-standards/rules/`                                    | The [installed rules](https://repo-standards.com/docs/reference/rules/) of every active declaration that has rules, and the generated `README.md` index of what each covers.                                                                                               |
| `.repo-standards/runtime/package.json`, `package-lock.json` | An isolated exact CLI dependency and npm's resolved dependency graph and integrity values.                                                                                                                                                                                 |
| `.repo-standards/.gitignore`                                | Ignores runtime dependencies, local reports/logs, and caches.                                                                                                                                                                                                              |
| `.repo-standards/.gitattributes`                            | Marks product state `linguist-generated`, so it never counts toward GitHub language statistics.                                                                                                                                                                            |
| `.agents/skills/repository-standards/`                      | The product-owned model-invocable skill from this exact CLI version, which looks up [installed rules](https://repo-standards.com/docs/reference/rules/) before file changes and reports [available updates](https://repo-standards.com/docs/reference/available-updates/). |
| Exact targets and `.agents/skills/<author skill>/`          | The selected author-owned content and complete skill resources.                                                                                                                                                                                                            |
| `.claude/skills/<skill>`                                    | A skill link for every skill above, system or author: a relative symbolic link to `../../.agents/skills/<skill>`.                                                                                                                                                          |

Discovery adoption additionally retains `inputs/scope-history.json`, and every
later run keeps writing it. It holds the current run only: its accepted
inspection identity, resolved selection, and, when the run discovered scope, its
source-resolved declarations, discovery guidance, proposal, rationale, evidence
paths, derived absence and observation identities, together with the run's scope
change against the previous run. This file is included in immutable input integrity.
`inspect --json` exposes it as historical scope after completion, independently of
source availability, as `repo-standards/scope-history/v7` in the
`repo-standards/inspection/v10` report, and `status` reports its scope change.
It also keeps each discovery script's draft that the confirmed entry was
decided from, which a later update compares with the fresh draft to
[reuse the scope answer](https://repo-standards.com/docs/reference/adoption-run/#reused-answers).

Retained scope evidence stores the run's discovery once: its identity, proposal,
absence, declarations and project observation without the evidence array that
observation implies. The named observation is stored as its delta from that
project observation: the confirmed targets and any boundary entry naming them
adds. Evidence arrays and the full named observation are rebuilt whenever the
file is read. The scope change lists, for each discovery declaration whose
discovered paths changed, the paths added and removed against the previous
run's confirmed scope; it is computed when the run is planned and stored with
it. Work intervals and final scope-validity assessments are committed in
`repo-standards/state/v8`, which holds the current run's evidence only, with
the answers it reused and each contextual declaration's scoped files, by
identity, at completion. Neither
file carries an earlier run, so neither grows with the number of runs; Git
history keeps the evidence of earlier runs.

Committed intervals are
[work evidence](https://repo-standards.com/docs/reference/script-protocol/#observed-adoption-scope): the
identities of the observations a run held and the delta between them, not the
observations themselves. Each interval keeps its phase, scope, operation
reference, changed paths with their before and after file state, boundary
changes, violations and restoration evidence, so an adoption pull request stays
reviewable and each run commits only its own evidence. The run record and the
uncommitted local run report record intervals in this same shape, so completion
carries them into state unchanged and neither record grows with the project.
Historical evidence makes no current-coverage claim.

Each artifact has exactly one format, which this CLI both writes and reads:

| Artifact                                                             | Format                                                           |
| -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Durable state, `.repo-standards/state.json`                          | `repo-standards/state/v8`                                        |
| Integrity lock, `.repo-standards/lock.json`                          | `repo-standards/lock/v2`                                         |
| Retained scope evidence, `.repo-standards/inputs/scope-history.json` | `repo-standards/scope-history/v7`                                |
| Run record, local run report, and archived abandoned report          | `repo-standards/run/v8`                                          |
| `status` report                                                      | `repo-standards/status/v10`                                      |
| Inspection report                                                    | `repo-standards/inspection/v10`                                  |
| Work request and assessment                                          | `repo-standards/work-request/v5`, `repo-standards/assessment/v3` |

An update also reads `repo-standards/state/v7`, `repo-standards/lock/v1` and
`repo-standards/scope-history/v6` as the adoption it updates, so that it [reuses](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) what those
records prove. Every other earlier format is retired: it is not read,
converted, or compacted. A project whose committed files carry one
[adopts fresh](https://repo-standards.com/docs/reference/adoption-run/#adopt-fresh-from-a-retired-format), and a run record in one
calls for the CLI that wrote it. An agent's assessment
submission is never committed: one in an earlier format is rejected with
`ASSESSMENT_FORMAT` until it is written again in the current format.

Discovery-backed updates, including an unchanged selection, inspect fresh
proposals, whose entries `adopt` [reuses](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) when their fresh
evidence is unchanged, and record their scope change against the prior run. Retry repeats
fixes under the confirmed scope and cannot authorize additional files; a scope
that needs to change is [corrected by adopting again](https://repo-standards.com/docs/reference/adoption-run/#correct-a-confirmed-scope).

The normalized manifest is separate from retained source files, so an author
may legitimately select their original `standards.yaml` as exact content.
References keep their original source-relative paths. The shared resolver also
interprets the retained manifest; inspection does not introduce a second format
interpreter.

Runtime `node_modules`, `.repo-standards/local/`, and caches remain ignored.
Durable progress lives at Git's `repo-standards-run.lock` path, outside tracked
content and separate for each working tree. It records the current run even if
installation is interrupted before local product reports can be created. Separate
process registrations under `repo-standards-run.lock.workers/` prevent concurrent
start, resume, retry, and abandon commands. Dead registrations do not hold an
execution lock. Saved installation material and the completion bytes a recovery
may need to verify, both addressed by their hashes, runtime staging, and the one
observation the run's last interval ends at remain in Git's working-tree
metadata until completion or abandonment.
`.repo-standards/local/run.json` records progress once installation begins.
Neither dependencies nor run records belong in commits.

## Completion and incomplete results

`start` prints a `repo-standards/run/v8` JSON report. Its fields include `id`,
`inspection`, `selection`, `root`, `head`, `affected`, `outcome`, `phase`, `reason`, `changes`, `completed`,
`uncertain`, `nextAction`, `prerequisites`, `operations`, `deferred`, `reused`, `assessments`, and contextual
`workRequest` when required. `reused` lists each [reused answer](https://repo-standards.com/docs/reference/adoption-run/#reused-answers)
by question `id`, `kind`, and `evidence`: those `adopt` reused for its start and
each assessment the run reused. `deferred` lists each fix the run defers, by
`declaration`, fix `id`, and `reason`: [remote setup](https://repo-standards.com/docs/reference/adoption-run/#remote-setup) that is
not ready, with the probe's reason, or every remote setup in a
[headless update](https://repo-standards.com/docs/reference/adoption-run/#update-headlessly), and each
[declined overwrite](https://repo-standards.com/docs/reference/adoption-run/#defer-a-declined-overwrite). `root` and `head` record the canonical project
root and HEAD at start for provenance; the inspection identity binds neither,
and neither is committed. The report carries no file bytes: `affected` holds
the hash inventories of the targets at start, `completion` the hashes of the
candidate lock and state, and the work request references guidance by path and
hash. `installation.files` and `installation.runtime` record
confirmed installation progress; `uncertain` describes work whose result has not
been verified and recorded. `retryHistory` preserves prior failure reasons,
uncertainty, and assessment evidence. Its `report` path points to the local report
bytes archived before retry, including any changes made by an interrupted author
process. Archived paths are relative to Git's directory for the working tree,
which `git rev-parse --absolute-git-dir` prints, such as
`repo-standards-reports/<run-id>/<name>`, so committed retry history records no
checkout location. Archival failure blocks retry before the existing report is
overwritten.
Each retry's `archivedFiles` also retains operation logs, including unrecorded
results. Archive names include content hashes so reusing an operation index
cannot replace earlier evidence.
`operations` retains recorded process results, and `observations` records each
observation interval as identities and deltas in the
[committed interval shape](https://repo-standards.com/docs/reference/script-protocol/#observed-adoption-scope),
without observation maps. Exit status is 0 for complete adoption, 1 for an
incomplete run or rejection, and 2 for invalid usage. Preflight rejections use
the common `valid: false` / `errors` diagnostic format.

Completion requires expected exact bytes and executable bits, whole-skill and
retained-input inventories, runtime dependencies, durable product files, and
unchanged HEAD and index. Exact and durable outputs must also be visible to
Git's normal add workflow; ignore rules hiding new adoption outputs make the
run incomplete. Verification uses the original expected installation
values; unexpected changes cannot become new baselines. Completion leaves all
changes uncommitted and releases the lock. Those changes include new untracked
files, which `git diff` omits; review them too, such as with
`git ls-files --others --exclude-standard -z`, as `adopt`'s next steps describe.

Fixes run serially before contextual work. Checks run after fixes for profiles
without contextual declarations; otherwise they wait for a satisfied, current agent assessment. Ordinary failed checks allow subsequent checks to collect evidence.
Blocked results, execution errors, check mutation, and integrity failures stop
the phase and preserve incomplete work. A fix that needs confirmation to
overwrite a setting stops the run until [`resume --confirmed`](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes). A contextual handoff is incomplete,
with no last-complete state. Apply its guidance, refresh the snapshot with
`resume --json`, and submit `resume --assessment <file> --json` to continue.

An incomplete adoption preserves changes and its lock. Its change report
observes actual Git changes and ignored product storage, including unexpected
additions; runtime dependencies are listed as one directory. The persisted
`affected` observations include author targets and the system skills,
so subsequent `status` calls also find ignored files and skill resources added
after interruption, and reflect paths reconciled since the run stopped.
Until the initial ignore-file write succeeds, the Git-directory lock remains
the report and no potentially visible local run record is created.

Failure to persist final completion is reported as an incomplete `completion`
phase with explicit uncertainty and recovery guidance. Candidate state is
preserved as ignored `.repo-standards/local/incomplete-state.json` when possible,
instead of asserting a last-complete adoption. If preserving that candidate also
fails, the report identifies the uncertainty for manual recovery.

## Summarize status

`status` prints a Markdown record with a **Ready to commit** verdict.
`status --summary` prints the same record; `status --json` returns
`readyToCommit`, a boolean, and `readinessReasons`, the failing conditions as
messages (empty when ready). The verdict is true only when:

* no adoption run is active;
* a last complete run is recorded;
* there is no `stateError`;
* every path in that run's `changeSet` is among Git's uncommitted changes.

A changed directory counts when at least one uncommitted path lies beneath it:
the directory path followed by `/`. For example, `.factory/Dockerfile` represents
`.factory`, but `.factory-old/Dockerfile` does not. A directory change with no
uncommitted file beneath it, such as creating an empty directory or changing
only its mode, does not count.

Staged, unstaged, and non-ignored untracked paths count as uncommitted, including
deleted paths and both ends of a rename. A path already committed or reverted
makes the verdict false, even when unrelated changes remain. A complete run
with an empty change set satisfies the path condition. The verdict describes
readiness for the project's commit workflow; it does not run checks or certify
ongoing compliance. Producing a status report still exits 0 when the verdict is
false; CLI pin, format, and integrity failures still fail as documented below.
Readiness depends on the checkout's current Git status, so the verdict can
differ between checkouts holding the same committed adoption state.

`status --summary` renders the status record as Markdown on stdout instead of
JSON. After a complete run it is the record of that run: the selection, every
operation with its result and message, then each deferred fix with the result
`deferred` and its reason, such as [remote setup](https://repo-standards.com/docs/reference/adoption-run/#remote-setup) with the
probe's reason or a [declined overwrite](https://repo-standards.com/docs/reference/adoption-run/#defer-a-declined-overwrite),
each path the run changed, once, with
the phases that changed it, the discovered-scope additions and removals the run
made, and the run, inspection, HEAD-at-start, and completion identities. A
`### Reused answers` subsection of its Operations section lists each
[reused answer](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) with why it was eligible, adding no level-1 or
level-2 heading, so the record stays a Repo Canon adoption record. During
an active run it renders the run's selection, outcome, phase, execution and
reason, its completed and uncertain work, operations and results, then its
deferred fixes and reused answers, changed paths, next action, and identities. Abandoned runs and a state error are listed
when present. The same record renders the same bytes, the summary describes the
record without prescribing anything, and combining `--summary` with `--json` is
a usage error.

After a complete run the record ends with an `## Impact` section followed by a
`## Migration` section, after any Abandoned runs. Impact holds the
[adopter action](https://github.com/lutzseverino/repo-standards/blob/main/GLOSSARY.md#language) the CLI derived: the update class,
the declarations whose contextual work the run asked for, which excludes each
[reused](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) assessment, and the remote setup that stayed
deferred. It then lists, oldest first, the author-written
`adopter-action` line of each release since the previous selection and of the
adopted release, with the reason for any release whose `standards.yaml` could
not be read, or for a release list that could not be read. Migration holds the
ordered steps those lines imply, or says that committing the update is the only
step. Both always say something meaningful, never a placeholder, so the record
is a valid pull request body under both a `chore:` and a `chore!:` title. The
run reads the skipped releases when it starts an update from the same source,
through the release list and one `standards.yaml` read per skipped release; a
failure of either is recorded in the record and does not fail the run. The
JSON status record of a complete adoption carries the same content as
`impact`: `derived`, `releases` (each with `version`, `action` and, when
unreadable, `reason`), `skipped` when the release list could not be read, and
`steps`. An initial adoption records only the adopted release.

The changed paths are the run's net change set, which completion keeps in
durable state as `changeSet`, so the changed-path table renders from committed
state alone, in any checkout. Each entry names a path whose state at completion differs from
its state before the run, and the phases that changed it: `installation` for
exact files and skill files, including the system skills' and a retired
declaration's removed target, that the run created, replaced, or removed; `fixes` and `agent` for the paths their intervals
recorded. A path that a later phase returned to its state before the run is not
listed, verified restoration of installed content after an interruption keeps
only the installation's attribution, and product state under `.repo-standards/`
is not listed. A run that [adopts again in place](https://repo-standards.com/docs/reference/adoption-run/#adopt-again-in-place)
covers the changes of the run it replaced too, relative to the HEAD that run
started from. The JSON status record of a complete adoption includes the same
`changeSet`.

The JSON status record of a complete adoption also includes `deferred`: each
fix its last complete run deferred, by `declaration`, fix `id`, and `reason`,
or an empty list. An active run reports its own `deferred`. Every JSON status
record includes `reused`: the [reused answers](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) of the active
run, or else of the last complete run, or an empty list.

The JSON status record of a complete discovery-backed adoption includes
`scopeChanges`: the additions and removals by declaration that its last complete
run made relative to the run before it, read from the retained scope evidence,
or every confirmed path for the first discovery-backed run.

Every `status --json` report uses `repo-standards/status/v10` (raised from v8 for
`reused`) and includes
`scopeProposal`: the last complete run's confirmed proposal, in the public
`repo-standards/scope/v2` format, or null when that run had no confirmed proposal
or no adoption has completed. It preserves the confirmed candidates, decisions,
reasons, evidence paths, coverage, and unresolved questions, with the list order
normalized at inspection. It carries no inspection or discovery identity.

The field reads only retained committed evidence and works in a fresh checkout,
offline, independently of the source flags used for inspection or an update.
During an incomplete or abandoned update, it reads the last complete adoption's
evidence from the clean commit at that run's start; the candidate proposal does
not become the last complete proposal. An update reuses the proposal's entries
only when fresh evidence reproduces what they were decided from, as
[reused answers](https://repo-standards.com/docs/reference/adoption-run/#reused-answers) describes. `status --summary` does not render
the proposal.

## Adopt afresh over installed content

Initial adoption never takes over existing product state in the current
formats: an established adoption inspects as an update, and any other
`.repo-standards/` content that is not
[retired](https://repo-standards.com/docs/reference/adoption-run/#adopt-fresh-from-a-retired-format) is an `EXISTING_ADOPTION`
blocker. Giving up readable retained state therefore remains a deliberate
change visible in Git. To adopt afresh over content that such an adoption
installed, finish or abandon any active run, remove the product state
directory, commit that removal through the project's normal workflow, and
inspect the selection again:

```sh
git rm -r --quiet .repo-standards  # tracked product state
rm -rf .repo-standards             # ignored runtime, local, and cache content
git commit -m "Remove Repo Standards product state"
```

The new inspection matches exact files and skill directories that still match
the selected source, and each system skill that matches the inspecting CLI's
packaged skill, without rewriting them. It replaces tracked content that
differs, such as a skill edited since installation or a system skill that a
different CLI version installed, and lists each such replacement among the
discarded edits. Evidence of the earlier adoption remains only in Git history.

## Adopt fresh from a retired format

Each record has one format this CLI reads. `status`, `resume`, and `abandon`
check the active run's CLI pin, or otherwise the recorded adoption's pin,
before checking any record format. A different CLI fails with
`CLI_PIN_MISMATCH` first, without changing anything.

When committed state, the integrity lock, or retained scope evidence carries an
older format, inspecting with `--source`, `--standards-version`, and
`--profile` previews a fresh adoption without anything removed or committed
first. Nothing in the retired state is read or converted, and the selection is
inspected as an initial adoption. Each of those records that is present must
still carry its own artifact's current or retired format, as a
current or readable previous lock beside retired state does; any other content
there fails with `STATE_INTEGRITY`, and nothing is removed:

* `retiredState` in the report, and **Retired product state** in its summary,
  list the retired records and every file of the `.repo-standards` directory
  as content the run removes. The directory is removed whole, including its
  ignored runtime dependencies, local reports, and cache, which the identity
  doesn't bind and the report doesn't list. Local content worth keeping, such
  as a candidate state an earlier CLI preserved in
  `local/incomplete-state.json`, is copied elsewhere before `start`. The
  inspection identity binds the rest, so changing it after the inspection
  fails `start` with `STALE_INSPECTION`.
* Exact files, skills, and system skills are matched or replaced as at any
  initial adoption: without an installed baseline, every replaced target is
  listed among the discarded edits. Content that an earlier adoption installed
  and the selection no longer declares stays in place as project content.
* Removing the retired state is not a
  [confirmation-required change](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes). Under its lock, `start`
  observes the same retired directory again, removes it, and then installs. The
  removal is left uncommitted with the run's other changes; HEAD and the index
  don't change. A directory that no longer matches the inspection when its
  removal begins fails the run with `INSTALLATION_CHANGED`, and nothing is
  removed. An interrupted removal is recovered with `resume --retry` like any
  interrupted installation. While the run is active, `status`, `resume`,
  and `abandon` read it rather than the retired state.

Every other command that would read a retired committed record, including
`inspect` and `start` without source flags, which inspect retained standards,
fails with `RETIRED_FORMAT` after any required pin check and before reading
further records or writing anything. The diagnostic names the record, its
retired format, and the format this CLI reads, for example:

```text
[RETIRED_FORMAT] .repo-standards/state.json carries the retired format repo-standards/state/v6; this CLI reads only repo-standards/state/v8. Adopt fresh: inspect with --source, --standards-version and --profile, and start that inspection, which removes the retired .repo-standards directory.
```

Run records live in Git's directory: the active run at
`git rev-parse --git-path repo-standards-run.lock`, and abandoned runs' reports
in the `repo-standards-reports/` directory beside it. An active run record in a
retired format may hold unfinished work, so every command that reads product
records, including the fresh-adoption preview and its start, fails with
`RETIRED_RUN` and removes nothing. `outdated` is the exception: it reads only
the pinned selection and writes only its ignored cache. The diagnostic names the earlier pinned CLI when the record carries
one, and its `resume --retry` and `abandon`, which can still continue or end
the run; this CLI can't:

```text
[RETIRED_RUN] The active adoption run record .git/repo-standards-run.lock carries the retired format repo-standards/run/v5; this CLI reads only repo-standards/run/v8. It may hold unfinished work: with the earlier pinned CLI 3.2.0, resume it with resume --retry or end it with abandon, then inspect again.
```

An archived report in `repo-standards/run/v6`, the run format CLI 9.0.0 wrote,
stays where it is and is not read. It blocks nothing, and `status` does not list
it among abandoned runs; CLI 9.0.0 still reads its evidence. This CLI does not
adopt again in place over the changes such a run left uncommitted. Finish them
with CLI 9.0.0, or commit or discard them through the project's normal workflow,
before updating. An archived report in any other older run format fails with
`RETIRED_FORMAT` and names that report: only the CLI that wrote it reads its
evidence, so it is moved out of Git's directory before this CLI continues.

A higher version of the same record format fails with `NEWER_FORMAT`, including
when a future schema no longer exposes the CLI pin where this CLI expects it:

```text
[NEWER_FORMAT] .repo-standards/state.json carries the newer format repo-standards/state/v9; this CLI reads only repo-standards/state/v8. Use the pinned CLI to read this record.
```

This diagnostic exits 1, reads no further records, and changes nothing. Use the
CLI pinned by the project or active run. A newer format never takes the
fresh-adoption path, and takes precedence over any retired record. The three
format diagnostics include `details.path`, `details.format`, and
`details.expected` in JSON output; `RETIRED_RUN` adds `details.cli` when the
run record names its CLI. Malformed or unrelated format identities, including
a same-prefix version that is not `vN` such as `repo-standards/state/vnext`,
are not classified as retired or newer. They fail integrity validation when
a command reads that record.

## Recover or abandon an interrupted run

Use the run's exact CLI version; `status`, `resume`, and `abandon` reject any
other with `CLI_PIN_MISMATCH`. If installation stopped before the project-local
CLI became usable, use the externally installed CLI that started the run. When
the project runtime manifest and npm lock do not yet both pin the run's CLI, the
diagnostic names that CLI instead of the runtime reinstall command, which could
not restore it.

`resume`, including `--retry` and `--assessment`, requires Git 2.32 or newer,
as `inspect` and `start` do. After the CLI pin check and before reading records
or observing project work, it checks the Git version. Older Git fails with
`GIT_VERSION_UNSUPPORTED`, naming the installed and minimum versions, and
changes nothing. `CLI_PIN_MISMATCH` still takes precedence under another CLI.

```sh
repo-standards status --json
repo-standards resume --retry --json
```

`status --json` reports the active run's `phase`, `reason`, `changes`,
`completed`, `uncertain`, `nextAction`, and `execution`. `execution: active`
means a command or recorded author process group is still running. Background
members keep the group active even after a fix or prerequisite probe returns.
Recorded leader start identities distinguish an unrelated live leader that
reuses a process-group number; a leaderless group is still treated
conservatively as active while it has surviving members.
`execution: interrupted` means durable incomplete progress
remains without live execution. A normal contextual handoff also has no live
execution. A second start is blocked until the run is resumed or abandoned.
The CLI uses the system `ps` utility on `PATH` to inspect process-group membership.
Minimal Debian/Ubuntu containers need the `procps` package. An unavailable or
unsuccessful `ps` blocks execution and recovery with `PROCESS_STATE`, identifying
the invocation's failure; provide or repair the utility and retry. Worker
and group-leader identities use kernel start values: boot identity and start
ticks from Linux procfs, and microsecond start times from macOS libproc through
the packaged Koffi binding. The macOS binding ships prebuilt for arm64 and x64;
installation does not require a compiler or enabled install scripts. Recovery
is rejected if process identity or liveness cannot be determined safely.

`resume --retry` explicitly authorizes repeating trusted operations. It checks
prerequisites again, verifies inspected installed bytes, executable state,
inventories, HEAD and index, and finishes pending installation from saved
material. A write interrupted before its progress was recorded may contain the
original inspected bytes or the expected installed bytes. Other edits block
retry for reconciliation; there is no force-overwrite. Once installation was
prepared, recovery needs neither the standards source nor fresh npm acquisition.
An interruption before preparation repeats inspection and acquisition and still
requires the original inspection identity to be fresh; the run's start already
carried any confirmation that inspection required.

Retry reruns repeat-safe fixes in declaration order, requests renewed contextual
assessment where applicable, reruns checks, and verifies final integrity before
recording completion. It retains earlier operation evidence and uncertainty as
history. Retry discards the run's accepted assessment: a new submission against
the retried request is required, even if project bytes match.
Retry records separate
fix and agent observation intervals, retaining earlier observed agent edits
even when replayed fixes overwrite the same files. Retry cannot hide
recorded scope violations or create scope authority, though restoring a
violating path to its state before the run reconciles its violation; see the
[observed execution contract](https://repo-standards.com/docs/reference/script-protocol/#observed-adoption-scope). Submit a new assessment separately after retry;
`--retry` and `--assessment` cannot be combined. Plain `resume` and
`resume --assessment` remain the contextual interface and never implicitly retry
uncertain process outcomes. A run stopped because a fix needs confirmation to
overwrite a setting continues with
[`resume --confirmed`](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes) once the maintainer
confirms, or with [`resume --defer`](https://repo-standards.com/docs/reference/adoption-run/#defer-a-declined-overwrite) once they
decline. A failed completion write remains incomplete until
its candidate state is verified and recovery finishes.

`abandon` ends an incomplete run while keeping its work:

```sh
repo-standards abandon --json
repo-standards status --json
```

Abandon leaves project content and HEAD in place and retains incomplete evidence.
It archives the report under Git's `repo-standards-reports/<run-id>.json`; `status`
returns these reports in `abandoned`. Operation logs and local report snapshots
are copied alongside the archived report in a directory named for the run ID.
Archived operations point to those copies, so later adoption and removal of the
incomplete installation cannot overwrite their evidence. Archived paths are
relative to Git's directory for the working tree, including when that directory
lives outside the working tree, as in a linked worktree.
`archivedFiles` maps original report and operation-log paths, which stay
project-relative, to their archived copies, including logs written before their operation result reached the journal.
Abandonment reports `outcome: incomplete` with `abandoned: true` and exits 0
once the run is abandoned; every refusal, such as `NO_ACTIVE_RUN` or a live
author process, exits 1. The report does not assert successful adoption or
replace last-complete evidence. The
CLI releases the run only after preserving any candidate completion state and
archiving its report, with the run's saved installation and the observation
its last interval ends at, which adopting again in place reads. Failed
preservation blocks abandonment and keeps the run active for reconciliation.
Preserved changes stay in the working tree. Run `adopt` in that checkout to
[adopt again in place](https://repo-standards.com/docs/reference/adoption-run/#adopt-again-in-place) over them, or reconcile them
through the project's normal workflow; any other new run requires a clean
project without conflicting product state and a fresh inspection.
An archived run report is moved out of Git's directory only when it carries a
[retired format](https://repo-standards.com/docs/reference/adoption-run/#adopt-fresh-from-a-retired-format) other than
`repo-standards/run/v6`, because this CLI cannot read it; `run/v6` reports stay
where they are.

## Correct a confirmed scope

A run's confirmed scope never changes while the run is active, and retry
repeats work under it. A structurally valid blocked scope review, reporting that
coverage needs files outside the scope or that a confirmed target is mistaken,
leaves the run incomplete with `SCOPE_INCOMPLETE`; its additional paths grant no
authority. Agent work outside the allowed targets, `ASSESSMENT_SCOPE`, and a
blocked assessment, `ASSESSMENT_BLOCKED`, also stop the run. A different scope
takes a new run, and `adopt` starts it in place.

### Adopt again in place

While a run is stopped for one of these reasons, its `adopt` report carries
each discovered declaration's `scope:<declaration>` question, answered with the
confirmed scope entry. Change that answer to cover the files the work needs,
such as a path `ASSESSMENT_SCOPE` names, and run `adopt --answers <file>` again.
In a terminal, choose to change the scope from the incomplete-run menu. A scope
answer is Git-undoable, so an agent changes it without asking. `adopt` then
replaces the run in the same checkout:

1. It archives the run's report as abandonment does, marked `abandoned: true`
   with a reason starting `REPLACED:`, keeping its changes.
2. It inspects the unchanged selection with the new scope, defaulting the
   version, profile, and remote setup deferral to the replaced run's, and asks
   for the new inspection's identity before starting.
3. It starts a new run over the replaced run's changes.

`adopt` in a checkout where a run was abandoned does the same from step 2,
defaulting the scope to the abandoned run's as well; so do `inspect` and
`start` of that selection. A start over a run's preserved changes requires
the checkout to still hold what the run left: its HEAD and index, its verified
installation, and each uncommitted path outside product state in the state the
run's last observation recorded. The Git start blockers exempt exactly those
paths. Any other uncommitted change still blocks with `DIRTY_PROJECT`, naming
its path, and the agent stops and tells the maintainer. Selecting another CLI,
source, version, profile, platform, or check location does not adopt in place. The last complete
adoption an update replaces is read from the HEAD the run started from, since
the checkout's product state is the run's own.

The new run keeps the installed runtime, reruns every fix, which is
repeat-safe, and asks for renewed assessments: the preserved contextual work
stays in the tree, is attributed to agent work, and must lie within the new
scope. Its change set and adoption record cover every change relative to the
HEAD the first run started from, with the phases that made each. The
replaced run's own evidence stays in its archived report.

Without changing the scope, a run stopped for `ASSESSMENT_SCOPE` also recovers
by restoring each named path, as its next steps say. Abandoning, committing or
discarding the changes, and adopting again from a clean checkout remains
possible, but no stop requires it.

## Fresh checkout and source disappearance

Restore the runtime from committed manifests using:

```sh
npm ci --ignore-scripts --prefix .repo-standards/runtime
.repo-standards/runtime/node_modules/.bin/repo-standards status --json
.repo-standards/runtime/node_modules/.bin/repo-standards inspect --json
```

The npm package must remain available from its locked location or an npm cache.
No standards-source connection is needed for these commands. `inspect` without
source flags verifies retained input integrity and resolves the current profile
from retained material. Local edits to exact project content remain visible in
the report, which has `retained: true`. With the pinned CLI it describes the
unchanged selection; with a different exact CLI version it describes a CLI
update. Either can be started as described above. Active discovery
declarations require fresh `--scope` proposals; retained historical scope never
substitutes for them.

`status` reports pins, active progress, and historical last-complete evidence
without any network request; [`outdated`](https://repo-standards.com/docs/reference/available-updates/) reports
available CLI and standards updates. Both require the pinned CLI, and so does
[`rules`](https://repo-standards.com/docs/reference/rules/#look-up-the-rules-for-a-path), which reads the installed
rules without any network request. `status` takes
the pin from the active run when a run is active, otherwise from the last
complete adoption; `outdated` takes it from the committed selection. Under
another CLI version each exits 1 with `CLI_PIN_MISMATCH`, as `resume` and
`abandon` do for an active run. The diagnostic names the pinned version and,
when the runtime manifest and npm lock both pin it, the project root and the
runtime reinstall command above; otherwise it names an exact CLI installed
outside the project, as [recovery](https://repo-standards.com/docs/reference/adoption-run/#recover-or-abandon-an-interrupted-run)
describes. Without a recorded pin, as before an initial adoption starts, any CLI
reports. Only `inspect` and `start` accept a different exact CLI, as a candidate
CLI pin change.
After an abandoned update, `status` still returns the archived report. If the
preserved product files do not represent complete adoption, `stateError`
describes that condition and names the abandoned run and the way forward,
adopting again in place; historical evidence comes from the matching archived
run and does not certify the candidate selection as complete. An abandoned report carrying
`repo-standards/run/v6` is excluded from matching; the state-integrity failure
is not replaced by advice to adopt over that run. `check` and
`rules` name the same way forward in their `STATE_INTEGRITY` diagnostic.
It does not claim ongoing compliance after subsequent project edits. While an
initial run is incomplete, no last-complete adoption is reported. `adopt`'s
next steps guide these same commands and confirmation requirements.
