constant-docs 0.6.0__tar.gz → 0.7.0__tar.gz

{constant_docs-0.6.0 → constant_docs-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: constant-docs
-Version: 0.6.0
+Version: 0.7.0
 Summary: Self-maintaining documentation for agentic codebases
 Keywords: documentation,docs,staleness,drift,ci,codegen,agents,llm
 Author: Ashborn Systems
@@ -51,14 +51,25 @@ constant_docs:
   - src/constant_docs/api.py
   - src/constant_docs/cli.py
   - src/constant_docs/kinds.py
-  source_hash: sha256:eb69c561d4938e68d3e01c5d7fe41d051f8c2883b1097137d80b09f2cb0e692a
+  source_hash: sha256:99017f4b3440779659af6e13a51d12da0e37146fd449a934a42751f6f6f8d50b
   hash_method: sha256-over-sorted-path-and-content
   hash_covers: source_files
-  timestamp: '2026-08-31T11:33:14Z'
-  generator: constant-docs/0.6.0
+  timestamp: '2026-09-05T13:18:40Z'
+  generator: constant-docs/0.7.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 -->
 
+
+# constant-docs
+
+Documentation that fails the build when it drifts.
+
+A Python command-line tool for codebases written with a coding agent. Each
+document records a hash of the source files it describes, and `constant-docs
+verify` exits 1 the moment the two disagree. The check is a hash comparison, so
+it needs no model client and no network. Your agent writes the documents. The
+tool names the ones that fell behind.
+
 ## How the loop works
 
 Edit a file, and the document describing it is already behind. The loop closes
@@ -79,12 +90,12 @@ $ constant-docs verify
 All modules up to date.
 ```
 
-Your coding agent writes every word, because it already holds the source and
-a model connection. constant-docs names the documents that moved and takes the
+Your coding agent writes every word, because it already holds the source and a
+model connection. constant-docs names the documents that moved and takes the
 new text back.
 
-That one command is also the whole CI integration. It exits 1, and a change
-that alters behaviour while leaving its documentation behind does not merge:
+That one command is also the whole CI integration. It exits 1 on drift, so a
+change that alters behaviour and leaves its document behind does not merge:
 
 ```yaml
 - run: constant-docs verify
@@ -126,7 +137,7 @@ modules:
 
 `constant-docs verify` now names what is missing.
 
-Every command and flag is in the [CLI reference](docs/CLI.md); every
+Every command and flag is in the [CLI reference](docs/CLI.md). Every
 configuration key is in the [configuration reference](docs/CONFIGURATION.md).
 Neither is restated here, because a second copy of the thing that changes most
 is the copy that goes stale.
@@ -149,30 +160,30 @@ $ git diff --name-only | xargs constant-docs mark
 $ constant-docs settle --json
 ```
 
-`settle` reports what `mark` recorded — and when nothing was recorded, it asks
-git what moved rather than reporting an empty list, so a harness that skips the
-marking step still gets real work back. Outside a git checkout it hashes every
-module instead: slower, and never a clean report on no evidence. `plan --json`
-considers every module regardless, and `verify` hashes everything and exits 1
-on drift whatever the marks say. Keep `verify` as the gate.
+`settle` reports what `mark` recorded. When nothing was recorded it asks git
+what moved, so a harness that skips the marking step still gets real work back.
+Outside a git checkout it hashes every module instead: slower, and never a
+clean report on no evidence. `plan --json` considers every module whatever the
+marks say. `verify` hashes everything and exits 1 on drift. Keep `verify` as
+the gate.
 
-**Claude Code gets a plugin.** Install it and two hooks run
-those commands for you: `PostToolUse` runs `mark`, `Stop` runs `settle --hook`.
-Edit a file, stop the turn, and its document is up to date. Nobody asked. Any
-harness that can run a command on write and at turn end does the same job.
+Claude Code gets a plugin. Install it and two hooks run those commands for you:
+`PostToolUse` runs `mark`, `Stop` runs `settle --hook`. Edit a file, stop the
+turn, and its document is up to date. Any harness that can run a command on
+write and at turn end does the same job.
 
 Regeneration happens at quiescence, never mid-edit, so the generator and the
 coding loop never write the same file at once. The dirty set lives in
-`.constant-docs/dirty.json` — gitignored — so a crashed session is picked up on
-the next run.
+`.constant-docs/dirty.json`, which is gitignored, so a crashed session is
+picked up on the next run.
 
 The [harness guide](guides/harness-integration.md) walks through each route.
 
 ## Kinds
 
-A document is not always a module explainer. Its **kind** decides which
-sections it must carry, which prompt its generator is handed, and whether a
-regeneration replaces the body or appends to it.
+A document is not always a module explainer. Its kind decides which sections it
+must carry, which prompt its generator is handed, and whether a regeneration
+replaces the body or appends to it.
 
 | Kind | For | Mode |
 |---|---|---|
@@ -202,7 +213,7 @@ to a log, or a single entry to a module document, and the tool refuses it. A
 configuration that has never heard of kinds behaves exactly as it did.
 
 One house style governs every generated document. It lives in a single file
-that all seven prompts receive, so the rules cannot drift apart.
+that all seven built-in prompts receive, so the rules cannot drift apart.
 
 ## Finding what is undocumented
 
@@ -213,12 +224,13 @@ constant-docs completeness  # kinds of document the contents warrant
 ```
 
 `verify` can only check what has been declared, so a repository could otherwise
-drift to a large fraction undocumented while every check passed. `coverage` does one thing: a set difference. Declare the directories that
-should carry no document in configuration, **with a reason each**. An
-exclusion nobody justified is one nobody decided.
+drift to a large fraction undocumented while every check passed. `coverage`
+does one thing: a set difference. Declare the directories that should carry no
+document in the configuration, with a reason each. An exclusion nobody
+justified is one nobody decided.
 
 Coverage answers whether a file has a document. It cannot answer whether the
-set of documents is complete — a document that was never written cannot drift,
+set of documents is complete: a document that was never written cannot drift,
 and a module document covers its files, so a repository with a document per
 module and no specification passes everything. `completeness` proposes the
 kinds your contents warrant, each with the fact behind it:
@@ -232,25 +244,26 @@ Warranted and not written (2):
     because declares the console script `yourtool` (pyproject.toml)
 ```
 
-It proposes from what is in the repository, never from the list of kinds a
-library with no command line is not offered a CLI reference, because a document
-nobody needs still has to be kept true and still refuses a commit when it
-drifts. Nothing warrants a changelog: every repository could keep one, so the
-signal fires everywhere and says nothing.
+It proposes from evidence in the repository, such as a console script or an
+exception hierarchy. The existence of a kind is not itself evidence. A library
+with no command line is not offered a CLI reference, because a document nobody
+needs still has to be kept true and still refuses a commit when it drifts.
+Nothing warrants a changelog: every repository could keep one, so the signal
+fires everywhere and says nothing.
 
 Write the document, or decline the kind under `unwarranted:` with a reason and
 it stops being proposed.
 
 `verify --coverage` and `verify --completeness` fold the two into the gate,
-both opt-in. `init` proposes and never removes: dropping a module orphans its
+both opt-in. `init` proposes. It never removes: dropping a module orphans its
 document, and `prune` deletes it.
 
 ## Files it will not touch
 
-**Already have a `docs/` folder? Pointing the tool at it is safe.** Every
-document this tool writes carries a block naming the tool, and — when you
-declare a `project` id — the project that wrote it. A markdown file without
-that block belongs to somebody else, and three commands act on the difference:
+Pointing the tool at a `docs/` folder the repository already has is safe. Every
+document this tool writes carries a block naming the tool, and, when you
+declare a `project` id, the project that wrote it. A markdown file without that
+block belongs to somebody else, and three commands act on the difference:
 
 - `apply` refuses to write over one. It names the file and changes no byte
 - `prune` refuses to delete one, and names every file it left alone
@@ -280,10 +293,10 @@ stays where it is. A mistyped glob costs you a failing check and nothing else.
 
 ## Documents outside the repository
 
-Set `docs_store` and documents land in a directory the repository does not own
-— an Obsidian vault, a shared folder, wherever your notes already live. A store
+Set `docs_store` and documents land in a directory the repository does not own:
+an Obsidian vault, a shared folder, wherever your notes already live. A store
 may be shared, so it requires a `project` id. That id keeps two repositories
-writing into one vault clear of each other's documents.
+that write into one vault clear of each other's documents.
 
 ```yaml
 project: payments-api
@@ -295,13 +308,13 @@ say `docs/src/payments.md`. The store answers the one question that wants a
 real directory on this machine: where to open the file.
 
 The variable must resolve when the configuration loads. Unset, empty, relative,
-or naming a directory that is not there — each refuses the configuration and
+or naming a directory that is not there, each refuses the configuration and
 says which. A store landing inside `.ssh`, `Secret/`, a cache or any other
 directory on the deny list is refused too. The tool declines to read those
-directories, so it declines to write documents into them. Plain `${NAME}` is the whole syntax, because a default value would
-let a machine without the vault write documents into the repository and report
-success. The Stop hook blocks on the same failure, so a missing variable cannot
-switch the gate off quietly.
+directories, so it declines to write documents into them. Plain `${NAME}` is
+the whole syntax. A default value would let a machine without the vault write
+documents into the repository and report success. The Stop hook blocks on the
+same failure, so a missing variable cannot switch the gate off quietly.
 
 Deletion changes as well. A repository's documents ride the branch, and `git
 checkout` brings one back. A store stands still while the checkout moves, so
@@ -323,27 +336,26 @@ auto:
 
 The tool still calls no model. constant-docs splits your command with `shlex`
 and runs it directly, so an agent CLI, a script and a Makefile target all work.
-No credential goes in it, and **the command's success is checked**: `auto`
-re-runs `verify` afterwards. It exits 0 when everything is clean, 1 when
-something is still stale, and 2 when the command could not run. Three
-outcomes, because a scheduler that confuses the last two retries the wrong
-one.
+No credential goes in it. The command's success is checked: `auto` re-runs
+`verify` afterwards. It exits 0 when everything is clean, 1 when something is
+still stale, and 2 when the command could not run or exited non-zero. Three
+outcomes, because a scheduler that confuses the last two retries the wrong one.
 
 ## Three things it checks that a hash cannot
 
 **A regeneration cannot drop a decision.** A document rewritten by a model can
 lose the thing it existed to record. Give each recorded decision an identifier
 and the tool refuses a rewrite that loses one, naming it. A rewrite may reword
-every decision it holds. Losing one costs a refusal, and retiring one is
-deliberate and gets written into the document.
+every decision it holds. Losing one costs a refusal. Retiring one is
+deliberate: name it with `--retire` and the retirement is recorded in the
+document, with a date.
 
 **A cross-cutting document follows what it covers.** `covers: [api, cli]` takes
-in those modules' files by name, so it goes stale when their boundary
-moves.
+in those modules' files by name, so it goes stale when their boundary moves.
 
-**An error catalogue agrees with the source, both ways.** Every message the code
-raises appears in the catalogue, and every entry still exists in the code.
-Neither needs parsing beyond a string scan, so it costs nothing — and it is the
+**An error catalogue agrees with the source, both ways.** Every message the
+code raises appears in the catalogue, and every entry still exists in the code.
+Neither needs parsing beyond a string scan, so it costs nothing, and it is the
 one document here the tool can actually guarantee. The rest are only fresh.
 
 ## What a document looks like
@@ -354,6 +366,8 @@ type: Code Module
 title: Payments
 description: Reconciles inbound payment events against ledger entries.
 tags: [code-module]
+created: '2026-08-19'
+updated: '2026-08-19'
 
 constant_docs:
   project: payments-api
@@ -367,7 +381,7 @@ constant_docs:
   hash_method: sha256-over-sorted-path-and-content
   hash_covers: source_files
   timestamp: '2026-08-19T09:14:00Z'
-  generator: constant-docs/0.6.0
+  generator: constant-docs/0.7.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 ---
 ## Purpose
@@ -378,8 +392,8 @@ and duplicate handling are internal.
 
 ## Correctness pillars
 
-WHEN a batch contains a duplicate event ID, the module SHALL discard the later
-event and record it in the report.
+A batch carrying the same event ID twice has the later one discarded, and the
+report records that it happened.
 
 ## Known failure modes
 
@@ -393,7 +407,7 @@ what the document describes, where its source lives, and how to recompute the
 digest. `project` answers the question asked before every overwrite and every
 deletion: whose document is this. The tool keeps everything it owns under one
 `constant_docs` key, an Open Knowledge Format producer extension. `type`,
-`title` and `tags` stay yours, and unknown keys survive a write.
+`title`, `tags` and the two dates stay yours, and unknown keys survive a write.
 
 ## Python API
 
@@ -413,37 +427,39 @@ prune()  # deletes orphans; under a store, lists them
 A module names a glob, and the tool digests the bytes of the files that glob
 matches. Nothing in that step knows a language, which is what makes yours work:
 no model client, no network call, no AST, no import graph. The cost is that any
-byte moves the hash, so fixing a typo in a comment reports the module stale and
+byte moves the hash. Fixing a typo in a comment reports the module stale, and
 your agent rewrites a document the edit never touched.
 
 It watches files and nothing else. A document quoting a queue depth or a
 production URL stays fresh for ever, because nobody edited anything. Hash what
 lives in files. Leave live values to something that owns them.
 
-It cannot catch two documents contradicting each other. Content hashing sees one thing: a document
-falling behind its source. That is why the tool always moves a section and
-never copies it.
+It cannot catch two documents contradicting each other. Content hashing sees
+one thing: a document falling behind its source. That is why a cross-cutting
+document takes in the modules it talks about through `covers` and never
+restates their facts.
 
-And it cannot catch a decision reworded into something weaker. The guard draws
-one line, between present and deleted. Degradation is left to review, and
-said so here so that you learn it now.
+It cannot catch a decision reworded into something weaker. The decision guard
+draws one line, between a decision present and a decision deleted. Degradation
+is left to review.
 
-It ships one ready-made integration. The Claude Code plugin installs and runs.
-For any other agent you wire `mark` and `settle` to whatever signals it gives
-you, which takes a few lines of shell.
+It ships one ready-made integration, the Claude Code plugin. For any other
+agent you wire `mark` and `settle` to whatever signals it gives you, which
+takes a few lines of shell.
 
-**This file maintains itself.** It carries the tool's own block in an HTML
-comment, which GitHub renders as nothing. It goes stale whenever the CLI, the
-kinds or the Python API move.
+This README is not one of the tracked documents. The tool does not track prose
+like this, so it is revised by hand, and nothing regenerates it.
 
 ## Reading further
 
-- [Specification](docs/SPEC.md) — the full design and its 183 acceptance criteria
-- [Architecture](docs/ARCHITECTURE.md) — what the parts are and how they meet
-- [CLI reference](docs/CLI.md) and [configuration reference](docs/CONFIGURATION.md)
-- [Error catalogue](docs/ERRORS.md) — every message, its cause, and what to do
-- [examples/](examples/) — a worked repository with its documents committed
+- [Specification](docs/SPEC.md): the full design and its 183 acceptance
+  criteria
+- [Architecture](docs/ARCHITECTURE.md): what the parts are and how they meet
+- [CLI reference](docs/CLI.md) and [configuration
+  reference](docs/CONFIGURATION.md)
+- [Error catalogue](docs/ERRORS.md): every message, its cause, and what to do
+- [examples/](examples/): a worked repository with its documents committed
 
 ## Licence
 
-Apache 2.0 — see [LICENSE](LICENSE).
+Apache 2.0. See [LICENSE](LICENSE).