@geminix/gxpm 0.1.0

package/core/orchestrator.ts

@@ -0,0 +1,54 @@
+import { listIssues } from "./issues";
+import { classifyIssueReadiness } from "./issue-readiness";
+import { type GxpmPhase, type IssueType } from "./state";
+
+export type DryRunDecision = "dispatchable" | "blocked" | "ignored";
+
+export interface OrchestratorDryRunIssue {
+  issueId: string;
+  issueType: IssueType;
+  currentPhase: GxpmPhase;
+  decision: DryRunDecision;
+  reason: string;
+}
+
+export interface OrchestratorDryRunReport {
+  schemaVersion: 1;
+  generatedAt: string;
+  issues: OrchestratorDryRunIssue[];
+  summary: {
+    dispatchable: number;
+    blocked: number;
+    ignored: number;
+  };
+}
+
+export function dryRunOrchestratorTick(input: { root?: string; includeAll?: boolean } = {}): OrchestratorDryRunReport {
+  const root = input.root ?? process.cwd();
+  const entries = listIssues({ root, includeAll: true });
+  const issues = entries
+    .map((entry) => classifyIssue(root, entry.issueId))
+    .filter((issue) => input.includeAll || issue.decision !== "ignored");
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    issues,
+    summary: {
+      dispatchable: issues.filter((issue) => issue.decision === "dispatchable").length,
+      blocked: issues.filter((issue) => issue.decision === "blocked").length,
+      ignored: issues.filter((issue) => issue.decision === "ignored").length,
+    },
+  };
+}
+
+function classifyIssue(root: string, issueId: string): OrchestratorDryRunIssue {
+  const readiness = classifyIssueReadiness({ root, issueId });
+  return {
+    issueId: readiness.issueId,
+    issueType: readiness.issueType,
+    currentPhase: readiness.currentPhase,
+    decision: readiness.decision === "ready" ? "dispatchable" : readiness.decision,
+    reason: readiness.reason,
+  };
+}

package/core/phase-artifact.ts

@@ -0,0 +1,32 @@
+import { type ArtifactType, writeArtifact } from "./artifacts";
+import { readIssueState, type GxpmPhase } from "./state";
+
+export interface PhaseArtifactInput {
+  root?: string;
+  issueId: string;
+}
+
+interface PhaseArtifactInitializerConfig {
+  artifactType: ArtifactType;
+  label: string;
+  payload: unknown;
+  requiredPhase: GxpmPhase;
+}
+
+export function createPhaseArtifactInitializer(config: PhaseArtifactInitializerConfig) {
+  return function initializePhaseArtifact(input: PhaseArtifactInput) {
+    const state = readIssueState({ root: input.root, issueId: input.issueId });
+    if (state.currentPhase !== config.requiredPhase) {
+      throw new Error(
+        `${config.label} can only be initialized from ${config.requiredPhase} phase: current phase is ${state.currentPhase}`,
+      );
+    }
+
+    return writeArtifact({
+      root: input.root,
+      issueId: input.issueId,
+      type: config.artifactType,
+      payload: config.payload,
+    });
+  };
+}

package/core/phase-gates.ts

@@ -0,0 +1,130 @@
+import { type ArtifactType } from "./artifacts";
+import { type GxpmPhase } from "./state";
+
+export const CODE_COMMIT_PHASES: ReadonlySet<GxpmPhase> = new Set([
+  "dispatch",
+  "implement",
+  "local-verify",
+  "ac-check",
+  "self-review",
+  "cleanup",
+  "ship",
+  "pr-check",
+  "verify",
+]);
+
+export const PROTECTED_PATH_PATTERNS: readonly RegExp[] = [
+  /^apps\//,
+  /^server\//,
+  /^packages\//,
+  /^scripts\//,
+  /^tests\//,
+  /^supabase\//,
+  /^e2e\//,
+];
+
+export interface PhaseGateRule {
+  command: string;
+  fromPhase: GxpmPhase;
+  nextPhase: GxpmPhase;
+  requiredArtifact: ArtifactType;
+}
+
+export const PHASE_GATE_RULES: PhaseGateRule[] = [
+  {
+    command: "gxpm triage init <issue-id>",
+    fromPhase: "triage",
+    nextPhase: "plan",
+    requiredArtifact: "acceptance-contract",
+  },
+  {
+    command: "gxpm plan init <issue-id>",
+    fromPhase: "plan",
+    nextPhase: "dispatch",
+    requiredArtifact: "implementation-plan",
+  },
+  {
+    command: "gxpm dispatch init <issue-id>",
+    fromPhase: "dispatch",
+    nextPhase: "specify",
+    requiredArtifact: "dispatch-handoff",
+  },
+  {
+    command: "gxpm specify init <issue-id>",
+    fromPhase: "specify",
+    nextPhase: "implement",
+    requiredArtifact: "behavior-spec",
+  },
+  {
+    command: "gxpm implement verify <issue-id>",
+    fromPhase: "implement",
+    nextPhase: "local-verify",
+    requiredArtifact: "local-verify",
+  },
+  {
+    command: "gxpm local-verify ac-check <issue-id>",
+    fromPhase: "local-verify",
+    nextPhase: "ac-check",
+    requiredArtifact: "acceptance-check",
+  },
+  {
+    command: "gxpm ac-check self-review <issue-id>",
+    fromPhase: "ac-check",
+    nextPhase: "self-review",
+    requiredArtifact: "self-review",
+  },
+  {
+    command: "gxpm self-review cleanup <issue-id>",
+    fromPhase: "self-review",
+    nextPhase: "cleanup",
+    requiredArtifact: "cleanup-report",
+  },
+  {
+    command: "gxpm cleanup ship <issue-id>",
+    fromPhase: "cleanup",
+    nextPhase: "ship",
+    requiredArtifact: "ship-readiness",
+  },
+  {
+    command: "gxpm ship pr-check <issue-id>",
+    fromPhase: "ship",
+    nextPhase: "pr-check",
+    requiredArtifact: "pr-check",
+  },
+  {
+    command: "gxpm pr-check verify <issue-id>",
+    fromPhase: "pr-check",
+    nextPhase: "verify",
+    requiredArtifact: "verify-findings",
+  },
+  {
+    command: "gxpm verify qa <issue-id>",
+    fromPhase: "verify",
+    nextPhase: "qa",
+    requiredArtifact: "qa-findings",
+  },
+  {
+    command: "gxpm qa land <issue-id>",
+    fromPhase: "qa",
+    nextPhase: "land",
+    requiredArtifact: "land-findings",
+  },
+];
+
+export const GATE_ARTIFACT_TYPES = PHASE_GATE_RULES.map((rule) => rule.requiredArtifact);
+
+export function isGateArtifact(artifactType: string): artifactType is ArtifactType {
+  return GATE_ARTIFACT_TYPES.includes(artifactType as ArtifactType);
+}
+
+export function getRequiredArtifactForTransition(fromPhase: GxpmPhase, nextPhase: GxpmPhase) {
+  return (
+    PHASE_GATE_RULES.find((rule) => rule.fromPhase === fromPhase && rule.nextPhase === nextPhase)
+      ?.requiredArtifact ?? null
+  );
+}
+
+export function getGateCommand(issueId: string, artifactType: string) {
+  const rule = PHASE_GATE_RULES.find((item) => item.requiredArtifact === artifactType);
+  return (rule?.command ?? "gxpm triage init <issue-id>").replace("<issue-id>", issueId);
+}

package/core/phase-rewind.ts

@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import {
+  appendIssueEvent,
+  assertValidPhase,
+  getIssuePaths,
+  readIssueState,
+  type GxpmPhase,
+} from "./state";
+import { resolveSessionId } from "./session";
+
+export interface RewindInput {
+  root?: string;
+  issueId: string;
+  toPhase: GxpmPhase | string;
+  reason: string;
+}
+
+export interface RewindResult {
+  fromPhase: GxpmPhase;
+  toPhase: GxpmPhase;
+  timestamp: string;
+}
+
+export function rewindPhase(input: RewindInput): RewindResult {
+  const toPhase = assertValidPhase(input.toPhase);
+  if (!input.reason || !input.reason.trim()) {
+    throw new Error("phase rewind requires --reason; explain why the rewind is needed");
+  }
+
+  const root = input.root ?? process.cwd();
+  const paths = getIssuePaths(root, input.issueId);
+  const state = readIssueState({ root, issueId: input.issueId });
+
+  if (state.currentPhase === toPhase) {
+    throw new Error(`Issue ${input.issueId} is already in phase ${toPhase}; nothing to rewind`);
+  }
+
+  const everEntered = state.phaseHistory?.some((h) => h.phase === toPhase);
+  if (!everEntered) {
+    throw new Error(
+      `Cannot rewind ${input.issueId} to ${toPhase}: phaseHistory does not contain that phase. ` +
+        `Only previously-entered phases may be rewound to.`,
+    );
+  }
+
+  const now = new Date().toISOString();
+  const fromPhase = state.currentPhase;
+
+  const updated = {
+    ...state,
+    currentPhase: toPhase,
+    updatedAt: now,
+    phaseHistory: [
+      ...state.phaseHistory,
+      { phase: toPhase, enteredAt: now, fromPhase },
+    ],
+  };
+  writeFileSync(paths.statePath, `${JSON.stringify(updated, null, 2)}\n`);
+
+  const graph = JSON.parse(readFileSync(paths.graphPath, "utf8"));
+  writeFileSync(
+    paths.graphPath,
+    `${JSON.stringify(
+      {
+        ...graph,
+        currentPhase: toPhase,
+        transitions: [
+          ...(Array.isArray(graph.transitions) ? graph.transitions : []),
+          { fromPhase, toPhase, timestamp: now, rewound: true },
+        ],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  appendIssueEvent({
+    issueDir: paths.issueDir,
+    event: {
+      schemaVersion: 1,
+      type: "phase.rewound",
+      issueId: input.issueId,
+      timestamp: now,
+      sessionId: resolveSessionId(),
+      payload: {
+        fromPhase,
+        toPhase,
+        reason: input.reason.trim(),
+      },
+    },
+  });
+
+  return { fromPhase, toPhase, timestamp: now };
+}

package/core/plan-lint.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PHASE_KEYWORDS = [
+  "triage",
+  "plan",
+  "dispatch",
+  "implement",
+  "local-verify",
+  "ac-check",
+  "self-review",
+  "ship",
+  "pr-check",
+  "verify",
+  "qa",
+  "land",
+];
+const TRANSITION_KEYWORDS = ["transition", "推进到", "next phase", "phase"];
+
+export interface PlanLintItem {
+  text: string;
+  matchedKeywords: string[];
+}
+
+export interface PlanLintFindings {
+  hasFindings: boolean;
+  items: PlanLintItem[];
+}
+
+export function lintCodexPlans(root: string, issueId: string): PlanLintFindings {
+  const path = join(root, ".gxpm", "issues", issueId, "codex-plans.jsonl");
+  if (!existsSync(path)) {
+    return { hasFindings: false, items: [] };
+  }
+
+  const items = readFileSync(path, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .flatMap((line) => extractPlanSteps(JSON.parse(line)));
+
+  const findings = items.flatMap((text) => {
+    const matched = [
+      ...PHASE_KEYWORDS.filter((keyword) => text.includes(keyword)),
+      ...TRANSITION_KEYWORDS.filter((keyword) => text.includes(keyword)),
+    ];
+    const hasPhase = PHASE_KEYWORDS.some((keyword) => text.includes(keyword));
+    const hasTransition = TRANSITION_KEYWORDS.some((keyword) => text.includes(keyword));
+    return hasPhase && hasTransition ? [{ text, matchedKeywords: matched }] : [];
+  });
+
+  return { hasFindings: findings.length > 0, items: findings };
+}
+
+function extractPlanSteps(entry: any): string[] {
+  const steps = entry?.arguments?.steps;
+  if (!Array.isArray(steps)) return [];
+  return steps
+    .map((step) => step?.description)
+    .filter((value): value is string => typeof value === "string");
+}

package/core/plan.ts

@@ -0,0 +1,77 @@
+import { writeArtifact } from "./artifacts";
+import { readIssueState } from "./state";
+
+interface PlanInput {
+  root?: string;
+  issueId: string;
+}
+
+export function initializePlan(input: PlanInput) {
+  const state = readIssueState({ root: input.root, issueId: input.issueId });
+  if (state.currentPhase !== "plan") {
+    throw new Error(
+      `Plan can only be initialized from plan phase: current phase is ${state.currentPhase}`,
+    );
+  }
+
+  const rigor = state.rigorLevel ?? "standard";
+
+  const constitutionCheck = {
+    capabilityDeclared: false,
+    testStrategyDefined: false,
+    simplicityJustified: false,
+    integrationPathClear: false,
+    status: "pending",
+  };
+
+  const litePayload = {
+    objective: "",
+    scope: "",
+    nonGoals: "",
+    constitutionCheck,
+    steps: [],
+    status: "draft",
+  };
+
+  const standardPayload = {
+    objective: "",
+    scope: "",
+    nonGoals: "",
+    approach: "",
+    constitutionCheck,
+    steps: [],
+    risks: [],
+    validation: [],
+    rollback: "",
+    status: "draft",
+  };
+
+  const fullPayload = {
+    objective: "",
+    scope: "",
+    nonGoals: "",
+    approach: "",
+    chosenApproach: "",
+    whyThisApproach: "",
+    implementationSlices: [],
+    dataModel: "",
+    alternativesConsidered: [],
+    alternativesRejected: [],
+    constitutionCheck,
+    steps: [],
+    risks: [],
+    validation: [],
+    rollback: "",
+    migrationPlan: "",
+    status: "draft",
+  };
+
+  const payload = rigor === "lite" ? litePayload : rigor === "full" ? fullPayload : standardPayload;
+
+  return writeArtifact({
+    root: input.root,
+    issueId: input.issueId,
+    type: "implementation-plan",
+    payload,
+  });
+}

package/core/port-allocation.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { getResolvedConfigValue } from "./config";
+
+/**
+ * Calculate a deterministic port offset from a path string.
+ * Uses MD5 hash to produce an offset in range 100-999.
+ * Same path always yields same offset.
+ */
+export function calculatePortOffset(path: string): number {
+  const hash = createHash("md5").update(path).digest();
+  return (hash.readUInt16BE(0) % 900) + 100;
+}
+
+export interface ResolveDevPortInput {
+  /** Workspace path used as hash seed. */
+  workspacePath: string;
+  /** Optional explicit base port (defaults to config or 3090). */
+  basePort?: number;
+  /** Optional root for config resolution. */
+  root?: string;
+}
+
+/**
+ * Resolve the dev server port for a workspace.
+ *
+ * Precedence:
+ * 1. GXPM_DEV_PORT env var (validated; exits on invalid)
+ * 2. PORT env var (validated; exits on invalid)
+ * 3. basePort + calculatePortOffset(workspacePath)
+ *
+ * @returns The resolved port number
+ */
+export function resolveDevPort(input: ResolveDevPortInput): number {
+  const envPort = process.env.GXPM_DEV_PORT ?? process.env.PORT;
+
+  if (envPort) {
+    const parsed = Number(envPort);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new Error(`Invalid port env var: ${envPort} (must be 1-65535)`);
+    }
+    return parsed;
+  }
+
+  const basePort =
+    input.basePort ??
+    Number(getResolvedConfigValue({ root: input.root, key: "workspace.basePort" }).value);
+
+  const offset = calculatePortOffset(input.workspacePath);
+  return basePort + offset;
+}

package/core/pr-check.ts

@@ -0,0 +1,15 @@
+import { createPhaseArtifactInitializer } from "./phase-artifact";
+
+export const initializePrCheck = createPhaseArtifactInitializer({
+  artifactType: "pr-check",
+  label: "PR check",
+  payload: {
+    pullRequest: "",
+    reviewFindings: [],
+    risks: [],
+    shipReadinessArtifact: "ship-readiness",
+    status: "draft",
+    summary: "",
+  },
+  requiredPhase: "ship",
+});