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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: constant-docs
-Version: 0.7.0
+Version: 0.8.0
 Summary: Self-maintaining documentation for agentic codebases
 Keywords: documentation,docs,staleness,drift,ci,codegen,agents,llm
 Author: Ashborn Systems
@@ -51,11 +51,11 @@ constant_docs:
   - src/constant_docs/api.py
   - src/constant_docs/cli.py
   - src/constant_docs/kinds.py
-  source_hash: sha256:99017f4b3440779659af6e13a51d12da0e37146fd449a934a42751f6f6f8d50b
+  source_hash: sha256:831cdb38a60c83171b114148aff40e507c1feb9c94600e9404de748e293f9b21
   hash_method: sha256-over-sorted-path-and-content
   hash_covers: source_files
-  timestamp: '2026-09-05T13:18:40Z'
-  generator: constant-docs/0.7.0
+  timestamp: '2026-09-05T16:46:40Z'
+  generator: constant-docs/0.8.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 -->
 
@@ -94,8 +94,9 @@ 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 on drift, so a
-change that alters behaviour and leaves its document behind does not merge:
+That one command is also the whole continuous-integration check. It exits 1 on
+drift, so a change that alters behaviour and leaves its document behind does
+not merge:
 
 ```yaml
 - run: constant-docs verify
@@ -168,12 +169,12 @@ 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. Any harness that can run a command on
-write and at turn end does the same job.
+`PostToolUse` runs `mark` after each edit, and `Stop` runs `settle --hook` when
+the turn ends. 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
+Regeneration happens at the end of a turn, 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`, which is gitignored, so a crashed session is
 picked up on the next run.
 
@@ -181,9 +182,9 @@ 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.
+Every document has a kind. The kind decides which sections its body must carry,
+which prompt its generator is handed, and whether a regeneration replaces the
+body or appends an entry.
 
 | Kind | For | Mode |
 |---|---|---|
@@ -191,7 +192,7 @@ replaces the body or appends to it.
 | `spec` | What a subsystem promises, and why | replace |
 | `log` | A changelog or build log | **append** |
 | `architecture` | The module map, with a diagram | replace |
-| `errors` | Every message the tool can emit | replace |
+| `errors` | Every message the covered code can raise | replace |
 | `config-reference` | Every configuration key | replace |
 | `cli-reference` | Every command and flag | replace |
 
@@ -212,8 +213,9 @@ An append never rewrites or reorders what is already there. Pass a whole body
 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 built-in prompts receive, so the rules cannot drift apart.
+One house style governs every document written from a built-in prompt. It lives
+in a single file that all seven built-in prompts receive, so the rules cannot
+drift apart.
 
 ## Finding what is undocumented
 
@@ -223,17 +225,18 @@ constant-docs coverage      # source no module covers, by directory
 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 the configuration, with a reason each. An exclusion nobody
-justified is one nobody decided.
+`verify` can only check what has been declared, so a repository can drift a
+long way undocumented while every check passes. `coverage` does one thing: a
+set difference. It reports the files no declared glob matches and no exclusion
+names. 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,
-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:
+set of documents is complete. A document that was never written cannot drift,
+and a repository with a document per module and no specification passes every
+coverage check. `completeness` proposes the kinds your contents warrant, each
+with the fact behind it:
 
 ```
 Warranted and not written (2):
@@ -247,11 +250,11 @@ Warranted and not written (2):
 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.
+needs still has to be kept true and still fails the build 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
+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,
@@ -261,13 +264,14 @@ document, and `prune` deletes it.
 ## Files it will not touch
 
 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:
+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
-- `verify` lists them under a heading of their own, and they fail nothing
+- `verify` lists them under a heading of their own, and none of them fails the
+  check
 
 Take one over when you want it maintained:
 
@@ -288,7 +292,7 @@ rewrite it. Every body your agent generates still carries those headings, and
 `apply` checks before it writes a byte.
 
 A glob that matches no file gets the same restraint. `verify` names the module
-and exits 1, `apply` refuses to record a digest over nothing, and the document
+and exits 1, `apply` refuses to record a hash over nothing, and the document
 stays where it is. A mistyped glob costs you a failing check and nothing else.
 
 ## Documents outside the repository
@@ -309,12 +313,14 @@ 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
-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. 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.
+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. 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
@@ -334,12 +340,14 @@ auto:
   budget: 5
 ```
 
-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. 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.
+constant-docs itself calls no model. It 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. 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
 
@@ -354,9 +362,10 @@ document, with a date.
 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
-one document here the tool can actually guarantee. The rest are only fresh.
+code raises appears in the catalogue, and every entry listed is still raised in
+the code. The check needs no parsing beyond a string scan, so it costs nothing,
+and it is the one document here the tool can guarantee. The rest are only
+fresh.
 
 ## What a document looks like
 
@@ -381,7 +390,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.7.0
+  generator: constant-docs/0.8.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 ---
 ## Purpose
@@ -404,7 +413,7 @@ report records that it happened.
 
 The frontmatter stands alone. An agent that has never run this tool can see
 what the document describes, where its source lives, and how to recompute the
-digest. `project` answers the question asked before every overwrite and every
+hash. `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`, `tags` and the two dates stay yours, and unknown keys survive a write.
@@ -424,11 +433,11 @@ prune()  # deletes orphans; under a store, lists them
 
 ## What it does not do
 
-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. Fixing a typo in a comment reports the module stale, and
-your agent rewrites a document the edit never touched.
+A module names a glob, and the tool hashes the bytes of the files that glob
+matches. Nothing in that step knows a language, which is what makes it work on
+yours: no model client, no network call, no syntax tree, no import graph. The
+cost is that any 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

{constant_docs-0.7.0 → constant_docs-0.8.0}/README.md

@@ -22,11 +22,11 @@ constant_docs:
   - src/constant_docs/api.py
   - src/constant_docs/cli.py
   - src/constant_docs/kinds.py
-  source_hash: sha256:99017f4b3440779659af6e13a51d12da0e37146fd449a934a42751f6f6f8d50b
+  source_hash: sha256:831cdb38a60c83171b114148aff40e507c1feb9c94600e9404de748e293f9b21
   hash_method: sha256-over-sorted-path-and-content
   hash_covers: source_files
-  timestamp: '2026-09-05T13:18:40Z'
-  generator: constant-docs/0.7.0
+  timestamp: '2026-09-05T16:46:40Z'
+  generator: constant-docs/0.8.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 -->
 
@@ -65,8 +65,9 @@ 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 on drift, so a
-change that alters behaviour and leaves its document behind does not merge:
+That one command is also the whole continuous-integration check. It exits 1 on
+drift, so a change that alters behaviour and leaves its document behind does
+not merge:
 
 ```yaml
 - run: constant-docs verify
@@ -139,12 +140,12 @@ 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. Any harness that can run a command on
-write and at turn end does the same job.
+`PostToolUse` runs `mark` after each edit, and `Stop` runs `settle --hook` when
+the turn ends. 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
+Regeneration happens at the end of a turn, 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`, which is gitignored, so a crashed session is
 picked up on the next run.
 
@@ -152,9 +153,9 @@ 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.
+Every document has a kind. The kind decides which sections its body must carry,
+which prompt its generator is handed, and whether a regeneration replaces the
+body or appends an entry.
 
 | Kind | For | Mode |
 |---|---|---|
@@ -162,7 +163,7 @@ replaces the body or appends to it.
 | `spec` | What a subsystem promises, and why | replace |
 | `log` | A changelog or build log | **append** |
 | `architecture` | The module map, with a diagram | replace |
-| `errors` | Every message the tool can emit | replace |
+| `errors` | Every message the covered code can raise | replace |
 | `config-reference` | Every configuration key | replace |
 | `cli-reference` | Every command and flag | replace |
 
@@ -183,8 +184,9 @@ An append never rewrites or reorders what is already there. Pass a whole body
 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 built-in prompts receive, so the rules cannot drift apart.
+One house style governs every document written from a built-in prompt. It lives
+in a single file that all seven built-in prompts receive, so the rules cannot
+drift apart.
 
 ## Finding what is undocumented
 
@@ -194,17 +196,18 @@ constant-docs coverage      # source no module covers, by directory
 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 the configuration, with a reason each. An exclusion nobody
-justified is one nobody decided.
+`verify` can only check what has been declared, so a repository can drift a
+long way undocumented while every check passes. `coverage` does one thing: a
+set difference. It reports the files no declared glob matches and no exclusion
+names. 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,
-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:
+set of documents is complete. A document that was never written cannot drift,
+and a repository with a document per module and no specification passes every
+coverage check. `completeness` proposes the kinds your contents warrant, each
+with the fact behind it:
 
 ```
 Warranted and not written (2):
@@ -218,11 +221,11 @@ Warranted and not written (2):
 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.
+needs still has to be kept true and still fails the build 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
+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,
@@ -232,13 +235,14 @@ document, and `prune` deletes it.
 ## Files it will not touch
 
 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:
+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
-- `verify` lists them under a heading of their own, and they fail nothing
+- `verify` lists them under a heading of their own, and none of them fails the
+  check
 
 Take one over when you want it maintained:
 
@@ -259,7 +263,7 @@ rewrite it. Every body your agent generates still carries those headings, and
 `apply` checks before it writes a byte.
 
 A glob that matches no file gets the same restraint. `verify` names the module
-and exits 1, `apply` refuses to record a digest over nothing, and the document
+and exits 1, `apply` refuses to record a hash over nothing, and the document
 stays where it is. A mistyped glob costs you a failing check and nothing else.
 
 ## Documents outside the repository
@@ -280,12 +284,14 @@ 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
-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. 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.
+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. 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
@@ -305,12 +311,14 @@ auto:
   budget: 5
 ```
 
-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. 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.
+constant-docs itself calls no model. It 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. 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
 
@@ -325,9 +333,10 @@ document, with a date.
 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
-one document here the tool can actually guarantee. The rest are only fresh.
+code raises appears in the catalogue, and every entry listed is still raised in
+the code. The check needs no parsing beyond a string scan, so it costs nothing,
+and it is the one document here the tool can guarantee. The rest are only
+fresh.
 
 ## What a document looks like
 
@@ -352,7 +361,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.7.0
+  generator: constant-docs/0.8.0
   generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
 ---
 ## Purpose
@@ -375,7 +384,7 @@ report records that it happened.
 
 The frontmatter stands alone. An agent that has never run this tool can see
 what the document describes, where its source lives, and how to recompute the
-digest. `project` answers the question asked before every overwrite and every
+hash. `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`, `tags` and the two dates stay yours, and unknown keys survive a write.
@@ -395,11 +404,11 @@ prune()  # deletes orphans; under a store, lists them
 
 ## What it does not do
 
-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. Fixing a typo in a comment reports the module stale, and
-your agent rewrites a document the edit never touched.
+A module names a glob, and the tool hashes the bytes of the files that glob
+matches. Nothing in that step knows a language, which is what makes it work on
+yours: no model client, no network call, no syntax tree, no import graph. The
+cost is that any 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

{constant_docs-0.7.0 → constant_docs-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "constant-docs"
-version = "0.7.0"
+version = "0.8.0"
 description = "Self-maintaining documentation for agentic codebases"
 readme = "README.md"
 requires-python = ">=3.11"

{constant_docs-0.7.0 → constant_docs-0.8.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "constant-docs"
-version = "0.7.0"
+version = "0.8.0"
 description = "Self-maintaining documentation for agentic codebases"
 readme = "README.md"
 # No contact address. PyPI does not require one, and it is published verbatim

{constant_docs-0.7.0 → constant_docs-0.8.0}/src/constant_docs/api.py

@@ -89,7 +89,10 @@ class ModulePlan:
     previous_body: str | None
     previous_description: str | None
     required_headings: list[str]
-    reason: Literal["changed", "missing"]
+    # "changed" and "missing" are answers about this repository. "regen" is an
+    # answer about the tool: the source has not moved and the document is
+    # listed anyway, because a newer prompt writes it differently.
+    reason: Literal["changed", "missing", "regen"]
     # A kind decides the shape of the write. `mode` is the one a caller must
     # branch on: "replace" takes a whole body through `apply`, "append" takes
     # a single entry through `append`, and passing one to the other is refused
@@ -403,6 +406,7 @@ def plan(
     config_path: str | Path | None = None,
     changed_paths: list[str] | None = None,
     modules: list[str] | None = None,
+    regen: bool = False,
 ) -> Plan:
     """Inspect the repository and return the current state.
 
@@ -412,9 +416,47 @@ def plan(
     *changed_paths* of ``None`` means consider every module. *modules* names
     module keys directly, which is what `settle` has and saves it inventing a
     path that resolves back to them.
+
+    *regen* lists every module as work whether or not its source moved, which
+    is the one question a content hash cannot answer: the document is not
+    behind its code, it is behind the conventions it was written against. A
+    release that changes the prompts leaves every document passing `verify`
+    and none of them written the new way.
+
+    The previous body is still supplied, and the prompt carries an
+    instruction to carry its content across. A regeneration that starts from
+    an empty page keeps every heading and loses the reasons underneath them,
+    which no check here can see.
     """
     resolved = _resolve_config(config_path)
-    return _plan(load_config(resolved), _repo_root(resolved), changed_paths, modules)
+    return _plan(
+        load_config(resolved), _repo_root(resolved), changed_paths, modules, regen=regen
+    )
+
+
+# Appended to every prompt a `--regen` plan carries. Without it, a rewrite
+# against an unchanged source loses content: regenerating this repository's
+# own `config` document dropped 22 of its 38 correctness pillars, and the SPEC
+# came back at 10,065 words against 24,502. The same run with this paragraph
+# in front of the generator returned 102% and 98% of the originals.
+#
+# It travels in the plan rather than in the skill, so a harness that reads
+# `settle --json` and follows the `prompt` field gets it without knowing what
+# `--regen` means.
+_REGEN_NOTE = """
+
+## This is a regeneration, not a rewrite
+
+Nothing in the source moved. This document is being written again because the
+conventions above have changed since it was last written.
+
+Carry every rule, every failure mode and every reason the previous body
+records into the new one. Change the wording, the order and the structure as
+the conventions now require. Merge two entries that say the same thing. Drop
+only something the source no longer supports.
+
+A shorter document is the failure mode here. If you cannot express a rule in
+the new form, keep the old sentence rather than losing the rule."""
 
 
 def _plan(
@@ -423,6 +465,7 @@ def _plan(
     changed_paths: list[str] | None = None,
     modules: list[str] | None = None,
     cache: DocumentCache | None = None,
+    regen: bool = False,
 ) -> Plan:
     """The body of :func:`plan`, over a configuration already loaded.
 
@@ -431,6 +474,12 @@ def _plan(
     the configuration three times and walk the repository three times with it.
     """
     cache = cache or DocumentCache()
+    # *regen* does not appear here. It decides what counts as work, not what
+    # is looked at, and the default scope is already every module. A branch
+    # widening the scope for it would only fire when a caller passed a
+    # narrowing argument *and* asked for a regeneration, and there the
+    # narrowing argument is the more specific instruction — the same reason
+    # `auto` keeps its budget through one.
     if modules is not None:
         modules_in_scope = {m for m in modules if m in cfg.module_files}
     else:
@@ -461,7 +510,7 @@ def _plan(
         doc_abs = store_path(cfg, repo_root, doc_file)
         previous_body: str | None = None
         previous_description: str | None = None
-        reason: Literal["changed", "missing"] = "missing"
+        reason: Literal["changed", "missing", "regen"] = "missing"
 
         if doc_abs.exists():
             try:
@@ -472,9 +521,18 @@ def _plan(
                 previous_body = existing.body
                 previous_description = existing.frontmatter.get("description")
                 if stored_hash == current_hash:
-                    fresh.append(mod_key)
-                    continue
-                reason = "changed"
+                    # A log is never regenerated. Its entries are a record of
+                    # what happened, and the only write it takes is one more
+                    # entry on the end. Listed under *regen* with nothing to
+                    # report, a harness writes an entry describing no change.
+                    # A log whose source did move is still work, and reaches
+                    # the list by the ordinary route below.
+                    if not regen or kind.mode == "append":
+                        fresh.append(mod_key)
+                        continue
+                    reason = "regen"
+                else:
+                    reason = "changed"
             except (OSError, DocumentError):
                 # Malformed document → treat as missing
                 reason = "missing"
@@ -490,7 +548,7 @@ def _plan(
                 reason=reason,
                 kind=kind.name,
                 mode=kind.mode,
-                prompt=_prompt_for(kind, repo_root),
+                prompt=_prompt_for(kind, repo_root) + (_REGEN_NOTE if regen else ""),
             )
         )
 
@@ -886,12 +944,20 @@ def apply(
 
 def append(
     module_key: str,
+    *,
     entry: str,
     title: str,
     config_path: str | Path | None = None,
 ) -> None:
     """Add one entry to the document for *module_key*.
 
+    *entry* and *title* are keyword-only, because they are two strings in the
+    opposite order to `constant-docs append <module> <title> <entry>` and
+    swapping them is silent: the whole entry becomes the heading and the
+    title becomes the paragraph under it. That happened to this repository's
+    own changelog. A caller that gets it wrong now fails on the call rather
+    than in the document.
+
     The entry goes under the kind's first section as an H3 whose text is
     Everything already in the document is left exactly as it is: an
     append that can modify history is a replace with extra steps.
@@ -1228,7 +1294,7 @@ def _unmarked_scope(
     return _Scope(modules=sorted(keys), evidence=evidence)
 
 
-def settle(config_path: str | Path | None = None) -> Plan:
+def settle(config_path: str | Path | None = None, regen: bool = False) -> Plan:
     """Plan over what has changed, without clearing the dirty set.
 
     Called at quiescence — the end of a turn — so the generator and the coding
@@ -1252,10 +1318,17 @@ def settle(config_path: str | Path | None = None) -> Plan:
 
     1. A scope declared for this run in the environment, which is how `auto`
        holds its budget across whatever loop its command runs
-    2. The dirty set, when a hook marked something. What a session touched is
+    2. Every module, when *regen* asks for one. It sits below the declared
+       scope so `auto` keeps its cap, and above the rest because the question
+       it asks is not "what moved" at all
+    3. The dirty set, when a hook marked something. What a session touched is
        the work that session owes, and planning over more of the repository
        would make `auto`'s cap advisory
-    3. Otherwise, what git says moved
+    4. Otherwise, what git says moved
+
+    A *regen* run records no baseline. A baseline claims every module was
+    fresh at this commit, and a run that listed every module as work has
+    established nothing of the kind.
     """
     resolved = _resolve_config(config_path)
     repo_root = _repo_root(resolved)
@@ -1278,6 +1351,8 @@ def settle(config_path: str | Path | None = None) -> Plan:
     declared = declared_scope()
     if declared:
         scope = _Scope(modules=declared)
+    elif regen:
+        scope = _Scope(modules=None)
     elif dirty.modules:
         scope = _Scope(modules=list(dirty.modules))
     else:
@@ -1299,7 +1374,7 @@ def settle(config_path: str | Path | None = None) -> Plan:
         if scope.modules is None
         else [m for m in scope.modules if m in cfg.module_files]
     )
-    p = _plan(cfg, repo_root, changed_paths=None, modules=known)
+    p = _plan(cfg, repo_root, changed_paths=None, modules=known, regen=regen)
 
     remaining = dirty.modules
     if p.fresh:

{constant_docs-0.7.0 → constant_docs-0.8.0}/src/constant_docs/cli.py

@@ -10,7 +10,7 @@ Usage::
     constant-docs prune [<config>]
     constant-docs index [<config>]
     constant-docs mark [<path>...]
-    constant-docs settle [--json] [--hook]
+    constant-docs settle [--json] [--hook] [--regen]
     constant-docs completeness [--json] [<config>]
     constant-docs prompt [<kind>]
 """
@@ -303,10 +303,10 @@ def cmd_verify(
         sys.exit(report.exit_code)
 
 
-def cmd_plan(config_path: str | None, json_output: bool) -> None:
+def cmd_plan(config_path: str | None, json_output: bool, regen: bool = False) -> None:
     """Inspect and report the current state."""
     try:
-        p = plan(_resolve_config(config_path))
+        p = plan(_resolve_config(config_path), regen=regen)
     except ConfigError as e:
         _exit_config_error(str(e))
 
@@ -359,7 +359,12 @@ def cmd_append(
 ) -> None:
     """Add one entry to an append-mode document."""
     try:
-        append(module_key, entry, title, config_path=_resolve_config(config_path))
+        append(
+            module_key,
+            entry=entry,
+            title=title,
+            config_path=_resolve_config(config_path),
+        )
         print(f"Appended to {module_key}.")
     except ConfigError as e:
         _exit_config_error(str(e))
@@ -907,11 +912,13 @@ def cmd_mark(paths: list[str]) -> int:
     return 0
 
 
-def cmd_settle(config_path: str | None, json_output: bool, hook: bool) -> int:
+def cmd_settle(
+    config_path: str | None, json_output: bool, hook: bool, regen: bool = False
+) -> int:
     """Report the work the dirty set implies, without clearing it."""
     try:
         resolved = _resolve_config(config_path)
-        p = settle(resolved)
+        p = settle(resolved, regen=regen)
     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.
@@ -1142,7 +1149,10 @@ def main(argv: list[str] | None = None) -> int:
                 wants_completeness,
             )
         elif subcommand == "plan":
-            cmd_plan(args[0] if args else None, json_output)
+            regen = "--regen" in args
+            if regen:
+                args.remove("--regen")
+            cmd_plan(args[0] if args else None, json_output, regen)
         elif subcommand == "apply":
             try:
                 retire = _take_repeated(args, "--retire")
@@ -1214,7 +1224,10 @@ def main(argv: list[str] | None = None) -> int:
             hook = "--hook" in args
             if hook:
                 args.remove("--hook")
-            return cmd_settle(args[0] if args else None, json_output, hook)
+            regen = "--regen" in args
+            if regen:
+                args.remove("--regen")
+            return cmd_settle(args[0] if args else None, json_output, hook, regen)
         elif subcommand == "append":
             if len(args) < 3:
                 print(
@@ -1259,7 +1272,8 @@ def _print_help() -> None:
         "\n"
         "Commands:\n"
         "  verify [--json] [<config>]  Check for stale/missing/orphan documents\n"
-        "  plan   [--json] [<config>]  List module states\n"
+        "  plan   [--json] [--regen] [<config>]\n"
+        "                              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"
@@ -1273,7 +1287,8 @@ def _print_help() -> None:
         "  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"
+        "  settle [--json] [--hook] [--regen]\n"
+        "                              Report what the dirty set implies\n"
         "  prompt [<name>]             Print a kind's conventions, or a guide\n"
         "\n"
         "Options:\n"
@@ -1333,7 +1348,13 @@ def _print_subcommand_help(cmd: str) -> None:
             "  --completeness  Also fail on a kind the contents warrant and\n"
             "                  nothing provides\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",
+        "plan": (
+            "Usage: constant-docs plan [--json] [--regen] [<config>]\n\n"
+            "List the state of every configured module.\n\n"
+            "Options:\n"
+            "  --json  Output machine-readable JSON\n"
+            "  --regen List every module as work, whether or not its source moved.\n          For after an upgrade that changed the conventions: the\n          documents are not behind their code, they are behind the\n          prompts they were written against, and no hash sees that.\n          Each plan still carries the previous body, and the prompt\n          it carries says to keep what that body records\n"
+        ),
         "apply": (
             "Usage: constant-docs apply <module> <body> [<config>] "
             "[--retire <id>]...\n\n"
@@ -1378,7 +1399,7 @@ def _print_subcommand_help(cmd: str) -> None:
             "document to a renamed module.\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",
+        "settle": "Usage: constant-docs settle [--json] [--hook] [--regen]\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  --regen List every module as work, whether or not its source moved.\n          For after an upgrade that changed the conventions: the\n          documents are not behind their code, they are behind the\n          prompts they were written against, and no hash sees that.\n          Each plan still carries the previous body, and the prompt\n          it carries says to keep what that body records\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": (