p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/linear/handoff-comment.ts

@@ -0,0 +1,19 @@
+import { hasHandoffCompletionMarker } from "./comments.js";
+import type { LinearCommentRecord } from "./writer.js";
+
+export function findLatestHandoffComment(
+  comments: LinearCommentRecord[],
+  orchestratorMarker: string,
+): LinearCommentRecord | null {
+  const handoffComments = comments.filter((comment) =>
+    hasHandoffCompletionMarker(comment.body, orchestratorMarker),
+  );
+
+  handoffComments.sort((a, b) => {
+    const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+    const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+    return bTime - aTime;
+  });
+
+  return handoffComments[0] ?? null;
+}

package/workspace-snapshot/files/src/linear/issue-query.ts

@@ -0,0 +1,70 @@
+import { LinearClient } from "@linear/sdk";
+import type { LinearIssueSnapshot } from "./client.js";
+
+export interface LinearIssueListItem {
+  id: string;
+  identifier: string;
+  title: string;
+  status: string | null;
+  projectName: string | null;
+  teamId: string | null;
+  url: string | null;
+}
+
+export async function listIssuesByStatus(
+  client: LinearClient,
+  teamId: string,
+  statusName: string,
+  projectNames?: string[],
+): Promise<LinearIssueListItem[]> {
+  const team = await client.team(teamId);
+  if (!team) {
+    throw new Error(`Linear team not found: ${teamId}`);
+  }
+
+  const normalizedStatus = statusName.trim().toLowerCase();
+  const connection = await team.issues({ first: 100 });
+  const nodes = connection.nodes ?? [];
+  const results: LinearIssueListItem[] = [];
+
+  for (const issue of nodes) {
+    const [state, project] = await Promise.all([issue.state, issue.project]);
+    const issueStatus = state?.name ?? null;
+    if (issueStatus?.trim().toLowerCase() !== normalizedStatus) {
+      continue;
+    }
+    const projectName = project?.name ?? null;
+    if (
+      projectNames &&
+      projectNames.length > 0 &&
+      (!projectName || !projectNames.includes(projectName))
+    ) {
+      continue;
+    }
+    results.push({
+      id: issue.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      status: issueStatus,
+      projectName,
+      teamId: team.id,
+      url: issue.url ?? null,
+    });
+  }
+
+  return results;
+}
+
+export function toIssueSnapshot(item: LinearIssueListItem): LinearIssueSnapshot {
+  return {
+    id: item.id,
+    identifier: item.identifier,
+    title: item.title,
+    description: null,
+    status: item.status,
+    projectName: item.projectName,
+    teamName: null,
+    teamId: item.teamId,
+    url: item.url,
+  };
+}

package/workspace-snapshot/files/src/linear/markers.ts

@@ -0,0 +1,238 @@
+export interface HarnessMarkers {
+  orchestratorMarker?: string;
+  phase?: string;
+  runId?: string;
+  cursorAgentId?: string;
+  cursorRunId?: string;
+  model?: string;
+  promptVersion?: string;
+  targetRepo?: string;
+  baseBranch?: string;
+  branch?: string;
+  prUrl?: string;
+  previewUrl?: string;
+  previousImplementationRunId?: string;
+  previousHandoffRunId?: string;
+  pmFeedbackCommentId?: string;
+  previousRevisionRunId?: string;
+  mergeCommitSha?: string;
+  deploymentUrl?: string;
+  githubActionsRunUrl?: string;
+  issueKey?: string;
+  prNumber?: string;
+  productionBranch?: string;
+  integrationSuccessStatus?: string;
+  productionHeadSha?: string;
+  previousMergeRunId?: string;
+  promotionProofMethod?: string;
+  repairAttempt?: string;
+  repairPath?: string;
+  triggerReason?: string;
+  conflictFiles?: string;
+  dependencyClosureFiles?: string;
+  touchedFiles?: string;
+  repairCycleId?: string;
+  executionEnvironment?: string;
+  executionEnvironmentMarker?: string;
+  hostname?: string;
+  codespaceName?: string;
+  githubRunId?: string;
+  githubWorkflow?: string;
+  gitBranch?: string;
+  gitSha?: string;
+}
+
+const HARNESS_HTML_METADATA_PATTERN = /<!--\s*([\s\S]*?)\s*-->/g;
+
+export function extractHarnessMetadataBlock(commentBody: string): string | null {
+  const matches = [...commentBody.matchAll(HARNESS_HTML_METADATA_PATTERN)];
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const block = matches[index]?.[1]?.trim();
+    if (
+      block &&
+      (block.includes("harness-orchestrator-v1") ||
+        /\nphase:\s*\S+/m.test(block) ||
+        /^phase:\s*\S+/m.test(block))
+    ) {
+      return block;
+    }
+  }
+  return null;
+}
+
+function parseHarnessMarkerLines(block: string): HarnessMarkers {
+  const markers: HarnessMarkers = {};
+
+  for (const line of block.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed === "---") continue;
+
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) {
+      if (trimmed.startsWith("harness-orchestrator")) {
+        markers.orchestratorMarker = trimmed;
+      }
+      continue;
+    }
+
+    const key = trimmed.slice(0, colonIndex).trim().toLowerCase();
+    const value = trimmed.slice(colonIndex + 1).trim();
+
+    switch (key) {
+      case "phase":
+        markers.phase = value;
+        break;
+      case "run_id":
+        markers.runId = value;
+        break;
+      case "cursor_agent_id":
+        markers.cursorAgentId = value;
+        break;
+      case "cursor_run_id":
+        markers.cursorRunId = value;
+        break;
+      case "model":
+        markers.model = value;
+        break;
+      case "prompt_version":
+        markers.promptVersion = value;
+        break;
+      case "target_repo":
+        markers.targetRepo = value;
+        break;
+      case "base_branch":
+        markers.baseBranch = value;
+        break;
+      case "branch":
+        markers.branch = value;
+        break;
+      case "pr_url":
+        markers.prUrl = value;
+        break;
+      case "preview_url":
+        markers.previewUrl = value;
+        break;
+      case "previous_implementation_run_id":
+        markers.previousImplementationRunId = value;
+        break;
+      case "previous_handoff_run_id":
+        markers.previousHandoffRunId = value;
+        break;
+      case "pm_feedback_comment_id":
+        markers.pmFeedbackCommentId = value;
+        break;
+      case "previous_revision_run_id":
+        markers.previousRevisionRunId = value;
+        break;
+      case "merge_commit_sha":
+        markers.mergeCommitSha = value;
+        break;
+      case "deployment_url":
+        markers.deploymentUrl = value;
+        break;
+      case "github_actions_run_url":
+        markers.githubActionsRunUrl = value;
+        break;
+      case "issue_key":
+        markers.issueKey = value;
+        break;
+      case "pr_number":
+        markers.prNumber = value;
+        break;
+      case "production_branch":
+        markers.productionBranch = value;
+        break;
+      case "integration_success_status":
+        markers.integrationSuccessStatus = value;
+        break;
+      case "production_head_sha":
+        markers.productionHeadSha = value;
+        break;
+      case "previous_merge_run_id":
+        markers.previousMergeRunId = value;
+        break;
+      case "promotion_proof_method":
+        markers.promotionProofMethod = value;
+        break;
+      case "repair_attempt":
+        markers.repairAttempt = value;
+        break;
+      case "repair_path":
+        markers.repairPath = value;
+        break;
+      case "trigger_reason":
+        markers.triggerReason = value;
+        break;
+      case "conflict_files":
+        markers.conflictFiles = value;
+        break;
+      case "dependency_closure_files":
+        markers.dependencyClosureFiles = value;
+        break;
+      case "touched_files":
+        markers.touchedFiles = value;
+        break;
+      case "repair_cycle_id":
+        markers.repairCycleId = value;
+        break;
+      case "execution_environment":
+        markers.executionEnvironment = value;
+        break;
+      case "execution_environment_marker":
+        markers.executionEnvironmentMarker = value;
+        break;
+      case "hostname":
+        markers.hostname = value;
+        break;
+      case "codespace_name":
+        markers.codespaceName = value;
+        break;
+      case "github_run_id":
+        markers.githubRunId = value;
+        break;
+      case "github_workflow":
+        markers.githubWorkflow = value;
+        break;
+      case "git_branch":
+        markers.gitBranch = value;
+        break;
+      case "git_sha":
+        markers.gitSha = value;
+        break;
+      default:
+        if (trimmed.startsWith("harness-orchestrator")) {
+          markers.orchestratorMarker = trimmed;
+        }
+        break;
+    }
+  }
+
+  if (block.includes("harness-orchestrator-v1") && !markers.orchestratorMarker) {
+    markers.orchestratorMarker = "harness-orchestrator-v1";
+  }
+
+  return markers;
+}
+
+function parseLegacyVisibleFooter(commentBody: string): HarnessMarkers {
+  const segments = commentBody.split(/\n---\n/);
+  const footerSegment =
+    [...segments]
+      .reverse()
+      .find(
+        (segment) =>
+          segment.includes("harness-orchestrator-v1") ||
+          /\nphase:\s*\S+/m.test(segment) ||
+          /^phase:\s*\S+/m.test(segment),
+      ) ?? segments.at(-1) ?? commentBody;
+
+  return parseHarnessMarkerLines(footerSegment);
+}
+
+export function parseHarnessMarkers(commentBody: string): HarnessMarkers {
+  const htmlBlock = extractHarnessMetadataBlock(commentBody);
+  if (htmlBlock) {
+    return parseHarnessMarkerLines(htmlBlock);
+  }
+  return parseLegacyVisibleFooter(commentBody);
+}

package/workspace-snapshot/files/src/linear/merge-source-comment.ts

@@ -0,0 +1,46 @@
+import { hasHandoffCompletionMarker } from "./comments.js";
+import { findLatestRevisionComment } from "./revision-comment.js";
+import { parseHarnessMarkers, type HarnessMarkers } from "./markers.js";
+import type { LinearCommentRecord } from "./writer.js";
+
+export type MergeSourceKind = "revision" | "handoff";
+
+export interface MergeSourceComment {
+  source: MergeSourceKind;
+  comment: LinearCommentRecord;
+  markers: HarnessMarkers;
+}
+
+export function findLatestMergeSourceComment(
+  comments: LinearCommentRecord[],
+  orchestratorMarker: string,
+): MergeSourceComment | null {
+  const revisionComment = findLatestRevisionComment(comments, orchestratorMarker);
+  if (revisionComment) {
+    return {
+      source: "revision",
+      comment: revisionComment,
+      markers: parseHarnessMarkers(revisionComment.body),
+    };
+  }
+
+  const handoffComments = comments.filter((comment) =>
+    hasHandoffCompletionMarker(comment.body, orchestratorMarker),
+  );
+  handoffComments.sort((a, b) => {
+    const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+    const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+    return bTime - aTime;
+  });
+
+  const handoffComment = handoffComments[0];
+  if (!handoffComment) {
+    return null;
+  }
+
+  return {
+    source: "handoff",
+    comment: handoffComment,
+    markers: parseHarnessMarkers(handoffComment.body),
+  };
+}

package/workspace-snapshot/files/src/linear/parser.ts

@@ -0,0 +1,101 @@
+import type { ParsedIssue } from "../types/parsed-issue.js";
+
+const SECTION_HEADERS = [
+  "target repo",
+  "task",
+  "problem",
+  "acceptance criteria",
+  "out of scope",
+  "validation expectations",
+  "context and links",
+  "eval hints",
+  "definition of ready",
+  "user / job story",
+] as const;
+
+function parseSections(description: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  const lines = description.split("\n");
+  let currentKey: string | null = null;
+  const buffer: string[] = [];
+
+  const flush = () => {
+    if (currentKey) {
+      sections.set(currentKey, buffer.join("\n").trim());
+      buffer.length = 0;
+    }
+  };
+
+  for (const line of lines) {
+    const match = line.match(/^##\s+(.+?)\s*$/);
+    if (match) {
+      flush();
+      currentKey = match[1]!.trim().toLowerCase();
+      continue;
+    }
+    if (currentKey !== null) {
+      buffer.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+function extractListItems(content: string): string[] {
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("-") || line.startsWith("*"))
+    .map((line) => line.replace(/^[-*]\s*(\[[ xX]\]\s*)?/, "").trim())
+    .filter(Boolean);
+}
+
+function extractTargetRepoFromContext(contextSection: string | undefined): string | undefined {
+  if (!contextSection) return undefined;
+  const match = contextSection.match(/target repo:\s*`?([^`\n]+)`?/i);
+  return match?.[1]?.trim();
+}
+
+export function parseIssueDescription(description: string): ParsedIssue {
+  const sections = parseSections(description);
+  const parseErrors: string[] = [];
+
+  const task =
+    sections.get("task")?.trim() || sections.get("problem")?.trim() || "";
+  if (!task) {
+    parseErrors.push("missing required section: Task (or Problem)");
+  }
+
+  const acceptanceSection = sections.get("acceptance criteria");
+  const acceptanceCriteria = acceptanceSection
+    ? extractListItems(acceptanceSection)
+    : [];
+  if (!acceptanceSection?.trim() || acceptanceCriteria.length === 0) {
+    parseErrors.push("missing required section: Acceptance criteria");
+  }
+
+  const outOfScopeSection = sections.get("out of scope");
+  const outOfScope = outOfScopeSection ? extractListItems(outOfScopeSection) : [];
+  if (!outOfScopeSection?.trim() || outOfScope.length === 0) {
+    parseErrors.push("missing required section: Out of scope");
+  }
+
+  const targetRepoRaw =
+    sections.get("target repo")?.trim() ||
+    extractTargetRepoFromContext(sections.get("context and links"));
+
+  const validationExpectations = sections.get("validation expectations")?.trim();
+
+  return {
+    targetRepoRaw: targetRepoRaw || undefined,
+    task,
+    acceptanceCriteria,
+    outOfScope,
+    validationExpectations: validationExpectations || undefined,
+    parseErrors,
+  };
+}
+
+export function isKnownSectionHeader(header: string): boolean {
+  return SECTION_HEADERS.includes(header.toLowerCase() as (typeof SECTION_HEADERS)[number]);
+}

package/workspace-snapshot/files/src/linear/phase-labels.ts

@@ -0,0 +1,58 @@
+export type PhaseStartPhase =
+  | "planning_start"
+  | "implementation_start"
+  | "revision_start"
+  | "merge_start";
+
+export type HarnessErrorPhase =
+  | "planning"
+  | "implementation"
+  | "handoff"
+  | "revision"
+  | "merge"
+  | "production_sync";
+
+const PHASE_START_LABELS: Record<PhaseStartPhase, string> = {
+  planning_start: "Planning",
+  implementation_start: "Building",
+  revision_start: "Revision",
+  merge_start: "Merging",
+};
+
+const COMPLETION_LABELS: Record<string, string> = {
+  planning: "Planning complete",
+  implementation: "Building complete",
+  handoff: "PM handoff",
+  revision: "Revision complete",
+  merge: "Merge complete",
+  production_sync: "Production promotion",
+};
+
+const ERROR_LABELS: Record<HarnessErrorPhase, string> = {
+  planning: "Planning",
+  implementation: "Building",
+  handoff: "PM handoff",
+  revision: "Revision",
+  merge: "Merge",
+  production_sync: "Production promotion",
+};
+
+export function getPhaseStartLabel(phase: PhaseStartPhase): string {
+  return PHASE_START_LABELS[phase];
+}
+
+export function getCompletionLabel(phase: string): string {
+  return COMPLETION_LABELS[phase] ?? phase;
+}
+
+export function getErrorLabel(phase: HarnessErrorPhase): string {
+  return ERROR_LABELS[phase];
+}
+
+export function formatHarnessPhaseLabel(label: string): string {
+  return label;
+}
+
+export function formatHarnessErrorPhaseLabel(phase: HarnessErrorPhase): string {
+  return `${getErrorLabel(phase)} error`;
+}

package/workspace-snapshot/files/src/linear/planning-comment.ts

@@ -0,0 +1,19 @@
+import { hasPlanningCompletionMarker } from "./comments.js";
+import type { LinearCommentRecord } from "./writer.js";
+
+export function findLatestPlanningComment(
+  comments: LinearCommentRecord[],
+  orchestratorMarker: string,
+): LinearCommentRecord | null {
+  const planningComments = comments.filter((comment) =>
+    hasPlanningCompletionMarker(comment.body, orchestratorMarker),
+  );
+
+  planningComments.sort((a, b) => {
+    const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+    const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+    return bTime - aTime;
+  });
+
+  return planningComments[0] ?? null;
+}

package/workspace-snapshot/files/src/linear/pm-feedback-comment.ts

@@ -0,0 +1,41 @@
+import { isHarnessOrchestratorComment } from "./comments.js";
+import type { LinearCommentRecord } from "./writer.js";
+
+export function findLatestPmFeedbackAfterHandoff(
+  comments: LinearCommentRecord[],
+  handoffComment: LinearCommentRecord,
+  orchestratorMarker: string,
+): LinearCommentRecord | null {
+  const handoffTime = handoffComment.createdAt
+    ? Date.parse(handoffComment.createdAt)
+    : 0;
+
+  const candidates = comments.filter((comment) => {
+    if (comment.id === handoffComment.id) {
+      return false;
+    }
+
+    const commentTime = comment.createdAt ? Date.parse(comment.createdAt) : 0;
+    if (handoffTime > 0 && commentTime > 0 && commentTime <= handoffTime) {
+      return false;
+    }
+
+    if (!comment.body.trim()) {
+      return false;
+    }
+
+    if (isHarnessOrchestratorComment(comment.body, orchestratorMarker)) {
+      return false;
+    }
+
+    return true;
+  });
+
+  candidates.sort((a, b) => {
+    const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+    const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+    return bTime - aTime;
+  });
+
+  return candidates[0] ?? null;
+}

package/workspace-snapshot/files/src/linear/revision-comment.ts

@@ -0,0 +1,19 @@
+import { hasRevisionCompletionMarker } from "./comments.js";
+import type { LinearCommentRecord } from "./writer.js";
+
+export function findLatestRevisionComment(
+  comments: LinearCommentRecord[],
+  orchestratorMarker: string,
+): LinearCommentRecord | null {
+  const revisionComments = comments.filter((comment) =>
+    hasRevisionCompletionMarker(comment.body, orchestratorMarker),
+  );
+
+  revisionComments.sort((a, b) => {
+    const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+    const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+    return bTime - aTime;
+  });
+
+  return revisionComments[0] ?? null;
+}

package/workspace-snapshot/files/src/linear/states.ts

@@ -0,0 +1,20 @@
+import { LinearClient } from "@linear/sdk";
+
+export async function resolveWorkflowStateId(
+  client: LinearClient,
+  teamId: string,
+  statusName: string,
+): Promise<string> {
+  const connection = await client.workflowStates({
+    filter: { team: { id: { eq: teamId } } },
+  });
+  const nodes = connection.nodes ?? [];
+  const normalized = statusName.trim().toLowerCase();
+  const match = nodes.find((state) => state.name?.toLowerCase() === normalized);
+  if (!match?.id) {
+    throw new Error(
+      `Workflow state "${statusName}" not found for team ${teamId}`,
+    );
+  }
+  return match.id;
+}