@balpal4495/quorum 2.0.0 → 3.0.0

package/modules/compass/prompts/index.ts

@@ -0,0 +1,230 @@
+export function buildBriefPrompt(params: {
+  chronicleContext: string
+  behaviorContext: string
+  area?: string
+}): string {
+  return `Produce a Compass Brief — a summary of current product direction.
+
+${params.area ? `Focus area: ${params.area}\n` : ""}
+
+## Chronicle evidence (approved project memory)
+${params.chronicleContext}
+
+## Current product behaviour
+${params.behaviorContext}
+
+Return ONLY valid JSON with this exact schema (no markdown fences, no explanation):
+{
+  "product_direction": "<one clear sentence describing where the product is pointed>",
+  "known_from_chronicle": ["<fact from Chronicle>"],
+  "known_from_behavior": ["<fact from code/docs/tests>"],
+  "inferred": ["<inference — not stated directly in evidence>"],
+  "assumptions": ["<assumption being made>"],
+  "unknowns": ["<what is not known — especially user behaviour>"],
+  "missing_evidence": ["<what evidence would improve this brief>"],
+  "recommended_next_step": "<specific quorum command or action>",
+  "confidence": <number 0–1>
+}
+
+Rules:
+- known_from_chronicle must cite specific decisions, not paraphrase
+- unknowns must include "No analytics or support evidence connected" if no user data provided
+- confidence reflects how strongly the direction can be stated from available evidence`
+}
+
+export function buildPathwaysPrompt(params: {
+  goal: string
+  horizon?: string
+  appetite?: string
+  chronicleContext: string
+  behaviorContext: string
+  area?: string
+  limit?: number
+}): string {
+  return `Generate ${params.limit ?? 5} product pathways toward the following goal.
+
+Goal: ${params.goal}
+${params.horizon ? `Horizon: ${params.horizon}` : ""}
+${params.appetite ? `Appetite: ${params.appetite}` : ""}
+${params.area ? `Focus area: ${params.area}` : ""}
+
+## Chronicle evidence (approved project memory)
+${params.chronicleContext}
+
+## Current product behaviour
+${params.behaviorContext}
+
+Return ONLY valid JSON with this exact schema (no markdown fences, no explanation):
+{
+  "pathways": [
+    {
+      "id": "<slug-id>",
+      "kind": "product_pathway",
+      "title": "<pathway title>",
+      "goal": "<goal this pathway serves>",
+      "target_user": "<who this is for>",
+      "problem": "<user problem being solved>",
+      "current_behaviors": ["<existing behaviour this builds on>"],
+      "opportunity": "<what gap or need this addresses>",
+      "why_now": "<why this makes sense at this stage>",
+      "smallest_useful_version": "<minimum version that validates the idea>",
+      "phases": [
+        {
+          "name": "<phase name>",
+          "outcome": "<what this phase delivers>",
+          "user_value": "<value to the user>",
+          "build_notes": ["<optional implementation note>"],
+          "dependencies": ["<dependency>"],
+          "risks": ["<risk>"]
+        }
+      ],
+      "dependencies": ["<dependency>"],
+      "risks": ["<risk>"],
+      "assumptions": ["<assumption — must be present>"],
+      "open_questions": ["<unanswered question>"],
+      "evidence": [
+        {
+          "id": "<evidence id>",
+          "kind": "chronicle|docs|cli|code|inference|assumption",
+          "source": "<source path or label>",
+          "summary": "<what this evidence says>",
+          "confidence": <0–1>
+        }
+      ],
+      "scores": {
+        "strategic_fit": <0–1>,
+        "user_problem_clarity": <0–1>,
+        "evidence_strength": <0–1>,
+        "leverage": <0–1>,
+        "feasibility": <0–1>,
+        "time_to_signal": <0–1>,
+        "reversibility": <0–1>,
+        "complexity_penalty": <0–1>,
+        "dependency_penalty": <0–1>,
+        "contradiction_penalty": <0–1>,
+        "evidence_gap_penalty": <0–1>,
+        "total": <0–100>
+      },
+      "confidence": <0–1>,
+      "time_to_signal": "<e.g. '1-2 sessions', '2 weeks'>",
+      "reversibility": "high|medium|low",
+      "suggested_next_step": "<specific actionable next step>"
+    }
+  ]
+}
+
+Rules:
+- Every pathway must cite at least one evidence reference
+- Reject generic feature ideas — every pathway must build on current behaviour or approved memory
+- Compute scores.total using: strategic_fit*20 + user_problem_clarity*15 + evidence_strength*20 + leverage*10 + feasibility*15 + time_to_signal*10 + reversibility*10 - complexity_penalty*10 - dependency_penalty*8 - contradiction_penalty*15 - evidence_gap_penalty*12
+- Clamp total to 0–100
+- Assumptions must always be present (minimum 1)
+- unknowns must note if no user evidence is connected
+- Sort by scores.total descending`
+}
+
+export function buildBetsPrompt(params: {
+  horizon?: string
+  goal?: string
+  appetite?: string
+  chronicleContext: string
+  behaviorContext: string
+}): string {
+  return `Generate 2–3 strategic product bets.
+
+${params.horizon ? `Horizon: ${params.horizon}` : ""}
+${params.goal ? `Goal: ${params.goal}` : ""}
+${params.appetite ? `Appetite: ${params.appetite}` : ""}
+
+## Chronicle evidence
+${params.chronicleContext}
+
+## Current product behaviour
+${params.behaviorContext}
+
+Return ONLY valid JSON with this exact schema (no markdown fences):
+{
+  "bets": [
+    {
+      "id": "<slug-id>",
+      "kind": "product_bet",
+      "title": "<bet title>",
+      "thesis": "<falsifiable product hypothesis — one sentence>",
+      "why_now": "<why this moment>",
+      "target_user": "<who>",
+      "upside": "<best case>",
+      "downside": "<realistic downside>",
+      "assumptions": ["<assumption — minimum 2>"],
+      "validation_signals": ["<signal that confirms the thesis>"],
+      "invalidation_signals": ["<signal that refutes the thesis>"],
+      "kill_criteria": ["<when to stop>"],
+      "first_experiment": "<smallest first test>",
+      "build_path": ["<phase 1>", "<phase 2>"],
+      "evidence": [{ "id": "<id>", "kind": "chronicle|inference|docs|cli", "source": "<source>", "summary": "<summary>", "confidence": <0–1> }],
+      "scores": {
+        "strategic_fit": <0–1>, "user_problem_clarity": <0–1>, "evidence_strength": <0–1>,
+        "leverage": <0–1>, "feasibility": <0–1>, "time_to_signal": <0–1>, "reversibility": <0–1>,
+        "complexity_penalty": <0–1>, "dependency_penalty": <0–1>, "contradiction_penalty": <0–1>,
+        "evidence_gap_penalty": <0–1>, "total": <0–100>
+      },
+      "confidence": <0–1>,
+      "time_to_signal": "<timeframe>",
+      "reversibility": "high|medium|low",
+      "appetite": "small|medium|large"
+    }
+  ]
+}
+
+Rules:
+- A bet is a falsifiable hypothesis, not a feature list
+- Kill criteria must be present
+- Invalidation signals must be present
+- If no user evidence is available, evidence_strength should be ≤ 0.4`
+}
+
+export function buildScorePrompt(params: {
+  idea: string
+  context?: string
+  chronicleContext: string
+  behaviorContext: string
+}): string {
+  return `Evaluate this product idea.
+
+Idea: ${params.idea}
+${params.context ? `Context: ${params.context}` : ""}
+
+## Chronicle evidence
+${params.chronicleContext}
+
+## Current product behaviour
+${params.behaviorContext}
+
+Return ONLY valid JSON with this exact schema (no markdown fences):
+{
+  "idea": "${params.idea}",
+  "summary": "<one sentence summary of what this idea is>",
+  "recommendation": "pursue|pursue-small-test|investigate-more|defer|avoid",
+  "scores": {
+    "strategic_fit": <0–1>, "user_problem_clarity": <0–1>, "evidence_strength": <0–1>,
+    "leverage": <0–1>, "feasibility": <0–1>, "time_to_signal": <0–1>, "reversibility": <0–1>,
+    "complexity_penalty": <0–1>, "dependency_penalty": <0–1>, "contradiction_penalty": <0–1>,
+    "evidence_gap_penalty": <0–1>, "total": <0–100>
+  },
+  "evidence": [{ "id": "<id>", "kind": "<kind>", "source": "<source>", "summary": "<summary>", "confidence": <0–1> }],
+  "supporting_reasons": ["<reason this scores well>"],
+  "risks": ["<risk>"],
+  "assumptions": ["<assumption>"],
+  "open_questions": ["<question>"],
+  "suggested_next_step": "<specific next action>"
+}
+
+Score total = strategic_fit*20 + user_problem_clarity*15 + evidence_strength*20 + leverage*10 + feasibility*15 + time_to_signal*10 + reversibility*10 - complexity_penalty*10 - dependency_penalty*8 - contradiction_penalty*15 - evidence_gap_penalty*12. Clamp 0–100.
+
+Penalise:
+- weak or missing evidence
+- conflicts with Chronicle decisions
+- high infrastructure/hosting/auth burden
+- unclear user problem
+- long time-to-signal
+- low reversibility`
+}

package/modules/compass/prompts/system.ts

@@ -0,0 +1,24 @@
+export const COMPASS_SYSTEM_PROMPT = `You are Quorum Compass, the product-direction module for an AI-assisted software team.
+
+Your job is to help decide where the product should go next.
+
+You are not a generic brainstormer.
+You must ground every recommendation in provided evidence.
+
+Evidence may come from:
+- Chronicle memory (human-approved past decisions)
+- current code behaviour
+- docs
+- tests
+- package metadata
+- CLI commands
+
+Rules:
+1. Separate known facts from inferences and assumptions.
+2. Never claim user demand unless user evidence (analytics, support, issues) is provided.
+3. Prefer small, reversible next moves unless asked for big bets.
+4. Identify contradictions with Chronicle or current product behaviour.
+5. Include assumptions, invalidation signals, and open questions.
+6. Do not recommend implementation details beyond product-level guidance.
+7. Return only valid JSON matching the requested schema.
+8. When no analytics/support data is connected, always state: "No direct user signal connected."`

package/modules/compass/propose.ts

@@ -0,0 +1,152 @@
+import type { OracleClient } from "../shared/types"
+import type {
+  CompassProposalInput, CompassProposalResult,
+  CompassOutcomeInput, CompassOutcomeResultPayload,
+  ProductPathway, ProductBet, ProductPathwayPhase,
+} from "./types"
+
+/**
+ * Stage a Compass-generated artifact as a Chronicle proposal.
+ *
+ * Writes to .chronicle/proposals/ ONLY via oracle.propose().
+ * Never calls oracle.commit(). Human must approve.
+ */
+export async function stageProposal(
+  input: CompassProposalInput,
+  oracle: OracleClient,
+): Promise<CompassProposalResult> {
+  const payload = input.payload as ProductPathway | ProductBet
+
+  const decision = buildDecision(input)
+  const key_insight = decision.slice(0, 200)
+
+  const entry = {
+    key_insight,
+    decision,
+    schema_version: 2 as const,
+    topic: buildTopic(input),
+    scope: buildScope(input),
+    affected_areas: buildAffectedAreas(input),
+    status: "open" as const,
+    confidence: "confidence" in payload ? payload.confidence : 0.7,
+    source_module: "compass",
+    evidence_cited: [],
+    alternatives_considered: "assumptions" in payload ? [] : [],
+    rejected_reason: [],
+    validation_plan: buildValidationPlan(input),
+    review_after: reviewAfterDate(),
+  }
+
+  const result = await oracle.propose(entry)
+
+  return {
+    proposal_id: result.proposalId,
+    message: `Staged Chronicle proposal ${result.proposalId.slice(0, 8)} — run 'quorum commit --list' to review.`,
+  }
+}
+
+/**
+ * Stage an outcome update for a prior product bet or pathway.
+ * Creates a new proposal that supersedes the original entry.
+ */
+export async function stageOutcome(
+  input: CompassOutcomeInput,
+  oracle: OracleClient,
+): Promise<CompassOutcomeResultPayload> {
+  const resultLabel: Record<string, string> = {
+    "validated": "has been validated",
+    "partially-validated": "has been partially validated",
+    "invalidated": "has been invalidated",
+    "unclear": "outcome is unclear — insufficient signal",
+    "superseded": "has been superseded by a newer approach",
+  }
+
+  const label = resultLabel[input.result] ?? input.result
+  const decision = `Product bet/pathway ${input.entry_id.slice(0, 8)} ${label}.${input.note ? " " + input.note : ""}`
+
+  const entry = {
+    key_insight: decision.slice(0, 200),
+    decision,
+    schema_version: 2 as const,
+    topic: `product/outcome/${input.entry_id.slice(0, 8)}`,
+    scope: ["product", "compass", "outcome"],
+    affected_areas: [],
+    status: "validated" as const,
+    confidence: input.result === "validated" ? 0.9
+      : input.result === "partially-validated" ? 0.7
+      : input.result === "invalidated" ? 0.6
+      : 0.5,
+    source_module: "compass",
+    evidence_cited: [input.entry_id],
+    alternatives_considered: [],
+    rejected_reason: [],
+    validation_plan: [],
+    post_merge_result: (input.result === "validated" ? "successful"
+      : input.result === "invalidated" ? "rolled-back"
+      : input.result === "partially-validated" ? "partial"
+      : undefined) as "successful" | "bug" | "partial" | "rolled-back" | undefined,
+  }
+
+  const result = await oracle.propose(entry)
+  return {
+    proposal_id: result.proposalId,
+    message: `Staged outcome proposal ${result.proposalId.slice(0, 8)} — run 'quorum commit --list' to review.`,
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildDecision(input: CompassProposalInput): string {
+  const p = input.payload as ProductPathway | ProductBet
+  if (input.artifact_kind === "product_pathway" && "smallest_useful_version" in p) {
+    return `Compass identified '${(p as ProductPathway).title}' as a product pathway: ${(p as ProductPathway).smallest_useful_version}`
+  }
+  if (input.artifact_kind === "product_bet" && "thesis" in p) {
+    return `Product bet: ${(p as ProductBet).thesis}`
+  }
+  if ("title" in p) {
+    return `Compass ${input.artifact_kind.replace("_", " ")}: ${(p as { title: string }).title}`
+  }
+  return `Compass generated ${input.artifact_kind} artifact.`
+}
+
+function buildTopic(input: CompassProposalInput): string {
+  const p = input.payload
+  if ("title" in p) return `product/${input.artifact_kind.replace("product_", "")}/${slugify((p as { title: string }).title)}`
+  return `product/${input.artifact_kind}`
+}
+
+function buildScope(input: CompassProposalInput): string[] {
+  const base = ["product", "compass", input.artifact_kind.replace("product_", "")]
+  const p = input.payload
+  if ("goal" in p && (p as ProductPathway).goal) base.push(slugify((p as ProductPathway).goal).slice(0, 20))
+  return base
+}
+
+function buildAffectedAreas(input: CompassProposalInput): string[] {
+  const p = input.payload
+  if ("phases" in p) {
+    return (p as ProductPathway).phases
+      .flatMap((ph: ProductPathwayPhase) => ph.dependencies)
+      .filter(Boolean)
+      .slice(0, 5)
+  }
+  return []
+}
+
+function buildValidationPlan(input: CompassProposalInput): string[] {
+  const p = input.payload
+  if ("validation_signals" in p) return (p as ProductBet).validation_signals.slice(0, 3)
+  if ("suggested_next_step" in p) return [(p as ProductPathway).suggested_next_step]
+  return []
+}
+
+function reviewAfterDate(): string {
+  const d = new Date()
+  d.setDate(d.getDate() + 45)
+  return d.toISOString().slice(0, 10)
+}
+
+function slugify(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40)
+}

package/modules/compass/schemas.ts

@@ -0,0 +1,121 @@
+import { z } from "zod"
+
+export const CompassEvidenceRefSchema = z.object({
+  id: z.string(),
+  kind: z.enum([
+    "chronicle", "advisor", "sentinel", "code", "docs", "tests",
+    "config", "cli", "package", "issue", "analytics", "support",
+    "inference", "assumption", "unknown",
+  ]),
+  source: z.string(),
+  path: z.string().optional(),
+  line: z.number().optional(),
+  entry_id: z.string().optional(),
+  summary: z.string().min(1),
+  quote: z.string().optional(),
+  confidence: z.number().min(0).max(1),
+})
+
+export const ProductScoreBreakdownSchema = z.object({
+  strategic_fit:         z.number().min(0).max(1),
+  user_problem_clarity:  z.number().min(0).max(1),
+  evidence_strength:     z.number().min(0).max(1),
+  leverage:              z.number().min(0).max(1),
+  feasibility:           z.number().min(0).max(1),
+  time_to_signal:        z.number().min(0).max(1),
+  reversibility:         z.number().min(0).max(1),
+  complexity_penalty:    z.number().min(0).max(1),
+  dependency_penalty:    z.number().min(0).max(1),
+  contradiction_penalty: z.number().min(0).max(1),
+  evidence_gap_penalty:  z.number().min(0).max(1),
+  total:                 z.number().min(0).max(100),
+})
+
+export const ProductPathwayPhaseSchema = z.object({
+  name:         z.string().min(1),
+  outcome:      z.string().min(1),
+  user_value:   z.string().min(1),
+  build_notes:  z.array(z.string()).optional(),
+  dependencies: z.array(z.string()),
+  risks:        z.array(z.string()),
+})
+
+export const ProductPathwaySchema = z.object({
+  id:                    z.string(),
+  kind:                  z.literal("product_pathway"),
+  title:                 z.string().min(1),
+  goal:                  z.string().min(1),
+  target_user:           z.string().optional(),
+  problem:               z.string().optional(),
+  current_behaviors:     z.array(z.string()).min(1),
+  opportunity:           z.string().min(1),
+  why_now:               z.string().min(1),
+  smallest_useful_version: z.string().min(1),
+  phases:                z.array(ProductPathwayPhaseSchema),
+  dependencies:          z.array(z.string()),
+  risks:                 z.array(z.string()),
+  assumptions:           z.array(z.string()).min(1),
+  open_questions:        z.array(z.string()),
+  evidence:              z.array(CompassEvidenceRefSchema).min(1),
+  scores:                ProductScoreBreakdownSchema,
+  confidence:            z.number().min(0).max(1),
+  time_to_signal:        z.string().min(1),
+  reversibility:         z.enum(["high", "medium", "low"]),
+  suggested_next_step:   z.string().min(1),
+})
+
+export const ProductBetSchema = z.object({
+  id:                   z.string(),
+  kind:                 z.literal("product_bet"),
+  title:                z.string().min(1),
+  thesis:               z.string().min(1),
+  why_now:              z.string().min(1),
+  target_user:          z.string().optional(),
+  upside:               z.string().min(1),
+  downside:             z.string().min(1),
+  assumptions:          z.array(z.string()).min(1),
+  validation_signals:   z.array(z.string()).min(1),
+  invalidation_signals: z.array(z.string()).min(1),
+  kill_criteria:        z.array(z.string()).min(1),
+  first_experiment:     z.string().min(1),
+  build_path:           z.array(z.string()),
+  evidence:             z.array(CompassEvidenceRefSchema).min(1),
+  scores:               ProductScoreBreakdownSchema,
+  confidence:           z.number().min(0).max(1),
+  time_to_signal:       z.string().min(1),
+  reversibility:        z.enum(["high", "medium", "low"]),
+  appetite:             z.enum(["small", "medium", "large"]),
+})
+
+export const ProductIdeaScoreSchema = z.object({
+  idea:               z.string().min(1),
+  summary:            z.string().min(1),
+  recommendation:     z.enum(["pursue", "pursue-small-test", "investigate-more", "defer", "avoid"]),
+  scores:             ProductScoreBreakdownSchema,
+  evidence:           z.array(CompassEvidenceRefSchema),
+  supporting_reasons: z.array(z.string()),
+  risks:              z.array(z.string()),
+  assumptions:        z.array(z.string()),
+  open_questions:     z.array(z.string()),
+  suggested_next_step: z.string().min(1),
+})
+
+export const CompassBriefLLMSchema = z.object({
+  product_direction:        z.string().min(1),
+  known_from_chronicle:     z.array(z.string()),
+  known_from_behavior:      z.array(z.string()),
+  inferred:                 z.array(z.string()),
+  assumptions:              z.array(z.string()),
+  unknowns:                 z.array(z.string()),
+  missing_evidence:         z.array(z.string()),
+  recommended_next_step:    z.string().min(1),
+  confidence:               z.number().min(0).max(1),
+})
+
+export const PathwaysLLMSchema = z.object({
+  pathways: z.array(ProductPathwaySchema),
+})
+
+export const BetsLLMSchema = z.object({
+  bets: z.array(ProductBetSchema),
+})

package/modules/compass/score.ts

@@ -0,0 +1,77 @@
+import type { ProductScoreBreakdown } from "./types"
+
+/**
+ * Compute a directional product score from raw dimension values.
+ *
+ * Each dimension is 0–1. Penalty dimensions reduce the total.
+ * Final score is clamped to 0–100.
+ *
+ * Interpretation:
+ *   85–100  Very strong; build or spec next
+ *   70–84   Strong; pursue a small test
+ *   55–69   Plausible; investigate more
+ *   40–54   Weak; defer unless strategic
+ *   0–39    Avoid for now
+ */
+export function computeScore(dims: Omit<ProductScoreBreakdown, "total">): ProductScoreBreakdown {
+  const raw =
+    dims.strategic_fit         * 20 +
+    dims.user_problem_clarity  * 15 +
+    dims.evidence_strength     * 20 +
+    dims.leverage              * 10 +
+    dims.feasibility           * 15 +
+    dims.time_to_signal        * 10 +
+    dims.reversibility         * 10 -
+    dims.complexity_penalty    * 10 -
+    dims.dependency_penalty    *  8 -
+    dims.contradiction_penalty * 15 -
+    dims.evidence_gap_penalty  * 12
+
+  const total = Math.max(0, Math.min(100, Math.round(raw)))
+  return { ...dims, total }
+}
+
+export function scoreToRecommendation(
+  total: number,
+): "pursue" | "pursue-small-test" | "investigate-more" | "defer" | "avoid" {
+  if (total >= 85) return "pursue"
+  if (total >= 70) return "pursue-small-test"
+  if (total >= 55) return "investigate-more"
+  if (total >= 40) return "defer"
+  return "avoid"
+}
+
+export function scoreToLabel(total: number): string {
+  if (total >= 85) return "Very strong"
+  if (total >= 70) return "Strong"
+  if (total >= 55) return "Plausible"
+  if (total >= 40) return "Weak"
+  return "Avoid"
+}
+
+/**
+ * Build a human-readable explanation for a score.
+ */
+export function explainScore(scores: ProductScoreBreakdown): { strengths: string[]; weaknesses: string[] } {
+  const strengths: string[] = []
+  const weaknesses: string[] = []
+
+  if (scores.strategic_fit >= 0.7) strengths.push("Strong strategic fit with current product direction")
+  if (scores.evidence_strength >= 0.7) strengths.push("Well-supported by Chronicle or code evidence")
+  if (scores.feasibility >= 0.7) strengths.push("Technically feasible given current architecture")
+  if (scores.reversibility >= 0.7) strengths.push("Highly reversible — easy to change course")
+  if (scores.leverage >= 0.7) strengths.push("High leverage — small build unlocks significant value")
+  if (scores.time_to_signal >= 0.7) strengths.push("Fast time-to-signal — team learns quickly")
+  if (scores.user_problem_clarity >= 0.7) strengths.push("Clear user problem and target")
+
+  if (scores.evidence_strength < 0.4) weaknesses.push("Weak evidence — mostly inference or assumption")
+  if (scores.evidence_gap_penalty > 0.5) weaknesses.push("Significant evidence gaps — needs more investigation")
+  if (scores.contradiction_penalty > 0.3) weaknesses.push("May conflict with prior Chronicle decisions")
+  if (scores.dependency_penalty > 0.4) weaknesses.push("High dependency burden — external services or platform work required")
+  if (scores.complexity_penalty > 0.4) weaknesses.push("Adds significant complexity — UI, infrastructure, or support burden")
+  if (scores.time_to_signal < 0.4) weaknesses.push("Long time-to-signal — hard to validate quickly")
+  if (scores.strategic_fit < 0.4) weaknesses.push("Weak strategic fit with current product direction")
+  if (scores.user_problem_clarity < 0.4) weaknesses.push("User problem or target not yet clearly defined")
+
+  return { strengths, weaknesses }
+}