p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/docs/p-dev.md

@@ -0,0 +1,213 @@
+# p-dev — Product Development Harness CLI
+
+**Canonical end-user guide** for the public `p-dev-harness` npm package.
+
+The operator product is still called **p-dev**. The npm package is published as **`p-dev-harness`** because the registry rejected `p-dev` as too similar to the existing [`pdev`](https://www.npmjs.com/package/pdev) package.
+
+`p-dev` launches the guided **Configure GUI** without cloning the harness source repository. It is the primary product-manager path for **v0.3.1**.
+
+## What p-dev is
+
+`p-dev` is a packaged operator shell for the Product Development Harness. It:
+
+- starts the seven-step Configure GUI locally
+- stores durable operator state under a workspace directory
+- can provision or reconnect a private `OWNER/p-dev-harness` workspace from the **embedded package snapshot** (0.3.1+) or reconnect legacy 0.3.0 managed workspaces
+- guides service credentials, Linear workspace/status setup, Vercel webhook bridge, target repos, local files, cloud secrets, and target workflow finalization
+
+It does **not** replace the source repository for harness development or contribution.
+
+## Supported environment
+
+| Requirement | Detail |
+|-------------|--------|
+| Node.js | **22+** required |
+| Packaged platform | **macOS validated** for browser auto-launch |
+| Agent provider | **Cursor only** (implemented) |
+| Control plane | **Linear + GitHub + GitHub Actions + Vercel** (supported stack) |
+| Maturity | Early-stage operator tool — **not** production SaaS |
+
+On non-macOS platforms, use `--no-open` and open the printed Configure URL manually. Browser auto-launch is not validated outside macOS.
+
+## Install and launch
+
+Pinned release:
+
+```bash
+npx --yes p-dev-harness@0.3.1
+```
+
+Latest channel:
+
+```bash
+npx --yes p-dev-harness
+```
+
+Do not open a browser automatically:
+
+```bash
+npx --yes p-dev-harness@0.3.1 --no-open
+```
+
+Use a custom workspace directory:
+
+```bash
+npx --yes p-dev-harness@0.3.1 --workspace /path/to/workspace
+```
+
+Or set `P_DEV_HOME`:
+
+```bash
+export P_DEV_HOME=/path/to/workspace
+npx --yes p-dev-harness@0.3.1
+```
+
+Default workspace when neither flag nor env is set: `~/.p-dev`.
+
+## Workspace and local state
+
+Workspace resolution priority: `--workspace` → `P_DEV_HOME` → `~/.p-dev`.
+
+The workspace is durable operator state. Typical files:
+
+| Path | Purpose |
+|------|---------|
+| `.env.local` | Local secrets and config pointer (gitignored pattern) |
+| `.harness/config.local.json` | Operator harness config |
+| `.harness/p-dev-managed-repo.json` | Managed private harness workspace marker (when provisioned) |
+
+`p-dev` seeds safe templates (`.env.example`, `.harness/config.example.json`) **without overwriting** existing operator files. Package preparation and npm install do **not** overwrite an existing workspace.
+
+## Required credentials
+
+You need accounts and API keys for:
+
+- **Linear** — workspace/team/project and workflow statuses
+- **Cursor** — cloud agent API key
+- **GitHub** — classic personal access token for packaged provisioning and remote setup
+- **Vercel** — team/project for the webhook bridge (when using cloud automation)
+
+### GitHub token permissions (derived from implementation)
+
+**Packaged workspace provisioning (Step 1, packaged mode only):**
+
+- Classic PAT required — fine-grained tokens are **not** supported for automatic provisioning
+- Scopes: **`repo`** and **`workflow`**
+- `public_repo` alone is insufficient for private workspace creation
+
+**Guided setup generally:**
+
+- Classic PAT: **`repo`** (or `public_repo` for public repos) and **`workflow`**
+- Fine-grained PAT: **Contents write** plus **Workflows write** on each target repo (workflow write is confirmed per repo in later steps; GitHub does not expose a dedicated read-only workflow-write API)
+
+Step 1 helper text: *"Use a classic GitHub personal access token with repo and workflow access. This lets the harness check your repos, save encrypted setup secrets, and open workflow install PRs later."*
+
+Do not commit tokens. Secret values never belong in docs, git, or PR comments.
+
+## Embedded workspace snapshot (0.3.1+)
+
+Fresh private harness workspaces are provisioned from the **immutable embedded workspace snapshot** inside the exact `p-dev-harness@X.Y.Z` npm package you install:
+
+- Snapshot manifest: `workspace-snapshot/manifest.json` in the published tarball
+- Provisioning uses GitHub git object APIs (`createUserRepository` + blob/tree/commit)
+- Marker v3 records `createdFromPackageSnapshot` provenance tied to the embedded manifest
+- Package version and snapshot identity are bound — reinstalling a different package version does not silently rewrite an existing workspace
+
+**First-time provisioning can take several minutes** while hundreds of snapshot blobs upload. Configure shows upload progress. If GitHub rate-limits the upload, the harness coordinates a shared pause and retries automatically.
+
+Optional advanced override: `HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY` (integer `1`–`4`; default `2`). Ordinary users do not need to set this.
+
+### Legacy 0.3.0 reconnect
+
+Valid existing managed workspaces created by `p-dev-harness@0.3.0` from `weston-uribe/p-dev-harness-template` reconnect without content rewrite. The public template is a **frozen legacy compatibility artifact** for 0.3.0 only — it is not used for 0.3.1+ fresh provisioning and does not need to remain available for new 0.3.1 installs.
+
+## Seven guided setup stages
+
+| Step | Title | What it does |
+|------|-------|--------------|
+| 1 | Connect services | Verify and save Linear, Cursor, GitHub, Vercel credentials; packaged mode may provision private harness workspace |
+| 2 | Set up Linear workspace | Create/map team, project, and required workflow statuses (confirmation-gated) |
+| 3 | Set up Vercel webhook bridge | Create/map Vercel resources, upsert env vars, configure Linear webhook, trigger production redeploy, verify signed webhook |
+| 4 | Choose target repo(s) | Select targets and create local setup files (confirmation-gated local writes) |
+| 5 | Check local readiness | Validate local config and permissions before cloud writes |
+| 6 | Connect cloud secrets | Write harness repo GitHub Actions secrets (confirmation-gated) |
+| 7 | Install target repo workflow | Create/reuse workflow install PR, validate checks, guarded merge, verify on production branch |
+
+Remote mutations require explicit confirmation and fingerprint checks. Step 1 does **not** auto-advance when keys become complete — click **Continue**.
+
+### Step 7 workflow finalization
+
+For harness-owned setup PRs, Step 7:
+
+- creates or updates `.github/workflows/trigger-harness-production-sync.yml` on an install branch
+- opens or reuses a PR (never writes directly to production)
+- polls required checks
+- merges automatically when checks pass and content is valid
+- verifies the workflow exists on the production branch after merge
+
+This automation applies to **system-owned setup PRs only**. Ordinary product implementation PRs remain governed by Linear status gates and are not made generically auto-mergeable.
+
+## Stop, restart, and resume
+
+- Stop: `Ctrl+C` in the terminal running `p-dev`
+- Restart: run the same `npx` command again
+- Resume: use the same workspace (`P_DEV_HOME` or `--workspace`); seeded and applied files are preserved
+
+## Troubleshooting
+
+| Symptom | Action |
+|---------|--------|
+| `ENOSPC` from npm `_npx` cache | Free disk space or clear npm cache — **do not delete `~/.p-dev`** unless you intend to reset operator state |
+| Browser does not open | Use `--no-open` and open the printed URL manually |
+| Step 6 blocked | Ensure harness dispatch repo is resolved (packaged provisioning or explicit config) |
+| Fine-grained PAT at Step 1 | Use classic `repo` + `workflow` for packaged provisioning; fine-grained may work for later steps with per-repo permissions |
+| Slow first provisioning | Normal for 0.3.1+ snapshot upload; wait for progress to complete; rate-limit pauses retry automatically |
+| Port in use | `p-dev` scans from port 3000; use the URL printed in the terminal |
+
+### Uninstall npm execution artifacts without deleting operator state
+
+To clear cached npx execution without removing `~/.p-dev`:
+
+```bash
+npm cache clean --force
+```
+
+Operator workspace files under `P_DEV_HOME` or `~/.p-dev` are separate from npm cache.
+
+## Security boundaries
+
+- Secrets live in local workspace files, GitHub Actions secrets, and Vercel env vars — never in the published package
+- Remote writes are confirmation-gated with fingerprint validation
+- Harness output is redacted before logs and artifacts
+- The published tarball excludes `.env.local`, local config, control-plane state, credentials, and generated private workspace content
+
+## Known limitations
+
+- **Cursor-only** agent provider
+- **Linear / GitHub / GitHub Actions / Vercel** stack only
+- **macOS validated** for packaged browser auto-launch; other platforms use `--no-open`
+- **No full real issue lifecycle** has been run from an isolated npm-installed workspace — setup completion is validated; end-to-end issue runs from a fresh npm install are not
+- **No automatic upgrade/sync** of an already-created private harness workspace to a newer package snapshot
+- **Not production-grade SaaS** or provider-agnostic
+- Manual eval rubrics remain where automation is not implemented
+
+## Source development path
+
+Contributors and harness maintainers should clone the source repository:
+
+```bash
+git clone https://github.com/weston-uribe/agentic-product-development-harness.git
+cd agentic-product-development-harness
+npm ci && npm run build
+npm run harness:configure
+```
+
+See [`docs/getting-started.md`](getting-started.md) and [`README.md`](../README.md).
+
+## Related docs
+
+- Release contract: [`docs/releases/v0.3.1.md`](releases/v0.3.1.md)
+- Local GUI (source): [`docs/gui-local.md`](gui-local.md)
+- Remote setup: [`docs/gui-remote-setup.md`](gui-remote-setup.md)
+- Security: [`docs/security.md`](security.md)
+- Historical packaging spike notes: [`docs/npm-packaging-spike.md`](npm-packaging-spike.md)

package/workspace-snapshot/files/docs/production-sync-automation.md

@@ -0,0 +1,176 @@
+# Production sync automation
+
+Operator guide for automatic production sync after a target repo integration branch is promoted to production.
+
+**Related:** [`docs/target-repo-branch-setup.md`](target-repo-branch-setup.md), [`docs/linear-watcher-setup.md`](linear-watcher-setup.md), [`docs/operator-config.md`](operator-config.md), [`docs/releases/v0.3.0.md`](releases/v0.3.0.md)
+
+---
+
+## Overview
+
+When `owner/example-target-app` **`main`** receives a push (after manual integration branch → production branch promotion), the harness should run production sync automatically:
+
+```text
+target repo push to main → repository_dispatch production_promoted → harness GHA → harness:sync-production --repo target-app
+```
+
+Powerful tokens stay in the **harness repo** GitHub Actions secrets only. The target repo receives at most **`HARNESS_DISPATCH_TOKEN`** (dispatch-only PAT scoped to the harness repo).
+
+Manual CLI remains supported:
+
+```bash
+npm run harness:sync-production -- --repo target-app
+```
+
+---
+
+## Workflow scope preflight
+
+Any add or update under `.github/workflows/**` may require a git credential with GitHub **`workflow` scope**. Before pushing workflow files:
+
+1. Run `gh auth status` and confirm scopes include `workflow`, **or**
+2. Apply workflow YAML via GitHub web UI (Settings → Actions → workflow editor / “Add file”), **or**
+3. Push with a PAT that includes `workflow` + `repo`.
+
+If workflow files cannot be pushed, use the exact YAML below via GitHub UI. Do **not** leave untracked workflow files in a local clone.
+
+---
+
+## Harness repo: `harness-auto-runner.yml`
+
+**Operator config:** set GitHub Actions secret **`HARNESS_CONFIG_JSON_B64`** with your private harness config so sync accepts your target repo ids. See [`docs/operator-config.md`](operator-config.md).
+
+**Track A:** merge the updated workflow to [`.github/workflows/harness-auto-runner.yml`](../.github/workflows/harness-auto-runner.yml) using a credential with **`workflow` scope**.
+
+**Track B (OAuth lacks `workflow` scope):** copy the full intended workflow from [`tests/fixtures/workflows/harness-auto-runner-with-production-sync.yml`](../tests/fixtures/workflows/harness-auto-runner-with-production-sync.yml) into GitHub web UI → edit `harness-auto-runner.yml` on `main`. Automation is **not live** until this lands on origin.
+
+The harness workflow must include:
+
+- `repository_dispatch` type **`production_promoted`**
+- Job **`sync-production`** running `npm run harness:sync-production -- --repo … --json`
+- Optional **`workflow_dispatch`** input **`sync_repo`** (e.g. `target-app`) for manual cloud sync
+- Optional **`workflow_dispatch`** input **`sync_dry_run`** (default **`true`**) — passes `--dry-run` to `harness:sync-production` so manual cloud validation inspects Linear without writes
+
+### Manual cloud sync (harness Actions)
+
+Actions → **Harness Auto Runner** → Run workflow → set **`sync_repo`** = `target-app` (leave **`issue`** empty).
+
+**Safe cloud validation sequence** (after `HARNESS_CONFIG_JSON_B64` is set):
+
+1. **`sync_repo=harness`** (or any repo where `baseBranch === productionBranch`) — confirms config loading and repo resolution with a no-op exit when branches match.
+2. **`sync_repo=real-target`** with **`sync_dry_run=true`** (default) — inspects production-sync routing and Linear issue candidates **without writes**.
+3. **`sync_dry_run=false`** only when ready for actual Linear status updates after a real `dev` → `main` promotion.
+
+Example dry-run dispatch:
+
+```bash
+gh workflow run "Harness Auto Runner" \
+  --repo weston-uribe/agentic-product-development-harness \
+  -f sync_repo=real-target \
+  -f sync_dry_run=true
+```
+
+`production_promoted` **repository_dispatch** runs always use live sync (no dry-run).
+
+---
+
+## Event payload
+
+**Event type:** `production_promoted`
+
+```json
+{
+  "repo": "target-app",
+  "productionBranch": "main",
+  "sourceRepo": "owner/example-target-app",
+  "after": "<commit-sha-on-main>",
+  "ref": "refs/heads/main",
+  "receivedAt": "2026-07-07T23:46:00.000Z"
+}
+```
+
+Optional: `githubRunId`, `githubDeliveryId` (audit only). Harness ignores `after` for promotion proof; per-issue strong proof is unchanged.
+
+### Test dispatch (no target repo push)
+
+Requires harness workflow on origin with `production_promoted` handler (see Track B fixture). Use JSON body:
+
+```bash
+gh api repos/weston-uribe/agentic-product-development-harness/dispatches --method POST --input - <<'EOF'
+{
+  "event_type": "production_promoted",
+  "client_payload": {
+    "repo": "target-app",
+    "productionBranch": "main",
+    "sourceRepo": "owner/example-target-app",
+    "after": "<main-sha>",
+    "ref": "refs/heads/main",
+    "receivedAt": "2026-07-07T23:46:00.000Z"
+  }
+}
+EOF
+```
+
+Requires a PAT with **Contents: write** on the harness repo (same class as Vercel `GITHUB_DISPATCH_TOKEN`).
+
+---
+
+## Target repo: trigger workflow
+
+**GUI path (Milestone 5):** after local config is ready, use Settings / Configure → **Remote setup** → target repo card to preview and open an install PR on branch `harness/setup-production-sync-<repoConfigId>`. The GUI never writes directly to the production branch. See [`docs/gui-remote-setup.md`](gui-remote-setup.md).
+
+**Track A:** add the file below to **`owner/example-target-app`** using a **`workflow`-scoped** credential.
+
+**Track B:** copy from [`tests/fixtures/workflows/trigger-harness-production-sync.yml`](../tests/fixtures/workflows/trigger-harness-production-sync.yml) via GitHub web UI → **Add file** on production branch.
+
+Path: `.github/workflows/trigger-harness-production-sync.yml`
+
+```yaml
+# See tests/fixtures/workflows/trigger-harness-production-sync.yml for canonical content.
+```
+
+**Guards:** runs only on **`main`** pushes — not the integration branch, not issue branches.
+
+### Target repo secret
+
+In the **target repo** → Settings → Secrets and variables → Actions:
+
+| Secret | Permission |
+|--------|------------|
+| `HARNESS_DISPATCH_TOKEN` | Fine-grained **Contents: Read and write** on `weston-uribe/agentic-product-development-harness` only; or classic `repo` scoped to harness repo |
+
+Can reuse the same PAT as Vercel `GITHUB_DISPATCH_TOKEN` for the Linear bridge.
+
+**Do not** add `LINEAR_API_KEY` or merge-capable target-repo `GITHUB_TOKEN` to the target repo.
+
+---
+
+## Track B: webhook trigger (optional)
+
+If adding a target repo workflow file is blocked, configure a **GitHub repo webhook** on the target repo (Settings → Webhooks):
+
+- URL: future harness Vercel endpoint (not implemented in v1; prefer target repo workflow above)
+- Events: **Push**
+- Filter in handler: `ref == refs/heads/main` only
+
+The harness workflow change on `production_promoted` is **still required**; webhook only replaces the target repo workflow file.
+
+---
+
+## Validation gates
+
+1. `npm test`, `npm run test:webhook`, `npm run build`, `npm run harness:doctor`
+2. Set `HARNESS_CONFIG_JSON_B64` with private config including target repo id (see [`docs/operator-config.md`](operator-config.md))
+3. Dispatch test (`gh api … production_promoted`) → harness **sync-production** job runs (not `run-harness`)
+3. Target repo push to **`main`** → dispatch → sync job
+4. Target repo push to integration branch → no dispatch workflow run
+5. Repeat **`main`** push → idempotent (no duplicate Linear comments)
+6. Issues update to **Merged / Deployed** only when merge commit is reachable on `main` (strong proof)
+
+---
+
+## Rollback
+
+1. Disable or delete target repo `trigger-harness-production-sync.yml`
+2. Remove `production_promoted` handler from harness workflow (or disable workflow)
+3. Continue manual sync: `npm run harness:sync-production -- --repo target-app`

package/workspace-snapshot/files/docs/provider-portability.md

@@ -0,0 +1,131 @@
+# Provider portability and configuration posture
+
+This document describes what is configurable, what is fixed, and what is
+intentionally **not** claimed for the harness. Read this as a promise boundary: what v0.3.0 supports today, and what it deliberately does not claim. It complements
+[`docs/decisions/0004-agent-provider-boundary.md`](decisions/0004-agent-provider-boundary.md).
+
+**Release contract:** [`docs/releases/v0.3.0.md`](releases/v0.3.0.md)
+
+## Current v0.3.0 posture
+
+v0.3.0 is a **Cursor-first** harness for **Linear + GitHub + GitHub Actions**. The
+architecture is modular by subsystem (product system, SCM/PR system, runner,
+agent provider, preview provider), but it is **not provider-agnostic yet**.
+Cursor is the only implemented agent execution provider. Runner phases import
+[`src/agents/`](../src/agents/) (provider-facing facade); the Cursor adapter
+delegates to [`src/cursor/`](../src/cursor/) for SDK-specific behavior.
+
+### Support matrix
+
+| Subsystem | Implemented / supported in v0.3.0 |
+|-----------|----------------------------------|
+| Product system | Linear |
+| Source control / PR system | GitHub |
+| Runner | GitHub Actions |
+| Agent provider | Cursor Cloud Agents only |
+| Model policy | standard / basic Composer 2.5 unless deliberately changed |
+| Preview provider | Vercel or none |
+| Target repos | GitHub repos configured in `harness.config.json` |
+
+## What is configurable today
+
+The following are configurable through `harness.config.json` (see
+[`harness.config.schema.json`](../harness.config.schema.json)):
+
+- `repos[].id`
+- `repos[].linearProjects`
+- `repos[].linearTeams`
+- `repos[].targetRepo`
+- `repos[].baseBranch`
+- `repos[].productionBranch`
+- `repos[].previewProvider`
+- `repos[].integrationPreviewUrl`
+- `repos[].productionUrl`
+- `repos[].integrationSuccessStatus`
+- `repos[].productionSuccessStatus`
+- `repos[].validation.commands`
+- `allowedTargetRepos`
+- `linear.eligibleStatuses`
+- `linear.transitionalStatuses`
+- timeouts and check/preview polling behavior
+- `agentProvider.id` — currently only `"cursor"` is accepted
+- `agentProvider.model.id` — preferred source for model resolution
+- `defaultModel.id` — backward-compatible fallback when `agentProvider.model` is absent
+
+## What is fixed in v0.3.0
+
+The following are structural assumptions in v0.3.0 and are **not** configurable as
+provider swaps:
+
+- Linear as the product system
+- GitHub as the SCM / PR provider
+- GitHub Actions as the cloud runner
+- Cursor Cloud Agents as the agent provider
+- Cursor-specific run observation
+- Cursor-specific marker fields
+- Vercel-specific preview capture where preview is enabled
+
+## What is intentionally not claimed
+
+To avoid overstating maturity, the harness does **not** claim any of the
+following in v0.3.0:
+
+- Claude Code support
+- Codex support
+- local VS Code agent support
+- GitLab / Bitbucket support
+- generic PM-system support
+- production-grade portability
+- production SaaS maturity
+- provider-agnostic operation
+
+## Future provider adapter requirements
+
+A future agent provider adapter should support the full run lifecycle used by
+the runner phases today:
+
+- planning run creation
+- implementation run creation
+- revision run against an existing PR branch
+- integration repair run against an existing PR branch
+- lifecycle observation
+- terminal status capture
+- assistant output capture
+- branch/PR capture
+- provider diagnostics
+- timeout/cancellation
+- generic error mapping
+- validation evidence reporting
+- raw provider artifact retention
+
+## Skill portability
+
+Harness skills are portable workflow contracts stored canonically at
+[`.agents/skills/<skill-name>/SKILL.md`](../.agents/skills/). Client-specific
+locations (`.cursor/skills`, `.claude/skills`, ChatGPT project files, future
+Codex adapters) are export or adaptation targets — not canonical sources.
+
+Implemented canonical skills: `issue-intake`, `code-health-audit`,
+`architecture-evolution-audit`, `security-audit`, `planner`, and `implementation`
+at [`.agents/skills/<skill-name>/SKILL.md`](../.agents/skills/). `performance-cost-audit`,
+skill registry, package manager, skill manifests, runner-skill prompt integration,
+and provider/client adapters are **not implemented** — see
+[`docs/skills/skill-architecture.md`](skills/skill-architecture.md).
+SDK runner prompts in [`src/prompts/`](../src/prompts/) remain runner
+implementation details, not canonical skills.
+
+## Recommended next implementation steps
+
+1. **Make Cursor explicit** in docs and config posture rather than implying
+   provider agnosticism. *(Done: `agentProvider.id: "cursor"` config shape and
+   `src/agents/` provider seam; only Cursor is implemented.)*
+2. **Introduce an internal provider seam** that isolates Cursor SDK calls out of
+   the runner phases behind a single interface. *(Done: runner phases import
+   `src/agents/`; Cursor implementation remains in `src/cursor/`.)*
+3. **Extend provider config only when a second adapter exists** — the
+   `agentProvider` shape is Cursor-only today; do not add speculative provider
+   ids or a plugin system.
+4. **Preserve legacy markers** (`cursorAgentId`, `cursorRunId`) and Linear
+   metadata until they can be safely migrated behind the provider seam.
+5. **Validate a second adapter** end-to-end against the full lifecycle before
+   claiming any additional provider support.