docgov-cli 0.2.0

package/schemas/frontmatter.json

@@ -0,0 +1,299 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ZeeshanSultan/DocGov/main/schemas/frontmatter.json",
+  "title": "DocGov document frontmatter",
+  "description": "The docgov block in a governed document's YAML frontmatter. Point your editor at this for completion and validation.",
+  "type": "object",
+  "required": [
+    "docgov"
+  ],
+  "properties": {
+    "docgov": {
+      "type": "object",
+      "required": [
+        "id",
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]{1,59}$",
+          "description": "Stable identifier. How every other document, relationship and agent addresses this one. Changing it breaks references."
+        },
+        "type": {
+          "enum": [
+            "constitution.product",
+            "constitution.principles",
+            "constitution.invariants",
+            "constitution.glossary",
+            "constitution.domains",
+            "product.vision",
+            "product.prd",
+            "product.feature",
+            "product.persona",
+            "product.roadmap",
+            "design.ux",
+            "design.flow",
+            "design.accessibility",
+            "architecture.overview",
+            "architecture.domain",
+            "architecture.component",
+            "architecture.data",
+            "architecture.integration",
+            "architecture.trd",
+            "architecture.adr",
+            "security.architecture",
+            "security.threat-model",
+            "security.authorization",
+            "security.data-classification",
+            "security.public-model",
+            "engineering.development",
+            "engineering.testing",
+            "engineering.conventions",
+            "engineering.dependencies",
+            "operations.deployment",
+            "operations.infrastructure",
+            "operations.configuration",
+            "operations.observability",
+            "operations.runbook",
+            "operations.disaster-recovery",
+            "release.notes",
+            "release.migration",
+            "release.deprecation",
+            "user.readme",
+            "user.getting-started",
+            "user.guide",
+            "user.admin-guide",
+            "user.tutorial",
+            "user.troubleshooting",
+            "user.faq",
+            "user.reference",
+            "governance.contributing",
+            "governance.support",
+            "governance.lifecycle",
+            "governance.policy",
+            "contract.openapi",
+            "contract.schema",
+            "note.internal",
+            "archive.document",
+            "agent.instructions",
+            "unknown"
+          ],
+          "description": "Document class. Determines location, template, required sections, limits and quality threshold."
+        },
+        "authority": {
+          "enum": [
+            "constitution",
+            "canonical",
+            "requirements",
+            "decision",
+            "machine-contract",
+            "implementation",
+            "generated",
+            "audience",
+            "historical"
+          ],
+          "description": "Defaults from the type. A lower-authority document may not contradict a higher one."
+        },
+        "domain": {
+          "type": "string",
+          "description": "Bounded area this belongs to. Joins the document to config domains and to invariant scoping."
+        },
+        "audience": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "visibility": {
+          "enum": [
+            "public",
+            "internal",
+            "confidential",
+            "generated-public",
+            "generated-internal"
+          ],
+          "description": "Governs which paths may hold it and whether it can be published."
+        },
+        "lens": {
+          "enum": [
+            "readme",
+            "developer",
+            "architecture",
+            "security",
+            "user",
+            "agent",
+            "operations"
+          ],
+          "description": "Review lens. Defaults from the type."
+        },
+        "owner": {
+          "type": "string",
+          "description": "Required in team and enterprise modes."
+        },
+        "status": {
+          "enum": [
+            "draft",
+            "active",
+            "deprecated",
+            "superseded",
+            "archived"
+          ]
+        },
+        "documents": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Code path globs this document describes. Without this the document is invisible to drift detection and to invariant injection \u2014 the single most valuable field in the block."
+        },
+        "invariants": {
+          "type": "array",
+          "description": "Explicit invariants. Usually written as list items in the body instead.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "id"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "statement": {
+                    "type": "string"
+                  },
+                  "paths": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "severity": {
+                    "enum": [
+                      "critical",
+                      "high",
+                      "medium",
+                      "low"
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "relationships": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Edges in the documentation graph. Inverses are derived automatically.",
+          "properties": {
+            "depends_on": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "defines": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "implements": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "derived_from": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "supersedes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "references": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "validated_by": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "generated_from": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "exposes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "documents": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "review": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "cadence": {
+              "type": "string",
+              "pattern": "^\\d+[dwmy]$"
+            },
+            "last": {
+              "type": "string"
+            }
+          }
+        },
+        "generation": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "enum": [
+                "human-maintained",
+                "generated",
+                "assisted"
+              ]
+            },
+            "source": {
+              "type": "string"
+            },
+            "generator": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/affected/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: affected
+description: Analyze which documents a code change affects and produce the documentation change manifest — required updates, optional updates, and the PR-ready review comment. Use before committing, when opening a PR, or for "what docs do I need to update".
+allowed-tools: Bash(docgov *) Bash(git diff*) Bash(git status*) Read Write Edit
+argument-hint: "[--base main]"
+---
+
+# Change impact
+
+## Impact and manifest
+
+!`docgov affected --json --compact $ARGUMENTS 2>&1 | head -c 10000`
+
+## What to do
+
+1. **Report the required list first.** Entries with `required: true` and `updated: false`
+   are the work. Everything else is context. Lead with the short list of files the user
+   actually has to touch.
+
+2. **Update them.** For each, read the document, find the part the change invalidates, and
+   make the minimal correct edit. Do not rewrite a document because one sentence is wrong.
+
+3. **Write the manifest** with `docgov checklist`. It lands in `.docgov/checklist.yaml` as a
+   deterministic checklist that survives across sessions and CI — and is deleted after
+   merge. Use it rather than holding the list in your head.
+
+4. **For a PR,** run `docgov checklist --pr` and post the output as a comment. It states the
+   code impact, the documentation impact, what is covered and what is outstanding.
+
+5. **If a required document genuinely does not need updating,** say why, explicitly, in the
+   PR comment or the commit message. "No documentation change needed because the refactor
+   preserved the documented behaviour" is a legitimate answer. Silence is not.
+
+## Signals worth reacting to
+
+- `securityChanged` — the security architecture and threat model are almost always affected
+  and almost always forgotten. Check them specifically.
+- `apiChanged` without a contract change — either the contract is now wrong, or the change
+  was internal and the signal is a false positive. Work out which.
+- `behaviorChanged` without `testsChanged` — not a documentation problem, but worth saying
+  out loud once.

package/skills/brief/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: brief
+description: Load the minimal authoritative documentation context for a topic or domain before changing code — the constitution, the canonical specification, the invariants in force, the relevant ADRs and the machine contracts, and nothing else. Use before implementing or modifying anything in a governed area.
+allowed-tools: Bash(docgov *) Read
+argument-hint: "<domain-or-topic>"
+---
+
+# Authoritative context
+
+!`docgov brief $ARGUMENTS 2>&1 | head -c 28000`
+
+## How to use this
+
+Everything above is authoritative and ordered: the most authoritative document is first.
+It replaces reading the documentation tree — that is the point, and it is why the pack is
+small.
+
+**The rules while you work in this area:**
+
+1. **Invariants are binding.** If one blocks your approach, the invariant wins. Changing it
+   means changing its source document in the same change, with a stated reason. Do not
+   route around it.
+
+2. **Machine contracts beat prose.** Where a schema, OpenAPI document or migration is
+   listed, it is authoritative over any description of it, including the one in this pack.
+
+3. **Lower authority may not contradict higher.** If you find the canonical specification
+   and a guide disagreeing, the canonical specification is right and the guide is a bug.
+
+4. **If the pack is wrong, fix the document.** Do not write code that works around
+   incorrect documentation and leave the documentation incorrect — that is exactly the
+   state this product exists to prevent.
+
+5. **"Not included in full"** entries are real documents that did not fit the budget. Read
+   them directly if your change touches what their headings describe.
+
+After you change code here, run `/docgov:affected` to find out which of these documents you
+now owe an update.

package/skills/create/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: create
+description: Create a new governed document of the right class in the right place, with its template, its required sections, and its relationships already wired into the documentation graph. Use whenever new documentation is needed — a PRD, TRD, ADR, threat model, runbook, domain spec, guide or README.
+allowed-tools: Bash(docgov *) Read Write Edit
+argument-hint: "<type> \"<name>\" [--domain <domain>]"
+---
+
+# Create a governed document
+
+## Before writing anything
+
+1. **Check it does not already exist.** Run `docgov find "<topic>"`. The results are in
+   authority order. If an authoritative document already covers this, update that one —
+   a second document on the same subject is how contradictions are born.
+
+2. **Pick the class.** `docgov types` lists all 56. If the user said "write docs for X",
+   decide which class X actually is rather than defaulting to a guide. Do not invent a class.
+
+3. **Load the authoritative context.** Run `docgov brief <domain-or-topic>`. Read it
+   before writing. It carries the constitution, the canonical spec, the invariants in
+   force and the machine contracts — the things your document must not contradict.
+
+## Create it
+
+```bash
+docgov create <type> "<name>" --domain <domain>
+```
+
+This puts the file in the canonical location, applies the template, declares the right
+authority and visibility, and wires `depends_on` / `implements` edges from documents it
+found to be related. It prints the required sections and the line limits.
+
+## Then write it
+
+- **Fill every required section.** They are a deterministic gate: a TRD with no failure
+  analysis fails `docgov check`, and rightly so.
+- **Stay inside the limit** the command printed. If the content genuinely needs more, the
+  document is probably two documents.
+- **Reference, do not restate.** Machine contracts (OpenAPI, schemas, migrations) are
+  authoritative; link them. Copying a schema into prose creates a second source of truth
+  that will be wrong within a month.
+- **Declare invariants** if this is a canonical document. Any line beginning
+  `INV-<DOMAIN>-001` becomes a first-class object that gets injected into every agent that
+  later touches the matching code. This is the highest-value thing you can write.
+- **Map the code** this document describes, in frontmatter: `documents: ["src/licensing/**"]`.
+  Without it the document is invisible to drift detection.
+- **Write for the class's audience.** A README is not an architecture document. A runbook
+  is numbered steps with expected results, not an essay.
+
+## Finish
+
+Run `docgov check --path <new-file>` and fix what it reports. Then `docgov affected` to see
+whether creating this document obliges you to update anything else.

package/skills/find/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: find
+description: Search documentation with authority-aware ranking, so the canonical specification is returned before the tutorial that paraphrases it. Use for "where is X documented", "what do we say about Y", or finding the authoritative source for a behaviour.
+allowed-tools: Bash(docgov *) Read
+argument-hint: "<query>"
+---
+
+# Find documentation
+
+!`docgov find "$ARGUMENTS" 2>&1 | head -c 10000`
+
+## How to read this
+
+Results are ordered by **authority first, relevance second**. That ordering is deliberate:
+an agent that reads the user guide before the canonical specification writes confidently
+wrong code.
+
+- `[CONSTITUTION]` / `[CANONICAL]` — authoritative. Start here. If something below
+  contradicts these, the thing below is wrong.
+- `[REQUIREMENTS]` / `[DECISION]` — why it was built this way. ADRs explain decisions you
+  might otherwise reverse by accident.
+- `[CONTRACT]` — machine-readable and authoritative over any prose about it.
+- `[AUDIENCE]` — written for a reader, not for precision. Do not treat a guide as a spec.
+- `[HISTORICAL]` — may be out of date on purpose. Check `status` before believing it.
+
+If a result is marked `deprecated` or `superseded`, follow its `supersedes` edge to the
+current document instead of using it.
+
+## If nothing relevant comes back
+
+That is a coverage gap, not a search failure. Run `docgov health` to see whether DocGov
+already knows the document is missing, and offer to create it with `/docgov:create`.

package/skills/health/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: health
+description: Score documentation health across coverage, freshness, consistency, structure, discoverability, cross-linking, canonical integrity and metadata, and list the gaps the repository's own stack implies. Use for "how are my docs doing", documentation audits, or a periodic review.
+allowed-tools: Bash(docgov *) Read
+---
+
+# Documentation health
+
+!`docgov health --json --compact 2>&1 | head -c 8000`
+
+## How to report this
+
+1. **The score, then the single highest-leverage fix.** Not eight bullet points of
+   component scores the user has to rank themselves. Lead with: "91/100. The one thing
+   worth fixing is X."
+
+2. **Explain any component below 80 in terms of what is actually wrong** — the files, not
+   the metric. "Freshness 67" means nothing; "four canonical documents have had no review
+   while the code they describe changed 30 times" is a fact someone can act on.
+
+3. **Coverage gaps are the most actionable part.** Each one means the repository's stack
+   implies documentation that does not exist — Kubernetes manifests with no deployment
+   guide, OAuth with no authentication model. Offer to create the top two or three with
+   `/docgov:create`.
+
+4. **Do not recommend raising the score.** Recommend fixing specific documents. A score
+   that goes up because someone added frontmatter to archived notes is worse than a score
+   that stays flat.
+
+## Context for the numbers
+
+- **canonical integrity** below 100 is the serious one: it means the authority model itself
+  has been violated, and every other number is built on sand.
+- **coverage** counts both what is classified and what the stack implies should exist.
+- **freshness** is semantic, not calendar-based — a correct document that has not changed
+  in two years scores fine.

package/skills/inspect/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: inspect
+description: Review documentation quality against its audience lens, find contradictions between documents, and check whether another agent could safely act on a document. Use for "review my docs", documentation quality checks, contradiction hunting, or before publishing.
+allowed-tools: Bash(docgov *) Read
+argument-hint: "[--path <file>] [--contradictions] [--lens readme|developer|architecture|security|user|agent|operations]"
+---
+
+# Review documentation
+
+## Deterministic findings (already decided, do not re-litigate)
+
+!`docgov check --json --compact 2>&1 | head -c 10000`
+
+## What to review
+
+Everything above is settled by software. Your job is the part software cannot decide.
+Work only on these four questions, and say plainly when the answer is "this is fine".
+
+### 1. Audience fit — apply the right lens
+
+Read the lens for the document's class in `lenses/<lens>.md` and judge against it, not
+against your general taste. The lenses are: `readme`, `developer`, `architecture`,
+`security`, `user`, `agent`, `operations`. A document that is excellent under the wrong
+lens is a defect: an architecture essay inside a getting-started guide fails even if every
+sentence is true.
+
+### 2. Contradictions
+
+Run `docgov inspect contradictions --json`. You get narrowed candidate pairs with excerpts,
+not a verdict. For each:
+- **Genuine contradiction** — two documents state incompatible facts. The higher-authority
+  document is presumed right; name which one must change and why.
+- **Equal authority** — no tie-break exists. This is the dangerous case. Escalate it to the
+  user rather than picking.
+- **Acceptable overlap** — different audiences saying the same thing differently. Leave it.
+
+Quote the conflicting sentences. A contradiction report without the two sentences in it is
+unactionable.
+
+### 3. Agent readiness
+
+Could a different agent act on this document without making a wrong assumption? Check for:
+unstated prerequisites, `TBD`/`TODO` that reads as fact, examples that cannot run as
+written, stale version numbers, and claims with no source. This lens matters more every
+month and is the one humans skip.
+
+### 4. Quality scores — advisory, and say so
+
+Run `docgov inspect quality --json` for the deterministic dimensions (structure, grounding,
+cross-references, freshness). Add your judgement on clarity, completeness, audience fit and
+security reasoning. Present the result as advice with the reasoning attached, never as a
+pass/fail. Do not tell the user a document "scores 87" without saying what the missing 13
+actually is.
+
+## Output
+
+Findings ordered by what you would fix first, each with the file, the line or section, and
+the concrete edit. No scores without reasons. No praise padding.

package/skills/publish/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: publish
+description: Analyze which documentation is safe to publish externally, detect information that would leak, and produce external-lens rewrite briefs. Use before publishing docs, opening a repository, or moving internal documentation to a public site.
+disable-model-invocation: true
+allowed-tools: Bash(docgov *) Read Write Edit
+argument-hint: "[--target docs/11-external]"
+---
+
+# Publishing analysis
+
+!`docgov publish --json --compact $ARGUMENTS 2>&1 | head -c 10000`
+
+## The rule this skill exists to enforce
+
+**An external document is a different artifact, not a copy of an internal one.** They serve
+different readers and answer different questions. Copying internal documentation outward —
+even with the secrets removed — produces documentation that is technically safe and
+practically useless, and it leaks information structure even when it leaks no values.
+
+## What to do
+
+1. **`blocked[]` — report and stop.** These contain detected sensitive patterns. List the
+   file, line and what was found. Do not publish, do not "clean up and publish anyway" on
+   your own judgement. Hand it back to the user.
+
+2. **`rewrite[]` — write a new document, do not edit the old one.** Use the brief in
+   `briefs[]`. Under the external lens:
+   - no internal jargon, team names, ticket ids, or hostnames
+   - no unmitigated risks, no infrastructure topology
+   - task-oriented: what the reader wants to do, not how the system is built
+   - prerequisites stated explicitly, because the external reader has none of your context
+   - every example runnable exactly as written
+
+3. **`publishable[]` — still read before shipping.** Soft flags (ticket references, email
+   addresses, work-in-progress markers) are judgement calls, not false positives.
+
+4. **Never publish.** This skill analyzes and drafts. A human approves and a human ships.
+   Say that explicitly when you report, and do not offer to push anything.
+
+## The threat model / public security model pair
+
+These are the canonical example of the same subject needing two documents. The threat model
+is `visibility: internal` and names unmitigated risks. The public security model is
+`visibility: public` and says what you protect and how to report a vulnerability. One is
+not a redaction of the other.

package/skills/review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: review
+description: Inventory, classify and produce a migration plan for a repository that already has documentation. Detects duplicates, contradictions, oversized documents, wrong locations, missing frontmatter and coverage gaps, then writes a plan that changes nothing until approved. Use for existing repositories, messy documentation trees, or "organize my docs".
+disable-model-invocation: true
+allowed-tools: Bash(docgov *) Bash(git status*) Bash(git log*) Read Write Edit
+---
+
+# Onboard an existing repository
+
+## Plan
+
+!`docgov review --json --compact 2>&1 | head -c 24000`
+
+## What to do
+
+The JSON above is the full plan; `.docgov/fix-plan.md` is the human-readable version.
+**Nothing has been changed.**
+
+1. **Summarize honestly, shortest first.** How many documents, how many DocGov could not
+   classify, how many moves, how many real judgement calls. Do not pad the summary with
+   the things that went fine.
+
+2. **Work the low-confidence classifications.** `classifications[]` entries with
+   `needsReview: true` are where the deterministic classifier gave up. Read each document
+   (just enough of it) and decide its class yourself. Run `docgov types` if you need the
+   list. Then write the decision into the document's frontmatter:
+
+   ```
+   docgov:
+     id: <kebab-id>
+     type: <class>
+     authority: <from the class>
+     visibility: internal|public|confidential
+   ```
+
+   Declaring the type is what turns a guess into a fact — the classifier never overrides
+   a declared type.
+
+3. **Adjudicate the contradiction candidates.** `contradictionCandidates[]` is a narrowed
+   list, not a verdict. For each pair, read both and decide: genuine contradiction,
+   acceptable overlap (different audiences saying the same thing in different words), or
+   genuine duplicate. Use the `architect` agent for the non-obvious ones. Only real
+   contradictions need fixing, and the higher-authority document is the one that is right
+   unless you have a reason to think otherwise.
+
+4. **Propose, do not perform, the high-risk actions.** `SPLIT`, `MERGE` and `EXTRACT`
+   rewrite prose. Present them to the user as a short list with your recommendation, and
+   handle them one at a time through `/docgov:tag`.
+
+5. **When the user approves, run the mechanical half:**
+   ```bash
+   docgov fix --dry-run     # every file operation, nothing touched
+   docgov fix               # on a branch, with link repair and verification
+   ```
+   `migrate` refuses to run without git or with a dirty tree. That is deliberate: the
+   "no information lost" promise is only real if every change is revertible.
+
+6. **Verify.** After migrating, run `docgov check` and `docgov health`. Report the health
+   score and the top three things that would raise it most.
+
+## Do not
+
+Do not move files yourself — `migrate` repairs links in the same transaction and your
+`mv` will not. Do not merge two documents' prose without showing the user what you are
+about to delete.