agent-doc-system 0.0.0-stage → 1.0.0

package/evals/scenarios/koda-05-modify-worker-binding.json

@@ -0,0 +1,25 @@
+{
+  "id": "koda-05",
+  "repository": "koda",
+  "title": "Modify a scheduler worker binding",
+  "touch": [
+    "workers/koda-cron/wrangler.toml"
+  ],
+  "truth": [
+    "component:default/koda-cron",
+    "constraint:workers/koda-cron/CONSTRAINTS.md",
+    "doc:workers/koda-cron/README.md",
+    "observation:production",
+    "conflict:binding.declared",
+    "conflict:binding.kind"
+  ],
+  "critical": [
+    "constraint:workers/koda-cron/CONSTRAINTS.md",
+    "observation:production",
+    "conflict:binding.declared",
+    "conflict:binding.kind"
+  ],
+  "verification": [
+    "verify:turbo run test --filter=@koda/koda-cron"
+  ]
+}

package/evals/scenarios/koda-06-change-cross-component-endpoint.json

@@ -0,0 +1,22 @@
+{
+  "id": "koda-06",
+  "repository": "koda",
+  "title": "Change the canonical teacher ingest contract",
+  "touch": [
+    "contracts/teacher-ingest.openapi.yaml"
+  ],
+  "truth": [
+    "api:default/teacher-ingest-api",
+    "component:default/teacher",
+    "component:default/learning-event-relay",
+    "provides:api:default/teacher-ingest-api",
+    "provider:component:default/teacher"
+  ],
+  "critical": [
+    "provides:api:default/teacher-ingest-api"
+  ],
+  "verification": [
+    "verify:turbo run test --filter=@koda/teacher",
+    "verify:pnpm --filter @koda/teacher test"
+  ]
+}

package/evals/scenarios/koda-07-change-shared-package.json

@@ -0,0 +1,16 @@
+{
+  "id": "koda-07",
+  "repository": "koda",
+  "title": "Change the shared lesson vocabulary package",
+  "touch": [
+    "packages/lesson-canon/src/events.ts"
+  ],
+  "truth": [
+    "component:default/lesson-canon",
+    "component:default/teacher",
+    "component:default/koda-cron",
+    "doc:packages/lesson-canon/README.md"
+  ],
+  "critical": [],
+  "verification": []
+}

package/evals/scenarios/koda-08-change-runtime-cron.json

@@ -0,0 +1,23 @@
+{
+  "id": "koda-08",
+  "repository": "koda",
+  "title": "Change the scheduled trigger expression",
+  "touch": [
+    "workers/koda-cron/wrangler.toml"
+  ],
+  "truth": [
+    "component:default/koda-cron",
+    "component:default/calendar",
+    "conflict:schedule.cron",
+    "observation:production",
+    "constraint:workers/koda-cron/CONSTRAINTS.md"
+  ],
+  "critical": [
+    "conflict:schedule.cron",
+    "observation:production",
+    "constraint:workers/koda-cron/CONSTRAINTS.md"
+  ],
+  "verification": [
+    "verify:turbo run test --filter=@koda/koda-cron"
+  ]
+}

package/evals/scenarios/koda-09-debug-production-mismatch.json

@@ -0,0 +1,26 @@
+{
+  "id": "koda-09",
+  "repository": "koda",
+  "title": "Debug why the nightly digest does not fire in production",
+  "touch": [
+    "workers/koda-cron/src/jobs.ts"
+  ],
+  "truth": [
+    "component:default/koda-cron",
+    "component:default/calendar",
+    "component:default/notifications",
+    "conflict:schedule.cron",
+    "conflict:schedule.target",
+    "observation:production",
+    "constraint:workers/koda-cron/CONSTRAINTS.md"
+  ],
+  "critical": [
+    "conflict:schedule.cron",
+    "conflict:schedule.target",
+    "observation:production",
+    "constraint:workers/koda-cron/CONSTRAINTS.md"
+  ],
+  "verification": [
+    "verify:turbo run test --filter=@koda/koda-cron"
+  ]
+}

package/evals/thresholds.json

@@ -0,0 +1,11 @@
+{
+  "_comment": "PRE-REGISTERED THRESHOLDS. Fixed before any scenario was executed against any repository. Moving a number here to convert a FAIL into a PASS invalidates the evaluation.",
+  "_registered_at": "2026-09-28",
+  "minRecall": 0.9,
+  "minCriticalRecall": 0.95,
+  "minVerificationRecall": 0.8,
+  "minPrecision": 0.75,
+  "maxNoise": 0.6,
+  "minRetrievalReduction": 0.4,
+  "minRecallOverBaseline": 0.9
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "agent-doc-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Portable documentation and software-catalog system with an explicit authority model, for AI coding agents",
+  "keywords": [
+    "agentdoc",
+    "software-catalog",
+    "documentation",
+    "ai-agents",
+    "architecture",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lbframe/agent-doc-system.git"
+  },
+  "homepage": "https://github.com/lbframe/agent-doc-system",
+  "bugs": "https://github.com/lbframe/agent-doc-system/issues",
+  "bin": {
+    "agentdoc": "./bin/agentdoc.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "eval": "node evals/run-all.mjs",
+    "selfcheck": "node bin/agentdoc.mjs doctor",
+    "compare": "python3 scripts/compare-koda.py"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "files": [
+    "adapters",
+    "bin",
+    "core",
+    "docs",
+    "evals/harness.mjs",
+    "evals/scenarios",
+    "evals/thresholds.json",
+    "schemas",
+    "skills",
+    "templates",
+    "INSTALL_FOR_AGENTS.md"
+  ],
+  "license": "MIT"
+}

package/schemas/api.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/api.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "properties": {
+    "apiVersion": {
+      "const": "agentdoc.dev/v1"
+    },
+    "kind": {
+      "const": "API"
+    },
+    "metadata": {
+      "$ref": "common.json#/$defs/metadata"
+    },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "provider",
+        "contract"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "openapi",
+            "asyncapi",
+            "protobuf",
+            "graphql",
+            "oidc",
+            "grpc-json",
+            "graphql-sdl"
+          ]
+        },
+        "provider": {
+          "$ref": "common.json#/$defs/componentRef"
+        },
+        "contract": {
+          "$ref": "#/$defs/contract"
+        },
+        "consumers": {
+          "description": "Optional reviewed consumer list. Discovery-derived consumers win; this is for consumers a deterministic extractor cannot see.",
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "common.json#/$defs/componentRef"
+          }
+        }
+      }
+    },
+    "extensions": {
+      "$ref": "common.json#/$defs/extensions"
+    }
+  },
+  "$defs": {
+    "contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "ref": {
+          "$ref": "common.json#/$defs/repoPath"
+        },
+        "standard": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        "discoveryPath": {
+          "type": "string",
+          "pattern": "^/[^?#\\s]*$"
+        }
+      }
+    }
+  }
+}

package/schemas/common.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/common.json",
+  "$defs": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 280,
+      "pattern": "\\S"
+    },
+    "rationale": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 600,
+      "pattern": "\\S"
+    },
+    "entityRef": {
+      "type": "string",
+      "pattern": "^(domain|system|component|api|resource):[a-z0-9][a-z0-9-]*/[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "componentRef": { "$ref": "#/$defs/entityRef" },
+    "apiRef": { "$ref": "#/$defs/entityRef" },
+    "repoPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300,
+      "pattern": "^[^\\s\\\\][^\\s]*$"
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 40
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "description"],
+      "properties": {
+        "name": { "$ref": "#/$defs/name" },
+        "description": { "$ref": "#/$defs/description" },
+        "labels": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 120 }
+        }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "$ref": "#/$defs/repoPath" },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        }
+      }
+    },
+    "warningAcceptance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "subject", "classification", "reason", "reviewWhen", "observedRefs", "evidence"],
+      "properties": {
+        "code": { "type": "string", "pattern": "^AGENTDOC_[A-Z_]+$" },
+        "subject": { "type": "string", "minLength": 1, "maxLength": 400, "pattern": "^\\S+$" },
+        "classification": { "type": "string", "pattern": "^[A-Z]+(?:_[A-Z]+)*$" },
+        "reason": { "$ref": "#/$defs/rationale" },
+        "reviewWhen": { "$ref": "#/$defs/rationale" },
+        "observedRefs": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/entityRef" } },
+        "evidence": { "$ref": "#/$defs/evidence" }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "docs": {
+          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/repoPath" }
+        },
+        "constraints": {
+          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/repoPath" }
+        },
+        "runbooks": {
+          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "items": { "$ref": "#/$defs/repoPath" }
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Forward-evolution escape hatch. Core validators ignore these keys.",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/component.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentdoc.dev/schema/component.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": { "const": "agentdoc.dev/v1" },
+    "kind": { "const": "Component" },
+    "metadata": { "$ref": "common.json#/$defs/metadata" },
+    "spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "enum": ["service", "worker", "job", "library", "contract-library", "web-app", "static-site", "cli", "infrastructure", "other"]
+        },
+        "system": { "$ref": "common.json#/$defs/name" },
+        "domain": { "$ref": "common.json#/$defs/name" },
+        "placementRationale": { "$ref": "common.json#/$defs/rationale" },
+        "repositories": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "uniqueItems": true,
+          "description": "Published artifacts or remotes this component is consumed through.",
+          "items": { "$ref": "common.json#/$defs/repoPath" }
+        },
+        "context": { "$ref": "common.json#/$defs/context" }
+      },
+      "oneOf": [
+        { "required": ["system"], "not": { "anyOf": [{ "required": ["domain"] }, { "required": ["placementRationale"] }] } },
+        { "required": ["domain"], "not": { "anyOf": [{ "required": ["system"] }, { "required": ["placementRationale"] }] } },
+        { "required": ["placementRationale"], "not": { "anyOf": [{ "required": ["system"] }, { "required": ["domain"] }] } }
+      ]
+    },
+    "extensions": { "$ref": "common.json#/$defs/extensions" }
+  }
+}