Put the Floors in the Contract Table, and Tie the Table to the Data

[ptr727]

Answers one of the two suppressed findings on the promotion pull request #643, which cannot take a fix of its own since its head is develop.

This section says python3 carries a 3.13 target floor and scripts/host_gate.py will enforce it as a hard minimum. The contract table above still says "Python 3", which can mislead a host on 3.12 into thinking it meets the requirement until the gate fails.

Accepted, and widened to the class. The table answers presence, and a tool below its floor answers --version exactly like one above it, so every column reported a host as fine while host_gate.py failed it. That was already true of gh before this session: a host on 2.46 reads the gh --version row, concludes it qualifies, and then fails the floor that has been declared since it was added. Patching only the row the finding named would have left the same trap one row up, so the fix is a Floor column covering both.

The kind is named beside the number, since the distinction decides what a failing host can do next. A measured floor gives them a defect to point at, and a target floor does not.

git-restore-mtime carries a floor and is deliberately absent from the table, because it is optional and no procedure here needs it, which the prose below the table already explains.

The number is now restated in two places, so a test holds them together

Copying a value out of spec/host-tools.json into prose creates exactly the drift this column exists to prevent: the data moves, the table does not, and a host reads the stale number and stops. A test now reads the shipped docs/host-setup.md and asserts every required tool's declared floor appears in a table row.

It was written before the table was correct, to confirm it fails rather than assuming it would, and the first failure it produced was a real finding rather than a bug in the test: git-restore-mtime declares a floor and has no row in the contract table. That is what scoped the assertion to required tools, and the reason is recorded in the test rather than left to the next reader.

Confirmed it catches the case it exists for, by rewriting the table to 3.12 and running it:

AssertionError: False is not true : python3 declares 3.13 and no table row states it

Verification

552 tests pass, spec/validate.py and scripts/host_gate.py exit 0, prose_lint.py with the CI check list exits 0, repo_gate.py reports all three checks clean, editorconfig-checker exits 0, and markdownlint-cli2 reports 0 issues across 44 files. The hook caught a wrapped comment sentence in the new test before it landed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the host setup contract documentation to make minimum-version floors explicit in the contract table, and adds a test that ties those documented floors back to the authoritative spec/host-tools.json data to prevent drift.

Changes:

• Add a Floor column to docs/host-setup.md (including whether each floor is “measured” vs “target”) to distinguish tool presence from version sufficiency.
• Add a unit test in scripts/test_host_gate.py that asserts every required tool with a declared floor has a corresponding contract-table row that states that floor.

Reviewed changes

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

File	Description
scripts/test_host_gate.py	Adds a regression test ensuring the host contract table restates required tool floors from spec/host-tools.json.
docs/host-setup.md	Expands the host contract table with a Floor column and explains why the column exists and how to interpret floor kinds.

---

💡 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 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (2)

scripts/test_host_gate.py:439

• This failure message is misleading: assertIn('python3', rows, ...) can fail because the table exists but the python3 row is missing. In that case the error is not 'no contract table found'. Adjust the message to reflect the actual condition being checked.

 self.assertIn('python3', rows, 'no contract table found in docs/host-setup.md')

scripts/test_host_gate.py:449

• The assertion for the minimum version can still pass for the wrong reason because it searches all cells in the row. If the minimum appears in Present when (e.g., python3.13 --version) or another column, the test would pass even if the Floor column drifted or was removed, reintroducing the brittleness this test is meant to prevent. Assert the version specifically in the Floor cell (last column).

 self.assertTrue(
any(t['minimum'] in c for c in rows[key]),
f'{t["name"]} declares {t["minimum"]} and no table row states it')

[ptr727]

Answering both suppressed findings from the round on c5765ca1, which carry no thread to resolve. Fixed in f04ef1f.

The version assertion searched the whole row

The assertion for the minimum version can still pass for the wrong reason because it searches all cells in the row. If the minimum appears in Present when (e.g., python3.13 --version) [...] the test would pass even if the Floor column drifted or was removed.

Accepted, and it is the previous finding over again one column across. The row lookup was fixed to key on the Tool cell, and the version assertion was left searching every cell, so the same accidental match was still available one line down.

Worth stating plainly: my own three-case check did not catch this, and passing it is what made me confident. It only passed because Present when does not happen to contain 3.13 today, which is precisely the "passes for a reason it does not intend" shape this test was written to prevent. A check built from the cases I could think of confirmed what I already believed.

The Floor column is now located by its header and the assertion reads that one cell. By header rather than as the last column, so appending a column later does not silently move what is asserted.

Re-checked against five rewrites, including the one you name:

Table rewrite	Result
floor number drifts to 3.12	FAILS, correct
floor cell emptied to none	FAILS, correct
Present when reworded to prose	passes, correct
version moved into Present when, Floor blanked	FAILS, correct
Floor column removed entirely	FAILS, correct

The failure message named the wrong condition

assertIn('python3', rows, ...) can fail because the table exists but the python3 row is missing. In that case the error is not 'no contract table found'.

Accepted. That assertion was doing two jobs, proving a table was parsed and proving one row existed, and reported only the first. A reader who deleted the python3 row would have been told the table was missing and gone looking in the wrong place.

They are now separate: assertIsNotNone(floor_col, ...) proves a contract table with a Floor column was found, and the per-tool assertIn(key, rows, ...) reports a missing row as a missing row. The version failure now prints the Floor cell it actually read, so the message carries the observed value rather than only the expected one.

[Copilot]

Pull request overview

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

Suppressed comments (1)

scripts/test_host_gate.py:445

• The contract-table parser keeps scanning every Markdown table in docs/host-setup.md after it finds the contract table header. Today that happens to be harmless, but it makes the test fragile (a later table could accidentally overwrite a tool key, or a future contract-table move could change which table is parsed). Consider stopping after the first contract table ends (first non-table line after the header) and only recording rows while inside that table.

 rows, floor_col = {}, None
for ln in doc.splitlines():
if not ln.startswith('| '):
continue
cells = [c.strip() for c in ln.strip('|').split('|')]

[ptr727]

Answering the suppressed finding from the round on f04ef1fd. Fixed in 9f839e4.

The contract-table parser keeps scanning every Markdown table in docs/host-setup.md after it finds the contract table header. Today that happens to be harmless, but it makes the test fragile (a later table could accidentally overwrite a tool key [...]).

Accepted. Measured the "today that happens to be harmless" part rather than taking it on trust, because it decides whether this is a latent break or a live one:

Table	Header
lines 17-23	`Tool
lines 226-232	`Now possible

The second table's first-column keys normalize to nowpossible, standupanewrepothroughstandu and similar. None collides with a tool name, so it is latent rather than live, exactly as you say.

Reading now stops at the first non-table line after the contract table.

Confirmed the fix is load-bearing rather than defensive, by appending a later table carrying a Python 3 row and running both versions against it:

previous test (f04ef1f) -> FAILS AssertionError: 2 not greater than 3 : the python3 row has no Floor cellthis commit -> passes

So the overwrite was real and the message it produced pointed at the contract table, which is the wrong place entirely. The drift cases still fail correctly: a floor drifting to 3.12 and a version hidden in Present when with Floor blanked both fail as before.

On the shape of these three findings

This is the third finding in a row on this one test, and all three are the same mistake: a lookup wider than the thing it meant to name. The row keyed on the whole line, then the version searched across every cell, then the table read to the end of the file. Each time I narrowed the one you named and left the next one open, and each time my own verification passed because the collision it needed did not exist yet in this document.

That is worth recording as more than an apology, because it is the failure mode the test itself was written to prevent: a check that passes on today's data while asserting nothing about the property it claims. The cases I construct to verify a check are drawn from the same understanding that wrote the check, so they confirm it rather than test it. The three rewrites I ran after the first fix are a good illustration, since they passed while two independent holes remained.

[Copilot]

Pull request overview

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