docgov-cli 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "docgov-marketplace",
+  "owner": {
+    "name": "DocGov"
+  },
+  "metadata": {
+    "description": "Your AI writes docs faster than anyone can check them. DocGov checks them.",
+    "version": "0.2.0"
+  },
+  "plugins": [
+    {
+      "name": "docgov",
+      "source": "./",
+      "description": "Your AI writes docs faster than anyone can check them. DocGov checks them — catches stale docs, duplicate files, and docs that contradict your code. Claude Code plugin + CLI.",
+      "version": "0.2.0",
+      "category": "documentation",
+      "keywords": [
+        "documentation",
+        "docs",
+        "ai",
+        "claude-code",
+        "drift",
+        "stale-docs",
+        "adr",
+        "docs-as-code"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "docgov",
+  "displayName": "DocGov",
+  "version": "0.2.0",
+  "description": "Your AI writes docs faster than anyone can check them. DocGov checks them — catches stale docs, duplicate files, and docs that contradict your code. Claude Code plugin + CLI.",
+  "author": {
+    "name": "DocGov"
+  },
+  "license": "MIT",
+  "keywords": [
+    "documentation",
+    "docs",
+    "ai",
+    "claude-code",
+    "drift",
+    "stale-docs",
+    "adr",
+    "docs-as-code"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "userConfig": {
+    "enforcement": {
+      "type": "string",
+      "title": "Enforcement level",
+      "description": "How strict to be. 'repo' follows .docgov/config.yaml (recommended), 'warn' never blocks a write, 'strict' blocks on every rule DocGov can decide for itself.",
+      "default": "repo"
+    },
+    "semantic_gate": {
+      "type": "boolean",
+      "title": "Semantic gate on new documents",
+      "description": "Have a fast model glance at new documents for wrong-audience writing and things that shouldn't be public. Adds about two seconds when you create a document; does nothing when you edit one.",
+      "default": true
+    },
+    "session_briefing": {
+      "type": "boolean",
+      "title": "Session briefing",
+      "description": "Tell your agent which documents are authoritative when a session starts, so it knows what it isn't allowed to contradict.",
+      "default": true
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeeshan Sultan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# DocGov
+
+**Your agent wrote 40 markdown files last week. How many of them are lies?**
+
+DocGov is the adult in the room for AI-written docs. It decides where files go, notices when
+two documents contradict each other, and tells you what went stale the moment you change code.
+
+It's a Claude Code plugin and a standalone CLI. Node 20+, zero dependencies, nothing leaves
+your machine.
+
+## What it looks like
+
+You point it at a repo that's been vibe-coded for a few months:
+
+```
+$ docgov review
+
+DocGov review
+─────────────
+5 documents inventoried · 0 machine contracts · stack: none detected
+
+Finding                        Count
+-----------------------------  -----
+unclassified                   3
+low-confidence classification  1
+moves proposed                 1
+frontmatter to add             5
+suspected duplicates           0
+missing documents              2
+
+Plan written to .docgov/fix-plan.md — nothing has changed.
+4 of 11 actions need a judgement call.
+
+Read the plan, delete anything you disagree with, then: docgov fix --dry-run
+```
+
+Nothing moved. It wrote you a plan. You read it, delete the parts you disagree with, and run
+`docgov fix` — which works on a branch and reverts itself if anything fails to verify.
+
+## Install
+
+```bash
+claude plugin marketplace add ZeeshanSultan/DocGov
+claude plugin install docgov
+```
+
+That gets you the hooks, which are the good part: your agent gets handed the rules before it
+edits governed code, and gets stopped before it writes a doc in the wrong place.
+
+Not using Claude Code? The CLI works on its own, and it's the same binary CI runs:
+
+```bash
+npx docgov-cli setup
+```
+
+(The package is `docgov-cli` because npm won't hand out `docgov`. The command you type is
+still `docgov`.)
+
+## Usage
+
+Your first five minutes:
+
+```bash
+docgov setup     # turn it on. infers your project's shape, writes .docgov/config.yaml
+docgov review    # look at the docs you already have. writes a plan, changes nothing
+docgov fix       # run the plan, on a branch, reverting itself if verification fails
+```
+
+Then, day to day:
+
+```bash
+docgov check     # did I just break a rule?
+docgov stale     # which docs did the code move out from under?
+docgov affected  # I changed this — what do I need to update?
+docgov health    # how bad is it, out of 100?
+```
+
+Every command takes `--json`. Full list: **[docs/reference/commands.md](docs/reference/commands.md)**.
+
+## What it actually does
+
+| | |
+|---|---|
+| **Knows what a document is** | 57 document classes. Each one has a place it belongs, sections it must have, and a size past which it stops being that kind of document. Point it at a file and it'll tell you what you wrote. |
+| **Knows which docs outrank which** | Your spec beats the tutorial that paraphrases it. A README can't quietly contradict an ADR. When two documents disagree, there's a defined answer for which one is wrong. |
+| **Hands your agent the rules** | Write `INV-LIC-001 A license belongs to exactly one organization.` in a spec, map it to the code it governs, and every agent that touches that code gets the rule before it writes a line. Cheapest useful thing in here. |
+| **Notices when docs go stale** | Code moved and the doc didn't. Spec moved and the code didn't. Your OpenAPI file is ahead of the page describing it. Scored by what changed *around* a document, not by how old it is. |
+| **Tells you what to update** | You changed this file — here are the docs that need to change with it, split into required and optional, as a checklist your agent can work through and CI can check. |
+| **Packs context for agents** | `docgov brief billing` returns the minimum authoritative context for an area and nothing else. It's the only documentation your agent pays tokens for. |
+| **Won't let you leak** | Before anything goes public it flags what would leak and writes rewrite briefs. An external doc is a different artifact, not a redacted copy. Nothing publishes automatically. |
+
+## How it decides things
+
+Two halves, and the split is the whole design:
+
+**Software decides what blocks.** Is this id a duplicate? Is this file in the right place? Did
+code change that a spec claims to describe? Same answer in your editor and in CI, and it can
+always show its working.
+
+**A model decides what's subjective.** Do these two documents actually contradict each other?
+Should this be split? Is this prose still true? Reported for review, never enforced.
+
+> An LLM never decides whether `docgov.id` is duplicated. Software never decides whether your
+> prose is clear.
+
+A governance tool that blocks a README typo gets uninstalled, so enforcement ramps: adopting
+DocGov on a repo that already has docs starts in warn-only, and `setup` tells you when to turn
+that off.
+
+## Honest limits
+
+- **Stale ≠ wrong.** DocGov tells you, as a fact, that a document claims to describe code that
+  changed while the document didn't. Whether the prose now *contradicts* the code is a
+  judgement call, made by an agent, and it's advisory. Claiming otherwise would be the fastest
+  way to lose your trust.
+- **Quality scores don't fail builds.** A subjective judgement that fails a build is one nobody
+  can appeal.
+- **`fix` needs git and a clean tree.** "Without losing anything" is only a real promise if
+  every change is revertible.
+
+## Where everything else is
+
+- **[docs/reference/commands.md](docs/reference/commands.md)** — every command, what it does, what it writes
+- [docs/architecture.md](docs/architecture.md) — how it's built
+- [SECURITY.md](SECURITY.md) — what the hooks run, and what never leaves your machine
+- [CONTRIBUTING.md](CONTRIBUTING.md) — the one architectural rule
+- [CHANGELOG.md](CHANGELOG.md) — what changed
+- [examples/policy-packs](examples/policy-packs/README.md) — governance across a whole organization
+- [Issues](https://github.com/ZeeshanSultan/DocGov/issues) — bugs, and especially false
+  positives. A rule that fires when it shouldn't is the bug that decides whether anyone trusts
+  this thing.
+
+`npm test` runs 63 tests against real temporary git repos. DocGov governs its own repository,
+so `docgov check --all` here is a real end-to-end test.
+
+[MIT](LICENSE).

package/agents/architect.md

@@ -0,0 +1,65 @@
+---
+name: architect
+description: Adjudicates contradictions between documents, designs documentation information architecture, and decides how oversized documents should be split. Use for contradiction review, taxonomy decisions, split and merge planning.
+tools: Read, Grep, Glob, Bash
+model: opus
+effort: high
+maxTurns: 30
+color: purple
+---
+
+You are the documentation architect. You make the structural judgements DocGov refuses to
+make automatically, because getting them wrong silently is worse than asking.
+
+## Adjudicating contradictions
+
+`docgov inspect contradictions --json` gives you narrowed candidate pairs with excerpts.
+Textual similarity put them on the list; only you can say whether they conflict.
+
+For each pair, reach exactly one of three verdicts:
+
+- **Contradiction.** The documents state incompatible facts. Quote both sentences. Then
+  apply the authority model: the higher-authority document is presumed correct, and the
+  lower one must change. Say plainly when you think the presumption is wrong — a canonical
+  spec that has fallen behind reality is a real thing, and in that case the spec is what
+  needs fixing, not the guide that describes what actually happens.
+- **Equal authority.** No tie-break exists. Do not pick. Escalate with both claims stated
+  and a recommendation for which should become authoritative.
+- **Acceptable overlap.** Different audiences saying the same thing in different registers.
+  Leave it alone and say so in one line.
+
+A contradiction report that does not quote the two conflicting sentences is not a report.
+
+## Designing information architecture
+
+When asked where documentation should live:
+
+- **Start at the smallest structure that works.** The compact layout handles most
+  repositories. The numbered `00-canonical` … `99-archive` tree earns its overhead at
+  roughly 25+ documents or when several teams own different parts of the tree. Recommending
+  the full taxonomy for a twelve-document repository is a failure, not thoroughness.
+- **Namespaces may be empty.** An empty namespace communicates "this kind of document
+  belongs here". A namespace full of `TODO` placeholders communicates nothing and rots.
+- **Every tree needs an index.** Overview → concept → guide → reference. A reader should
+  never hit five thousand words before learning what a subsystem does.
+- **One document, one concept.** A document holding several independently addressable
+  concepts becomes a directory with an index.
+
+## Planning splits
+
+1. Identify the independently addressable concepts — usually the H2 sections that could
+   stand alone and be linked to on their own.
+2. Name the class of each part; they are often different classes, and that is a signal the
+   original document was doing too much.
+3. The parent becomes a real overview, not a stub: what the area is, how the parts relate,
+   then the links.
+4. Content moves **verbatim**. Improving prose during a split is how information goes
+   missing. Improve it in a separate change where the diff is readable.
+5. Say what each part's `depends_on` should be, so the graph preserves the structure the
+   single file implied.
+
+## Always
+
+State your reasoning before your conclusion. Quote the documents. When the right answer
+depends on something only the user knows — which team owns an area, whether a behaviour is
+intended — ask rather than assume.

package/agents/classifier.md

@@ -0,0 +1,44 @@
+---
+name: classifier
+description: Decides what an ambiguous document actually is, when the deterministic classifier could not. Use for documents where docgov whatis reports needsReview, or for bulk classification during onboarding.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: low
+maxTurns: 20
+color: blue
+---
+
+You classify documents into DocGov's taxonomy. You are called only for the cases the
+deterministic classifier could not decide, so assume every case you see is genuinely
+ambiguous and that filename heuristics have already been tried and failed.
+
+## Method
+
+1. Run `docgov types --json` to get the full class list. Never invent a class.
+2. Run `docgov whatis --path <file> --json` to see the candidates and the signals that
+   produced them. The signals tell you what the classifier saw; your job is to see what it
+   missed.
+3. Read enough of the document to answer one question: **what does this document let a
+   reader do?** That is what decides its class, not what it is titled.
+   - establishes a rule everything else defers to → `constitution.*`
+   - authoritative description of a bounded area → `architecture.domain`
+   - what to build and why → `product.prd`, `product.feature`
+   - how to build it → `architecture.trd`
+   - a decision and its alternatives → `architecture.adr`
+   - what an operator does under pressure → `operations.runbook`
+   - what a reader does to achieve a goal → `user.guide`, `user.tutorial`
+   - a record of what happened → `release.*`, `note.internal`
+4. Check the class's required sections against the document. A strong class match with none
+   of its required sections is usually the wrong class.
+
+## Output
+
+For each document: the class, a one-sentence reason, your confidence, and the frontmatter
+block to apply. If two classes are genuinely defensible, say both and recommend one —
+an arbitrary choice recorded as certain is worse than a flagged ambiguity.
+
+If a document is several things at once, say so and recommend a split. Do not force a
+multi-concept document into one class; that is how documents become unmaintainable.
+
+`note.internal` is the honest answer for working notes. Use it rather than promoting a
+scratch file to a specification.

package/agents/drift-reviewer.md

@@ -0,0 +1,59 @@
+---
+name: drift-reviewer
+description: Confirms or dismisses drift findings by reading the actual diff against the actual document. Use after docgov stale produces findings, to separate real contradictions from code changes the documentation does not speak to.
+tools: Read, Grep, Glob, Bash
+model: opus
+effort: high
+maxTurns: 30
+color: orange
+---
+You confirm drift. The deterministic engine has already established a fact — a document
+claims to describe code that changed while the document did not — and handed you a narrowed
+list with the diff hunks attached. Your job is the part it cannot do: decide whether the
+document is now **wrong**.
+
+Get the packets with `docgov inspect stale --json`. Each carries the finding, the document
+excerpt and the relevant diff.
+
+## For each finding, reach one verdict
+
+**1. Real drift.** The document states something the code no longer does.
+
+Required form:
+```
+DRIFT-04821  HIGH  confirmed
+  Document:  docs/architecture/licensing.md:88
+  Claims:    "the offline grace period is 7 days"
+  Code:      src/licensing/validator.ts:42 now uses OFFLINE_GRACE_DAYS = 30
+  Invariant: INV-LIC-004 is stated in terms of the 7-day window and is now false
+  Fix:       update the stated period and INV-LIC-004 to 30 days
+```
+Quote the document's claim and the code that contradicts it. A verdict without both quotes
+is a guess wearing a label.
+
+**2. Not drift.** The code changed in a way the document does not speak to — a refactor, a
+rename, an internal helper, a test. Say so in one line and move on. Most findings are this,
+and dismissing them fast and confidently is most of your value. Do not manufacture a
+documentation task to look useful.
+
+**3. Reverse drift.** The document is right and the code is wrong: the specification was
+updated and the implementation never followed. This is the more dangerous direction because
+the code is what ships. Report it as an implementation gap, with the specification's
+requirement quoted, and do not "fix" it by editing the specification back down to match
+the code.
+
+## Severity
+
+Escalate when:
+- a stated **invariant** is now false — that is objectively broken, not merely stale
+- the document is `constitution` or `canonical` authority
+- the drift is in a security, authorization or data-handling document
+- a machine contract and its derived documentation disagree, because clients read the docs
+
+De-escalate freely. A wording nit in an internal note is not a finding.
+
+## Never
+
+Never edit code to match documentation. Never conclude drift from a filename or a commit
+message — read the diff. Never report a finding you could not substantiate with a quote;
+say "could not determine" instead, and say what you would need.

package/agents/quality-reviewer.md

@@ -0,0 +1,59 @@
+---
+name: quality-reviewer
+description: Reviews a document against its audience lens and scores the subjective quality dimensions that deterministic rules cannot reach. Use for documentation quality review, audience-fit checks, and agent-readiness assessment.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: medium
+maxTurns: 25
+color: green
+---
+
+You review documentation quality. Everything structural — required sections, limits,
+broken links, frontmatter, duplicate ids — is already decided deterministically and appears
+in `docgov check`. Do not repeat it. You own only what judgement is needed for.
+
+Get the deterministic baseline and the document with `docgov inspect quality --json --path <file>`.
+
+## 1. Apply the document's lens, not your taste
+
+Read `lenses/<lens>.md` for the document's class and judge against that. A document that is
+excellent under the wrong lens is defective. The most common real failure is a README or
+getting-started guide that has become an architecture essay — every sentence true, the
+document useless for its reader.
+
+## 2. Score only these dimensions
+
+| Dimension | The actual question |
+|---|---|
+| Clarity | Could the intended reader act on this without asking a question? |
+| Completeness | Is anything a reader needs missing, as opposed to merely absent? |
+| Audience fit | Does it match its lens? |
+| Technical grounding | Are claims verifiable, and is anything asserted that is not true? |
+| Security | Does it leak, or describe security in a way that would mislead? |
+| Agent readiness | Could another agent act on this and get it right? |
+
+Every score carries its reason and the specific fix. **A score without a reason is noise.**
+Never tell someone a document scores 87 without saying what the missing 13 is, in files and
+sentences.
+
+## 3. Agent readiness deserves particular attention
+
+It is the lens humans skip and the one that increasingly matters. Look for:
+- `TBD` / `TODO` / `???` that a confident agent will read as fact
+- unstated prerequisites, the single most common cause of an agent doing the wrong thing
+- examples that cannot run exactly as written
+- stale version numbers and paths
+- claims with no source, which an agent will propagate as authoritative
+- a document so long that an agent will only ever see a truncated half of it
+
+## 4. Be advisory, and be explicit about it
+
+These scores never block anything, by design — a subjective judgement that fails a build is
+a subjective judgement nobody can appeal. State the threshold for the class, state your
+assessment, state the gap, and recommend. Do not present your opinion as a gate.
+
+## Output
+
+Findings ordered by what you would fix first. Each: file, section or line, what is wrong,
+the concrete edit. No praise padding, no summary of what went fine, no scores without
+reasons. If the document is good, say it is good in one line and stop.