Carry the Host Contract and Declare the jq Floor

[ptr727]

Your call, per the decision to accept the fleet-wide finding. Floor set to 1.7 per your follow-up.

The jq gap

jq is used by the ruleset normalizer in repo-config/configure.sh, the ruleset diff in AUDIT.md section 6, and payload regeneration in docs/repo-config-carry.md. It was declared in neither the contract table nor spec/host-tools.json. A host without it cannot apply, check, or audit a repo's branch configuration, and nothing said so.

The floor is 1.7, and it is a target

I did not pick a number and justify it after. Measuring first said no floor was warranted at all: nothing in the tree uses a post-1.5 jq feature (checked walk, @base64d, --args, $__loc__, pick, toarray, abs, getpath, ltrimstr, splits, limit, $ENV — the only hits were shell variables and Actions expressions, not jq filters). So the floor is a target, the same kind as python3, and the entry says so rather than implying a defect nobody found.

1.7 is anchored to what the platform provides: current Debian stable packages 1.7.1, so a distribution install satisfies the floor and no host needs a manual build to meet it, while an older release sits below and is the case the floor exists for. That anchor is what makes it actionable. Two rejected alternatives, for the record:

• 1.8 (the newest, installed here) would fail a current apt host that runs every documented filter correctly. A floor set to whatever happens to be installed is a host failure nobody can act on, which is the hazard this file's own note names.
• 1.6 would encode the walk/1 boundary, which is a fact about the filters rather than something a host operator can act on.

Facts kept in the entry because a reader needs them: on jq 1.5 walk/1 does not degrade, it fails to compile, so a diff built on it reports drift on every ruleset it never compared. And the claim that keys_unsorted also needs 1.6 stays disproved per the .github/copilot-instructions.md record, measured on jq-1.5-1-a5b5cbe.

Consequences swept, not left

The floor now sits above 1.6, so walk/1 is available — which made false the comments in AUDIT.md and repo-config/configure.sh that justified hand-defining a recursion by walk's absence. Both now give the reason that survives: the recursion costs nothing and compiles below the floor as well. This is the same class of defect as #649 (a rule changed, its prose left asserting the old one), so it was swept by term rather than by instance.

host-tools.json becomes a carried file

A repo now states the tools its own procedures need beyond the fleet declaration, so the tighten-only layering lives somewhere a reader finds rather than has to know to look for. A repo with nothing to add carries the stub with an empty tools list — the footing OPERATIONS.md already set — and this repo's new root file is that worked example, with a note distinguishing it from spec/host-tools.json.

Measured before landing: none of the 22 cataloged repos carries one, so this adds exactly one LETTER per repo. This PR satisfies the hub's own.

The gate joins the procedures it was written for

scripts/host_gate.py existed and no procedure ran it. STANDUP.md section 0 and AUDIT.md now do, alongside RESYNC.md in #651. Each passes --repo, because the gate reads the target's declaration relative to that flag and a bare run layers the hub's instead while printing the same healthy digest either way.

Verification

scripts/test_host_gate.pyfailed first, which is the tests working: test_the_declared_floors_are_the_ones_with_a_stated_reason asserts the floor set exactly, so a new floor cannot land unnoticed. I updated it and generalized test_a_target_floor_says_so_rather_than_implying_a_defect from the single python3 entry to the set of target floors, so a third one added without the two-kinds wording fails rather than reading as measured.

The boundary is checked through the gate's own compare/parse_version rather than a reimplementation of them:

jq 1.5 -> FAILS jq 1.7 -> meets
jq 1.6 -> FAILS jq 1.7.1 -> meets
jq 1.6.1 -> FAILS jq 1.8.2 -> meets

• 552 script tests OK, --selftest PASS, validate.py OK
• host_gate.py: 7 tools, jq 1.8.2 meets the 1.7 floor, and it reads the hub's own stub (host-tools.json layered 0 local entry(s))
• prose_lint, repo_gate --check eol, markdownlint-cli2, cspell on the gated files: all clean
• editorconfig-checker caught a real defect every other gate passed: a sed -i I used wrote one bare LF into AUDIT.md. Fixed and re-verified byte-wise; the diff stayed at 9 lines rather than a whole-file rewrite.

One bookkeeping item left for you

The keys_unsorted entry in .github/copilot-instructions.md carries Delete when - "nothing this check runs on carries a jq older than 1.6", and an enforced 1.7 floor arguably satisfies that. I left it in place rather than deleting it unilaterally, because it exists to answer a repeat reviewer finding and its measured proof is cited from the new jq entry. Your call whether it retires.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This pull request updates the fleet host-tool contract to include jq (with a declared target floor), adds a carried per-repo host-tools.json stub, and wires the host verification gate into the documented onboarding/audit procedures so host misconfiguration is detected before running hub tooling.

Changes:

• Declare jq as a required host tool in spec/host-tools.json with a minimum (target) version of 1.6, and reflect it in docs/host-setup.md.
• Add host-tools.json to the baseline file set and introduce a root host-tools.json stub for repo-specific layering.
• Document invoking scripts/host_gate.py --repo ... in STANDUP.md and AUDIT.md, and update tests to lock the expected floors/wording.

Reviewed changes

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

Show a summary per file

File	Description
STANDUP.md	Documents running host_gate.py during standup and clarifies why --repo is required; updates baseline narrative for host-tools.json.
AUDIT.md	Adds a “verify host first” step calling host_gate.py --repo ... before audit runs.
spec/host-tools.json	Adds jq as a required tool with a target minimum version and detailed rationale/source guidance.
docs/host-setup.md	Updates the host contract table to include jq and adds the missing AUDIT.md link ref used by the new row.
spec/files.json	Adds host-tools.json as a baseline file expected in all repos.
host-tools.json	Introduces the repo-local layering stub (empty tools list) with schema pointer and explanatory note.
scripts/test_host_gate.py	Updates tests to include the new jq floor and generalizes target-floor wording assertions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (3)

STANDUP.md:28

• This placeholder reads like it should point at the hub checkout (“this checkout”), but the surrounding text says --repo must point at the repository being stood up so its own root host-tools.json is layered. Using a target-repo placeholder here also matches AUDIT.md’s example.

python3 scripts/host_gate.py --repo <path-to-this-checkout> # run from a hub checkout, floors from spec/host-tools.json

host-tools.json:5

• host-tools.json declares $schema: "./spec/host-tools.schema.json", but that schema requires tools to have at least 1 item (minItems: 1), while this stub intentionally sets "tools": []. This makes the file schema-invalid in editors/validators and contradicts the stated intent of carrying an empty stub.

{
"$schema": "./spec/host-tools.schema.json",
"note": "This repository's own host-tool declaration, layered over the fleet declaration in spec/host-tools.json by scripts/host_gate.py. The two are not the same file and do not hold the same thing. The fleet declaration states what every repository's procedures need and is the hub's to change. This one states what this repository needs beyond that, so it is where a tool only this repository uses, or a floor only this repository requires, is declared. Layering is tighten-only: an entry here may add a tool, raise a floor, or turn an optional tool required, and may not lower a floor or turn a required tool optional, because that would retire a fleet check from inside the repository it protects. A rejected relaxation is reported rather than dropped. The tools list is empty because this repository needs no tool the fleet declaration does not already carry, and the file is still present rather than absent, on the same footing as OPERATIONS.md: a repository with nothing to add carries the stub, so the declaration is somewhere a reader can find rather than somewhere they have to know to look.",
"tools": []
}

spec/host-tools.json:53

• PR description states “The floor is 1.6”, but this change declares jq’s minimum as 1.7 (and docs/host-setup.md also says 1.7). Please reconcile the PR description with the implemented/documented floor to avoid confusion for readers relying on the PR text.

 "probes": [["jq", "--version"]],
"pattern": "jq-(\\d+(?:\\.\\d+)*)",
"minimum": "1.7",
"why": "Needed by the ruleset normalizer in repo-config/configure.sh, the ruleset diff in AUDIT.md section 6, and the payload regeneration in docs/repo-config-carry.md, so a host without it cannot apply, check, or audit a repository's branch configuration. The floor is a target rather than a measured breakage one version below it, and it says so rather than implying a defect nobody found. It is anchored to what the fleet's own platform provides: current Debian stable packages 1.7.1, so a distribution install satisfies the floor and no host needs a manual build to meet it, while an older release sits below and is the case the floor is for. That anchor is what keeps it actionable, since a floor set to the newest release instead would fail a host running every documented filter correctly. Two lower versions matter to a reader and neither is the floor. 1.6 is where walk/1 arrived, so the floor sits above it and walk is available, and the filters nonetheless define their own recursion, which costs nothing and keeps them compiling below the floor. On jq 1.5 walk/1 does not degrade, it fails to compile the filter, so a diff built on it reports drift on every ruleset it never compared, which is the inverse of the false clean the comparison exists to close. The neighbouring claim that keys_unsorted needs 1.6 is disproved rather than assumed, measured on jq-1.5-1-a5b5cbe where keys_unsorted evaluates and walk(.) answers a compile error, so the two builtins are not in the same position and the analogy between them is the whole of what carried that claim. A host below the floor is therefore unverified rather than known broken, since every filter here is written to a feature set older than the floor requires. A separate implementation is worth knowing about and is not this entry's subject: gh --jq is gojq built into the CLI rather than this binary, and it emits object keys sorted, which is why the section 6 filter canonicalizes key order itself rather than depending on whichever implementation produced its input.",

[Copilot]

Pull request overview

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

Suppressed comments (1)

host-tools.json:4

• host-tools.json declares $schema: "./spec/host-tools.schema.json", but that schema currently requires tools to have minItems: 1 (i.e., cannot be an empty list). As added here, the stub has "tools": [], so it is not schema-valid and will show as invalid in schema-aware editors/validators.

Consider either (a) updating spec/host-tools.schema.json to allow an empty tools list for repo-local layering stubs, or (b) pointing this file at a dedicated schema for the local overlay format.

 "$schema": "./spec/host-tools.schema.json",
"note": "This repository's own host-tool declaration, layered over the fleet declaration in spec/host-tools.json by scripts/host_gate.py. The two are not the same file and do not hold the same thing. The fleet declaration states what every repository's procedures need and is the hub's to change. This one states what this repository needs beyond that, so it is where a tool only this repository uses, or a floor only this repository requires, is declared. Layering is tighten-only: an entry here may add a tool, raise a floor, or turn an optional tool required, and may not lower a floor or turn a required tool optional, because that would retire a fleet check from inside the repository it protects. A rejected relaxation is reported rather than dropped. The tools list is empty because this repository needs no tool the fleet declaration does not already carry, and the file is still present rather than absent, on the same footing as OPERATIONS.md: a repository with nothing to add carries the stub, so the declaration is somewhere a reader can find rather than somewhere they have to know to look.",
"tools": []

[ptr727]

Two suppressed findings answered, both correct.

The stub shipped schema-invalid. Fixed in 1dcff2c, and the defect was wider than the empty list. spec/host-tools.schema.json carries minItems: 1 on toolsand requires name, probes, pattern, minimum, why on every entry. So pointing an overlay at it forbids both shapes an overlay exists for: the empty list a repo with nothing to add carries, and the partial entry that lets a repo raise one floor without restating a tool. That second half matters more, since host_gate.py's field_problems is explicitly built for partial overrides ("Only fields that are present are judged, which is what lets an override carry one field without restating an entry"), so a real overlay adding just a floor would have been invalid too.

Took your option (b). spec/host-tools-local.schema.json now states the overlay format, requiring only name, allowing an empty list, and recording in its description that the gate rather than the schema is the authority on tighten-only layering, since a schema compares nothing against the fleet declaration.

Worth noting why nothing caught it: CI validates no JSON schema and jsonschema is not installed, so the $schema pointer's only reader is a schema-aware editor. The file read as invalid exactly where it is edited and nowhere else. Four tests now hold the split open, and the last one asserts the overlay would still fail the fleet schema, so if that stops being true the split has lost its justification and the test says so rather than leaving two schemas nobody can tell apart.

The PR description said 1.6 while the code said 1.7. Correct, and it was stale rather than wrong at the time: the floor moved from 1.6 to 1.7 mid-review on the maintainer's call, and I updated the body afterwards. It now states 1.7 and records both rejected candidates and why. Fair catch that a reader relying on the PR text would have been misled.

[Copilot]

Pull request overview

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

Suppressed comments (1)

spec/files.json:21

• host-tools.json points at ./spec/host-tools-local.schema.json, but the carry baseline in spec/files.json currently adds only host-tools.json (and not the schema file). That means newly stood-up downstream repos will carry a $schema reference to a path that doesn’t exist, so editors will flag the file as invalid and schema-aware tooling can’t validate it.

 { "path": ".gitignore", "appliesTo": "*" },
{ "path": "host-tools.json", "appliesTo": "*" },
{ "path": "version.json", "fidelity": "intent", "intentRef": "WORKFLOW.md#d3---versioning-and-classification", "appliesTo": "*" },

[ptr727]

Correct, and it is the same dangling-pointer defect this branch just fixed for the hub, reintroduced one step downstream. Fixed in 3aea9ac.

You are right that no schema file is carried: spec/files.json declares no *.schema.json entry at all, so a repository copying the stub would hold ./spec/host-tools-local.schema.json pointing at a path it does not have.

The fleet already answers this, so the fix is stating settled practice rather than inventing a rule. The hub's spec/secrets.json carries ./secrets.schema.json, and every downstream copy of that file omits the key - checked against Blog, PlexCleaner and Utilities, all three report no $schema. So a carried config drops the pointer because the schema is hub-only.

Two places now say so, because either alone leaves the trap open:

• STANDUP.md section 2 states that the carried copy drops the pointer, why, and that spec/secrets.json is the precedent.
• The stub's own note says it too, since the stub is what a repository copies and a worked example that omits its own caveat is exactly what a reader would follow into the defect.

I considered and rejected the two alternatives. Carrying the schema file downstream would make every repository hold a hub schema, which the carried-against-reached rule puts on the wrong side. An absolute hub URL in $schema would put a template-repo reference into a carried file, which GOVERNANCE.md "Documentation Style Conventions" bans outright.

[Copilot]

Pull request overview

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

Suppressed comments (1)

scripts/test_host_gate.py:442

• test_the_overlay_would_be_invalid_under_the_fleet_schema hard-codes a property of the current shipped overlay (empty list) and will start failing as soon as this repo’s overlay legitimately adds a tool override that happens to satisfy the fleet schema (e.g., a full entry). The justification for a separate overlay schema is that the schema is more permissive (empty list + partial entries), not that the current overlay must always be invalid under the fleet schema.

Consider replacing this with an assertion about the schemas’ relative permissiveness, and let the other tests cover the shipped overlay shape.

 def test_the_overlay_would_be_invalid_under_the_fleet_schema(self):
"""The reason the separate schema exists, asserted so it cannot quietly stop being true.
If the overlay ever satisfies the fleet schema, the split has no justification left and this
test says so rather than leaving two schemas nobody can tell apart.

[ptr727]

Right on both counts, and the fault was mine rather than a difference of taste. Fixed in 39b1527.

The test coupled a schema-design invariant to one data instance. An overlay that legitimately grew a full tool entry would satisfy the fleet schema and fail that test while the split stayed exactly as justified, so it would have failed for being right. And as you say, the justification is that the schema is more permissive, not that the current overlay must stay invalid under the other one.

Replaced with the invariant asserted in both directions over constructed documents:

self.assertTrue(self.accepts(self.fleet_schema, full_entry)) # everything the fleet acceptsself.assertTrue(self.accepts(self.local_schema, full_entry)) # the overlay accepts toofordocin (empty_list, partial_entry): # and two shapes it rejectsself.assertFalse(self.accepts(self.fleet_schema, doc))
self.assertTrue(self.accepts(self.local_schema, doc))

The helper reads only tools.minItems and the per-entry required list, which is the whole of what separates the two schemas, and its docstring says it is not a validator rather than implying it is. jsonschema is not installed and CI validates no schema, so a dependency-free check of the two axes under discussion is what can actually run.

Verified three ways rather than just running it green:

• Against the scenario you named. With the overlay holding a full entry, the new test passes where the old one fails.
• Against a mutant tightening the overlay's minItems back to 1: caught, the overlay schema rejects an empty tools list.
• Against a mutant demanding every field of an overlay entry: caught, the overlay schema rejects a partial entry.

test_the_shipped_overlay_satisfies_its_own_schema still covers the shipped file's shape, which is the division of labour you suggested.

[Copilot]

Pull request overview

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

Suppressed comments (1)

spec/host-tools-local.schema.json:34

• The overlay schema is documented (and tested in scripts/test_host_gate.py) as differing from the fleet schema only in tools.minItems and the per-entry required list, but this schema currently also relaxes other constraints (e.g., minimum has no version pattern and source is any object). That makes schema-aware editors accept values the gate will reject (or that won’t produce useful install guidance), and it undermines the “only two axes differ” invariant the tests describe.

Tighten the shared fields to match the fleet schema (while keeping the overlay-only relaxations).

 "pattern": { "type": "string", "minLength": 1 },
"minimum": { "type": ["string", "null"] },
"why": { "type": "string", "minLength": 1 },
"source": { "type": "object" }

[Copilot]

Pull request overview

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

[ptr727]

Correct on both fields, and acting on it turned up a third. Fixed in 0e50dec.

The two you named.minimum had lost pattern: "^\\d+(\\.\\d+)*$", so a schema-aware editor accepted a floor parse_version rejects, and source had lost its named platforms and its additionalProperties: false, so a key reaching no platform read as valid. Both now match the fleet constraint exactly. You are also right about the wider problem: the tests beside it said only two axes differed, which made that claim wrong rather than merely incomplete.

The structural fix. A test now compares the two schemas field by field rather than trusting prose, because the alternative to duplication is a cross-file $ref that editors resolve inconsistently. That is what keeps hand-copied constraints honest.

The third divergence it found immediately, which is why the test was worth writing rather than just editing the two fields: the fleet declares required with default: true and the overlay declared none. That one is correct and stays, and it is a semantic difference rather than drift. merge() iterates entry.items(), so an overlay applies only the fields it carries, which means an omitted required inherits the hub's value rather than defaulting to true. Declaring a default here would tell a reader the opposite of what the merge does. It is excluded by name with that reason, plus a positive assertion that the key stays absent, so a fourth relaxation fails the test rather than quietly widening the claim.

The schema's own description now says three ways rather than two, and says a test rather than the sentence is what holds it.

Each exclusion is checked against a mutant rather than assumed to bite:

minimum loses its version pattern: caught
source reopens its property set: caught
required declares default true: caught

One process note, since it is the second time this round: this finding arrived suppressed, with no thread, and I only found it by diffing the finding list against my own replies. pr_review.py status reports suppressed=N (on_head=X earlier=Y), and the earlier bucket is easy to walk past once the head is clean.

[Copilot]

Pull request overview

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