Merge branch 'main' into feat/compute-strategy

Author: MichaelWalker-git

.cursor/rules/agent-runtime.mdc

@@ -0,0 +1,13 @@
+---
+description: Python agent runtime in isolated compute
+globs: agent/**/*.py
+alwaysApply: false
+---
+
+# Agent runtime (`agent/`)
+
+- **`entrypoint.py`** is the main task loop; prompts live under **`agent/prompts/`** with **`system_prompt.py`** for shared behavior.
+- Follow **`agent/README.md`** for GitHub PAT scopes, env vars, and local **`./agent/run.sh`** usage.
+- Use **`mise run quality`** in **`agent/`** (or root **`mise run build`**, which runs agent quality before CDK) after substantive changes.
+- Do not embed secrets; the stack supplies credentials via Secrets Manager / env as documented.
+- Prefer **`ruff`** / existing patterns; see **`pyproject.toml`** for **`ruff`** and **`pytest`** configuration.

.cursor/rules/cdk-handlers.mdc

@@ -0,0 +1,13 @@
+---
+description: CDK Lambda handlers and shared task pipeline conventions
+globs: cdk/src/handlers/**/*.ts
+alwaysApply: false
+---
+
+# CDK handlers
+
+- Prefer extending existing helpers in `cdk/src/handlers/shared/` (orchestration, validation, preflight) over duplicating logic.
+- When changing API shapes, edit **`cdk/src/handlers/shared/types.ts`** and mirror the same definitions in **`cli/src/types.ts`**.
+- Add or update Jest tests under **`cdk/test/handlers/`** or **`cdk/test/handlers/shared/`** next to the behavior you change (see **AGENTS.md** for a file map).
+- Use **`mise //cdk:test`** and **`mise //cdk:compile`** from the repo root instead of ad-hoc `jest` / `tsc` in the wrong directory.
+- Task lifecycle and admission behavior are described in **`docs/design/ORCHESTRATOR.md`**.

.cursor/rules/cli-package.mdc

@@ -0,0 +1,13 @@
+---
+description: bgagent CLI package conventions
+globs: cli/src/**/*.ts
+alwaysApply: false
+---
+
+# CLI (`@backgroundagent/cli`)
+
+- One command per file under **`cli/src/commands/`**; wire flags and options consistently with existing commands.
+- **`cli/src/types.ts`** must stay aligned with **`cdk/src/handlers/shared/types.ts`** when the REST API changes.
+- Console output is intentional: **`no-console`** is disabled for CLI sources.
+- The API base URL from deployment already includes the stage (e.g. **`/v1/`**); append only resource paths in **`api-client.ts`**.
+- Run **`mise //cli:build`** or **`cd cli && mise run test`** to verify changes.

.cursor/rules/docs-sources.mdc

@@ -0,0 +1,11 @@
+---
+description: Authoritative docs live under guides/ and design/; Starlight is generated
+globs: docs/guides/**/*.md,docs/design/**/*.md
+alwaysApply: false
+---
+
+# Documentation sources
+
+- Edit **`docs/guides/`** and **`docs/design/`** (and root **`CONTRIBUTING.md`** when it affects the site). Do **not** hand-edit **`docs/src/content/docs/`** — that tree is produced by **`docs/scripts/sync-starlight.mjs`**.
+- After changing guides or design Markdown, run **`mise //docs:sync`** or **`mise //docs:build`** from the repo root.
+- **`AGENTS.md`** is the root entry for contributors and coding agents; keep it in sync conceptually when you change cross-cutting dev workflows.

.github/ISSUE_TEMPLATE/documentation.yml

@@ -9,6 +9,20 @@ body:
     attributes:
       value: |
         Thanks for helping improve the documentation. Relevant docs live in `docs/guides/`, `docs/design/`, and the repo README.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Doc area
+      description: What kind of documentation is affected?
+      options:
+        - User guide (`docs/guides/USER_GUIDE.md` or synced site)
+        - Developer guide (`docs/guides/DEVELOPER_GUIDE.md` or synced site)
+        - Design / architecture (`docs/design/`)
+        - Roadmap or prompts (`docs/guides/`)
+        - README / root docs
+        - Other
+    validations:
+      required: true
   - type: textarea
     id: description
     attributes:

.github/ISSUE_TEMPLATE/rfc.yml

@@ -9,6 +9,21 @@ body:
     attributes:
       value: |
         Use this template for significant feature or design proposals. Please add as much detail as possible. See the [ROADMAP](https://github.com/krokoko/bgagent/blob/main/docs/guides/ROADMAP.md) and [design docs](https://github.com/krokoko/bgagent/tree/main/docs/design) for existing direction; your RFC should align or explain divergence.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Primary area
+      description: Which part of the repo does this RFC mainly affect?
+      options:
+        - CDK / infrastructure
+        - Agent (Python runtime)
+        - CLI (bgagent)
+        - API or orchestration
+        - Documentation
+        - Tooling / CI
+        - Cross-cutting / multiple
+    validations:
+      required: true
   - type: input
     id: relation
     attributes:

.github/pull_request_template.md

@@ -8,7 +8,40 @@ You are an **AWS CDK (Cloud Development Kit) and TypeScript** expert. This proje
 
 ## Project knowledge
 
-To get started and understand the developer flow, follow the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md). For architecture and design, see [docs/design/](./docs/design/ARCHITECTURE.md).
+To get started and understand the developer flow, follow the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md). For architecture and design, see [docs/design/](./docs/design/ARCHITECTURE.md). Task lifecycle and handler contracts are summarized in [Orchestrator design](./docs/design/ORCHESTRATOR.md) (including **API and agent contracts**).
+
+### Where to make changes
+
+Use this routing before editing so the right package and tests get updated:
+
+| Change | Primary location | Also update |
+|--------|------------------|-------------|
+| REST API, Lambdas, task validation, orchestration | `cdk/src/handlers/`, `cdk/src/stacks/`, `cdk/src/constructs/` | Matching tests under `cdk/test/` |
+| Shared API request/response shapes | `cdk/src/handlers/shared/types.ts` | **`cli/src/types.ts`** (must stay in sync) |
+| `bgagent` CLI commands and HTTP client | `cli/src/`, `cli/test/` | `cli/src/types.ts` if API types change |
+| Agent runtime (clone, tools, prompts, container) | `agent/` (`entrypoint.py`, `prompts/`, `Dockerfile`, etc.) | `agent/tests/`, `agent/README.md` for env/PAT |
+| User-facing or design prose | `docs/guides/`, `docs/design/` | Run **`mise //docs:sync`** or **`mise //docs:build`** (do not edit `docs/src/content/docs/` by hand) |
+| Monorepo tasks, CI glue | Root `mise.toml`, `scripts/`, `.github/workflows/` | — |
+
+### CDK handler tests (quick map)
+
+Colocated tests under `cdk/test/handlers/shared/` cover most shared logic:
+
+- `validation.test.ts` — request validation
+- `preflight.test.ts` — preflight / admission checks
+- `create-task-core.test.ts` — task creation core path
+- `context-hydration.test.ts` — prompt / context assembly
+- `repo-config.test.ts`, `memory.test.ts`, `gateway.test.ts`, `response.test.ts`, `prompt-version.test.ts` — respective modules
+
+Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.test.ts`, `webhook-create-task.test.ts`. Construct wiring: `cdk/test/constructs/task-orchestrator.test.ts`, `task-api.test.ts`.
+
+### Common mistakes
+
+- Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.
+- Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
+- Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)).
+- **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
+- **`mise run build`** runs **`//agent:quality`** before CDK — the deployed image bundles **`agent/`**; agent changes belong in that tree.
 
 ### Tech stack
 
@@ -24,7 +57,7 @@ To get started and understand the developer flow, follow the [Developer guide](.
 - **`scripts/`** (root) — Optional cross-package helpers; **`scripts/ci-build.sh`** runs the full monorepo build (same as CI).
 - **`cdk/`** — CDK app package (`@abca/cdk`): `cdk/src/`, `cdk/test/`, `cdk/cdk.json`, `cdk/tsconfig.json`, `cdk/tsconfig.dev.json`, and `cdk/.eslintrc.json`.
 - **`cli/`** — `@backgroundagent/cli` — CLI tool for interacting with the deployed REST API (see below).
-- **`agent/`** — Python code that runs inside the agent compute environment (entrypoint, server, system prompt, Dockerfile, requirements).
+- **`agent/`** — Python code that runs inside the agent compute environment (entrypoint, server, system prompt, Dockerfile, requirements). The system prompt is refactored into `agent/prompts/` with a shared base template and per-task-type workflow variants (`new_task`, `pr_iteration`, `pr_review`).
 - **`docs/`** — Authoritative Markdown in `guides/` (developer, user, roadmap, prompt) and `design/`; assets in `diagrams/`, `imgs/`. The Starlight docs site lives here (`astro.config.mjs`, `package.json`); `src/content/docs/` is refreshed via `docs/scripts/sync-starlight.mjs`.
 - **`CONTRIBUTING.md`** — Contribution guidelines at the repository root.
 - **`package.json`** (root), **`yarn.lock`** — Yarn workspace root (minimal manifest); dependencies live in **`cdk/`**, **`cli/`**, and **`docs/`** package manifests.
@@ -40,7 +73,7 @@ The `@backgroundagent/cli` package provides the `bgagent` executable for submitt
 - `src/api-client.ts` — HTTP client wrapping `fetch` with auth header injection
 - `src/auth.ts` — Cognito login, token caching (`~/.bgagent/credentials.json`), auto-refresh
 - `src/config.ts` — Read/write `~/.bgagent/config.json`
-- `src/types.ts` — API request/response types (mirrored from `cdk/src/handlers/shared/types.ts`)
+- `src/types.ts` — API request/response types (mirrored from `cdk/src/handlers/shared/types.ts`), including `TaskType` (`new_task` | `pr_iteration` | `pr_review`)
 - `src/format.ts` — Output formatting (table, detail view, JSON)
 - `src/debug.ts` — Verbose/debug logging (`--verbose` flag)
 - `src/errors.ts` — `CliError` and `ApiError` classes

AGENTS.md

@@ -22,6 +22,8 @@ When filing an issue, please check [existing open](https://github.com/aws-sample
 
 ### Pull Request Checklist
 
+When planning edits, use **[AGENTS.md](./AGENTS.md)** at the repo root for **where to change code** (CDK vs CLI vs agent vs docs), **which tests to extend**, and **common pitfalls** (generated docs, mirrored API types, `mise` tasks).
+
 * [ ] Testing
   - Unit test added (prefer not to modify an existing test, otherwise, it's probably a breaking change)
   - Integration test added (if adding a new pattern or making a significant update to an existing pattern)

CONTRIBUTING.md

@@ -42,8 +42,9 @@ Each task follows a **blueprint** — a hybrid workflow that mixes deterministic
 
 1. **Admission** — the orchestrator validates the request, checks concurrency limits, and queues the task if needed.
 2. **Context hydration** — the platform gathers context: task description, GitHub issue body, repo-intrinsic knowledge (CLAUDE.md, README), and memory from past tasks on the same repo.
-3. **Agent execution** — the agent runs in an isolated MicroVM: clones the repo, creates a branch, edits code, commits, runs tests and lint. The orchestrator polls for completion without blocking compute.
-4. **Finalization** — the orchestrator infers the result (PR created or not), runs optional validation (lint, tests), extracts learnings into memory, and updates task status.
+3. **Pre-flight** — fail-closed readiness checks verify GitHub API reachability and repository access before consuming compute. Doomed tasks fail fast with a clear reason (`GITHUB_UNREACHABLE`, `REPO_NOT_FOUND_OR_NO_ACCESS`) instead of burning runtime.
+4. **Agent execution** — the agent runs in an isolated MicroVM with persistent session storage for select caches: clones the repo, creates a branch, edits code, commits, runs tests and lint. The orchestrator polls for completion without blocking compute.
+5. **Finalization** — the orchestrator infers the result (PR created or not), runs optional validation (lint, tests), extracts learnings into memory, and updates task status.
 
 For the full architecture, see [ARCHITECTURE.md](./docs/design/ARCHITECTURE.md).
 
@@ -58,7 +59,7 @@ ABCA is under active development. The platform ships iteratively — each iterat
 | **3a** | Done | Repo onboarding, per-repo GitHub App credentials, turn caps, prompt guide |
 | **3b** | Done | Memory Tier 1, insights, agent self-feedback, prompt versioning, commit attribution |
 | **3bis** | Done | Hardening — reconciler error tracking, error serialization, test coverage gaps |
-| **3c** | WIP | Deterministic validation, PR review task type, multi-modal input |
+| **3c** | WIP | Pre-flight checks, persistent session storage, deterministic validation, PR review task type, multi-modal input |
 | **3d** | Planned | Review feedback loop, PR outcome tracking, evaluation pipeline |
 | **4** | Planned | GitLab, visual proof, Slack, control panel, WebSocket streaming |
 | **5** | Planned | Pre-warming, multi-user/team, cost management, guardrails, alternate runtime |