FIN Production Parity Program — Stock + Vendors + Customers + Projections + Agentic Hardening

FIN Production Parity Program

Date: 2026-05-16 Status: Active (execution sequencing below) Authority basis: Engineering Spec [§3.1 schemas], [§3.4 mixed-section model], [§3.5 confidence stratification], [§11.5 doc-CQRS], [§11.6 snapshots], [§11.7 incremental embedding], [§13.6 cite-then-claim], [ADR-006 two-layer rendering], [TZ-5 living intelligence design], [project_living_wiki_drill_through_vision memory], [project_world_class_search_drill_through memory], [feedback_tenant_intel_sovereignty memory]

---

0. Headline

16 parts (A–P), each independently shippable, organized in 3 strata + Discipline:

TRACKER: FIN_PRODUCTION_PARITY_TRACKER_2026-05-16.md — per-task severity (P0–P3), state, progress, owner, dependencies, and required proof artifacts. A task is not complete until its proof artifact is attached in the tracker. The plan describes WHAT; the tracker enforces HOW MUCH IS REALLY DONE. 137 discrete tasks identified across A–P.

1. Foundation (A–F): Stock parity + T7 worker loop + T15 entity renderers + proof/QC/photos + projection parity audit + frontmatter hardening
2. Optimization (G, H): Agentic system hardening + Memory optimization
3. Specialization → Apex (I–O, M): Briefing refinement & personalization → MCP tool & projection index optimization → Sales/Buyer team world-class profiles → Historical data integration → Role-augmented drill-throughs → External market data sources → Data fusion engine + proof package excellence (apex)
4. Discipline (P): Data quality + accessibility + serving SLOs across everything above — production discipline that makes the corpus trustworthy

Rough total: 125–155 hours of focused Claude session work + 8–14 hours of Rob’s CF/UI/sourcing/budget work, sequenced across 19 sessions over ~3.5 weeks (5/16–5/31).

Deliverable is production parity + hyper-specialization for the Tenant Zero corpus + the projection systems serving it + the agentic surface presenting it — across both FIN Central (universal Plane 3) and Nathel (operational overlay) — with cross-source data fusion that produces world-class company projections, proof packages, and per-role briefs that actually demonstrate the agentic ERP claim.

The diff result that drives Foundation: Nathel currently holds 1,203 lots / 540 SKUs / 142 vendors / 256 brands. Vault has 87 commodity profiles + 244 variety profiles + 0 vendor profiles + 0 customer profiles. Coverage:

• ~691 of 965 SKUs (72%) map to existing commodity profiles
• ~15–25 real commodity gaps (apricot, bok_choy, brocolini, chayote, chives, collard_greens, kohlrabi, marjoram, mustard_greens, parsnip, shallot, star_fruit, yucca_root, lemongrass, anise/fennel, dandelion, broccoli_rabe, bay_leaf)
• 0% vendor coverage — every active vendor needs a profile
• 0% customer coverage — pending sales reports

The existing scaffolding that Specialization builds on:

• 17 briefing files + voice-briefing DO + Slack templates + M-19 personalization landed (Part I refines, doesn’t rebuild)
• 511 MCP tools + role-tool-catalog.ts + capability-registry.ts (Part J curates)
• 7 approved projections + 8 strategy modules (Part J extends to 15+)
• Vendor + customer parser/transformer/validator/loader in packages/migration/ (Part C wraps as renderers)
• QC narrative card + photo provider + R2 upload + vision tool (Part D + L wire historical narratives)
• 15-subtype signal.* event family (Part L adds historical importers as signal.* sources)

---

1. Part A — Stock Parity Backfill (Commodities)

Scope

• Render the ~15–25 missing commodity profiles
• Re-run knowledge-forge bulk-render with widened SKIP_LIST tightened
• Verify 95%+ inventory SKU coverage post-run

Deliverables

1. scripts/audit/inventory-commodity-gap-report.ts — runs the diff between any inventory snapshot CSV and vault commodity coverage
2. New commodity profile docs for the gap list (committed to fin-central-intranet)
3. Gap report doc at docs/audits/STOCK_COMMODITY_PARITY_2026-05-16.md

Acceptance criteria

• ≥95% of inventory SKUs map to a vault commodity profile (any stem matches an existing slug)
• Each new commodity profile renders with ≥3 sections (Identity & Botany, Post-Harvest, Market Intelligence at minimum)
• Diff report committed to docs/audits/

Dependencies

• Existing commodity_profile_renderer v1.0.0 ✓
• Existing bulk-render-knowledge-forge.ts ✓
• Inventory CSV input (provided by Rob)

Estimate

2-3 hours Claude. Most of the gap is data-not-in-knowledge-forge — needs hand-curated GDF stub OR knowledge-forge enrichment task to fill.

---

2. Part B — T7 Doc Projection Pipeline Worker Loop + E2E

Scope

Close out T7. The schema, parser, upsertDoc, webhook, and migrations 049/050 already exist. What’s missing:

• Apply migrations 049/050 to fin-central-prod
• Implement entity-doc-renderer-worker.ts body (currently interface-only)
• Wire vault webhook to actually invoke worker on doc.indexed events
• E2E test: vault commit → fin-central-prod row visible in <60s
• Per-entity-type renderer dispatch (commodity / variety / vendor / customer / region / etc.)
• Wikilink resolver (entity_doc_projection lookup + anchor fallback per ADR-004)

Deliverables

1. Migration 049/050 applied to fin-central-prod (verified via neon__run_sql)
2. entity-doc-renderer-worker.ts implementation w/ rebuild queue consumer (status='stale' → render → status='current')
3. routeRenderer() dispatch with registered renderers (commodity, variety initially; vendor/customer/region in Part C)
4. packages/agent/src/wikilink-resolver/index.ts — typed wikilink resolution
5. E2E integration test (Vitest) hitting real fin-central-prod test branch
6. CLI: pnpm cli replay-projection --projection=entity_doc_projection --tenant=fin-central works

Acceptance criteria

• Push a test doc to fin-central-intranet → within 60s a row exists in knowledge.domain=doc, key=<slug>, tenant_id='fin-central' AND entity_doc_projection.status='current' AND chunks in operational_memory
• Replay command rebuilds entity_doc_projection from scratch deterministically
• [[commodity:apple]] resolves to entity_doc_projection row → returns doc
• [[variety:hass]] falls back to commodity_profile_avocado#hass anchor when no standalone exists

Dependencies

• Migrations 049/050 written ✓
• Vault webhook handler scaffolded ✓
• DocContent schema ✓
• commodity_profile_renderer ✓

Estimate

6–8 hours Claude. Worker loop + dispatch + wikilink resolver + E2E test.

---

3. Part C — T15 Renderers (Vendor + Customer + Variety + Region)

Scope per ADR-006 two-layer pattern

Vendor — split:

• Universal layer (FIN Central): vendor entity profile with name, brands, NAICS code, region of operation, public ownership history, GS1 GLN if known, public certifications. Renderable from public/external data + tenant-contributed (anonymized) brand mappings. Lives in fin-central-intranet/docs/entity_profiles/vendors/<vendor_slug>.md.
• Tenant overlay (Nathel): vendor performance metrics (on-time %, defect rate, avg load score, payment terms, vendor_number, last contract date). Tenant-private. Lives in nathel-intranet/docs/vendors/<vendor_slug>_overlay.md.

Customer — tenant-only:

• By nature relationship_data not universal — lives ONLY in nathel-intranet/docs/customers/<customer_slug>.md. Universal layer would violate sovereignty.
• Sourced from sales reports. Includes: customer_id, primary contact, account history, top SKUs, payment terms, demand pattern, agent notes.

Variety — already exists:

• 244 variety profiles already rendered. Need to wire the renderer behind routeRenderer() dispatch (Part B) so future Tier 2 additions auto-render.

Region — new:

• Universal Plane 3. Source: knowledge-forge region data + USDA crop reports + scraped harvest comms.
• Sections: geography, crop calendar, FSMA 204 lane status, primary commodity exports, common transit corridors, current weather/seasonal flags.
• Lives in fin-central-intranet/docs/entity_profiles/regions/<region_slug>.md.

Deliverables

1. packages/mcp-server/src/ingestion/renderers/vendor-profile-renderer.ts (universal Plane 3)
2. packages/mcp-server/src/ingestion/renderers/vendor-overlay-renderer.ts (tenant)
3. packages/mcp-server/src/ingestion/renderers/customer-profile-renderer.ts (tenant only)
4. packages/mcp-server/src/ingestion/renderers/region-profile-renderer.ts (universal)
5. packages/mcp-server/src/ingestion/renderers/variety-profile-renderer.ts (extracted from bulk-render-knowledge-forge.ts adapter logic — make it reusable)
6. Test suite (Vitest) per renderer: 10–15 tests each, schema/composition/determinism/snapshot
7. Bulk seed scripts: bulk-render-vendors.ts, bulk-render-customers.ts (when sales reports land)
8. Registration in routeRenderer() dispatch (Part B)

Acceptance criteria

• Each renderer passes Vitest contract tests (schema validation + determinism + snapshot)
• Bulk-render produces 142 vendor profiles in fin-central-intranet
• Sample 5 vendors verified for: brand list correct, NAICS plausible, no tenant-private fields leaked into universal layer
• Region renderer covers ≥10 regions (CA Central Valley, MX Sonora, MX Uruapan, FL Plant City, GA Vidalia, ID Idaho potato country, NY Hudson Valley, NJ South Jersey, Chile Valparaiso, Peru Ica)

Dependencies

• Existing packages/migration/src/parsers/vendor-parser.ts ✓
• Existing packages/migration/src/parsers/customer-parser.ts ✓
• Sales reports for customer profiles (pending — Rob to source)
• Vendor data in PO reports + inventory + intel@ buyers org box (existing parsers in packages/shared/src/parsers/produce-pro/)

Estimate

8–10 hours Claude. Per-renderer ~1.5–2h. Bulk seed scripts ~1h each. Tests ~30min each.

---

4. Part D — Proof Package + QC Inspection Projection + QC Photo Pipeline

Scope

proof_package projection (per spec §11.6 snapshot pattern):

• New projection table OR new doc_kind=proof_package with snapshot_period + immutable hash
• Generated weekly (W19, W20, …) and monthly (M05, M06, …)
• Bundles: events ingested, inspections completed, photos attached, lots received, sales generated, vendor scores, doc-CQRS rebuild stats — all with citations
• Output: nathel-intranet/docs/proof/<period>/proof_package.md — federal-grade audit artifact

qc_inspections_projection (migration 048 — already applied):

• Consumer wiring: write-side already exists in events; read model qc_inspections_projection exists
• Need: handler that materializes projection on qc.inspection_completed events
• Need: doc-render path so each inspection becomes a citable entity_profile (inspection_profile_<inspection_id>)
• Acceptance criteria from program §3 Day 3 T5

QC photo pipeline (existing code: analyze-qc-photo.ts, r2-photo-upload.ts, qc-photo-vision.ts, qc-photo-pipeline.ts blueprint):

• E2E verify: photo capture → R2 upload → artifact.uploaded event → vision analysis → qc.photo_analyzed event → linked to inspection
• Verify customer-visibility hard rules apply on render (no vendor names, no cost annotations on customer-facing photo galleries)
• Mobile-first PWA capture (per project_mobile_is_primary_for_qc memory)

Deliverables

1. proof_package projection design doc + migration (if needed) + handler + renderer
2. qc_inspection_profile renderer + worker registration
3. QC photo E2E test (synthetic photo → upload → analyze → link → render in inspection profile)
4. Customer-visibility hard-rule verification suite (negative tests: tenant photo with vendor watermark fails customer-portal render)

Acceptance criteria

• Weekly proof_package generated for W19 with ≥5 inspections, ≥10 photos, ≥3 vendor scores, ≥1 lot-completion-trace
• A new qc.inspection_completed event materializes both:
  • Row in qc_inspections_projection (queryable via list endpoint)
  • Doc at inspection_profile_<id>.md in nathel-intranet
• Photo upload from inspector PWA → visible in inspection profile within 30s
• Customer-portal render of inspection photo strips vendor name + cost basis (verified by negative test)

Dependencies

• T7 worker loop (Part B) for entity_doc_projection wiring
• Vendor + Customer renderers (Part C) for photo/lot context

Estimate

6–8 hours Claude. proof_package design + impl ~3h, qc_inspection wiring ~2h, photo E2E ~2h, hard-rule tests ~1h.

---

5. Part E — All-Projection-Parity Audit

Scope

Per Rob’s spec: “all projection types should have parity” across FIN Central + Nathel. Currently the registry has 7 projections (lot_status, pulse_admin_active_holds, actor_pulse_aggregate, kb_health_summary, system_health_snapshot, doc_backlink_projection, entity_doc_projection). Audit each for:

• ✅ Migration applied to BOTH fin-central-prod AND nathel-prod
• ✅ Handler/projector wired
• ✅ Replay command works (pnpm cli replay-projection --projection=X --tenant=Y)
• ✅ RLS policies present and forced
• ✅ Source-of-truth event family documented
• ✅ Read-API endpoint exists (MCP tool OR REST route)
• ✅ Test coverage ≥80%

Deliverables

1. docs/audits/PROJECTION_PARITY_AUDIT_2026-05-16.md — full table per projection per tenant
2. Gap-fix migrations / handler completions where audit reveals partials
3. Replay smoke test bundle: pnpm cli replay-projection-smoke-test runs all 7 projections against test branch

Acceptance criteria

• All 7 projections green on every column for both tenants
• Replay smoke test exits 0
• Audit doc committed

Dependencies

• T7 worker loop done (entity_doc_projection wiring)
• Migrations 049/050 applied to fin-central-prod

Estimate

3–4 hours Claude. Mostly audit + gap-fix; existing infra is solid.

---

6. Part F — Frontmatter + Provenance Hardening

Scope

Per ADR-003 + Rob’s spec: every fin-agentic AND knowledge-forge planning/build doc needs:

• Full DocContent frontmatter (per Engineering Spec §3.1)
• source_attribution[] per spec §3.1
• Wikilink references where applicable
• Migration to fin-central-intranet vault per ADR-003

Inventory:

• fin-agentic/docs/ 15 canonical docs (already copied per TZ-1; frontmatter incomplete per FRONTMATTER_AUDIT)
• fin-agentic/docs/handoffs/ ~30 handoff docs (frontmatter likely thin)
• fin-agentic/docs/runbooks/ 2 runbooks (Phase 1 + Phase 5)
• knowledge-forge/AGENTS.md, HANDOFF.md, README.md, CODEX-PROMPT-*.md (~10 docs, currently no frontmatter)

Deliverables

1. scripts/audit/frontmatter-bulk-fix.ts — applies missing fields conservatively, preserves existing
2. Run script across both repos (output to vault)
3. Updated docs/audits/FRONTMATTER_AUDIT_2026-05-16.md showing 100% compliance
4. fin-central-intranet vault now mirrors all canonical docs with full frontmatter

Acceptance criteria

• Every md file in fin-agentic/docs/, knowledge-forge/*.md, and the vault has minimum 7 required DocContent fields (schema_version, doc_id, doc_kind, title, slug, source_attribution, lifecycle_status)
• Vault structure mirrors target per Phase 5 Runbook §2.2 + §6.4 Doc Index
• Lint check pnpm lint:frontmatter passes

Dependencies

• DocContent schema ✓

Estimate

3–4 hours Claude. Bulk script ~1h, run + spot-check ~2h, lint integration ~30min.

---

7. Part G — Agentic System Hardening

Scope

Per Rob’s spec: “harden and optimize the agentic system access and use of the new data formats and test the presentation of it in the ui/ux and the response improvement/quality of the agentic responses and the relevance of the responses regarding context.”

Three tracks:

G.1 — Tool surface for new formats

• New MCP tools / extend existing:
  • get_entity_profile(domain, key, tenant_id?, snapshot?) — reads entity_doc_projection + composes universal + overlay if both exist
  • walk_provenance(claim_anchor, doc_id) — chains claim → fact_citations → events
  • get_doc_graph(doc_id, depth) — uses doc_backlink_projection
  • search_entity_profiles(query, entity_type?, tenant_id?) — embeddings + filter
• Update tool catalog registration + role-based curation lists

G.2 — UI/UX presentation

• Drill-through composer plugin (Quartz fin-living-intel-composer) per TZ-5 §5.1
• Side-dock ambient intelligence per TZ-5 §5.2
• Role-aware section ordering per TZ-5 §5.1 ROLE_PRESETS
• Mobile-first verification (per project_mobile_is_primary_for_qc memory)
• Playwright tests per role group across staging fin-demo

G.3 — Response quality + context relevance

• Eval suite: 30 representative produce questions across roles (sales, QC, warehouse, foreman, exec)
• A/B vs structured-only baseline per program §10 acceptance criterion
• Gradeboard delta target: +0.5 (current 4.01 → 4.51 minimum)
• Citation correctness: every agent response cites ≥1 fact_citation
• Context relevance: actor’s current role + zone + open task surfaces the right entity profiles

Deliverables

1. 4 new MCP tools registered
2. Quartz composer plugin (paired with Phase 5 §3 Rob CF Pages work)
3. Side-dock module
4. Playwright eval suite at tests/playwright/agentic-presentation.spec.ts
5. docs/audits/AGENTIC_RESPONSE_QUALITY_2026-05-16.md — eval results + gradeboard delta

Acceptance criteria

• Drill-through page for /commodities/avocado renders Universal + Overlay layers, role-aware ordering applied
• Salesman eval question “We just got a load of seedless mini watermelons from Sonora…” cites ≥3 facts to events/knowledge per program §10
• Gradeboard ≥4.51

Dependencies

• Parts B, C, D complete (data needs to be there to query)
• Phase 5 §3 + §4 done (Rob — CF Pages + Access)

Estimate

8–10 hours Claude. Tools ~3h, composer ~3h, side-dock ~1h, eval suite ~2h, gradeboard runs ~1h.

---

8. Part H — Memory Optimization

Scope

Per Rob’s spec: “optimize the memory management systems of the overall system and the agentic system.”

H.1 — actor.memory hot-path

• Read patterns: actor.memory.context queried on every tool call. Currently scans whole JSONB. Add: indexed JSONB paths for current_role, current_zone, current_task_id, recent_actions[-5].
• Write patterns: append-only recent_actions with TTL pruning (keep last 50).

H.2 — operational_memory chunk pruning

• Current: every doc_indexed event creates chunks; never deleted
• Add: chunk.archived event when source doc archives
• Add: cold-storage tier for chunks with no access in 90 days
• Migration to enable

H.3 — Embedding cache layer

• Cache embedding lookups by content_hash (per spec §11.7)
• Avoid re-embedding when frontmatter-only changes detected
• Hit rate target: ≥80% on incremental rebuilds

H.4 — Token budget per tool invocation

• Tool result size limit (current: unlimited → can blow context)
• Max return: 4KB per tool call by default; pagination cursor for larger
• Per-tool override allowed

H.5 — Session journal compaction

• Per CLAUDE.md session-management rules: handoffs at 20% context
• Add: auto-handoff trigger when context drops below 25%
• Memory file rotation when MEMORY.md exceeds 30KB

Deliverables

1. JSONB indexes on actors.memory paths (migration)
2. Chunk archival policy (migration + handler)
3. Embedding cache layer in packages/shared/src/embedding-cache.ts
4. Token budget enforcement in MCP tool wrapper
5. Auto-handoff hook
6. docs/audits/MEMORY_OPTIMIZATION_2026-05-16.md — before/after metrics

Acceptance criteria

• actor.memory queries: avg latency <50ms (from current ~150ms estimate)
• Embedding cache hit rate ≥80% on test corpus
• 90% of tool results fit in 4KB; pagination available for larger
• Auto-handoff fires at 25% context with no data loss
• Memory.md rotation working (verified by synthetic 35KB test)

Dependencies

• None — independent track, can run parallel with other Parts

Estimate

4–6 hours Claude. Indexes ~1h, chunk archival ~1h, embedding cache ~1.5h, token budget ~1h, auto-handoff ~30min, audit doc ~30min.

---

9. Part I — Briefing Refinement & Personalization

Scope

The existing briefing system is substantial and partially-personalized; it needs to be plugged into the new Tenant Zero data spine and pushed further on personalization.

Existing inventory (do NOT rebuild — refine + integrate):

• packages/shared/src/buyer-brief.ts (FINN-061) — buyer intel: price trends, seasonal alerts, vendor scores, action items
• packages/shared/src/shift-brief.ts (FINN-054) — day/night shift metrics + pricing actions
• packages/shared/src/unified-brief.ts
• packages/agent/src/blueprints/morning-brief.ts, wf-brief-001.ts
• packages/mcp-server/src/tools/{get-brief,generate-shift-brief,get-briefing-content,query-briefing-inbox,start-voice-briefing}.ts
• packages/mcp-server/src/do/voice-briefing-session-do.ts (Durable Object voice session)
• packages/workspace/src/components/cards/{BriefCard,VoiceBriefingCard}.tsx
• packages/mcp-server/src/admin/handlers/scheduled-actor-briefs.ts
• packages/shared/src/slack/templates/brief-block.ts
• M-19 personalization landed 2026-04-06 — actor.memory.briefing_preferences (preferred_mode, prioritized_sections, confidence_floor, per-section limits, detail-level greeting)

Refinement targets:

1. Data-source upgrade — every brief generator reads from entity_doc_projection + walk_provenance instead of ad-hoc queries; benefits from Part B/C/D data spine
2. Personalization deepening — extend actor.memory.context schema:
   • physical_location: warehouse_zone | remote | hybrid
   • supply_chain_position: receiving | qc | picking | sales | dispatch | exec | gm
   • specialties: top commodities, top customers (sales), top vendors (buyer)
   • account_portfolio: customer/vendor list with weight (sales/buyer)
3. Per-role brief variants (currently buyer + shift exist):
   • gm_brief — daily margin position, top opportunities, vendor scorecards, customer health, market position vs Hunts Point benchmark
   • sales_rep_brief — per-rep account portfolio, today’s calls, customer demand signals, pricing leverage notes, recent loss-recovery opportunities
   • qc_inspector_brief — today’s expected loads, vendor patterns, pending re-inspections, defect-history-flagged commodities
   • foreman_brief — team roster, dock assignments, current shift position, holds blocking dispatch
   • exec_brief — week’s operational position, fill rate, margin vs market, vendor risk flags, customer churn signals
4. EIF live-freshness wiring — briefs subscribe to signal.* events for sub-5min freshness on pricing + arrivals
5. Cite-then-claim discipline — every brief item carries fact_citations[] per §13.6
6. Voice + Slack + Workspace + Email parity — same brief content, role-appropriate formatting per channel

Deliverables

1. packages/shared/src/schemas/actor-memory.ts — extended context shape (physical_location, supply_chain_position, specialties, account_portfolio)
2. 5 new brief shapes: gm-brief.ts, sales-rep-brief.ts, qc-inspector-brief.ts, foreman-brief.ts, exec-brief.ts (mirror buyer-brief.ts pattern — pure functions, no DB)
3. 5 new tools: generate-{gm,sales-rep,qc-inspector,foreman,exec}-brief
4. packages/agent/src/blueprints/per-role-brief.ts — orchestrator that dispatches to the right shape based on actor role + context
5. EIF subscriber: brief-staleness-mapper that marks briefs stale on relevant signal.* events
6. Brief renderer at packages/mcp-server/src/ingestion/renderers/brief-renderer.ts — produces the brief AS a doc projection (brief_<role>_<actor_id>_<date>.md) so it lands in the vault and is queryable
7. Test suite: per-role brief contract tests + personalization tests + freshness tests

Acceptance criteria

• Each role’s brief renders in <2s with at least 5 fact_citations per brief
• Personalization actually changes content: a salesman brief shows their accounts; a different salesman sees different accounts
• Voice + Slack + Workspace render the same source brief in role-appropriate format
• Brief becomes stale within 60s of a relevant signal.* event being emitted
• Briefs land in vault as docs (citable, searchable, audit-trailable)

Dependencies

• Part B (T7 worker loop — for brief→doc projection)
• Part C (entity profiles — for citation targets)
• Part D (qc_inspection projection — for QC brief)
• Existing buyer/shift/voice briefing code ✓

Estimate

6–8 hours Claude. 5 brief shapes ~3h, tools+blueprint ~2h, EIF wiring ~1h, brief renderer + tests ~2h.

---

10. Part J — MCP Tool & Projection Index Optimization

Scope

MCP tool surface today: 511 tools. That’s almost certainly bloated, redundant, and unevenly role-scoped. Need a tool-curation pass that produces a tight, role-curated catalog the agent can actually navigate efficiently.

Projection index today: 7 projections in approved registry (lot_status, pulse_admin_active_holds, actor_pulse_aggregate, kb_health_summary, system_health_snapshot, doc_backlink_projection, entity_doc_projection) + 8 projection strategies in code (financial-reconciliation, inbound-cost-layering, order-fulfillment, paca-tracking, qc-inspection, rcv-load-receipt, van-count, vendor-onboarding). Need to add high-value cross-cutting projections that drive the personalized briefings + the world-class sales/buyer profiles.

J.1 — MCP Tool Index Optimization

1. Audit 511 tools against:
   • Redundancy (multiple tools doing same thing — collapse to one)
   • Deprecated (tools no replaced — archive)
   • Role-scoping (tool accessible to right role only)
   • Return-shape consistency (every generation tool §13.6 structured)
   • Token budget (tool result fits in budget per Part H)
   • Capability tagging (tool tagged with capability per capability-registry.ts)
2. Target: ~80–120 tools across 6 role-curated catalogs
3. Output: each tool documented with one-line purpose + role-list + capability + return-shape contract
4. Migrate stale tools to packages/mcp-server/src/tools/_archive/ (kept for reference, not exposed)

J.2 — Projection Index Optimization

Add high-value projections (each becomes a doc_kind=projection in the vault for full provenance):

New projection	Source events	Refresh	Use case
customer_360	sales.* + comms.* + signal.* + qc.inspection_completed (where customer linked)	5min debounce	Sales rep “what’s this customer’s full state”
vendor_360	lot.received + qc.inspection_* + signal.vendor_quote_observed + payment.*	5min debounce	Buyer “what’s this vendor’s full state”
commodity_360	already partially covered by entity_doc_projection commodity_overlay; promote to first-class projection	event-driven	Drill-through living wiki (TZ-5 §3.2)
location_intel	weather + harvest signals + region commodity exports + transit corridors	hourly	”What’s the supply position in MX Sonora this week”
supply_chain_position	inbound + sellable inventory + outbound demand + on-order	15min	”Where in the chain is each commodity right now”
daily_company_pulse	aggregates all above + briefings + proof_package elements	1x/day	Exec view; foundation for proof packages
sales_team_dashboard	per-rep aggregates + customer_360 fan-in	1x/hr	Sales floor wallboard
buyer_team_dashboard	per-buyer aggregates + vendor_360 fan-in	1x/hr	Buyer desk wallboard

Each new projection:

• Migration adds a CQRS table (transactional or fire-and-forget per data criticality)
• RLS forced
• Replay command in registry
• Handler in packages/shared/src/projections/strategies/
• Doc-projection wrapper so it’s queryable as markdown via the vault

Deliverables

1. docs/audits/MCP_TOOL_INDEX_AUDIT_2026-05-16.md — full inventory + curation plan + role-catalog tables
2. packages/mcp-server/src/tools/_archive/ directory with deprecated tools moved
3. Updated role-tool-catalog.ts with curated per-role lists
4. 8 new projections (migrations + handlers + tests + registry entries)
5. docs/projections/PROJECTION_CATALOG_2026-05-16.md — updated catalog reflecting all 15 projections (7 existing + 8 new)
6. Doc-projection wrapper for each so each renders into vault

Acceptance criteria

• Tool count post-curation: 80–120
• Each role’s curated catalog: ≤30 tools, every tool has one-line purpose + capability + return-shape contract
• All 8 new projections: migration applied to both tenants, handler tested, replay command works
• Each new projection visible in vault as a queryable doc

Dependencies

• Part B (T7 worker loop — for projection→doc wrapper)
• Part C (entity renderers — for vendor_360 / customer_360 composition)
• Part E (parity audit — does Part J’s new projections too)

Estimate

8–10 hours Claude. Tool audit ~3h, curation + archive ~2h, 8 new projections ~5h.

---

11. Part K — Sales & Buyer Team World-Class Profiles

Scope

Per Rob: “produce world class sales and buyers profile projections that are hyper specialized for the tenant buying team and sales team.”

These are NOT the same as customer_360 or vendor_360 (which are entity-centric). These are team-centric views — what does the sales team see? What does the buyer team see? Each rep / buyer’s personal view, then the team rollup.

K.1 — Sales Rep Profile + Sales Team Dashboard

Per-rep profile (sales_rep_profile_<actor_id>.md):

• Account portfolio (their customers with weight + tier + last contact)
• Today’s call list (auto-prioritized by demand signal + customer health + opportunity score)
• Quota progress (week, month, quarter)
• Pricing leverage notes per customer (margin headroom, price elasticity, last sale context)
• Win/loss patterns (which commodities, which customers, which competitors)
• Top 5 opportunities (by expected value × probability)
• Customer health flags (churn risk, AR aging, satisfaction signal)
• Specialty knowledge (commodities they own deepest; what they’re known for)
• Coaching cues from GM brief (what to push this week)

Sales team dashboard (sales_team_dashboard.md):

• Team quota vs progress
• Customer-portfolio coverage map (any orphan customers? any over-concentration?)
• Hot opportunities across team
• Lost deals this week (root cause)
• Cross-rep collaboration suggestions (rep A has customer X who needs commodity Y; rep B specializes in Y)

K.2 — Buyer Profile + Buyer Team Dashboard

Per-buyer profile (buyer_profile_<actor_id>.md):

• Vendor portfolio (their vendors with weight + tier + relationship strength)
• Today’s procurement list (auto-prioritized by demand signal + market position + harvest window)
• Open contracts (pending negotiations, expiring contracts, optionality)
• Market position per commodity (Nathel cost vs Blair benchmark vs FOB)
• Pricing leverage per vendor (volume share, payment-terms cushion, alt-vendor availability)
• Hedging notes (long positions, short positions, basis risk)
• Savings achieved (vs benchmark, vs spot, vs prior period)
• Specialty knowledge (commodities they own deepest)
• Coaching cues from GM (what to lock down, what to walk away from)

Buyer team dashboard (buyer_team_dashboard.md):

• Team coverage map per commodity (any commodity with no primary buyer? over-concentration?)
• Market position summary (margin vs Hunts Point benchmark)
• Expected arrivals (next 7 days)
• Hold-blocking risks
• Vendor relationship health
• Cross-buyer collaboration (buyer A needs commodity X for unusual customer Y; buyer B has the supplier line)

K.3 — Specialization Layer

Per Rob’s “hyper specialized for the tenant buying team and sales team” — the profiles MUST encode:

• Tenant physical location — Hunts Point NY, peer market dynamics, regional customer base
• Supply chain position — wholesale distributor (Tier 2 in chain: vendor → distributor → retail/foodservice)
• Operational position — receiving/holding/dispatching cold-chain produce; daily cycle (3pm rollover per project_pp_day_rollover memory)
• Local market intelligence — Hunts Point market trades, peer-distributor signals, NY-metro foodservice + retail customer base

Each profile renderer reads tenant config + actor.memory.context + signal.* feed + entity profiles. Output = hyper-personalized.

Deliverables

1. packages/mcp-server/src/ingestion/renderers/sales-rep-profile-renderer.ts
2. packages/mcp-server/src/ingestion/renderers/sales-team-dashboard-renderer.ts
3. packages/mcp-server/src/ingestion/renderers/buyer-profile-renderer.ts
4. packages/mcp-server/src/ingestion/renderers/buyer-team-dashboard-renderer.ts
5. Tenant config schema extension: tenant.physical_location, tenant.supply_chain_position, tenant.local_market_intel_sources
6. Actor.memory.context extensions per Part I §2 (physical_location, supply_chain_position, specialties, account_portfolio)
7. Bulk seed scripts to render initial profiles for current Nathel sales reps + buyers
8. Tests: each renderer + team-vs-rep coherence test (team dashboard sums correctly across reps)

Acceptance criteria

• Sales rep profile for Nathel rep R1 ≠ Nathel rep R2 (verifies personalization)
• Buyer profile cites at least 5 fact_citations from real events
• Team dashboard math checks out (team quota = sum of rep quotas)
• Drill-through from team dashboard → rep profile → customer/vendor 360 → events all work

Dependencies

• Part C (customer + vendor renderers + bulk render)
• Part J.2 (customer_360, vendor_360, sales_team_dashboard, buyer_team_dashboard projections)
• Sales report data (Rob to source)

Estimate

6–8 hours Claude. 4 renderers ~4h, schema extensions ~1h, bulk seeds + tests ~2h.

---

12. Part L — Historical Data Integration

Scope

Per Rob: “I recently extracted a lot of historical intel from teams chats, gm pricing and market notes and memos, salesmen ground truth pricing/hunts point market truth, and historical qc inspection narratives. I didnt get the associated qc inspection photos yet but there is a graph with that ties the photos to the inspections and narratives. We need to be sure to leverage that historical data also.”

L.1 — Historical source inventory (Rob to confirm exact file locations)

Source	What	Likely volume	Status
Teams chat extraction	Internal ops chat history (vendor calls, customer comms, intra-day pricing decisions)	~thousands of msgs	Extracted; location TBD
GM pricing notes	Daily / weekly market memos (margin position, push/pull recommendations)	~hundreds	Extracted; location TBD
GM market notes/memos	Periodic market commentary (seasonal outlook, vendor behavior, customer trends)	~dozens	Extracted; location TBD
Salesmen ground truth pricing	Per-rep observed selling prices, customer reactions, competitive intel	~thousands of records	Extracted; location TBD
Hunts Point market truth	Peer-market trade observations, daily floor pricing	~hundreds	Extracted; location TBD
Historical QC inspection narratives	Inspector free-text on past inspections (pre-FIN)	~thousands	Extracted; location TBD
QC inspection photo graph	Relations linking inspections ↔ photos (photos pending)	Graph only	Extracted; photos pending

L.2 — Ingestion path per source

Each historical source maps to existing signal.* event family (per project_signal_event_family memory — 15 closed subtypes):

• Teams chat → signal.teams_message (existing) + classifier (signal.email_classified-style for body_kind + speaker_role)
• GM pricing notes → signal.market_chatter + signal.price_anomaly (where applicable)
• GM market memos → signal.market_chatter (with poster_role=gm)
• Salesman ground truth → signal.price_observation + signal.market_chatter
• Hunts Point market truth → signal.market_chatter (with poster_role=peer_distributor)
• QC inspection narratives → signal.quality_observation (with retroactive_event=true flag)
• Photo-narrative-inspection graph → relations.* events linking artifact_ids when photos arrive

L.3 — Backfill discipline

• Every historical event carries:
  • timestamp: original event time (not ingestion time)
  • ingestion_metadata: { source, extracted_at, retroactive=true, extractor_version }
  • content_hash for dedup
  • actor_id: original actor where known, else system_historical_extractor
• Idempotency: re-running ingestion produces no duplicates (content_hash dedup)
• Provenance: artifact_uploaded events for the source extracts (Teams export file, memo PDFs, etc.)

L.4 — Projection enrichment

Once events backfilled, Part J’s projections re-render with historical context:

• vendor_360 includes historical defect rates, payment patterns, GM-noted reliability
• customer_360 includes historical pricing reactions, salesman notes, churn precursors
• commodity_360 includes seasonal pricing memory, defect-prone vendors per season, historical demand patterns
• Buyer profiles cite GM coaching memos
• Sales rep profiles cite their own historical wins/losses with context

Deliverables

1. packages/mcp-server/src/ingestion/historical/teams-chat-importer.ts
2. packages/mcp-server/src/ingestion/historical/gm-memo-importer.ts
3. packages/mcp-server/src/ingestion/historical/salesman-ground-truth-importer.ts
4. packages/mcp-server/src/ingestion/historical/hunts-point-market-importer.ts
5. packages/mcp-server/src/ingestion/historical/qc-narrative-importer.ts
6. packages/mcp-server/src/ingestion/historical/photo-graph-stitcher.ts (handles QC photo graph; resolves to artifact links when photos arrive)
7. CLI: pnpm cli historical-backfill --source=<source> --dry-run then --apply
8. docs/audits/HISTORICAL_DATA_BACKFILL_2026-05-16.md — manifest of what was ingested + counts + dedup stats

Acceptance criteria

• Each importer is idempotent (re-run produces no duplicates by content_hash)
• All historical events carry retroactive=true + ingestion_metadata
• Vendor scorecards reflect historical data within 1 hour of backfill
• QC inspection profiles surface historical narratives in their “prior_inspections[]” section
• When QC photos arrive, photo-graph-stitcher links them retroactively without re-rendering historical events

Dependencies

• Existing signal.* event family ✓
• Part B (T7 — for projection rebuild after backfill)
• Part C (vendor + customer renderers — for projection enrichment)
• Rob to provide source file locations (TBD)

Estimate

6–8 hours Claude. 6 importers ~4h, CLI + idempotency tests ~2h, backfill + manifest ~2h.

---

13. Part M — Data Fusion Insights & Proof Package Excellence

Scope

Per Rob: “high quality high fidelity company projections that give an accurate operational picture of the tenant and the produce industry that is highly specialized and has unique insights gained from the data fusion.”

This is the destination state — where all the data spine work (A–L) compounds into proof packages and operational projections that actually demonstrate the agentic ERP claim.

M.1 — Cross-source fusion engine

A new module packages/agent/src/fusion/ that composes facts from multiple sources at projection time:

Fusion patterns:

1. Pricing fusion = sales (current customer prices) × inventory (current cost basis) × intel@ (Blair pricing) × historical (last year same week) × peer-market (Hunts Point floor) → recommended action
2. Quality fusion = QC narratives (historical) × photo gallery × inspection outcomes (current) × vendor scorecards × commodity defect-mode data → vendor quality pattern
3. Buyer fusion = GM memos × current arrivals × salesman pricing × customer demand → procurement recommendations
4. Supply position fusion = inbound on-order × sellable inventory × outbound commitments × harvest signals (region) × transit ETAs → fill-rate forecast + risk flags
5. Margin fusion = sell price × cost basis × shrink × handling cost × payment terms → contribution margin per lot/customer/commodity
6. Customer demand fusion = sales velocity × customer health × seasonal pattern × competitive signals → churn risk + opportunity score
7. Insight discovery = pattern-detection across fusion outputs → “vendor X’s defect rate spiked 3 weeks running on commodity Y after their packing facility change in week N”

Each fusion output is a structured FusionInsight { insight_type, narrative, supporting_facts[], confidence, action_recommendation } with full provenance.

M.2 — Proof package as company snapshot

Replaces the simpler proof_package design from Part D with the high-fidelity version:

Proof package (weekly W19/M05) sections:

1. Operational picture — events ingested, inspections completed, photos captured, lots received, sales generated, fills, returns, holds
2. Industry context — Blair benchmarks, USDA pricing, harvest reports, peer-market activity, seasonal status
3. Tenant-specific position — margin vs market, fill rate vs benchmark, customer health, vendor scorecards, commodity coverage
4. Specialized insights (from fusion engine M.1):
   • Defect patterns flagged
   • Market opportunities flagged
   • Supply risk flagged
   • Customer churn signals
   • Vendor anomalies
   • Pricing opportunities
5. Personalized layer — per-actor/role appendices: GM strategic summary, sales team performance, buyer team performance, QC summary, foreman summary
6. Provenance ledger — every claim links to walk_provenance chain

Proof package as federal-grade artifact:

• Snapshot pattern (§11.6) — immutable W19 / M05 versions
• Cite-then-claim discipline (§13.6) — every metric has fact_citations
• Replay-able from events (per approved-projection registry rules)
• Rendered as markdown into vault → also exported as PDF for external review (federal lane)

M.3 — Operational picture for the tenant

Per Rob’s spec: “accurate operational picture of the tenant and the produce industry that is highly specialized and has unique insights gained from the data fusion.”

The proof_package + the daily_company_pulse (Part J.2) together form this. The daily_company_pulse is the “live” version (updates 1x/day); the proof_package is the “audit-grade” version (snapshotted weekly/monthly).

Deliverables

1. packages/agent/src/fusion/index.ts + 7 fusion modules per pattern in M.1
2. packages/mcp-server/src/ingestion/renderers/proof-package-renderer.ts (replaces simpler one in Part D)
3. packages/mcp-server/src/ingestion/renderers/daily-company-pulse-renderer.ts
4. New event subtype: fusion.insight_discovered (joins signal.* family — would make 16 subtypes; check project_signal_event_family memory before adding)
5. PDF export for proof packages (Part D extension)
6. Tests: fusion engine determinism + proof package contract + walk_provenance coverage
7. Sample W19 proof package generated end-to-end

Acceptance criteria

• Sample W19 proof package: ≥30 sections, ≥100 fact_citations, every metric provenance-walkable
• Fusion engine: each pattern produces a FusionInsight that surfaces in at least one consuming projection (briefing, dashboard, proof package)
• daily_company_pulse renders in <30s from event stream
• PDF export passes federal-grade format check (timestamps, signatures, cryptographic hash)
• A blind reader can reconstruct the operational position from a proof package alone

Dependencies

• Parts A–L all complete (this is the apex)
• Part J (projection index optimization includes daily_company_pulse)
• Part L (historical data — for fusion patterns that need history)

Estimate

8–12 hours Claude. Fusion engine ~5h, proof package renderer ~3h, daily pulse ~2h, PDF + tests ~2h.

---

14. Part N — Role-Augmented Operational Drill-Throughs

Scope

Per Rob: “We need to think about the data, cross-linking, and drill-throughs that are most beneficial to each role. Then we need to list and optimize with the goal of augmenting each role with the most helpful data for their role and the dynamic operational and market context.”

The infrastructure exists — 5 explore-* tools (explore-vendor, explore-load, explore-inventory, explore-lot, explore-commodity) + explore-breadcrumbs.ts shared util + 18+ inventory query tools (inventory-intelligence, inventory-freshness, inventory-reconciliation, inventory-valuation, query-vendor-performance, query-market-signal, query-seasonal-curve, query-price-sheet, query-inbound-loads, get-inventory-freshness, get-inventory-alerts, get-pickable-inventory-with-gate, allocate-inventory, search-operational-records, search-unified).

What’s missing: role-specific composition — natural drill-through chains optimized per role, with cross-link contracts, ambient intel side-docks, and live op + market context layered.

N.1 — The Canonical Inventory Drill-Through (Rob’s example)

The single most important drill-through pattern in produce ops:

case_count(commodity)
  → lots_of_commodity[]
      → lot_detail (vendor, brand, dock, received_date, age, location)
          ├→ inspection_history[] (defects, photos, narratives, holds)
          ├→ vendor_profile (this vendor's pattern, recent loads, scorecard)
          │    └→ vendor_lot_history[] (their other lots in stock)
          ├→ lot_sales[] (what's been sold, to whom, at what price)
          │    └→ customer_demand_for_commodity[]
          └→ commodity_market_position (Blair, USDA AMS, Hunts Point)
               ├→ commodity_profile (universal facts)
               └→ commodity_overlay (tenant operational state)

Every step is a typed link. Every step shows ambient context relevant to that hop. Every step lets the user keep going.

N.2 — Per-Role Drill-Through Matrix

Role	Default entry point	Natural drill chain	Ambient side-dock	Live op signal	Live market signal
Sales Rep	Customer profile OR commodity sell-list	customer → today’s pricing → available lots → margin headroom → competing inventory	Customer health, AR aging, last contact, account portfolio coverage	Order received, hold blocking commitment, customer comm received	Blair commodity price moves, demand signals, peer-market chatter
Buyer	Vendor profile OR commodity market position	commodity → market position → vendor availability → recent quotes → harvest forecast → contract pipeline	Vendor relationship state, hedging, savings vs benchmark, margin context	Vendor quote received, harvest update, ETA change	Blair, USDA AMS daily, harvest comms, weather impact, futures (where applicable)
QC Inspector	Today’s expected loads OR pending re-inspection	load → vendor history → commodity defect modes → photo gallery → narrative archive → similar lot outcomes	Zone, current shift, inspector specialty, vendor pattern flags	Load arrived, photo uploaded, defect detected, hold placed	Vendor historical defect rates, regional outbreak alerts, FDA recall feed
Box Man (warehouse worker)	Pick list OR put-away assignment	lot → location (zone+slot) → pallet config → handling notes → temperature spec → freshness urgency	Zone, current dock, shift, pick velocity	Pick assigned, lot moved, position vacated/assigned	(none — operational only)
Receiver / Dept Receiver	Inbound load board OR specific load detail	load → expected vendor → dock face → unload sequence → scale → put-away path	Door congestion, current shift roster, dock face accept_inbound state	Load expected, load arrived, dock face status change	(vendor harvest comms only — limited)
Foreman	Today’s roster + dock board + active holds	dock → loads expected → team available → bottlenecks → escalations	Full warehouse state, shift KPIs, hold queue, team performance	Any operational event in their dept	Supply chain pulse (anything blocking inbound?)
Checker	Order ready-for-load OR specific shipment	order → lot allocations → pallet builds → checker manifest → load truck	Departing shipments, customer instructions, returns history	Order picked, pallet built, checker scan	(none)
Porter	Cleaning rotation OR equipment status	zone → cleanliness state → equipment status → trash queue	Zone state, supply level	Spill reported, equipment moved	(none)
Delivery Driver	Today’s route OR specific delivery	route → stop list → load detail → customer instructions → ETA	Today’s route, traffic, customer windows, returns	Stop completed, scanner update	(traffic only)
GM / Exec	Daily pulse OR margin position OR customer health	KPI → operational driver → root cause → vendor/customer → action recommendation	Week-over-week, month-over-month, vs benchmark, fusion insights	All major events filtered to anomaly	Full external context — Blair, USDA, X chatter, news, futures
Admin (Rob/Alex)	Federation health OR tenant onboarding state	tenant → system health → projection freshness → audit trail	Cross-tenant aggregate (anonymized), platform observability	Any system event	(only if relevant to billing / federation)
Customer (portal — limited)	Their orders OR available commodities for their account	order → status → tracking → customer-safe lot info (no vendor name, no cost)	Their account history, contact, AR	Their order status changes	(none in v1; could add anonymized seasonal pricing in Wave 3)
Vendor (portal — limited)	Their open POs OR payment status	PO → load status → QC outcome → payment ETA	Their performance dashboard (their data only)	PO acknowledged, load arrived, QC complete, payment scheduled	(none in v1)

N.3 — Cross-Link Contracts

Every entity profile MUST declare (in linked_entities[] per DocContent schema):

• Parents (taxonomic above): variety→commodity, lot→commodity+vendor+brand, customer→tenant, vendor→tenant
• Siblings (peer set): variety→other_varieties_of_same_commodity, lot→other_lots_of_same_commodity_received_today
• Children (taxonomic below): commodity→varieties, vendor→vendor_lot_history, customer→customer_orders
• Projections (read-side): commodity→commodity_360, vendor→vendor_360, customer→customer_360, lot→lot_status_projection
• Live state (operational): lot→current_location, lot→inspection_history, lot→holds_active

Wikilink resolver (Part B) honors all these typed links. Drill-through composer (Part G) renders the right link set per current entity type.

N.4 — Drill-Through Auditability

Every drill chain emits a drill.step_taken event with:

• actor_id + role
• from_entity + to_entity
• link_type (parent/sibling/child/projection/live)
• via_tool (which explore-* tool was invoked)
• timestamp

This produces a drill_pattern_projection (new — Part J registry) showing which paths each role actually walks. Drives optimization: paths walked frequently get promoted to one-click; paths walked rarely get demoted.

N.5 — Side-Dock Ambient Intel (TZ-5 §5.2 operationalization)

Per-role side-dock content is computed by a new module packages/agent/src/side-dock/:

• Reads actor.memory.context (role, zone, current task)
• Reads relevant projections (customer_360 if role=sales; vendor_360 if role=buyer; etc.)
• Composes 3-5 ambient items with action affordances (“Customer X usually orders weekly — last order 14 days ago — call them?“)
• Refreshes on signal.* events that change the picture

Deliverables

1. docs/audits/ROLE_DRILLTHROUGH_DESIGN_2026-05-16.md — full per-role matrix with concrete first-100-queries-per-role + drill chains documented
2. Refactored explore-* tools to return next_steps[] suggestions (drill hints) per the matrix
3. packages/agent/src/side-dock/index.ts + per-role composers
4. drill.step_taken event subtype + drill_pattern_projection (in Part J)
5. packages/agent/src/cross-link/index.ts — entity profile cross-link enforcement (validates linked_entities[] meets the contracts in N.3)
6. Workspace UI: drill breadcrumb component + side-dock component + next-step suggestion strip
7. Playwright test: each role’s canonical 5-step inventory drill works end-to-end

Acceptance criteria

• Sales rep “Cucumber Hot House available?” → cases → top-3 lots → lot detail → vendor → margin → today’s market price ≤ 6 clicks, < 10s total
• Buyer “Asparagus market position?” → commodity_360 → market chart (Blair vs USDA vs internal) → vendor availability → contract pipeline ≤ 5 clicks
• QC inspector “Mission Produce today” → expected loads → vendor history → commodity defect modes ≤ 4 clicks
• Drill breadcrumb persists across hops (no losing your place)
• Side-dock surfaces ≥3 actionable items per role on every drill page
• drill_pattern_projection populated; top-10 paths per role identifiable after 1 week of use

Dependencies

• Part B (T7 — wikilink resolver)
• Part C (entity renderers — the destinations)
• Part J (projections — customer_360, vendor_360, drill_pattern_projection)
• Part G (composer plugin + UI)

Estimate

6–8 hours Claude. Audit doc + matrix ~2h, explore-* refactor ~1.5h, side-dock module ~2h, cross-link validator ~1h, drill projection + tests ~1.5h.

---

15. Part O — External Market Data Sources

Scope

Per Rob: “if there are important market data types and sources that we need to tap into to further enrich our produce industry data we need to call it out and plan. i.e. produce industry news, x api, blue book subscription, etc.”

Existing integrations: USDA AMS Market News (usda-market-news.ts), USDA inspections (usda-inspection.ts), FDA recall (fda-recall-monitor.ts), NOAA NWS weather (nws-weather.ts), Samsara carrier (samsara-handler.ts). All emit into the existing 15-subtype signal.* event family.

O.1 — Source Inventory (16 sources, 3 tiers)

Tier 1 — Must Have (subscriptions + critical free)

Source	What	Cost	Integration	Signal mapping
Blue Book Services	THE produce industry trade reference DB — vendor credit ratings, integrity scores, business size, NAICS, contact, bonded status, growers/distributors/retailers	Subscription (~$4-12K/yr depending on tier)	API (Blue Book Online API) — needs auth	signal.vendor_quote_observed enrichment + new signal.vendor_credit_observed
USDA AMS Market News ✓	Daily wholesale prices by commodity by terminal market (Hunts Point, Boston, Atlanta, etc.)	Free	Existing — extend coverage to all relevant terminals	signal.market_pricing_observed
The Packer	Produce industry news, vendor moves, market commentary, harvest reports	Subscription (~$300/yr)	RSS + scraping for paywalled	new signal.industry_news
Produce News	Same shape as The Packer	Subscription	RSS + scraping	new signal.industry_news
X (Twitter) API	Produce-twitter handles (USDA, big shippers, growers, weather services, market reps); real-time market chatter, weather alerts from growing regions	$100-200/mo (Basic tier)	X API v2	signal.market_chatter
FDA Recall RSS ✓	Public food safety recall feed	Free	Existing — verify coverage	new signal.recall_observed (extends compliance-recall.ts)
CDC Outbreak Feed	Foodborne illness outbreak reports	Free	RSS / API	new signal.outbreak_observed

Tier 2 — High Value

Source	What	Cost	Integration	Signal mapping
USDA NASS	Crop production estimates by region by commodity	Free	NASS Quick Stats API	new signal.crop_estimate_observed
NOAA NWS ✓	US weather forecasts + alerts	Free	Existing — extend with growing-region geocoding (CA Central Valley, MX Sonora coords, etc.)	signal.temperature_exception (existing) + new signal.weather_event
OpenWeatherMap / AccuWeather	International weather (MX, Chile, Peru, etc.)	$40-180/mo	API	signal.weather_event
NOAA Marine + Transportation	Port closures, shipping delays	Free	RSS / API	new signal.transit_disruption
Currency FX API (e.g., openexchangerates.org)	USD ↔ MXN, USD ↔ CLP, etc. for import costing	$10-100/mo	API	new signal.fx_rate_observed

Tier 3 — Nice to Have

Source	What	Cost	Integration	Signal mapping
CBP Cargo Entries	Import volume by HS code by country	Free (FOIA / API)	API	signal.import_volume_observed
DOT FMCSA SAFER	Carrier safety scores	Free	API	new signal.carrier_safety_observed
CME / ICE futures	Adjacent commodity futures (orange juice, lean hogs for foodservice context)	Subscription	API	new signal.futures_observed
PMA / IFPA / UFPA news	Industry trade org events + reports	Free	RSS	signal.industry_news
PMG (Produce Marketing Guide)	Industry data tables	Subscription	Manual scrape	offline ingest

O.2 — Connector Pattern

Each source connector follows the existing pattern (see usda-market-news.ts, nws-weather.ts):

• packages/mcp-server/src/integrations/<source>.ts — fetcher (auth, rate limit, parse)
• packages/mcp-server/src/event-handlers/<source>-consumer.ts — emits signal.* events
• packages/agent/src/blueprints/<source>-refresh.ts — scheduled refresh (cron or DO)
• packages/shared/src/events/payloads/signal/<subtype>.ts — payload schema
• Tests + integration tests with recorded fixtures

O.3 — Data Plane Discipline

• Tier 0 sources (public free): Land in fin-central-prod directly (universal Plane 3); mirror to tenant via Taproot sync
• Tier 1 subscriptions (Blue Book, news): Land in fin-central-prod; license-protected — tenant access via API only, NOT raw data sync
• X API: Land in fin-central-prod; subject to X TOS; aggregated insights flow to tenants, raw tweets do not (X TOS compliance)
• Per-tenant private fetches (e.g., tenant’s own carrier integration): stay in tenant deployment

O.4 — Schedule + Cadence

Source	Cadence	Reason
Blue Book vendor lookup	On-demand + weekly batch refresh	Vendor profile rendering trigger
USDA AMS Market News	Daily 8am ET (each terminal)	Their publish cadence
The Packer / Produce News RSS	Hourly	News fluidity
X API stream	Real-time (filter on @list)	Market chatter freshness
FDA Recall	Every 4 hours	FDA publish cadence
CDC Outbreak	Every 12 hours	Lower frequency
USDA NASS	Weekly (Mon AM)	Weekly publish
NWS Weather (US)	Every 6 hours + alert push	Forecast cadence
Intl Weather	Every 6 hours	Same
NOAA Marine	Every 6 hours + alert	Same
Currency FX	Daily	Daily settlement
CBP Cargo	Weekly	FOIA cadence
DOT FMCSA	Monthly batch	Reference data
Futures	Real-time during trading	Market data

O.5 — Cost Budget (Subscription Tier)

Approximate annual cost if all Tier 1 + Tier 2 active:

• Blue Book: $4-12K
• The Packer: $300
• Produce News: $300
• X API Basic: $1,200-2,400
• OpenWeatherMap: $480-2,160
• Currency FX: $120-1,200
• CME futures: variable, prob $3-5K
• Total Tier 1+2 subscriptions: ~$10-25K/yr (for all of FIN, not per tenant)

Rob to approve subscription budget. Tier 1 critical for Wave 2 GTM (need credible vendor intelligence for buyer team profile credibility).

Deliverables

1. docs/audits/EXTERNAL_MARKET_DATA_SOURCES_2026-05-16.md — full source inventory with per-source connector spec
2. 7 new Tier 1 connectors: blue-book, the-packer, produce-news, x-api, cdc-outbreak, plus extension of usda-ams + fda-recall
3. 5 new Tier 2 connectors: usda-nass, openweather-intl, noaa-marine, currency-fx, (existing nws-weather extension for growing regions)
4. New signal.* subtypes (likely 5-7 new): vendor_credit_observed, industry_news, recall_observed (extend), outbreak_observed, crop_estimate_observed, weather_event, transit_disruption, fx_rate_observed, import_volume_observed, carrier_safety_observed, futures_observed
5. Update project_signal_event_family.md memory + packages/shared/src/events/payloads/signal/registry.ts
6. Per-source rate-limit + cost monitoring at packages/agent/src/admin/external-source-health.ts
7. Subscription credentials in AWS SM under /fin/central/external-data/<source>/

Acceptance criteria

• Each Tier 1 connector ingests at least one full day of data without error
• Signal events flow to commodity_360 + vendor_360 + customer_360 within their refresh window
• Tier 1 monthly cost stays under approved budget
• Blue Book vendor lookup enriches vendor profile within 24h of vendor profile creation (Part C)
• The Packer / Produce News headlines surface in daily company pulse (Part M)
• X API filtered stream produces ≥10 relevant signal.market_chatter events per business day
• Source-health monitoring catches dead connectors within 1 cron cycle

Dependencies

• Existing usda-market-news.ts ✓
• Existing nws-weather.ts ✓
• Existing fda-recall-monitor.ts ✓
• Existing 15-subtype signal.* family ✓
• Rob to approve Tier 1 subscription budget
• Rob to provision API keys + credentials in AWS SM

Estimate

10–14 hours Claude. 7 Tier 1 connectors ~1-1.5h each (~10h), 5 Tier 2 connectors ~1h each (~5h), event family extension + tests ~2h, source-health monitoring ~1h. Note: some hours absorbed by signal-subtype additions overlapping with Part L.

---

16. Part P — Data Quality, Accessibility & Serving Discipline

Scope

Per Rob: “an important facet of having good data is that it is properly accessible at the right time and that it is properly served and maintained and accurate.”

This part establishes the production discipline that makes Parts A–O actually trustworthy at runtime. Without it, the data corpus is theoretically beautiful but operationally fragile.

P.1 — Data SLO Definitions

For every projection (15 total post-Part J) and every curated MCP tool (80–120 post-Part J.1), explicit SLOs:

Dimension	Target	Measurement
Latency p50	<200ms (read) / <2s (compose)	Worker analytics
Latency p95	<500ms (read) / <5s (compose)	Worker analytics
Latency p99	<2s (read) / <10s (compose)	Worker analytics
Freshness	varies per projection (5min for hot, 1hr for warm, 24h for cold)	Compare projection.updated_at vs latest source event
Availability	99.5% (Wave 2) → 99.9% (Wave 4)	Health endpoint uptime
Accuracy	100% (event-derived must match replay)	Periodic replay compare
Completeness	≥95% of expected rows present	Row count vs expected per period

Each projection + tool publishes its SLO in docs/projections/SLO_CATALOG_2026-05-16.md.

P.2 — Data Quality Monitoring

Automated checks running on cron:

1. Completeness — for each projection, expected vs actual row count per tenant per period; deviation >5% emits signal.data_quality_alert
2. Accuracy — periodic spot-replay (10% sample) of projection rows; mismatch with replay output emits alert
3. Consistency — cross-projection joins detect orphans (e.g., lot in inventory but no events_for_lot)
4. Freshness — every projection row has last_refreshed_at; staleness beyond SLO emits alert
5. Lineage integrity — every entity_doc_projection row’s walk_provenance chain must terminate in real events; broken chains emit alert

Output: data_quality_dashboard projection + admin tool get_data_quality_status().

P.3 — Data Maintenance Policies

1. Archival: chunks unused for 90 days move to cold storage tier (R2 glacier-class); accessed-on-demand
2. Deprecation: entity profiles for archived entities (lot.consumed, customer.churned, vendor.terminated) get lifecycle_status: archived (not deleted); searchable but de-prioritized in agent context
3. Lineage: every projection row carries source_event_ids[] (per spec §11.5.3 transactional writes); inability to prove lineage fails CI gate
4. Snapshot rotation: weekly snapshots (W19, W20) preserved 1yr; monthly (M05, M06) preserved 7yr (FSMA 204 rule)
5. PII expiration: customer-portal data expires per their contractual data-retention agreement (default: 7 years post-relationship-end)

P.4 — Data Serving Observability

1. Cloudflare Worker analytics — per-route latency, error rate, cache hit %; dashboards live in CF account
2. Per-projection query patterns — top-10 query paths per projection per role (drives caching strategy)
3. Per-tool usage stats — invocation count, avg latency, error rate, token-budget utilization
4. Cache strategy:
   • Hot projections (lot_status, actor_pulse, customer_360): KV cache 5min TTL
   • Warm projections (vendor_360, commodity_360): KV cache 1hr TTL
   • Cold projections (proof_package, daily_company_pulse): KV cache 24hr TTL
   • Static (entity_doc_projection commodity_profile, variety_profile): KV cache 7d TTL with content_hash invalidation
5. Error budget — per-projection allowed error rate; budget burn-down alerts before SLO breach

P.5 — Per-Projection SLO Mapping

Each of 15 projections gets an SLO row:

Projection	Read p95	Freshness	Tier	Cache TTL
lot_status_projection	<300ms	5min	hot	5min KV
actor_pulse_aggregate	<500ms	5min	hot	5min KV
customer_360	<500ms	5min	hot	5min KV
vendor_360	<500ms	5min	warm	1hr KV
commodity_360	<500ms	event-driven	warm	1hr KV invalidate-on-event
location_intel	<1s	1hr	warm	1hr KV
supply_chain_position	<500ms	15min	warm	15min KV
daily_company_pulse	<2s	24h	cold	24h KV
sales_team_dashboard	<1s	1hr	warm	1hr KV
buyer_team_dashboard	<1s	1hr	warm	1hr KV
entity_doc_projection (commodity)	<300ms	7d	static	7d KV w/ content_hash
entity_doc_projection (variety)	<300ms	7d	static	7d KV w/ content_hash
doc_backlink_projection	<500ms	event-driven	warm	invalidate-on-event
kb_health_summary	<500ms	1hr	warm	1hr KV
system_health_snapshot	<500ms	1hr	warm	1hr KV

P.6 — Per-Tool SLO Mapping

Sample (curated to ~80 tools post-J.1, each gets SLO):

Tool	Latency p95	Token-budget	Accuracy req
query_knowledge	<500ms	4KB	100% match to source
get_entity_profile	<300ms (cached) / <2s (cold)	8KB	100% match to projection
walk_provenance	<500ms per hop	2KB per hop	100% terminating in events
get_doc_graph	<1s per depth	4KB	100% covered links
search_entity_profiles	<2s	6KB	recall ≥95% on test queries
explore-* drill tools	<500ms	4KB	next_steps[] correctness
generate-{role}-brief	<2s	12KB	≥5 fact_citations
get_inventory_freshness	<500ms	2KB	accurate to last lot.received

Deliverables

1. docs/projections/SLO_CATALOG_2026-05-16.md — complete per-projection + per-tool SLO registry
2. packages/agent/src/observability/slo-monitor.ts — collects metrics, emits alerts
3. packages/agent/src/admin/data-quality-dashboard.ts + data_quality_dashboard projection
4. signal.data_quality_alert event subtype (joins family)
5. CF Worker analytics dashboard (Rob’s CF account-level setup)
6. Cache layer migrations (KV namespaces per cache tier)
7. pnpm cli check-data-quality — runs full quality sweep across tenants
8. Lineage CI gate (PR fails if migration breaks lineage)

Acceptance criteria

• 100% of projections have published SLOs; CI fails if SLO undeclared on new projection
• Data quality dashboard surfaces all 5 check types (completeness/accuracy/consistency/freshness/lineage) per projection per tenant
• Cache hit rate ≥80% for hot projections, ≥60% for warm
• SLO breach within last 7 days surfaces in daily_company_pulse (Part M)
• Lineage broken chain blocks merge to main
• Sample monthly snapshot (M05) reproducible byte-for-byte from event replay (proves accuracy)

Dependencies

• Part B (T7 worker loop — for projection observability hooks)
• Part E (projection parity audit — surfaces gaps)
• Part J (curated tool catalog — gives the universe to SLO)
• Part M (daily_company_pulse — hosts SLO surfacing)

Estimate

6–8 hours Claude. SLO catalog ~2h, monitor module ~2h, dashboard ~1h, cache layer + CI gate ~2h, replay-equivalence test ~1h.

---

17. Execution Sequence (Recommended)

DAG of dependencies (now 15 parts):

Part A (stock parity) ─────────┐
                                │
Part B (T7 worker loop) ────────┼─→ Part C (T15 renderers) ──→ Part D (proof + QC + photo)
                                │            │                       │
                                │            ▼                       │
                                │     Part E (projection parity)     │
                                │            │                       │
Part F (frontmatter) ───────────┴─→ (parallel)                       │
                                              │                      │
Part H (memory opt) ──────────────────────────┴─→ Part G (agentic hardening)
                                                              │
                            ┌─────────────────────────────────┤
                            ▼                                 ▼
                  Part I (briefing refinement)     Part N (role drill-throughs)
                            │                                 │
                            ▼                                 │
                  Part J (MCP+projection index)               │
                            │                                 │
                            ├─────────────────────────────────┘
                            ▼
                  Part O (external market data sources)
                            │
Part L (historical backfill) ──────────────→ Part K (sales+buyer team profiles)
                            │                         │
                            └─────────────────────────┤
                                                      ▼
                                          Part M (fusion + proof excellence) — APEX

Recommended phasing (16 sessions over ~3 weeks)

Week 1 — Foundation (Parts A, B, C, D, E, F)

Session	Day	Parts	Hours
1	Sat 5/16	A (stock parity) + start F (frontmatter)	4–5
2	Sat 5/16	B (T7 worker loop + E2E)	6–8
3	Sun 5/17	C.1+C.2 (Vendor universal + overlay + bulk-render 142)	5–6
4	Sun 5/17	C.4+C.5 (Region + Variety wiring)	3–4
5	Mon 5/18	C.3 (Customer renderer when sales data lands) + finish F	4–5
6	Tue 5/19	D (proof + QC + photos — simpler v1)	6–8
7	Wed 5/20	E (projection parity audit)	3–4

Week 2 — Optimization + Personalization (Parts H, G, I, J)

Session	Day	Parts	Hours
8	Thu 5/21	H (memory optimization)	4–6
9	Fri 5/22	G (agentic hardening — MCP tools + composer + eval baseline)	8–10
10	Sat 5/23	I (briefing refinement + 5 new role-briefs)	6–8
11	Sun 5/24	J (MCP tool index audit + curation + 8 new projections)	8–10

Week 3 — Specialization + Apex (Parts N, O, L, K, M)

Session	Day	Parts	Hours
12	Mon 5/25	N (role drill-through design + cross-link contracts + side-dock + drill audit)	6–8
13	Tue 5/26	O.1 (Tier 1 connectors: Blue Book, X API, The Packer/Produce News, CDC outbreak — 4 of 7)	6–8
14	Wed 5/27	O.2 (Tier 1 finish + Tier 2 connectors: USDA NASS, OpenWeather intl, NOAA marine, FX) + L start	6–8
15	Thu 5/28	L (historical data backfill — needs Rob’s source files) + K.1 start	6–8
16	Fri 5/29	K.2 + K.3 (buyer profile + buyer dashboard + specialization layer)	5–6
17	Sat 5/30	M.1 (fusion engine — 7 patterns)	5–6
18	Sun 5/31	M.2+M.3 (proof package excellence + daily company pulse + PDF)	6–8
19	Mon 6/1	P (SLOs + data quality monitor + dashboard + lineage gate)	6–8

Total: ~125–155 hours over 19 sessions. (was 95–115 / 16 sessions before N + O + P)

Parallel-friendly batches:

• Sessions 1–2 (A + B) — parallel-able with isolation
• Sessions 8–9 (H + G) — H independent
• Sessions 10–11 (I + J) — partially parallelizable; J.2 projections depend on I freshness mapper
• Sessions 13–14 (K.1 + K.2) — parallel-able if Rob has 2 windows

Rob parallel work (interleaved across 3 weeks):

• Phase 5 §3 (CF Pages) — needed before Session 9 (Part G UX work)
• Phase 5 §4 (CF Access) — needed before Session 9 eval suite
• Sales reports sourcing — unblocks Session 5 (Part C.3 customer renderer)
• R2 bucket nathel-artifacts provisioning — needed before Session 6 (Part D photo pipeline)
• Historical data file locations — needed before Session 12 (Part L)
• 3 inspector identities (per original program §C-2) — needed for Part K personalization seeding
• Telnyx 10DLC confirmation — needed before any voice briefing test (Part I)

---

18. Acceptance Criteria for Whole Program

When all 13 parts ship:

Foundation (A–F):

1. ✅ ≥95% of Nathel inventory SKUs map to a vault commodity profile (Part A)
2. ✅ Vault commits flow to fin-central-prod within 60s (Part B)
3. ✅ All 142 active Nathel vendors have universal-layer profiles in fin-central-intranet AND tenant overlay in nathel-intranet (Part C)
4. ✅ Active customers have profiles in nathel-intranet (Part C, when sales data lands)
5. ✅ Weekly W19 proof_package generated with ≥5 inspections + photos (Part D — superseded by M for v2)
6. ✅ All 15 projections (7 existing + 8 new in Part J) operational on both tenants with replay smoke test green (Part E + Part J)
7. ✅ All fin-agentic + knowledge-forge canonical docs have full DocContent frontmatter (Part F)

Optimization (G, H): 8. ✅ Drill-through page composes universal + overlay layers role-aware (Part G) 9. ✅ Gradeboard ≥4.51 (Part G) 10. ✅ actor.memory query latency <50ms; embedding cache hit ≥80% (Part H)

Specialization + Personalization (I, J, K, L): 11. ✅ 5 new per-role briefs (gm, sales_rep, qc_inspector, foreman, exec) live + personalized + cite ≥5 facts each (Part I) 12. ✅ MCP tool catalog: 80–120 tools, role-curated, every tool documented (Part J) 13. ✅ 8 new projections operational + each renders to vault as queryable doc (Part J) 14. ✅ Sales rep profiles: rep R1 ≠ rep R2 (verifies personalization); team dashboard math correct (Part K) 15. ✅ Buyer profiles: buyer B1 ≠ buyer B2; team dashboard math correct (Part K) 16. ✅ Hyper-specialization layer encoded: tenant.physical_location + supply_chain_position + local_market_intel surfaces in profiles + briefs (Part K.3) 17. ✅ Historical data backfilled idempotently across all 6 sources; vendor + customer + commodity 360 projections include historical context within 1 hour of backfill (Part L) 18. ✅ QC photo-graph stitcher links photos retroactively when they arrive (Part L)

Role Augmentation + External Data (N, O): 19. ✅ Per-role drill-through matrix documented; canonical inventory chain (cases→lots→lot info→inspection→vendor→sales→commodity sales) ≤6 clicks for sales rep entry (Part N) 20. ✅ Side-dock surfaces ≥3 actionable items per role on every drill page (Part N) 21. ✅ drill_pattern_projection populated; top-10 paths per role identifiable after 1 week of use (Part N) 22. ✅ All 7 Tier 1 external sources connected + emitting signal.* events (Blue Book, USDA AMS extended, The Packer, Produce News, X API, FDA Recall extended, CDC Outbreak) (Part O) 23. ✅ All 5 Tier 2 connectors live (USDA NASS, OpenWeather Intl, NOAA Marine, FX, NWS extended) (Part O) 24. ✅ External-source health monitor catches dead connectors within 1 cron cycle (Part O) 25. ✅ Tier 1 monthly cost stays under approved budget; subscription credentials in AWS SM (Part O)

Apex (M): 26. ✅ Fusion engine produces FusionInsights across 7 patterns; insights surface in briefings + dashboards + proof packages (Part M.1) 27. ✅ Sample W19 proof package: ≥30 sections, ≥100 fact_citations, every metric provenance-walkable, federal-grade PDF export (Part M.2) 28. ✅ daily_company_pulse renders in <30s; provides accurate operational picture (Part M.3) 29. ✅ A blind reader can reconstruct Nathel’s operational position from a single proof package (Part M apex test)

---

19. Anti-Patterns to Avoid

Anti-pattern	Why rejected
Render every SKU as its own commodity profile	SKUs are pack/size variants; commodity is the entity. SKU-level is a separate pack-spec dimension, not a profile axis
Vendor profile combines universal + tenant fields	Violates ADR-006 sovereignty boundary
Customer profiles in fin-central	Customers are tenant operational data; never universal
Skip migrations 049/050 application	T7 cannot work without entity_doc_projection table existing
Inline render in vault webhook handler	Should enqueue rebuild → worker consumes → write — keeps webhook fast
Photo metadata in customer-facing render	Hard rule per CLAUDE.md customer-info boundary
Frontmatter expansion that breaks existing parsers	Lock to additive only; never remove fields

---

20. Open Questions for Rob

Foundation (A–H) — original:

ID	Question	Default
Q-1	When can we expect a sales report dump for customer profile bootstrap?	Defer Part C.3 to Session 5 (Mon 5/18); can also defer to W2 if needed
Q-2	Should vendor profiles include public ownership / SAM.gov data?	Yes for federal lane prep; out-of-scope for v1 if it adds >2h to Part C
Q-3	proof_package weekly cadence — Friday EOD or Monday AM?	Default Monday AM (covers prior week W19 = Mon 5/18 covers W19 May 11–17)
Q-4	Photo storage: continue R2 fin-central-artifacts OR per-tenant R2?	Per-tenant for sovereignty; need nathel-artifacts bucket. Rob to provision.
Q-5	Memory.md rotation policy — keep last 30KB always vs date-keyed archives?	Date-keyed archives (MEMORY-2026-05.md, MEMORY-2026-04.md …) — preserves recall
Q-6	Engineering Spec amendment for migration 045/046 → 049/050 (per ADR-005) — fold into Part F?	Yes; minimal effort once frontmatter sweep is running

Specialization (I–M) — added:

ID	Question	Default
Q-7	What are the current Nathel sales rep + buyer identities? Need actor_ids for personalization (Part K bulk seeding)	3 inspectors + Alex per program §C-2; rest TBD
Q-8	Where are the historical extraction files?	CONFIRMED: /Users/robert/Projects/FIN/_03_Dev/ — teams-qc-export-2026-05-06.json (143KB main extract), teams-qc-export-2026-05-06-manifest.md (41KB), teams-qc-photo-narrative-pairing-2026-05-06.json (78KB — the photo-graph), teams-qc-photos/ (photos directory), plus FIN-TEAMS-QC-DATA-FOUNDATION-HANDOFF-2026-05-06.md and fin-agentic-pp-arrivals-teams-qc-e2e/ fixture set. GM pricing memos + salesman ground truth + Hunts Point market truth: locations TBD (likely in .teams-stage-2026-05-12-v2-hydrated/02-business-planning/ or 07-meetings-status/)
Q-9	Should briefings be generated push (cron) or pull (on-demand)?	Push: 5am daily for morning briefs; pull-augmented for shift changes; voice on-demand always
Q-10	Tenant-config: who authors tenant.physical_location + supply_chain_position + local_market_intel_sources? (Part K.3 prereq)	Rob authors v1; subsequent tenants self-author during onboarding
Q-11	Fusion engine confidence floor — drop insights below X confidence?	0.7 default; configurable per actor.memory.briefing_preferences (extends M-19 work)
Q-12	PDF export of proof packages — generate via headless Chromium in Worker, or external service?	Headless puppeteer in Cloudflare Workers Browser Rendering; falls back to external if Browser Rendering not available in account tier
Q-13	New event subtype fusion.insight_discovered — adds to signal.* family (would be 16 subtypes). OK to add?	Yes; follows same closed-discriminated-union pattern as existing 15
Q-14	Tool curation aggressiveness in Part J.1 — archive any tool with <3 usages in prior 90 days, or be more conservative?	Conservative: keep if any usage; archive only if zero usages + replaced by clearer alternative
Q-15	Briefing personalization scope creep — should briefings also adapt to actor’s dominant accent/locale (i18n already exists in workspace)?	Out of scope for v1; revisit Wave 2

Role Augmentation + External Sources (N, O) — added:

ID	Question	Default
Q-16	Subscription budget approval — Tier 1 + Tier 2 = ~$10-25K/yr ongoing. OK to proceed?	Tier 1 critical for buyer team profile credibility; Tier 2 high-value not blocking. Recommend approve Tier 1 (~$6-15K/yr including Blue Book + X API + The Packer + Produce News) for Wave 2 GTM.
Q-17	Blue Book API tier — they offer multiple tiers ($4KBasicto$12K Premium). Which?	Premium for Wave 2 (need full vendor scoring + integrity history); can downgrade post-pilot if not used.
Q-18	X API filter list — which produce-twitter handles to monitor?	Bootstrap list: USDA AMS handles, top-10 grower-shippers per commodity (Mission Produce, Driscoll’s, Sunkist, Grimmway, etc. — note Nathel doesn’t carry Driscoll’s per memory but their market signals still relevant), regional weather services, key analyst handles. ~50 handles for v1.
Q-19	Should drill-throughs auto-trigger background prefetch (e.g., when sales rep opens customer X, prefetch customer_360 + recent orders + pending quotes)?	Yes for top-10 most-walked paths per role; lazy for tail. Drives drill_pattern_projection optimization loop.
Q-20	Cross-link contract enforcement (Part N.3) — fail render if linked_entities[] missing required parents/siblings/children? Or warn-only?	Fail in fin-central-prod (production discipline); warn-only in dev branches.
Q-21	Side-dock UI density — 3 items minimum, what’s the max before it overwhelms?	5 max for desktop; 3 max for mobile (per project_mobile_is_primary_for_qc memory). Configurable per actor.memory.briefing_preferences.
Q-22	Source-of-truth for vendor when Blue Book and Nathel records disagree (e.g., Blue Book says vendor address X, Nathel records say Y)?	Blue Book wins for universal-layer (canonical); Nathel records win for tenant-overlay (operational). Composer shows both with provenance.

---

21. References

• Engineering Spec: Intranet Projection Spec v0.2 — §3.1, §3.4, §3.5, §11.5, §11.6, §11.7, §13.6
• TZ-5 Living Intelligence Design: TZ_5_LIVING_INTELLIGENCE_DESIGN_2026-05-16.md
• ADR-006: Tenant Zero rendering strategy
• ADR-004: Variety embedded by default
• ADR-003: Vault authoritative canon
• ADR-005: Doc-CQRS migration renumbering
• 2-Week Execution Program: fin-agentic/docs/programs/FIN_TWO_WEEK_EXECUTION_PROGRAM_2026-05-15.md — covers T1-T16
• Phase 5 Runbook: fin-agentic/docs/runbooks/PHASE_5_FIN_CENTRAL_INTRANET_BOOTSTRAP_RUNBOOK_2026-05-15.md
• Demarcation Master Plan: fin-agentic/docs/architecture/FIN_CENTRAL_TENANT_DEMARCATION_PLAN_2026-05-15.md
• Anonymization Policy v1: docs/policies/anonymization/FIN_ANONYMIZATION_POLICY_V1_2026-05-15.md
• Approved-projection registry: fin-agentic/audit/card-window-system/approved-projection-tables.json
• Inventory snapshot input: ~/Downloads/inventory_snapshot_20260515.csv (1,203 lots, 540 SKUs, 142 vendors)
• Memory pointers:
  • project_living_wiki_drill_through_vision.md
  • project_world_class_search_drill_through.md
  • project_role_and_actor_aware_pulse.md
  • project_orchestrated_intelligent_frictionless_elegant.md
  • feedback_tenant_intel_sovereignty.md
  • project_mobile_is_primary_for_qc.md
  • project_signal_event_family.md
  • project_email_intel_fusion_program.md