constant-docs 0.4.0__py3-none-any.whl

constant_docs/cli.py

@@ -0,0 +1,1085 @@
+"""Command-line interface for constant-docs.
+
+Usage::
+
+    constant-docs verify [--json] [<config>]
+    constant-docs plan [--json] [<config>]
+    constant-docs apply <module> <body> [<config>] [--retire <id>]...
+    constant-docs append <module> <title> <entry> [<config>]
+    constant-docs add <name> [<config>] [--glob <p>]... [--covers <m>]... [--kind <k>]
+    constant-docs prune [<config>]
+    constant-docs index [<config>]
+    constant-docs mark [<path>...]
+    constant-docs settle [--json] [--hook]
+    constant-docs prompt [<kind>]
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from constant_docs import __version__, state
+from constant_docs.api import _resolve_config as discover_config
+from constant_docs.api import append, apply, plan, prune, settle
+from constant_docs.api import verify as verify_api
+from constant_docs.config import MISSING_KEY, ConfigError, add_module
+from constant_docs.config import load as load_config
+from constant_docs.decisions import DecisionError
+from constant_docs.document import DocumentError
+from constant_docs.globs import GlobError
+from constant_docs.index import write as index_write
+from constant_docs.kinds import (
+    BUILTIN_KINDS,
+    DEFAULT_KIND,
+    KindError,
+    guide_names,
+    guide_path,
+    resolve_prompt,
+)
+
+_CONFIG_PATH = Path("constant-docs.yaml")
+
+# What `init` writes when there is nothing. `modules: {}` is explicit rather
+# than omitted: an absent key stays an error, so that a mistyped one cannot
+# load as a repository where every check passes and nothing is checked.
+_BLANK_CONFIG = """version: 1
+
+# Where documents are written. Everything under it is excluded from every glob.
+docs_root: docs
+
+# Module key to glob. The key is the document's path stem, so `src/payments`
+# writes `docs/src/payments.md`. Add one with:
+#
+#   constant-docs add src/payments --glob 'src/payments/**/*.py'
+modules: {}
+
+# Glob to the reason it deliberately carries no document. A reason is required:
+# an exclusion nobody justified is one nobody decided.
+#
+# uncovered:
+#   "tests/fixtures/**": Test data rather than source
+"""
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "module.md"
+
+# Block counter sentinel: the guard has already released this exact set of
+# stale modules, and must not block on it again until the work changes.
+_RELEASED = -1
+
+
+def _resolve_config(path: str | None) -> Path:
+    """Return the config path, discovered from the working directory.
+
+    A hook's working directory is not guaranteed to be the repository root,
+    so discovery walks up rather than assuming.
+
+    Discovery's own `ConfigError` propagates. Catching it and substituting
+    `constant-docs.yaml` threw away the sentence that says a parent walk ran
+    and failed, and replaced it with one naming a relative path nothing had
+    looked for — indistinguishable from "you passed a path and it is missing".
+    Every subcommand already handles a `ConfigError`, and the two that must be
+    silent outside a repository test its key.
+    """
+    if path:
+        return Path(path)
+    return discover_config(None)
+
+
+def _take_repeated(args: list[str], flag: str) -> list[str]:
+    """Remove every ``--flag <value>`` pair from *args* and return the values.
+
+    Written by hand rather than reached for through `argparse`, because the
+    rest of this CLI parses positionally and mixing the two produces a help
+    text that describes neither. A flag with no value is an error rather than
+    a silently ignored trailing token: `--retire` with nothing after it means
+    the caller believes a retirement was declared.
+    """
+    values: list[str] = []
+    index = 0
+    while index < len(args):
+        if args[index] != flag:
+            index += 1
+            continue
+        if index + 1 >= len(args):
+            raise ValueError(f"{flag} needs a value")
+        values.append(args[index + 1])
+        del args[index : index + 2]
+    return values
+
+
+def _exit_ok(data: Any = None) -> None:
+    """Print *data* as JSON if it's not None, then exit 0."""
+    if data is not None:
+        print(json.dumps(data, indent=2, default=str))
+    sys.exit(0)
+
+
+def _exit_drift(drift_report: Any) -> None:
+    """Print the drift report as JSON, exit 1."""
+    print(json.dumps(drift_report, indent=2, default=str))
+    sys.exit(1)
+
+
+def _exit_config_error(message: str) -> None:
+    """Print the error, exit 2."""
+    print(f"Configuration error: {message}", file=sys.stderr)
+    sys.exit(2)
+
+
+# What an exception that reached `main` unhandled is worth as an exit code.
+# 1 is drift and belongs to `verify` alone; anything that got this far is a
+# refusal or a crash, and both are 2. A scheduler tells those apart by the
+# code and nothing else.
+_EXIT_CODES: tuple[tuple[type[BaseException], int], ...] = (
+    (ConfigError, 2),
+    (DecisionError, 2),
+    (DocumentError, 2),
+    (KindError, 2),
+)
+_UNEXPECTED_EXIT = 2
+
+
+def _exit_code_for(exc: BaseException) -> int:
+    """Return the exit code for an exception that reached the top level."""
+    for exc_type, code in _EXIT_CODES:
+        if isinstance(exc, exc_type):
+            return code
+    return _UNEXPECTED_EXIT
+
+
+def cmd_verify(
+    config_path: str | None, json_output: bool, coverage: bool = False
+) -> None:
+    """Run verification and report drift."""
+    try:
+        report = verify_api(_resolve_config(config_path), coverage=coverage)
+    except ConfigError as e:
+        _exit_config_error(str(e))
+
+    if json_output:
+        payload = {
+            "exit_code": report.exit_code,
+            "stale": report.stale,
+            "missing": report.missing,
+            "orphans": [
+                {
+                    "doc_path": str(o.doc_path),
+                    "module_key": o.module_key,
+                    "probable_move": o.probable_move,
+                    "probable_moves": o.probable_moves,
+                }
+                for o in report.orphans
+            ],
+            "fresh": report.fresh,
+            "conformance_issues": report.conformance_issues,
+            "content_issues": report.content_issues,
+            "coverage_gaps": report.coverage_gaps,
+        }
+        if report.exit_code == 0:
+            _exit_ok(payload)
+        else:
+            _exit_drift(payload)
+    else:
+        if report.exit_code == 0:
+            print("All modules up to date.")
+            sys.exit(0)
+        if report.stale:
+            print("Stale modules:", ", ".join(report.stale))
+        if report.missing:
+            print("Missing documents:", ", ".join(report.missing))
+        if report.orphans:
+            print(f"Orphaned documents ({len(report.orphans)}):")
+            for o in report.orphans:
+                if o.probable_move:
+                    print(f"  {o.doc_path} → probably now {o.probable_move}")
+                elif o.probable_moves:
+                    candidates = ", ".join(o.probable_moves)
+                    print(f"  {o.doc_path} → one of {candidates}, cannot tell")
+                else:
+                    print(f"  {o.doc_path}")
+        if report.conformance_issues:
+            print(f"Conformance issues ({len(report.conformance_issues)}):")
+            for issue in report.conformance_issues:
+                print(f"  {issue}")
+        if report.content_issues:
+            print(f"Content issues ({len(report.content_issues)}):")
+            for issue in report.content_issues:
+                print(f"  {issue}")
+        if report.coverage_gaps:
+            print(f"Uncovered source ({len(report.coverage_gaps)}):")
+            for gap in report.coverage_gaps:
+                print(f"  {gap}")
+        sys.exit(report.exit_code)
+
+
+def cmd_plan(config_path: str | None, json_output: bool) -> None:
+    """Inspect and report the current state."""
+    try:
+        p = plan(_resolve_config(config_path))
+    except ConfigError as e:
+        _exit_config_error(str(e))
+
+    if json_output:
+        _exit_ok(_plan_payload(p))
+    else:
+        if p.stale:
+            for m in p.stale:
+                print(f"[{m.reason}] {m.module} ({m.kind}) → {m.doc_path}")
+        if p.fresh:
+            for f in p.fresh:
+                print(f"[fresh] {f}")
+        if p.orphans:
+            for o in p.orphans:
+                print(f"[orphan] {o.doc_path}")
+        if not p.stale and not p.orphans:
+            print("Everything up to date.")
+        sys.exit(0)
+
+
+def cmd_apply(
+    config_path: str | None,
+    module_key: str,
+    body_text: str,
+    retire: list[str] | None = None,
+) -> None:
+    """Write a body to a module document."""
+    try:
+        config = _resolve_config(config_path)
+        apply(module_key, body_text, config_path=config, retire=retire or [])
+        print(f"Applied {module_key}.")
+    except ConfigError as e:
+        _exit_config_error(str(e))
+    except DecisionError as e:
+        # Its own clause rather than falling into the generic one, because
+        # the caller's next move depends on which decisions are at fault and
+        # a truncated message costs them a round trip.
+        print(f"Refused: {e}", file=sys.stderr)
+        sys.exit(2)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except DocumentError as e:
+        print(f"Document error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_append(
+    config_path: str | None, module_key: str, title: str, entry: str
+) -> None:
+    """Add one entry to an append-mode document."""
+    try:
+        append(module_key, entry, title, config_path=_resolve_config(config_path))
+        print(f"Appended to {module_key}.")
+    except ConfigError as e:
+        _exit_config_error(str(e))
+    except DecisionError as e:
+        # The same clause `cmd_apply` has. `DuplicateDecision` is a
+        # `DecisionError` and deliberately not a `DocumentError`, so it fell
+        # past all three clauses to the blanket handler and reported a refused
+        # write as exit 1 — the code this tool defines as drift, which a
+        # harness answers by retrying.
+        print(f"Refused: {e}", file=sys.stderr)
+        sys.exit(2)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except DocumentError as e:
+        print(f"Document error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_add(
+    config_path: str | None,
+    name: str,
+    globs: list[str],
+    covers: list[str],
+    kind: str,
+) -> int:
+    """Register a document in the configuration."""
+    try:
+        add_module(
+            _resolve_config(config_path),
+            name,
+            globs=globs,
+            covers=covers,
+            kind=kind,
+        )
+    except ConfigError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 2
+    print(f"Added {name}.")
+    return 0
+
+
+def cmd_auto(config_path: str | None, json_output: bool) -> int:
+    """Settle, run the configured command, verify, and report.
+
+    Exit codes are the tool's usual three and must not collapse: 0 clean
+    afterwards, 1 still stale, 2 could not run. A command that ran and achieved
+    nothing is a working automation producing no result; one that could not run
+    is a broken automation. A scheduler that cannot tell them apart retries the
+    wrong one.
+    """
+    from constant_docs.auto import run as run_auto
+
+    try:
+        resolved = _resolve_config(config_path)
+        cfg = load_config(resolved)
+    except ConfigError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 2
+
+    if cfg.auto is None:
+        print(
+            "No 'auto' block in the configuration. Declare the command to run:"
+            "\n\n  auto:\n    command: \"<your agent> -p 'Run the constant-docs "
+            "settle loop'\"\n",
+            file=sys.stderr,
+        )
+        return 2
+
+    outcome = run_auto(cfg, resolved.resolve().parent, resolved)
+
+    if json_output:
+        print(
+            json.dumps(
+                {
+                    "exit_code": outcome.exit_code,
+                    "attempted": outcome.attempted,
+                    "ran": outcome.ran,
+                    "command_exit": outcome.command_exit,
+                    "selected": outcome.selected,
+                    "skipped": outcome.skipped,
+                    "still_stale": outcome.still_stale,
+                    "clean": outcome.clean,
+                },
+                indent=2,
+            )
+        )
+        return outcome.exit_code
+
+    if not outcome.attempted:
+        if outcome.clean:
+            print("Nothing stale; the command was not run.")
+        else:
+            # Nothing to regenerate and still not passing. Saying so is the
+            # whole point: the previous wording reported a clean repository
+            # on the strength of the one check that happened to pass.
+            print(
+                "Nothing stale, but `verify` still fails. Run "
+                "`constant-docs verify` for the orphans, conformance or "
+                "content issues behind it.",
+                file=sys.stderr,
+            )
+        return outcome.exit_code
+    if not outcome.ran:
+        print(
+            f"Could not run {cfg.auto.command!r}. Nothing was regenerated.",
+            file=sys.stderr,
+        )
+        return outcome.exit_code
+
+    if outcome.command_exit:
+        print(
+            f"The command exited {outcome.command_exit}. Nothing is assumed "
+            f"about what it did.",
+            file=sys.stderr,
+        )
+
+    if outcome.skipped:
+        # Named, never silent: a cap nobody is told about reads as
+        # "everything was covered".
+        print(
+            f"Budget of {cfg.auto.budget} reached. Left for the next run "
+            f"({len(outcome.skipped)}): " + ", ".join(outcome.skipped)
+        )
+
+    if outcome.clean:
+        print(f"Regenerated {len(outcome.selected)}; everything is current.")
+    elif outcome.still_stale:
+        print("Still stale: " + ", ".join(outcome.still_stale))
+    else:
+        # Not clean, nothing stale: a non-zero exit with no diagnosis is an
+        # operator re-running `verify` by hand to find out what happened.
+        print(
+            "Nothing is stale, but `verify` still fails. Run "
+            "`constant-docs verify` for what is left.",
+            file=sys.stderr,
+        )
+
+    return outcome.exit_code
+
+
+def cmd_coverage(config_path: str | None, json_output: bool) -> int:
+    """Report source that no module covers.
+
+    Reporting is not failing: this exits 0 whatever it finds. Folding it into
+    the gate is `verify --coverage`, and it is opt-in for the same reason.
+    """
+    from constant_docs.coverage import by_directory, uncovered_files
+
+    try:
+        resolved = _resolve_config(config_path)
+        cfg = load_config(resolved)
+    except ConfigError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 2
+
+    missing = uncovered_files(cfg, resolved.resolve().parent)
+    grouped = by_directory(missing)
+
+    if json_output:
+        print(
+            json.dumps(
+                {
+                    "uncovered": [p.as_posix() for p in missing],
+                    "by_directory": grouped,
+                    "excluded": dict(sorted(cfg.uncovered.items())),
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    if not missing:
+        print("Every file is covered by a module or declared uncovered.")
+        return 0
+
+    print(f"Source covered by no module ({len(missing)} files):")
+    for directory, files in grouped.items():
+        print(f"  {directory}  ({len(files)})")
+    print(
+        "\nRegister one with `constant-docs add <name> --glob <pattern>`, or "
+        "declare it uncovered in the configuration with a reason."
+    )
+    return 0
+
+
+def cmd_init(config_path: str | None, json_output: bool) -> int:
+    """Gather what a harness needs to propose a module map.
+
+    Writes a configuration when there is none, and **never removes**. A re-run
+    is additive and proposing only: dropping a module orphans its document and
+    `prune` then deletes it, so periodic plus destructive would be data loss.
+    Removing a module stays a hand edit, because it destroys a document and
+    that should cost somebody a decision.
+    """
+    from constant_docs.coverage import facts
+
+    target = Path(config_path) if config_path else _CONFIG_PATH
+    created = False
+    if not target.exists():
+        target.write_text(_BLANK_CONFIG, encoding="utf-8")
+        created = True
+
+    try:
+        cfg = load_config(target)
+    except ConfigError as e:
+        print(f"Configuration error: {e}", file=sys.stderr)
+        return 2
+
+    found = facts(cfg, target.resolve().parent)
+
+    if json_output:
+        print(
+            json.dumps(
+                {
+                    "created": created,
+                    "config": str(target),
+                    "directories": [
+                        {
+                            "path": d.path,
+                            "files": d.files,
+                            "bytes": d.bytes,
+                            "covered": d.covered,
+                        }
+                        for d in found.directories
+                    ],
+                    "uncovered": found.uncovered,
+                    "excluded": found.excluded,
+                    "empty_modules": found.empty_modules,
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    if created:
+        print(f"Wrote {target}.")
+
+    for key in found.empty_modules:
+        print(
+            f"Module {key!r} matches no file. Left alone: removing it would "
+            f"orphan its document, which `prune` deletes."
+        )
+
+    proposals = _propose(found)
+    if not proposals:
+        print("Nothing to propose — every file is covered or declared uncovered.")
+        return 0
+
+    print(f"Source covered by no module, by directory ({len(proposals)}):\n")
+    for directory, count in proposals:
+        print(f"  {directory}  ({count} files)")
+    print(
+        "\nDecide what a module is here, then register each one:\n"
+        "\n  constant-docs add <name> --glob '<pattern>'\n"
+        "\nA directory that should carry no document is declared in the "
+        "configuration under `uncovered:`, with a reason."
+    )
+    return 0
+
+
+def _propose(found: Any) -> list[tuple[str, int]]:
+    """Return (directory, file count) for every directory with uncovered source."""
+    counts: dict[str, int] = {}
+    for rel in found.uncovered:
+        parent = str(Path(rel).parent)
+        counts[parent] = counts.get(parent, 0) + 1
+    return sorted(counts.items())
+
+
+def cmd_prune(config_path: str | None) -> None:
+    """Delete orphaned documents, and name every file left alone."""
+    config = _resolve_config(config_path)
+    try:
+        report = prune(config)
+    except ConfigError as e:
+        _exit_config_error(str(e))
+        return
+    root = config.resolve().parent
+
+    def shown(path: Path) -> str:
+        try:
+            return path.resolve().relative_to(root).as_posix()
+        except ValueError:
+            return str(path)
+
+    # Every deletion named, one line each. `PruneReport` carries `deleted` for
+    # this and this alone: printing "Pruned orphans." and nothing else is how
+    # this command destroyed documents it had never written without anybody
+    # noticing, and a command that just deleted files owes the reader the list.
+    if report.deleted:
+        print(f"Pruned orphans ({len(report.deleted)}):")
+        for path in report.deleted:
+            print(f"  {shown(path)}")
+    else:
+        print("No orphaned documents to prune.")
+
+    if report.failed:
+        # Named on stderr, because this is the one part of the output that
+        # says the command did not finish what it set out to do.
+        print(f"\nCould not remove ({len(report.failed)}):", file=sys.stderr)
+        for problem in report.failed:
+            print(f"  {problem}", file=sys.stderr)
+
+    if not report.skipped:
+        return
+
+    # Named on every run that has any, one line each. A count alone would be
+    # the same silence in a shorter form: the reader cannot tell whether the
+    # file they care about is in it. This is a command that just deleted
+    # things, and the useful sentence is which ones it did not.
+    print(
+        f"\nLeft alone — carries no constant-docs frontmatter ({len(report.skipped)}):"
+    )
+    for path in report.skipped:
+        print(f"  {shown(path)}")
+
+
+def cmd_index(config_path: str | None) -> None:
+    """Assemble and write the root index."""
+    try:
+        config = _resolve_config(config_path)
+        cfg = load_config(config)
+        target = index_write(cfg, config.resolve().parent)
+    except ConfigError as e:
+        _exit_config_error(str(e))
+    except DocumentError as e:
+        # The index refuses to overwrite a file it did not write. A refusal is
+        # exit 2, the same as every other one.
+        print(f"Refused: {e}", file=sys.stderr)
+        sys.exit(2)
+    print(f"Wrote {target}.")
+
+
+def _plan_payload(p: Any) -> dict[str, Any]:
+    """The JSON shape shared by `plan` and `settle` (criterion 30).
+
+    `unreadable` is here as well as in `verify` because these two are what a
+    regeneration loop actually drives. A module whose sources cannot be hashed
+    is in neither `stale` nor `fresh`, so leaving it out told the loop the
+    repository was fully documented while one module had dropped silently out
+    of the report.
+    """
+    return {
+        "unreadable": list(getattr(p, "unreadable", [])),
+        "stale": [
+            {
+                "module": m.module,
+                "doc_path": str(m.doc_path),
+                "files": [str(f) for f in m.files],
+                "previous_body": m.previous_body,
+                "previous_description": m.previous_description,
+                "reason": m.reason,
+                "kind": m.kind,
+                "mode": m.mode,
+                "required_headings": m.required_headings,
+                "prompt": m.prompt,
+            }
+            for m in p.stale
+        ],
+        "orphans": [
+            {"doc_path": str(o.doc_path), "module_key": o.module_key} for o in p.orphans
+        ],
+        "fresh": p.fresh,
+    }
+
+
+def _paths_from_hook_stdin() -> list[str]:
+    """Read a PostToolUse payload from stdin and return the paths it names.
+
+    Reading the hook JSON directly is why the shipped hook needs no `jq` — a
+    dependency the user may not have, whose absence they would experience as
+    this tool being broken. Anything unparseable yields nothing, silently:
+    a hook that shouts about a payload it did not understand is a hook
+    somebody switches off.
+    """
+    try:
+        payload = json.load(sys.stdin)
+    except (ValueError, OSError):
+        return []
+    if not isinstance(payload, dict):
+        return []
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return []
+
+    found: list[str] = []
+    for key in ("file_path", "notebook_path"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            found.append(value)
+    # Some edit tools carry a list of edits, each naming its own file.
+    edits = tool_input.get("edits")
+    if isinstance(edits, list):
+        for edit in edits:
+            if isinstance(edit, dict):
+                value = edit.get("file_path")
+                if isinstance(value, str) and value:
+                    found.append(value)
+    return found
+
+
+def cmd_mark(paths: list[str]) -> int:
+    """Add every module the given paths belong to, to the dirty set.
+
+    Runs on every file write, so it must be cheap and silent. It never reads
+    a source file and never hashes: the path is matched against the declared
+    patterns as a string.
+    """
+    if not paths:
+        paths = _paths_from_hook_stdin()
+    if not paths:
+        return 0
+    try:
+        state.mark(_resolve_config(None), paths)
+    except (ConfigError, GlobError, OSError):
+        # No configuration here, or an unreadable one. A hook installed
+        # globally fires in every repository, including those that do not use
+        # this tool, and must be invisible in them.
+        return 0
+    return 0
+
+
+def cmd_settle(config_path: str | None, json_output: bool, hook: bool) -> int:
+    """Report the work the dirty set implies, without clearing it."""
+    try:
+        resolved = _resolve_config(config_path)
+        p = settle(resolved)
+    except ConfigError as e:
+        # See cmd_mark: silence outside a configured repository. A Stop hook
+        # that fails everywhere else is a Stop hook nobody keeps.
+        #
+        # A configuration that exists and does not parse is the opposite case
+        # and must not borrow that silence: it would switch the gate off in
+        # the one repository that does use the tool, while reporting
+        # "Nothing outstanding." As a hook it still allows the stop, because
+        # blocking on a broken file traps the agent with no way to satisfy it.
+        if e.key != MISSING_KEY:
+            print(f"Configuration error: {e}", file=sys.stderr)
+            return 0 if hook else 2
+        return 0
+
+    if hook:
+        return _settle_as_hook(resolved.resolve().parent, p)
+
+    if json_output:
+        print(json.dumps(_plan_payload(p), indent=2, default=str))
+        return 0
+
+    if not p.stale:
+        print("Nothing outstanding.")
+        return 0
+    for m in p.stale:
+        print(f"[{m.reason}] {m.module} ({m.kind}, {m.mode}) → {m.doc_path}")
+    return 0
+
+
+def _settle_as_hook(repo_root: Path, p: Any) -> int:
+    """The Stop-hook form: exit 2 to block the stop, 0 to allow it.
+
+    Exit 2 is what makes the specification's "regeneration runs at
+    quiescence" true rather than hoped for — Claude Code shows stderr to the
+    agent and continues the turn.
+
+    Claude Code documents no loop guard for `Stop`, so this is ours: after
+    `MAX_BLOCKS` attempts on an identical set, step aside. An agent that
+    cannot satisfy the plan must not be trapped in a loop with no exit.
+    """
+    dirty = state.read(repo_root)
+
+    if not p.stale:
+        if dirty.blocked_signature or dirty.blocked_count:
+            dirty.blocked_signature, dirty.blocked_count = None, 0
+            state.write(repo_root, dirty)
+        return 0
+
+    signature = hashlib.sha256(
+        "\n".join(sorted(m.module for m in p.stale)).encode()
+    ).hexdigest()
+
+    if signature != dirty.blocked_signature:
+        dirty.blocked_signature, dirty.blocked_count = signature, 1
+    elif dirty.blocked_count < 0:
+        # Already released for this exact set. Blocking again would be a
+        # slower loop rather than no loop; stay out of the way until the work
+        # actually changes.
+        return 0
+    else:
+        dirty.blocked_count += 1
+
+    if dirty.blocked_count > state.MAX_BLOCKS:
+        dirty.blocked_count = _RELEASED
+        state.write(repo_root, dirty)
+        print(
+            (
+                "constant-docs: documents are still stale after "
+                f"{state.MAX_BLOCKS} attempts; not blocking again. Run "
+                "`constant-docs settle --json` when you are ready to "
+                "regenerate."
+            ),
+            file=sys.stderr,
+        )
+        return 0
+
+    state.write(repo_root, dirty)
+    lines = [
+        (
+            "constant-docs: these documents are stale and must be "
+            "regenerated before this turn ends."
+        ),
+        "",
+    ]
+    for m in p.stale:
+        lines.append(f"  {m.module}  ({m.kind}, {m.mode}) → {m.doc_path}")
+    lines += [
+        "",
+        (
+            "Run `constant-docs settle --json` for each module's file list, "
+            "previous body, required headings, and prompt."
+        ),
+        (
+            "Then `constant-docs apply <module> <body>` for a replace-mode "
+            "document, or `constant-docs append <module> <title> <entry>` "
+            "for an append-mode one."
+        ),
+    ]
+    print("\n".join(lines), file=sys.stderr)
+    return 2
+
+
+def cmd_prompt(kind_name: str | None) -> None:
+    """Print the generation conventions for a kind, `module` by default.
+
+    Falls back to the shipped kinds when there is no configuration, or none
+    that can be read, so the command still works outside a repository — a
+    harness asking "how do I write one of these" should not first have to find
+    a config file, and a command for bootstrapping must not need the thing it
+    is bootstrapping.
+    """
+    # The default is the `module` kind, resolved below through the
+    # configuration like any other, rather than the packaged file read
+    # directly. The two forms disagreeing would matter most in exactly the
+    # repositories that redeclare `module` — which is the reason to look.
+    kind_name = kind_name or DEFAULT_KIND
+
+    # An authoring guide is not a kind — a README is not a tracked document —
+    # but "how do I write one of these" is the same question, so it is the
+    # same command.
+    guide = guide_path(kind_name)
+    if guide.is_file():
+        print(guide.read_text(encoding="utf-8"), end="")
+        return
+
+    # The configured kinds first, the shipped ones as the fallback. Reading
+    # `BUILTIN_KINDS` alone made the one command whose job is "tell me how to
+    # write one of these" unable to answer for a kind the repository declares —
+    # and its own error text then told the reader to go and open the prompt
+    # file by hand, which is not something a harness can do.
+    kinds = dict(BUILTIN_KINDS)
+    root = Path.cwd()
+    try:
+        config = discover_config(None)
+        kinds = load_config(config).kinds
+        root = config.resolve().parent
+    except (ConfigError, OSError):
+        # `OSError` as well as `ConfigError`: a configuration the process
+        # cannot even open must not take down the one command whose job is to
+        # explain how to write a document.
+        pass
+
+    kind = kinds.get(kind_name)
+    if kind is None:
+        print(
+            f"Unknown kind: {kind_name}. Available kinds: "
+            f"{', '.join(sorted(kinds))}. Authoring guides: "
+            f"{', '.join(guide_names())}.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    try:
+        print(resolve_prompt(kind, root), end="")
+    except KindError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``constant-docs`` console script.
+
+    Returns an exit code suitable for ``sys.exit()``.
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if not argv or argv[0] in ("-h", "--help"):
+        _print_help()
+        return 0
+
+    if argv[0] in ("-V", "--version"):
+        print(f"constant-docs {__version__}")
+        return 0
+
+    subcommand = argv[0]
+    args = argv[1:]
+
+    # Handle --help on any subcommand
+    if "-h" in args or "--help" in args:
+        _print_subcommand_help(subcommand)
+        return 0
+
+    json_output = "--json" in args
+    if json_output:
+        args.remove("--json")
+
+    try:
+        if subcommand == "verify":
+            coverage = "--coverage" in args
+            if coverage:
+                args.remove("--coverage")
+            cmd_verify(args[0] if args else None, json_output, coverage)
+        elif subcommand == "plan":
+            cmd_plan(args[0] if args else None, json_output)
+        elif subcommand == "apply":
+            try:
+                retire = _take_repeated(args, "--retire")
+            except ValueError as e:
+                print(f"Error: {e}", file=sys.stderr)
+                return 2
+            if len(args) < 2:
+                print(
+                    "Usage: constant-docs apply <module> <body> [<config>] "
+                    "[--retire <id>]...",
+                    file=sys.stderr,
+                )
+                return 2
+            module_key = args[0]
+            body_text = args[1]
+            config_path = args[2] if len(args) > 2 else None
+            cmd_apply(config_path, module_key, body_text, retire)
+        elif subcommand == "add":
+            try:
+                globs = _take_repeated(args, "--glob")
+                covers = _take_repeated(args, "--covers")
+                kinds = _take_repeated(args, "--kind")
+            except ValueError as e:
+                print(f"Error: {e}", file=sys.stderr)
+                return 2
+            if len(kinds) > 1:
+                print("Error: --kind may be given once", file=sys.stderr)
+                return 2
+            if not args:
+                print(
+                    "Usage: constant-docs add <name> [<config>] "
+                    "[--glob <pattern>]... [--covers <module>]... [--kind <kind>]",
+                    file=sys.stderr,
+                )
+                return 2
+            return cmd_add(
+                args[1] if len(args) > 1 else None,
+                args[0],
+                globs,
+                covers,
+                kinds[0] if kinds else DEFAULT_KIND,
+            )
+        elif subcommand == "auto":
+            return cmd_auto(args[0] if args else None, json_output)
+        elif subcommand == "coverage":
+            return cmd_coverage(args[0] if args else None, json_output)
+        elif subcommand == "init":
+            return cmd_init(args[0] if args else None, json_output)
+        elif subcommand == "prune":
+            cmd_prune(args[0] if args else None)
+        elif subcommand == "index":
+            cmd_index(args[0] if args else None)
+        elif subcommand == "mark":
+            return cmd_mark(args)
+        elif subcommand == "settle":
+            hook = "--hook" in args
+            if hook:
+                args.remove("--hook")
+            return cmd_settle(args[0] if args else None, json_output, hook)
+        elif subcommand == "append":
+            if len(args) < 3:
+                print(
+                    "Usage: constant-docs append <module> <title> <entry> [<config>]",
+                    file=sys.stderr,
+                )
+                return 2
+            cmd_append(args[3] if len(args) > 3 else None, args[0], args[1], args[2])
+        elif subcommand == "prompt":
+            cmd_prompt(args[0] if args else None)
+        else:
+            print(f"Unknown command: {subcommand}", file=sys.stderr)
+            _print_help()
+            return 2
+    except SystemExit as e:
+        # The command handlers report by calling `sys.exit`, which is the
+        # right thing when the process is the caller and the wrong thing when
+        # a test or an embedder is. `main` is documented as returning an exit
+        # code, so it returns one; the console script hands it to the shell.
+        return 0 if e.code is None else int(e.code)
+    except Exception as e:  # noqa: BLE001
+        # One place where an exception that reached the top level becomes a
+        # code. Two things were wrong here. A `ConfigError` was handled by
+        # `_exit_config_error`, which raises `SystemExit` from inside this very
+        # except block, where the clause above cannot catch it — so `main`
+        # raised where it is documented to return. And everything unhandled was
+        # reported as 1, which this tool defines as *drift*: a repository whose
+        # parser is crashing was answered by scheduling another regeneration
+        # against it, forever.
+        if isinstance(e, ConfigError):
+            print(f"Configuration error: {e}", file=sys.stderr)
+        else:
+            print(f"Error: {e}", file=sys.stderr)
+        return _exit_code_for(e)
+
+    return 0
+
+
+def _print_help() -> None:
+    print(
+        "Usage: constant-docs <command> [options]\n"
+        "\n"
+        "Commands:\n"
+        "  verify [--json] [<config>]  Check for stale/missing/orphan documents\n"
+        "  plan   [--json] [<config>]  List module states\n"
+        "  apply  <module> <body> [<config>] [--retire <id>]...\n"
+        "                              Write a document body\n"
+        "  append <module> <title> <entry> [<config>]  Add one log entry\n"
+        "  add    <name> [--glob <p>]... [--covers <m>]... [--kind <k>]\n"
+        "                              Register a document in the configuration\n"
+        "  auto   [--json] [<config>]  Run the configured regeneration command\n"
+        "  coverage [--json] [<config>]  Report source no module covers\n"
+        "  init   [--json] [<config>]  Gather facts for a new configuration\n"
+        "  prune  [<config>]           Delete orphaned documents\n"
+        "  index  [<config>]           Rebuild the root index from descriptions\n"
+        "  mark   [<path>...]          Add a path's modules to the dirty set\n"
+        "  settle [--json] [--hook]    Report what the dirty set implies\n"
+        "  prompt [<name>]             Print a kind's conventions, or a guide\n"
+        "\n"
+        "Options:\n"
+        "  --json   Output as JSON (verify, plan, settle, coverage, init, auto)\n"
+        "  -h, --help  This help\n"
+        "  -V, --version  Show version\n"
+    )
+
+
+def _print_subcommand_help(cmd: str) -> None:
+    """Print help for a specific subcommand."""
+    helps = {
+        "auto": (
+            "Usage: constant-docs auto [--json] [<config>]\n\n"
+            "Settle, run the command declared under `auto:` in the\n"
+            "configuration, then verify the result. The tool calls no model;\n"
+            "the command does, and its success is not taken on trust.\n\n"
+            "Exits 0 when everything is clean afterwards, 1 when something is\n"
+            "still stale, and 2 when the command could not run or exited\n"
+            "non-zero. The last two must not be confused: a command that ran\n"
+            "and achieved nothing is a working automation with no result.\n"
+        ),
+        "coverage": (
+            "Usage: constant-docs coverage [--json] [<config>]\n\n"
+            "Report every file no module covers and no `uncovered:` entry\n"
+            "names, grouped by directory. Exits 0 whatever it finds;\n"
+            "`verify --coverage` is the form that gates.\n"
+        ),
+        "init": (
+            "Usage: constant-docs init [--json] [<config>]\n\n"
+            "Gather what is needed to propose a module map, and write a\n"
+            "configuration if there is none. Proposing only: a re-run never\n"
+            "removes or rewrites an existing entry, because dropping a module\n"
+            "orphans its document and `prune` then deletes it.\n"
+        ),
+        "verify": "Usage: constant-docs verify [--json] [--coverage] [<config>]\n\nCheck for stale, missing, or orphaned documents.\nExits 0 when everything is current, 1 on drift.\n\nOptions:\n  --json  Output machine-readable JSON\n",
+        "plan": "Usage: constant-docs plan [--json] [<config>]\n\nList the state of every configured module.\n\nOptions:\n  --json  Output machine-readable JSON\n",
+        "apply": (
+            "Usage: constant-docs apply <module> <body> [<config>] "
+            "[--retire <id>]...\n\n"
+            "Write a document body for a module.\n\n"
+            "A body that drops a decision the previous body recorded is\n"
+            "refused, naming it. Rewording a decision is always accepted;\n"
+            "only losing one is not. Retire a decision deliberately with\n"
+            "--retire <id>, which records the retirement in the document.\n"
+            "Declaring a retirement that did not happen is refused too, so\n"
+            "the flag cannot be used to switch the check off.\n"
+        ),
+        "add": (
+            "Usage: constant-docs add <name> [<config>] [--glob <pattern>]... "
+            "[--covers <module>]... [--kind <kind>]\n\n"
+            "Register a document in the configuration, so that adding one is a\n"
+            "command rather than a hand edit.\n\n"
+            "--covers names other modules whose files this document also takes\n"
+            "in, transitively, so a cross-cutting document follows when their\n"
+            "globs move instead of restating them. --glob and --covers compose.\n\n"
+            "A name that already exists is refused. The result is validated by\n"
+            "loading it, and the file is restored untouched if it does not\n"
+            "load.\n"
+        ),
+        "prune": "Usage: constant-docs prune [<config>]\n\nDelete orphaned documents and empty directories.\n",
+        "mark": "Usage: constant-docs mark [<path>...]\n\nAdd every module the given paths belong to, to `.constant-docs/dirty.json`.\nPass paths as arguments from any harness. With no arguments, reads a\nPostToolUse hook payload from stdin, the shape Claude Code sends.\nSilent and exit 0 when a path matches nothing, or outside a configured\nrepository.\n",
+        "settle": "Usage: constant-docs settle [--json] [--hook]\n\nReport the work the dirty set implies. The set is NOT cleared by being\nread; it clears on the apply or append that satisfies each module.\n\nOptions:\n  --json  Machine-readable plan, the same structure `plan --json` emits\n  --hook  Stop-hook form: exit 2 with instructions on stderr when work is\n          outstanding, exit 0 when it is not\n",
+        "index": "Usage: constant-docs index [<config>]\n\nRebuild <docs_root>/index.md from every document's description.\nLeaves the file byte-identical when nothing changed.\n",
+        "append": "Usage: constant-docs append <module> <title> <entry> [<config>]\n\nAdd one entry to an append-mode document. The title becomes the entry's\nH2 heading. Nothing already written is rewritten or reordered.\n",
+        "prompt": (
+            "Usage: constant-docs prompt [<name>]\n\n"
+            "Print a kind's generation conventions, or a shipped authoring\n"
+            "guide. Defaults to the `module` kind.\n"
+        ),
+    }
+    print(helps.get(cmd, f"Unknown command: {cmd}\n"))
+    print("See `constant-docs --help` for all commands.")