constant-docs 0.4.0__tar.gz

constant_docs-0.4.0/LICENSE

@@ -0,0 +1,15 @@
+Apache License, Version 2.0
+
+Copyright 2026 Ashborn Systems
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

constant_docs-0.4.0/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: constant-docs
+Version: 0.4.0
+Summary: Self-maintaining documentation for agentic codebases
+Keywords: documentation,docs,staleness,drift,ci,codegen,agents,llm
+Author: Ashborn Systems
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/ashborn-systems/constant-docs
+Project-URL: Repository, https://github.com/ashborn-systems/constant-docs
+Project-URL: Documentation, https://github.com/ashborn-systems/constant-docs/blob/main/README.md
+Project-URL: Changelog, https://github.com/ashborn-systems/constant-docs/blob/main/docs/CHANGELOG.md
+Project-URL: Issues, https://github.com/ashborn-systems/constant-docs/issues
+Project-URL: Specification, https://github.com/ashborn-systems/constant-docs/blob/main/docs/SPEC.md
+Description-Content-Type: text/markdown
+
+<!-- constant-docs
+type: Readme
+title: README
+description: Self-maintaining documentation for agentic codebases.
+tags:
+- readme
+created: '2026-08-26'
+updated: '2026-08-26'
+
+constant_docs:
+  module: README
+  kind: readme
+  source_glob:
+  - src/constant_docs/cli.py
+  - src/constant_docs/kinds.py
+  - src/constant_docs/api.py
+  - plugin/hooks/hooks.json
+  - pyproject.toml
+  source_files:
+  - plugin/hooks/hooks.json
+  - pyproject.toml
+  - src/constant_docs/api.py
+  - src/constant_docs/cli.py
+  - src/constant_docs/kinds.py
+  source_hash: sha256:fc83f9e4fa284f88138c90b174bbd6452527577e4a329b8edb68673c5e33c26a
+  hash_method: sha256-over-sorted-path-and-content
+  hash_covers: source_files
+  timestamp: '2026-08-26T15:46:02Z'
+  generator: constant-docs/0.4.0
+  generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/SPEC.md
+-->
+
+
+
+
+
+# constant-docs
+
+**Documentation that writes and maintains itself.**
+
+A command-line tool and a Python library. It runs in any repository, in any
+language, driven by whatever coding agent you already use.
+
+Agents ship code faster than anyone can keep the docs up to date.
+
+Each document records a hash of the code behind it. Change that code and the
+document goes stale. constant-docs names what fell behind, and your agent
+rewrites it.
+
+```console
+$ constant-docs verify
+Stale modules: src/payments
+```
+
+## How the loop works
+
+Edit a file, and the document describing it is already behind. The loop closes
+inside the same turn:
+
+```console
+$ constant-docs verify
+All modules up to date.
+
+$ echo 'def refund(charge_id: str) -> None: ...' >> src/payments/core.py
+
+$ constant-docs verify
+Stale modules: src/payments
+
+$ # your agent reads the source, rewrites docs/src/payments.md, and:
+
+$ 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
+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:
+
+```yaml
+- run: constant-docs verify
+```
+
+## Install
+
+```bash
+pip install constant-docs        # or: uv add constant-docs
+```
+
+One dependency, PyYAML. Python 3.11 or newer.
+
+## Try it
+
+```bash
+cd examples/sample-repo
+constant-docs verify
+```
+
+```console
+Missing documents: src/ledger, src/payments
+```
+
+Point it at your own repository with a `constant-docs.yaml` at the root:
+
+```yaml
+version: 1
+docs_root: docs
+
+modules:
+  src/payments: src/payments/**/*.py
+  src/ledger: src/ledger/**/*.py
+```
+
+`constant-docs verify` now names what is missing.
+
+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.
+
+## Driving it from your agent
+
+Three commands carry the whole integration, and none of them names a particular
+tool:
+
+| Command | Run it | It does |
+|---|---|---|
+| `constant-docs mark <path>` | after your agent writes a file | notes which documents that path affects. A glob match and a dictionary insert |
+| `constant-docs settle --json` | when your agent goes quiet | names what the marks turned up, and hands over each document's files, its previous text, and the conventions to write against |
+| `constant-docs apply <module> "<body>"` | once your agent has written | stores the text and moves the hash |
+
+A shell script drives that loop. So does a Makefile, a git hook, or a person:
+
+```console
+$ git diff --name-only | xargs constant-docs mark
+$ constant-docs settle --json
+```
+
+`settle` reports what `mark` recorded, so a harness that skips the marking step
+sees an empty list. `plan --json` considers every module, and `verify` hashes
+everything and exits 1 on drift whatever the marks say. Keep `verify` as the
+gate.
+
+**Claude Code gets a plugin.** Install it from `plugin/` 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.
+
+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.
+
+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.
+
+| Kind | For | Mode |
+|---|---|---|
+| `module` | A set of source files. The default | replace |
+| `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 |
+| `config-reference` | Every configuration key | replace |
+| `cli-reference` | Every command and flag | replace |
+
+```yaml
+modules:
+  src/payments: src/payments/**/*.py    # kind `module`, the default
+
+  SPEC:
+    glob: ["src/**/*.py", "tests/test_*.py"]
+    kind: spec
+
+  SECURITY:
+    covers: [src/payments, src/web]     # follows when either glob moves
+    kind: spec
+```
+
+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 prompts receive, so the rules cannot drift apart.
+
+## Finding what is undocumented
+
+```bash
+constant-docs init          # what is here, and what covers none of it
+constant-docs coverage      # source no module covers, by directory
+```
+
+`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.
+
+`verify --coverage` folds it into the gate, opt-in. And `init` never removes: it
+proposes, because dropping a module orphans its document and `prune` deletes
+it.
+
+**Already have a `docs/` folder? Pointing the tool at it is safe.** `prune`
+deletes only documents carrying this tool's frontmatter. Your hand-written
+decision record belongs to somebody else, so the tool never touches it. It
+names those files on every run, so you never mistake silence for *"there was
+nothing else"*. It still *reports* them, because the docs root is a bundle and
+they do not conform to it. Refusing to check a file and refusing to delete it
+are two different things.
+
+## Running it on a schedule
+
+Hooks need a live session. Changes also arrive from a timer, a chat client, or
+somebody editing files directly, and nothing fires for those. `auto` runs a
+command you declare, then checks what it left behind:
+
+```yaml
+auto:
+  command: "<your agent> -p 'Run the constant-docs settle loop'"
+  when: stale
+  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, 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.
+
+## 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. Rewording is always
+free; only losing is not. Retiring one is deliberate and gets written into the
+document.
+
+**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.
+
+**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
+
+```markdown
+---
+type: Code Module
+title: Payments
+description: Reconciles inbound payment events against ledger entries.
+tags: [code-module]
+
+constant_docs:
+  module: src/payments
+  kind: module
+  source_glob: src/payments/**/*.py
+  source_files:
+  - src/payments/core.py
+  - src/payments/reconcile.py
+  source_hash: sha256:a3f1c07e…
+  hash_method: sha256-over-sorted-path-and-content
+  hash_covers: source_files
+  timestamp: '2026-08-19T09:14:00Z'
+  generator: constant-docs/0.4.0
+  generator_spec: https://github.com/ashborn-systems/constant-docs/blob/main/docs/SPEC.md
+---
+## Purpose
+
+Owns the mapping between external payment events and internal ledger entries.
+Callers submit a batch and receive a report. Matching strategy, retry policy,
+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.
+
+## Known failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Report totals disagree with the ledger | Batch submitted while a ledger write was in flight | Submit batches only from the settled-state queue |
+```
+
+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. 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.
+
+## Python API
+
+```python
+from constant_docs import append, apply, plan, prune, settle, verify
+
+p = plan(changed_paths=["src/payments/reconcile.py"])
+apply("src/payments", body="## Purpose\n…")  # writes only if the body differs
+append("CHANGELOG", entry="…", title="0.3.0")
+report = verify()  # no writes, no network
+prune()  # delete orphaned documents
+```
+
+## What it does not do
+
+No model client, no network call, no source parsing. No AST, no tree-sitter,
+no import graph. Modules are globs and files are bytes, which is what makes
+"any language" a property here.
+
+It cannot catch writing about the world outside your files. A document saying
+a disk is half full 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.
+
+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 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.
+
+**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.
+
+## Reading further
+
+- [Specification](docs/SPEC.md) — the full design and its 156 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).