Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352

Design (design-architect pass 30, 2026-11-01). Full design doc: files/designs/code-operator-argument-contract.md in the keep-the-four-repos-healthy goal workspace. Audited at origin/main 5de8ee19. No user/review: every origin carries explicit acceptance with a verified laptop probe, and the judgment calls below are the architect's recorded decisions.

Summary

The repo's operator scripts parse their command lines by membership test — args.includes("--dry-run"), argv.indexOf("--store") — and are silent about everything else. Ten filings in three days are that silence, in two costumes plus a sibling:

• Unknown argument silently ignored → the mutating operation runs. pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264 (pkarr-worker deploy: --dry-rnu deploys for real; --deploy-version=<id> falls through to deploying HEAD), github-backup(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real deploy (upload + secret reset) #3287 (github-backup worker deploy, written after pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264 was filed), id-mail(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu enters the real deploy sequence and force-deletes the retired 'id-mail' Worker #3281 (id-mail worker deploy: a typo'd preview force-deletes the retired Worker, then deploys), opencode-claimant(install): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real install, and a typo'd --stor writes the real OpenChamber store #3278 (opencode-claimant install: typo'd --dry-rnu installs for real; typo'd --stor silently re-aims at the real OpenChamber store), proxy-supervise: unrecognized arguments are silently ignored — a typo'd --dry-rnu starts/rolls real proxies, and a typo'd --statuz reconciles instead of reporting status #3296 (proxy-supervise: --dry-rnu starts real proxies; --statuz reconciles instead of reporting status), sync-models: unrecognized arguments are silently ignored — a typo'd --dry-rnu rewrites the live OpenCode config in place (and reloads opencode) #3297 (sync-models: a typo'd preview rewrites the live OpenCode config and reloads opencode).
• A value option present but valueless is silently replaced / consumed / crashed on. aggregator(charges-producer): a trailing or flag-like --start/--end/--out value is silently replaced by the defaults — the producer overwrites the live candidates file for the wrong period and exits 0 #3333 (charges producer: trailing --out overwrites the live candidates file via the ?? default), aggregator(backfill): trailing --dir crashes with a raw TypeError, and a flag-like value (--dir --print) silently writes the rebuilt history into a directory named '--print' #3330 (snapshot backfill: trailing --dir raw TypeError; --dir --print writes into a directory named --print), aggregator(snapshots): append-usage-snapshots --by with no value silently discards every derived record — exit 0, 'no records derived' #3295 (snapshot append: trailing --by silently discards the run's records, exit 0), mcpx(docs-history): a value-taking flag as the last argument panics — stamp/check arg loops index rest[i] after i++ with no bounds check #3312 (mcpx docs-history, Go: trailing value flag panics instead of printing usage).
• Sibling: pkarr-worker(deploy): --dry-run is ignored on the --deploy-version path — a rollback preview creates a real 100% deployment #3252 — the recognized --dry-run is dropped on pkarr deploy's --deploy-version branch, so a rollback preview creates a real 100% deployment.

The strict behaviour already exists in-tree (lib/bws-to-sops.sh:53 dies on unknown argument; scripts/stage-docs.sh:45; compact-usage-snapshots.ts:28-31 exits 2 naming a bad value). No operator script uses a strict platform parser (zero parseArgs hits). Sibling contracts: #2835 governs env numbers, #3005 measurement strings, dezren39/darwin-nix#1145 another repo's scripts — this repo's argv has no stated contract.

The contract (recorded decisions)

Every argument is accounted for before anything happens. A script declares its whole command line and parses strictly; anything unaccounted for is a usage error naming the offending argument, exit non-zero (2 where no usage code is established), before any subprocess / network / file write / lock / deploy step.

1. Unknown means stop — unknown flag, stray positional, and typo'd flag are the same event.
2. --opt=value either works identically to --opt value or is refused under (1) — never a silent fall-through to a different operation (per-tool pin in triage, stated in usage text).
3. Present-but-valueless is not absent — trailing, flag-valued, or (where non-empty is required) empty values are usage errors naming the option; defaults apply only when the option was not given.
4. A parsed safety flag (--dry-run, --status) is honoured on every path; tests cover the flag × path matrix.
5. Per-tool strict parsing (tools deploy independently, three languages, no shared imports); the contract and one probe matrix are shared: unknown flag → zero stubbed side-effect calls; typo'd safety flag → same; value-option edge forms → pinned behaviour; previously valid invocations unchanged.

Phases (adopted origins — no parallel issues)

• Phase 1 = pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264 + pkarr-worker(deploy): --dry-run is ignored on the --deploy-version path — a rollback preview creates a real 100% deployment #3252, github-backup(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real deploy (upload + secret reset) #3287, id-mail(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu enters the real deploy sequence and force-deletes the retired 'id-mail' Worker #3281, opencode-claimant(install): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real install, and a typo'd --stor writes the real OpenChamber store #3278, proxy-supervise: unrecognized arguments are silently ignored — a typo'd --dry-rnu starts/rolls real proxies, and a typo'd --statuz reconciles instead of reporting status #3296, sync-models: unrecognized arguments are silently ignored — a typo'd --dry-rnu rewrites the live OpenCode config in place (and reloads opencode) #3297 (unknown means stop on the side-effecting tools; lands first).
• Phase 2 = aggregator(charges-producer): a trailing or flag-like --start/--end/--out value is silently replaced by the defaults — the producer overwrites the live candidates file for the wrong period and exits 0 #3333, aggregator(backfill): trailing --dir crashes with a raw TypeError, and a flag-like value (--dir --print) silently writes the rebuilt history into a directory named '--print' #3330, aggregator(snapshots): append-usage-snapshots --by with no value silently discards every derived record — exit 0, 'no records derived' #3295, mcpx(docs-history): a value-taking flag as the last argument panics — stamp/check arg loops index rest[i] after i++ with no bounds check #3312 (present-but-valueless; independent of Phase 1).
• Phase 3 = closing inventory audit + contract statement (filed as a sub-issue, gated on Phases 1–2): every remaining hand-rolled argv parser in bin/, pm-stack/*/scripts/, deploy/install scripts and the Go tools, dispositioned covered / strict / deliberately lenient with reason (interactive REPL id(repl): find/search/show/peek parsers silently swallow unknown and mistyped flags — a typo'd flag vanishes and its value becomes a query #2274 named deliberately-local; env-value pkarr-worker(retention): RETENTION_SECONDS is parsed with a bare Number() and no guard — '0'/'7d'/' ' schedule the deletion alarm at/before now (or NaN), so stored packets vanish right after a 204, and '1e9' never expires #3261 dispositioned against Design: env numbers are arguments — one strict parse for boot-time configuration #2835/Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837, not adopted).

Open questions stay in the design doc (repeated value options; short-flag style; a mechanical net; leading-dash values).

Displacement note: this pass's standing candidate was the pkgs/id plain-output rendering family (#2839/#3111/#3089, pass 29). It is displaced by this cluster per pass 29's own watch condition (unknown-args "revisit at a third tool" — now six, plus four) and remains the standing candidate for pass 31.

Acceptance criteria

• Every operator script in the audit scope either rejects unknown arguments with a non-zero exit and a named error, or is explicitly dispositioned as deliberately lenient with its reason recorded (per the design doc's contract statement).
• Phases 1-3 (the origin issues named in the design) are filed as linked implementation issues and land or are dispositioned; the closing argv-parser inventory (Phase 3, Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353) finds no un-dispositioned hand-rolled parser in scope.
• A typo'd flag on a mutating script (e.g. --dry-rnu on a deploy script) provably performs no mutation — verified by probe on at least one script per family.