# Author format: repo-standards/v2

An independently authored standards repository supplies one root
`standards.yaml` and ordinary referenced files. Run
`repo-standards source validate [directory] [--json]` before publication. The
directory defaults to the current directory. All profiles are validated; there
is no profile filter. This command reads local sources, never executes author
scripts or prerequisite probes, and does not change the source or Git state.
Local-directory adoption is not an interface of this product.

## Format identity

Every source declares `format: repo-standards/v2`, the only supported format.
Validation rejects any other value with `INVALID_FORMAT`. Repository guidance
uses either explicit targets or project-specific discovery; file declarations,
skills, operations, and profile resolution are the same for both scope modes.
Set the CLI compatibility range to versions actually validated; the format
identity and CLI package version are independent. Older CLIs reject unsupported
formats.

This implementation supports discovery authoring, validation, and
[two-pass scope inspection](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope).
A selected profile with unresolved discovery returns guidance, eligible evidence,
a discovery request identity, the draft of each
[discovery script](https://repo-standards.com/docs/reference/author-format/#discovery-scripts), and a `DISCOVERY_REQUIRED` start blocker.
`inspect --scope` validates an evidence-backed `repo-standards/scope/v2` proposal
and presents concrete paths in the complete inspection. Initial adoption passes
the same proposal to `start --scope`, bound to that inspection’s identity.
Contextual assessment reviews coverage again after fixes and before
submission. Empty scope retains the declaration and its operations; an
[optional](https://repo-standards.com/docs/reference/author-format/#optional-discovery) declaration may instead have no scope, which
installs none of its rules and runs none of its operations. Source
validation alone proves neither project-specific safety nor semantic coverage.
An active run cannot change its confirmed scope; when contextual work needs
other paths, a new run
[adopts again with a new confirmed scope](https://repo-standards.com/docs/reference/adoption-run/#correct-a-confirmed-scope).
Fresh discovery proposals also apply during every update, including one that
applies an unchanged selection again. `adopt` reuses the recorded entry in that
proposal only while the declaration's discovery guidance, rules and fresh
discovery-script draft are unchanged and every path the entry names exists,
and otherwise proposes it for review
([reused answers](https://repo-standards.com/docs/reference/adoption-run/#reused-answers)): changing discovery guidance,
rules, or what a discovery script drafts makes adopters review the scope again.
Changing a contextual declaration's rules, or its adoption guidance when it has
no rules, likewise makes adopters assess it again. Between complete runs, scope
can add or remove individual paths; removals end governance without deleting
project content.

## Root and profiles

The root requires exactly these fields, and may set one optional field,
`adopter-action`. Unknown fields at every schema level
are errors, including adoption hooks, environment overrides, shell options,
custom working directories, and profile inheritance fields.

| Field         | Value                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `format`      | `repo-standards/v2`                                                                                                                                    |
| `name`        | Nonempty descriptive string                                                                                                                            |
| `description` | Nonempty descriptive string                                                                                                                            |
| `requires`    | Mapping containing only `repo-standards`, a nonempty npm SemVer range compatible with the running CLI; declare an open-ended minimum such as `>=7.0.0` |
| `defaults`    | Mapping containing only `declarations`, a mapping of IDs to declarations (possibly empty)                                                              |
| `profiles`    | Nonempty mapping of profile names to complete profiles                                                                                                 |

### Adopter action

The optional root field `adopter-action` holds one nonempty line of plain text
that tells adopters of this release what to do outside adoption, such as
rotating a credential the standards stop using. It is additive within
`repo-standards/v2`. Validation rejects an empty or blank value, a value with
more than one line or a control character, and a value that is not a string,
with `INVALID_TYPE`. The CLI cannot check that the action lies outside
adoption, which the run already performs: the author is responsible for that.

Older CLIs reject the field as `UNKNOWN_FIELD`, so a source that sets it raises
`requires.repo-standards` to the first CLI release that accepts it. The CLI
retains the line with the other source metadata, shows it in the
[inspection summary](https://repo-standards.com/docs/reference/inspection/#markdown-summary) and the adoption record's
Impact and Migration sections, and renders each newer release's line in
[`outdated`](https://repo-standards.com/docs/reference/available-updates/#adopter-actions). It derives the rest of
the [adopter action](https://github.com/lutzseverino/repo-standards/blob/main/GLOSSARY.md#language) itself.

Each profile requires a nonempty `description` and a `declarations` mapping,
which may be empty, and may name the hosting [platforms](https://repo-standards.com/docs/reference/author-format/#platforms) it
supports. Declaration IDs, skill names, and operation IDs use
lower-case ASCII kebab-case: letters or digits separated by single hyphens.
Declaration IDs are local to the source. Operation IDs are unique across the
checks and fixes of their declaration; another declaration may reuse one.

Exactly two resolution levels exist: defaults and one selected profile.
Omitting an ID inherits its whole declaration. Repeating it replaces the whole
declaration, including checks and fixes. A new ID adds a declaration.
`id: {exclude: true}` removes an existing default declaration and its operations;
it cannot have any other fields, appear in defaults, or name a nonexistent
default. Fields never merge. Resolved declarations are ordered by ID, with
operation list order preserved. No targets are compared across separate
profiles. Every declared reference is checked, including a default replaced or
excluded by all profiles.

YAML is a single document with string mapping keys and standard YAML 1.2
scalar types. Quote version ranges and literal numeric arguments. Duplicate
mapping keys are errors, including repeated profile and declaration IDs.
Anchors and nonrecursive aliases are supported; custom tags and merge keys are
not part of the format. Recursive, excessively deep, or excessively expanded
YAML is rejected with `YAML_STRUCTURE`. Duplicate fields remain invalid, but
their alternative values are still validated for independent errors; more than
256 ambiguous interpretations also produces `YAML_STRUCTURE`.

### Platforms

```yaml
defaults:
  declarations:
    ci-workflow:
      kind: file
      platform: github
      target: .github/workflows/check.yml
      exact: content/check.yml
profiles:
  work:
    description: Work projects
    platforms: [github]
    declarations: {}
```

A profile lists the hosting platforms an adopting project can select it on in
`platforms`, a nonempty list of distinct platform names. A profile without
`platforms` supports `github` alone, so a source that names no platform is
unchanged. The adopting project selects its platform separately from its
profile; see [choose the hosting platform](https://repo-standards.com/docs/reference/adoption-run/#choose-the-hosting-platform).
Do not split a profile per platform, such as `react-github` and
`react-gitlab`: declare the platform choice inside the profile.

Any declaration may name the one `platform` it applies on, in defaults or a
profile. On every other platform the declaration is left out of the resolved
profile, before scope, so it installs nothing, runs no operation and needs no
discovery. That differs from an [optional](https://repo-standards.com/docs/reference/author-format/#optional-discovery) declaration's
no scope, which each project decides in its scope answer. A declaration without `platform`
applies on every platform of its profile. An exclusion takes no `platform`.

Older CLIs reject `platforms` and `platform` as unknown fields, so a source
that uses them raises `requires.repo-standards` to the first CLI that accepts
them. Platforms are named as Postern names them. This CLI supports `github` only, so
every other name fails with `UNSUPPORTED_PLATFORM`, an empty list with
`EMPTY_PLATFORMS`, and a repeated platform with `DUPLICATE_IDENTITY`. Until
another platform is supported, published files stay GitHub-shaped.
Declarations for different platforms never apply together, so their targets
may overlap; targets of declarations that can apply together may not.

## Check locations

A profile may offer `check-locations: [github, runner, self-reported]`, or any
nonempty subset. `github` means hosted GitHub Actions, `runner` a
repository-named machine posting commit statuses, and `self-reported` the
authoring agent's sandbox. Omitting the profile key means `[github]`.
The project selects exactly one through `--checks` or an answers-file `checks`
answer, independently of its hosting platform; see
[choose the check location](https://repo-standards.com/docs/reference/adoption-run/#choose-the-check-location).

Any declaration, in defaults or a profile, may filter applicability through
`check-locations: [...]`. Without that key it applies at every location the
profile offers. Both arrays must contain unique supported strings and be
nonempty. Invalid types, empty arrays, duplicates and unknown values name the
offending field and, for an invalid entry, its value.

```yaml
profiles:
  work:
    description: Work projects
    check-locations: [github, runner, self-reported]
    declarations:
      ci-workflow:
        kind: file
        platform: github
        check-locations: [github]
        target: .github/workflows/check.yml
        exact: content/check.yml
```

Platform and check-location filters apply together before scope: a declaration
left out installs nothing, contributes no rules, executes no checks, fixes or
discovery script, and asks for no scope. This is distinct from confirming an
optional declaration with no scope. Defaults, whole replacements and exclusions
keep their usual meaning; an exclusion accepts only `exclude: true`.
Declarations that cannot apply together on any offered location and platform
may share targets; overlapping applicability keeps the usual target conflicts.
Declaration `checks` still names executable operations, never a location filter.

Sources using either optional author key must set `requires.repo-standards` to
an open-ended minimum CLI release that understands check locations. Older CLIs
reject the keys. The optional author keys keep `repo-standards/v2` because
sources that omit them keep their meaning.

## Declarations

All four forms may contain optional `checks` and `fixes` lists. Omitted lists
resolve to empty lists, and every form but an exact skill may name optional
[`rules`](https://repo-standards.com/docs/reference/author-format/#rules-and-adoption-guidance). Their remaining fields are:

| Form                | Required fields                                                                                                                                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Exact file          | `kind: file`, one `target`, and `exact` referencing a regular source file                                                                                                                                                                                          |
| Contextual file     | `kind: file`, one `target`, and `guidance`, its adoption guidance, referencing a regular source file                                                                                                                                                               |
| Exact skill         | `kind: skill`, `name`, and `source` referencing a whole directory containing a regular `SKILL.md`                                                                                                                                                                  |
| Repository guidance | `kind: repository`, `guidance`, its adoption guidance, referencing a regular file, and exactly one scope mode: explicit `targets` containing both `paths` and `directories` lists, or `discovery` referencing a regular file, optionally with a `discovery-script` |

A file must have exactly one of `exact` or `guidance`. Repository guidance
requires exactly one of `targets` or `discovery`, and explicit targets need at
least one path or directory.

### Rules and adoption guidance

Every form but an exact skill may also name `rules`, referencing a regular
source file: human-readable Markdown stating the declaration's lasting
requirements. Adoption installs each active declaration's rules at
`.repo-standards/rules/<declaration ID>.md` as exact content the CLI owns, with
a generated index, and checks and assessments cite them; see
[installed rules](https://repo-standards.com/docs/reference/rules/). `guidance` is the declaration's adoption guidance:
one-time instructions for the run, such as a migration, a question for the
maintainer, or how to assess the declaration. It is kept only with the
retained inputs and never installed. Keep lasting requirements in `rules` and
one-time steps in `guidance`.

A skill declaration with `rules` fails with `UNKNOWN_FIELD`. A declaration with
`rules` cannot have the ID `readme`, whose installed rules would collide with
the index `README.md`; it fails with `RESERVED_NAME`. A repository guidance
declaration whose confirmed scope is empty is repository-wide: its rules cover
every path of the adopting project. An
[optional](https://repo-standards.com/docs/reference/author-format/#optional-discovery) declaration confirmed with no scope installs
no rules at all. Exact skills target
`.agents/skills/<name>` as a whole, and adoption also installs the skill's
[skill link](https://repo-standards.com/docs/reference/adoption-run/#skill-links) at `.claude/skills/<name>`, which is a
target of the skill too: no other target may overlap it. `repository-standards`,
`author-standards`, and `adopt-repository-standards` are product-owned system skill names reserved against
author skills. The retired `adopt-standards` and `standards-updates` names are
not reserved. Author skill content remains ordinary Agent Skill material; source
validation verifies its directory, `SKILL.md` references, and invocation agreement, not prose quality or
skill behavior.

### Skill invocation

Claude Code reads `disable-model-invocation` from the YAML frontmatter in
`SKILL.md`. Codex reads `policy.allow_implicit_invocation` from the skill's
`agents/openai.yaml`. These settings must agree: manual-only skills use `true`
and `false`, respectively; model-invocable skills use `false` and `true`.
An absent setting means model-invocable, including absent frontmatter or an
absent `agents/openai.yaml`. A skill that states neither passes unchanged.
Present invocation settings must be YAML booleans. Other skill metadata is
outside the author schema.

Unrelated duplicate keys, invalid YAML, or non-mapping metadata with no
invocation setting use the setting's default without a diagnostic. A duplicated
invocation key, a non-boolean setting, or an unparseable document containing a
line for that setting produces a diagnostic naming its metadata file.
Frontmatter delimiters accept trailing spaces or tabs and a leading byte-order
mark before the opening delimiter.

`source validate` checks every declared skill, including replaced or excluded
defaults and skills in unselected profiles. A disagreement produces
`SKILL_INVOCATION_MISMATCH`, naming the skill and both effective values.

### Discovery guidance

```yaml
format: repo-standards/v2
name: project-documentation
description: Documentation for maintained projects
requires: { repo-standards: "<validated CLI SemVer range>" }
defaults:
  declarations:
    project-documentation:
      kind: repository
      guidance: guidance/documentation.md
      rules: rules/documentation.md
      discovery: guidance/find-projects.md
profiles:
  work:
    description: Documentation for all maintained projects
    declarations: {}
```

Replace the compatibility placeholder with the CLI SemVer range actually tested,
and supply the referenced files. `rules/documentation.md` states what the
discovered documentation must keep satisfying, such as documenting real
commands. `guidance/documentation.md` is the adoption guidance: how to assess
or adapt project content during the run, such as preserving useful facts while
moving them. `guidance/find-projects.md` describes where that guidance applies: for
example, evidence of maintained projects including projects missing READMEs, and
criteria for distinguishing fixtures, generated output, and organizational
directories. Discovery guidance is prose that an agent or person interprets.
A declaration may also name a [discovery script](https://repo-standards.com/docs/reference/author-format/#discovery-scripts) that
drafts the proposal; the prose remains valid with or without one.

A source-resolved discovery declaration has a `discovery` reference and no
`targets`; this is unresolved scope, not an empty or whole-repository entitlement.
Project discovery must eventually identify individual existing or intended file
paths, including migration sources, destinations, and link repairs. Semantic
coverage requires agent interpretation and adopter review. Discovered directory
trees, globs, root scope, `protect` fields, and subtracting exact descendants
from contextual trees are unsupported. Explicit directory scopes remain disjoint,
including from exact configuration beneath them.

### Discovery scripts

```yaml
project-documentation:
  kind: repository
  guidance: guidance/documentation.md
  discovery: guidance/find-projects.md
  discovery-script:
    run:
      executable: node
      script: discovery/find-projects.mjs
      resources: [discovery/data]
      arguments: []
    prerequisite:
      version-arguments: ["--version"]
      version: ">=24.0.0 <25.0.0 || >=26.0.0 <27.0.0"
    timeout-seconds: 60
```

A declaration with `discovery` may name a `discovery-script`, declared like a
[check](https://repo-standards.com/docs/reference/author-format/#checks-and-fixes) without an `id`: `run`, `prerequisite` and
`timeout-seconds` have the same fields and rules. A `discovery-script` without
`discovery` is `INVALID_DECLARATION`. Source validation checks its fields and
references and never runs it. When discovery is required, inspection runs it
read-only to draft the declaration's scope proposal and its open questions; it
never decides scope. The
[discovery script protocol](https://repo-standards.com/docs/reference/script-protocol/#discovery-scripts) defines its
input, output and failures.

### Optional discovery

```yaml
hosting-settings:
  kind: repository
  guidance: guidance/hosting.md
  rules: rules/hosting.md
  discovery: discovery/hosting.md
  optional: true
```

A declaration with `discovery` may be marked `optional: true` when an
adopting project may have nothing it governs. Its confirmed scope may then be
*no scope*, which a [scope proposal](https://repo-standards.com/docs/reference/inspection/#discover-contextual-file-scope)
marks with `noScope`. No scope differs from an empty scope:

* an empty scope makes the declaration repository-wide, so its rules cover
  every path, and its checks and fixes run;
* no scope installs none of its rules, is never repository-wide, and runs none
  of its checks or fixes. The adoption still assesses whether no project file
  belongs in its scope.

A proposal without `noScope` keeps its ordinary meaning for an optional
declaration too, so an optional declaration's empty scope is still
repository-wide. Each update reviews the scope again: an update can give an
optional declaration a scope it had none of, which installs its rules and runs
its operations, or take its scope away, which removes its installed rules and
leaves project content in place.

`optional` must be `true`. On repository guidance with explicit `targets` it
fails with `INVALID_DECLARATION`, and on a file or a skill with
`UNKNOWN_FIELD`. Only discovered scope can be no scope.

### Paths and ownership

Source and target paths use repository-relative forward-slash syntax. Absolute
paths, drive prefixes, backslashes, control characters, empty components, `.`
and `..` components are rejected. Write `src/file.ts`, not `./src/file.ts`.
Targets also reject glob metacharacters (`* ? [ ] { }`). Paths are relative to
the source root or future adopting-project root, never the YAML file's section.

All referenced files, directory ancestors, and whole skill/resource trees must
exist and contain only regular files and directories, with no symbolic links.
The source root and `standards.yaml` cannot themselves be symbolic links.
Root license entries and their contents retained by adoption are selected
material too and cannot contain symbolic links. Entries may be files or
directories. Their root names match `LICENSE` or `LICENCE` case-insensitively,
optionally followed by a dot or hyphen suffix.
Unreferenced source files are outside validation's selected material. Targets
need not exist in the standards repository; adopting-project symlink and
ownership checks belong to inspection and adoption.

Within each resolved profile, no explicit target can equal, contain, or be contained
by another target, including two entries of one repository declaration.
Comparison also catches case-insensitive and Unicode-normalized collisions.
Product state (`.repo-standards`), every system skill target
(`.agents/skills/repository-standards`, `.agents/skills/author-standards`,
and `.agents/skills/adopt-repository-standards`)
and its skill link
(`.claude/skills/<name>`), Git metadata (`.git`), and their ancestors and descendants are reserved targets.
These restrictions apply to exact files, contextual files, and repository
guidance as well as skills, using the same case-folded and Unicode-normalized
comparison. Validation checks defaults and every profile, including profiles
other than the one selected for inspection.

Reservation applies within the standards format; it does not manage unrelated
global skill installations. Adoption installs the `repository-standards`
system skill matched to the project's exact CLI pin. It
does not automatically install the standalone `author-standards` or
`adopt-repository-standards` skills or change runtime ownership,
integrity baselines, or update behavior.

## Checks and fixes

Every operation requires all of the following fields:

```yaml
checks:
  - id: headings
    run:
      executable: python3
      script: defaults/checks/readme.py
      resources: [defaults/checks/data]
      arguments: ["--strict", "two words", ""]
    prerequisite:
      version-arguments: ["--version"]
      version: ">=3.12.0 <4.0.0"
    timeout-seconds: 60
```

`run` and `prerequisite` are mappings with exactly the fields shown.
`executable` identifies one command name or executable path with this syntax:

* Allowed characters are ASCII letters, digits, `.`, `_`, `+`, `-`, and `/`.
* The value cannot begin with `-`. Use an explicit path such as `./-wrapper`
  for an executable whose basename starts with a hyphen.
* `/` separates path components; a leading `/` denotes an absolute path.
  Empty components elsewhere, a trailing `/`, and basenames `.` or `..`
  are rejected. Directory components `.` and `..` are allowed.

Examples: `python3`, `clang++`, `/usr/bin/python3`, `./tools/checker`, and
`../tools/checker`. This explicit character set rejects shell expressions,
quoting, whitespace, controls, and non-ASCII executable spellings. Executable
paths refer to installed tools on the adopting machine; they are not retained
source paths. Relative executable paths resolve from the adopting-project root.
The value is preserved literally and is not looked up or run during source
validation. A syntactically valid executable may be unavailable; adoption's
prerequisite checking reports that separately.

`script` must reference a regular source file.
`resources` explicitly lists any additional source files or whole directory
trees; an empty list is valid. `arguments` and `version-arguments` are literal
string lists; empty lists and empty string arguments are valid. NUL bytes
cannot occur in strings. The prerequisite `version` is a nonempty npm SemVer
range. `timeout-seconds` is a positive safe integer.

Adoption invokes the executable directly with the retained script path
followed by literal arguments, from the adopting-project root. No shell
expansion is applied to arguments. Scripts are trusted code; resources describe
retention and do not restrict host or network access. Fixes must be safe to
repeat; checks must not mutate project content. A fix that would overwrite an
existing setting holding a different value asks for the maintainer's
confirmation instead, unless its request allows overwriting. See the
[public script protocol](https://repo-standards.com/docs/reference/script-protocol/) for the
versioned input/result protocol and execution rules. Source validation does not execute these operations.

### Remote setup

A fix that changes the hosting platform's settings, rather than project files,
can declare itself remote setup with an optional `remote-setup` mapping. It
holds exactly one field, `probe`: a readiness probe declared like a check,
with exactly `run`, `prerequisite`, and `timeout-seconds`, validated as above,
and no `id`; the probe belongs to its fix.

```yaml
fixes:
  - id: labels
    run:
      executable: gh
      script: fixes/labels.sh
      resources: [fixes/labels.json]
      arguments: []
    prerequisite:
      version-arguments: ["--version"]
      version: ">=2.40.0"
    timeout-seconds: 60
    remote-setup:
      probe:
        run:
          executable: gh
          script: probes/labels.sh
          resources: []
          arguments: []
        prerequisite:
          version-arguments: ["--version"]
          version: ">=2.40.0"
        timeout-seconds: 30
```

Only fixes take `remote-setup`; on a check it is an unknown field. Inspection
runs the probe read-only before anything is written, and the adopter can defer
a remote setup that is not ready and complete adoption without it; see
[remote setup](https://repo-standards.com/docs/reference/adoption-run/#remote-setup) and the probe's
[protocol](https://repo-standards.com/docs/reference/script-protocol/#remote-setup-probes). The probe's script and
resources are selected material, retained like an operation's. Remote setup
names no platform: the probe states what readiness means, such as a reachable
remote, a signed-in tool, or a sufficient role.

## Results and diagnostics

Exit status is `0` for a valid source, `1` for source validation errors, and `2`
for unsupported CLI usage. `--help` and `--version` are available. Human success
output lists profiles; human errors go to stderr as
`file:line:column [CODE] message (path)`.

With `--json`, stdout is one JSON object, and expected validation failures do
not write stderr. A successful report contains `valid: true`, `errors: []`,
normalized root `source` metadata, and `profiles`, keyed by profile name. Each
profile has its description, its `platforms`, its offered `check-locations`, and the complete source-resolved
declarations array, which holds the declarations of every platform.
Declarations include their `id`, any `platform` and `check-locations` filter, and explicit operation `checks` and
`fixes` arrays; a remote setup fix keeps its `remote-setup` probe.
The source retains its authored format identity. A successful report also includes
`scope.verified` describing the source-owned facts checked, `scope.limitations`
explaining project-specific limits, and `scope.discoveryRequired`, a mapping of
all profile names to their active discovery declaration IDs (empty lists for
profiles without discovery). Human output presents these same facts and limits.

Validation verifies every profile's schema, references (including guidance,
discovery guidance and rules files), operations, identities, reservations, and all determinable explicit-target
conflicts. It cannot establish concrete scope safety or semantic completeness in
an unfamiliar adopting project, even when all explicit source targets are valid.
Excluded discovery declarations do not require project discovery; their source
references are still validated like every other default reference.

A failed report contains `valid: false`, `errors`, and `profiles: {}`. Invalid
selections are never offered as resolved results. Each diagnostic contains a
stable `code`, explanatory `message`, absolute `file`, one-based `line` and
`column`, and an RFC 6901 JSON-pointer `path` into the YAML. Conflict errors
also identify `profile`, including conflicts inherited from defaults. Missing
fields point to their containing mapping; unreadable root documents use 1:1
and an empty path. Independent errors are collected across all profiles;
structurally invalid YAML may limit what can be determined.

| Code                         | Meaning                                                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SOURCE_READ`                | Source document or referenced material cannot be read                                                                                            |
| `YAML_SYNTAX`                | Invalid YAML, unsupported tag, or multiple documents                                                                                             |
| `YAML_STRUCTURE`             | Unresolved/recursive alias or YAML expansion/depth limit                                                                                         |
| `DUPLICATE_IDENTITY`         | Duplicate YAML key, operation ID, or platform of a profile                                                                                       |
| `UNKNOWN_FIELD`              | Field outside the author schema                                                                                                                  |
| `REQUIRED_FIELD`             | Required field omitted                                                                                                                           |
| `INVALID_TYPE`               | Wrong mapping, list, scalar, or string type                                                                                                      |
| `INVALID_FORMAT`             | Format identity other than `repo-standards/v2`                                                                                                   |
| `INVALID_VERSION`            | Malformed SemVer range                                                                                                                           |
| `INCOMPATIBLE_CLI`           | Running CLI does not satisfy the source range; the message recommends an open-ended minimum                                                      |
| `EMPTY_PROFILES`             | No complete named profile                                                                                                                        |
| `UNSUPPORTED_PLATFORM`       | A profile or declaration names a platform this CLI does not support                                                                              |
| `UNSUPPORTED_CHECK_LOCATION` | A `check-locations` array names an unsupported value                                                                                             |
| `EMPTY_CHECK_LOCATIONS`      | A profile or declaration has an empty `check-locations` array                                                                                    |
| `EMPTY_PLATFORMS`            | A profile's `platforms` list is empty                                                                                                            |
| `INVALID_ID`                 | Declaration, skill, or operation identity is malformed                                                                                           |
| `INVALID_DECLARATION`        | Unknown kind, file without exactly one content mode, repository guidance without exactly one scope mode, or a discovery script without discovery |
| `SKILL_INVOCATION_MISMATCH`  | Skill's Claude Code and Codex invocation settings disagree; message names the skill and both effective values                                    |
| `INVALID_EXCLUSION`          | Invalid exclusion value, level, or default identity                                                                                              |
| `INVALID_EXECUTABLE`         | Executable violates the documented name/path syntax                                                                                              |
| `INVALID_TIMEOUT`            | Timeout is not a positive safe integer                                                                                                           |
| `EMPTY_TARGETS`              | Repository guidance has no targets                                                                                                               |
| `UNSAFE_PATH`                | Path can escape its root or uses unsupported path syntax                                                                                         |
| `MISSING_REFERENCE`          | Referenced file or directory does not exist                                                                                                      |
| `REFERENCE_TYPE`             | Referenced entry has the wrong filesystem type                                                                                                   |
| `SOURCE_SYMLINK`             | Source document or selected material contains a symlink                                                                                          |
| `RESERVED_NAME`              | An author tries to supply a product-owned system skill, or names a declaration with rules `readme`                                               |
| `RESERVED_TARGET`            | Target overlaps reserved storage                                                                                                                 |
| `TARGET_OVERLAP`             | Two resolved targets that can apply on one platform and check location overlap, including folded collisions                                      |

## Alice's complete example

The executable [Alice fixture](https://github.com/lutzseverino/repo-standards/blob/main/examples/alice/standards.yaml) uses the
accepted architecture example verbatim. Its `work` profile replaces agent
guidance, inherits README guidance, the review skill, and source-layout
guidance, and excludes contribution guidance. Exclusion leaves the future
adopting project's employer-owned `CONTRIBUTING.md` outside governance.

The example's Python check reads the public operation input and checks README
headings. It reports structural evidence; the agent separately assesses whether
commands and explanations are useful for the actual project. See
[Author workflow](https://repo-standards.com/docs/guides/author-a-source/) for validation, publication and evolution.
