agent-doc-system 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -9,6 +9,25 @@ refused by the next with `AGENTDOC_COMPILER_MISMATCH` until it is recompiled.
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-11-14
+
+### Fixed
+
+- Explicit context documents now have content provenance, allowing task-context delivery to verify linked files outside conventional document locations.
+- Component, System and Resource context lists now accept more than twelve documentation, constraint or runbook references. Projects no longer need to omit applicable decisions or reclassify them to satisfy schema validation. Markdown display budgets remain adjustable and report truncation; task context delivery uses token budgets and continuation.
+- Agent guidance distinguishes document-path navigation from content delivery and documents the current component-level applicability boundary.
+
+Recompile committed graphs after upgrading, as the compiler version is now 1.5.2 and the schema input hash changes.
+
+## [1.5.1] - 2026-11-13
+
+### Fixed
+
+- Evaluation and optimization entrypoints now execute when invoked through a symbolic link, including installed paths under macOS temporary-directory aliases. Previously they could exit successfully without producing output.
+- CI now exercises agent evaluation and package installation on macOS in addition to the Node 22/24/26 Linux matrix.
+
+Recompile committed graphs after upgrading, as the compiler version is now 1.5.1.
+
 ## [1.5.0] - 2026-11-13
 
 ### Added
@@ -440,7 +459,9 @@ First public release.
   for project health.
 - An Agent Skill under `skills/agent-doc-system/`.
 
-[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/lbframe/agent-doc-system/compare/v1.5.2...HEAD
+[1.5.2]: https://github.com/lbframe/agent-doc-system/compare/v1.5.1...v1.5.2
+[1.5.1]: https://github.com/lbframe/agent-doc-system/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/lbframe/agent-doc-system/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/lbframe/agent-doc-system/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/lbframe/agent-doc-system/compare/v1.2.0...v1.3.0

package/core/compile.mjs

@@ -527,6 +527,16 @@ function compileOnce(root, opts = {}) {
     prov.add("declared", e.file, "descriptor-reader", subjects);
   }
 
+  // Pin linked document contents as well as the descriptor that declares the
+  // link. Task-context delivery verifies these bytes against graph provenance.
+  for (const e of sources.entities) {
+    for (const [kind, paths] of Object.entries(e.doc.spec?.context || {})) {
+      for (const p of paths) {
+        prov.add("observed", p, "context-document-reader", ["entf:" + e.ref + ":/spec/context/" + kind]);
+      }
+    }
+  }
+
   // ── contract adapters run once, after every unit is known ───────────────
   const contractOut = [];
   ctx.addContract = (rec) => {

package/core/graph.mjs

@@ -9,7 +9,7 @@ import { assertDeterministic, structuralProjection } from "./determinism.mjs";
 import { sha256Hex } from "./fsx.mjs";
 
 export const COMPILER_NAME = "agentdoc-compiler";
-export const COMPILER_VERSION = "1.5.0";
+export const COMPILER_VERSION = "1.5.2";
 export const GRAPH_SCHEMA_VERSION = "agentdoc.dev/graph/v1";
 
 // Resolve symbolic provenance subjects to RFC 6901 pointers into the graph.

package/docs/CI.md

@@ -20,7 +20,7 @@ jobs:
         with: { fetch-depth: 0 }
       - uses: actions/setup-node@v4
         with: { node-version: '24' }
-      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.5.0 —
+      # Pin a tag for reproducibility, e.g. github:lbframe/agent-doc-system#v1.5.2 —
       # a compiler upgrade intentionally invalidates every committed graph.
       - run: npm install -g github:lbframe/agent-doc-system
       - run: agentdoc validate

package/docs/CONTEXT.md

@@ -8,6 +8,12 @@ printf '%s\n' '{"task":"Change the engine API","paths":["crates/engine"],"intent
 
 Intents are `implement` (default), `change-contract`, `debug-runtime` and `review`. The first implementation conservatively retains the same obligation closure across intents. The packet contains typed, versioned records, evidence references, selected checks, analysis limitations and stale runtime observation IDs. It does not infer that unsupported or dynamic dependencies are absent.
 
+Document selection currently follows component ownership and impact, rather
+than file-specific document filters. All declared references remain eligible,
+including lists longer than twelve entries; the token budget governs delivery,
+not what the repository may declare. Constraints are critical obligations;
+ordinary documentation and runbooks remain available through continuation.
+
 ## Budget and continuation
 
 The exact serialized output, including its final newline, metadata and continuation, is counted using pinned `js-tiktoken@1.0.21`. Select `o200k_base` or `cl100k_base` explicitly to match the encoding used by your model; AgentDoc does not guess model tokenization. The supported budget is 256–1,000,000 tokens. A budget too small for the envelope or next indivisible record fails with `AGENTDOC_CONTEXT_BUDGET` and must be increased.

package/docs/QUERY.md

@@ -170,6 +170,19 @@ documentation, constraints and runbooks appear under `docs`, `CONSTRAINTS` and
 `runbooks`, respectively. Components also include conventional files discovered
 in their source root. API and Domain schemas do not allow `context`.
 
+Authored `context.docs`, `context.constraints` and `context.runbooks` have no
+item-count cap. Declare every applicable reference; do not move a document to
+another category or split a component to fit a display budget. Choose the
+category by its role: supporting documentation, active obligations, or operating
+procedures. An ADR may be the source of an active obligation.
+
+These links are component-level context, not file-specific applicability.
+Linking a document to one component does not establish coverage of every other
+component that needs it. `query` returns document paths; use `prepare` and
+`expand` when the consumer needs their contents with a token budget and explicit
+continuation (see [CONTEXT.md](CONTEXT.md)). Neither delivery nor a link proves
+that an obligation has been understood or implemented.
+
 Markdown docs and runbooks default to 12 paths each. Constraints are uncapped by
 default so critical routing context is preserved. Set an explicit cap with, for
 example, `--budget docs=1,constraints=5,runbooks=1`. A shortened line ends with

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

package/evals/agent/optimize.mjs

@@ -43,6 +43,6 @@ export async function optimize(config){
   const decision=validation.stopped?{adopt:false,reason:validation.stopped}:selectCandidate(validation.attempts.filter(x=>x.condition==='reference'),validation.attempts.filter(x=>x.condition===candidate),config.criteria);
   return {schemaVersion:'agentdoc.eval.optimization/v1',status:decision.adopt?'candidate-selected':'inconclusive',candidate,decision,spent,development,validation,publication:'not-performed',finalTest:'required-on-independent-tasks-before-production-performance-claims'};
 }
-if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+if(process.argv[1]&&fs.existsSync(process.argv[1])&&fs.realpathSync(process.argv[1])===fs.realpathSync(fileURLToPath(import.meta.url))){
   try{const config=JSON.parse(fs.readFileSync(process.argv[2],'utf8'));const report=await optimize(config);const text=JSON.stringify(report,null,2)+'\n';if(process.argv[3])fs.writeFileSync(process.argv[3],text);else process.stdout.write(text);if(report.status!=='candidate-selected')process.exitCode=1;}catch(e){console.error(e.message);process.exitCode=2;}
 }

package/evals/agent/run.mjs

@@ -150,7 +150,7 @@ export async function campaign(config){
   return {schemaVersion:'agentdoc.eval.campaign/v1',runtime:{node:process.version,runnerHash:RUNNER_HASH,corpusHash:createHash('sha256').update(JSON.stringify(tasks.map(t=>({id:t.id,pin:t.fixtureHash,cases:t.cases})))).digest('hex'),driverFiles:Object.fromEntries(config.driver.filter(p=>path.isAbsolute(p)&&fs.existsSync(p)&&fs.statSync(p).isFile()).map(p=>[p,createHash('sha256').update(fs.readFileSync(p)).digest('hex')]))},config,attempts,summary:summarize(attempts),conditions:Object.fromEntries(Object.keys(conditions).map(k=>[k,summarize(attempts.filter(x=>x.condition===k))]))};
 }
 
-if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+if(process.argv[1]&&fs.existsSync(process.argv[1])&&fs.realpathSync(process.argv[1])===fs.realpathSync(fileURLToPath(import.meta.url))){
   try{
     if(process.argv.includes('--list'))process.stdout.write(JSON.stringify(tasks.map(t=>({...publicTask(t),family:t.family,split:t.split})),null,2)+'\n');
     else{

package/package.json

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

package/schemas/common.schema.json

@@ -125,15 +125,15 @@
       "additionalProperties": false,
       "properties": {
         "docs": {
-          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "type": "array", "minItems": 1, "uniqueItems": true,
           "items": { "$ref": "#/$defs/repoPath" }
         },
         "constraints": {
-          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "type": "array", "minItems": 1, "uniqueItems": true,
           "items": { "$ref": "#/$defs/repoPath" }
         },
         "runbooks": {
-          "type": "array", "minItems": 1, "maxItems": 12, "uniqueItems": true,
+          "type": "array", "minItems": 1, "uniqueItems": true,
           "items": { "$ref": "#/$defs/repoPath" }
         }
       }

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

@@ -59,13 +59,20 @@ another. If the graph reports a conflict or an unresolved fact, say so.
 | 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>` |
+| QUERY | navigate a path or entity | `agentdoc query <path-or-ref>` |
+| TASK CONTEXT | receive document contents for a change | `agentdoc prepare` → `expand` → `refresh` |
 | 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).
 
+`query` returns document paths, not their contents. Open the applicable files
+and resolve any reported truncation, or use the task context protocol below to
+receive their contents under a token budget. Context lists have no declaration
+count cap: preserve every applicable reference and classify by role, never by
+remaining capacity. A link or a delivered record is not proof of implementation.
+
 ## The normal loop
 
 ```bash

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