@agentskit/doc-bridge 1.7.45 → 1.9.0

package/docs/study/phase4-public-pilot-result-v1.json

@@ -0,0 +1,52 @@
+{
+  "type": "phase4-public-pilot-result",
+  "schemaVersion": 1,
+  "resultVersion": "phase4-public-pilot-result-v1",
+  "status": "pilot-complete",
+  "scope": {
+    "populationCount": 1,
+    "taskCount": 4,
+    "replicatesPerTask": 1,
+    "models": ["low-cost-model", "reference-model"],
+    "scenarios": ["repository-only", "deterministic-doc-bridge"],
+    "plannedObservations": 16,
+    "pilotOnly": true
+  },
+  "run": {
+    "runId": "phase4-public-pilot-04",
+    "planHash": "fdc33d417de30a1aa48cc0711c89d87096bb2ad628b5d43f32046e9d0c16ef6a",
+    "ledgerHash": "1cde4be16c44f15ad28fa9f3d7089aef8f2c9f98d7ba847287f125678718b659",
+    "providerConfigHash": "8b2dfc9ba3456dbbd18689009a72402295addc1b3645ae6aef2ba927778d1b6c",
+    "repositoryConfigHash": "1db7dd10c89e0fb664ad50f3e00544529f682b9828327a9d03684f9528bfea6a"
+  },
+  "execution": {
+    "observations": 16,
+    "completed": 16,
+    "failed": 0,
+    "budgetExceeded": 0,
+    "providerReportedOutcome": { "success": 13, "partial": 2, "incomplete": 1 },
+    "automatedAdjudication": { "success": 7, "partial": 8, "incomplete": 1, "incorrect": 0, "blocked": 0 }
+  },
+  "pairedMetrics": {
+    "pairs": 8,
+    "repositoryOnly": { "providerTokenEquivalentUnits": 648461, "durationP95Ms": 45430 },
+    "deterministicDocBridge": { "providerTokenEquivalentUnits": 628018, "durationP95Ms": 42007 },
+    "providerTokenEquivalentReductionPct": 3.1525,
+    "durationP95ReductionPct": 7.5347,
+    "providerTokenEquivalentDefinition": "Provider-reported input plus output tokens; not currency."
+  },
+  "failedPreparationRuns": [
+    { "runId": "phase4-public-pilot-01", "observations": 6, "reason": "Provider output schema rejected by current Codex CLI because an optional property was not listed as required." },
+    { "runId": "phase4-public-pilot-02", "observations": 1, "reason": "The 40000-token execution budget was below observed provider usage." },
+    { "runId": "phase4-public-pilot-03", "observations": 2, "reason": "The 120000-token execution budget was below observed provider usage for one model/task combination." }
+  ],
+  "limitations": [
+    "This is a one-population public fixture pilot and is not enterprise evidence.",
+    "The comparison has one replicate per task and eight paired observations.",
+    "Automated rubric outcomes are not independent semantic approval of documentation correctness.",
+    "The aggregate reduction is not uniform: individual paired tasks moved in both directions.",
+    "No currency claim is made because provider pricing was intentionally not configured."
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "f736c7f1fb83a1e4bde8c47aad2838af6f6f6d61f5ed7b5e0dad3ab463084cdd"
+}

package/docs/study/phase4-public-pilot-run-plan-v1.json

@@ -0,0 +1,26 @@
+{
+  "type": "controlled-study-run-plan",
+  "schemaVersion": 1,
+  "planVersion": "phase4-public-pilot-v1",
+  "protocolVersion": "v2",
+  "protocolHash": "97202235c4dbd556f41fe1aa08663d35b16d516de827aebae73b136bb6a538f6",
+  "taskSuiteHash": "226cd26a07fd0bd811fcc8ccf0eee8ef0f9813f68aa9c53d465f98dad44f62a7",
+  "sourceRevisionHash": "b58455ffc94e25c95d1dbf359565643afd343774a4c0d5d0ae2942e6b019d6db",
+  "configurationHash": "80e4ca1d574159b3cc09292d8df65156f5a8d6ab3d13fbf8f2f7ddbabd76e455",
+  "docBridgeVersion": "1.8.0",
+  "models": [
+    { "id": "low-cost-model", "role": "low-cost", "provider": "codex", "model": "gpt-5.6-sol", "version": "codex-cli-0.154.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.154.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": ["public-fixture-discovery", "public-fixture-architecture", "public-fixture-documentation", "public-fixture-implementation"],
+  "sampling": { "strategy": "pairwise-task-strata", "sampleSize": 16, "scenarioIds": ["repository-only", "deterministic-doc-bridge"] },
+  "budget": { "maxTokens": 200000, "maxRuntimeMs": 180000, "maxOutputBytes": 256000, "maxAttempts": 1 },
+  "runId": "phase4-public-pilot-04",
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "fdc33d417de30a1aa48cc0711c89d87096bb2ad628b5d43f32046e9d0c16ef6a"
+}

package/docs/study/phase4-public-pilot-task-suite-v1.json

@@ -0,0 +1,71 @@
+{
+  "type": "study-task-suite",
+  "schemaVersion": 1,
+  "suiteVersion": "phase4-public-pilot-v1",
+  "protocolVersion": "v2",
+  "title": "Bounded public pilot for documentation and knowledge discovery",
+  "population": ["public-fixture"],
+  "modelIds": ["low-cost-model", "reference-model"],
+  "scenarioIds": ["repository-only", "deterministic-doc-bridge", "registry-assisted"],
+  "maxTokensPerTask": 12000,
+  "maxRuntimeMsPerTask": 120000,
+  "maxRuns": 48,
+  "replicatesPerTask": 1,
+  "ordering": { "strategy": "balanced-counter-order", "seed": "phase4-public-pilot-v1" },
+  "tasks": [
+    {
+      "id": "public-fixture-discovery", "repositoryId": "public-fixture", "category": "discovery", "difficulty": "easy",
+      "objective": "Locate the public fixture entrypoints, ownership boundary, and canonical agent documentation.",
+      "initialContext": ["Start with the repository root and declared documentation."],
+      "allowedTools": ["repository-read", "doc-bridge-query", "shell-read"], "forbiddenActions": ["Modify files", "Invent undocumented ownership"],
+      "expectedOutcome": "A concise map names the fixture entrypoints, owner, and evidence without unsupported claims.",
+      "evidenceRequirements": [{ "id": "entrypoint-evidence", "description": "Observed declarations supporting the fixture entrypoint and ownership.", "source": "artifact" }],
+      "acceptanceChecks": [{ "id": "fixture-discovery-check", "command": "node -e \"const fs=require('node:fs'); if(!fs.existsSync('doc-bridge.config.json')||!fs.existsSync('llms.txt')) process.exit(1)\"", "expected": "The public fixture declares its Doc Bridge configuration and agent-readable index." }],
+      "budget": { "maxTokens": 6000, "maxRuntimeMs": 60000 },
+      "surfaces": { "logic": { "required": true }, "endpoint": { "required": false, "reason": "The public fixture has no endpoint." }, "database": { "required": false, "reason": "The public fixture has no database." }, "cli": { "required": true }, "mcp": { "required": false, "reason": "MCP is not required for this bounded discovery task." }, "ui": { "required": false, "reason": "The public fixture has no UI." }, "docs": { "required": true } },
+      "rubric": { "success": ["The entrypoint and owner are correct and evidenced."], "partial": ["The primary entrypoint is correct but one non-critical citation is missing."], "incorrect": ["The answer identifies an unsupported entrypoint or owner."], "incomplete": ["The answer does not cover the fixture scope."], "blocked": ["Required fixture evidence cannot be accessed."] },
+      "variantGroup": "public-fixture-discovery", "variants": [{ "id": "variant-a", "label": "Entrypoint-first wording", "context": "Begin with the declared configuration and package entrypoint." }, { "id": "variant-b", "label": "Documentation-first wording", "context": "Begin with the agent-readable index and trace ownership." }]
+    },
+    {
+      "id": "public-fixture-architecture", "repositoryId": "public-fixture", "category": "architecture", "difficulty": "medium",
+      "objective": "Describe the public fixture architecture as connected components and identify one evidence-backed boundary.",
+      "initialContext": ["Use workspace metadata, routing configuration, and agent documentation."],
+      "allowedTools": ["repository-read", "doc-bridge-map", "shell-read"], "forbiddenActions": ["Modify files", "Infer runtime edges without evidence"],
+      "expectedOutcome": "A bounded architecture view identifies the package, documentation corpus, and routing relationship.",
+      "evidenceRequirements": [{ "id": "architecture-evidence", "description": "Observed configuration and documentation supporting the architecture view.", "source": "artifact" }],
+      "acceptanceChecks": [{ "id": "fixture-architecture-check", "command": "node -e \"const fs=require('node:fs'); const c=JSON.parse(fs.readFileSync('doc-bridge.config.json')); if(c.routing?.plugin!=='pnpm-monorepo'||!c.corpus?.agent?.index) process.exit(1)\"", "expected": "The fixture declares a routing plugin and an agent documentation index." }],
+      "budget": { "maxTokens": 8000, "maxRuntimeMs": 90000 },
+      "surfaces": { "logic": { "required": true }, "endpoint": { "required": false, "reason": "The architecture task is static." }, "database": { "required": false, "reason": "The public fixture has no database." }, "cli": { "required": true }, "mcp": { "required": false, "reason": "MCP is not required for this bounded architecture task." }, "ui": { "required": false, "reason": "The public fixture has no UI." }, "docs": { "required": true } },
+      "rubric": { "success": ["The map is bounded, directional, and every relation has evidence."], "partial": ["The main components are correct but one relation or limitation is missing."], "incorrect": ["The map asserts an unsupported component or relation."], "incomplete": ["The answer is a list without connected evidence."], "blocked": ["The architecture evidence cannot be inspected."] },
+      "variantGroup": "public-fixture-architecture", "variants": [{ "id": "variant-a", "label": "Component-first wording", "context": "Start by grouping the observed fixture components." }, { "id": "variant-b", "label": "Relation-first wording", "context": "Start by tracing the strongest observed connection." }]
+    },
+    {
+      "id": "public-fixture-documentation", "repositoryId": "public-fixture", "category": "documentation", "difficulty": "hard",
+      "objective": "Find one stale, missing, unclear, redundant, or contradictory documentation claim in the public fixture and classify it with evidence.",
+      "initialContext": ["Compare the agent-readable index, human documentation metadata, and routing configuration."],
+      "allowedTools": ["repository-read", "doc-bridge-audit", "shell-read"], "forbiddenActions": ["Edit documentation", "Treat an unverified semantic inference as fact"],
+      "expectedOutcome": "The review reports a precise documentation issue, evidence, confidence, limitation, and next action.",
+      "evidenceRequirements": [{ "id": "documentation-evidence", "description": "Document and configuration evidence for the classified documentation issue.", "source": "artifact" }, { "id": "review-limitation", "description": "A limitation or confidence statement for the semantic judgment.", "source": "human" }],
+      "acceptanceChecks": [{ "id": "fixture-documentation-check", "command": "node -e \"const fs=require('node:fs'); if(!fs.existsSync('docs/for-agents/INDEX.md')||!fs.existsSync('llms.txt')||!fs.existsSync('doc-bridge.config.json')) process.exit(1)\"", "expected": "The fixture exposes the documentation surfaces required for a bounded comparison." }],
+      "budget": { "maxTokens": 10000, "maxRuntimeMs": 120000 },
+      "surfaces": { "logic": { "required": true }, "endpoint": { "required": false, "reason": "Documentation classification does not require an endpoint." }, "database": { "required": false, "reason": "Documentation classification does not require a database." }, "cli": { "required": true }, "mcp": { "required": false, "reason": "MCP is not required for this bounded audit task." }, "ui": { "required": false, "reason": "Documentation classification is not a UI task." }, "docs": { "required": true } },
+      "rubric": { "success": ["The issue category, evidence, confidence, and limitation are correct."], "partial": ["The issue is real but its category or limitation needs correction."], "incorrect": ["The claimed issue is contradicted by current evidence."], "incomplete": ["The answer names a concern without enough evidence."], "blocked": ["The documentation corpus cannot be compared."] },
+      "variantGroup": "public-fixture-documentation", "variants": [{ "id": "variant-a", "label": "Claim-first wording", "context": "Begin with a documentation claim and trace it to configuration." }, { "id": "variant-b", "label": "Evidence-first wording", "context": "Begin with observed configuration and find its documentation coverage." }]
+    },
+    {
+      "id": "public-fixture-implementation", "repositoryId": "public-fixture", "category": "implementation", "difficulty": "hard",
+      "objective": "Propose a minimal documentation-only correction for a verified public fixture knowledge gap without changing source code.",
+      "initialContext": ["Use the preceding discovery, architecture, and documentation evidence as context."],
+      "allowedTools": ["repository-read", "doc-bridge-query", "shell-read"], "forbiddenActions": ["Modify files", "Invent behavior not present in evidence"],
+      "expectedOutcome": "A minimal proposal identifies the documentation location, preserves conventions, and states how it would be verified.",
+      "evidenceRequirements": [{ "id": "patch-evidence", "description": "Evidence identifying the target document and verified knowledge gap.", "source": "artifact" }, { "id": "verification-plan", "description": "A real command or review step that would validate the proposal.", "source": "runner" }],
+      "acceptanceChecks": [{ "id": "fixture-proposal-check", "command": "node -e \"const fs=require('node:fs'); if(!fs.existsSync('.doc-bridge/index.json')||!fs.existsSync('docs/for-agents/INDEX.md')) process.exit(1)\"", "expected": "The fixture has a generated index and canonical agent documentation for proposal verification." }],
+      "budget": { "maxTokens": 10000, "maxRuntimeMs": 120000 },
+      "surfaces": { "logic": { "required": true }, "endpoint": { "required": false, "reason": "The proposal is documentation-only." }, "database": { "required": false, "reason": "The proposal is documentation-only." }, "cli": { "required": true }, "mcp": { "required": false, "reason": "MCP is not required for a bounded proposal." }, "ui": { "required": false, "reason": "The proposal does not change UI." }, "docs": { "required": true } },
+      "rubric": { "success": ["The proposal is minimal, correctly scoped, evidence-backed, and verifiable."], "partial": ["The proposal is safe but needs a location or verification correction."], "incorrect": ["The proposal targets the wrong document or asserts unsupported behavior."], "incomplete": ["The proposal lacks a usable change or verification plan."], "blocked": ["The target documentation cannot be safely identified."] },
+      "variantGroup": "public-fixture-implementation", "variants": [{ "id": "variant-a", "label": "Gap-to-patch wording", "context": "Start from the verified gap and derive the smallest correction." }, { "id": "variant-b", "label": "Patch-to-proof wording", "context": "Start from the expected proof and identify the smallest documentation change." }]
+    }
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "226cd26a07fd0bd811fcc8ccf0eee8ef0f9813f68aa9c53d465f98dad44f62a7"
+}

package/docs/study/pilot-round-2026-08-31.json

@@ -0,0 +1,46 @@
+{
+  "type": "controlled-study-pilot-report",
+  "schemaVersion": 1,
+  "studyRound": "baseline-codex-2026-08-31",
+  "planHash": "949e7642f85ac2f598e006a0c47ccdcf7c0a4c44f8f2697a0e5c7993bfc0add4",
+  "ledgerHash": "675b343552fabde2bb13dee441b6154949a85b302a88517b214334977cc61111",
+  "providerConfigHash": "c321593deefd52b8c1e5d7d096052989535959e6affe4a8b36714798bd51f517",
+  "repositoryConfigHash": "d85352921b5d18aa1d480d02ffdc5247755833e9f717c734b965023c6cec5c28",
+  "observations": [
+    {
+      "taskId": "consumer-02-documentation",
+      "modelId": "low-cost-model",
+      "scenarioId": "deterministic-doc-bridge",
+      "status": "completed",
+      "providerTokens": 209704,
+      "durationMs": 79451,
+      "toolCalls": 6,
+      "taskOutcome": "partial",
+      "evidenceQuality": "medium",
+      "safetyOutcome": "safe"
+    },
+    {
+      "taskId": "consumer-01-architecture",
+      "modelId": "reference-model",
+      "scenarioId": "registry-assisted",
+      "status": "budget-exceeded",
+      "providerTokens": 400078,
+      "durationMs": 82142,
+      "toolCalls": 12
+    }
+  ],
+  "aggregate": {
+    "observationCount": 2,
+    "completedRate": 0.5,
+    "providerTokens": 609782,
+    "latencyP95Ms": 82142,
+    "averageToolCalls": 9
+  },
+  "limitations": [
+    "Pilot sample is not a controlled baseline and cannot establish improvement.",
+    "Semantic task success remains pending human adjudication.",
+    "The reference task exceeded the configured token ceiling."
+  ],
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "3d3e99aca88de44ca4fa2688b7453f75da500bda858c3f9f63d65c34aa50da6e"
+}

package/docs/study/protocol-v1.json

@@ -0,0 +1,90 @@
+{
+  "type": "study-protocol",
+  "schemaVersion": 1,
+  "protocolVersion": "v1",
+  "title": "Documentation quality and agent efficiency 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": "task-success", "family": "task", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of task acceptance criteria satisfied." },
+    { "id": "tokens-to-answer", "family": "discovery", "unit": "tokens", "source": "provider", "required": true, "description": "Tokens consumed before a correct evidence-backed answer." },
+    { "id": "time-to-answer", "family": "discovery", "unit": "milliseconds", "source": "runner", "required": true, "description": "Elapsed time before a correct evidence-backed answer." },
+    { "id": "evidence-citation-rate", "family": "discovery", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of answer claims supported by required evidence." },
+    { "id": "documentation-correctness", "family": "documentation", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of reviewed claims agreeing with observed evidence." },
+    { "id": "documentation-completeness", "family": "documentation", "unit": "ratio", "source": "adjudicator", "required": true, "description": "Proportion of required knowledge present for the declared scope." },
+    { "id": "documentation-clarity", "family": "documentation", "unit": "ratio", "source": "human", "required": true, "description": "Proportion of reviewed documents understandable to the declared audience." },
+    { "id": "documentation-maintainability", "family": "documentation", "unit": "ratio", "source": "human", "required": true, "description": "Proportion of critical documents with maintainable ownership and validation metadata." },
+    { "id": "docbridge-runtime", "family": "operations", "unit": "milliseconds", "source": "doc-bridge", "required": true, "description": "Doc Bridge analysis and report runtime." },
+    { "id": "study-cost", "family": "cost", "unit": "currency", "source": "runner", "required": true, "description": "Measured cost of analysis and controlled task execution." }
+  ],
+  "outcomes": [
+    { "id": "protocol-integrity", "statement": "The study protocol is valid, versioned, and reproducible.", "checks": [{ "id": "protocol-validation", "command": "ak-docs study protocol docs/study/protocol-v1.json --json" }] },
+    { "id": "historical-evidence", "statement": "Historical observations preserve provenance, missing measurements, and limitations.", "checks": [{ "id": "history-validation", "command": "ak-docs study history docs/study/historical-evidence-v1.json --protocol docs/study/protocol-v1.json --json" }] },
+    { "id": "controlled-comparison", "statement": "Controlled task results can be compared only under a fixed protocol and source revision.", "checks": [{ "id": "controlled-run-validation", "command": "ak-verify plan approved --allow-dirty --config .codex/verification.json && ak-verify start --config .codex/verification.json && ak-verify verify --config .codex/verification.json --json" }] },
+    { "id": "documentation-quality", "statement": "Documentation quality is measured for correctness, completeness, clarity, and maintainability.", "checks": [{ "id": "documentation-quality-review", "command": "pnpm docs:typecheck" }] },
+    { "id": "semantic-consistency", "statement": "Documentation claims can be compared with observed repository evidence.", "checks": [{ "id": "semantic-evidence-review", "command": "ak-docs study history docs/study/historical-evidence-v1.json --protocol docs/study/protocol-v1.json --json" }] },
+    { "id": "agent-efficiency", "statement": "Agent task efficiency is measured with tokens, time, evidence, and task success.", "checks": [{ "id": "efficiency-metric-contract", "command": "pnpm exec vitest run tests/study-protocol.test.ts" }] },
+    { "id": "privacy", "statement": "Published study artifacts contain no private repository names, paths, prompts, or raw responses.", "checks": [{ "id": "privacy-scan", "command": "rg -qi \"forbidden-pattern\" docs/study docs/spec/study-protocol-v1.md" }] },
+    { "id": "recovery", "statement": "Invalid or incomplete evidence is rejected or preserved as explicit missing data.", "checks": [{ "id": "recovery-contract-tests", "command": "pnpm exec vitest run tests/study-protocol.test.ts" }] },
+    { "id": "longitudinal-reporting", "statement": "Study runs are versioned and auditable over time.", "checks": [{ "id": "content-hash-validation", "command": "pnpm exec vitest run tests/study-protocol.test.ts" }] },
+    { "id": "stopping-rules", "statement": "The study defines measurable stopping targets before controlled rounds begin.", "checks": [{ "id": "stopping-target-validation", "command": "ak-docs study protocol docs/study/protocol-v1.json --json" }] }
+  ],
+  "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-answer", "direction": "decrease", "threshold": 0.25 },
+      { "metricId": "time-to-answer", "direction": "decrease", "threshold": 0.2 },
+      { "metricId": "task-success", "direction": "no-regression", "threshold": 0 }
+    ]
+  },
+  "contentHashAlgo": "sha256-normalized-v1",
+  "contentHash": "fe26951579d9003f1cd616f12fb6d6007a60ec69db5efbb9acd5d80c817002d1"
+}

package/docs/study/publication-gate-v1.md

@@ -0,0 +1,45 @@
+---
+title: Study publication gate v1
+description: Reviewable gates for publishing anonymized Doc Bridge efficiency measurements.
+---
+
+# Study publication gate v1
+
+This gate prevents a smaller context payload, a provider-token measurement,
+and a correct task result from being presented as the same claim.
+
+## Required evidence
+
+Before publishing a study result, all of the following must be present:
+
+1. A versioned protocol, task suite, run plan, ledger, and result with content
+   hashes.
+2. A current `ak-verify` run whose source revision and configuration match the
+   artifacts.
+3. A privacy scan with zero forbidden matches.
+4. Explicit classification of completed, partial, failed, blocked, and missing
+   observations.
+5. Separate values for context payload, provider-token usage, latency, and
+   tokens-to-correct-action. Missing correctness evidence remains missing.
+6. A human publication decision recorded by the tracking workflow.
+
+## Reproduction
+
+```bash
+node bin/ak-docs.js study metrics docs/study/phase4-public-pilot-ledger-v1.json --json
+node scripts/phase4-public-pilot-check.mjs
+node scripts/study-privacy-gate.mjs docs/study
+```
+
+The first command exposes the machine-readable metric contract. The second
+checks the pilot's hashes, bindings, scope, and arithmetic. The third scans
+publication-bound artifacts without printing matched secret values.
+
+## Claim boundaries
+
+- `context payload reduction` is not provider-token reduction.
+- `provider-token reduction` is not a currency saving unless configured pricing
+  and provider usage are both available.
+- `tokens-to-correct-action` is `null` when semantic success is not established.
+- A bounded pilot is not evidence of enterprise-wide generalization.
+- Publication requires human review even when every deterministic check passes.