docgov-cli 0.2.0

package/lenses/developer.md

@@ -0,0 +1,26 @@
+# Developer lens
+
+**The question:** can a competent engineer who does not know this system reproduce what the
+document describes, and predict what happens when it goes wrong?
+
+## Evaluates
+
+- **Technical precision.** Exact names, exact paths, exact versions. "Configure the service"
+  is not an instruction.
+- **Reproducibility.** Every command runnable as written. Prerequisites stated, not assumed.
+- **Examples.** At least one complete one. Fragments that assume surrounding context fail.
+- **Assumptions stated.** What must already be true. This is the most common omission and
+  the most expensive.
+- **Failure modes.** What breaks, how it surfaces, what to do. A document that only
+  describes the happy path is half a document.
+- **Dependencies.** What this needs, and what degrades when each is unavailable.
+- **Links to architecture.** Why, not just how — otherwise the reader cannot tell which
+  parts are safe to change.
+
+## Fails the lens
+
+- Passive voice hiding the actor: "the token is validated" — by what, when, and what happens
+  if it is not?
+- Version-less instructions that were true once.
+- "Simply", "just", "obviously". Each one marks a step the author skipped.
+- Copy-pasted schema or config instead of a link to the authoritative source.

package/lenses/operations.md

@@ -0,0 +1,32 @@
+# Operations lens
+
+**The question:** can an on-call engineer, woken at 3am, who did not build this, execute
+this correctly on the first attempt?
+
+## Evaluates
+
+- **Trigger.** The exact signal that starts this. An alert name, a symptom, a threshold.
+- **Preconditions.** Access required, approvals needed, what must be true first.
+- **Diagnostics before action.** Commands that establish what is actually happening.
+  Procedures that act before confirming cause make outages worse.
+- **Numbered steps, one action each.** Each with its expected result.
+- **Copy-pasteable commands.** No placeholders that need thought to fill.
+- **Validation.** How you know it worked, measured not assumed.
+- **Rollback.** How to undo, and the point past which you cannot.
+- **Escalation.** Who to wake, at what threshold, by what route.
+- **Time expectations.** If a step takes eleven minutes, say so, or it will be declared
+  hung and interrupted.
+
+## Fails the lens
+
+- Prose. Under pressure, prose is unreadable. Numbered steps.
+- "Investigate the issue" as a step.
+- "Contact the team" with no name, rotation or channel.
+- A step whose outcome is not observable.
+- Commands requiring access the preconditions did not mention.
+- Last reviewed two years ago with no verification that the commands still exist.
+
+## The test
+
+Could someone who has never seen this system execute it without asking a question? If not,
+the missing answer is the finding. A runbook is tested by being executed, not by being read.

package/lenses/readme.md

@@ -0,0 +1,32 @@
+# README lens
+
+**The question:** can a developer who has never seen this project understand what it is and
+get it running in five minutes?
+
+## Must answer, in roughly this order
+
+1. What is this? (one or two sentences, no marketing)
+2. Why would I use it instead of the obvious alternative?
+3. What does it look like? (one example, or one image)
+4. How do I install it?
+5. How do I do the first useful thing?
+6. What else can it do? (a list, with links)
+7. Where is the deeper documentation?
+8. How do I contribute?
+9. Where do I get help?
+
+## Fails the lens
+
+- Architecture explained rather than summarized. Three lines and a link, not 200 lines.
+- Installation buried below the feature tour.
+- An example that does not run as written.
+- Internal implementation detail, team names, ticket references.
+- API reference inline. That is a reference document.
+- A changelog inline. That is `CHANGELOG.md`.
+- Badges occupying more vertical space than the description.
+- Over 300 lines. Past 500 it has stopped being a README.
+
+## The test
+
+Delete every section a first-time reader does not need in their first five minutes. If the
+README is now much shorter, the deleted sections were other documents wearing a README.

package/lenses/security.md

@@ -0,0 +1,33 @@
+# Security lens
+
+**The question:** does this document let a reader reason correctly about what is protected,
+from whom, and what is not protected at all?
+
+## Evaluates
+
+- **Trust boundaries.** Where trust changes, and what crosses each boundary.
+- **Threat actors.** Who, with what capability and what motive. "Hackers" is not an actor.
+- **Assets.** What is worth protecting, and why, in order.
+- **Authorization.** Subjects, resources, actions, and the rule that joins them. Checked
+  where — at the edge, in the service, in the database?
+- **Secret handling.** Where secrets live, how they rotate, who can read them.
+- **Abuse cases.** Not just "can an attacker get in" but "what can a legitimate user do that
+  they should not".
+- **Assumptions.** What must be true for the model to hold. When an assumption breaks, this
+  is the list that tells you what else just broke.
+- **Residual risk.** What remains after the controls, and who accepted it.
+
+## Fails the lens
+
+- Controls with no threats. A control list is not a threat model.
+- Threats with no controls and no residual-risk entry — silently accepted risk.
+- "We use encryption." Which data, at rest or in transit, which algorithm, whose keys?
+- Compliance framework names standing in for a security argument.
+- **Visibility error:** a threat model that names unmitigated vulnerabilities must be
+  `internal`. If it is in a public path, that is a critical finding, not a style note.
+
+## The internal/external pair
+
+A threat model (`internal`) and a public security model (`public`) are two documents, not
+one document with redactions. The public one says what you protect and how to report a
+vulnerability. The internal one says what you have not fixed yet.

package/lenses/user.md

@@ -0,0 +1,30 @@
+# User lens
+
+**The question:** can the intended reader — who does not know how the system is built and
+should not have to — complete the task they came for?
+
+## Evaluates
+
+- **Task orientation.** Organized around what the reader wants to do, not around how the
+  system is structured. Readers arrive with goals, not with a mental model of your modules.
+- **Jargon.** Every internal term either removed or defined on first use.
+- **No internal leakage.** No service names, team names, ticket ids, or hostnames.
+- **Prerequisites.** Stated before step one, not discovered at step four.
+- **Examples.** Runnable exactly as written, with realistic values.
+- **Expected results.** Each step says what the reader should see. Without that they cannot
+  tell success from silent failure.
+- **Failure recovery.** What to do when a step does not work, or where to go.
+
+## Fails the lens
+
+- Architecture explained to justify an instruction.
+- "See the API reference" where a concrete example belongs.
+- Screenshots of a UI that has since changed, with no version note.
+- Steps written from the author's environment: absolute paths, personal directories.
+- Diátaxis confusion: a tutorial that is really a reference, a how-to that is really an
+  explanation. Each of the four forms answers a different need; mixing them serves none.
+
+## The test
+
+Hand it to someone who has never used the system. If they ask a question the document could
+have answered, that question is the finding.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "docgov-cli",
+  "version": "0.2.0",
+  "description": "Your AI writes docs faster than anyone can check them. DocGov checks them.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "docgov": "bin/docgov"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "docgov": "node ./bin/docgov"
+  },
+  "files": [
+    "bin",
+    "core",
+    "templates",
+    "lenses",
+    "schemas",
+    "policy",
+    "skills",
+    "agents",
+    "hooks",
+    ".claude-plugin"
+  ],
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZeeshanSultan/DocGov.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ZeeshanSultan/DocGov/issues"
+  },
+  "homepage": "https://github.com/ZeeshanSultan/DocGov#readme",
+  "author": "Zeeshan Sultan"
+}

package/policy/documentation.md

@@ -0,0 +1,82 @@
+# Documentation rules
+
+DocGov governs documentation in this repository. Mode: `{{MODE}}`. Layout: `{{LAYOUT}}`.
+
+These rules apply to every agent and every human. They exist because a repository
+with many authors — most of them now agents — degrades its documentation faster
+than any review process can repair it.
+
+## Before creating any documentation
+
+1. **Check whether it already exists.** `docgov find "<topic>"` returns results in
+   authority order. If an authoritative document already covers the topic, update
+   that document. Do not create a second one.
+2. **Find out what you are writing.** `docgov whatis --path <intended-file>` names
+   the document class, its canonical location, its required sections and its limits.
+3. **Create it through DocGov.** `docgov create <type> "<name>" [--domain <d>]` puts
+   it in the right place, applies the template, and wires it into the graph. A
+   document not in the graph is invisible to impact analysis, which means nobody
+   will be told when it goes stale.
+
+Never invent a new top-level Markdown file. Never invent a new documentation
+directory. The taxonomy has 57 document classes; run `docgov types` before
+concluding that yours is not one of them.
+
+## Before editing code in a governed area
+
+Run `docgov brief <domain>` and read it. It is the minimum authoritative context
+for that area: the constitution, the canonical specification, the rules in
+force, the relevant ADRs and the machine contracts — and nothing else.
+
+If a rule blocks what you were about to do, the rule wins. Changing it
+means changing its source document in the same change, with a reason.
+
+## Authority
+
+Authority is ordered and it is not negotiable:
+
+```
+constitution  >  canonical  >  requirements / decision  >  machine contract
+              >  implementation  >  generated  >  audience  >  historical
+```
+
+A lower-authority document may not contradict a higher one. If you find a
+contradiction, do not fix it by editing the lower document into agreement — work
+out which one is actually right, fix that one, and record the decision.
+
+Machine contracts (OpenAPI, JSON Schema, protobuf, GraphQL, migrations) are
+authoritative over any prose that describes them. Reference them; do not restate
+their contents.
+
+## Writing
+
+- Apply the template for the class. Required sections are a deterministic gate, not
+  a style preference — a TRD with no failure analysis is not a TRD.
+- Respect the audience. A README answers "what is this and how do I start" in under
+  300 lines and links everything deeper. An architecture document does not explain
+  how to install anything.
+- Keep one document to one concept. If a document holds several independently
+  addressable concepts, it should be a directory with an index.
+- Never edit a generated document. Change its source and regenerate.
+- Never edit the archive. It is a historical record.
+- No TBD, TODO or FIXME in a document another agent will read as fact. Either state
+  what is true, or say explicitly that it is unknown and who owns finding out.
+
+## After changing anything material
+
+1. `docgov affected` — which documents this change affects, and which of them are
+   required rather than optional.
+2. Update the required ones in the same change. "I will document it later" is how
+   drift starts.
+3. `docgov check` — deterministic violations. Blocking checks in this mode:
+   `{{BLOCKING}}`.
+4. If a check is genuinely wrong for your case, `docgov ignore <ID> --reason "..."`.
+   A suppression needs a reason, stays visible in every report, and can expire. What
+   it never does is disappear.
+
+## What DocGov will not do for you
+
+It will not decide whether two documents contradict each other, whether a document
+should be split, or whether prose is clear. Those are judgement calls: they are
+reported for review, never enforced automatically. Everything DocGov blocks is
+something software can decide without guessing.

package/schemas/config.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ZeeshanSultan/DocGov/main/schemas/config.json",
+  "title": "DocGov configuration",
+  "description": ".docgov/config.yaml \u2014 every governance decision is configurable here. A policy pack may set any of these; local config always wins.",
+  "type": "object",
+  "required": [
+    "version",
+    "project"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "project": {
+      "type": "object",
+      "required": [
+        "mode"
+      ],
+      "properties": {
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "mode": {
+          "enum": [
+            "solo",
+            "team",
+            "enterprise",
+            "open-source"
+          ],
+          "description": "Decides how much blocks. solo blocks 3 rules; enterprise blocks 12. Over-enforcement is the main reason governance tooling gets uninstalled."
+        },
+        "visibility": {
+          "enum": [
+            "internal",
+            "public",
+            "mixed"
+          ]
+        },
+        "layout": {
+          "enum": [
+            "compact",
+            "full"
+          ],
+          "description": "compact suits most repositories. full is the numbered 00-canonical\u202699-archive tree; it earns its overhead at roughly 25+ documents."
+        }
+      }
+    },
+    "documentation": {
+      "type": "object",
+      "properties": {
+        "root": {
+          "type": "string"
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Agent infrastructure is excluded by default: governing the files that configure DocGov is not useful."
+        },
+        "registrations": {
+          "type": "object",
+          "description": "Documents governed from config instead of from a `docgov:` block in the file. GitHub renders YAML frontmatter in Markdown as a table, so the files it surfaces on a project's front page \u2014 README, CONTRIBUTING, SECURITY, CHANGELOG \u2014 should be registered here and carry no frontmatter. Keys are repository-relative paths; values take the same fields as a `docgov:` block.",
+          "additionalProperties": {
+            "$ref": "frontmatter.json#/properties/docgov"
+          }
+        }
+      }
+    },
+    "governance": {
+      "type": "object",
+      "properties": {
+        "canonical_changes_require_review": {
+          "type": "boolean"
+        },
+        "prevent_duplicate_domains": {
+          "type": "boolean"
+        },
+        "enforce": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          },
+          "description": "Rule ids that block. null derives the list from the project mode."
+        },
+        "warn_only": {
+          "type": "boolean",
+          "description": "Nothing blocks. Useful while adopting DocGov on an existing repository."
+        },
+        "max_new_root_docs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "description": "Per document type. Line counts gate whether a semantic review is worth spending; they never trigger an automatic split.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "soft_lines": {
+            "type": "integer"
+          },
+          "hard_lines": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    "quality": {
+      "type": "object",
+      "description": "Advisory thresholds per type. Never used as a hard gate: a subjective judgement that fails a build is one nobody can appeal.",
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 100
+      }
+    },
+    "visibility_paths": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "glob",
+          "require"
+        ],
+        "properties": {
+          "glob": {
+            "type": "string"
+          },
+          "require": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "generated_paths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "drift": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "stale_threshold": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "lookback": {
+          "type": "string"
+        },
+        "fail_on": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ]
+          }
+        }
+      }
+    },
+    "generated": {
+      "type": "object",
+      "properties": {
+        "allow_manual_edit": {
+          "type": "boolean"
+        }
+      }
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    },
+    "domains": {
+      "type": "object",
+      "description": "The highest-leverage section. Mapping a domain to code paths is what switches on context packs, invariant injection and drift detection.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "docs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "owner": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "policy_packs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "V3 organizational governance: paths to policy packs whose taxonomy, limits, quality thresholds and invariants layer under this config. The repository always keeps the last word."
+    },
+    "suppressions_file": {
+      "type": "string"
+    }
+  }
+}