p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/workflow/validate.ts

@@ -0,0 +1,43 @@
+import { isDispatchPhase } from "../runner/phase-args.js";
+
+const ISSUE_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+export const REPO_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+const VALID_FORCE = new Set(["true", "false"]);
+
+export function validateIssueKey(value: string | null | undefined): boolean {
+  if (!value || typeof value !== "string") {
+    return false;
+  }
+  return ISSUE_KEY_PATTERN.test(value.trim().toUpperCase());
+}
+
+export function validatePhase(value: string | null | undefined): boolean {
+  return isDispatchPhase(value);
+}
+
+export function validateForce(value: string | null | undefined): boolean {
+  if (!value || typeof value !== "string") {
+    return false;
+  }
+  return VALID_FORCE.has(value.trim().toLowerCase());
+}
+
+export function validateRepoIdFormat(
+  value: string | null | undefined,
+): boolean {
+  if (!value || typeof value !== "string") {
+    return false;
+  }
+  return REPO_ID_PATTERN.test(value.trim());
+}
+
+export function validateRepoId(
+  value: string | null | undefined,
+  allowedIds: readonly string[],
+): boolean {
+  if (!validateRepoIdFormat(value)) {
+    return false;
+  }
+  return allowedIds.includes(value!.trim());
+}

package/workspace-snapshot/files/src/workflow/write-dispatch-metadata.ts

@@ -0,0 +1,8 @@
+import {
+  buildDispatchMetadataFromEnv,
+  DEFAULT_DISPATCH_METADATA_PATH,
+  writeDispatchMetadata,
+} from "./dispatch-metadata.js";
+
+const payload = buildDispatchMetadataFromEnv(process.env);
+writeDispatchMetadata(DEFAULT_DISPATCH_METADATA_PATH, payload);

package/workspace-snapshot/files/templates/eval-scorecard.md

@@ -0,0 +1,54 @@
+# Eval scorecard: [Issue title]
+
+<!-- Human-readable readiness rubric. v0.1: manual scoring; automation planned for v0.2+. -->
+
+## Run metadata
+
+| Field | Value |
+|-------|-------|
+| Issue | |
+| Target repo | |
+| Branch / PR | |
+| Agent / executor | Cursor (manual loop) |
+| Date | |
+
+## Scoring legend
+
+| Score | Meaning |
+|-------|---------|
+| **Pass** | Criterion fully met; evidence attached |
+| **Partial** | Mostly met; minor gaps documented |
+| **Fail** | Not met; blocks readiness |
+| **N/A** | Not applicable to this work type |
+
+## Criteria
+
+| # | Criterion | Score | Evidence |
+|---|-----------|-------|----------|
+| 1 | Matches acceptance criteria from issue | | |
+| 2 | Scope limited to approved plan | | |
+| 3 | No secrets or env files committed | | |
+| 4 | Lint / typecheck pass (if applicable) | | |
+| 5 | UI matches intent on desktop (if applicable) | | |
+| 6 | UI matches intent on mobile (if applicable) | | |
+| 7 | Copy / content reviewed for accuracy | | |
+| 8 | Accessibility basics (labels, contrast) if UI | | |
+
+Add or remove rows per issue. Document why rows are N/A.
+
+## Summary
+
+- **Overall readiness:** Ready / Not ready / Ready with notes
+- **Blocking failures:** (list criterion numbers or none)
+
+## Human sign-off
+
+- [ ] PM / owner reviewed scorecard
+- Sign-off: _______________
+- Date: _______________
+
+## Follow-ups
+
+Issues or template improvements discovered during this eval:
+
+- 

package/workspace-snapshot/files/templates/implementation-plan.md

@@ -0,0 +1,59 @@
+# Implementation plan: [Issue title]
+
+<!-- Draft before Cursor execution. Human approval required in v0.1. -->
+
+## Issue reference
+
+- Issue: [link or file path]
+- Target repo: [e.g. example-target-app]
+- Branch name (proposed): `feat/...` or `fix/...`
+
+## Context
+
+Brief summary of the problem and constraints the agent must respect.
+
+## Approach
+
+1. Step one
+2. Step two
+3. Step three
+
+## Files to touch
+
+| File / area | Change |
+|-------------|--------|
+| `path/to/file` | Description |
+
+## Files explicitly out of scope
+
+- Paths or areas the agent must not modify
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Example: breaks existing route | Run dev server; check affected pages |
+
+## Validation plan
+
+How the agent (and human) will verify the work:
+
+- [ ] Manual check: ...
+- [ ] Lint / typecheck: ...
+- [ ] Preview URL review: ... (when applicable)
+
+## Rollback
+
+How to revert safely if the change is wrong (e.g. revert commit, feature flag, restore file).
+
+## Release impact (optional — include only when the plan identifies distributable surface)
+
+- Classification from plan:
+- Outstanding human-gated release preparation (if any):
+- Explicitly not authorized in this implementation run: publish, tag, deploy, create releases
+
+## Approval
+
+- [ ] Plan reviewed by human before execution
+- Approved by: _______________
+- Date: _______________

package/workspace-snapshot/files/templates/linear-issue.md

@@ -0,0 +1,53 @@
+# Issue: [Short title]
+
+Assign the issue to a **mapped Linear project** (e.g. Example Target App) when possible. Routing is controlled by the **Linear status field** (e.g. Ready for Planning, Ready for Build), not by any section in this description.
+
+> `## Problem` is a parser fallback for `## Task`; prefer `## Task` for new issues.
+
+## Target repo
+
+owner/repo
+
+_Include when known. May be copied from Linear project metadata (`Harness metadata: Target repo: ...`) or omitted when the issue is assigned to a mapped Linear project._
+
+## Task
+
+Single clear objective in one or two sentences.
+
+## Acceptance criteria
+
+- [ ] Observable, testable outcome 1
+- [ ] Observable, testable outcome 2
+
+## Out of scope
+
+- Explicitly excluded work
+
+## Validation expectations
+
+- `npm run lint`
+- `npm run build`
+
+## Context and links
+
+- Related issues / PRs:
+- Design or research links:
+- Target repo: `owner/repo` (optional backup if `## Target repo` is omitted)
+
+## User / job story
+
+As a **[persona]**, I want **[capability]** so that **[outcome]**.
+
+## Eval hints
+
+| Criterion | Priority |
+|-----------|----------|
+| Matches acceptance criteria | Required |
+| No unrelated file changes | Required |
+
+## Definition of ready
+
+- [ ] Task and acceptance criteria are clear
+- [ ] Out of scope is documented
+- [ ] Linear project assigned (or target repo identified)
+- [ ] PM / owner assigned for review

package/workspace-snapshot/files/templates/pr-readiness-report.md

@@ -0,0 +1,57 @@
+# PR readiness report: [Issue / PR title]
+
+<!-- Summarize readiness for human product and engineering review. v0.1: manual. -->
+
+## Summary
+
+One paragraph: what changed and why.
+
+## Issue and plan links
+
+- Issue:
+- Implementation plan:
+- Branch / PR:
+
+## Scope check
+
+- [ ] Changes match approved implementation plan
+- [ ] No out-of-scope files modified
+- [ ] Acceptance criteria addressed (list below)
+
+### Acceptance criteria status
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| | Done / Partial / Not done | |
+
+## Validation results
+
+| Check | Result | Evidence |
+|-------|--------|----------|
+| Lint / typecheck | Pass / Fail / Not run | |
+| Dev server / build | Pass / Fail / Not run | |
+| Manual UI review | Pass / Fail / N/A | |
+| Preview URL | [link or N/A] | |
+
+## Eval scorecard
+
+Link or embed: [`eval-scorecard.md`](eval-scorecard.md) for this run.
+
+## Open questions
+
+- Questions reviewers should answer before merge
+
+## Reviewer checklist
+
+- [ ] Product intent satisfied
+- [ ] No obvious regressions
+- [ ] Copy / UX acceptable for audience
+- [ ] Ready for engineering review (if applicable)
+
+## Recommendation
+
+- [ ] **Ready for review**
+- [ ] **Not ready** — blockers listed above
+
+Prepared by: _______________  
+Date: _______________

package/workspace-snapshot/files/tests/agents/cursor-provider.test.ts

@@ -0,0 +1,238 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { cursorAgentProvider } from "../../src/agents/cursor-provider.js";
+import { getAgentProvider } from "../../src/agents/provider.js";
+import type { HarnessConfig } from "../../src/config/types.js";
+
+const factoryMocks = vi.hoisted(() => ({
+  createPlanningCloudAgent: vi.fn(),
+  createImplementationCloudAgent: vi.fn(),
+  createRevisionCloudAgent: vi.fn(),
+  createIntegrationRepairCloudAgent: vi.fn(),
+  disposeCloudAgent: vi.fn(),
+}));
+
+const observerMocks = vi.hoisted(() => ({
+  sendAndObserve: vi.fn(),
+}));
+
+const modelMocks = vi.hoisted(() => ({
+  resolveModelId: vi.fn(),
+}));
+
+vi.mock("../../src/cursor/agent-factory.js", () => ({
+  createPlanningCloudAgent: factoryMocks.createPlanningCloudAgent,
+  createImplementationCloudAgent: factoryMocks.createImplementationCloudAgent,
+  createRevisionCloudAgent: factoryMocks.createRevisionCloudAgent,
+  createIntegrationRepairCloudAgent: factoryMocks.createIntegrationRepairCloudAgent,
+  disposeCloudAgent: factoryMocks.disposeCloudAgent,
+}));
+
+vi.mock("../../src/cursor/run-observer.js", () => ({
+  sendAndObserve: observerMocks.sendAndObserve,
+}));
+
+vi.mock("../../src/cursor/model.js", () => ({
+  resolveModelId: modelMocks.resolveModelId,
+}));
+
+const TARGET_REPO = "https://github.com/owner/example-target-app";
+
+function makeConfig(overrides: Partial<HarnessConfig> = {}): HarnessConfig {
+  return {
+    version: 1,
+    orchestratorMarker: "harness-orchestrator-v1",
+    logDirectory: "runs",
+    repos: [
+      {
+        id: "target-app",
+        targetRepo: TARGET_REPO,
+        baseBranch: "main",
+        productionBranch: "main",
+      },
+    ],
+    allowedTargetRepos: [TARGET_REPO],
+    ...overrides,
+  } as HarnessConfig;
+}
+
+function mockCursorAgent(id = "agent-1") {
+  return {
+    agentId: id,
+    [Symbol.asyncDispose]: async () => undefined,
+  };
+}
+
+describe("getAgentProvider", () => {
+  it("returns a Cursor provider", () => {
+    const provider = getAgentProvider(makeConfig());
+    expect(provider.id).toBe("cursor");
+  });
+});
+
+describe("cursorAgentProvider", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    factoryMocks.disposeCloudAgent.mockResolvedValue(undefined);
+  });
+
+  it("delegates resolveModelId to cursor model resolution", () => {
+    const config = makeConfig({
+      agentProvider: { id: "cursor", model: { id: "composer-2.5" } },
+      defaultModel: { id: "other-model" },
+    });
+    modelMocks.resolveModelId.mockReturnValue("composer-2.5");
+
+    expect(cursorAgentProvider.resolveModelId(config)).toBe("composer-2.5");
+    expect(modelMocks.resolveModelId).toHaveBeenCalledWith(config);
+  });
+
+  it("delegates createPlanningAgent to createPlanningCloudAgent", async () => {
+    const cursorAgent = mockCursorAgent();
+    factoryMocks.createPlanningCloudAgent.mockResolvedValue(cursorAgent);
+    const config = makeConfig();
+    const params = {
+      apiKey: "key",
+      config,
+      targetRepo: TARGET_REPO,
+      baseBranch: "dev",
+    };
+
+    const handle = await cursorAgentProvider.createPlanningAgent(params);
+
+    expect(factoryMocks.createPlanningCloudAgent).toHaveBeenCalledWith(params);
+    expect(handle).toBeDefined();
+    expect((handle as { __brand?: symbol }).__brand).toBeDefined();
+  });
+
+  it("delegates createImplementationAgent to createImplementationCloudAgent", async () => {
+    factoryMocks.createImplementationCloudAgent.mockResolvedValue(mockCursorAgent());
+    const config = makeConfig();
+    const params = {
+      apiKey: "key",
+      config,
+      targetRepo: TARGET_REPO,
+      baseBranch: "dev",
+    };
+
+    await cursorAgentProvider.createImplementationAgent(params);
+
+    expect(factoryMocks.createImplementationCloudAgent).toHaveBeenCalledWith(params);
+  });
+
+  it("delegates createRevisionAgent to createRevisionCloudAgent", async () => {
+    factoryMocks.createRevisionCloudAgent.mockResolvedValue(mockCursorAgent());
+    const config = makeConfig();
+    const params = {
+      apiKey: "key",
+      config,
+      targetRepo: TARGET_REPO,
+      branch: "cursor/wes-1-test",
+      prUrl: `${TARGET_REPO}/pull/1`,
+    };
+
+    await cursorAgentProvider.createRevisionAgent(params);
+
+    expect(factoryMocks.createRevisionCloudAgent).toHaveBeenCalledWith(params);
+  });
+
+  it("delegates createIntegrationRepairAgent to createIntegrationRepairCloudAgent", async () => {
+    factoryMocks.createIntegrationRepairCloudAgent.mockResolvedValue(mockCursorAgent());
+    const config = makeConfig();
+    const params = {
+      apiKey: "key",
+      config,
+      targetRepo: TARGET_REPO,
+      branch: "cursor/wes-1-test",
+      prUrl: `${TARGET_REPO}/pull/1`,
+    };
+
+    await cursorAgentProvider.createIntegrationRepairAgent(params);
+
+    expect(factoryMocks.createIntegrationRepairCloudAgent).toHaveBeenCalledWith(
+      params,
+    );
+  });
+
+  it("maps ObservedRunResult to ObservedAgentRun without dropping fields", async () => {
+    const cursorAgent = mockCursorAgent();
+    factoryMocks.createPlanningCloudAgent.mockResolvedValue(cursorAgent);
+    observerMocks.sendAndObserve.mockResolvedValue({
+      agentId: "agent-1",
+      runId: "run-1",
+      result: { id: "run-1", status: "completed" },
+      assistantText: "plan output",
+      gitResult: {
+        repoUrl: TARGET_REPO,
+        branch: "cursor/wes-1-test",
+        prUrl: `${TARGET_REPO}/pull/1`,
+      },
+      cancelOutcome: "cancelled",
+    });
+
+    const handle = await cursorAgentProvider.createPlanningAgent({
+      apiKey: "key",
+      config: makeConfig(),
+      targetRepo: TARGET_REPO,
+      baseBranch: "dev",
+    });
+
+    const observed = await cursorAgentProvider.sendAndObserve(
+      handle,
+      "prompt",
+      "/tmp/run",
+      { log: vi.fn() } as never,
+      { phase: "planning", apiKey: "key" },
+    );
+
+    expect(observerMocks.sendAndObserve).toHaveBeenCalledWith(
+      cursorAgent,
+      "prompt",
+      "/tmp/run",
+      expect.anything(),
+      { phase: "planning", apiKey: "key" },
+    );
+    expect(observed).toEqual({
+      agentId: "agent-1",
+      runId: "run-1",
+      assistantText: "plan output",
+      gitResult: {
+        repoUrl: TARGET_REPO,
+        branch: "cursor/wes-1-test",
+        prUrl: `${TARGET_REPO}/pull/1`,
+      },
+      cancelOutcome: "cancelled",
+    });
+  });
+
+  it("delegates disposeAgent to disposeCloudAgent", async () => {
+    const cursorAgent = mockCursorAgent();
+    factoryMocks.createPlanningCloudAgent.mockResolvedValue(cursorAgent);
+    const handle = await cursorAgentProvider.createPlanningAgent({
+      apiKey: "key",
+      config: makeConfig(),
+      targetRepo: TARGET_REPO,
+      baseBranch: "dev",
+    });
+
+    await cursorAgentProvider.disposeAgent(handle);
+
+    expect(factoryMocks.disposeCloudAgent).toHaveBeenCalledWith(cursorAgent);
+  });
+});
+
+describe("src/agents sdk import boundary", () => {
+  it("contains no direct @cursor/sdk imports", async () => {
+    const agentsDir = path.join(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "../../src/agents",
+    );
+    const files = ["types.ts", "provider.ts", "cursor-provider.ts", "index.ts"];
+    for (const file of files) {
+      const contents = await readFile(path.join(agentsDir, file), "utf8");
+      expect(contents).not.toContain("@cursor/sdk");
+    }
+  });
+});

package/workspace-snapshot/files/tests/artifacts/manifest.test.ts

@@ -0,0 +1,54 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { writeManifest, readManifest } from "../../src/artifacts/manifest.js";
+import { emptyMergeManifestFields } from "../../src/artifacts/manifest-fields.js";
+import type { RunManifest } from "../../src/types/run.js";
+
+describe("manifest writer", () => {
+  it("round-trips manifest with required M1 fields", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "harness-manifest-"));
+    const manifest: RunManifest = {
+      runId: "2026-07-06T20-30-00Z-WES-11",
+      issueKey: "WES-11",
+      phase: "implementation",
+      phaseInferredFromStatus: "Ready for Build",
+      linearStatusBefore: "Ready for Planning",
+      linearStatusAfter: "Ready for Planning",
+      targetRepo: "https://github.com/owner/example-target-app",
+      baseBranch: "main",
+      resolutionSource: "explicit",
+      dryRun: true,
+      finalOutcome: "success",
+      errorClassification: null,
+      startedAt: "2026-07-06T20:30:00.000Z",
+      finishedAt: "2026-07-06T20:30:01.000Z",
+      milestone: "m1",
+      promptVersion: null,
+      cursorAgentId: null,
+      cursorRunId: null,
+      branch: null,
+      prUrl: null,
+      previewUrl: null,
+      validationSummary: null,
+      changedFiles: null,
+      checkSummary: null,
+      previousImplementationRunId: null,
+      previousHandoffRunId: null,
+      pmFeedbackCommentId: null,
+      ...emptyMergeManifestFields(),
+      model: null,
+    };
+
+    await writeManifest(dir, manifest);
+    const raw = await readFile(path.join(dir, "manifest.json"), "utf8");
+    expect(raw).toContain('"milestone": "m1"');
+
+    const loaded = await readManifest(dir);
+    expect(loaded.runId).toBe(manifest.runId);
+    expect(loaded.finalOutcome).toBe("success");
+
+    await rm(dir, { recursive: true, force: true });
+  });
+});

package/workspace-snapshot/files/tests/artifacts/redact.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { redactSecrets, redactSecretsString } from "../../src/artifacts/redact.js";
+
+describe("redactSecretsString", () => {
+  it("redacts Linear API keys", () => {
+    const input = "auth failed: lin_api_abc123xyz";
+    expect(redactSecretsString(input)).toBe("auth failed: [REDACTED]");
+  });
+
+  it("redacts GitHub PATs", () => {
+    const input = "token ghp_abcdefghijklmnopqrstuvwxyz1234567890";
+    expect(redactSecretsString(input)).toContain("[REDACTED]");
+    expect(redactSecretsString(input)).not.toContain("ghp_");
+  });
+
+  it("redacts Bearer tokens", () => {
+    const input = "Authorization: Bearer eyJhbGciOi.test";
+    expect(redactSecretsString(input)).toContain("[REDACTED]");
+  });
+
+  it("truncates long error bodies", () => {
+    const input = `error: ${"x".repeat(300)}`;
+    expect(redactSecretsString(input).length).toBeLessThanOrEqual(201);
+  });
+});
+
+describe("redactSecrets", () => {
+  it("redacts sensitive object keys", () => {
+    const result = redactSecrets({
+      apiKey: "lin_api_secret",
+      nested: { token: "ghp_test" },
+      safe: "visible",
+    }) as Record<string, unknown>;
+
+    expect(result.apiKey).toBe("[REDACTED]");
+    expect(result.nested).toEqual({ token: "[REDACTED]" });
+    expect(result.safe).toBe("visible");
+  });
+
+  it("redacts token patterns in string values", () => {
+    const result = redactSecrets({
+      message: "failed with ghp_abcdefghijklmnopqrstuvwxyz1234567890",
+    }) as Record<string, unknown>;
+
+    expect(result.message).toContain("[REDACTED]");
+  });
+});