backspec 0.0.1__py3-none-any.whl

backspec/host/cli.py

@@ -0,0 +1,313 @@
+"""The command line. It holds no logic: it turns flags into a Config and prints what comes back.
+Results go to stdout or the output file; progress goes to stderr."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from backspec.host.adapters.cache_admin import NotACache, describe
+from backspec.host.composition import (CAPABILITIES_FILE, Config, cache_clear, cache_info, default_previous, extract,
+                                   load_result, orient, review_requirement, status, validate, write_tree)
+from backspec.kernel.llm import LLMError
+from backspec.modules.capabilities.facade import CapabilitiesFileError
+from backspec.modules.discovery.facade import DiscoveryFacade
+from backspec.modules.lint.facade import summary as lint_summary
+from backspec.modules.report.facade import (ExtractionResult, RenderOutput, coverage_report, coverage_text, formats,
+                                        render)
+from backspec.modules.staleness.facade import summary
+from backspec.modules.review.facade import UnknownRequirement
+
+app = typer.Typer(add_completion=False, no_args_is_help=True,
+                  help="Extract user requirements from a codebase, with verified citations.")
+
+
+Include = Annotated[list[str], typer.Option("--include", help="Gitignore-style pattern to include. Repeatable.")]
+Exclude = Annotated[list[str], typer.Option("--exclude", help="Gitignore-style pattern to exclude. Repeatable.")]
+NoDefaultExcludes = Annotated[bool, typer.Option(help="Do not apply the built-in excludes.")]
+ProviderOpt = Annotated[str, typer.Option("--provider", help="Model backend.")]
+FastModel = Annotated[Optional[str], typer.Option(help="Model for observing, orienting and assigning.")]
+Concurrency = Annotated[int, typer.Option(help="Parallel model calls.")]
+CacheDir = Annotated[Optional[Path], typer.Option(help="Where to cache model replies.")]
+NoCache = Annotated[bool, typer.Option(help="Do not read or write the cache.")]
+Replay = Annotated[bool, typer.Option(help="Serve every call from the cache; fail on a miss.")]
+CapabilitiesOpt = Annotated[Optional[Path], typer.Option(
+    "--capabilities", help=f"The capabilities file. Default: {CAPABILITIES_FILE} under PATH.")]
+MULTI_FILE = ("openspec",)   # formats that write a directory tree; `-o` is then required
+ERRORS = (LLMError, OSError, ValueError)   # CapabilitiesFileError and a bad result file are ValueErrors
+
+
+def _say(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def _emit(text: str, output: Optional[Path]) -> None:
+    if output:
+        output.write_text(text, encoding="utf-8")
+        _say(f"written: {output}")
+    else:
+        typer.echo(text)
+
+
+def _check_format(fmt: str, output: Optional[Path]) -> None:
+    """Refuse an unknown format, or a multi-file format without a directory, before any work."""
+    if fmt not in formats():
+        raise typer.BadParameter(f"unknown format {fmt!r}; known formats: {', '.join(formats())}", param_hint="--format")
+    if fmt in MULTI_FILE and output is None:
+        raise typer.BadParameter(f"--format {fmt} writes several files; -o DIRECTORY is required", param_hint="-o")
+
+
+def _emit_output(rendered: RenderOutput, output: Optional[Path]) -> None:
+    if rendered.is_tree:
+        paths = write_tree(rendered.files, output)  # type: ignore[arg-type]
+        _say(f"written: {len(paths)} files under {output}")
+    else:
+        _emit(rendered.text or "", output)
+
+
+@app.command("extract")
+def extract_command(
+    path: Path = typer.Argument(..., help="The repository or directory to read."),
+    include: Include = [],
+    exclude: Exclude = [],
+    no_default_excludes: NoDefaultExcludes = False,
+    output: Optional[Path] = typer.Option(None, "-o", "--output", help="Write the result here instead of stdout."),
+    fmt: str = typer.Option("json", "--format", help="Output format: json, md, csv, html or openspec."),
+    provider: ProviderOpt = "claude-code",
+    model: Optional[str] = typer.Option(None, help="Model for synthesis and the support check."),
+    fast_model: FastModel = None,
+    no_assess_support: bool = typer.Option(False, help="Skip the support check."),
+    concurrency: Concurrency = 4,
+    cache_dir: CacheDir = None,
+    no_cache: NoCache = False,
+    replay: Replay = False,
+    capabilities: CapabilitiesOpt = None,
+    gate: bool = typer.Option(False, help="Write the capabilities file if there is none, then stop before "
+                                          "assignment and synthesis."),
+    dry_run: bool = typer.Option(False, help="List the files that would be read, and stop."),
+    review: Optional[Path] = typer.Option(None, "--review", help="The review file. Default: backspec.review.yaml in PATH, if present."),
+    no_reuse: bool = typer.Option(False, "--no-reuse", help="Read every file again, even those unchanged since "
+                                  "the previous result."),
+    previous: Optional[Path] = typer.Option(None, "--previous", help="An earlier JSON result whose ids to carry forward. "
+                                            "Default: the -o file, if it already exists."),
+    include_hidden: bool = typer.Option(False, "--include-hidden", help="csv: also list requirements rejected in review."),
+    strict: Optional[bool] = typer.Option(None, "--strict/--no-strict", help="openspec: leave out requirements with "
+                                          "no evidenced scenario (default: strict)."),
+    max_tokens: Optional[int] = typer.Option(None, "--max-tokens", min=1, help="Stop sending model calls once this "
+                                             "many tokens are used or reserved. The run is then partial."),
+    text_only: bool = typer.Option(False, "--text-only", help="Read every file as plain text, even if "
+                                   "tree-sitter is installed."),
+    no_triage: bool = typer.Option(False, "--no-triage", help="Read every file in full; skip the first look."),
+    triage_audit: float = typer.Option(0.1, "--triage-audit", metavar="FRACTION",
+                                       help="Share of the files triage skips that are read anyway, to check "
+                                            "triage. 0 turns the audit off, 1.0 reads everything triage skips."),
+) -> None:
+    """Run the pipeline on PATH."""
+    _check_format(fmt, output)
+    if not 0 <= triage_audit <= 1:
+        raise typer.BadParameter("--triage-audit must be between 0 and 1")
+    if dry_run:
+        from backspec.host.adapters.filesystem import DiskRepo
+        found = DiscoveryFacade(DiskRepo(path)).discover(include, exclude, not no_default_excludes)
+        lines = sum(len(f.lines) for f in found.files)
+        for source in found.files:
+            typer.echo(f"read      {source.path}")
+        for left in found.left:
+            typer.echo(f"{left.state:9s} {left.path}  ({left.reason})")
+        tokens = sum(len("\n".join(f.lines)) for f in found.files) // 4
+        _say(f"{len(found.files)} files, {lines} lines to read; {len(found.left)} left out. "
+             f"About {max(1, lines // 1300)} observe calls, about {tokens} tokens to read (estimated, "
+             f"characters / 4). Nothing was sent to a model.")
+        raise typer.Exit(0)
+    config = Config(include=include, exclude=exclude, default_excludes=not no_default_excludes,
+                    assess_support=not no_assess_support, provider=provider, fast_model=fast_model,
+                    strong_model=model, concurrency=concurrency, cache_dir=cache_dir,
+                    use_cache=not no_cache, replay=replay, capabilities_file=capabilities, gate=gate,
+                    review_file=review, previous=default_previous(previous, output, fmt), reuse=not no_reuse,
+                    max_tokens=max_tokens, syntax=not text_only,
+                    triage=not no_triage, triage_audit=triage_audit)
+    try:
+        result = extract(path, config, progress=_say)
+    except ERRORS as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+    _emit_output(render(result, fmt, include_hidden=include_hidden, strict=strict), output)
+    _say(f"{len(result.requirements)} requirements; {result.run.calls} model calls, "
+         f"{result.run.cached_calls} from cache; "
+         f"{result.run.input_tokens} tokens in, {result.run.output_tokens} out"
+         f"{' (estimated)' if result.run.tokens_estimated else ''}; status {result.run.status}")
+    if result.run.budget_reached:
+        _say(f"token budget reached: {result.run.input_tokens + result.run.output_tokens} tokens used "
+             f"(limit {max_tokens}); some calls were not sent and the result is partial")
+    if result.run.stopped_after:
+        _say(f"stopped after {result.run.stopped_after}, as asked by --gate")
+        raise typer.Exit(0)
+    raise typer.Exit(0 if result.run.status == "complete" else 1)
+
+
+@app.command("orient")
+def orient_command(
+    path: Path = typer.Argument(..., help="The repository or directory to read."),
+    include: Include = [],
+    exclude: Exclude = [],
+    no_default_excludes: NoDefaultExcludes = False,
+    provider: ProviderOpt = "claude-code",
+    fast_model: FastModel = None,
+    concurrency: Concurrency = 4,
+    cache_dir: CacheDir = None,
+    no_cache: NoCache = False,
+    replay: Replay = False,
+    capabilities: CapabilitiesOpt = None,
+    force: bool = typer.Option(False, "--force", help="Replace the capabilities file if it exists."),
+    text_only: bool = typer.Option(False, "--text-only", help="Read every file as plain text, even if "
+                                   "tree-sitter is installed."),
+) -> None:
+    """Propose the capabilities of PATH, write them to the capabilities file and stop."""
+    config = Config(include=include, exclude=exclude, default_excludes=not no_default_excludes, provider=provider,
+                    fast_model=fast_model, concurrency=concurrency, cache_dir=cache_dir, use_cache=not no_cache,
+                    replay=replay, capabilities_file=capabilities, syntax=not text_only)
+    try:
+        found = orient(path, config, progress=_say, force=force)
+    except (*ERRORS, FileExistsError, ValueError) as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+    for capability in found:
+        typer.echo(f"{capability.id}: {capability.name}")
+
+
+@app.command("render")
+def render_command(
+    file: Path = typer.Argument(..., help="A JSON result written by `backspec extract`."),
+    output: Optional[Path] = typer.Option(None, "-o", "--output", help="File to write; a directory for openspec."),
+    fmt: str = typer.Option("md", "--format", help="Output format: json, md, csv, html or openspec."),
+    technical: bool = typer.Option(False, help="Include technical-level requirements (md)."),
+    include_hidden: bool = typer.Option(False, "--include-hidden", help="csv: also list requirements rejected in review."),
+    strict: Optional[bool] = typer.Option(None, "--strict/--no-strict", help="openspec: leave out requirements with "
+                                          "no evidenced scenario (default: strict)."),
+    title: Optional[str] = typer.Option(None, "--title", help="html: the name shown on the page (default: the "
+                                        "name of the folder that was read)."),
+) -> None:
+    """Turn a saved JSON result into another format. No model is called."""
+    _check_format(fmt, output)
+    try:
+        result = load_result(file)
+        rendered = render(result, fmt, include_technical=technical, include_hidden=include_hidden, strict=strict,
+                          title=title)
+        _emit_output(rendered, output)
+    except (OSError, ValueError) as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+
+
+@app.command("schema")
+def schema_command() -> None:
+    """Print the JSON Schema of the result."""
+    typer.echo(json.dumps(ExtractionResult.model_json_schema(), indent=1))
+
+
+@app.command("status")
+def status_command(
+    file: Path = typer.Argument(..., help="A JSON result written by `backspec extract`."),
+    root: Path = typer.Option(Path("."), "--root", help="The repository the result was made from."),
+    as_json: bool = typer.Option(False, "--json", help="Print the report as JSON."),
+) -> None:
+    """Show which requirements rest on files that have changed or gone. No model is called."""
+    try:
+        report = status(file, root)
+    except (OSError, ValueError) as error:   # a pydantic ValidationError is a ValueError
+        _say(f"error: {file} is not a valid result: {error}")
+        raise typer.Exit(2)
+    typer.echo(report.model_dump_json(indent=1) if as_json else summary(report))
+    raise typer.Exit(0 if report.all_current else 1)
+
+
+@app.command("review")
+def review_command(
+    file: Path = typer.Argument(..., help="A JSON result written by `backspec extract`."),
+    requirement_id: str = typer.Argument(..., metavar="REQ-ID", help="The requirement to review."),
+    confirm: bool = typer.Option(False, "--confirm", help="The requirement is right."),
+    reject: bool = typer.Option(False, "--reject", help="The requirement is wrong; hide it."),
+    statement: Optional[str] = typer.Option(None, "--statement", help="Replace the statement."),
+    condition: list[str] = typer.Option([], "--condition", help="With --statement: a condition. Repeatable."),
+    reviewer: Optional[str] = typer.Option(None, "--reviewer", help="Who decided. Default: the current user."),
+    note: Optional[str] = typer.Option(None, "--note"),
+    review: Optional[Path] = typer.Option(None, "--review", help="The review file. Default: backspec.review.yaml here."),
+) -> None:
+    """Record a decision about one requirement, to be applied by later runs."""
+    try:
+        typer.echo(review_requirement(file, requirement_id, confirm=confirm, reject=reject, statement=statement,
+                                      conditions=condition, reviewer=reviewer, note=note, review_file=review))
+    except UnknownRequirement:
+        _say(f"error: {requirement_id} is not in {file}")
+        raise typer.Exit(2)
+    except (OSError, ValueError) as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+
+
+@app.command("validate")
+def validate_command(
+    file: Path = typer.Argument(..., help="A JSON result written by `backspec extract`."),
+    as_json: bool = typer.Option(False, "--json", help="Print the findings as JSON."),
+    strict: bool = typer.Option(False, "--strict", help="Count warnings as errors."),
+) -> None:
+    """Check a saved result against the schema, then lint it. No model is called."""
+    try:
+        report = validate(file)
+    except (OSError, ValueError) as error:
+        _say(f"error: {file} is not a valid result: {error}")
+        raise typer.Exit(2)
+    typer.echo(report.model_dump_json(indent=1) if as_json else lint_summary(report))
+    raise typer.Exit(1 if report.failed(strict) else 0)
+
+
+@app.command("coverage")
+def coverage_command(
+    file: Path = typer.Argument(..., help="A JSON result written by `backspec extract`."),
+    as_json: bool = typer.Option(False, "--json", help="Print the report as JSON."),
+    show_all: bool = typer.Option(False, "--all", help="Do not truncate long lists."),
+) -> None:
+    """Show what happened to every file of a saved result. No model is called."""
+    try:
+        report = coverage_report(load_result(file))
+    except (OSError, ValueError) as error:
+        _say(f"error: {file} is not a valid result: {error}")
+        raise typer.Exit(2)
+    typer.echo(report.model_dump_json(indent=1) if as_json else coverage_text(report, show_all))
+
+
+cache_app = typer.Typer(no_args_is_help=True, help="Look at or empty the cache of model replies.")
+app.add_typer(cache_app, name="cache")
+CachePath = Annotated[Path, typer.Argument(help="The repository whose cache to use.")]
+CacheDirOpt = Annotated[Optional[Path], typer.Option("--cache-dir", help="The cache folder, instead of the default for PATH.")]
+
+
+@cache_app.command("info")
+def cache_info_command(path: CachePath = Path("."), cache_dir: CacheDirOpt = None) -> None:
+    """Print the cache folder, the cached replies per stage and their size."""
+    try:
+        typer.echo(describe(cache_info(path, cache_dir)))
+    except NotACache as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+
+
+@cache_app.command("clear")
+def cache_clear_command(
+    path: CachePath = Path("."), cache_dir: CacheDirOpt = None,
+    yes: bool = typer.Option(False, "--yes", help="Actually delete. Without it, only report."),
+) -> None:
+    """Delete the cached replies of a repository. Reports only, unless --yes."""
+    try:
+        info = cache_clear(path, cache_dir, delete=yes)
+    except NotACache as error:
+        _say(f"error: {error}")
+        raise typer.Exit(2)
+    if yes:
+        typer.echo(f"deleting {info.total} cached replies ({info.size} bytes) from {info.directory}")
+        typer.echo("deleted")
+    else:
+        typer.echo(f"would delete {info.total} cached replies ({info.size} bytes) from {info.directory}; "
+                   "nothing deleted, pass --yes to delete")

backspec/host/composition.py

@@ -0,0 +1,211 @@
+"""Where the adapters are chosen and handed to the modules. Nothing else in backspec knows which
+model backend, file system or cache is in use."""
+from __future__ import annotations
+
+import datetime
+import getpass
+import hashlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from backspec.host.adapters.cache import CachedLLM
+from backspec.host.adapters import cache_admin
+from backspec.host.adapters.capabilities_file import YamlCapabilitiesFile
+from backspec.host.adapters.claude_code import ClaudeCode
+from backspec.host.adapters.codex import Codex
+from backspec.host.adapters.filesystem import DiskRepo
+from backspec.host.adapters.treesitter import TreeSitterSyntax
+from backspec.host.adapters.review_yaml import YamlReviewStore
+from backspec.kernel.llm import LLMError, LLMPort
+from backspec.modules.capabilities.facade import CapabilitiesFacade, Capability
+from backspec.modules.discovery.facade import DiscoveryFacade
+from backspec.modules.evidence.facade import EvidenceFacade
+from backspec.modules.extraction.facade import Progress, Settings, orient_only, run
+from backspec.modules.lint.facade import LintReport, lint
+from backspec.modules.report.facade import ExtractionResult
+from backspec.modules.requirements.facade import RequirementsFacade
+from backspec.modules.review.facade import ReviewFacade
+from backspec.modules.triage.facade import TriageFacade
+from backspec.modules.staleness.facade import StalenessFacade, StatusReport
+
+
+CAPABILITIES_FILE = "backspec.capabilities.yaml"
+REVIEW_FILE = "backspec.review.yaml"
+
+
+@dataclass
+class Config:
+    """Everything a run can be told. The command line and the library take the same fields."""
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    default_excludes: bool = True
+    assess_support: bool = True
+    provider: str | LLMPort = "claude-code"
+    fast_model: str | None = None
+    strong_model: str | None = None
+    concurrency: int = 4
+    cache_dir: Path | None = None
+    use_cache: bool = True
+    replay: bool = False
+    capabilities_file: Path | None = None   # default: CAPABILITIES_FILE under the root
+    gate: bool = False   # write the capabilities file if there is none, and stop before assignment
+    review_file: Path | None = None   # default: backspec.review.yaml under the root, used only if it exists
+    previous: Path | None = None      # a saved JSON result whose ids this run carries forward
+    max_tokens: int | None = None     # stop sending calls once this many tokens are spent or reserved
+    syntax: bool = True               # use symbols from tree-sitter when it is installed; False reads everything as text
+    reuse: bool = True                # keep whatever the previous result settled and whose inputs have not changed
+    triage: bool = True               # look at each file first; skip those a model is sure hold no behaviour
+    triage_audit: float = 0.1         # share of the skipped files read anyway: 0 is off, 1.0 reads them all
+
+
+def default_cache_dir(root: Path) -> Path:
+    """A folder per repository under the user's cache directory, never inside the repository."""
+    base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+    return base / "backspec" / hashlib.sha256(str(root).encode()).hexdigest()[:16]
+
+
+def _provider(config: Config) -> tuple[LLMPort, str]:
+    if not isinstance(config.provider, str):
+        return config.provider, getattr(config.provider, "name", type(config.provider).__name__)
+    if config.provider == "claude-code":
+        return ClaudeCode(config.fast_model, config.strong_model), "claude-code"
+    if config.provider == "codex":
+        return Codex(config.fast_model, config.strong_model), "codex"
+    raise LLMError(f"Unknown provider {config.provider!r}. This version ships `claude-code` and `codex`; "
+                   "pass a provider object to use another.")
+
+
+def _evidence(llm: LLMPort, config: Config) -> EvidenceFacade:
+    return EvidenceFacade(llm, config.concurrency, TreeSitterSyntax.load() if config.syntax else None)
+
+
+def _wiring(path: str | Path, config: Config):
+    root = Path(path).resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"{root} is not a directory")
+    inner, name = _provider(config)
+    directory = (config.cache_dir or default_cache_dir(root)) if config.use_cache else None
+    llm = CachedLLM(inner, directory, config.replay, config.max_tokens)
+    settings = Settings(include=config.include, exclude=config.exclude, default_excludes=config.default_excludes,
+                        assess_support=config.assess_support, gate=config.gate,
+                        triage=config.triage, triage_audit=config.triage_audit)
+    store = YamlCapabilitiesFile(config.capabilities_file or root / CAPABILITIES_FILE)
+    return root, name, llm, settings, store
+
+
+def extract(path: str | Path, config: Config | None = None, progress: Progress = lambda _: None) -> ExtractionResult:
+    """Read the code under `path` and return its requirements, observations and coverage.
+
+    A capabilities file, if there is one, is used as it is. With `Config(gate=True)` the run stops
+    once the capabilities are settled: requirements are empty, `run.status` is `partial` and
+    `run.stopped_after` is `capabilities`."""
+    config = config or Config()
+    root, name, llm, settings, store = _wiring(path, config)
+    review_path = config.review_file or root / REVIEW_FILE
+    if config.review_file and not review_path.is_file():
+        raise FileNotFoundError(f"review file not found: {review_path}")
+    review_store = YamlReviewStore(review_path) if review_path.is_file() else None
+    before = load_result(config.previous) if config.previous else None
+    if config.previous and root in Path(config.previous).resolve().parents:
+        # a result saved inside the repository is backspec's own output, never source to read
+        settings.exclude = [*settings.exclude, "/" + Path(config.previous).resolve().relative_to(root).as_posix()]
+    return run(root=root.name, provider=name, settings=settings,
+               discovery=DiscoveryFacade(DiskRepo(root)),
+               evidence=_evidence(llm, config),
+               capabilities=CapabilitiesFacade(llm, config.concurrency, store),
+               requirements=RequirementsFacade(llm, config.concurrency),
+               usage=llm.usage, spend=llm.spend, progress=progress, review=ReviewFacade(review_store), before=before,
+               reuse=config.reuse, triage=TriageFacade(llm, config.concurrency))
+
+
+def status(result: ExtractionResult | str | Path, root: str | Path = ".") -> StatusReport:
+    """Which requirements in a result rest on files that are no longer what was read.
+    `result` is an ExtractionResult or the path of a saved JSON result. No model is called."""
+    if not isinstance(result, ExtractionResult):
+        result = ExtractionResult.model_validate_json(Path(result).read_text(encoding="utf-8"))
+    return StalenessFacade(DiskRepo(root)).check(result)
+
+
+def validate(result: ExtractionResult | str | Path) -> LintReport:
+    """Deterministic checks on a result (or the path of a saved one). No model is called.
+    Raises ValueError for a file that is not a valid result."""
+    if not isinstance(result, ExtractionResult):
+        result = load_result(Path(result))
+    return lint(result)
+
+
+def cache_directory(path: str | Path = ".", cache_dir: Path | None = None) -> Path:
+    """The cache folder for the repository at `path`, as `extract` would use it."""
+    return cache_dir or default_cache_dir(Path(path).resolve())
+
+
+def cache_info(path: str | Path = ".", cache_dir: Path | None = None) -> cache_admin.CacheInfo:
+    return cache_admin.inspect(cache_directory(path, cache_dir))
+
+
+def cache_clear(path: str | Path = ".", cache_dir: Path | None = None, delete: bool = False) -> cache_admin.CacheInfo:
+    """What the cache holds, deleted when `delete`. Raises cache_admin.NotACache for a folder that is not one."""
+    return cache_admin.clear(cache_directory(path, cache_dir), delete)
+
+
+def orient(path: str | Path, config: Config | None = None, progress: Progress = lambda _: None,
+           force: bool = False) -> list[Capability]:
+    """Propose the capabilities of the code under `path` and write them to the capabilities file.
+    Raises FileExistsError if the file exists, unless `force`."""
+    config = config or Config()
+    root, _, llm, settings, store = _wiring(path, config)
+    return orient_only(settings, DiscoveryFacade(DiskRepo(root)), _evidence(llm, config),
+                       CapabilitiesFacade(llm, config.concurrency, store), force, progress)
+
+
+def load_result(file: Path) -> ExtractionResult:
+    """A saved JSON result."""
+    return ExtractionResult.model_validate_json(Path(file).read_text(encoding="utf-8"))
+
+
+def default_previous(previous: Path | None, output: Path | None, fmt: str = "json") -> Path | None:
+    """The previous result: the one named, else the JSON output file if it already exists."""
+    if previous is not None:
+        return previous
+    return output if output is not None and fmt == "json" and output.is_file() else None
+
+
+def review_requirement(file: Path, requirement_id: str, *, confirm: bool = False, reject: bool = False,
+                       statement: str | None = None, conditions: list[str] | None = None,
+                       reviewer: str | None = None, note: str | None = None,
+                       review_file: Path | None = None) -> str:
+    """Record a decision about one requirement of a saved result, and say what was written.
+    Raises UnknownRequirement for an id the result does not have, ValueError for a bad request."""
+    if confirm + reject + (statement is not None) != 1:
+        raise ValueError("give exactly one of --confirm, --reject or --statement")
+    if conditions and statement is None:
+        raise ValueError("--condition goes with --statement")
+    decision = "confirm" if confirm else "reject" if reject else "edit"
+    path = review_file or Path(REVIEW_FILE)
+    if not reviewer:
+        try:
+            reviewer = getpass.getuser()
+        except Exception:
+            reviewer = "unknown"
+    ReviewFacade(YamlReviewStore(path)).record(
+        load_result(file).requirements, requirement_id, decision,  # type: ignore[arg-type]
+        statement=statement, conditions=(conditions or []) if statement is not None else None,
+        reviewer=reviewer, date=datetime.date.today().isoformat(), note=note)
+    return f"{requirement_id}: {decision} by {reviewer} written to {path}"
+
+
+def write_tree(files: dict[str, str], directory: Path) -> list[Path]:
+    """Write a rendered set of files (relative path -> text) under `directory`. A path that
+    would leave the directory is refused before anything is written."""
+    root = Path(directory).resolve()
+    targets = {}
+    for name, text in files.items():
+        target = (root / name).resolve()
+        if root != target and root not in target.parents:
+            raise ValueError(f"refusing to write outside {directory}: {name}")
+        targets[target] = text
+    for target, text in targets.items():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+    return list(targets)

backspec/kernel/llm.py

@@ -0,0 +1,64 @@
+"""The one port every stage uses to reach a model, and the rule for reading its replies.
+
+A stage builds a prompt, says which tier it needs and what shape the answer must have. The
+pipeline, not the adapter, parses and validates the reply, and asks again when it is malformed.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Literal, Protocol, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+Tier = Literal["fast", "strong"]
+Reply = TypeVar("Reply", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class LLMRequest:
+    stage: str
+    prompt: str
+    tier: Tier = "fast"
+
+
+class LLMPort(Protocol):
+    def complete(self, request: LLMRequest) -> str:
+        """The model's reply as text. Raises LLMError when no reply could be had."""
+        ...
+
+
+class LLMError(Exception):
+    """The model could not be reached, or never gave a reply in the required shape."""
+
+
+def extract_json(text: str) -> object:
+    """The JSON value in a reply, whether bare, fenced, or surrounded by a sentence or two."""
+    text = text.strip()
+    fenced = re.search(r"```(?:json)?\s*\n(.*?)\n```", text, re.DOTALL)
+    if fenced:
+        text = fenced.group(1).strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        start, end = text.find("{"), text.rfind("}")
+        if start == -1 or end <= start:
+            raise
+        return json.loads(text[start:end + 1])
+
+
+def ask(llm: LLMPort, request: LLMRequest, shape: type[Reply], retries: int = 2) -> Reply:
+    """Ask until the reply parses as `shape`, at most `retries` more times, telling the model
+    what was wrong with its last attempt."""
+    prompt = request.prompt
+    problem = ""
+    for _ in range(retries + 1):
+        text = llm.complete(LLMRequest(request.stage, prompt, request.tier))
+        try:
+            return shape.model_validate(extract_json(text))
+        except (json.JSONDecodeError, ValidationError) as error:
+            problem = str(error)[:1500]
+            prompt = (f"{request.prompt}\n\nYour previous reply could not be used:\n{problem}\n"
+                      "Reply again with the JSON only, in exactly the shape asked for.")
+    raise LLMError(f"{request.stage}: no usable reply after {retries + 1} attempts: {problem}")

backspec/kernel/prompts.py

@@ -0,0 +1,10 @@
+"""The prompt templates, shipped with the package. PROMPT_VERSION changes whenever one does."""
+from __future__ import annotations
+
+from importlib import resources
+
+PROMPT_VERSION = "2026-11-d"
+
+
+def load(name: str) -> str:
+    return resources.files("backspec.prompts").joinpath(f"{name}.md").read_text(encoding="utf-8")

backspec/kernel/templates.py

@@ -0,0 +1,12 @@
+"""The page templates, shipped with the package."""
+from __future__ import annotations
+
+from importlib import resources
+
+
+def load(name: str) -> str:
+    return resources.files("backspec.templates").joinpath(name).read_text(encoding="utf-8")
+
+
+def load_bytes(name: str) -> bytes:
+    return resources.files("backspec.templates").joinpath(name).read_bytes()

backspec/kernel/text.py

@@ -0,0 +1,23 @@
+"""Small text helpers shared by every module."""
+from __future__ import annotations
+
+import hashlib
+import re
+
+
+def squash(text: str) -> str:
+    """Text with every run of whitespace as one space, for comparing quotes with code."""
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def numbered(lines: list[str], first: int) -> list[str]:
+    """Lines prefixed with their real line number. A model copies the number; it never counts."""
+    return [f"{first + offset:5d}| {line}" for offset, line in enumerate(lines)]
+
+
+def short_hash(*parts: object) -> str:
+    return hashlib.sha256("|".join(str(part) for part in parts).encode()).hexdigest()[:8]
+
+
+def sha256(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode()).hexdigest()