Gate 10 close Read-Need comprehension

Adds the typed bitcode.read.request record inside Read-Needs, preserves feedback and previous-Need lineage during resynthesis, and exposes ReadNeedComprehensionSynthesis contract traces through route telemetry.

Updates Terminal gating so accepted Read-Need truth is recorded with Finding Fits admission evidence, adds focused package and route coverage, and wires the Gate 10 readiness check into V28 gate quality.

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -46,6 +46,7 @@ jobs:
           node scripts/check-bitcode-canonical-inputs.mjs --current-target V27
           node scripts/check-v28-metadevelopment-readiness.mjs --skip-branch-check
           node scripts/check-v28-gate9-depository-evidence.mjs
+          node scripts/check-v28-gate10-read-need-comprehension.mjs
           node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run
 
       - name: Validate source casing and imports

BITCODE_SPEC_V28.md

@@ -826,6 +826,24 @@ reviewable Need through `ReadNeedComprehensionSynthesis`, allow feedback and
 resynthesis, persist accepted Need truth, and block Finding Fits until the Need
 is reviewed.
 
+Gate 10 acceptance requires:
+
+- a typed `bitcode.read.request` record embedded in every `bitcode.read.need`
+  so the raw request remains auditable as request truth rather than fit truth;
+- `ReadNeedComprehensionSynthesis` contract trace exposure for every phase,
+  PTRR agent, PTRR step, and ThricifiedGeneration identifier used by route
+  telemetry and Terminal stream/history surfaces;
+- resynthesis lineage: each resynthesized Need records the prior Need id and
+  appends operator feedback without losing earlier feedback turns;
+- accepted Need truth: accepting a Need computes an acceptance root, records
+  review state `accepted`, and emits Finding Fits admission evidence;
+- strict admission: `ReadFindingFitsSynthesis` receives only an accepted
+  `bitcode.read.need` when `requireAcceptedReadNeed=true`; raw Read requests
+  and unaccepted Needs produce blocked readiness;
+- Terminal exposes the first two enterprise Reading steps without raw JSON:
+  synthesize Need, review measurements/proof expectations/feedback, request
+  resynthesis, or accept the Need before the Fit button becomes ready.
+
 ### Gate 11: Finding Fits And Source-Safe AssetPack Preview
 
 Gate 11 owns `ReadFindingFitsSynthesis`: depository search, candidate fit
@@ -1171,8 +1189,9 @@ Gate 4 implementation state:
 
 - `/api/read-review` exposes server-side Read-Need synthesis, resynthesis, and
   acceptance actions while preserving the prior Read review boundary. The
-  response stores prompt input, interpolated source context, parsed Need,
-  measurement root, review state, feedback, and synthesis telemetry.
+  response stores prompt input, interpolated source context, typed
+  `bitcode.read.request`, parsed Need, measurement root, review state,
+  feedback, resynthesis lineage, contract trace, and synthesis telemetry.
 - Read-Need test coverage must stay implementation-guiding rather than
   snapshot-only: it must assert typed Need fields, measurement roots,
   source-disclosure constraints, pricing measurement vectors, acceptance

BITCODE_SPEC_V28_DELTA.md

@@ -198,6 +198,14 @@ harness deposit reference. The vector document policy is explicit:
 `text-embedding-3-small`, 1536 dimensions, `deliverable_vectors`, and
 `match_deliverable_vectors`.
 
+Gate 10 introduces the first two enterprise Reading steps as typed protocol
+state. `/api/read-review` can synthesize, resynthesize, and accept
+Read-Needs; every Need embeds its `bitcode.read.request`, feedback lineage, and
+prior Need id when resynthesized. Route telemetry exposes the
+ReadNeedComprehensionSynthesis contract trace across phases, PTRR agents,
+PTRR steps, and ThricifiedGeneration identifiers. Terminal cannot request
+Finding Fits from this path until an accepted `bitcode.read.need` is present.
+
 ## Later Version Handoff
 
 - V29: deeper Terminal workflows and transaction operation beyond V28 MVP QA.

BITCODE_SPEC_V28_NOTES.md

@@ -570,6 +570,26 @@ distance. Gate 9 records the vector document as ready for embedding generation;
 later Finding Fits and live validation gates own provider execution, ranking,
 settlement, and protected-source disclosure boundaries.
 
+## Gate 10 Read-Need comprehension closure notes
+
+Gate 10 closes the first two enterprise Reading UX steps. The raw request is
+stored as `bitcode.read.request` and embedded in the synthesized
+`bitcode.read.need`. This keeps request capture auditable without allowing a
+raw request to drive depository discovery.
+
+ReadNeedComprehensionSynthesis route telemetry now carries a contract trace for
+all request, comprehend, measure, and review phase PTRR agents, their four PTRR
+steps, and the three ThricifiedGeneration identifiers under each step. The
+route-level telemetry also includes prompt template, interpolated context, raw
+structured response posture, parsed typed output, measurement root, review
+state, and resynthesis lineage.
+
+Resynthesis appends operator feedback and records the previous Need id. Need
+acceptance computes an acceptance root and returns Finding Fits admission
+evidence. Terminal uses that accepted Need as the only live harness input for
+Finding Fits while keeping the previous measured-Read history path visible for
+readback compatibility.
+
 ## Non-Goals For V28
 
 - V28 does not implement or QA Exchange product behavior, broad order-book depth, external market routing, wrapper liquidity, or third-party marketplace integration.

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -173,8 +173,8 @@ by a later V28 gate before `version/v28` can be promoted to `main`.
 | Carryforward surface | Next gate | Required commercial implementation | Required proof/test coverage | Carryforward closure requirement |
 | --- | --- | --- | --- | --- |
 | Source Depositing and depository evidence | Gate 9 | Repository inventory, deposit admission, source measurement, depository asset rows, lexical/vector search documents, depositor wallet boundary, source proof roots, execution-history projection, and Terminal deposit history. | Protocol deposit evidence tests, depository-search tests, pipeline harness deposit-root propagation tests, staging-testnet SQL/readback queries, Terminal UX tests, and no demonstration runtime imports. | A user can deposit real source material and see source-bound evidence persisted, searchable, journaled, root-projected into Finding Fits, and owned by the depositor boundary. |
-| Read Request capture | Gate 10 | Enterprise Read Request form/state, repository target, source branch/commit context, constraints, non-goals, desired artifact types, and feedback history. | UAPI route tests, Terminal form tests, typed Read Request schema tests, prompt/context interpolation tests. | Raw requests are persisted as requests only; they do not directly trigger Finding Fits until a reviewed Need exists. |
-| Read-Need synthesis, review, and resynthesis | Gate 10 | `ReadNeedComprehensionSynthesis` execution over PTRR agents and ThricifiedGenerations, reviewable Need object, operator feedback, resynthesis attempts, acceptance root, and blocked-readiness reasons. | Pipeline contract tests, prompt/return audits, mocked typed-envelope tests, live local OpenAI validation, Terminal stream/accordion tests. | A Reader can accept or resynthesize the Need; accepted Need truth becomes the only input admitted to Finding Fits. |
+| Read Request capture | Gate 10 | Enterprise Read Request form/state, repository target, source branch/commit context, constraints, non-goals, desired artifact types, and feedback history, encoded as `bitcode.read.request` inside the Need. | UAPI route tests, Terminal form tests, typed Read Request schema tests, prompt/context interpolation tests, `check:v28-gate10`. | Raw requests are persisted as requests only; they do not directly trigger Finding Fits until a reviewed Need exists. |
+| Read-Need synthesis, review, and resynthesis | Gate 10 | `ReadNeedComprehensionSynthesis` execution over PTRR agents and ThricifiedGenerations, contract trace telemetry, reviewable Need object, operator feedback, resynthesis attempts, acceptance root, and blocked-readiness reasons. | Pipeline contract tests, prompt/return audits, mocked typed-envelope tests, route resynthesis tests, live local OpenAI validation, Terminal stream/accordion tests. | A Reader can accept or resynthesize the Need; accepted Need truth becomes the only input admitted to Finding Fits. |
 | Finding Fits over the depository | Gate 11 | `ReadFindingFitsSynthesis.discovery` searches lexical/vector deposits, ranks all threshold-passing fits, records fit deposits, query/ranking roots, blockers, and no-worthy-fit outcomes. | Depository search tests, embedding policy tests, tool telemetry tests, staging-testnet readback verifier, mock/live parity tests. | Discovery returns all fit deposits above threshold and never invents source outside the depository. |
 | AssetPack synthesis and preview | Gate 11 | Implementation phase uses fit deposits as context, synthesizes AssetPack measurements, source-safe preview, quality score, disclosure policy, and Share-to-Fee quote without protected source leakage. | AssetPack synthesis tests, disclosure-boundary tests, prompt telemetry tests, UI preview tests, source leakage scans. | Reader sees enough measured fit confidence to decide whether to settle, without seeing the protected AssetPack source before payment. |
 | BTC settlement and read-license/right transfer | Gate 12 | Fee quote/root, PSBT/finality posture, BTC payment row, BTD range/ownership/license rows, depositor/reader boundary, settlement blockers, and reconciliation. | BTD package tests, API route tests, staging-testnet ledger/database readback, reconciliation tests, wallet/signing failure tests. | Payment transfers read rights/license according to the committed policy and never grants unpaid protected-source visibility. |

package.json

@@ -40,6 +40,7 @@
     "check:spec-family": "node scripts/check-bitcode-spec-family.mjs",
     "check:v28-metadevelopment": "node scripts/check-v28-metadevelopment-readiness.mjs",
     "check:v28-gate9": "node scripts/check-v28-gate9-depository-evidence.mjs",
+    "check:v28-gate10": "node scripts/check-v28-gate10-read-need-comprehension.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/pipelines/asset-pack/src/__tests__/read-need.test.ts

@@ -72,6 +72,15 @@ describe('Read-Need synthesis and Finding Fits admission', () => {
     expect(need.needId).toMatch(/^need-[a-f0-9]{16}$/);
     expect(need.reviewState).toBe('needs_acceptance');
     expect(need.measurementRoot).toMatch(/^sha256:/);
+    expect(need.request).toMatchObject({
+      schema: 'bitcode.read.request',
+      requestId: 'read-1',
+      prompt: input.read.prompt,
+      repositoryFullName: 'engineeredsoftware/ENGI',
+      sourceBranch: 'main',
+      sourceCommit: '31bbc0c5227b6b3aed5d107fd8507d35ec22970a',
+      previousNeedId: null,
+    });
     expect(need.sourceConstraints).toMatchObject({
       repositoryFullName: 'engineeredsoftware/ENGI',
       sourceBranch: 'main',
@@ -86,6 +95,27 @@ describe('Read-Need synthesis and Finding Fits admission', () => {
     );
   });
 
+  it('carries Read Request lineage and feedback through resynthesis', () => {
+    const first = synthesizeReadNeedForPipelineInput({
+      ...input,
+      feedback: ['Keep proof roots prominent.'],
+    });
+    const second = synthesizeReadNeedForPipelineInput({
+      ...input,
+      previousReadNeed: first,
+      feedback: ['Exclude settlement completion from Need comprehension.'],
+    });
+
+    expect(second.needId).not.toBe(first.needId);
+    expect(second.request.previousNeedId).toBe(first.needId);
+    expect(second.feedbackHistory).toEqual([
+      'Keep proof roots prominent.',
+      'Exclude settlement completion from Need comprehension.',
+    ]);
+    expect(second.request.feedbackHistory).toEqual(second.feedbackHistory);
+    expect(second.reviewState).toBe('needs_acceptance');
+  });
+
   it('accepts a Need as the only admissible input to strict Finding Fits search', () => {
     const accepted = acceptReadNeed(synthesizeReadNeedForPipelineInput(input), '2026-05-18T00:00:00.000Z');
 

packages/pipelines/asset-pack/src/__tests__/reading-pipeline-contract.test.ts

@@ -4,6 +4,7 @@ import {
   READ_NEED_COMPREHENSION_SYNTHESIS,
   READ_NEED_COMPREHENSION_SYNTHESIS_CONTRACT,
   READING_PIPELINE_CONTRACTS,
+  listReadingPipelineTelemetryTrace,
   listReadingPipelineContractSummaries,
 } from '../reading-pipeline-contract';
 
@@ -138,4 +139,22 @@ describe('Reading pipeline contracts', () => {
       }),
     ]);
   });
+
+  it('lists every PTRR step as telemetry-ready trace entries with ThricifiedGeneration substeps', () => {
+    const readNeedTrace = listReadingPipelineTelemetryTrace(READ_NEED_COMPREHENSION_SYNTHESIS_CONTRACT);
+    const findingFitsTrace = listReadingPipelineTelemetryTrace(READ_FINDING_FITS_SYNTHESIS_CONTRACT);
+
+    expect(readNeedTrace).toHaveLength(16);
+    expect(findingFitsTrace).toHaveLength(32);
+    expect(readNeedTrace.map((entry) => entry.ptrrStepId)).toContain(
+      'ReadNeedComprehensionSynthesis.comprehend.need-synthesizer.try',
+    );
+
+    for (const entry of [...readNeedTrace, ...findingFitsTrace]) {
+      expect(entry.agentId.startsWith(`${entry.pipelineName}.`)).toBe(true);
+      expect(entry.thricifiedGenerationIds).toHaveLength(3);
+      expect(entry.thricifiedGenerations).toHaveLength(3);
+      expect(entry.telemetry.every((telemetry) => telemetry.startsWith(`${entry.pipelineName}.telemetry.`))).toBe(true);
+    }
+  });
 });

packages/pipelines/asset-pack/src/index.ts

@@ -288,9 +288,11 @@ export {
   resolveReadNeedFromPipelineInput,
   shouldRequireAcceptedReadNeed,
   synthesizeReadNeedForPipelineInput,
+  synthesizeReadNeedForPipelineInputWithInference,
   type AssetPackReadRightState,
   type AssetPackSourceSafePreview,
   type ReadNeed,
+  type ReadNeedRequest,
   type ReadFindingFitsAdmission,
   type ReadNeedMeasurementDimension,
   type ReadNeedReviewState,

packages/pipelines/asset-pack/src/read-need.ts

@@ -18,11 +18,26 @@ export interface ReadNeedMeasurementDimension {
   volume: number;
 }
 
+export interface ReadNeedRequest {
+  schema: 'bitcode.read.request';
+  requestId: string;
+  prompt: string;
+  repositoryFullName?: string | null;
+  sourceBranch?: string | null;
+  sourceCommit?: string | null;
+  targetArtifactKinds: string[];
+  closureCriteria: string[];
+  failureModes: string[];
+  feedbackHistory: string[];
+  previousNeedId?: string | null;
+}
+
 export interface ReadNeed {
   schema: 'bitcode.read.need';
   needId: string;
   reviewState: ReadNeedReviewState;
   measurementRoot: string;
+  request: ReadNeedRequest;
   read: {
     id?: string | null;
     prompt: string;
@@ -172,6 +187,8 @@ type ReadNeedSourceInput = {
   closureCriteria?: unknown;
   failureModes?: unknown;
   feedback?: unknown;
+  readNeed?: unknown;
+  previousReadNeed?: unknown;
 };
 
 const inferredStringListSchema = z.preprocess(
@@ -232,6 +249,10 @@ function stringArray(value: unknown): string[] {
     .filter(Boolean);
 }
 
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
 function getPath(value: unknown, path: string[]): unknown {
   let cursor = value;
   for (const part of path) {
@@ -245,6 +266,13 @@ function normalizeArtifactKind(value: string): string {
   return value.toLowerCase().replace(/[_\s]+/g, '-');
 }
 
+function priorReadNeed(input: ReadNeedSourceInput): Record<string, unknown> | null {
+  const direct = recordValue(input.readNeed);
+  if (direct?.schema === 'bitcode.read.need') return direct;
+  const previous = recordValue(input.previousReadNeed);
+  return previous?.schema === 'bitcode.read.need' ? previous : null;
+}
+
 function normalizeSource(input: ReadNeedSourceInput) {
   const readRecord = recordValue(input.read);
   const requestRecord = recordValue(input.readRequest);
@@ -373,28 +401,47 @@ function clampQuality(value: number): number {
 export function synthesizeReadNeedForPipelineInput(input: ReadNeedSourceInput): ReadNeed {
   const read = normalizeSource(input);
   const targetArtifactKinds = normalizeTargetArtifactKinds(input);
+  const previousNeed = priorReadNeed(input);
   const explicitClosureCriteria = [
     ...stringArray(input.closureCriteria),
     ...stringArray(recordValue(input.read)?.closureCriteria),
     ...stringArray(recordValue(input.readRequest)?.closureCriteria),
     ...stringArray(recordValue(input.readMeasurement)?.closureCriteria),
   ];
   const closureCriteria = explicitClosureCriteria.length
-    ? [...new Set(explicitClosureCriteria)]
+    ? uniqueStrings(explicitClosureCriteria)
     : defaultClosureCriteria(read);
   const failureModes = [
     ...defaultFailureModes(),
     ...stringArray(input.failureModes),
     ...stringArray(recordValue(input.read)?.failureModes),
     ...stringArray(recordValue(input.readRequest)?.failureModes),
   ];
-  const feedbackHistory = stringArray(input.feedback);
+  const feedbackHistory = uniqueStrings([
+    ...stringArray(previousNeed?.feedbackHistory),
+    ...stringArray(recordValue(previousNeed?.request)?.feedbackHistory),
+    ...stringArray(recordValue(input.readRequest)?.feedback),
+    ...stringArray(input.feedback),
+  ]);
   const measurementVector = measurementVectorForNeed(read, targetArtifactKinds, closureCriteria);
+  const readRequest: ReadNeedRequest = {
+    schema: 'bitcode.read.request',
+    requestId: read.id || `request-${sha256(stableStringify({ read, targetArtifactKinds })).slice(0, 16)}`,
+    prompt: read.prompt,
+    repositoryFullName: read.repositoryFullName,
+    sourceBranch: read.sourceBranch,
+    sourceCommit: read.sourceCommit,
+    targetArtifactKinds,
+    closureCriteria,
+    failureModes: uniqueStrings(failureModes),
+    feedbackHistory,
+    previousNeedId: firstString(previousNeed?.needId),
+  };
   const seed = {
+    request: readRequest,
     read,
     targetArtifactKinds,
     closureCriteria,
-    failureModes,
     feedbackHistory,
     measurementVector,
   };
@@ -410,10 +457,11 @@ export function synthesizeReadNeedForPipelineInput(input: ReadNeedSourceInput):
     needId: `need-${sha256(stableStringify(seed)).slice(0, 16)}`,
     reviewState: 'needs_acceptance',
     measurementRoot,
+    request: readRequest,
     read,
     requirements: defaultRequirements(read),
     closureCriteria,
-    failureModes: [...new Set(failureModes)],
+    failureModes: readRequest.failureModes,
     targetArtifactKinds,
     sourceConstraints: {
       repositoryFullName: read.repositoryFullName,
@@ -475,7 +523,8 @@ export async function synthesizeReadNeedForPipelineInputWithInference(
       targetArtifactKinds,
       closureCriteria: explicitClosureCriteria,
       failureModes: stringArray(input.failureModes),
-      feedbackHistory: stringArray(input.feedback),
+      feedbackHistory: fallbackNeed.feedbackHistory,
+      previousNeedId: fallbackNeed.request.previousNeedId,
       requiredOutput:
         'requirements, closureCriteria, failureModes, targetArtifactKinds, proofExpectations',
     }),