p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/docs/releases/v0.2.0.md

@@ -0,0 +1,193 @@
+# V0.2.0 — Release contract
+
+**Tag status:** Tagged — tag `v0.2.0` on `fe37e307930467d66840624c82bce9dc0b4af0f2`. GitHub release: https://github.com/weston-uribe/agentic-product-development-harness/releases/tag/v0.2.0
+
+**Release type:** GitHub **source release** (annotated tag + curated release notes). This is **not** an npm package publication. `package.json` remains `private: true`.
+
+## TL;DR
+
+V0.2.0 is the first source release of the working harness: Linear-triggered Cursor Cloud Agent runs, GitHub PR lifecycle automation, production sync, and the public-repo security baseline.
+
+It is intentionally narrow:
+
+- Cursor only
+- Linear only
+- GitHub / GitHub Actions only
+- Vercel only where preview/webhook support is configured
+
+It is not a provider-agnostic platform and not an npm package.
+
+## Who this is for
+
+V0.2.0 is for a solo operator or small product/engineering team that wants to run a controlled AI-assisted product-development loop from Linear to GitHub PRs.
+
+It assumes the operator is comfortable configuring GitHub Actions secrets, Vercel environment variables, Linear statuses, and target repo branch strategy.
+
+---
+
+## Summary
+
+V0.2.0 is a Cursor-first harness for orchestrating product work through **Linear + GitHub + GitHub Actions**. SDK runners handle planning through merge and production sync; Linear status changes trigger cloud harness runs via a Vercel webhook bridge and GitHub `repository_dispatch`.
+
+---
+
+## What ships
+
+| Area | What ships in V0.2.0 |
+|------|----------------------|
+| Agent provider | Cursor Cloud Agents only (`agentProvider.id: "cursor"`) |
+| Product system | Linear |
+| SCM / PR | GitHub |
+| Cloud runner | GitHub Actions |
+| Preview provider | Vercel (when enabled) or none |
+| SDK runners | planning, implementation, handoff, revision, merge, production sync |
+| Auto-runner | Linear webhook → Vercel → `repository_dispatch` → GHA → `--phase auto` |
+| Trigger statuses | Ready for Planning, Ready for Build, PR Open, Needs Revision, Ready to Merge |
+| Issue intake | ChatGPT prompt, Cursor skill, parser template, `validate-issue` CLI |
+| Provider seam | Internal `src/agents/` facade; Cursor adapter in `src/cursor/` |
+| GHA hardening | Pinned actions, env-var shell safety, output redaction, CI, CodeQL, Dependabot |
+| Security baseline | Public-repo threat model, token matrix, ruleset on `main`, Actions allowlist |
+| Solo automation | Trusted branch → PR → required checks → merge (0 required GitHub approvals) |
+| Target-repo integration posture | PRs → `dev`; manual `dev` → `main`; production sync updates Linear |
+
+---
+
+## What does not ship
+
+- Provider agnosticism
+- Claude Code, Codex, or local VS Code agent support
+- GitLab, Bitbucket, or generic PM-system support
+- npm package publication or npm stability guarantee
+- Generic auto-merge for any green public PR
+- OpenSSF Scorecard
+- Required GitHub human approval in solo-maintainer mode
+- Autonomous shipping without Linear/status gates
+- Production-grade portability
+- Automated eval runners (manual rubrics only)
+
+---
+
+## Supported stack / support matrix
+
+| Subsystem | V0.2.0 |
+|-----------|--------|
+| Agent provider | Cursor Cloud Agents |
+| Product system | Linear |
+| SCM / PR | GitHub |
+| Runner | GitHub Actions |
+| Preview | Vercel or none |
+| Model policy | Composer 2.5 (standard/basic) unless deliberately changed |
+
+Details: [`docs/provider-portability.md`](../provider-portability.md)
+
+---
+
+## Security model
+
+- **Secrets** live in GitHub Actions secrets, Vercel environment variables, or local untracked `.env` files — never committed.
+- **Public repo:** untrusted users cannot push to `main` or trigger secret-bearing automation without write access or a dispatch token.
+- **`main` protection:** ruleset requires PR, required status checks (`test`, `Analyze (javascript-typescript)`), no direct push, no force push.
+- **Actions allowlist:** only pinned first-party actions permitted.
+- **Output redaction:** harness stdout is redacted before logs, summaries, and artifacts.
+- **Accepted risks:** documented in [`docs/security.md`](../security.md) (dispatch token model, transitive `undici` advisory, public Actions logs).
+
+---
+
+## Solo repo automation policy
+
+While Weston is the sole maintainer:
+
+| Setting | Value |
+|---------|-------|
+| PR required to merge to `main` | Yes |
+| Required status checks | `test`, `Analyze (javascript-typescript)` |
+| Direct push to `main` | No |
+| Required GitHub approvals | **0** |
+| CODEOWNER review enforced | **No** (`.github/CODEOWNERS` exists for documentation/future enforcement) |
+
+**Linear/status gates remain required.** Automation runs only when the issue is on an allowlisted status; merge runs only after **Ready to Merge**. This is human-controlled product judgment via Linear — not bypassed by GitHub review settings.
+
+**Re-enable GitHub approvals and CODEOWNER review** when a second engineer joins or when accepting external contributions.
+
+---
+
+## Setup prerequisites
+
+1. Node.js 22+, npm
+2. Linear team with harness workflow statuses configured
+3. GitHub repo with Actions secrets: `LINEAR_API_KEY`, `CURSOR_API_KEY`, `HARNESS_GITHUB_TOKEN`
+4. Vercel project for webhook bridge (production env vars only — see security doc)
+5. `harness.config.json` with target repos and Linear mappings
+6. Optional: integration branch/`main` branch setup and production sync dispatch
+
+Operator guides:
+
+- [`docs/getting-started.md`](../getting-started.md)
+- [`docs/linear-watcher-setup.md`](../linear-watcher-setup.md)
+- [`docs/target-repo-branch-setup.md`](../target-repo-branch-setup.md)
+- [`docs/production-sync-automation.md`](../production-sync-automation.md)
+- [`docs/security.md`](../security.md)
+
+---
+
+## Validation checklist
+
+Run before tagging (also run locally on the release-doc PR):
+
+```bash
+npm ci
+npm run build
+npm test
+npm run test:webhook
+```
+
+Optional operator checks:
+
+- `npm run harness:doctor`
+- `npm run harness:validate-issue -- --file <draft> --intended-phase planning`
+- `npm run harness:run -- --issue WES-XX --dry-run`
+
+---
+
+## Known limitations
+
+See [CHANGELOG.md](../../CHANGELOG.md) Known limitations section for the full list. Key points:
+
+- **Cursor-only** — no Claude Code, Codex, or local VS Code agent support
+- **Linear + GitHub only** — not a generic PM or SCM platform
+- **Manual evals** — automated eval contract is deferred; scorecards are human-readable rubrics
+- **Operator setup required** — not a plug-and-play product; expect to configure secrets, statuses, and branch strategy
+
+---
+
+## Upgrade notes from v0.1
+
+| v0.1 | V0.2.0 |
+|------|--------|
+| Manual Cursor loop + docs/templates | SDK runners for full lifecycle |
+| No auto-run | Event-driven auto-runner from Linear |
+| Implicit Cursor usage | Explicit `agentProvider.id: "cursor"` config |
+| Single-branch merge assumption | Integration branch (`dev`) + production sync |
+| Manual security guidance | Implemented ruleset, allowlist, redaction |
+| `version: 0.1.0` | `version: 0.2.0` (source marker only) |
+
+Historical v0.1 artifacts (ADRs, milestone docs, example run 001) remain valid as history.
+
+---
+
+## Release readiness checklist
+
+- [ ] Release-doc PR merged to `main`
+- [ ] Required checks green on merge commit (`test`, `Analyze (javascript-typescript)`)
+- [ ] `docs/releases/v0.2.0.md` and `CHANGELOG.md` reflect final scope
+- [ ] Local validation: `npm ci`, `npm run build`, `npm test`, `npm run test:webhook`
+- [ ] Tag preflight: `v0.2.0` tag does not already exist
+- [ ] Annotated tag `v0.2.0` created and pushed
+- [ ] GitHub release created with curated notes (not `--generate-notes`)
+- [ ] Follow-up PR updates tag status in this doc to **Tagged**
+
+---
+
+## Tag / release
+
+Do **not** create the tag in the release-doc PR. Follow [`release-process.md`](release-process.md) after merge.

package/workspace-snapshot/files/docs/releases/v0.3.0.md

@@ -0,0 +1,188 @@
+# V0.3.0 — Release contract
+
+**Tag status:** Tagged — annotated tag `v0.3.0` on `f55f21825802a246a9db130ae5e128ad8165384d`. GitHub release: https://github.com/weston-uribe/agentic-product-development-harness/releases/tag/v0.3.0
+
+**npm status:** Published — `p-dev-harness@0.3.0` on https://www.npmjs.com/package/p-dev-harness
+
+**Release type:** GitHub **source release** (annotated tag + curated release notes) plus public npm CLI package **`p-dev-harness@0.3.0`**.
+
+**npm naming note:** Registry rejected bare `p-dev` as too similar to existing [`pdev`](https://www.npmjs.com/package/pdev). The published package name is `p-dev-harness`.
+
+## TL;DR
+
+V0.3.0 is the guided-onboarding and distribution release. Product managers can start with `npx --yes p-dev-harness@0.3.0` without cloning the source repository. The seven-step Configure GUI automates service credentials, Linear workspace setup, Vercel webhook bridge, target repos, cloud secrets, and guarded workflow install PR finalization.
+
+## Who this is for
+
+- Product managers and solo operators who want guided harness onboarding
+- Contributors who develop the harness from the source repository
+- Teams already on Linear + GitHub + GitHub Actions + Vercel + Cursor
+
+## Primary install command
+
+```bash
+npx --yes p-dev-harness@0.3.0
+```
+
+Requires Node.js 22+. macOS is the validated packaged platform; use `--no-open` elsewhere.
+
+Full guide: [`docs/p-dev.md`](../p-dev.md)
+
+## Architecture / workspace model
+
+| Boundary | Role |
+|----------|------|
+| `p-dev-harness` npm package | Packaged operator shell and Configure GUI launcher |
+| Operator workspace (`~/.p-dev`, `P_DEV_HOME`, `--workspace`) | Durable local secrets and config |
+| Public template (`weston-uribe/p-dev-harness-template`) | Provisioning source for private harness workspace |
+| Private `OWNER/p-dev-harness` | Managed harness workspace for cloud automation |
+| Target repos | Product codebases the harness operates on |
+
+## What ships
+
+| Area | V0.3.0 |
+|------|--------|
+| Product install | `p-dev-harness@0.3.0` on public npm |
+| Configure GUI | Seven-step guided setup with confirmation gates |
+| Packaged provisioning | Private harness workspace from public template |
+| Linear setup | Automated workspace/status configuration |
+| Vercel bridge | Env vars, webhook, redeploy polling, signed verification |
+| Cloud secrets | Harness repo GitHub Actions secret writes |
+| Target workflow | Install PR create/reuse, checks, guarded merge, production verify |
+| Canonical skills | Six skills under `.agents/skills/` |
+| Source release | Annotated tag + GitHub release on this repository |
+
+## Setup flow
+
+1. Connect services (optional packaged harness workspace provisioning)
+2. Set up Linear workspace
+3. Set up Vercel webhook bridge
+4. Choose target repo(s)
+5. Check local readiness
+6. Connect cloud secrets
+7. Install target repo workflow (guarded auto-finalization for system-owned setup PRs)
+
+Remote mutations require explicit confirmation. Ordinary product PRs remain governed by Linear status gates.
+
+## Canonical skills
+
+Implemented under `.agents/skills/`:
+
+- `issue-intake`
+- `code-health-audit`
+- `architecture-evolution-audit`
+- `security-audit`
+- `planner`
+- `implementation`
+
+Deferred: `performance-cost-audit`, skill registry/package manager, manifests, provider adapters, runner-skill prompt integration. Planner and implementation SKILL.md files do not replace `src/prompts/*.md` runner implementation.
+
+## Changes from v0.2.0
+
+| v0.2.0 | v0.3.0 |
+|--------|--------|
+| Source clone only | `p-dev-harness` npm package for product onboarding |
+| Manual/scattered setup docs | Seven-step guided Configure GUI |
+| No canonical skills | Six canonical skills documented and implemented |
+| No public template provisioning | Private harness workspace from public template |
+| Manual workflow install guidance | Guarded Step 7 auto-finalization for setup PRs |
+| Source release only | Source release + public npm package |
+
+## Security model
+
+- Secrets in local workspace, GitHub Actions secrets, and Vercel env vars — never in the published package
+- Confirmation-gated remote writes with fingerprint validation
+- Output redaction before logs and artifacts
+- Published tarball excludes credentials and operator state
+
+Details: [`docs/security.md`](../security.md)
+
+## Validation evidence
+
+- Codespaces source-based Configure GUI validation
+- Controlled separate-account packaged onboarding through Setup complete
+- Package pack/inspect tests and tarball smoke (Configure route HTTP 200)
+- Registry-installed smoke: `npx --yes p-dev-harness@0.3.0 --no-open` → `/settings/configure` HTTP 200
+- Expanded setup, GUI, and provisioning test suite
+
+**Not validated:** full real issue lifecycle from an isolated npm-installed workspace.
+
+## Support matrix
+
+| Subsystem | V0.3.0 |
+|-----------|--------|
+| Product install | `p-dev-harness@0.3.0` (npm) |
+| Packaged platform | macOS validated; `--no-open` elsewhere |
+| Node.js | 22+ |
+| Agent provider | Cursor Cloud Agents |
+| Product system | Linear |
+| SCM / PR | GitHub |
+| Runner | GitHub Actions |
+| Preview / bridge | Vercel |
+
+## Known limitations
+
+- Cursor-only agent provider
+- Linear / GitHub / GitHub Actions / Vercel stack
+- macOS validated for packaged browser auto-launch
+- No full isolated npm issue lifecycle validated
+- No automatic private harness workspace upgrade/sync
+- Public template compatibility dependency
+- Not production SaaS or provider-agnostic
+- Manual eval rubrics where automation is not implemented
+
+## Upgrade notes from v0.2.0
+
+- Product managers: use `npx --yes p-dev-harness@0.3.0` instead of cloning for onboarding
+- Contributors: continue cloning source repository
+- Existing source-based workspaces: unchanged; operator workspace remains under `~/.p-dev` by default
+- Template main updated for authoritative provenance after npm package rename
+
+## Template dependency / provenance
+
+| Artifact | SHA / value | Notes |
+|----------|-------------|-------|
+| Template repo | `weston-uribe/p-dev-harness-template` | Public GitHub template |
+| Template **main** (authoritative) | `9cdf5534638194036b55d84a3d959f092c47c201` | PR [#17](https://github.com/weston-uribe/p-dev-harness-template/pull/17) — aligned to primary `f55f218`, `p-dev-harness` naming |
+| Template tag `v0.3.0` (immutable) | `8dac15dfeef798909f9216028708c66aebd55dd6` | PR [#16](https://github.com/weston-uribe/p-dev-harness-template/pull/16) — initial sync from primary `156eab6`; **not moved** |
+| `templateContentId` on template main | `agentic-product-development-harness-f55f21825802a246a9db130ae5e128ad8165384d-curated-v1` | Matches authoritative primary release commit |
+
+GitHub template provisioning uses repository **default branch** (`main`), so corrected template `main` is authoritative for new private workspaces. The immutable template tag `v0.3.0` remains a historical snapshot from the pre-rename sync.
+
+## Immutable release evidence
+
+| Field | Value |
+|-------|-------|
+| **RELEASE_SHA** | `f55f21825802a246a9db130ae5e128ad8165384d` |
+| Primary annotated tag object | `e6cdc5f69c1f394e0403bc90a14b317e2b6b134b` |
+| Primary tag peeled commit | `f55f21825802a246a9db130ae5e128ad8165384d` |
+| GitHub release | https://github.com/weston-uribe/agentic-product-development-harness/releases/tag/v0.3.0 |
+| Release-prep PR | https://github.com/weston-uribe/agentic-product-development-harness/pull/56 |
+| npm rename PR | https://github.com/weston-uribe/agentic-product-development-harness/pull/57 |
+| npm package | `p-dev-harness@0.3.0` |
+| npm dist-tag `latest` | `0.3.0` |
+| npm dist.shasum | `fbc2c9e3d29ad4181776008b1880e5845e3aec53` |
+| npm dist.integrity | `sha512-0p2ggAnyVOv4QVEpFFPp54e2eaPfFNfyLhVdyYLySfTVym/iOcB6nJR0v3UcRTM9uQc05F2bayG9i7JltnuUmA==` |
+| Local tarball | `packages/p-dev/p-dev-harness-0.3.0.tgz` |
+| Local tarball bytes | 1,630,506 |
+| Local tarball SHA-1 | `fbc2c9e3d29ad4181776008b1880e5845e3aec53` |
+| Local tarball SHA-256 | `d7b99605f40f1837ef9a7bd64dd1f712d18259c6dafc9124527337b29a60c916` |
+| Registry smoke | `npx --yes p-dev-harness@0.3.0 --no-open` → HTTP 200 on `/settings/configure` |
+| Release timestamp (UTC) | 2026-07-13 |
+
+## Release readiness checklist
+
+- [x] Release-prep PR merged to `main`
+- [x] npm package-name correction PR merged
+- [x] Required checks green on merge commits
+- [x] Template sync PR merged; immutable template tag `v0.3.0` at `8dac15d`
+- [x] Template provenance correction merged to template `main`
+- [x] `p-dev-harness@0.3.0` published from exact tarball
+- [x] Registry smoke: `npx --yes p-dev-harness@0.3.0 --no-open`
+- [x] Annotated primary tag `v0.3.0` pushed at `RELEASE_SHA`
+- [x] GitHub release created
+- [x] Finalization PR records immutable tag/npm/template evidence
+
+## Tag / npm / GitHub release procedure
+
+Historical operator steps: [`release-process.md`](release-process.md)

package/workspace-snapshot/files/docs/releases/v0.3.1.md

@@ -0,0 +1,138 @@
+# v0.3.1 — Immutable workspace provisioning
+
+**Release type:** GitHub source release (annotated tag + curated release notes) plus public npm package **`p-dev-harness@0.3.1`**.
+
+## TL;DR
+
+`p-dev-harness@0.3.1` binds each published package version to an **immutable embedded workspace snapshot** and provisions fresh private workspaces from that snapshot without calling the public template repository at runtime. Existing valid `p-dev-harness@0.3.0` managed workspaces reconnect without content rewrite.
+
+**Primary install command:**
+
+```bash
+npx --yes p-dev-harness@0.3.1
+```
+
+Requires Node.js 22+. macOS is the validated packaged platform; use `--no-open` elsewhere.
+
+Full guide: [`docs/p-dev.md`](../p-dev.md)
+
+## What ships
+
+- Embedded `workspace-snapshot/manifest.json` + `workspace-snapshot/files/**` in the npm tarball
+- Package-owned GitHub provisioning (`createUserRepository` + git blob/tree/commit APIs)
+- Managed marker v3 with `createdFromPackageSnapshot` provenance
+- Default blob-upload concurrency **2** with shared rate-limit coordination and automatic retry/pause
+- Legacy reconnect for valid `p-dev-harness@0.3.0` managed workspaces
+- Conditional release-impact guidance in planner/implementation contracts
+
+## What does not ship
+
+- Automatic upgrade of existing managed workspaces to the 0.3.1 snapshot
+- Changes to `weston-uribe/p-dev-harness-template` default branch or tags
+- Provider-agnostic agent support or production SaaS claims
+
+## Embedded snapshot behavior
+
+Each `p-dev-harness@0.3.1` install carries a curated workspace snapshot generated from the release commit. Fresh private `OWNER/p-dev-harness` workspaces are created by uploading snapshot blobs to GitHub and committing the snapshot tree plus a managed marker overlay.
+
+- **Package-to-snapshot immutability:** manifest `sourceCommit`, `snapshotContentId`, `snapshotSha256`, and `gitRootTreeSha1` are recorded in the tarball
+- **First-time provisioning** can take several minutes; Configure shows upload progress
+- **Rate-limit recovery** is automatic — shared pause coordination across concurrent upload workers; no env var required for the default path
+- Optional advanced override: `HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY` (integer `1`–`4`)
+
+## Compatibility
+
+| Workspace type | Behavior |
+|----------------|----------|
+| Fresh install @0.3.1 | Provisions from embedded snapshot |
+| Valid 0.3.0 managed workspace | Reconnects without rewrite |
+| Existing workspace on newer snapshot | Not auto-upgraded |
+
+`weston-uribe/p-dev-harness-template` remains a **frozen** compatibility artifact for `p-dev-harness@0.3.0` only.
+
+## Release-impact agent-contract changes
+
+Planner and implementation skills include conditional release-impact analysis for published artifacts. Agents must classify impact but do **not** authorize publish, tag, or deploy actions.
+
+## Security and mutation boundaries
+
+- Secrets remain in operator workspace, GitHub Actions secrets, and Vercel env vars — never in the published package
+- Published tarball excludes credentials, operator state, and local caches
+- Release validation uses uniquely named private repositories; production `weston-uribe/p-dev-harness` is not mutated
+- External template repository is not mutated for 0.3.1+
+
+## Validation summary
+
+Release validation includes:
+
+- Full test suite, webhook tests, package prepare/pack/inspect
+- Packed npm README and snapshot manifest correctness
+- Exact tarball launcher smoke (`/settings/configure` HTTP 200, stop/relaunch)
+- Real-account provisioning gate from installed tarball at default concurrency 2
+- Registry smoke after npm publication
+
+Immutable npm, tag, and detailed validation evidence are recorded below and in the post-release finalization PR.
+
+## Known limitations
+
+- Cursor-only agent provider
+- Linear / GitHub / GitHub Actions / Vercel stack
+- macOS validated for packaged browser auto-launch
+- No full isolated npm issue lifecycle validated
+- No automatic private harness workspace upgrade/sync to newer snapshots
+- Not production SaaS or provider-agnostic
+
+## Rollback
+
+- **Unpublished code:** revert merge commit on `main`
+- **Published npm:** follow npm deprecation policy only under explicit operator approval; prefer forward-fix `0.3.2` for defects
+- **Never** overwrite tags or republish the same npm version with different bytes
+
+## Immutable release evidence
+
+| Field | Value |
+|-------|-------|
+| **RELEASE_SHA** | `995387c74334ba85206d9d87d7d78d4ecbfa8361` |
+| **Merge PR** | https://github.com/weston-uribe/agentic-product-development-harness/pull/60 |
+| **npm package** | [`p-dev-harness@0.3.1`](https://www.npmjs.com/package/p-dev-harness/v/0.3.1) |
+| **npm published (UTC)** | `2026-07-14T04:26:06.351Z` |
+| **registry shasum** | `d71a6f4a71a9913f51232cfcd066826c1045f36b` |
+| **registry integrity** | `sha512-7q53Cuxcg/B8DECHyaJcfecdLdWuBP/Z0uhIC0nb0vF/bFJqwB1t2kmAcIpdkZswk7HRTh/EcDuYmPBl9fh9Tw==` |
+| **GitHub tag / release** | https://github.com/weston-uribe/agentic-product-development-harness/releases/tag/v0.3.1 |
+| **Tarball path** | `packages/p-dev/p-dev-harness-0.3.1.tgz` |
+| **Tarball bytes** | `2,344,371` |
+| **Tarball SHA-1** | `d71a6f4a71a9913f51232cfcd066826c1045f36b` |
+| **Tarball SHA-256** | `894d0d92ea0fd5b65fb149380b1c2802b52a9b2c8c5dcc9048ee8eb4bb4550ee` |
+| **npm inspect entry count** | `1736` |
+| **Manifest `sourceCommit`** | `995387c74334ba85206d9d87d7d78d4ecbfa8361` |
+| **Manifest `snapshotContentId`** | `f934bf224266ff7e2a8bae9d0a73b7399ca785392269ad1df44c59d075f62803` |
+| **Manifest `snapshotSha256`** | `396315fe2e48630609563d32da78e2831eb57e40fac0be3f946f13142753fa77` |
+| **Manifest `gitRootTreeSha1`** | `1c99e6d9dbd304d1372effdc7373d8b30391ddca` |
+| **Manifest file count** | `611` |
+
+### Post-merge validation (installed exact tarball, default concurrency 2)
+
+| Field | Value |
+|-------|-------|
+| **Tarball launcher smoke** | Pass — `/settings/configure` HTTP 200, stop/relaunch with same `P_DEV_HOME` |
+| **Post-merge live gate repo** | https://github.com/weston-uribe/p-dev-harness-validation-031-release-995387c-20260714042343 |
+| **Repository ID** | `1300003493` |
+| **Init / snapshot / marker SHAs** | `fc3dccdb…` / `72ac3a7c…` / `4399c2dd…` |
+| **Provision duration** | ~102s |
+| **Rate-limit pauses** | `0` |
+| **Verification** | Pass |
+| **HEAD unchanged on replay** | Pass (replay provision returned expected ambiguous-create guard; no mutation) |
+| **Archived** | Yes (private) |
+
+### Registry smoke (published package)
+
+| Field | Value |
+|-------|-------|
+| **`npx p-dev-harness@0.3.1 --no-open`** | Pass — `/settings/configure` HTTP 200 |
+| **Installed manifest `sourceCommit`** | `995387c74334ba85206d9d87d7d78d4ecbfa8361` |
+
+### Branch validation (pre-merge repair evidence on PR #60)
+
+Default-path live gate from branch tarball at `3a5e31a` is recorded in PR #60 comments. Post-merge artifact above is the authoritative release validation.
+
+See [`release-process.md`](release-process.md) for the operator workflow.

package/workspace-snapshot/files/docs/releases/v0.4.0.md

@@ -0,0 +1,93 @@
+# v0.4.0 — Associations, fingerprint gate, and release-sync runner
+
+**Release type:** GitHub source release (annotated tag + curated release notes) plus public npm package **`p-dev-harness@0.4.0`**.
+
+**Status:** Release-preparation — not tagged, not published on npm, and no GitHub release until operator approval of the release-prep PR and final artifact checksum.
+
+## TL;DR
+
+`p-dev-harness@0.4.0` hardens first-run Linear→repo association routing, pairs `HARNESS_CONFIG_JSON_B64` with `HARNESS_CONFIG_FINGERPRINT` for fail-closed `cloud_config_stale` checks, speeds Step 1 provisioning, and ships an operator CLI (`release:sync-managed-runner`) to sync a managed harness runner and require the configuration canary. The in-app **Update PDev runner** card remains **disabled by default**.
+
+**Primary install command (after npm publish):**
+
+```bash
+npx --yes p-dev-harness@0.4.0
+```
+
+Requires Node.js 22+. macOS is the validated packaged platform; use `--no-open` elsewhere.
+
+Full guide: [`docs/p-dev.md`](../p-dev.md)
+
+## What ships
+
+- Authoritative Linear associations for issue routing (Settings + Configure Step 2)
+- Paired cloud config secret + repository variable fingerprint (`HARNESS_CONFIG_JSON_B64` / `HARNESS_CONFIG_FINGERPRINT`), including `run-merge`
+- Configuration canary with safe failure diagnostics (expected/computed fingerprint, decode + association success) and workflow_dispatch 204 run location via `canary_operation_id`
+- Operator CLI: `npm run release:sync-managed-runner`
+- Faster Step 1 provisioning (bulk authenticated git push / packaged Git object pack)
+- Guided Configure UX holds and Step 7 server-authoritative finalization improvements
+- Runner status comments / conditional Blocked finalization refinements
+- In-app Update PDev runner implementation **hidden unless** `P_DEV_RUNNER_UPGRADE_UI_ENABLED=1`
+
+## What does not ship
+
+- Enabled-by-default in-app runner upgrade UI (deferred; experience TBD)
+- Automatic upgrade of every existing managed workspace without operator action
+- Changes to `weston-uribe/p-dev-harness-template`
+- Provider-agnostic agent support or production SaaS claims
+- npm publish / git tag / GitHub release in the release-prep PR (operator-gated after merge)
+
+## Compatibility
+
+| Workspace type | Behavior |
+|----------------|----------|
+| Fresh install @0.4.0 | Provisions from embedded snapshot |
+| Valid 0.3.0 / 0.3.1 managed workspace | Reconnects; operator may use `release:sync-managed-runner` for known test harness upgrade |
+| In-app Update PDev runner card | Hidden unless feature flag enabled |
+
+## Security and mutation boundaries
+
+- Secrets remain in operator workspace, GitHub Actions secrets/vars, and Vercel env vars — never in the published package
+- Published tarball excludes credentials, operator state, and local caches
+- Release-prep validation must not publish npm, create tags, or create GitHub releases
+- External template repository is not mutated for 0.3.1+
+
+## Validation summary
+
+Release-prep validation includes:
+
+- Full test suite + webhook tests
+- `npm run build`
+- `package:p-dev:prepare` / `pack` / `inspect`
+- `npm audit --audit-level=moderate` (document accepted transitive risk if unchanged)
+- Minimal packaged smoke: install tarball, launch server, load `/settings/configure`
+- Prior FRE-1 end-to-end release gate on the test workspace (not re-run for this prep PR)
+
+Immutable npm/tag evidence is filled in the post-release finalization PR after operator-approved publish.
+
+## Known limitations
+
+- Cursor-only agent provider
+- Linear / GitHub / GitHub Actions / Vercel stack
+- macOS validated for packaged browser auto-launch
+- In-app runner upgrade UX intentionally unfinished / disabled for 0.4
+- Not production SaaS or provider-agnostic
+
+## Rollback
+
+- **Unpublished code:** revert merge commit on `main`
+- **Published npm:** follow npm deprecation policy only under explicit operator approval; prefer forward-fix patch for defects
+- **Never** overwrite tags or republish the same npm version with different bytes
+
+## Immutable release evidence
+
+| Field | Value |
+|-------|-------|
+| **RELEASE_SHA** | _(fill after merge to main)_ |
+| **Merge PR** | _(fill after PR open)_ |
+| **npm package** | `p-dev-harness@0.4.0` — **not published yet** |
+| **GitHub release / tag** | **not created yet** |
+| **Tarball** | `packages/p-dev/p-dev-harness-0.4.0.tgz` |
+| **Tarball SHA-256** | _(fill from release-prep validation)_ |
+| **Manifest sourceCommit** | _(fill from prepare at release-prep HEAD)_ |
+| **Manifest snapshotContentId** | _(fill from prepare)_ |

package/workspace-snapshot/files/docs/research/001-manual-run-retrospective.md

@@ -0,0 +1,64 @@
+# Retrospective: Manual harness run 001
+
+**Run:** [`examples/runs/001-target-app-github-link/`](../examples/runs/001-target-app-github-link/)  
+**Target:** `owner/example-target-app`  
+**Outcome:** PR [#1](https://github.com/owner/example-target-app/pull/1) squash-merged; production deployed  
+**Date:** 2026-07-06
+
+This documents one **manual** v0.1 loop. It does not prove the harness is automated, reusable at scale, or ready for skills.
+
+---
+
+## What worked
+
+- **Bounded issue scope** — single link, one surface; easy to eval and merge in one PR.
+- **Templates gave structure** — issue → plan → scorecard → readiness report stayed aligned without a control plane.
+- **Repo inspection step** — forcing the agent to find contact/link patterns before coding avoided wrong placement guesses from the harness repo alone.
+- **Human gates** — PM review before merge caught nothing blocking, but the gate itself matched the intended workflow.
+- **Three-file diff** — narrow scope made code review and harness artifact updates straightforward.
+
+## What slowed the loop
+
+- **Cross-repo context switching** — harness repo for artifacts, target repo for implementation; manual copy of evidence between them.
+- **Preliminary plan → post-inspection update** — plan started with TBD file list; agent had to discover `contact-section.tsx`, `content.ts`, `breakpoints.ts` during execution.
+- **Icon library surprise** — Lucide `Github` not in pinned version; unplanned inline SVG workaround (acceptable, but added a decision mid-run).
+- **Artifact updates in two passes** — readiness artifacts updated after implementation, then again after merge; no automation linking PR state to harness folder.
+- **Explicit mobile check** — responsive grid implied mobile OK; no dedicated mobile viewport note in validation until follow-up.
+
+## Reusable template improvements (not skills)
+
+| Improvement | Where | Why |
+|-------------|-------|-----|
+| **Repo inspection checklist** | `implementation-plan.md` | Standardize “find link patterns, content source, validation commands” before “Files to touch” |
+| **Icon / dependency check** | `implementation-plan.md` | Prompt: verify icon/component exists in pinned library version before planning Lucide names |
+| **Explicit mobile validation row** | `implementation-plan.md`, `eval-scorecard.md` | Avoid inferring mobile from desktop/grid checks |
+| **Merge / deploy section** | `pr-readiness-report.md` | Fields for main commit SHA, deployment URL, merge method after PR closes |
+
+These are **template edits** for v0.1 — not automations.
+
+## What should not become a skill yet
+
+- **"Add social link to site"** — one data point; pattern may differ on kinterra or non-Next.js repos.
+- **PR → harness artifact sync** — only one run; manual updates worked; automation premature.
+- **Vercel deploy polling** — no repeated pain at scale yet.
+- **Target repo bootstrap** — agent still needs `AGENTS.md` and local conventions; don’t encode until run 002 confirms repetition.
+
+Skills require **validated repetition** across runs, not one successful merge.
+
+## Next hypothesis for run 002
+
+**Candidate:** A slightly larger target-app change that still fits one PR — e.g. copy or content update in an existing case study section, or a small UX fix that touches `lib/content.ts` plus one component.
+
+**Hypothesis to test:**
+
+- Does the repo inspection checklist (if added to templates) reduce plan TBD time?
+- Do the same eval criteria apply, or does content-heavy work need a different scorecard row set?
+- Is the harness artifact folder structure sufficient, or does run 002 need a linked issue ID from Linear/GitHub Issues?
+
+**Explicit non-goals for run 002:** Linear integration, cloud agents, skills, CI eval runners.
+
+---
+
+## Honest maturity statement
+
+Run 001 proves Weston can execute **one structured manual loop** with docs and templates. The harness remains v0.1 documentation scaffold plus example artifacts — not a productized agentic sprint system.