supipowers 2.0.2 → 2.2.0

package/src/harness/docs/provenance.ts

@@ -0,0 +1,125 @@
+/**
+ * Provenance marker for harness-generated docs.
+ *
+ * Every doc rendered by the docs stage carries a single HTML-style comment on the first
+ * line:
+ *
+ *   <!-- harness-docs:session=<sid> generated=<iso> contentHash=<sha256> -->
+ *
+ * The marker is the only thing the user must not edit. It lets the regen-decision logic
+ * distinguish between (1) a doc that is still in sync with what the harness produced,
+ * (2) a doc the user hand-edited and should not be overwritten, and (3) a doc that just
+ * needs to be regenerated because its inputs changed.
+ *
+ * Format is intentionally compact and easy to parse with a regex — the marker is on a
+ * single line, fields are `key=value` pairs separated by spaces.
+ */
+
+import { sha256 } from "./source-hash.js";
+
+const MARKER_PREFIX = "<!-- harness-docs:";
+const MARKER_SUFFIX = " -->";
+
+export interface DocProvenance {
+  /** Session id that produced the doc. */
+  sessionId: string;
+  /** ISO timestamp the doc was generated. */
+  generatedAt: string;
+  /** sha256 of the doc body after the marker line (excludes the marker itself). */
+  contentHash: string;
+}
+
+/** Render a provenance marker line. Always single-line; no trailing newline. */
+export function renderProvenanceMarker(provenance: DocProvenance): string {
+  // Each value passes through `encode` so an accidental quote/space cannot break parsing.
+  const session = encodeValue(provenance.sessionId);
+  const generated = encodeValue(provenance.generatedAt);
+  const hash = encodeValue(provenance.contentHash);
+  return `${MARKER_PREFIX}session=${session} generated=${generated} contentHash=${hash}${MARKER_SUFFIX}`;
+}
+
+/**
+ * Parse a markdown doc and return its provenance + the body after the marker. Returns
+ * `null` when the first line is not a recognizable marker.
+ *
+ * Tolerant: the marker MUST be on the first line. A doc without a first-line marker is
+ * always treated as user-authored.
+ */
+export function parseProvenance(markdown: string): { provenance: DocProvenance; body: string } | null {
+  const newlineIndex = markdown.indexOf("\n");
+  const firstLine = newlineIndex >= 0 ? markdown.slice(0, newlineIndex) : markdown;
+  if (!firstLine.startsWith(MARKER_PREFIX) || !firstLine.endsWith(MARKER_SUFFIX)) {
+    return null;
+  }
+
+  const inner = firstLine.slice(MARKER_PREFIX.length, firstLine.length - MARKER_SUFFIX.length).trim();
+  const fields = parseFields(inner);
+
+  const sessionId = fields.get("session");
+  const generatedAt = fields.get("generated");
+  const contentHash = fields.get("contentHash");
+  if (!sessionId || !generatedAt || !contentHash) return null;
+
+  const body = newlineIndex >= 0 ? markdown.slice(newlineIndex + 1) : "";
+  return {
+    provenance: { sessionId, generatedAt, contentHash },
+    body,
+  };
+}
+
+/** Compute the content hash for a body (i.e., everything after the marker line). */
+export function computeBodyContentHash(body: string): string {
+  return sha256(body);
+}
+
+/**
+ * Wrap a body with a fresh provenance marker. Convenience for renderers. Returns the full
+ * doc string starting with the marker line.
+ */
+export function attachProvenance(body: string, provenance: DocProvenance): string {
+  return `${renderProvenanceMarker(provenance)}\n${body}`;
+}
+
+/**
+ * Detect whether a stored doc was hand-edited after the harness produced it. Returns:
+ * - `"unmarked"` when there is no marker (treat as user-authored — never overwrite blindly).
+ * - `"edited"` when the marker exists but the body hash does not match.
+ * - `"intact"` when marker + body hash agree (safe to regen using the marker's sourceHash).
+ */
+export function detectUserEdit(markdown: string): "unmarked" | "edited" | "intact" {
+  const parsed = parseProvenance(markdown);
+  if (!parsed) return "unmarked";
+  const actual = computeBodyContentHash(parsed.body);
+  return actual === parsed.provenance.contentHash ? "intact" : "edited";
+}
+
+// ── Internals ───────────────────────────────────────────────────────────────
+
+/** Parse the inner part of a marker into a Map of key/value pairs. */
+function parseFields(inner: string): Map<string, string> {
+  const out = new Map<string, string>();
+  // Tokenize on whitespace. Values must not contain spaces (encodeValue enforces this).
+  for (const token of inner.split(/\s+/)) {
+    if (!token) continue;
+    const eq = token.indexOf("=");
+    if (eq <= 0) continue;
+    const key = token.slice(0, eq);
+    const value = decodeValue(token.slice(eq + 1));
+    out.set(key, value);
+  }
+  return out;
+}
+
+/**
+ * Encode a value so the marker remains parseable. Spaces and the literal `-->` sequence
+ * are forbidden in the canonical values we accept (session id pattern, ISO timestamps,
+ * hex hashes). The encode step is defensive: spaces become `%20`, the marker terminator
+ * is escaped to `--&gt;`. Decoding inverts those.
+ */
+function encodeValue(value: string): string {
+  return value.replace(/-->/g, "--&gt;").replace(/ /g, "%20");
+}
+
+function decodeValue(value: string): string {
+  return value.replace(/%20/g, " ").replace(/--&gt;/g, "-->");
+}

package/src/harness/docs/regen-decision.ts

@@ -0,0 +1,167 @@
+/**
+ * Decide which per-layer docs need regeneration, which to skip, and which were
+ * hand-edited by the user.
+ *
+ * Pure function over filesystem reads. Inputs:
+ *   - the active layer set
+ *   - the cwd hosting `docs/layers/<id>.md`
+ *   - the expected source hash per layer
+ *
+ * Outputs the three buckets the docs stage acts on:
+ *   - `regen`: missing doc OR sourceHash mismatch with provenance intact
+ *   - `skip`:  doc exists, provenance intact, sourceHash matches expected
+ *   - `userEdited`: marker present but body hash mismatch (or marker missing on a file
+ *      that exists at the well-known path)
+ *
+ * The docs stage refuses to overwrite `userEdited` files; it surfaces them as warnings.
+ */
+
+import * as fs from "node:fs";
+
+import type { HarnessLayerRule } from "../../types.js";
+import { getHarnessRepoDocsLayerPath } from "../project-paths.js";
+import type { PlatformPaths } from "../../platform/types.js";
+import {
+  detectUserEdit,
+  parseProvenance,
+} from "./provenance.js";
+
+export type RegenAction = "regen" | "skip" | "userEdited";
+
+export interface RegenDecisionEntry {
+  layerId: string;
+  action: RegenAction;
+  /** Reason note; useful for tracing decisions. */
+  reason: string;
+}
+
+export interface DecideRegenSetInput {
+  paths: PlatformPaths;
+  cwd: string;
+  layers: readonly HarnessLayerRule[];
+  /** Map from layer id → expected source hash. Missing entries default to "regen". */
+  expectedSourceHashes: ReadonlyMap<string, string>;
+}
+
+export interface DecideRegenSetResult {
+  /** Convenience: layers that must regen. */
+  regen: string[];
+  /** Convenience: layers that can skip. */
+  skip: string[];
+  /** Convenience: layers preserved because the user edited them. */
+  userEdited: string[];
+  /** Full per-layer decision trace. */
+  entries: RegenDecisionEntry[];
+}
+
+/**
+ * Compute the regen decision for every layer. Reads the repo-local docs/layers/<id>.md
+ * if it exists; never writes.
+ */
+export function decideRegenSet(input: DecideRegenSetInput): DecideRegenSetResult {
+  const entries: RegenDecisionEntry[] = [];
+  for (const layer of input.layers) {
+    const docPath = getHarnessRepoDocsLayerPath(input.paths, input.cwd, layer.layer);
+    const expected = input.expectedSourceHashes.get(layer.layer);
+
+    if (!fs.existsSync(docPath)) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "doc missing",
+      });
+      continue;
+    }
+
+    let contents: string;
+    try {
+      contents = fs.readFileSync(docPath, "utf8");
+    } catch (error) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: `unable to read doc: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+
+    const editState = detectUserEdit(contents);
+    if (editState === "unmarked") {
+      entries.push({
+        layerId: layer.layer,
+        action: "userEdited",
+        reason: "doc has no harness-docs marker; treated as user-authored",
+      });
+      continue;
+    }
+    if (editState === "edited") {
+      entries.push({
+        layerId: layer.layer,
+        action: "userEdited",
+        reason: "doc body hash differs from marker contentHash; user edits preserved",
+      });
+      continue;
+    }
+
+    // intact → compare frontmatter sourceHash to expected.
+    if (!expected) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "no expected source hash supplied",
+      });
+      continue;
+    }
+
+    const sourceHash = readFrontmatterSourceHash(contents);
+    if (!sourceHash) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "doc is intact but frontmatter lacks sourceHash",
+      });
+      continue;
+    }
+    if (sourceHash !== expected) {
+      entries.push({
+        layerId: layer.layer,
+        action: "regen",
+        reason: "frontmatter sourceHash does not match expected (inputs changed)",
+      });
+      continue;
+    }
+
+    entries.push({
+      layerId: layer.layer,
+      action: "skip",
+      reason: "doc is up-to-date",
+    });
+  }
+
+  return {
+    regen: entries.filter((e) => e.action === "regen").map((e) => e.layerId),
+    skip: entries.filter((e) => e.action === "skip").map((e) => e.layerId),
+    userEdited: entries.filter((e) => e.action === "userEdited").map((e) => e.layerId),
+    entries,
+  };
+}
+
+/**
+ * Extract the `sourceHash:` value from the YAML frontmatter of a docs file. Returns
+ * null when the doc lacks well-formed frontmatter.
+ */
+function readFrontmatterSourceHash(markdown: string): string | null {
+  const parsed = parseProvenance(markdown);
+  const body = parsed ? parsed.body : markdown;
+  if (!body.startsWith("---")) return null;
+  const firstNewline = body.indexOf("\n");
+  if (firstNewline < 0) return null;
+  const closeIdx = body.indexOf("\n---", firstNewline);
+  if (closeIdx < 0) return null;
+  const inner = body.slice(firstNewline + 1, closeIdx);
+  for (const line of inner.split("\n")) {
+    const match = line.match(/^sourceHash\s*:\s*(.+)\s*$/);
+    if (match) return match[1].trim();
+  }
+  return null;
+}

package/src/harness/docs/representative-files.ts

@@ -0,0 +1,175 @@
+/**
+ * Representative-file selection for the docs stage.
+ *
+ * Given a list of files in a layer, pick the top-N by LOC and produce a head-K slice of
+ * each for the subagent's input bundle. Caps the total payload so even pathological
+ * monorepo layers never blow the prompt budget.
+ *
+ * Deterministic ordering is non-negotiable — the source-hash composition depends on it.
+ * Ordering is LOC-descending, then path-ascending as a tiebreaker.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { sha256 } from "./source-hash.js";
+
+/**
+ * Default top-N representative files to include. Matches the plan's Q7a contract.
+ */
+export const DEFAULT_REPRESENTATIVE_COUNT = 5;
+
+/**
+ * Default head-K LOC to sample per representative file. Matches the plan's Q7a contract.
+ */
+export const DEFAULT_REPRESENTATIVE_HEAD_LOC = 80;
+
+/**
+ * Hard cap on the total subagent input bundle in bytes. Keeps us well inside any
+ * reasonable model context budget; representative-file output is the only growable
+ * component.
+ */
+export const DEFAULT_BUNDLE_BYTES_CAP = 25_000;
+
+export interface RepresentativeFileEntry {
+  /** Forward-slashed path relative to the repo root. */
+  path: string;
+  /** Total LOC in the underlying file (used for ordering only). */
+  loc: number;
+  /** Head-K slice of the file body, with trailing "…\n" when the body was truncated. */
+  sample: string;
+  /** sha256 of the file's full contents at read time. */
+  contentHash: string;
+}
+
+export interface SelectRepresentativeFilesInput {
+  /** Repo root. All `files` paths are resolved relative to this. */
+  cwd: string;
+  /** Candidate files (forward-slashed, relative to `cwd`). */
+  files: readonly string[];
+  /** Max number of representative files to keep. */
+  topN?: number;
+  /** Max LOC to sample per file. */
+  headLoc?: number;
+  /** Total bundle byte cap; files past it are dropped in tail order. */
+  bundleBytesCap?: number;
+}
+
+export interface SelectRepresentativeFilesResult {
+  /** Selected representative files, sorted by LOC desc → path asc. */
+  entries: RepresentativeFileEntry[];
+  /** Files we considered but skipped because reading failed; useful for debugging. */
+  unreadable: string[];
+}
+
+/**
+ * Read every candidate file, sort by LOC desc, and emit a deterministic, byte-capped
+ * representative sample list. Pure-ish: reads the filesystem but never writes.
+ */
+export function selectRepresentativeFiles(
+  input: SelectRepresentativeFilesInput,
+): SelectRepresentativeFilesResult {
+  const topN = input.topN ?? DEFAULT_REPRESENTATIVE_COUNT;
+  const headLoc = input.headLoc ?? DEFAULT_REPRESENTATIVE_HEAD_LOC;
+  const bundleCap = input.bundleBytesCap ?? DEFAULT_BUNDLE_BYTES_CAP;
+
+  type Stat = { path: string; loc: number; contents: string; contentHash: string };
+
+  const stats: Stat[] = [];
+  const unreadable: string[] = [];
+  for (const rel of input.files) {
+    const absolute = path.join(input.cwd, rel);
+    let contents: string;
+    try {
+      contents = fs.readFileSync(absolute, "utf8");
+    } catch {
+      unreadable.push(rel);
+      continue;
+    }
+    const loc = countLines(contents);
+    stats.push({
+      path: rel,
+      loc,
+      contents,
+      contentHash: sha256(contents),
+    });
+  }
+
+  stats.sort((a, b) => {
+    if (a.loc !== b.loc) return b.loc - a.loc;
+    return a.path.localeCompare(b.path);
+  });
+
+  const limited = stats.slice(0, topN);
+
+  // Byte-cap pass: build samples and stop when the cumulative byte count would exceed
+  // bundleBytesCap. We always emit the largest-LOC file (top of the list) even if it
+  // alone exceeds the cap — the runner must know about it. Subsequent files yield to
+  // the cap.
+  const entries: RepresentativeFileEntry[] = [];
+  let used = 0;
+  for (let i = 0; i < limited.length; i += 1) {
+    const stat = limited[i];
+    const sample = headSlice(stat.contents, headLoc);
+    const cost = Buffer.byteLength(sample, "utf8");
+    if (i > 0 && used + cost > bundleCap) break;
+    used += cost;
+    entries.push({
+      path: stat.path,
+      loc: stat.loc,
+      sample,
+      contentHash: stat.contentHash,
+    });
+  }
+
+  return { entries, unreadable };
+}
+
+function countLines(contents: string): number {
+  if (contents.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < contents.length; i += 1) {
+    if (contents.charCodeAt(i) === 10 /* \n */) count += 1;
+  }
+  // A trailing newline implies the last "line" is empty; subtract one to match `wc -l`-ish
+  // semantics callers expect.
+  if (contents.charCodeAt(contents.length - 1) === 10) count -= 1;
+  return count;
+}
+
+function headSlice(contents: string, headLoc: number): string {
+  if (headLoc <= 0) return "";
+  let consumed = 0;
+  let cursor = 0;
+  for (let i = 0; i < contents.length; i += 1) {
+    if (contents.charCodeAt(i) === 10 /* \n */) {
+      consumed += 1;
+      if (consumed >= headLoc) {
+        cursor = i + 1;
+        break;
+      }
+    }
+    cursor = i + 1;
+  }
+  if (cursor >= contents.length) return contents;
+  return `${contents.slice(0, cursor)}…\n`;
+}
+
+/**
+ * Render the subagent input bundle's representative-files block.
+ *
+ * Format mirrors the plan's Q7a contract:
+ *   --- src/path/a.ts ---
+ *   <sample>
+ *   --- src/path/b.ts ---
+ *   ...
+ */
+export function renderRepresentativeBlock(entries: readonly RepresentativeFileEntry[]): string {
+  if (entries.length === 0) return "(no representative files)";
+  const out: string[] = [];
+  for (const entry of entries) {
+    out.push(`--- ${entry.path} ---`);
+    out.push(entry.sample.endsWith("\n") ? entry.sample.slice(0, -1) : entry.sample);
+  }
+  return out.join("\n");
+}

package/src/harness/docs/source-hash.ts

@@ -0,0 +1,106 @@
+/**
+ * Source-hash composition for the docs stage.
+ *
+ * The hash is the single trigger that decides whether a per-layer doc needs to be
+ * regenerated. It composes every input the subagent sees (layer rule, layer file paths,
+ * representative file contents, golden principles, peer layer descriptors, prompt
+ * version) into a stable JSON payload, then sha256s the result.
+ *
+ * Determinism is non-negotiable — any inadvertently mutable input (filesystem order,
+ * representative-file ordering, etc.) defeats the cache and forces wasteful re-runs.
+ */
+
+import * as crypto from "node:crypto";
+
+import type { HarnessLayerRule } from "../../types.js";
+
+export interface RepresentativeFileFingerprint {
+  /** Path relative to the repo root, forward-slashed. */
+  path: string;
+  /** sha256 of the file contents at hash-compute time. */
+  contentHash: string;
+}
+
+export interface PeerLayerFingerprint {
+  /** Layer id. */
+  id: string;
+  /** Human-readable description; empty string when the layer rule omits one. */
+  description: string;
+}
+
+export interface ComputeLayerSourceHashInput {
+  /** Layer rule under consideration. Embedded verbatim into the hash payload. */
+  layerRule: HarnessLayerRule;
+  /** Sorted (lexicographic) list of every file path matching the layer glob. */
+  globPaths: readonly string[];
+  /** Representative files the subagent reads (top-N by LOC), each with a content hash. */
+  representativeFiles: readonly RepresentativeFileFingerprint[];
+  /** Repo-wide golden principles, in their original document order. */
+  goldenPrinciples: readonly string[];
+  /** Peer layer descriptors (id + description). Sorted internally before hashing. */
+  peerLayers: readonly PeerLayerFingerprint[];
+  /** sha256 of the subagent system prompt at build time. */
+  promptVersion: string;
+}
+
+/**
+ * Compute the deterministic source hash for a single layer doc. Pure function.
+ *
+ * Sort behavior:
+ * - `globPaths` are sorted defensively (lexicographic).
+ * - `representativeFiles` are sorted by `path` (lexicographic).
+ * - `peerLayers` are sorted by `id` (lexicographic).
+ *
+ * Determinism contract: any deep-equal set of inputs yields the same hash regardless of
+ * caller-provided ordering on the three sorted arrays.
+ */
+export function computeLayerSourceHash(input: ComputeLayerSourceHashInput): string {
+  const sortedGlobPaths = [...input.globPaths].sort((a, b) => a.localeCompare(b));
+  const sortedRepFiles = [...input.representativeFiles]
+    .map((entry) => ({ path: entry.path, contentHash: entry.contentHash }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const sortedPeerLayers = [...input.peerLayers]
+    .map((entry) => ({ id: entry.id, description: entry.description }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const payload = {
+    layerRule: serializeLayerRule(input.layerRule),
+    globPaths: sortedGlobPaths,
+    representativeFiles: sortedRepFiles,
+    goldenPrinciples: [...input.goldenPrinciples],
+    peerLayers: sortedPeerLayers,
+    promptVersion: input.promptVersion,
+  };
+
+  return sha256Json(payload);
+}
+
+/** Compute sha256 of a UTF-8 string. */
+export function sha256(text: string): string {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/** Compute sha256 of a JSON-serializable payload. Object key order is preserved verbatim. */
+export function sha256Json(payload: unknown): string {
+  return sha256(JSON.stringify(payload));
+}
+
+/**
+ * Reduce a layer rule to a deterministic shape (sorted import lists, normalized description)
+ * so two semantically-equal rules produce the same hash regardless of source ordering.
+ */
+function serializeLayerRule(rule: HarnessLayerRule): {
+  layer: string;
+  globs: string[];
+  allowedImports: string[];
+  forbiddenImports: string[];
+  description: string;
+} {
+  return {
+    layer: rule.layer,
+    globs: [...rule.globs].sort((a, b) => a.localeCompare(b)),
+    allowedImports: [...rule.allowedImports].sort((a, b) => a.localeCompare(b)),
+    forbiddenImports: [...rule.forbiddenImports].sort((a, b) => a.localeCompare(b)),
+    description: rule.description ?? "",
+  };
+}