chore(compat): cite CONTRACT §7 Hermeticity in code and README (#16)

§7 Hermeticity landed in commit 47e6d64 (PR #9), so the three call
sites that described the property as a "harness invariant the contract
does not promise today" are now stale — the property IS a contract
promise, and these bundles pin down what §7 promises.

Updates:
- compat/dates/dates.go: helpIsHermetic and flagValidationIsHermetic
  godocs swap "harness invariant" framing for "Pins down the … path of
  CONTRACT §7 Hermeticity on every PR" (section reference by name; no
  fabricated quoted text per the standing rule).
- compat/formats/formats.go: flagValidationIsHermetic same.
- compat/README.md: the two subtest tables flip the Contract column
  from "harness invariant" → "§7" for the three hermetic rows so
  citation-verifier CI (QUA-20, when it lands) recognizes them as
  contract-anchored.

Net: -19 lines of bridging prose, +10 lines of canonical refs.

Follow-up to QUA-22; the §7 section itself is already on main.

Co-authored-by: LeadGoEngineer <leadgoengineer@quantcli.local>
Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: 3 people

compat/README.md

@@ -100,8 +100,8 @@ The exporter does not need a separate `go.mod` for compat tests — the standard
 |---|---|---|
 | `HelpDocumentsDateFlags` | §3 | `--help` mentions `--since` and `--until` and exits 0. |
 | `InvalidSinceValueFails` | §3, §4 | `--since obviously-not-a-date` exits non-zero, writes to stderr, leaves stdout empty. |
-| `HelpIsHermetic` | harness invariant | `--help` succeeds with all HTTP proxies pointed at an unreachable address. |
-| `FlagValidationIsHermetic` | harness invariant | A parse failure also produces no successful outbound request. |
+| `HelpIsHermetic` | §7 | `--help` succeeds with all HTTP proxies pointed at an unreachable address. |
+| `FlagValidationIsHermetic` | §7 | A parse failure also produces no successful outbound request. |
 
 When `compat.Runner.Subcommands` is set, every row above runs once per declared subcommand under `subcommand=NAME/...`.
 
@@ -111,7 +111,7 @@ When `compat.Runner.Subcommands` is set, every row above runs once per declared
 |---|---|---|
 | `HelpDocumentsFormatFlag` | §4 | `--help` mentions `--format` and exits 0. |
 | `UnknownFormatFails` | §4 | `--format obviously-not-a-format` exits non-zero, writes to stderr, leaves stdout empty. |
-| `FlagValidationIsHermetic` | harness invariant | The unknown-format parse failure makes no successful outbound request. |
+| `FlagValidationIsHermetic` | §7 | The unknown-format parse failure makes no successful outbound request. |
 | `JSONIsArray` | §4 | `--format json` exits 0 and emits stdout that unmarshals as `[]any`. |
 | `CSVHasHeader` | §4 | `--format csv` exits 0 and emits at least one non-empty line on stdout (the header row, present even on an empty result). |
 | `DefaultIsMarkdown` | §4 | No `--format` flag produces byte-identical stdout to `--format markdown`. |

compat/dates/dates.go

@@ -161,13 +161,9 @@ func invalidSinceValueFails(t *testing.T, r compat.Runner) {
 // unreachable address. If the CLI tries to hit the network at all, it
 // will fail or hang — the latter is caught by the Runner timeout.
 //
-// This is a harness invariant, not a property the contract promises
-// today. A `--help` that dialed out would still satisfy §3 surface
-// checks but would be unusable for LLM-agent introspection (an agent
-// must be able to ask "what does this CLI do" without a token or
-// network). Codifying hermeticity as its own CONTRACT.md section is
-// tracked separately; in the meantime the framework defends the
-// property here so an exporter cannot regress it silently.
+// Pins down the `--help` path of CONTRACT §7 Hermeticity on every PR.
+// §7 is load-bearing for LLM-agent introspection: an agent must be able
+// to ask "what does this CLI do" without a token or working network.
 func helpIsHermetic(t *testing.T, r compat.Runner) {
 	t.Helper()
 	res := r.WithEnv(noNetworkEnv()...).MustRun(t, "--help")
@@ -176,10 +172,11 @@ func helpIsHermetic(t *testing.T, r compat.Runner) {
 	}
 }
 
-// flagValidationIsHermetic is the parse-failure half of the same
-// harness invariant documented on helpIsHermetic above: a CLI that
-// dialed out before rejecting an invalid flag would have already
-// leaked a network call by the time it exits non-zero.
+// flagValidationIsHermetic is the date-parse-failure half of CONTRACT
+// §7 Hermeticity, paired with helpIsHermetic above: a CLI that dialed
+// out before rejecting an invalid flag would have already leaked a
+// network call by the time it exits non-zero. Pins down the
+// date-parse-failure path of §7 on every PR.
 func flagValidationIsHermetic(t *testing.T, r compat.Runner) {
 	t.Helper()
 	args := []string{"--since", "obviously-not-a-date", "--until", "obviously-not-a-date"}

compat/formats/formats.go

@@ -154,14 +154,8 @@ func unknownFormatFails(t *testing.T, r compat.Runner) {
 // failure does not dial out. Mirrors the dates bundle's parse-failure
 // hermetic test, but exercises the `--format` parse path explicitly
 // in case the CLI looks up format codecs differently than date
-// values.
-//
-// This is the same harness invariant the dates bundle defends — a
-// flag-validation failure must not have already opened a connection
-// by the time it exits non-zero. It is not a contractual claim
-// (CONTRACT.md does not define a hermeticity section today);
-// codifying that is tracked separately. Until then, the framework
-// enforces it here so an exporter cannot regress it silently.
+// values. Pins down the `--format` parse-failure path of CONTRACT §7
+// Hermeticity on every PR.
 func flagValidationIsHermetic(t *testing.T, r compat.Runner) {
 	t.Helper()
 	res, err := r.WithEnv(noNetworkEnv()...).Run(context.Background(), "--format", unknownFormatValue)