Skip to content

Reconcile .surface snapshot with the post-#499 generator #539

Description

@jeremy

The committed .surface snapshot has drifted from what scripts/check-cli-surface.sh generates, and nothing in CI catches it: make check-surface generates to /tmp and validates the binary's output, but never compares against the committed file.

Root cause

#499 changed how the script derives ROOT_FLAGS — from a child command's inherited_flags instead of the root's .flags. Since --help --agent curates inherited flags down to the salient set (account, json, md, project, quiet — see salientRootFlags in internal/cli/help.go), the generated snapshot no longer lists non-salient root globals (--verbose, --jq, --agent, --cache-dir, …) on every command. The committed snapshot predates #499 and still carries them all.

Current delta

Regenerating at HEAD produces:

  • ~8,965 deletions — the stale non-salient root-flag records on all commands
  • 2 missing additions — records that landed without a snapshot update:
    • FLAG basecamp recordings --assignee type=string
    • FLAG basecamp recordings list --assignee type=string

Why it matters

check-skill-drift and check-smoke-coverage validate against the committed .surface, so the snapshot is load-bearing. Recent flag additions (e.g. #538's --notify-on-completion records) had to be hand-inserted to avoid burying an unrelated 9k-line regeneration in a bugfix PR.

Suggested resolution

  1. Decide whether the post-Fix --version over-propagation in check-cli-surface.sh #499 output (curated root flags only) is the intended snapshot shape. If root globals should still be tracked per-command, the script needs a non-curated source instead of inherited_flags.
  2. Regenerate .surface in a dedicated PR and reconcile .surface-skill-drift baselines if affected.
  3. Consider a CI check that the committed snapshot matches fresh generation, so this can't drift silently again.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions