p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/docs/milestones/m5-revision-phase.md

@@ -0,0 +1,101 @@
+# Milestone 5 — Revision phase
+
+**Status:** Implemented (Needs Revision → Revising → PM Review; no merge loop)
+
+## What exists
+
+- Live revision orchestration triggered from Linear **Needs Revision**
+- Reads latest durable **handoff** marker for `pr_url`, `branch`, `target_repo`, `preview_url`
+- Reads latest **PM feedback** comment after the handoff marker
+- Verifies linked GitHub PR is still open (`GITHUB_TOKEN` required)
+- Cursor SDK **cloud** revision agent on existing branch/PR (`autoCreatePR: false`)
+- Linear status transitions: **Needs Revision** → **Revising** → **PM Review** (or **Blocked** after entering Revising)
+- Revision summary comment with durable marker footer keyed to `pm_feedback_comment_id`
+- Post-success duplicate skip from **PM Review** when latest PM feedback already revised
+- Auto phase routing: **Needs Revision** → `revision`
+
+## What is deferred
+
+- Engineering Review transition
+- Merge/deploy automation
+- Watcher/poller
+- Releases and skills
+
+## Prerequisites
+
+1. Copy `.env.example` to `.env` and set:
+   - `LINEAR_API_KEY`
+   - `CURSOR_API_KEY`
+   - `GITHUB_TOKEN`
+2. Issue must have a prior handoff marker and PM feedback comment after handoff.
+3. Issue must be in **Needs Revision** (or **Revising** with `--force` retry).
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+npm run harness:doctor
+
+# Live revision
+npm run harness:run -- --issue WES-13 --phase revision
+
+# Auto phase infers revision from Needs Revision
+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
+
+**PR:** [target repo PR #4](https://github.com/owner/example-target-app/pull/4) (open, unmerged)
+
+**Human setup:**
+
+1. Add PM feedback comment: “Please change the Hello World page copy to say: Hello from the agentic harness.”
+2. Move WES-13: **PM Review → Needs Revision**
+
+**Live command:**
+
+```bash
+npm run harness:run -- --issue WES-13 --phase revision
+```
+
+**Pass criteria:**
+
+- WES-13: Needs Revision → Revising → PM Review
+- PR #4 updated on **same branch**; **no new PR**
+- Revision comment with marker footer (`phase: revision`, `pm_feedback_comment_id`, `previous_handoff_run_id`)
+- Post-success re-run from **PM Review** → duplicate skip (exit 0)
+
+## Artifacts
+
+```text
+runs/<issue>/<run-id>/
+  manifest.json
+  run-summary.md
+  events.jsonl
+  linear/
+    handoff-comment-loaded.md
+    pm-feedback-comment-loaded.md
+    revision-comment.md
+  prompts/revision-agent.md
+  outputs/revision-result.md
+  github/pr-before.json
+  github/pr-after.json
+  vercel/deployment.json
+```
+
+## Idempotency
+
+| Status | Matching revision marker for latest PM feedback | Result |
+|--------|-----------------------------------------------|--------|
+| Needs Revision | No | Proceed |
+| Needs Revision | Yes | Duplicate skip |
+| PM Review | Yes | Duplicate skip (post-success re-run) |
+| PM Review | No | `wrong_status` |
+| Other | — | `wrong_status` |

package/workspace-snapshot/files/docs/milestones/m6-merge-phase.md

@@ -0,0 +1,143 @@
+# Milestone 6 — Merge phase
+
+**Status:** Implemented (Ready to Merge → Merging → Merged / Deployed)
+
+## What exists
+
+- Live merge orchestration triggered from Linear **Ready to Merge**
+- Reads latest **revision** marker if present; otherwise latest **handoff** marker
+- Verifies GitHub PR is open, correct repo, and checks policy before merge
+- Squash merges PR via GitHub REST API (`GITHUB_TOKEN` with merge permission required)
+- Best-effort production deployment URL capture after merge
+- Posts merge completion comment with durable marker footer
+- Linear transitions: **Ready to Merge** → **Merging** → **Merged / Deployed**
+- Recovery path when PR already merged without merge marker
+- Integration repair after merge-queue drift: deterministic GitHub update-branch first, then a narrow Composer 2.5 Cursor repair agent if conflicts require local resolution
+- Post-success duplicate skip from **Merged / Deployed**
+- Auto phase routing: **Ready to Merge** → `merge`
+
+## What is deferred
+
+- Engineering Review
+- Release tags / GitHub Releases
+- Branch deletion (config flag `deleteBranchAfterMerge` defaults **false**)
+- Watcher/poller
+- Skills
+- Vercel API token integration
+
+## Prerequisites
+
+1. Copy `.env.example` to `.env` and set:
+   - `LINEAR_API_KEY`
+   - **`GITHUB_TOKEN`** with `repo` merge permissions and PR head-branch write (classic `repo`, or fine-grained Contents: Read and write plus Pull requests: Read and write)
+   - `CURSOR_API_KEY` when integration repair may need an agent
+2. Issue must have a prior handoff or revision marker with `pr_url`.
+3. PM must manually move issue **PM Review → Ready to Merge** before running merge.
+4. Run `npm run harness:doctor -- --profile merge`; doctor verifies base branches and target-repo write permission needed for PR branch repair.
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+npm run harness:doctor
+
+# Live merge
+npm run harness:run -- --issue WES-13 --phase merge
+
+# Auto phase infers merge from Ready to Merge
+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
+
+**PR:** [target repo PR #4](https://github.com/owner/example-target-app/pull/4)
+
+**Human setup:**
+
+1. Review PR #4 / preview manually.
+2. Move WES-13: **PM Review → Ready to Merge**
+
+**Live command:**
+
+```bash
+npm run harness:run -- --issue WES-13 --phase merge
+```
+
+**Pass criteria:**
+
+- WES-13: Ready to Merge → Merging → **Merged / Deployed**
+- PR #4 **squash merged** on GitHub
+- Completion comment with `phase: merge` marker footer
+- Deployment URL captured if available; warning only if not (default config)
+- Re-run from **Merged / Deployed** → duplicate skip (exit 0)
+
+## Checks policy (default)
+
+| Check state | Behavior |
+|-------------|----------|
+| success | Allow merge |
+| neutral / skipped | Allow merge |
+| failure / cancelled / action_required | Block (`checks_failing`) |
+| pending | Block (`checks_pending`) |
+| none / unreadable | Block (`checks_unknown`) |
+
+Override via `merge.allowPendingChecks` / `merge.allowUnknownChecks` in config.
+
+**Vercel preview note:** When GitHub check runs and commit statuses are inconclusive but the Vercel bot comment reports **Ready**, merge proceeds with a warning (see `validationSummary` in manifest).
+
+## Integration repair
+
+When a PR becomes `behind` or `dirty` after waiting in the serialized merge queue:
+
+1. The issue stays **Merging**.
+2. The runner verifies `GITHUB_TOKEN` can write PR head branches.
+3. The runner calls GitHub update-branch, which merges the latest base branch into the PR branch.
+4. If update-branch succeeds cleanly, the runner waits for checks and returns directly to merge.
+5. If update-branch cannot resolve conflicts, the runner launches a Composer 2.5 Cursor cloud repair agent on the PR branch.
+6. The repair agent fetches the base branch, locally merges base into head, resolves conflicts, commits, runs validation, and pushes the PR branch.
+7. The runner re-inspects the PR, waits for checks, and returns directly to merge if validation passes.
+8. If repair fails, is ambiguous, violates scope, or needs broader product judgment, the issue moves to **Blocked** with an actionable reason.
+
+Repair may edit conflict files and direct dependency-closure files required to compile and pass validation. It may not make unrelated product changes, broad refactors, broad formatting sweeps, or direct edits to `dev` / `main`.
+
+Canceled repair runs recover through **Harness Auto Runner** `workflow_dispatch` with the issue key, `phase=merge`, and force enabled. There is no Merging webhook re-dispatch in v1.
+
+## Artifacts
+
+```text
+runs/<issue>/<run-id>/
+  manifest.json
+  run-summary.md
+  events.jsonl
+  linear/
+    merge-source-comment-loaded.md
+    merge-completion-comment.md
+  github/
+    pr-before-merge.json
+    checks-before-merge.json
+    merge-result.json
+    pr-after-merge.json
+  prompts/
+    integration-repair-agent.md # only when agent repair runs
+  vercel/
+    production-deployment.json
+  outputs/
+    merge-recovery.json   # only on post-merge Linear failure
+```
+
+## Idempotency
+
+| Scenario | Result |
+|----------|--------|
+| Ready to Merge, PR open, no merge marker | Proceed |
+| Merge marker exists for PR URL | Duplicate skip |
+| Merged / Deployed | Duplicate skip |
+| PR merged, no merge marker | Recovery: post comment + move to Merged / Deployed |
+| PM Review (no Ready to Merge) | `wrong_status` |

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

@@ -0,0 +1,72 @@
+# Milestone 7 — Issue intake
+
+**Status:** Implemented (issue-intake skill, template alignment, validate-issue CLI)
+
+## What exists
+
+- **Issue intake skill** — [`.agents/skills/issue-intake/SKILL.md`](../.agents/skills/issue-intake/SKILL.md) interviews Weston and produces a Linear-ready issue package
+- **Parser-aligned template** — [`templates/linear-issue.md`](../templates/linear-issue.md)
+- **Operator guide** — [`docs/issue-intake.md`](../issue-intake.md)
+- **Read-only validator CLI** — `harness validate-issue` with route-specific `--intended-phase planning|implementation`
+- Reuses parser, resolver, allowlist, narrow heuristic, and planning-marker detection
+- Tests and fixtures for validation paths
+
+## What is deferred
+
+- Lead agent skill, `performance-cost-audit`, skill registry/package manager, manifests, provider/client adapters, and runner-skill integration (see [`docs/skills/skill-architecture.md`](../skills/skill-architecture.md))
+- ChatGPT/Linear automation for intake
+- Label enforcement in runner code
+- Writing to Linear from the validator
+
+## Prerequisites
+
+1. `harness.config.json` with repo mappings and `allowedTargetRepos`
+2. For `--issue` mode: `LINEAR_API_KEY` in `.env` (read-only fetch)
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+
+# Validate a draft file (planning route)
+npm run harness:validate-issue -- --file draft.md --intended-phase planning
+
+# Validate a draft file (build-direct route)
+npm run harness:validate-issue -- --file draft.md --intended-phase implementation
+
+# Validate a live Linear issue (read-only)
+npm run harness:validate-issue -- --issue WES-XX --intended-phase implementation
+
+# JSON output
+npm run harness:validate-issue -- --file draft.md --json
+
+# Regression: preflight dry-run still works
+npm run harness:run -- --issue WES-FIXTURE --dry-run \
+  --fixture tests/fixtures/issues/valid-target-app.md
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Passes route check (planning by default; implementation when `--intended-phase implementation`) |
+| 1 | CLI/config error (bad args, missing API key, invalid phase) |
+| 2 | Validation failure for the requested route |
+
+## Pass criteria
+
+- Skill output passes route-specific validator for recommended status
+- `--intended-phase implementation` fails broad issues at file-validation time
+- Validator catches `ambiguous_issue`, `missing_target_repo`, `unknown_repo_denied`
+- No Linear writes from validator
+- Full test suite green
+
+## Artifacts
+
+The validator prints a report to stdout only. It does not write under `runs/`.
+
+## Authoritative workspace
+
+Use `/Users/weston/Code/agentic-product-development-harness` (not the stale `.cursor` workspace clone).

package/workspace-snapshot/files/docs/milestones/m8-linear-watcher.md

@@ -0,0 +1,80 @@
+# Milestone 8 — Linear watcher / auto-runner
+
+**Status:** Implemented (Vercel webhook bridge + GitHub Actions auto-runner)
+
+## What exists
+
+- **Vercel webhook endpoint** — [`api/linear-webhook.ts`](../../api/linear-webhook.ts) verifies Linear signatures and dispatches GitHub `repository_dispatch`
+- **Webhook modules** — [`src/webhook/`](../../src/webhook/) (verify, parse, filter, dispatch)
+- **Dispatch allowlist** — only trigger statuses dispatch GHA: Ready for Planning, Ready for Build, PR Open, Needs Revision, Ready to Merge
+- **GitHub Actions runner** — [`.github/workflows/harness-auto-runner.yml`](../../.github/workflows/harness-auto-runner.yml)
+- **Manual fallback** — `workflow_dispatch` runs harness in cloud without local CLI
+- **Operator guide** — [`docs/linear-watcher-setup.md`](../linear-watcher-setup.md)
+- Tests under [`tests/webhook/`](../../tests/webhook/)
+
+## What is deferred
+
+- Polling Linear
+- Database-backed queue
+- Lead agent / autonomous repair agent
+- Production release tags
+- GitHub App (PAT-based dispatch is sufficient)
+
+## Prerequisites
+
+1. Vercel project with webhook env vars (see setup guide)
+2. GitHub Actions secrets: `LINEAR_API_KEY`, `CURSOR_API_KEY`, `HARNESS_GITHUB_TOKEN` (mapped to runtime `GITHUB_TOKEN`)
+3. Linear Issue webhook pointed at Vercel endpoint
+4. Harness repo default branch `main`
+
+## Architecture
+
+```text
+Linear status change
+  → Vercel /api/linear-webhook (verify + filter)
+  → GitHub repository_dispatch
+  → GitHub Actions harness-auto-runner
+  → npm run harness:run -- --issue WES-XX --phase auto
+```
+
+## Dispatch allowlist
+
+| Status | Dispatches GHA? | Harness phase |
+|--------|-----------------|---------------|
+| Ready for Planning | yes | planning |
+| Ready for Build | yes | implementation |
+| PR Open | yes | handoff |
+| Needs Revision | yes | revision |
+| Ready to Merge | yes | merge |
+| Planning, Building, PM Review, Merging, Merged / Deployed, etc. | no (`ignored_status`) | — |
+
+Harness remains authoritative for phase execution and idempotency once GHA runs.
+
+## Commands
+
+```bash
+npm install
+npm test
+npm run build
+npm run generate:config-schema
+npm run harness:doctor
+
+# Webhook unit tests only
+npm run test:webhook
+```
+
+## Manual validation gates
+
+See [`docs/linear-watcher-setup.md`](../linear-watcher-setup.md) for Gates 1–4.
+
+## Pass criteria
+
+- Unit tests green including webhook filter (`ignored_status`) cases
+- `workflow_dispatch` runs harness in GitHub Actions without local CLI
+- `repository_dispatch` triggers workflow with test payload
+- Live Linear status change to allowlisted status starts GHA run
+- Transitional statuses (Planning, PM Review, etc.) return `ignored_status` with no GHA run
+
+## Authoritative workspace
+
+Use `/Users/weston/Code/agentic-product-development-harness` or sync to `origin/main` before implementing follow-ups.

package/workspace-snapshot/files/docs/npm-packaging-spike.md

@@ -0,0 +1,52 @@
+# npm packaging spike (historical)
+
+**Status:** Historical — superseded by the public `p-dev` package in v0.3.0.
+
+The canonical end-user guide is [`docs/p-dev.md`](p-dev.md).
+
+## What this spike proved (now shipped)
+
+- A dedicated npm package boundary at [`packages/p-dev/`](../packages/p-dev/)
+- `npx --yes p-dev-harness@0.3.0` launch without cloning the source repository
+- Durable operator workspace under `P_DEV_HOME`, `--workspace`, or `~/.p-dev`
+- macOS browser auto-launch for the Configure GUI
+- Packaged guided setup through private harness workspace provisioning
+
+## Maintainer tarball validation
+
+From a clean repository checkout:
+
+```bash
+npm ci
+npm run build
+npm test
+npm run test:webhook
+npm run package:p-dev:pack
+npm run package:p-dev:inspect
+```
+
+Packed tarball smoke from a clean temporary directory:
+
+```bash
+TARBALL="/absolute/path/to/repo/packages/p-dev/p-dev-harness-0.3.0.tgz"
+WORKDIR=$(mktemp -d)
+export P_DEV_HOME="$WORKDIR/workspace"
+cd "$WORKDIR"
+npx --yes "file:$TARBALL" --no-open
+```
+
+Verify the printed Configure URL responds:
+
+```bash
+curl -fsS "http://localhost:3000/settings/configure" | head
+```
+
+## Source-development path
+
+Repo-local commands remain the contributor path:
+
+- `npm run harness:gui`
+- `npm run harness:configure`
+- `npm run harness:configure:stable`
+
+See [`docs/getting-started.md`](getting-started.md).

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.