lib.opportunity-spec

@lssm-tech/lib.opportunity-spec

Provider-neutral opportunity scoring and selection contracts for autonomous-company candidates.

This package closes the first canonical ContractSpec slice for the Autonomous Company Opportunity Engine. It defines reviewable candidate, scorecard, evidence, gate, validation, simulation, portfolio, and handoff contracts; it does not research markets, call providers, mutate CompanyOS/Builder state, or approve production implementation.

Scope

Use this package to model:

• autonomous-company opportunity candidates;
• core scorecards: AFS, BVS, GFS, CES, DMS, RTS, RCS, SFS, and TMS;
• diagnostic scores: QAS, DRS, TVS, VCS, and OTS;
• per-score and per-estimate evidence claims from hypothesis to live customer metrics;
• hard kill gates, downgrade gates, HITL load, GTM/CAC/budget assumptions, validation experiments, simulations, and portfolio decisions;
• branded refs to CompanyOS, Builder, ProductIntent, growth, finance, assurance, and orchestration surfaces.

Boundary

This package is contract-only. It must not contain provider credentials, network calls, filesystem mutation, live research, customer-facing sends, production workflow creation, or module imports. High opportunity scores are decision evidence, not implementation approval.

Public entrypoints

• @lssm-tech/lib.opportunity-spec — root barrel
• @lssm-tech/lib.opportunity-spec/types — Zod schemas and inferred types
• @lssm-tech/lib.opportunity-spec/validation — semantic validation helpers
• @lssm-tech/lib.opportunity-spec/validation-rules — reusable validation rule primitives for score coverage and evidence ref checks
• @lssm-tech/lib.opportunity-spec/fixtures — safe synthetic fixtures

Evidence thresholds

• customer_validated requires evidence level 3 or higher.
• pilot_validated requires evidence level 4 or higher.
• live_proven requires evidence level 5.

Distribution-first drafts (additive, experimental)

@lssm-tech/lib.opportunity-spec/discovery exports OpportunityDraftSchema, OpportunityWaveSchema, scoped evidence/metric contracts, the owning OpportunityDiscoveryWaveFeature, and validateOpportunityDraft / validateOpportunityWave. Drafts preserve unassessed fields and unknown customer metrics; they do not require a company, canonical scores, budgets or simulations.

Commercial roles, acquisition mechanisms, creative production, publishing, offers and retention modes are independent dimensions. Catalog cash/effort/time ranges are editorial planning priors, never measured CAC, churn or conversion. Evidence supports its particular product, claim, audience, geography and period; vendor offers establish category facts, not our willingness to pay or demand.

Use the repository's scripts/opportunity-wave.ts captured-input runner to emit the generation prompt, validate, screen and export another wave. The runtime's separate selfserve-first@1.0.0 profile produces research/experiment priorities, without granting implementation, campaign or spending authority. Promotion to OpportunityCandidate requires independently supplied mature requirements and canonical validation. Existing mature contracts remain unchanged.

Wave 1.1.0: sales-assisted profile, production assets, channel variety

OpportunityWaveV11Schema (schemaVersion: "1.1.0") sits beside the frozen 1.0.0 schema; validate either with validateOpportunityDiscoveryWave.

• profileId is selfserve-first or sales-assisted (OPPORTUNITY_DISCOVERY_PROFILE_REQUIREMENTS). sales-assisted replaces the selfserve_purchase gate with bounded_sales_effort and the selfserve_adoption dimension with assisted_conversion.
• A play may declare salesMotion: AI preparation, a human role, a handoff boundary. It passes bounded_sales_effort only with at most two calls and at most 90 planned human minutes per closed account; a play above the ceiling must fail the gate and is deferred. Under selfserve-first a mandatory call cannot pass selfserve_purchase. sales_led, ai_sdr_calls and webinar_demo plays must declare a motion under sales-assisted.
• A play may declare productionAsset (paid UGC, AI UGC, founder content, product demo, commissioned creator, customer content). It supplies creative, never reach. AI UGC declares a synthetic person; paid or synthetic people are never presented as customers; creator amplification needs explicit ad authorization.
• A wave of eight or more drafts keeps any primary method at or below 25% and spans at least four method families (OPPORTUNITY_WAVE_V11_CHANNEL_VARIETY).

Package verification

• bun run test
• bun run typecheck
• bun run lint:check
• bun run build