Composition: Smart Product Recommendations (DDD + Hypothesis-Driven Development + BDD + Kanban)

Implements methodology backlog **Example 1** (AI-powered product recommendations engine). See ../backlog.md (~line 1744, Status **📝 Not Implemented**): "Smart Product Recommendations". This composition supersedes that *Not Implemented* status only — no code module is replaced.

Why this composition

bounded contexts, a context map, and a ubiquitous language. The artifact that crosses its seam is the **domain model** (bounded contexts + ubiquitous language), which the strategist turns into candidate uplift levers.

falsifiable hypothesis with a primary metric, a quantified uplift target, guardrail metrics, and a measurement plan. The artifact that crosses its seam is the **hypothesis + measurement plan**.

Given/When/Then recommendation scenarios (cold-start, personalization relevance, diversity/guardrails, **no-fallback ranking**), authored **in parallel per bounded context**, each scenario id embedding its contextId and hypothesisId. The artifact that crosses its seam is the **executable gherkin suite**.

implemented so their mapped scenarios execute green, with flow metrics drawn from real card history. The artifact that crosses its seam is the **implemented, tested build**.

• **Domain-Driven Design** owns the map: it models the catalog/shopper domain into subdomains,
• **Hypothesis-Driven Development** owns measurable uplift: each candidate lever becomes a
• **BDD / Specification by Example** owns executable behavior: every hypothesis is specified as
• **Kanban** owns delivery flow: scenarios become WIP-limited cards pulled through the board,

The seam this composition exists to encode: **domain model -> hypotheses -> executable scenarios -> tested build -> validated experiment -> production rollout**, with an adversarial executed-evidence gate re-checking every seam.

Seam map

Inputs

{
  storefrontName: string (required),
  catalogDescription: string (required),
  recommendationGoals: string (required),
  boundedContextHints?: string[],
  experimentLanes?: [{ laneId, variant, description }]  (if absent, derived from validated hypotheses),
  upliftTargets?: object   (explicit per-metric uplift targets; else formulated in P2),
  requirementsClear?: boolean (default false — when false, P0 runs the interview + breakpoint),
  maxParallelContexts?: number (default 3 — parallel authoring/build chunk size),
  maxFixAttempts?: number (default 2 — adversarial-gate fix budget),
  kipEnabled?: boolean (default true),
  kipDir?: string (default '.a5c/kip'),
  kipModel?: string (default 'sonnet')
}

Outputs

{
  success: boolean,
  domainModel: { subdomains, boundedContexts, contextMapPath, ubiquitousLanguage },
  hypotheses: [{ hypothesisId, statement, contextId, primaryMetric, upliftTarget, guardrailMetrics, measurementPlanPath }],
  scenarios: [{ contextId, gherkinPath, stepDefPath, scenarioIds }],
  flow: { boardPath, wipLimits, flowMetrics, cardsImplemented },
  seamGates: { domainToHypothesis, hypothesisToScenarios, flowToExperiment } each { passed, attempts, escalated, issues, evidence },
  experiment: { launch, lanes: [{ laneId, computedMetrics, rawDataPath }], analysis, validationGate },
  rollout: { approved, breakpointId, expert, autoApproved, rolledOut, response },
  retro,
  kipFactsAsserted: number,
  artifacts: array,
  metadata: { processId, runId, breakpointsHit }
}

success is true only if all three seam gates passed, experiment validation passed, the launch was approved, and (if rollout was approved) the model was rolled out. A failed seam gate, a rejected launch, or a failed validation returns an explicit success: false shape with nothing downstream ever invoked — never a silent fallback that resumes the pipeline.

Policy-gated actions

Both are raised via routedBreakpoint with breakpointId = actionId, tags ['policy-gated', 'csr', <phase-tag>], strategy single, and **no** autoApproveAfterN — the process never auto-approves a policy gate. Provenance { approved, autoApproved, breakpointId, expert, response } is always recorded (autoApproved reflects response?.autoApproved === true set by an external rule). Ready for adapters/policy YAML gating on the policy-gated tag. A conditional requirements-interview breakpoint (growth-product-lead) is raised in P0 only when requirementsClear !== true.

Adversarial seam gates (executed evidence)

Every methodology handoff carries an adversarialGate reducing to { passed, issues, evidence } with mandatory evidence; three independent IRON-LAW critics fan out in parallel (none is the drafting agent, none sees another's verdict), a bounded fixer loop runs maxFixAttempts rounds between critic rounds, and exhaustion escalates to owner via the combinator-owned <gateId>.gate-escalation breakpoint.

The executed-evidence gates use the imported executeTestsTask to produce executed output threaded into the critics' context.

Composed modules

defineBoundedContextsTask, createContextMapTask, buildUbiquitousLanguageTask

formulateHypothesisTask, createMeasurementPlanTask, analyzeResultsTask

pullSystemTask, flowMetricsTask, retrospectiveTask

• `../domain-driven-design/` — identifySubdomainsTask,
• `../hypothesis-driven-development/` —
• `../bdd-specification-by-example/` — executeTestsTask
• `../kanban/` — boardVisualizationTask, wipLimitManagementTask,

Combinators come from `../../specializations/common-utilities/routed-gate-combinators.js` (routedBreakpoint, adversarialGate, kipRecall, kipAssert). Phase interiors compose **by import** where ingredient exports exist; csr.* tasks are defined only for cross-methodology seams, recommendation-domain authoring/execution, and the two guarded policy executors.

Usage

const result = await orchestrate('methodologies/composition-smart-product-recommendations', {
  storefrontName: 'NovaMart',
  catalogDescription: 'Mid-size fashion storefront: 40k SKUs, returning + cold-start shoppers',
  recommendationGoals: 'Lift average order value and PDP click-through with cross-sell + personalization',
  requirementsClear: false,
});

Design rules honored

performed BY agents who paste executed output as evidence.

failed validation each return an explicit success: false shape; the recommendation ranking itself must specify missing-signal handling as an explicit behavior (enforced by no-fallback-ranking-critic) — never a silent alternate path. pickWinningLane returns an honest null when no lane qualifies rather than defaulting to an arbitrary lane.

requirements-interview and the combinator-owned gate escalations.

per-context authoring, P4 parallelSafe-card fan-out, P5 experiment lanes), each bounded by maxParallelContexts via chunk; dependent cards are awaited in dependsOn order via orderByDependencies, never speculatively co-scheduled.

approved === true — ready for adapters/policy YAML gating on the policy-gated tag.

• **No shell subtasks**: every csr.* task is kind: 'agent'; scenario and metric execution is
• **No fallbacks**: invalid inputs throw; a failed seam gate, a rejected experiment launch, and a
• **Sparse breakpoints**: exactly the two policy gates plus a conditional
• **Bounded loops**: each adversarial gate fixer runs at most maxFixAttempts.
• **Honest scheduling**: ctx.parallel.all is used at exactly three sites in process code (P3
• **Provenance recorded** for both policy gates; executors are strictly guarded on