Skip to content

docs: USAGE.adoc, catalogue.adoc and man/pons.1 document subcommands and flags the binary does not have #43

Description

@hyperpolymath

Problem

Three documents that landed in #39 describe a CLI that does not exist:

  • docs/USAGE.adoc
  • docs/catalogue.adoc
  • docs/man/pons.1

They document these subcommands: extract, trace, spell, search, doctor, challenge and catalogue. They also document these flags: --rule, --lang, --protocol and --no-speculative, among others. The binary at main (7ec7e08) has only this surface:

pons scan <PATH> [--format human|json|sarif] [--fail-on info|warn|error]

catalogue.adoc says it is generated by pons catalogue. No such generator exists; it is scheduled for M7.

For a tool whose contract is "never dress a heuristic up as a proof", documentation that claims features the binary lacks is a correctness defect, not just stale text.

Acceptance criteria

  • Every subcommand and flag in USAGE.adoc and man/pons.1 either exists in pons --help at the commit that closes this issue, or is marked planned (M) with its PLAN.adoc milestone.
  • catalogue.adoc does not claim to be generated until the M7 generator and its drift test exist. Until then it lists only the 8 registered T0 rules, in RuleRegistry::all() order.
  • A test or just recipe diffs the documented flag set against pons scan --help. A mutant that adds a fake flag to USAGE.adoc must turn it red.
  • PROOF-PROGRESS.adoc "Known gaps" row is removed or updated when this closes.

Not a blocker for M4. It must close before the v0.1.0 tag (M8).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationDocs, prose, diagrams, READMEs, ADRspriority:p2Normal - queue itscope:repoConfined to this repository

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions