agent-doc-system 0.0.0-stage → 1.0.0

package/schemas/journeys.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/journeys.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "journeys"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "agentdoc.dev/journeys/v1"
+    },
+    "journeys": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "description",
+          "components"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "common.json#/$defs/name"
+          },
+          "description": {
+            "$ref": "common.json#/$defs/description"
+          },
+          "components": {
+            "type": "array",
+            "minItems": 2,
+            "uniqueItems": true,
+            "items": {
+              "$ref": "common.json#/$defs/componentRef"
+            }
+          },
+          "notes": {
+            "$ref": "common.json#/$defs/rationale"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/observation.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/observation.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "properties": {
+    "apiVersion": {
+      "const": "agentdoc.dev/observation/v1"
+    },
+    "kind": {
+      "const": "ObservationSet"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "description",
+        "environment",
+        "capturedAt",
+        "sourceSystem",
+        "collector",
+        "evidenceBundle"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "common.json#/$defs/name"
+        },
+        "description": {
+          "$ref": "common.json#/$defs/description"
+        },
+        "environment": {
+          "description": "Which environment the observation describes. Never a secret-bearing identifier.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 60,
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "capturedAt": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+        },
+        "maxAgeDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650
+        },
+        "sourceSystem": {
+          "description": "The authoritative external system the facts came from.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "collector": {
+          "description": "Retrieval method identity: the command or API used to read the source system.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "pattern": "^[^\\n\\r]+$"
+        },
+        "evidenceBundle": {
+          "description": "Durable, secret-free, repository-relative reference to the raw observation. Never a temp path, host path or console URL with credentials.",
+          "$ref": "common.json#/$defs/repoPath"
+        },
+        "supersedes": {
+          "$ref": "common.json#/$defs/name"
+        },
+        "provenance": {
+          "type": "string",
+          "maxLength": 280
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "facts"
+      ],
+      "properties": {
+        "facts": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "subject",
+              "key",
+              "value",
+              "semantics"
+            ],
+            "properties": {
+              "id": {
+                "$ref": "common.json#/$defs/name"
+              },
+              "subject": {
+                "$ref": "common.json#/$defs/entityRef"
+              },
+              "key": {
+                "description": "Dotted claim key, e.g. schedule.cron, binding.kv, contract.supports-annotations.",
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80,
+                "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$"
+              },
+              "value": {
+                "description": "Observed value. A JSON scalar, array of scalars, or null when the fact is known to be absent."
+              },
+              "semantics": {
+                "description": "What the observed value actually means, in one sentence.",
+                "$ref": "common.json#/$defs/rationale"
+              },
+              "observedRefs": {
+                "type": "array",
+                "maxItems": 16,
+                "uniqueItems": true,
+                "items": {
+                  "$ref": "common.json#/$defs/entityRef"
+                }
+              },
+              "detail": {
+                "type": "string",
+                "maxLength": 600
+              }
+            }
+          }
+        }
+      }
+    },
+    "extensions": {
+      "$ref": "common.json#/$defs/extensions"
+    }
+  }
+}

package/schemas/resource.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/resource.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": { "const": "agentdoc.dev/v1" },
+    "kind": { "const": "Resource" },
+    "metadata": { "$ref": "common.json#/$defs/metadata" },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["logical-database", "logical-dataset", "event-bus", "queue", "cache", "object-store", "search-index", "secret-store", "other"] },
+        "placementRationale": { "$ref": "common.json#/$defs/rationale" },
+        "system": { "$ref": "common.json#/$defs/name" },
+        "context": { "$ref": "common.json#/$defs/context" }
+      },
+      "oneOf": [
+        { "required": ["system"] },
+        { "required": ["placementRationale"] }
+      ]
+    },
+    "extensions": { "$ref": "common.json#/$defs/extensions" }
+  }
+}

package/schemas/system.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/system.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": { "const": "agentdoc.dev/v1" },
+    "kind": { "const": "System" },
+    "metadata": { "$ref": "common.json#/$defs/metadata" },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "domain": { "$ref": "common.json#/$defs/name" },
+        "placementRationale": { "$ref": "common.json#/$defs/rationale" },
+        "context": { "$ref": "common.json#/$defs/context" }
+      },
+      "oneOf": [
+        { "required": ["domain"], "not": { "required": ["placementRationale"] } },
+        { "required": ["placementRationale"], "not": { "required": ["domain"] } }
+      ]
+    },
+    "extensions": { "$ref": "common.json#/$defs/extensions" }
+  }
+}

package/skills/agent-doc-system/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: agent-doc-system
+description: Use AgentDoc to create, migrate, query, validate, and maintain an agent-oriented software catalog and documentation system for a codebase. Use when architectural context, dependency impact, documentation drift, provenance, authority conflicts, or repository documentation migration matters.
+---
+
+# AgentDoc
+
+AgentDoc is a machine-installed CLI (`agentdoc`) that compiles a repository into
+one deterministic graph and routes a path or entity to the minimum context
+needed to change it safely. This skill teaches you how to operate it.
+
+## Prerequisite
+
+The CLI must already be installed on this machine:
+
+```bash
+agentdoc --version
+```
+
+If that fails, AgentDoc is not installed. Stop, report the missing prerequisite,
+and point the user at `INSTALL_FOR_AGENTS.md` in the agent-doc-system
+repository. Do not clone the source repository into the user's project — the
+CLI is installed on the machine, never vendored into a project.
+
+## When to use it
+
+- The repository contains `agentdoc/agentdoc.config.yaml` — a catalog exists
+  and you are using it.
+- You are about to change files and need to know what else must stay
+  consistent.
+- You were asked to document a repository, audit its docs, find what depends
+  on X, or explain why production disagrees with the manifest.
+
+Do not use it to write prose. The system routes facts; prose lives in the files
+it points at.
+
+## The mental model
+
+Three kinds of claim get conflated in most repositories, and the confusion is
+the main way an agent goes wrong:
+
+| kind | who makes it | how it fails |
+|---|---|---|
+| what the repository **claims** | authored docs, config, manifests | drifts; states intent, not fact |
+| what is **derived** from code | imports, manifests, contracts | incomplete; cannot know intent |
+| what was **observed** running | schedulers, bindings, live APIs | goes stale; disagrees with intent |
+
+A fact carries an evidence class, a confidence, and a pointer to its evidence.
+When classes disagree, the disagreement is **surfaced as a conflict**, not
+reconciled. There is no global precedence order: authority depends on the fact.
+
+**Your obligation:** never present a claim from one class as if it came from
+another. If the graph reports a conflict or an unresolved fact, say so.
+
+## Pick the workflow
+
+| workflow | when | entry point |
+|---|---|---|
+| CREATE | no `agentdoc/` config exists | `agentdoc init`, then `scaffold --write` |
+| MIGRATE | established repo, scattered or stale docs | `agentdoc audit`, then work the report |
+| VALIDATE | before committing, in CI | `agentdoc validate` → `compile` → `check` |
+| QUERY | before and during a change | `agentdoc query <path-or-ref>` |
+| MAINTAIN | after a change | `agentdoc impact <paths>` |
+
+CREATE versus MIGRATE is not about size: a repository whose existing docs make
+*claims* is a migration, because those claims must be verified. Details:
+[references/create-migrate.md](references/create-migrate.md).
+
+## The normal loop
+
+```bash
+agentdoc impact <files I will change>   # what this reaches
+agentdoc query <path>                   # minimum context, compact
+agentdoc query <path> --json            # full payload
+# ... make the change ...
+agentdoc impact <files I changed>       # what must stay consistent
+agentdoc validate && agentdoc check     # prove it
+```
+
+If `check` fails, the committed graph no longer describes the repository. Do
+not work around it: run `agentdoc compile`, review the diff, commit the graph.
+
+## Rules that are never optional
+
+- **Never vendor the CLI.** A project gets `agentdoc/` project data (config,
+  descriptors, observations), `docs/` skeletons, `.agentdoc/graph.json` and a
+  CI workflow — never a copy of the agentdoc source tree (`core/`, `bin/`,
+  `adapters/`, `schemas/`, `templates/`, `evals/`, `tests/`).
+- **Never promote uncertainty.** Heuristic guesses do not become authored
+  facts; they become `reviewedOverrides` with evidence, or they stay out.
+- **Never reconcile a conflict by editing one side.** Add an authority rule for
+  the key, or report both values to a human. Details:
+  [references/authority-and-conflicts.md](references/authority-and-conflicts.md).
+- **Never write a secret** into a descriptor, observation, evidence bundle or
+  commit message. Validation fails on secret-shaped input *and* output.
+- **Never hand-edit `.agentdoc/graph.json`.** The gate rejects it, and it would
+  be wrong anyway.
+- **Do not trust existing documentation.** In MIGRATE it is evidence of what
+  someone once believed; the audit says where that belief contradicts the code.
+
+## Deeper references
+
+| file | covers |
+|---|---|
+| [references/cli.md](references/cli.md) | every command, flag and exit code |
+| [references/create-migrate.md](references/create-migrate.md) | the two onboarding workflows and the audit report |
+| [references/authority-and-conflicts.md](references/authority-and-conflicts.md) | evidence classes, elections, secrets, descriptors |
+| [references/maintenance.md](references/maintenance.md) | keeping the catalog true: gates, freshness, evidence handover |
+
+The normative specification (`docs/SPEC.md`, `docs/AUTHORITY.md`,
+`docs/PROVENANCE.md`, `docs/QUERY.md`, `docs/MIGRATION.md`, `docs/CI.md`) lives
+in the agent-doc-system repository — read it when a rule here needs the full
+contract behind it.

package/skills/agent-doc-system/references/authority-and-conflicts.md

@@ -0,0 +1,70 @@
+# Evidence, authority and conflicts
+
+## The three evidence classes
+
+| class | source | may be authored? |
+|---|---|---|
+| `AUTHORED` | a file in the repository you can point at | yes |
+| `DERIVED` | a deterministic extractor produces it | yes, once reviewed |
+| `OBSERVED_RUNTIME` | an `agentdoc/observations/*.yaml` ObservationSet, written after actually reading the external system | **no** — it belongs in an ObservationSet |
+| `REVIEWED_OVERRIDE` | a reviewed human interpretation, citing pinned evidence | yes, with `reviewWhen` and evidence digests |
+
+There is no global precedence order. The committed manifest is authoritative
+for *intent*; a live scheduler is authoritative for *what fires*; the canonical
+contract is authoritative for the *desired wire surface* while a live probe is
+authoritative for *what is deployed today*. Which class wins is decided per
+fact key, by an explicit authority rule.
+
+## When you cannot establish a fact
+
+- **Heuristic guess** — do not write it. Add a `reviewedOverrides` entry with a
+  `reason`, a `reviewWhen`, and file-level `evidence` (path + sha256, via
+  `agentdoc pin-evidence`), or leave it out.
+- **Two sources disagree** — do not pick one. Either add an authority rule that
+  says which class is authoritative *for that key*, or report the contradiction
+  to a human. Fail-closed is the default: a disagreeing fact with no governing
+  rule is an error, and no gate passes while it stands.
+- **Product or ownership decision** — ask. Do not infer ownership from folder
+  names.
+
+## Handling a reported conflict
+
+`agentdoc query <ref> --json` returns `authority.conflicts`. For each one:
+
+1. Read `election.basis` and `election.ruleId`. `basis: none` means no rule
+   governs this fact and the system refused to choose.
+2. Both values stay in the graph. Report both to the human, with their evidence
+   pointers, and say which one the system elected and why.
+3. If the right answer is "the runtime wins for this key", add an authority
+   rule with `elect: [OBSERVED_RUNTIME]`, a `rationale`, and a `reviewWhen`.
+   Do not edit the observation to match the manifest, and do not edit the
+   manifest to match the observation.
+
+## Secrets
+
+Never write a credential, token, key or credentialed URL into a descriptor, an
+observation, an evidence bundle, or a commit message. `agentdoc validate`
+fails on secret-shaped input, and the output scanner fails on secret-shaped
+output too. Observations cite a committed, secret-free evidence bundle by
+repository-relative path — a temp path, a console URL with a session token, or
+a screenshot filename is not evidence.
+
+## Writing descriptors
+
+The templates ship with the CLI (`templates/` in the package). The rules that
+matter:
+
+- A Component descriptor lives at the root of the unit it describes, named by
+  `discovery.componentDescriptorName` (conventionally `agentdoc.yaml`).
+- `metadata.description` is **one sentence, present tense**, ending in `.`,
+  `!` or `?`. It says what the component is *for*.
+- Placement is exactly one of `system`, `domain`, or `placementRationale`.
+- Every durable cross-component boundary has exactly one canonical
+  machine-readable contract, and exactly one API descriptor pointing at it.
+  Default to OpenAPI 3.1 for JSON HTTP; a protocol's native schema is equally
+  valid.
+- You never author a relation. Placement and API provider edges come from the
+  descriptor; everything else is derived or reviewed.
+
+The full model is `docs/AUTHORITY.md` and `docs/PROVENANCE.md` in the agentdoc
+repository.

package/skills/agent-doc-system/references/cli.md

@@ -0,0 +1,89 @@
+# agentdoc CLI reference
+
+The binary is `agentdoc`, installed once per machine. Every command that
+operates on a catalog can be run from any subdirectory of the repository: the
+configuration is found by walking up to `agentdoc/agentdoc.config.yaml`. No
+command ever needs the agentdoc source tree or a path to it.
+
+Exit codes: `0` ok, `1` failure, `2` usage.
+
+## Meta
+
+```bash
+agentdoc --version          # installed version
+agentdoc --help             # command list (also: agentdoc <command> --help)
+agentdoc doctor             # machine check: is this CLI install healthy
+agentdoc doctor --project   # the same, plus the current project's catalog health
+```
+
+`doctor` answers "is the CLI itself healthy": supported Node, schema bundle,
+compiler version. It never fails because a project is not configured yet.
+`doctor --project` additionally checks `agentdoc/agentdoc.config.yaml` exists,
+parses, and that the repository root is writable — run it inside a project.
+
+## Onboarding
+
+```bash
+agentdoc init [--force]     # write agentdoc/agentdoc.config.yaml + doc skeleton
+agentdoc audit              # inventory the repo, classify every fact (JSON)
+agentdoc scaffold [--write] # generate descriptors for what can be proven
+```
+
+`init` never overwrites an existing file without `--force`, and run inside a
+subdirectory of a cataloged repository it writes at the catalog root, not the
+current directory. `scaffold` is a dry run without `--write`; with `--write` it
+is a superset of `init` — it also installs anything missing from the config,
+doc skeleton and CI workflow, not only component descriptors. `audit` works
+even when the repository cannot compile yet; it reports the compilation
+failures as part of its output.
+
+## Validation
+
+```bash
+agentdoc validate                       # sources + schemas + semantic checks
+agentdoc compile [--require-clean]      # deterministic graph build, atomic write
+agentdoc check [--require-clean] [--allow-stale-observations]
+```
+
+`compile` writes `.agentdoc/graph.json` (or the path in `output.graph`).
+`check` is the gate: it fails on a stale or hand-edited graph, a compiler or
+schema version mismatch, an observation past its declared `maxAgeDays`, and —
+with `--require-clean` — catalog inputs that differ from `HEAD`.
+
+## Query and impact
+
+```bash
+agentdoc query <path|entity-ref>          # compact markdown context
+agentdoc query <path|entity-ref> --json   # full payload
+agentdoc query <path> --budget relations=10,verification=4
+agentdoc impact <paths...>                # what a change forces consistent
+agentdoc impact --diff <git-ref>          # the same, for a commit range
+```
+
+`query` refuses a stale graph — it never falls back to one. `impact` answers a
+question about the working tree, so it compiles in memory instead: run it
+*before* rebuilding.
+
+Entity refs look like `component:<namespace>/<name>` — `query --json` returns
+`entity.ref` values you can reuse.
+
+## Maintenance
+
+```bash
+agentdoc pin-evidence [--json]   # which pinned evidence digests are current
+agentdoc eval routing [--json]   # routing evaluation (meaningful on a source
+                                 # checkout; exits SKIP on other repositories)
+```
+
+Reviewed overrides pin their evidence by content hash, re-verified on every
+compile. `pin-evidence` reports `CURRENT` / `STALE` / `MISSING` per entry so a
+digest can be updated without computing SHA-256 by hand. It exits `1` when any
+entry is not current.
+
+## Error output
+
+Diagnostics are lines of the form `ERROR <CODE>: <message>` on stderr, with a
+JSON stats object. `WARN` lines are non-fatal; `WARN ACCEPTED` lines carry the
+acceptance classification and reason. The full code registry is
+`core/codes.mjs` in the agentdoc source; the operator-facing table is in
+`docs/CI.md` of the repository.

package/skills/agent-doc-system/references/create-migrate.md

@@ -0,0 +1,101 @@
+# CREATE and MIGRATE
+
+Two onboarding workflows. CREATE for a repository with no catalog; MIGRATE for
+an established one. Both start with the same audit; MIGRATE adds a
+source-of-truth mapping and a reviewed-ambiguity list a human must work
+through.
+
+## Choosing
+
+| situation | mode |
+|---|---|
+| no `agentdoc/` directory, small or new repository | CREATE |
+| no `agentdoc/`, large or established repository | MIGRATE |
+| an existing catalog, documentation that has drifted | MIGRATE |
+
+The test is not size. It is whether the repository has documentation that
+*claims* things. Claims need verifying — that is migration work regardless of
+how few components there are.
+
+## CREATE
+
+```bash
+cd <repository root>
+agentdoc doctor --project          # expect configurationFound: false for now
+agentdoc init                      # config skeleton + documentation hierarchy
+$EDITOR agentdoc/agentdoc.config.yaml
+agentdoc audit                     # what is provable, what is not
+agentdoc scaffold                  # dry run: what it would write
+agentdoc scaffold --write          # write descriptors for provable units
+$EDITOR '**/agentdoc.yaml'         # review every generated description
+agentdoc validate && agentdoc compile && agentdoc check
+```
+
+`init` writes `agentdoc/agentdoc.config.yaml`, the central descriptor files
+(`domains.yaml`, `systems.yaml`, `apis.yaml`, `resources.yaml`),
+`agentdoc/journeys.yaml`, the documentation hierarchy under `docs/`, the
+observations README, and a CI workflow. It writes **project data only** — it
+never copies the agentdoc implementation into the repository.
+
+In `agentdoc.config.yaml`:
+
+- Set `namespace`, fix `discovery.componentDescriptors` to match the real
+  layout, and enable the adapters for the technologies present. `adapters: []`
+  is a valid but useless starting point: with no adapter, a component
+  descriptor is an unsupported claim and compilation fails on purpose.
+- Three example authority rules are written **commented out**. Uncomment only
+  the ones you can justify, with the rationale in your own words. An authority
+  rule is a governance decision; the scaffolder does not make it for you.
+
+A generated description is a statement about artifact evidence, not a product
+claim. Read every one and fix the ones that are wrong. The scaffolder never
+chooses a `system` or `domain`: placement is an ownership decision, so the
+generated descriptor carries a commented `placementRationale` prompt instead.
+
+## The audit report
+
+`agentdoc audit` runs even when the repository cannot compile, and inventories
+four truth sources independently: derivable facts, machine-readable contracts,
+authored documentation, and ObservationSets. Key fields:
+
+| field | meaning |
+|---|---|
+| `facts` | every major fact classified `CONFIRMED` / `DERIVED` / `OBSERVED` / `CONFLICT` / `UNRESOLVED` |
+| `contradictions`, `documentationContradictions` | where sources disagree |
+| `reviewedAmbiguity` | the list a human must decide |
+| `documentation.orphanDocs` | documents nothing will ever route to |
+| `documentation.undocumentedComponents` | components an agent will get wrong |
+| `contracts.unclaimed` | contract files no API descriptor owns |
+| `scaffold` | what the scaffolder proposes to write |
+
+`OBSERVED` facts cannot be authored — they belong in an ObservationSet under
+`agentdoc/observations/`. `CONFLICT` and `UNRESOLVED` need a human.
+
+## MIGRATE
+
+```bash
+agentdoc init
+# set componentDescriptors to the real layout; enable the right adapters
+agentdoc audit > migration-report.json
+```
+
+Then, in order:
+
+1. **Source-of-truth mapping.** For each major claim, record which inventory
+   supports it. Anything supported by none goes to `reviewedAmbiguity`.
+2. **Contradictions.** Work `contradictions` and `documentationContradictions`.
+   Each needs a human decision: fix the docs, fix the code, or add an authority
+   rule saying which class wins for that key.
+3. **Orphan docs.** Link each to a component via `context.docs`, or delete it.
+4. **Missing docs.** Work `undocumentedComponents` / `unverifiedComponents`.
+5. **Stale contracts.** Point the API descriptor at the current contract file.
+6. **Ownership.** Placement from code where unambiguous, from a human elsewhere.
+7. **Catalog.** `scaffold --write`, review every generated file.
+8. **Gate.** `validate` → `compile` → `check`, then install CI.
+
+**Do not trust existing documentation.** The single most common migration
+failure is copying existing prose into descriptions. If you cannot write a
+one-sentence present-tense statement of a component's current purpose, the
+purpose is not understood yet — that discovery is the point.
+
+The full workflow contract is `docs/MIGRATION.md` in the agentdoc repository.

package/skills/agent-doc-system/references/maintenance.md

@@ -0,0 +1,52 @@
+# Maintaining the catalog
+
+## The gate
+
+`agentdoc check` is the contract. Inside it, in order:
+
+1. compilation errors;
+2. time-dependent gates (an observation older than its `maxAgeDays`);
+3. graph freshness and byte comparison against a fresh deterministic compile;
+4. `--require-clean` (catalog inputs must match `HEAD`).
+
+Step 2 precedes step 3 on purpose: "your observation is five years old" and
+"rebuild the graph" send the reader to different places, and when both are true
+the first is the one that matters.
+
+## Discipline
+
+- Any PR that changes a compiler input must recompile and commit the graph.
+  `agentdoc impact <paths>` tells you which files are inputs.
+- Never hand-edit `.agentdoc/graph.json`. The gate rejects it, and it would be
+  wrong anyway.
+- A change to a warning acceptance is a deliberate act: the acceptance pins the
+  evidence digests it was written against, and changing the evidence
+  invalidates it on purpose.
+- An observation is a promise about freshness. Re-observe before `maxAgeDays`,
+  or restate the fact as authored intent if the divergence is intended.
+- Schema and compiler versions are recorded in the graph. Upgrading the CLI
+  invalidates every graph; recompile, review the diff, commit.
+- `agentdoc pin-evidence` reports which reviewed-override digests are current
+  so stale evidence can be re-pinned without computing SHA-256 by hand.
+
+## CI
+
+`agentdoc init` writes `.github/workflows/agentdoc.yml`: validate, compile,
+check, `check --require-clean`. The runner installs the CLI
+(`npm install -g github:lbframe/agent-doc-system`). Any other runner works the
+same way — the gate is four commands and an exit code; `docs/CI.md` in the
+repository lists the failure codes and what each one asks of you.
+
+## Packaging final evidence
+
+When you finish a task in a cataloged repository, hand over:
+
+1. `agentdoc check` output (must pass).
+2. `agentdoc query <path> --json` for each surface you touched.
+3. `agentdoc impact <changed files>` showing what you kept consistent.
+4. For any conflict you encountered: both values, their evidence, the election,
+   and your recommendation.
+5. Anything left `UNRESOLVED`, stated as unresolved.
+
+Do not summarise a conflict away. The value of this system is that it tells you
+when you do not know something.