@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/invocation/parse-brief.ts

@@ -0,0 +1,188 @@
+/**
+ * scripts/invocation/parse-brief.ts
+ * R2.6 (+D2) — natural-language operator-brief parser (regex v0.2).
+ * Type A — Pure Script (deterministic regex parse; NO clock/random/LLM/I-O).
+ *
+ * The slash-command `/mutagent-diagnostics "<brief>"` takes a single positional
+ * natural-language arg. This parser extracts a best-effort structured shape:
+ *   { agent?, timeWindow?, focus?, residual, scopeType, entity? }
+ *
+ * DEFENSIVE BY DESIGN (plan §4 R2.6): the parser NEVER throws and NEVER drops the
+ * brief. Anything it cannot classify lands in `residual` and the run proceeds with
+ * a neutral survey (design philosophy §2.2 — operator-driven, never skill-prompts).
+ *
+ * D2: the caller stores the VERBATIM brief (runMeta.operatorInvocation) ALONGSIDE
+ * this parsed shape (runMeta.parsedInvocation) — the verbatim is never dropped even
+ * when parsing fully succeeds (re-parse later + intent context + library authenticity).
+ *
+ * v0.2 regex grammar (documented, intentionally simple — iterate later):
+ *   agent      ← "agent <name>" | "for <name>" | "diagnose <name>"
+ *                NOTE: "the agent <name>" is NOT matched (article false-positive guard)
+ *   timeWindow ← "last <N> <unit>" | "past <N> <unit>" | "<N><unit-short> window"
+ *   focus      ← "focus on <text>" | "focused on <text>" | "focus: <text>" | "about <text>"
+ *   scopeType  ← derived from the named entity: "skill" if it looks like a skill name
+ *                (contains "skill" / "diagnostics" / ends in "-skill"), "agent" otherwise.
+ *                null when no entity is extractable.
+ *   entity     ← the raw extracted name (same as agent field when set)
+ *
+ * W11-06 changes:
+ *   - FOCUS_RE: added "focus: <text>" colon form
+ *   - AGENT_RE: negative lookbehind (?<!the\s) to guard "the agent X" false-positive
+ *   - ParsedInvocation: added scopeType + entity fields
+ */
+
+export interface ParsedInvocation {
+  /** Agent / entity the operator named, when extractable. */
+  agent?: string;
+  /** Time window phrase, normalized (e.g. "last 24h"). */
+  timeWindow?: string;
+  /** Focus directive — when set, the report leads with a Guided tab. */
+  focus?: string;
+  /** Everything not classified — the brief is NEVER dropped (defensive). */
+  residual: string;
+  /**
+   * W11-06: classified scope of the diagnosed subject.
+   * - "skill"  — the named entity looks like a skill (contains "skill" or
+   *              "diagnostics", or ends in "-skill")
+   * - "agent"  — a named entity was found but it does not match skill heuristics
+   * - null     — no entity was extractable from the brief
+   */
+  scopeType: "skill" | "agent" | null;
+  /**
+   * W11-06: the raw extracted entity name (same value as `agent` when set).
+   * Populated when scopeType is non-null; absent when scopeType === null.
+   */
+  entity?: string;
+}
+
+/**
+ * W11-06 AGENT_RE:
+ * Guards against "the agent X" false-positive in two layers:
+ *
+ * Layer 1 — Negative lookbehind (?<!the\s):
+ *   Prevents the "agent" keyword itself from firing when preceded by "the ".
+ *   Handles "focus on the agent" where "agent" is a generic noun, not a trigger.
+ *
+ * Layer 2 — Negative lookahead (?!the\b|a\b|an\b):
+ *   Prevents article/determiner words from being captured as the entity name.
+ *   Handles "diagnose the agent" where "diagnose" triggers and "the" would
+ *   otherwise be captured as the entity name.
+ *
+ * Combined: "diagnose the agent" → no entity (both layers block it)
+ *           "diagnose search-agent" → entity = "search-agent" (neither layer fires)
+ */
+const AGENT_RE =
+  /(?<!the\s)\b(?:agent|for|diagnose)\s+(?!the\b|a\b|an\b)([a-z0-9][a-z0-9._-]*)/i;
+const TIME_RE =
+  /\b(?:last|past)\s+(\d+)\s*(hours?|hrs?|h|days?|d|weeks?|w|minutes?|mins?|m)\b/i;
+/**
+ * W11-06 FOCUS_RE: extended to also match "focus: <text>" (colon form).
+ * Original forms retained: "focus on", "focused on", "about".
+ */
+const FOCUS_RE = /\b(?:focus(?:ed)?\s+on|focus\s*:|about)\s+(.+?)(?:\s*$|[.;])/i;
+
+/** Normalize a time unit token to a short canonical form. */
+function normalizeUnit(unit: string): string {
+  const u = unit.toLowerCase();
+  if (u.startsWith("h")) return "h";
+  if (u.startsWith("d")) return "d";
+  if (u.startsWith("w")) return "w";
+  if (u.startsWith("min") || u === "m") return "m";
+  return u;
+}
+
+/**
+ * W11-06: Classify a named entity as 'skill' or 'agent' from its name heuristic.
+ * Deterministic — same input always returns same output.
+ * Heuristic: skill if name contains "skill", "diagnostics", or ends in "-skill".
+ */
+function classifyScopeType(name: string): "skill" | "agent" {
+  const lower = name.toLowerCase();
+  if (
+    lower.includes("skill") ||
+    lower.includes("diagnostics") ||
+    lower.endsWith("-skill")
+  ) {
+    return "skill";
+  }
+  return "agent";
+}
+
+/**
+ * R2.6 — parse a natural-language brief into ParsedInvocation. Deterministic +
+ * defensive: never throws, always returns a residual. An empty/whitespace brief
+ * yields `{ residual: "", scopeType: null }` and the caller falls back to a neutral survey.
+ */
+export function parseBrief(brief: string): ParsedInvocation {
+  const trimmed = (brief ?? "").trim();
+  if (trimmed.length === 0) return { residual: "", scopeType: null };
+
+  const result: ParsedInvocation = { residual: trimmed, scopeType: null };
+
+  const agentMatch = AGENT_RE.exec(trimmed);
+  if (agentMatch) {
+    const name = agentMatch[1];
+    result.agent = name;
+    result.entity = name;
+    result.scopeType = classifyScopeType(name);
+  }
+
+  const timeMatch = TIME_RE.exec(trimmed);
+  if (timeMatch)
+    result.timeWindow = `last ${timeMatch[1]}${normalizeUnit(timeMatch[2])}`;
+
+  const focusMatch = FOCUS_RE.exec(trimmed);
+  if (focusMatch) result.focus = focusMatch[1].trim();
+
+  return result;
+}
+
+/**
+ * True when the parsed invocation carries a focus directive — drives the report's
+ * tab layout (focus → Guided REPLACES Overview; no focus → neutral survey).
+ */
+export function isFocusedInvocation(parsed: ParsedInvocation): boolean {
+  return typeof parsed.focus === "string" && parsed.focus.trim().length > 0;
+}
+
+// ── CLI entrypoint (PRD-SO-05) ────────────────────────────────────────────────
+//
+// Usage:
+//   bun scripts/cli/run.sh scripts/invocation/parse-brief.ts "<brief string>"
+//   bun scripts/cli/run.sh scripts/invocation/parse-brief.ts --output <file> "<brief>"
+//
+// Accepts a positional brief string (may be quoted). Emits { verbatim, parsed } JSON
+// to --output (stdout when omitted). Exit 0 always (parse-brief never throws).
+
+if (import.meta.main) {
+  const { writeFileSync } = await import("node:fs");
+  const { resolve } = await import("node:path");
+
+  const args = process.argv.slice(2);
+
+  let outputPath: string | null = null;
+  const remaining: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--output" && args[i + 1]) {
+      outputPath = args[++i];
+    } else {
+      remaining.push(args[i]);
+    }
+  }
+
+  // The brief is everything in remaining joined (handles multi-word quoted strings
+  // that the shell may have split across positions).
+  const brief = remaining.join(" ").trim();
+  const parsed = parseBrief(brief);
+
+  const out = { verbatim: brief, parsed };
+  const json = JSON.stringify(out, null, 2);
+
+  if (outputPath) {
+    writeFileSync(resolve(outputPath), json, "utf-8");
+    console.info(`parse-brief result written to ${outputPath}`);
+  } else {
+    console.info(json);
+  }
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/library/match.ts

@@ -0,0 +1,114 @@
+/**
+ * scripts/library/match.ts
+ * R2.3 — library-first Tier-0 matching. Promoted regex patterns are matched
+ * BEFORE the generic Tier-0 heuristics so a known failure mode is recognised
+ * cheaply on the next run.
+ * Type A — Pure Script (deterministic regex matching; library is loaded read-only).
+ *
+ * PRD-MP-07 (PR-037): Step 4.5 library-match is MANDATORY when this function
+ * returns priors for the entity. The orchestrator MUST:
+ *   1. Call matchLibraryPatterns() before runTier0ScanPlatformAware()
+ *   2. Pass matches to runTier0ScanWithLibrary() (attaches 3× weight priors)
+ *   3. When ≥1 approved prior exists: SKIP the Step 3.5 awareness mini-sample
+ *      (shouldFireAwareness({priorSignalsRef}) will return fire:false)
+ *   4. Record the skip in runMeta.exemptions or runMeta.decisions
+ *
+ * Library writes are approved-only (scripts/library/store.ts addPattern — operator gate).
+ * Per-host storage: .mutagent/diagnostics/library/ (gitignored).
+ * 3× weight is HARD-CODED (Q15: not configurable — prevents tuning drift).
+ */
+
+import type { TraceMetadata } from "../normalize/trace.ts";
+import type { LibraryPattern } from "./types.ts";
+import { loadEntity } from "./store.ts";
+import { entitySlug } from "./paths.ts";
+
+export interface LibraryMatch {
+  patternId: string;
+  signal: string;
+  /** Trace IDs that matched the pattern. */
+  traceIds: string[];
+  /** PRIOR_SIGNAL_WEIGHT applied (3×) — library priors outrank fresh Tier-0 signals. */
+  weight: number;
+}
+
+/**
+ * Build a deterministic text surface for a trace to match patterns against. Uses
+ * stable, content-derived fields only (tags + agentId + platform). No clock/random.
+ */
+function traceText(t: TraceMetadata): string {
+  const parts = [t.agentId ?? "", t.sourcePlatform, ...(t.tags ?? [])];
+  return parts.join(" ");
+}
+
+/** Compile a library pattern to a RegExp, returning null on an invalid source. */
+function compile(p: LibraryPattern): RegExp | null {
+  try {
+    return new RegExp(p.regex, p.flags ?? "");
+  } catch {
+    return null; // a malformed stored pattern is skipped, never throws.
+  }
+}
+
+/**
+ * R2.3 — match library patterns for an entity against a batch of traces. Returns
+ * one LibraryMatch per pattern that hit at least one trace. Deterministic: patterns
+ * iterate in stored order, traces in input order. The 3× prior weight is attached.
+ */
+export function matchLibraryPatterns(
+  entityName: string,
+  traces: TraceMetadata[],
+  home?: string,
+  weight: number = 3
+): LibraryMatch[] {
+  const entity = loadEntity(entitySlug(entityName), home);
+  if (!entity || entity.patterns.length === 0) return [];
+
+  const matches: LibraryMatch[] = [];
+  for (const pattern of entity.patterns) {
+    const re = compile(pattern);
+    if (!re) continue;
+    const hitIds: string[] = [];
+    for (const t of traces) {
+      if (re.test(traceText(t))) hitIds.push(t.traceId);
+    }
+    if (hitIds.length > 0) {
+      matches.push({ patternId: pattern.patternId, signal: pattern.signal, traceIds: hitIds, weight });
+    }
+  }
+  return matches;
+}
+
+/**
+ * PRD-MP-07: Convenience predicate — true when the library has ≥1 approved prior
+ * for the entity. The orchestrator uses this to decide whether to skip the
+ * Step 3.5 awareness mini-sample (Q18: require ≥1 approved prior, not ≥3).
+ *
+ * NOTE: This does NOT run the match (no traces needed) — it checks whether the
+ * entity record exists AND has at least one pattern. Callers that need actual
+ * match counts should use matchLibraryPatterns(). For a pure existence check
+ * (without loading match state), scripts/library/store.ts hasPriors() is sufficient.
+ *
+ * Preferred match-aware predicate: call matchLibraryPatterns() and check length.
+ * This function provides a quick path when trace data is not yet available.
+ */
+export function hasLibraryPriors(entityName: string, home?: string): boolean {
+  const entity = loadEntity(entitySlug(entityName), home);
+  return entity !== null && entity.patterns.length > 0;
+}
+
+/**
+ * PRD-MP-07: Build a priorSignalsRef string for matchLibraryPatterns results,
+ * suitable for passing to shouldFireAwareness(). Returns undefined when no
+ * matches so the awareness layer fires normally.
+ *
+ * Format: "<entity>:<matchCount> library hits" — stable, human-readable, grep-able.
+ * Use this AFTER calling matchLibraryPatterns() to build the ref from actual hits.
+ */
+export function buildMatchPriorSignalsRef(
+  entityName: string,
+  matches: LibraryMatch[]
+): string | undefined {
+  if (matches.length === 0) return undefined;
+  return `${entitySlug(entityName)}:${matches.length} library hits`;
+}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/scripts/library/paths.ts

@@ -0,0 +1,95 @@
+/**
+ * scripts/library/paths.ts
+ * R2.3 — class-memory library path resolution. LOCAL (per-install) + GITIGNORED.
+ * Type A — Pure Script (path construction only; the base dir is INJECTABLE).
+ *
+ * The library is the skill's cross-run memory: per-entity journals of approved
+ * findings + regex patterns that get matched FIRST in Tier-0 (so a known failure
+ * mode is recognised cheaply on the next run). It lives LOCAL under the unified
+ * `.mutagent/` at the install/init dir (`<root>/.mutagent/diagnostics/library/`)
+ * and is GITIGNORED — we commit the library CODE + a .gitignore entry, NEVER the
+ * library DATA (it is install-/operator-specific and may carry operator-private
+ * invocation briefs via D2). Relocated from the former per-host home dir to the
+ * local `.mutagent/` source of truth (operator decision 2026-06-29): the library
+ * is now per-install, not cross-project per-host.
+ *
+ * Layout (Evolvr-style):
+ *   <root>/.mutagent/diagnostics/library/
+ *     INDEX.md                      # deterministic ToC, sorted by entity
+ *     by-entity/<entity-slug>/
+ *       entity.json                 # machine record (name, type, runs[], priors)
+ *       journal.md                  # append-only human log of approved findings
+ *       patterns/<pattern-id>.json  # regex detectors promoted from approved findings
+ *       deep-read-ledger.json       # BLOCK G — cross-run deep-read digests (deduped by traceId)
+ *
+ * The base dir is INJECTABLE (defaults to the process cwd = the host project root
+ * where `.mutagent/` lives) so tests pass a temp dir and never touch real disk.
+ */
+
+import { join } from "path";
+
+/** Root of the local class-memory library. Injectable base for tests. */
+export function libraryRoot(base: string = process.cwd()): string {
+  return join(base, ".mutagent", "diagnostics", "library");
+}
+
+export function indexPath(base?: string): string {
+  return join(libraryRoot(base), "INDEX.md");
+}
+
+export function byEntityRoot(base?: string): string {
+  return join(libraryRoot(base), "by-entity");
+}
+
+export function entityDir(entitySlug: string, base?: string): string {
+  return join(byEntityRoot(base), entitySlug);
+}
+
+export function entityJsonPath(entitySlug: string, base?: string): string {
+  return join(entityDir(entitySlug, base), "entity.json");
+}
+
+export function journalPath(entitySlug: string, base?: string): string {
+  return join(entityDir(entitySlug, base), "journal.md");
+}
+
+export function patternsDir(entitySlug: string, base?: string): string {
+  return join(entityDir(entitySlug, base), "patterns");
+}
+
+export function patternPath(entitySlug: string, patternId: string, base?: string): string {
+  return join(patternsDir(entitySlug, base), `${patternId}.json`);
+}
+
+/**
+ * BLOCK G — per-entity deep-read ledger file (cross-run digests, deduped by traceId).
+ * Lives under the entity's class-memory dir, alongside entity.json — same local,
+ * gitignored boundary as the rest of the library.
+ */
+export function deepReadLedgerPath(entitySlug: string, base?: string): string {
+  return join(entityDir(entitySlug, base), "deep-read-ledger.json");
+}
+
+/**
+ * UNIFIED VERDICT LEDGER — per-entity finding-verdict memory (both polarities:
+ * approved + dismissed). Lives alongside entity.json in the entity's class-memory
+ * dir, same local + gitignored boundary as the rest of the library. Separate file
+ * (like deep-read-ledger.json) so the approved-only entity.json write gate stays clean
+ * and the approve→pattern promote bytes are unchanged.
+ */
+export function verdictLedgerPath(entitySlug: string, base?: string): string {
+  return join(entityDir(entitySlug, base), "verdict-ledger.json");
+}
+
+/**
+ * Deterministic entity slug: lowercase, non-alphanumerics → "-", collapse repeats,
+ * trim leading/trailing "-". Stable across runs so the same entity always maps to
+ * the same library dir.
+ */
+export function entitySlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "unknown";
+}