@agentskit/doc-bridge 1.7.44 → 1.9.0

package/docs/study/round-1-instrumentation-plan-v1.md

@@ -0,0 +1,39 @@
+---
+title: Round 1 instrumentation plan v1
+description: Acceptance contract for configurable study cost attribution and independent adjudication.
+---
+
+# Round 1 instrumentation plan v1
+
+## Objective
+
+Make controlled study results auditable without bundling a local model runtime: record configured USD attribution when usage is available and support a separate adjudicator process that cannot approve its own provider output.
+
+## Acceptance criteria
+
+| ID | Criterion | Evidence |
+| --- | --- | --- |
+| R1-C1 | Provider and adjudicator rates are schema-validated, content-addressed, and use an explicit USD formula. | Focused provider CLI test and current configuration hash. |
+| R1-C2 | The runner records `agentCostUsd` only for labeled provider usage with configured rates; missing data remains missing. | Runner test and metrics output. |
+| R1-C3 | A separate bounded CLI can adjudicate a ledger using only anonymized structured candidate data. | Independent adjudicator test and CLI smoke run. |
+| R1-C4 | Adjudicator timeout, invalid output, unavailable command, and output-limit failures remain `pending`. | Focused failure-path test. |
+| R1-C5 | Token-equivalent and USD measurements remain distinct and auditable by source, run ID, configuration hash, and content hashes. | Ledger schema, metrics report, and verification harness evidence. |
+| R1-C6 | The smoke run against a private consumer repository produces no publication-bound private path, repository content, prompt, or raw response. | Deterministic privacy gate and anonymized output inspection. |
+
+## Deliberate boundary
+
+Round 1 adjudicates the bounded structured candidate record, not raw model prose or private repository contents. This proves the independent process, privacy boundary, cost accounting, and failure behavior. Semantic review of documentation quality and code/documentation contradictions remains a later round because it requires richer evidence and a separately approved evaluation protocol.
+
+## Measurement fields
+
+- `agentCostUsd`: configured-rate USD estimate for the evaluated provider.
+- `adjudicatorCostUsd`: configured-rate USD estimate for the independent adjudicator.
+- `providerTokenCostUnits` and `adjudicatorTokenCostUnits`: provider-reported input plus output tokens.
+- `adjudicatorLatencyMs`: elapsed adjudicator process time.
+- `adjudication.status`, `actor`, `method`, `outcome`, `confidence`, and `reasonCodes`: independent decision provenance.
+
+Rates are experimental configuration inputs, not vendor billing claims. Every result must retain the config hash and run identifier used to produce it.
+
+## Recorded smoke evidence
+
+The private-consumer smoke processed one observation with `--limit 1` and kept the remaining ledger observations unchanged. The anonymized output ledger hash is `3f2c80e6768ffd33a14f38ca8fb9eeb482f4722c9f028ec29adc7d09d54aaef6`; the configuration hash is `7ea4b4496d23c15f93527120927ec46105d8fc46c66114e0c710426f5f417ea8`. The independent adjudicator recorded 150 token-cost units, USD 0.00034 at the configured study rates, and 49 ms latency. The privacy gate scanned the output and found zero forbidden matches.

package/docs/study/round-2-expanded-adjudication-v1.json

@@ -0,0 +1,91 @@
+{
+  "type": "expanded-adjudication-result",
+  "schemaVersion": 1,
+  "round": "round-2-expanded-adjudication-2026-08-31",
+  "sourceLedgerHash": "cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5",
+  "outputLedgerHash": "a89fa316b88eea707347c1b2caae64c6895ce19688a57a7909e15abb51058f20",
+  "configurationHash": "d816148be351fd8dacdf82f204d6694b41e3f3af90ce5f8cae11ced8c99ef37b",
+  "sampleSize": 12,
+  "independentAdjudicationCount": 12,
+  "pendingCount": 0,
+  "coverage": 1,
+  "providerNetwork": true,
+  "adjudicatorModelId": "gpt-5.6-luna",
+  "scenarioCoverage": [
+    "deterministic-doc-bridge",
+    "repository-only"
+  ],
+  "categoryCoverage": [
+    "architecture",
+    "discovery",
+    "documentation",
+    "implementation"
+  ],
+  "repositoryCoverage": [
+    "consumer-01",
+    "consumer-03",
+    "consumer-04",
+    "consumer-05",
+    "consumer-06"
+  ],
+  "inputTokens": 226577,
+  "outputTokens": 3297,
+  "tokenCostUnits": 229874,
+  "configuredCostUsd": 0.302758,
+  "latencyMs": {
+    "min": 8078,
+    "max": 11503,
+    "average": 9841.5,
+    "p95": 11503
+  },
+  "outcomeCounts": {
+    "incomplete": 2,
+    "partial": 5,
+    "blocked": 5
+  },
+  "reasonCodeCounts": {
+    "acceptance-check-blocked": 1,
+    "acceptance-check-failed": 1,
+    "acceptance-check-not-established": 1,
+    "acceptance-check-not-executed": 1,
+    "acceptance-check-not-passed": 2,
+    "acceptance-check-unavailable": 1,
+    "architecture-artifact-not-inspected": 1,
+    "budget-exceeded-does-not-establish-blocked-target": 1,
+    "candidate-outcome-misclassified": 1,
+    "candidate-record-omits-discovery-map": 1,
+    "correct-target-and-evidence": 1,
+    "discovery-evidence-not-validated": 3,
+    "documentation-only-scope": 1,
+    "entrypoint-evidence-present": 1,
+    "entrypoints-and-owners-not-stated": 1,
+    "evidence-content-not-provided": 1,
+    "evidence-identifiers-alone-do-not-prove-correctness": 1,
+    "execution-budget-exceeded": 1,
+    "issue-category-not-provided": 1,
+    "knowledge-gap-evidence-present": 3,
+    "minimal-documentation-only-proposal": 1,
+    "precise-documentation-issue-not-provided": 1,
+    "required-acceptance-check-blocked": 1,
+    "required-acceptance-check-failed": 2,
+    "required-evidence-insufficient": 1,
+    "success-not-supported": 1,
+    "target-document-identified": 3,
+    "target-document-not-identified": 1,
+    "verification-command-blocked": 1,
+    "verification-command-unavailable": 1,
+    "verification-plan-present": 3
+  },
+  "privacy": {
+    "forbiddenMatchCount": 0,
+    "rawRepositoryPathsIncluded": false,
+    "rawRepositoryContentIncluded": false
+  },
+  "limitations": [
+    "The sample is anonymized and bounded; it is not a full-repository evaluation.",
+    "The configured USD rates are experimental study rates, not a vendor invoice.",
+    "Independent adjudication evaluates the bounded candidate record and cannot recover evidence omitted from it."
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "df4a869c9da7354c7fdd6a6ed993f67f9fb16ccb8c2953b8c937328e248701ce"
+}

package/docs/study/round-2-expanded-validation-v1.md

@@ -0,0 +1,58 @@
+---
+title: Round 2 expanded validation v1
+description: Auditable independent adjudication results for an anonymized study sample.
+---
+
+# Round 2 expanded validation v1
+
+## Objective
+
+Measure whether a real, configurable Codex CLI can independently evaluate bounded study observations while preserving provenance, privacy, token accounting, cost attribution, and latency measurements.
+
+## Contract and sample
+
+The run selected 12 observations from the anonymized `phase-9-ab-adjudicated-cost-03` run. The sample covers all four task categories (`architecture`, `discovery`, `documentation`, and `implementation`), both scenarios (`repository-only` and `deterministic-doc-bridge`), and five anonymized consumer identifiers. The adjudicator was the real Codex CLI running `gpt-5.6-luna`, separated from the provider execution being evaluated.
+
+The adapter sent only bounded task metadata and candidate measurements. It did not send repository paths, raw repository content, prompts, credentials, or raw provider responses.
+
+## Results
+
+| Metric | Result |
+| --- | ---: |
+| Sample size | 12 |
+| Independent adjudications | 12 |
+| Adjudication coverage | 100% |
+| Pending adjudications | 0 |
+| Input tokens | 226,577 |
+| Output tokens | 3,297 |
+| Token cost units | 229,874 |
+| Configured study cost | USD 0.302758 |
+| Mean latency | 9,841.5 ms |
+| P95 latency | 11,503 ms |
+
+The independent outcomes were 2 `incomplete`, 5 `partial`, and 5 `blocked`; no observation was promoted to `success`. The dominant signals were missing or unvalidated discovery evidence, unavailable or unexecuted acceptance checks, and insufficiently specific documentation evidence. These are actionable study findings, not a claim that the underlying repositories are defective in every respect.
+
+## Acceptance evidence
+
+| Criterion | Result | Evidence |
+| --- | --- | --- |
+| Real configurable adjudicator executed | Validated | Output ledger hash `a89fa316b88eea707347c1b2caae64c6895ce19688a57a7909e15abb51058f20`; 12 automated decisions. |
+| Coverage and category/scenario representation measured | Validated | `round-2-expanded-adjudication-v1.json`. |
+| Token, latency, and configured cost measured | Validated | Per-observation adjudicator measurements and aggregate summary. |
+| Privacy boundary preserved | Validated | `forbiddenMatchCount: 0`; raw paths and content excluded. |
+| Result reproducibility bound to inputs | Validated | Source ledger hash, output ledger hash, configuration hash, and content hash are recorded. |
+| Full-repository semantic quality established | Not analyzed | This bounded sample evaluates candidate records; it does not replace a full documentation/code comparison. |
+
+## Provenance
+
+- Source ledger: `cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5`.
+- Adjudicator configuration: `d816148be351fd8dacdf82f204d6694b41e3f3af90ce5f8cae11ced8c99ef37b`.
+- Summary artifact: `df4a869c9da7354c7fdd6a6ed993f67f9fb16ccb8c2953b8c937328e248701ce`.
+
+## Limitations
+
+- The sample is anonymized and bounded; it is not a full-repository evaluation.
+- The configured USD rates are experimental study rates, not a vendor invoice.
+- The adjudicator can evaluate only evidence present in the bounded candidate record and cannot recover omitted evidence.
+
+The initial batch attempt exposed an invalid strict JSON schema and produced only `pending` results. The schema was corrected to require nullable usage fields, a one-observation CLI smoke passed, and the controlled 12-observation run was repeated successfully. The failed attempt is retained only as an operational limitation, not as quality evidence.

package/docs/study/round-3-evidence-contract-v1.json

@@ -0,0 +1,75 @@
+{
+  "type": "expanded-adjudication-result",
+  "schemaVersion": 1,
+  "round": "round-3-evidence-contract-2026-08-31",
+  "sourceLedgerHash": "cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5",
+  "outputLedgerHash": "3a5191e9bb839da91c7bf8bcfe58ba77e718a381c27e8867243fc7c859167eee",
+  "configurationHash": "1735f10937845e1db35873c27fd38700e8c5a93bbd412884df5bd0b550628ce5",
+  "sampleSize": 12,
+  "independentAdjudicationCount": 12,
+  "pendingCount": 0,
+  "coverage": 1,
+  "providerNetwork": true,
+  "adjudicatorModelId": "gpt-5.6-luna",
+  "scenarioCoverage": ["deterministic-doc-bridge", "repository-only"],
+  "categoryCoverage": ["architecture", "discovery", "documentation", "implementation"],
+  "repositoryCoverage": ["consumer-01", "consumer-03", "consumer-04", "consumer-05", "consumer-06"],
+  "inputTokens": 227535,
+  "outputTokens": 3029,
+  "tokenCostUnits": 230564,
+  "configuredCostUsd": 0.330994,
+  "latencyMs": {"min": 7360, "max": 11643, "average": 9498.08, "p95": 11643},
+  "outcomeCounts": {"success": 1, "incomplete": 2, "blocked": 5, "partial": 4},
+  "reasonCodeCounts": {
+    "acceptance-budget-exceeded": 1,
+    "acceptance-check-failed": 5,
+    "acceptance-check-not-passed": 1,
+    "acceptance-check-passed": 1,
+    "acceptance-check-unexecuted": 4,
+    "ak-docs-command-unavailable": 1,
+    "architecture-artifact-unavailable": 1,
+    "candidate-issue-not-provided": 1,
+    "command-not-found": 1,
+    "discovery-check-not-passed": 1,
+    "evidence-present-but-validation-failed": 1,
+    "evidence-quality-high": 1,
+    "missing-documentation-evidence": 1,
+    "missing-review-limitation": 1,
+    "no-basis-for-success": 1,
+    "not-blocked": 1,
+    "patch-evidence-missing": 1,
+    "proposal-bounded-and-safe": 1,
+    "required-evidence-missing": 4,
+    "required-evidence-present": 3,
+    "required-patch-evidence-missing": 1,
+    "required-verification-plan-evidence-missing": 1,
+    "target-and-gap-identified": 1,
+    "target-document-not-safely-identified": 2,
+    "verification-blocked-by-environment": 1,
+    "verification-check-unexecuted": 1,
+    "verification-plan-evidence-missing": 1,
+    "verification-plan-present-but-runner-evidence-missing": 1
+  },
+  "comparisonToRound2": {
+    "coverageDelta": 0,
+    "inputTokensDelta": 958,
+    "outputTokensDelta": -268,
+    "tokenCostUnitsDelta": 690,
+    "configuredCostUsdDelta": 0.028236,
+    "latencyAverageDeltaMs": -343.42,
+    "latencyP95DeltaMs": 140,
+    "successCountDelta": 1,
+    "partialCountDelta": -1,
+    "incompleteCountDelta": 0,
+    "blockedCountDelta": 0
+  },
+  "privacy": {"forbiddenMatchCount": 0, "rawRepositoryPathsIncluded": false, "rawRepositoryContentIncluded": false},
+  "limitations": [
+    "The same anonymized bounded sample was re-adjudicated; this isolates contract effects but does not establish causality.",
+    "The configured USD rates are experimental study rates, not a vendor invoice.",
+    "A changed model response can affect outcomes; round-3 results are directional until replicated.",
+    "Independent adjudication evaluates the bounded candidate record and cannot recover evidence omitted from it."
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "a75b0bdd23eeb0ba65d25e1ff0c9836922190f78a25f317cc38172266c586e32"
+}

package/docs/study/round-3-evidence-contract-v1.md

@@ -0,0 +1,57 @@
+---
+title: Round 3 evidence contract validation v1
+description: Before-and-after measurement of structured evidence coverage in independent study adjudication.
+---
+
+# Round 3 evidence contract validation v1
+
+## Objective
+
+Improve the study evidence contract so an independent adjudicator can distinguish missing evidence from unexecuted acceptance checks without receiving repository content or paths.
+
+## Change
+
+The adjudicator input now includes a bounded `evidenceCoverage` object with presence for each required evidence identifier, a reference count, and an `acceptanceExecution` object with execution status, observed passed/total counts, and a measurement-presence flag. The provider contract also asks agents to execute declared acceptance checks when available and to emit typed coverage measurements. No raw repository data, credentials, prompts, or provider responses are included.
+
+## Results
+
+The exact 12-observation anonymized sample from round 2 was re-adjudicated with the real Codex CLI (`gpt-5.6-luna`).
+
+| Metric | Round 2 | Round 3 | Change |
+| --- | ---: | ---: | ---: |
+| Independent coverage | 100% | 100% | 0 pp |
+| Success outcomes | 0 | 1 | +1 |
+| Partial outcomes | 5 | 4 | -1 |
+| Incomplete outcomes | 2 | 2 | 0 |
+| Blocked outcomes | 5 | 5 | 0 |
+| Adjudicator input tokens | 226,577 | 227,535 | +958 |
+| Adjudicator output tokens | 3,297 | 3,029 | -268 |
+| Token cost units | 229,874 | 230,564 | +690 |
+| Configured study cost | USD 0.302758 | USD 0.330994 | +USD 0.028236 |
+| Mean latency | 9,841.5 ms | 9,498.08 ms | -343.42 ms |
+| P95 latency | 11,503 ms | 11,643 ms | +140 ms |
+
+The new contract produced clearer reason codes, including `required-evidence-present`, `required-evidence-missing`, and `acceptance-check-unexecuted`. One observation was classified as `success`, but the sample remains inconclusive: five observations stayed blocked and the same sample was re-adjudicated, so model response variance is a confounder.
+
+## Acceptance evidence
+
+| Criterion | Result | Evidence |
+| --- | --- | --- |
+| Evidence coverage is explicit and bounded | Validated | Round-3 adapter input contract and 12 automated adjudications. |
+| Real Codex CLI executed with the new contract | Validated | Output ledger hash `3a5191e9bb839da91c7bf8bcfe58ba77e718a381c27e8867243fc7c859167eee`. |
+| Before/after metrics are auditable | Validated | `round-3-evidence-contract-v1.json` and round-2 summary. |
+| Privacy boundary preserved | Validated | Zero forbidden matches; raw paths and content excluded. |
+| Full semantic documentation quality proven | Not analyzed | The bounded sample measures evidence sufficiency, not full-repository truth. |
+
+## Provenance
+
+- Source ledger: `cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5`.
+- Round-3 configuration: `1735f10937845e1db35873c27fd38700e8c5a93bbd412884df5bd0b550628ce5`.
+- Summary artifact: `a75b0bdd23eeb0ba65d25e1ff0c9836922190f78a25f317cc38172266c586e32`.
+
+## Limitations
+
+- This is a same-sample re-adjudication, not a causal A/B experiment.
+- The configured USD rates are experimental study rates, not a vendor invoice.
+- The adjudicator cannot recover evidence omitted from the candidate record.
+- The next confirmatory round should use a fresh representative sample and test whether the improved contract generalizes.

package/docs/study/round-4-confirmation-v1.json

@@ -0,0 +1,75 @@
+{
+  "type": "expanded-adjudication-result",
+  "schemaVersion": 1,
+  "round": "round-4-confirmation-2026-08-31",
+  "sourceLedgerHash": "cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5",
+  "initialOutputLedgerHash": "1a394924244ba13fb1a0aefa73f81a245b4be3a37d3d9b0af270c498d7268622",
+  "recoveryOutputLedgerHash": "1a2464518ce659d8fdda176a5ab30ef4313fb571c65be20e2416a940bcbfa101",
+  "configurationHash": "80590115a04157a385a6535cdc84d2040955599301ff9ae3b2f5194bc64ca482",
+  "sampleSelection": {"runId": "phase-9-ab-adjudicated-cost-03", "offset": 12, "limit": 12},
+  "recoverySelection": {"offset": 17, "limit": 1},
+  "sampleSize": 12,
+  "independentAdjudicationCount": 12,
+  "pendingCount": 0,
+  "coverage": 1,
+  "providerNetwork": true,
+  "adjudicatorModelId": "gpt-5.6-luna",
+  "scenarioCoverage": ["deterministic-doc-bridge", "repository-only"],
+  "categoryCoverage": ["architecture", "discovery", "documentation", "implementation"],
+  "modelCoverage": ["low-cost-model", "reference-model"],
+  "repositoryCoverage": ["consumer-01", "consumer-02", "consumer-04", "consumer-05", "consumer-06"],
+  "inputTokens": 227799,
+  "outputTokens": 2416,
+  "tokenCostUnits": 230215,
+  "configuredCostUsd": 0.301934,
+  "latencyMs": {"min": 6840, "max": 12474, "average": 9672.67, "p95": 12474},
+  "outcomeCounts": {"incomplete": 3, "blocked": 8, "partial": 1},
+  "reasonCodeCounts": {
+    "acceptance-check-failed": 8,
+    "acceptance-check-result-unverified": 1,
+    "acceptance-check-timed-out": 1,
+    "acceptance-check-unexecuted": 2,
+    "architecture-artifact-unavailable": 1,
+    "architecture-evidence-present": 1,
+    "architecture-map-not-generated": 1,
+    "artifact-generation-blocked": 1,
+    "artifact-inspection-blocked-by-eprem": 1,
+    "attention-point-evidence-backed": 1,
+    "candidate-claims-success-without-evidence": 1,
+    "directional-relations-present": 1,
+    "discovery-not-validated": 1,
+    "discovery-unvalidated": 1,
+    "issue-not-precisely-classified": 1,
+    "issue-plausibly-classified-as-redundant": 1,
+    "required-documentation-evidence-not-present": 1,
+    "required-evidence-marked-missing": 1,
+    "required-evidence-missing": 7,
+    "required-review-limitation-not-present": 1,
+    "source-corpus-available": 1,
+    "validation-unavailable": 1
+  },
+  "comparisonToRound3": {
+    "coverageDelta": 0,
+    "inputTokensDelta": 264,
+    "outputTokensDelta": -613,
+    "tokenCostUnitsDelta": -349,
+    "configuredCostUsdDelta": -0.02906,
+    "latencyAverageDeltaMs": 174.59,
+    "latencyP95DeltaMs": 831,
+    "successCountDelta": -1,
+    "partialCountDelta": -3,
+    "incompleteCountDelta": 1,
+    "blockedCountDelta": 3
+  },
+  "comparisonToRound2": {"coverageDelta": 0, "successCountDelta": 0},
+  "privacy": {"forbiddenMatchCount": 0, "rawRepositoryPathsIncluded": false, "rawRepositoryContentIncluded": false},
+  "limitations": [
+    "The sample is fresh relative to rounds 2 and 3 but remains anonymized and bounded; it is not a full-repository evaluation.",
+    "One observation required an explicit timeout recovery; the initial timeout remains recorded as operational evidence.",
+    "The configured USD rates are experimental study rates, not a vendor invoice.",
+    "Independent adjudication evaluates the bounded candidate record and cannot recover evidence omitted from it.",
+    "The final sample did not demonstrate semantic improvement: no observation reached success."
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "98a56b9c351e08c7b04860ee4da52eabab7654072fdd8f59d419aac0d167b27e"
+}

package/docs/study/round-4-confirmation-v1.md

@@ -0,0 +1,55 @@
+---
+title: Round 4 final confirmation v1
+description: Final fresh-sample confirmation of the evidence contract and study limitations.
+---
+
+# Round 4 final confirmation v1
+
+## Objective
+
+Test whether the round-3 evidence contract generalizes to a fresh representative anonymized sample, with the real configurable Codex CLI adjudicator and auditable operational measurements.
+
+## Sample and recovery
+
+The run selected 12 records at offset 12 from `phase-9-ab-adjudicated-cost-03`, avoiding the 12 records used in rounds 2 and 3. The sample covered all four task categories, both controlled scenarios, both configured models, and five anonymized consumers. One architecture observation timed out and was retried in isolation at offset 17; the initial timeout remains recorded and is not counted as a successful decision.
+
+## Final result
+
+| Metric | Result |
+| --- | ---: |
+| Sample size | 12 |
+| Independent adjudications | 12 |
+| Final coverage | 100% |
+| Input tokens | 227,799 |
+| Output tokens | 2,416 |
+| Token cost units | 230,215 |
+| Configured study cost | USD 0.301934 |
+| Mean latency | 9,672.67 ms |
+| P95 latency | 12,474 ms |
+| `success` outcomes | 0 |
+| `partial` outcomes | 1 |
+| `incomplete` outcomes | 3 |
+| `blocked` outcomes | 8 |
+
+The final result is `inconclusive` for semantic improvement. The round-3 contract improved the structure of the adjudicator's explanations, but this fresh sample produced no successful outcome. The dominant issues were failed or unexecuted acceptance checks, missing required evidence, unavailable architecture artifacts, and unavailable validation commands. The evidence contract is therefore useful for diagnosis and measurement, but not sufficient by itself to establish documentation quality or delivery correctness.
+
+## Acceptance evidence
+
+| Criterion | Result | Evidence |
+| --- | --- | --- |
+| Fresh sample was selected deterministically | Validated | Selection `offset: 12`, `limit: 12`; recovery `offset: 17`, `limit: 1`. |
+| Real Codex adjudicator executed | Validated | Initial and recovery ledger hashes recorded in `round-4-confirmation-v1.json`. |
+| Coverage, tokens, latency, cost, and outcomes measured | Validated | Summary artifact with per-run aggregate values and round-3 deltas. |
+| Timeout recovery is explicit and auditable | Validated | Initial output and recovery output hashes are both recorded. |
+| Privacy and reproducibility boundaries hold | Validated | Zero forbidden matches; source/config/output hashes recorded; no raw paths or content published. |
+| Semantic documentation quality is proven | Not analyzed | The bounded candidate-record study cannot establish full-repository truth. |
+
+## Study conclusion
+
+Across four rounds, Doc Bridge now has a reproducible measurement path for bounded evidence coverage, provider/adjudicator tokens, configured cost, latency, privacy, and failure recovery. The study does not support a claim that the evidence-contract change improves semantic correctness. A stronger claim requires a larger fresh sample, executable repository acceptance checks, richer validated evidence artifacts, and an independently approved semantic review protocol.
+
+## Provenance
+
+- Source ledger: `cc3eb8a816f961b4a4d8fdefd96365e6b89f3fd7d5aad287c3c5cc79a80ed0f5`.
+- Round-4 configuration: `80590115a04157a385a6535cdc84d2040955599301ff9ae3b2f5194bc64ca482`.
+- Summary artifact: `98a56b9c351e08c7b04860ee4da52eabab7654072fdd8f59d419aac0d167b27e`.

package/docs/study/run-plan-v1.json

@@ -0,0 +1,33 @@
+{
+  "type": "controlled-study-run-plan",
+  "schemaVersion": 1,
+  "planVersion": "v1",
+  "protocolVersion": "v1",
+  "protocolHash": "7a56ae4da91ae56fb8b4b7e506adce525ab6fcb637d635cafb7091c2bd437adf",
+  "taskSuiteHash": "d7810828bce3c6616f00897fd7c92dfa4ecdf12e549923795cd95cc81a2b0029",
+  "sourceRevisionHash": "e74d5608daa1b6c7b3c44628f6976a0b0ca522f9aa61ba9b24b7545bf295002e",
+  "configurationHash": "f94d74f17dfcd00f3bcd8b972caf48371158d29244afb2e5358613736429650a",
+  "docBridgeVersion": "1.7.45",
+  "models": [
+    { "id": "low-cost-model", "role": "low-cost", "provider": "codex", "model": "gpt-5.6-sol", "version": "codex-cli-0.149.0", "parametersHash": "6dc5481139cc4fc6960a38ffd4c7e68605108d0d3eac9ac3c269c92703200273", "contextLimit": 272000, "toolConfigurationHash": "a08b38a4fa7e559811713cabc2e2f62cb05ef266d406dcb38cf46be627417e20", "promptContractHash": "5ba19f0e4ea57c4206d2965a55fc1bbd081348a8ccf89c86ff64a81df93bf98b" },
+    { "id": "reference-model", "role": "reference", "provider": "codex", "model": "gpt-5.6-luna", "version": "codex-cli-0.149.0", "parametersHash": "785593a535c713ae8015defb031047fb9ae55926ec4ac0cb0cafcdaa5cba1e30", "contextLimit": 272000, "toolConfigurationHash": "d2fe8bbf1fa6add2b357c4a199a37224c03bbe4edf29901ff45ae0ef8ee99366", "promptContractHash": "5ba19f0e4ea57c4206d2965a55fc1bbd081348a8ccf89c86ff64a81df93bf98b" }
+  ],
+  "scenarios": [
+    { "id": "repository-only", "network": false },
+    { "id": "deterministic-doc-bridge", "network": false },
+    { "id": "registry-assisted", "agentId": "ecosystem-doc-bridge-corpus-scanner", "agentVersion": "v1.0.0", "network": false }
+  ],
+  "taskIds": [
+    "consumer-01-discovery", "consumer-01-architecture", "consumer-01-documentation", "consumer-01-implementation",
+    "consumer-02-discovery", "consumer-02-architecture", "consumer-02-documentation", "consumer-02-implementation",
+    "consumer-03-discovery", "consumer-03-architecture", "consumer-03-documentation", "consumer-03-implementation",
+    "consumer-04-discovery", "consumer-04-architecture", "consumer-04-documentation", "consumer-04-implementation",
+    "consumer-05-discovery", "consumer-05-architecture", "consumer-05-documentation", "consumer-05-implementation",
+    "consumer-06-discovery", "consumer-06-architecture", "consumer-06-documentation", "consumer-06-implementation"
+  ],
+  "sampling": { "strategy": "balanced-task-strata", "sampleSize": 24 },
+  "budget": { "maxTokens": 400000, "maxRuntimeMs": 180000, "maxOutputBytes": 256000, "maxAttempts": 1 },
+  "runId": "phase-7-canonical-metrics-01",
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "29e95cc2d8fa7f3e6a789884943f9d2cf20896ddb5405196b5ae869e87577d28"
+}

package/docs/study/semantic-adjudication-cycle-8.md

@@ -0,0 +1,20 @@
+# Cycle 8 — Bounded semantic adjudication
+
+Run evidence: `.codex/verification-0.28-round28/semantic-adjudication/`.
+
+Hypothesis: published metadata, CI configuration, and the deterministic README gate can distinguish a real contradiction from a local unreleased version, substantiate a CI claim, and expose remaining deterministic gaps without automatic documentation edits.
+
+Budget: local read-only inspection, one npm metadata lookup, one deterministic README gate, no provider calls, no automatic documentation edits, and no external tracking mutation.
+
+- [x] **1. Freeze the adjudication scope and keep it read-only.**
+- [x] **2. Load the prior two-model semantic review as candidate evidence.**
+- [x] **3. Resolve the published npm version from package metadata.**
+- [x] **4. Compare the published version with the README claim.**
+- [x] **5. Classify the local `package.json` version separately from the published version.**
+- [x] **6. Verify the README gate is configured on the pull-request workflow.**
+- [x] **7. Re-run the deterministic README gate and preserve its failure output.**
+- [x] **8. Reproduce the onboarding overlap candidate.**
+- [x] **9. Record adjudications without silently editing documentation.**
+- [x] **10. Preserve the open source-hash gap and define the next corrective action.**
+
+Decision: bounded adjudication completed. The published version and README agree (`1.7.45`); the local `package.json` version (`1.8.0`) is not a contradiction by itself. The CI claim is substantiated by `.github/workflows/ci.yml`. The README gate exposes three stale generated source hashes, which is the next deterministic correction. The onboarding overlap remains a low-severity documentation-ownership candidate. No automatic documentation edit is authorized.