@balpal4495/quorum 3.0.4 → 3.1.0

package/modules/compass/types.ts

@@ -1,431 +0,0 @@
-import type { LLMProvider, OracleClient } from "../shared/types"
-import type { AdvisorOutput } from "../advisor/types"
-
-// ── Evidence ──────────────────────────────────────────────────────────────────
-
-export type CompassEvidenceKind =
-  | "chronicle"
-  | "advisor"
-  | "sentinel"
-  | "code"
-  | "docs"
-  | "tests"
-  | "config"
-  | "cli"
-  | "package"
-  | "issue"
-  | "analytics"
-  | "support"
-  | "inference"
-  | "assumption"
-  | "unknown"
-
-export interface CompassEvidenceRef {
-  id: string
-  kind: CompassEvidenceKind
-  source: string
-  path?: string
-  line?: number
-  entry_id?: string
-  summary: string
-  quote?: string
-  confidence: number
-}
-
-// ── Source scanner interface ──────────────────────────────────────────────────
-
-export interface ProductSourceFinding {
-  id: string
-  kind: CompassEvidenceKind
-  source: string
-  path?: string
-  line?: number
-  title: string
-  summary: string
-  raw?: string
-  confidence: number
-  tags: string[]
-}
-
-export interface ProductSourceScanInput {
-  rootDir: string
-  area?: string
-  include?: string[]
-  exclude?: string[]
-}
-
-export interface ProductSource {
-  id: string
-  kind: "docs" | "code" | "tests" | "config" | "cli" | "package" | "issue" | "analytics" | "support"
-  scan(input: ProductSourceScanInput): Promise<ProductSourceFinding[]>
-}
-
-// ── Bearings ──────────────────────────────────────────────────────────────────
-
-export interface ProductBearing {
-  id: string
-  title: string
-  summary: string
-  area?: string
-  evidence: CompassEvidenceRef[]
-  confidence: number
-}
-
-// ── Terrain / behaviour map ───────────────────────────────────────────────────
-
-export type BehaviorBasis = "documented" | "implemented" | "tested" | "observed" | "inferred"
-
-export interface ProductBehavior {
-  id: string
-  area: string
-  name: string
-  description: string
-  current_behavior: string
-  evidence: CompassEvidenceRef[]
-  basis: BehaviorBasis[]
-  confidence: number
-  notes?: string[]
-}
-
-export interface ProductBehaviorGap {
-  id: string
-  area: string
-  gap: string
-  why_it_matters: string
-  evidence: CompassEvidenceRef[]
-  confidence: number
-}
-
-export interface ProductBehaviorContradiction {
-  id: string
-  area: string
-  docs_claim: string
-  implementation_claim: string
-  evidence: CompassEvidenceRef[]
-  severity: "low" | "medium" | "high"
-}
-
-export interface BehaviorMap {
-  generated_at: string
-  area?: string
-  behaviors: ProductBehavior[]
-  gaps: ProductBehaviorGap[]
-  contradictions: ProductBehaviorContradiction[]
-  confidence: number
-}
-
-export interface BehaviorMapInput {
-  area?: string
-  source?: string
-}
-
-export interface BehaviorQuestionInput {
-  question: string
-  area?: string
-  deterministic?: boolean
-}
-
-export interface BehaviorAnswer {
-  question: string
-  what_exists: string[]
-  what_appears_missing: string[]
-  product_implication: string
-  evidence: CompassEvidenceRef[]
-  confidence: number
-}
-
-// ── Observations ──────────────────────────────────────────────────────────────
-
-export interface ProductObservation {
-  id: string
-  kind: "product_observation"
-  title: string
-  observation: string
-  area: string
-  evidence: CompassEvidenceRef[]
-  implications: string[]
-  confidence: number
-}
-
-// ── Hypotheses ────────────────────────────────────────────────────────────────
-
-export interface ProductHypothesis {
-  id: string
-  kind: "product_hypothesis"
-  title: string
-  hypothesis: string
-  target_user?: string
-  problem?: string
-  assumptions: string[]
-  validation_signals: string[]
-  invalidation_signals: string[]
-  evidence: CompassEvidenceRef[]
-  confidence: number
-}
-
-// ── Scoring ───────────────────────────────────────────────────────────────────
-
-export interface ProductScoreBreakdown {
-  strategic_fit: number
-  user_problem_clarity: number
-  evidence_strength: number
-  leverage: number
-  feasibility: number
-  time_to_signal: number
-  reversibility: number
-  complexity_penalty: number
-  dependency_penalty: number
-  contradiction_penalty: number
-  evidence_gap_penalty: number
-  total: number
-}
-
-// ── Opportunities ─────────────────────────────────────────────────────────────
-
-export interface ProductOpportunity {
-  id: string
-  title: string
-  area: string
-  why_it_matters: string
-  evidence_strength: "strong" | "medium" | "weak" | "inferred"
-  suggested_next_step: string
-  evidence: CompassEvidenceRef[]
-  confidence: number
-}
-
-export interface OpportunitiesInput {
-  goal?: string
-  area?: string
-  limit?: number
-}
-
-// ── Pathways ──────────────────────────────────────────────────────────────────
-
-export interface ProductPathwayPhase {
-  name: string
-  outcome: string
-  user_value: string
-  build_notes?: string[]
-  dependencies: string[]
-  risks: string[]
-}
-
-export interface ProductPathway {
-  id: string
-  kind: "product_pathway"
-  title: string
-  goal: string
-  target_user?: string
-  problem?: string
-  current_behaviors: string[]
-  opportunity: string
-  why_now: string
-  smallest_useful_version: string
-  phases: ProductPathwayPhase[]
-  dependencies: string[]
-  risks: string[]
-  assumptions: string[]
-  open_questions: string[]
-  evidence: CompassEvidenceRef[]
-  scores: ProductScoreBreakdown
-  confidence: number
-  time_to_signal: string
-  reversibility: "high" | "medium" | "low"
-  suggested_next_step: string
-}
-
-export interface PathwaysInput {
-  goal: string
-  horizon?: string
-  appetite?: "small" | "medium" | "large"
-  area?: string
-  limit?: number
-}
-
-// ── Bets ──────────────────────────────────────────────────────────────────────
-
-export interface ProductBet {
-  id: string
-  kind: "product_bet"
-  title: string
-  thesis: string
-  why_now: string
-  target_user?: string
-  upside: string
-  downside: string
-  assumptions: string[]
-  validation_signals: string[]
-  invalidation_signals: string[]
-  kill_criteria: string[]
-  first_experiment: string
-  build_path: string[]
-  evidence: CompassEvidenceRef[]
-  scores: ProductScoreBreakdown
-  confidence: number
-  time_to_signal: string
-  reversibility: "high" | "medium" | "low"
-  appetite: "small" | "medium" | "large"
-}
-
-export interface BigBetsInput {
-  horizon?: string
-  goal?: string
-  appetite?: "small" | "medium" | "large"
-}
-
-// ── Idea scoring ──────────────────────────────────────────────────────────────
-
-export interface ProductIdeaScore {
-  idea: string
-  summary: string
-  recommendation: "pursue" | "pursue-small-test" | "investigate-more" | "defer" | "avoid"
-  scores: ProductScoreBreakdown
-  evidence: CompassEvidenceRef[]
-  supporting_reasons: string[]
-  risks: string[]
-  assumptions: string[]
-  open_questions: string[]
-  suggested_next_step: string
-}
-
-export interface ScoreIdeaInput {
-  idea: string
-  context?: string
-}
-
-// ── Product brief ─────────────────────────────────────────────────────────────
-
-export interface ProductBrief {
-  title: string
-  problem: string
-  target_user?: string
-  current_behavior: string[]
-  product_opportunity: string
-  recommended_solution: string
-  smallest_useful_version: string
-  non_goals: string[]
-  user_flow: string[]
-  implementation_notes: string[]
-  dependencies: string[]
-  risks: string[]
-  open_questions: string[]
-  assumptions: string[]
-  validation_signals: string[]
-  invalidation_signals: string[]
-  evidence: CompassEvidenceRef[]
-  suggested_quorum_checks: string[]
-}
-
-export interface ProductBriefInput {
-  title: string
-  pathway_id?: string
-  idea?: string
-  context?: string
-}
-
-// ── Compass brief ─────────────────────────────────────────────────────────────
-
-export interface CompassBrief {
-  generated_at: string
-  area?: string
-  product_direction: string
-  known_from_chronicle: string[]
-  known_from_behavior: string[]
-  inferred: string[]
-  assumptions: string[]
-  unknowns: string[]
-  opportunities: ProductOpportunity[]
-  missing_evidence: string[]
-  recommended_next_step: string
-  confidence: number
-}
-
-export interface CompassBriefInput {
-  area?: string
-}
-
-// ── Proposals ─────────────────────────────────────────────────────────────────
-
-export type CompassArtifactKind =
-  | "product_observation"
-  | "product_hypothesis"
-  | "product_pathway"
-  | "product_bet"
-  | "product_idea_score"
-  | "product_outcome"
-
-export interface CompassProposalInput {
-  artifact_kind: CompassArtifactKind
-  artifact_id: string
-  payload: ProductPathway | ProductBet | ProductObservation | ProductIdeaScore
-}
-
-export interface CompassProposalResult {
-  proposal_id: string
-  message: string
-}
-
-// ── Outcomes ──────────────────────────────────────────────────────────────────
-
-export type CompassOutcomeResult =
-  | "validated"
-  | "partially-validated"
-  | "invalidated"
-  | "unclear"
-  | "superseded"
-
-export interface CompassOutcomeInput {
-  entry_id: string
-  result: CompassOutcomeResult
-  note?: string
-}
-
-export interface CompassOutcomeResultPayload {
-  proposal_id: string
-  message: string
-}
-
-// ── Main Compass interface ────────────────────────────────────────────────────
-
-export interface Compass {
-  brief(input?: CompassBriefInput): Promise<CompassBrief>
-  mapBehaviors(input?: BehaviorMapInput): Promise<BehaviorMap>
-  behavior(input: BehaviorQuestionInput): Promise<BehaviorAnswer>
-  opportunities(input?: OpportunitiesInput): Promise<ProductOpportunity[]>
-  pathways(input: PathwaysInput): Promise<ProductPathway[]>
-  bigBets(input: BigBetsInput): Promise<ProductBet[]>
-  scoreIdea(input: ScoreIdeaInput): Promise<ProductIdeaScore>
-  productBrief(input: ProductBriefInput): Promise<ProductBrief>
-  propose(input: CompassProposalInput): Promise<CompassProposalResult>
-  outcome(input: CompassOutcomeInput): Promise<CompassOutcomeResultPayload>
-}
-
-// ── Options ───────────────────────────────────────────────────────────────────
-
-export interface CreateCompassOptions {
-  oracle: OracleClient
-  advisor?: {
-    ask: (question: string) => Promise<AdvisorOutput>
-  }
-  /**
-   * Required for LLM-backed commands: brief (with synthesis), pathways,
-   * bigBets, scoreIdea, productBrief, behavior (non-deterministic).
-   * Not required for deterministic mapBehaviors.
-   */
-  llm?: LLMProvider
-  rootDir?: string
-  chronicleDir?: string
-  sources?: ProductSource[]
-  models?: {
-    brief?: string
-    pathways?: string
-    bets?: string
-    score?: string
-  }
-  /**
-   * How aggressively to surface low-evidence recommendations.
-   * "strict" penalises more. "exploratory" allows weaker evidence through.
-   * Default: "balanced"
-   */
-  minimumEvidence?: "strict" | "balanced" | "exploratory"
-}

package/modules/council/advisors.ts

@@ -1,71 +0,0 @@
-import type { LLMProvider, OracleResult } from "../shared/types"
-import { entryText } from "../shared/types"
-import type { AdvisorPersona } from "./personas"
-
-export interface AdvisorResponse {
-  persona: string
-  response: string
-}
-
-function formatEvidence(evidence: OracleResult[]): string {
-  if (evidence.length === 0) {
-    return "No Oracle entries are available. Reason from absence of evidence — name what is missing."
-  }
-  return evidence
-    .map(e =>
-      `[${e.id}] (${e.status})
-${entryText(e)}
-Areas: ${e.affected_areas.join(", ")}${e.scope ? " | " + e.scope.join(", ") : ""}`,
-    )
-    .join("\n\n")
-}
-
-/**
- * Run all advisors in parallel.
- * Each advisor receives the framed question, the Oracle evidence pack,
- * and their persona's system prompt fragment.
- *
- * Advisors MUST cite specific Oracle entry IDs — this is enforced in the prompt.
- */
-export async function fanOutAdvisors(
-  framedQuestion: string,
-  evidence: OracleResult[],
-  personas: readonly AdvisorPersona[],
-  llm: LLMProvider,
-  model?: string,
-): Promise<AdvisorResponse[]> {
-  const evidenceText = formatEvidence(evidence)
-
-  return Promise.all(
-    personas.map(async (persona): Promise<AdvisorResponse> => {
-      const systemPrompt = [
-        `You are a Council advisor — ${persona.name}.`,
-        "",
-        persona.systemFragment,
-        "",
-        "Rules:",
-        "- Reason ONLY from the Oracle evidence provided. Do not use general knowledge.",
-        "- Cite specific Oracle entry IDs (e.g. [abc-123]) for every claim you make.",
-        "- If the evidence is insufficient to support a claim, say so explicitly.",
-        "- Keep your response focused and under 400 words.",
-      ].join("\n")
-
-      const userPrompt = [
-        framedQuestion,
-        "",
-        "## Oracle Evidence",
-        evidenceText,
-      ].join("\n")
-
-      const response = await llm(
-        [
-          { role: "system", content: systemPrompt },
-          { role: "user", content: userPrompt },
-        ],
-        model,
-      )
-
-      return { persona: persona.name, response }
-    }),
-  )
-}

package/modules/council/chairman.ts

@@ -1,183 +0,0 @@
-import { z } from "zod"
-import type { LLMProvider, OracleResult } from "../shared/types"
-import { entryText } from "../shared/types"
-import type { AdvisorResponse } from "./advisors"
-import type { ReviewerResponse } from "./reviewers"
-import type { CouncilOutput, CitationValidation } from "./types"
-
-const BlockerSchema = z.object({
-  issue: z.string().min(1),
-  evidence: z.array(z.string()),
-  required_fix: z.string().min(1),
-})
-
-const WarningSchema = z.object({
-  issue: z.string().min(1),
-  suggested_fix: z.string().optional(),
-})
-
-const AdvisorSplitSchema = z.object({
-  proceed: z.number().int().min(0),
-  redesign: z.number().int().min(0),
-  "investigate-more": z.number().int().min(0),
-})
-
-const ChairmanOutputSchema = z.object({
-  satisfied: z.boolean(),
-  verdict: z.string().min(1),
-  blockers: z.array(BlockerSchema),
-  warnings: z.array(WarningSchema),
-  evidence_cited: z.array(z.string()),
-  advisor_split: AdvisorSplitSchema,
-  recommendation: z.enum(["proceed", "redesign", "investigate-more"]),
-})
-
-function formatAdvisors(responses: AdvisorResponse[]): string {
-  return responses
-    .map(r => `## ${r.persona}\n${r.response}`)
-    .join("\n\n---\n\n")
-}
-
-function formatReviewers(responses: ReviewerResponse[]): string {
-  return responses
-    .map(r => `## ${r.reviewerId}\n${r.review}`)
-    .join("\n\n---\n\n")
-}
-
-function formatEvidence(evidence: OracleResult[]): string {
-  if (evidence.length === 0) return "No Oracle evidence."
-  return evidence
-    .map(
-      e =>
-        `[${e.id}] (${e.status}, confidence: ${e.confidence.toFixed(2)}) ${entryText(e)}`,
-    )
-    .join("\n")
-}
-
-/**
- * Validate that every ID in evidence_cited actually appeared in the evidence pack.
- * Hallucinated IDs are cited but were never in the evidence sent to Council.
- */
-function validateCitations(
-  citedIds: string[],
-  evidence: OracleResult[],
-): CitationValidation {
-  const evidenceIds = new Set(evidence.map(e => e.id))
-  const valid_ids: string[] = []
-  const hallucinated_ids: string[] = []
-
-  for (const id of citedIds) {
-    if (evidenceIds.has(id)) {
-      valid_ids.push(id)
-    } else {
-      hallucinated_ids.push(id)
-    }
-  }
-
-  return { valid_ids, hallucinated_ids }
-}
-
-const CHAIRMAN_SYSTEM_PROMPT = [
-  "You are the Council Chairman. You synthesise the final verdict from all advisor and reviewer inputs.",
-  "",
-  "Your output must classify findings by severity:",
-  "  blockers — issues that MUST be resolved before the design can proceed",
-  "    (e.g. no rollback plan for a destructive migration, repeated a documented failure mode)",
-  "  warnings — issues that SHOULD be addressed but do not block execution",
-  "    (e.g. no test coverage for an edge case, a preferred pattern not followed)",
-  "",
-  "For each blocker, cite the Oracle entry IDs that evidence it and state the required fix precisely.",
-  "For each warning, a suggested_fix is optional but preferred.",
-  "",
-  "advisor_split: count how many advisors recommended each option from their responses.",
-  "  High split (no clear majority) is a signal of genuine uncertainty — reflect this in your verdict.",
-  "",
-  "satisfied = true  → no blockers, design can proceed to the human gate",
-  "satisfied = false → at least one blocker exists, or the design needs rework",
-  "",
-  "evidence_cited: list every Oracle entry ID that materially influenced the verdict.",
-  "  Only cite IDs that appeared in the Oracle Evidence section below.",
-  "  Do not cite IDs from memory or general knowledge.",
-  "",
-  "Return ONLY valid JSON — no markdown fences, no explanation:",
-  JSON.stringify({
-    satisfied: "<boolean>",
-    verdict: "<string ≤400 words — clear synthesis citing entry IDs>",
-    blockers: [{ issue: "<string>", evidence: ["<Oracle entry ID>"], required_fix: "<string>" }],
-    warnings: [{ issue: "<string>", suggested_fix: "<string — optional>" }],
-    evidence_cited: ["<Oracle entry ID — only IDs present in the evidence pack>"],
-    advisor_split: { proceed: "<int>", redesign: "<int>", "investigate-more": "<int>" },
-    recommendation: "proceed | redesign | investigate-more",
-  }),
-].join("\n")
-
-/**
- * Chairman synthesises the verdict from all advisor and reviewer inputs.
- * Classifies findings into blockers and warnings, validates citations,
- * and tracks advisor split to surface genuine disagreement.
- *
- * Throws if the LLM returns non-JSON or output fails schema validation.
- */
-export async function chairman(
-  advisorResponses: AdvisorResponse[],
-  reviewerResponses: ReviewerResponse[],
-  evidence: OracleResult[],
-  llm: LLMProvider,
-  model?: string,
-): Promise<CouncilOutput> {
-  const userPrompt = [
-    "## Advisor Responses",
-    formatAdvisors(advisorResponses),
-    "",
-    "## Reviewer Critiques",
-    formatReviewers(reviewerResponses),
-    "",
-    "## Oracle Evidence",
-    formatEvidence(evidence),
-  ].join("\n")
-
-  const raw = await llm(
-    [
-      { role: "system", content: CHAIRMAN_SYSTEM_PROMPT },
-      { role: "user", content: userPrompt },
-    ],
-    model,
-  )
-
-  let parsed: unknown
-  try {
-    const cleaned = raw
-      .replace(/^```(?:json)?\s*/m, "")
-      .replace(/\s*```$/m, "")
-      .trim()
-    parsed = JSON.parse(cleaned)
-  } catch {
-    throw new Error(
-      `Council chairman: LLM returned non-JSON. Raw (first 300 chars): ${raw.slice(0, 300)}`,
-    )
-  }
-
-  const result = ChairmanOutputSchema.safeParse(parsed)
-  if (!result.success) {
-    throw new Error(
-      `Council chairman: output failed schema validation. Issues: ${JSON.stringify(result.error.issues)}`,
-    )
-  }
-
-  const data = result.data
-
-  // Validate citations — flag any IDs cited that weren't in the evidence pack
-  const citation_validation = validateCitations(data.evidence_cited, evidence)
-
-  // Derive flat challenges array for backwards compatibility
-  const challenges = [
-    ...data.blockers.map(b => `[BLOCKER] ${b.issue}`),
-    ...data.warnings.map(w => w.issue),
-  ]
-
-  return {
-    ...data,
-    challenges,
-    citation_validation,
-  }
-}