agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/ci_readiness.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+READY_TO_MERGE = "READY_TO_MERGE"
+ALREADY_MERGED = "ALREADY_MERGED"
+WAITING = "WAITING"
+BLOCKED = "BLOCKED"
+TIMEOUT = "TIMEOUT"
+GH_ERROR = "GH_ERROR"
+
+SUCCESS_OUTCOMES = {READY_TO_MERGE, ALREADY_MERGED}
+FAILED_CONCLUSIONS = {
+    "ACTION_REQUIRED",
+    "CANCELLED",
+    "FAILURE",
+    "STARTUP_FAILURE",
+    "STALE",
+    "TIMED_OUT",
+}
+SUCCESS_CONCLUSIONS = {"SUCCESS", "NEUTRAL", "SKIPPED"}
+
+
+@dataclass(frozen=True)
+class ReadinessDecision:
+    outcome: str
+    reasons: tuple[str, ...]
+    terminal: bool
+
+    @property
+    def success(self) -> bool:
+        return self.outcome in SUCCESS_OUTCOMES
+
+
+SnapshotProvider = Callable[[], dict[str, Any]]
+Clock = Callable[[], float]
+Sleeper = Callable[[float], None]
+
+
+def normalize_status_checks(snapshot: dict[str, Any]) -> list[dict[str, str]]:
+    raw = snapshot.get("statusCheckRollup") or []
+    if isinstance(raw, dict):
+        raw = raw.get("nodes") or raw.get("edges") or []
+    checks: list[dict[str, str]] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        if isinstance(item.get("node"), dict):
+            item = item["node"]
+        checks.append(
+            {
+                "name": str(item.get("name") or item.get("context") or ""),
+                "status": str(item.get("status") or item.get("state") or "").upper(),
+                "conclusion": str(item.get("conclusion") or "").upper(),
+            }
+        )
+    return checks
+
+
+def classify_pr_readiness(
+    snapshot: dict[str, Any],
+    *,
+    expected_head_sha: str | None = None,
+    elapsed_seconds: int = 0,
+    timeout_seconds: int = 2700,
+    expected_checks: tuple[str, ...] = (),
+) -> ReadinessDecision:
+    if elapsed_seconds >= timeout_seconds:
+        return ReadinessDecision(
+            TIMEOUT,
+            (f"timeout reached after {elapsed_seconds}s",),
+            True,
+        )
+
+    actual_head_sha = str(
+        snapshot.get("headRefOid") or snapshot.get("headSha") or snapshot.get("head_sha") or ""
+    )
+    if expected_head_sha and actual_head_sha and actual_head_sha != expected_head_sha:
+        return ReadinessDecision(
+            BLOCKED,
+            (f"head SHA changed: expected {expected_head_sha}, got {actual_head_sha}",),
+            True,
+        )
+
+    state = str(snapshot.get("state") or "").upper()
+    checks = normalize_status_checks(snapshot)
+    successful = [
+        check
+        for check in checks
+        if check["status"] == "COMPLETED" and check["conclusion"] in SUCCESS_CONCLUSIONS
+    ]
+
+    if state == "MERGED" and checks and len(successful) == len(checks):
+        return ReadinessDecision(ALREADY_MERGED, (), True)
+
+    if state != "OPEN":
+        return ReadinessDecision(BLOCKED, (f"PR state is not OPEN: {state or '<unknown>'}",), True)
+
+    if not checks:
+        return ReadinessDecision(WAITING, ("no status checks reported yet",), False)
+
+    names = {check["name"] for check in checks}
+    missing = tuple(name for name in expected_checks if name and name not in names)
+    if missing:
+        return ReadinessDecision(
+            WAITING,
+            tuple(f"expected check missing: {name}" for name in missing),
+            False,
+        )
+
+    failed = [check for check in checks if check["conclusion"] in FAILED_CONCLUSIONS]
+    if failed:
+        return ReadinessDecision(
+            BLOCKED,
+            tuple(f"check failed: {check['name'] or '<unknown>'}" for check in failed),
+            True,
+        )
+
+    pending = [check for check in checks if check not in successful]
+    if pending:
+        return ReadinessDecision(
+            WAITING,
+            tuple(f"check pending: {check['name'] or '<unknown>'}" for check in pending),
+            False,
+        )
+
+    merge_state = str(snapshot.get("mergeStateStatus") or "").upper()
+    mergeable = snapshot.get("mergeable")
+    if merge_state != "CLEAN":
+        return ReadinessDecision(
+            BLOCKED,
+            (f"mergeStateStatus is not CLEAN: {merge_state or '<unknown>'}",),
+            True,
+        )
+    if mergeable not in (True, "MERGEABLE", "mergeable"):
+        return ReadinessDecision(BLOCKED, (f"PR is not mergeable: {mergeable!r}",), True)
+
+    return ReadinessDecision(
+        READY_TO_MERGE,
+        ("all required checks passed and merge state is clean",),
+        True,
+    )
+
+
+def wait_for_pr_readiness(
+    snapshot_provider: SnapshotProvider,
+    *,
+    expected_head_sha: str | None = None,
+    timeout_seconds: int = 2700,
+    interval_seconds: int = 20,
+    expected_checks: tuple[str, ...] = (),
+    clock: Clock = time.monotonic,
+    sleep: Sleeper = time.sleep,
+) -> ReadinessDecision:
+    start = clock()
+    while True:
+        elapsed = int(clock() - start)
+        try:
+            snapshot = snapshot_provider()
+        except Exception as exc:
+            return ReadinessDecision(GH_ERROR, (str(exc),), True)
+        decision = classify_pr_readiness(
+            snapshot,
+            expected_head_sha=expected_head_sha,
+            elapsed_seconds=elapsed,
+            timeout_seconds=timeout_seconds,
+            expected_checks=expected_checks,
+        )
+        if decision.terminal:
+            return decision
+        remaining = timeout_seconds - elapsed
+        if remaining <= 0:
+            return ReadinessDecision(TIMEOUT, ("timeout reached while waiting for CI",), True)
+        sleep(min(interval_seconds, remaining))
+
+
+def gh_pr_snapshot_provider(pr_number: int) -> SnapshotProvider:
+    def provider() -> dict[str, Any]:
+        completed = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "view",
+                str(pr_number),
+                "--json",
+                "state,headRefOid,mergeStateStatus,mergeable,statusCheckRollup",
+            ],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if completed.returncode != 0:
+            details = completed.stderr.strip() or completed.stdout.strip() or "gh pr view failed"
+            raise RuntimeError(details)
+        return json.loads(completed.stdout)
+
+    return provider
+
+
+def render_pr_readiness(decision: ReadinessDecision) -> str:
+    lines = [
+        f"PR readiness outcome: {decision.outcome}",
+        f"terminal={str(decision.terminal).lower()}",
+        f"success={str(decision.success).lower()}",
+    ]
+    lines.extend(f"- {reason}" for reason in decision.reasons)
+    return "\n".join(lines)

agentic_project_kit/cli.py

@@ -0,0 +1,147 @@
+import typer
+
+from agentic_project_kit.cli_commands.actions import actions_app
+from agentic_project_kit.cli_commands.boot import boot_app
+from agentic_project_kit.cli_commands.checks import register_check_commands
+from agentic_project_kit.cli_commands.chat import chat_app
+from agentic_project_kit.cli_commands.cockpit import cockpit_app
+from agentic_project_kit.cli_commands.commands import (
+    audit_command_authority_command,
+    audit_command_manifest_command,
+    command_for_command,
+    commands_app,
+)
+from agentic_project_kit.cli_commands.dev import dev_app
+from agentic_project_kit.cli_commands.direction import direction_app
+from agentic_project_kit.cli_commands.dpa import dpa_app
+from agentic_project_kit.cli_commands.evidence import app as evidence_app
+from agentic_project_kit.cli_commands.github import register_github_commands
+from agentic_project_kit.cli_commands.governance import governance_app
+from agentic_project_kit.cli_commands.gui import gui_app
+from agentic_project_kit.cli_commands.handoff import handoff_app
+from agentic_project_kit.cli_commands.human_workflows import release_flow_app, work_app
+from agentic_project_kit.cli_commands.init import register_init_command
+from agentic_project_kit.cli_commands.instruction import instruction_app
+from agentic_project_kit.cli_commands.pass_already_done import app as pass_already_done_app
+from agentic_project_kit.cli_commands.patterns import patterns_app
+from agentic_project_kit.cli_commands.pr import pr_app, register_pr_closeout_alias
+from agentic_project_kit.cli_commands.pr_hygiene import register_pr_hygiene_command
+from agentic_project_kit.cli_commands.profiles import register_profile_commands
+from agentic_project_kit.cli_commands.release import register_release_commands
+from agentic_project_kit.cli_commands.remote_next import register_remote_next_command
+from agentic_project_kit.cli_commands.remote_branch_hygiene import register_remote_branch_hygiene_command
+from agentic_project_kit.cli_commands.rules import register_rules_commands
+from agentic_project_kit.cli_commands.rule_registry import rule_registry_app
+from agentic_project_kit.cli_commands.scaffold import scaffold_app
+from agentic_project_kit.cli_commands.slice import slice_app
+from agentic_project_kit.cli_commands.state import state_app
+from agentic_project_kit.cli_commands.todo import todo_app
+from agentic_project_kit.cli_commands.transfer import transfer_app
+from agentic_project_kit.cli_commands.transfer_post_merge_complete import (
+    register_transfer_post_merge_complete_command,
+)
+from agentic_project_kit.cli_commands.transfer_post_merge_settle import (
+    register_transfer_post_merge_settle_command,
+)
+from agentic_project_kit.cli_commands.transfer_pr_closeout_complete import (
+    register_transfer_pr_closeout_complete_command,
+)
+from agentic_project_kit.cli_commands.validation import register_validation_commands
+from agentic_project_kit.cli_commands.version import register_version_callback
+from agentic_project_kit.cli_commands.work_orders import work_orders_app
+from agentic_project_kit.cli_commands.workspace import workspace_app
+from agentic_project_kit.cli_commands.workflow import workflow_app
+from agentic_project_kit.cli_commands.workflow_guard import workflow_guard_app
+from agentic_project_kit.cli_commands.removed_ns_commands import register_removed_ns_commands
+from agentic_project_kit.cli_commands.ns_legacy_audit import audit_ns_legacy_references_command
+from agentic_project_kit.cli_commands.absolute_path_audit import audit_absolute_path_portability_command
+from agentic_project_kit.cli_commands.doc_currency_audit import audit_doc_currency_command
+from agentic_project_kit.cli_commands.doc_registry import doc_registry_app
+from agentic_project_kit.cli_commands.docs import docs_app
+from agentic_project_kit.cli_commands.status_current_state_audit import audit_status_current_state_command
+from agentic_project_kit.cli_commands.planning_docs_audit import audit_planning_docs_consolidation_command
+from agentic_project_kit.cli_commands.program_redundancy_audit import audit_program_redundancy_command
+from agentic_project_kit.cli_commands.gui_readiness_gate import gui_readiness_gate_command
+from agentic_project_kit.cli_commands.patch_failure_discipline_audit import audit_patch_failure_discipline_command
+from agentic_project_kit.cli_commands.path_literal_audit import audit_path_literals_command
+from agentic_project_kit.cli_commands.release_publish_orchestration import release_publish_command
+from agentic_project_kit.cli_commands.standard_gates_audit_suite import standard_gates_audit_suite_command
+from agentic_project_kit.cli_commands.command_taxonomy import command_taxonomy_check_command
+from agentic_project_kit.cli_commands.patch_preflight import patch_preflight_command
+from agentic_project_kit.cli_commands.artifact_gc import artifact_gc_command
+from agentic_project_kit.cli_commands.project_direction import project_direction_command
+from agentic_project_kit.cli_commands.mutation_lock_audit import register_mutation_lock_audit_command
+from agentic_project_kit.patch_artifact_preflight import register_patch_preflight_command
+
+app = typer.Typer(help="Generate and check agentic GitHub project skeletons.")
+register_version_callback(app)
+app.command("project-direction")(project_direction_command)
+app.command("artifact-gc")(artifact_gc_command)
+app.command("patch-scope-preflight")(patch_preflight_command)
+app.command("command-taxonomy-check")(command_taxonomy_check_command)
+app.command("audit-command-authority")(audit_command_authority_command)
+app.command("audit-command-manifest")(audit_command_manifest_command)
+app.command("command-for")(command_for_command)
+app.command("standard-gates-audit-suite")(standard_gates_audit_suite_command)
+app.command("release-publish")(release_publish_command)
+app.command("audit-patch-failure-discipline")(audit_patch_failure_discipline_command)
+app.command("audit-path-literals")(audit_path_literals_command)
+app.command("gui-readiness-gate")(gui_readiness_gate_command)
+app.command("audit-program-redundancy")(audit_program_redundancy_command)
+app.command("audit-planning-docs-consolidation")(audit_planning_docs_consolidation_command)
+app.command("audit-doc-currency")(audit_doc_currency_command)
+app.command("audit-status-current-state")(audit_status_current_state_command)
+app.command("audit-absolute-path-portability")(audit_absolute_path_portability_command)
+app.command("audit-ns-legacy-references")(audit_ns_legacy_references_command)
+
+register_init_command(app)
+register_profile_commands(app)
+register_pr_hygiene_command(app)
+register_github_commands(app)
+register_check_commands(app)
+register_release_commands(app)
+register_remote_next_command(app)
+register_remote_branch_hygiene_command(app)
+register_rules_commands(app)
+register_validation_commands(app)
+register_patch_preflight_command(app)
+register_transfer_post_merge_complete_command(transfer_app)
+register_transfer_post_merge_settle_command(transfer_app)
+register_transfer_pr_closeout_complete_command(transfer_app)
+register_removed_ns_commands(transfer_app)
+app.add_typer(work_app, name="work")
+app.add_typer(release_flow_app, name="release")
+app.add_typer(workflow_app, name="workflow")
+app.add_typer(workflow_guard_app, name="workflow-guard")
+app.add_typer(rule_registry_app, name="rule-registry")
+app.add_typer(doc_registry_app, name="doc-registry")
+app.add_typer(docs_app, name="docs")
+app.add_typer(chat_app, name="chat")
+app.add_typer(instruction_app, name="instruction")
+app.add_typer(handoff_app, name="handoff")
+app.add_typer(boot_app, name="boot")
+app.add_typer(commands_app, name="commands")
+app.add_typer(pass_already_done_app, name="pass-already-done")
+app.add_typer(actions_app, name="actions")
+app.add_typer(dev_app, name="dev")
+app.add_typer(direction_app, name="direction")
+app.add_typer(dpa_app, name="dpa")
+app.add_typer(evidence_app, name="evidence")
+app.add_typer(work_orders_app, name="work-order")
+app.add_typer(workspace_app, name="workspace")
+app.add_typer(governance_app, name="governance")
+app.add_typer(gui_app, name="gui")
+app.add_typer(pr_app, name="pr")
+register_pr_closeout_alias(app)
+register_mutation_lock_audit_command(app)
+app.add_typer(cockpit_app, name="cockpit")
+app.add_typer(patterns_app, name="patterns")
+app.add_typer(scaffold_app, name="scaffold")
+app.add_typer(slice_app, name="slice")
+app.add_typer(state_app, name="state")
+app.add_typer(todo_app, name="todo")
+app.add_typer(transfer_app, name="transfer")
+
+
+if __name__ == "__main__":
+    app()

agentic_project_kit/cli_commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the agentic-kit CLI."""

agentic_project_kit/cli_commands/absolute_path_audit.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.absolute_path_portability_audit import (
+    audit_absolute_path_portability,
+    render_absolute_path_portability_audit,
+)
+
+
+def audit_absolute_path_portability_command(
+    root: Path = typer.Option(Path("."), "--root"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Audit absolute local paths that may break portability."""
+    result = audit_absolute_path_portability(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_absolute_path_portability_audit(result), nl=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)

agentic_project_kit/cli_commands/actions.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import typer
+
+from agentic_project_kit.action_specs import built_in_action_specs, get_action_spec, render_action_spec
+
+actions_app = typer.Typer(help="Inspect parameterized action specifications.")
+
+@actions_app.command("list")
+def list_actions() -> None:
+    for spec in built_in_action_specs().values():
+        typer.echo(f"{spec.action_id}\t{spec.safety_class.value}\t{spec.title}")
+
+@actions_app.command("show")
+def show_action(action_id: str) -> None:
+    try:
+        spec = get_action_spec(action_id)
+    except KeyError as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1) from exc
+    typer.echo(render_action_spec(spec))

agentic_project_kit/cli_commands/artifact_gc.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.communication_artifact_gc import (
+    DEFAULT_TMP_LOG_TTL_SECONDS,
+    collect_candidates,
+    execute_gc,
+    execute_report_retention_gc,
+    execute_tmp_log_gc,
+    execute_transfer_run_report_gc,
+    render_plan,
+)
+from agentic_project_kit.local_garbage_collector import run_local_garbage_collector
+from agentic_project_kit.workspace import load_workspace
+
+
+def _message_lines(message: str) -> list[str]:
+    return [line for line in message.splitlines() if line.strip()]
+
+
+def _emit_json(
+    *,
+    mode: str,
+    outcome: str,
+    message: str,
+    execute: bool,
+    ttl_seconds: int | None = None,
+    older_than: str = "",
+) -> None:
+    lines = _message_lines(message)
+    typer.echo(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "kind": "artifact_gc_result",
+                "mode": mode,
+                "result_status": "PASS" if _ok(outcome) else "FAIL",
+                "outcome": outcome,
+                "execute": execute,
+                "dry_run": not execute,
+                "ttl_seconds": ttl_seconds,
+                "older_than": older_than or None,
+                "candidate_count": len(lines),
+                "candidates": lines,
+                "remote_execution_policy": {
+                    "status": "not_automatic",
+                    "allowed_path": "dry-run report -> explicit confirm -> normal commit/PR lifecycle",
+                    "forbidden_path": "ad-hoc remote deletion or a new transfer gc-logs command",
+                },
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+def _emit(outcome: str, message: str) -> None:
+    typer.echo(outcome)
+    if message:
+        typer.echo(message)
+
+
+def _ok(outcome: str) -> bool:
+    return outcome.startswith("PASS") or outcome.startswith("PENDING")
+
+
+def _ttl_from_older_than(older_than: str, *, default_ttl_seconds: int) -> int:
+    text = older_than.strip()
+    if not text:
+        return default_ttl_seconds
+    try:
+        if len(text) == 10:
+            cutoff = datetime.fromisoformat(text).replace(tzinfo=timezone.utc)
+        else:
+            cutoff = datetime.fromisoformat(text.replace("Z", "+00:00"))
+            if cutoff.tzinfo is None:
+                cutoff = cutoff.replace(tzinfo=timezone.utc)
+    except ValueError as exc:
+        raise typer.BadParameter("--older-than must be an ISO date or datetime") from exc
+    now = datetime.now(timezone.utc)
+    return max(0, int((now - cutoff.astimezone(timezone.utc)).total_seconds()))
+
+
+def artifact_gc_command(
+    tmp_logs: bool = typer.Option(False, "--tmp-logs", help="Collect expired local tmp logs."),
+    local_tmp: bool = typer.Option(False, "--local-tmp", help="Use repository-local tmp/ instead of /tmp for --tmp-logs."),
+    local_tmp_contents: bool = typer.Option(
+        False,
+        "--local-tmp-contents",
+        help="Collect expired untracked files and empty directories under repository-local tmp/.",
+    ),
+    transfer_runs: bool = typer.Option(False, "--transfer-runs", help="Collect expired docs/reports/transfer_runs files."),
+    report_retention: bool = typer.Option(
+        False,
+        "--report-retention",
+        help="Collect expired report-like files and generated successor-handoff Markdown under selected docs/report surfaces.",
+    ),
+    execute: bool = typer.Option(False, "--execute", help="Actually delete candidates. Default is dry-run."),
+    ttl_seconds: int = typer.Option(
+        DEFAULT_TMP_LOG_TTL_SECONDS,
+        "--ttl-seconds",
+        min=0,
+        help="Retention age in seconds for age-gated modes.",
+    ),
+    older_than: str = typer.Option(
+        "",
+        "--older-than",
+        help="ISO date/datetime cutoff. Overrides --ttl-seconds for age-gated modes.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Dry-run by default garbage collector for transient communication artifacts."""
+    selected_modes = sum(1 for enabled in (tmp_logs, local_tmp_contents, transfer_runs, report_retention) if enabled)
+    if selected_modes > 1:
+        if json_output:
+            _emit_json(
+                mode="invalid",
+                outcome="FAIL_MUTUALLY_EXCLUSIVE_MODES",
+                message="Choose only one GC mode.",
+                execute=execute,
+                ttl_seconds=ttl_seconds,
+                older_than=older_than,
+            )
+        else:
+            typer.echo("FAIL_MUTUALLY_EXCLUSIVE_MODES")
+        raise typer.Exit(code=1)
+
+    effective_ttl_seconds = _ttl_from_older_than(older_than, default_ttl_seconds=ttl_seconds)
+
+    if local_tmp_contents:
+        result = run_local_garbage_collector(
+            Path("."),
+            dry_run=not execute,
+            retention_seconds=effective_ttl_seconds,
+            write_report=True,
+            skip_if_run_id_seen=False,
+        )
+        result = {
+            **result,
+            "mode": "local-tmp-contents",
+            "older_than": older_than or None,
+            "remote_execution_policy": {
+                "status": "forbidden",
+                "allowed_path": "local repo tmp/ cleanup only",
+                "forbidden_path": "remote tmp cleanup, report retention, or git push from this mode",
+            },
+        }
+        if json_output:
+            typer.echo(json.dumps(result, indent=2, sort_keys=True))
+        else:
+            typer.echo("PASS_LOCAL_TMP_CONTENTS" if result["result_status"] == "PASS" else "FAIL_LOCAL_TMP_CONTENTS")
+            for path in [*result.get("deleted", []), *result.get("deleted_directories", [])]:
+                typer.echo(path)
+        if result["result_status"] != "PASS":
+            raise typer.Exit(code=1)
+        return
+
+    if tmp_logs:
+        tmp_root = load_workspace(Path(".")).tmp() if local_tmp else Path("/tmp")
+        outcome, message = execute_tmp_log_gc(tmp_root, execute=execute, ttl_seconds=effective_ttl_seconds)
+        if json_output:
+            _emit_json(
+                mode="tmp-logs-local" if local_tmp else "tmp-logs",
+                outcome=outcome,
+                message=message,
+                execute=execute,
+                ttl_seconds=effective_ttl_seconds,
+                older_than=older_than,
+            )
+        else:
+            _emit(outcome, message)
+        if not _ok(outcome):
+            raise typer.Exit(code=1)
+        return
+
+    if transfer_runs:
+        outcome, message = execute_transfer_run_report_gc(Path("."), execute=execute, ttl_seconds=effective_ttl_seconds)
+        if json_output:
+            _emit_json(
+                mode="transfer-runs",
+                outcome=outcome,
+                message=message,
+                execute=execute,
+                ttl_seconds=effective_ttl_seconds,
+                older_than=older_than,
+            )
+        else:
+            _emit(outcome, message)
+        if not _ok(outcome):
+            raise typer.Exit(code=1)
+        return
+
+    if report_retention:
+        outcome, message = execute_report_retention_gc(Path("."), execute=execute, ttl_seconds=effective_ttl_seconds)
+        if json_output:
+            _emit_json(
+                mode="report-retention",
+                outcome=outcome,
+                message=message,
+                execute=execute,
+                ttl_seconds=effective_ttl_seconds,
+                older_than=older_than,
+            )
+        else:
+            _emit(outcome, message)
+        if not _ok(outcome):
+            raise typer.Exit(code=1)
+        return
+
+    if execute:
+        outcome, message = execute_gc(Path("."))
+        if json_output:
+            _emit_json(
+                mode="communication-artifacts",
+                outcome=outcome,
+                message=message,
+                execute=execute,
+            )
+        else:
+            _emit(outcome, message)
+        if not outcome.startswith("PASS"):
+            raise typer.Exit(code=1)
+        return
+
+    message = render_plan(collect_candidates(Path(".")))
+    if json_output:
+        outcome, *rest = message.splitlines()
+        _emit_json(
+            mode="communication-artifacts",
+            outcome=outcome,
+            message="\n".join(rest),
+            execute=False,
+        )
+    else:
+        typer.echo(message)