p-dev-harness 0.3.0 → 0.4.0

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

@@ -0,0 +1,123 @@
+# Getting started
+
+Operator guide for the Product Development Harness.
+
+**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.4.0
+```
+
+- Node.js **22+** required
+- Starts the guided Configure GUI
+- Stores operator state under `~/.p-dev` (or `P_DEV_HOME` / `--workspace`)
+- macOS validated for browser auto-launch; use `--no-open` elsewhere
+
+Full guide: [`docs/p-dev.md`](p-dev.md)
+
+### Contributors — clone the source repository
+
+```bash
+git clone https://github.com/weston-uribe/agentic-product-development-harness.git
+cd agentic-product-development-harness
+npm ci
+npm run build
+npm test
+npm run harness:configure
+```
+
+GitHub Codespaces is supported for source-based development. See [`docs/gui-local.md`](gui-local.md) and [`docs/gui-remote-setup.md`](gui-remote-setup.md).
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Node.js 22+ | Required for source and `p-dev` |
+| Linear account | Team with harness workflow statuses |
+| GitHub account | Harness repo, target repos, and tokens |
+| Cursor API key | For live cloud agent phases |
+| Vercel account | For webhook bridge (cloud automation) |
+
+---
+
+## Source repository setup
+
+### Configuration
+
+Use private operator config — see [`docs/operator-config.md`](operator-config.md).
+
+**Recommended local setup:**
+
+1. `npm ci && npm run build`
+2. `npm run harness:configure` — guided Configure GUI
+3. Or `npm run harness:operator:init` — CLI scaffold
+4. `npm run harness:doctor` — validates config
+5. Base64-encode `.harness/config.local.json` for GitHub Actions secret `HARNESS_CONFIG_JSON_B64`
+
+### Where secrets go
+
+| Secret class | Store here |
+|--------------|------------|
+| `LINEAR_API_KEY`, `CURSOR_API_KEY`, `HARNESS_GITHUB_TOKEN` | GitHub Actions secrets |
+| `LINEAR_WEBHOOK_SECRET`, `GITHUB_DISPATCH_TOKEN` | Vercel production env |
+| Local dev tokens | Untracked `.env.local` |
+
+Full matrix: [`docs/security.md`](security.md)
+
+---
+
+## Local validation before live automation
+
+```bash
+npm run harness:validate-issue -- --file draft.md --intended-phase planning
+npm run harness:run -- --issue WES-FIXTURE --dry-run --fixture tests/fixtures/issues/valid-target-app.md
+npm run harness:doctor
+```
+
+---
+
+## Live setup (production automation)
+
+| Component | Guide |
+|-----------|-------|
+| Guided Configure GUI | [`docs/gui-local.md`](gui-local.md), [`docs/gui-remote-setup.md`](gui-remote-setup.md) |
+| p-dev packaged path | [`docs/p-dev.md`](p-dev.md) |
+| Linear webhook + Vercel bridge | [`docs/linear-watcher-setup.md`](linear-watcher-setup.md) |
+| Target repo branch strategy | [`docs/target-repo-branch-setup.md`](target-repo-branch-setup.md) |
+| Production sync | [`docs/production-sync-automation.md`](production-sync-automation.md) |
+| Security baseline | [`docs/security.md`](security.md) |
+
+---
+
+## PM issue intake
+
+1. Copy [`prompts/issue-intake-chatgpt.md`](../prompts/issue-intake-chatgpt.md) into ChatGPT, **or**
+2. Use [`.agents/skills/issue-intake/SKILL.md`](../.agents/skills/issue-intake/SKILL.md) in Cursor
+3. Validate: `npm run harness:validate-issue`
+
+---
+
+## What not to do
+
+- Do not commit secrets
+- Do not assume provider agnosticism — Cursor is the only implemented agent provider
+- Do not create git tags or GitHub releases from doc PRs — follow [`docs/releases/release-process.md`](releases/release-process.md)
+
+---
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| `p-dev` ENOSPC from npm cache | Clear npm cache; do not delete `~/.p-dev` unless resetting operator state |
+| Browser does not open | Use `--no-open` and open printed URL |
+| `validate-issue` fails | Compare draft to [`templates/linear-issue.md`](../templates/linear-issue.md) |
+| Auto-run does not trigger | Vercel env vars, Linear webhook URL, dispatch token scope |
+
+Architecture: [`ARCHITECTURE.md`](../ARCHITECTURE.md) · Agents: [`AGENTS.md`](../AGENTS.md)

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

@@ -0,0 +1,151 @@
+# Local GUI
+
+Launch the Product Development Harness GUI for guided Settings / Configure setup.
+
+**v0.4.0 paths:**
+
+- **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. 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)
+
+Run the stable dev server in **your own terminal** (not a read-only agent terminal):
+
+```bash
+npm run harness:configure:stable
+```
+
+Open:
+
+**http://localhost:3000/settings/configure**
+
+This is the operator-facing convention for M6 Configure GUI testing. `localhost` and `127.0.0.1` are equivalent loopback hosts, but this harness standardizes on **`localhost:3000`**.
+
+`harness:configure:stable` will:
+
+1. Stop stale Next.js GUI dev servers on ports **3000** and **3001** when they look like harness GUI processes.
+2. Refuse to start if port **3000** is occupied by a **non-GUI** process (clear error instead of switching ports).
+3. Start Next.js dev on **`localhost:3000`** without silently falling back to another port.
+4. Run a lightweight health check on `/settings/configure` and verify Next.js CSS assets load.
+5. If the page would render unstyled (missing `/_next/static` CSS), delete only **`apps/gui/.next`** and restart **once**.
+
+### If the page looks unstyled
+
+1. Stop the dev server (`Ctrl+C`).
+2. Run `npm run harness:configure:stable` again — it cleans `apps/gui/.next` when the health check detects broken static assets.
+3. Hard-refresh the browser on **http://localhost:3000/settings/configure**.
+
+Do **not** delete source files, `.env`, `.env.local`, `.harness/config.local.json`, backups, or secrets.
+
+## GitHub Codespaces
+
+Keep the dev server running in one terminal (do not Ctrl+C it). In another terminal, verify:
+
+```bash
+curl -I http://127.0.0.1:3000/settings/configure
+```
+
+That should return `HTTP/1.1 200 OK`.
+
+Start the GUI for port forwarding:
+
+```bash
+npm run harness:configure -- --host 0.0.0.0 --port 3000
+```
+
+Open the app from the **Ports** panel (globe icon on port **3000**), not by guessing the URL. Set port visibility to **Public** if the forwarded link fails. Append `/settings/configure` if needed.
+
+Next.js 15 blocks unknown dev origins by default. This repo allows `*.app.github.dev` in `apps/gui/next.config.ts` (`allowedDevOrigins`). Restart the dev server after changing that file.
+
+## Quick start (auto port fallback)
+
+```bash
+npm run harness:gui
+```
+
+Alias:
+
+```bash
+npm run harness:configure
+```
+
+Default bind: `http://localhost:3000/settings/configure`
+
+If port `3000` is busy, the quick launcher auto-picks the next available port. For repeatable operator testing, prefer **`npm run harness:configure:stable`** instead.
+
+## Port configuration
+
+- Stable canonical server: `npm run harness:configure:stable` (fixed `localhost:3000`)
+- CLI override (quick launcher): `npm run harness:gui -- --port 3333`
+- Env: `HARNESS_GUI_PORT=3333 npm run harness:gui`
+- Host: `HARNESS_GUI_HOST=localhost` (default)
+- Repo root: `HARNESS_REPO_ROOT` is set automatically by GUI launchers; setup files are resolved from the harness repo root, not `apps/gui`.
+
+## Scope (Milestone 4+)
+
+The GUI is local-first and supports guided local setup:
+
+- setup state summary
+- guided environment and target-repo forms
+- redacted preview before apply
+- explicit confirmation before local file writes
+- apply `.env.local` and `.harness/config.local.json` through setup core only
+- missing setup steps and local/static doctor summary
+
+Ordinary guided steps do **not** write GitHub Actions secrets, target repo workflows, cloud workflow dispatches, or harness phases without explicit confirmation. Confirmation-gated remote setup is integrated into the seven-step flow:
+
+- **Step 2:** Linear workspace setup (confirmation-gated)
+- **Step 3:** Vercel webhook bridge setup (confirmation-gated)
+- **Step 6:** harness repo GitHub Actions secret writes (confirmation-gated)
+- **Step 7:** target workflow install branch/PR creation and guarded finalization (confirmation-gated)
+
+The advanced **Remote setup** section also exposes the same remote actions — see [`docs/gui-remote-setup.md`](gui-remote-setup.md).
+
+## Guided local setup flow
+
+1. Open **Settings / Configure**.
+2. Edit environment fields (`.env.local`) and target repo config fields (`.harness/config.local.json`).
+3. Click **Generate preview** — required before apply.
+4. Review redacted `.env.local` preview and config JSON preview.
+5. Check the confirmation box and click **Apply local setup files**.
+
+Existing secret values in `.env.local` are shown as **Set** / **Missing** only. Leave a secret field blank to preserve an existing value.
+
+## API routes (local server only)
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/api/setup/summary` | GET | Read-only setup summary |
+| `/api/setup/preview-local-files` | POST | Dry-run preview with redaction |
+| `/api/setup/apply-local-files` | POST | Confirmation-gated local file writes |
+
+All writes go through setup core (`src/setup/local-apply-actions.ts`). Apply requires `confirmed: true` and a matching preview fingerprint.
+
+## Security
+
+- Secrets are never stored in browser `localStorage`, `sessionStorage`, or query params.
+- Existing secret values are never returned to the browser — presence only.
+- Newly entered secrets exist only in transient form state and POST bodies.
+- Secret values are never printed in GUI logs or API error responses.
+- Setup action previews use setup-core redaction before crossing the server boundary.
+
+## Design system
+
+The GUI uses Tailwind CSS v4 and shadcn/ui:
+
+- `apps/gui/components/ui/` — generated shadcn primitives
+- `apps/gui/components/custom/` — harness-specific reusable components
+- `apps/gui/lib/constants/` — layout, spacing, form, and responsive tokens
+- `apps/gui/styles/globals.css` — semantic theme variables
+
+Use named token constants for layout and responsive patterns. Do not scatter arbitrary Tailwind values across page JSX.
+
+## Related
+
+- [`docs/p-dev.md`](p-dev.md) — canonical `p-dev` npm package guide
+- [`docs/npm-packaging-spike.md`](npm-packaging-spike.md) — historical packaging spike notes
+- [`docs/operator-config.md`](operator-config.md)
+- [`docs/getting-started.md`](getting-started.md)
+- [`docs/design/product-development-harness-gui.md`](design/product-development-harness-gui.md)

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

@@ -0,0 +1,106 @@
+# Remote setup GUI
+
+Guided remote setup for harness repo GitHub Actions secrets and target-repo production sync workflow install PRs.
+
+**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.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)
+
+---
+
+## Start
+
+```bash
+npm run harness:configure
+```
+
+Open **Settings / Configure** and scroll to **Remote setup**.
+
+Requires `GITHUB_TOKEN` in `.env.local` for live GitHub status checks and apply paths. Development and CI use mocked providers — no live remote writes during automated validation.
+
+For **target workflow install PR** writes, the token must also be able to create or update `.github/workflows/*` files on the target repo. Classic PATs need the `workflow` scope in addition to `repo`. Fine-grained PATs need Actions/workflows write permission on the target repo. Without this scope, GitHub may return a misleading `404 Not Found` instead of a clear permission error.
+
+---
+
+## Scope (Milestone 5 PR 2)
+
+The remote setup section supports:
+
+- harness dispatch repo resolution and access status
+- harness repo Actions secret status (`present` / `missing` / `unknown` only)
+- per-target-repo workflow status (`present` / `missing` / `differs` / `unknown`)
+- preview + confirmation-gated harness repo Actions secret writes
+- preview + confirmation-gated target workflow branch/PR install per configured repo
+- manual copy-paste instructions beside each automated action
+
+It does **not**:
+
+- write Linear issues or comments
+- trigger harness phases or cloud workflow dispatch
+- write directly to target repo `main` or production branches
+- bundle local + remote actions into a single “do everything” button
+- store secret values in browser storage
+
+---
+
+## Remote setup flow
+
+### Harness repo Actions secrets
+
+1. Confirm `GITHUB_TOKEN` is configured in `.env.local`.
+2. Review harness dispatch repo and secret status badges.
+3. Enter only the secrets you want to create or update:
+   - `LINEAR_API_KEY`
+   - `CURSOR_API_KEY`
+   - `HARNESS_GITHUB_TOKEN`
+4. `HARNESS_CONFIG_JSON_B64` is generated server-side from validated `.harness/config.local.json` during apply — it is never shown in previews or API responses.
+5. Click **Preview harness secrets** — required before apply.
+6. Review the redacted plan (key names and actions only) and manual instructions.
+7. Check the `remote-secret-write` confirmation and click **Apply harness secrets**.
+
+### Target workflow install PR (per repo)
+
+1. Open the card for each configured target repo.
+2. Click **Preview workflow PR**.
+3. Review the install branch name, workflow path, PR title, and manual instructions.
+4. Check the `remote-repo-write` confirmation and click **Apply workflow PR**.
+
+Branch name: `harness/setup-production-sync-<repoConfigId>`
+
+Workflow path: `.github/workflows/trigger-harness-production-sync.yml`
+
+PR title: `Install harness production sync workflow`
+
+Base branch: `repos[].productionBranch` from harness config
+
+If the workflow already matches on the production branch, apply returns `already-installed` and does not open a PR.
+
+---
+
+## API routes (local server only)
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/api/setup/remote-summary` | GET | Remote status summary (no secret values) |
+| `/api/setup/preview-harness-secrets` | POST | Dry-run harness secret write preview |
+| `/api/setup/apply-harness-secrets` | POST | Confirmation-gated harness secret writes |
+| `/api/setup/preview-target-workflow` | POST | Dry-run target workflow branch/PR preview |
+| `/api/setup/apply-target-workflow` | POST | Confirmation-gated target workflow branch/PR install |
+
+Route handlers parse input and delegate to `apps/gui/lib/setup-server.ts`. GitHub semantics live in setup-core provider code (`src/setup/github-remote-setup-live.ts`).
+
+Apply requires `confirmed: true` and a matching preview `fingerprint`.
+
+---
+
+## Security
+
+- `GITHUB_TOKEN` is loaded server-side from `.env.local` only.
+- API responses never include raw tokens, generated `HARNESS_CONFIG_JSON_B64`, or existing GitHub Actions secret values.
+- GitHub API errors are sanitized before returning to the GUI.
+- Secret inputs are POST-only — never in GET routes, query params, or browser storage.
+- Target workflow apply never writes directly to production or `main` branches.
+
+See [`docs/security.md`](security.md).

package/workspace-snapshot/files/docs/integration-repair.md

@@ -0,0 +1,82 @@
+# Integration repair
+
+Integration repair automatically handles known merge-queue drift after a PR waits behind another issue targeting the same repo and base branch.
+
+## What it does
+
+When merge re-inspection finds a PR is `behind` or `dirty`, the issue stays **Merging** and the harness tries repair before blocking:
+
+1. **Deterministic repair:** GitHub update-branch merges the latest base branch into the PR branch.
+2. **Agent repair:** If GitHub cannot resolve conflicts automatically, a Composer 2.5 Cursor cloud agent starts on the PR branch, fetches the latest base branch, runs a local base-into-head merge, resolves conflicts, commits, validates, and pushes the PR branch.
+3. **Return to merge:** The harness re-inspects the PR, waits for checks, and merges if validation passes.
+
+The issue does not return to PM Review just because repair changed the PR branch.
+
+## Safety boundaries
+
+Repair may modify:
+
+- Conflict files.
+- Direct dependency-closure files required to compile and pass validation, such as importers, route registries, shared constants, shared type files, directly covering tests, or small adjacent files required by the resolution.
+
+Repair must not:
+
+- Push directly to `dev`, `main`, or any configured base/production branch.
+- Make unrelated product changes.
+- Make unrelated refactors.
+- Run broad formatting sweeps.
+- Expand scope beyond the issue acceptance criteria and behavior already merged into the base branch.
+
+If the repair agent needs broader changes, the harness blocks with `repair_requires_product_judgment`. If the agent touches unrelated files, the harness blocks with `repair_scope_violation`.
+
+## Required setup
+
+`HARNESS_GITHUB_TOKEN` must be able to update PR branches in target repos.
+
+- Classic PAT: `repo` scope.
+- Fine-grained PAT: **Contents: Read and write** plus **Pull requests: Read and write** on each target repo.
+
+`CURSOR_API_KEY` is required in the merge job because repair may need a cloud agent.
+
+Validate setup:
+
+```bash
+npm run harness:doctor -- --profile merge
+```
+
+Doctor verifies configured base branches and target-repo write permission. If write is missing, repair blocks with setup instructions before trying to update the PR branch or launch an agent.
+
+## Merge queue behavior
+
+Merge jobs run in the GitHub Actions concurrency group:
+
+```yaml
+concurrency:
+  group: harness-merge-${{ needs.gate.outputs.merge_concurrency_group }}
+  cancel-in-progress: false
+  queue: max
+```
+
+This preserves multiple pending merge jobs for the same repo/base branch and processes them one at a time. Repair runs while the merge lock is held so another PR cannot merge into the same base branch during the repair.
+
+## Recovery
+
+If GitHub Actions is canceled while an issue is **Merging**, recover manually through **Harness Auto Runner**:
+
+1. Open the workflow dispatch form.
+2. Set `issue` to the Linear issue key.
+3. Set `phase` to `merge`.
+4. Set `force` to `true`.
+
+v1 intentionally does not add a webhook trigger for **Merging** + incomplete repair markers. That extra automation surface is deferred until there is evidence it is needed.
+
+## Blocking reasons
+
+| Classification | Meaning |
+|----------------|---------|
+| `repair_head_branch_write_denied` | Token cannot update PR branches in the target repo |
+| `repair_validation_failed` | Agent repair or post-repair validation failed |
+| `repair_ambiguous` | Conflict resolution requires semantic judgment |
+| `repair_scope_violation` | Agent touched files outside conflict + declared dependency closure |
+| `repair_requires_product_judgment` | Repair needs broader product changes |
+| `repair_base_branch_violation` | Agent attempted to modify the base branch |

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

@@ -0,0 +1,136 @@
+# Issue intake
+
+How to turn a fuzzy product idea into a harness-compatible Linear issue before planning or implementation runs.
+
+## When to use
+
+- Starting new harness work from an unstructured idea
+- Drafting a Linear issue description
+- Checking whether an issue is ready for **Ready for Planning** or **Ready for Build**
+
+## Paths
+
+### ChatGPT copy-paste prompt (primary PM UX)
+
+Product managers draft issues in a **normal ChatGPT thread**—no Custom GPT required:
+
+1. Open [`prompts/issue-intake-chatgpt.md`](../prompts/issue-intake-chatgpt.md)
+2. Copy the **entire file** into a new ChatGPT conversation
+3. Answer the upfront intake form (**Linear project first**; target repo optional when project metadata includes `Harness metadata: Target repo: ...`)
+4. Review the **proposed Linear issue** (title, status, labels, description)
+5. Approve creation; ChatGPT creates the issue if Linear access is available in that thread, otherwise create it manually in Linear
+6. Set the **status** and **labels** on the issue per the recommendation (not in the description)
+7. Operator optionally validates the live issue with CLI (below)
+
+### Cursor skill + CLI (operator path)
+
+1. Invoke the **issue-intake** skill in Cursor ([`.agents/skills/issue-intake/SKILL.md`](../.agents/skills/issue-intake/SKILL.md))
+2. Answer the upfront intake form (same eight fields as the ChatGPT prompt)
+3. Save the description to a draft markdown file
+4. Validate with route-specific flags:
+
+```bash
+# Recommended Ready for Planning
+npm run harness:validate-issue -- --file draft.md --intended-phase planning
+
+# Recommended Ready for Build (fails if issue is too broad)
+npm run harness:validate-issue -- --file draft.md --intended-phase implementation
+
+# General check (both routes reported; exit 0 if planning-valid)
+npm run harness:validate-issue -- --file draft.md
+```
+
+5. Paste the description into Linear and set the **status** field per the recommendation (not in the description)
+6. Re-validate after paste:
+
+```bash
+npm run harness:validate-issue -- --issue TEAM-XX --intended-phase planning
+# or
+npm run harness:validate-issue -- --issue TEAM-XX --intended-phase implementation
+```
+
+## Deferred: Custom GPT package
+
+A Custom GPT setup package exists at [`gpt/issue-intake/`](../gpt/issue-intake/) for future productization (OAuth, uploaded knowledge, dedicated GPT). **It is not the current operating path.** See [`gpt/issue-intake/setup-guide.md`](../gpt/issue-intake/setup-guide.md).
+
+## Plan-first vs build-direct
+
+| Route | Linear status | When |
+|-------|---------------|------|
+| Plan first | Ready for Planning | Broad, ambiguous, cross-cutting, high-risk, or >7 AC / task >240 chars |
+| Build direct | Ready for Build | Narrow, low-risk, ≤7 AC, task ≤240 chars |
+| Not ready | Backlog | Open questions remain |
+
+**Routing is the Linear status field.** Labels (`requires-plan`, `skip-plan`) are operational hints only — the runner does not read them today.
+
+## Narrow-issue thresholds
+
+Direct implementation without a prior planning comment requires:
+
+- Task ≤ 240 characters
+- Acceptance criteria ≤ 7 hyphen bullets
+
+Constants: [`src/validate/constants.ts`](../src/validate/constants.ts)
+
+Full contract: [`prompts/issue-intake-chatgpt.md`](../prompts/issue-intake-chatgpt.md) (canonical) or [`gpt/issue-intake/knowledge.md`](../gpt/issue-intake/knowledge.md) (deferred GPT reference)
+
+## File vs Linear validation
+
+| Mode | Planning marker check |
+|------|----------------------|
+| `--file` | No — only narrow heuristic for build-direct |
+| `--issue` | Yes — durable planning comment can satisfy build-direct for broad issues |
+
+After a planning run completes, re-validate broad issues with `--issue` and `--intended-phase implementation`.
+
+## Parser contract
+
+Authoritative parser: [`src/linear/parser.ts`](../src/linear/parser.ts)
+
+Template: [`templates/linear-issue.md`](../templates/linear-issue.md)
+
+**Project-first intake:** assign the issue to a Linear project mapped in [`harness.config.json`](../harness.config.json) `repos[].linearProjects`. The runner resolves target repo from project when `## Target repo` is absent.
+
+| Linear project (WES) | Resolved target repo |
+|----------------------|----------------------|
+| Example Target App | `owner/example-target-app` |
+| Agentic Product Development Harness | `weston-uribe/agentic-product-development-harness` |
+
+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)
+- `## Task`
+- `## Acceptance criteria` (≥1 `-` bullet)
+- `## Out of scope` (≥1 `-` bullet)
+
+## Skill installation
+
+The canonical skill lives at [`.agents/skills/issue-intake/`](../.agents/skills/issue-intake/). To use it as a Cursor project skill, symlink or copy to `.cursor/skills/issue-intake/` in this repo or your user skills directory. The `.cursor/skills` path is a Cursor adapter location, not the canonical source.
+
+The legacy [`skills/issue-intake/`](../skills/issue-intake/) path is a compatibility pointer only.
+
+## Related
+
+- Canonical ChatGPT prompt: [`prompts/issue-intake-chatgpt.md`](../prompts/issue-intake-chatgpt.md)
+- Deferred Custom GPT package: [`gpt/issue-intake/`](../gpt/issue-intake/)
+- Milestone doc: [`docs/milestones/m7-issue-intake.md`](milestones/m7-issue-intake.md)
+- State machine: [`docs/architecture/linear-automation-state-machine.md`](architecture/linear-automation-state-machine.md)