Bootstrap and public inspection
See Install the CLI and skills for npm and standalone-bootstrap acquisition and the adoption run reference for adoption, runtime pins and retained inspection. Public release status is recorded in the product repository.
Obtain the CLI outside the adopting project
Section titled “Obtain the CLI outside the adopting project”Use macOS or Linux with Node.js 24 or 26, npm, and Git 2.32 or newer on PATH. Node.js 24 or 26 installers
at https://nodejs.org/en/download include npm. Missing prerequisites produce
actionable setup instructions. Before observing project state, inspect,
start, resume, and
check check the Git version. An older Git fails with GIT_VERSION_UNSUPPORTED,
which names the installed version and the minimum, 2.32. This minimum ensures
Git does not follow symbolic .gitignore files whose referent is not bound.
Only stable 24.x and 26.x are supported, with their bundled npm. Node.js 22 is outside the support policy; odd majors, prereleases and future majors are also excluded.
The executable bootstrap/repo-standards is a standalone POSIX shell file with
an embedded Node.js program. It needs no product checkout, pnpm, or installed
JavaScript dependencies. Follow public installation
to obtain it from the matching release and install it outside your project.
Then inspect a selection:
cd /path/to/adopting-project"$HOME/.local/bin/repo-standards-bootstrap" --cli-version 10.0.0 inspect \ --source https://github.com/OWNER/STANDARDS \ --standards-version v1.2.3 --profile work --jsonReplace the source, tag, and profile with a published standards source. Add
--platform <name> for a profile that supports several
platforms; a profile that supports one selects
it, and without --platform a profile that supports several fails with
PLATFORM_REQUIRED. A platform the profile does not support fails with
UNKNOWN_PLATFORM. The selected platform’s declarations are inspected, and the
others are left out before scope. Without source flags, inspection keeps the
recorded platform and check location, and --platform and --checks are usage errors.
For a profile offering several check locations, add --checks <value>; missing
and unoffered choices fail with CHECK_LOCATION_REQUIRED and
UNKNOWN_CHECK_LOCATION, respectively. Both filters apply before discovery. The
bootstrap needs the requested CLI package in the configured npm registry.
The packed CLI also exposes repo-standards-bootstrap; installing the product
package globally installs both executable names.
An explicit --cli-version must be an exact stable package version. When it is
omitted, the bootstrap reads published versions once and selects the greatest
stable SemVer, excluding prereleases. It discloses that exact version on stderr
before installation, installs only that version, verifies its installed identity,
and invokes it. It never falls back to a different version. Each new invocation
is a new selection; reuse the disclosed --cli-version to repeat it. Inspection
records the invoked package and version.
Installation uses an external temporary directory and npm’s configured cache,
with lifecycle scripts disabled and the project’s .npmrc out of scope. The
cache is reused so an exact CLI version and its dependencies can be acquired
when already cached, including with npm offline mode. The configured cache must
resolve outside the project, and its _cacache content tree cannot contain
symbolic links or the adopting project. Acquisition logs stay in temporary
storage, even if the configured cache has a linked _logs directory. Normal
completion or failure removes the temporary installation and logs while
preserving the reusable cache. The project’s language, package
manager, dependency manifests, and content are unchanged. Do not redirect the
report into the project if the entire invocation must leave it unchanged.
Keep the disclosed CLI for start and recovery
Section titled “Keep the disclosed CLI for start and recovery”The bootstrap removes its temporary runtime after inspection. To continue,
install the disclosed exact version in a persistent directory outside the
adopting project (replace 10.0.0 with that version):
adoption_cli="$HOME/.local/share/repo-standards/cli-10.0.0"mkdir -p "$adoption_cli"(cd "$adoption_cli" && npm install --prefix "$adoption_cli" \ --ignore-scripts --save-exact --no-audit --no-fund \ @lutzseverino/repo-standards@10.0.0)"$adoption_cli/node_modules/.bin/repo-standards" --versionUse that executable from the project root for inspection and start.
adopt needs no external installation:
it drives these commands and pins the CLI that ran it.
Keep the external runtime available until completion for interrupted-installation
recovery. The adoption workflow documents start and continuation.
Inspect with an already installed exact CLI
Section titled “Inspect with an already installed exact CLI”repo-standards inspect \ --source https://github.com/OWNER/STANDARDS \ --standards-version v1.2.3 --profile work \ --project /path/to/adopting-project --json--project defaults to the current directory; subdirectories resolve to the Git
working-tree root. Inspection works with staged, unstaged, untracked, and ignored
content, and an unborn HEAD. Non-Git and bare repositories are rejected. Default
output and --json provide the complete indented JSON report; --json also makes
failures structured JSON on stdout. --summary renders the report as
Markdown instead.
Git observation disables hooks, fsmonitor and clean/smudge/process filters and prevents index refresh writes. Because author-defined normalization cannot run during inspection, filtered working content may be reported as differing from the index even when ordinary Git status considers it clean.
Adopting-project submodules are permitted outside adoption targets when every submodule is initialized, clean recursively, and checked out at the commit its immediate parent records in the index gitlink. Inspection observes initialized submodules with the same sanitized, read-only Git commands as the parent: no hooks, filters, fsmonitor, network access, index refresh writes or lock files. Staged or unstaged changes, non-ignored untracked files, hidden index flags, checkout mismatches and unsafe or unreadable Git state block start, with the affected project-relative submodule path. Ignored files retain their normal treatment. Parent or submodule ignore-submodule settings cannot hide dirt.
An uninitialized or deinitialized submodule blocks with a manual
git submodule update --init --recursive -- <path> prerequisite, run from its
immediate parent repository. Inspection never initializes, fetches, resets,
cleans or repairs a submodule. If its state cannot be established, it fails closed.
It rechecks recursive state before returning a usable report, and start freshly
validates it again before writing, even with a previously eligible identity.
Discovery excludes submodule contents. Explicit and discovered targets may not
be at, inside, or contain a gitlink, even if its checkout is absent; replacement
and removal targets have the same restriction. .gitmodules cannot be a target.
Read-only observation grants no installation or contextual-write authority
inside submodules. Adopting from inside a submodule is unsupported. This policy
concerns the adopting project; standards-source acquisition still rejects
submodules.
Only public HTTPS GitHub repository URLs are accepted. A trailing .git or /
is normalized through GitHub’s canonical metadata. The version must name an
existing stable SemVer tag (1.2.3 or v1.2.3, optionally with build metadata).
Branches, commit-only inputs, ranges, prereleases, local directories, SSH, private
sources, and other hosts are unsupported. Direct inspection needs no discovery.
Acquisition uses GitHub REST repository and Git-object endpoints. Every GitHub
REST request uses GH_TOKEN, or otherwise GITHUB_TOKEN, as bearer authorization
when present. Values are trimmed; empty or whitespace-only values count as
absent. A token uses the authenticated
API quota instead of the shared anonymous quota. Credentials are optional for
supported public sources and never make private sources supported. Git object
downloads use Git’s separate anonymous smart protocol and do not send the token.
Both token variables are removed from every Git subprocess environment so a
GitHub CLI credential helper cannot consume the REST token. The CLI keeps them
available to its HTTP boundaries.
The token is never recorded in reports, inspection identity, retained inputs,
caches, or logs; the same inspection has the same identity with or without it.
An exhausted quota (HTTP 429, or 403 with x-ratelimit-remaining: 0 or
retry-after) fails inspect and start with exit status 1 and
QUOTA_EXHAUSTED. The message names GH_TOKEN and GITHUB_TOKEN and the reset
time or retry delay when GitHub provides a usable header. A usable retry-after
takes precedence over x-ratelimit-reset when both arrive. Retry after that
time; the CLI does not wait or retry automatically. A 401 with a token fails
SOURCE_UNAVAILABLE, saying the token was rejected, with no anonymous retry.
After a cross-origin redirect strips authorization, a target’s 401 is reported
as the redirect target’s failure instead of a rejected token.
Other connection and API failures remain SOURCE_UNAVAILABLE.
Acquisition resolves lightweight or annotated tags to a commit and downloads that commit’s
tree and blobs outside the project. Blob bytes are verified against Git object
identities; executable bits are preserved. No checkout hooks, filters, author
scripts, or prerequisite probes run. Symbolic links outside selected material
are ignored and never extracted. The source root, standards.yaml, retained
root license entries and their contents, selected references and their ancestors,
and whole selected skill or resource trees
cannot contain symbolic links; these fail with SOURCE_SYMLINK, as in local
source validation. Link entries still count in tree-listing integrity checks.
Submodules, special files, unsafe paths, incomplete trees, and corrupt blobs
are rejected. Before extraction,
source paths that collide after Unicode normalization and case folding are
rejected. Source
references and the root standards.yaml must use their exact Git path spelling,
including on case-insensitive filesystems. GitHub rate limits and
API size limits can prevent acquisition; failures never select another revision.
Observed tag-to-commit identities persist outside the project under
$XDG_CACHE_HOME/repo-standards/tags, or ~/.cache/repo-standards/tags by default.
A previously observed tag that moves is rejected across separate CLI invocations.
Preserve this cache to preserve observation history. It is not retained input
storage and cannot detect movement before the first observation. TMPDIR and
the tag-cache location must resolve outside the project, including via symlinks.
Report and inspection identity
Section titled “Report and inspection identity”Every report has the single format repo-standards/inspection/v10. A profile
with discovery declarations adds the discovery and sourceResolved fields
described below:
| Field | Meaning |
|---|---|
selection | Exact CLI package/version, canonical standards URL, version tag, commit SHA, profile, platform, and check location (checks). |
source, resolved | Validated metadata and the resolver’s complete active profile on the selected platform. |
exact | Declaration and target; create, replace, or match; each file’s before and after hash inventories; a unified diff for a changed text file, or binary: true for changed binary content, which carries only its before and after hashes. A skill also has its link: the skill link .claude/skills/<name> as target, with its own create, replace, or match action. |
systemSkills | Each system skill adoption installs, repository-standards, by name and reserved .agents/skills/<name> target, with create, replace, or match against the copy packaged with the inspecting exact CLI, and its link as in exact. |
removed | For an update, each installed target the selection no longer installs and the run removes, including a retired skill’s link, with its installer (id for a declaration, or systemSkill for a retired system skill) and each file’s or link’s before and after hash inventories and diff, as in exact. |
retiredState | For a fresh adoption over retired committed product state, the target .repo-standards, which the run removes whole; its retired records, each by path, retired format, and the expected format this CLI reads; and the project path of each of its files, sorted, without its ignored generated directories. |
kept | For an update, each edited installed target the selection no longer installs and the run keeps, including the link of a kept skill, by its installer (id for a declaration, or systemSkill for a retired system skill) and target, sorted by path. The project owns it from then on. |
discardedEdits | Each target whose replacement or removal discards content that is not its installed baseline, in the order of the target blockers. At initial adoption there is no baseline, so every replaced existing target is listed. |
confirmation | Whether start needs confirmation after reviewing discarded edits. required is true exactly when discardedEdits is not empty, and reasons has one { "change": "discarded-edit", "target": <path> } entry per discarded edit, in the same order. See confirmation. |
guidance | Guidance by source-relative source path, SHA-256 and executable state, with its explicit project paths or directory trees. |
operations | Ordered fixes and checks, literal arguments, the script by path and hash, resource hash inventories, timeout, and declared prerequisite probe/range. |
project | Hash inventories of the affected targets, of each system skill target in systemSkills by path, of each installed skill’s link in skillLinks by path, and of the durable product state. The project root, Git HEAD, index, and status are not reported. |
inputs, manifest | Hash inventories of the selected source material, and the hash of the normalized single-profile metadata, that adoption retains. |
remoteSetup | Each remote setup fix by declaration and fix id, in execution order, with its readiness status: ready, not-ready with the probe’s reason, or not-checked when the report has start blockers. See remote setup readiness. |
start | Known blockers and prerequisite status. eligible is false for known blockers, null for unverified author prerequisites, and true when neither remains. Start probes every declared prerequisite before installation; contextual declarations stop incomplete after fixes until assessment is available. |
identity | SHA-256 of deterministic report content, prefixed with sha256:. |
Entries in removed and kept carry exactly one installer field: id is
always the standards declaration’s ID, while systemSkill names a retired
product skill such as standards-updates. A system skill has no declaration
and its entry has no id. The summary labels these entries under Owner and
prefixes a product skill’s name with system skill.
For an established adoption, the report is an update. update lists every
changed selection component, in the order cli, standards, source,
profile, platform, and checks, and is empty for an unchanged selection. A recorded
selection without a platform or check location reads that component as github. The standards component
changes with the version tag or its commit. previousSelection records the
current selection, and retired lists declarations that will leave governance.
The installed targets of retired declarations, and any other installed target
the selection no longer installs, leave the selection. Each one that still
matches its installed baseline is listed in removed, and the run removes it.
Each edited one is listed in kept, never in discardedEdits: the run leaves
it in place, durable state no longer records it, and later runs neither list
nor remove it. A skill directory is judged whole, so a skill with any added,
removed, or changed file is kept whole, together with its link whenever the
link is there and safe, tracked or not. A skill link
is otherwise judged on its own, so a link the project replaced with its own
content is kept even when its unedited skill is removed. Only tracked content
is an edit, so ignored or other untracked content alone keeps nothing and still
blocks removal with UNTRACKED_REPLACEMENT. A target observed as unsafe, such
as a re-pointed link, is never kept: it is listed in removed and its safety
blockers stand. 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.
Nor is one at or inside a target the selection still installs, whose own action
covers it. One that contains such a target is removed, even when edited, and
the run then installs the contained target. Initial adoption omits these fields. Any update can be
started; an unchanged selection is applied again. A complete discovery-backed
update also includes scopeChanges, listing individual additions and removals
by declaration relative to the prior complete adoption. Removed contextual
paths remain project content and are not deleted.
Every update report states its class in updateClass. It is an exact update
(exact) only when each declaration’s guidance, discovery guidance, and
operations, including their scripts, arguments, and resources, and each
contextual declaration’s rules, are hash-identical to the retained
inputs, its confirmed scope is unchanged, and no declaration retires. Exact
content, an exact declaration’s rules, skills, and the selection itself can
change in an exact update, and an unchanged selection is one. Any other difference
makes it a contextual update (contextual). contextualChanges lists each
differing declaration by ID with what differs, in the order guidance,
rules, discovery, operations, and scope, or retired for a declaration the
candidate no longer declares; it is empty for an exact update. Operations
compare their complete definitions, including prerequisite probes, timeouts,
and any remote setup readiness probe.
An active discovery declaration differs in scope until a scope proposal
confirms its paths, so a report still awaiting that proposal is contextual.
The class describes the update; it does not decide how the update is handled.
Initial adoption omits both fields.
For an established selection, project.productState is the hash inventory of
the full durable .repo-standards/ tree, including unexpected files. Inspection
rejects additions or removals from its recorded file inventory before creating
an adoption run. This verification is independent of the discovery observation,
which excludes durable product state entirely. Only .repo-standards/local/,
.repo-standards/cache/, and .repo-standards/runtime/node_modules/ are
excluded from this observation; equally named directories elsewhere remain part
of durable state. Installation and final verification use the same inventory
rules.
Reports embed no file bytes. A hash inventory keeps the observed tree: a
directory lists its entries by name, each file has its sha256 and
executable state, and links and unsafe entries keep their observation. Text is
lossless UTF-8 without NUL bytes; anything else is binary. A changed text file’s
diff is a unified diff with three lines of context, a/ and b/ path
prefixes, /dev/null for a missing side, and the \ No newline at end of file
marker. A matching or mode-only change has no diff, and neither has creating
or deleting an empty file, which the before and after states express. Read referenced guidance,
discovery guidance, scripts, and resources at their source-relative paths in
the standards source at selection.standards.commit; adoption retains the same
bytes at .repo-standards/inputs/source/<path>. Start acquires the source again
and verifies its bytes against the hashes the identity binds, so a
report needs no bytes to remain safe.
Whole-skill inventories include existing and supplied files.
Matching exact files and skill directories are matched without rewriting during
adoption.
When an existing exact target conflicts with the supplied file/directory type,
the replacement entry retains both complete root observations, including any
directory inventory. The type conflict remains a start blocker.
Operations list all fixes before all checks; within each phase, declarations
appear by ID and operations retain their declared list order.
Contextual content stays project-owned. All operation prerequisites remain
not-checked: inspection runs no operation and probes no operation
prerequisite. The only author scripts it runs are
remote setup readiness probes.
Identity has no timestamp, random acquisition path, or checkout location. It
binds what the run reads: the exact selection, resolved declarations and
materials through their hashes, affected bytes and executable state through
their hashes, the product-state inventory, blockers and safety observations,
and, when discovery is active, the discovery observation and confirmed scope.
The project root, Git HEAD, the index, and Git status are not bound, except
through the start blockers Git state produces, such as a dirty tree. The same
content inspected from two clones with the same file executable bits has
one identity, so an inspection made in a throwaway clone starts a run in
the maintainer’s checkout. A commit that
touches nothing the run reads leaves the identity unchanged, so an inspection
survives unrelated work between inspection and start; a change to an affected
file’s bytes or executable bit, a retained input, or the product-state inventory changes
it. The discovery observation spans the tracked and non-ignored tree, so for a
discovery-backed selection most commits change the identity. Start still
requires a clean committed tree, except over the changes an abandoned or
replaced run of the same selection preserved, and the run records the project
root and HEAD at start for provenance. Repeated unchanged inspection has the same identity.
start --identity <identity> checks this identity on every start, before it
checks confirmation, and fails with STALE_INSPECTION when
the project or selection no longer produces it.
Confirmation
Section titled “Confirmation”Asking to adopt or update a selection is the maintainer’s consent. An agent
reviews and confirms discarded edits recoverable from Git; a person at a
terminal confirms their own review. Only a fix’s overwrite of a remote setting
someone chose waits for the maintainer’s decision, because Git cannot restore
remote state.
Inspection finds the discarded edits deterministically, from the same
observation as discardedEdits, without running source code. confirmation
is required for every discarded edit, including at an initial adoption, where
every replaced existing target is one. Nothing else requires it: a breaking
source change, a contextual update, a scope proposal, removing retired product
state, and removing unedited installed content in removed all leave
confirmation.required false.
"confirmation": { "required": true, "reasons": [{ "change": "discarded-edit", "target": "AGENTS.md" }]}When required is false, start --identity <identity> proceeds with the
identity alone, and adding --confirmed fails with
CONFIRMATION_NOT_REQUIRED. When it is true, start without --confirmed
fails with CONFIRMATION_REQUIRED, naming each reason in its message and
listing them in its details, and changes nothing; after review and
confirmation, start --identity <identity> --confirmed proceeds. The report binds
confirmation into its identity, so a start’s confirmation always refers to
the inspection it names.
Remote setup readiness
Section titled “Remote setup readiness”When the report has no start blockers, inspection runs the readiness probe of
every remote setup fix, in execution order, before
anything is written. Each probe first has its own prerequisite probed, then runs
as the script protocol describes,
from the project root, with its script read from the acquired or retained
source. A probe that reports ready is ready. Anything else is not-ready
with a reason: the probe’s message, the prerequisite’s code and an
explanation, such as EXECUTABLE_MISSING: gh is not installed or not on PATH.,
or the execution error’s code.
"remoteSetup": [ { "declaration": "github", "id": "labels", "status": "not-ready", "reason": "Sign in with gh auth login." }]Probes must leave the project unchanged. Inspection observes the project,
product state, HEAD and the index around each probe, as check does around a
check, and fails with PROBE_MUTATION, naming the probe and the changed paths,
when a probe changed them; the changes are preserved for review. A probe that
leaves its processes running fails the inspection with AUTHOR_PROCESS_ACTIVE.
With start blockers, no probe runs and each remote setup is not-checked.
The report binds remoteSetup, readiness and reasons, into its identity, so
start runs the probes again and fails with STALE_INSPECTION when a probe’s
answer changed. Keep a probe’s reason stable for the same state. A start whose
inspection has a not-ready entry fails with REMOTE_SETUP_NOT_READY and
writes nothing unless it passes --defer-remote-setup; see
remote setup.
Known blockers include missing commits, dirty Git state, symlink or non-directory
ancestors, special files, case-folded existing-path conflicts, file/directory type
conflicts, and ignored or untracked replacement content.
Case conflicts retain every alias and the exact component when present, so
changes to either remain visible and change the inspection identity.
Git assume-unchanged or skip-worktree flags also block eligibility because they
can hide working-tree changes; clear those flags and reconcile content first.
One ownership rule holds for every installation target, including author
skills and the system skills, at initial adoption and at update. An
existing target whose complete inventory, bytes, and executable state equal the
candidate is matched without rewriting. Tracked content that differs is
replaced, because Git can recover it, and a replaced skill directory is
replaced whole. Content that is ignored or untracked, including an empty
directory, blocks with UNTRACKED_REPLACEMENT. discardedEdits lists each
replacement that discards content other than the target’s installed baseline,
and each one requires confirmation. Existing product
state blocks initial adoption with EXISTING_ADOPTION, unless it is retired,
when the run removes it; see
adopting afresh over installed content.
An inspection of the selection an abandoned or replaced run adopted, in a
checkout that still holds what that run left, adopts again in place.
The run’s verified product state is not an existing adoption, and an update’s
last complete adoption is read from the HEAD the run started from. The Git
start blockers exempt exactly the uncommitted paths the run’s last
observation recorded, and those paths count as recoverable content at their
targets rather than untracked replacement content. Every other uncommitted path
blocks with DIRTY_PROJECT, naming it. The report’s shape and identity are
those of any inspection: what the checkout holds is what it binds.
Established projects can use inspect --json with their pinned CLI to inspect
the unchanged selection from retained material. Starting that inspection
starts a run that applies the selection again. It requires a complete prior
adoption and a clean committed project, and reuses retained source material
when the original source is unavailable. The resolver
rejects targets overlapping .git, .repo-standards, or a system skill.
Inspect updates
Section titled “Inspect updates”Every change to an established selection is one update: the CLI pin, the
standards version, the source, the profile, the platform, the check location, or any combination.
Pass all three source flags to select a standards version, source, or profile,
and --platform with them to select a platform. With the project’s pinned
CLI:
.repo-standards/runtime/node_modules/.bin/repo-standards inspect \ --source https://github.com/OWNER/STANDARDS \ --standards-version v1.3.0 --profile work --jsonTo change the CLI pin, run the candidate exact CLI outside the project. Omit the source flags to keep the current retained standards, or pass them to change the standards selection in the same inspection:
repo-standards-bootstrap --cli-version 10.0.0 inspect --jsonSelecting a standards version, source, or profile requires its public source.
Without source flags, inspection works from retained inputs if the source is
unavailable, but a changed CLI pin still needs its exact npm package and
dependencies to be public or cached. 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 alone. Every update inspection compares bytes, executable state, and
complete skill inventories with the last-complete baselines, and lists each
target whose replacement or removal discards a committed local edit in
discardedEdits; an uncommitted edit makes the project dirty. Known moved tags, incompatible
CLI/format combinations, and changed retained product state are also blockers
or structured failures before mutation.
Exit status 0 means a report was produced, including reports with start blockers.
Status 1 means acquisition, compatibility, prerequisites, or inspection failed.
Status 2 means invalid CLI usage. JSON failures contain valid: false and
errors with stable code and message fields. Source-validation failures
include precise resolver diagnostics in details. Bootstrap failures go to
stderr and exit 1; otherwise it forwards the invoked CLI’s exit status.
Markdown summary
Section titled “Markdown summary”inspect --summary renders the report as a Markdown proposal on stdout instead
of JSON. It has these sections, in order:
- Selection: each selection component before and after, and the changed components; initial adoption has no previous selection.
- Update class: for an update, whether it is an exact or a contextual update, and each declaration that makes it contextual.
- Changed declarations: exact content by declaration and path, created, modified, deleted, or mode changed, including removed targets, each system skill the run creates or replaces, and each skill link the run creates or replaces, after its skill; and contextual declarations with their targets and what changed.
- Discarded edits: present only when a replacement or removal discards
content that is not the target’s installed baseline, listing each such
target, then, when
confirmation.requiredis true, a line stating that starting the run needs confirmation of these discarded edits after review. - Kept targets: present only when an update keeps edited targets that leave the selection, listing each with its declaration as now owned by the project.
- Operations: every fix and check with its literal argument vector, prerequisite probe and range, and timeout.
- Remote setup: present only when the selection declares remote setup, listing each fix by declaration with its readiness, ready, not ready, or not checked, and the probe’s reason.
- Scope changes: discovered-scope additions and removals by declaration, the confirmed discovered scope of an initial adoption, or that discovery scope is not confirmed yet.
- Retired declarations: for an update, the declarations that leave governance and whose unedited installed targets are removed.
- Adopter action: the adopter action the
CLI derives from this inspection, and the candidate release’s author-written
line, or that it sets none. The derived line is deterministic and names the
update class, the declarations whose contextual work the run asks for (every
declaration of an initial adoption, and in an update each declaration whose
inputs differ; a run later reuses the recorded assessment of one whose inputs
and scoped files are unchanged) and any remote setup that is not ready. An
exact update with nothing pending says nothing is needed beyond reviewing and
committing the update. The report carries both in
adopterAction, asderivedand, when the release sets one,authored. - Blockers: present only when the report has start blockers.
- Identity: the inspection identity and start eligibility.
The summary is a pure rendering of the report: the same report renders the same
bytes, so two inspections with the same identity print the same summary. It
describes the report and prescribes nothing. Failures print the usual diagnostic
on stderr, and combining --summary with --json is a usage error with exit
status 2. status --summary renders the status
record the same way.
Discover contextual file scope
Section titled “Discover contextual file scope”A selected repository declaration with discovery uses two read-only inspections.
The first invocation uses the same source, version, profile and project flags
shown above. Its repo-standards/inspection/v10 report adds discovery instructions,
eligible evidence, a request identity, and DISCOVERY_REQUIRED in start.blockers.
The report still includes exact changes, contextual guidance, and all operations.
Unresolved declarations remain in sourceResolved; they do not manufacture
executable targets in resolved.
A proposal answers the request with judgment: which candidates meet each
declaration’s discovery guidance, with reasons, supporting evidence, a coverage
explanation, and unresolved questions. Inventory and hash evidence establish
what was observed; they do not prove that a candidate is a maintained project.
The adopter reviews semantic coverage together with the complete inspection.
adopt asks for each declaration’s entry
in its answers file and prints next steps for judging the candidates.
A declaration may name a
discovery script. Then this first
inspection runs it read-only and returns its entry in discovery.draft, a
repo-standards/scope/v2 proposal with one entry per script, in declaration ID
order. A draft is a starting point, never an accepted scope: the report keeps
DISCOVERY_REQUIRED, and the --summary proposal lists each draft’s included
and excluded candidates and open questions. Answer the questions in
unresolved from project evidence, with reasons, complete the entries of
declarations without a script, and inspect the proposal with --scope as below. The report
of an inspection with --scope carries no draft. start still runs each
script under its lock, and so does adopt while it compares a
recorded scope answer with the fresh draft: the
run retains the draft each confirmed entry was decided from. A script that fails, times out or changes its copy of
the project fails inspection with DISCOVERY_SCRIPT_FAILED, and the project is
unchanged.
Write the JSON proposal outside the adopting project, then inspect it:
repo-standards inspect \ --source https://github.com/OWNER/STANDARDS \ --standards-version v1.2.3 --profile work \ --scope /tmp/project-scope.json --jsonThe proposal holds only judgment and has exactly this structure:
{ "format": "repo-standards/scope/v2", "declarations": [ { "id": "project-docs", "coverage": "Widget is the only maintained project; the other candidates are fixtures.", "candidates": [ { "path": "apps/widget/README.md", "decision": "include", "reason": "The manifest and source establish project membership.", "evidence": ["apps/widget/package.json", "apps/widget/src"] }, { "path": "fixtures/fake", "decision": "exclude", "reason": "This directory supplies test data, not a maintained project.", "evidence": ["fixtures/fake/package.json"] } ], "unresolved": [] } ]}Supply exactly one entry per active discovery declaration, and none for explicit
or excluded declarations; the error names each missing or unknown declaration.
All fields shown are required, and an entry may also carry
noScope; unknown fields, duplicate keys, duplicate list entries, and any other
proposal format fail. Lists are unordered and normalized;
explanation text is preserved verbatim, and any change to the proposal’s text
changes the final inspection identity.
Each included candidate is an individual repository-relative filename, including
an intended new file. Excluded candidates may describe directories or
exact/reserved paths. Every candidate uses the shared safe, repository-relative
explicit-path syntax; exclusions cannot use root, parent, absolute, backslash, or
glob paths. Every entry needs a nonempty coverage explanation, even without
candidates. Empty scope retains the declaration, guidance, and its fixes/checks,
and makes its rules repository-wide.
Nonempty unresolved produces an inspectable report with UNRESOLVED_SCOPE,
never a startable result.
A candidate’s evidence lists the paths of files and directories from
discovery.evidence that support its decision. A path the observation does not
hold as eligible evidence fails, and the error names it. Directory inventories
contain eligible immediate child paths, not all ignored siblings. Every candidate
needs at least one evidence path, except an included file that does not exist
yet. Evidence may come from outside the candidate’s directory, including for a
missing README or README.*. The CLI checks this structural support; the
author’s discovery guidance, agent, and adopter determine its meaning.
The CLI derives every mechanical field from the observation it inspects against:
the request binding, each evidence path’s identity, the absence evidence of each
missing included file, returned in discovery.absence, and the concrete scope
from the included candidates.
Included paths reuse the shared target validation: no directories, globs, root
write scope, unsafe ancestors, symbolic links, special files, exact/reserved overlaps,
duplicate ownership, or aliases under Unicode normalization and case folding.
A valid proposal populates ordinary targets.paths with empty targets.directories
in resolved; the source declarations in sourceResolved and the retained source
manifest remain unchanged. The complete report includes normalized proposal,
rationale, candidate exclusions, guidance, exact changes, and operations together.
The request binds the selection, the durable product-state inventory, and the
complete tracked and non-ignored project snapshot; HEAD and the index are not
bound. Observation records file hashes/executable state,
directory inventories and boundaries, effective Git observation settings, and
consulted .gitignore, Git info/exclude, and global ignore inputs, including their
absence. Directory permissions are not bound: they depend on the checkout’s
umask and Git does not track them. File executable bits remain bound.
Ignore inputs are named by role, never by absolute location: global
for the global excludes, info for the repository info exclude, and each
.gitignore by its project-relative path, each with its content state. A
symbolic .gitignore is recorded by the hash of its target, never the target
itself; the bytes it points to are not bound, as Git 2.32 and later do not
follow it. Changing an input’s content changes the request; moving it with
unchanged content does not. Configured ignore paths preserve significant whitespace when the input is
read; an explicitly empty core.excludesFile disables the default global ignore
input. It retains relevant settings and ignore hashes, not unrelated Git
configuration, credentials, or external ignore-file contents. The final identity
also binds the proposal, rationale, named targets, and their ancestors. Named
paths remain observed even if ignored. Ignored untracked files cannot be used as
file evidence. Unlisted ignored siblings remain outside the observation promise.
Durable product state is excluded from every discovery observation: no file
state, evidence entry, directory inventory, or boundary is recorded for
.repo-standards/ or anything beneath it, and its bytes never count toward the
limits below. Inspection verifies that tree separately and reports it as
project.productState.
Inspection compares observations again before returning. Read failures, unsafe state, detected instability, or exceeded limits return a structured error without a partial successful report. Each observation is bounded to 20,000 directory entries/file observations, 128 directory levels, 8 MiB per file, 64 MiB of file reads, and 30 seconds of traversal. Proposals are limited to 2 MiB. There is no continuous monitoring or atomic filesystem snapshot guarantee. A proposal is judged against the observation it is inspected with. When a change after inspection alters the inspection identity, start rejects the stale identity, and only a new inspection can start.
For initial adoption, start takes the same external proposal file and the
complete inspection’s identity, with --confirmed only when its
confirmation is required:
repo-standards start --source https://github.com/OWNER/STANDARDS \ --standards-version v1.2.3 --profile work --scope /tmp/scope.json \ --identity 'sha256:INSPECTION_HASH' --jsonStart reconstructs the inspection before prerequisites and again before
installation. Missing, invalid, unresolved, or stale scope cannot authorize
mutation. Initial clean committed-project and prerequisite rules still apply.
A scope proposal needs no confirmation of its own. Explicit-target selections
produce the same report format without discovery; execution uses the
observed-scope contract.
Every update, including an unchanged selection, repeats this fresh discovery
pass for every active discovery declaration: pass --scope <file> to the
update commands described above and to the matching start. The
selection, product-state inventory, and project observation are bound into the
request and final inspection identities, so neither a retained historical
proposal nor an earlier inspection authorizes the new run. adopt writes that
proposal from the recorded entries it reuses,
because their discovery guidance, rules and fresh draft are unchanged and their
paths exist, and from the answers it asks for.
After ordinary discovery completion, retained inspect --json remains
repo-standards/inspection/v10 and exposes historicalScope as
repo-standards/scope-history/v7: the last complete run’s accepted inspection
identity, materialized concrete selection, and, when that run discovered scope,
its source-resolved declarations and discovery proposal, rationale, guidance,
references, observation identities, and the draft of each discovery script the
confirmed entry was decided from, with scopeChanges, the paths that run
added and removed against the run before it. After all discovery declarations
are retired, it holds the no-discovery run and the removals that retirement
made. Its evidence: historical describes prior authorization, even in a fresh
checkout without the source. The ordinary report’s current discovery request is
separate and confers no authority or claim of current coverage.
The committed file holds that one run only; earlier runs stay in Git history. It stores the project observation without the evidence array it implies, and the named observation as the delta of the confirmed targets and any boundary entry naming them adds. Both are rebuilt on read with the product’s existing derivation. Scope-history v7 is the only format written; an update also reads scope-history v6. Both readable formats retain discovery drafts.
Retained inspection reads the committed durable state, which is
repo-standards/state/v8, the only state format written, with the last
complete run’s work evidence as
identities and deltas; status echoes it as repo-standards/status/v10. The
older readable repo-standards/state/v7, repo-standards/lock/v1 and
scope-history v6 are read as
the adoption an update replaces. Retained inspection rejects a committed state,
retained scope history, or integrity lock in any other older format with
RETIRED_FORMAT before reading anything else; nothing is converted. Inspecting a source instead previews a
fresh adoption that removes the
retired product state. An active run record in an older format fails every
inspection with RETIRED_RUN, and an archived one with RETIRED_FORMAT, except that an archived
repo-standards/run/v6 report is left unread. A
newer version of any of them fails with NEWER_FORMAT and names using the
pinned CLI; it never calls for fresh adoption.
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.
A confirmed scope never changes during a run. When contextual work needs files outside it, or a confirmed target is mistaken, a different scope takes a new run with a new proposal; see Correct a confirmed scope.
No scope
Section titled “No scope”The entry of an optional declaration may
carry "noScope": true to give it no scope:
{ "id": "hosting-settings", "coverage": "The project is not hosted on a platform these settings govern.", "candidates": [ { "path": "deploy/hosting.yaml", "decision": "exclude", "reason": "This file configures a local preview server, not hosting.", "evidence": ["deploy/hosting.yaml"] } ], "unresolved": [], "noScope": true}noScope must be true, and the entry includes no candidate; its coverage
explanation and evidence-backed exclusions are required as for any entry. No
scope keeps the declaration and its adoption guidance for its assessment, and
nothing else: in resolved the declaration has empty targets, no rules, no
checks or fixes, and "no-scope": true, so the run installs none of its rules,
lists none of its operations, and runs none of them. Its rules are never
repository-wide. A noScope entry for a declaration that is not optional fails
with INVALID_SCOPE, naming the declaration, and so does one with an included
candidate. An entry without noScope keeps the meaning above for every
declaration. The --summary report shows the declaration’s targets and
confirmed scope as no scope, distinct from an empty scope.
An update proposes each scope again. The retained proposal, which status
reports as scopeProposal, keeps noScope, so an update can carry the
decision forward. Moving an optional declaration from no scope into a scope,
or out of one, is a scope change of the
update class, with rules and
operations when it has them: moving in installs its rules and runs its
operations; moving out removes its installed rules file and index entry, as
product-owned state, and ends its governance without changing project content.