@geminix/gxpm 0.1.0

package/core/self-review.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeArtifact } from "./artifacts";
+import { lintCodexPlans } from "./plan-lint";
+import { readIssueState } from "./state";
+import { AgentRegistry } from "./agent-runtime";
+
+export function initializeSelfReview(input: { root?: string; issueId: string; army?: boolean }) {
+  const root = input.root ?? process.cwd();
+  const state = readIssueState({ root, issueId: input.issueId });
+  if (state.currentPhase !== "ac-check") {
+    throw new Error(`Self review can only be initialized from ac-check phase: current phase is ${state.currentPhase}`);
+  }
+
+  const result = writeArtifact({
+    root,
+    issueId: input.issueId,
+    type: "self-review",
+    payload: {
+      findings: [],
+      reviewedArtifacts: ["acceptance-check", "local-verify"],
+      risks: [],
+      status: "draft",
+      summary: "",
+      plan_lint_findings: lintCodexPlans(root, input.issueId),
+    },
+  });
+
+  // When army mode is enabled, also initialize the review-report artifact
+  if (input.army) {
+    const registry = new AgentRegistry();
+    // Discover from the project root (where agents/ directory lives)
+    // Fallback to process.cwd() if root doesn't contain agents/
+    const discoverRoot = existsSync(join(root, "agents")) ? root : process.cwd();
+    registry.discover(discoverRoot);
+    const agents = registry.listByArmy("review-army");
+
+    if (agents.length === 0) {
+      console.warn("warning: --army flag set but no review-army agents found");
+    } else {
+      // Write an initial review-report with empty findings
+      // The actual execution happens via the host's subagent mechanism
+      writeArtifact({
+        root,
+        issueId: input.issueId,
+        type: "review-report",
+        payload: {
+          army: "review-army",
+          phase: "self-review",
+          issueId: input.issueId,
+          generatedAt: new Date().toISOString(),
+          findings: [],
+          summary: `${agents.length} review role(s) queued for execution: ${agents.map((a) => a.name).join(", ")}`,
+          status: "draft",
+          agents: agents.map((a) => ({ name: a.name, role: a.role, description: a.description })),
+        },
+      });
+    }
+  }
+
+  return result;
+}

package/core/session.ts

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getConfigValue } from "./config";
+
+let volatileSessionId: string | null = null;
+
+export function resolveSessionId(env: NodeJS.ProcessEnv = process.env): string {
+  const codexSessionId = env.CODEX_COMPANION_SESSION_ID?.trim();
+  if (codexSessionId) {
+    return `codex:${codexSessionId}`;
+  }
+
+  const cmuxSurfaceId = env.CMUX_SURFACE_ID?.trim();
+  if (cmuxSurfaceId) {
+    return `cmux:${cmuxSurfaceId}`;
+  }
+
+  return `gen:${readOrCreateGeneratedSessionId(env)}`;
+}
+
+export interface AgentIdentity {
+  host: string;
+  sessionId: string;
+  actor: string;
+}
+
+export function resolveAgentIdentity(
+  env: NodeJS.ProcessEnv = process.env,
+  root?: string,
+): AgentIdentity {
+  const sessionId = resolveSessionId(env);
+  const host = sessionId.split(":")[0] ?? "gen";
+  const envName = env.GXPM_AGENT_NAME?.trim() ?? "";
+  const configName = root ? String(getConfigValue({ root, key: "agent.name" }).value ?? "").trim() : "";
+  const actor = envName || configName || host;
+  return { host, sessionId, actor };
+}
+
+function readOrCreateGeneratedSessionId(env: NodeJS.ProcessEnv): string {
+  for (const cachePath of candidateCachePaths(env)) {
+    try {
+      if (existsSync(cachePath)) {
+        const cached = readFileSync(cachePath, "utf8").trim();
+        if (cached) {
+          return cached;
+        }
+      }
+
+      const generated = randomUUID();
+      mkdirSync(join(cachePath, ".."), { recursive: true });
+      writeFileSync(cachePath, `${generated}\n`);
+      return generated;
+    } catch {}
+  }
+
+  volatileSessionId ??= randomUUID();
+  return volatileSessionId;
+}
+
+function candidateCachePaths(env: NodeJS.ProcessEnv): string[] {
+  const paths = new Set<string>();
+  const home = env.HOME?.trim() || homedir();
+  if (home) {
+    paths.add(join(home, ".gxpm", "session-id"));
+  }
+  paths.add(join(tmpdir(), "gxpm", "session-id"));
+  return [...paths];
+}

package/core/ship.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeArtifact } from "./artifacts";
+import { readIssueState } from "./state";
+import { AgentRegistry } from "./agent-runtime";
+
+export function initializeShipReadiness(input: { root?: string; issueId: string; army?: boolean }) {
+  const root = input.root ?? process.cwd();
+  const state = readIssueState({ root, issueId: input.issueId });
+  if (state.currentPhase !== "cleanup" && state.currentPhase !== "self-review") {
+    throw new Error(`Ship readiness can only be initialized from cleanup or self-review phase: current phase is ${state.currentPhase}`);
+  }
+
+  const result = writeArtifact({
+    root,
+    issueId: input.issueId,
+    type: "ship-readiness",
+    payload: {
+      checklist: [],
+      compatibilityMigration: {
+        backwardCompatible: true,
+        configChanges: false,
+        migrationSteps: "",
+      },
+      blastRadius: {
+        affectedSubsystems: [],
+        guardrails: "",
+        unintendedEffects: "",
+      },
+      humanVerification: {
+        edgeCases: "",
+        notVerified: "",
+        verifiedScenarios: "",
+      },
+      releaseNotes: "",
+      reviewedArtifacts: ["self-review", "acceptance-check"],
+      risks: [],
+      risksAndMitigations: [],
+      rollbackPlan: {
+        failureSymptoms: "",
+        featureFlags: "",
+        rollbackCommand: "",
+      },
+      securityImpact: {
+        fileSystemAccessChanged: false,
+        networkCallsChanged: false,
+        newPermissionsOrCapabilities: false,
+        riskAndMitigation: "",
+        secretsHandlingChanged: false,
+      },
+      status: "draft",
+      summary: "",
+      targetBranch: "",
+    },
+  });
+
+  // When army mode is enabled, also initialize the ship-audit-report artifact
+  if (input.army) {
+    const registry = new AgentRegistry();
+    const discoverRoot = existsSync(join(root, "agents")) ? root : process.cwd();
+    registry.discover(discoverRoot);
+    const agents = registry.listByArmy("ship-audit-army");
+
+    if (agents.length === 0) {
+      console.warn("warning: --army flag set but no ship-audit-army agents found");
+    } else {
+      writeArtifact({
+        root,
+        issueId: input.issueId,
+        type: "ship-audit-report",
+        payload: {
+          army: "ship-audit-army",
+          phase: "ship",
+          issueId: input.issueId,
+          generatedAt: new Date().toISOString(),
+          findings: [],
+          summary: `${agents.length} audit role(s) queued for execution: ${agents.map((a) => a.name).join(", ")}`,
+          status: "draft",
+          agents: agents.map((a) => ({ name: a.name, role: a.role, description: a.description })),
+        },
+      });
+    }
+  }
+
+  return result;
+}

package/core/specify.ts

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { writeArtifact } from "./artifacts";
+import { readIssueState } from "./state";
+import { resolveAgentIdentity } from "./session";
+import { BehaviorSpecSchema, type BehaviorSpec } from "./contracts/behavior-spec.schema";
+
+interface SpecifyInput {
+  root?: string;
+  issueId: string;
+}
+
+export function initializeSpecify(input: SpecifyInput) {
+  const state = readIssueState({ root: input.root, issueId: input.issueId });
+  if (state.currentPhase !== "specify") {
+    throw new Error(
+      `Specify can only be initialized from specify phase: current phase is ${state.currentPhase}`,
+    );
+  }
+
+  const now = new Date().toISOString();
+  const identity = resolveAgentIdentity();
+
+  const payload = {
+    $schema: "behavior-spec.v1",
+    issueId: input.issueId,
+    createdAt: now,
+    createdBy: identity.actor,
+    confirmedAt: null,
+    confirmedBy: null,
+    feature: {
+      title: "<placeholder>",
+      asA: "<placeholder>",
+      iWant: "<placeholder>",
+      soThat: "<placeholder>",
+    },
+    scenarios: [
+      {
+        id: "scn-01",
+        name: "<placeholder>",
+        given: ["<placeholder>"],
+        when: "<placeholder>",
+        then: ["<placeholder>"],
+        examples: [],
+        stubPath: "<placeholder>",
+      },
+    ],
+    guidelinesRef: "docs/governance/gherkin-style.md@v1",
+  };
+
+  return writeArtifact({
+    root: input.root,
+    issueId: input.issueId,
+    type: "behavior-spec",
+    payload,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface ConfirmInput {
+  root?: string;
+  issueId: string;
+  confirmedBy?: string;
+}
+
+function gitUserEmail(): string {
+  try {
+    return execSync("git config user.email", { encoding: "utf8" }).trim();
+  } catch {
+    return "unknown@local";
+  }
+}
+
+function specArtifactPath(root: string, issueId: string): string {
+  return join(root, ".gxpm", "issues", issueId, "artifacts", "behavior-spec.json");
+}
+
+function readStoredSpec(root: string, issueId: string): { stored: { payload: BehaviorSpec; [key: string]: unknown } } {
+  const path = specArtifactPath(root, issueId);
+  if (!existsSync(path)) {
+    throw new Error(
+      `behavior-spec.json not found for ${issueId}; run \`gxpm specify init ${issueId}\` first`,
+    );
+  }
+  const stored = JSON.parse(readFileSync(path, "utf8"));
+  BehaviorSpecSchema.parse(stored.payload);
+  return { stored };
+}
+
+const PLACEHOLDER_SENTINEL = "<placeholder>";
+
+function findRemainingPlaceholders(spec: BehaviorSpec): string[] {
+  const violations: string[] = [];
+  const f = spec.feature;
+  for (const [key, val] of Object.entries(f)) {
+    if (val === PLACEHOLDER_SENTINEL) violations.push(`feature.${key}`);
+  }
+  spec.scenarios.forEach((scn, idx) => {
+    const tag = `scenarios[${idx}]`;
+    if (scn.name === PLACEHOLDER_SENTINEL) violations.push(`${tag}.name`);
+    if (scn.when === PLACEHOLDER_SENTINEL) violations.push(`${tag}.when`);
+    if (scn.stubPath === PLACEHOLDER_SENTINEL) violations.push(`${tag}.stubPath`);
+    scn.given.forEach((g, i) => {
+      if (g === PLACEHOLDER_SENTINEL) violations.push(`${tag}.given[${i}]`);
+    });
+    scn.then.forEach((t, i) => {
+      if (t === PLACEHOLDER_SENTINEL) violations.push(`${tag}.then[${i}]`);
+    });
+  });
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+export function confirmSpecify(input: ConfirmInput) {
+  const root = input.root ?? process.cwd();
+  const { stored } = readStoredSpec(root, input.issueId);
+  const spec = stored.payload;
+
+  const placeholders = findRemainingPlaceholders(spec);
+  if (placeholders.length > 0) {
+    throw new Error(
+      `Cannot confirm: <placeholder> sentinels remain in: ${placeholders.join(", ")}`,
+    );
+  }
+
+  for (const scn of spec.scenarios) {
+    const file = scn.stubPath.split(":")[0];
+    const abs = join(root, file);
+    if (!existsSync(abs)) {
+      throw new Error(`Stub file missing: ${file} (scenario ${scn.id})`);
+    }
+  }
+
+  const now = new Date().toISOString();
+  const confirmedBy = input.confirmedBy ?? gitUserEmail();
+  stored.payload.confirmedAt = now;
+  stored.payload.confirmedBy = confirmedBy;
+  writeFileSync(
+    specArtifactPath(root, input.issueId),
+    `${JSON.stringify(stored, null, 2)}\n`,
+  );
+}
+
+export function reviseSpecify(input: { root?: string; issueId: string }) {
+  const root = input.root ?? process.cwd();
+  // Revise must be schema-tolerant: its purpose is to restore a confirmable state.
+  // We deliberately skip BehaviorSpecSchema.parse() so a spec that was edited into
+  // an inconsistent shape (e.g. confirmedAt set but confirmedBy null, or partial
+  // field types) can still be reset to draft. The next confirmSpecify call will
+  // re-validate against the full schema.
+  const path = specArtifactPath(root, input.issueId);
+  if (!existsSync(path)) {
+    throw new Error(
+      `behavior-spec.json not found for ${input.issueId}; run \`gxpm specify init ${input.issueId}\` first`,
+    );
+  }
+  const stored = JSON.parse(readFileSync(path, "utf8"));
+  if (!stored?.payload || typeof stored.payload !== "object") {
+    throw new Error(
+      `behavior-spec.json is malformed (missing payload) for ${input.issueId}; cannot revise`,
+    );
+  }
+  stored.payload.confirmedAt = null;
+  stored.payload.confirmedBy = null;
+  writeFileSync(path, `${JSON.stringify(stored, null, 2)}\n`);
+}