Skip to content
This repository was archived by the owner on Aug 13, 2026. It is now read-only.
This repository was archived by the owner on Aug 13, 2026. It is now read-only.

F11 follow-up: annotate bounded-input flags with vers:enum:* #192

Description

@AlephNotation

PR #191 wired an enum-annotation hook into vers agent-context but did not apply it to any existing commands. This issue tracks the sweep.

Background

cmd/agent_context.go walks every flag and looks for an annotation on the parent command of the form vers:enum:<flag-name> with comma-separated valid values. When present, the flag's schema entry includes an enum: [...] array.

// Example wiring
cmd.Annotations["vers:enum:visibility"] = "public,private,unlisted"

This unlocks two agent-native wins:

  1. agent-context consumers learn the constraint without parsing --help text or reading server responses.
  2. errorsx can produce self-enumerating errors per principle 3 ("errors that teach"): error: --visibility must be one of: public, private, unlisted (got: "secret").

Candidates to annotate

A non-exhaustive sweep of bounded-input flags:

Command Flag Probable enum
repo visibility positional <visibility> public, private
commit publish / unpublish (state shape) n/a
Any future --deliver flag (F17) --deliver scheme stdout, file:, webhook:
Logging flags --log-level if added debug, info, warn, error

Scope

  1. Audit every --<flag> in cmd/ that takes a string with a closed set of valid values.
  2. Add cmd.Annotations["vers:enum:<flag>"] = "..." for each.
  3. Wire errorsx.EnumError(flagName, got, valid) (new helper) and use it on validation paths.
  4. Update the relevant flag's Long/Usage to mention the enum.
  5. Verify in agent-context output: jq '.commands.<name>.flags."--<flag>".enum' returns the array.

Out of scope

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions