p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/docs/architecture/linear-automation-state-machine.md

@@ -0,0 +1,283 @@
+# Linear automation state machine
+
+**Status:** Partially implemented — statuses and labels configured manually in Linear; planning-router Cursor Automation validated (see research note 003). Implementation, revision, and merge/deploy automations remain planned.
+
+This document defines the Linear issue lifecycle for the agentic product development harness. It is the contract for Cursor Automations.
+
+**Related:** [`ARCHITECTURE.md`](../../ARCHITECTURE.md), [`docs/decisions/0003-automation-state-machine-and-auto-model-policy.md`](../decisions/0003-automation-state-machine-and-auto-model-policy.md), [`docs/research/002-linear-cursor-integration-smoke-test.md`](../research/002-linear-cursor-integration-smoke-test.md), [`docs/research/003-cursor-automation-planning-router-spike.md`](../research/003-cursor-automation-planning-router-spike.md)
+
+---
+
+## Default active workflow
+
+The default path includes optional planning. `Plan Review` is **not** part of this flow.
+
+```text
+Backlog
+  → Ready for Planning
+  → Planning
+  → Ready for Build
+  → Building
+  → PR Open
+  → PM Review
+  → Engineering Review
+  → Merged / Deployed
+```
+
+### Revision loop
+
+When PM review requests changes:
+
+```text
+PM Review
+  → Needs Revision
+  → Revising
+  → PM Review
+```
+
+### Merge repair sub-states
+
+Integration repair is a merge sub-mode, not a new top-level Linear phase. When a PR becomes `behind` or `dirty` after waiting in the serialized repo/base merge queue, the issue stays **Merging** while the runner attempts repair.
+
+```text
+Ready to Merge
+  → Merging
+    → repair_start
+    → repair_deterministic
+    → repair_agent_start (only if conflicts remain)
+    → repair_complete
+  → Merged to Dev / Merged / Deployed
+```
+
+If deterministic and agent repair fail, or the repair needs product judgment, the issue moves to **Blocked**. Successful repair returns directly to merge; it does not route back to PM Review solely because the PR branch changed.
+
+### Planning bypass path
+
+For low-risk, narrow, well-scoped issues that skip planning:
+
+```text
+Backlog
+  → Ready for Build
+  → Building
+  → PR Open
+  → PM Review
+  → Engineering Review
+  → Merged / Deployed
+```
+
+Issues on the bypass path join the default flow at **Building** and follow the same review and merge stages.
+
+---
+
+## Terminal and exception statuses
+
+| Status | Meaning |
+|--------|---------|
+| **Blocked** | Work cannot proceed; requires human intervention |
+| **Canceled** | Issue abandoned; no further automation |
+| **Duplicate** | Superseded by another issue; no further automation |
+
+Automations must **exit without action** when an issue is in one of these statuses unless explicitly designed for cleanup (not planned in the first spike).
+
+---
+
+## Deprecated: Plan Review
+
+`Plan Review` is **not** part of the default or current automation path.
+
+- If the status still exists in Linear, treat it as **deprecated / reserved**, not active.
+- Do not route automations to `Plan Review`.
+- Plan review may be reintroduced later for high-risk work; that is out of scope for the current spike.
+
+---
+
+## Planning policy
+
+Planning is **optional**, not mandatory for every issue.
+
+| Label | Behavior |
+|-------|----------|
+| `requires-plan` | Issue must go through **Ready for Planning** → **Planning** before **Ready for Build** |
+| `skip-plan` | Issue may go directly from **Backlog** to **Ready for Build** |
+
+### When to require planning
+
+Require planning (via `requires-plan` or human triage) when the issue is:
+
+- Broad or ambiguous in scope
+- High-risk (security, data, auth, payments, infra)
+- Multi-file or cross-cutting
+- Unclear on acceptance criteria or rollback
+
+### When to bypass planning
+
+Bypass planning (via `skip-plan` or direct **Ready for Build**) when the issue is:
+
+- Small and low-risk
+- Narrow and well-scoped
+- Has clear acceptance criteria in the Linear issue body
+
+For bypass issues, the **Implementation Agent** may build directly from the Linear issue without a separate plan artifact. The issue description and acceptance criteria are the durable input.
+
+### Uninitialized product routing
+
+When the target repository marker on the **development branch** (`repos[].baseBranch`, usually `dev`) reports `Product initialization: uninitialized`:
+
+- Issues with `## Product foundation` route to **Ready for Planning** for stack selection and foundation planning.
+- Direct **Ready for Build** routing is blocked until approved architecture exists and the marker reads `initialized`.
+- After foundation merge to `dev`, the merge workflow updates Linear project metadata to `Product initialization: initialized` idempotently.
+
+Application preview/deployment capability is **not** inferred from the marker. Harness `repos[].previewProvider` is the sole runtime authority (`vercel` or `none`).
+
+### Planning agent output
+
+When planning runs:
+
+1. The **Planning Agent** reads the Linear issue and repo context.
+2. It posts a **durable plan comment** in Linear (structured per [`templates/implementation-plan.md`](../../templates/implementation-plan.md)).
+3. It moves the issue to **Ready for Build** only after the plan comment exists.
+
+Automations must **not** advance status to **Ready for Build** without a durable plan comment when `requires-plan` is set.
+
+---
+
+## Cursor model policy
+
+| Rule | Detail |
+|------|--------|
+| **Preferred future policy** | **`Auto`**, if Cursor Automations support it as a model setting |
+| **Current automation policy** | **Composer 2.5** — required because Cursor Automations currently need a concrete model selection and `Auto` is not available |
+| **Mid-run switching** | **Disallowed** — agents must not change models during a run |
+| **Documentation** | Reports, comments, and automation output must state the **actual configured model**, not a preferred policy |
+| **Future flexibility** | Harness docs and prompts should be written so the model setting can change later without rewriting workflows |
+
+---
+
+## Router automation design
+
+Cursor Automations should use a **router** pattern, not many independent automations per status.
+
+### Why a router
+
+- **Broad Linear status-change triggers are expected** — automations fire on any status transition, not only the intended one.
+- The router must inspect issue **status and labels first** before acting.
+- **Non-matching runs must exit silently** — no branch, no PR, no Linear comments, no status writes.
+- **Duplicate self-triggered runs are acceptable only if silent** — when the automation moves an issue through **Planning** or **Ready for Build**, each transition re-fires the trigger; those runs must no-op without Linear noise.
+
+Validated in WES-9 and WES-10 — see [`docs/research/003-cursor-automation-planning-router-spike.md`](../research/003-cursor-automation-planning-router-spike.md).
+
+### Router behavior
+
+| Issue status | Action |
+|--------------|--------|
+| **Ready for Planning** | Run planning flow (Planning Agent) |
+| **Ready for Build** | Run implementation flow (Implementation Agent) — **not yet validated** |
+| **Needs Revision** | Run revision flow (Builder follow-up) — **implemented** |
+| Any other status | **Silent exit** — no changes, no Linear writes |
+
+The router may delegate logically to role-specific prompts. The planning spike implements this as **one Cursor Automation prompt** that routes based on Linear status.
+
+### Planning run output
+
+A successful planning run must post **exactly one combined planning/report comment** in Linear before moving the issue to **Ready for Build**. Duplicate or non-matching runs must not add comments.
+
+### Spike scope
+
+The **planning-router spike is validated** (WES-9 + WES-10). The next spike is **implementation automation** — docs-only, starting from **Ready for Build**, creating a branch and PR, moving Linear to **PR Open** or **PM Review**. No revision loop yet.
+
+---
+
+## Agent roles
+
+Role maturity varies — see honest maturity table below. Planning Agent behavior is validated; other roles remain planned.
+
+### Router Agent
+
+| Field | Detail |
+|-------|--------|
+| **Trigger / status** | Linear status change (any); acts only on supported statuses above |
+| **Input** | Linear issue (status, labels, title, description, comments) |
+| **Output** | Delegation to Planning, Implementation, or Revision flow; or clean exit |
+| **Linear writes** | None directly — may update status only when sub-flow completes (via delegated agent) |
+| **GitHub writes** | None |
+| **Must not do** | Run build or planning on unsupported statuses; write Linear comments on no-op exit; merge PRs |
+
+### Planning Agent
+
+| Field | Detail |
+|-------|--------|
+| **Trigger / status** | **Ready for Planning** (via router) |
+| **Input** | Linear issue, target repo context, existing comments |
+| **Output** | Durable plan comment in Linear |
+| **Linear writes** | Plan comment; move to **Ready for Build** after plan exists; move to **Planning** while working if status model requires it |
+| **GitHub writes** | None |
+| **Must not do** | Implement code; open PRs; skip plan comment; post duplicate comments on re-triggered runs |
+
+### Implementation Agent
+
+| Field | Detail |
+|-------|--------|
+| **Trigger / status** | **Ready for Build** (via router) |
+| **Input** | Linear issue, plan comment (if `requires-plan`), repo context |
+| **Output** | Feature branch, commits, PR; readiness summary in Linear comment |
+| **Linear writes** | Progress comments; move to **Building** while working; move to **PR Open** when PR exists |
+| **GitHub writes** | Branch, commits, PR (link back to Linear issue) |
+| **Must not do** | Merge PRs; deploy without human gate; advance past **PR Open** without a PR |
+
+### Builder (implementation, revision, repair)
+
+| Field | Detail |
+|-------|--------|
+| **Trigger / status** | **Ready for Build** (create); **Needs Revision** (resume follow-up); **Merging** agent repair (resume follow-up when deterministic repair is insufficient) |
+| **Input** | Linear issue, plan comment (if `requires-plan`), repo context; revision adds PM feedback; repair adds PR/check context |
+| **Output** | Feature branch, commits, PR (implementation); additional commits and revision summary (revision); repair commits or summary (agent repair) |
+| **Linear writes** | Hidden metadata: `builder_agent_id`, `builder_thread_generation`, `builder_thread_action`, `builder_origin_run_id`, `builder_thread_idempotency_key`, and replacement fields when applicable; phase-specific `cursor_agent_id` / `cursor_run_id` remain as Cursor evidence |
+| **GitHub writes** | Branch, commits, PR (implementation); commits on existing branch (revision / repair) |
+| **Must not do** | Merge PRs; create a separate revision or repair cloud agent when lineage can be resumed; replace Builder on transient resume or uncertain-send failures |
+
+Implementation creates generation `1`. Revision and agent repair resolve the canonical Builder from durable Linear metadata, call `Agent.resume` (unarchive when needed), and send follow-up prompts with stable idempotency keys. Replacement Builders are created only for definitive agent loss or exhausted legacy lineage.
+
+### Revision Agent (deprecated role name)
+
+The historical **Revision Agent** label referred to a separate Cursor cloud agent. Current behavior uses the **Builder** thread resumed from handoff / implementation markers. Docs and prompts may still say "revision" for the phase, but there is no independent revision agent role.
+
+### Merge / Deployment Reporter
+
+| Field | Detail |
+|-------|--------|
+| **Trigger / status** | **Merged / Deployed** (manual or post-merge hook — not in first spike) |
+| **Input** | Merged PR, deployment URL (e.g. Vercel preview/production) |
+| **Output** | Final status comment with links and evidence |
+| **Linear writes** | Closure comment with PR merge link and preview/production URL |
+| **GitHub writes** | None (read-only) |
+| **Must not do** | Trigger merges |
+
+---
+
+## Durable context principle
+
+Automations and agents must treat **durable artifacts** as the source of truth.
+
+| Principle | Detail |
+|-----------|--------|
+| **Durable state required** | Linear comments, GitHub PR/commits/branch, Vercel preview URLs, and issue fields must hold enough context to resume work |
+| **Session reuse is optional** | Resuming the canonical Builder via Cursor `Agent.resume` is the happy path when lineage is valid |
+| **Fresh agent recovery** | A replacement Builder (or Planner for planning-only work) must always be able to reconstruct context from Linear, GitHub, branch, PR, commits, Vercel preview, and Linear comments |
+| **No hidden memory** | Hidden agent or session memory must **never** be the source of truth |
+
+Before advancing Linear status, the agent must ensure the required durable artifact exists (plan comment, PR link, revision summary, etc.).
+
+---
+
+## Honest maturity
+
+| Item | Status |
+|------|--------|
+| Linear statuses and labels | **Configured manually** in Linear |
+| Native Cursor ↔ Linear trigger | **Smoke-tested once** — see research note 002 |
+| Planning-router Cursor Automation | **Validated** — see research note 003 (WES-9, WES-10) |
+| Implementation automation | **Planned** — next spike |
+| Revision loop automation | **Planned** |
+| Merge/deploy reporting automation | **Planned** |
+| Full autonomous build loop | **Not planned** |
+| Automation model | **Composer 2.5** (current); **`Auto` preferred** when supported |

package/workspace-snapshot/files/docs/decisions/0001-cursor-first-v0.1.md

@@ -0,0 +1,59 @@
+# ADR 0001: Cursor-first v0.1 with modular architecture
+
+**Status:** Accepted  
+**Date:** 2026-07-06
+
+## Decision
+
+v0.1 of the agentic product development harness is **Cursor-specific** for execution, but the **architecture is modular** so components can be rewired to other environments later.
+
+## Context
+
+Weston's current product development workflow centers on:
+
+- **Cursor** for AI-assisted implementation
+- **GitHub** for version control and PR review
+- **Target repo** (`example-target-app`) as the first real target for case study and prototype work
+- **Linear-style issues** as the intended PM intake format (Linear itself is not wired in v0.1)
+- **Vercel previews** as the intended product review surface for UI changes
+
+The harness is being built to structure how an AI-native PM defines work, guides implementation, and evaluates outputs before human review—not to automate shipping on day one.
+
+## Rationale
+
+1. **Prove the loop manually first.** Automation and skills should encode a workflow that already works by hand. Premature skills and cloud agents add complexity before the contracts are clear.
+
+2. **Cursor is the available execution environment today.** v0.1 should meet the practitioner where they work, not wait for a hypothetical platform.
+
+3. **Modular components preserve optionality.** Issue intake, planning, evals, and readiness reporting are defined as separate stages so Linear, GitHub Actions, or cloud agents can be added in later phases without redesign.
+
+4. **Docs and templates are the cheapest way to align humans and agents.** Shared templates reduce scope drift and make PM judgment visible before code exists.
+
+## Consequences
+
+### Positive
+
+- Fast path to a public, honest v0.1 repo
+- Clear boundaries for agents (no invented maturity)
+- Target repo can serve as the first validation target
+
+### Negative / accepted tradeoffs
+
+- No UI or control plane in v0.1
+- No cloud automation or Linear integration yet
+- No reusable Cursor skills until manual loops repeat
+- Cursor-specific execution may require adaptation docs for other IDEs later
+
+## Alternatives considered
+
+| Alternative | Why not v0.1 |
+|-------------|--------------|
+| Cloud-first agents | Higher ops burden; human review gates less visible |
+| Skills-first | Encodes unvalidated workflows; hard to debug |
+| Linear-first | PM tool wiring before templates exist |
+| Monolithic “ship bot” | Overstates maturity; unsafe for public positioning |
+
+## References
+
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md)
+- [`ROADMAP.md`](../../ROADMAP.md)

package/workspace-snapshot/files/docs/decisions/0003-automation-state-machine-and-auto-model-policy.md

@@ -0,0 +1,65 @@
+# ADR 0003: Automation state machine and model policy
+
+**Status:** Accepted (amended 2026-07-06 — planning-router spike results)  
+**Date:** 2026-07-06
+
+## Decision
+
+1. Adopt the Linear status model documented in [`docs/architecture/linear-automation-state-machine.md`](../architecture/linear-automation-state-machine.md), with **optional planning**, a **planning bypass path**, and **no Plan Review** in the default active flow.
+2. **Preferred future model policy:** **`Auto`**, if Cursor Automations support it as a model setting.
+3. **Current automation model policy:** **Composer 2.5** — Cursor Automations currently require a concrete model selection and `Auto` is not available. Agents must **not switch models mid-run**. Documentation and comments must state the **actual configured model**.
+4. Implement Cursor Automations as a **status-triggered router** that inspects issue status/labels and **exits silently** (no Linear writes) on unsupported or duplicate runs.
+5. **Planning-router spike validated** (WES-9, WES-10) — see [`docs/research/003-cursor-automation-planning-router-spike.md`](../research/003-cursor-automation-planning-router-spike.md).
+
+## Context
+
+Linear statuses and labels were updated manually ahead of Cursor Automations spikes. The previously assumed workflow included **Plan Review** as a default gate. Operational experience and spike scope require a simpler machine:
+
+- Planning is optional; small/low-risk issues can go directly to build.
+- `Plan Review` remains in Linear only as deprecated/reserved if present — not routed by automations.
+- Native Cursor ↔ Linear integration was smoke-tested once ([`docs/research/002-linear-cursor-integration-smoke-test.md`](../research/002-linear-cursor-integration-smoke-test.md)).
+- **WES-9** proved Linear status-change automation can trigger, authenticate to Linear MCP, post a planning comment, and move the issue to **Ready for Build** — but broad status-change triggers caused duplicate runs and extra comments.
+- **WES-10** proved the quiet/idempotent router fix: duplicate and non-matching runs exit silently without Linear comments.
+- Cursor Automations currently require a concrete model selection; **`Auto` is not available** as an automation model setting. The planning-router automation uses **Composer 2.5**.
+
+## Rationale
+
+1. **Optional planning reduces friction** for narrow, well-scoped work while preserving a path for high-risk or ambiguous issues via `requires-plan`.
+2. **Removing Plan Review from the default path** avoids an extra human gate before automation spikes; it may return later for high-risk work only.
+3. **Router-first automation** prevents duplicate or conflicting automations when Linear fires status-change triggers broadly; silent no-op is required for self-triggered duplicate runs.
+4. **Document actual model configuration** — prefer `Auto` when supported, but do not misrepresent the configured model during spikes.
+5. **Durable context in Linear/GitHub** ensures any fresh agent can resume work without hidden session memory.
+
+## Consequences
+
+### Positive
+
+- Clear contract for Cursor Automations spikes
+- Labels (`requires-plan`, `skip-plan`) give explicit routing hints
+- Silent early exit on unsupported statuses limits runaway agent actions and Linear comment noise
+- Planning-router behavior validated end-to-end
+
+### Negative / accepted tradeoffs
+
+- Plan Review gate is deferred; high-risk work relies on labels and human triage until reintroduced
+- Implementation, revision, and merge/deploy automations remain planned
+- Automations use **Composer 2.5** until `Auto` is supported or policy changes in a future ADR
+- Broad status-change triggers produce duplicate runs that must be handled idempotently
+
+## Alternatives considered
+
+| Alternative | Why not now |
+|-------------|-------------|
+| Mandatory planning for all issues | Too heavy for small/docs-only work |
+| Plan Review in default flow | Extra gate before spike; removed from active path |
+| Separate automations per status | Broad Linear triggers cause duplicate runs |
+| Block automations until `Auto` is supported | Would delay validated planning-router spike |
+| Named model per role (e.g. Claude for planning) | Unnecessary complexity; single configured model per automation |
+
+## References
+
+- [`docs/architecture/linear-automation-state-machine.md`](../architecture/linear-automation-state-machine.md)
+- [`docs/research/003-cursor-automation-planning-router-spike.md`](../research/003-cursor-automation-planning-router-spike.md)
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md)
+- [`ROADMAP.md`](../../ROADMAP.md)
+- [`AGENTS.md`](../../AGENTS.md)

package/workspace-snapshot/files/docs/decisions/0004-agent-provider-boundary.md

@@ -0,0 +1,109 @@
+# ADR 0004: Agent provider boundary
+
+**Status:** Accepted (amended 2026-07-08 — internal `src/agents/` provider seam)  
+**Date:** 2026-07-08
+
+## Decision
+
+V0.2 remains **Cursor Cloud Agent-first**. The only implemented agent execution
+provider is **Cursor**. The harness should still be developed with a **future
+provider boundary in mind** so that additional agent execution providers can be
+introduced later behind a stable internal seam — without rewriting runner
+phases.
+
+Agent provider selection is **not merely a model or env-var swap**. Different
+providers differ across auth, runtime, repository attachment, observation,
+cancellation, and output behavior. Until real adapters exist and are validated,
+the harness must **not claim** support for Claude Code, Codex, VS Code local
+agents, GitLab, Bitbucket, or any non-Linear product system.
+
+To preserve compatibility, current **Cursor marker fields** and **Linear
+metadata** are retained as-is.
+
+## Context
+
+The harness embeds Cursor SDK calls in [`src/cursor/`](../src/cursor/). Runner
+phases import [`src/agents/`](../src/agents/) for agent lifecycle operations;
+the Cursor adapter delegates to `src/cursor/`. This is intentional for V0.2 —
+Cursor is the only execution provider that has been implemented and validated
+end-to-end against Linear + GitHub + GitHub Actions.
+
+It is tempting to describe agent-provider portability as a configuration switch
+(e.g. picking a different model id or setting an environment variable). That
+framing is inaccurate and would overstate maturity. Real providers diverge on:
+
+- **Auth** — how credentials are supplied and scoped.
+- **Runtime** — where and how the agent executes.
+- **Repository attachment** — how the target repo/branch is made available.
+- **Observation** — how run lifecycle and progress are polled or streamed.
+- **Cancellation** — how timeouts and cancels are requested and confirmed.
+- **Output behavior** — how assistant output, branches, and PRs are surfaced.
+
+Because these differences are structural, provider portability requires a real
+adapter interface, not a value swap.
+
+## Rationale
+
+1. **Honest maturity.** Claiming multi-provider support before adapters exist
+   would violate the harness's no-invented-maturity principle.
+2. **Compatibility.** Existing Cursor marker fields and Linear metadata are load
+   -bearing for idempotency and recovery; preserving them avoids breaking
+   in-flight issues.
+3. **Optionality without rewrite.** Designing with a provider boundary in mind
+   keeps the door open for future adapters while keeping V0.2 shippable.
+
+## Future provider adapter requirements
+
+A future agent provider adapter should support:
+
+- planning run creation
+- implementation run creation
+- revision run against an existing PR branch
+- integration repair run against an existing PR branch
+- lifecycle observation
+- terminal status capture
+- assistant output capture
+- branch/PR capture
+- provider diagnostics
+- timeout/cancellation
+- generic error mapping
+- validation evidence reporting
+- raw provider artifact retention
+
+## Near-term migration guidance
+
+- **Make Cursor explicit.** Name Cursor as the provider in docs and config
+  posture rather than implying provider agnosticism. A Cursor-only
+  `agentProvider` config shape now exists (`id: "cursor"`, optional
+  `model.id`); no second adapter is implemented.
+- **Add provider config extensions later** only when a second adapter is
+  validated — do not add speculative provider ids now.
+- **Introduce an internal provider seam later** to isolate Cursor SDK calls out
+  of runner phases behind an interface. *(Done: `src/agents/` seam; runner phases
+  no longer import `src/cursor/` directly.)*
+- **Preserve legacy markers.** Keep `cursorAgentId` and `cursorRunId` markers
+  until they can be safely migrated behind the provider seam.
+- **Preserve `defaultModel` backward compatibility** until callers migrate to
+  `agentProvider.model.id`.
+
+## Consequences
+
+### Positive
+
+- Clear, honest V0.2 posture: Cursor-first, single implemented provider.
+- Compatibility preserved for in-flight Linear issues and recovery.
+- A concrete checklist for what a real adapter must implement.
+
+### Negative / accepted tradeoffs
+
+- Cursor SDK calls remain in `src/cursor/`; runner phases use `src/agents/`.
+- `agentProvider` config exists but only accepts `id: "cursor"`; no second
+  adapter or plugin system is implemented.
+
+## References
+
+- [`docs/provider-portability.md`](../provider-portability.md)
+- [`docs/decisions/0001-cursor-first-v0.1.md`](0001-cursor-first-v0.1.md)
+- [`docs/decisions/0003-automation-state-machine-and-auto-model-policy.md`](0003-automation-state-machine-and-auto-model-policy.md)
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md)
+- [`README.md`](../../README.md)