@agentskit/doc-bridge 1.7.45 → 1.10.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

@@ -158,6 +158,20 @@ the evidence and requires a new workflow and verification run.
 - 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

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,7 +51,7 @@ 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.
 
@@ -62,7 +67,7 @@ When a report is shared outside its repository, configure `report.privacy: 'anon
 
 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.45",
+  "version": "1.10.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.45",
+  "version": "1.10.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",
@@ -74,11 +73,25 @@
     "access": "public"
   },
   "dependencies": {
+    "@agentskit/harness": "0.11.0",
     "github-slugger": "^2.0.0",
+    "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": "^4.4.3"
+    "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",
@@ -110,27 +123,28 @@
   },
   "devDependencies": {
     "@agentskit/chat": "0.4.1",
-    "@agentskit/core": "1.12.8",
+    "@agentskit/core": "1.12.9",
     "@agentskit/ink": "0.10.9",
-    "@agentskit/react": "0.7.4",
+    "@agentskit/react": "0.8.3",
     "@anthropic-ai/mcpb": "2.1.2",
     "@changesets/cli": "^3.0.1",
     "@lhci/cli": "^0.15.1",
-    "@playwright/test": "1.62.1",
+    "@playwright/test": "1.63.0",
     "@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",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "4.1.11",
     "esbuild": "^0.28.2",
-    "fumadocs-core": "16.15.4",
+    "fumadocs-core": "16.15.10",
     "fumadocs-mdx": "15.4.0",
-    "fumadocs-ui": "16.15.4",
-    "lucide-react": "1.34.0",
-    "next": "16.3.3",
+    "fumadocs-ui": "16.15.10",
+    "lucide-react": "1.45.0",
+    "next": "16.3.5",
     "proxy-agent": "8.0.2",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "tailwindcss": "4.3.3",
     "tsup": "^8.5.0",
     "vitest": "^4.1.11"
@@ -151,6 +165,7 @@
     "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",
@@ -176,9 +191,13 @@
     "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 --test scripts/verification-harness.test.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",

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) {
@@ -43,7 +69,9 @@ for (const file of requiredFiles) {
   }
   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 upstream = await fetchText(url.href)
+  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/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.

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from 'node:child_process'
 import { isAbsolute } from 'node:path'
 
-const VERSION = '1.7.45'
+const VERSION = '1.10.0'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]