[BUG] Policy source format documented inconsistently across CLI help and docs

[edenfunf]

Describe the bug

The "policy source" format (the value passed to --policy / --policy-source) is documented inconsistently across at least four locations: two Click help texts in source code, and two sections of the CLI reference docs. The actual parser accepts the same set of forms in all entry points, so this is purely a documentation/help-text drift, not a user-facing surface divergence -- but the drift means users reading any single doc page get an incomplete or differently-worded list.

Discovered while investigating #994, where a broken cross-reference (Same shape as 'apm install --policy') is the surface symptom. The cross-reference cannot reliably stay correct while the underlying documented format itself drifts.

Evidence: drift across four locations

#	Location	Forms listed
1	src/apm_cli/commands/policy.py:288 (Click help for policy status --policy-source)	'org', local file path, owner/repo, https URL
2	src/apm_cli/commands/audit.py:440 (Click help for audit --policy)	'org' (auto-discover), file path, URL
3	docs/src/content/docs/reference/cli-commands.md:435 (audit --policy reference)	'org' (auto-discover from org), file path, URL
4	docs/src/content/docs/reference/cli-commands.md:523 (policy status --policy-source reference)	'org', file path, URL

Concrete consequence: owner/repo is listed in location 1 only. Locations 2-4 omit it. Users reading docs cannot discover that apm policy status --policy-source contoso/.github is valid input.

Verified locally: parser accepts owner/repo, both commands route through it

1. The parser in src/apm_cli/policy/discovery.py accepts owner/repo shorthand. An existing unit test pins this, and it passes on current main (2023e8c):

   $ pytest tests/unit/policy/test_discovery.py::TestDiscoverPolicy::test_override_owner_repo -v
   apm\tests\unit\policy\test_discovery.py::TestDiscoverPolicy::test_override_owner_repo PASSED [100%]
   ============================== 1 passed in 1.90s ==============================
   

   Test source:

   # tests/unit/policy/test_discovery.py:524-535
   def test_override_owner_repo(self, mock_fetch):
       mock_fetch.return_value = (VALID_POLICY_YAML, None)
       with tempfile.TemporaryDirectory() as tmpdir:
           result = discover_policy(
               Path(tmpdir),
               policy_override="contoso/.github",
               no_cache=True,
           )
           self.assertTrue(result.found)
           self.assertIn("org:", result.source)

2. Both commands route their --policy / --policy-source value through the same discover_policy() function:

   • audit.py:534-536: discover_policy(project_root, policy_override=policy_source, no_cache=no_cache)
   • policy status similarly forwards to discover_policy (covered by tests/unit/commands/test_policy_status.py:303)

   So audit --policy contoso/.github and policy status --policy-source contoso/.github both succeed at the parser level. Only the help texts and docs claim otherwise.

Expected behavior

A single canonical list of accepted "policy source" forms, reflected identically in:

• The --policy Click help on apm audit
• The --policy-source Click help on apm policy status
• The apm audit section of docs/src/content/docs/reference/cli-commands.md
• The apm policy status section of the same docs file
• (Possibly) docs/src/content/docs/enterprise/policy-reference.md, where the format is also referenced

A regression test that pins the parser's accepted set so future drift fails CI rather than silently re-introducing the inconsistency.

Suggested approach

1. Read src/apm_cli/policy/discovery.py end-to-end and enumerate the forms the parser actually accepts (the canonical set; test_override_owner_repo and siblings already cover most cases).
2. Update the four (or five) locations to a single canonical wording.
3. Extend the parser unit tests to lock the accepted set, so drift reappears as a test failure.

Relation to #994

#994 reports a broken cross-reference (Same shape as 'apm install --policy') and proposes redirecting it to apm audit --policy. The minimal fix for #994 will remove the broken cross-reference outright. This issue tracks the underlying drift that made the cross-reference unreliable in the first place. Per CONTRIBUTING.md ("only one concern per PR"), the two are addressed in separate PRs.

Environment

• APM version: 0.10.0 (latest main, post-2023e8c)
• OS: N/A (documentation / help-text drift, not platform-specific)

[github-actions]

Triage decision

accept

Proposed labels

area/cli
area/docs-site
type/docs
status/accepted
priority/low
good first issue

Milestone

0.10.1

Suggested next action

Update the four documented locations (two Click help strings + two cli-commands.md sections) to a single canonical wording that lists all accepted policy source forms, then add a regression test that locks the parser's accepted set so future drift fails CI.

Suggested issue comment

Thanks for the thorough investigation, @edenfunf -- the table showing
drift across four locations and the passing test output make this
immediately actionable.

You are correct: `discover_policy()` accepts `owner/repo` shorthand,
both `apm audit --policy` and `apm policy status --policy-source` route
through it, and the existing unit test (`test_override_owner_repo`) pins
that behaviour. The drift is purely documentation/help-text, not a code
bug.

The fix involves three files:

1. `src/apm_cli/commands/audit.py` -- update the `--policy` Click help
   string to add `owner/repo` to the listed forms.
2. `src/apm_cli/commands/policy.py` -- same for `--policy-source` Click
   help.
3. `docs/src/content/docs/reference/cli-commands.md` -- align the two
   sections (audit around line 435, policy status around line 523) with
   the canonical set.
4. Optionally `docs/src/content/docs/enterprise/policy-reference.md` if
   the format is also described there.
5. A regression test (or extension of an existing test) that asserts the
   canonical set of accepted forms -- so drift re-appears as a test
   failure rather than silent drift.

Per CONTRIBUTING.md this should land in its own PR, separate from #994.
The APM CLI reference doc rule (Rule 4) requires that the implementing
PR updates `cli-commands.md` in the same commit as the source change.

This is marked `good first issue` because all the investigation is done
-- the fix is mechanical synchronization. If you would like to submit a
PR, feel free to claim it!

See the CLI reference for the authoritative command surface:
https://github.com/microsoft/apm/blob/main/docs/src/content/docs/reference/cli-commands.md

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Clear discoverability failure: owner/repo is valid at the parser level and pinned by a passing unit test, but listed in only 1 of 4 documented locations. A user reading apm audit --help or the CLI reference cannot discover that apm audit --policy contoso/.github is valid input. Fails the discoverability test directly. The issue is correctly scoped -- 4 locations enumerated, fix involves 2 Python files and 1 markdown file. The regression-test request is appropriate: without it, the accepted-forms set has no CI gate and will drift again. Maps to an existing APM capability (enterprise policy enforcement); no new surface is proposed.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. The parser already accepts owner/repo shorthand; documenting it more visibly does not change the code path, token scope, or security profile. The fix does not touch discover_policy() logic, lockfile handling, path guards, or auth flows. No theme/security or theme/governance label is warranted. The policy enforcement surface (area/audit-policy) is touched conceptually but the issue proposes no behaviour change -- keeping the label set to area/cli and area/docs-site is correct.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a CONTRIBUTOR (not FIRST_TIME_CONTRIBUTOR or NONE) with a thorough, expert-level report that includes code references, test output, and a structured comparison table; no warmth-tuning adjustment is needed.

Python Architect -- Architecture Reviewer

Not activated -- the fix is purely documentation and help-text synchronization with an already-correct parser; there is no cross-cutting design decision, interface change, schema migration, or new primitive involved. No status/needs-design warranted.

Doc Writer -- Documentation Reviewer

Activated: issue explicitly proposes updating docs/src/content/docs/reference/cli-commands.md (two sections) and mentions policy-reference.md as a possible fifth location. area/docs-site is added as a secondary area label so the implementing PR is reminded that docs are in scope. The issue's vocabulary ("policy source", --policy, --policy-source) matches the canonical terminology used in the enterprise governance docs and CLI reference. Suggested comment wording is clear and grounded in APM's user vocabulary. The rule from the DevX persona is directly applicable: "If a CLI change is not reflected in cli-commands.md in the same PR, that change is incomplete by definition."

APM CEO -- Triage Arbiter

Decision: accept. This is a zero-ambiguity docs bug: investigation is complete, the code is correct, and the fix is mechanical. Omitting mega-theme is correct -- only area/cli and area/docs-site apply (pure infra per the label-construction rules). good first issue is warranted because all the detective work is done and the fix is bounded. Milestone 0.10.1 (current patch, 43 open issues). priority/low is appropriate -- no user-facing behaviour regression, but the omission does block enterprise users from discovering a valid policy source form. Separation from #994 (broken cross-reference) is correct per CONTRIBUTING.md.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": ["good first issue"],
  "milestone": "0.10.1",
  "next_action": "Update the four documented locations (two Click help strings + two cli-commands.md sections) to a single canonical wording that lists all accepted policy source forms, then add a regression test that locks the parser accepted set so future drift fails CI.",
  "comment_markdown": "Thanks for the thorough investigation, @edenfunf -- the table showing drift across four locations and the passing test output make this immediately actionable.\n\nYou are correct: `discover_policy()` accepts `owner/repo` shorthand, both `apm audit --policy` and `apm policy status --policy-source` route through it, and the existing unit test (`test_override_owner_repo`) pins that behaviour. The drift is purely documentation/help-text, not a code bug.\n\nThe fix involves three files:\n\n1. `src/apm_cli/commands/audit.py` -- update the `--policy` Click help string to add `owner/repo` to the listed forms.\n2. `src/apm_cli/commands/policy.py` -- same for `--policy-source` Click help.\n3. `docs/src/content/docs/reference/cli-commands.md` -- align the two sections (audit around line 435, policy status around line 523) with the canonical set.\n4. Optionally `docs/src/content/docs/enterprise/policy-reference.md` if the format is also described there.\n5. A regression test (or extension of an existing test) that asserts the canonical set of accepted forms.\n\nPer CONTRIBUTING.md this should land in its own PR, separate from #994. This is marked `good first issue` because all the investigation is done -- the fix is mechanical synchronization. If you would like to submit a PR, feel free to claim it!"
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel for issue #998 · ● 675K · ◷