V48 (implementation-only): Align deposit SDIVF prompts to sourceCheckoutCatalog and A/B/C ready-to-finish

Rewrite Setup/Discovery/Implementation/Validation PTRR identities and step parts
to the accepted deposit algorithm: sourceCheckoutCatalog (not inventory), AssetPack
as patch + measurements + metadata (host attaches absolutes), Validation as single
A/B/C ready-to-finish gate, no lens/Fits Finding framing. Update prompt contracts
and related agent tests; fix jest mapper for doc-comment-generics.

Author: geraldarthurdavis

packages/asset-packs-pipelines/domain/jest.config.cjs

@@ -68,8 +68,8 @@ module.exports = {
     '^@bitcode/generic-tools/use-computer/(.*)$': '<rootDir>/../../generic-tools/use-computer/src/$1',
     '^@bitcode/registry$': '<rootDir>/../../registry/src/index.ts',
     '^@bitcode/registry/(.*)$': '<rootDir>/../../registry/src/$1',
-    '^@bitcode/doc-comment-generics$': '<rootDir>/../../doc-comment/src/index.ts',
-    '^@bitcode/doc-comment-generics/(.*)$': '<rootDir>/../../doc-comment/src/$1',
+    '^@bitcode/doc-comment-generics$': '<rootDir>/../../doc-comment-generics/src/index.ts',
+    '^@bitcode/doc-comment-generics/(.*)$': '<rootDir>/../../doc-comment-generics/src/$1',
     '^@bitcode/btd/(.*)$': '<rootDir>/../../btd/src/$1.ts',
     '^@bitcode/btd$': '<rootDir>/../../btd/src/index.ts',
   },

packages/asset-packs-pipelines/domain/src/__tests__/deposit-agent-prompt-contracts.test.ts

@@ -198,10 +198,17 @@ describe('deposit agent context/store contract', () => {
         discoveryExec,
       );
       expect(result.success).toBe(true);
-      expect(result.guidance).toEqual(guidance);
+      // Host may enrich with searchQueries / tool underservedTopics; core fields preserved.
+      expect(result.guidance.summary).toBe(guidance.summary);
+      expect(result.guidance.likelyReadTopics).toEqual(guidance.likelyReadTopics);
+      expect(result.guidance.underservedTopics).toEqual(
+        expect.arrayContaining(['token refresh']),
+      );
       // Stored on the SHARED execution (cross-phase law).
-      expect(shared.get('discovery', 'depositorySearch')).toEqual(guidance);
-      expect(shared.child('seq-2').findUp('discovery', 'depositorySearch')).toEqual(guidance);
+      expect(shared.get('discovery', 'depositorySearch').summary).toBe(guidance.summary);
+      expect(shared.child('seq-2').findUp('discovery', 'depositorySearch').summary).toBe(
+        guidance.summary,
+      );
     }, 60000);
 
     it('inherent regurgitation stores discovery:inherentRegurgitation (the key the synthesis agent reads)', async () => {
@@ -259,25 +266,42 @@ describe('deposit agent context/store contract', () => {
 
       expect(result.success).toBe(true);
       expect(result.semanticKind).toBe('asset-pack-written-asset');
-      expect(result.options).toEqual(options);
-      expect(result.summary).toBe('Synthesized 2 measured deposit AssetPack patch(es).');
+      // AssetPack = patch + measurements + metadata: host attaches absolutes after PTRR.
+      expect(result.options).toHaveLength(2);
+      for (const opt of result.options) {
+        expect(opt).toMatchObject({
+          kind: expect.any(String),
+          title: expect.any(String),
+          patch: expect.objectContaining({
+            fileChanges: expect.any(Array),
+            patchSummary: expect.any(String),
+          }),
+        });
+        expect(Array.isArray(opt.absolutes)).toBe(true);
+        expect(opt.absolutes.length).toBeGreaterThan(0);
+      }
+      expect(result.summary).toBe(
+        'Synthesized 2 measured deposit AssetPack(s) (patch + measurements + metadata).',
+      );
       expect(result.assetPack).toEqual({ repository: REPOSITORY });
 
       // implementation:options — the store the /deposits route's completion read
       // and the deposit validation agent consume; implementation:assetPacks — the
       // SAME array. Stored on the SHARED execution (cross-phase law): the route
       // holds the root, so its `execution.get('implementation','options')`
       // completion read (route.ts) resolves DIRECTLY.
-      expect(shared.get('implementation', 'options')).toEqual(options);
-      expect(shared.get('implementation', 'assetPacks')).toEqual(options);
+      expect(shared.get('implementation', 'options')).toBe(result.options);
+      expect(shared.get('implementation', 'assetPacks')).toBe(result.options);
       expect(shared.get('implementation', 'options')).toBe(shared.get('implementation', 'assetPacks'));
       // implementation:assetPack + implementation:summary — the stores Finish reads,
       // resolvable from the Finish sibling via the upward walk.
       expect(shared.get('implementation', 'assetPack')).toEqual({ repository: REPOSITORY });
       expect(shared.get('implementation', 'summary')).toBe(
-        'Synthesized 2 measured deposit AssetPack patch(es).',
+        'Synthesized 2 measured deposit AssetPack(s) (patch + measurements + metadata).',
+      );
+      expect(shared.child('seq-3').child('seq-0').findUp('implementation', 'options')).toBe(
+        result.options,
       );
-      expect(shared.child('seq-3').child('seq-0').findUp('implementation', 'options')).toEqual(options);
     }, 60000);
 
     it('threads cross-phase stores written on the SHARED parent into the synthesis generation context (F20 law)', async () => {

packages/asset-packs-pipelines/domain/src/__tests__/deposit-agent-store-contract.test.ts

@@ -74,7 +74,9 @@ describe('runDepositAssetPackSynthesisAgent (boundary-mocked PTRR)', () => {
 
     expect(out.success).toBe(true);
     expect(out.semanticKind).toBe('asset-pack-written-asset');
-    expect(out.summary).toBe('Synthesized 2 measured deposit AssetPack patch(es).');
+    expect(out.summary).toBe(
+      'Synthesized 2 measured deposit AssetPack(s) (patch + measurements + metadata).',
+    );
     expect(Array.isArray(out.options)).toBe(true);
     expect(out.options.length).toBeGreaterThanOrEqual(1);
     expect(out.options.length).toBeLessThanOrEqual(4);
@@ -123,7 +125,7 @@ describe('runDepositAssetPackSynthesisAgent (boundary-mocked PTRR)', () => {
     expect(assetPacks).toBe(options); // the SAME array under both keys
     expect(exec.get('implementation', 'assetPack')).toEqual(out.assetPack);
     expect(exec.get('implementation', 'summary')).toBe(
-      'Synthesized 2 measured deposit AssetPack patch(es).',
+      'Synthesized 2 measured deposit AssetPack(s) (patch + measurements + metadata).',
     );
   }, 120000);
 

packages/asset-packs-pipelines/domain/src/__tests__/deposit-asset-pack-synthesis-agent.test.ts

@@ -1,5 +1,8 @@
 /**
  * @jest-environment node
+ *
+ * Lightweight unit tests for the single deposit Validation ready-to-finish gate.
+ * Heavy PTRR / measure / catalog graph is mocked so A/B/C merge logic is isolated.
  */
 jest.mock('../agents/validation/agent-measure-absolutes', () => ({
   measureAssetPackAbsolutes: jest.fn(async () => [
@@ -15,6 +18,13 @@ jest.mock('../agents/validation/agent-measure-absolutes', () => ({
   ]),
 }));
 
+jest.mock('../asset-packs-synthesis', () => ({
+  ASSET_PACK_ABSOLUTES_CATALOG: [
+    { measurementKind: 'function-count', label: 'Functions', weight: 0.12 },
+  ],
+  projectInventoryForPrompt: (catalog: unknown) => catalog,
+}));
+
 jest.mock('@bitcode/agent-generics', () => ({
   factoryPTRRAgent: () =>
     async function mockPtrr() {

packages/asset-packs-pipelines/domain/src/__tests__/deposit-ready-to-finish-agent.test.ts

@@ -178,10 +178,16 @@ describe('deposit Discovery lens agents (boundary-mocked PTRR)', () => {
     const out = await runDepositDepositorySearchAgent(DEPOSIT_INPUT, exec);
 
     expect(out.success).toBe(true);
-    expect(out.guidance).toEqual(MOCK_DEPOSITORY_GUIDANCE);
-    expect(out.guidance.underservedTopics).toEqual(['idempotent invoice replay']);
+    // Host enriches guidance with searchQueries and may merge tool underservedTopics.
+    expect(out.guidance.summary).toBe(MOCK_DEPOSITORY_GUIDANCE.summary);
+    expect(out.guidance.likelyReadTopics).toEqual(MOCK_DEPOSITORY_GUIDANCE.likelyReadTopics);
+    expect(out.guidance.underservedTopics).toEqual(
+      expect.arrayContaining(['idempotent invoice replay']),
+    );
+    expect(Array.isArray(out.guidance.searchQueries)).toBe(true);
+    expect(out.guidance.searchQueries!.length).toBeGreaterThan(0);
     expectNoEnvelopeLeak(out);
-    expect(exec.get('discovery', 'depositorySearch')).toEqual(MOCK_DEPOSITORY_GUIDANCE);
+    expect(exec.get('discovery', 'depositorySearch').summary).toBe(MOCK_DEPOSITORY_GUIDANCE.summary);
   }, 30000);
 
   it('inherent-regurgitation: typed regurgitation result + discovery:inherentRegurgitation store', async () => {
@@ -196,15 +202,17 @@ describe('deposit Discovery lens agents (boundary-mocked PTRR)', () => {
     expect(exec.get('discovery', 'inherentRegurgitation')).toEqual(MOCK_REGURGITATION);
   }, 30000);
 
-  it('a minimal model response ({summary} only) satisfies the lens schemas without a retry storm', async () => {
+  it('a minimal model response ({summary} only) satisfies the guidance schema without a retry storm', async () => {
     setBoundaryLLMOutput({ guidance: { summary: 'Minimal demand guidance.' } });
     const exec = new Execution('discovery-node');
 
     const out = await runDepositDepositorySearchAgent(DEPOSIT_INPUT, exec);
 
     // One required string; every array dimension is optional — the schema is
-    // satisfiable by the leanest well-formed model response.
-    expect(out.guidance).toEqual({ summary: 'Minimal demand guidance.' });
+    // satisfiable by the leanest well-formed model response. Host still attaches
+    // searchQueries for the Depository search tool.
+    expect(out.guidance.summary).toBe('Minimal demand guidance.');
+    expect(Array.isArray(out.guidance.searchQueries)).toBe(true);
     // No schema-driven retry storm: a straight PTRR run is 4 steps x 3 failsafes
     // x 3 generations = 36 LLM calls; stay comfortably at/below that baseline.
     expect(getBoundaryLLMCalls().length).toBeGreaterThan(0);
@@ -246,7 +254,10 @@ describe('deposit Discovery lens agents (boundary-mocked PTRR)', () => {
     setBoundaryLLMOutput({ guidance: MOCK_DEPOSITORY_GUIDANCE });
     const exec = new Execution('shared-node');
     await runDepositDepositorySearchAgent(DEPOSIT_INPUT, exec);
-    expect(exec.get('discovery', 'depositorySearch')).toEqual(MOCK_DEPOSITORY_GUIDANCE);
+    expect(exec.get('discovery', 'depositorySearch').summary).toBe(MOCK_DEPOSITORY_GUIDANCE.summary);
+    expect(exec.get('discovery', 'depositorySearch').underservedTopics).toEqual(
+      expect.arrayContaining(['idempotent invoice replay']),
+    );
 
     // ...and the Implementation agent, reading the same node, threads that
     // guidance (summary + underservedTopics) into its synthesis prompt.
@@ -321,13 +332,15 @@ describe('discovery conditional runtime registry roster', () => {
     };
   }
 
-  it('deposit mode registers exactly the three deposit lenses and never touches the read roster', () => {
+  it('deposit mode registers the three Discovery agents (native keys + stable aliases), not the read roster', () => {
     const registry = recordingRegistry();
     registerDiscoveryAgents(registry, 'deposit');
     expect([...registry.registrations.keys()].sort()).toEqual([
       'discovery:codebase-comprehension',
+      'discovery:comprehend-codebase',
       'discovery:depository-search',
       'discovery:inherent-regurgitation',
+      'discovery:search-depository',
     ]);
   });
 

packages/asset-packs-pipelines/domain/src/__tests__/deposit-setup-discovery-agents.test.ts

@@ -90,17 +90,18 @@ const REQUIREMENTS = part(
 );
 
 const PLAN = part(
-  'Plan: combine measurements, LSP signals, file-tree structure, and key file reads to ' +
-    'map capability, structure, and synthesis opportunities.',
+  'Plan: combine absolute measurements, LSP signals, file-tree structure, and key file ' +
+    'reads from the sourceCheckoutCatalog to map capability, structure, and synthesis opportunities.',
 );
 const TRY = part(
-  'Try: synthesize the codebase knowledge map using measurements + LSP + tree + key files.',
+  'Try: synthesize the codebase knowledge map — capabilities, knowledge areas, notable ' +
+    'modules, measurementInsights, structureInsights — from measurements + LSP + tree + key files.',
 );
 const REFINE = part(
-  'Refine: ensure the map is source-safe, grounded in provided evidence, and useful for pack synthesis.',
+  'Refine: ensure the map is source-safe, grounded in provided sourceCheckoutCatalog evidence, and useful for pack synthesis.',
 );
 const RETRY = part(
-  'Retry: return a minimal source-safe map grounded in path list and measurements rather than failing.',
+  'Retry: return a minimal source-safe knowledge map grounded in path list and measurements rather than failing comprehension.',
 );
 
 function createPrompt(): Prompt {

packages/asset-packs-pipelines/domain/src/agents/discovery/deposit-codebase-comprehension-agent.ts

@@ -44,10 +44,10 @@ const DepositorySearchOutputSchema = z.object({
 export type DepositReadDemandGuidance = z.infer<typeof ReadDemandGuidanceSchema>;
 
 const IDENTITY = part(
-  'You are the SynthesizeAssetPacks discovery agent searching the Bitcode Depository ' +
+  'You are the SynthesizeAssetPacks Discovery agent that searches the Bitcode Depository ' +
     'for settled AssetPack supply relevant to this deposit synthesis run. Build search ' +
-    'queries from the source checkout catalog, obfuscations, measurements, and demand ' +
-    'context so synthesized packs have high likelihood of future demand. Be source-safe.',
+    'queries from the sourceCheckoutCatalog, obfuscations, checkout measurements, and ' +
+    'demand context so synthesized packs have high likelihood of future demand. Be source-safe.',
 );
 
 const REQUIREMENTS = part(
@@ -60,13 +60,15 @@ const REQUIREMENTS = part(
 );
 
 const PLAN = part(
-  'Plan: from source paths, measurements, obfuscations, and demand context, synthesize ' +
-    'Depository search queries that will retrieve AssetPacks relevant to high-demand synthesis.',
+  'Plan: from sourceCheckoutCatalog paths, measurements, obfuscations, and demand context, ' +
+    'synthesize Depository search queries that retrieve AssetPacks relevant to high-demand synthesis.',
 );
 const TRY = part(
   'Try: produce demand guidance and the searchQueries list the Depository search tool will run.',
 );
-const REFINE = part('Refine: ensure queries and guidance are grounded, demand-aligned, and source-safe.');
+const REFINE = part(
+  'Refine: ensure queries and guidance are grounded in sourceCheckoutCatalog evidence, demand-aligned, and source-safe.',
+);
 const RETRY = part('Retry: return minimal demand guidance and broad searchQueries rather than failing.');
 
 function createPrompt(): Prompt {

packages/asset-packs-pipelines/domain/src/agents/discovery/deposit-depository-search-agent.ts

@@ -33,8 +33,9 @@ export type DepositInherentRegurgitation = z.infer<typeof InherentKnowledgeSchem
 const IDENTITY = part(
   'You are the SynthesizeAssetPacks Discovery agent that contributes model-inherent ' +
     'knowledge for deposit AssetPack synthesis. From your training data, return patterns, ' +
-    'best practices, and domain knowledge useful for this repository. Source-safe: never ' +
-    'quote the repository’s raw source or secrets.',
+    'best practices, and domain knowledge useful for this repository (grounded by ' +
+    'sourceCheckoutCatalog path context for relevance only). Source-safe: never quote ' +
+    'the repository’s raw source or secrets.',
 );
 
 const REQUIREMENTS = part(
@@ -43,10 +44,16 @@ const REQUIREMENTS = part(
     'general and source-safe. Return ONLY {"regurgitation": {...}}.',
 );
 
-const PLAN = part('Plan: identify trained knowledge relevant to this repository domain.');
-const TRY = part('Try: regurgitate relevant knowledge, patterns, best practices, and references.');
-const REFINE = part('Refine: ensure knowledge is relevant, generally-known, and source-safe.');
-const RETRY = part('Retry: return minimal relevant knowledge rather than failing.');
+const PLAN = part(
+  'Plan: identify which of your trained knowledge is relevant to this repository domain.',
+);
+const TRY = part(
+  'Try: regurgitate relevant knowledge, well-known patterns, best practices, and references.',
+);
+const REFINE = part(
+  'Refine: ensure the knowledge is relevant, generally-known, and source-safe.',
+);
+const RETRY = part('Retry: return minimal relevant knowledge rather than failing the regurgitation.');
 
 function createPrompt(): Prompt {
   const prompt = new Prompt();

packages/asset-packs-pipelines/domain/src/agents/discovery/deposit-inherent-regurgitation-agent.ts

@@ -1,11 +1,11 @@
 /**
  * Deposit-mode AssetPack synthesis agent (V48 Gate 3).
  *
- * The deposit lens of the SynthesizeAssetPacks Implementation phase: synthesize
- * reviewable AssetPacks from the DEPOSITOR's repository. Each AssetPack is a
- * completely synthesized artifact = MEASURED PATCH (patch + measurements +
- * metadata). Schema and prompts live in co-located siblings; this file owns
- * the PTRR factory agent, patch-write materialization, and cross-phase stores.
+ * Implementation phase of SynthesizeDepositAssetPacks: synthesize reviewable
+ * AssetPacks from the depositor Host checkout. Each AssetPack is
+ * patch + measurements + metadata. Schema and prompts are co-located siblings;
+ * this file owns the PTRR factory agent, patch-write materialization, absolute
+ * measurement attachment, and cross-phase stores.
  *
  * Default export (run factory path) and `DepositAssetPackSynthesisAgent` remain
  * stable for phase registration and tests.
@@ -34,7 +34,7 @@ const depositPrompt = createDepositSynthesisPrompt();
 export const DepositAssetPackSynthesisAgent = factoryPTRRAgent<any, DepositSynthesisOptions>({
   name: 'DepositAssetPackSynthesisAgent',
   description:
-    'Synthesizes reviewable, source-safe, measured AssetPack candidate options from the depositor repository source (deposit lens).',
+    'Synthesizes reviewable AssetPacks (patch + measurements + metadata) from the depositor Host sourceCheckoutCatalog.',
   outputSchema: depositCandidateSetSchema,
   tools: [],
   prompt: depositPrompt,