docpolicy 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of docpolicy might be problematic. Click here for more details.
- docpolicy-0.1.0/.docpolicy.yaml +31 -0
- docpolicy-0.1.0/LICENSE +21 -0
- docpolicy-0.1.0/MANIFEST.in +10 -0
- docpolicy-0.1.0/PKG-INFO +276 -0
- docpolicy-0.1.0/README.md +256 -0
- docpolicy-0.1.0/deploy_plugin.sh +76 -0
- docpolicy-0.1.0/docpolicy/__init__.py +3 -0
- docpolicy-0.1.0/docpolicy/__main__.py +4 -0
- docpolicy-0.1.0/docpolicy/checks.py +505 -0
- docpolicy-0.1.0/docpolicy/classify.py +37 -0
- docpolicy-0.1.0/docpolicy/cli.py +401 -0
- docpolicy-0.1.0/docpolicy/frontmatter.py +38 -0
- docpolicy-0.1.0/docpolicy/miniyaml.py +195 -0
- docpolicy-0.1.0/docpolicy/policy.py +172 -0
- docpolicy-0.1.0/docpolicy/triage.py +587 -0
- docpolicy-0.1.0/docpolicy.egg-info/PKG-INFO +276 -0
- docpolicy-0.1.0/docpolicy.egg-info/SOURCES.txt +31 -0
- docpolicy-0.1.0/docpolicy.egg-info/dependency_links.txt +1 -0
- docpolicy-0.1.0/docpolicy.egg-info/entry_points.txt +2 -0
- docpolicy-0.1.0/docpolicy.egg-info/top_level.txt +1 -0
- docpolicy-0.1.0/docs/design.md +74 -0
- docpolicy-0.1.0/hermes_plugin/README.md +52 -0
- docpolicy-0.1.0/hermes_plugin/__init__.py +557 -0
- docpolicy-0.1.0/hermes_plugin/cli.py +77 -0
- docpolicy-0.1.0/hermes_plugin/plugin.yaml +15 -0
- docpolicy-0.1.0/hermes_plugin/tests/__init__.py +0 -0
- docpolicy-0.1.0/hermes_plugin/tests/test_plugin.py +445 -0
- docpolicy-0.1.0/pyproject.toml +32 -0
- docpolicy-0.1.0/scripts/docpolicy_all.sh +82 -0
- docpolicy-0.1.0/scripts/docpolicy_audit_email.sh +46 -0
- docpolicy-0.1.0/scripts/inbox_sweep.sh +50 -0
- docpolicy-0.1.0/setup.cfg +4 -0
- docpolicy-0.1.0/tests/test_docpolicy.py +660 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# docpolicy — one policy per repo. Docs: see the docpolicy README.
|
|
2
|
+
# Class order matters: FIRST matching class wins — declare narrow classes
|
|
3
|
+
# (archive, ephemeral) BEFORE broad canonical globs.
|
|
4
|
+
version: 1
|
|
5
|
+
|
|
6
|
+
classes:
|
|
7
|
+
- id: archive
|
|
8
|
+
mode: archive
|
|
9
|
+
paths: ["**/archive/**"]
|
|
10
|
+
- id: scratch
|
|
11
|
+
mode: ephemeral
|
|
12
|
+
paths: [".hermes/plans/**"]
|
|
13
|
+
max_age_days: 2
|
|
14
|
+
require_pointer: true
|
|
15
|
+
- id: inbox
|
|
16
|
+
mode: inbox
|
|
17
|
+
paths: ["inbox/**"]
|
|
18
|
+
dest: "docs"
|
|
19
|
+
max_age_days: 14
|
|
20
|
+
- id: generated
|
|
21
|
+
mode: generated
|
|
22
|
+
paths: []
|
|
23
|
+
generator: ""
|
|
24
|
+
- id: exempt
|
|
25
|
+
mode: exempt
|
|
26
|
+
paths:
|
|
27
|
+
- "README.md"
|
|
28
|
+
- "hermes_plugin/README.md"
|
|
29
|
+
- id: docs
|
|
30
|
+
mode: canonical
|
|
31
|
+
paths: ["docs/**/*.md"]
|
docpolicy-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Roger Holenweger
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include LICENSE
|
|
3
|
+
include .docpolicy.yaml
|
|
4
|
+
include deploy_plugin.sh
|
|
5
|
+
recursive-include docpolicy *.py
|
|
6
|
+
recursive-include docs *.md
|
|
7
|
+
recursive-include hermes_plugin *.py *.yaml *.md
|
|
8
|
+
recursive-include scripts *.sh
|
|
9
|
+
recursive-include tests *.py
|
|
10
|
+
global-exclude __pycache__ *.py[cod]
|
docpolicy-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: docpolicy
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Portable documentation-drift enforcement — one policy file per repo, one stdlib-only checker, several enforcement surfaces.
|
|
5
|
+
Author: Roger Holenweger
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/rogerholenweger/docpolicy
|
|
8
|
+
Project-URL: Repository, https://github.com/rogerholenweger/docpolicy
|
|
9
|
+
Project-URL: Issues, https://github.com/rogerholenweger/docpolicy/issues
|
|
10
|
+
Keywords: documentation,docs,lint,policy,frontmatter,agent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Topic :: Documentation
|
|
13
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# docpolicy
|
|
22
|
+
|
|
23
|
+
Portable documentation-drift enforcement for repos maintained by a human + AI coding agent. One policy file per repo, one checker, several enforcement surfaces (Hermes plugin hooks, git pre-commit, pre-deploy gate, cron audits) that all run the same binary — no surface carries rules of its own.
|
|
24
|
+
|
|
25
|
+
Works on any machine: the checker is Python 3 stdlib only, no dependencies. The optional LLM label layer is the only network consumer, and it never enforces anything.
|
|
26
|
+
|
|
27
|
+
**Repo layout:**
|
|
28
|
+
|
|
29
|
+
| Path | Purpose |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `docpolicy/` | checker package (`python3 -m docpolicy`) |
|
|
32
|
+
| `hermes_plugin/` | Hermes plugin: hooks, tools, `hermes docpolicy` CLI |
|
|
33
|
+
| `scripts/` | cron helpers + multi-repo runner: `docpolicy_all.sh` (check/audit across all repos, one command), `docpolicy_audit_email.sh` (weekly audit), `inbox_sweep.sh` (daily inbox digest, never promotes) |
|
|
34
|
+
| `deploy_plugin.sh` | install/refresh the plugin symlink, drift-guarded |
|
|
35
|
+
| `docs/` | design note for the inbox-triage subsystem (`docs/design.md`) |
|
|
36
|
+
| `tests/` | unittest suite (`python3 -m unittest discover tests`) |
|
|
37
|
+
|
|
38
|
+
## The invariant
|
|
39
|
+
|
|
40
|
+
The enforceable form of "only one doc". Every doc carries frontmatter:
|
|
41
|
+
|
|
42
|
+
```yaml
|
|
43
|
+
---
|
|
44
|
+
subject: sprint-plan # the identity: ONE active doc per subject
|
|
45
|
+
status: active # active | superseded | archived | draft
|
|
46
|
+
superseded_by: plans/new.md # required when status: superseded
|
|
47
|
+
---
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- For every `subject` value, **exactly one** doc may have `status: active`.
|
|
51
|
+
- Any other doc with that subject must be `status: superseded` with `superseded_by` pointing at the active doc.
|
|
52
|
+
- Collisions, dangling pointers, missing frontmatter, stale generated docs, broken links, and dead issue references are all mechanical findings — nothing relies on memory or discipline.
|
|
53
|
+
|
|
54
|
+
Replacing a doc (the "versioning" half of the deal):
|
|
55
|
+
|
|
56
|
+
1. Write the new doc: `subject: ladder`, `status: active`.
|
|
57
|
+
2. Flip the old one: `subject: ladder`, `status: superseded`, `superseded_by: <new path>`.
|
|
58
|
+
3. Commit. The checker enforces 1+2 as a pair (`C2` + `C3`).
|
|
59
|
+
|
|
60
|
+
## CLI
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
docpolicy init [--repo DIR] [--force] # policy template + .githooks/pre-commit + core.hooksPath
|
|
64
|
+
docpolicy check [--repo DIR] [--staged] [--files P ...] [--stdin-file R] [--json] [--advisory]
|
|
65
|
+
docpolicy audit [--repo DIR] [--json] [--advisory] # full pass (adds C4-C6, C8, C10, C12)
|
|
66
|
+
docpolicy brief [--repo DIR] [--md] # policy table (injected into agent sessions)
|
|
67
|
+
docpolicy fix [--repo DIR] [--dry-run] [--apply] # mechanical frontmatter conformance
|
|
68
|
+
docpolicy triage [--repo DIR] [--json] [--apply] [--force] [--queue --project CODE] [--llm] [--no-llm]
|
|
69
|
+
docpolicy llm [--json] [--set-key] [--set-model M] [--set-base URL] [--clear]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Via the Hermes plugin (same checker, any cwd):
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
hermes docpolicy <check|audit|brief|fix|triage|llm> [args...]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Exit codes:** `0` clean/advisory · `1` error-severity findings · `2` config error.
|
|
79
|
+
|
|
80
|
+
## Quickstart (new repo)
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
PYTHONPATH=/path/to/docpolicy python3 -m docpolicy init --repo ~/src/newrepo
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
This writes `.docpolicy.yaml` + `.githooks/pre-commit` and sets `git config core.hooksPath=.githooks`. Then **edit the classes** to match the repo (see [Policy reference](#policy-reference)).
|
|
87
|
+
|
|
88
|
+
For repos maintained through this Hermes instance, also deploy the plugin (see [Enforcement surfaces](#enforcement-surfaces)) — the pre-commit hook alone already covers human + agent commits; the plugin adds real-time blocking and inbox pickup.
|
|
89
|
+
|
|
90
|
+
## Daily workflows
|
|
91
|
+
|
|
92
|
+
### Capture: drop a raw document
|
|
93
|
+
|
|
94
|
+
Drop any file into the repo's `inbox/` directory. No frontmatter needed — inbox docs are deliberately exempt from the frontmatter contract and from `FM`/`C2`/`C9` (zero friction at capture time is the point). The cost surfaces as two advisory checks instead:
|
|
95
|
+
|
|
96
|
+
- `C11` — capture older than the inbox class's `max_age_days` → triage or delete.
|
|
97
|
+
- `C10` — two active docs sharing 2+ tags → same topic? merge or differentiate.
|
|
98
|
+
|
|
99
|
+
The plugin's `pre_llm_call` hook injects an inbox notice into agent sessions ("N untriaged captures...") so captures cannot be silently forgotten.
|
|
100
|
+
|
|
101
|
+
### Triage: turn captures into canonical docs
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
hermes docpolicy triage --repo . # propose only (LLM labels when a key is configured)
|
|
105
|
+
hermes docpolicy triage --repo . --no-llm # propose with deterministic labels
|
|
106
|
+
hermes docpolicy triage --repo . --apply # promote items with NO open questions
|
|
107
|
+
hermes docpolicy triage --repo . --apply --llm # same, forcing the LLM layer (~60s per doc)
|
|
108
|
+
hermes docpolicy triage --repo . --force # promote even flagged items
|
|
109
|
+
hermes docpolicy triage --repo . --queue # file a queue.db task per flagged item
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
- Proposals carry subject/title/description/tags/related-docs/confidence and a destination (the inbox class's `dest`, e.g. `docs/research`).
|
|
113
|
+
- Label source: when an LLM key is configured (env or `~/.hermes/docpolicy/llm.json`) triage applies the model layer **by default**; `--no-llm` forces deterministic labels, `--llm` forces the model layer (it degrades to deterministic labels when no key is set).
|
|
114
|
+
- `--apply` never promotes a flagged item; `--force` does; `--queue` files a task instead (project code from `--project` or the policy's `project:` key).
|
|
115
|
+
- Promotion writes **one** frontmatter block carrying both docpolicy (`subject`/`status`) and OKF (`type`/`title`/`description`/`tags`/`timestamp`/`source`) fields — a second block would be invisible to the brain's FTS index.
|
|
116
|
+
- Triage is propose-only by default. Nothing is ever auto-promoted.
|
|
117
|
+
|
|
118
|
+
### Re-triage an old doc (pre-docpolicy or badly labeled)
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
git mv docs/Junk_stem.md inbox/
|
|
122
|
+
hermes docpolicy triage --repo . --apply --llm
|
|
123
|
+
# review proposals, then: audit, repair any C5 broken links, commit
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Batch in small groups; each LLM-labeled doc costs ~60s. `git mv` keeps history.
|
|
127
|
+
|
|
128
|
+
### Write or edit a canonical doc
|
|
129
|
+
|
|
130
|
+
Frontmatter (`subject` + `status`) is required on canonical docs. The plugin evaluates content **before** it lands (`write_file` content goes through a virtual doc): a write that would produce missing frontmatter, a second active doc for an existing subject, or a rule-violating write into an archive/ephemeral class gets **blocked** with the exact fix in the message. Fix and rewrite — do not `--no-verify`. Existing OKF frontmatter (`type`/`title`/`tags`/...) is preserved; docpolicy only requires `subject` + `status`.
|
|
131
|
+
|
|
132
|
+
### Retire a doc
|
|
133
|
+
|
|
134
|
+
Move it into the archive class (`docs/archive/**` here) with `status: superseded` (+ `superseded_by`) or `archived`. Archive docs must not be `status: active` (`C9`).
|
|
135
|
+
|
|
136
|
+
### Check / audit / fix / brief
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
hermes docpolicy check --repo . # fast: C1-C3, FM, C7, C9, C11 (per-commit safe)
|
|
140
|
+
hermes docpolicy audit --repo . # full: everything
|
|
141
|
+
hermes docpolicy audit --repo . --json # machine-readable
|
|
142
|
+
hermes docpolicy audit --repo . --advisory # all warn-level, exit 0 (scoring runs)
|
|
143
|
+
hermes docpolicy fix --repo . --dry-run # propose frontmatter for unlabelled canonical docs
|
|
144
|
+
hermes docpolicy fix --repo . --apply # write them (subject = filename stem)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Policy reference
|
|
148
|
+
|
|
149
|
+
`.docpolicy.yaml` at the repo root:
|
|
150
|
+
|
|
151
|
+
```yaml
|
|
152
|
+
version: 1
|
|
153
|
+
sources:
|
|
154
|
+
issues: ~/notes/queue.db # task store for C6 (PROJECT-NN refs)
|
|
155
|
+
project: NAT # default project code for triage --queue
|
|
156
|
+
classes:
|
|
157
|
+
- id: archive
|
|
158
|
+
mode: archive
|
|
159
|
+
paths: ["docs/archive/**"]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**Class order matters: first matching class wins.** Declare narrow classes (`archive`, `ephemeral`, `inbox`, `exempt`) **before** broad canonical globs.
|
|
163
|
+
|
|
164
|
+
| Mode | Extra keys | Meaning |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| `canonical` | — | the real docs; frontmatter contract enforced |
|
|
167
|
+
| `generated` | `generator`, `facts` | build output; `C4` re-runs the generator and diffs (side-effect free: bytes restored). With `facts:` (a JSON file the generator writes), specs' `assert:` frontmatter is checked against it (`C12`) |
|
|
168
|
+
| `archive` | — | history; must not be `status: active` (`C9`) |
|
|
169
|
+
| `ephemeral` | `max_age_days`, `require_pointer` | session scratch; ages out (`C7`) and must link to a canonical doc (the `.hermes/plans` rule) |
|
|
170
|
+
| `append-only` | — | logs; never checked for frontmatter |
|
|
171
|
+
| `exempt` | — | path-classified only, content **never** read (secrets: `.env`, key files, legal, licenses) |
|
|
172
|
+
| `inbox` | `dest`, `max_age_days` | raw captures; exempt from `FM`/`C2`/`C9`; ages into `C11`; triage promotes to `dest` |
|
|
173
|
+
|
|
174
|
+
Severity defaults — errors: `C1 C2 C3 C4 C7 C9 C12 FM`; warnings: `C5 C6 C8 C10 C11`. Override per repo (known codes only):
|
|
175
|
+
|
|
176
|
+
```yaml
|
|
177
|
+
# Block style only: miniyaml does not parse inline maps,
|
|
178
|
+
# so "severity: { C5: error }" would parse as a string and be ignored.
|
|
179
|
+
rules:
|
|
180
|
+
severity:
|
|
181
|
+
C5: error
|
|
182
|
+
C10: off
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Checks reference
|
|
186
|
+
|
|
187
|
+
| Code | Sev | Meaning / fix |
|
|
188
|
+
|---|---|---|
|
|
189
|
+
| `C1` | error | unclassified file — add a class glob or move the file |
|
|
190
|
+
| `C2` | error | subject has >1 active doc — supersede all but one |
|
|
191
|
+
| `C3` | error | superseded doc missing/invalid `superseded_by` — point at the active doc |
|
|
192
|
+
| `C4` | error | generated file stale — re-run the generator (audit restores bytes) |
|
|
193
|
+
| `C5` | warn | broken relative md link — repair or unlink |
|
|
194
|
+
| `C6` | warn | `PROJECT-NN` reference not in the task store (codes are read *from* the store, so `SHA-256`/`AVX-512` cannot false-positive) |
|
|
195
|
+
| `C7` | error | ephemeral doc too old or missing pointer to a canonical doc |
|
|
196
|
+
| `C8` | warn | duplicate H1 across canonical docs — one subject, one doc? |
|
|
197
|
+
| `C9` | error | archive doc with active status — set superseded/archived |
|
|
198
|
+
| `C10` | warn | two active docs sharing ≥2 tags — same topic? merge or differentiate |
|
|
199
|
+
| `C11` | warn | inbox capture older than `max_age_days` — triage or delete |
|
|
200
|
+
| `C12` | error | spec `assert:` frontmatter contradicts the machine facts file — fix the doc or the code, then regenerate |
|
|
201
|
+
| `FM` | error | canonical doc without/malformed frontmatter — add `subject` + `status` |
|
|
202
|
+
|
|
203
|
+
Per-file semantics: in `--files` / `--stdin-file` mode, `C2`/`C3` still scan the whole repo but only report findings involving the target — a pre-existing collision elsewhere never blocks an unrelated write.
|
|
204
|
+
|
|
205
|
+
## Enforcement surfaces
|
|
206
|
+
|
|
207
|
+
All surfaces run the same checker.
|
|
208
|
+
|
|
209
|
+
1. **Hermes plugin** (`hermes_plugin/`, deploy via `deploy_plugin.sh`):
|
|
210
|
+
- `pre_tool_call` — **blocks** `write_file`/`patch`/`create_file` on `*.md` that would violate `FM`/`C2`/`C7`/`C9`; `write_file` content is evaluated pre-write (virtual doc via `--stdin-file`); `patch` is evaluated against the on-disk state **before** the patch applies, so a patch that introduces a new violation is caught by the pre-commit hook, not here; fail-open on internal errors so a broken plugin cannot brick the agent.
|
|
211
|
+
- `pre_llm_call` — injects the inbox notice ("N untriaged captures...").
|
|
212
|
+
- `on_session_start` — logs `docpolicy brief --md` to the session log (observer hook: return values are ignored, only `pre_llm_call` injects into the turn).
|
|
213
|
+
- `on_session_end` — logs a one-line check summary.
|
|
214
|
+
- Tools: `docpolicy_brief`, `docpolicy_check`, `docpolicy_triage`.
|
|
215
|
+
- Runtime state: `~/.hermes/docpolicy/` (`config.json` = plugin settings `{advisory, repos}`, `advisory.log`) — deliberately **not** inside the plugin install path (a symlink to this repo). Knobs: `advisory: true` = log-only, never block; `repos: [...]` = empty means all repos with a policy file.
|
|
216
|
+
2. **git pre-commit** — `.githooks/pre-commit` via `core.hooksPath`; checks **staged** `.md` files; blocks the commit on error-severity findings (`--no-verify` works but is discouraged).
|
|
217
|
+
3. **pre-deploy gate** — a deploy script runs `check` as a phase before shipping; the deploy aborts on error findings.
|
|
218
|
+
4. **Cron** (email-only alerting via msmtp):
|
|
219
|
+
- `10 8 * * 0` — `scripts/docpolicy_audit_email.sh`: weekly full audit across `DOCPOLICY_REPOS`; emails `DOCPOLICY_AUDIT_TO` only on findings.
|
|
220
|
+
- `20 8 * * *` — `scripts/inbox_sweep.sh`: daily inbox digest; **never** promotes anything.
|
|
221
|
+
|
|
222
|
+
## Multi-repo runner
|
|
223
|
+
|
|
224
|
+
One command checks every repo that has a policy:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
docpolicy-all # fast check (C1-C3, frontmatter, archive) on all repos
|
|
228
|
+
docpolicy-all --audit # full audit (adds C4-C8, C10, C12)
|
|
229
|
+
docpolicy-all notes # subset: named repos only (basename or path)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
- Installed as `~/.local/bin/docpolicy-all` → symlink to `scripts/docpolicy_all.sh`; runs from any cwd.
|
|
233
|
+
- Default repo list: `DOCPOLICY_REPOS` (space-separated paths), else the `REPOS` array in the script. Repos without a `.docpolicy.yaml` are skipped with a note — add each repo once you init it.
|
|
234
|
+
- Prints a one-line summary per repo; exit `1` if any repo has error findings.
|
|
235
|
+
- Human-readable summary line per repo; use `docpolicy check --repo <dir>` directly for full per-finding detail.
|
|
236
|
+
|
|
237
|
+
## LLM label layer (optional)
|
|
238
|
+
|
|
239
|
+
Labels only — it never decides placement and is never required. Resolution: env (`DOCPOLICY_LLM_KEY` | `OPENROUTER_API_KEY`, `DOCPOLICY_LLM_MODEL`, `DOCPOLICY_LLM_BASE`, `DOCPOLICY_LLM_TIMEOUT`) → config file → defaults (model `qwen/qwen3.8-flash`, base `https://openrouter.ai/api/v1`).
|
|
240
|
+
|
|
241
|
+
```bash
|
|
242
|
+
hermes docpolicy llm # show resolved config + key source
|
|
243
|
+
hermes docpolicy llm --set-key # key from hidden stdin, stored 0600
|
|
244
|
+
hermes docpolicy llm --set-model qwen/qwen3.8-flash
|
|
245
|
+
hermes docpolicy llm --clear # remove the config file
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- Config file: `~/.hermes/docpolicy/llm.json` (`DOCPOLICY_LLM_CONFIG` overrides the path). `llm.json` is the checker's credential file (0600); `config.json` in the same directory is the plugin's state — different owners.
|
|
249
|
+
- Env note: commands run under `hermes` inherit Hermes' secrets, so `hermes docpolicy triage` may be model-enabled while a bare shell or cron run is not — set `llm.json` when cron should match. The checker never reads Hermes' own provider config.
|
|
250
|
+
- Fail-open: any LLM error degrades to deterministic labels (`prop.llm` records why).
|
|
251
|
+
|
|
252
|
+
## Troubleshooting
|
|
253
|
+
|
|
254
|
+
| Symptom | Cause / fix |
|
|
255
|
+
|---|---|
|
|
256
|
+
| Write blocked with `ERROR [FM]...` | the doc needs frontmatter — add `subject` + `status`; do not `--no-verify` |
|
|
257
|
+
| OpenRouter 401 `Missing Authentication header` or `User not found.` | the stored key is **malformed**, not a model/network problem. Canonical shape: `sk-or-v1-` + exactly 64 hex (73 chars). Re-set: `hermes docpolicy llm --set-key` |
|
|
258
|
+
| triage tool call times out (~8s) | the Hermes tool wrapper caps runtime; run the CLI directly with `--llm` and a generous timeout, or `--no-llm` |
|
|
259
|
+
| audit "0 findings" right after an inbox drop | correct — inbox is exempt until triaged; `C11` ages stale captures out |
|
|
260
|
+
| `--repodir: unrecognized argument` | the flag is `--repo` |
|
|
261
|
+
| Will an audit mutate my repo? | No: `C4` re-runs generators and restores the original bytes afterwards |
|
|
262
|
+
|
|
263
|
+
## Status
|
|
264
|
+
|
|
265
|
+
Self-hosting: this repo carries its own `.docpolicy.yaml` and a pre-commit hook
|
|
266
|
+
(`core.hooksPath=.githooks`), so a commit that violates the policy is rejected by
|
|
267
|
+
the same checker the repo ships. Both test suites are stdlib-only and run offline.
|
|
268
|
+
|
|
269
|
+
- Version 0.1.0 — check codes, class modes and CLI flags are stable; internal
|
|
270
|
+
modules (`miniyaml`, the triage heuristics) may still move.
|
|
271
|
+
- Known limits are documented in `docs/design.md`: related-doc scoring is
|
|
272
|
+
bag-of-words overlap (no embeddings), and the LLM layer only ever labels —
|
|
273
|
+
it never decides placement or blocks anything.
|
|
274
|
+
- Secrets hygiene: `exempt`-classed docs are never read beyond path
|
|
275
|
+
classification, and the optional LLM credential (`llm.json`, 0600) is the only
|
|
276
|
+
credential file the checker touches.
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
# docpolicy
|
|
2
|
+
|
|
3
|
+
Portable documentation-drift enforcement for repos maintained by a human + AI coding agent. One policy file per repo, one checker, several enforcement surfaces (Hermes plugin hooks, git pre-commit, pre-deploy gate, cron audits) that all run the same binary — no surface carries rules of its own.
|
|
4
|
+
|
|
5
|
+
Works on any machine: the checker is Python 3 stdlib only, no dependencies. The optional LLM label layer is the only network consumer, and it never enforces anything.
|
|
6
|
+
|
|
7
|
+
**Repo layout:**
|
|
8
|
+
|
|
9
|
+
| Path | Purpose |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `docpolicy/` | checker package (`python3 -m docpolicy`) |
|
|
12
|
+
| `hermes_plugin/` | Hermes plugin: hooks, tools, `hermes docpolicy` CLI |
|
|
13
|
+
| `scripts/` | cron helpers + multi-repo runner: `docpolicy_all.sh` (check/audit across all repos, one command), `docpolicy_audit_email.sh` (weekly audit), `inbox_sweep.sh` (daily inbox digest, never promotes) |
|
|
14
|
+
| `deploy_plugin.sh` | install/refresh the plugin symlink, drift-guarded |
|
|
15
|
+
| `docs/` | design note for the inbox-triage subsystem (`docs/design.md`) |
|
|
16
|
+
| `tests/` | unittest suite (`python3 -m unittest discover tests`) |
|
|
17
|
+
|
|
18
|
+
## The invariant
|
|
19
|
+
|
|
20
|
+
The enforceable form of "only one doc". Every doc carries frontmatter:
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
---
|
|
24
|
+
subject: sprint-plan # the identity: ONE active doc per subject
|
|
25
|
+
status: active # active | superseded | archived | draft
|
|
26
|
+
superseded_by: plans/new.md # required when status: superseded
|
|
27
|
+
---
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- For every `subject` value, **exactly one** doc may have `status: active`.
|
|
31
|
+
- Any other doc with that subject must be `status: superseded` with `superseded_by` pointing at the active doc.
|
|
32
|
+
- Collisions, dangling pointers, missing frontmatter, stale generated docs, broken links, and dead issue references are all mechanical findings — nothing relies on memory or discipline.
|
|
33
|
+
|
|
34
|
+
Replacing a doc (the "versioning" half of the deal):
|
|
35
|
+
|
|
36
|
+
1. Write the new doc: `subject: ladder`, `status: active`.
|
|
37
|
+
2. Flip the old one: `subject: ladder`, `status: superseded`, `superseded_by: <new path>`.
|
|
38
|
+
3. Commit. The checker enforces 1+2 as a pair (`C2` + `C3`).
|
|
39
|
+
|
|
40
|
+
## CLI
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
docpolicy init [--repo DIR] [--force] # policy template + .githooks/pre-commit + core.hooksPath
|
|
44
|
+
docpolicy check [--repo DIR] [--staged] [--files P ...] [--stdin-file R] [--json] [--advisory]
|
|
45
|
+
docpolicy audit [--repo DIR] [--json] [--advisory] # full pass (adds C4-C6, C8, C10, C12)
|
|
46
|
+
docpolicy brief [--repo DIR] [--md] # policy table (injected into agent sessions)
|
|
47
|
+
docpolicy fix [--repo DIR] [--dry-run] [--apply] # mechanical frontmatter conformance
|
|
48
|
+
docpolicy triage [--repo DIR] [--json] [--apply] [--force] [--queue --project CODE] [--llm] [--no-llm]
|
|
49
|
+
docpolicy llm [--json] [--set-key] [--set-model M] [--set-base URL] [--clear]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Via the Hermes plugin (same checker, any cwd):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
hermes docpolicy <check|audit|brief|fix|triage|llm> [args...]
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Exit codes:** `0` clean/advisory · `1` error-severity findings · `2` config error.
|
|
59
|
+
|
|
60
|
+
## Quickstart (new repo)
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
PYTHONPATH=/path/to/docpolicy python3 -m docpolicy init --repo ~/src/newrepo
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
This writes `.docpolicy.yaml` + `.githooks/pre-commit` and sets `git config core.hooksPath=.githooks`. Then **edit the classes** to match the repo (see [Policy reference](#policy-reference)).
|
|
67
|
+
|
|
68
|
+
For repos maintained through this Hermes instance, also deploy the plugin (see [Enforcement surfaces](#enforcement-surfaces)) — the pre-commit hook alone already covers human + agent commits; the plugin adds real-time blocking and inbox pickup.
|
|
69
|
+
|
|
70
|
+
## Daily workflows
|
|
71
|
+
|
|
72
|
+
### Capture: drop a raw document
|
|
73
|
+
|
|
74
|
+
Drop any file into the repo's `inbox/` directory. No frontmatter needed — inbox docs are deliberately exempt from the frontmatter contract and from `FM`/`C2`/`C9` (zero friction at capture time is the point). The cost surfaces as two advisory checks instead:
|
|
75
|
+
|
|
76
|
+
- `C11` — capture older than the inbox class's `max_age_days` → triage or delete.
|
|
77
|
+
- `C10` — two active docs sharing 2+ tags → same topic? merge or differentiate.
|
|
78
|
+
|
|
79
|
+
The plugin's `pre_llm_call` hook injects an inbox notice into agent sessions ("N untriaged captures...") so captures cannot be silently forgotten.
|
|
80
|
+
|
|
81
|
+
### Triage: turn captures into canonical docs
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
hermes docpolicy triage --repo . # propose only (LLM labels when a key is configured)
|
|
85
|
+
hermes docpolicy triage --repo . --no-llm # propose with deterministic labels
|
|
86
|
+
hermes docpolicy triage --repo . --apply # promote items with NO open questions
|
|
87
|
+
hermes docpolicy triage --repo . --apply --llm # same, forcing the LLM layer (~60s per doc)
|
|
88
|
+
hermes docpolicy triage --repo . --force # promote even flagged items
|
|
89
|
+
hermes docpolicy triage --repo . --queue # file a queue.db task per flagged item
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- Proposals carry subject/title/description/tags/related-docs/confidence and a destination (the inbox class's `dest`, e.g. `docs/research`).
|
|
93
|
+
- Label source: when an LLM key is configured (env or `~/.hermes/docpolicy/llm.json`) triage applies the model layer **by default**; `--no-llm` forces deterministic labels, `--llm` forces the model layer (it degrades to deterministic labels when no key is set).
|
|
94
|
+
- `--apply` never promotes a flagged item; `--force` does; `--queue` files a task instead (project code from `--project` or the policy's `project:` key).
|
|
95
|
+
- Promotion writes **one** frontmatter block carrying both docpolicy (`subject`/`status`) and OKF (`type`/`title`/`description`/`tags`/`timestamp`/`source`) fields — a second block would be invisible to the brain's FTS index.
|
|
96
|
+
- Triage is propose-only by default. Nothing is ever auto-promoted.
|
|
97
|
+
|
|
98
|
+
### Re-triage an old doc (pre-docpolicy or badly labeled)
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
git mv docs/Junk_stem.md inbox/
|
|
102
|
+
hermes docpolicy triage --repo . --apply --llm
|
|
103
|
+
# review proposals, then: audit, repair any C5 broken links, commit
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Batch in small groups; each LLM-labeled doc costs ~60s. `git mv` keeps history.
|
|
107
|
+
|
|
108
|
+
### Write or edit a canonical doc
|
|
109
|
+
|
|
110
|
+
Frontmatter (`subject` + `status`) is required on canonical docs. The plugin evaluates content **before** it lands (`write_file` content goes through a virtual doc): a write that would produce missing frontmatter, a second active doc for an existing subject, or a rule-violating write into an archive/ephemeral class gets **blocked** with the exact fix in the message. Fix and rewrite — do not `--no-verify`. Existing OKF frontmatter (`type`/`title`/`tags`/...) is preserved; docpolicy only requires `subject` + `status`.
|
|
111
|
+
|
|
112
|
+
### Retire a doc
|
|
113
|
+
|
|
114
|
+
Move it into the archive class (`docs/archive/**` here) with `status: superseded` (+ `superseded_by`) or `archived`. Archive docs must not be `status: active` (`C9`).
|
|
115
|
+
|
|
116
|
+
### Check / audit / fix / brief
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
hermes docpolicy check --repo . # fast: C1-C3, FM, C7, C9, C11 (per-commit safe)
|
|
120
|
+
hermes docpolicy audit --repo . # full: everything
|
|
121
|
+
hermes docpolicy audit --repo . --json # machine-readable
|
|
122
|
+
hermes docpolicy audit --repo . --advisory # all warn-level, exit 0 (scoring runs)
|
|
123
|
+
hermes docpolicy fix --repo . --dry-run # propose frontmatter for unlabelled canonical docs
|
|
124
|
+
hermes docpolicy fix --repo . --apply # write them (subject = filename stem)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Policy reference
|
|
128
|
+
|
|
129
|
+
`.docpolicy.yaml` at the repo root:
|
|
130
|
+
|
|
131
|
+
```yaml
|
|
132
|
+
version: 1
|
|
133
|
+
sources:
|
|
134
|
+
issues: ~/notes/queue.db # task store for C6 (PROJECT-NN refs)
|
|
135
|
+
project: NAT # default project code for triage --queue
|
|
136
|
+
classes:
|
|
137
|
+
- id: archive
|
|
138
|
+
mode: archive
|
|
139
|
+
paths: ["docs/archive/**"]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**Class order matters: first matching class wins.** Declare narrow classes (`archive`, `ephemeral`, `inbox`, `exempt`) **before** broad canonical globs.
|
|
143
|
+
|
|
144
|
+
| Mode | Extra keys | Meaning |
|
|
145
|
+
|---|---|---|
|
|
146
|
+
| `canonical` | — | the real docs; frontmatter contract enforced |
|
|
147
|
+
| `generated` | `generator`, `facts` | build output; `C4` re-runs the generator and diffs (side-effect free: bytes restored). With `facts:` (a JSON file the generator writes), specs' `assert:` frontmatter is checked against it (`C12`) |
|
|
148
|
+
| `archive` | — | history; must not be `status: active` (`C9`) |
|
|
149
|
+
| `ephemeral` | `max_age_days`, `require_pointer` | session scratch; ages out (`C7`) and must link to a canonical doc (the `.hermes/plans` rule) |
|
|
150
|
+
| `append-only` | — | logs; never checked for frontmatter |
|
|
151
|
+
| `exempt` | — | path-classified only, content **never** read (secrets: `.env`, key files, legal, licenses) |
|
|
152
|
+
| `inbox` | `dest`, `max_age_days` | raw captures; exempt from `FM`/`C2`/`C9`; ages into `C11`; triage promotes to `dest` |
|
|
153
|
+
|
|
154
|
+
Severity defaults — errors: `C1 C2 C3 C4 C7 C9 C12 FM`; warnings: `C5 C6 C8 C10 C11`. Override per repo (known codes only):
|
|
155
|
+
|
|
156
|
+
```yaml
|
|
157
|
+
# Block style only: miniyaml does not parse inline maps,
|
|
158
|
+
# so "severity: { C5: error }" would parse as a string and be ignored.
|
|
159
|
+
rules:
|
|
160
|
+
severity:
|
|
161
|
+
C5: error
|
|
162
|
+
C10: off
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Checks reference
|
|
166
|
+
|
|
167
|
+
| Code | Sev | Meaning / fix |
|
|
168
|
+
|---|---|---|
|
|
169
|
+
| `C1` | error | unclassified file — add a class glob or move the file |
|
|
170
|
+
| `C2` | error | subject has >1 active doc — supersede all but one |
|
|
171
|
+
| `C3` | error | superseded doc missing/invalid `superseded_by` — point at the active doc |
|
|
172
|
+
| `C4` | error | generated file stale — re-run the generator (audit restores bytes) |
|
|
173
|
+
| `C5` | warn | broken relative md link — repair or unlink |
|
|
174
|
+
| `C6` | warn | `PROJECT-NN` reference not in the task store (codes are read *from* the store, so `SHA-256`/`AVX-512` cannot false-positive) |
|
|
175
|
+
| `C7` | error | ephemeral doc too old or missing pointer to a canonical doc |
|
|
176
|
+
| `C8` | warn | duplicate H1 across canonical docs — one subject, one doc? |
|
|
177
|
+
| `C9` | error | archive doc with active status — set superseded/archived |
|
|
178
|
+
| `C10` | warn | two active docs sharing ≥2 tags — same topic? merge or differentiate |
|
|
179
|
+
| `C11` | warn | inbox capture older than `max_age_days` — triage or delete |
|
|
180
|
+
| `C12` | error | spec `assert:` frontmatter contradicts the machine facts file — fix the doc or the code, then regenerate |
|
|
181
|
+
| `FM` | error | canonical doc without/malformed frontmatter — add `subject` + `status` |
|
|
182
|
+
|
|
183
|
+
Per-file semantics: in `--files` / `--stdin-file` mode, `C2`/`C3` still scan the whole repo but only report findings involving the target — a pre-existing collision elsewhere never blocks an unrelated write.
|
|
184
|
+
|
|
185
|
+
## Enforcement surfaces
|
|
186
|
+
|
|
187
|
+
All surfaces run the same checker.
|
|
188
|
+
|
|
189
|
+
1. **Hermes plugin** (`hermes_plugin/`, deploy via `deploy_plugin.sh`):
|
|
190
|
+
- `pre_tool_call` — **blocks** `write_file`/`patch`/`create_file` on `*.md` that would violate `FM`/`C2`/`C7`/`C9`; `write_file` content is evaluated pre-write (virtual doc via `--stdin-file`); `patch` is evaluated against the on-disk state **before** the patch applies, so a patch that introduces a new violation is caught by the pre-commit hook, not here; fail-open on internal errors so a broken plugin cannot brick the agent.
|
|
191
|
+
- `pre_llm_call` — injects the inbox notice ("N untriaged captures...").
|
|
192
|
+
- `on_session_start` — logs `docpolicy brief --md` to the session log (observer hook: return values are ignored, only `pre_llm_call` injects into the turn).
|
|
193
|
+
- `on_session_end` — logs a one-line check summary.
|
|
194
|
+
- Tools: `docpolicy_brief`, `docpolicy_check`, `docpolicy_triage`.
|
|
195
|
+
- Runtime state: `~/.hermes/docpolicy/` (`config.json` = plugin settings `{advisory, repos}`, `advisory.log`) — deliberately **not** inside the plugin install path (a symlink to this repo). Knobs: `advisory: true` = log-only, never block; `repos: [...]` = empty means all repos with a policy file.
|
|
196
|
+
2. **git pre-commit** — `.githooks/pre-commit` via `core.hooksPath`; checks **staged** `.md` files; blocks the commit on error-severity findings (`--no-verify` works but is discouraged).
|
|
197
|
+
3. **pre-deploy gate** — a deploy script runs `check` as a phase before shipping; the deploy aborts on error findings.
|
|
198
|
+
4. **Cron** (email-only alerting via msmtp):
|
|
199
|
+
- `10 8 * * 0` — `scripts/docpolicy_audit_email.sh`: weekly full audit across `DOCPOLICY_REPOS`; emails `DOCPOLICY_AUDIT_TO` only on findings.
|
|
200
|
+
- `20 8 * * *` — `scripts/inbox_sweep.sh`: daily inbox digest; **never** promotes anything.
|
|
201
|
+
|
|
202
|
+
## Multi-repo runner
|
|
203
|
+
|
|
204
|
+
One command checks every repo that has a policy:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
docpolicy-all # fast check (C1-C3, frontmatter, archive) on all repos
|
|
208
|
+
docpolicy-all --audit # full audit (adds C4-C8, C10, C12)
|
|
209
|
+
docpolicy-all notes # subset: named repos only (basename or path)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
- Installed as `~/.local/bin/docpolicy-all` → symlink to `scripts/docpolicy_all.sh`; runs from any cwd.
|
|
213
|
+
- Default repo list: `DOCPOLICY_REPOS` (space-separated paths), else the `REPOS` array in the script. Repos without a `.docpolicy.yaml` are skipped with a note — add each repo once you init it.
|
|
214
|
+
- Prints a one-line summary per repo; exit `1` if any repo has error findings.
|
|
215
|
+
- Human-readable summary line per repo; use `docpolicy check --repo <dir>` directly for full per-finding detail.
|
|
216
|
+
|
|
217
|
+
## LLM label layer (optional)
|
|
218
|
+
|
|
219
|
+
Labels only — it never decides placement and is never required. Resolution: env (`DOCPOLICY_LLM_KEY` | `OPENROUTER_API_KEY`, `DOCPOLICY_LLM_MODEL`, `DOCPOLICY_LLM_BASE`, `DOCPOLICY_LLM_TIMEOUT`) → config file → defaults (model `qwen/qwen3.8-flash`, base `https://openrouter.ai/api/v1`).
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
hermes docpolicy llm # show resolved config + key source
|
|
223
|
+
hermes docpolicy llm --set-key # key from hidden stdin, stored 0600
|
|
224
|
+
hermes docpolicy llm --set-model qwen/qwen3.8-flash
|
|
225
|
+
hermes docpolicy llm --clear # remove the config file
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
- Config file: `~/.hermes/docpolicy/llm.json` (`DOCPOLICY_LLM_CONFIG` overrides the path). `llm.json` is the checker's credential file (0600); `config.json` in the same directory is the plugin's state — different owners.
|
|
229
|
+
- Env note: commands run under `hermes` inherit Hermes' secrets, so `hermes docpolicy triage` may be model-enabled while a bare shell or cron run is not — set `llm.json` when cron should match. The checker never reads Hermes' own provider config.
|
|
230
|
+
- Fail-open: any LLM error degrades to deterministic labels (`prop.llm` records why).
|
|
231
|
+
|
|
232
|
+
## Troubleshooting
|
|
233
|
+
|
|
234
|
+
| Symptom | Cause / fix |
|
|
235
|
+
|---|---|
|
|
236
|
+
| Write blocked with `ERROR [FM]...` | the doc needs frontmatter — add `subject` + `status`; do not `--no-verify` |
|
|
237
|
+
| OpenRouter 401 `Missing Authentication header` or `User not found.` | the stored key is **malformed**, not a model/network problem. Canonical shape: `sk-or-v1-` + exactly 64 hex (73 chars). Re-set: `hermes docpolicy llm --set-key` |
|
|
238
|
+
| triage tool call times out (~8s) | the Hermes tool wrapper caps runtime; run the CLI directly with `--llm` and a generous timeout, or `--no-llm` |
|
|
239
|
+
| audit "0 findings" right after an inbox drop | correct — inbox is exempt until triaged; `C11` ages stale captures out |
|
|
240
|
+
| `--repodir: unrecognized argument` | the flag is `--repo` |
|
|
241
|
+
| Will an audit mutate my repo? | No: `C4` re-runs generators and restores the original bytes afterwards |
|
|
242
|
+
|
|
243
|
+
## Status
|
|
244
|
+
|
|
245
|
+
Self-hosting: this repo carries its own `.docpolicy.yaml` and a pre-commit hook
|
|
246
|
+
(`core.hooksPath=.githooks`), so a commit that violates the policy is rejected by
|
|
247
|
+
the same checker the repo ships. Both test suites are stdlib-only and run offline.
|
|
248
|
+
|
|
249
|
+
- Version 0.1.0 — check codes, class modes and CLI flags are stable; internal
|
|
250
|
+
modules (`miniyaml`, the triage heuristics) may still move.
|
|
251
|
+
- Known limits are documented in `docs/design.md`: related-doc scoring is
|
|
252
|
+
bag-of-words overlap (no embeddings), and the LLM layer only ever labels —
|
|
253
|
+
it never decides placement or blocks anything.
|
|
254
|
+
- Secrets hygiene: `exempt`-classed docs are never read beyond path
|
|
255
|
+
classification, and the optional LLM credential (`llm.json`, 0600) is the only
|
|
256
|
+
credential file the checker touches.
|