agent-doc-system 1.3.0 → 1.5.0

package/schemas/context.schema.json

@@ -0,0 +1,222 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "agentdoc.dev/context/v1"
+    },
+    "packet": {
+      "type": "string"
+    },
+    "snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "inputHash": {
+          "type": "string"
+        },
+        "compiler": {
+          "type": "object"
+        },
+        "graphHash": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "inputHash",
+        "compiler",
+        "graphHash"
+      ]
+    },
+    "task": {
+      "type": "string"
+    },
+    "intent": {
+      "enum": [
+        "implement",
+        "change-contract",
+        "debug-runtime",
+        "review"
+      ]
+    },
+    "scope": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "unmatched": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "limitations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "staleObservations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "unmatched",
+        "limitations",
+        "staleObservations"
+      ]
+    },
+    "records": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "subject": {
+            "type": "string"
+          },
+          "key": {
+            "type": "string"
+          },
+          "value": {},
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "critical": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id",
+          "version",
+          "kind",
+          "subject",
+          "key",
+          "value",
+          "evidence",
+          "critical"
+        ]
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "offset": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "omitted": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "criticalOmitted": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "partial": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "offset",
+        "total",
+        "omitted",
+        "criticalOmitted",
+        "partial"
+      ]
+    },
+    "continuation": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "packet": {
+              "type": "string"
+            },
+            "offset": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "required": [
+            "packet",
+            "offset"
+          ]
+        }
+      ]
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "used": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "encoding": {
+          "enum": [
+            "o200k_base",
+            "cl100k_base"
+          ]
+        },
+        "tokenizerVersion": {
+          "const": "js-tiktoken@1.0.21"
+        }
+      },
+      "required": [
+        "limit",
+        "used",
+        "encoding",
+        "tokenizerVersion"
+      ]
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "packet",
+    "snapshot",
+    "task",
+    "intent",
+    "scope",
+    "coverage",
+    "records",
+    "delivery",
+    "continuation",
+    "budget"
+  ],
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/context.schema.json"
+}

package/schemas/resource.schema.json

@@ -16,7 +16,15 @@
         "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" }
+        "context": { "$ref": "common.json#/$defs/context" },
+        "migrationPaths": {
+          "description": "Repository directories (or files) holding this logical database's schema migrations, matched as whole-segment path prefixes. Authoritative for change impact: a change under one of them is a change to this Resource, whichever component owns the file. Never a binding: which components use the database is still derived. Only a logical-database may declare them.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": { "$ref": "common.json#/$defs/repoPath" }
+        }
       },
       "oneOf": [
         { "required": ["system"] },

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

@@ -116,3 +116,9 @@ 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.
+
+## Task context protocol (1.5+)
+
+For an onboarded repository, use `agentdoc prepare` with a JSON request on stdin: `{"task":"Describe the intended change","paths":["relative/path"],"budget":{"tokens":4096,"encoding":"o200k_base"}}`. The response describes the current working tree, with no requirement to compile a committed graph first. Select the encoding your model uses; do not assume all models share one tokenizer.
+
+A partial packet is incomplete: follow its continuation through `agentdoc expand`, increasing the budget if a record does not fit. After edits, use `agentdoc refresh` with the previous packet reference and only record IDs still retained in active context. Apply retractions and changed versions. Reset after losing context. Stale observations and unknown execution directories require resolution before treating facts as current or running checks. The complete protocol is in `docs/CONTEXT.md`. Existing query/impact/check workflows remain available.

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.3.0
+        #   github:lbframe/agent-doc-system#v1.5.0
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile