@geminix/gxpm 0.1.0

package/core/dag-schemas.ts

@@ -0,0 +1,150 @@
+/**
+ * DAG Execution Schemas
+ *
+ * Types and validation for the gxpm DAG executor.
+ * Inspired by Archon's dag-executor.ts and loader.ts,
+ * adapted for gxpm's phase-runtime and capability model.
+ */
+
+export const TRIGGER_RULES = [
+  "all_success",
+  "one_success",
+  "none_failed_min_one_success",
+  "all_done",
+] as const;
+
+export type TriggerRule = (typeof TRIGGER_RULES)[number];
+
+export const NODE_STATES = [
+  "pending",
+  "running",
+  "completed",
+  "skipped",
+  "failed",
+] as const;
+
+export type NodeState = (typeof NODE_STATES)[number];
+
+/** Base fields every DAG node shares */
+export interface DagNodeBase {
+  id: string;
+  depends_on?: string[];
+  trigger_rule?: TriggerRule;
+  when?: string;
+  retry?: {
+    max_attempts: number;
+    delay_ms?: number;
+    on_error?: "transient" | "all";
+  };
+}
+
+/** A node that runs an agent prompt */
+export interface PromptNode extends DagNodeBase {
+  type: "prompt";
+  prompt: string;
+  provider?: string;
+  model?: string;
+  systemPrompt?: string;
+  output_format?: Record<string, unknown>;
+  maxBudgetUsd?: number;
+  allowed_tools?: string[];
+  denied_tools?: string[];
+}
+
+/** A node that runs a shell/bash command */
+export interface BashNode extends DagNodeBase {
+  type: "bash";
+  bash: string;
+}
+
+/** A node that runs a local script file */
+export interface ScriptNode extends DagNodeBase {
+  type: "script";
+  script: string;
+}
+
+/** A node that represents a gxpm phase gate */
+export interface PhaseNode extends DagNodeBase {
+  type: "phase";
+  phase: string;
+}
+
+/** A no-op node used for gating or grouping */
+export interface ApprovalNode extends DagNodeBase {
+  type: "approval";
+  message?: string;
+}
+
+/** A node that cancels the workflow on failure */
+export interface CancelNode extends DagNodeBase {
+  type: "cancel";
+}
+
+export type DagNode =
+  | PromptNode
+  | BashNode
+  | ScriptNode
+  | PhaseNode
+  | ApprovalNode
+  | CancelNode;
+
+export function isPromptNode(node: DagNode): node is PromptNode {
+  return node.type === "prompt";
+}
+
+export function isBashNode(node: DagNode): node is BashNode {
+  return node.type === "bash";
+}
+
+export function isScriptNode(node: DagNode): node is ScriptNode {
+  return node.type === "script";
+}
+
+export function isPhaseNode(node: DagNode): node is PhaseNode {
+  return node.type === "phase";
+}
+
+export function isApprovalNode(node: DagNode): node is ApprovalNode {
+  return node.type === "approval";
+}
+
+export function isCancelNode(node: DagNode): node is CancelNode {
+  return node.type === "cancel";
+}
+
+/** Result of executing a single node */
+export interface NodeOutput {
+  state: NodeState;
+  output: string;
+  error?: string;
+  durationMs?: number;
+  retries?: number;
+}
+
+/** Overall DAG execution result */
+export interface DagExecutionResult {
+  success: boolean;
+  nodeOutputs: Map<string, NodeOutput>;
+  durationMs: number;
+  error?: string;
+}
+
+/** Raw workflow definition (before validation) */
+export interface WorkflowDefinition {
+  name: string;
+  description: string;
+  provider?: string;
+  model?: string;
+  nodes: DagNode[];
+}
+
+/** Validation / load error */
+export interface WorkflowLoadError {
+  filename: string;
+  error: string;
+  errorType: "parse_error" | "validation_error" | "runtime_error";
+}
+
+export type ParseResult =
+  | { workflow: WorkflowDefinition; error: null }
+  | { workflow: null; error: WorkflowLoadError };

package/core/dispatch.ts

@@ -0,0 +1,125 @@
+import { readArtifact, writeArtifact } from "./artifacts";
+import { readIssueState } from "./state";
+import type { PhaseArtifactInput } from "./phase-artifact";
+
+interface DispatchHandoffPayload {
+  inputArtifacts: string[];
+  status: "draft" | "finalized";
+  stopRule: string;
+  targetBranch: string;
+  validation: string[];
+  worktreePath: string;
+  worktreeDecision: "pending" | "created" | "reused" | "existing";
+  workflowType: string;
+  workflowId: string;
+  workerTasks: Array<{ id: string; description: string; status: "pending" | "in_progress" | "done" }>;
+}
+
+function generateTaskId(index: number): string {
+  return `task-${String(index + 1).padStart(3, "0")}`;
+}
+
+function safeReadArtifactPayload(
+  root: string | undefined,
+  issueId: string,
+  type: string,
+): Record<string, unknown> | undefined {
+  try {
+    const artifact = readArtifact({ root, issueId, type });
+    return (artifact.payload ?? {}) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildStopRule(
+  planPayload: Record<string, unknown> | undefined,
+  triagePayload: Record<string, unknown> | undefined,
+): string {
+  const parts: string[] = [];
+
+  const planRisks = planPayload?.risks;
+  if (Array.isArray(planRisks)) {
+    for (const item of planRisks) {
+      if (typeof item === "string" && item.trim()) {
+        parts.push(item.trim());
+      }
+    }
+  }
+
+  const triageNonGoals = triagePayload?.nonGoals;
+  if (Array.isArray(triageNonGoals)) {
+    for (const item of triageNonGoals) {
+      if (typeof item === "string" && item.trim()) {
+        parts.push(item.trim());
+      }
+    }
+  }
+
+  return parts.join("; ");
+}
+
+function buildWorkerTasks(
+  planPayload: Record<string, unknown> | undefined,
+): DispatchHandoffPayload["workerTasks"] {
+  const steps = planPayload?.steps;
+  if (!Array.isArray(steps)) {
+    return [];
+  }
+
+  const tasks: DispatchHandoffPayload["workerTasks"] = [];
+  for (const step of steps) {
+    if (typeof step === "string" && step.trim()) {
+      tasks.push({
+        id: generateTaskId(tasks.length),
+        description: step.trim(),
+        status: "pending",
+      });
+    }
+  }
+  return tasks;
+}
+
+function buildValidation(
+  planPayload: Record<string, unknown> | undefined,
+): string[] {
+  const raw = planPayload?.validation;
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter((item): item is string => typeof item === "string" && item.trim() !== "");
+}
+
+export function initializeDispatch(input: PhaseArtifactInput) {
+  const root = input.root ?? process.cwd();
+  const state = readIssueState({ root, issueId: input.issueId });
+
+  if (state.currentPhase !== "dispatch") {
+    throw new Error(
+      `Dispatch can only be initialized from dispatch phase: current phase is ${state.currentPhase}`,
+    );
+  }
+
+  const planPayload = safeReadArtifactPayload(root, input.issueId, "implementation-plan");
+  const triagePayload = safeReadArtifactPayload(root, input.issueId, "triage-report");
+
+  const payload: DispatchHandoffPayload = {
+    inputArtifacts: ["acceptance-contract", "implementation-plan"],
+    status: "draft",
+    stopRule: buildStopRule(planPayload, triagePayload),
+    targetBranch: "",
+    validation: buildValidation(planPayload),
+    worktreePath: "",
+    worktreeDecision: "pending",
+    workflowType: "issue",
+    workflowId: input.issueId,
+    workerTasks: buildWorkerTasks(planPayload),
+  };
+
+  return writeArtifact({
+    root,
+    issueId: input.issueId,
+    type: "dispatch-handoff",
+    payload,
+  });
+}

package/core/evidence.ts

@@ -0,0 +1,148 @@
+import { dirname, join, resolve, sep } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { getIssuePaths, readIssueState } from "./state";
+
+export const EVIDENCE_KINDS = [
+  "command-logs",
+  "browser-snapshots",
+  "browser-screenshots",
+  "browser-console",
+  "browser-errors",
+  "screenshots",
+  "investigations",
+  "review",
+  "release",
+  "test-runs",
+] as const;
+
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+
+export interface IssueEvidencePath {
+  schemaVersion: 1;
+  issueId: string;
+  kind: EvidenceKind;
+  path: string;
+  absolutePath: string;
+}
+
+export interface IssueEvidenceRecord extends IssueEvidencePath {
+  writtenAt: string;
+  mediaType: string;
+}
+
+interface EvidencePathInput {
+  root?: string;
+  issueId: string;
+  kind: EvidenceKind | string;
+  filename: string;
+}
+
+interface WriteEvidenceInput extends EvidencePathInput {
+  mediaType?: string;
+}
+
+interface WriteJsonEvidenceInput extends WriteEvidenceInput {
+  payload: unknown;
+}
+
+interface WriteTextEvidenceInput extends WriteEvidenceInput {
+  text: string;
+}
+
+interface WriteBytesEvidenceInput extends WriteEvidenceInput {
+  bytes: Uint8Array;
+}
+
+const SAFE_FILENAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const SAFE_EXTENSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+export function evidenceFilename(prefix: string, extension: string, timestamp = new Date()) {
+  assertSafeFilenamePart(prefix, "evidence filename prefix");
+  const normalizedExtension = extension.startsWith(".") ? extension.slice(1) : extension;
+  if (!SAFE_EXTENSION_PATTERN.test(normalizedExtension)) {
+    throw new Error(`Invalid evidence filename extension: ${extension}`);
+  }
+  const stamp = timestamp.toISOString().replace(/[:.]/g, "-");
+  return `${prefix}-${stamp}.${normalizedExtension}`;
+}
+
+export function prepareIssueEvidencePath(input: EvidencePathInput): IssueEvidencePath {
+  const root = input.root ?? process.cwd();
+  const kind = assertValidEvidenceKind(input.kind);
+  assertSafeEvidenceFilename(input.filename);
+
+  const paths = getIssuePaths(root, input.issueId);
+  readIssueState({ root, issueId: input.issueId });
+
+  const relativePath = toPosixPath(join("evidence", kind, input.filename));
+  const absolutePath = join(paths.issueDir, relativePath);
+  assertInsideIssueDir(paths.issueDir, absolutePath);
+  mkdirSync(dirname(absolutePath), { recursive: true });
+
+  return {
+    schemaVersion: 1,
+    issueId: input.issueId,
+    kind,
+    path: relativePath,
+    absolutePath,
+  };
+}
+
+export function writeIssueEvidenceJson(input: WriteJsonEvidenceInput): IssueEvidenceRecord {
+  const path = prepareIssueEvidencePath(input);
+  return writeIssueEvidence(path, `${JSON.stringify(input.payload, null, 2)}\n`, input.mediaType ?? "application/json");
+}
+
+export function writeIssueEvidenceText(input: WriteTextEvidenceInput): IssueEvidenceRecord {
+  const path = prepareIssueEvidencePath(input);
+  return writeIssueEvidence(path, input.text, input.mediaType ?? "text/plain");
+}
+
+export function writeIssueEvidenceBytes(input: WriteBytesEvidenceInput): IssueEvidenceRecord {
+  const path = prepareIssueEvidencePath(input);
+  return writeIssueEvidence(path, input.bytes, input.mediaType ?? "application/octet-stream");
+}
+
+function writeIssueEvidence(
+  path: IssueEvidencePath,
+  content: string | Uint8Array,
+  mediaType: string,
+): IssueEvidenceRecord {
+  writeFileSync(path.absolutePath, content);
+  return {
+    ...path,
+    writtenAt: new Date().toISOString(),
+    mediaType,
+  };
+}
+
+function assertValidEvidenceKind(value: string): EvidenceKind {
+  if (!EVIDENCE_KINDS.includes(value as EvidenceKind)) {
+    throw new Error(`Invalid evidence kind: ${value}`);
+  }
+  return value as EvidenceKind;
+}
+
+function assertSafeEvidenceFilename(filename: string) {
+  if (!SAFE_FILENAME_PATTERN.test(filename)) {
+    throw new Error(`Invalid evidence filename: ${filename}`);
+  }
+}
+
+function assertSafeFilenamePart(value: string, label: string) {
+  if (!SAFE_FILENAME_PATTERN.test(value)) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+}
+
+function assertInsideIssueDir(issueDir: string, absolutePath: string) {
+  const issueRoot = resolve(issueDir);
+  const target = resolve(absolutePath);
+  if (target !== issueRoot && !target.startsWith(`${issueRoot}${sep}`)) {
+    throw new Error(`Evidence path escapes issue directory: ${absolutePath}`);
+  }
+}
+
+function toPosixPath(path: string) {
+  return path.split(sep).join("/");
+}

package/core/gate.ts

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import {
+  CODE_COMMIT_PHASES,
+  PHASE_GATE_RULES,
+  PROTECTED_PATH_PATTERNS,
+} from "./phase-gates";
+import { PHASE_SKIP_MAP, type GxpmPhase, type IssueState } from "./state";
+
+export type GateType = "pre-commit" | "commit-msg" | "pre-push" | "post-merge";
+
+export type GateCode =
+  | "no-state"
+  | "no-issue-id"
+  | "no-protected-paths"
+  | "main-worktree-non-main"
+  | "feature-branch-outside-worktree-root"
+  | "wrong-phase"
+  | "missing-artifact"
+  | "missing-issue-ref"
+  | "phase-ok"
+  | "land-pending"
+  | "already-landed"
+  | "disabled"
+  | "contamination-detected"
+  | "missing-changed-files";
+
+export interface GateVerdict {
+  allowed: boolean;
+  code: GateCode;
+  reason: string;
+  details?: Record<string, unknown>;
+}
+
+export interface PostMergeOutcome {
+  transitionTo: GxpmPhase | null;
+  reason: string;
+}
+
+export type Env = Record<string, string | undefined>;
+
+export type HasArtifactFn = (issueId: string, artifactType: string) => boolean;
+
+export interface BranchPolicyInput {
+  currentRoot: string;
+  currentBranch?: string;
+  canonicalMainRoot: string;
+  allowedWorktreeRoot?: string;
+  baseBranch?: string;
+  env: Env;
+}
+
+const ISSUE_REF_PATTERN = /\b(GXG|GXPM)-\d+\b/i;
+
+function isDisabled(env: Env): boolean {
+  return env.GXPM_GATE_DISABLE === "1";
+}
+
+function isProtected(path: string): boolean {
+  return PROTECTED_PATH_PATTERNS.some((re) => re.test(path));
+}
+
+function normalizePath(path: string): string {
+  const resolved = resolve(path).replace(/\/+$/, "");
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function isInsidePath(root: string, candidate: string): boolean {
+  const normalizedRoot = normalizePath(root);
+  const normalizedCandidate = normalizePath(candidate);
+  const rel = relative(normalizedRoot, normalizedCandidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function evaluateBranchPolicy(input: BranchPolicyInput): GateVerdict {
+  if (isDisabled(input.env)) {
+    return { allowed: true, code: "disabled", reason: "GXPM_GATE_DISABLE=1" };
+  }
+
+  const currentRoot = normalizePath(input.currentRoot);
+  const canonicalMainRoot = normalizePath(input.canonicalMainRoot);
+  const currentBranch = input.currentBranch ?? "HEAD";
+  const baseBranch = input.baseBranch ?? "main";
+
+  if (currentBranch === baseBranch) {
+    return { allowed: true, code: "phase-ok", reason: `current branch is ${baseBranch}` };
+  }
+
+  if (currentRoot === canonicalMainRoot) {
+    return {
+      allowed: false,
+      code: "main-worktree-non-main",
+      reason: `canonical main checkout must stay on ${baseBranch}; currentBranch=${currentBranch}`,
+      details: { currentRoot, canonicalMainRoot, currentBranch, baseBranch },
+    };
+  }
+
+  if (input.allowedWorktreeRoot && !isInsidePath(input.allowedWorktreeRoot, currentRoot)) {
+    return {
+      allowed: false,
+      code: "feature-branch-outside-worktree-root",
+      reason: `feature branches must run under worktree root: ${normalizePath(input.allowedWorktreeRoot)}`,
+      details: {
+        currentRoot,
+        canonicalMainRoot,
+        currentBranch,
+        allowedWorktreeRoot: normalizePath(input.allowedWorktreeRoot),
+      },
+    };
+  }
+
+  return {
+    allowed: true,
+    code: "phase-ok",
+    reason: `currentBranch=${currentBranch} is outside canonical main checkout`,
+    details: { currentRoot, canonicalMainRoot, currentBranch },
+  };
+}
+
+export function evaluatePreCommit(
+  state: IssueState,
+  stagedFiles: string[],
+  env: Env,
+): GateVerdict {
+  if (isDisabled(env)) {
+    return { allowed: true, code: "disabled", reason: "GXPM_GATE_DISABLE=1" };
+  }
+
+  const protectedHits = stagedFiles.filter(isProtected);
+  if (protectedHits.length === 0) {
+    return {
+      allowed: true,
+      code: "no-protected-paths",
+      reason: "no staged files in protected paths",
+    };
+  }
+
+  if (CODE_COMMIT_PHASES.has(state.currentPhase)) {
+    return {
+      allowed: true,
+      code: "phase-ok",
+      reason: `currentPhase=${state.currentPhase} permits code edits`,
+    };
+  }
+
+  return {
+    allowed: false,
+    code: "wrong-phase",
+    reason: `currentPhase=${state.currentPhase} forbids commits to protected paths`,
+    details: { protectedHits, currentPhase: state.currentPhase },
+  };
+}
+
+export function evaluateCommitMsg(
+  message: string,
+  _state: IssueState,
+  env: Env,
+): GateVerdict {
+  if (isDisabled(env)) {
+    return { allowed: true, code: "disabled", reason: "GXPM_GATE_DISABLE=1" };
+  }
+
+  if (!ISSUE_REF_PATTERN.test(message)) {
+    return {
+      allowed: false,
+      code: "missing-issue-ref",
+      reason: "commit message must reference GXG-NNN or GXPM-NNN",
+    };
+  }
+
+  return { allowed: true, code: "phase-ok", reason: "issue ref present" };
+}
+
+export function evaluatePrePush(
+  state: IssueState,
+  hasArtifactFn: HasArtifactFn,
+  env: Env,
+  root?: string,
+): GateVerdict {
+  if (isDisabled(env)) {
+    return { allowed: true, code: "disabled", reason: "GXPM_GATE_DISABLE=1" };
+  }
+
+  const rule = PHASE_GATE_RULES.find((r) => r.fromPhase === state.currentPhase);
+  if (!rule) {
+    return {
+      allowed: true,
+      code: "phase-ok",
+      reason: `phase=${state.currentPhase} has no outbound artifact gate`,
+    };
+  }
+
+  // Under compressed rigor levels, skip artifact gates for phases that are
+  // collapsed (e.g. standard mode skips local-verify / ac-check / cleanup gates).
+  const skipSet = state.rigorLevel ? PHASE_SKIP_MAP[state.rigorLevel] : new Set<GxpmPhase>();
+  if (skipSet.has(rule.nextPhase)) {
+    return {
+      allowed: true,
+      code: "phase-ok",
+      reason: `phase=${state.currentPhase} outbound gate skipped under rigor=${state.rigorLevel}`,
+    };
+  }
+
+  if (!hasArtifactFn(state.issueId, rule.requiredArtifact)) {
+    return {
+      allowed: false,
+      code: "missing-artifact",
+      reason: `pre-push: ${rule.requiredArtifact} required for next transition`,
+      details: { requiredArtifact: rule.requiredArtifact, command: rule.command },
+    };
+  }
+
+  if (root) {
+    const artifactDir = resolve(root, ".gxpm", "issues", state.issueId, "artifacts");
+
+    // Check for .contaminated files
+    if (existsSync(artifactDir)) {
+      const contaminated = readdirSync(artifactDir).filter((f) => f.startsWith(".contaminated"));
+      if (contaminated.length > 0) {
+        return {
+          allowed: false,
+          code: "contamination-detected",
+          reason: `pre-push: contamination detected (${contaminated.join(", ")}). Run gxpm phase rewind ${state.issueId} --to implement --reason "contamination" and re-verify.`,
+          details: { contaminatedFiles: contaminated },
+        };
+      }
+    }
+
+    // Check local-verify changedFiles is non-empty
+    if (rule.requiredArtifact === "local-verify") {
+      try {
+        const artifactPath = resolve(artifactDir, "local-verify.json");
+        const raw = JSON.parse(readFileSync(artifactPath, "utf8"));
+        const payload = raw.payload ?? raw;
+        const changedFiles = payload.changedFiles ?? [];
+        if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+          return {
+            allowed: false,
+            code: "missing-changed-files",
+            reason: `pre-push: local-verify changedFiles is empty. Record what was changed before transitioning.`,
+            details: { command: `gxpm artifact edit ${state.issueId} local-verify` },
+          };
+        }
+      } catch {
+        // ignore malformed artifact — missing-artifact check already passed,
+        // so this is an edge case we let through to avoid false blocks
+      }
+    }
+  }
+
+  return { allowed: true, code: "phase-ok", reason: "required artifact present" };
+}
+
+export function evaluatePostMerge(state: IssueState): PostMergeOutcome {
+  if (state.currentPhase === "qa") {
+    return { transitionTo: "land", reason: "merged from qa → auto-transition to land" };
+  }
+  if (state.currentPhase === "land") {
+    return { transitionTo: null, reason: "already landed" };
+  }
+  return {
+    transitionTo: null,
+    reason: `phase=${state.currentPhase} is not a merge-trigger phase`,
+  };
+}