Address panel review: diagnostic warning, fail-closed tests, stale docs

- Emit logger.warning when .github-private returns absent on a GitHub
  host -- signals a likely token-scope gap (GitHub returns 404, not 403,
  for private repos with insufficient scope).
- Add test_403_is_error_not_absent: proves 403 -> cache_miss_fetch_fail.
- Add test_github_private_auth_error_does_not_fall_through: proves auth
  error on .github-private stops the cascade (fail-closed).
- Add test_github_private_absent_falls_back_to_github: proves the
  backwards-compat cascade from .github-private to .github.
- Assert candidate name in test_github_com_error_fail_closed.
- Update 15+ stale .github references in governance-guide sections 11,
  12, 15, 16 and policy-reference quickstart checklist.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: Sergio Sisternes

docs/src/content/docs/enterprise/apm-policy.md

@@ -204,7 +204,7 @@ Commit and push. On the next `apm install` in any repo in the org, a user who de
 
 ### 2. Preview before you commit
 
-Point at a policy explicitly to test it before it lands in `.github-private`:
+Point at a policy explicitly to test it before it lands in your policy repo (`.github-private` or `.github`):
 
 ```bash
 apm policy status --policy-source ./apm-policy.yml

docs/src/content/docs/enterprise/governance-guide.md

@@ -393,7 +393,7 @@ graph TD
     style P4 fill:#fce4ec,stroke:#c2185b,stroke-width:3px,color:#000
 ```
 
-**Phase 1 -- ship a warn-mode policy.** Land `apm-policy.yml` in `<org>/.github` with `enforcement: warn`. Nothing breaks anywhere. Every `apm install` in the org now discovers the policy, runs the checks, and logs `[!]` warnings for violations -- but proceeds.
+**Phase 1 -- ship a warn-mode policy.** Land `apm-policy.yml` in `<org>/.github-private` (or `<org>/.github`) with `enforcement: warn`. Nothing breaks anywhere. Every `apm install` in the org now discovers the policy, runs the checks, and logs `[!]` warnings for violations -- but proceeds.
 
 **Phase 2 -- wire audit into CI.** Use a shared GitHub Actions template (or composite action) that runs `apm audit --ci --policy org -f sarif` and uploads the SARIF to GitHub Code Scanning. Violations become visible to repo owners as code-scanning alerts. Be honest with stakeholders here: in `warn` mode, audit rewrites violations to `passed=True` so the exit code stays 0. CI does not fail. The visibility is in the SARIF + Code Scanning UI, not in the green/red check. Branch protection cannot enforce yet.
 
@@ -423,9 +423,9 @@ For richer customization (matrix builds, monorepo splits, vendored policy paths)
 `apm audit --ci` in warn mode rewrites violations to `passed=True` (audit.py:589-598), so the audit command exits 0 even on policy violations. Visibility is in the SARIF upload + Code Scanning UI, not in branch-protection status. To gate merges on policy violations, you must run in `block` mode.
 :::
 
-**Phase 3 -- triage and clean up.** Repo owners either fix their `apm.yml` to comply with the policy, or they open a PR to `<org>/.github/apm-policy.yml` to add an explicit allow entry with rationale. The PR flow is the policy change-management trail (see section 12).
+**Phase 3 -- triage and clean up.** Repo owners either fix their `apm.yml` to comply with the policy, or they open a PR to the org policy repo (`<org>/.github-private/apm-policy.yml` or `<org>/.github/apm-policy.yml`) to add an explicit allow entry with rationale. The PR flow is the policy change-management trail (see section 12).
 
-**Phase 4 -- flip to block.** Once Code Scanning shows the violation backlog is drained, change `enforcement: block` in `<org>/.github/apm-policy.yml`. Stage by team if the org is large: a team can adopt block early by setting `enforcement: block` in its own team-level intermediate policy, leaving the org policy at `warn`. (Tighten-only merge means the team's `block` wins for repos under that team's `extends:` chain.) Use `apm policy status --check` in CI as a pre-flight that explains the effective policy and surfaces what would be blocked, before the gate phase actually blocks it.
+**Phase 4 -- flip to block.** Once Code Scanning shows the violation backlog is drained, change `enforcement: block` in the org policy repo. Stage by team if the org is large: a team can adopt block early by setting `enforcement: block` in its own team-level intermediate policy, leaving the org policy at `warn`. (Tighten-only merge means the team's `block` wins for repos under that team's `extends:` chain.) Use `apm policy status --check` in CI as a pre-flight that explains the effective policy and surfaces what would be blocked, before the gate phase actually blocks it.
 
 **Circuit-breaker rollout for large fleets.** For 100+ repos, do not flip block org-wide in one commit. Stage: enable `block` for 10% of repos for 1 week (via team-level extends), monitor SARIF alert volume and on-call pages, expand to 50% for 1 week, then 100%. If SARIF volume spikes or on-call escalations cluster, revert to `warn` at the org level (one commit) while you triage.
 
@@ -437,13 +437,13 @@ For step-by-step CI YAML and SARIF upload examples beyond the snippet above, see
 
 The org policy file is the trust root. Protecting it is on you, not on APM.
 
-- **CODEOWNERS on `<org>/.github/apm-policy.yml`** -- restrict to a security team. Every change requires their review.
-- **Branch protection on `<org>/.github` main** -- required reviewers, no force push, no direct push to main, dismiss stale approvals on new commits.
-- **GitHub Ruleset on the org `.github` repo** (recommended) -- requires approval from a specific team for any change to policy files. See [GitHub Rulesets](../integrations/github-rulesets/).
+- **CODEOWNERS on `<org>/.github-private/apm-policy.yml`** (or `<org>/.github/apm-policy.yml`) -- restrict to a security team. Every change requires their review.
+- **Branch protection on `<org>/.github-private` main** (or `<org>/.github`) -- required reviewers, no force push, no direct push to main, dismiss stale approvals on new commits.
+- **GitHub Ruleset on the org `.github-private` repo** (recommended) -- requires approval from a specific team for any change to policy files. See [GitHub Rulesets](../integrations/github-rulesets/).
 - **Change history is `git log apm-policy.yml`.** Rationale lives in commit messages and PR descriptions. Make commit-message rationale a CODEOWNERS-checked review item.
 - **Policy change cooling period** (recommended) -- every change to `apm-policy.yml` requires a PR with rationale and a 24-72 hour waiting period before merge. This is a process control, not a code control, but it is the single most important thing you can add.
 
-**Separation of duties for SOX / SOD-sensitive environments.** CODEOWNERS for `apm-policy.yml` should require approvals from a team distinct from the team authoring the change. Configure GitHub Rulesets on the `<org>/.github` repo to require reviewers from `@org/policy-approvers`, where that team is disjoint from `@org/policy-authors`. The same author cannot self-approve, and the approval team has no commit rights to the policy file directly.
+**Separation of duties for SOX / SOD-sensitive environments.** CODEOWNERS for `apm-policy.yml` should require approvals from a team distinct from the team authoring the change. Configure GitHub Rulesets on the `<org>/.github-private` (or `<org>/.github`) repo to require reviewers from `@org/policy-approvers`, where that team is disjoint from `@org/policy-authors`. The same author cannot self-approve, and the approval team has no commit rights to the policy file directly.
 
 **Lint for bypass flags in CI workflows.** Add a pre-merge check that fails any PR introducing a policy-bypass flag without an explicit security review label:
 
@@ -541,7 +541,7 @@ graph TD
     style HubYaml fill:#fce4ec,stroke:#c2185b,stroke-width:1px,color:#000
 ```
 
-**Minimal policy (1-10 repos)** -- one file at `<org>/.github/apm-policy.yml`:
+**Minimal policy (1-10 repos)** -- one file at `<org>/.github-private/apm-policy.yml` (or `<org>/.github/apm-policy.yml`):
 
 ```yaml
 name: "Starter policy"
@@ -577,14 +577,14 @@ compilation:
 **Hub + org + repo (100+ repos)** -- enterprise hub with broad allows, org extending and tightening, repos pinning the hash:
 
 ```yaml
-# enterprise-hub-org/.github/apm-policy.yml
+# enterprise-hub-org/.github-private/apm-policy.yml
 name: "Enterprise baseline"
 version: "1.0.0"
 enforcement: warn
 dependencies:
   allow: ["microsoft/*", "contoso/*", "partner-corp/*"]
 
-# contoso/.github/apm-policy.yml
+# contoso/.github-private/apm-policy.yml
 extends: "enterprise-hub-org"
 enforcement: block
 dependencies:
@@ -601,7 +601,7 @@ policy:
 ## 16. Where to next
 
 :::tip[Starting a pilot?]
-**15-minute path:** copy `templates/apm-policy-starter.yml` to `<your-org>/.github/apm-policy.yml`, wire the CI YAML from section 11 Phase 2, ship in warn mode. Flip to block once SARIF is clean.
+**15-minute path:** copy `templates/apm-policy-starter.yml` to `<your-org>/.github-private/apm-policy.yml` (or `<your-org>/.github/apm-policy.yml`), wire the CI YAML from section 11 Phase 2, ship in warn mode. Flip to block once SARIF is clean.
 :::
 
 - [`apm-policy.yml`](./apm-policy/) -- the file's mental model.

docs/src/content/docs/enterprise/policy-reference.md

@@ -943,7 +943,7 @@ All violation messages above flow through `InstallLogger.policy_violation`; unde
 
 Checklist to publish a policy:
 
-1. Create `<org>/.github/apm-policy.yml` in the org's `.github` repository.
+1. Create `<org>/.github-private/apm-policy.yml` (or `<org>/.github/apm-policy.yml`) in the org's policy repository.
 2. Start from the [Standard org policy](#standard-org-policy) example above and trim it to the minimum that reflects your governance posture.
 3. Set `enforcement: warn` first. Let CI surface diagnostics across consuming repos for one cycle without breaking installs.
 4. When the warn-cycle is clean, switch to `enforcement: block`. Communicate the change in your org's CHANGELOG/announcements channel — `apm install` will start failing for any non-compliant repo.

src/apm_cli/policy/discovery.py

@@ -700,6 +700,17 @@ def _auto_discover(
                 candidate_repo,
                 host,
             )
+            # Warn when .github-private is absent on a GitHub host -- GitHub
+            # returns 404 (not 403) when the token lacks private-repo scope,
+            # so an absent result may mask a token-permission problem.
+            if candidate_repo == ".github-private" and _is_github_host(host):
+                logger.warning(
+                    "Policy repo %s/%s not found (or token lacks private-repo "
+                    "read scope). If your org publishes policy in .github-private, "
+                    "ensure the token has Contents:read permission on that repo.",
+                    org,
+                    candidate_repo,
+                )
             continue
 
         # Any other outcome (found, error, malformed, etc.) -> return immediately

tests/unit/policy/test_discovery.py

@@ -749,9 +749,62 @@ def test_github_com_error_fail_closed(self, mock_extract, mock_fetch):
             result = _auto_discover(Path(tmpdir), no_cache=True)
             # Only one call -- error stops the cascade
             self.assertEqual(mock_fetch.call_count, 1)
+            self.assertEqual(mock_fetch.call_args_list[0][0][0], "contoso/.github-private")
             self.assertFalse(result.found)
             self.assertIn("401", result.error)
 
+    @patch("apm_cli.policy.discovery._fetch_from_repo")
+    @patch("apm_cli.policy.discovery._extract_org_from_git_remote")
+    def test_403_is_error_not_absent(self, mock_extract, mock_fetch):
+        """HTTP 403 -> fail-closed (cache_miss_fetch_fail), not absent."""
+        mock_extract.return_value = ("contoso", "github.com")
+        mock_fetch.return_value = PolicyFetchResult(
+            error="403: Access denied to contoso/.github-private",
+            outcome="cache_miss_fetch_fail",
+        )
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = _auto_discover(Path(tmpdir), no_cache=True)
+            self.assertEqual(mock_fetch.call_count, 1)
+            self.assertEqual(result.outcome, "cache_miss_fetch_fail")
+            self.assertNotEqual(result.outcome, "absent")
+            self.assertFalse(result.found)
+
+    @patch("apm_cli.policy.discovery._fetch_from_repo")
+    @patch("apm_cli.policy.discovery._extract_org_from_git_remote")
+    def test_github_private_auth_error_does_not_fall_through(self, mock_extract, mock_fetch):
+        """.github-private auth error -> fail-closed, .github NOT tried."""
+        mock_extract.return_value = ("contoso", "github.com")
+        mock_fetch.side_effect = [
+            PolicyFetchResult(error="403: Access denied", outcome="cache_miss_fetch_fail"),
+            PolicyFetchResult(policy=ApmPolicy(), outcome="found"),
+        ]
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = _auto_discover(Path(tmpdir), no_cache=True)
+            # Only .github-private tried -- error stops cascade
+            self.assertEqual(mock_fetch.call_count, 1)
+            self.assertFalse(result.found)
+
+    @patch("apm_cli.policy.discovery._fetch_from_repo")
+    @patch("apm_cli.policy.discovery._extract_org_from_git_remote")
+    def test_github_private_absent_falls_back_to_github(self, mock_extract, mock_fetch):
+        """.github-private absent (404) -> cascade to .github."""
+        mock_extract.return_value = ("contoso", "github.com")
+        mock_fetch.side_effect = [
+            PolicyFetchResult(outcome="absent"),  # .github-private 404
+            PolicyFetchResult(
+                policy=ApmPolicy(), source="org:contoso/.github", outcome="found"
+            ),  # .github found
+        ]
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = _auto_discover(Path(tmpdir), no_cache=True)
+            self.assertEqual(mock_fetch.call_count, 2)
+            self.assertEqual(mock_fetch.call_args_list[0][0][0], "contoso/.github-private")
+            self.assertEqual(mock_fetch.call_args_list[1][0][0], "contoso/.github")
+            self.assertTrue(result.found)
+
     @patch("apm_cli.policy.discovery._fetch_from_repo")
     @patch("apm_cli.policy.discovery._extract_org_from_git_remote")
     def test_ghe_repo_ref_includes_host(self, mock_extract, mock_fetch):