agent-doc-system 1.0.0 → 1.1.0

package/docs/MIGRATION.md

@@ -41,6 +41,7 @@ independently:
   "counts":     { "CONFIRMED": 4, "DERIVED": 38 },
   "contradictions": [ ... ],
   "documentationContradictions": [ ... ],
+  "normative":  { "sections": [ { "path", "section", "heading", "sha256", "coveredBy" } ], "uncovered": [ ... ], "requirements": [ ... ] },
   "reviewedAmbiguity": [ ... ],
   "documentation": { "orphanDocs", "undocumentedComponents", "unverifiedComponents" },
   "contracts":  { "inventory", "unclaimed" },
@@ -77,6 +78,64 @@ be checked at all.
 The rule for extending this: only check vocabulary the graph owns. A check that
 guesses is a check that cries wolf.
 
+**These are the only automatic documentation checks.** The audit does not read
+prose for meaning, so it does not find where an arbitrary sentence contradicts
+the code. A specification saying "the verifier runtime is installed on the
+production host" is invisible to it until someone turns that sentence into a
+requirement — which is what the next section makes mandatory.
+
+### Normative requirements
+
+A specification that is linked to a component is *routed*; that says nothing
+about whether anyone checked the implementation against it. List the documents
+that state obligations in `docs.normative`:
+
+```yaml
+docs:
+  normative:
+    - specs/**
+    - verification_layer/*_PROFILE.md
+```
+
+Every level-2 (`##`) section of those documents is then pinned by digest and
+must be accounted for in one of two ways:
+
+- **a requirement** on the component that must fulfil it, citing the section:
+
+  ```yaml
+  # provisioning/agentdoc.yaml
+  spec:
+    requirements:
+      - id: verification-runtime-on-host
+        key: requirement.provides.verification-runtime
+        value: provided
+        source:
+          path: specs/EXECUTION_LAYER_SPEC.md
+          section: 13-host-configuration
+          sha256: <digest from `agentdoc audit` → normative.sections>
+        satisfiedBy: [ansible]
+        expects:
+          installs: /var/lib/agent-platform-runtime/verification-python-v1
+  ```
+
+- **an attestation** in `normativeCoverage` that the section carries no
+  implementation obligation (`disposition: no-implementation-obligation` or
+  `informative`), with a reason and a review condition.
+
+A section that is neither raises `AGENTDOC_NORMATIVE_UNCOVERED`. A requirement
+is an `AUTHORED` fact that can only be *corroborated*: until implementation
+evidence on the same key agrees with it — a `DERIVED` fact from an adapter
+named in `satisfiedBy` that finds what `expects` names (see `ADAPTERS.md`,
+`ansible`), or a
+`requirement-satisfaction` reviewed override citing the implementation — it is
+`UNRESOLVED` and raises `AGENTDOC_REQUIREMENT_UNVERIFIED`, naming the adapter in
+`satisfiedBy` that is missing. Implementation evidence that disagrees is a
+conflict no authority rule may settle (see `AUTHORITY.md`). Editing a cited
+section invalidates its requirement or attestation
+(`AGENTDOC_NORMATIVE_SOURCE_STALE`): the review has to be redone.
+
+A missing adapter lowers coverage; it never makes an obligation disappear.
+
 ### Reviewed ambiguity
 
 The list a human must work through:
@@ -88,6 +147,8 @@ The list a human must work through:
 | `UNCLAIMED_CONTRACT` | which API owns this contract, or is it dead? |
 | `REVIEWED_OVERRIDE` | is this interpretation still true? |
 | `NEGATED_COMPONENT`, `PORT_MISMATCH`, `UNLINKED_PORT_CLAIM` | which source is right? |
+| `NORMATIVE_UNCOVERED` | what does this section oblige, and which component must do it? |
+| `REQUIREMENT_UNVERIFIED` | where is the implementation — or is this a gap to fix before release? |
 
 ## CREATE
 
@@ -132,9 +193,12 @@ agentdoc audit > migration-report.json
 
 Then, in order:
 
-1. **Source-of-truth mapping.** For each major claim, record which of the four
-   inventories supports it. Anything supported by none goes to
-   `reviewedAmbiguity`.
+1. **Source-of-truth mapping.** Configure `docs.normative`, then work
+   `normative.uncovered`: every section of every normative document becomes a
+   component requirement or a reviewed attestation. Prove each requirement
+   with implementation evidence, or leave it `REQUIREMENT_UNVERIFIED` for a
+   human. For other major claims, record which of the four inventories
+   supports them; anything supported by none goes to `reviewedAmbiguity`.
 2. **Contradiction detection.** Work `contradictions` and
    `documentationContradictions`. Each one needs a human decision: fix the
    documentation, fix the code, or record an authority rule saying which class
@@ -152,7 +216,11 @@ Then, in order:
    from a human everywhere else.
 7. **Catalog proposal.** `scaffold` lists what it would write.
 8. **Migration.** `scaffold --write`, then review every generated file.
-9. **Validation.** `validate` → `compile` → `check`.
+9. **Validation.** `validate` → `compile` → `check --strict`. The strict gate
+   fails on every warning not accepted with pinned evidence, so a migration
+   cannot finish with an unreviewed normative section or an unproven
+   requirement. A known gap is accepted explicitly (`warningAcceptances`) and
+   stays `UNRESOLVED` in the audit.
 
 ### Do not trust the documentation
 

package/docs/ci/github-actions.yml

@@ -21,7 +21,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.0.0
+        #   github:lbframe/agent-doc-system#v1.1.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-doc-system",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Portable documentation and software-catalog system with an explicit authority model, for AI coding agents",
   "keywords": [

package/schemas/common.schema.json

@@ -66,6 +66,46 @@
         }
       }
     },
+    "normativeCitation": {
+      "description": "One section of a configured normative document, pinned by the digest it had when it was reviewed. `agentdoc audit` lists every section with its current digest.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "section", "sha256"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repoPath" },
+        "section": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S+$" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "requirementKey": { "type": "string", "maxLength": 80, "pattern": "^requirement\\.[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "requirementValue": { "type": "string", "maxLength": 80, "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+    "requirement": {
+      "description": "An implementation obligation a normative document places on this component. It is an AUTHORED fact that must be corroborated by implementation evidence on the same key; it never stands on its own word.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "key", "value", "source"],
+      "properties": {
+        "id": { "$ref": "#/$defs/name" },
+        "key": { "$ref": "#/$defs/requirementKey" },
+        "value": { "$ref": "#/$defs/requirementValue" },
+        "source": { "$ref": "#/$defs/normativeCitation" },
+        "satisfiedBy": {
+          "description": "Adapters able to derive the implementation side of this requirement. Named so a missing extractor is reported as such instead of as silence.",
+          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+        },
+        "expects": {
+          "description": "What an adapter in satisfiedBy must find for the requirement to be provided: a host path installed, or a service managed. Without it an adapter has nothing deterministic to compare.",
+          "type": "object",
+          "additionalProperties": false,
+          "oneOf": [{ "required": ["installs"] }, { "required": ["service"] }],
+          "properties": {
+            "installs": { "type": "string", "maxLength": 400, "pattern": "^/[^\\s{}]*[^\\s{}/]$" },
+            "service": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9@._-]+$" }
+          }
+        }
+      }
+    },
     "warningAcceptance": {
       "type": "object",
       "additionalProperties": false,

package/schemas/component.schema.json

@@ -27,7 +27,11 @@
           "description": "Published artifacts or remotes this component is consumed through.",
           "items": { "$ref": "common.json#/$defs/repoPath" }
         },
-        "context": { "$ref": "common.json#/$defs/context" }
+        "context": { "$ref": "common.json#/$defs/context" },
+        "requirements": {
+          "type": "array", "minItems": 1, "maxItems": 64,
+          "items": { "$ref": "common.json#/$defs/requirement" }
+        }
       },
       "oneOf": [
         { "required": ["system"], "not": { "anyOf": [{ "required": ["domain"] }, { "required": ["placementRationale"] }] } },

package/schemas/config.schema.json

@@ -358,7 +358,8 @@
               "capability",
               "component-placement",
               "event-producer",
-              "event-consumer"
+              "event-consumer",
+              "requirement-satisfaction"
             ]
           },
           "subject": {
@@ -416,6 +417,12 @@
             "minLength": 1,
             "maxLength": 200
           },
+          "key": {
+            "$ref": "common.json#/$defs/requirementKey"
+          },
+          "value": {
+            "$ref": "common.json#/$defs/requirementValue"
+          },
           "reason": {
             "$ref": "common.json#/$defs/rationale"
           },
@@ -633,6 +640,59 @@
                 ]
               }
             }
+          },
+          {
+            "if": {
+              "properties": {
+                "fact": {
+                  "const": "requirement-satisfaction"
+                }
+              },
+              "required": [
+                "fact"
+              ]
+            },
+            "then": {
+              "required": [
+                "key",
+                "value"
+              ],
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "target"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "transport"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "role"
+                    ]
+                  }
+                ]
+              }
+            },
+            "else": {
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "key"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "value"
+                    ]
+                  }
+                ]
+              }
+            }
           }
         ]
       }
@@ -644,6 +704,51 @@
         "$ref": "common.json#/$defs/warningAcceptance"
       }
     },
+    "normativeCoverage": {
+      "description": "Reviewed attestations that a normative section carries no implementation obligation. Pinned by the section digest; a changed section invalidates its attestation and forces a fresh review.",
+      "type": "array",
+      "maxItems": 2048,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "section",
+          "sha256",
+          "disposition",
+          "reason",
+          "reviewWhen"
+        ],
+        "properties": {
+          "path": {
+            "$ref": "common.json#/$defs/repoPath"
+          },
+          "section": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200,
+            "pattern": "^\\S+$"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "disposition": {
+            "enum": [
+              "no-implementation-obligation",
+              "informative"
+            ]
+          },
+          "reason": {
+            "$ref": "common.json#/$defs/rationale"
+          },
+          "reviewWhen": {
+            "type": "string",
+            "minLength": 12
+          }
+        }
+      }
+    },
     "output": {
       "type": "object",
       "additionalProperties": false,
@@ -678,6 +783,17 @@
         },
         "runbookDir": {
           "$ref": "common.json#/$defs/repoPath"
+        },
+        "normative": {
+          "description": "Globs of normative documents (specifications, technical profiles). Every level-2 section of a matched Markdown document must be cited by a component requirement or attested in normativeCoverage; otherwise AGENTDOC_NORMATIVE_UNCOVERED.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
         }
       }
     }

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

@@ -96,7 +96,11 @@ not work around it: run `agentdoc compile`, review the diff, commit the graph.
 - **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.
+  someone once believed. The audit flags only a narrow set of contradictions
+  automatically (negated components, port claims); it does not read prose for
+  meaning. Obligations in specifications are checked only once declared:
+  configure `docs.normative`, turn every section into a component requirement
+  or a reviewed attestation, and finish with `agentdoc check --strict`.
 
 ## Deeper references
 

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

@@ -5,13 +5,18 @@ 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.
+Exit codes: `0` ok, `1` failure, `2` usage. Flags are declared per command:
+an unknown or misspelled flag is a usage error (`2`), with a suggestion when
+one is close — it is never silently ignored, so `check --strcit` cannot pass
+for `check --strict`. `agentdoc <command> --help` lists exactly what a command
+accepts.
 
 ## Meta
 
 ```bash
 agentdoc --version          # installed version
-agentdoc --help             # command list (also: agentdoc <command> --help)
+agentdoc --help             # command list
+agentdoc <command> --help   # every flag of one command (also: agentdoc help <command>)
 agentdoc doctor             # machine check: is this CLI install healthy
 agentdoc doctor --project   # the same, plus the current project's catalog health
 ```
@@ -42,13 +47,16 @@ failures as part of its output.
 ```bash
 agentdoc validate                       # sources + schemas + semantic checks
 agentdoc compile [--require-clean]      # deterministic graph build, atomic write
-agentdoc check [--require-clean] [--allow-stale-observations]
+agentdoc check [--strict] [--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`.
+with `--require-clean` — catalog inputs that differ from `HEAD`. With
+`--strict` it also fails on every warning not accepted in `warningAcceptances`
+— the gate that ends a MIGRATE (unreviewed normative sections, unproven
+requirements, orphan documents).
 
 ## Query and impact
 

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

@@ -81,8 +81,14 @@ 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`.
+1. **Source-of-truth mapping.** Set `docs.normative` to the specifications and
+   profiles, then empty `normative.uncovered`: each section becomes a
+   `spec.requirements` entry on the component that must fulfil it, or a
+   `normativeCoverage` attestation that it obliges nothing. Prove each
+   requirement (adapter evidence or a `requirement-satisfaction` override);
+   an unproven one stays `REQUIREMENT_UNVERIFIED`. For other major claims,
+   record which inventory supports them; 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.
@@ -91,7 +97,13 @@ Then, in order:
 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.
+8. **Gate.** `validate` → `compile` → `check --strict`, then install CI. Strict
+   fails on any unaccepted warning: an unreviewed section or an unproven
+   requirement cannot ship in a "complete" migration.
+
+**The audit does not read prose for meaning.** It checks only negated
+components and port claims automatically; every other documented obligation is
+caught only if it is declared as a requirement.
 
 **Do not trust existing documentation.** The single most common migration
 failure is copying existing prose into descriptions. If you cannot write a

package/templates/ci.yml

@@ -17,7 +17,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.0.0
+        #   github:lbframe/agent-doc-system#v1.1.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile