supipowers 1.5.2 → 2.0.0

package/src/harness/default-agents/design.md

@@ -0,0 +1,23 @@
+---
+name: harness-design
+description: Compose the harness design spec from discover + research artifacts
+supportedSlots: [design]
+focus: design
+---
+
+You are the **design** agent for the supipowers harness pipeline.
+
+Read `<session>/discover.json` and every file under `<session>/research/`. Compose a complete `HarnessDesignSpec` object covering:
+
+1. Layered architecture rules (one per layer; allowed/forbidden imports must be explicit).
+2. Taste invariants (3–7 short bullets).
+3. Tooling choices (lint, structural test, eval framework — one each, picked from the research recommendations).
+4. Top 10 mechanical golden principles (no philosophy; rules a `grep` could enforce).
+5. Documentation tree shape.
+6. Validation gates the harness should install.
+7. Supipowers wiring opt-in (review agent + checks gate).
+8. **Anti-slop section**: backend (fallow / desloppify / hybrid / supi-native), hook toggles, score floor, agent-skill distribution targets.
+
+Persist the spec by calling `harness_design_spec_persist` with the rendered markdown, then record each gray-area decision via `harness_decision_record`.
+
+You **MUST NOT** advance to plan or implementation. Your only output is the design spec + decisions.

package/src/harness/default-agents/discover.md

@@ -0,0 +1,18 @@
+---
+name: harness-discover
+description: Repository reconnaissance for the harness pipeline; fills gaps the deterministic scanner can't reach
+supportedSlots: [discover]
+focus: codebase-discovery
+---
+
+You are the **discover** agent for the supipowers harness pipeline.
+
+Your job is to **augment**, not replace, the deterministic discover artifact already produced by `buildDiscoverArtifact`. Read `<session>/discover.json` and fill in fields the static scanner could not infer:
+
+- `frameworks`: project-specific frameworks not detectable from `package.json` alone (e.g. SvelteKit vs. Svelte, Next App Router vs. Pages router).
+- `commitConventions`: when no commitlint is configured, infer the convention from `git log --oneline -50`.
+- `notes`: short observations that influence Design (e.g. "monorepo uses TypeScript project references", "tests run via `vitest --coverage`").
+
+You **MUST** call `harness_discover_record` exactly once with the augmented artifact. Do **NOT** chat with the user. Do **NOT** generate scenarios or plans.
+
+You **MUST NOT** invent data. If a field is unknown, leave it as-is.

package/src/harness/default-agents/implement.md

@@ -0,0 +1,24 @@
+---
+name: harness-implement
+description: Execute approved plan tasks for the harness pipeline
+supportedSlots: [implement]
+focus: implementation
+---
+
+You are the **implement** agent for the supipowers harness pipeline.
+
+Drive the approved plan tasks one at a time. For each task:
+
+1. Read the affected files (the `Files` list in the task header).
+2. Apply the change.
+3. Run targeted verification (typecheck, the test that covers the change, lint on the touched files).
+4. Record progress via `todo_write` so the user can see the cursor.
+
+You **MUST** call `harness_validate_finding` whenever a verification step surfaces a deferred issue you cannot resolve in this turn — that lands in the implement log and the queue for GC.
+
+After every task that wrote files, the post-session sweep hook fires and may add dead-code findings to the queue. Treat those as follow-up work; do not ignore them.
+
+You **MUST NOT**:
+- Skip tasks.
+- Mark a task done before its `criteria` is observably satisfied.
+- Delete user-authored content outside the plan's `Files` list without explicit confirmation.

package/src/harness/default-agents/plan.md

@@ -0,0 +1,19 @@
+---
+name: harness-plan
+description: Render the harness plan from a design spec
+supportedSlots: [plan]
+focus: plan
+---
+
+You are the **plan** agent for the supipowers harness pipeline.
+
+The structured plan is computed deterministically from the design spec via `buildHarnessPlanTasks`. Your role is **review and refinement only**:
+
+- Read the rendered plan markdown and the design spec.
+- For each task, validate that `criteria` and `complexity` match what the design demands.
+- Add missing edge-case tasks the deterministic builder would not catch (e.g. "migrate existing CI workflow to call `bunx supipowers harness validate`").
+- Cap individual task labels at 200 chars.
+
+You **MUST** persist the plan via the standard `/supi:plan` approval flow — `emitHarnessPlanFromSpec` already wrote the plan to the canonical plans directory before you started. Your job is to ensure the markdown is review-ready.
+
+You **MUST NOT** execute the plan. Implementation runs in a separate session after user approval.

package/src/harness/default-agents/research.md

@@ -0,0 +1,21 @@
+---
+name: harness-research
+description: Per-topic research writeup with primary sources for the harness pipeline
+supportedSlots: [research]
+focus: research
+---
+
+You are the **research** agent for the supipowers harness pipeline.
+
+Your job is to write a single research topic markdown for the harness session. The topic slug + title are passed in the assignment prompt; do not invent your own.
+
+You **MUST**:
+- Use the `web_search` tool to find at least **two distinct primary sources** (papers, official docs, RFCs). Engine-ranking-only — do **NOT** filter by year.
+- Structure the output with these headings, in order: `## Background`, `## Options`, `## Recommendation`, `## Sources`, `## Last verified`.
+- Set the frontmatter `lastVerified` field to today's ISO date.
+- Call `harness_research_record` exactly once with `{sessionId, topicSlug, markdown}`.
+
+You **MUST NOT**:
+- Cite blog posts or tutorials as primary sources.
+- Skip the `## Options` heading or the recommendation.
+- Submit fewer than 2 source URLs.

package/src/harness/default-agents/validate.md

@@ -0,0 +1,22 @@
+---
+name: harness-validate
+description: Run validate sub-checks and surface findings via harness_validate_finding
+supportedSlots: [validate]
+focus: validation
+---
+
+You are the **validate** agent for the supipowers harness pipeline.
+
+The deterministic validate pass (`runValidate`) has already produced `<session>/validate-report.json`. Your role is to **surface unactionable warnings to the user** — the deterministic pass classifies items but cannot triage them.
+
+For each finding in the report:
+
+1. Read the underlying file at the cited line.
+2. Confirm the finding is real (not a false positive from a stale scan).
+3. Record a follow-up via `harness_validate_finding` with `severity` and `remediation`.
+4. If the finding maps to a slop-queue entry, link it via the `details.queueId` field.
+
+You **MUST NOT**:
+- Re-run scans (the deterministic pass already did, and it cached the score).
+- Approve the validate report — the user owns the accept gate.
+- Apply auto-fixes (those run from `/supi:harness gc`, not from validate).

package/src/harness/gc/reporter.ts

@@ -0,0 +1,28 @@
+/**
+ * Render a human-readable summary of a GC report.
+ */
+
+import type { GcReport } from "./runner.js";
+
+export function renderGcReport(report: GcReport): string {
+  const lines: string[] = [];
+  lines.push("Harness GC report");
+  lines.push("─────────────────");
+  lines.push(`Inspected:           ${report.inspected}`);
+  lines.push(`Mechanical attempted: ${report.mechanicalAttempted}`);
+  lines.push(`Mechanical resolved:  ${report.mechanicalResolved}`);
+  lines.push(`Judgmental reported:  ${report.judgmentalReported}`);
+  if (report.failures.length > 0) {
+    lines.push("");
+    lines.push(`Failures (${report.failures.length}):`);
+    for (const failure of report.failures.slice(0, 10)) {
+      lines.push(`  - ${failure.id}: ${failure.reason}`);
+    }
+    if (report.failures.length > 10) {
+      lines.push(`  …and ${report.failures.length - 10} more.`);
+    }
+  }
+  lines.push("");
+  lines.push(`Elapsed: ${report.durationMs} ms`);
+  return lines.join("\n");
+}

package/src/harness/gc/runner.ts

@@ -0,0 +1,136 @@
+/**
+ * GC subcommand driver.
+ *
+ * Drains the persistent slop queue and re-runs Validate. For each unresolved entry, the
+ * GC classifies as **mechanical** (auto-fixable) or **judgmental** (reported only).
+ * Mechanical fixes apply via the configured backend's `fix(apply: true)` and on success
+ * the entry transitions to `resolved`.
+ *
+ * Concurrency is configurable (default 4). The runner is best-effort: a single failed
+ * fixer never aborts the rest.
+ */
+
+import type { Platform, PlatformPaths } from "../../platform/types.js";
+import type {
+  HarnessAntiSlopBackend,
+  HarnessSlopQueueEntry,
+} from "../../types.js";
+import type { SlopBackend } from "../anti_slop/backend.js";
+import {
+  backlog as readBacklog,
+  resolve as resolveQueueEntry,
+} from "../anti_slop/queue.js";
+
+const DEFAULT_CONCURRENCY = 4;
+
+const MECHANICAL_KINDS: ReadonlySet<HarnessSlopQueueEntry["kind"]> = new Set([
+  "dead-code",
+  "naming",
+  "file-too-large",
+]);
+
+export interface GcInput {
+  platform: Platform;
+  paths: PlatformPaths;
+  cwd: string;
+  backend: HarnessAntiSlopBackend;
+  /** Backend adapter, when the backend supports automated fixes. */
+  adapter: SlopBackend | null;
+  /** Concurrency for fix dispatch. Defaults to 4. */
+  concurrency?: number;
+  /** When true, fixes are applied; when false, GC dry-runs (reports only). */
+  apply: boolean;
+}
+
+export interface GcReport {
+  inspected: number;
+  mechanicalAttempted: number;
+  mechanicalResolved: number;
+  judgmentalReported: number;
+  failures: { id: string; reason: string }[];
+  durationMs: number;
+}
+
+/**
+ * Classify whether an entry is mechanical (eligible for auto-fix) or judgmental.
+ */
+export function isMechanical(entry: HarnessSlopQueueEntry): boolean {
+  return MECHANICAL_KINDS.has(entry.kind);
+}
+
+/**
+ * Run the GC drain. Pure dispatcher for tests; the real subcommand wraps this with
+ * progress UI and report rendering.
+ */
+export async function runHarnessGc(input: GcInput): Promise<GcReport> {
+  const startedAt = Date.now();
+  const result: GcReport = {
+    inspected: 0,
+    mechanicalAttempted: 0,
+    mechanicalResolved: 0,
+    judgmentalReported: 0,
+    failures: [],
+    durationMs: 0,
+  };
+
+  const backlog = readBacklog(input.paths, input.cwd, { state: "open" });
+  if (!backlog.ok) {
+    result.durationMs = Date.now() - startedAt;
+    result.failures.push({ id: "(read)", reason: backlog.error.message });
+    return result;
+  }
+
+  const entries = backlog.value;
+  result.inspected = entries.length;
+
+  const mechanical = entries.filter(isMechanical);
+  const judgmental = entries.filter((e) => !isMechanical(e));
+  result.judgmentalReported = judgmental.length;
+
+  if (mechanical.length === 0 || !input.adapter) {
+    result.durationMs = Date.now() - startedAt;
+    return result;
+  }
+
+  const concurrency = input.concurrency ?? DEFAULT_CONCURRENCY;
+  let cursor = 0;
+
+  async function worker(): Promise<void> {
+    while (cursor < mechanical.length) {
+      const idx = cursor;
+      cursor += 1;
+      if (idx >= mechanical.length) return;
+      const entry = mechanical[idx];
+      result.mechanicalAttempted += 1;
+      const fix = await (input.adapter as SlopBackend).fix(input.platform, {
+        cwd: input.cwd,
+        entryIds: [entry.id],
+        apply: input.apply,
+      });
+      if (fix.ok && fix.appliedIds.includes(entry.id)) {
+        const resolved = resolveQueueEntry(input.paths, input.cwd, entry.id);
+        if (resolved.ok && resolved.value) {
+          result.mechanicalResolved += 1;
+        } else {
+          result.failures.push({
+            id: entry.id,
+            reason: !resolved.ok ? resolved.error.message : "entry already resolved or missing",
+          });
+        }
+      } else {
+        const failure = fix.failedIds.find((f) => f.id === entry.id);
+        result.failures.push({
+          id: entry.id,
+          reason: failure?.reason ?? "fix did not include entry id",
+        });
+      }
+    }
+  }
+
+  const workers: Promise<void>[] = [];
+  for (let i = 0; i < concurrency; i += 1) workers.push(worker());
+  await Promise.all(workers);
+
+  result.durationMs = Date.now() - startedAt;
+  return result;
+}

package/src/harness/hooks/layer-context-inject.ts

@@ -0,0 +1,155 @@
+/**
+ * Layer-context-injection hook.
+ *
+ * Registered on `before_agent_start`. Reads `docs/architecture.md`, determines the layer
+ * of the file the agent is about to edit, and prepends a system-prompt addendum so the
+ * agent is reminded of the import rules.
+ *
+ * Degrades gracefully:
+ *  - missing `docs/architecture.md` → no addendum,
+ *  - no rule matches the file → no addendum,
+ *  - addendum exceeds `addendum_max_chars` → truncated with "…".
+ *
+ * The hook does NOT block tool calls; it only augments the system prompt. We never
+ * extract the "file the agent is about to edit" from the system-prompt event itself —
+ * that would require parsing user prompts. Instead, callers wire the hook with a
+ * `file-resolver` that pulls the candidate file from the active session metadata, and
+ * fall back to no-op when no candidate exists.
+ */
+
+import * as fs from "node:fs";
+
+import type { Platform } from "../../platform/types.js";
+import { prependSystemPromptBlock } from "../../platform/system-prompt.js";
+import type { HarnessHookConfig, HarnessLayerRule } from "../../types.js";
+import {
+  buildLayerAddendum,
+  parseArchitectureMarkdown,
+  resolveLayerForFile,
+} from "../anti_slop/architecture-parser.js";
+import {
+  getHarnessArchitectureDocPath,
+  getHarnessMarkerPath,
+} from "../project-paths.js";
+
+export interface LayerContextHookOptions {
+  /**
+   * Resolves a candidate file path from the event/ctx pair. Implementations consult
+   * session metadata, the user's last prompt, or recent tool calls — whatever the
+   * harness can wire through. Returning `null` short-circuits the hook.
+   */
+  resolveCandidateFile: (event: unknown, ctx: unknown) => string | null;
+  /** Hook config snapshot. Defaults to disabled when undefined. */
+  config?: HarnessHookConfig["layer_context_inject"];
+}
+
+const DEFAULT_CONFIG: HarnessHookConfig["layer_context_inject"] = {
+  enabled: false,
+  addendum_max_chars: 800,
+};
+
+interface CachedRules {
+  layerRules: HarnessLayerRule[];
+  mtimeMs: number;
+}
+
+/** Cache the parsed rules per architecture-doc path so we don't re-read on every hook. */
+const rulesCache = new Map<string, CachedRules>();
+
+function loadRules(archPath: string): HarnessLayerRule[] {
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(archPath);
+  } catch {
+    return [];
+  }
+  const cached = rulesCache.get(archPath);
+  if (cached && cached.mtimeMs === stat.mtimeMs) return cached.layerRules;
+  let md: string;
+  try {
+    md = fs.readFileSync(archPath, "utf8");
+  } catch {
+    return [];
+  }
+  const layerRules = parseArchitectureMarkdown(md);
+  rulesCache.set(archPath, { layerRules, mtimeMs: stat.mtimeMs });
+  return layerRules;
+}
+
+export interface LayerContextInjectionResult {
+  /** Addendum to prepend to the system prompt; empty string when no-op. */
+  addendum: string;
+  /** Why the hook returned what it did — used by tests. */
+  reason: string;
+}
+
+/**
+ * Compute the addendum for a single hook invocation. Pure-ish: reads the file system but
+ * never mutates state. Tests call this directly with a known cwd + candidate file.
+ */
+export function computeLayerAddendum(input: {
+  cwd: string;
+  candidateFile: string | null;
+  config: HarnessHookConfig["layer_context_inject"];
+  /** Override the resolved architecture-doc path; tests use this to point at a fixture. */
+  archPath?: string;
+}): LayerContextInjectionResult {
+  if (!input.config.enabled) return { addendum: "", reason: "disabled" };
+  if (!input.candidateFile) return { addendum: "", reason: "no candidate file" };
+  const archPath = input.archPath ?? `${input.cwd}/docs/architecture.md`;
+  const rules = loadRules(archPath);
+  if (rules.length === 0) return { addendum: "", reason: "no rules parsed" };
+  const rule = resolveLayerForFile(input.candidateFile, rules);
+  if (!rule) return { addendum: "", reason: "no rule matches candidate file" };
+  const addendum = buildLayerAddendum(input.candidateFile, rule, input.config.addendum_max_chars);
+  return { addendum, reason: "matched" };
+}
+
+/**
+ * Register the hook. Returns a teardown function the caller can invoke to revoke
+ * registration (used by tests). The hook is gated by the harness marker — when the
+ * marker is missing, the hook is a no-op (it never reads the architecture doc).
+ */
+export function registerLayerContextInjectHook(
+  platform: Platform,
+  options: LayerContextHookOptions,
+): () => void {
+  const config = options.config ?? DEFAULT_CONFIG;
+  if (!config.enabled) {
+    return () => {};
+  }
+
+  let unregistered = false;
+  const handler = (event: unknown, ctx: unknown): { systemPrompt: string[] } | undefined => {
+    if (unregistered) return undefined;
+    const cwd = (ctx as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+    if (!fs.existsSync(getHarnessMarkerPath(platform.paths, cwd))) return undefined;
+
+    const candidateFile = options.resolveCandidateFile(event, ctx);
+    const result = computeLayerAddendum({
+      cwd,
+      candidateFile,
+      config,
+      archPath: getHarnessArchitectureDocPath(platform.paths, cwd),
+    });
+    if (result.addendum.length === 0) return undefined;
+
+    return {
+      systemPrompt: prependSystemPromptBlock(
+        (event as { systemPrompt?: unknown } | undefined)?.systemPrompt,
+        result.addendum,
+      ),
+    };
+  };
+
+  platform.on("before_agent_start", handler);
+
+  return () => {
+    unregistered = true;
+  };
+}
+
+/** Reset the in-memory rule cache. Tests use this to re-read the architecture doc. */
+export function _resetLayerRuleCacheForTests(): void {
+  rulesCache.clear();
+}

package/src/harness/hooks/post-session-sweep.ts

@@ -0,0 +1,130 @@
+/**
+ * Post-session dead-code sweep.
+ *
+ * Registered on `agent_end`. After every turn that wrote files, runs the configured
+ * backend's `deadCode` scan against changed files and appends new findings to the queue.
+ *
+ * The hook never blocks the session — `block_on_new_dead_code` only controls whether we
+ * surface a warning steer message back to the user. Even when surfacing, we do not
+ * replace `agent_end` with `awaiting-user` semantics; we simply notify.
+ */
+
+import * as fs from "node:fs";
+
+import type { Platform } from "../../platform/types.js";
+import type { HarnessHookConfig, HarnessSlopQueueEntry } from "../../types.js";
+import { type SlopBackend } from "../anti_slop/backend.js";
+import { computeQueueEntryId } from "../anti_slop/queue.js";
+import { appendSlopQueueEntry } from "../storage.js";
+import { getHarnessMarkerPath } from "../project-paths.js";
+
+export interface PostSessionSweepOptions {
+  adapter: SlopBackend | null;
+  config: HarnessHookConfig["post_session_sweep"];
+  /** Optional override for the per-turn timeout (ms). Defaults to 30 s. */
+  timeoutMs?: number;
+}
+
+export interface SweepResult {
+  ran: boolean;
+  newFindings: number;
+  durationMs: number;
+  reason: string;
+}
+
+/** Run the sweep and append new findings. Pure dispatcher, used by both the live hook and tests. */
+export async function runPostSessionSweep(input: {
+  platform: Platform;
+  cwd: string;
+  adapter: SlopBackend;
+  timeoutMs: number;
+}): Promise<SweepResult> {
+  const startedAt = Date.now();
+  const result = await input.adapter.deadCode(input.platform, {
+    cwd: input.cwd,
+    changedSinceHead: true,
+    timeoutMs: input.timeoutMs,
+  });
+  if (!result.ok) {
+    return {
+      ran: false,
+      newFindings: 0,
+      durationMs: Date.now() - startedAt,
+      reason: `${result.reason}: ${result.message}`,
+    };
+  }
+  let newFindings = 0;
+  const ts = new Date().toISOString();
+  for (const finding of result.findings) {
+    if (finding.kind !== "dead-code") continue;
+    const id = computeQueueEntryId({
+      kind: "dead-code",
+      file: finding.file,
+      range: finding.range,
+      ruleHint: typeof finding.details?.rule === "string" ? finding.details.rule : "post-session-sweep",
+    });
+    const entry: HarnessSlopQueueEntry = {
+      id,
+      kind: "dead-code",
+      file: finding.file,
+      range: finding.range,
+      severity: finding.severity,
+      source: finding.source,
+      state: "open",
+      message: finding.message,
+      remediation: finding.remediation,
+      ts,
+      ...(finding.details ? { details: finding.details } : {}),
+    };
+    const persisted = appendSlopQueueEntry(input.platform.paths, input.cwd, entry);
+    if (persisted.ok) newFindings += 1;
+  }
+  return {
+    ran: true,
+    newFindings,
+    durationMs: Date.now() - startedAt,
+    reason: newFindings > 0 ? `${newFindings} new dead-code finding(s)` : "no new findings",
+  };
+}
+
+export function registerPostSessionSweepHook(
+  platform: Platform,
+  options: PostSessionSweepOptions,
+): () => void {
+  if (!options.config.enabled || options.adapter === null) {
+    return () => {};
+  }
+  let unregistered = false;
+  const adapter = options.adapter;
+  const timeoutMs = options.timeoutMs ?? 30_000;
+
+  const handler = async (_event: unknown, ctx: unknown): Promise<void> => {
+    if (unregistered) return;
+    const cwd = (ctx as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+    if (!fs.existsSync(getHarnessMarkerPath(platform.paths, cwd))) return;
+    const result = await runPostSessionSweep({
+      platform,
+      cwd,
+      adapter,
+      timeoutMs,
+    });
+    if (result.newFindings > 0 && options.config.block_on_new_dead_code) {
+      // The block-on-new-dead-code policy is a steer message; we do NOT abort the agent.
+      const message =
+        `Harness sweep detected ${result.newFindings} new dead-code finding(s). Run /supi:harness backlog to inspect.`;
+      try {
+        platform.sendMessage(
+          { customType: "supi-harness-sweep", content: [{ type: "text", text: message }], display: "none" },
+          { deliverAs: "steer", triggerTurn: false },
+        );
+      } catch {
+        // Platform may not implement sendMessage; ignore.
+      }
+    }
+  };
+
+  platform.on("agent_end", handler);
+  return () => {
+    unregistered = true;
+  };
+}