@reliance/repo-standards

The repository-hygiene checks every Reliance repo runs.

npm install --save-dev @reliance/repo-standards

// package.json
"scripts": {
  "check:codeowners": "reliance-check-codeowners",
  "check:skills": "reliance-check-skills",
  "check:agents": "reliance-check-agents",
  "check:template-sync": "reliance-check-template-sync",
  "check:sync-trailer": "reliance-check-sync-trailer"
}

Each prints what is wrong and how to fix it, then exits 0 or 1. Add them to whatever your repo runs in CI.

reliance-check-codeowners

Fails if a sensitive path declared in CLAUDE.md has no CODEOWNERS rule naming the reviewer the declaration promises.

Reads the table between the sensitive-paths markers:

<!-- sensitive-paths:start -->

| Domain   | Path           | Reviewer                    |
| -------- | -------------- | --------------------------- |
| Payments | `src/payments` | @reliancehealthinc/security |

<!-- sensitive-paths:end -->

Declaring None is a valid answer. Deleting the markers is not — a missing section is indistinguishable from "no sensitive paths".

What it checks:

• Placeholder owners are rejected. @org/PLACEHOLDER-squad matches nobody, so the rule requests no review and the PR merges. A template may carry them — see Template identity.
• Named teams can actually review here, via gh when a credential that can list this repo's teams is available. A rule applies only if the team is attached to this repo with write access, so pull and triage fail, as does a team attached to no repo at all and a team from another organisation. Skips with a note otherwise, which is the normal case in CI — a workflow's GITHUB_TOKEN is repo-scoped — and then the success line says team access was not verified rather than implying it was.
• Every declared path is covered by a rule that is not the catch-all. * @some-squad does not count — as a prefix match it would cover every path ever declared, so accepting it would make the check pass on any repo with a default owner.

What the skip costs. Team access is the one part that needs a credential, so on a CI run it goes unchecked. To answer it by hand:

gh api repos/<org>/<repo>/teams --jq '.[] | "\(.slug) \(.permission)"'

push, maintain or admin is what CODEOWNERS needs. pull and triage match nobody.

reliance-check-skills

Validates frontmatter of .claude/skills/*/SKILL.md. Broken frontmatter has no runtime signal: an unknown field is ignored, a malformed entry is dropped, and the skill still loads — declaring a control it does not have.

Checks that fields are known, name matches its directory, description is present and on one line, model is an alias (opus, sonnet, haiku, fable, inherit) rather than a pinned id, and allowed-tools / disallowed-tools entries are well-formed.

--root <dir> overrides the directory scanned.

The check is limited to things that are mechanically true or false. Whether a description is good is left to review.

reliance-check-agents

Validates frontmatter of .claude/agents/*.md. Same class of failure: a malformed entry in tools is dropped with no error, so the agent loads with fewer tools than it declares and reads as though it chose not to use one.

Checks that fields are known, name is present and lowercase-and-hyphens, description is present, model is an alias, and tools / disallowedTools entries are well-formed.

--root <dir> overrides the directory scanned. Passes quietly when there is no .claude/agents/ — agents usually live in the engineering-core plugin, which validates its own.

Tool lists: skills and agents take different grammars

This is the distinction both checks exist to enforce, and it goes in opposite directions:

| | SKILL.md allowed-tools / disallowed-tools | agents/*.md tools / disallowedTools | | --- | --- | --- | | Read | ✅ | ✅ | | mcp__server__tool, mcp__* | ✅ | ✅ | | Bash(npm test:*) | ✅ the way to grant least privilege | ❌ silently dropped | | Agent(worker, researcher) | — | ✅ the one scoped form that is valid |

Scope an agent's shell access in settings.json, or in the SKILL.md the agent runs.

All three separator forms are accepted on both sides, because all three are valid:

allowed-tools: Read Grep                  # space-separated
allowed-tools: Read, Grep                 # comma-separated
allowed-tools:                            # YAML list
  - Read
  - Bash(npm test:*)

Splitting is parenthesis-aware, so Bash(git add, git commit) stays one entry.

reliance-check-template-sync

Fails when nobody has reviewed the template for too long, and when the review record is malformed.

// .reliance-sync.json
{
  "reviewedTo": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "at": "2026-04-20",
  "decisions": [
    {
      "change": "strict-csp",
      "since": "9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c",
      "label": "standard",
      "disposition": "declined",
      "scope": "embedded",
      "reason": "the host monolith sets its own CSP header",
      "revisit": "when the app stops being embedded"
    }
  ]
}

reviewedTo is the template commit you have reviewed up to, so the next diff starts from your last decision rather than from your service.

Every reference is a git sha, matching reliance.template.commit. revisit is prose: it is never parsed and nothing acts on it.

Each decision carries four things

| Field | | | --- | --- | | label | what the template called it — compliance, standard, capability, repair | | disposition | declined (a choice) or not-applicable (a structural fact) | | scope | optional — which build target or variant this covers. Absent means the whole repo | | reason | required. A decision without one is indistinguishable from an oversight |

Both are recorded, not re-derived. The label travels as a Sync: trailer on a template commit, so recovering it later would mean resolving that commit — which needs the template repo, which is exactly what this check cannot reach.

The pairing is what gets enforced:

| | declined | not-applicable | | --- | --- | --- | | compliance | fails — adopt or escalate | noted for a reviewer | | standard | recorded | recorded | | repair | recorded | recorded | | capability | noted as redundant | noted as redundant |

A compliance change genuinely may not apply — a data-redaction change cannot reach a service built with --no-db. That is why the disposition exists, and why it is surfaced rather than accepted quietly.

The record is normally written by /engineering-core:sync-template, not by hand.

What it measures, and what it can't

| | Source | Result | | --- | --- | --- | | .reliance-sync.json present | at | age measured from your last review | | absent, but provenance present | reliance.template.initialisedAt | age measured from generation — never reviewed | | neither | — | inert, and says so |

Thresholds are fixed in the package — 180 days fails, 90 days notes. They are not configurable from the repo: a threshold you can raise from your own config is a check you can switch off.

It does not tell you how far behind you are. That needs to read the template repo, and in CI a workflow's GITHUB_TOKEN is scoped to the current repository — so the answer would be unavailable exactly where the check runs. /engineering-core:sync-template does that half, where a human and a real credential are both present. This half answers only "has anyone looked lately", which needs no network and is true where it is stated.

Adopting it

Add the script and commit a record. If your repo has provenance, the check is already live with no record at all — it measures from generation. If it has neither, it passes and says it is inert until one exists.

reliance-check-sync-trailer

Templates only. A Sync: <label> on a template commit must be one that git — and therefore the sync-template skill — can actually read.

Git treats only the last paragraph of a commit message as trailers, so this puts the label in the prose:

Sync: capability
                        <- this blank line ends the trailer block
Co-Authored-By: Claude Opus 5 <[email protected]>

%(trailers:key=Sync,valueonly) returns nothing. The skill sees an unlabelled commit; a reviewer sees a perfectly good label.

What it checks:

• A label git cannot read. The case above.
• A label git reads but the vocabulary does not contain — Sync: complience parses cleanly and means nothing downstream. The four real labels are printed with a one-line description each, read from sync.conformance.json, so nobody has to open the contract.
• Two labels on one commit. A change propagates one way, or it is two commits.

It never requires a label. A commit that says nothing passes. An unlabelled change is already handled: labels.unlabelled.default sends it to needs-triage and the skill always surfaces that group. Requiring one trains people to paste a label to clear CI, and a confident wrong label is worse than needs-triage — needs-triage gets read.

It is as tolerant as git about spelling and no more. Git matches trailer keys case-insensitively and allows space around the colon, so sync: repair, SYNC: repair and Sync : repair are all the same trailer and all pass — including in the misplaced-label check, so the convention is not enforced only against the people already following it. Label values are normalised the same way: Repair is repair. complience is where it stops.

git commit --trailer "Sync: repair" places it correctly for you, as does a second -m. That is worth more than this check: it makes the right form the easy one.

Adopting it

Add the script to whatever your repo runs on a pull request. Two things to get right:

• It needs history. The range is origin/main..HEAD, falling back to main. On a shallow clone neither resolves, so set fetch-depth: 0 on actions/checkout — otherwise the check skips, and says loudly that it did rather than passing over an empty range.
• It is silent in a service repo, gated on template identity. The convention governs template commits, so a generated app running the same verify sees nothing. No configuration needed.

Pass a base ref as the first argument to compare against something else.

Template identity

Two checks need to know "am I the template, or an app generated from it?", because a template legitimately carries what they exist to reject: its own package name, and PLACEHOLDER-* owners.

isTemplate = (git origin is the template repo) AND (package name is the template package)

Anything else — no remote, a fork, a renamed package, an unreadable package.json — is not the template, so the checks enforce. There is no environment-variable override: a control a repo can switch off from its own CI config is not a control.

.reliance-standards.json

Declare the two constants in a file at your repo root:

{
  "templateRepo": "reliancehealthinc/reliance-frontend-template",
  "templatePkg": "reliance-frontend-template"
}

They describe the template, permanently, in every app generated from it. They are not "this app's name", and nothing should ever rewrite them — if a rename reaches them, every app generated afterwards declares itself the template, tolerates placeholder owners forever, and no check fires.

For that reason they live here rather than in package.json (which init:app rewrites) or under scripts/ (what find-and-replace sweeps target). Assert both values in your own test suite — that assertion is correct in the template and in every app generated from it, and it is the tripwire for a rename reaching in.

A repo with no config is treated as not the template, so the exemption cannot be earned by deleting a file. The missing config is only reported when it changes an outcome, so a repo with no placeholder owners can adopt this package without adding one.

API

For the rare case a binary will not do:

import { templateIdentity, createReport, loadConfig } from '@reliance/repo-standards';

const { isTemplate, reason } = templateIdentity({
  templateRepo: 'reliancehealthinc/reliance-frontend-template',
  templatePkg: 'reliance-frontend-template',
});

templateIdentity throws without both constants rather than defaulting them — any default would be one real template's name that another repo would silently match.

templateProvenance(cwd)

For a generator recording what it created a repo from. Reads templateRepo from .reliance-standards.json, so it takes no constants of its own:

import { templateProvenance } from '@reliance/repo-standards';

// in init:app / init:service, writing into the generated package.json
pkg.reliance = { template: templateProvenance(targetDir) };

"reliance": {
  "template": {
    "repo": "reliancehealthinc/reliance-frontend-template",
    "commit": "d22dbd87c52ed4cb08c596482a733412ddf4f558", // or null
    "initialisedAt": "2026-08-16",
  },
}

The shape is the contract — one question answerable of any repo in the estate without knowing which template it came from. commit is null when there is no shared history to point at: GitHub's "Use this template" squashes into a fresh repository, so its HEAD resolves to nothing in the template, and an honest null beats a sha that answers no question. initialisedAt always survives.

Throws if .reliance-standards.json is unusable, rather than recording a repo that names nothing. Pass { now } to fix the date in tests.

Note it uses a different rule from templateIdentity: origin only, not origin AND package name. templateIdentity gates an exemption so it must fail closed; this asks whether HEAD is resolvable in the template, which the package name says nothing about — and init:app is what renames the package, so requiring a name match would make the answer depend on call ordering.

Migrating off the copied scripts

If your repo carries its own copies:

1. Install this package; point check:codeowners / check:skills / check:agents at the binaries.
2. Add .reliance-standards.json with the values from scripts/lib/template-repo.mjs.
3. Delete scripts/check-codeowners.mjs, scripts/check-skills.mjs, scripts/check-agents.mjs, scripts/lib/report.mjs, scripts/lib/tool-list.mjs, scripts/lib/template-identity.mjs, scripts/lib/template-provenance.mjs and their tests.
4. Delete scripts/lib/template-identity.conformance.json and its runner. It existed to prove two copies agreed; there is one implementation now.
5. Keep scripts/lib/template-repo.test.mjs, retargeted at .reliance-standards.json. That one stays per-repo.
6. Import templateProvenance in init:app / init:service instead of computing the reliance.template block locally.

Expect the reconciled check:skills to disagree with an old copy in a few places. If it fires on something you believe is correct, that is worth an issue — a false positive here runs in everyone's CI.