Define correction exit statuses

[BenWestgate]

Fixes #39.

correct now has a stable, documented status contract:

• 0: input is already valid
• 1: a correction suggestion was emitted
• 2: command or input syntax is invalid
• 3: no usable suggestion was emitted

Status 3 covers no result, incomplete searches with no usable suggestion, ambiguous searches, refused disclosure, and a missing dependency needed to present a suggestion. Worksheet-residue repairs return 1 when they emit repair instructions. Other commands retain their existing status behavior.

This PR is stacked on #42 because its tests include the mixed-case correction path. It is one human-authored focused commit on #42 head 7c7ba26; current #45 head is 794f898. All inline review threads are resolved, including the immutable-HRP syntax check, the generalized BIP93 1–83 HRP contract, and the incomplete-search documentation qualification.

Validation:

• correction/status/disclosure subset: 104 passed normally and 104 under python -O;
• frozen differential correction verifier: all 57 cases passed;
• Ruff check: clean for the touched Python files;
• git diff --check: clean;
• exact-head GitHub Python-package run 433: success.

Human review order is #42 first, then #45.

The HRP check follows the generalized BIP93 draft (BenWestgate/bips PR #2 @ 01374bf): BIP93 uses the BIP173 HRP grammar, including the 1–83 character bound; the larger limit is for the expanded checksum codeword, not the HRP.

Disclosure: AI tools were used while implementing and checking review follow-ups, per docs/developer/AI_POLICY.md.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9178bf4cde

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BenWestgate]

Thanks for suggesting this one @FractalEncrypt.

[BenWestgate]

AI-generated review (Claude), posted at the maintainer's request.

Concept ACK. Code looks right; not ACKing 5a826bd until the merge commits are gone.

• I checked correct on the head: already valid → 0, garbage prefix/empty → 2, uncorrectable/non-ASCII → 3, EOF at the YES gate → CorrectionDeclined → 3. That matches the docs.
• The branch has two merges of #42 (60cb96e, 5a826bd). Rebase to 9178bf4 + 06e4a05 per CONTRIBUTING.

[BenWestgate]

Release-gate recheck: the prior Concept ACK still has one mechanical blocker. Current head remains 5a826bd with the two #42 refresh merges (60cb96e, 5a826bd) in a 4-commit stack. Rebase to a linear #42 head + the substantive status commits (9178bf4 and its follow-up) before human review/merge, per CONTRIBUTING. The exit-status behavior itself remains accepted.

[BenWestgate]

Release-gate follow-up: the earlier branch-history blocker is resolved. Current head eb7cfdd is a single linear commit directly on #42 head 2d925d6; the refresh merge commits are gone, the only review thread is resolved, and fresh Python package run 36291117100 completed successfully. The exit-status behavior remains the previously Concept-ACKed design, so #45 is ready for human review after #42.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 87f0ff8190

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8de15a739

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BenWestgate]

AI-generated review, posted at the maintainer's request.

ACK 3d5e60d code. Before merge, squash/rewrite the Codex-authored follow-up under the responsible human author per the AI policy.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ee752abfde

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BenWestgate]

Release-gate ACK 794f898.

Current head is the one human-authored focused commit on #42. The resolved review findings are present in the final tree: standalone correct uses distinct 0/1/2/3 statuses, malformed immutable HRPs are usage errors under the 1–83 BIP93/BIP173 contract, disclosure refusal/no-result paths use status 3, and emitted incomplete best-effort suggestions remain status 1. All inline threads are resolved and exact-head Python-package run 433 is green.

No remaining code blocker from this review. Review #42 first, then #45.

[BenWestgate]

Agent release-gate review at current head 794f898: reviewed the single current commit. The status contract is internally consistent (0 valid, 1 suggestion emitted, 2 usage/input syntax, 3 no usable suggestion), residue repair correctly returns 1 when it emits instructions, malformed immutable HRPs remain usage errors, and non-correct commands retain status 1 for command/Core failures. Exact-head Python-package run 36646776371 succeeded. No remaining code-review blocker found; review #42 first, then this PR.

[BenWestgate]

crACK