fix(learning): preserve research feedback and measured evidence

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 14.0.0 — 2026-09-05
+
+### Changed
+
+- `ResearchDriver` gains optional `isComplete()`.
+The research loop requires this result and storage readiness before it reports ready.
+An unfinished driver receives steering rounds even when storage requirements pass.
+Drivers without this method retain their storage readiness behavior.
+The exported interface shape requires a major release under the package compatibility check.
+- Requires `agent-eval` `>=0.174.0 <0.175.0` and tests against `0.174.0`.
+This cohort uses Eval's corrected complete-method result and cost accounting contracts.
+- Default knowledge evaluator version `2` averages only measured dimensions.
+It omits `answer_quality` without answer evaluation, `promotion_decision` without a decision, and `blocking_readiness` without blocking requirements.
+Consumers must handle absent dimension keys and compare scores using their evaluator version.
+Structural-only results state that no task outcome evaluation occurred.
+`candidate-ready` still leaves the candidate detached from the live knowledge base.
+
+### Fixed
+
+- Knowledge diagnosis runs before acquisition and updates.
+One lifecycle carries findings, acquisition, and update results into final answer checks and the promotion decision.
+Diagnosis alone does not consume final evaluation cases.
+Disabling a required phase fails before candidate work starts.
+Final measurement still uses frozen candidate bytes and cannot feed another adaptive update.
+
 ## 13.0.1 — 2026-09-01
 
 ### Changed

README.md

@@ -309,10 +309,18 @@ Reusing a run ID with a different implementation reference fails before cached w
 Different run IDs create separate candidate workspaces, so workers can explore in parallel.
 Promotion checks the original base hash and rejects a stale candidate instead of replacing newer work.
 Candidate retries use `evaluateDevelopment` when provided, otherwise they use deterministic validation, readiness, and KB quality checks.
+Diagnosis runs before acquisition and updates, using development data only.
+Its findings and update results remain available to final answer checks and the promotion decision.
 Development evaluation must use only train or selection data.
 The configured `evaluate` callback and final RAG phases run once, on the first candidate that passes those development checks.
 A failed final evaluation ends the run instead of selecting another candidate against final data.
 
+The default evaluator reports only measured dimensions and averages those dimensions with equal weight.
+It omits `answer_quality` without answer evaluation, `promotion_decision` without a promotion decision, and `blocking_readiness` without blocking readiness requirements.
+Default evaluator version `2` records this weighting.
+A candidate can pass structural checks without any task outcome evaluation; the metric notes state this limit.
+`candidate-ready` means the configured checks passed and the candidate remains detached from the live knowledge base.
+
 Candidate promotion currently requires Linux because it relies on Linux directory descriptors for exact file identity.
 
 ## Evaluate and improve RAG

api-surface.json

@@ -410,7 +410,7 @@
       "ResearchClaimRecord": "value febfce5cc05e",
       "ResearchClaimRecordSchema": "value 373728f5643d",
       "ResearchContribution": "value 4ef9b903af78",
-      "ResearchDriver": "value 39a48e748009",
+      "ResearchDriver": "value 76db7bd73161",
       "ResearchDrivingDriver": "value 919454a2ef43",
       "ResearchDrivingDriverOptions": "value bf4180687f2d",
       "ResearchDrivingState": "value 55bc4328e4c3",

docs/architecture.md

@@ -58,6 +58,10 @@ After the exact submitted bytes are durable, `runVerifiedResearchLoop` passes th
 The ledger materializes only observations whose complete source identity matches a confirmed record, so reusing one URI for different bytes cannot activate the wrong claims and a crash on either side resumes safely.
 Unversioned URI-only ledgers cannot prove which bytes produced their observations; reads and writes fail with `ClaimLedgerMigrationRequiredError` and preserve the original file for an explicit archive-and-reverify migration.
 Before synchronous question generation, the persistent driver records `preparedRounds`; a resume reconstructs and checkpoints any prepared round whose questions were interrupted, and the loop publishes its `research.iteration` event only after that checkpoint succeeds.
+The research loop requires storage readiness and the driver's optional `isComplete()` result before it reports completion.
+An unfinished driver can generate steering with no remaining storage gaps, so passing source requirements does not stop research prematurely.
+Drivers without `isComplete()` use storage readiness alone.
+Without readiness specifications, the loop runs to its round limit and never reports ready.
 
 Every write in this layer goes through `durable-fs` (`writeFileDurable`, `writeJsonDurableWithinRoot`): temp file, fsync, atomic rename, and parent fsync.
 `O_NOFOLLOW` descriptors anchored through `/proc/self/fd` prevent a directory swapped for a symlink during a write from redirecting it outside the root.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "13.0.1",
+  "version": "14.0.0",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -84,14 +84,14 @@
     "zod": "4.5.4"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.173.0 <0.174.0",
+    "@tangle-network/agent-eval": ">=0.174.0 <0.175.0",
     "@tangle-network/agent-interface": "^2.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.11",
     "@neo4j-labs/agent-memory": "0.4.1",
-    "@tangle-network/agent-eval": "0.173.0",
+    "@tangle-network/agent-eval": "0.174.0",
     "@tangle-network/agent-interface": "2.0.0",
     "@types/node": "^26.4.0",
     "mem0ai": "3.1.7",

src/kb-improvement/contracts.ts

@@ -554,14 +554,14 @@ export interface LeaseHandle {
 export const DEFAULT_LEASE_TTL_MS = 15 * 60 * 1000
 
 export const UPDATE_PHASES: readonly RagKnowledgeImprovementPhase[] = [
+  'gap-diagnosis',
   'knowledge-acquisition',
   'knowledge-update',
 ]
 
 export const EVALUATION_PHASES: readonly RagKnowledgeImprovementPhase[] = [
   'rag-optimization',
   'retrieval-tuning',
-  'gap-diagnosis',
   'answer-quality',
   'promotion',
 ]