p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/docs/linear-watcher-setup.md

@@ -0,0 +1,184 @@
+# Linear watcher setup
+
+Operator guide for the v0.3.0 event-driven auto-runner.
+
+**Related:** [`docs/milestones/m8-linear-watcher.md`](milestones/m8-linear-watcher.md), [`ARCHITECTURE.md`](../ARCHITECTURE.md), [`docs/security.md`](security.md), [`docs/releases/v0.3.0.md`](releases/v0.3.0.md)
+
+---
+
+## Overview
+
+When a Linear issue moves to an **actionable trigger status**, the harness runs automatically in GitHub Actions — no local `npm run harness:run` required.
+
+```text
+Linear webhook → Vercel bridge → GitHub repository_dispatch → GitHub Actions → harness --phase auto
+```
+
+---
+
+## 1. Vercel webhook bridge
+
+### Create Vercel project
+
+1. Link this repo to Vercel (production branch: `main`).
+2. Deploy; endpoint path is `/api/linear-webhook`.
+
+### Vercel environment variables (Production)
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| `LINEAR_WEBHOOK_SECRET` | yes | From Linear webhook signing secret |
+| `GITHUB_DISPATCH_TOKEN` | yes | See [GitHub dispatch token](#github-dispatch-token) |
+| `GITHUB_DISPATCH_REPOSITORY` | no | Default: `weston-uribe/agentic-product-development-harness` |
+| `GITHUB_DISPATCH_EVENT_TYPE` | no | Default: `linear_issue_status_changed` |
+| `LINEAR_WEBHOOK_TIMESTAMP_TOLERANCE_MS` | no | Default: `60000` |
+| `HARNESS_TEAM_KEY` | **yes in production** | Set to `WES` — reject non-team issue keys |
+
+**Do not** put `LINEAR_API_KEY`, `CURSOR_API_KEY`, or merge-capable `GITHUB_TOKEN` in Vercel. See [`docs/security.md`](security.md) for the full token matrix.
+
+### GitHub dispatch token
+
+`GITHUB_DISPATCH_TOKEN` must be able to call `POST /repos/{owner}/{repo}/dispatches`:
+
+| PAT type | Required permission |
+|----------|---------------------|
+| **Fine-grained** | **Contents: write** on `weston-uribe/agentic-product-development-harness` only |
+| **Classic** | **`repo` scope** |
+
+- Contents: read is **not** sufficient.
+- Scope the token to the harness repo only (fine-grained PAT).
+- This token triggers workflows; it does not need access to target repos.
+
+---
+
+## 2. GitHub Actions secrets
+
+In repo **Settings → Secrets and variables → Actions**:
+
+| Secret | Used by |
+|--------|---------|
+| `LINEAR_API_KEY` | All live harness phases |
+| `CURSOR_API_KEY` | planning, implementation, revision, merge repair fallback |
+| `HARNESS_GITHUB_TOKEN` | handoff, revision, merge — mapped to runtime `GITHUB_TOKEN` in the workflow |
+
+`HARNESS_GITHUB_TOKEN` must be a PAT with access to **target repos** used by the harness (e.g. target-app), including classic `repo` scope or equivalent fine-grained permissions for PR read, checks, merge, and PR branch repair. Fine-grained PATs need **Contents: Read and write** plus **Pull requests: Read and write** on target repos.
+
+Run `npm run harness:doctor -- --profile merge` with `GITHUB_TOKEN` set before enabling merge automation. Doctor verifies target base branches and token write permission used by integration repair.
+
+Do **not** name the Actions secret `GITHUB_TOKEN` — GitHub reserves that name for the auto-generated workflow token. The workflow maps `HARNESS_GITHUB_TOKEN` → `env: GITHUB_TOKEN` for the harness CLI.
+
+---
+
+## 3. Linear webhook
+
+1. Linear → **Settings → API → Webhooks → New webhook**
+2. URL: `https://<vercel-project>.vercel.app/api/linear-webhook`
+3. Team: WES (or all public teams)
+4. Resource types: **Issue** only
+5. Copy signing secret → Vercel `LINEAR_WEBHOOK_SECRET`
+
+### Dispatch allowlist (bridge filter)
+
+The webhook **only dispatches GitHub Actions** when the issue's **current status** is:
+
+- Ready for Planning
+- Ready for Build
+- PR Open
+- Needs Revision
+- Ready to Merge
+
+All other statuses return HTTP 200 with `{ "accepted": false, "reason": "ignored_status" }` and **do not** start GHA. This includes transitional statuses the harness sets itself (Planning, Building, PM Review, Merging, Merged / Deployed).
+
+Harness-initiated **Building → PR Open** still dispatches because `PR Open` is allowlisted.
+
+---
+
+## 4. Manual validation gates
+
+### Gate 1: Local / unit tests
+
+```bash
+npm install
+npm test
+npm run build
+npm run generate:config-schema
+npm run harness:doctor
+```
+
+Requires local `.env` with harness secrets for doctor checks.
+
+### Gate 2: workflow_dispatch
+
+1. Confirm GHA secrets are set.
+2. Actions → **Harness Auto Runner** → Run workflow.
+3. Input: `issue=WES-XX`, `phase=auto`.
+4. Confirm harness runs in cloud; download artifact with `runs/WES-XX/<run-id>/`.
+
+For canceled or stuck integration repair while the issue is **Merging**, use `workflow_dispatch` with `issue=WES-XX`, `phase=merge`, and `force=true`. v1 intentionally does not dispatch from **Merging** automatically.
+
+### Gate 3: repository_dispatch
+
+```bash
+gh api repos/weston-uribe/agentic-product-development-harness/dispatches \
+  -f event_type=linear_issue_status_changed \
+  -f client_payload[issueKey]=WES-XX \
+  -f client_payload[statusName]="Ready for Planning" \
+  -f client_payload[linearDeliveryId]=manual-test-1 \
+  -f client_payload[receivedAt]=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+
+Confirm GHA run starts and executes `harness:run --phase auto`.
+
+Use a PAT with Contents: write (fine-grained) or `repo` scope (classic).
+
+### Gate 4: Linear webhook live
+
+1. Deploy Vercel endpoint; configure Linear Issue webhook.
+2. Move test issue **Backlog → Ready for Planning** (or **Ready for Build**).
+3. Confirm Vercel log shows dispatch; GHA run starts; harness executes correct phase.
+4. Duplicate delivery: confirm idempotent skip, no harmful duplicate work.
+5. **Negative — PM Review:** After handoff, confirm `{ "reason": "ignored_status" }` and **no GHA run**.
+6. **Negative — Planning/Building:** Harness moves to transitional status; confirm `ignored_status`, no GHA.
+7. **Negative — title edit:** Edit title only; confirm `ignored_event`, no GHA.
+
+---
+
+## 5. Local webhook testing
+
+```bash
+# Sign a fixture body
+BODY=$(cat tests/fixtures/webhook/issue-ready-for-planning.json)
+SIG=$(node -e "const c=require('crypto');console.log(c.createHmac('sha256',process.env.LINEAR_WEBHOOK_SECRET).update(process.argv[1]).digest('hex'))" "$BODY")
+
+curl -X POST http://localhost:3000/api/linear-webhook \
+  -H "Content-Type: application/json" \
+  -H "Linear-Signature: $SIG" \
+  -H "Linear-Delivery: test-uuid" \
+  -H "Linear-Event: Issue" \
+  -H "Linear-Timestamp: 1700000000000" \
+  -d "$BODY"
+```
+
+Use `vercel dev` for local endpoint testing.
+
+---
+
+## 6. Recovery
+
+| Scenario | Recovery |
+|----------|----------|
+| GHA run failed after successful dispatch | Re-run via `workflow_dispatch` with same issue key |
+| Dispatch failed (webhook 500) | Linear retries automatically; fix token/repo config |
+| Wrong phase / stuck issue | Manual status change to allowlisted trigger status |
+
+---
+
+## 7. Failure responses (webhook)
+
+| HTTP | Body | Meaning |
+|------|------|---------|
+| 401 | `invalid_signature` / `timestamp_out_of_tolerance` | Reject; fix secret or clock |
+| 200 | `ignored_status` | Expected for non-trigger statuses |
+| 200 | `ignored_event` | Non-Issue or no status change |
+| 200 | `missing_issue_key` | Payload unusable; check Linear config |
+| 500 | `dispatch_failed` | GitHub dispatch failed; Linear will retry |

package/workspace-snapshot/files/docs/milestones/m1-runner-foundation.md

@@ -0,0 +1,51 @@
+# Milestone 1 — Runner foundation
+
+**Status:** Implemented (dry-run path only)
+
+## What exists
+
+- TypeScript CLI: `doctor`, `run --dry-run`, `inspect`
+- `harness.config.json` with Zod validation and `allowedTargetRepos` allowlist
+- Linear issue description parser (required sections + Target repo fallback)
+- Target repo resolver (explicit field → project/team mapping → denial)
+- Run artifacts under `runs/<issue>/<run-id>/` (gitignored)
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run harness:doctor
+npm run harness:run -- --issue WES-FIXTURE --dry-run --fixture tests/fixtures/issues/valid-target-app.md
+npm run harness:inspect -- --run runs/WES-FIXTURE/<run-id>
+```
+
+Live Linear dry-run is optional when `LINEAR_API_KEY` is set in `.env`.
+
+## Required issue headers
+
+- `## Target repo` (preferred) or `Target repo:` under Context and links
+- `## Task` or `## Problem`
+- `## Acceptance criteria`
+- `## Out of scope`
+- `## Validation expectations` (optional)
+
+## Deferred to later milestones
+
+- Cursor SDK agent launch
+- Linear status transitions and comments
+- GitHub PR discovery and Vercel preview capture
+- `harness:watch` poller
+- Revision and merge/deploy loops
+
+## Authoritative workspace
+
+Use `/Users/weston/Code/agentic-product-development-harness` (not the stale `.cursor` workspace clone).
+
+## Config schema
+
+Zod schema: `src/config/schema.ts`. Regenerate JSON Schema (optional):
+
+```bash
+npm run generate:config-schema
+```

package/workspace-snapshot/files/docs/milestones/m2-planning-phase.md

@@ -0,0 +1,129 @@
+# Milestone 2 — Planning phase
+
+**Status:** Implemented (live planning path; no implementation agent)
+
+## What exists
+
+- Live planning orchestration triggered from Linear **Ready for Planning**
+- Cursor SDK **cloud** planning agent against the resolved target repo (not harness cwd)
+- Linear status transitions: **Planning** → **Ready for Build** (or **Blocked** on failure after entering Planning)
+- Planning comment posted to Linear with harness marker footer
+- Idempotency guard via marker footer (`harness-orchestrator-v1`, `phase: planning`, `run_id`, cursor IDs, model, target repo)
+- Extended artifacts, manifest fields, and JSONL events for planning runs
+- Doctor checks `CURSOR_API_KEY` (required for live planning); model/repo listing is warn-only
+
+## What is deferred
+
+- Implementation / build phase agent
+- Branch creation, PR open, preview capture, watcher poller
+- Revision and merge/deploy loops
+
+## Prerequisites
+
+1. Copy `.env.example` to `.env` and set:
+   - `LINEAR_API_KEY`
+   - `CURSOR_API_KEY`
+2. Target repo must be connected in Cursor cloud settings (validated by live planning run; doctor warns if `Cursor.repositories.list()` is unavailable).
+3. Linear issue must include required sections (see Milestone 1 docs) and be in **Ready for Planning**.
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+
+# Config and auth checks
+npm run harness:doctor
+
+# M1 regression (fixture, no network)
+npm run harness:run -- --issue WES-FIXTURE --dry-run \
+  --fixture tests/fixtures/issues/valid-target-app.md
+
+# Optional live preflight (read-only)
+npm run harness:run -- --issue WES-XX --dry-run
+
+# Live planning (manual integration gate)
+npm run harness:run -- --issue WES-XX --phase planning
+
+# Auto phase infers planning from issue status
+npm run harness:run -- --issue WES-XX
+
+# Re-run after partial failure (issue stuck in Planning)
+npm run harness:run -- --issue WES-XX --phase planning --force
+
+# Inspect artifacts
+npm run harness:inspect -- --run runs/WES-XX/<run-id>
+```
+
+## Manual target-app integration test
+
+Create a Linear issue in **Ready for Planning** targeting the target repo.
+
+**Suggested task (planning-only, harmless):**
+
+> Plan adding a temporary Hello World page and top-nav link. Do not implement.
+
+**Required sections:** Target repo, Task, Acceptance criteria, Out of scope
+
+**Run:**
+
+```bash
+npm run harness:run -- --issue WES-XX --phase planning
+```
+
+**Pass criteria:**
+
+- Linear issue moves to **Ready for Build**
+- One planning comment with full marker footer
+- `runs/WES-XX/<run-id>/manifest.json` has `cursorAgentId`, `cursorRunId`, `finalOutcome: success`
+- No PR or branch on the target repo
+- Re-run without `--force` exits with duplicate skip and does not post a new comment
+
+## Artifacts (planning run)
+
+```text
+runs/<issue>/<run-id>/
+  manifest.json
+  run-summary.md
+  events.jsonl
+  linear/
+    issue-snapshot-before.json
+    issue-snapshot-after.json
+    comments-written.md
+  prompts/
+    planning-agent.md
+  outputs/
+    planning-result.md
+  cursor/
+    run-result.json
+  errors/
+    error.json                 # on failure
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success or duplicate skip |
+| 1 | Config / CLI error |
+| 2 | Preflight failure (parse, resolver, allowlist) |
+| 3 | Planning phase failure after eligible start |
+
+## Authoritative workspace
+
+Use `/Users/weston/Code/agentic-product-development-harness` (not the stale `.cursor` workspace clone).
+
+## Config
+
+`harness.config.json` adds:
+
+- `defaultModel` — Cursor model for planning agent
+- `linear.transitionalStatuses.readyForBuild` — post-planning status
+- `planning.timeoutSeconds` — cloud agent wait timeout (default 1800)
+
+Regenerate JSON Schema (optional):
+
+```bash
+npm run generate:config-schema
+```

package/workspace-snapshot/files/docs/milestones/m3-implementation-phase.md

@@ -0,0 +1,158 @@
+# Milestone 3 — Implementation phase
+
+**Status:** Implemented (live implementation path; no preview/revision/merge loop)
+
+## What exists
+
+- Live implementation orchestration triggered from Linear **Ready for Build**
+- Optional loading of the latest durable planning comment
+- Cursor SDK **cloud** implementation agent against the resolved target repo
+- Linear status transitions: **Building** → **PR Open** (or **Blocked** after entering Building)
+- Branch and PR capture from Cursor SDK git metadata
+- Implementation summary comment posted to Linear with harness marker footer
+- Extended artifacts, manifest fields, and JSONL events for implementation runs
+
+## What is deferred
+
+- Vercel preview capture
+- PM Review transition
+- Revision loop
+- Watcher/poller
+- Merge/deploy automation
+- Releases and skills
+
+## Prerequisites
+
+1. Copy `.env.example` to `.env` and set:
+   - `LINEAR_API_KEY`
+   - `CURSOR_API_KEY`
+2. Target repo must be connected in Cursor cloud settings.
+3. Linear issue must include required sections and be in **Ready for Build**.
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+
+# Config and auth checks
+npm run harness:doctor
+
+# M1 regression (fixture, no network)
+npm run harness:run -- --issue WES-FIXTURE --dry-run \
+  --fixture tests/fixtures/issues/valid-target-app.md
+
+# Live implementation
+npm run harness:run -- --issue WES-12 --phase implementation
+
+# Auto phase infers implementation from Ready for Build
+npm run harness:run -- --issue WES-12
+
+# Retry after partial failure when issue is stuck in Building
+npm run harness:run -- --issue WES-12 --phase implementation --force
+
+# Inspect artifacts
+npm run harness:inspect -- --run runs/WES-12/<run-id>
+```
+
+## Manual target-app integration gate
+
+Do **not** use WES-11. WES-11 was the Milestone 2 planning-only gate and explicitly prohibited implementation, branches, and PRs.
+
+Create a new Linear issue, likely **WES-12**.
+
+**Title:** M3 implementation integration test — target app hello world
+
+**Status:** Ready for Build
+
+**Labels:** `harness`, `target-app`, `implementation-agent`
+
+**Description:**
+
+```markdown
+## Target repo
+owner/example-target-app
+
+## Task
+Add a temporary Hello World page to the target app and add a top-nav link to that page.
+
+## Acceptance criteria
+- [ ] A temporary Hello World page exists in the target app
+- [ ] A visible top-nav link opens the Hello World page
+- [ ] The change is narrow and reversible
+- [ ] Validation commands are run
+- [ ] A PR is opened against the target repo
+- [ ] No merge is performed
+- [ ] No preview capture or PM Review transition is required in this milestone
+
+## Out of scope
+- [ ] Merging the PR
+- [ ] Capturing Vercel preview
+- [ ] Moving the issue to PM Review
+- [ ] Revision loop
+- [ ] Merge/deploy automation
+- [ ] Editing the harness repo except through orchestrator code
+- [ ] Releases
+- [ ] Skills
+
+## Validation expectations
+Run the target repo validation commands from harness config, expected to include npm run lint and npm run build if available.
+```
+
+**Pass criteria:**
+
+- Issue moves **Ready for Build** → **Building** → **PR Open**
+- PR opens against `owner/example-target-app`
+- Branch matches `cursor/<issue-key>-*`
+- One implementation comment includes marker footer with `branch` and `pr_url`
+- `manifest.json` has `finalOutcome: success`, `branch`, `prUrl`, `cursorAgentId`, `cursorRunId`
+- No merge, PM Review transition, or preview capture
+- Re-run without `--force` exits with duplicate skip
+
+## Artifacts
+
+```text
+runs/<issue>/<run-id>/
+  manifest.json
+  run-summary.md
+  events.jsonl
+  linear/
+    issue-snapshot-before.json
+    issue-snapshot-after.json
+    planning-comment-loaded.md
+    comments-written.md
+  prompts/
+    implementation-agent.md
+  outputs/
+    implementation-result.md
+  cursor/
+    run-result.json
+  github/
+    pr-metadata.json
+  errors/
+    error.json                 # on failure
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success or duplicate skip |
+| 1 | Config / CLI error |
+| 2 | Preflight or eligibility failure |
+| 3 | Live phase failure after eligible start |
+
+## Config
+
+`harness.config.json` includes:
+
+- `implementation.timeoutSeconds` — cloud agent wait timeout
+- `implementation.branchPrefix` — deterministic branch prefix
+- `repos[].validation.commands` — target-repo validation commands included in the implementation prompt
+
+Regenerate JSON Schema after config changes:
+
+```bash
+npm run generate:config-schema
+```

package/workspace-snapshot/files/docs/milestones/m4-handoff-phase.md

@@ -0,0 +1,122 @@
+# Milestone 4 — Handoff phase
+
+**Status:** Implemented (PR Open → PM Review handoff; no revision loop or merge)
+
+## What exists
+
+- Live handoff orchestration triggered from Linear **PR Open**
+- Reads the latest durable **implementation** marker comment for `pr_url`, `branch`, and `target_repo`
+- Inspects the linked GitHub PR via REST API (`GITHUB_TOKEN` required)
+- Captures Vercel preview URL from PR comments when available (bounded polling)
+- Posts PM handoff comment to Linear with harness marker footer
+- Linear status transition: **PR Open** → **PM Review** (or **Blocked** after handoff begins on failure)
+- Extended artifacts, manifest fields, and JSONL events for handoff runs
+- Auto phase routing: **PR Open** → `handoff` (not implementation)
+
+## What is deferred
+
+- Revision loop (**Needs Revision** → **Revising** → **PM Review**)
+- Engineering Review transition
+- Merge/deploy automation
+- Watcher/poller
+- Releases and skills
+
+## Prerequisites
+
+1. Copy `.env.example` to `.env` and set:
+   - `LINEAR_API_KEY`
+   - **`GITHUB_TOKEN`** (required for handoff — `repo` or fine-grained PR read scope)
+2. Issue must be in **PR Open** with a prior implementation marker comment containing `pr_url`.
+3. `CURSOR_API_KEY` is **not** required for handoff runs.
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+
+# Config and auth checks (GITHUB_TOKEN required under M4)
+npm run harness:doctor
+
+# Live handoff
+npm run harness:run -- --issue WES-13 --phase handoff
+
+# Auto phase infers handoff from PR Open
+npm run harness:run -- --issue WES-13
+
+# Inspect artifacts
+npm run harness:inspect -- --run runs/WES-13/<run-id>
+```
+
+## Manual integration gate
+
+**Issue:** WES-13 (starts **PR Open**)
+
+**PR:** [target repo PR #4](https://github.com/owner/example-target-app/pull/4) (open, unmerged)
+
+**Pass criteria:**
+
+- WES-13: PR Open → PM Review
+- Exactly one new handoff comment with marker footer (`phase: handoff`, `pr_url`, `branch`, `preview_url` if found, `previous_implementation_run_id`)
+- `manifest.json`: `finalOutcome: success`, populated `prUrl`, `branch`, `changedFiles`, `checkSummary`
+- Artifacts: `github/pr.json`, `linear/handoff-comment.md`, `vercel/deployment.json` (if preview captured)
+- PR #4 remains **open**, **unmerged**
+- Re-run without `--force` → duplicate skip (exit 0)
+
+**Do not:** merge PR #4, rerun WES-12, modify target repo manually, move to Engineering Review.
+
+## Artifacts
+
+```text
+runs/<issue>/<run-id>/
+  manifest.json
+  run-summary.md
+  events.jsonl
+  linear/
+    issue-snapshot-before.json
+    issue-snapshot-after.json
+    implementation-comment-loaded.md
+    handoff-comment.md
+    comments-written.md
+  github/
+    pr.json
+    checks.json
+  vercel/
+    deployment.json
+  errors/
+    error.json                 # on failure
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success or duplicate skip |
+| 1 | Config / CLI error |
+| 2 | Preflight, eligibility, or auth failure (no Linear writes when auth fails at start) |
+| 3 | Live phase failure after handoff began |
+
+## Config
+
+`harness.config.json` includes:
+
+- `handoff.allowPmReviewWithoutPreview` — proceed to PM Review when preview is not found (default: `true`)
+- `preview.pollTimeoutSeconds` — max wait for Vercel preview comment
+- `preview.pollIntervalSeconds` — poll interval between comment fetches
+- `linear.eligibleStatuses.handoff` — statuses eligible for handoff (default: PR Open)
+
+Regenerate JSON Schema after config changes:
+
+```bash
+npm run generate:config-schema
+```
+
+## GITHUB_TOKEN
+
+Handoff requires a valid GitHub token before any Linear writes:
+
+- `harness:doctor` fails when `GITHUB_TOKEN` is missing or invalid
+- Handoff preflight returns exit code 2 with `github_auth_failure` when the token is absent at run start
+
+Recommended scopes: classic `repo` or fine-grained token with read access to pull requests and checks for the target repository.