p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/examples/runs/001-target-app-github-link/pr-readiness-report.md

@@ -0,0 +1,92 @@
+# PR readiness report: Add GitHub link to site contact or footer
+
+<!-- Run 001 — merged and deployed. Based on templates/pr-readiness-report.md -->
+
+## Summary
+
+PR [#1](https://github.com/owner/example-target-app/pull/1) added a GitHub contact card to the target app contact section so hiring managers can open the public repo (`example-target-app`) directly from the site. Card order: Email → LinkedIn → GitHub → Resume; balanced 2×2 grid from `md` breakpoint upward. Squash-merged to `main`; production deployment succeeded.
+
+**Status:** **Merged and deployed.**
+
+## Issue and plan links
+
+- Issue: [`linear-issue.md`](linear-issue.md)
+- Implementation plan: [`implementation-plan.md`](implementation-plan.md)
+- Branch: `feat/target-app-github-link` (kept on local and origin)
+- PR: https://github.com/owner/example-target-app/pull/1 (#1) — **merged** (squash)
+- Feature commit: `1a4a4e3406bc9e8e7f86c85fc2660ad71263e92a` — Add GitHub contact link
+- Main commit (post-merge): `9a58a7e283b1bee07fc33894174830e2578e08b5`
+- Target repo: https://github.com/owner/example-target-app
+- Vercel preview (pre-merge): https://example-target-app-git-feat-portfo-f948b1-kinterra-team-url.vercel.app
+- Production deployment: https://vercel.com/kinterra-team-url/example-target-app/8TPFTiY79nviGt95rwFWMi2DVeqq — **success**
+
+## Scope check
+
+- [x] Changes match approved implementation plan (contact section placement after repo inspection)
+- [x] No out-of-scope files modified
+- [x] Acceptance criteria addressed (see table below)
+
+### Files changed
+
+| File | Change |
+|------|--------|
+| `components/custom/contact-section.tsx` | GitHub card UI; inline GitHub SVG icon |
+| `lib/content.ts` | GitHub link entry in contact data |
+| `lib/constants/breakpoints.ts` | Grid/layout support for 2×2 contact cards |
+
+### Acceptance criteria status
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| GitHub link in contact section | Done | Contact section only; footer unchanged |
+| Correct repo URL | Done | `https://github.com/owner/example-target-app` |
+| New tab + rel attributes | Done | `target="_blank"`, `rel="noopener noreferrer"` |
+| Visual consistency | Done | Matches card pattern; inline SVG like LinkedIn |
+| Accessible link | Done | Manual contact-section inspection passed |
+| Resume / LinkedIn / email unchanged | Done | Verified on preview and production |
+| Lint and build pass | Done | Both passed pre-merge |
+
+## Validation results
+
+| Check | Result | Evidence |
+|-------|--------|----------|
+| Lint / typecheck | **Pass** | `npm run lint` — passed |
+| Dev server / build | **Pass** | `npm run build` — passed |
+| Manual UI review (contact section) | **Pass** | Manual contact-section inspection — passed |
+| Vercel preview | **Pass** | Pre-merge preview check — success |
+| Production deployment | **Pass** | [Deployment](https://vercel.com/kinterra-team-url/example-target-app/8TPFTiY79nviGt95rwFWMi2DVeqq) — success |
+
+## Eval scorecard
+
+See [`eval-scorecard.md`](eval-scorecard.md) — all criteria **Pass**; PM/product sign-off **complete**.
+
+## Risks (resolved)
+
+| Risk | Outcome |
+|------|---------|
+| Lucide `Github` icon unavailable; inline SVG used | Accepted — shipped; no post-merge issues reported |
+| Merge before PM review | Resolved — PM approved; squash merged |
+| Preview-only validation | Resolved — production deployment succeeded |
+
+## Open questions (closed or deferred)
+
+- **GitHub card placement order** — Approved as shipped (Email → LinkedIn → GitHub → Resume).
+- **Footer GitHub link** — Deferred; contact-only sufficient for v0.1 run scope.
+- **Mobile explicit check** — Inferred from responsive grid; note for future runs (see retrospective).
+
+## Reviewer checklist
+
+- [x] Product intent satisfied — hiring managers can reach the repo from the site
+- [x] No obvious regressions on contact section or footer
+- [x] Copy / UX acceptable for hiring-manager audience
+- [x] Engineering code review complete
+- [x] Merged and deployed to production
+
+## Recommendation
+
+- [ ] Ready for review
+- [ ] Not ready
+- [x] **Merged and deployed** — PR #1 squash-merged; production deployment successful
+
+Prepared by: Harness run 001 (manual v0.1)  
+Date: 2026-07-06 (completion update)

package/workspace-snapshot/files/examples/runs/m5.5-live-sandbox-smoke/README.md

@@ -0,0 +1,73 @@
+# M5.5 live sandbox smoke test
+
+Browser-driven first-run smoke of Settings / Configure against disposable GitHub sandbox repos.
+
+**Date:** 2026-07-09  
+**Branch:** `m5.5-live-sandbox-smoke-hardening`  
+**Model:** Composer 2.5 (local agent run)
+
+## Sandbox resources
+
+| Resource | URL |
+|----------|-----|
+| Harness sandbox | https://github.com/weston-uribe/pdh-smoke-harness-20260709-191523 |
+| Target sandbox | https://github.com/weston-uribe/pdh-smoke-target-20260709-191523 |
+| Target workflow PR | https://github.com/weston-uribe/pdh-smoke-target-20260709-191523/pull/1 |
+| Install branch | `harness/setup-production-sync-smoke-target` |
+
+## Harness secrets written (names only)
+
+- `HARNESS_CONFIG_JSON_B64`
+- `LINEAR_API_KEY`
+- `CURSOR_API_KEY`
+- `HARNESS_GITHUB_TOKEN`
+
+Dummy operator values were used for Linear/Cursor/harness GitHub secret fields during smoke (`smoke-*-placeholder-20260709-191523`).
+
+## Smoke path results
+
+| Step | Result | Evidence |
+|------|--------|----------|
+| Page load / local setup summary | Pass | GUI at `http://127.0.0.1:3001/settings/configure` |
+| Remote summary | Pass | Sandbox dispatch repo + smoke target config rendered |
+| Harness secret preview/apply | Pass | UI success message; `gh secret list` on harness sandbox |
+| Target workflow preview | Pass | Install branch + workflow path + `directProductionBranchWrite: false` |
+| Target workflow apply (OAuth token without `workflow` scope) | Pass after fix | Sanitized error instead of raw GitHub JSON |
+| Target workflow apply (workflow-capable token) | Pass | PR #1 opened; workflow file on install branch only |
+| Target `main` unchanged | Pass | `main` SHA `ec535c5fe43c` ≠ install branch SHA `26409a7223ad` |
+
+## Objective bugs found and fixed
+
+1. **Raw GitHub JSON leaked to GUI on workflow apply failure** — `sanitizeGitHubSetupError` passed through JSON bodies unchanged. Fixed by parsing GitHub API JSON and formatting readable messages.
+2. **Misleading workflow permission failures** — OAuth tokens without `workflow` scope return HTTP 403 (update) or misleading HTTP 404 (create) for `.github/workflows/*`. Fixed with workflow-specific sanitization and setup guidance in `docs/gui-remote-setup.md`.
+
+## UX friction log
+
+| Title | Symptom | Why it slows setup | Recommendation | Classification |
+|-------|---------|-------------------|----------------|----------------|
+| Workflow scope not surfaced in GUI | Apply fails until operator knows PAT needs `workflow` scope | First-run operators may use OAuth tokens that work for secrets but not workflow files | Documented in remote setup guide; error message now actionable | `small-obvious-fix` (docs + error text) |
+| Password field preview trigger | `browser_fill` on secret fields did not always enable preview | Browser automation quirk; manual typing works | No product change | `log-only` |
+| Port selection | GUI bound to 3001 when 3000 in use | Minor local dev confusion | Existing port fallback behavior | `log-only` |
+
+## Safety confirmations
+
+- No writes to `weston-uribe/agentic-product-development-harness`
+- No writes to any non-sandbox target repo
+- No Linear writes
+- No live harness phases, cloud workflow dispatch, or repository dispatch events
+- No tags or releases
+- No private secrets committed to tracked files
+- Sandbox repos are private
+
+## Validation
+
+| Check | Result |
+|-------|--------|
+| `npm run build` | Pass |
+| `npm test` | Pass (537 tests) |
+| `npm run test:webhook` | Pass (89 tests) |
+| Disallowed project-reference grep | Zero matches |
+
+## Cleanup
+
+Disposable sandbox repos were left for inspection. **Do not delete without operator approval.**

package/workspace-snapshot/files/gpt/issue-intake/custom-gpt-instructions.md

@@ -0,0 +1,112 @@
+# Custom GPT instructions — Product Issue Intake
+
+Paste this entire document into the **Instructions** field when creating the Custom GPT.
+
+---
+
+You are a product intake assistant. Your job is to turn fuzzy product ideas into harness-compatible Linear issues for AI-assisted development workflows.
+
+## Constraints
+
+- Be generic. Do not assume a specific person, company, or workspace unless the user provides it.
+- Do not reference local files, repo paths, or templates. The uploaded knowledge file is your sole contract reference.
+- Do not explain internal automation internals (webhooks, runners, orchestrator markers, CI pipelines, or agent models).
+- Do not solution or design during intake. Capture intent, scope, and success criteria only.
+- Routing is controlled by the **Linear status field**, never by a section inside the issue description.
+
+## Intake behavior
+
+### Upfront form (default)
+
+On the first substantive turn—or when the user describes new work—ask for **all eight fields in one message** using a numbered checklist:
+
+1. **Product/repo or target system** — which GitHub repo or product area (e.g. `acme-corp/checkout-web`)
+2. **Desired outcome** — what success looks like
+3. **Current problem / current behavior** — what is wrong or missing today
+4. **Requested change** — what should be built or changed
+5. **Acceptance criteria or observable success** — how we know it worked
+6. **Out of scope / what not to change** — explicit boundaries
+7. **Validation expectations** — optional; "none known" is acceptable
+8. **Initial Linear status preference** — Backlog | Ready for Planning | Ready for Build | Draft only
+
+**Defaults when omitted:** status → Backlog; do not create a Linear issue until the user approves the final package.
+
+### Follow-up questions
+
+Ask follow-up questions **only** when required information is missing or ambiguous (e.g. no target repo, vague acceptance criteria, conflicting scope). Do not interview one question at a time by default.
+
+### Synthesis
+
+Combine fields 2–4 into a concise `## Task` section. Put measurable outcomes in `## Acceptance criteria`. Put boundaries in `## Out of scope`. Follow the description contract in the knowledge file exactly.
+
+## Output package
+
+When intake is complete, produce this artifact:
+
+```markdown
+## Linear issue package
+
+**Title:** ...
+**Recommended status:** Backlog | Ready for Planning | Ready for Build
+**Optional labels:** ... (or "none")
+**Target repo:** owner/repo
+
+### Readiness assessment
+- Valid for planning: yes/no — reason
+- Valid for direct implementation: yes/no — reason
+
+### Blocking questions
+- ... (or "none")
+
+### Linear description (copy-paste)
+<full markdown body with required ## sections only>
+```
+
+Apply the readiness assessment algorithm from the knowledge file. Use reason strings such as `task length N exceeds 240 characters` or `acceptance criteria count N exceeds 7` when thresholds fail.
+
+## Status recommendation rules
+
+| Condition | Recommended status |
+|-----------|-------------------|
+| Blocking questions remain | Backlog |
+| User chose Draft only | Package only; no Linear create |
+| Structurally incomplete | Backlog |
+| Narrow + low-risk (task ≤240 chars, AC ≤7, clear scope) | May recommend Ready for Build **only after user confirms** |
+| Broad, ambiguous, cross-cutting, high-risk, or >7 AC / long task | Ready for Planning or Backlog |
+| Default | Backlog |
+
+- **Never** set Ready for Build for broad or ambiguous work, even if the user requests it. Explain why and offer Ready for Planning or Backlog.
+- **Never** recommend Ready for Planning or Ready for Build until the user has seen the full package and explicitly approved that status.
+- Do not add a routing or status recommendation section inside the Linear description body.
+
+## Approval gates
+
+1. Always show the complete issue package before any Linear write.
+2. Ask for explicit approval to create (e.g. "Approve and create in Linear?" or "Create this issue?").
+3. If the user chose **Draft only**, deliver the package only—no Linear create.
+4. Before creating, confirm **Linear workspace, team/project, and status** when ambiguous (e.g. user has multiple teams or did not specify).
+5. Default created status to **Backlog** unless the user explicitly approved a higher status in the same conversation.
+
+## Linear integration
+
+- **Prefer the built-in Linear app** (ChatGPT Apps / Connectors) when available.
+- After approval, create the issue with: title, description (markdown body only—not the package wrapper), status, and optional labels.
+- Return the issue URL or identifier to the user.
+- If the Linear app is unavailable or write fails, deliver the copy-paste package and instruct the user to create the issue manually in Linear. Remind them to set the **status field** separately—it is not part of the description.
+
+Do not use custom Actions for Linear unless the operator has confirmed the built-in app cannot create issues.
+
+## Never
+
+- Create a Linear issue before the user approves the final package
+- Set Ready for Build for broad, ambiguous, or high-risk work
+- Hide blocking questions—surface them clearly in the package
+- Invent a target repo, workspace, or team
+- Reference local repo files or paths in your responses
+- Include harness implementation details a normal PM does not need
+- Use personal or operator-specific workflow language
+- Add a required routing recommendation section to the issue description
+
+## Tone
+
+Professional, concise, PM-friendly. Focus on clarity and scope control. Help the user ship well-scoped issues that automation can execute reliably.

package/workspace-snapshot/files/gpt/issue-intake/knowledge.md

@@ -0,0 +1,278 @@
+# Harness-compatible Linear issue intake — knowledge reference
+
+This document is the authoritative contract for drafting Linear issues that work with AI-assisted product development workflows. Use it when interviewing a product manager, assembling an issue package, or assessing readiness before creation.
+
+---
+
+## Purpose
+
+A harness-compatible Linear issue captures **product intent in a structured, reviewable form** before any code is written. The issue description is the durable input for planning and implementation agents. It must be clear enough that a fresh agent—with no hidden session memory—can understand scope, success criteria, and boundaries from the issue alone.
+
+---
+
+## Routing model
+
+**What happens next is controlled by the Linear status field—not by any section in the issue description.**
+
+Set the recommended status on the issue when creating or updating it. Do not add a "routing recommendation," "recommended status," or similar section inside the description body.
+
+### PM-facing status glossary
+
+| Status | Meaning |
+|--------|---------|
+| **Backlog** | Work is captured but not ready to trigger automation. Use when open questions remain or the user has not approved a higher status. |
+| **Ready for Planning** | Triggers a planning workflow. Use for broad, ambiguous, cross-cutting, or high-risk work that needs a plan before implementation. |
+| **Ready for Build** | Triggers direct implementation. Use only for narrow, low-risk issues with clear acceptance criteria (see narrow thresholds below). |
+| **Draft only** | Produce the issue package only; do not create a Linear issue until the user explicitly approves later. |
+
+Statuses like Planning, Building, PR Open, PM Review, and Merged / Deployed are set by automation during execution—do not recommend them at intake.
+
+---
+
+## Description contract
+
+Issue descriptions use **level-2 markdown headers** (`##`). Section names are case-insensitive when parsed.
+
+### Required sections
+
+| Section | Content |
+|---------|---------|
+| `## Target repo` | GitHub repository where work happens (see formats below) |
+| `## Task` | Single clear objective in one or two sentences |
+| `## Acceptance criteria` | At least one hyphen bullet; observable, testable outcomes |
+| `## Out of scope` | At least one hyphen bullet; explicitly excluded work |
+
+### Optional sections
+
+- `## Validation expectations` — commands or checks to run (e.g. lint, build, manual preview)
+- `## Context and links` — related issues, designs, research links
+- `## User / job story` — persona, capability, outcome
+- `## Eval hints` — evaluation priorities for reviewers
+- `## Definition of ready` — checklist before work starts
+
+### Formatting rules
+
+- **Acceptance criteria** and **Out of scope** must use hyphen bullets (`-`). Checkbox bullets (`- [ ]`) are allowed and treated as list items.
+- Prefer `## Task` over `## Problem`. `## Problem` is accepted as a fallback for Task but should not be used in new issues.
+- Do not nest required sections under other headers.
+- Keep the Task section concise; put detail in acceptance criteria or context.
+
+### Anti-patterns (do not include in descriptions)
+
+- A routing or status recommendation section inside the body
+- Vague acceptance criteria ("works well," "looks good")
+- Empty or missing out-of-scope section
+- Invented target repos or workspaces
+- Internal automation jargon (webhooks, orchestrator markers, runner phases, etc.)
+
+---
+
+## Target repo formats
+
+Accepted formats for `## Target repo`:
+
+- `owner/repo` (e.g. `acme-corp/checkout-web`)
+- `github.com/owner/repo`
+- `https://github.com/owner/repo`
+
+The repo must be a real GitHub repository the team intends to change. Never invent or guess a repo. If the user is ambiguous ("the main app," "our API"), ask a blocking question before finalizing.
+
+---
+
+## Direct implementation eligibility (narrow thresholds)
+
+Direct implementation without a prior planning step is appropriate **only** when all of the following are true:
+
+1. **Task length** — `## Task` body is **240 characters or fewer** (including spaces)
+2. **Acceptance criteria count** — **7 or fewer** hyphen bullets under `## Acceptance criteria`
+3. **Scope** — Low-risk and clear: no auth, payments, security-sensitive changes, multi-repo work, or ambiguous boundaries
+
+If any threshold fails, or scope is broad/ambiguous/high-risk, recommend **Ready for Planning** or **Backlog**—never Ready for Build.
+
+### High-risk signals (planning-first)
+
+- Security, authentication, or authorization changes
+- Payments or billing
+- Data migrations or schema changes
+- Infrastructure or multi-service changes
+- Cross-cutting UI or information-architecture redesigns
+- Unclear or disputed acceptance criteria
+
+---
+
+## Readiness assessment algorithm
+
+Perform this assessment for every completed issue package. This is a **structural** check only—it does not verify that a repo exists on an operator allowlist.
+
+### Valid for planning: yes/no
+
+**Yes** when all of the following hold:
+
+- `## Target repo` is present and identifiable (not empty, not invented)
+- `## Task` (or `## Problem`) is present and non-empty
+- `## Acceptance criteria` has at least one hyphen bullet
+- `## Out of scope` has at least one hyphen bullet
+
+**No** when any required section is missing or empty. State which sections failed.
+
+### Valid for direct implementation: yes/no
+
+**Yes** when:
+
+- Valid for planning is **yes**, AND
+- Task length ≤ 240 characters, AND
+- Acceptance criteria count ≤ 7, AND
+- Scope is low-risk and clear (no high-risk signals above)
+
+**No** otherwise. Include a reason string, e.g.:
+
+- `task length 312 exceeds 240 characters`
+- `acceptance criteria count 8 exceeds 7`
+- `scope is broad or high-risk; planning recommended`
+- `missing required section: Out of scope`
+
+---
+
+## Labels (optional)
+
+Labels are operational hints only. They are **never required** for a valid issue.
+
+| Label | Meaning |
+|-------|---------|
+| `requires-plan` | Should go through planning before build |
+| `skip-plan` | May bypass planning if status is Ready for Build |
+| `harness` | Work uses the agentic development harness |
+| Repo id label | Short identifier for the target repo (team convention) |
+
+Suggest labels only when they add clarity. Omit if the user's workspace does not use them.
+
+---
+
+## Example 1 — Narrow issue (Ready for Build candidate)
+
+**Title:** Add order confirmation toast on checkout success
+
+**Recommended status:** Backlog (default until user approves Ready for Build)
+
+**Optional labels:** `harness`, `checkout-web`, `skip-plan`
+
+**Target repo:** acme-corp/checkout-web
+
+### Readiness assessment
+
+- Valid for planning: yes — all required sections present
+- Valid for direct implementation: yes — task 58 characters, 3 acceptance criteria, low-risk UI change
+
+### Blocking questions
+
+- none
+
+### Linear description (copy-paste)
+
+```markdown
+## Target repo
+
+acme-corp/checkout-web
+
+## Task
+
+Show a success toast when the customer completes checkout.
+
+## Acceptance criteria
+
+- [ ] A toast appears within 2 seconds of successful payment
+- [ ] Toast message includes the order confirmation number
+- [ ] Toast auto-dismisses after 5 seconds
+
+## Out of scope
+
+- Email confirmation changes
+- Payment provider integration changes
+- Other pages or flows
+
+## Validation expectations
+
+- `npm run lint`
+- `npm run build`
+- Manual test on staging checkout flow
+```
+
+---
+
+## Example 2 — Broad issue (Ready for Planning)
+
+**Title:** Redesign checkout navigation and information architecture
+
+**Recommended status:** Ready for Planning
+
+**Optional labels:** `harness`, `checkout-web`, `requires-plan`
+
+**Target repo:** acme-corp/checkout-web
+
+### Readiness assessment
+
+- Valid for planning: yes — all required sections present
+- Valid for direct implementation: no — task length 142 characters OK but acceptance criteria count 8 exceeds 7; cross-cutting IA change is high-risk
+
+### Blocking questions
+
+- none
+
+### Linear description (copy-paste)
+
+```markdown
+## Target repo
+
+acme-corp/checkout-web
+
+## Task
+
+Redesign checkout navigation and information architecture so customers can complete purchase, review order details, and access support without confusion.
+
+## Acceptance criteria
+
+- [ ] Primary nav reflects the new IA across checkout steps
+- [ ] Mobile nav matches desktop destinations
+- [ ] Cart is reachable in one click from any checkout step
+- [ ] Order summary is reachable in one click from payment step
+- [ ] Support/help link is visible on every checkout step
+- [ ] No broken internal links after restructure
+- [ ] Preview looks correct on mobile and desktop
+- [ ] Lint and build pass
+
+## Out of scope
+
+- Payment provider integration changes
+- New CMS integration
+- Backend API redesign
+
+## Validation expectations
+
+- `npm run lint`
+- `npm run build`
+- Manual preview review on staging
+```
+
+---
+
+## Synthesizing Task from intake fields
+
+When assembling an issue from the upfront intake form:
+
+1. **Desired outcome** — what success looks like for the user or business
+2. **Current problem / current behavior** — what is wrong or missing today
+3. **Requested change** — what should be built or changed
+
+Combine fields 2–4 into a concise `## Task` (one or two sentences). Put measurable outcomes in `## Acceptance criteria`. Put boundaries in `## Out of scope`.
+
+---
+
+## Default behavior summary
+
+| Setting | Default |
+|---------|---------|
+| Recommended status | Backlog |
+| Create Linear issue | Only after user approves the final package |
+| Ready for Planning / Ready for Build | Recommend only after explicit user approval of status |
+| Labels | Optional; suggest only when useful |
+| Follow-up questions | Only when required information is missing or ambiguous |

package/workspace-snapshot/files/gpt/issue-intake/setup-guide.md

@@ -0,0 +1,115 @@
+# Custom GPT setup guide — Product Issue Intake
+
+> **Status: Deferred / optional.** This is **not** the current operating path for issue intake.
+>
+> **Current path:** Copy [`prompts/issue-intake-chatgpt.md`](../../prompts/issue-intake-chatgpt.md) into a normal ChatGPT thread. See [`docs/issue-intake.md`](../../docs/issue-intake.md).
+>
+> Keep this guide for future productization (Custom GPT, uploaded knowledge, OAuth). Do not configure a Custom GPT unless explicitly approved.
+
+Operator guide for configuring a ChatGPT Custom GPT that drafts harness-compatible Linear issues for product managers.
+
+## Prerequisites
+
+- **ChatGPT plan** — Plus, Pro, or Team (Linear app availability varies by region; some EEA/UK plans may have restrictions per OpenAI docs)
+- **Linear account** — with permission to create issues in the target workspace
+- **Harness repo** — clone or browse to copy files from `gpt/issue-intake/`
+
+## Create the Custom GPT
+
+1. Open ChatGPT → **Explore GPTs** → **Create** (or **My GPTs** → **Create a GPT**)
+2. Use **Configure** tab for full control (recommended over Create-by-chat)
+
+## Configure instructions
+
+1. Open [`custom-gpt-instructions.md`](custom-gpt-instructions.md) in this directory
+2. Copy the **entire** document (from the role section through Tone)
+3. Paste into the GPT **Instructions** field
+
+Do not add repo file paths or template references to the instructions—the GPT must rely only on the uploaded knowledge file.
+
+## Upload knowledge
+
+1. In the GPT **Knowledge** section, upload **one file only**: [`knowledge.md`](knowledge.md)
+2. Do **not** upload repo templates, `harness.config.json`, or skill files
+
+The knowledge file is the authoritative contract for issue descriptions, status semantics, narrow thresholds, and examples.
+
+## Connect the Linear app
+
+1. In ChatGPT, go to **Settings** → **Apps** (or **Connectors**)
+2. Search for **Linear** → **Connect**
+3. Authorize with a Linear account that can create issues
+4. Verify the connection includes **write** permission (issue creation)
+
+In the Custom GPT **Configure** tab, enable the Linear app for this GPT if the UI offers per-GPT app toggles.
+
+### Known limitations
+
+- Newly created issues may take time to appear in synced search
+- The app only sees issues visible to the connected user
+- Regional/plan restrictions may block the app on some accounts
+- If issue creation fails, the GPT falls back to copy-paste instructions (see smoke test case 8)
+
+## Recommended GPT settings
+
+| Setting | Recommendation |
+|---------|----------------|
+| **Name** | Product Issue Intake (or your team name) |
+| **Description** | Draft harness-compatible Linear issues from product ideas. Requires approval before create. |
+| **Conversation starters** | "I have a new feature idea" / "Draft a Linear issue for a bug fix" |
+| **Web browsing** | Off (not required) |
+| **Code Interpreter** | Off (not required) |
+| **Actions** | None — use built-in Linear app only unless smoke test proves create is impossible |
+
+## What not to configure
+
+- Custom GPT Actions / OpenAPI schema for Linear (deferred unless smoke test fails)
+- Repo URLs or file paths in instructions
+- Multiple knowledge files (use the single master `knowledge.md`)
+
+## PM handoff
+
+Share the GPT link with PMs. Explain:
+
+1. The GPT asks for eight fields up front—answer in one reply when possible
+2. Default status is **Backlog**; higher statuses require explicit approval
+3. The GPT will **not** create a Linear issue until they approve the final package
+4. **Status is set on the issue**, not inside the description
+5. Labels are optional
+
+Tell PMs which **Linear team or project** to name when asked (e.g. "Use team ENG and project Checkout").
+
+## Operator validation (optional hardening)
+
+After the GPT creates an issue, an operator with harness repo access can validate structurally:
+
+```bash
+npm run harness:validate-issue -- --issue TEAM-123 --intended-phase planning
+```
+
+For build-direct candidates:
+
+```bash
+npm run harness:validate-issue -- --issue TEAM-123 --intended-phase implementation
+```
+
+The GPT readiness assessment is structural only—it does not check `harness.config.json` allowlists. Operator validation catches unknown repos.
+
+## Troubleshooting
+
+| Problem | What to try |
+|---------|-------------|
+| Linear app not visible | Check ChatGPT plan and region; connect from Settings → Apps first |
+| Create failed | Confirm write scope; try manual create with copy-paste package |
+| Wrong team/project | Tell PMs the default team name; GPT should confirm before create |
+| Issue not in search | Sync delay—use issue URL from create response |
+| GPT references repo files | Re-paste instructions; ensure only `knowledge.md` is uploaded |
+| GPT creates before approval | Re-paste instructions; emphasize approval gates section |
+
+## Escalation: custom Actions
+
+Only if a tester on a supported plan **cannot** create issues via the built-in Linear app after correct setup, open a follow-up to add a minimal Linear Action schema. That is out of M9 scope by default.
+
+## Smoke test
+
+Run [`smoke-test.md`](smoke-test.md) before handing the GPT to PMs.