code-mower 0.9.0b1__tar.gz → 0.9.1b1__tar.gz

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-mower
-Version: 0.9.0b1
+Version: 0.9.1b1
 Summary: Multi-reviewer AI code audit orchestration
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
@@ -95,12 +95,17 @@ wrappers, run `code-mower migration setup-drift --repo-path .` before copying a
 fresh `.code-mower.generated` tree. It is read-only and reports path-level
 classifications (`same`, `differs`, `new`, `repo-only`,
 `missing-from-output`) without file contents or diffs.
+Use [Upgrade An Existing Repository](docs/upgrade-existing-repo.md) for the
+reviewed PR flow, repo-only file handling, builder identity checks, and
+wrapper/pin drift checks.
 
 After `init` and `doctor`, use `code-mower lanes status --repo OWNER/REPO` to
 see active builder/reviewer lanes, gate/check state, recent Code Mower
 workflows, local board/process hints when present, and the next operator
 action. Text and JSON output redact local cwd paths by default; use
-`--show-local-paths` only for local debugging.
+`--show-local-paths` only for local debugging. Local Board discovery is
+best-effort across common macOS and Linux listener tools; when a host restricts
+listener inventory, remote PR/check status still reports normally.
 
 For the same redacted metadata in a local browser view, run
 `code-mower board serve --repo OWNER/REPO` and open the printed localhost URL.
@@ -164,10 +169,12 @@ after reinstalling, especially when switching between pipx and uv.
 | C. Builder experiment | You want to compare authoring loops before trusting them broadly. | Use a work order or experiment spec, run `code-mower builder-experiment run` around an explicit command, then review the source-free `authoringRun` artifact and normal audit evidence. | [Builder Experiments](docs/builder-experiments.md) |
 
 The current package-index announcement entry point is the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.0-beta.1/docs/try-in-10-minutes.md)
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.1-beta.1/docs/try-in-10-minutes.md)
 guide. The v0.9 beta includes the completed native Board work plus the adoption
-and upgrade hardening from recent install rehearsals, so package-only users can
-start from the public package rather than a source checkout.
+and upgrade hardening from recent install rehearsals; v0.9.1 adds a smaller
+announcement-hardening pass on Board visibility, doctor guidance, and safer
+setup docs. Package-only users can start from the public package rather than a
+source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -190,13 +197,15 @@ review-request signals to propose known-clean and known-blocked cases. Review
 every disposition before using it for lane promotion or merge policy.
 
 Full walkthrough: [docs/try-in-10-minutes.md](docs/try-in-10-minutes.md).
+Existing-repo upgrade flow:
+[docs/upgrade-existing-repo.md](docs/upgrade-existing-repo.md).
 First-time command map: [docs/launch-command-surface.md](docs/launch-command-surface.md).
 Provider-contract baseline for the next release train:
 [docs/v06-truth-baseline.md](docs/v06-truth-baseline.md).
 
 For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the package-index procedure for `v0.9.0-beta.1` / `code-mower==0.9.0b1`. The
+the package-index procedure for `v0.9.1-beta.1` / `code-mower==0.9.1b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -382,8 +391,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.9.0-beta.1`, with pinned package
-install spec `code-mower==0.9.0b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.1-beta.1`, with pinned package
+install spec `code-mower==0.9.1b1`. Release evidence is recorded on the GitHub
 release and in the first-user install rehearsal. The public repository is
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), and
 GitHub releases remain the auditable source for tags, build artifacts, and
@@ -424,6 +433,7 @@ first so local work exercises the same package entrypoint users install.
 ## Docs Map
 
 - [Install And Bootstrap](docs/install.md)
+- [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md)
 - [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md)
 - [Quickstart Reference](docs/quickstart.md)

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/README.md

@@ -78,12 +78,17 @@ wrappers, run `code-mower migration setup-drift --repo-path .` before copying a
 fresh `.code-mower.generated` tree. It is read-only and reports path-level
 classifications (`same`, `differs`, `new`, `repo-only`,
 `missing-from-output`) without file contents or diffs.
+Use [Upgrade An Existing Repository](docs/upgrade-existing-repo.md) for the
+reviewed PR flow, repo-only file handling, builder identity checks, and
+wrapper/pin drift checks.
 
 After `init` and `doctor`, use `code-mower lanes status --repo OWNER/REPO` to
 see active builder/reviewer lanes, gate/check state, recent Code Mower
 workflows, local board/process hints when present, and the next operator
 action. Text and JSON output redact local cwd paths by default; use
-`--show-local-paths` only for local debugging.
+`--show-local-paths` only for local debugging. Local Board discovery is
+best-effort across common macOS and Linux listener tools; when a host restricts
+listener inventory, remote PR/check status still reports normally.
 
 For the same redacted metadata in a local browser view, run
 `code-mower board serve --repo OWNER/REPO` and open the printed localhost URL.
@@ -147,10 +152,12 @@ after reinstalling, especially when switching between pipx and uv.
 | C. Builder experiment | You want to compare authoring loops before trusting them broadly. | Use a work order or experiment spec, run `code-mower builder-experiment run` around an explicit command, then review the source-free `authoringRun` artifact and normal audit evidence. | [Builder Experiments](docs/builder-experiments.md) |
 
 The current package-index announcement entry point is the tagged
-[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.0-beta.1/docs/try-in-10-minutes.md)
+[Try Code Mower In 10 Minutes](https://github.com/codemower-ai/code-mower/blob/v0.9.1-beta.1/docs/try-in-10-minutes.md)
 guide. The v0.9 beta includes the completed native Board work plus the adoption
-and upgrade hardening from recent install rehearsals, so package-only users can
-start from the public package rather than a source checkout.
+and upgrade hardening from recent install rehearsals; v0.9.1 adds a smaller
+announcement-hardening pass on Board visibility, doctor guidance, and safer
+setup docs. Package-only users can start from the public package rather than a
+source checkout.
 
 ## What Calibration Does And Does Not Prove
 
@@ -173,13 +180,15 @@ review-request signals to propose known-clean and known-blocked cases. Review
 every disposition before using it for lane promotion or merge policy.
 
 Full walkthrough: [docs/try-in-10-minutes.md](docs/try-in-10-minutes.md).
+Existing-repo upgrade flow:
+[docs/upgrade-existing-repo.md](docs/upgrade-existing-repo.md).
 First-time command map: [docs/launch-command-surface.md](docs/launch-command-surface.md).
 Provider-contract baseline for the next release train:
 [docs/v06-truth-baseline.md](docs/v06-truth-baseline.md).
 
 For release verification,
 [First-User Install Rehearsal](docs/first-user-install-rehearsal.md) records
-the package-index procedure for `v0.9.0-beta.1` / `code-mower==0.9.0b1`. The
+the package-index procedure for `v0.9.1-beta.1` / `code-mower==0.9.1b1`. The
 GitHub release records the workflow and rehearsal evidence for the exact tag.
 
 ## Optional: Plan Before Coding
@@ -365,8 +374,8 @@ measurement work.
 
 ## Installation Status
 
-The current package-index beta baseline is `v0.9.0-beta.1`, with pinned package
-install spec `code-mower==0.9.0b1`. Release evidence is recorded on the GitHub
+The current package-index beta baseline is `v0.9.1-beta.1`, with pinned package
+install spec `code-mower==0.9.1b1`. Release evidence is recorded on the GitHub
 release and in the first-user install rehearsal. The public repository is
 [codemower-ai/code-mower](https://github.com/codemower-ai/code-mower), and
 GitHub releases remain the auditable source for tags, build artifacts, and
@@ -407,6 +416,7 @@ first so local work exercises the same package entrypoint users install.
 ## Docs Map
 
 - [Install And Bootstrap](docs/install.md)
+- [Upgrade An Existing Repository](docs/upgrade-existing-repo.md)
 - [Try Code Mower In 10 Minutes](docs/try-in-10-minutes.md)
 - [Build Loop In 30 Minutes](docs/build-loop-in-30-minutes.md)
 - [Quickstart Reference](docs/quickstart.md)

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-mower"
-version = "0.9.0b1"
+version = "0.9.1b1"
 description = "Multi-reviewer AI code audit orchestration"
 requires-python = ">=3.12"
 readme = "README.md"

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/src/code_mower/__init__.py

@@ -1,3 +1,3 @@
 """Code Mower package."""
 
-__version__ = "0.9.0b1"
+__version__ = "0.9.1b1"

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/src/code_mower/board.py

@@ -655,6 +655,14 @@ def render_board_html(config: BoardConfig) -> str:
     const stateClass = (value) => /fail|error|blocked/i.test(text(value)) ? "bad" : /warn|pending|waiting|queued|progress/i.test(text(value)) ? "warn" : "ok";
     const seconds = (value) => Number.isFinite(Number(value)) ? `${{Number(value).toFixed(1)}}s` : "n/a";
     const money = (value) => Number.isFinite(Number(value)) ? `$${{Number(value).toFixed(3)}}` : "n/a";
+    const localTime = (value) => {{
+      const raw = text(value);
+      if (!raw) return "";
+      const date = new Date(raw);
+      if (Number.isNaN(date.getTime())) return esc(raw);
+      const local = new Intl.DateTimeFormat(undefined, {{year:"numeric", month:"short", day:"numeric", hour:"numeric", minute:"2-digit", second:"2-digit", timeZoneName:"short"}}).format(date);
+      return `<time datetime="${{esc(raw)}}" title="UTC ${{esc(raw)}}">${{esc(local)}}</time>`;
+    }};
     function labels(groups) {{
       return Object.values(groups || {{}}).flat().map(pill).join(" ") || '<span class="muted">none</span>';
     }}
@@ -663,7 +671,7 @@ def render_board_html(config: BoardConfig) -> str:
     }}
     function render(data) {{
       document.getElementById("repo").textContent = REPO;
-      document.getElementById("generated").textContent = `Generated ${{data.generated_at || ""}}`;
+      document.getElementById("generated").innerHTML = data.generated_at ? `Generated ${{localTime(data.generated_at)}}` : "Loading...";
       const prs = data.remote?.pull_requests || [];
       const runs = data.remote?.workflow_runs || [];
       const alerts = data.remote?.gate_health?.alerts || [];
@@ -681,18 +689,18 @@ def render_board_html(config: BoardConfig) -> str:
         `<div class="metric"><span class="muted">Agent cards</span><b>${{agentCards.length}}</b></div>`,
         `<div class="metric"><span class="muted">Gate alerts</span><b class="${{alerts.length ? "warn" : "ok"}}">${{alerts.length}}</b></div>`
       ].join(""));
-      put("owner", ownerQueue.length ? ownerQueue.map(item => `<div class="row"><div class="line"><a href="${{esc(href(item.url))}}">#${{esc(item.pr_number)}} ${{esc(item.kind)}}</a>${{pill(item.next_action)}}${{pill(item.head_sha_prefix)}}</div><div class="muted">${{esc(item.branch)}} by ${{esc(item.author)}} updated ${{esc(item.updated_at)}}</div></div>`).join("") : empty(data.owner_queue?.message || "No owner queue items."));
-      put("agents", agentCards.length ? agentCards.map(agent => `<div class="row"><div class="line"><b>${{esc(agent.provider)}}</b>${{pill(agent.role)}}${{pill(agent.status)}}${{agent.lane ? pill(agent.lane) : ""}}${{agent.pr_number ? pill(`#${{agent.pr_number}}`) : ""}}</div><div>${{esc(agent.title || agent.next_action || "local agent")}}</div><div class="muted">${{esc(agent.branch || agent.repo || "")}}${{agent.pid ? ` pid=${{esc(agent.pid)}}` : ""}}${{agent.cwd ? ` cwd=${{esc(agent.cwd)}}` : ""}}${{agent.updated_at ? ` updated ${{esc(agent.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.agent_adapters?.message || "No local agent adapter cards."));
+      put("owner", ownerQueue.length ? ownerQueue.map(item => `<div class="row"><div class="line"><a href="${{esc(href(item.url))}}">#${{esc(item.pr_number)}} ${{esc(item.kind)}}</a>${{pill(item.next_action)}}${{pill(item.head_sha_prefix)}}</div><div class="muted">${{esc(item.branch)}} by ${{esc(item.author)}}${{item.updated_at ? ` updated ${{localTime(item.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.owner_queue?.message || "No owner queue items."));
+      put("agents", agentCards.length ? agentCards.map(agent => `<div class="row"><div class="line"><b>${{esc(agent.provider)}}</b>${{pill(agent.role)}}${{pill(agent.status)}}${{agent.lane ? pill(agent.lane) : ""}}${{agent.pr_number ? pill(`#${{agent.pr_number}}`) : ""}}</div><div>${{esc(agent.title || agent.next_action || "local agent")}}</div><div class="muted">${{esc(agent.branch || agent.repo || "")}}${{agent.pid ? ` pid=${{esc(agent.pid)}}` : ""}}${{agent.cwd ? ` cwd=${{esc(agent.cwd)}}` : ""}}${{agent.updated_at ? ` updated ${{localTime(agent.updated_at)}}` : ""}}</div></div>`).join("") : empty(data.agent_adapters?.message || "No local agent adapter cards."));
       put("prs", prs.length ? prs.map(pr => `<div class="row">
         <div class="line"><a href="${{esc(href(pr.url))}}">#${{esc(pr.number)}} ${{esc(pr.title)}}</a>${{pill(pr.merge_state)}}${{pr.is_draft ? pill("draft") : ""}}${{pr.stale ? pill("stale") : ""}}</div>
-        <div class="muted">${{esc(pr.branch)}} by ${{esc(pr.author)}} updated ${{esc(pr.updated_at)}}</div>
+        <div class="muted">${{esc(pr.branch)}} by ${{esc(pr.author)}}${{pr.updated_at ? ` updated ${{localTime(pr.updated_at)}}` : ""}}</div>
         <div>labels: ${{labels(pr.labels)}}</div>
         <div>checks: ${{checks(pr.checks)}}</div>
         <div>next: <b>${{esc(pr.next_action)}}</b></div>
       </div>`).join("") : empty("No open pull requests."));
       put("alerts", alerts.length ? alerts.map(a => `<div class="row"><b class="warn">${{esc(a.kind)}}</b> ${{esc(a.message)}}</div>`).join("") : empty("No gate alerts."));
-      put("runs", runs.length ? runs.slice(0, 8).map(run => `<div class="row"><div class="line"><a href="${{esc(href(run.url))}}">${{esc(run.workflow || "workflow")}}</a>${{pill(run.conclusion || run.status || "unknown")}}</div><div class="muted">${{esc(run.branch)}} updated ${{esc(run.updated_at)}}</div></div>`).join("") : empty("No recent Code Mower workflow runs."));
-      put("verdicts", verdicts.length ? verdicts.map(v => `<div class="row"><div class="line"><a href="${{esc(href(v.url))}}">#${{esc(v.pr_number)}} ${{esc(v.lane)}}</a>${{pill(v.verdict)}}${{pill(v.head_sha_prefix)}}</div><div class="muted">${{esc(v.created_at)}}</div></div>`).join("") : empty(timelines.verdicts?.message || "No local reviewer verdict history yet."));
+      put("runs", runs.length ? runs.slice(0, 8).map(run => `<div class="row"><div class="line"><a href="${{esc(href(run.url))}}">${{esc(run.workflow || "workflow")}}</a>${{pill(run.conclusion || run.status || "unknown")}}</div><div class="muted">${{esc(run.branch)}}${{run.updated_at ? ` updated ${{localTime(run.updated_at)}}` : ""}}</div></div>`).join("") : empty("No recent Code Mower workflow runs."));
+      put("verdicts", verdicts.length ? verdicts.map(v => `<div class="row"><div class="line"><a href="${{esc(href(v.url))}}">#${{esc(v.pr_number)}} ${{esc(v.lane)}}</a>${{pill(v.verdict)}}${{pill(v.head_sha_prefix)}}</div><div class="muted">${{localTime(v.created_at)}}</div></div>`).join("") : empty(timelines.verdicts?.message || "No local reviewer verdict history yet."));
       const spendRows = [
         ...spendGroups.map(g => `<div class="row"><div class="line"><b>${{esc(g.lane)}}</b>${{pill(g.verdict)}}${{pill(`${{g.runs}} runs`)}}</div><div class="muted">${{seconds(g.wall_seconds_total)}} total / ${{seconds(g.wall_seconds_avg)}} avg / ${{money(g.cost_usd_total)}} / ${{esc(g.total_tokens || 0)}} tokens</div></div>`),
         spend.skipped_rows ? `<div class="row muted">Skipped ${{esc(spend.skipped_rows)}} malformed spend row(s).</div>` : "",
@@ -708,7 +716,7 @@ def render_board_html(config: BoardConfig) -> str:
       put("history", events.length ? events.slice().reverse().map(event => {{
         const s = event.summary || {{}};
         const remote = s.remote_available ? "remote available" : "remote unavailable";
-        return `<div class="row"><div class="line"><b>${{esc(event.created_at)}}</b>${{pill(remote)}}</div><div>next: <b>${{esc(s.next_action || "inspect")}}</b></div><div class="muted">PRs ${{esc(s.open_prs ?? 0)}} / alerts ${{esc(s.gate_alerts ?? 0)}} / local ${{esc((s.local_boards ?? 0) + (s.local_processes ?? 0))}}</div></div>`;
+        return `<div class="row"><div class="line"><b>${{localTime(event.created_at)}}</b>${{pill(remote)}}</div><div>next: <b>${{esc(s.next_action || "inspect")}}</b></div><div class="muted">PRs ${{esc(s.open_prs ?? 0)}} / alerts ${{esc(s.gate_alerts ?? 0)}} / local ${{esc((s.local_boards ?? 0) + (s.local_processes ?? 0))}}</div></div>`;
       }}).join("") : empty(history.message || "No local board events recorded yet."));
     }}
     async function load() {{

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/src/code_mower/doctor_checks/__init__.py

@@ -13,6 +13,7 @@ from .cloud import (
     token_file_mentions_cloud_token,
 )
 from .adoption import (
+    check_adoption_posture_guidance,
     check_adoption_setup,
     config_with_repository_target,
     detect_repo_slug,
@@ -31,6 +32,7 @@ from .github_human_token import (
     human_automation_token_config,
     human_automation_token_required,
 )
+from .github_trusted_authors import trusted_author_variable_statuses
 from .groups import GROUP_LABELS, doctor_check_group_id
 from .models import (
     STATUS_FAIL,
@@ -105,11 +107,13 @@ __all__ = [
     "auth_probe_output_detail",
     "build_doctor_run_plan",
     "check_cloud_token_surface",
+    "check_adoption_posture_guidance",
     "check_adoption_setup",
     "check_github_auth_surface",
     "check_macos_runner_launchagent",
     "check_github_setup",
     "check_human_automation_token",
+    "trusted_author_variable_statuses",
     "check_repository_posture",
     "check_lane_runtime",
     "check_review_hygiene",

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/src/code_mower/doctor_checks/adoption.py

@@ -5,13 +5,25 @@ from __future__ import annotations
 import re
 import subprocess
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Mapping, Sequence
 
 from .models import STATUS_PASS, STATUS_WARN, DoctorCheck
 
 
 OWNER_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
 OWNER_LOGIN_PLACEHOLDER = "TODO_OWNER_LOGIN"
+TRUSTED_AUDIT_AUTHOR_VARIABLES = (
+    "CLAUDE_AUDIT_BOT_AUTHORS",
+    "CODEX_BOT_AUTHORS",
+)
+GENERATED_SETUP_MARKERS = {
+    "generated_config": (".code-mower.generated/code-mower.yml",),
+    "installed_gate_workflow": (".github/workflows/code-mower-gate.yml",),
+    "installed_dispatch_workflow": (".github/workflows/dispatch-lanes.yml",),
+    "installed_agent_pr_labeler": (
+        ".github/workflows/code-mower-agent-pr-labeler.yml",
+    ),
+}
 
 
 def normalize_repo_slug(value: str, *, option: str = "--repo") -> str:
@@ -103,6 +115,85 @@ def _configured_repositories(config: Mapping[str, Any] | None) -> list[str]:
     return slugs
 
 
+def _generated_setup_marker_types(repo_root: Path | None) -> list[str]:
+    if repo_root is None:
+        return []
+    marker_types: list[str] = []
+    for marker_type, relative_paths in GENERATED_SETUP_MARKERS.items():
+        if any((repo_root / relative_path).exists() for relative_path in relative_paths):
+            marker_types.append(marker_type)
+    return marker_types
+
+
+def _config_source_state(
+    *,
+    source: str,
+    using_packaged_example: bool,
+    generated_marker_types: Sequence[str],
+) -> str:
+    if not using_packaged_example:
+        return source or "repository_config"
+    if source == "source_tree_starter":
+        return "source_tree_starter"
+    if generated_marker_types:
+        return "generated_without_root_config"
+    return "cold_configless"
+
+
+def check_adoption_posture_guidance(
+    checks: Sequence[DoctorCheck],
+    *,
+    adoption: bool,
+    adoption_posture: str,
+) -> tuple[DoctorCheck, ...]:
+    """Return first-run guidance when default posture may not match this host."""
+
+    if not adoption or adoption_posture != "reviewer-gate":
+        return ()
+    local_provider_gap_names = {"runtime.local_cli", "runtime.local_cli.probe"}
+    gap_lanes = sorted(
+        {
+            str(check.lane)
+            for check in checks
+            if check.lane
+            and (
+                check.name in local_provider_gap_names
+                or check.name.startswith("runtime.local_audit")
+            )
+            and check.status == STATUS_WARN
+        }
+    )
+    if not gap_lanes:
+        return ()
+    return (
+        DoctorCheck(
+            name="doctor.adoption.posture_hint",
+            status=STATUS_WARN,
+            message=(
+                "default reviewer-gate posture found local provider setup gaps"
+            ),
+            detail={
+                "adoption_posture": adoption_posture,
+                "local_provider_gap_lanes": gap_lanes,
+                "next_steps": [
+                    "rerun_orchestrator_only_if_this_host_only_coordinates",
+                    "rerun_hosted_builders_if_this_host_observes_hosted_lanes",
+                    "finish_local_cli_setup_if_this_host_runs_reviewers",
+                ],
+                "commands": [
+                    "code-mower doctor --adoption --orchestrator-only --repo OWNER/REPO",
+                    "code-mower doctor --adoption --hosted-builders --repo OWNER/REPO",
+                ],
+            },
+            remediation=(
+                "If this host only coordinates or observes hosted builders, "
+                "rerun with `--orchestrator-only` or `--hosted-builders`; "
+                "otherwise finish the local CLI/token setup for the listed lanes."
+            ),
+        ),
+    )
+
+
 def check_adoption_setup(
     *,
     config: Mapping[str, Any] | None,
@@ -112,6 +203,8 @@ def check_adoption_setup(
     repo_source: str,
     using_packaged_example: bool,
     config_source: str = "",
+    repo_root: Path | None = None,
+    trusted_author_variables: Mapping[str, str] | None = None,
 ) -> tuple[DoctorCheck, ...]:
     """Return first-run adoption posture checks."""
 
@@ -148,27 +241,64 @@ def check_adoption_setup(
     source = config_source or (
         "packaged_starter" if using_packaged_example else "repository_config"
     )
+    generated_marker_types = _generated_setup_marker_types(repo_root)
+    source_state = _config_source_state(
+        source=source,
+        using_packaged_example=using_packaged_example,
+        generated_marker_types=generated_marker_types,
+    )
     source_messages = {
         "explicit_config": "using explicit Code Mower config",
+        "cold_configless": (
+            "using packaged starter config because no repository code-mower.yml was found"
+        ),
+        "generated_without_root_config": (
+            "using packaged starter config because generated Code Mower setup exists "
+            "but repository code-mower.yml is not installed"
+        ),
         "packaged_starter": "using packaged starter config for adoption checks",
         "repository_config": "using repository Code Mower config",
         "source_tree_starter": "using source-tree starter config for adoption checks",
     }
+    next_steps = (
+        [
+            "review_generated_setup",
+            "install_root_config",
+            "rerun_adoption_doctor",
+        ]
+        if source_state == "generated_without_root_config"
+        else [
+            "run_init_easy_apply",
+            "edit_generated_config",
+            "rerun_adoption_doctor",
+        ]
+        if source_state == "cold_configless"
+        else []
+    )
     detail = {
         "config_path": str(config_path),
         "config_source": source,
+        "config_source_state": source_state,
         "configured_repositories": repositories,
         "effective_repository": repo_slug,
+        "repository_config_present": not using_packaged_example,
+        "generated_setup_detected": bool(generated_marker_types),
+        "generated_setup_marker_types": generated_marker_types,
     }
+    if next_steps:
+        detail["next_steps"] = next_steps
     if using_packaged_example:
         checks.append(
             DoctorCheck(
                 name="doctor.adoption.config_source",
                 status=STATUS_WARN,
-                message=source_messages.get(source, source_messages["packaged_starter"]),
+                message=source_messages.get(source_state, source_messages["packaged_starter"]),
                 detail=detail,
                 remediation=(
-                    "Run `code-mower init --easy --apply`, review the generated "
+                    "Review the generated setup, commit an edited code-mower.yml "
+                    "at the repository root, then rerun doctor."
+                    if source_state == "generated_without_root_config"
+                    else "Run `code-mower init --easy --apply`, review the generated "
                     "setup, and commit an edited code-mower.yml before relying "
                     "on recurring workflows."
                 ),
@@ -236,17 +366,35 @@ def check_adoption_setup(
             )
         )
 
+    trusted_detail: dict[str, Any] = {
+        "variables": list(TRUSTED_AUDIT_AUTHOR_VARIABLES)
+    }
+    if trusted_author_variables is not None:
+        variable_status = {
+            name: str(trusted_author_variables.get(name) or "missing")
+            for name in TRUSTED_AUDIT_AUTHOR_VARIABLES
+        }
+        trusted_detail["variable_status"] = variable_status
+        all_present = all(
+            variable_status[name] == "present" for name in TRUSTED_AUDIT_AUTHOR_VARIABLES
+        )
+        if all_present:
+            checks.append(
+                DoctorCheck(
+                    name="doctor.adoption.trusted_authors",
+                    status=STATUS_PASS,
+                    message="trusted audit-comment author variables are configured",
+                    detail=trusted_detail,
+                )
+            )
+            return tuple(checks)
+
     checks.append(
         DoctorCheck(
             name="doctor.adoption.trusted_authors",
             status=STATUS_WARN,
             message="human-run audit comments must be listed as trusted lane authors",
-            detail={
-                "variables": [
-                    "CLAUDE_AUDIT_BOT_AUTHORS",
-                    "CODEX_BOT_AUTHORS",
-                ]
-            },
+            detail=trusted_detail,
             remediation=(
                 "For manual pilot audits, set repository variables such as "
                 "CLAUDE_AUDIT_BOT_AUTHORS and CODEX_BOT_AUTHORS to the "

code_mower-0.9.1b1/src/code_mower/doctor_checks/github_trusted_authors.py

@@ -0,0 +1,38 @@
+"""GitHub repository variable checks for trusted audit-comment authors."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .github_api import _github_api_json
+
+
+def trusted_author_variable_statuses(
+    *,
+    gh_path: str,
+    slug: str,
+    variables: Iterable[str],
+    http_timeout: int,
+) -> dict[str, str]:
+    """Return safe presence statuses for trusted-author repository variables."""
+
+    statuses: dict[str, str] = {}
+    for variable in variables:
+        name = str(variable).strip()
+        if not name:
+            continue
+        payload, _detail = _github_api_json(
+            gh_path,
+            f"repos/{slug}/actions/variables/{name}",
+            http_timeout=http_timeout,
+        )
+        if payload is None:
+            statuses[name] = "missing"
+        elif str(payload.get("value") or "").strip():
+            statuses[name] = "present"
+        else:
+            statuses[name] = "empty"
+    return statuses
+
+
+__all__ = ("trusted_author_variable_statuses",)

{code_mower-0.9.0b1 → code_mower-0.9.1b1}/src/code_mower/doctor_checks/runner.py

@@ -3,16 +3,23 @@
 from __future__ import annotations
 
 from pathlib import Path
+import shutil
 from typing import Any, Mapping
 
 from code_mower import config as code_mower_config
 
-from .adoption import check_adoption_setup, config_with_repository_target
+from .adoption import (
+    TRUSTED_AUDIT_AUTHOR_VARIABLES,
+    check_adoption_posture_guidance,
+    check_adoption_setup,
+    config_with_repository_target,
+)
 from .audit_limits import check_effective_audit_limits
 from .cloud import check_cloud_token_surface
 from .common import ACTIONS_COST_SAMPLE_DEFAULT, load_inputs
 from .github import check_github_setup
 from .github_config import check_repository_posture
+from .github_trusted_authors import trusted_author_variable_statuses
 from .models import STATUS_FAIL, STATUS_PASS, DoctorCheck, DoctorReport
 from .providers import check_lane_runtime, effective_lane, provider_template_coverage, selected_lanes
 from .registry import DoctorCheckStage, build_doctor_run_plan
@@ -108,6 +115,22 @@ def run_doctor(
     repo_root = None if config_path.name == "code-mower.example.yml" else config_path.parent
     config, templates, checks = load_inputs(config_path, provider_templates_path)
     using_packaged_example = config_path.name == "code-mower.example.yml"
+    trusted_author_variables = None
+    trusted_author_repo_slug = repo_slug
+    if not trusted_author_repo_slug and isinstance(config, Mapping):
+        for repository in config.get("repositories") or []:
+            if isinstance(repository, Mapping) and repository.get("slug"):
+                trusted_author_repo_slug = str(repository.get("slug") or "")
+                break
+    if github and trusted_author_repo_slug:
+        gh_path = shutil.which("gh")
+        if gh_path:
+            trusted_author_variables = trusted_author_variable_statuses(
+                gh_path=gh_path,
+                slug=trusted_author_repo_slug,
+                variables=TRUSTED_AUDIT_AUTHOR_VARIABLES,
+                http_timeout=http_timeout,
+            )
     checks.extend(
         check_adoption_setup(
             config=config,
@@ -117,6 +140,8 @@ def run_doctor(
             repo_source=repo_source,
             config_source=config_source,
             using_packaged_example=using_packaged_example,
+            repo_root=Path.cwd() if using_packaged_example else config_path.parent,
+            trusted_author_variables=trusted_author_variables,
         )
     )
     if config is not None and repo_slug:
@@ -217,6 +242,13 @@ def run_doctor(
                 http_timeout=http_timeout,
             )
         )
+    checks.extend(
+        check_adoption_posture_guidance(
+            checks,
+            adoption=adoption,
+            adoption_posture=adoption_posture,
+        )
+    )
 
     if "github" in enabled_stages:
         checks.extend(