p-dev-harness 0.3.1 → 0.4.0

package/workspace-snapshot/files/docs/architecture/canonical-product-development-workflow.md

@@ -0,0 +1,70 @@
+# Canonical product-development workflow
+
+**Status:** implemented in source (Workflow page + runner preflight)
+
+The harness uses one canonical Linear workflow descriptor for product-development work. The descriptor lives in `src/workflow/canonical-product-development-workflow.ts` and contains product semantics only (status names, categories, roles, transitions, merge-path variants, and agent-phase keys).
+
+## Dispatch triggers
+
+Exactly five Linear statuses trigger repository dispatch:
+
+- Ready for Planning
+- Ready for Build
+- PR Open
+- Needs Revision
+- Ready to Merge
+
+## Human gates
+
+- **Backlog** → Ready for Planning or Ready for Build
+- **PM Review** → Needs Revision or Engineering Review
+- **Engineering Review** → Needs Revision or Ready to Merge (human gate only; no PR review agent)
+
+## Role-based agent models
+
+Production Workflow configuration stores authoritative model selections in `harness.config.json` under `roleModels`:
+
+- **Planner** — planning agents
+- **Builder** — implementation, revision, and integration-repair follow-ups on one canonical Builder thread
+
+The Workflow page exposes Planner and Builder controls only. There are no independent revision or integration-repair model settings. Each Builder prompt sends `resolveBuilderModel(config)` so a changed Builder model applies on the next run.
+
+Model changes autosave locally and sync to the harness repo cloud secret `HARNESS_CONFIG_JSON_B64` only.
+
+## Builder thread continuity
+
+One durable Builder Cursor conversation is preserved per implementation lineage:
+
+| Phase | Builder behavior |
+|-------|------------------|
+| **Building** | Create generation `1`; persist `builder_agent_id` before first `send()` |
+| **Revising** | Resolve lineage from handoff / prior markers; resume Builder; send PM feedback as follow-up |
+| **Integration repair (agent)** | Resolve latest canonical Builder; send narrow repair follow-up |
+| **Integration repair (deterministic)** | Agent-free; unchanged |
+
+**Source of truth:** hidden Linear comment metadata (not session memory). Legacy issues without `builder_agent_id` may fall back to validated `cursor_agent_id` on implementation-start markers only.
+
+**Replacement policy:** create a new Builder only for definitive agent loss or exhausted legacy lineage — never for auth, network, rate-limit, busy, or uncertain `send()` outcomes.
+
+**Idempotency:** stable keys from durable triggers (issue + branch, PM feedback comment ID, repair cycle SHAs) — not harness `run_id`.
+
+**No VM guarantee:** resume/unarchive is best-effort; durable artifacts must always allow a fresh agent to reconstruct context.
+
+## Duplicate status contract
+
+Linear **Duplicate** is an optional system terminal status. Setup does not create it. Its absence does not block harness runs. When present, validation requires the canonical name and `canceled` category.
+
+## Merge path variants
+
+- **Different integration and production branches:** Ready to Merge → Merging → Merged to Dev → Merged / Deployed
+- **Same branch:** Ready to Merge → Merging → Merged / Deployed
+
+## Workflow UI
+
+The Workflow page is cards-only (health panel + expandable workflow cards). Sidebar card expansion state is stored in browser session storage.
+
+Legacy `/operations` routes redirect to Workflow. The retired draft API returns **410 Gone**.
+
+## Validation
+
+Canonical Linear workflow validation runs before authoritative runner side effects when live Linear team workflow states are available. Noncanonical `harness.config.json` workflow-status overrides are reported as configuration errors and are not silently rewritten.

package/workspace-snapshot/files/docs/architecture/linear-automation-state-machine.md

@@ -119,6 +119,16 @@ Bypass planning (via `skip-plan` or direct **Ready for Build**) when the issue i
 
 For bypass issues, the **Implementation Agent** may build directly from the Linear issue without a separate plan artifact. The issue description and acceptance criteria are the durable input.
 
+### Uninitialized product routing
+
+When the target repository marker on the **development branch** (`repos[].baseBranch`, usually `dev`) reports `Product initialization: uninitialized`:
+
+- Issues with `## Product foundation` route to **Ready for Planning** for stack selection and foundation planning.
+- Direct **Ready for Build** routing is blocked until approved architecture exists and the marker reads `initialized`.
+- After foundation merge to `dev`, the merge workflow updates Linear project metadata to `Product initialization: initialized` idempotently.
+
+Application preview/deployment capability is **not** inferred from the marker. Harness `repos[].previewProvider` is the sole runtime authority (`vercel` or `none`).
+
 ### Planning agent output
 
 When planning runs:
@@ -162,7 +172,7 @@ Validated in WES-9 and WES-10 — see [`docs/research/003-cursor-automation-plan
 |--------------|--------|
 | **Ready for Planning** | Run planning flow (Planning Agent) |
 | **Ready for Build** | Run implementation flow (Implementation Agent) — **not yet validated** |
-| **Needs Revision** | Run revision flow (Revision Agent) — **not yet validated** |
+| **Needs Revision** | Run revision flow (Builder follow-up) — **implemented** |
 | Any other status | **Silent exit** — no changes, no Linear writes |
 
 The router may delegate logically to role-specific prompts. The planning spike implements this as **one Cursor Automation prompt** that routes based on Linear status.
@@ -214,16 +224,22 @@ Role maturity varies — see honest maturity table below. Planning Agent behavio
 | **GitHub writes** | Branch, commits, PR (link back to Linear issue) |
 | **Must not do** | Merge PRs; deploy without human gate; advance past **PR Open** without a PR |
 
-### Revision Agent
+### Builder (implementation, revision, repair)
 
 | Field | Detail |
 |-------|--------|
-| **Trigger / status** | **Needs Revision** (via router) |
-| **Input** | Linear issue, PM review feedback comments, existing PR and branch |
-| **Output** | Additional commits on branch; revision summary comment |
-| **Linear writes** | Revision summary comment; move to **Revising** while working; move back to **PM Review** when ready |
-| **GitHub writes** | Commits on existing PR branch |
-| **Must not do** | Merge PRs; ignore PM feedback |
+| **Trigger / status** | **Ready for Build** (create); **Needs Revision** (resume follow-up); **Merging** agent repair (resume follow-up when deterministic repair is insufficient) |
+| **Input** | Linear issue, plan comment (if `requires-plan`), repo context; revision adds PM feedback; repair adds PR/check context |
+| **Output** | Feature branch, commits, PR (implementation); additional commits and revision summary (revision); repair commits or summary (agent repair) |
+| **Linear writes** | Hidden metadata: `builder_agent_id`, `builder_thread_generation`, `builder_thread_action`, `builder_origin_run_id`, `builder_thread_idempotency_key`, and replacement fields when applicable; phase-specific `cursor_agent_id` / `cursor_run_id` remain as Cursor evidence |
+| **GitHub writes** | Branch, commits, PR (implementation); commits on existing branch (revision / repair) |
+| **Must not do** | Merge PRs; create a separate revision or repair cloud agent when lineage can be resumed; replace Builder on transient resume or uncertain-send failures |
+
+Implementation creates generation `1`. Revision and agent repair resolve the canonical Builder from durable Linear metadata, call `Agent.resume` (unarchive when needed), and send follow-up prompts with stable idempotency keys. Replacement Builders are created only for definitive agent loss or exhausted legacy lineage.
+
+### Revision Agent (deprecated role name)
+
+The historical **Revision Agent** label referred to a separate Cursor cloud agent. Current behavior uses the **Builder** thread resumed from handoff / implementation markers. Docs and prompts may still say "revision" for the phase, but there is no independent revision agent role.
 
 ### Merge / Deployment Reporter
 
@@ -245,8 +261,8 @@ Automations and agents must treat **durable artifacts** as the source of truth.
 | Principle | Detail |
 |-----------|--------|
 | **Durable state required** | Linear comments, GitHub PR/commits/branch, Vercel preview URLs, and issue fields must hold enough context to resume work |
-| **Session reuse is optional** | Reusing an existing agent session is a happy-path optimization when Cursor supports it and it saves tokens |
-| **Fresh agent recovery** | A new agent must always be able to reconstruct context from Linear, GitHub, branch, PR, commits, Vercel preview, and Linear comments |
+| **Session reuse is optional** | Resuming the canonical Builder via Cursor `Agent.resume` is the happy path when lineage is valid |
+| **Fresh agent recovery** | A replacement Builder (or Planner for planning-only work) must always be able to reconstruct context from Linear, GitHub, branch, PR, commits, Vercel preview, and Linear comments |
 | **No hidden memory** | Hidden agent or session memory must **never** be the source of truth |
 
 Before advancing Linear status, the agent must ensure the required durable artifact exists (plan comment, PR link, revision summary, etc.).

package/workspace-snapshot/files/docs/design/product-development-harness-gui.md

@@ -885,7 +885,6 @@ Deliverables:
 
 - ordered guided stepper as the default first-run experience
 - shared readiness / blocker / next-action model over existing setup summaries
-- advanced checklist dashboard escape hatch with the same readiness model
 - final ready/blocked state without live harness run trigger
 
 Non-goals for M6:

package/workspace-snapshot/files/docs/getting-started.md

@@ -2,14 +2,14 @@
 
 Operator guide for the Product Development Harness.
 
-**Current release:** v0.3.1 — see [`docs/releases/v0.3.1.md`](releases/v0.3.1.md)
+**Current release:** v0.4.0 — see [`docs/releases/v0.4.0.md`](releases/v0.4.0.md)
 
 ## Choose your path
 
 ### Product managers — use p-dev (recommended)
 
 ```bash
-npx --yes p-dev-harness@0.3.1
+npx --yes p-dev-harness@0.4.0
 ```
 
 - Node.js **22+** required

package/workspace-snapshot/files/docs/gui-local.md

@@ -2,12 +2,12 @@
 
 Launch the Product Development Harness GUI for guided Settings / Configure setup.
 
-**v0.3.1 paths:**
+**v0.4.0 paths:**
 
-- **Product managers (packaged):** `npx --yes p-dev-harness@0.3.1` — see [`docs/p-dev.md`](p-dev.md)
+- **Product managers (packaged):** `npx --yes p-dev-harness@0.4.0` — see [`docs/p-dev.md`](p-dev.md)
 - **Contributors (source):** `npm run harness:configure` — this document
 
-The guided Configure flow has **seven steps** before the completion screen. See [`docs/gui-remote-setup.md`](gui-remote-setup.md) for remote setup and Step 7 workflow finalization.
+The guided Configure flow has **seven steps** before the completion screen. Fresh Configure visits first show a **Data sharing** gate; after you continue, the guided stepper appears at the derived current step. Change the choice later from **Settings → Data sharing**. See [`docs/gui-remote-setup.md`](gui-remote-setup.md) for remote setup and Step 7 workflow finalization.
 
 ## Canonical local testing (recommended)
 

package/workspace-snapshot/files/docs/gui-remote-setup.md

@@ -2,9 +2,9 @@
 
 Guided remote setup for harness repo GitHub Actions secrets and target-repo production sync workflow install PRs.
 
-**v0.3.1:** The seven-step Configure GUI includes remote setup in Steps 2–3, 6–7. Step 7 **automatically** validates, merges, and verifies system-owned workflow install PRs when checks pass — it does not leave manual merge as the only path. Ordinary product implementation PRs remain governed by Linear status gates.
+**v0.4.0:** The seven-step Configure GUI includes remote setup in Steps 2–3, 6–7. Step 7 **automatically** validates, merges, and verifies system-owned workflow install PRs when checks pass — it does not leave manual merge as the only path. Ordinary product implementation PRs remain governed by Linear status gates.
 
-Packaged launch: `npx --yes p-dev-harness@0.3.1` — see [`docs/p-dev.md`](p-dev.md).
+Packaged launch: `npx --yes p-dev-harness@0.4.0` — see [`docs/p-dev.md`](p-dev.md).
 
 **Related:** [`docs/gui-local.md`](gui-local.md), [`docs/security.md`](security.md), [`docs/operator-config.md`](operator-config.md), [`docs/production-sync-automation.md`](production-sync-automation.md)
 

package/workspace-snapshot/files/docs/issue-intake.md

@@ -101,8 +101,20 @@ Project descriptions may include:
 ```text
 Harness metadata:
 Target repo: owner/repo
+Product initialization: uninitialized
 ```
 
+For PDev-created products, Linear project metadata is written during workspace setup and updated to `initialized` after the approved foundation PR merges to the development branch.
+
+### ChatGPT vs Cursor inspection
+
+| Path | Product initialization signal |
+|------|------------------------------|
+| **ChatGPT intake** | Reads `Harness metadata:` from the Linear project description (or asks the PM) |
+| **Cursor issue-intake skill** | May inspect the target repo marker on the **development branch** (`dev` by default) via GitHub |
+
+Neither path should assume application deployment is configured from `.p-dev/product.json`. Runtime preview/deployment capability comes from harness `repos[].previewProvider` only.
+
 Required description sections:
 
 - `## Target repo` (include when known — derived from project metadata or PM override)

package/workspace-snapshot/files/docs/observability-and-privacy.md

@@ -0,0 +1,247 @@
+# Observability and privacy
+
+This document is the canonical contract for optional, consent-gated observability in the published `p-dev-harness` npm package.
+
+## Purpose
+
+Packaged observability helps the maintainer understand onboarding reliability and Configure funnel outcomes without collecting source code, credentials, prompts, or account identity.
+
+Telemetry is **evidence, not authoritative**. Never trigger releases, security actions, or Linear issues solely from Sentry or PostHog data.
+
+## Consent model
+
+Two independent categories:
+
+1. **Anonymous product analytics** (PostHog)
+2. **Automated sanitized error reports** (Sentry)
+
+Defaults:
+
+- No network transmission until the user chooses for each category.
+- Consent changes are local preferences only and do **not** emit analytics events.
+- Environment kill switches override persisted preferences without mutating them:
+  - `DO_NOT_TRACK=1`
+  - `P_DEV_OBSERVABILITY_DISABLED=1`
+  - `P_DEV_ANALYTICS_DISABLED=1`
+  - `P_DEV_SENTRY_DISABLED=1`
+
+Local state path: `.harness/observability.local.json` under the resolved `P_DEV_HOME`.
+
+## Identity
+
+| Field | PostHog | Sentry |
+|-------|---------|--------|
+| Session ID (ephemeral) | yes | yes |
+| Installation ID (stable per `P_DEV_HOME`) | yes (`distinct_id`) | **no** |
+| Package version / release SHA | yes | yes (release/tags) |
+
+The installation ID is generated only when analytics is first enabled.
+
+## Runtime boundary
+
+Observability runs only in packaged `p-dev` runtime (`P_DEV_RUNTIME_MODE=packaged`). It is disabled in source development, tests, CI, package preparation, snapshot generation, and other non-packaged contexts unless tests inject fake transports.
+
+## Public vendor configuration
+
+Tracked source file: `config/observability.public.json`
+
+Package copy: `observability.public.json`
+
+Contains only:
+
+- Sentry public DSN
+- PostHog project token
+- PostHog ingestion host
+- Observability schema version
+
+Maintainer-only overrides (not required for end users):
+
+- `P_DEV_SENTRY_DSN`
+- `P_DEV_POSTHOG_PROJECT_TOKEN`
+- `P_DEV_POSTHOG_HOST`
+- `P_DEV_SENTRY_ENVIRONMENT`
+
+Never ship Sentry auth tokens, PostHog personal API keys (`phx_`), or organization-management credentials.
+
+## PostHog event contract (schema version 1)
+
+Allowed events:
+
+- `p_dev_session_started`
+- `p_dev_configure_step_viewed`
+- `p_dev_configure_step_completed`
+- `p_dev_workspace_provision_started`
+- `p_dev_workspace_provision_completed`
+- `p_dev_workspace_provision_failed`
+- `p_dev_setup_completed`
+
+Consent preference events are intentionally excluded.
+
+All analytics events set `$process_person_profile: false`.
+
+## Sentry context contract (schema version 1)
+
+Allowed tags/context include package/release metadata, ephemeral session ID, lifecycle phase, structured product error codes, bounded buckets, and sanitized exception data.
+
+Sentry fingerprints use structured product error code and lifecycle phase only (not package version).
+
+## Sentry outbound privacy boundary
+
+The Sentry adapter builds allowlisted error events and sends them through an isolated `NodeClient` using `sendEvent()`, bypassing default SDK scope merge and tracing integrations.
+
+### Client envelope guarantees
+
+Automated envelope tests prove the structured outbound payload omits:
+
+- `user`, `request`, `breadcrumbs`, `transaction`, `server_name`, `contexts`
+- `ip_address`, `trace_id`, `span_id`, `parent_span_id`, installation ID
+- tracing/profiling client options (rates are omitted entirely, not set to `0`)
+- envelope-header `trace` metadata
+
+Allowed content is limited to approved product error messages, sanitized exception metadata, allowlisted tags, package/release metadata, ephemeral session ID, and fingerprints based on product error code plus lifecycle phase.
+
+Production enforcement is best-effort: if a final outbound event or envelope cannot be scrubbed into compliance, the adapter **drops** it and continues harness execution. Automated tests **throw** on the same violations.
+
+### Vendor-derived metadata (not client fields)
+
+Sentry may derive metadata during HTTP ingestion that does not appear in the client-built event JSON:
+
+- **Geography** under User in the Sentry UI is commonly derived from the ingestion request IP, not from a `user` field sent by this harness.
+- **Trace Details / Trace Preview** in the Sentry UI may appear even when the client envelope contains no trace context. Inspect the raw stored event JSON; do not treat UI chrome alone as proof of client transmission.
+
+Official Sentry server-side scrubbing documents that geographic information can be extracted from IP even when "Prevent storing IP addresses" is enabled. Removing stored geo requires an Advanced Data Scrubbing rule.
+
+### Mandatory Sentry project settings (release gate)
+
+Before enabling a public DSN in `config/observability.public.json`, verify the target Sentry project (`kinterra/p-dev-harness`, US ingestion region) has all of the following settings and that live sandbox raw-event evidence matches them.
+
+**Required privacy settings**
+
+- Data Scrubber: enabled
+- Default Scrubbers: enabled
+- Prevent Storing IP Addresses: enabled
+- Advanced Data Scrubbing: `[Remove] [Anything] from [$user.geo.**]`
+- Advanced Data Scrubbing: `[Remove] [Anything] from [contexts.trace]`
+
+**Required disabled capabilities**
+
+Keep these disabled unless repository evidence explicitly requires otherwise:
+
+- tracing / performance monitoring
+- profiling
+- replay
+- logs
+- metrics
+- AI monitoring
+- automatic HTTP instrumentation
+- automatic console instrumentation
+- source-map uploading
+- JavaScript source fetching
+- SCM source context
+
+**Other expected settings**
+
+- TLS verification enabled
+- Spike Protection enabled
+- Auto Resolve disabled
+- no user-identifying integrations enabled
+
+**Packaged credential boundary**
+
+- The public DSN is packaged in `config/observability.public.json` and copied into the npm tarball.
+- Sentry auth tokens, organization-management tokens, and source-map upload credentials must never be packaged.
+- Sentry capture starts only after affirmative error-reporting consent; consent withdrawal must stop subsequent capture.
+
+**Vendor UI vs stored fields**
+
+- Sentry may show trace-related issue UI even when stored `contexts.trace` has been scrubbed.
+- Raw stored event JSON and authoritative Discover fields are the release gate; do not treat UI chrome alone as proof of client transmission.
+
+Release remains blocked until:
+
+- automated envelope tests pass in CI
+- sandbox raw event JSON shows no `user`, `user.geo`, `ip_address`, or `contexts.trace`
+- the project settings above are verified on the target Sentry project
+- source maps, JavaScript source fetching, and SCM source context remain disabled
+
+## Dashboard: p-dev Packaged Onboarding Health
+
+**Status:** implemented in PostHog project `p-dev-harness` (US region, `https://us.i.posthog.com`).
+
+Machine-readable contract: [`src/observability/posthog-dashboard-contract.ts`](../src/observability/posthog-dashboard-contract.ts)
+
+Dashboard identity:
+
+- **Name:** `p-dev Packaged Onboarding Health`
+- **Default date range:** last 30 days
+- **Dashboard filters:** `package_version`, `release_sha`, `os_family`
+
+Mandatory cards:
+
+1. Interpretation (Markdown)
+2. Packaged Sessions by Release (`p_dev_session_started` by `package_version`)
+3. Packaged Sessions by OS (`p_dev_session_started` by `os_family`)
+4. Session to Setup Completion (`p_dev_session_started` → `p_dev_setup_completed`)
+5. Configure Step Completion Funnel (all eight `p_dev_configure_step_completed` steps with `completion_outcome` in `success` / `skipped_already_complete`, or the authorized split funnels Steps 1–4 and Steps 5–8)
+6. Configure Outcomes by Step (`step_id` × `completion_outcome`)
+7. Workspace Provisioning Outcomes (started / completed / failed trends)
+8. Provisioning Failure Categories (`failure_category`)
+9. Provisioning Duration Buckets (`duration_bucket`)
+10. Provisioning Retry Buckets (`retry_count_bucket`)
+11. Rate-Limit Pause Buckets (`rate_limit_pause_count_bucket`)
+
+PostHog project privacy settings (defense in depth):
+
+- Discard client IP data: enabled
+- GeoIP enrichment: disabled
+- Person profiles: disabled (`$process_person_profile: false` on every event)
+- Server-only transport (no browser SDK, autocapture, session replay, or web analytics)
+
+Public packaged configuration:
+
+- Organization: `Kinterra`
+- Project: `p-dev-harness`
+- Public project ingestion token is packaged in `config/observability.public.json` and mirrored to `packages/p-dev/observability.public.json`
+- Personal API keys (`phx_`), MCP credentials, and organization-management credentials are forbidden in tracked files and tarballs
+
+Do not build consent-rate metrics; affirmative consent makes non-consenting installs intentionally invisible.
+
+Reconstruction procedure: use PostHog MCP (`dashboard-create`, `insight-create`, `dashboard-create-text-tile`) with query definitions from `posthog-dashboard-contract.ts`. Validate saved dashboard and insight definitions against the repository contract before merge.
+
+## PostHog release validation
+
+Before an observability-enabled npm release:
+
+- Verify legacy `Default Project` deletion and clean `p-dev-harness` project creation
+- Verify packaged public PostHog token (not `phx_`) and unchanged Sentry public DSN
+- Verify no pre-consent telemetry in packaged smoke tests
+- Verify tarball includes public config and excludes local observability state
+- Verify live packaged validation sequence `0 / 1 / 1` for `p_dev_session_started`
+- Verify stored PostHog events satisfy the privacy allowlist and create no person profile
+- Verify dashboard insight queries execute against validation data
+- Run `tests/observability/posthog-dashboard-contract.test.ts`
+
+## Sentry alerts (minimal)
+
+- New unhandled error in latest package
+- Regression of resolved issue
+- High-frequency provisioning error
+- Launch / Configure API crash
+- Error rate increase by release version
+
+## Reset
+
+Delete `.harness/observability.local.json` to clear local data-sharing preferences and telemetry identity. Configure no longer exposes a reset control; use **Settings → Data sharing** to change preferences after onboarding.
+
+## Release validation
+
+Before an observability-enabled npm release:
+
+- Verify no pre-consent telemetry in packaged smoke tests
+- Verify tarball includes public config and excludes local observability state
+- Verify sandbox Sentry/PostHog payloads match allowlists
+- Compare funnel/error metrics by `package_version` after fixes
+- Verify automated Sentry envelope privacy tests pass
+- Verify sandbox raw event JSON and mandatory Sentry project privacy settings before authorizing a public DSN
+
+Do not claim legal compliance in this document.

package/workspace-snapshot/files/docs/operator-config.md

@@ -55,7 +55,7 @@ GUI-assisted fields:
 | Surface | Fields |
 |---------|--------|
 | `.env.local` | `HARNESS_CONFIG_PATH`, `LINEAR_API_KEY`, `CURSOR_API_KEY`, `GITHUB_TOKEN` |
-| `.harness/config.local.json` | `linear.teamKey`, model id, per-repo `id`, `targetRepo`, branches, preview provider/URLs, Linear status names, validation commands |
+| `.harness/config.local.json` | `linear.teamKey`, `linear.teamId`, model id, per-repo `id`, `targetRepo`, branches, `previewProvider` (`vercel` or `none`), preview URLs, Linear status names, validation commands |
 
 Local GUI docs: [`docs/gui-local.md`](../gui-local.md)
 
@@ -147,6 +147,21 @@ Operator replaces:
 
 ---
 
+## Application preview provider (`previewProvider`)
+
+Each `repos[]` entry may set `previewProvider`:
+
+| Value | Meaning |
+|-------|---------|
+| `"vercel"` | Harness polls target-repo PR comments and production merge output for Vercel application preview/deployment URLs. |
+| `"none"` | Skip application preview capture. Handoff, implementation, revision, and merge phases log `application_preview_not_configured` and continue without polling. |
+
+`previewProvider: "none"` does **not** disable the **PDev automation bridge** (Linear webhook → harness dispatch). That bridge is configured separately in guided setup Step 3 and still requires `VERCEL_TOKEN` when used.
+
+Use `"none"` when the target app is not deployed on Vercel or when PM review should proceed without automated preview URLs.
+
+---
+
 ## Branch protection
 
 Target repos should use integration branch + production branch strategy. See [`docs/target-repo-branch-setup.md`](target-repo-branch-setup.md).

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

@@ -4,7 +4,7 @@
 
 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**.
+`p-dev` launches the guided **Configure GUI** without cloning the harness source repository. It is the primary product-manager path for **v0.4.0**.
 
 ## What p-dev is
 
@@ -34,7 +34,7 @@ On non-macOS platforms, use `--no-open` and open the printed Configure URL manua
 Pinned release:
 
 ```bash
-npx --yes p-dev-harness@0.3.1
+npx --yes p-dev-harness@0.4.0
 ```
 
 Latest channel:
@@ -46,20 +46,20 @@ npx --yes p-dev-harness
 Do not open a browser automatically:
 
 ```bash
-npx --yes p-dev-harness@0.3.1 --no-open
+npx --yes p-dev-harness@0.4.0 --no-open
 ```
 
 Use a custom workspace directory:
 
 ```bash
-npx --yes p-dev-harness@0.3.1 --workspace /path/to/workspace
+npx --yes p-dev-harness@0.4.0 --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
+npx --yes p-dev-harness@0.4.0
 ```
 
 Default workspace when neither flag nor env is set: `~/.p-dev`.
@@ -119,7 +119,7 @@ Optional advanced override: `HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY` (integer `1`
 
 ### 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.
+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.4.0 installs.
 
 ## Seven guided setup stages
 
@@ -128,13 +128,39 @@ Valid existing managed workspaces created by `p-dev-harness@0.3.0` from `weston-
 | 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) |
+| 4 | Choose target repo(s) | **Create** a technology-neutral product repository or **connect** an existing GitHub repo URL, then preview and confirm local setup files (confirmation-gated local writes only) |
 | 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 4 — Create or connect target repository
+
+Step 4 offers two paths:
+
+| Mode | What it does |
+|------|----------------|
+| **Create new product** | Preview and confirm GitHub repository creation via `preview-target-repo-provisioning` / `apply-target-repo-provisioning`. Provisions `main`, `dev`, `README.md`, and `.p-dev/product.json` only. |
+| **Connect existing** | Enter and verify an existing GitHub target repo URL (unchanged flow). |
+
+**Explicit local-config consent (sequential):**
+
+1. Repository create apply (when using Create) populates the guided target-repo form with URL, `baseBranch: dev`, `productionBranch: main`, and `previewProvider: none`.
+2. Repository confirmation **does not** write `.env.local` or `.harness/config.local.json`.
+3. The operator must still run **Preview local setup files** and confirm **Create local setup files** before Step 4 completes.
+
+New PDev-created repositories default to `previewProvider: "none"` (application deployment capture disabled). The **PDev automation bridge** (Step 3) is separate and still uses `VERCEL_TOKEN` when configured.
+
+### Provisioning vs foundation CI boundary
+
+Repository **creation** installs only:
+
+- Generic bootstrap files (`README.md`, `.p-dev/product.json`)
+- The generic PDev target workflow (Step 7)
+
+It does **not** install stack-specific CI, required branch checks, language manifests, or application deployment configuration. Those belong to the **approved foundation PR** during product initialization after the stack is chosen.
+
 ### Step 7 workflow finalization
 
 For harness-owned setup PRs, Step 7:
@@ -187,7 +213,7 @@ Operator workspace files under `P_DEV_HOME` or `~/.p-dev` are separate from npm
 - **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
+- **No automatic silent upgrade** of an already-created private harness workspace — use **Settings → Deployments → Update PDev runner** for an operator-initiated upgrade (three-way conflict blocking + GitHub Actions config canary). Automatic background upgrade/sync remains unsupported.
 - **Not production-grade SaaS** or provider-agnostic
 - Manual eval rubrics remain where automation is not implemented
 
@@ -204,9 +230,17 @@ npm run harness:configure
 
 See [`docs/getting-started.md`](getting-started.md) and [`README.md`](../README.md).
 
+## Optional observability
+
+Packaged runs offer a unified, opt-in **Data sharing** choice in Configure before setup begins. The same preference can be changed later from **Settings → Data sharing**. When enabled, both anonymous product analytics and automated sanitized error reports may be sent; when disabled, both remain off.
+
+No network transmission occurs before you choose. Local preferences live in `.harness/observability.local.json` under your workspace. Source-development runs (`npm run harness:configure`) do not send telemetry, but source launchers still supply a process-scoped nonce so local preference writes can persist.
+
+Canonical contract: [`docs/observability-and-privacy.md`](observability-and-privacy.md)
+
 ## Related docs
 
-- Release contract: [`docs/releases/v0.3.1.md`](releases/v0.3.1.md)
+- Release contract: [`docs/releases/v0.4.0.md`](releases/v0.4.0.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)