Gate the pattern-detectable half of the representative-data rule

[ptr727]

Why

GOVERNANCE.md "Representative Data in Agent-Authored Text" says agent-authored text illustrates with constructed data rather than data observed in the maintainer's environment, and says in the same breath that no pattern closes it. This gates the half a pattern can reach.

It is introduced as that half deliberately. The leak that motivated the rule was name-shaped and sat in a pull request comment, which no committed-file linter reads, so a check mistaken for the answer is what stops anyone looking at the exposure the rule actually exists for.

Carries the TODO.md cluster "The Representative-Data Path Check", which #595 released from blocked once the scope floor shipped in #594.

The shapes were measured, not assumed

The backlog recorded four shapes, /home/<name>, /Users/<name>, C:\Users\<name>, and a bare drive letter. Run against this repository, a bare drive letter matched 11 files and named a path in none of them.

An escaped newline after any word ending in a letter and a colon reads as a drive letter, so a YAML fixture is full of them:

Matched text	What it actually is
e:\n needs	jobs:\n needs inside a test fixture string
s:\n a	jobs:\n a: inside a test fixture string
C:\tmp (8 hits)	a temp path in fixtures for the string-literal rule

That shape is dropped. The one kept is a drive letter followed by Users, which matches nothing in the tree today. This is narrower than the committed prose, which says "an absolute home path or a drive letter", so the narrowing is stated here rather than left for a reader to discover.

The exemption is built, not listed

A wrong exemption hands out a work list that damages correct documents, and this rule has two self-referential problems that a file-name allowlist would solve badly and briefly.

The rule's own wording quotes the shapes it forbids. Requiring a real user segment solves it by construction: the documentation placeholder is not a valid account name, so it describes the shape without matching it. No exemption names GOVERNANCE.md, and none goes stale when the text moves.

Probe	Verdict
C:\Users\<name> in documentation	no match
/home/<name> in documentation	no match
/home/vscode/.ssh	exempt, container account
a real absolute home path	flagged

Container accounts are exempt by name. Every home path in this repository, all 15, is /home/vscode from the devcontainer snippets and the doc describing them. Without that exemption the rule would open with 15 findings and no true positive among them.

The gate reads its own source, so the bait paths in the tests are assembled from parts and a case asserts that neither prose_lint.py nor its test file carries a literal. That is the approach the file already takes for non-ASCII, which it writes as escapes for exactly this reason.

Operational repositories are exempt, and told so

An operational repository's runbook carries the literal path an operator types. That is the repository's own content rather than an agent quoting an environment it observed, which is the distinction the rule is about.

The model is read from what the repository carries rather than from the hub registry, which a downstream checkout cannot see: spec/files.json declares repo-config/operational/develop.json for the operational model and repo-config/develop.json for the release one. The hub carries both, being the template for each, so it reads as release rather than exempting itself from a rule it authors.

The skip is announced on stderr, because a rule that silently stops running reads as a rule that passed, which is the same failure #594 closed on the other side.

Scope note

Unlike every other prose rule, this one reads fenced blocks and configuration values rather than stripped prose. A transcript pasted from a terminal and a bind mount naming a real home are the exposure in its most consequential forms, and neither is a sentence.

Verification

• python3 scripts/test_prose_lint.py - 188 pass, up from 173. Of the 14 new cases, 10 fail against develop and 4 pass against both, holding the must-not-fire direction.
• python3 scripts/prose_lint.py . --check home-path - clean across the tracked tree.
• python3 scripts/prose_lint.py . --summary - 557 violations across 45 files, the prose_lint: the hub's own docs, spec, and catalog do not pass the gate it ships #519 backlog figure unchanged, with home-path contributing none. Adding a rule to DEFAULT_RULES did not move the number.
• python3 spec/validate.py, python3 spec/audit.py --selftest, python3 scripts/repo_gate.py - clean.
• The blocking CI prose run - clean.

Correction: this branch carries the TODO bookkeeping too

An earlier revision of this description said the TODO.md edits were held back to avoid conflicting with #595. That was wrong. This branch was cut from #595's branch rather than from develop, so it already contained that commit, and the description claimed an absence a reader could disprove from the diff.

The review then caught the real consequence: the cluster entry still promised a bare drive letter after the implementation dropped that shape. Correcting the bullet was the smaller half of the answer, since this is the pull request that ships the cluster, so c6fca9e applies step 9 and deletes it rather than leaving a corrected description of finished work. The disproved claim is recorded here and in the commit message, alongside the measurement that disproved it.

This makes #595 redundant, since every line of it is already in this branch. Closing it as superseded is the maintainer's call rather than something this branch does.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new home-path rule to scripts/prose_lint.py to gate the pattern-detectable subset of the "Representative Data in Agent-Authored Text" policy (absolute home paths that look like real user homes), including tests and an operational-repository exemption, and updates the corresponding TODO cluster state.

Changes:

• Add home-path detection to scripts/prose_lint.py, include it in DEFAULT_RULES, and exempt operational checkouts (with an explicit stderr note).
• Add focused unit tests for home-path, including placeholder non-matches, service-account exemptions, fenced/config coverage, and operational exemption behavior.
• Update TODO.md to mark the representative-data path check cluster as ready and refresh its Checked anchor.

Reviewed changes

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

File	Description
TODO.md	Updates the work-cluster state/anchors for the representative-data path check.
scripts/prose_lint.py	Implements the home-path rule, adds it to defaults, and adds an operational-checkout exemption.
scripts/test_prose_lint.py	Adds unit tests covering the new home-path rule and the operational exemption behavior.

Suppressed comments (1)

TODO.md:37

• This list of shapes still includes "a bare drive letter", but the new home-path regex intentionally excludes that form due to false positives. Consider updating the shapes here to match what the gate actually checks.

  - **Settled** - The shapes are `/home/<name>`, `/Users/<name>`, `C:\Users\<name>`, and a bare drive letter.

[Copilot]

Pull request overview

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

Suppressed comments (3)

scripts/prose_lint.py:64

• HOME_PATH matches only "\Users\" with a capital U. Windows paths are case-insensitive, so a pasted path like "C:\users\alice" would currently be missed (false negative). Consider allowing lowercase as well to match real-world logs and terminal output.

HOME_PATH = re.compile(r'(?:/home/|/Users/|[A-Za-z]:\\Users\\)(?P<user>[A-Za-z][A-Za-z0-9._-]*)')

scripts/prose_lint.py:160

• home_path_findings includes the full matched absolute path in the lint output. Since the purpose of this rule is to prevent leaking real home paths, echoing the literal path into CI logs can unnecessarily amplify the exposure. The file+line is already reported, so the message can stay actionable without repeating the sensitive value.

        out.append((lineno, 'home-path',
                    f'absolute home path {m.group(0)!r} -> use a constructed path, not an '
                    'observed one'))

scripts/test_prose_lint.py:1585

• Test name reads as a grammatical typo ("persons" vs "person"). Renaming improves readability and avoids introducing a new inconsistent identifier.

    def test_a_container_account_is_not_a_persons_home(self) -> None:

[ptr727]

Answering the three suppressed comments from the round on c6fca9e, since a suppressed finding has no thread to pair an answer to. Two accepted, one declined, all fixed or answered in f8d6090.

Accepted, prose_lint.py:64 - case sensitivity on the Windows branch. Correct and a real false negative. Verified before fixing:

Probe	Before	After
C:\Users\<user>	match	match
C:\users\<user>	miss	match
c:\USERS\<user>	miss	match

The fix is scoped to the drive-letter branch rather than applied to the whole pattern, which is the part worth recording. Widening the POSIX branch the same way would match https://api.example.com/users/<user>, and a lowercase /users/ is the commonest REST path there is, so it would flag an API route in every document that has one. Two cases now hold both halves.

Accepted, test_prose_lint.py:1585 - the possessive read as a typo. Renamed to test_a_container_account_is_not_a_personal_home.

Declined, prose_lint.py:160 - echoing the matched path into CI logs. The reasoning is sound in general and I checked it rather than dismissing it, but its premise does not hold here. The value being echoed is already in a committed file in this repository, and the log line points at that file and line. The reader of the log and the reader of the file are the same audience with the same access, so the log adds no exposure that the file does not already carry. What it would cost is real: the message is what tells an author which of several paths on a line is the finding, and dropping it leaves a rule name and a line number for a rule whose whole subject is a specific string.

The case the finding is reaching for is a path that never reaches a commit, which this gate cannot see, since it reads committed files. That gap is genuine and is stated in the description rather than closed here: the leak that motivated the rule was in a pull request comment, which no committed-file linter reads.

[Copilot]

Pull request overview

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