Skip to content

Envelope errors[].category isn't the coarse category the docs promise #699

Closed

Description

@goosewobbler

Problem

docs/cli.md says each envelope error carries "a coarse category", and its table lists one category per exit family (general, config, input, template, llm, github, git, version, publish). But categoryForCode (packages/core/src/envelope.ts ~87) derives the category from the specific code:

code category emitted
PIPELINE_STAGE_ERROR pipeline-stage
INVALID_CONFIG invalid-config
TAG_ALREADY_EXISTS tag-already-exists
CARGO_LOCK_SYNC_ERROR (#674) cargo-lock-sync

So category is just the code reformatted, not a coarse grouping. An agent that branches on category gets an open-ended set of values instead of the nine documented ones. This has been visible since #651, when release/standing-pr started reporting stage codes, and #616 (enveloping version/publish) adds more.

Found during the #616 review (round 3), verified with the built CLIs.

Options

  1. Make it coarse: derive category from the code's exit family. feat(cli)!: envelope the version and publish commands, unwrap on the pipe #616 adds CODE_TO_EXIT, a complete code → family table, which is the natural source. A changed category value is a contract change for consumers, so decide whether it needs a schemaVersion bump or a release-notes callout.
  2. Make the docs match: say category is a slug of the code, and point readers at the exit code for the family.

Option 1 matches what the contract was meant to give agents.

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

    type:bugSomething isn't working

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions