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

agentic_project_kit/cli_commands/boot.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import typer
+
+from agentic_project_kit.chat_bootloader import check_boot_sources
+from agentic_project_kit.chat_bootloader import render_boot_report
+from agentic_project_kit.chat_bootloader import render_bootloader
+from agentic_project_kit.chat_bootloader import run_chat_switch_closeout
+from agentic_project_kit.chat_bootloader import write_boot_report
+from agentic_project_kit.chat_bootloader import write_next_chat_bootstrap
+
+boot_app = typer.Typer(help="Render and check successor-chat boot information.")
+
+
+@boot_app.command("prompt")
+def prompt(root: str = ".") -> None:
+    typer.echo(render_bootloader(root))
+
+
+@boot_app.command("check")
+def check(root: str = ".") -> None:
+    typer.echo(render_bootloader(root))
+    missing = [item.source for item in check_boot_sources(root) if not item.exists]
+    if missing:
+        raise typer.Exit(code=1)
+
+
+@boot_app.command("write")
+def write(
+    path: str = "docs/handoff/NEXT_CHAT_BOOTSTRAP.md",
+    root: str = ".",
+    include_state: bool = False,
+) -> None:
+    output_path = write_next_chat_bootstrap(path, root, include_state=include_state)
+    typer.echo(f"WROTE {output_path}")
+
+
+@boot_app.command("report")
+def report(root: str = ".", path: str = "") -> None:
+    if path:
+        output_path = write_boot_report(path, root)
+        typer.echo(f"WROTE {output_path}")
+    else:
+        typer.echo(render_boot_report(root))
+
+
+@boot_app.command("closeout")
+def closeout(root: str = ".") -> None:
+    findings = run_chat_switch_closeout(root)
+    if findings:
+        typer.echo("CHAT_SWITCH_CLOSEOUT: FAIL")
+        for finding in findings:
+            typer.echo(f"- {finding}")
+        raise typer.Exit(code=1)
+    typer.echo("CHAT_SWITCH_CLOSEOUT: PASS")

agentic_project_kit/cli_commands/chat.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import typer
+
+from agentic_project_kit.chat_entrypoint_contract import (
+    render_chat_refresher,
+    render_chat_session_start,
+)
+
+chat_app = typer.Typer(help="Render command-manifest-aware chat entrypoints.")
+
+
+@chat_app.command("refresher")
+def chat_refresher_command(
+    mode: str = typer.Option("copy-paste", "--mode", help="copy-paste, remote, or file-transfer."),
+) -> None:
+    """Render the compact six-line command manifest refresher."""
+    try:
+        typer.echo(render_chat_refresher(mode), nl=False)
+    except ValueError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc
+
+
+@chat_app.command("session-start")
+def chat_session_start_command(
+    mode: str = typer.Option("copy-paste", "--mode", help="copy-paste, remote, or file-transfer."),
+) -> None:
+    """Render the session-start refresher and full inline command list."""
+    try:
+        typer.echo(render_chat_session_start(mode), nl=False)
+    except ValueError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc

agentic_project_kit/cli_commands/checks.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from agentic_project_kit.checks import (
+    CheckContext,
+    build_check_context,
+    check_all,
+    check_docs,
+    check_todo,
+)
+from agentic_project_kit.doc_mesh import (
+    apply_doc_mesh_repair_plan,
+    build_doc_mesh_repair_plan,
+    build_doc_mesh_report,
+    render_doc_mesh_repair_plan,
+    render_doc_mesh_repair_result,
+    render_doc_mesh_report,
+    write_doc_mesh_json_report,
+    write_doc_mesh_repair_plan,
+    write_doc_mesh_repair_result,
+)
+from agentic_project_kit.doc_lifecycle import (
+    build_doc_lifecycle_report,
+    build_doc_lifecycle_strict_findings,
+    render_doc_lifecycle_report,
+    render_doc_lifecycle_strict_findings,
+    write_doc_lifecycle_json_report,
+)
+from agentic_project_kit.doc_lifecycle_signals import (
+    build_doc_orphan_report,
+    build_review_after_suggestions,
+    render_doc_orphan_report,
+    render_review_after_suggestions,
+    review_after_suggestions_to_dict,
+    write_doc_orphan_json_report,
+)
+from agentic_project_kit.documentation_registry import (
+    build_documentation_registry_summary,
+    render_documentation_registry_summary,
+    write_documentation_registry_summary_json,
+)
+from agentic_project_kit.documentation_system_audit import (
+    build_documentation_system_audit,
+    render_documentation_system_audit,
+    write_documentation_system_audit_json,
+)
+from agentic_project_kit.doctor import build_doctor_report, render_doctor_report
+
+console = Console()
+
+
+def register_check_commands(app: typer.Typer) -> None:
+    app.command("check")(check_command)
+    app.command("check-docs")(check_docs_command)
+    app.command("check-todo")(check_todo_command)
+    app.command("docs-audit")(docs_audit_command)
+    app.command("docs-registry")(docs_registry_command)
+    app.command("doc-mesh-audit")(doc_mesh_audit_command)
+    app.command("doc-lifecycle-audit")(doc_lifecycle_audit_command)
+    app.command("audit-doc-orphans")(audit_doc_orphans_command)
+    app.command("doc-mesh-repair")(doc_mesh_repair_command)
+    app.command("doctor")(doctor_command)
+
+
+def check_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Emit machine-readable check result with execution context."),
+    ] = False,
+    show_context: Annotated[
+        bool,
+        typer.Option("--context", help="Print check execution context before the text result."),
+    ] = False,
+) -> None:
+    root = project_root.resolve()
+    errors = check_all(root)
+    _print_result(
+        errors,
+        command="check",
+        project_root=root,
+        json_output=json_output,
+        show_context=show_context,
+    )
+
+
+def check_docs_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Emit machine-readable check result with execution context."),
+    ] = False,
+    show_context: Annotated[
+        bool,
+        typer.Option("--context", help="Print check execution context before the text result."),
+    ] = False,
+) -> None:
+    root = project_root.resolve()
+    errors = check_docs(root)
+    _print_result(
+        errors,
+        command="check-docs",
+        project_root=root,
+        json_output=json_output,
+        show_context=show_context,
+    )
+
+
+def check_todo_command(project_root: Path = typer.Option(Path("."), "--root")) -> None:
+    errors = check_todo(project_root.resolve())
+    _print_result(errors)
+
+
+def docs_audit_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    report_path: Annotated[Path | None, typer.Option("--report")] = None,
+) -> None:
+    """Run the umbrella documentation-system audit."""
+    report = build_documentation_system_audit(project_root.resolve())
+    if report_path is not None:
+        write_documentation_system_audit_json(report, report_path)
+    console.print(render_documentation_system_audit(report), markup=False)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def docs_registry_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    report_path: Annotated[Path | None, typer.Option("--report")] = None,
+) -> None:
+    """Show a read-only summary of the documentation registry."""
+    summary = build_documentation_registry_summary(project_root.resolve())
+    if report_path is not None:
+        write_documentation_registry_summary_json(summary, report_path)
+    console.print(render_documentation_registry_summary(summary), markup=False)
+
+
+def doc_lifecycle_audit_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    report_path: Annotated[Path | None, typer.Option("--report")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON instead of text.")] = False,
+    strict: Annotated[
+        bool,
+        typer.Option("--strict", help="Fail on deterministic lifecycle blocker findings."),
+    ] = False,
+    current_version: Annotated[
+        str | None,
+        typer.Option("--current-version", help="Override the version used for release review_after checks."),
+    ] = None,
+    suggest_review_after: Annotated[
+        bool,
+        typer.Option("--suggest-review-after", help="Print report-only review_after suggestions from version target prose."),
+    ] = False,
+) -> None:
+    """Audit lifecycle status headers for planning, roadmap, strategy, and idea documents."""
+    if suggest_review_after:
+        suggestions = build_review_after_suggestions(project_root.resolve())
+        if json_output:
+            typer.echo(json.dumps(review_after_suggestions_to_dict(suggestions), indent=2, sort_keys=True))
+        else:
+            console.print(render_review_after_suggestions(suggestions), markup=False)
+        return
+
+    root = project_root.resolve()
+    report = build_doc_lifecycle_report(root, current_version=current_version)
+    strict_requested = strict or report.hygiene_mode == "strict"
+    strict_findings = (
+        build_doc_lifecycle_strict_findings(root, report=report)
+        if strict_requested
+        else ()
+    )
+    if report_path is not None:
+        write_doc_lifecycle_json_report(report, report_path)
+    if json_output:
+        payload = report.to_dict()
+        if strict_requested:
+            payload["strict"] = {
+                "ok": not strict_findings,
+                "blocker_count": len(strict_findings),
+                "blockers": [finding.to_dict() for finding in strict_findings],
+                "source": "--strict" if strict else "workspace hygiene",
+            }
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        console.print(render_doc_lifecycle_report(report), markup=False)
+        if strict_requested:
+            console.print(render_doc_lifecycle_strict_findings(strict_findings), markup=False)
+    if strict_requested and strict_findings:
+        raise typer.Exit(code=1)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def audit_doc_orphans_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    report_path: Annotated[Path | None, typer.Option("--report")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON instead of text.")] = False,
+) -> None:
+    """Report registered documents without incoming repository references."""
+    report = build_doc_orphan_report(project_root.resolve())
+    if report_path is not None:
+        write_doc_orphan_json_report(report, report_path)
+    if json_output:
+        typer.echo(json.dumps(report.to_dict(), indent=2, sort_keys=True))
+    else:
+        console.print(render_doc_orphan_report(report), markup=False)
+
+
+def doc_mesh_audit_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    report_path: Annotated[Path | None, typer.Option("--report")] = None,
+    repair_plan_path: Annotated[Path | None, typer.Option("--repair-plan")] = None,
+) -> None:
+    """Audit cross-document state, governance, architecture, and historical-plan drift."""
+    report = build_doc_mesh_report(project_root.resolve())
+    if report_path is not None:
+        write_doc_mesh_json_report(report, report_path)
+    if repair_plan_path is not None:
+        repair_plan = build_doc_mesh_repair_plan(report)
+        write_doc_mesh_repair_plan(repair_plan, repair_plan_path)
+        console.print(render_doc_mesh_repair_plan(repair_plan), markup=False)
+    console.print(render_doc_mesh_report(report), markup=False)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def doc_mesh_repair_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    result_path: Annotated[Path | None, typer.Option("--result")] = None,
+) -> None:
+    """Apply safe automatic documentation mesh repairs."""
+    report = build_doc_mesh_report(project_root.resolve())
+    repair_plan = build_doc_mesh_repair_plan(report)
+    result = apply_doc_mesh_repair_plan(project_root.resolve(), repair_plan)
+    if result_path is not None:
+        write_doc_mesh_repair_result(result, result_path)
+    console.print(render_doc_mesh_repair_result(result), markup=False)
+
+
+def doctor_command(project_root: Path = typer.Option(Path("."), "--root")) -> None:
+    """Run a compact project health check."""
+    report = build_doctor_report(project_root.resolve())
+    console.print(render_doctor_report(report), markup=False)
+    if not report.ok:
+        raise typer.Exit(code=1)
+
+
+def _print_result(
+    errors: list[str],
+    *,
+    command: str | None = None,
+    project_root: Path | None = None,
+    json_output: bool = False,
+    show_context: bool = False,
+) -> None:
+    if json_output:
+        if command is None or project_root is None:
+            raise RuntimeError("JSON check output requires command and project root context")
+        payload = _check_result_payload(command, project_root, errors)
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+        if errors:
+            raise typer.Exit(code=1)
+        return
+    if show_context and project_root is not None:
+        _print_check_context(build_check_context(project_root))
+    if errors:
+        console.print("[bold red]Agentic project check failed[/bold red]")
+        for error in errors:
+            console.print(f"[red]- {error}[/red]")
+        raise typer.Exit(code=1)
+    console.print("[bold green]Agentic project check passed[/bold green]")
+
+
+def _check_result_payload(command: str, project_root: Path, errors: list[str]) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "kind": "agentic_project_check_result",
+        "command": command,
+        "status": "PASS" if not errors else "FAIL",
+        "error_count": len(errors),
+        "errors": errors,
+        "context": build_check_context(project_root).as_dict(),
+    }
+
+
+def _print_check_context(context: CheckContext) -> None:
+    console.print("CHECK_CONTEXT", markup=False)
+    console.print(f"MODE={context.mode}", markup=False)
+    console.print(
+        f"EXTERNAL_MANIFEST_WORKSPACE={str(context.external_manifest_workspace).lower()}",
+        markup=False,
+    )
+    console.print(f"GATE_FAMILY={context.gate_family}", markup=False)
+    console.print(f"CHECK_RENDERS_STATUSES={str(context.check_renders_statuses).lower()}", markup=False)
+    console.print(f"SKIP_STATUS_RENDERER={context.skip_status_renderer}", markup=False)
+    if context.gate_documents:
+        console.print(f"GATE_DOCUMENTS={','.join(context.gate_documents)}", markup=False)
+    if context.invalid_manifest_error:
+        console.print(f"INVALID_MANIFEST_ERROR={context.invalid_manifest_error}", markup=False)

agentic_project_kit/cli_commands/cockpit.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from agentic_project_kit.cockpit import (
+    action_inventory_as_json_data,
+    action_result_as_json_data,
+    build_cockpit_status,
+    cockpit_actions,
+    render_action_inventory,
+    render_action_selection,
+    render_cockpit_status,
+    run_cockpit_action,
+)
+from agentic_project_kit.gui_gatekeeper_status import (
+    build_gui_gatekeeper_status,
+    gui_gatekeeper_status_as_json_data,
+    render_gui_gatekeeper_status,
+)
+
+
+cockpit_app = typer.Typer(help="Inspect local cockpit status and structured project actions.")
+console = Console()
+
+
+@cockpit_app.command("status")
+def cockpit_status_command(project_root: Annotated[Path, typer.Option("--root")] = Path(".")) -> None:
+    status = build_cockpit_status(project_root.resolve())
+    console.print(render_cockpit_status(status), markup=False)
+
+
+@cockpit_app.command("gatekeeper-status")
+def cockpit_gatekeeper_status_command(
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON GUI gatekeeper status."),
+    ] = False,
+) -> None:
+    status = build_gui_gatekeeper_status(project_root.resolve())
+    if json_output:
+        typer.echo(json.dumps(gui_gatekeeper_status_as_json_data(status), indent=2, sort_keys=True))
+        return
+    console.print(render_gui_gatekeeper_status(status), markup=False)
+
+
+@cockpit_app.command("actions")
+def cockpit_actions_command(
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON action inventory."),
+    ] = False,
+) -> None:
+    actions = cockpit_actions()
+    if json_output:
+        typer.echo(json.dumps(action_inventory_as_json_data(actions), indent=2, sort_keys=True))
+        return
+    console.print(render_action_inventory(actions), markup=False)
+
+
+@cockpit_app.command("select")
+def cockpit_select_command() -> None:
+    actions = cockpit_actions()
+    console.print(render_action_selection(actions), markup=False)
+
+
+@cockpit_app.command("run")
+def cockpit_run_command(
+    action_id: str,
+    project_root: Annotated[Path, typer.Option("--root")] = Path("."),
+    allow_bounded: Annotated[bool, typer.Option("--allow-bounded")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON action result.")] = False,
+) -> None:
+    result = run_cockpit_action(action_id, project_root.resolve(), allow_bounded=allow_bounded)
+    if json_output:
+        typer.echo(json.dumps(action_result_as_json_data(result), indent=2, sort_keys=True))
+        if not result.allowed:
+            raise typer.Exit(code=2)
+        if result.returncode not in (None, 0):
+            raise typer.Exit(code=result.returncode)
+        return
+    console.print(f"action_id={result.action_id}", markup=False)
+    console.print(f"allowed={str(result.allowed).lower()}", markup=False)
+    console.print(f"executed={str(result.executed).lower()}", markup=False)
+    console.print(f"result_status={result.result_status}", markup=False)
+    console.print(f"safety={result.safety}", markup=False)
+    console.print(f"dirty_state={result.dirty_state}", markup=False)
+    if result.returncode is not None:
+        console.print(f"returncode={result.returncode}", markup=False)
+    console.print(result.message, markup=False)
+    if result.stdout:
+        console.print(result.stdout, markup=False)
+    if result.stderr:
+        console.print(result.stderr, markup=False)
+    if not result.allowed:
+        raise typer.Exit(code=2)
+    if result.returncode not in (None, 0):
+        raise typer.Exit(code=result.returncode)

agentic_project_kit/cli_commands/command_taxonomy.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.command_taxonomy import (
+    build_command_taxonomy_report,
+    render_command_taxonomy_report,
+)
+
+
+def command_taxonomy_check_command(
+    root: Path = typer.Option(Path("."), "--root"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Check that public commands have stable GUI-usable taxonomy."""
+    report = build_command_taxonomy_report(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(report.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_command_taxonomy_report(report), nl=False)
+    if not report.ok:
+        raise typer.Exit(code=1)

agentic_project_kit/cli_commands/commands.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.command_selector import (
+    render_command_selection,
+    select_for_raw,
+    select_for_task,
+)
+from agentic_project_kit.command_manifest import (
+    MD_PATH,
+    build_current_reference,
+    evaluate_command_manifest,
+    load_manifest,
+    render_command_manifest_audit,
+    render_markdown,
+)
+from agentic_project_kit.command_authority_audit import (
+    evaluate_command_authority,
+    render_command_authority_audit,
+)
+from agentic_project_kit.chat_entrypoint_contract import sync_entrypoint_files
+
+
+commands_app = typer.Typer(help="Inspect and render the agentic-kit command manifest.")
+
+
+@commands_app.command("render-md")
+def commands_render_md_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    execute: bool = typer.Option(False, "--execute", help="Write generated Markdown."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Render docs/reference/AGENTIC_KIT_COMMANDS.md from the JSON manifest."""
+    root = root.resolve()
+    data = load_manifest(root)
+    rendered = render_markdown(data)
+    path = root / MD_PATH
+    changed = path.read_text(encoding="utf-8") != rendered if path.exists() else True
+    if execute:
+        path.write_text(rendered, encoding="utf-8")
+    payload = {
+        "schema_version": 1,
+        "kind": "commands_render_md_result",
+        "result_status": "PASS",
+        "path": MD_PATH.as_posix(),
+        "changed": changed,
+        "written": bool(execute),
+        "manifest_sha": (data.get("meta") or {}).get("manifest_sha"),
+    }
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        if execute:
+            typer.echo(f"COMMANDS_RENDER_MD\nSTATUS=PASS\nWRITTEN={path.as_posix()}\n")
+        else:
+            typer.echo(rendered, nl=False)
+
+
+@commands_app.command("sync-entrypoints")
+def commands_sync_entrypoints_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    execute: bool = typer.Option(False, "--execute", help="Write synchronized entrypoint files."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Synchronize command reference files and command-manifest entrypoint headers."""
+    root = root.resolve()
+    data = build_current_reference()
+    rendered = render_markdown(data)
+    payload = sync_entrypoint_files(root, manifest=data, markdown=rendered, execute=execute)
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    status = "CHANGED" if payload["changed"] else "CURRENT"
+    typer.echo(
+        "COMMANDS_SYNC_ENTRYPOINTS\n"
+        f"STATUS=PASS\nSTATE={status}\n"
+        f"MANIFEST_SHA={payload['manifest_sha']}\n"
+        f"EXECUTE={str(execute).lower()}\n"
+    )
+
+
+def audit_command_manifest_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Audit command manifest hash, CLI coverage, safety metadata, and MD sync."""
+    audit = evaluate_command_manifest(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(audit.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_command_manifest_audit(audit), nl=False)
+    if not audit.ok:
+        raise typer.Exit(code=audit.returncode)
+
+
+def audit_command_authority_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Audit agent-facing command authority surfaces for current command-for guidance."""
+    audit = evaluate_command_authority(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(audit.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_command_authority_audit(audit), nl=False)
+    if not audit.ok:
+        raise typer.Exit(code=audit.returncode)
+
+
+def command_for_command(
+    raw: str | None = typer.Option(None, "--raw", help="Raw command line to map to a wrapper."),
+    task: str | None = typer.Option(None, "--task", help="Task tag to list matching commands."),
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+) -> None:
+    """Select the deterministic wrapper command for a raw command or task tag."""
+    if bool(raw) == bool(task):
+        typer.echo("Provide exactly one of --raw or --task.", err=True)
+        raise typer.Exit(code=2)
+    manifest = load_manifest(root.resolve())
+    selection = select_for_raw(manifest, raw) if raw is not None else select_for_task(manifest, str(task))
+    if json_output:
+        typer.echo(json.dumps(selection.payload, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_command_selection(selection), nl=False)

agentic_project_kit/cli_commands/dev.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import typer
+
+from agentic_project_kit.local_feature_gate import run_local_feature_gate
+
+dev_app = typer.Typer(help="Run local developer gates without remote side effects.")
+
+
+@dev_app.command("local-feature-gate", context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def local_feature_gate_command(
+    ctx: typer.Context,
+    include_pr_hygiene: bool = typer.Option(
+        False,
+        "--include-pr-hygiene",
+        help="Also run PR hygiene after the local feature gate.",
+    ),
+) -> None:
+    """Run the local feature gate through the supported agentic-kit CLI."""
+    pytest_args = list(ctx.args)
+    if pytest_args[:1] == ["--"]:
+        pytest_args = pytest_args[1:]
+    raise typer.Exit(code=run_local_feature_gate(pytest_args, include_pr_hygiene=include_pr_hygiene))