Skip to content

Trusted script protocol

Every active declaration may own checks and repeat-safe fixes as described in Author format. Inspection displays their scripts, literal arguments, resources and prerequisites without executing them; it runs only the read-only readiness probes of remote setup fixes and discovery scripts. The maintainer’s request to adopt authorizes their execution. Scripts are trusted code with the invoking user’s host, environment and network access. Declared resources control retention, not sandbox access.

Before changing project content, start invokes every operation’s executable, except a deferred remote setup fix’s, with its literal prerequisite.version-arguments, from the project root. It compares the first complete SemVer-like version observed in either output stream with the declared npm SemVer range. Version fragments from different streams are never combined. A leading v, prerelease and build suffixes are supported. Missing executables, unsuccessful or timed-out probes, unreadable versions and incompatible versions are reported for all operations and block installation. The CLI never installs prerequisites. The operation’s timeout also applies to its probe, with a 1 MiB limit on each output stream.

After installation the CLI invokes this argument vector directly:

[executable, absolute-retained-script-path, ...literal-arguments]

The current directory is the adopting-project root. Arguments containing spaces, empty strings, wildcard characters or shell expressions retain their literal values. There is no shell, author-defined environment override, or custom working directory. The process inherits the CLI environment, except that PWD names its current directory. Retained scripts live under .repo-standards/inputs/source/ at their original source-relative paths. Declared resources keep the same layout; scripts can locate them relative to their own retained path. Other profiles and unrelated source material are not retained.

The CLI supplies one UTF-8 JSON object and closes stdin:

{
"format": "repo-standards/operation/v2",
"operation": { "declaration": "readme", "phase": "checks", "id": "headings" },
"projectRoot": "/absolute/project",
"standards": {
"repository": "https://github.com/alice/standards",
"version": "v1.0.0",
"commit": "40-character-resolved-commit-sha"
},
"profile": "work",
"platform": "github",
"checks": "github",
"declarations": [],
"allowedTargets": { "paths": ["README.md"], "directories": [] },
"overwriteAllowed": false,
"invocation": "run"
}

platform is the hosting platform the project selected, which a script may read to act on that platform; the declarations of other platforms are not active. The optional checks request field names the selected check location; its absence in requests from earlier CLIs means github. It is independent of platform, and does not change declarations’ executable checks arrays. The operation and discovery input formats retain their versions under the optional author-input rule; scripts must ignore fields they do not use. declarations contains every active, fully resolved declaration, including its ID, any platform it names, and complete checks/fixes lists; the empty array above is abbreviated. operation.phase is fixes or checks, or probes for a readiness probe. allowedTargets describes this operation’s owning declaration: file targets are explicit paths, skills are whole .agents/skills/<name> directories, and repository guidance retains its explicit paths and directory trees. All targets are project-relative. Authors must respect that scope, the active profile, and exclusions. overwriteAllowed tells a fix whether it may change or remove an existing setting that holds a different value; it is true only when the maintainer confirmed that overwrite, as described below, and always false for a check.

invocation tells a check what invoked it: "run" for an adoption run, including checks-only continuation after an accepted assessment and resume --retry, and "check" for repo-standards check. Only checks receive it; fix and readiness probe requests have no invocation. A source may use it to apply a rule only within a run. CLIs before the release that added the field omit it, so a script that reads it must handle its absence.

A script must ignore request fields it does not read. The CLI may add fields to repo-standards/operation/v2 without a new format version.

Return exactly one UTF-8 JSON object with these three fields, and exit zero:

{
"format": "repo-standards/result/v2",
"status": "passed",
"message": "Required headings are present."
}

A fix status is unchanged, changed, blocked, or confirmation-required. A check status is passed, failed, or blocked. message is a string explaining the result. Additional fields, wrong formats, including the retired repo-standards/result/v1, invalid statuses, missing fields, multiple JSON values, and non-JSON stdout are protocol errors. Surrounding whitespace is accepted. Write human logs to stderr. A standards failure is a zero-exit failed result; it is distinct from a process failure.

Nonzero exits, signals, timeouts, spawn failures, output exceeding 1 MiB per stream, and invalid protocol output are execution errors. On timeout or excess output the CLI kills the operation’s process group with SIGKILL, so a process ignoring SIGTERM cannot keep the run waiting. This is process cleanup, not a sandbox. Captured output is bounded and retained under ignored .repo-standards/local/operations/. Reports separate process evidence (exitCode, signal, error, timedOut), a parsed result or null, the execution error code or null, and stdout/stderr log paths. Durable state keeps check evidence; detailed logs remain local and are absent from fresh checkouts.

A fix creates a missing setting without asking. When it would change or remove an existing setting that holds a different value, and the request’s overwriteAllowed is false, the fix makes no change and returns confirmation-required, its message naming the setting, its current value, and the value the standard sets:

{
"format": "repo-standards/result/v2",
"status": "confirmation-required",
"message": "tsconfig.json compilerOptions.strict is false; the standard sets true."
}

That is a confirmation-required change: the run stops resumably at the fix, recording its result, and the fixes after it wait. Once the maintainer confirms, resume --confirmed invokes the same fix again with overwriteAllowed: true, and the fix makes the change; the run then continues with the fixes after it, each asking for its own confirmation when it needs one. Once the maintainer declines, resume --defer records the whole fix as deferred, invokes it no further in that run, and continues with the fixes after it; every later run invokes it again, with overwriteAllowed: false. A fix invoked with overwriteAllowed: true must not return confirmation-required; that result is a protocol error. A check never returns it.

A fix that returns confirmation-required must have made no change. When its observed interval changed any path, the result is a protocol error: the run stops with PROTOCOL_ERROR, naming the changed paths, and resume --confirmed does not accept it. Recover with resume --retry, or abandon the run.

A remote setup fix’s readiness probe runs during inspection, before anything is written, so it reads its script from the acquired source, or from the retained inputs when inspection uses retained standards. Its prerequisite is probed first, as an operation’s is. The probe is invoked like a check, from the project root, with the same input: its operation is { "declaration": <id>, "phase": "probes", "id": <fix id> }, allowedTargets are its fix’s declaration’s, and overwriteAllowed is always false. It has no invocation.

A probe status is ready or not-ready; message explains it, and for not-ready it is the reason the adopter reads, such as Sign in with gh auth login. Keep the reason stable for the same state: it is part of the inspection identity. A probe must not change anything, in the project or on the platform. Inspection fails with PROBE_MUTATION when a probe changed the project, as check fails with CHECK_MUTATION. A missing or incompatible executable, an execution error, or a protocol error makes the remote setup not-ready, with the code as its reason, and does not stop inspection; only a change to the project, or processes the probe leaves running, does. Probes run in every inspection, including later runs that apply a deferred remote setup once its probe reports ready.

A deferred remote setup’s fix does not run, and its prerequisite is not probed, in that run. A remote setup that is ready runs as any other fix, with the fix protocol above.

Declarations execute by ID; operations execute in their listed order. All fixes but deferred remote setup run before contextual work. Checks run after a satisfied, current agent assessment; profiles without contextual declarations run checks immediately after fixes. Excluded declarations and their operations never run. Fixes stop at the first block, execution error, or confirmation-required result. Ordinary failed checks allow remaining checks to collect evidence. A blocked check or execution error stops further execution.

Fixes must be safe to repeat, including after interruption at any point. Observe the current project and make only the missing changes; do not assume a previous invocation finished or never started. Return unchanged when no work is needed. The CLI records an uncertain operation before invocation and records its result afterward. Recovery requires explicit resume --retry: it verifies installed progress, repeats fixes, requests renewed contextual assessment, and reruns checks before completion. It never implicitly retries an uncertain operation. Use abandon to preserve incomplete work and its report without asserting completion. A surviving author process group blocks retry and abandonment even after its direct fix or prerequisite probe returns. See the recovery commands.

Checks must leave project content unchanged. The CLI compares tracked and non-ignored untracked content before and after each check, independently of whether adoption already dirtied the working tree. It also verifies exact bytes and executable state, whole skill inventories, retained inputs, runtime files, product state, HEAD and the index against installation expectations after each operation. Index verification includes skip-worktree and assume-unchanged flags that can conceal later edits from Git status. Unexpected changes are preserved and adoption remains incomplete; they cannot redefine the installed baseline. Altered local run-report bytes are preserved beside the operation logs before the incomplete report is saved.

Between runs, check runs the adopted checks on demand with the same input and prerequisites, and fails when a check changes the project.

Use status --json and the incomplete report to review actual changes and successful, failed or uncertain work. Follow the recovery instructions in Adoption. No process error, blocked result, failed check or contextual handoff asserts complete adoption.

A discovery declaration’s optional discovery script drafts its scope proposal. inspect runs it only when discovery is required, which means inspection without --scope. Each active declaration that names a script runs it, in declaration ID order. Inspection first runs its prerequisite probe as above. An unmet prerequisite fails inspection with DISCOVERY_SCRIPT_FAILED, the probe’s code as its reason, and the probe’s output as its stdout and stderr. The script does not run.

The script runs in a temporary copy of the files and directories the discovery observation holds: the project’s tracked and non-ignored content, without Git metadata or .repo-standards. A symbolic link whose target leaves the copy is omitted. The copy is its current directory and projectRoot, and relative executables resolve from it. The argument vector is the same as an operation’s, with the script’s absolute path in the acquired or retained source. The script reads one JSON object on stdin:

{
"format": "repo-standards/discovery/v1",
"declaration": "project-docs",
"projectRoot": "/tmp/repo-standards-discovery-1a2b3c/project",
"standards": {
"repository": "https://github.com/alice/standards",
"version": "v1.0.0",
"commit": "40-character-resolved-commit-sha"
},
"profile": "work",
"platform": "github",
"checks": "github"
}

A discovery script must ignore request fields it does not read, including unfamiliar additive request fields, matching the operation-input rule. This requirement applies from the owner’s 2026-10-26 decision onward; it does not establish that previously authored strict readers violated the earlier contract. The CLI may add compatible optional fields to repo-standards/discovery/v1 without a new format version, under the input format-version policy. This input-field tolerance does not change discovery output validation below.

It prints a repo-standards/scope/v2 proposal holding exactly one entry, for its declaration, and exits with status 0. Its evidence paths are project-relative paths of eligible files and directories, and the membership questions it cannot answer go in unresolved. For an optional declaration, the entry may propose no scope with "noScope": true; for any other declaration such an entry is a PROTOCOL_ERROR. The script only drafts: the person or agent answers its questions and submits the completed proposal, as the inspection contract describes.

The script must not change the copy. Inspection fails with DISCOVERY_SCRIPT_FAILED when the script:

reasonThe script
TIMEOUTRan longer than its timeout
PROCESS_ERRORCould not start, exceeded an output limit, or left processes in its group
SIGNALEnded by a signal
NONZERO_EXITExited with a status other than 0
PROJECT_WRITEAdded, removed or changed anything in the copy
PROTOCOL_ERRORPrinted other than one valid entry for its declaration

A valid entry passes the checks inspect --scope applies to a submitted entry, except how its targets fit those of other declarations. The error’s details name the declaration, the reason, and the script’s stdout and stderr, each limited to 1 MiB. Inspection stops processes the script or its probe left in their group before it removes the copy. A group that survives being killed fails inspection with AUTHOR_PROCESS_ACTIVE, naming the group and the copy, which is left in place, as it is when process state cannot be read (PROCESS_STATE). The project is unchanged in every case. The copy protects the project, not the host: a discovery script is trusted code like every other author script.

Every adoption uses the same execution machinery and unchanged repo-standards/operation/v2 input and repo-standards/result/v2 output. Each fix’s observed added, deleted, edited, and executable-state-changed files must fit its owning declaration, not the union of all declarations. A violation reports OPERATION_SCOPE, the operation, and the offending paths that still differ from their state before the run. Checks report CHECK_MUTATION for observed writes, even within their allowed targets. Restoring such a path in place reconciles the violation, as described below. A successful process/result does not override scope or exact-integrity failure. Exact bytes, executable state, and complete skill inventories (including directory paths and added empty directories) stay protected against their own declaration’s fixes too.

Observations include tracked and non-ignored content, named targets even after they become ignored, their ancestors, effective observation settings and ignore inputs. Explicit directory targets include ignored descendants. Generated .repo-standards content is verified separately against installation expectations. The same directory-aware inventory comparison protects durable product state, including retained inputs and runtime manifests. Only local, cache, and runtime/node_modules are excluded from that inventory: local logs/caches are generated outputs, and runtime dependencies have their own complete-tree integrity check. Unlisted ignored siblings outside explicit directory trees are not inventoried; trusted scripts retain host/network access. These are bounded before/after observations, not continuous monitoring or atomic filesystem snapshots. The same observation limits apply; incomplete reads, unsafe boundaries, instability, or exhausted limits block progression and preserve incomplete work.

repo-standards/run/v8 records observations separately from operations and assessments. Each interval has a phase (fixes, checks, or agent), its applicable declaration scope, and the before observation identity. Closed intervals add the after identity, changes, boundaryChanges, and violations. Operation intervals identify the operation and its operationIndex in the run’s operation history; an interval closed during explicit recovery has interrupted: true when its operation outcome was not fully recorded. An open interval is evidence that observation is incomplete, never evidence of no changes. Observations contain file identities and executable state, boundaries, settings, and consulted ignore-input identities. Changes to external ignore inputs/settings are reported as @ignore/global, @ignore/info, or @git/observation-settings and cannot be authorized as project paths.

The run record, the local run report, and an archived abandoned report record each interval in the same shape committed state uses, described below, and never carry an observation map; a run record that does fails integrity validation. Full observations are held in memory while a command observes. Only the one observation the last interval ends at, its before while open or its after once closed, is kept beside the run record in Git’s working-tree metadata, named by its identity, so a later command can close or continue that interval. It is replaced as the run advances and removed at completion or abandonment. When it is missing or altered, status reports that in uncertain and resume fails with STATE_INTEGRITY; abandon the run to keep its evidence.

Adjacent observations are compared across operation and handoff boundaries; work between author invocations has its own agent interval. Named file scope permits creating missing parent directories and removing a directory whose files the authorized changes removed, but not changing directory modes or replacing directories. A directory emptied earlier in the run may be removed later. Checks may not create or remove even empty directories.

Retry retains intervals and earlier agent evidence before repeating fixes; it cannot authorize new scope or hide a recorded violation. A recorded scope or check-mutation violation is reconciled when its path, a file or a boundary directory, is back at the state it had before the earliest interval of the run that changed it: remove a file the run added, restore an edited file’s committed content, or remove a directory the run created. Reconciled violations stop nothing, and the intervals keep them as observed. A path that still differs, a changed directory mode, or a directory replaced by a file still violates until restored. A fix or check that writes the path again records a new violation and fails as before. An incomplete observation must first become readable and complete. Restoring corrupted exact content is permitted only after verifying the immutable installation expectations; restoredExact records those restored identities separately from contextual work. restoredBoundaries covers only recreated parents of restored exact files or removal of extra directories inside a verified skill inventory; it never exempts changes to existing directory modes. This grants no new contextual scope. Durable repo-standards/state/v8 and repo-standards/status/v10 retain work evidence: the run’s intervals, operation history, retry history, final checks and assessments, and the run’s net change set, changeSet. Completion commits the run record’s intervals unchanged. A recorded interval is identities plus delta, never an observation map. It keeps before and after observation identities, changes mapping each changed path to its before and after file state, boundaryChanges mapping each changed boundary to its before and after state, violations, any restoredExact and restoredBoundaries evidence, its phase, scope, operation reference, operationIndex, and interrupted. Identities are the product’s observation identity, sha256: over the observation the run held, so the recorded delta stays tamper-evident without the full maps.

State v8 holds the last complete run’s evidence only, with its lastComplete record; a completion replaces the previous run’s evidence rather than carrying it, and Git history keeps earlier runs. Detailed logs remain local; the recorded outcomes and interval evidence survive a fresh checkout. The integrity lock remains repo-standards/lock/v2 and binds the new state bytes.

State v8 is the only state format written. An update also reads state v7, lock v1 and scope-history v6 as the adoption it replaces, so that it reuses the answers they prove. A committed state whose intervals carry observation maps, whose closed interval is missing either identity, or that carries an earlier run’s history, fails state integrity validation. A state, run record, or scope history in a retired format is never read or converted; the project adopts fresh, and a run record calls for the CLI that wrote it. A newer version of these records fails with NEWER_FORMAT, requiring the pinned CLI without changing anything. status, resume, and abandon reject a different CLI with CLI_PIN_MISMATCH before checking record formats. Retained inspection also checks exact-skill and durable product directories against the paths implied by the recorded file inventory, so later empty-directory edits block updates before mutation. Retained inspection is repo-standards/inspection/v10 with repo-standards/scope-history/v7 after discovery completion, the only scope-history format written: it holds the last complete run, its discovery stored as its project observation without the derived evidence array, its named observation as a delta, and each discovery script’s draft its confirmed entry was decided from, and its scope change against the run before it.

Confirmed discovery declarations are materialized into the existing target representation before execution. allowedTargets.paths is the confirmed file list and allowedTargets.directories is empty. The active resolved declarations carry those same targets; operations do not interpret discovery guidance. Empty scope still executes its fixes and checks and requires contextual coverage review. An optional declaration with no scope executes none: its resolved declaration, as every operation’s declarations input lists it, has empty targets, no checks or fixes, no rules, and "no-scope": true. Deletion and creation are separate observed changes: a move grants no implicit authority for its destination or link repairs. Excluded candidates and declarations grant no deletion authority.