supipowers 1.5.3 → 2.0.0

package/src/harness/stages/plan.ts

@@ -0,0 +1,335 @@
+/**
+ * PLAN stage runner.
+ *
+ * Reads the design spec and emits a Plan markdown into the canonical plans directory.
+ * The plan is the user-approved task list that Implement will execute.
+ *
+ * The plan structure is the same shape `parsePlan` (src/storage/plans.ts) understands —
+ * we run `validatePlanMarkdown` on the rendered output so the same approval flow that
+ * gates `/supi:plan` gates the harness plan, no special-casing.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { HarnessDesignSpec } from "../../types.js";
+import { validatePlanMarkdown } from "../../planning/validate.js";
+import { savePlan } from "../../storage/plans.js";
+import { getProjectStatePath } from "../../workspace/state-paths.js";
+import {
+  type HarnessStageRunResult,
+  type HarnessStageRunner,
+  type HarnessStageRunnerContext,
+  nowIso,
+} from "../stage-runner.js";
+import {
+  loadHarnessDesignSpecJson,
+} from "../storage.js";
+
+export interface HarnessPlanTask {
+  id: number;
+  name: string;
+  description: string;
+  files: string[];
+  criteria: string;
+  complexity: "small" | "medium" | "large";
+}
+
+/**
+ * Build the canonical task list from a design spec. Always emits the "harden" tasks
+ * (AGENTS.md, docs/architecture.md, docs/golden-principles.md, lint/structural/eval
+ * configs); appends the conditional anti-slop tasks per Design's backend choice.
+ */
+export function buildHarnessPlanTasks(spec: HarnessDesignSpec): HarnessPlanTask[] {
+  const tasks: HarnessPlanTask[] = [];
+  let id = 1;
+
+  tasks.push({
+    id: id++,
+    name: "Generate AGENTS.md",
+    description: "Write a ≤120-line AGENTS.md at the repo root summarizing the harness contract for any agent.",
+    files: ["AGENTS.md"],
+    criteria: "AGENTS.md exists, references docs/architecture.md and docs/golden-principles.md, and ends with a 'When in doubt' section.",
+    complexity: "small",
+  });
+
+  tasks.push({
+    id: id++,
+    name: "Write docs/architecture.md",
+    description: "Render the layer-table convention required by the layer-context-inject hook.",
+    files: ["docs/architecture.md"],
+    criteria: "docs/architecture.md parses cleanly via parseArchitectureMarkdown and reflects the design's layer rules.",
+    complexity: "small",
+  });
+
+  tasks.push({
+    id: id++,
+    name: "Write docs/golden-principles.md",
+    description: "List the ≤10 mechanical rules from the design spec.",
+    files: ["docs/golden-principles.md"],
+    criteria: "docs/golden-principles.md exists and contains every principle from the design spec.",
+    complexity: "small",
+  });
+
+  if (spec.tooling.lint) {
+    tasks.push({
+      id: id++,
+      name: `Wire lint tool (${spec.tooling.lint})`,
+      description: `Install and configure ${spec.tooling.lint} per the design spec.`,
+      files: [],
+      criteria: `${spec.tooling.lint} runs cleanly via the recommended invocation.`,
+      complexity: "small",
+    });
+  }
+
+  if (spec.tooling.structuralTest) {
+    tasks.push({
+      id: id++,
+      name: `Wire structural test tool (${spec.tooling.structuralTest})`,
+      description: `Install and configure ${spec.tooling.structuralTest} per the design spec.`,
+      files: [],
+      criteria: `${spec.tooling.structuralTest} runs cleanly.`,
+      complexity: "small",
+    });
+  }
+
+  if (spec.tooling.eval) {
+    tasks.push({
+      id: id++,
+      name: `Wire eval framework (${spec.tooling.eval})`,
+      description: `Set up the eval framework per the design spec.`,
+      files: [],
+      criteria: `Eval framework runs cleanly.`,
+      complexity: "small",
+    });
+  }
+
+  tasks.push({
+    id: id++,
+    name: "Wire local harness quality command",
+    description: `Add a local quality command that runs every validation gate from the design spec. The canonical command must be \`${spec.ci.localCommand}\`.`,
+    files: ["package.json"],
+    criteria: `Running \`${spec.ci.localCommand}\` executes the configured validation gates and exits non-zero on the first failed required gate.`,
+    complexity: "small",
+  });
+
+  tasks.push({
+    id: id++,
+    name: "Wire CI harness quality workflow",
+    description: `Create ${spec.ci.workflowPath} for ${spec.ci.provider}. It must invoke \`${spec.ci.localCommand}\` instead of duplicating gate logic inline.`,
+    files: [spec.ci.workflowPath],
+    criteria: `Workflow exists, runs on ${
+      spec.ci.trigger.mode === "all-prs" ? "all pull requests" : `pull requests targeting ${spec.ci.trigger.branches.join(", ")}`
+    }, and calls \`${spec.ci.localCommand}\`.`,
+    complexity: "small",
+  });
+
+  // Anti-slop conditional tasks
+  if (spec.antiSlop.backend === "fallow" || spec.antiSlop.backend === "hybrid") {
+    tasks.push({
+      id: id++,
+      name: "Install fallow + write .fallowrc.json",
+      description: "Run `bun install -g fallow` (or set up `npx fallow` shim) and emit `.fallowrc.json` with detected entry points + architecture rules.",
+      files: [".fallowrc.json"],
+      criteria: "`fallow audit --format json` runs cleanly on the repo.",
+      complexity: "small",
+    });
+  }
+
+  if (spec.antiSlop.backend === "desloppify" || spec.antiSlop.backend === "hybrid") {
+    tasks.push({
+      id: id++,
+      name: "Install desloppify",
+      description: 'Run `pip install --upgrade "desloppify[full]"` and add `.desloppify/` to `.gitignore`.',
+      files: [".gitignore"],
+      criteria: "`desloppify scan --format json` runs cleanly on the repo.",
+      complexity: "small",
+    });
+    if (spec.antiSlop.skillTargets.length > 0) {
+      tasks.push({
+        id: id++,
+        name: "Distribute agent-skills",
+        description: `Run desloppify update-skill for each target: ${spec.antiSlop.skillTargets.join(", ")}.`,
+        files: [],
+        criteria: "Every target client has the desloppify skill installed.",
+        complexity: "small",
+      });
+    }
+  }
+
+  tasks.push({
+    id: id++,
+    name: "Register anti-slop hooks",
+    description: "Ensure src/harness/hooks/register.ts wires pre-edit dupe probe, post-session sweep, and layer-context-inject only when the harness marker exists.",
+    files: ["src/harness/hooks/register.ts"],
+    criteria: "Hooks are registered idempotently and gated by the marker file.",
+    complexity: "small",
+  });
+
+  tasks.push({
+    id: id++,
+    name: "Initialize slop queue",
+    description: "Touch the project-scoped queue.jsonl so the queue exists before hooks fire.",
+    files: [],
+    criteria: "queue.jsonl exists and is readable; readSlopQueue returns []",
+    complexity: "small",
+  });
+
+  tasks.push({
+    id: id++,
+    name: "Generate scorecard skeleton + README badge",
+    description: "Compute the initial score and write a repo-local snapshot at .omp/supipowers/harness/score.json.",
+    files: [".omp/supipowers/harness/score.json"],
+    criteria: "Score JSON exists; SVG badge is renderable from it.",
+    complexity: "small",
+  });
+
+  if (spec.supipowersWiring.addReviewAgent) {
+    tasks.push({
+      id: id++,
+      name: "Add architecture-aware review agent",
+      description: "Generate `.omp/supipowers/review-agents/harness-architecture.md` from architecture + golden principles.",
+      files: [".omp/supipowers/review-agents/harness-architecture.md"],
+      criteria: "Review agent file exists and is loaded by `/supi:review`.",
+      complexity: "small",
+    });
+  }
+
+  if (spec.supipowersWiring.wireChecksGate) {
+    tasks.push({
+      id: id++,
+      name: "Wire `/supi:checks` gate",
+      description: `Add a custom gate to .omp/supipowers/config.json that runs the ${spec.antiSlop.backend} scan.`,
+      files: [".omp/supipowers/config.json"],
+      criteria: "`/supi:checks` runs the anti-slop scan as part of its gate set.",
+      complexity: "medium",
+    });
+  }
+
+  return tasks;
+}
+
+/** Render the plan markdown that lands in the canonical plans directory. */
+export function renderHarnessPlanMarkdown(input: {
+  spec: HarnessDesignSpec;
+  tasks: readonly HarnessPlanTask[];
+  recordedAt: string;
+  planName: string;
+}): string {
+  const lines: string[] = [];
+  lines.push("---");
+  lines.push(`name: ${input.planName}`);
+  lines.push(`created: ${input.recordedAt}`);
+  lines.push("tags: [harness, anti-slop]");
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${input.planName}`);
+  lines.push("");
+  lines.push("## Context");
+  lines.push("");
+  lines.push(
+    `Generated by /supi:harness from design spec ${input.spec.sessionId}. Anti-slop backend: \`${input.spec.antiSlop.backend}\`.`,
+  );
+  lines.push("");
+  lines.push("## Tasks");
+  lines.push("");
+  for (const task of input.tasks) {
+    lines.push(`### Task ${task.id}: ${task.name}`);
+    lines.push("");
+    lines.push(task.description);
+    lines.push("");
+    if (task.files.length > 0) {
+      lines.push("**Files:**");
+      for (const f of task.files) lines.push(`- Modify: \`${f}\``);
+      lines.push("");
+    }
+    lines.push(`**criteria**: ${task.criteria}`);
+    lines.push(`**complexity**: ${task.complexity}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export interface PlanStageInput {
+  /** Override for the plan filename. Defaults to `harness-<sessionId>.md`. */
+  planFilename?: string;
+}
+
+export class HarnessPlanStage implements HarnessStageRunner {
+  readonly stage = "plan" as const;
+
+  constructor(private readonly input: PlanStageInput = {}) {}
+
+  async isReady(ctx: HarnessStageRunnerContext): Promise<boolean> {
+    return loadHarnessDesignSpecJson(ctx.paths, ctx.cwd, ctx.sessionId).ok;
+  }
+
+  async isComplete(ctx: HarnessStageRunnerContext): Promise<boolean> {
+    const designResult = loadHarnessDesignSpecJson(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!designResult.ok) return false;
+    const planName = this.input.planFilename ?? `harness-${ctx.sessionId}`;
+    const planPath = path.join(
+      getProjectStatePath(ctx.paths, ctx.cwd, "plans"),
+      `${planName}.md`,
+    );
+    return fs.existsSync(planPath);
+  }
+
+  async run(ctx: HarnessStageRunnerContext): Promise<HarnessStageRunResult> {
+    const designResult = loadHarnessDesignSpecJson(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!designResult.ok) {
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        blocker: {
+          code: "design-spec-missing",
+          message:
+            "Plan stage requires <session>/design-spec.json. Run /supi:harness design first to produce it.",
+        },
+      };
+    }
+    const result = emitHarnessPlanFromSpec({
+      ctx: { paths: ctx.paths, cwd: ctx.cwd },
+      spec: designResult.value,
+      recordedAt: nowIso(ctx),
+      planName: this.input.planFilename ?? `harness-${ctx.sessionId}`,
+    });
+    return {
+      status: "awaiting-user",
+      stage: this.stage,
+      artifactPaths: [result.planPath],
+      details: {
+        taskCount: result.tasks.length,
+        planPath: result.planPath,
+      },
+    };
+  }
+}
+
+/**
+ * Convenience helper for the command handler: render and persist the plan in one call.
+ * The plan goes into the standard plans directory used by `/supi:plan` so the same
+ * approval flow lights up.
+ */
+export function emitHarnessPlanFromSpec(input: {
+  ctx: Pick<HarnessStageRunnerContext, "paths" | "cwd">;
+  spec: HarnessDesignSpec;
+  recordedAt?: string;
+  planName?: string;
+}): { planPath: string; planMarkdown: string; tasks: HarnessPlanTask[] } {
+  const recordedAt = input.recordedAt ?? new Date().toISOString();
+  const planName = input.planName ?? `harness-${input.spec.sessionId}`;
+  const tasks = buildHarnessPlanTasks(input.spec);
+  const planMarkdown = renderHarnessPlanMarkdown({ spec: input.spec, tasks, recordedAt, planName });
+  const filename = `${planName}.md`;
+  const planPath = savePlan(input.ctx.paths, input.ctx.cwd, filename, planMarkdown);
+  return { planPath, planMarkdown, tasks };
+}
+
+/** Validator wrapper — re-uses the canonical validator. */
+export function validateHarnessPlanMarkdown(markdown: string, planName: string): string[] {
+  const result = validatePlanMarkdown(markdown, planName);
+  if (result.output) return [];
+  return result.errors.map((e: { path: string; message: string }) => `${e.path}: ${e.message}`);
+}

package/src/harness/stages/research.ts

@@ -0,0 +1,263 @@
+/**
+ * RESEARCH stage runner.
+ *
+ * Builds `<session>/research/<topic>.md` for every mandatory research topic. The plan
+ * specifies these topics (§5 Phase 4):
+ *
+ *  - "AGENTS.md best practices"
+ *  - "Layered architecture enforcement for <lang>" (capped at 3 languages; ≥3 → polyglot)
+ *  - "Structural test patterns for <stack>"
+ *  - "Eval frameworks for <stack>"
+ *  - "Drift detection patterns"
+ *  - "LLM-failure-mode taxonomy"
+ *  - "Code-duplication detection tools"
+ *  - "Dead-code detection per language"
+ *  - "Pre-edit duplicate-probe ergonomics"
+ *  - "Persistent execution-queue patterns"
+ *
+ * The runner emits a structured stub for each topic (mandatory headings + frontmatter)
+ * the user / a downstream agent fills in. The validator (which lives in the command
+ * handler) requires ≥2 primary-source URLs and the `## Options` + `## Recommendation`
+ * sections; stubs only ship those headings, so a validation pass after Research
+ * intentionally fails until a researcher completes them.
+ *
+ * Why deterministic stubs and not auto-fan-out? Two reasons:
+ *  1. Web search results drift; we must not bake them in.
+ *  2. The plan calls for parallel sub-agents. Spawning them properly requires the model
+ *     resolution wired through model.json — which we do here, but the actual writeups
+ *     are best authored manually for v1 to keep the dependency surface narrow. The agent
+ *     entry point lives in command-handlers, not the stage runner.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  type HarnessStageRunResult,
+  type HarnessStageRunner,
+  type HarnessStageRunnerContext,
+  nowIso,
+} from "../stage-runner.js";
+import {
+  loadHarnessDiscover,
+  saveHarnessResearchTopic,
+} from "../storage.js";
+import { getHarnessResearchDir } from "../project-paths.js";
+
+const BASE_TOPICS: readonly string[] = [
+  "agents-md-best-practices",
+  "drift-detection-patterns",
+  "llm-failure-mode-taxonomy",
+  "code-duplication-detection-tools",
+  "dead-code-detection-per-language",
+  "pre-edit-duplicate-probe-ergonomics",
+  "persistent-execution-queue-patterns",
+];
+
+const STACK_TOPICS_PREFIX = "layered-architecture-enforcement";
+const STRUCTURAL_PREFIX = "structural-test-patterns";
+const EVAL_PREFIX = "eval-frameworks";
+
+const POLYGLOT_BUCKET_THRESHOLD = 3;
+const TOPIC_CAP = 12;
+
+export interface ResearchTopicPlan {
+  slug: string;
+  title: string;
+  context: string;
+}
+
+/**
+ * Compute the topic plan from the discover artifact's languages. Caps at TOPIC_CAP and
+ * collapses to a polyglot bucket when ≥3 languages are present.
+ */
+export function buildResearchTopicPlan(input: { languages: readonly string[] }): ResearchTopicPlan[] {
+  const languages = [...new Set(input.languages.map((l) => l.toLowerCase()))].filter((l) => l.length > 0);
+  const topics: ResearchTopicPlan[] = [];
+
+  for (const slug of BASE_TOPICS) {
+    topics.push({
+      slug,
+      title: humanizeSlug(slug),
+      context: "Always-on base topic (independent of stack).",
+    });
+  }
+
+  if (languages.length >= POLYGLOT_BUCKET_THRESHOLD) {
+    topics.push({
+      slug: `${STACK_TOPICS_PREFIX}-polyglot`,
+      title: "Layered architecture enforcement (polyglot)",
+      context: `${languages.length} languages detected; collapsed into a single polyglot topic.`,
+    });
+    topics.push({
+      slug: `${STRUCTURAL_PREFIX}-polyglot`,
+      title: "Structural test patterns (polyglot)",
+      context: "Multi-language repo; structural tests need to span every detected stack.",
+    });
+    topics.push({
+      slug: `${EVAL_PREFIX}-polyglot`,
+      title: "Eval frameworks (polyglot)",
+      context: "Multi-language repo; eval suites must support multiple test runners.",
+    });
+  } else {
+    for (const lang of languages.slice(0, 3)) {
+      topics.push({
+        slug: `${STACK_TOPICS_PREFIX}-${lang}`,
+        title: `Layered architecture enforcement for ${lang}`,
+        context: `${lang} detected as a primary language.`,
+      });
+    }
+    const dominant = languages[0];
+    if (dominant) {
+      topics.push({
+        slug: `${STRUCTURAL_PREFIX}-${dominant}`,
+        title: `Structural test patterns for ${dominant}`,
+        context: `${dominant} is the dominant language.`,
+      });
+      topics.push({
+        slug: `${EVAL_PREFIX}-${dominant}`,
+        title: `Eval frameworks for ${dominant}`,
+        context: `${dominant} is the dominant language.`,
+      });
+    }
+  }
+
+  return topics.slice(0, TOPIC_CAP);
+}
+
+function humanizeSlug(slug: string): string {
+  return slug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Render the markdown stub for a research topic. Always includes the mandatory `##
+ * Options` and `## Recommendation` headings + a frontmatter block; sources start empty
+ * (the validator demands ≥2 before Research is considered complete).
+ */
+export function renderResearchTopicStub(input: {
+  topic: ResearchTopicPlan;
+  recordedAt: string;
+}): string {
+  return [
+    "---",
+    `topic: ${input.topic.slug}`,
+    `title: ${JSON.stringify(input.topic.title)}`,
+    `lastVerified: ${input.recordedAt}`,
+    "sources: []",
+    "---",
+    "",
+    `# ${input.topic.title}`,
+    "",
+    `> ${input.topic.context}`,
+    "",
+    "## Background",
+    "",
+    "_Pending researcher writeup. Validator will fail until this section is filled in._",
+    "",
+    "## Options",
+    "",
+    "_List candidate approaches with tradeoffs._",
+    "",
+    "## Recommendation",
+    "",
+    "_State the recommended approach and the criteria that drove the choice._",
+    "",
+    "## Sources",
+    "",
+    "_Cite at least two primary sources (papers, official docs, RFCs). Validator rejects writeups with fewer._",
+    "",
+    "## Last verified",
+    "",
+    `${input.recordedAt}`,
+    "",
+  ].join("\n");
+}
+
+export class HarnessResearchStage implements HarnessStageRunner {
+  readonly stage = "research" as const;
+
+  async isReady(ctx: HarnessStageRunnerContext): Promise<boolean> {
+    const discover = loadHarnessDiscover(ctx.paths, ctx.cwd, ctx.sessionId);
+    return discover.ok;
+  }
+
+  async isComplete(ctx: HarnessStageRunnerContext): Promise<boolean> {
+    const dir = getHarnessResearchDir(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!fs.existsSync(dir)) return false;
+    try {
+      const entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+      return entries.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  async run(ctx: HarnessStageRunnerContext): Promise<HarnessStageRunResult> {
+    if (await this.isComplete(ctx)) {
+      return {
+        status: "skipped",
+        stage: this.stage,
+        artifactPaths: ["research/"],
+        details: { reason: "research/ already populated" },
+      };
+    }
+
+    const discover = loadHarnessDiscover(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!discover.ok) {
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths: [],
+        blocker: {
+          code: "discover-missing",
+          message: "Research requires a completed Discover artifact",
+        },
+      };
+    }
+
+    const plan = buildResearchTopicPlan({ languages: discover.value.languages });
+    const recordedAt = nowIso(ctx);
+    const written: string[] = [];
+    for (const topic of plan) {
+      const stub = renderResearchTopicStub({ topic, recordedAt });
+      const result = saveHarnessResearchTopic(ctx.paths, ctx.cwd, ctx.sessionId, topic.slug, stub);
+      if (!result.ok) {
+        return {
+          status: "failed",
+          stage: this.stage,
+          artifactPaths: written,
+          error: `failed to write research topic ${topic.slug}: ${result.error.message}`,
+        };
+      }
+      written.push(path.posix.join("research", `${topic.slug}.md`));
+    }
+
+    return {
+      status: "completed",
+      stage: this.stage,
+      artifactPaths: written,
+      details: { topicCount: plan.length },
+    };
+  }
+}
+
+/**
+ * Validate a research writeup. Returns an array of error messages (empty when valid).
+ * Mirrors the plan's validator: ≥2 sources + presence of `## Options` and `##
+ * Recommendation` headings.
+ */
+export function validateResearchTopic(markdown: string): string[] {
+  const errors: string[] = [];
+  if (!/^##\s+Options\b/im.test(markdown)) errors.push("missing `## Options` heading");
+  if (!/^##\s+Recommendation\b/im.test(markdown)) errors.push("missing `## Recommendation` heading");
+
+  // Sources: count distinct URLs in the doc body. We accept either a frontmatter
+  // `sources: [...]` block or inline `https://` links anywhere.
+  const urls = new Set<string>();
+  for (const match of markdown.matchAll(/https?:\/\/[^\s)<>"']+/g)) {
+    urls.add(match[0]);
+  }
+  if (urls.size < 2) errors.push(`requires ≥2 source URLs (found ${urls.size})`);
+
+  return errors;
+}