audit_discovery_completeness

Overview ¶

Command audit_discovery_completeness reports discovery-metadata gaps that affect how well models can find and choose the right action. It extends the existing R-META auditor (cmd/audit_metadata_completeness) with two new dimensions:

• Check B — Field-level: empty_param_description (input-schema property descriptions that are blank or boilerplate) and empty_output_description (lower priority).

• Check C — Sibling-cluster / confusable-action: cluster actions by (owner_package, base_action_stem) stripping variant suffixes (_batch/_bulk/_all/_directory/_single) and CRUD verbs. Flag any cluster member that lacks both a sibling in RelatedActions (or a CommonConfusions entry naming a sibling) AND a Usage string that mentions a distinguishing signal. This is the link_create_batch / publish vs publish_directory class of gap that motivated the discovery program.

Check A — Action-level (weak_aliases, generic_usage, empty_related, weak_individual_description) reuses the R-META logic. missing_next_steps is a Phase 0 stub (see TODO) — Phase 1 will wire it to the markdown formatter registry via an exported HasRegisteredMarkdownFormatter helper.

missing_parameter_guidance is a field-level check of its own: an action whose ParameterGuidance is no richer than the scope defaults internal/tools fills into every spec, while it requires an identifier those defaults do not cover (topic_id, hook_id, agent_id, merge_request_iid). Asking instead whether a spec carries any guidance at all, which is what this asked until 3.1.0, could never fire, because that central fill runs first and covers exactly the parameter names the old question looked for.

Output JSON shape (plan/discovery-backlog.json):

{
  "schema_version": 1,
  "summary": {...},                  // global counts
  "clusters": [{"package", "stem", "members"}],
  "packages": [{"package", "actions", "findings"}]
}

Flags:

-output PATH        path to write JSON (default "-" stdout)
-gaps-only          omit actions without any finding
-min-aliases N      threshold for weak_aliases (default 3)
-severity LEVEL     error|warning|info for -check threshold (default error)
-check              exit non-zero if any finding meets/exceeds -severity

Usage:

go run ./cmd/audit_discovery_completeness/                 # full report to stdout
go run ./cmd/audit_discovery_completeness/ -gaps-only      # only findings
go run ./cmd/audit_discovery_completeness/ -check          # CI gate