supipowers 1.5.3 → 2.0.0

package/src/context-mode/web/fetcher.ts

@@ -1,3 +1,4 @@
+import type { KnowledgeOwner } from "../../types.js";
 import { type Chunk, chunkMarkdown } from "../knowledge/chunker.js";
 import type { KnowledgeStore } from "../knowledge/store.js";
 import { htmlToMarkdown } from "./html-to-md.js";
@@ -7,6 +8,8 @@ export interface FetchOptions {
   source?: string;
   /** Bypass 24h TTL cache. */
   force?: boolean;
+  /** Ownership scope for indexed/cached content. Defaults to project-owned when omitted. */
+  owner?: KnowledgeOwner;
 }
 
 export interface FetchResult {
@@ -28,15 +31,22 @@ export async function fetchAndIndex(
   options?: FetchOptions,
 ): Promise<FetchResult> {
   const source = options?.source ?? new URL(url).hostname;
+  const owner = options?.owner;
+  const resolvedOwner = resolveOwner(owner);
 
-  // Check cache unless forced
+  // Check cache unless forced. Explicit owners must be isolated exactly; the
+  // default project-owned path also accepts migrated legacy rows so upgraded
+  // stores do not refetch and duplicate visible search results.
   if (!options?.force) {
-    const cached = store.db
-      .prepare("SELECT fetched_at FROM url_cache WHERE url = ? AND source = ?")
-      .get(url, source) as { fetched_at: number } | null;
+    const cacheOwners = owner ? [resolvedOwner] : [resolvedOwner, { ownerScope: "legacy" as const, ownerId: "" }];
+    for (const cacheOwner of cacheOwners) {
+      const cached = store.db
+        .prepare("SELECT fetched_at FROM url_cache WHERE url = ? AND source = ? AND owner_scope = ? AND owner_id = ?")
+        .get(url, source, cacheOwner.ownerScope, cacheOwner.ownerId) as { fetched_at: number } | null;
 
-    if (cached && Date.now() - cached.fetched_at < TTL_MS) {
-      return buildCachedResult(store, source);
+      if (cached && Date.now() - cached.fetched_at < TTL_MS) {
+        return buildCachedResult(store, source, cacheOwner);
+      }
     }
   }
 
@@ -51,11 +61,11 @@ export async function fetchAndIndex(
   const markdown = toMarkdown(rawText, contentType);
 
   const chunks = chunkMarkdown(markdown, source);
-  store.index(chunks, source);
+  store.index(chunks, source, owner);
 
   store.db.run(
-    "INSERT OR REPLACE INTO url_cache (url, source, fetched_at) VALUES (?, ?, ?)",
-    [url, source, Date.now()],
+    "INSERT OR REPLACE INTO url_cache (url, source, owner_scope, owner_id, fetched_at) VALUES (?, ?, ?, ?, ?)",
+    [url, source, resolvedOwner.ownerScope, resolvedOwner.ownerId, Date.now()],
   );
 
   return {
@@ -102,11 +112,20 @@ function buildPreview(chunks: Chunk[]): string {
   return out;
 }
 
+function resolveOwner(owner: KnowledgeOwner | undefined): Required<KnowledgeOwner> {
+  return {
+    ownerScope: owner?.ownerScope ?? "project",
+    ownerId: owner?.ownerId ?? "",
+  };
+}
+
 /** Reconstruct a cached result by querying stored chunks. */
-function buildCachedResult(store: KnowledgeStore, source: string): FetchResult {
+function buildCachedResult(store: KnowledgeStore, source: string, owner: Required<KnowledgeOwner>): FetchResult {
   const rows = store.db
-    .prepare("SELECT title, body, content_type AS contentType FROM content_chunks WHERE source = ? ORDER BY id")
-    .all(source) as Chunk[];
+    .prepare(
+      "SELECT title, body, content_type AS contentType FROM content_chunks WHERE source = ? AND owner_scope = ? AND owner_id = ? ORDER BY id",
+    )
+    .all(source, owner.ownerScope, owner.ownerId) as Chunk[];
 
   return {
     preview: buildPreview(rows),

package/src/debug/logger.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { PlatformPaths } from "../platform/types.js";
+import { getProjectStatePath } from "../workspace/state-paths.js";
 
 export type DebugSessionContext = {
   cwd?: string;
@@ -74,7 +75,7 @@ export function createDebugLogger(
     };
   }
 
-  const filePath = paths.project(cwd, "debug", `tool-${sanitizedTool}__session-${sessionId}.jsonl`);
+  const filePath = getProjectStatePath(paths, cwd, "debug", `tool-${sanitizedTool}__session-${sessionId}.jsonl`);
 
   const logger: DebugLogger = {
     enabled: true,

package/src/deps/registry.ts

@@ -148,7 +148,7 @@ export const DEPENDENCIES: Dependency[] = [
     binary: "playwright",
     required: false,
     category: "testing",
-    description: "Test runner for E2E tests (run-e2e-tests.sh)",
+    description: "Test runner used by the portable QA Bun entrypoints",
     checkFn: (exec) => checkBinary(exec, "playwright"),
     installCmd: null, // Compound command (&&) — not compatible with installDep's naive split
     url: "https://playwright.dev",

package/src/discipline/failure-summarizer.ts

@@ -0,0 +1,170 @@
+// src/discipline/failure-summarizer.ts
+//
+// Offline analyzer that walks stored reliability records and persisted
+// session artifacts, classifies each failure via the failure taxonomy,
+// and produces a compact deterministic report.
+//
+// The summarizer is pure: given the same input records it produces the
+// same report. Every data source is optional — callers pass what they
+// have, the summarizer copes with partial inputs.
+//
+// Phase 8 exit gate: recurring failures are aggregated so the next
+// hardening target is evidence-driven, not anecdotal.
+
+import type { PlatformPaths } from "../platform/types.js";
+import type { ReliabilityRecord } from "../types.js";
+import { readReliabilityRecords } from "../storage/reliability-metrics.js";
+import {
+  FAILURE_CLASSES,
+  classifyFailure,
+  describeFailureClass,
+  type FailureClass,
+} from "./failure-taxonomy.js";
+
+export interface FailureOccurrence {
+  /** Timestamp of the underlying event. */
+  ts: string;
+  /** Command that produced the failure. */
+  command: string;
+  /** Specific operation (e.g. "commit-plan"), when known. */
+  operation?: string;
+  /** All classes that fired for this occurrence. */
+  classes: FailureClass[];
+  /** Truthful reason from the record. */
+  reason?: string;
+}
+
+export interface FailureClassAggregate {
+  class: FailureClass;
+  description: string;
+  /** Total occurrences of this class in the input. */
+  count: number;
+  /** Count per command, sorted alphabetically. */
+  byCommand: Array<{ command: string; count: number }>;
+  /** Up to `exampleCount` representative records for review. */
+  examples: FailureOccurrence[];
+}
+
+export interface FailureSummary {
+  /** Total non-ok records considered. */
+  totalFailures: number;
+  /** Failure classes that fired at least once, sorted by taxonomy order. */
+  aggregates: FailureClassAggregate[];
+  /** Non-ok records that did NOT match any taxonomy class. */
+  unclassified: FailureOccurrence[];
+}
+
+export interface SummarizeOptions {
+  /** Number of example occurrences per class. Default 3. */
+  exampleCount?: number;
+}
+
+function isFailureRecord(record: ReliabilityRecord): boolean {
+  return record.outcome !== "ok";
+}
+
+function classifyRecord(record: ReliabilityRecord): FailureOccurrence {
+  const classes = classifyFailure({
+    outcome: record.outcome,
+    reason: record.reason,
+    // attempts used by unproductive-retry rule
+    attempts: record.attempts,
+  } as any);
+  return {
+    ts: record.ts,
+    command: record.command,
+    operation: record.operation,
+    classes,
+    reason: record.reason,
+  };
+}
+
+function aggregate(
+  occurrences: FailureOccurrence[],
+  exampleCount: number,
+): FailureClassAggregate[] {
+  const map = new Map<FailureClass, FailureOccurrence[]>();
+  for (const occ of occurrences) {
+    for (const cls of occ.classes) {
+      const list = map.get(cls) ?? [];
+      list.push(occ);
+      map.set(cls, list);
+    }
+  }
+
+  const aggregates: FailureClassAggregate[] = [];
+  for (const cls of FAILURE_CLASSES) {
+    const list = map.get(cls);
+    if (!list || list.length === 0) continue;
+    const byCommandMap = new Map<string, number>();
+    for (const occ of list) {
+      byCommandMap.set(occ.command, (byCommandMap.get(occ.command) ?? 0) + 1);
+    }
+    const byCommand = [...byCommandMap.entries()]
+      .map(([command, count]) => ({ command, count }))
+      .sort((a, b) => a.command.localeCompare(b.command));
+
+    aggregates.push({
+      class: cls,
+      description: describeFailureClass(cls),
+      count: list.length,
+      byCommand,
+      examples: list.slice(0, Math.max(0, exampleCount)),
+    });
+  }
+
+  return aggregates;
+}
+
+/**
+ * Summarize an arbitrary list of reliability records. Pure — no filesystem.
+ * Callers can combine records from multiple sources before summarizing.
+ */
+export function summarizeFailures(
+  records: ReliabilityRecord[],
+  options: SummarizeOptions = {},
+): FailureSummary {
+  const exampleCount = options.exampleCount ?? 3;
+  const failures = records.filter(isFailureRecord).map(classifyRecord);
+
+  const classified = failures.filter((f) => f.classes.length > 0);
+  const unclassified = failures.filter((f) => f.classes.length === 0);
+
+  return {
+    totalFailures: failures.length,
+    aggregates: aggregate(classified, exampleCount),
+    unclassified,
+  };
+}
+
+/**
+ * Convenience: load records from the per-cwd reliability store and
+ * summarize. Empty store produces an empty summary (no crashes).
+ */
+export function summarizeLocalFailures(
+  paths: PlatformPaths,
+  cwd: string,
+  options: SummarizeOptions = {},
+): FailureSummary {
+  return summarizeFailures(readReliabilityRecords(paths, cwd), options);
+}
+
+/**
+ * Format a summary as readable lines. `[]` when there are no failures so
+ * callers can branch on length without a special case.
+ */
+export function formatFailureSummary(summary: FailureSummary): string[] {
+  if (summary.totalFailures === 0) return [];
+
+  const lines: string[] = [`Failure summary: ${summary.totalFailures} non-ok record(s)`];
+  for (const agg of summary.aggregates) {
+    lines.push(`  [${agg.class}] ${agg.description} \u2014 ${agg.count} occurrence(s)`);
+    for (const per of agg.byCommand) {
+      lines.push(`    \u00b7 ${per.command}: ${per.count}`);
+    }
+  }
+  if (summary.unclassified.length > 0) {
+    lines.push(`  [unclassified] ${summary.unclassified.length} record(s) did not match any taxonomy class`);
+  }
+  return lines;
+}

package/src/discipline/failure-taxonomy.ts

@@ -0,0 +1,131 @@
+/**
+ * Workflow failure taxonomy.
+ *
+ * Small, explicit set of failure classes used by summarizer and eval-promotion
+ * to turn raw reliability records + session notes into actionable categories.
+ *
+ * Classification is pure: regex / string checks only, no dynamic evaluation,
+ * deterministic for the same input, never throws.
+ */
+
+export const FAILURE_CLASSES = [
+	"premature-completion",
+	"wrong-tool-path",
+	"missing-artifact",
+	"verification-skipped",
+	"discovery-miss",
+	"unproductive-retry",
+] as const;
+
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+
+export interface FailureSignals {
+	/** Stored reliability record, optional. */
+	outcome?: "ok" | "blocked" | "retry-exhausted" | "fallback" | "agent-error";
+	/** Reason string from the reliability record or log, optional. */
+	reason?: string;
+	/** Tool call name if the failure involves a blocked/rerouted tool. */
+	toolName?: string;
+	/** Path of an artifact that was expected but not found. */
+	missingArtifactPath?: string;
+	/** Free-text description from debug traces or session notes. */
+	note?: string;
+	/** Attempt count from the reliability record, optional. */
+	attempts?: number;
+}
+
+// Tool names blocked by `routeToolCall` when context-mode is active.
+// Keep in lock-step with `src/context-mode/routing.ts` — every native tool
+// that the router redirects must classify as `wrong-tool-path` here.
+const BLOCKED_TOOLS = new Set<string>([
+	"search",
+	"find",
+	"bash-grep",
+	"bash-find",
+	"curl",
+	"wget",
+	"fetch",
+	"web_fetch",
+	"WebFetch",
+]);
+
+const DESCRIPTIONS: Record<FailureClass, string> = {
+	"premature-completion":
+		"Workflow claimed done before required artifact existed.",
+	"wrong-tool-path":
+		"Workflow reached for a blocked tool instead of the preferred ctx_* tool.",
+	"missing-artifact":
+		"Required output (plan file, session, findings.md) was never written.",
+	"verification-skipped":
+		"Agent skipped a mandatory verification step (test, typecheck, eval).",
+	"discovery-miss":
+		"Workflow wandered before finding the right entry point.",
+	"unproductive-retry":
+		"Retry loop spent attempts without making progress.",
+};
+
+/**
+ * Classify a failure based on signals. Returns one or more matching classes in
+ * priority order (matching `FAILURE_CLASSES` order); empty array when no class
+ * fires. Deterministic — never throws.
+ */
+export function classifyFailure(signals: FailureSignals): FailureClass[] {
+	const reason = signals.reason ?? "";
+	const note = signals.note ?? "";
+	const matches: FailureClass[] = [];
+
+	// premature-completion
+	if (
+		(signals.outcome === "ok" &&
+			/incomplete|partial|unresolved/i.test(reason)) ||
+		(signals.outcome === "fallback" &&
+			/never produced valid artifact/i.test(reason))
+	) {
+		matches.push("premature-completion");
+	}
+
+	// wrong-tool-path
+	if (
+		(signals.toolName && BLOCKED_TOOLS.has(signals.toolName)) ||
+		/ctx_/.test(reason)
+	) {
+		matches.push("wrong-tool-path");
+	}
+
+	// missing-artifact
+	if (
+		signals.missingArtifactPath !== undefined ||
+		(/missing/i.test(reason) && /plan|findings|session/i.test(reason))
+	) {
+		matches.push("missing-artifact");
+	}
+
+	// verification-skipped
+	if (
+		/without running (validator|tests|typecheck)/i.test(reason) ||
+		/skipped (verification|validation|test)/i.test(reason)
+	) {
+		matches.push("verification-skipped");
+	}
+
+	// discovery-miss
+	if (
+		/wandered/i.test(reason) ||
+		/wrong file/i.test(reason) ||
+		/searched broadly/i.test(note)
+	) {
+		matches.push("discovery-miss");
+	}
+
+	// unproductive-retry
+	if (signals.outcome === "retry-exhausted" && (signals.attempts ?? 0) >= 3) {
+		matches.push("unproductive-retry");
+	}
+
+	return matches;
+}
+
+/** Canonical human-friendly description per class. */
+export function describeFailureClass(cls: FailureClass): string {
+	return DESCRIPTIONS[cls];
+}

package/src/discipline/workflow-invariants.ts

@@ -0,0 +1,125 @@
+// src/discipline/workflow-invariants.ts
+//
+// Runtime invariants that AI-heavy workflows must satisfy before reporting
+// completion. When an invariant fails, the workflow yields a truthful
+// blocker instead of silently claiming success. Used by plan/review/qa/fix-pr
+// completion paths and by Phase 0 evals that test workflow boundaries.
+//
+// Design notes:
+//   - Invariants are pure functions over a workflow-specific context object.
+//   - Invariants return either `{ state: "satisfied" }` or a blocker with a
+//     human-readable `reason`. Keep reasons short and actionable.
+//   - `checkInvariants` returns the FIRST blocker, not a list. Workflows
+//     surface one blocker at a time so the user (or the model) can fix it
+//     and proceed, rather than being handed a noisy report.
+//   - This module owns only the generic abstraction. Workflow-specific
+//     invariant builders live next to their workflow (e.g. plan's PlanSpec
+//     validation in src/planning/approval-flow.ts).
+
+export type InvariantState =
+  | { state: "satisfied" }
+  | { state: "blocked"; reason: string };
+
+export interface WorkflowInvariant<TContext> {
+  /** Stable identifier. Used for logging and test assertions. */
+  name: string;
+  /**
+   * Evaluate this invariant against the workflow context. Return a blocker
+   * with a truthful reason if the invariant fails.
+   */
+  check: (ctx: TContext) => InvariantState | Promise<InvariantState>;
+}
+
+export type InvariantCheckResult =
+  | { state: "satisfied" }
+  | { state: "blocked"; invariant: string; reason: string };
+
+/**
+ * Run invariants in order against `ctx`. Stop at the first blocker and
+ * return it. Returns `{ state: "satisfied" }` only when every invariant
+ * reports satisfied.
+ */
+export async function checkInvariants<TContext>(
+  invariants: readonly WorkflowInvariant<TContext>[],
+  ctx: TContext,
+): Promise<InvariantCheckResult> {
+  for (const invariant of invariants) {
+    const result = await invariant.check(ctx);
+    if (result.state === "blocked") {
+      return { state: "blocked", invariant: invariant.name, reason: result.reason };
+    }
+  }
+  return { state: "satisfied" };
+}
+
+// ---------------------------------------------------------------------------
+// Invariant builders — the common shapes workflows compose from
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an invariant that is satisfied only when the predicate returns true.
+ */
+export function requireCondition<TContext>(
+  name: string,
+  predicate: (ctx: TContext) => boolean | Promise<boolean>,
+  reason: string,
+): WorkflowInvariant<TContext> {
+  return {
+    name,
+    async check(ctx) {
+      const satisfied = await predicate(ctx);
+      return satisfied ? { state: "satisfied" } : { state: "blocked", reason };
+    },
+  };
+}
+
+/**
+ * Build an invariant that is satisfied only when the artifact exists. The
+ * caller supplies both the existence check and the artifact identifier used
+ * in the blocker reason.
+ */
+export function requireArtifact<TContext>(
+  name: string,
+  exists: (ctx: TContext) => boolean | Promise<boolean>,
+  artifactLabel: string,
+): WorkflowInvariant<TContext> {
+  return requireCondition(
+    name,
+    exists,
+    `Required artifact is missing: ${artifactLabel}.`,
+  );
+}
+
+/**
+ * Build an invariant that blocks when the workflow still has pending work.
+ * Typical uses: outstanding todos, unresolved review comments, undispatched
+ * follow-up steps.
+ */
+export function requireNoPendingWork<TContext>(
+  name: string,
+  pending: (ctx: TContext) => number | Promise<number>,
+  workLabel: string,
+): WorkflowInvariant<TContext> {
+  return {
+    name,
+    async check(ctx) {
+      const count = await pending(ctx);
+      return count === 0
+        ? { state: "satisfied" }
+        : {
+            state: "blocked",
+            reason: `${count} ${workLabel} still pending \u2014 workflow cannot complete.`,
+          };
+    },
+  };
+}
+
+/**
+ * Render a blocker result as a single line for notifications, logs, or
+ * prompts. `satisfied` states render as an empty string so callers can join
+ * multiple results without branching.
+ */
+export function formatInvariantResult(result: InvariantCheckResult): string {
+  if (result.state === "satisfied") return "";
+  return `[${result.invariant}] ${result.reason}`;
+}

package/src/discovery/index.ts

@@ -0,0 +1,31 @@
+// src/discovery/index.ts
+//
+// Deterministic repo-entry-point discovery. Given a workflow query (e.g.
+// "fix the login bug", "review the latest commit") and context signals
+// (changed files, workspace targets), rank likely-relevant files with a
+// short rationale for each candidate.
+//
+// Used by /supi:review, /supi:plan, /supi:qa, and /supi:fix-pr to start
+// from strong candidates rather than broad wandering.
+//
+// Non-goals:
+//   - Hosted search / vector database
+//   - Replacing native tools (grep/lsp). This layer *orchestrates* them.
+//
+// Phase 6 exit gate: fixture workspaces rank expected files first, every
+// candidate carries rationale, behavior stays stable when inputs are empty.
+
+export type {
+  DiscoveryCandidate,
+  DiscoveryInput,
+  DiscoveryResult,
+  DiscoverySource,
+} from "./rank.js";
+
+export { rankDiscoveryCandidates } from "./rank.js";
+export { discoverFromSources } from "./sources.js";
+
+export { rankWithLspAugmentation } from "./lsp.js";
+export type { LspSymbolLocation, LspAugmentedResult } from "./lsp.js";
+export { suggestCandidatesForWorkflow } from "./workflow.js";
+export type { WorkflowDiscoveryInput, WorkflowDiscoveryResult } from "./workflow.js";

package/src/discovery/lsp.ts

@@ -0,0 +1,87 @@
+// src/discovery/lsp.ts
+//
+// LSP-assisted discovery: convert symbol search results into external
+// signals the ranker consumes. When LSP is unavailable or the symbol
+// lookup returns nothing, falls through cleanly — callers should never
+// require LSP for discovery to work.
+//
+// This module deliberately does not talk to LSP directly. Callers pass in
+// a `querySymbols` callback so the same function can be driven by:
+//   - the live platform LSP bridge in production
+//   - a deterministic fixture in tests
+
+import type { DiscoveryCandidate } from "./rank.js";
+import { rankDiscoveryCandidates, type DiscoveryInput } from "./rank.js";
+
+export interface LspSymbolLocation {
+  /** Repo-relative path where the symbol is defined or referenced. */
+  path: string;
+  /** Short reason string attached to the candidate. */
+  reason: string;
+  /** Extra score beyond the baseline LSP boost. Optional. */
+  bonus?: number;
+}
+
+export interface LspDiscoveryInput extends DiscoveryInput {
+  /**
+   * Called with the workflow `query`. Must return a (possibly empty) list
+   * of symbol locations. Any thrown error is caught and treated as
+   * "LSP unavailable" — discovery still returns a ranked list from the
+   * remaining sources.
+   */
+  querySymbols: (query: string) => LspSymbolLocation[] | Promise<LspSymbolLocation[]>;
+}
+
+export interface LspAugmentedResult {
+  candidates: DiscoveryCandidate[];
+  lspAvailable: boolean;
+  lspHitCount: number;
+}
+
+const WEIGHT_LSP = 6;
+
+/**
+ * Run LSP symbol discovery against the query, fold the hits into external
+ * signals, and rank the combined candidate pool. When `querySymbols` throws
+ * or returns [], the result is still valid — discovery degrades, not fails.
+ */
+export async function rankWithLspAugmentation(
+  input: LspDiscoveryInput,
+): Promise<LspAugmentedResult> {
+  let lspAvailable = true;
+  let lspHits: LspSymbolLocation[] = [];
+
+  if (input.query && input.query.trim().length > 0) {
+    try {
+      lspHits = await input.querySymbols(input.query);
+    } catch {
+      lspAvailable = false;
+      lspHits = [];
+    }
+  }
+
+  const externalSignals: Record<string, { score: number; rationale: string }> = {
+    ...(input.externalSignals ?? {}),
+  };
+  for (const hit of lspHits) {
+    const prior = externalSignals[hit.path];
+    const score = WEIGHT_LSP + (hit.bonus ?? 0);
+    externalSignals[hit.path] = prior
+      ? {
+          score: prior.score + score,
+          rationale: `${prior.rationale}; ${hit.reason}`,
+        }
+      : { score, rationale: hit.reason };
+  }
+
+  const ranked = rankDiscoveryCandidates({
+    ...input,
+    externalSignals,
+  });
+
+  return {
+    candidates: ranked.candidates,
+    lspAvailable,
+    lspHitCount: lspHits.length,
+  };
+}