p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/preview/vercel-from-pr.ts

@@ -0,0 +1,123 @@
+export interface PreviewCaptureResult {
+  previewUrl: string | null;
+  source: "vercel_comment" | "vercel_url_scan" | null;
+  polledSeconds: number;
+  warnings: string[];
+}
+
+const PREVIEW_LINK_REGEX =
+  /\[Preview\]\((https:\/\/[^)]+\.vercel\.app[^)]*)\)/i;
+const VERCEL_APP_URL_REGEX = /https:\/\/[a-z0-9-]+\.vercel\.app[^\s)"']*/gi;
+
+export function extractVercelPreviewFromComments(
+  comments: { author: string; body: string }[],
+): PreviewCaptureResult {
+  const vercelComments = comments.filter((comment) =>
+    comment.author.toLowerCase().startsWith("vercel"),
+  );
+
+  for (const comment of vercelComments) {
+    const previewMatch = comment.body.match(PREVIEW_LINK_REGEX);
+    if (previewMatch?.[1]) {
+      return {
+        previewUrl: previewMatch[1],
+        source: "vercel_comment",
+        polledSeconds: 0,
+        warnings: [],
+      };
+    }
+  }
+
+  for (const comment of comments) {
+    const matches = comment.body.match(VERCEL_APP_URL_REGEX);
+    if (matches?.[0]) {
+      return {
+        previewUrl: matches[0],
+        source: "vercel_url_scan",
+        polledSeconds: 0,
+        warnings: [],
+      };
+    }
+  }
+
+  return {
+    previewUrl: null,
+    source: null,
+    polledSeconds: 0,
+    warnings: ["No Vercel preview URL found in PR comments"],
+  };
+}
+
+async function fetchCommentsWithDeadline(
+  fetchComments: () => Promise<{ author: string; body: string }[]>,
+  deadlineMs: number,
+): Promise<{ author: string; body: string }[] | null> {
+  const remainingMs = deadlineMs - Date.now();
+  if (remainingMs <= 0) {
+    return null;
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      fetchComments(),
+      new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), remainingMs);
+      }),
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+export async function pollForVercelPreview(
+  fetchComments: () => Promise<{ author: string; body: string }[]>,
+  options: {
+    pollTimeoutSeconds: number;
+    pollIntervalSeconds: number;
+    sleep?: (ms: number) => Promise<void>;
+  },
+): Promise<PreviewCaptureResult> {
+  const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+  const deadline = Date.now() + options.pollTimeoutSeconds * 1000;
+  let polledSeconds = 0;
+  let fetchTimedOut = false;
+
+  while (Date.now() <= deadline) {
+    const comments = await fetchCommentsWithDeadline(fetchComments, deadline);
+    if (comments === null) {
+      fetchTimedOut = true;
+      break;
+    }
+
+    const result = extractVercelPreviewFromComments(comments);
+    if (result.previewUrl) {
+      return { ...result, polledSeconds };
+    }
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      break;
+    }
+
+    const waitMs = Math.min(options.pollIntervalSeconds * 1000, remaining);
+    await sleep(waitMs);
+    polledSeconds += waitMs / 1000;
+  }
+
+  const finalComments = await fetchCommentsWithDeadline(fetchComments, deadline);
+  const finalResult = extractVercelPreviewFromComments(finalComments ?? []);
+  return {
+    ...finalResult,
+    polledSeconds,
+    warnings: finalResult.previewUrl
+      ? []
+      : [
+          ...(finalResult.warnings ?? []),
+          ...(fetchTimedOut ? ["Preview comment fetch timed out before deadline"] : []),
+          `Preview not found within ${options.pollTimeoutSeconds}s`,
+        ],
+  };
+}

package/workspace-snapshot/files/src/prompts/branch-name.ts

@@ -0,0 +1,22 @@
+import { DEFAULT_IMPLEMENTATION_BRANCH_PREFIX } from "../config/defaults.js";
+import type { HarnessConfig } from "../config/types.js";
+
+function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+export function buildBranchName(
+  issueKey: string,
+  title: string,
+  config: HarnessConfig,
+): string {
+  const prefix =
+    config.implementation?.branchPrefix ?? DEFAULT_IMPLEMENTATION_BRANCH_PREFIX;
+  const key = issueKey.toLowerCase();
+  const slug = slugify(title);
+  return slug ? `${prefix}/${key}-${slug}` : `${prefix}/${key}`;
+}

package/workspace-snapshot/files/src/prompts/builder.ts

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LinearIssueSnapshot } from "../linear/client.js";
+import type { ParsedIssue } from "../types/parsed-issue.js";
+import type { ResolvedTarget } from "../resolver/target-repo.js";
+import {
+  IMPLEMENTATION_PROMPT_VERSION,
+  PLANNING_PROMPT_VERSION,
+} from "../config/defaults.js";
+
+const planningTemplatePath = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "planning.md",
+);
+
+const implementationTemplatePath = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "implementation.md",
+);
+
+function formatList(items: string[]): string {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "_none_";
+}
+
+export interface BuildImplementationPromptParams {
+  issue: LinearIssueSnapshot;
+  parsed: ParsedIssue;
+  resolved: ResolvedTarget;
+  runId: string;
+  branchName: string;
+  planningCommentBody: string | null;
+  validationCommands: string[];
+}
+
+export async function buildPlanningPrompt(
+  issue: LinearIssueSnapshot,
+  parsed: ParsedIssue,
+  resolved: ResolvedTarget,
+): Promise<{ prompt: string; promptVersion: string }> {
+  const template = await readFile(planningTemplatePath, "utf8");
+  const validationSection = parsed.validationExpectations
+    ? `### Validation expectations\n\n${parsed.validationExpectations}`
+    : "";
+
+  const prompt = template
+    .replaceAll("{{promptVersion}}", PLANNING_PROMPT_VERSION)
+    .replaceAll("{{issueKey}}", issue.identifier)
+    .replaceAll("{{issueTitle}}", issue.title)
+    .replaceAll("{{task}}", parsed.task)
+    .replaceAll("{{acceptanceCriteria}}", formatList(parsed.acceptanceCriteria))
+    .replaceAll("{{outOfScope}}", formatList(parsed.outOfScope))
+    .replaceAll("{{validationExpectations}}", validationSection)
+    .replaceAll("{{targetRepo}}", resolved.targetRepo)
+    .replaceAll("{{baseBranch}}", resolved.baseBranch);
+
+  return { prompt, promptVersion: PLANNING_PROMPT_VERSION };
+}
+
+export async function buildImplementationPrompt(
+  params: BuildImplementationPromptParams,
+): Promise<{ prompt: string; promptVersion: string }> {
+  const template = await readFile(implementationTemplatePath, "utf8");
+  const validationSection = params.parsed.validationExpectations
+    ? `### Validation expectations\n\n${params.parsed.validationExpectations}`
+    : "";
+  const planningComment =
+    params.planningCommentBody?.trim() ||
+    "_No durable planning comment was found. Proceed only because the issue is narrow and well-scoped._";
+
+  const prompt = template
+    .replaceAll("{{promptVersion}}", IMPLEMENTATION_PROMPT_VERSION)
+    .replaceAll("{{issueKey}}", params.issue.identifier)
+    .replaceAll("{{issueTitle}}", params.issue.title)
+    .replaceAll("{{issueUrl}}", params.issue.url ?? "n/a")
+    .replaceAll("{{task}}", params.parsed.task)
+    .replaceAll("{{acceptanceCriteria}}", formatList(params.parsed.acceptanceCriteria))
+    .replaceAll("{{outOfScope}}", formatList(params.parsed.outOfScope))
+    .replaceAll("{{validationExpectations}}", validationSection)
+    .replaceAll("{{targetRepo}}", params.resolved.targetRepo)
+    .replaceAll("{{baseBranch}}", params.resolved.baseBranch)
+    .replaceAll("{{branchName}}", params.branchName)
+    .replaceAll("{{planningComment}}", planningComment)
+    .replaceAll("{{validationCommands}}", formatList(params.validationCommands))
+    .replaceAll("{{runId}}", params.runId);
+
+  return { prompt, promptVersion: IMPLEMENTATION_PROMPT_VERSION };
+}

package/workspace-snapshot/files/src/prompts/implementation.md

@@ -0,0 +1,77 @@
+# Implementation agent ({{promptVersion}})
+
+You are the **implementation agent** for the agentic product development harness.
+
+## Mode: implementation
+
+- Work only in the target repository below.
+- Create exactly one branch using the required branch name.
+- Make only the requested scoped changes.
+- Run the validation commands listed below when available.
+- Open a PR against the target repository base branch.
+- Do not merge the PR.
+- Do not deploy manually.
+- Do not create releases or tags.
+- Do not publish npm packages or deploy.
+- When the planning context includes release-impact boundaries, preserve them and report outstanding release preparation in the final report.
+- Do not create Cursor skills.
+- Do not make unrelated changes.
+- Do not edit the harness repository unless it is the resolved target repo.
+
+## Linear issue
+
+- **Key:** {{issueKey}}
+- **Title:** {{issueTitle}}
+- **URL:** {{issueUrl}}
+
+### Task
+
+{{task}}
+
+### Acceptance criteria
+
+{{acceptanceCriteria}}
+
+### Out of scope
+
+{{outOfScope}}
+
+{{validationExpectations}}
+
+## Target repository
+
+- **Repo:** {{targetRepo}}
+- **Base branch:** {{baseBranch}}
+- **Required branch name:** {{branchName}}
+
+## Planning context
+
+{{planningComment}}
+
+## Validation commands
+
+{{validationCommands}}
+
+## PR requirements
+
+- Open the PR against `{{baseBranch}}` in `{{targetRepo}}`.
+- PR title: `[{{issueKey}}] {{issueTitle}}`
+- PR body must include:
+  - Linear issue link/key
+  - Summary
+  - Files changed
+  - Validation run
+  - Known deviations
+  - Harness run id: `{{runId}}`
+  - Cursor agent/run id if available
+
+## Final response
+
+Return markdown only with:
+
+- Summary
+- Files changed
+- Validation run
+- Known deviations
+- Branch
+- PR URL

package/workspace-snapshot/files/src/prompts/integration-repair-builder.ts

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LinearIssueSnapshot } from "../linear/client.js";
+import type { ParsedIssue } from "../types/parsed-issue.js";
+import type { ResolvedTarget } from "../resolver/target-repo.js";
+import { INTEGRATION_REPAIR_PROMPT_VERSION } from "../config/defaults.js";
+
+const integrationRepairTemplatePath = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "integration-repair.md",
+);
+
+function formatList(items: string[]): string {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "_none_";
+}
+
+export interface BuildIntegrationRepairPromptParams {
+  issue: LinearIssueSnapshot;
+  parsed: ParsedIssue;
+  resolved: ResolvedTarget;
+  branch: string;
+  prUrl: string;
+  baseHeadSha: string;
+  conflictFiles: string[];
+  changedFiles: string[];
+  baseBranchDelta: string[];
+  validationCommands: string[];
+}
+
+export async function buildIntegrationRepairPrompt(
+  params: BuildIntegrationRepairPromptParams,
+): Promise<{ prompt: string; promptVersion: string }> {
+  const template = await readFile(integrationRepairTemplatePath, "utf8");
+  const validationSection = params.parsed.validationExpectations
+    ? `### Validation expectations\n\n${params.parsed.validationExpectations}`
+    : "";
+
+  const prompt = template
+    .replaceAll("{{promptVersion}}", INTEGRATION_REPAIR_PROMPT_VERSION)
+    .replaceAll("{{issueKey}}", params.issue.identifier)
+    .replaceAll("{{issueTitle}}", params.issue.title)
+    .replaceAll("{{issueUrl}}", params.issue.url ?? "n/a")
+    .replaceAll("{{task}}", params.parsed.task)
+    .replaceAll("{{acceptanceCriteria}}", formatList(params.parsed.acceptanceCriteria))
+    .replaceAll("{{outOfScope}}", formatList(params.parsed.outOfScope))
+    .replaceAll("{{validationExpectations}}", validationSection)
+    .replaceAll("{{targetRepo}}", params.resolved.targetRepo)
+    .replaceAll("{{branch}}", params.branch)
+    .replaceAll("{{prUrl}}", params.prUrl)
+    .replaceAll("{{baseBranch}}", params.resolved.baseBranch)
+    .replaceAll("{{baseHeadSha}}", params.baseHeadSha)
+    .replaceAll("{{productionBranch}}", params.resolved.productionBranch)
+    .replaceAll("{{conflictFiles}}", formatList(params.conflictFiles))
+    .replaceAll("{{changedFiles}}", formatList(params.changedFiles))
+    .replaceAll("{{baseBranchDelta}}", formatList(params.baseBranchDelta))
+    .replaceAll(
+      "{{validationCommands}}",
+      params.validationCommands.length > 0
+        ? params.validationCommands.map((cmd) => `- \`${cmd}\``).join("\n")
+        : "_none configured_",
+    );
+
+  return { prompt, promptVersion: INTEGRATION_REPAIR_PROMPT_VERSION };
+}

package/workspace-snapshot/files/src/prompts/integration-repair.md

@@ -0,0 +1,111 @@
+# Integration repair agent ({{promptVersion}})
+
+You are the **integration repair agent** for the agentic product development harness.
+
+## Mode: integration repair
+
+- Work only in the target repository below.
+- Start from the existing PR branch and update the existing PR only.
+- Do not create a new PR.
+- Do not merge the PR through GitHub.
+- Do not push directly to `{{baseBranch}}`, `{{productionBranch}}`, `main`, or `dev`.
+- Do not create releases or tags.
+- Do not make unrelated product changes, unrelated refactors, or broad formatting sweeps.
+
+## Linear issue
+
+- **Key:** {{issueKey}}
+- **Title:** {{issueTitle}}
+- **URL:** {{issueUrl}}
+
+### Task
+
+{{task}}
+
+### Acceptance criteria
+
+{{acceptanceCriteria}}
+
+### Out of scope
+
+{{outOfScope}}
+
+{{validationExpectations}}
+
+## Target repository
+
+- **Repo:** {{targetRepo}}
+- **PR branch:** {{branch}}
+- **Existing PR:** {{prUrl}}
+- **Base branch:** {{baseBranch}}
+- **Base branch HEAD:** {{baseHeadSha}}
+- **Production branch:** {{productionBranch}}
+
+## Required git workflow
+
+Perform the real base-into-head conflict repair workflow:
+
+1. Confirm you are on the PR branch `{{branch}}`.
+2. Fetch the latest base branch: `git fetch origin {{baseBranch}}`.
+3. Merge the base branch into the PR branch locally: `git merge origin/{{baseBranch}}`.
+4. If conflicts occur, resolve them in the working tree and remove all conflict markers.
+5. Preserve both:
+   - the current issue acceptance criteria and PR intent
+   - behavior already merged into `{{baseBranch}}`
+6. Commit the conflict resolution to `{{branch}}`.
+7. Run validation.
+8. Push the repaired PR branch to origin.
+
+## Conflict files
+
+{{conflictFiles}}
+
+## PR changed files
+
+{{changedFiles}}
+
+## Base branch changes since merge queue entry
+
+{{baseBranchDelta}}
+
+## Validation commands
+
+{{validationCommands}}
+
+## Allowed repair edits
+
+Allowed:
+
+- Conflict files listed above.
+- Direct dependency-closure files required to make the conflict resolution compile and pass validation, such as importers, route registries, shared constants, shared type files, directly covering tests, or small adjacent files required by the resolution.
+
+Forbidden:
+
+- Unrelated product changes.
+- Unrelated refactors.
+- Broad formatting sweeps.
+- Direct edits to `{{baseBranch}}`, `{{productionBranch}}`, `main`, or `dev`.
+- Scope expansion beyond the issue acceptance criteria and already-merged base behavior.
+
+If resolving the conflict requires broader product judgment, stop and report `repair_requires_product_judgment`.
+
+## Final response
+
+Return markdown with a fenced JSON block containing this exact shape:
+
+```json
+{
+  "status": "success",
+  "merge_commit_sha": "final pushed PR branch HEAD sha",
+  "validation_summary": "commands run and result",
+  "touched_files": [
+    {
+      "path": "relative/path",
+      "category": "conflict",
+      "reason": "why this file was required"
+    }
+  ]
+}
+```
+
+Use `category: "dependency_closure"` for allowed files that were not direct conflict files. If repair fails, set `status` to `failed`, `ambiguous`, or `requires_product_judgment` and explain why.

package/workspace-snapshot/files/src/prompts/planning.md

@@ -0,0 +1,64 @@
+# Planning agent ({{promptVersion}})
+
+You are the **planning agent** for the agentic product development harness.
+
+## Mode: planning only
+
+- Inspect the target repository and Linear issue context.
+- Produce a structured implementation plan.
+- **Do not** edit files.
+- **Do not** create a branch.
+- **Do not** commit.
+- **Do not** open a PR.
+- **Do not** merge or deploy.
+
+## Release impact (conditional)
+
+When the work touches a published artifact, deployment contract, persisted data contract, public API, installer, template/package surface, compatibility boundary, or versioned distribution:
+
+- Inspect repo release docs, manifests, package config, changelog, and versioning conventions before recommending a version increment.
+- Do **not** assume npm or SemVer for every target repository.
+- Classify impact as: no release impact, later release preparation required, or human decision required.
+- Identify compatibility, migration, rollback, and release-validation implications when relevant.
+- **Do not** authorize publishing, tagging, deployment, or final release execution.
+
+Omit this section for internal prototype work with no distributable surface unless the issue explicitly asks for release analysis.
+
+## Linear issue
+
+- **Key:** {{issueKey}}
+- **Title:** {{issueTitle}}
+
+### Task
+
+{{task}}
+
+### Acceptance criteria
+
+{{acceptanceCriteria}}
+
+### Out of scope
+
+{{outOfScope}}
+
+{{validationExpectations}}
+
+## Target repository
+
+- **Repo:** {{targetRepo}}
+- **Base branch:** {{baseBranch}}
+
+## Output format
+
+Return markdown only, structured like the harness implementation plan template:
+
+- Context
+- Approach (numbered steps)
+- Files to touch (table)
+- Files explicitly out of scope
+- Risks (table)
+- Validation plan (checklist)
+- Rollback
+- Release impact (only when relevant; do not authorize publish/tag/deploy)
+
+Do not include harness marker footers — the orchestrator adds those.

package/workspace-snapshot/files/src/prompts/revision-builder.ts

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { LinearIssueSnapshot } from "../linear/client.js";
+import type { ParsedIssue } from "../types/parsed-issue.js";
+import type { ResolvedTarget } from "../resolver/target-repo.js";
+import { REVISION_PROMPT_VERSION } from "../config/defaults.js";
+
+const revisionTemplatePath = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "revision.md",
+);
+
+function formatList(items: string[]): string {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "_none_";
+}
+
+export interface BuildRevisionPromptParams {
+  issue: LinearIssueSnapshot;
+  parsed: ParsedIssue;
+  resolved: ResolvedTarget;
+  runId: string;
+  branch: string;
+  prUrl: string;
+  pmFeedback: string;
+  changedFiles: string[];
+  validationCommands: string[];
+}
+
+export async function buildRevisionPrompt(
+  params: BuildRevisionPromptParams,
+): Promise<{ prompt: string; promptVersion: string }> {
+  const template = await readFile(revisionTemplatePath, "utf8");
+  const validationSection = params.parsed.validationExpectations
+    ? `### Validation expectations\n\n${params.parsed.validationExpectations}`
+    : "";
+
+  const prompt = template
+    .replaceAll("{{promptVersion}}", REVISION_PROMPT_VERSION)
+    .replaceAll("{{issueKey}}", params.issue.identifier)
+    .replaceAll("{{issueTitle}}", params.issue.title)
+    .replaceAll("{{issueUrl}}", params.issue.url ?? "n/a")
+    .replaceAll("{{task}}", params.parsed.task)
+    .replaceAll("{{acceptanceCriteria}}", formatList(params.parsed.acceptanceCriteria))
+    .replaceAll("{{outOfScope}}", formatList(params.parsed.outOfScope))
+    .replaceAll("{{validationExpectations}}", validationSection)
+    .replaceAll("{{targetRepo}}", params.resolved.targetRepo)
+    .replaceAll("{{branch}}", params.branch)
+    .replaceAll("{{prUrl}}", params.prUrl)
+    .replaceAll("{{pmFeedback}}", params.pmFeedback.trim())
+    .replaceAll("{{changedFiles}}", formatList(params.changedFiles))
+    .replaceAll(
+      "{{validationCommands}}",
+      params.validationCommands.length > 0
+        ? params.validationCommands.map((cmd) => `- \`${cmd}\``).join("\n")
+        : "_none configured_",
+    )
+    .replaceAll("{{runId}}", params.runId);
+
+  return { prompt, promptVersion: REVISION_PROMPT_VERSION };
+}

package/workspace-snapshot/files/src/prompts/revision.md

@@ -0,0 +1,71 @@
+# Revision agent ({{promptVersion}})
+
+You are the **revision agent** for the agentic product development harness.
+
+## Mode: revision
+
+- Work only in the target repository below.
+- Use the **existing branch** and update the **existing PR** listed below.
+- Apply **only** the PM feedback requested below.
+- Do not create a new PR.
+- Do not merge the PR.
+- Do not deploy manually.
+- Do not create releases or tags.
+- Do not make unrelated changes.
+- Do not edit the harness repository unless it is the resolved target repo.
+
+## Linear issue
+
+- **Key:** {{issueKey}}
+- **Title:** {{issueTitle}}
+- **URL:** {{issueUrl}}
+
+### Task
+
+{{task}}
+
+### Acceptance criteria
+
+{{acceptanceCriteria}}
+
+### Out of scope
+
+{{outOfScope}}
+
+{{validationExpectations}}
+
+## Target repository
+
+- **Repo:** {{targetRepo}}
+- **Existing branch:** {{branch}}
+- **Existing PR:** {{prUrl}}
+
+## PM feedback (instruction source)
+
+{{pmFeedback}}
+
+## Prior changed files (from handoff / PR inspect)
+
+{{changedFiles}}
+
+## Validation commands
+
+{{validationCommands}}
+
+## PR requirements
+
+- Push commits to the existing branch `{{branch}}`.
+- Update the existing PR `{{prUrl}}` only.
+- Do **not** open a new PR.
+- PR title should remain tied to `[{{issueKey}}]` when possible.
+
+## Final response
+
+Return markdown only with:
+
+- Summary of PM feedback applied
+- Files changed
+- Validation run
+- Known deviations
+- Branch (must be `{{branch}}`)
+- PR URL (must be `{{prUrl}}`)