p-dev-harness 0.3.0 → 0.4.0

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.

package/workspace-snapshot/files/gpt/issue-intake/smoke-test.md

@@ -0,0 +1,119 @@
+# Smoke test — Product Issue Intake Custom GPT
+
+Manual validation script. Run each case in ChatGPT with the configured Custom GPT. Record **pass / fail** and notes.
+
+**Pass criteria:** Cases 1–6 and 9–10 pass in ChatGPT. Case 7 passes when Linear app is connected. Case 8 documents fallback behavior.
+
+---
+
+## Test matrix
+
+| # | Scenario | Input gist | Expected | Pass | Notes |
+|---|----------|------------|----------|------|-------|
+| 1 | Happy path narrow | Small UI tweak, 3 AC, clear repo | Package complete; readiness planning yes, direct impl yes; default status Backlog; after approval may offer Ready for Build | | |
+| 2 | Broad feature | IA redesign, 8+ AC | direct impl no; recommends Ready for Planning; refuses Ready for Build even if user insists | | |
+| 3 | Incomplete intake | User skips out-of-scope | Blocking questions; Backlog; valid for planning no | | |
+| 4 | Draft only | User selects Draft only in field 8 | Package only; no Linear create attempted | | |
+| 5 | Approval gate | User says "create it" before package shown | GPT shows full package first, then asks explicit approval | | |
+| 6 | Ambiguous repo | "the main app" without repo name | Blocking question; does not invent repo | | |
+| 7 | Linear app create | Approve narrow issue from case 1 | Issue created in correct team; status Backlog unless user approved higher; description has `##` sections only, no routing section | | |
+| 8 | No Linear app | Disconnect Linear app or use account without app | Copy-paste package + manual create instructions; no failed silent create | | |
+| 9 | Generic language | Any scenario | No personal names, operator-specific repos, or harness-internal jargon in PM-visible output | | |
+| 10 | Description contract | Any created or drafted issue | Required `##` sections present; AC and out-of-scope use `-` bullets; no routing recommendation in body | | |
+
+---
+
+## Case prompts (copy-paste)
+
+### Case 1 — Happy path narrow
+
+```
+I need a small UI change:
+
+1. Repo: acme-corp/checkout-web
+2. Outcome: Customers see confirmation feedback after checkout
+3. Problem: No feedback after successful payment
+4. Change: Add a success toast
+5. AC: Toast within 2s; shows order number; auto-dismiss 5s
+6. Out of scope: Email, payment provider, other pages
+7. Validation: lint, build, manual staging test
+8. Status: Backlog
+```
+
+### Case 2 — Broad feature
+
+```
+1. Repo: acme-corp/checkout-web
+2. Outcome: Customers never get lost in checkout
+3. Problem: Navigation is confusing across steps
+4. Change: Full IA and nav redesign for checkout
+5. AC: (list 8+ items covering nav, mobile, cart, support, links, preview, lint, build)
+6. Out of scope: Payment provider, CMS, backend API
+7. Validation: lint, build, staging preview
+8. Status: Ready for Build
+```
+
+After package, insist "Set it to Ready for Build anyway." GPT should refuse and explain.
+
+### Case 3 — Incomplete intake
+
+Provide fields 1–5 only; omit out of scope when asked in upfront form.
+
+### Case 4 — Draft only
+
+Same as case 1 but field 8 = `Draft only`. Confirm no Linear create.
+
+### Case 5 — Approval gate
+
+Start with: "Create a Linear issue for adding a logout button to acme-corp/admin-portal" before answering intake fields.
+
+### Case 6 — Ambiguous repo
+
+```
+1. Repo: the main app
+2–7. (reasonable content)
+8. Backlog
+```
+
+### Case 7 — Linear app create
+
+Complete case 1, approve package, confirm team if asked. Verify issue in Linear UI.
+
+### Case 8 — No Linear app
+
+Disconnect Linear or use environment without app. Complete case 1 and approve. Expect manual instructions only.
+
+---
+
+## Structural validation (operator)
+
+Paste example descriptions from [`knowledge.md`](knowledge.md) into draft files and run in harness repo:
+
+```bash
+# Narrow example — planning pass
+npm run harness:validate-issue -- --file narrow-draft.md --intended-phase planning
+
+# Narrow example — implementation pass
+npm run harness:validate-issue -- --file narrow-draft.md --intended-phase implementation
+
+# Broad example — planning pass, implementation fail
+npm run harness:validate-issue -- --file broad-draft.md --intended-phase planning
+npm run harness:validate-issue -- --file broad-draft.md --intended-phase implementation
+```
+
+Exit code 2 on broad + `--intended-phase implementation` is expected.
+
+---
+
+## Escalation
+
+If case 7 fails on a supported ChatGPT plan with Linear app connected and authorized for write, document the error and open follow-up for custom GPT Actions. Do not block M9 delivery on Actions unless create is impossible.
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Result |
+|------|------|------|--------|
+| Operator | | | |
+| PM reviewer | | | |