Add a scope model and selector mechanism for carried rules (#368, PR-1)

[ptr727]

What and why

First of four staged PRs for #368: give every governance rule a single explicit scope, so carried docs become granular single-scope pieces composed per repo rather than large pieces with internal carve-outs a reader must piece out. This PR is the inert foundation — it adds the mechanism and documents the model, with zero fleet-finding delta. Policy changes (turning on section-presence checking, the doc surgery, carrying Verification Discipline) follow in later PRs, each held before main.

Changes

• spec/scope-model.md (new, hub-only, not in the carried baseline): the two axes — home (host vs repo) and reach (hub-only / all-downstream / type-specific) — and the appliesToselector vocabulary: four disjoint namespaces (project types, workflowModel, releaseTrigger, consumerModel). States the load-bearing semantics: appliesTo is any-of (cross-axis AND is deliberately not expressible — that's the signal to split a piece), and entry-level AND section-level appliesTo compose. Records CODESTYLE.md's section→scope mapping (whole-carried, so documented not mechanized).
• spec/files.schema.json: a sections element may be a bare string or a {name, appliesTo} object (oneOf). Backward-compatible — every existing entry stays valid.
• spec/audit.py: match appliesTo against a repo's full selector set (repo_selectors), and replace the hardcoded operational develop.json path-swap with two data entries in files.json (appliesTo: ["release"] vs ["operational"]). This is the proof that the selector model subsumes an existing ad-hoc carve-out.
• spec/validate.py: first pass over files.json — every appliesTo token must resolve to a known selector, no project type may collide with a reserved token (keeps the namespaces disjoint), and every cataloged repo must declare consumerModel so a push/pull-scoped section can't fail open.
• AUDIT.md §3 + files.json note: one-line pointers to the scope model.

Inertness — verified

The four selector namespaces are disjoint and no current appliesTo token is non-*, so broadening the matcher changes no match. Proven by computing the required-file set for all 21 cataloged repos under old-code+old-data vs new-code+new-data: 0 differences. spec/validate.py stays green (and now also validates files.json). markdownlint, editorconfig-checker clean.

Held on develop — no develop → main promotion — per the standing instruction to observe what returns to develop first.

[Copilot]

Pull request overview

Introduces a scope model and selector mechanism (appliesTo) for carried governance files/sections, enabling per-repo composition without changing current fleet findings.

Changes:

• Add scope-selector vocabularies and files.json selector validation to spec/validate.py.
• Add selector-aware matching to spec/audit.py, including moving the operational develop.json swap from code into spec/files.json data.
• Add the appliesTo model documentation (spec/scope-model.md) and extend spec/files.schema.json to allow per-section selector objects.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
spec/validate.py	Adds selector vocab + validates consumerModel presence and files.jsonappliesTo tokens.
spec/scope-model.md	Documents the scope model, selector namespaces, and appliesTo semantics.
spec/files.schema.json	Extends schema to allow sections entries as strings or { name, appliesTo } objects.
spec/files.json	Adds selector-scoped baseline entries (notably release vs operational develop rulesets) and documents appliesTo.
spec/audit.py	Computes repo selector sets and applies appliesTo matching when auditing baseline file presence.
AUDIT.md	Points readers to the scope model when explaining applicability for carried files/sections.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

spec/files.schema.json:40

• The top-level entry "appliesTo" schema is also unconstrained for array element types. Restrict it to "string" or "array of strings" for consistency with the section-level form and to prevent non-string tokens from reaching runtime matchers.

 "intentRef": { "type": "string" },
"appliesTo": { "type": ["string", "array"] }
}

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

spec/audit.py:100

• repo_selectors() falls back to defaults.get('consumerModel'), but registry/repos.schema.json does not allow defaults.consumerModel (defaults has additionalProperties:false and only defines groundTruthBranch/releaseTrigger/workflowModel). Keeping a defaults fallback here is dead code and can mislead future editors about supported registry shape; prefer to read only the per-repo consumerModel (which validate.py already requires for cataloged repos).

 sel.add(entry.get("workflowModel") or defaults.get("workflowModel") or "release")
sel.add(entry.get("releaseTrigger") or defaults.get("releaseTrigger") or "two-phase")
cm = entry.get("consumerModel") or defaults.get("consumerModel")
if cm:
sel.add(cm)

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.