@agentskit/doc-bridge 1.7.44 → 1.9.0

package/docs/study/token-efficiency-protocol-v2.json

@@ -0,0 +1,62 @@
+{
+  "type": "study-protocol",
+  "schemaVersion": 1,
+  "protocolVersion": "token-efficiency-v2",
+  "title": "Token efficiency and correct-action study",
+  "evidenceClasses": ["historical", "controlled"],
+  "repositories": [
+    { "id": "consumer-01", "visibility": "anonymized", "role": "consumer" },
+    { "id": "consumer-02", "visibility": "anonymized", "role": "consumer" },
+    { "id": "consumer-03", "visibility": "anonymized", "role": "consumer" },
+    { "id": "consumer-04", "visibility": "anonymized", "role": "consumer" },
+    { "id": "consumer-05", "visibility": "anonymized", "role": "consumer" },
+    { "id": "consumer-06", "visibility": "anonymized", "role": "consumer" }
+  ],
+  "taskCategories": ["discovery", "architecture", "documentation", "implementation"],
+  "models": [
+    { "id": "low-cost-model", "role": "low-cost", "status": "pinned", "provider": "codex", "model": "gpt-5.6-sol", "version": "codex-cli-0.149.0", "promptContractHash": "20897bddf03704d26f975003bf3ba0d4d8cb38559b382603d7a03cb17b487a7c" },
+    { "id": "reference-model", "role": "reference", "status": "pinned", "provider": "codex", "model": "gpt-5.6-luna", "version": "codex-cli-0.149.0", "promptContractHash": "a0a90a4141327fef23e2d7ef99da79cd44cfe66fa65d7757484e95629b3fe7bd" }
+  ],
+  "scenarios": [
+    { "id": "repository-only", "label": "Repository only", "source": "repository-only", "modelIds": ["low-cost-model", "reference-model"], "requiresHumanApproval": true },
+    { "id": "deterministic-doc-bridge", "label": "Deterministic Doc Bridge", "source": "deterministic-doc-bridge", "modelIds": ["low-cost-model", "reference-model"], "requiresHumanApproval": true },
+    { "id": "registry-assisted", "label": "Doc Bridge plus Registry agent", "source": "doc-bridge-registry-agent", "modelIds": ["low-cost-model", "reference-model"], "registryAgent": "configured", "requiresHumanApproval": true }
+  ],
+  "metrics": [
+    { "id": "tokens-to-correct-action", "family": "discovery", "unit": "tokens", "source": "provider", "required": true, "description": "Provider tokens consumed until a correct evidence-backed action passes applicable acceptance checks." },
+    { "id": "correct-action-rate", "family": "task", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of eligible tasks with correct evidence and passing acceptance checks." },
+    { "id": "context-tokens-p95", "family": "discovery", "unit": "tokens", "source": "provider", "required": true, "description": "P95 provider tokens in Doc Bridge context before task execution." },
+    { "id": "time-to-first-evidence", "family": "discovery", "unit": "milliseconds", "source": "runner", "required": true, "description": "Elapsed time until the first required evidence item is found." },
+    { "id": "time-to-correct-action-p95", "family": "discovery", "unit": "milliseconds", "source": "runner", "required": true, "description": "P95 elapsed time among tasks reaching a correct action." },
+    { "id": "tool-calls-per-correct-action", "family": "operations", "unit": "count", "source": "runner", "required": true, "description": "Tool calls used by tasks that reach a correct action." },
+    { "id": "clarification-rate", "family": "task", "unit": "ratio", "source": "runner", "required": true, "description": "Proportion of tasks requiring human clarification." },
+    { "id": "rework-rate", "family": "task", "unit": "ratio", "source": "runner", "required": true, "description": "Proportion of tasks requiring a corrective second attempt." },
+    { "id": "evidence-precision", "family": "task", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of returned evidence relevant to the declared task." },
+    { "id": "evidence-recall", "family": "task", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of required evidence found by the workflow." },
+    { "id": "safety-rate", "family": "task", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of tasks with no unsafe or unauthorized action." },
+    { "id": "total-cost-per-correct-action", "family": "cost", "unit": "currency", "source": "runner", "required": true, "description": "Doc Bridge, agent, and adjudicator cost for successful tasks." }
+  ],
+  "outcomes": [
+    { "id": "protocol-integrity", "statement": "The token-efficiency protocol is valid, versioned, and reproducible.", "checks": [{ "id": "protocol-validation", "command": "ak-docs study protocol docs/study/token-efficiency-protocol-v2.json --json" }] },
+    { "id": "historical-separation", "statement": "Historical protocol and result artifacts remain unchanged and separately classified.", "checks": [{ "id": "historical-immutability", "command": "git diff --exit-code -- docs/study/protocol-v1.json docs/study/ab-baseline-result-v1.json docs/study/ab-adjudicated-cost-result-v1.json" }] },
+    { "id": "metric-integrity", "statement": "Token methods, missing data, and correct-action nullability remain explicit.", "checks": [{ "id": "metric-contract-tests", "command": "pnpm exec vitest run tests/study-protocol.test.ts" }] },
+    { "id": "privacy", "statement": "Publication-bound study artifacts contain no private repository data or raw agent material.", "checks": [{ "id": "privacy-scan", "command": "pnpm build && node scripts/study-privacy-gate.mjs docs/study" }] },
+    { "id": "documentation-integrity", "statement": "The published study documentation remains type-safe and buildable.", "checks": [{ "id": "docs-typecheck", "command": "pnpm docs:typecheck" }] }
+  ],
+  "budget": { "maxTokensPerTask": 400000, "maxRuntimeMsPerTask": 180000, "maxRuns": 288, "maxNetworkRequests": 0 },
+  "privacy": { "mode": "anonymized", "forbiddenFields": ["repository-content", "paths", "prompts", "credentials", "private-identifiers", "raw-agent-responses"], "publicationRequiresHumanReview": true },
+  "stopping": {
+    "minControlledRounds": 3,
+    "consecutiveNoMaterialImprovementRounds": 3,
+    "targets": [
+      { "metricId": "tokens-to-correct-action", "direction": "decrease", "threshold": 0.25 },
+      { "metricId": "time-to-correct-action-p95", "direction": "decrease", "threshold": 0.2 },
+      { "metricId": "correct-action-rate", "direction": "no-regression", "threshold": 0 },
+      { "metricId": "evidence-precision", "direction": "no-regression", "threshold": 0 },
+      { "metricId": "evidence-recall", "direction": "no-regression", "threshold": 0 },
+      { "metricId": "safety-rate", "direction": "no-regression", "threshold": 0 }
+    ]
+  },
+  "contentHash": "97202235c4dbd556f41fe1aa08663d35b16d516de827aebae73b136bb6a538f6",
+  "contentHashAlgo": "sha256-normalized-v1"
+}

package/docs/study/verification-binding-v1.json

@@ -0,0 +1,27 @@
+{
+  "type": "controlled-study-verification",
+  "schemaVersion": 1,
+  "verificationRunId": "verification-fixture-01",
+  "sourceRevisionHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "protocolHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "configurationHash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+  "baselineHash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+  "artifactHashes": {
+    "metrics": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+    "ledger": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
+  },
+  "privacy": {
+    "mode": "anonymized",
+    "checkedArtifactCount": 2,
+    "forbiddenMatchCount": 0,
+    "publicationReview": "approved"
+  },
+  "budget": {
+    "maxTokens": 1000,
+    "usedTokens": 800,
+    "maxRuntimeMs": 2000,
+    "usedRuntimeMs": 1500
+  },
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "1c94cb0a2b70e18cffc99f4317d772760dfd9f29039009ece86d2031078bb781"
+}

package/docs/validation-cycle-plan.md

@@ -102,6 +102,21 @@ This plan is a validation contract. A green result from one cycle never substitu
 - the known-case fixture matrix has 100% detection of expected findings and 0 unsupported findings;
 - the real target report does not show zero findings merely because reconciliation was disabled.
 
+### Phase 3 — Real-artifact documentation inventory
+
+The first AKOS audit exposed that the repository contains multiple documentation
+surfaces. A single `documentedDocumentCount / documentCount` ratio mixed the 27
+agent-corpus documents with human guides, project files, archives, and
+unclassified Markdown. Doc Bridge now reports deterministic document counts by
+classification and marks `docs-archive` as `archive`; the report highlights the
+agent-corpus ratio separately. This keeps the metric useful without hiding the
+full inventory.
+
+The phase gate is satisfied only when the real AKOS artifact reports the
+classification totals, the agent-corpus numerator/denominator, and evidence for
+the classification rule. A changed source revision or configuration invalidates
+the evidence and requires a new workflow and verification run.
+
 ### Cycle 5 — Registry agent quality
 
 **Purpose:** validate the configured agent from the AgentsKit Registry as an evidence-grounded assistant to discovery and classification.
@@ -143,6 +158,20 @@ This plan is a validation contract. A green result from one cycle never substitu
 - issue/PR tracking is updated only after authorization and includes the exact run ID;
 - task-owned temporary artifacts are cleaned while user-owned or ambiguous artifacts remain untouched;
 - structural decisions are documented in the relevant ADR/RFC;
+
+## Documentation quality audit baseline — 2026-08-29
+
+The first deterministic audit run across the five consumer repositories used the same local Doc Bridge source revision. Repository names are intentionally anonymized in this study artifact; the evidence remains in each repository's local verification state.
+
+| Consumer | Documents | Package coverage | Title rate | Example rate | Exact duplicate groups | Structure gaps | Contradictions | Stale |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| Consumer 01 | 4,098 | 82/83 (98.8%) | 32.4% | 15.0% | 23 | 2,712 | 0 | 0 |
+| Consumer 02 | 1,537 | 26/26 (100%) | 71.2% | 42.0% | 2 | 0 | 0 | 0 |
+| Consumer 03 | 169 | 20/21 (95.2%) | 96.4% | 59.8% | 0 | 1,083 | 0 | 0 |
+| Consumer 04 | 163 | 0/2 (0%) | 98.2% | 58.3% | 0 | 512 | 0 | 0 |
+| Consumer 05 | 416 | 0/1 (0%) | 99.8% | 23.6% | 0 | 5,118 | 0 | 0 |
+
+These numbers are a baseline, not a quality score. The audit reports semantic contradiction, unnecessary content, and generated-document freshness as `not-analyzed` until a configured AgentsKit Registry agent or human review supplies evidence. Future rounds must retain the same metrics and compare source revision, configuration hash, audit hash, and verification run ID.
 - final report states residual risks and the next human action; enterprise readiness is not claimed while any required gate is pending.
 
 ## Initial baseline to collect
@@ -234,3 +263,7 @@ Cycle 7 shipped Doc Bridge `1.7.28` to `agentskit-os` and made the large-report
 - the current verification contract covers the package dogfood target, not the complete Doc Bridge enterprise objective.
 
 The current run is `AWAITING_HUMAN_APPROVAL`, not complete. Discovery, package-level reconciliation, Registry-agent proof, documentation cohesion, export accuracy, CLI execution, and measured efficiency passed. The benchmark baseline was not replaced. After human approval, the next cycle should use these numbers as the comparison point and focus on classifying the remaining 9 production runtime-wiring candidates and improving documentation usefulness rather than report transport performance.
+
+### Phase 2 — Semantic classification measurement
+
+The next cycle adds a small, deterministic labeled benchmark around the real reconciliation function. It covers confirmed, undocumented, stale, not-analyzed, conflicting, and unresolved declarations. The acceptance threshold is exact per-case diagnostic classification with non-empty evidence, plus `1.000` finding precision, `1.000` finding recall, and `1.000` evidence ratio. The AKOS verification contract runs this gate directly against the checked-out Doc Bridge source so a later change cannot silently preserve only the aggregate report counts.

package/docs/verification-harness.md

@@ -5,18 +5,21 @@ description: Fail-closed, evidence-backed verification for humans and agents.
 
 # Verification harness
 
-`ak-verify` is the executable completion gate for work that must be proven, not merely compiled. Harness 1.3 also blocks failed contract outcomes and measured regressions.
+`ak-verify` delegates to the provider-neutral `@agentskit/harness@0.9.0`. It is the executable completion gate for work that must be proven, not merely compiled. The Doc Bridge contract enables YOLO autonomy for intermediate verification, while required UI review and external tracking remain explicit gates.
 
 ```bash
-ak-verify run --config .codex/verification.json --json
+ak-verify plan approved --allow-dirty --config .codex/verification.json --json
+ak-verify start --config .codex/verification.json --json
+ak-verify verify --config .codex/verification.json --json
 ak-verify status --config .codex/verification.json --json
 ak-verify approve <run-id> approved --by human --config .codex/verification.json
 ak-verify authorize <run-id> approved --by human --config .codex/verification.json
-ak-verify baseline replace benchmarks/new.json approved --by human --config .codex/verification.json
 ak-verify clean --periodic --config .codex/verification.json
 ```
 
-The contract is JSON so it works without adding a YAML runtime. It declares the artifact surfaces that apply to the run, executable checks, explicit non-applicable reasons, the verification profile, and tracking policy.
+The contract is JSON so it works without adding a YAML runtime. It declares the artifact surfaces that apply to the run, executable checks, explicit non-applicable reasons, the verification profile, YOLO autonomy, and tracking policy. This repository stores current official-harness artifacts under `.codex/verification-0.9/`; older `.codex/verification/` artifacts are historical and are not reused by the 0.9.0 CLI.
+
+For audit-only work, set `mode: "discovery"`. Checks remain executable and their failures remain in the evidence ledger, but they are non-blocking by default. Mark only the minimum inventory/evidence-integrity checks with `blocking: true` when a failure must prevent advancing to the next audit unit. This keeps discovery complete without treating an observed quality defect as an implementation gate.
 
 ## Global policy and project contract
 
@@ -34,6 +37,8 @@ set of repository-specific checks fits every project.
 
 Before implementation, the human intent and acceptance criteria must be explicit. Every criterion must map to an executable check and its expected evidence. If a criterion is not mapped, the run is `CLARIFYING` or `BLOCKED`; a project may not silently shrink the scope to the checks that are easiest to run.
 
+An explicit human approval of the goal or plan authorizes the intermediate implementation, verification, tracking, and cleanup steps within that same contract. The harness must not repeatedly request approval for those intermediate steps. This approval does not waive evidence: failed, missing, stale, or newly out-of-scope work still blocks completion, and material artifact changes still require the applicable evidence review.
+
 ## States
 
 `CLARIFYING` → `PLANNED` → `VERIFYING` → `AWAITING_HUMAN_APPROVAL` / `AWAITING_AUTHORIZATION` → `COMPLETE`.
@@ -46,19 +51,23 @@ The seven applicability surfaces are `logic`, `cli`, `mcp`, `ui`, `docs`, `endpo
 
 ## Evidence and recovery
 
-Runs live under `.codex/verification/runs/<run-id>/run.json`. The latest pointer is `.codex/verification/latest.json`. Commands are captured with exit code, duration, stdout, stderr, source revision, configuration hash, and input hash. Re-running an unchanged pending or completed run is idempotent; changed source or contract creates a new run.
+Runs live under the configured `stateDir`, currently `.codex/verification-0.9/runs/<run-id>/run.json`. The latest pointer is in that same state directory. Commands are captured with exit code, duration, stdout, stderr, source revision, configuration hash, and input hash. Re-running an unchanged pending or completed run is idempotent; changed source or contract creates a new run.
 
 Checks may emit one final JSON line with `status` set to `passed`, `failed`, or `pending-human-review`. Structured `failed` evidence blocks the run even when the process exits with code 0; structured pending evidence remains explicitly awaiting human approval. This prevents a visual checker from being mistaken for a successful verification merely because it launched.
 
 Visual checks must use a real browser or an explicitly configured equivalent. A passing build is not visual approval. Endpoint, database, CLI, and MCP checks must execute their real artifact when the contract marks that surface as required.
 
+UI checks fail closed unless the check declares the `real-browser` and `screenshot` capabilities and its final structured result contains `capability: "real-browser"`, screenshot artifacts with project-relative paths, SHA-256 hashes and viewports, plus a passing result for every contract outcome mapped to that check. Missing files, stale hashes, placeholder pending results, and unmapped criteria block the run before human approval is available.
+
+Delegated work does not weaken the gate. Subagents receive the parent contract hash, assigned criterion IDs, allowed scope, required capabilities, and expected evidence. Their output remains provisional until the orchestrator reruns this harness against the combined current source revision.
+
 The final evidence ledger must distinguish `validated`, `partially validated`, `not analyzed`, `blocked`, and `not applicable`. Counts such as indexed documents, package presence, or rendered reports do not prove semantic documentation/code agreement, stale-content detection, runtime wiring, or UI behavior.
 
 When a report is shared outside its repository, configure `report.privacy: 'anonymized'`. This is separate from `safety.redactSecrets`: secret redaction does not anonymize project names, paths, identifiers, snippets, or finding messages. The privacy check must inspect the generated HTML and all lazy chunks, not only the configuration.
 
 When `measurement.required` is enabled, the named required check must emit structured evidence with `status: "passed"`, a numeric `metrics` object, a `baselineHash`, and an empty `regressions` array. Missing or regressed measurements block completion. Baselines are explicit, versioned artifacts and are never updated implicitly by a verification run.
 
-Baseline replacement is an explicit, human-intended operation. `baseline replace` copies a JSON baseline into the configured target only when the source and target are inside the project root and appends a hash, actor, intent, and timestamp to `.codex/verification/baseline-audit.jsonl`.
+Baseline replacement is outside the `@agentskit/harness@0.9.0` verification CLI. Doc Bridge study tooling must treat baseline replacement as a separate, explicit, human-authorized operation and record the new artifact hash, actor, intent, and timestamp in the study evidence ledger. A normal verification run never replaces a baseline.
 
 The run JSON exposes `profile`, `profilePolicy`, `applicability`, `exemptions`, `checks`, `evidenceReferences`, `metrics`, `transitions`, `sourceRevision`, `contractHash`, `outputHash`, and the exact `runId`. Approval records are bound to the input, source, contract, and output hashes of that run.
 

package/ecosystem-claims.json

@@ -95,7 +95,7 @@
         },
         {
           "id": "memory-backends",
-          "value": 17,
+          "value": 18,
           "noun": "memory backends",
           "evidence": {
             "type": "repository-derivation",
@@ -169,7 +169,7 @@
       "productId": "code-review",
       "source": {
         "type": "repository",
-        "repo": "AgentsKit-io/code-review-cli"
+        "repo": "AgentsKit-io/code-review"
       },
       "verification": "declared",
       "claims": []

package/ecosystem-upstream.json

@@ -3,7 +3,7 @@
   "repository": "AgentsKit-io/agentskit",
   "ref": "main",
   "files": {
-    "ecosystem.json": "260530c0f998ed18dc311342ffd88e7958bf8a368e681a2aeea24e7ac9888aef",
-    "ecosystem-claims.json": "9921d8dbfbeeff44c9202ebccb08d45297ab026602a3bdd4dc12221b194205f7"
+    "ecosystem.json": "21f28c132685f9984979afc83b66a61310e2bb79666d826662f7e8f234fbf36f",
+    "ecosystem-claims.json": "6e77a801d93e58e6580fe5d69d8899bf8d396bffba367f3a705fa751aea83a06"
   }
 }

package/ecosystem.json

@@ -327,12 +327,12 @@
       "role": "verification",
       "promise": "Run deep, low-noise review with the model already in use.",
       "maturity": "alpha",
-      "repo": "AgentsKit-io/code-review-cli",
+      "repo": "AgentsKit-io/code-review",
       "accent": "#F97316",
       "surfaces": {
-        "home": "https://github.com/AgentsKit-io/code-review-cli",
-        "docs": "https://github.com/AgentsKit-io/code-review-cli#readme",
-        "llms": "https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms.txt",
+        "home": "https://github.com/AgentsKit-io/code-review",
+        "docs": "https://github.com/AgentsKit-io/code-review#readme",
+        "llms": "https://raw.githubusercontent.com/AgentsKit-io/code-review/main/llms.txt",
         "documentation": "repository",
         "chat": "none"
       },

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.7.44",
+  "version": "1.9.0",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {
@@ -87,6 +87,14 @@
     {
       "name": "docbridge.proposals",
       "description": "Create, inspect, approve, and apply human-gated Doc Bridge proposals."
+    },
+    {
+      "name": "knowledge.search",
+      "description": "Rank every indexed entity for a query, optionally by kind, with an explanation and within a token budget."
+    },
+    {
+      "name": "knowledge.lookup",
+      "description": "Return an entity with its neighbours, documents, handoff, open diagnostics and evidence, within a token budget."
     }
   ],
   "tools_generated": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.7.44",
+  "version": "1.9.0",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -25,7 +25,6 @@
     "bin",
     "action.yml",
     "scripts/prepare.mjs",
-    "scripts/verification-harness.mjs",
     "scripts/report-visual-check.mjs",
     "scripts/check-ecosystem-upstream.mjs",
     "ecosystem.json",
@@ -46,51 +45,6 @@
     "src",
     "skills"
   ],
-  "scripts": {
-    "prebuild": "node scripts/sync-version.mjs",
-    "build": "tsup",
-    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
-    "test:watch": "vitest",
-    "coverage": "vitest run --coverage",
-    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
-    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
-    "typecheck": "tsc --noEmit",
-    "smoke:packaged": "node scripts/smoke-packaged.mjs",
-    "smoke:docsites": "node scripts/smoke-docsites.mjs",
-    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
-    "smoke:ollama": "node scripts/smoke-ollama.mjs",
-    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
-    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
-    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
-    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
-    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
-    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
-    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
-    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
-    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
-    "coverage:badge": "node scripts/update-coverage-badge.mjs",
-    "changeset": "changeset",
-    "version-packages": "changeset version && node scripts/sync-version.mjs",
-    "release": "npm run build && npm test && changeset publish",
-    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
-    "prepublishOnly": "npm run build && npm test",
-    "prepare": "node scripts/prepare.mjs",
-    "prepack": "npm run build",
-    "docs:dev": "cd apps/docs && next dev",
-    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
-    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
-    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
-    "docs:e2e": "playwright test",
-    "report:visual": "node scripts/report-visual-check.mjs",
-    "test:verification-harness": "node --test scripts/verification-harness.test.mjs",
-    "docs:lighthouse": "lhci autorun",
-    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
-    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
-    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
-    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
-    "check:readme-standard": "node scripts/check-readme-standard.mjs",
-    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
-  },
   "keywords": [
     "agentskit",
     "documentation",
@@ -119,11 +73,25 @@
     "access": "public"
   },
   "dependencies": {
+    "@agentskit/harness": "0.11.0",
     "github-slugger": "^2.0.0",
-    "mermaid": "^11.16.1",
+    "graphology": "~0.26.0",
+    "graphology-communities-louvain": "~2.0.2",
+    "graphology-dag": "~0.4.1",
+    "graphology-metrics": "~2.4.2",
+    "graphology-shortest-path": "~2.1.0",
+    "knap": "~0.5.1",
+    "mdast-util-to-string": "^4.0.0",
+    "mermaid": "^11.17.2",
     "minimatch": "^10.2.6",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
     "typescript": "^6.0.3",
-    "zod": "^3.24.2"
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.5.4"
   },
   "peerDependencies": {
     "@agentskit/adapters": ">=0.12.0 <1",
@@ -154,30 +122,32 @@
     }
   },
   "devDependencies": {
-    "@agentskit/chat": "0.4.0",
-    "@agentskit/core": "1.12.3",
-    "@agentskit/ink": "0.10.4",
-    "@agentskit/react": "0.7.4",
+    "@agentskit/chat": "0.4.1",
+    "@agentskit/core": "1.12.8",
+    "@agentskit/ink": "0.10.9",
+    "@agentskit/react": "0.8.3",
     "@anthropic-ai/mcpb": "2.1.2",
-    "@changesets/cli": "^2.31.0",
+    "@changesets/cli": "^3.0.1",
     "@lhci/cli": "^0.15.1",
-    "@playwright/test": "1.61.1",
-    "@tailwindcss/postcss": "4.3.2",
-    "@types/node": "^22.15.3",
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "@vitest/coverage-v8": "4.1.10",
-    "esbuild": "^0.28.1",
-    "fumadocs-core": "15.6.5",
-    "fumadocs-mdx": "11.6.4",
-    "fumadocs-ui": "15.6.5",
-    "lucide-react": "0.460.0",
-    "next": "15.5.21",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "tailwindcss": "4.3.2",
+    "@playwright/test": "1.62.1",
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^26.4.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitest/coverage-v8": "4.1.11",
+    "esbuild": "^0.28.2",
+    "fumadocs-core": "16.15.4",
+    "fumadocs-mdx": "15.4.0",
+    "fumadocs-ui": "16.15.4",
+    "lucide-react": "1.38.0",
+    "next": "16.3.3",
+    "proxy-agent": "8.0.2",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tailwindcss": "4.3.3",
     "tsup": "^8.5.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.11"
   },
   "directories": {
     "doc": "docs",
@@ -188,5 +158,52 @@
   "bugs": {
     "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
   },
-  "homepage": "https://doc-bridge.agentskit.io/"
-}
+  "homepage": "https://doc-bridge.agentskit.io/",
+  "scripts": {
+    "prebuild": "node scripts/sync-version.mjs",
+    "build": "tsup",
+    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "bench:retrieval": "node bin/ak-docs.js bench retrieval docs/bench/retrieval-suite-v1.json --baseline docs/bench/retrieval-baseline-v1.json --text",
+    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
+    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
+    "typecheck": "tsc --noEmit",
+    "smoke:packaged": "node scripts/smoke-packaged.mjs",
+    "smoke:docsites": "node scripts/smoke-docsites.mjs",
+    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
+    "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
+    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
+    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
+    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
+    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
+    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
+    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
+    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
+    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
+    "coverage:badge": "node scripts/update-coverage-badge.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-version.mjs",
+    "release": "npm run build && npm test && changeset publish",
+    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
+    "docs:dev": "cd apps/docs && next dev",
+    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
+    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
+    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
+    "docs:freshness": "node scripts/verify-generated-docs.mjs",
+    "docs:semantic-review": "node scripts/run-registry-semantic-review.mjs",
+    "docs:semantic-adjudication": "node scripts/run-semantic-adjudication.mjs",
+    "quality:scorecard": "pnpm build && node scripts/quality-scorecard-eval.mjs",
+    "docs:e2e": "playwright test",
+    "report:visual": "node scripts/report-visual-check.mjs",
+    "test:verification-harness": "node bin/ak-verify.js doctor --config .codex/verification.json --json",
+    "docs:lighthouse": "lhci autorun",
+    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
+    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
+    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
+    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
+    "check:readme-standard": "node scripts/check-readme-standard.mjs",
+    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
+  }
+}

package/scripts/check-ecosystem-upstream.mjs

@@ -6,7 +6,12 @@ import { fileURLToPath } from 'node:url'
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const metadata = JSON.parse(readFileSync(join(root, 'ecosystem-upstream.json'), 'utf8'))
-if (metadata.schemaVersion !== 1 || typeof metadata.repository !== 'string' || typeof metadata.ref !== 'string') {
+if (
+  metadata.schemaVersion !== 1 ||
+  typeof metadata.repository !== 'string' ||
+  !/^[^/]+\/[^/]+$/.test(metadata.repository) ||
+  typeof metadata.ref !== 'string'
+) {
   throw new Error('Invalid ecosystem-upstream.json metadata.')
 }
 
@@ -20,18 +25,39 @@ if (
   throw new Error('Upstream metadata must contain SHA-256 digests for both canonical files.')
 }
 
-const fetchText = async (url) => {
+const fetchText = async (url, apiUrl) => {
   let lastError
-  for (let attempt = 1; attempt <= 2; attempt += 1) {
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
     try {
-      const response = await fetch(url, { signal: AbortSignal.timeout(10_000) })
+      const response = await fetch(url, {
+        headers: { 'user-agent': 'doc-bridge-ecosystem-check' },
+        signal: AbortSignal.timeout(10_000),
+      })
       if (!response.ok) throw new Error(`HTTP ${response.status}`)
       return await response.text()
     } catch (error) {
       lastError = error
     }
   }
-  throw new Error(`Unable to verify ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}`)
+  try {
+    const response = await fetch(apiUrl, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        'user-agent': 'doc-bridge-ecosystem-check',
+      },
+      signal: AbortSignal.timeout(10_000),
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    const payload = await response.json()
+    if (payload?.encoding !== 'base64' || typeof payload.content !== 'string') {
+      throw new Error('GitHub API response did not contain a base64 file.')
+    }
+    return Buffer.from(payload.content.replace(/\s+/g, ''), 'base64').toString('utf8')
+  } catch (error) {
+    const fallback = error instanceof Error ? error.message : String(error)
+    const primary = lastError instanceof Error ? lastError.message : String(lastError)
+    throw new Error(`Unable to verify ${url}: ${primary}; API fallback: ${fallback}`)
+  }
 }
 
 for (const file of requiredFiles) {
@@ -41,8 +67,11 @@ for (const file of requiredFiles) {
   if (localDigest !== expectedDigest) {
     throw new Error(`${file} differs from its recorded upstream SHA-256 digest.`)
   }
-  const url = `https://raw.githubusercontent.com/${metadata.repository}/${metadata.ref}/${file}`
-  const upstream = await fetchText(url)
+  const url = new URL(`https://raw.githubusercontent.com/${metadata.repository}/${metadata.ref}/${file}`)
+  if (url.hostname !== 'raw.githubusercontent.com') throw new Error('Unexpected upstream host.')
+  const apiUrl = new URL(`https://api.github.com/repos/${metadata.repository}/contents/${file}`)
+  apiUrl.searchParams.set('ref', metadata.ref)
+  const upstream = await fetchText(url.href, apiUrl.href)
   if (sha256(upstream) !== expectedDigest || upstream !== local) {
     throw new Error(`${file} is stale against ${metadata.repository}@${metadata.ref}. Sync the canonical snapshot and digest.`)
   }

package/scripts/report-visual-check.mjs

@@ -94,6 +94,12 @@ const inspect = async (frame, width, height) => frame.evaluate(({ width: viewpor
     diagnosticCount: typeof globalThis.__DOC_BRIDGE_DATA__?.diagnosticCount === 'number'
       ? globalThis.__DOC_BRIDGE_DATA__.diagnosticCount
       : Number.parseInt(document.querySelector('#finding-count')?.textContent ?? '', 10) || document.querySelectorAll('.finding').length,
+    actionableCount: typeof globalThis.__DOC_BRIDGE_DATA__?.actionableCount === 'number'
+      ? globalThis.__DOC_BRIDGE_DATA__.actionableCount
+      : Number.parseInt((document.querySelector('#finding-count')?.textContent ?? '').match(/(\d+) actionable findings/)?.[1] ?? '0', 10),
+    confirmedCount: typeof globalThis.__DOC_BRIDGE_DATA__?.confirmedCount === 'number'
+      ? globalThis.__DOC_BRIDGE_DATA__.confirmedCount
+      : Number.parseInt((document.querySelector('#finding-count')?.textContent ?? '').match(/(\d+) confirmed checks/)?.[1] ?? '0', 10),
     unnamedButtonCount: unnamedButtons.length,
     visibleOverflowCount: visibleOverflow.length,
     contrastFailures,
@@ -157,7 +163,8 @@ const exercise = async (frame, result) => {
     if (await load.count()) await load.click()
     else if (result.diagnosticCount > 0 && await frame.locator('.finding-group').count() === 0) throw new Error('finding loader is missing while findings are present')
   }, async () => {
-    if (result.diagnosticCount > 0) {
+    const evidenceView = await frame.locator('body').getAttribute('data-report-view') === 'coverage'
+    if (result.actionableCount > 0 || (evidenceView && result.confirmedCount > 0)) {
       await poll(() => frame.locator('.finding-group').count(), (count) => count > 0, 'finding groups')
     } else if (await frame.locator('.finding-group').count() !== 0) {
       throw new Error('finding groups rendered despite zero findings')
@@ -280,6 +287,16 @@ const result = {
       : 'Automated checks passed; screenshots require human visual review. Re-run with --human-approved only after review.',
 }
 writeFileSync(join(outputDir, 'result.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8')
-console.log(JSON.stringify(result, null, 2))
-console.log(JSON.stringify(result))
+console.log(JSON.stringify({
+  status,
+  capability: result.capability,
+  artifacts: result.artifacts,
+  criteria: result.criteria,
+  reportPath: result.reportPath,
+  outputDir: result.outputDir,
+  viewports: result.viewports,
+  themes: result.themes,
+  failures: result.failures,
+  note: result.note,
+}))
 if (status === 'failed') process.exitCode = 1

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/docs/for-agents/packages/payments.md

@@ -1,3 +1,10 @@
+---
+owner: fixture-maintainers
+lifecycle: active
+sourceOfTruth: skills/doc-bridge-handoff/fixtures/synthetic-repo
+validationPath: pnpm test:portable-skill
+---
+
 # Payments package
 
 This is public synthetic guidance for the portable skill compatibility test.