p-dev-harness 0.3.0 → 0.3.1

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)