docgov-cli 0.2.0

package/skills/setup/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: setup
+description: Establish DocGov documentation governance in this repository — infer the project mode and layout, create the taxonomy namespaces, install agent documentation rules, and build the initial registry and graph. Use when a repository has no .docgov/config.yaml yet.
+disable-model-invocation: true
+allowed-tools: Bash(docgov *) Read Write Edit
+argument-hint: "[--mode solo|team|enterprise|open-source] [--layout full|compact]"
+---
+
+# Establish governance
+
+## Current repository
+
+!`docgov tools --json 2>/dev/null || echo '{}'`
+
+## What to do
+
+1. **Run `docgov setup $ARGUMENTS`.** It infers mode from the repository (a LICENSE plus
+   CONTRIBUTING means open-source; CODEOWNERS means team) and layout from document count.
+   Report what it inferred and why, in one line each.
+
+2. **Confirm the inferences with the user before anything else.** These two choices shape
+   everything afterwards and are annoying to change later:
+   - `mode` decides how much blocks. `solo` blocks three rules; `enterprise` blocks twelve.
+   - `layout` decides where documents live. `compact` is right for most repositories;
+     `full` (the numbered `00-canonical` … `99-archive` tree) earns its overhead at roughly
+     25+ documents or when several teams own different parts of the tree.
+
+   If the repository is small, say so and recommend `compact` + `solo`. Documentation
+   architecture astronautics is a real failure mode and this is where it starts.
+
+3. **Set up domains if the codebase has obvious ones.** Look at the top-level source
+   layout. If there are clear bounded areas (`src/auth/`, `src/billing/`, `src/licensing/`),
+   add them to `.docgov/config.yaml`:
+
+   ```yaml
+   domains:
+     licensing:
+       paths: ["src/licensing/**", "migrations/*licen*"]
+       owner: platform
+   ```
+
+   Domains are what make `docgov brief <domain>` and invariant injection work. Without
+   them most of DocGov's value stays switched off. This is the highest-leverage thing to
+   get right during setup.
+
+4. **Then run `/docgov:review`** if documentation already exists, or `/docgov:create` for
+   the first document if not.
+
+## Do not
+
+Do not create documents during init. Do not populate empty namespaces with placeholder
+files — an empty namespace is a namespace, a file full of `TODO` is debt.

package/skills/stale/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: stale
+description: Detect documentation drift — implementation changed but documentation did not, documentation changed but implementation did not, machine contracts ahead of their derived docs, and semantic staleness. Use for "are my docs still true", before a release, or after a large change.
+allowed-tools: Bash(docgov *) Bash(git diff*) Bash(git log*) Read
+argument-hint: "[--base main]"
+---
+
+# Detect documentation drift
+
+## Deterministic drift report
+
+!`docgov stale --json --compact $ARGUMENTS 2>&1 | head -c 14000`
+
+## What this report is, and is not
+
+The findings above are facts: a document claims to describe code that changed while the
+document did not, or a specification changed with no corresponding implementation change.
+Those are decided from the diff and the graph.
+
+What the report does **not** claim is that the prose actually contradicts the new code.
+That is your job, and it needs the diff.
+
+## Confirm each finding
+
+Run `docgov inspect stale --json` for review packets: each finding comes with the relevant
+diff hunks and the document excerpt, so you read kilobytes instead of the repository.
+
+For each packet decide one of three things and say which:
+
+1. **Real drift.** The document states something the code no longer does. Quote the
+   document's claim and the code that contradicts it, then make the edit. Be specific —
+   "the document says the offline grace period is 7 days; `validator.ts:42` now uses 30"
+   is actionable, "the licensing docs look stale" is not.
+2. **Not drift.** The code changed in a way the document does not speak to. Say so in one
+   line and move on. Most findings are this, and saying so quickly is the valuable part.
+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 ships. Flag it as an implementation gap, not a documentation task.
+
+## Invariants
+
+If a finding carries invariants, check them specifically: an invariant the code now
+violates is a higher-severity problem than a stale sentence, and it is the one thing here
+that can be objectively wrong.
+
+## Staleness
+
+The `staleness` array scores risk from what changed *around* a document, not from its age.
+A document untouched for two years with no implementation churn is not stale. Only report
+entries whose signals you can explain.
+
+## If a finding is wrong
+
+`docgov ignore DRIFT-xxxxx --reason "..." [--expires YYYY-MM-DD]`. It stays visible in
+every report. Suppress the finding, never the rule.

package/skills/tag/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: tag
+description: Reorganize existing documentation — add missing frontmatter, split oversized documents, extract overgrown README sections, merge duplicates, and archive superseded documents. Use for "clean up the docs", oversized files, duplicate documents, or after onboarding leaves judgement calls.
+disable-model-invocation: true
+allowed-tools: Bash(docgov *) Bash(git *) Read Write Edit
+argument-hint: "[--path <file>]"
+---
+
+# Reorganize documentation
+
+## State
+
+!`docgov tag --json 2>&1 | head -c 8000`
+
+## Mechanical work first
+
+`docgov tag --apply` writes missing frontmatter for everything it can classify
+confidently. Run it, then report how many documents it annotated. Moves stay with
+`docgov fix` so that link repair and the move happen in one transaction.
+
+## Then the judgement calls, one at a time
+
+### Splits
+
+A document flagged for splitting holds several independently addressable concepts. Do it
+like this, and only this way:
+
+1. Create each part with `docgov create <type> "<part name>" --domain <d>` so it lands in
+   the right place with the right frontmatter.
+2. Move the content across **verbatim**. Rewriting while splitting is how information gets
+   lost; if prose needs improving, that is a separate change.
+3. Turn the parent into an index: a short overview plus a link to each part. Not a stub —
+   an overview that is useful on its own.
+4. Add `depends_on` from each part back to the parent, so the graph keeps the structure.
+5. Run `docgov check` to confirm no link broke.
+
+### README extraction
+
+A README section that has grown past ~40 lines belongs elsewhere. Move the body to the
+document class DocGov names, then leave behind a summary of roughly one line per fifteen
+removed, plus a link. A README answers "what is this, why would I use it, how do I start,
+where is the depth" — it is not the project encyclopedia.
+
+### Merges
+
+Never merge prose silently. Show the user both documents, say which content you would
+keep, which you would drop, and why. Then merge into the **higher-authority** path, point
+`supersedes` at the retired one, and archive rather than delete it.
+
+### Archiving
+
+Superseded documents go to the archive namespace with `status: superseded` and a
+`supersedes` edge from their replacement. The archive is a record: do not edit it
+afterwards, and DocGov will block attempts to.
+
+## Report
+
+End with the `docgov health` score before and after, and the single change that would
+raise it most.

package/templates/architecture.adr.md

@@ -0,0 +1,42 @@
+# <Decision, stated as an imperative: "Use Postgres for the primary store">
+
+## Status
+
+proposed
+
+<!-- proposed → accepted → superseded. Never delete an ADR; supersede it and link both ways. -->
+
+## Context
+
+<!--
+The forces in play, written so a reader in two years understands why this was even a
+question. Constraints, deadlines, existing commitments, what the alternatives were
+competing on. Link the canonical document or PRD this decision serves.
+-->
+
+## Decision
+
+<!-- One sentence, active voice, no hedging. Then the specifics. -->
+
+## Alternatives
+
+<!--
+Each alternative that was seriously considered, and the reason it lost. An ADR whose
+alternatives are straw men is worse than no ADR — it forecloses a reconsideration that
+should stay open.
+-->
+
+## Consequences
+
+<!--
+What this makes easier. What it makes harder. What it forecloses. What has to be true for
+this to keep being the right call, so a future reader can tell when it stops being true.
+-->
+
+## Security implications
+
+<!-- Trust boundaries moved, new attack surface, new secrets, new data flows. "None" is a valid answer when you have checked. -->
+
+## Supersedes
+
+<!-- ADR ids this replaces, or "none". Mirror this with `supersedes:` in the frontmatter relationships. -->

package/templates/architecture.domain.md

@@ -0,0 +1,44 @@
+# <Domain name>
+
+> Canonical specification for this domain. Nothing of lower authority may contradict it.
+> If reality and this document disagree, one of them is a bug — decide which before editing.
+
+## Purpose
+
+<!-- What this domain is responsible for, in one paragraph. -->
+
+## Boundaries
+
+<!-- What this domain owns and what it explicitly delegates. Which other domains it may call and which it may not. -->
+
+## Model
+
+<!-- The core concepts and their relationships, in this domain's own vocabulary. Keep terms consistent with the glossary — one term per concept. -->
+
+## Invariants
+
+<!--
+Rules that must hold at all times. Give each an id:
+
+- INV-<DOMAIN>-001 <statement>
+
+These become first-class objects: DocGov injects them into any agent that edits the code
+mapped by this document's `documents:` frontmatter. This is the highest-leverage section in
+the whole documentation tree — an invariant written here is enforced everywhere afterwards.
+-->
+
+## Interfaces
+
+<!-- What this domain exposes and consumes. Point at the machine contract; the contract is authoritative. -->
+
+## Failure modes
+
+<!-- What goes wrong, how it surfaces, what degrades, what recovers on its own. -->
+
+## Dependencies
+
+<!-- Other domains and external services, with the direction of dependency and what breaks without each. -->
+
+## Open questions
+
+<!-- Unresolved, each with an owner. -->

package/templates/architecture.trd.md

@@ -0,0 +1,72 @@
+# <System or change name> — Technical Requirements
+
+## Context
+
+<!-- Why this document exists and what it implements. Link the PRD; do not restate it. -->
+
+## Requirements mapping
+
+<!-- Each PRD requirement id → where in this document it is addressed. This table is how a reviewer checks coverage. -->
+
+## Existing architecture
+
+<!-- What is there now, honestly, including the parts you wish were different. Link the canonical domain documents. -->
+
+## Proposed architecture
+
+<!-- What it becomes. Boundaries, responsibilities, what moves. -->
+
+## Components
+
+<!-- Each component: what it owns, what it depends on, what it exposes. -->
+
+## Data model
+
+<!-- Entities, relationships, lifecycle. Reference the migration or schema; do not copy it. -->
+
+## Interfaces
+
+<!-- APIs, events, queues. Point at the machine contract. The contract is authoritative; this section is orientation. -->
+
+## State transitions
+
+<!-- Legal states and the transitions between them. Which transitions are irreversible. -->
+
+## Failure handling
+
+<!--
+Each failure mode: how it is detected, what degrades, what the user sees, what recovers
+automatically and what needs a human. A TRD without this section is a design sketch.
+-->
+
+## Security
+
+<!-- Trust boundaries, authorization checkpoints, secret handling, data classification. Link the threat model. -->
+
+## Performance
+
+<!-- Expected load, measured baseline, target, and where the first bottleneck will be. -->
+
+## Observability
+
+<!-- What signals prove this is working, which dashboard shows them, which alert fires when it stops. -->
+
+## Migration
+
+<!-- How existing data and clients move across. Backfill, dual-write, cutover. What is reversible and where that stops. -->
+
+## Testing
+
+<!-- What is covered at which level, and what is deliberately not covered and why. -->
+
+## Rollout
+
+<!-- Order, gates, flag strategy, blast radius at each stage. -->
+
+## Rollback
+
+<!-- How to undo at each stage, and the point of no return. If there is no rollback, say so here, in bold. -->
+
+## Open questions
+
+<!-- Unresolved, each with an owner. -->

package/templates/constitution.invariants.md

@@ -0,0 +1,40 @@
+# Invariants
+
+> Project-level rules that must hold at all times. These are enforced, not aspirational:
+> any line beginning with an id becomes an object DocGov injects into agents editing the
+> code it governs.
+
+## How to write one
+
+```
+- INV-<DOMAIN>-<NNN> <A single statement, present tense, falsifiable.>
+```
+
+Good:  `INV-LIC-001 A license belongs to exactly one organization.`
+Bad:   `INV-LIC-001 Licensing should be robust.`
+
+An invariant that cannot be violated by a specific code change is not an invariant, it is a
+principle — put it in `PRINCIPLES.md` instead.
+
+Map the code each invariant governs in the frontmatter of the document that states it:
+
+```yaml
+docgov:
+  documents: ["src/licensing/**", "migrations/*licen*"]
+```
+
+Without that mapping the invariant is documentation. With it, every agent that edits
+licensing code is handed the rule before it writes a line.
+
+## Invariants
+
+<!--
+- INV-<DOMAIN>-001 <statement>
+- INV-<DOMAIN>-002 <statement>
+-->
+
+## Changing an invariant
+
+Changing one of these is a deliberate act. State what changed, why, what it breaks, and
+which ADR records the decision. Do not soften an invariant to make a failing change pass —
+that is the one manoeuvre this document exists to prevent.

package/templates/operations.runbook.md

@@ -0,0 +1,47 @@
+# <Runbook name>
+
+> Written for someone woken at 3am who did not build this. Numbered steps, one action each,
+> expected result stated. Prose is unreadable under pressure.
+
+## Purpose
+
+<!-- What this procedure achieves, in one sentence. -->
+
+## Trigger
+
+<!-- The exact signal: alert name, symptom, threshold. Not "when things look wrong". -->
+
+## Preconditions
+
+<!-- Access required, approvals needed, what must be true before step one. -->
+
+## Diagnostics
+
+<!--
+Commands that establish what is actually happening, before anything is changed. Each with
+what its output means. Acting before confirming cause turns an incident into two.
+-->
+
+## Procedure
+
+<!--
+1. <action>
+   Expected: <observable result>
+2. <action>
+   Expected: <observable result>
+
+Commands copy-pasteable with no placeholders to reason about. If a step takes more than a
+minute, say how long, or it will be declared hung and interrupted.
+-->
+
+## Validation
+
+<!-- How you know it worked. A measurement, not an impression. -->
+
+## Rollback
+
+<!-- How to undo each step, and the point past which you cannot. -->
+
+## Escalation
+
+<!-- Who to wake, at what threshold, by what route. Names a rotation, not a person. -->

package/templates/product.prd.md

@@ -0,0 +1,60 @@
+# <Product or feature name>
+
+## Context
+
+<!-- What exists today and what is happening that makes this worth doing now. Link the product constitution. -->
+
+## Problem
+
+<!--
+The problem in the user's terms, not the solution's. If this section mentions your
+proposed mechanism, it is describing a solution and the problem is still unstated.
+-->
+
+## Goals
+
+<!-- Outcomes, each observable. "Users can recover an account without support" — not "build account recovery". -->
+
+## Non-goals
+
+<!-- What this explicitly does not do. The most valuable section in the document and the one most often left out. -->
+
+## Personas
+
+<!-- Who this is for, what they are trying to do, what they already know. Link persona documents rather than restating them. -->
+
+## Requirements
+
+<!-- The requirement set, grouped. Each one numbered so tests, TRDs and reviews can cite it. -->
+
+## User flows
+
+<!-- The paths through the product, including the ones that fail. Link UX documents for detail. -->
+
+## Functional requirements
+
+<!-- What the system must do. Each independently verifiable. -->
+
+## Non-functional requirements
+
+<!-- Latency, throughput, availability, limits. Numbers, not adjectives. Targets with no number cannot be met or missed. -->
+
+## Security considerations
+
+<!-- New data, new trust boundaries, new authorization. Link the threat model if one is needed. -->
+
+## Edge cases
+
+<!-- Empty states, concurrency, partial failure, abuse, the largest plausible input. Where requirements go to be tested. -->
+
+## Dependencies
+
+<!-- Teams, services, contracts and decisions this needs. What happens to the plan if each one slips. -->
+
+## Acceptance criteria
+
+<!-- Conditions a reviewer can check. If a criterion cannot be checked, it is an aspiration, not a criterion. -->
+
+## Open questions
+
+<!-- Unresolved, each with an owner and the date by which it blocks. -->

package/templates/security.threat-model.md

@@ -0,0 +1,51 @@
+# <System> — Threat Model
+
+> This document names risks that are not yet fixed. It must stay `visibility: internal`.
+> The public counterpart is a separate document (`security.public-model`), not a redaction.
+
+## Scope
+
+<!-- What this covers and, just as importantly, what it does not. Out-of-scope components need their own model or an explicit statement that they are trusted. -->
+
+## Assets
+
+<!-- What is worth protecting, in priority order, and why. Data, availability, integrity, reputation. -->
+
+## Actors
+
+<!--
+Each actor with capability and motive. Include the unglamorous ones: a legitimate user
+exceeding their authorization, a compromised dependency, an employee with production access,
+an automated agent acting on an injected instruction.
+-->
+
+## Trust boundaries
+
+<!-- Where trust changes. For each: what crosses it, what is validated there, and by what. -->
+
+## Entry points
+
+<!-- Every way input enters: endpoints, queues, webhooks, file uploads, CLI, admin interfaces, agent tool calls. -->
+
+## Data flows
+
+<!-- How data moves between boundaries, in what form, with what protection at each hop. -->
+
+## Threats
+
+<!--
+Each threat: the asset, the actor, the entry point, the mechanism, and the likelihood. Give
+each an id so controls and residual risks can cite it.
+-->
+
+## Controls
+
+<!-- What stops each threat, with a link to the implementation. A control with no threat is a checklist item; a threat with no control belongs under residual risks. -->
+
+## Residual risks
+
+<!-- What remains after the controls. Who accepted it, when, and under what condition it needs revisiting. An empty section here almost always means the analysis stopped early. -->
+
+## Assumptions
+
+<!-- What must be true for this model to hold. When one of these breaks, this list tells you what else just broke. -->

package/templates/user.readme.md

@@ -0,0 +1,43 @@
+# <Project name>
+
+<!-- One or two sentences: what this is. No marketing, no "blazing fast". -->
+
+## Why
+
+<!-- Why use this rather than the obvious alternative. Two or three lines. -->
+
+## Install
+
+```bash
+# the shortest path from nothing to installed
+```
+
+## Usage
+
+```bash
+# the smallest useful example, runnable exactly as written
+```
+
+<!-- Then what the reader should see. -->
+
+## What it does
+
+<!-- A short list of capabilities, each linking to its own document. A list, not a tour. -->
+
+## Documentation
+
+<!-- Links to the real documentation. This is where depth lives; the README points at it. -->
+
+## Contributing
+
+<!-- Link CONTRIBUTING.md. -->
+
+## Help
+
+<!-- Where to ask. Issues, discussions, a channel. -->
+
+<!--
+README lens: under 300 lines. Architecture gets three lines and a link, never 200 lines.
+If a section has grown past about 40 lines it has become its own document — run
+`docgov check` and it will tell you where to move it.
+-->