p-dev-harness 0.3.0 → 0.3.1

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/operator-config.md

@@ -0,0 +1,187 @@
+# Operator configuration
+
+Guide for private target-repo configuration so production sync and harness automation work for operator-specific repos without committing personal wiring to the public harness repo.
+
+**Related:** [`docs/getting-started.md`](getting-started.md), [`docs/production-sync-automation.md`](production-sync-automation.md), [`docs/security.md`](security.md)
+
+---
+
+## Overview
+
+The committed [`harness.config.json`](../harness.config.json) is a **generic example** (`target-app`, `owner/example-target-app`). Real operator target repos belong in **private configuration** loaded at runtime.
+
+Config resolution order (fail closed):
+
+1. **Explicit CLI `--config`** — only when `argv` contains `--config` (overrides ambient env)
+2. **`HARNESS_CONFIG_JSON_B64`** — base64-encoded JSON (GitHub Actions secret)
+3. **`HARNESS_CONFIG_JSON`** — raw JSON string (local/debug)
+4. **`HARNESS_CONFIG_PATH`** — path to a local config file
+5. **`harness.config.json`** — committed default example
+
+If the resolved source is missing, unreadable, or invalid, harness commands exit non-zero.
+
+---
+
+## Recommended local setup
+
+**GUI path (recommended):**
+
+1. `npm run harness:gui` — guided Settings / Configure forms with preview and confirmation-gated local writes
+2. Apply `.env.local` and `.harness/config.local.json` from the GUI, or use CLI scaffold below as fallback
+3. `npm run harness:doctor`
+
+**CLI scaffold path:**
+
+1. `npm run harness:operator:init` — scaffolds `.env.local` and `.harness/config.local.json` from committed examples via setup core services (does not overwrite unless `--force`)
+2. Edit `.harness/config.local.json` with your real target repo mapping
+3. Keep `HARNESS_CONFIG_PATH=.harness/config.local.json` in `.env.local`
+4. `npm run harness:doctor`
+
+| File | Role |
+|------|------|
+| `.env.local` | Local secrets and `HARNESS_CONFIG_PATH` pointer (gitignored) |
+| `.harness/config.local.json` | Structured private target-repo config (gitignored) |
+| [`.harness/config.example.json`](../.harness/config.example.json) | Committed starter template (single target repo) |
+| [`harness.config.json`](../harness.config.json) | Committed public example/fallback when no private source is set |
+
+The starter config in `.harness/config.example.json` is for first-time users with **one** target repo. Add more entries to `repos[]` and `allowedTargetRepos[]` for every repo you want the harness to manage.
+
+Setup core services in [`src/setup/`](../src/setup/) power `harness:operator:init`, the local Product Development Harness GUI Settings / Configure screen (`npm run harness:gui`), confirmation-gated local file writes (`src/setup/local-apply-actions.ts`), and confirmation-gated remote harness secret / target workflow PR writes (`src/setup/remote-apply-actions.ts`). They support dry-run previews, local and remote writes after confirmation, permission classification, and manual instruction generation without changing runtime harness automation behavior.
+
+**Remote setup (GUI):** after local config is in place, use Settings / Configure → **Remote setup** to preview and apply harness repo Actions secrets and target workflow install PRs. See [`docs/gui-remote-setup.md`](../gui-remote-setup.md).
+
+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 |
+
+Local GUI docs: [`docs/gui-local.md`](../gui-local.md)
+
+---
+
+## Private config is a full replacement (not an overlay)
+
+**`HARNESS_CONFIG_JSON_B64` and other private config sources replace the whole harness config for that run.** They do **not** merge with or overlay committed [`harness.config.json`](../harness.config.json).
+
+When a private source wins the resolution chain, only that JSON is used. Any repo id the harness must resolve in cloud automation must appear in the private config itself, with matching entries in both `repos[]` and `allowedTargetRepos[]`.
+
+**Example:** If an operator sets `HARNESS_CONFIG_JSON_B64` with only one private target repo, harness self-automation may stop resolving the `harness` repo id from the committed fallback. For an operator managing multiple repos (e.g. `my-app` and the harness repo itself), the private config must include **every** repo the harness should manage — not just the newest target.
+
+Do not solve this by committing operator-specific values to the public repo. Document and maintain the full private JSON locally and in `HARNESS_CONFIG_JSON_B64`.
+
+---
+
+## Local development
+
+Point at a private config file:
+
+```bash
+export HARNESS_CONFIG_PATH=/path/to/private/harness.config.json
+npm run harness:doctor
+```
+
+Or pass an explicit file (overrides env):
+
+```bash
+npm run harness:doctor -- --config /path/to/private/harness.config.json
+```
+
+Inline JSON for quick tests:
+
+```bash
+export HARNESS_CONFIG_JSON='{"version":1,...}'
+npm run harness:doctor
+```
+
+---
+
+## GitHub Actions (private operator config)
+
+1. Maintain a **private** config locally at `.harness/config.local.json` (via `npm run harness:operator:init`) — do not commit operator target repos to the public harness repo.
+2. Ensure the private JSON includes **every** repo the harness should manage in `repos[]` and `allowedTargetRepos[]` (full replacement — see above).
+3. Base64-encode the full config (no newlines):
+
+   ```bash
+   base64 < .harness/config.local.json | tr -d '\n'
+   ```
+
+4. Store the result as GitHub Actions secret **`HARNESS_CONFIG_JSON_B64`** on the harness repo.
+5. The secret must include all operator `repos[]` entries, Linear mappings, and `allowedTargetRepos` — it replaces committed `harness.config.json` for cloud runs.
+
+The harness workflow sets `HARNESS_CONFIG_JSON_B64` on all jobs (`gate`, `run-harness`, `run-merge`, `sync-production`). Because GHA does not pass `--config`, the secret is used automatically.
+
+---
+
+## Migrating from public target-app config
+
+The committed [`harness.config.json`](../harness.config.json) demonstrates shape only — it is **not** an operator’s live target-repo wiring.
+
+To run production sync for a real target repo:
+
+1. Copy the example config to a **private file** and add your target repo under `repos[]` with a stable `id` (e.g. `real-target`).
+2. Add the target URL to `allowedTargetRepos`.
+3. Set **`HARNESS_CONFIG_JSON_B64`** in harness repo Actions secrets with the full private JSON.
+4. Update the **target repo dispatch workflow** ([`tests/fixtures/workflows/trigger-harness-production-sync.yml`](../tests/fixtures/workflows/trigger-harness-production-sync.yml)) so the `production_promoted` payload `repo` field matches your private config `repos[].id` (not necessarily `target-app`).
+5. Until private config is present, production sync **fails closed** with `unknown_repo_id` when dispatch references a repo id not in the resolved config.
+
+See [`docs/production-sync-automation.md`](production-sync-automation.md) for dispatch payload shape and trigger workflow setup.
+
+---
+
+## Target repo dispatch workflow
+
+Install in each target repo (not in the harness repo):
+
+- Path: `.github/workflows/trigger-harness-production-sync.yml`
+- Canonical fixture: [`tests/fixtures/workflows/trigger-harness-production-sync.yml`](../tests/fixtures/workflows/trigger-harness-production-sync.yml)
+
+Operator replaces:
+
+- Harness dispatch URL (owner/repo of harness installation)
+- Payload `repo` → private config `repos[].id`
+- Payload `sourceRepo` → `owner/target-repo` slug matching configured `targetRepo`
+
+**Guards:** runs only on production branch pushes (e.g. `main`), not integration branch pushes.
+
+---
+
+## Branch protection
+
+Target repos should use integration branch + production branch strategy. See [`docs/target-repo-branch-setup.md`](target-repo-branch-setup.md).
+
+Production sync assumes merge commits are promoted to the configured `productionBranch` before dispatch fires.
+
+---
+
+## Token boundary
+
+| Credential | Where | Purpose |
+|------------|-------|---------|
+| `HARNESS_CONFIG_JSON_B64` | Harness GHA secrets | Private config (sensitive metadata, not a write token) |
+| `LINEAR_API_KEY`, `CURSOR_API_KEY`, `HARNESS_GITHUB_TOKEN` | Harness GHA secrets | Live harness phases |
+| `HARNESS_DISPATCH_TOKEN` | Target repo GHA secrets | Dispatch-only PAT scoped to harness repo |
+
+Full matrix: [`docs/security.md`](security.md)
+
+Do **not** put merge-capable tokens or Linear/Cursor keys in target repos or Vercel.
+
+---
+
+## Validation
+
+```bash
+npm run harness:doctor
+HARNESS_CONFIG_PATH=/path/to/private.json npm run harness:doctor
+npm test
+npm run test:webhook
+```
+
+After setting `HARNESS_CONFIG_JSON_B64`, validate cloud config loading safely:
+
+1. **Config smoke test:** `workflow_dispatch` with `sync_repo=harness` (or a repo where integration and production branches match) — expect no-op success when branches match.
+2. **Target repo dry-run:** `workflow_dispatch` with `sync_repo=<your-repo-id>` and `sync_dry_run=true` (default) — inspects sync without Linear writes.
+3. **Live sync:** set `sync_dry_run=false` only when ready for real Linear status updates.
+
+See [`docs/production-sync-automation.md`](production-sync-automation.md) for dispatch examples. For `production_promoted` **repository_dispatch**, sync always runs live (no dry-run).