Skip to content

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 and the update guide walk through the same steps as tasks.

adopt drives inspection, inspect and start, and resume. These remain available for callers that need the lower-level adoption run interface described below. The script protocol defines author operations; the assessment protocol defines contextual work evidence. Neither protocol needs to be read to start with adopt.

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. 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 the start, and no remote-setup answer is resolve.
  • No question is open. The answers file answers a question, a reused answer does, and so does a default adopt proposes as the answer: the version, the profile, and a 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. 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 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; 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.

A profile names the hosting platforms it supports, and the project selects its platform separately from its profile; see 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.

Select exactly one offered check location 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.

An update carries the last complete adoption’s recorded answers forward (ADR 0024). 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.

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:

Terminal window
.repo-standards/runtime/node_modules/.bin/repo-standards adopt --headless --json

It keeps the recorded source, profile and 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 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, 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 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.

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.

idAsked whenanswer
versionAlways; the template proposes the newest stable release.A stable tag from choices, the source’s stable releases newest first.
profileAlways; proposed for an update or a single profile.A profile name from choices, each with its description.
platformOnce 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.
scope:<declaration>For each active discovery declaration, and while a run is stopped for its scope.Its scope entry without id: coverage, candidates, and unresolved, and noScope for 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 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.
checksWhen the profile offers several locations, or a headless update loses its recorded location.One offered location: github, runner or self-reported.
remote-setupWhen a remote setup probe is not ready.defer to complete adoption without it, or resolve to stop, writing nothing. In an update, a reused 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.
confirmationWhen 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.
inspectionOnce 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.
assessment:<declaration>For each declaration of contextual work.Its assessment 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 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.

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 by question id, kind, and the evidence that made it eligible. A headless update’s 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:

outcomeMeaning
answers-requiredQuestions in missing need answers, including a fix’s confirmation or deferral in an active run; before a run, nothing was changed.
blockedInspection blockers, a resolve remote setup answer, or a start that stopped before writing anything, with its run.reason.
contextualThe 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.
completeThe run completed; its changes are uncommitted.
incompleteThe 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.

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.

adopt 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. First inspect the public GitHub selection:

Terminal window
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:

Terminal window
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, 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.

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 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:

Terminal window
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 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:

Terminal window
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.

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

Terminal window
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. 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.

A fix that changes the hosting platform’s settings, such as its labels or merge rules, can declare itself remote setup, with a readiness probe. Inspection runs every remote setup probe before anything is written and reports each one in remoteSetup 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:

Terminal window
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. A headless update 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 the recorded deferral while the same probe still reports it not ready. Remote setup names no platform; the probe decides readiness.

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 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. inspect --summary renders the report as a Markdown proposal.

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:

Terminal window
.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:

Terminal window
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:

Terminal window
"$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:

Terminal window
.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 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. 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 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.

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.

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.

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). 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.

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

PathRecorded material
.repo-standards/selection.yamlExact CLI package/version, canonical source URL, stable tag, commit SHA, profile, platform, and check location (checks).
.repo-standards/lock.jsonInspection 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.jsonLast-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 of every active declaration that has rules, and the generated README.md index of what each covers.
.repo-standards/runtime/package.json, package-lock.jsonAn isolated exact CLI dependency and npm’s resolved dependency graph and integrity values.
.repo-standards/.gitignoreIgnores runtime dependencies, local reports/logs, and caches.
.repo-standards/.gitattributesMarks 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 before file changes and reports 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.

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: 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:

ArtifactFormat
Durable state, .repo-standards/state.jsonrepo-standards/state/v8
Integrity lock, .repo-standards/lock.jsonrepo-standards/lock/v2
Retained scope evidence, .repo-standards/inputs/scope-history.jsonrepo-standards/scope-history/v7
Run record, local run report, and archived abandoned reportrepo-standards/run/v8
status reportrepo-standards/status/v10
Inspection reportrepo-standards/inspection/v10
Work request and assessmentrepo-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 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, 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 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.

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.

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 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 that is not ready, with the probe’s reason, or every remote setup in a headless update, and each 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, 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. 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.

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 with the probe’s reason or 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 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 the CLI derived: the update class, the declarations whose contextual work the run asked for, which excludes each reused 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 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 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 describes. status --summary does not render the proposal.

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 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:

Terminal window
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.

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. 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:

[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:

[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:

[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.

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.

Terminal window
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. 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 once the maintainer confirms, or with resume --defer 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:

Terminal window
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 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 other than repo-standards/run/v6, because this CLI cannot read it; run/v6 reports stay where they are.

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.

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.

Restore the runtime from committed manifests using:

Terminal window
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 reports available CLI and standards updates. Both require the pinned CLI, and so does rules, 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 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.