Skip to content

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:

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

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

Terminal window
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" --version

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

Every report has the single format repo-standards/inspection/v10. A profile with discovery declarations adds the discovery and sourceResolved fields described below:

FieldMeaning
selectionExact CLI package/version, canonical standards URL, version tag, commit SHA, profile, platform, and check location (checks).
source, resolvedValidated metadata and the resolver’s complete active profile on the selected platform.
exactDeclaration 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.
systemSkillsEach 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.
removedFor 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.
retiredStateFor 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.
keptFor 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.
discardedEditsEach 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.
confirmationWhether 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.
guidanceGuidance by source-relative source path, SHA-256 and executable state, with its explicit project paths or directory trees.
operationsOrdered fixes and checks, literal arguments, the script by path and hash, resource hash inventories, timeout, and declared prerequisite probe/range.
projectHash 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, manifestHash inventories of the selected source material, and the hash of the normalized single-profile metadata, that adoption retains.
remoteSetupEach 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.
startKnown 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.
identitySHA-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.

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.

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.

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:

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

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

Terminal window
repo-standards-bootstrap --cli-version 10.0.0 inspect --json

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

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.required is 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, as derived and, 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.

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:

Terminal window
repo-standards inspect \
--source https://github.com/OWNER/STANDARDS \
--standards-version v1.2.3 --profile work \
--scope /tmp/project-scope.json --json

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

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

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

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.