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

agentic_project_kit/cli_commands/direction.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+import typer
+
+from agentic_project_kit.project_direction import (
+    audit_project_direction_drift,
+    load_project_direction,
+    render_direction_drift_audit,
+    render_direction_validation,
+    render_project_direction,
+    validate_project_direction,
+)
+
+direction_app = typer.Typer(help="Validate, render, and audit project direction state.")
+
+Section = Literal["all", "strategy", "roadmap", "plans", "ideas", "done", "discarded"]
+OutputFormat = Literal["text", "markdown", "json"]
+
+
+@direction_app.command("validate")
+def direction_validate_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    strict_planning_files: bool = typer.Option(
+        False,
+        "--strict-planning-files",
+        help="Fail when free docs/planning files are not canonical files or listed sources.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Validate docs/planning/PROJECT_DIRECTION.yaml."""
+    result = validate_project_direction(root, strict_planning_files=strict_planning_files)
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_direction_validation(result), nl=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)
+
+
+@direction_app.command("render")
+def direction_render_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    section: Section = typer.Option(
+        "all",
+        "--section",
+        help="all, strategy, roadmap, plans, ideas, done, or discarded.",
+    ),
+    output_format: OutputFormat = typer.Option("text", "--format", help="text, markdown, or json."),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        help="Optional tmp/*.md, tmp/*.txt, or tmp/*.json output path.",
+    ),
+) -> None:
+    """Render project direction without overwriting committed projections."""
+    rendered = render_project_direction(
+        load_project_direction(root),
+        section=section,
+        output_format=output_format,
+    )
+    if output is None:
+        typer.echo(rendered, nl=False)
+        return
+
+    root_path = root.resolve()
+    output_path = output if output.is_absolute() else root_path / output
+    try:
+        relative = output_path.resolve().relative_to(root_path)
+    except ValueError as exc:
+        raise typer.BadParameter("output must stay inside the repository") from exc
+    if not relative.as_posix().startswith("tmp/"):
+        raise typer.BadParameter("output must be under tmp/")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(rendered, encoding="utf-8")
+    typer.echo(f"PROJECT_DIRECTION_RENDER\nSTATUS=PASS\nOUTPUT={relative.as_posix()}")
+
+
+@direction_app.command("audit-drift")
+def direction_audit_drift_command(
+    root: Path = typer.Option(Path("."), "--root", help="Repository root."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Report planning files that are not yet represented in project direction."""
+    result = audit_project_direction_drift(root)
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_direction_drift_audit(result), nl=False)

agentic_project_kit/cli_commands/doc_currency_audit.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from agentic_project_kit.doc_currency_audit import (
+    audit_doc_currency,
+    render_doc_currency_audit,
+)
+
+
+def audit_doc_currency_command(
+    root: Path = typer.Option(Path("."), "--root"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Audit current release/documentation currency across handoff and release docs."""
+    result = audit_doc_currency(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_currency_audit(result), nl=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)

agentic_project_kit/cli_commands/doc_registry.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agentic_project_kit.documentation_registry import (
+    build_doc_registry_reconcile_report,
+    render_doc_registry_reconcile_report,
+    build_unregistered_document_candidates_report,
+    register_documentation_registry_entry,
+)
+
+doc_registry_app = typer.Typer(help="Register reviewed documentation registry entries.")
+
+
+@doc_registry_app.command("register")
+def doc_registry_register(
+    document_path: Annotated[str, typer.Option("--path", help="Repository-relative document path.")],
+    document_class: Annotated[str, typer.Option("--class", help="Allowed documentation registry class.")],
+    owner: Annotated[str, typer.Option("--owner", help="Document owner recorded in the registry.")] = "maintainers",
+    project_root: Annotated[Path, typer.Option("--root", help="Project root.")] = Path("."),
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Add one reviewed document entry to the documentation registry."""
+    result = register_documentation_registry_entry(
+        project_root.resolve(),
+        document_path=document_path,
+        document_class=document_class,
+        owner=owner,
+    )
+    if json_output:
+        typer.echo(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        typer.echo("DOC_REGISTRY_REGISTER")
+        typer.echo(f"STATUS={result['result_status']}")
+        typer.echo(f"CODE={result['code']}")
+        typer.echo(f"PATH={result['path']}")
+        typer.echo(f"CLASS={result['class']}")
+        typer.echo(f"WRITTEN={result['written']}")
+    if result.get("result_status") != "PASS":
+        raise typer.Exit(code=1)
+
+
+
+@doc_registry_app.command("reconcile")
+def doc_registry_reconcile(
+    project_root: Annotated[Path, typer.Option("--root", help="Project root.")] = Path("."),
+    execute: Annotated[
+        bool,
+        typer.Option(
+            "--execute",
+            help="Reserved for a later slice; current implementation is dry-run only.",
+        ),
+    ] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Reconcile documentation registry, declared scope, and decision projection."""
+    if execute:
+        payload = {
+            "schema_version": 1,
+            "kind": "doc_registry_reconcile_report",
+            "result_status": "BLOCK",
+            "mode": "execute",
+            "message": "--execute is reserved for a later K2c slice; dry-run only.",
+        }
+        if json_output:
+            typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+        else:
+            typer.echo("DOC_REGISTRY_RECONCILE")
+            typer.echo("STATE: BLOCK")
+            typer.echo("MODE: execute")
+            typer.echo("MESSAGE: --execute is reserved for a later K2c slice; dry-run only.")
+        raise typer.Exit(2)
+
+    report = build_doc_registry_reconcile_report(project_root.resolve())
+    if json_output:
+        typer.echo(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_registry_reconcile_report(report))
+
+    if report["result_status"] == "BLOCK":
+        raise typer.Exit(2)
+
+@doc_registry_app.command("check-unregistered")
+def doc_registry_check_unregistered(
+    project_root: Annotated[Path, typer.Option("--root", help="Project root.")] = Path("."),
+    strict_scope: Annotated[
+        bool,
+        typer.Option(
+            "--strict-scope",
+            help="Fail when unregistered Markdown files violate declared required scope paths.",
+        ),
+    ] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """List unregistered docs candidates with optional strict declared-scope failure."""
+    report = build_unregistered_document_candidates_report(
+        project_root.resolve(),
+        strict_scope=strict_scope,
+    )
+    if json_output:
+        typer.echo(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        typer.echo("DOC_REGISTRY_UNREGISTERED")
+        typer.echo(f"STATUS={report['result_status']}")
+        typer.echo(f"CANDIDATES={report['candidate_count']}")
+        for candidate in report["candidates"]:
+            typer.echo(f"- {candidate}")
+        if report["scope_present"] and (
+            report["scope_required_path_count"]
+            or report["scope_exempt_path_count"]
+            or report["scope_violation_count"]
+            or report["scope_errors"]
+        ):
+            typer.echo(f"STRICT_SCOPE={report['strict_scope']}")
+            typer.echo(f"EXEMPTED={report['exempted_count']}")
+            typer.echo(f"SCOPE_VIOLATIONS={report['scope_violation_count']}")
+            for violation in report["scope_violations"]:
+                typer.echo(f"SCOPE-VIOLATION {violation}")
+            for error in report["scope_errors"]:
+                typer.echo(f"SCOPE-ERROR {error}")
+    if report.get("result_status") == "FAIL":
+        raise typer.Exit(code=1)

agentic_project_kit/cli_commands/docs.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agentic_project_kit.doc_lifecycle import (
+    build_doc_lifecycle_apply_payload,
+    build_doc_lifecycle_evidence_report_payload,
+    build_doc_lifecycle_plan_payload,
+    build_doc_lifecycle_triage_payload,
+    render_doc_lifecycle_apply_report,
+    render_doc_lifecycle_evidence_report_result,
+    render_doc_lifecycle_plan_report,
+    render_doc_lifecycle_triage_report,
+)
+from agentic_project_kit.doc_lifecycle_sweep import (
+    build_doc_lifecycle_bootstrap_payload,
+    build_doc_lifecycle_propose_delete_payload,
+    build_doc_lifecycle_sweep_payload,
+    json_dumps,
+    render_doc_lifecycle_bootstrap,
+    render_doc_lifecycle_propose_delete,
+    render_doc_lifecycle_sweep,
+)
+from agentic_project_kit.removed_source_audit import (
+    DEFAULT_CENTRAL_TARGET,
+    build_removed_source_audit,
+    render_removed_source_audit,
+)
+
+docs_app = typer.Typer(help="Documentation maintenance and migration guards.")
+lifecycle_app = typer.Typer(help="Safe documentation lifecycle triage and planning.")
+docs_app.add_typer(lifecycle_app, name="lifecycle")
+
+
+@lifecycle_app.command("bootstrap")
+def docs_lifecycle_bootstrap_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run/--execute", help="Preview or stamp missing lifecycle headers."),
+    ] = True,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Stamp missing lifecycle headers without claiming semantic currency."""
+    payload = build_doc_lifecycle_bootstrap_payload(
+        root.resolve(),
+        execute=not dry_run,
+    )
+    if json_output:
+        typer.echo(json_dumps(payload))
+    else:
+        typer.echo(render_doc_lifecycle_bootstrap(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+@lifecycle_app.command("propose-delete")
+def docs_lifecycle_propose_delete_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """List archive documents that may be old enough for manual deletion review."""
+    payload = build_doc_lifecycle_propose_delete_payload(root.resolve())
+    if json_output:
+        typer.echo(json_dumps(payload))
+    else:
+        typer.echo(render_doc_lifecycle_propose_delete(payload), nl=False)
+
+
+@lifecycle_app.command("sweep")
+def docs_lifecycle_sweep_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run/--execute", help="Preview or apply selected lifecycle hygiene actions."),
+    ] = True,
+    only: Annotated[
+        str,
+        typer.Option("--only", help="Comma-separated finding id(s) to execute. Required with --execute."),
+    ] = "",
+    until: Annotated[
+        str | None,
+        typer.Option("--until", help="YYYY-MM-DD deferral date for selected defer actions."),
+    ] = None,
+    review_after: Annotated[
+        str | None,
+        typer.Option("--review-after", help="Optional registry review_after value for confirm-current actions."),
+    ] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Build or apply a bounded documentation lifecycle sweep plan."""
+    payload = build_doc_lifecycle_sweep_payload(
+        root.resolve(),
+        execute=not dry_run,
+        only=only,
+        until=until,
+        review_after=review_after,
+    )
+    if json_output:
+        typer.echo(json_dumps(payload))
+    else:
+        typer.echo(render_doc_lifecycle_sweep(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+
+
+@lifecycle_app.command("apply")
+def docs_lifecycle_apply_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    scope: Annotated[str, typer.Option("--scope", help="Repository-relative documentation scope.")] = "docs",
+    only: Annotated[str, typer.Option("--only", help="Plan step id to apply.")] = "",
+    execute: Annotated[bool, typer.Option("--execute", help="Required explicit execution flag.")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Apply one safe documentation lifecycle plan step."""
+    payload = build_doc_lifecycle_apply_payload(
+        root.resolve(),
+        scope,
+        only,
+        execute=execute,
+    )
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_lifecycle_apply_report(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+
+@lifecycle_app.command("report")
+def docs_lifecycle_report_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    scope: Annotated[str, typer.Option("--scope", help="Repository-relative documentation scope.")] = "docs",
+    output: Annotated[Path, typer.Option("--output", help="Evidence JSON output path.")] = Path(
+        "docs/architecture/evidence/doc-lifecycle-report.json"
+    ),
+    execute: Annotated[bool, typer.Option("--execute", help="Write the evidence report.")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Build or write one documentation lifecycle evidence report."""
+    payload = build_doc_lifecycle_evidence_report_payload(
+        root.resolve(),
+        scope,
+        output,
+        execute=execute,
+    )
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_lifecycle_evidence_report_result(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+@lifecycle_app.command("plan")
+def docs_lifecycle_plan_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    scope: Annotated[str, typer.Option("--scope", help="Repository-relative documentation scope.")] = "docs",
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Build a dry-run lifecycle plan for one documentation scope."""
+    payload = build_doc_lifecycle_plan_payload(root.resolve(), scope)
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_lifecycle_plan_report(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+@lifecycle_app.command("triage")
+def docs_lifecycle_triage_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Propose safe documentation lifecycle actions without applying changes."""
+    payload = build_doc_lifecycle_triage_payload(root.resolve())
+    if json_output:
+        typer.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        typer.echo(render_doc_lifecycle_triage_report(payload), nl=False)
+    if payload["result_status"] == "BLOCK":
+        raise typer.Exit(code=2)
+
+
+@docs_app.command("removed-source-audit")
+def removed_source_audit_command(
+    root: Annotated[Path, typer.Option("--root", help="Repository root.")] = Path("."),
+    path: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--path",
+            help=(
+                "Repository-relative removed source path to audit. "
+                "May be supplied multiple times. Defaults to removed_source paths in PROJECT_DIRECTION.yaml."
+            ),
+        ),
+    ] = None,
+    central_target: Annotated[
+        str,
+        typer.Option("--central-target", help="Repository-relative central document that may retain removed_source metadata."),
+    ] = DEFAULT_CENTRAL_TARGET,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Fail if removed documentation sources still have live refs or registry refs."""
+    result = build_removed_source_audit(
+        root.resolve(),
+        paths=path,
+        central_target=central_target,
+    )
+    if json_output:
+        typer.echo(json.dumps(result.as_dict(), indent=2, sort_keys=True))
+    else:
+        typer.echo(render_removed_source_audit(result), nl=False)
+    if not result.ok:
+        raise typer.Exit(code=result.returncode)