@jwilger/pi-development-system 0.1.2 → 0.3.0

package/extensions/development-system.ts

@@ -1,7 +1,14 @@
 import { readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendContextTail, renderContextTail } from "../src/context/context-tail.ts";
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
 import { applyPromptSection } from "../src/context/system-prompt.ts";
+import { createApprovalStore } from "../src/gates/approvals.ts";
+import { registerGitGuard } from "../src/gates/git-guard.ts";
+import { createRecordDepartureTool } from "../src/gates/record-departure-tool.ts";
+import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
+import { registerTestGuard } from "../src/gates/test-guard.ts";
+import { createJevHolder } from "../src/jev/holder.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 
 const nonNegotiables = readFileSync(
@@ -12,20 +19,26 @@ const nonNegotiables = readFileSync(
 /** Composition root: wires modules, holds no logic. */
 export function createDevelopmentSystem(pi: ExtensionAPI) {
   const state = createSessionState(pi);
+  const approvals = createApprovalStore(pi);
 
+  const jevHolder = createJevHolder();
+  let jevModel: string | undefined;
   let lastCtx: ExtensionContext | undefined;
 
   const refreshStatus = () => {
-    lastCtx?.ui.setStatus(STATUS_KEY, renderStatusLine(state.get()));
+    lastCtx?.ui.setStatus(STATUS_KEY, renderStatusLine(state.get(), jevModel));
   };
 
   const rebuild = (ctx: ExtensionContext) => {
     lastCtx = ctx;
-    state.rebuildFrom(
-      ctx.sessionManager
-        .getBranch()
-        .flatMap((e) => (e.type === "custom" ? [{ customType: e.customType, data: e.data }] : [])),
-    );
+    const probe = jevHolder.probe(ctx);
+    jevModel = probe.model;
+    state.update((s) => (s.jev === probe.availability ? s : { ...s, jev: probe.availability }));
+    const entries = ctx.sessionManager
+      .getBranch()
+      .flatMap((e) => (e.type === "custom" ? [{ customType: e.customType, data: e.data }] : []));
+    state.rebuildFrom(entries);
+    approvals.rebuildFrom(entries);
     refreshStatus();
   };
 
@@ -37,10 +50,20 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     applyPromptSection(event, state.get(), nonNegotiables);
   });
 
+  pi.on("context", (event) => {
+    const messages = appendContextTail(event.messages, renderContextTail(state.get()), Date.now());
+    return messages === undefined ? undefined : { messages };
+  });
+
+  registerGitGuard({ pi, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
+  registerTestGuard({ pi, state, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
+  pi.registerTool(createRecordDepartureTool({ pi, state }));
+  pi.registerTool(createRequestApprovalTool({ pi, approvals }));
+
   pi.registerCommand("devsys-status", {
     description: "Show development-system phase, sizing, slice, departures and Jev status",
     handler: async (_args, ctx) => {
-      ctx.ui.notify(renderStatus(state.get()), "info");
+      ctx.ui.notify(renderStatus(state.get(), jevModel), "info");
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"
@@ -32,11 +32,12 @@
     ]
   },
   "dependencies": {
+    "shell-quote": "^1.12.0",
     "smol-toml": "^1.4.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
@@ -46,6 +47,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
+    "@types/shell-quote": "^1.7.5",
     "@typesafe-ai/sdk": "^0.6.0",
     "typescript": "^7.0.2"
   },

package/src/context/context-tail.ts

@@ -0,0 +1,39 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Departure, DevsysState } from "../core/types.ts";
+
+const MAX_LINES = 25;
+const REMINDER =
+  "Departures: call devsys_record_departure before acting against a default; hard stops need the user.";
+
+const scopeLabel = (d: Departure): string =>
+  d.scope.kind === "slice" ? `slice ${d.scope.slice}` : d.scope.kind;
+
+/** Small, cache-friendly reminder appended at the end of the context; undefined when nothing to say. */
+export function renderContextTail(state: DevsysState): string | undefined {
+  if (state.phase === "idle" && state.openDepartures.length === 0) return undefined;
+  const head = [
+    "[development-system]",
+    `phase: ${state.phase} · slice: ${state.activeSlice ?? "none"}`,
+    `Jev: ${state.jev}`,
+  ];
+  const tailLines = [REMINDER];
+  const room = MAX_LINES - head.length - tailLines.length - 1;
+  const lines = state.openDepartures.map(
+    (d) => `- ${d.gate} — ${d.chosen.replace(/\s+/g, " ")} (${scopeLabel(d)})`,
+  );
+  const shown =
+    lines.length <= room
+      ? lines
+      : [...lines.slice(0, room - 1), `- …and ${lines.length - room + 1} more`];
+  return [...head, "Open departures:", ...shown, ...tailLines].join("\n");
+}
+
+/** Appends the tail as a user-role message at the end of `messages`. */
+export function appendContextTail(
+  messages: ReadonlyArray<AgentMessage>,
+  tail: string | undefined,
+  now: number,
+): AgentMessage[] | undefined {
+  if (tail === undefined) return undefined;
+  return [...messages, { role: "user", content: tail, timestamp: now }];
+}

package/src/context/status.ts

@@ -2,15 +2,18 @@ import type { DevsysState } from "../core/types.ts";
 
 export const STATUS_KEY = "devsys";
 
-export const renderStatusLine = (state: DevsysState): string =>
-  `devsys: ${state.phase} · jev ${state.jev}`;
+const jevLabel = (state: DevsysState, model: string | undefined): string =>
+  state.jev === "online" && model !== undefined ? `online (${model})` : state.jev;
 
-export const renderStatus = (state: DevsysState): string =>
+export const renderStatusLine = (state: DevsysState, jevModel?: string): string =>
+  `devsys: ${state.phase} · jev ${jevLabel(state, jevModel)}`;
+
+export const renderStatus = (state: DevsysState, jevModel?: string): string =>
   [
     "Development system status",
     `- phase: ${state.phase}`,
     `- sizing: ${state.sizing ?? "unset"}`,
     `- active slice: ${state.activeSlice ?? "none"}`,
     `- open departures: ${state.openDepartures.length}`,
-    `- jev: ${state.jev}`,
+    `- jev: ${jevLabel(state, jevModel)}`,
   ].join("\n");

package/src/core/departure.ts

@@ -0,0 +1,96 @@
+import {
+  type Departure,
+  type DepartureId,
+  type DepartureScope,
+  type GateId,
+  isParseError,
+  type ParseError,
+  parseError,
+  parseGateId,
+  type SliceRef,
+} from "./types.ts";
+
+export type { Departure } from "./types.ts";
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+function parseScope(input: unknown): DepartureScope | ParseError {
+  if (!isRecord(input)) return parseError("scope must be an object");
+  const { kind, slice, toolCallId } = input;
+  if (kind === "session") return { kind: "session" };
+  if (kind === "slice" && typeof slice === "string") {
+    return { kind: "slice", slice: slice as SliceRef };
+  }
+  if (kind === "once" && typeof toolCallId === "string") return { kind: "once", toolCallId };
+  return parseError(`invalid scope: ${JSON.stringify(input)}`);
+}
+
+const TEXT_FIELDS = ["id", "default", "chosen", "why", "costIfWrong", "recordedAt"] as const;
+
+/** Boundary parse for a Departure (persisted entries, tool input). */
+export function parseDeparture(input: unknown): Departure | ParseError {
+  if (!isRecord(input)) return parseError("departure must be an object");
+  for (const field of TEXT_FIELDS) {
+    if (typeof input[field] !== "string") return parseError(`departure.${field} must be a string`);
+  }
+  const { id, gate: rawGate, tier, approver, revisitWhen } = input;
+  const gate = parseGateId(String(rawGate));
+  if (isParseError(gate)) return gate;
+  if (tier !== "soft" && tier !== "hard") return parseError(`departure.tier invalid: ${tier}`);
+  if (approver !== "agent" && approver !== "user") {
+    return parseError(`departure.approver invalid: ${approver}`);
+  }
+  if (revisitWhen !== undefined && typeof revisitWhen !== "string") {
+    return parseError("departure.revisitWhen must be a string");
+  }
+  const scope = parseScope(input.scope);
+  if (isParseError(scope)) return scope;
+  return {
+    id: id as DepartureId,
+    gate,
+    tier,
+    default: String(input.default),
+    chosen: String(input.chosen),
+    why: String(input.why),
+    costIfWrong: String(input.costIfWrong),
+    approver,
+    scope,
+    ...(revisitWhen !== undefined ? { revisitWhen } : {}),
+    recordedAt: String(input.recordedAt),
+  };
+}
+
+function renderScope(scope: DepartureScope): string {
+  switch (scope.kind) {
+    case "slice":
+      return `slice \`${scope.slice}\``;
+    case "session":
+      return "session";
+    case "once":
+      return `once (${scope.toolCallId})`;
+  }
+}
+
+/** Decision-log entry (plan Appendix A). Ends with a newline. */
+export function renderDepartureMarkdown(d: Departure): string {
+  const revisit = d.revisitWhen !== undefined ? ` · **Revisit when:** ${d.revisitWhen}` : "";
+  return [
+    `### ${d.recordedAt} · ${d.gate} · ${d.tier} · ${d.approver}`,
+    `- **Default:** ${d.default}`,
+    `- **Chosen:** ${d.chosen}`,
+    `- **Why:** ${d.why}`,
+    `- **Cost if wrong:** ${d.costIfWrong}`,
+    `- **Scope:** ${renderScope(d.scope)}${revisit}`,
+    "",
+  ].join("\n");
+}
+
+/** The first departure recorded for `gate` at or before `now` (ISO-8601 UTC strings compare lexically). */
+export function matchesPending(
+  departures: ReadonlyArray<Departure>,
+  gate: GateId,
+  now: string,
+): Departure | undefined {
+  return departures.find((d) => d.gate === gate && d.recordedAt <= now);
+}

package/src/core/gates.ts

@@ -0,0 +1,42 @@
+import type { Tier } from "./types.ts";
+
+export type GateInfo = { readonly tier: Tier; readonly default: string };
+
+/** Registered gate ids (plan Appendix A); grows per increment. Qualified ids use their base entry. */
+export const GATES: Readonly<Record<string, GateInfo>> = {
+  "git.history-rewrite": { tier: "hard", default: "never rewrite published history" },
+  "git.force-push": { tier: "hard", default: "never force-push" },
+  "git.branch-delete-remote": { tier: "hard", default: "never delete remote branches" },
+  "git.destructive-reset": {
+    tier: "hard",
+    default: "never discard uncommitted work with reset --hard",
+  },
+  "git.no-verify": { tier: "hard", default: "never skip commit hooks" },
+  "tests.weaken": { tier: "soft", default: "never weaken, skip or delete tests to get green" },
+  "commit.rationale": { tier: "soft", default: "commit messages carry their rationale" },
+  "commit.mixed-change": {
+    tier: "soft",
+    default: "structural and behavioural changes go in separate commits",
+  },
+  "commit.forbidden-trailer": { tier: "soft", default: "no Co-Authored-By or AI trailers" },
+  "push.red-trunk": { tier: "soft", default: "do not push unrelated work onto a red trunk" },
+  "push.delivery-mode": { tier: "soft", default: "follow the repository's delivery mode" },
+  "tdd.red-first": { tier: "soft", default: "write a failing test before changing behaviour" },
+  "lints.suppression": { tier: "soft", default: "do not suppress lints without a reasoned note" },
+  "review.unsatisfied": { tier: "soft", default: "finish the fresh-context review before release" },
+  "scope.expansion": { tier: "soft", default: "stay within the agreed scope" },
+  "models.phase-mismatch": { tier: "soft", default: "use the model slot routed for this phase" },
+  "artifact.skipped": {
+    tier: "soft",
+    default: "produce the planning artifact for this size of work",
+  },
+  "adr.missing": { tier: "soft", default: "record an ADR for architecture-shaping decisions" },
+};
+
+/** Looks up a gate by id, ignoring any `:qualifier`. */
+export function lookupGate(id: string): GateInfo | undefined {
+  const base = id.split(":")[0] ?? id;
+  return GATES[base];
+}
+
+export const gateIds = (): string[] => Object.keys(GATES);

package/src/core/git-intent.ts

@@ -0,0 +1,275 @@
+import { parse } from "shell-quote";
+
+export type GitIntent =
+  | "history-rewrite"
+  | "force-push"
+  | "branch-delete-remote"
+  | "destructive-reset"
+  | "no-verify"
+  | "ordinary"
+  | "unknown";
+
+/** Highest severity first. */
+const SEVERITY: ReadonlyArray<GitIntent> = [
+  "force-push",
+  "branch-delete-remote",
+  "history-rewrite",
+  "destructive-reset",
+  "no-verify",
+  "unknown",
+  "ordinary",
+];
+
+const worst = (a: GitIntent, b: GitIntent): GitIntent =>
+  SEVERITY.indexOf(a) <= SEVERITY.indexOf(b) ? a : b;
+
+/** Splits a command string on newlines that are outside quotes; backslash-newline is a continuation. */
+function splitLines(command: string): string[] {
+  const lines: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  for (let i = 0; i < command.length; i++) {
+    const ch = command.charAt(i);
+    if (quote !== undefined) {
+      if (ch === quote) quote = undefined;
+      current += ch;
+    } else if (ch === "\\" && command.charAt(i + 1) === "\n") {
+      i++;
+    } else if (ch === "#" && (current === "" || /\s$/.test(current))) {
+      // A comment runs to the end of the line; quotes inside it do not open a quote.
+      while (i < command.length && command.charAt(i) !== "\n") current += command.charAt(i++);
+      i--;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+      current += ch;
+    } else if (ch === "\n") {
+      lines.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  lines.push(current);
+  return lines;
+}
+
+const isRedirect = (op: string): boolean => /^[<>]/.test(op) && !op.endsWith("(");
+
+/** Tokens of one line grouped into simple commands (operators separate segments). */
+function segments(line: string): string[][] {
+  const result: string[][] = [[]];
+  for (const token of parse(line, (name) => `$${name}`)) {
+    if (typeof token === "string") result[result.length - 1]?.push(token);
+    else if ("pattern" in token) result[result.length - 1]?.push(token.pattern);
+    else if ("op" in token && isRedirect(token.op)) continue;
+    else if (!("comment" in token)) result.push([]);
+  }
+  return result.filter((s) => s.length > 0);
+}
+
+const WRAPPERS = new Set(["command", "sudo", "env", "time", "nohup", "exec", "builtin", "nice"]);
+const KEYWORDS = new Set(["then", "do", "else", "elif", "if", "while", "until", "{", "!", "time"]);
+const DATA_ONLY = new Set([
+  "echo",
+  "printf",
+  "cat",
+  "grep",
+  "rg",
+  "man",
+  "which",
+  "type",
+  "head",
+  "tail",
+]);
+const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+const OPAQUE = new Set(["xargs", "ssh", "find", "parallel", "watch"]);
+const GLOBAL_WITH_VALUE = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace"]);
+const HOOK_SKIP_ENV = new Set(["LEFTHOOK=0", "HUSKY=0"]);
+
+const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+const isAssignment = (t: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*=/.test(t);
+
+/** True when `arg` is `name` or an unambiguous-looking git abbreviation of it (`--amen`, `--del=x`). */
+const isLong = (arg: string, ...names: string[]): boolean => {
+  const key = arg.split("=")[0] ?? "";
+  return key.length >= 4 && key.startsWith("--") && names.some((n) => n.startsWith(key));
+};
+
+function classifyGitArgs(globals: string[], sub: string | undefined, args: string[]): GitIntent {
+  let intent: GitIntent = "ordinary";
+  if (globals.some((g) => /^core\.hookspath=/i.test(g))) intent = worst(intent, "no-verify");
+  if (args.some((a) => isLong(a, "--no-verify"))) intent = worst(intent, "no-verify");
+  switch (sub) {
+    case "push": {
+      const shortFlags = args.filter((a) => /^-[A-Za-z]+$/.test(a));
+      if (
+        args.some((a) =>
+          isLong(a, "--force", "--force-with-lease", "--force-if-includes", "--mirror"),
+        ) ||
+        shortFlags.some((a) => a.includes("f")) ||
+        args.some((a) => /^\+\S/.test(a))
+      ) {
+        return worst(intent, "force-push");
+      }
+      if (
+        args.some((a) => isLong(a, "--delete")) ||
+        shortFlags.includes("-d") ||
+        args.some((a) => /^:\S/.test(a))
+      ) {
+        return worst(intent, "branch-delete-remote");
+      }
+      return intent;
+    }
+    case "commit":
+      if (args.some((a) => isLong(a, "--amend"))) return worst(intent, "history-rewrite");
+      if (args.some((a) => /^-[A-Za-z]*n[A-Za-z]*$/.test(a))) return worst(intent, "no-verify");
+      return intent;
+    case "rebase":
+      return args.some((a) => ["--abort", "--continue", "--skip", "--quit"].includes(a))
+        ? intent
+        : worst(intent, "history-rewrite");
+    case "filter-branch":
+    case "filter-repo":
+      return worst(intent, "history-rewrite");
+    case "reset":
+      return args.some((a) => isLong(a, "--hard")) ? worst(intent, "destructive-reset") : intent;
+    default:
+      return intent;
+  }
+}
+
+function classifySegment(tokens: string[]): GitIntent {
+  let hookSkip = false;
+  let i = 0;
+  for (;;) {
+    const t = tokens[i];
+    if (t === undefined) return "ordinary";
+    if (isAssignment(t)) {
+      if (HOOK_SKIP_ENV.has(t)) hookSkip = true;
+      i++;
+    } else if (WRAPPERS.has(t) || KEYWORDS.has(t)) {
+      i++;
+    } else {
+      break;
+    }
+  }
+  const head = tokens[i] ?? "";
+  const rest = tokens.slice(i + 1);
+  const base = basename(head);
+  const withHookSkip = (intent: GitIntent): GitIntent =>
+    hookSkip ? worst(intent, "no-verify") : intent;
+  if (head.startsWith("$") || base === "$GIT") return "unknown";
+  if (SHELLS.has(base)) {
+    const c = rest.findIndex((t) => /^-[A-Za-z]*c[A-Za-z]*$/.test(t));
+    const script = c >= 0 ? rest[c + 1] : undefined;
+    return script !== undefined ? classifyGitCommand(script) : "ordinary";
+  }
+  if (base === "eval") return classifyGitCommand(rest.join(" "));
+  if (OPAQUE.has(base)) return rest.some((t) => basename(t) === "git") ? "unknown" : "ordinary";
+  if (base !== "git") {
+    if (DATA_ONLY.has(base)) return "ordinary";
+    // Wrapper with options (`sudo -E git ...`, `timeout 5 git ...`): classify from the git token.
+    const at = rest.findIndex((t) => basename(t) === "git");
+    return at >= 0 ? withHookSkip(classifySegment(rest.slice(at))) : "ordinary";
+  }
+  const globals: string[] = [];
+  let j = 0;
+  while (j < rest.length && (rest[j] ?? "").startsWith("-")) {
+    const opt = rest[j] ?? "";
+    if (GLOBAL_WITH_VALUE.has(opt)) {
+      globals.push(rest[j + 1] ?? "");
+      j += 2;
+    } else {
+      j++;
+    }
+  }
+  const sub = rest[j];
+  const args = rest.slice(j + 1);
+  const dynamic =
+    (sub ?? "").startsWith("$") ||
+    (["push", "reset", "rebase"].includes(sub ?? "") &&
+      args.some((t) => t.startsWith("$") || t.includes("`")));
+  const intent = classifyGitArgs(globals, sub, args);
+  return withHookSkip(dynamic ? worst(intent, "unknown") : intent);
+}
+
+/**
+ * The parts of a line bash may still execute or treat as syntax: single-quoted text and
+ * backslash-escaped characters are dropped; double-quoted text is kept unless `dropDouble`.
+ */
+function live(line: string, dropDouble: boolean): string {
+  let out = "";
+  let quote: "'" | '"' | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line.charAt(i);
+    if (quote === "'") {
+      if (ch === "'") quote = undefined;
+    } else if (ch === "\\") {
+      i++;
+    } else if (quote === '"') {
+      if (ch === '"') quote = undefined;
+      else if (!dropDouble) out += ch;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+/** Bodies of `$(...)` and backtick substitutions anywhere in the text (quoted or not). */
+function substitutions(text: string): string[] {
+  const bodies: string[] = [];
+  for (let at = text.indexOf("$("); at >= 0; at = text.indexOf("$(", at + 2)) {
+    let depth = 1;
+    let end = at + 2;
+    for (; end < text.length && depth > 0; end++) {
+      const ch = text.charAt(end);
+      if (ch === "(") depth++;
+      else if (ch === ")") depth--;
+    }
+    bodies.push(text.slice(at + 2, depth === 0 ? end - 1 : end));
+  }
+  for (const m of text.matchAll(/`([^`]*)`/g)) bodies.push(m[1] ?? "");
+  return bodies;
+}
+
+const HEREDOC = /^<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/;
+
+/** The delimiter of a heredoc started by an unquoted `<<` on this line, if any. */
+function heredocDelimiter(line: string): string | undefined {
+  let quote: "'" | '"' | undefined;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line.charAt(i);
+    if (quote !== undefined) {
+      if (ch === quote) quote = undefined;
+    } else if (ch === "\\") {
+      i++;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+    } else if (line.startsWith("<<<", i)) {
+      i += 2;
+    } else if (ch === "<" && line.charAt(i + 1) === "<") {
+      return HEREDOC.exec(line.slice(i))?.[2];
+    }
+  }
+  return undefined;
+}
+
+/** Classifies the most severe git intent in a shell command (deterministic fast path). */
+export function classifyGitCommand(command: string): GitIntent {
+  let intent: GitIntent = "ordinary";
+  let heredocEnd: string | undefined;
+  for (const line of splitLines(command)) {
+    if (heredocEnd !== undefined) {
+      if (line.trim() === heredocEnd) heredocEnd = undefined;
+      continue;
+    }
+    for (const segment of segments(line)) intent = worst(intent, classifySegment(segment));
+    for (const body of substitutions(live(line, false)))
+      intent = worst(intent, classifyGitCommand(body));
+    heredocEnd = heredocDelimiter(line) ?? heredocEnd;
+  }
+  return intent;
+}

package/src/core/redact.ts

@@ -0,0 +1,10 @@
+/** Removes credentials from text before it is written to committed logs or session entries (R11). */
+export function redactSecrets(text: string): string {
+  return text
+    .replace(/(\w+:\/\/)[^\s/@]+@/g, "$1[redacted]@")
+    .replace(/\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{16,}/g, "[redacted]")
+    .replace(/\b(\w*(?:TOKEN|KEY|SECRET|PASSWORD)\w*)=("[^"]*"|'[^']*'|\S+)/gi, "$1=[redacted]")
+    .replace(/\b(Authorization:\s*)\w+\s+[^\s'"]+/gi, "$1[redacted]")
+    .replace(/\bBearer\s+[^\s'"]+/g, "Bearer [redacted]")
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}/g, "[redacted]");
+}

package/src/core/result.ts

@@ -0,0 +1,7 @@
+/** A value or a typed error (errors as values, R2/R3). */
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });

package/src/core/test-paths.ts

@@ -0,0 +1,27 @@
+export type TestPathProfile = { readonly testGlobs?: readonly string[] };
+
+const PATTERNS: readonly RegExp[] = [
+  /(^|\/)(test|tests|__tests__|spec|specs|e2e)\//,
+  /\.(test|spec|cy)\.[cm]?[jt]sx?$/,
+  /_test\.(go|rb|py|exs?|rs)$/,
+  /(^|\/)test_[^/]+\.py$/,
+  /_spec\.rb$/,
+];
+
+const SPECIALS = /[.+^$(){}|[\]\\]/g;
+
+function globToRegExp(glob: string): RegExp {
+  const escaped = glob
+    .replace(SPECIALS, "\\$&")
+    .replace(/\*\*/g, "@@GLOBSTAR@@")
+    .replace(/\*/g, "[^/]*")
+    .replace(/@@GLOBSTAR@@/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+/** Whether a repo-relative path is a test file (conventions, plus profile-supplied globs). */
+export function isTestPath(path: string, profile?: TestPathProfile): boolean {
+  const normalized = path.replace(/^\.\//, "");
+  if (PATTERNS.some((p) => p.test(normalized))) return true;
+  return (profile?.testGlobs ?? []).some((g) => globToRegExp(g).test(normalized));
+}