Guard semantics the lane's consumers restate in prose have no drift detection

[kyle-sexton]

Problem

A consumer configuring a host permission classifier for this plugin's lane has to restate, in prose, facts that actually live in this repository's code. Four rounds of independent review on melodic-software/dotfiles#315 produced a wrong statement about one of these three separate times, and each time the only thing that caught it was a human or agent reading both the prose and the source side by side.

The facts being restated, with where they really live:

• Resolver flag semantics. babysit_resolve_thread.py enforces bot-only at line 189 iff --include-human is absent, and the isOutdated check at 193 iff --autonomous or --only-outdated. The pin chain at 325 → 345 → 362 is what makes --autonomous mean "single pinned thread" rather than "bulk". A consumer's permission rule that says "resolves only outdated bot threads" is true only for a specific flag combination.
• Where a refusal lives. bin/source-control-babysit-merge refuses --allow-unpinned-head in bash; babysit_merge.py accepts it as an ordinary argparse flag. Whether an invocation is safe depends on which of the two you called, and nothing in the Python says so.
• Which helpers mutate. request_review.py --apply posts a comment, prune_babysit_worktrees.py --apply runs git worktree remove, the lease and ledger helpers write state. A consumer that classifies these as read-only is wrong, and the scripts' names do not say which is which.
• What a script actually calls. refresh_pr_branch.py requests GitHub's server-side update-branch endpoint rather than pushing — safer than it reads, but a consumer reasoning about push guards will reason about the wrong mechanism.

Why it drifts silently

Nothing connects the two. If a flag is added, if the merge wrapper's refusal moves into Python, if a helper starts mutating, the consumer's prose keeps asserting the old behavior — and autoUpdate: true on the marketplace carries the code change to every machine while the prose stays exactly where it was.

So a consumer's permission configuration is verified as of a commit and has no mechanism to stay verified. That is the opposite of how the rest of this repo treats its contracts: test_skill_contract.py exists precisely because prose about behavior rots.

What would fix it

Not another documentation pass. Something that fails when the semantics change. Rough shapes, unranked:

1. A machine-readable capability manifest per lane script — mutating vs read-only, which flags gate which guard, which entry point carries a refusal the other does not — emitted from the code (argparse introspection gets most of it) and asserted by a test.
2. A contract test that pins the specific guard predicates a consumer is told to rely on, so changing line 189's condition fails CI with a message naming the downstream claim.
3. A documented "what a permission rule may assume" section with a stability commitment, so consumers cite a contract rather than reverse-engineering the source. Weakest of the three — still prose — but it puts the burden in one reviewable place.

Option 1 has a second payoff: /source-control:setup's new lane-script reachability probe (#787, PR #1264) currently has to name the plugin's scripts from prose too. A manifest would let it enumerate them instead.

Context

• melodic-software/dotfiles#315 is the consumer configuration that surfaced this. Its audit trail has the specific instances.
• Related: source-control:babysit-prs: read-only babysit_merge.py invocation blocked by host auto-mode permission classifier #787 (lane scripts denied by a host classifier), Autonomous thread-resolve: pin pre-push isOutdated state (per-thread comment pins don't stop own-push displacement) #571 (the displacement case that makes isOutdated a weak signal — itself a guard semantics fact consumers restate).
• Not urgent. It is a durable structural gap, not a live defect.

[kyle-sexton]

The question that decides between the three options

Option 1 rests on a speculation in the issue body: that "argparse introspection gets most of it."
Investigated against origin/main. It does not.

Measured across the 9 CLI scripts (of 18 .py files under
skills/babysit-prs/scripts/):

• add_mutually_exclusive_group appears in 2 of 9 parsers — babysit_findings.py and
  pr_queue_snapshot.py — and neither guards a mutation. Both are input-source choices
  (--pr vs --comments-json).
• Every inter-flag constraint on a mutating path is imperative post-parse_args() code: 7
  parser.error(...) calls plus 19 bespoke return 2 / return 3 refusal blocks, 9 of those in
  babysit_resolve_thread.py and babysit_merge.py alone.
• The guard predicates are boolean expressions over runtime API data, not over flags:
  (autonomous or only_outdated) and not thread["isOutdated"]. Argparse has no view into that.
• --include-human, --allow-unpinned-thread and --autonomous are three identical store_true
  declarations. Only the if bodies distinguish "lifts the bot-only bright line" from "requires a
  pin" from "refuses bulk". Nothing in the parser says which relaxes and which tightens.
• Refusal precedence is statement order: --allowed-owners (exit 3) fires before head-format
  validation (exit 2) in merge, and after it in resolve.
• The bash refusal in bin/source-control-babysit-merge is outside Python entirely.

Mutating-vs-read-only is not derivable from flag names, and the naive mapping is actively wrong.
manage_babysit_lease.py's --apply help reads "reap only: actually delete expired worker lease
files (default: dry run)". But acquire, heartbeat, and release write lease files
unconditionally under state_lock — no --apply involved. A manifest derived from flag names
classifies acquire as read-only. It is not.

So option 1's guard section is hand-authored — the same as option 3

Mechanically derivable from argparse: flag names, action/type/choices/default, required=True,
help text, the two input-source exclusion groups, positional action choices. That is a flag
catalogue — roughly 30% of what a consumer needs.

Hand-authored regardless: every guard predicate, the mutating/read-only classification, the bash
refusal, the exit-code contract, refusal precedence. Roughly 26 refusal sites' worth of semantics.

The discriminating axis was never manifest-vs-prose. It is whether each claim is bound to an
executable assertion. A hand-written manifest that nothing runs is option 3 with a JSON schema,
and drifts identically. A manifest whose rows are the parametrized input to a test that invokes
the CLI is option 2 with a data file. Built that way, options 1 and 2 are one artifact.

The machinery already exists

skills/babysit-prs/scripts/tests/test_guards.py (162 lines) is already a partial option 2, and
the issue does not mention it. Its docstring:

Every assertion here exercises a refusal that must fire BEFORE any network call, so the tests
need no gh stub: a fail-closed guard rejects on argument shape alone.

It black-box-invokes both guarded CLIs by subprocess and asserts (exit code, error substring) —
already covering the --autonomous bulk-resolve refusal and the
--autonomous --allow-unpinned-thread refusal. Each additional row costs one subprocess call and
two assertions. No gh stub, no fixture.

(test_skill_contract.py, by contrast, is a pure prose-rot test — it asserts literal substrings in
SKILL.md and reference/safety.md. It pins documentation text, never CLI behavior.)

Recommendation

Option 2, extended — with the manifest as its data table. Grow test_guards.py from
hand-written cases into a table-driven suite whose table is the consumer-facing artifact: one row
per (entry point, argument shape, expected exit code, expected error substring, mutating yes/no),
plus the prose claim each row backs. Changing a guard predicate then fails CI with a message naming
the downstream claim — issue option 2's stated goal — and consumers cite the table rather than
reverse-engineering the source.

Reject option 1 as sketched. Its premise is falsified.

Defer the argparse flag-catalogue layer, with a trigger. It is genuinely additive — it catches
flag-surface drift (a renamed --only-outdated, a changed default) that a behavior test would not
— but it is not free: all 9 parsers are constructed inside main(), and none exposes an un-parsed
parser object, so an emitter needs a build_parser() refactor across 9 files or --help scraping
before it emits its first line. Trigger: the first time a flag rename or default change ships
without a corresponding table update.

Two findings for the linked work

1. #787 / PR fix(source-control): emit a readiness verdict on the gate's silent failure paths #1264's reachability probe cannot enumerate scripts by convention. There is no
   manifest. The directory over-counts — 18 .py files, 9 with an ArgumentParser. Naming probes
   misfire in both directions: babysit_findings.py is a real CLI despite the shared
   babysit_* library prefix, while babysit_review_trigger.py and babysit_delta.py look like
   entry points and are not. bin/ is a genuine enumerable list but covers 2 of 11. The precise
   mechanically-derivable entry-point list is "files containing ArgumentParser" plus the 2 bin/
   wrappers.

2. A live instance of this issue sits in the file PR fix(source-control): emit a readiness verdict on the gate's silent failure paths #1264 edits. reference/safety.md
   §Pinned-Command Degradation hard-codes the full bin/-path wrapper command line with its flag
   list. It drifts against babysit_merge.py's parser with nothing detecting it. Also:
   bin/source-control-babysit-resolve-thread is a 15-line pure passthrough with no filter loop,
   while bin/source-control-babysit-merge refuses --allow-unpinned-head in bash — one wrapper
   carries a refusal the other does not, and nothing on the Python side sees it. That is precisely
   the issue's "which entry point carries a refusal the other does not".

[kyle-sexton]

This was generated by AI during triage.

Verified — decision already made, and in flight

PR #1285 is open and carries Closes #1265. The status: needs-decision this item carried is stale: the decision it was waiting on has been made and implemented.

The item body offered three options and rested option 1 on a stated speculation ("argparse introspection gets most of it"). That speculation was investigated and falsified — recorded both in this item's own first comment and in PR #1285's body: add_mutually_exclusive_group appears in 2 of 9 CLI parsers and neither guards a mutation; every inter-flag constraint on a mutating path is imperative post-parse_args() code; and mutating-vs-read-only is not derivable from flag names (manage_babysit_lease.py's --apply help says "reap only" while acquire/heartbeat/release write unconditionally).

The chosen resolution is closest to option 2, generalized: scripts/tests/guard_contract.py holds the guard table as the single source of truth, test_guards.py executes every row, and reference/guard-contract.md is generated from the same tables and asserted current — so the drift detection this item asked for is a CI failure naming the downstream prose claim, not another documentation pass.

Classification

• Work class: C4 structural — establishes a new executable contract surface consumed across repositories (the melodic-software/dotfiles#315 host permission configuration cites it).
• Disposition: human-gated, human-merge — C4 always is. Cleared status: needs-decision (resolved) and the raw marker; applied status: ready since the work is authored and under review.

Related items this does not close

PR #1285 lands the contract harness. Two sibling items remain open and are the natural first consumers of it — both were triaged in this same sweep:

• source-control:babysit-prs: --apply helpers need mechanically-validated wrappers like the merge gate and thread resolver #1281 — the --apply helpers still need mechanically-validated wrappers; source-control:babysit-prs: --apply helpers need mechanically-validated wrappers like the merge gate and thread resolver #1281's "properties of the current implementation with no test asserting them" is precisely what this harness can now assert.
• source-control:babysit-prs: babysit_resolve_thread.py --autonomous does not enforce severity or own-PR conditions its callers rely on #1287 — babysit_resolve_thread.py --autonomous still does not enforce severity or own-PR conditions.