antemortem 0.2.0__py3-none-any.whl

antemortem/__init__.py

@@ -0,0 +1,6 @@
+"""Antemortem CLI — tooling for the Antemortem pre-implementation reconnaissance discipline.
+
+See https://github.com/hibou04-ops/Antemortem for the methodology.
+"""
+
+__version__ = "0.2.0"

antemortem/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m antemortem`."""
+
+from antemortem.cli import app
+
+if __name__ == "__main__":
+    app()

antemortem/api.py

@@ -0,0 +1,159 @@
+"""Anthropic Claude API wrapper for the classification step.
+
+The ``run_classification`` function is the single boundary between the CLI
+and the Anthropic SDK. Everything else in the package is framework-free and
+testable without the network. Tests mock the ``client`` argument.
+
+Caching strategy:
+- The system prompt is rendered with ``cache_control={"type": "ephemeral"}``
+  on a top-level system text block. On Opus 4.7 this requires the prompt to
+  exceed the 4096-token cacheable-prefix minimum; we size ``SYSTEM_PROMPT``
+  accordingly and verify via ``usage.cache_read_input_tokens`` on each call.
+- The user payload carries no caching control — it's volatile (different
+  traps each run). A second breakpoint on the files block is a v0.2.1
+  optimization when we add iterative-run UX.
+
+Model and sampling:
+- ``claude-opus-4-7`` is the only supported model in v0.2 (matches Antemortem
+  discipline + enforces a known behavioral contract for the prompt).
+- No ``temperature`` / ``top_p`` / ``top_k`` — removed on Opus 4.7.
+- ``thinking={"type": "adaptive"}`` — off by default on 4.7; explicitly
+  enabled because classification benefits from multi-file chain tracing.
+- ``output_config={"effort": "high"}`` — minimum recommended for
+  intelligence-sensitive work per Anthropic's migration guide.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from antemortem.prompts import SYSTEM_PROMPT
+from antemortem.schema import AntemortemOutput
+
+MODEL = "claude-opus-4-7"
+DEFAULT_MAX_TOKENS = 16000
+
+
+class _MessagesNamespace(Protocol):
+    """Duck-typed interface for the subset of ``anthropic.messages`` we use.
+
+    Accepting a Protocol rather than the concrete class keeps the hot path
+    testable without importing ``anthropic`` in unit tests.
+    """
+
+    def parse(self, **kwargs: Any) -> Any: ...  # noqa: D401
+
+
+class _AnthropicLike(Protocol):
+    """Minimal interface we need from an Anthropic client instance."""
+
+    messages: _MessagesNamespace
+
+
+def _build_user_content(
+    spec: str,
+    traps_table_md: str,
+    files: list[tuple[str, str]],
+) -> str:
+    """Render the user-turn payload as the prompt expects."""
+    file_blocks: list[str] = []
+    for path, content in sorted(files, key=lambda item: item[0]):
+        # Normalize path separators so cache keys don't drift on Windows.
+        normalized = path.replace("\\", "/")
+        file_blocks.append(f'<file path="{normalized}">\n{content}\n</file>')
+    files_section = "\n".join(file_blocks)
+    return (
+        f"<files>\n{files_section}\n</files>\n\n"
+        f"<spec>\n{spec.strip()}\n</spec>\n\n"
+        f"<traps>\n{traps_table_md.strip()}\n</traps>"
+    )
+
+
+def _usage_to_dict(usage: Any) -> dict[str, int]:
+    """Extract token counts from the SDK's usage object into a plain dict."""
+    return {
+        "input_tokens": getattr(usage, "input_tokens", 0) or 0,
+        "output_tokens": getattr(usage, "output_tokens", 0) or 0,
+        "cache_creation_input_tokens": getattr(usage, "cache_creation_input_tokens", 0) or 0,
+        "cache_read_input_tokens": getattr(usage, "cache_read_input_tokens", 0) or 0,
+    }
+
+
+def run_classification(
+    client: _AnthropicLike,
+    spec: str,
+    traps_table_md: str,
+    files: list[tuple[str, str]],
+    *,
+    max_tokens: int = DEFAULT_MAX_TOKENS,
+) -> tuple[AntemortemOutput, dict[str, int]]:
+    """Call Claude Opus 4.7 to classify traps against provided files.
+
+    Parameters
+    ----------
+    client:
+        An ``anthropic.Anthropic`` instance (or duck-typed equivalent for
+        tests).
+    spec:
+        Text of the change description from the antemortem document.
+    traps_table_md:
+        The pre-recon Traps table as a markdown string (raw, including
+        header row).
+    files:
+        List of ``(path, content)`` pairs. Sorted internally so cache
+        behavior is deterministic regardless of caller ordering.
+    max_tokens:
+        Upper bound on output tokens. Defaults to 16000 — the ~8k-output
+        typical classification response has ample headroom.
+
+    Returns
+    -------
+    A tuple ``(output, usage)``:
+
+    - ``output``: a validated ``AntemortemOutput`` instance.
+    - ``usage``: ``{"input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"}``.
+    """
+    user_content = _build_user_content(spec, traps_table_md, files)
+
+    response = client.messages.parse(
+        model=MODEL,
+        max_tokens=max_tokens,
+        thinking={"type": "adaptive"},
+        output_config={"effort": "high"},
+        system=[
+            {
+                "type": "text",
+                "text": SYSTEM_PROMPT,
+                "cache_control": {"type": "ephemeral"},
+            }
+        ],
+        messages=[{"role": "user", "content": user_content}],
+        output_format=AntemortemOutput,
+    )
+
+    stop_reason = getattr(response, "stop_reason", None)
+    if stop_reason == "refusal":
+        text = ""
+        for block in getattr(response, "content", []) or []:
+            if getattr(block, "type", None) == "text":
+                text = getattr(block, "text", "")
+                break
+        raise RuntimeError(
+            "Claude refused the classification request. This usually means the "
+            "spec or traps contain content flagged by safety filters. "
+            f"Response text: {text!r}"
+        )
+
+    parsed: AntemortemOutput | None = getattr(response, "parsed_output", None)
+    if parsed is None:
+        raise RuntimeError(
+            "SDK returned no parsed_output. This indicates a schema mismatch or "
+            "a malformed response. Raw stop_reason: "
+            f"{stop_reason!r}"
+        )
+    if not isinstance(parsed, AntemortemOutput):
+        # Some SDK versions may pass through a dict — coerce defensively.
+        parsed = AntemortemOutput.model_validate(parsed)
+
+    usage = _usage_to_dict(getattr(response, "usage", None))
+    return parsed, usage

antemortem/citations.py

@@ -0,0 +1,135 @@
+"""Citation parsing and on-disk verification.
+
+The discipline requires every classification to carry a ``path:line`` or
+``path:line-line`` citation. This module parses those strings, resolves them
+against a repository root, and verifies the cited line range lies within the
+file's actual bounds. It does not execute any cited code — read-only checks.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_CITATION_RE = re.compile(
+    r"""^\s*
+    (?P<path>[^\s:]+(?:[^\s:]+)*)      # non-whitespace, non-colon path
+    :
+    (?P<start>\d+)                       # start line (required)
+    (?:-(?P<end>\d+))?                   # optional end line
+    \s*$""",
+    re.VERBOSE,
+)
+
+
+@dataclass(frozen=True)
+class ParsedCitation:
+    """A parsed citation reference."""
+
+    path: str
+    start: int
+    end: int  # equals start for single-line citations
+
+
+@dataclass(frozen=True)
+class VerificationResult:
+    """Outcome of verifying a citation against disk."""
+
+    ok: bool
+    reason: str = ""
+    parsed: ParsedCitation | None = None
+
+
+def parse_citation(citation: str) -> ParsedCitation | None:
+    """Parse a ``path:line`` or ``path:line-line`` citation string.
+
+    Returns ``None`` when the citation does not match the expected shape.
+    """
+    if not citation:
+        return None
+    # Normalize Windows backslashes to forward slashes for uniform handling.
+    normalized = citation.replace("\\", "/").strip()
+    match = _CITATION_RE.match(normalized)
+    if match is None:
+        return None
+
+    start = int(match.group("start"))
+    end_raw = match.group("end")
+    end = int(end_raw) if end_raw is not None else start
+
+    if start < 1 or end < start:
+        return None
+
+    return ParsedCitation(path=match.group("path"), start=start, end=end)
+
+
+def count_lines(path: Path) -> int:
+    """Count newline-terminated lines in a file. Tolerates non-UTF-8 encodings."""
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            return sum(1 for _ in fh)
+    except UnicodeDecodeError:
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            return sum(1 for _ in fh)
+
+
+def verify_citation(citation: str, repo_root: Path) -> VerificationResult:
+    """Check that ``citation`` resolves to a real file:line range within ``repo_root``.
+
+    Returns a ``VerificationResult`` whose ``ok`` field signals whether the
+    citation is valid. When ``ok`` is false, ``reason`` explains the failure in
+    one line suitable for CLI output.
+    """
+    parsed = parse_citation(citation)
+    if parsed is None:
+        return VerificationResult(
+            ok=False,
+            reason=f"invalid format — expected 'path:line' or 'path:line-line', got {citation!r}",
+        )
+
+    file_path = (repo_root / parsed.path).resolve()
+    try:
+        root_resolved = repo_root.resolve()
+    except FileNotFoundError:
+        return VerificationResult(
+            ok=False,
+            reason=f"--repo directory does not exist: {repo_root}",
+            parsed=parsed,
+        )
+
+    # Refuse paths that escape the repo root via '..' traversal.
+    try:
+        file_path.relative_to(root_resolved)
+    except ValueError:
+        return VerificationResult(
+            ok=False,
+            reason=f"cited path escapes repo root: {parsed.path!r}",
+            parsed=parsed,
+        )
+
+    if not file_path.exists():
+        return VerificationResult(
+            ok=False,
+            reason=f"cited file does not exist: {parsed.path}",
+            parsed=parsed,
+        )
+    if not file_path.is_file():
+        return VerificationResult(
+            ok=False,
+            reason=f"cited path is not a regular file: {parsed.path}",
+            parsed=parsed,
+        )
+
+    line_count = count_lines(file_path)
+    if parsed.start > line_count or parsed.end > line_count:
+        return VerificationResult(
+            ok=False,
+            reason=(
+                f"line {parsed.start}-{parsed.end} out of range "
+                f"(file {parsed.path} has {line_count} lines)"
+            ),
+            parsed=parsed,
+        )
+
+    return VerificationResult(ok=True, parsed=parsed)

antemortem/cli.py

@@ -0,0 +1,44 @@
+"""Top-level Typer application for the antemortem CLI."""
+
+import typer
+
+from antemortem import __version__
+from antemortem.commands import init as init_cmd
+from antemortem.commands import lint as lint_cmd
+from antemortem.commands import run as run_cmd
+
+app = typer.Typer(
+    name="antemortem",
+    help="CLI for the Antemortem pre-implementation reconnaissance discipline.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"antemortem {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(  # noqa: B008
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Antemortem — scaffold, run, and lint pre-implementation recon documents."""
+
+
+app.command(name="init", help="Scaffold a new antemortem document from a template.")(init_cmd.init)
+app.command(name="run", help="Run LLM-assisted classification on an antemortem document.")(run_cmd.run)
+app.command(name="lint", help="Validate an antemortem document's schema and citations.")(lint_cmd.lint)
+
+
+if __name__ == "__main__":
+    app()

antemortem/commands/__init__.py

@@ -0,0 +1 @@
+"""Subcommand modules for the antemortem CLI."""

antemortem/commands/init.py

@@ -0,0 +1,84 @@
+"""`antemortem init` — scaffold a new antemortem document from a template."""
+
+from datetime import date
+from pathlib import Path
+
+import typer
+
+from antemortem.templates import get_template
+
+
+def _build_frontmatter(
+    name: str,
+    today: str,
+    enhanced: bool,
+) -> str:
+    template_label = "enhanced" if enhanced else "basic"
+    return (
+        "---\n"
+        f"name: {name}\n"
+        f"date: {today}\n"
+        "scope: change-local\n"
+        "reversibility: high\n"
+        "status: draft\n"
+        f"template: {template_label}\n"
+        "---\n\n"
+    )
+
+
+def init(
+    name: str = typer.Argument(  # noqa: B008
+        ...,
+        help="Short name for the change (used as filename). Example: my-feature, auth-refactor.",
+    ),
+    enhanced: bool = typer.Option(  # noqa: B008
+        False,
+        "--enhanced",
+        "-e",
+        help="Use the enhanced template (calibration dimensions, skeptic pass, decision-first output).",
+    ),
+    output_dir: Path = typer.Option(  # noqa: B008
+        Path("antemortem"),
+        "--output-dir",
+        "-o",
+        help="Directory to create the document in. Created if missing.",
+        file_okay=False,
+        dir_okay=True,
+    ),
+    force: bool = typer.Option(  # noqa: B008
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing document if present.",
+    ),
+) -> None:
+    """Create antemortem/<name>.md with YAML frontmatter and the chosen template."""
+    if not name or any(ch in name for ch in ("/", "\\", "..")):
+        typer.secho(
+            f"Invalid name {name!r}: use a simple identifier (letters, digits, hyphens).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    target = output_dir / f"{name}.md"
+
+    if target.exists() and not force:
+        typer.secho(
+            f"Refusing to overwrite {target} — pass --force to replace.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    today = date.today().isoformat()
+    content = _build_frontmatter(name, today, enhanced) + get_template(enhanced)
+    target.write_text(content, encoding="utf-8")
+
+    label = "enhanced" if enhanced else "basic"
+    typer.secho(f"Created {target} ({label} template)", fg=typer.colors.GREEN)
+    typer.secho(
+        "Next: fill in the spec, enumerate traps, then run `antemortem run` to classify.",
+        fg=typer.colors.BRIGHT_BLACK,
+    )

antemortem/commands/lint.py

@@ -0,0 +1,160 @@
+"""`antemortem lint` — schema and citation validation.
+
+Two tiers of checks:
+
+1. **Document schema**: YAML frontmatter parses, spec is non-empty, at least
+   one trap row is present, and at least one file is listed under the Recon
+   protocol. These apply to every antemortem document.
+2. **Classification verification**: if a companion ``<doc>.json`` audit
+   artifact exists (produced by ``antemortem run``), validate that every
+   input trap has a classification, every citation parses, and every
+   ``file:line`` points to an existing line within ``--repo``.
+
+Exit 0 on pass, 1 on failure. Suitable for CI.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import NamedTuple
+
+import typer
+from pydantic import ValidationError
+
+from antemortem.citations import verify_citation
+from antemortem.parser import DocumentParseError, parse_document
+from antemortem.schema import AntemortemDocument, AntemortemOutput
+
+
+class LintResult(NamedTuple):
+    """Outcome of a lint pass."""
+
+    ok: bool
+    violations: list[str]
+    checked: int  # number of checks that ran (passed or failed)
+
+
+def _lint_document(doc: AntemortemDocument) -> list[str]:
+    """Pre-run schema checks that apply to every antemortem document."""
+    violations: list[str] = []
+    if not doc.spec.strip():
+        violations.append("spec: '## 1. The change' section is empty or missing")
+    if not doc.traps:
+        violations.append("traps: no rows parsed from the pre-recon Traps table")
+    if not doc.files_to_read:
+        violations.append("files_to_read: no files listed under 'Recon protocol'")
+    return violations
+
+
+def _lint_artifact(
+    artifact_path: Path,
+    doc: AntemortemDocument,
+    repo_root: Path,
+) -> list[str]:
+    """Post-run checks that apply when a JSON audit artifact exists."""
+    violations: list[str] = []
+    try:
+        payload = json.loads(artifact_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [f"{artifact_path.name}: invalid JSON — {exc.msg} at line {exc.lineno}"]
+    except OSError as exc:
+        return [f"{artifact_path.name}: cannot read — {exc}"]
+
+    try:
+        output = AntemortemOutput.model_validate(payload)
+    except ValidationError as exc:
+        return [f"{artifact_path.name}: schema validation failed — {exc.error_count()} issues"]
+
+    trap_ids = {t.id for t in doc.traps}
+    classified_ids = {c.id for c in output.classifications}
+
+    for missing in sorted(trap_ids - classified_ids):
+        violations.append(f"classification: missing for trap {missing}")
+
+    for c in output.classifications:
+        if c.id not in trap_ids:
+            violations.append(
+                f"classification {c.id}: refers to a trap id not present in the input table"
+            )
+        if c.label == "UNRESOLVED":
+            if c.citation is not None:
+                violations.append(
+                    f"classification {c.id}: UNRESOLVED must have citation=null (got {c.citation!r})"
+                )
+            continue
+        if not c.citation:
+            violations.append(f"classification {c.id}: citation is required for {c.label}")
+            continue
+        result = verify_citation(c.citation, repo_root)
+        if not result.ok:
+            violations.append(f"classification {c.id}: {result.reason}")
+
+    for nt in output.new_traps:
+        result = verify_citation(nt.citation, repo_root)
+        if not result.ok:
+            violations.append(f"new_trap {nt.id}: {result.reason}")
+
+    return violations
+
+
+def run_lint(
+    document: Path,
+    repo_root: Path,
+) -> LintResult:
+    """Programmatic lint entry point. Returns ``LintResult`` without exiting."""
+    try:
+        doc = parse_document(document)
+    except DocumentParseError as exc:
+        return LintResult(ok=False, violations=[f"document: {exc}"], checked=1)
+
+    violations = _lint_document(doc)
+
+    artifact_path = document.with_suffix(".json")
+    ran_artifact = artifact_path.exists()
+    if ran_artifact:
+        violations.extend(_lint_artifact(artifact_path, doc, repo_root))
+
+    checked = 3 + (1 if ran_artifact else 0)  # spec, traps, files, (+ artifact)
+    return LintResult(ok=len(violations) == 0, violations=violations, checked=checked)
+
+
+def lint(
+    document: Path = typer.Argument(  # noqa: B008
+        ...,
+        help="Path to the antemortem document to validate.",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    repo: Path = typer.Option(  # noqa: B008
+        Path.cwd(),
+        "--repo",
+        "-r",
+        help="Repository root to resolve cited files against. Defaults to current directory.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+    ),
+) -> None:
+    """Validate schema and verify file:line citations."""
+    result = run_lint(document, repo)
+    artifact_note = (
+        " (schema + classifications)"
+        if document.with_suffix(".json").exists()
+        else " (schema only; no audit artifact)"
+    )
+
+    if result.ok:
+        typer.secho(
+            f"PASS — {document.name} validates clean{artifact_note}",
+            fg=typer.colors.GREEN,
+        )
+        raise typer.Exit(code=0)
+
+    typer.secho(f"FAIL — {document.name}{artifact_note}", fg=typer.colors.RED, err=True)
+    for v in result.violations:
+        typer.secho(f"  - {v}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)