# Trusted script protocol

Every active declaration may own checks and repeat-safe fixes as described in
[Author format](https://repo-standards.com/docs/reference/author-format/#checks-and-fixes). Inspection displays their
scripts, literal arguments, resources and prerequisites without executing them;
it runs only the read-only readiness probes of
[remote setup](https://repo-standards.com/docs/reference/script-protocol/#remote-setup-probes) fixes and
[discovery scripts](https://repo-standards.com/docs/reference/script-protocol/#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.

## Prerequisites and invocation

Before changing project content, start invokes every operation's executable,
except a deferred [remote setup](https://repo-standards.com/docs/reference/script-protocol/#remote-setup-probes) 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:

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

## JSON input on stdin

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

```json
{
  "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](https://repo-standards.com/docs/reference/script-protocol/#remote-setup-probes). `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](https://repo-standards.com/docs/reference/script-protocol/#overwriting-a-setting), 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`](https://repo-standards.com/docs/reference/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.

## JSON result on stdout

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

```json
{
  "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.

### Overwriting a setting

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:

```json
{
  "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](https://repo-standards.com/docs/reference/adoption-run/#confirmation-required-changes):
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.

## Remote setup probes

A [remote setup](https://repo-standards.com/docs/reference/author-format/#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.

## Ordering, integrity and incomplete work

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](https://repo-standards.com/docs/reference/assessment-protocol/);
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](https://repo-standards.com/docs/reference/adoption-run/#recover-or-abandon-an-interrupted-run).

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`](https://repo-standards.com/docs/reference/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](https://repo-standards.com/docs/reference/adoption-run/#completion-and-incomplete-results). No process error,
blocked result, failed check or contextual handoff asserts complete adoption.

## Discovery scripts

A discovery declaration's optional
[discovery script](https://repo-standards.com/docs/reference/author-format/#discovery-scripts) 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](https://repo-standards.com/docs/reference/script-protocol/#prerequisites-and-invocation). 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:

```json
{
  "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](https://repo-standards.com/docs/reference/script-protocol/#json-input-on-stdin). This requirement applies from the
[owner's 2026-10-26 decision](https://github.com/lutzseverino/repo-standards/issues/354#issuecomment-6407013223)
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](https://github.com/lutzseverino/repo-standards/blob/main/docs/development/architecture.md#format-versions).
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](https://repo-standards.com/docs/reference/author-format/#optional-discovery) declaration, the entry may
propose [no scope](https://repo-standards.com/docs/reference/inspection/#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](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope)
describes.

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

| `reason`         | The script                                                                |
| ---------------- | ------------------------------------------------------------------------- |
| `TIMEOUT`        | Ran longer than its timeout                                               |
| `PROCESS_ERROR`  | Could not start, exceeded an output limit, or left processes in its group |
| `SIGNAL`         | Ended by a signal                                                         |
| `NONZERO_EXIT`   | Exited with a status other than `0`                                       |
| `PROJECT_WRITE`  | Added, removed or changed anything in the copy                            |
| `PROTOCOL_ERROR` | Printed 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.

## Observed adoption scope

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](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope)
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](https://repo-standards.com/docs/reference/adoption-run/#reused-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](https://repo-standards.com/docs/reference/adoption-run/#adopt-fresh-from-a-retired-format), 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](https://repo-standards.com/docs/reference/inspection/#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.
