b5985f33bb
Add Docker atomic deploy tooling, CI, Playwright smoke/visual suite, shared industrial theme, physics invariants, quality-mode wiring, and a worktree-isolated agent implementer MVP with hard safety limits. Co-authored-by: Cursor <cursoragent@cursor.com>
125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
# Implementer MVP (worktree-isolated)
|
|
|
|
**Status:** Implemented in `agent/cli.mjs`
|
|
**Date:** 2026-07-15
|
|
|
|
Safe, deterministic Implementer cycle that **does not** require an external LLM.
|
|
Patches run only inside a git worktree. The agent **never** merges to `main`, **never** deploys, and **never** pushes.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
| Command | Purpose |
|
|
| ------- | ------- |
|
|
| `dry-run` | Plan only (baseline + propose) |
|
|
| `run-once` | Verify baseline only (no patches) |
|
|
| `implement [--task <path>]` | Full Implementer cycle |
|
|
| `start` | Same as implement, but requires `AUTONOMOUS_AGENT_ENABLED=true` |
|
|
| `status` / `stop` / `resume` / `pause` / `report` | Control plane |
|
|
|
|
```bash
|
|
# Recommended successful demo cycle
|
|
node agent/cli.mjs implement --task agent/tasks/demo-docs.json
|
|
|
|
# Or via helper script
|
|
bash scripts/agent-implement.sh --task agent/tasks/demo-docs.json
|
|
|
|
# Gated continuous entry (still one cycle in MVP)
|
|
AUTONOMOUS_AGENT_ENABLED=true node agent/cli.mjs start --task agent/tasks/demo-docs.json
|
|
```
|
|
|
|
---
|
|
|
|
## Implementer cycle
|
|
|
|
1. **Watchdog** — kill switch, single lock, disk, load, memory
|
|
2. **Plan** — load task JSON (default: `agent/tasks/demo-docs.json`)
|
|
3. **Validate policy** — allowlist only: `docs`, `tests`, `data-testid`, `a11y`, `small-ui`, `logging-scripts`
|
|
4. **Create worktree** — `.agent/worktrees/<run-id>` on branch `agent/<run-id>/<task-slug>`
|
|
5. **Apply bounded patch** — e.g. create `docs/AGENT_CYCLE_DEMO.md`
|
|
6. **Enforce limits** — ≤12 files, ≤800 diff lines, ≤25 min cycle
|
|
7. **Verify** — `npm test && npm run build` inside the worktree
|
|
8. **Score + decide** — `ACCEPT_CANDIDATE` or `REJECT`
|
|
9. **Report** — `agent/reports/<run-id>.json` (+ `latest.json`)
|
|
|
|
### On REJECT
|
|
|
|
- Remove worktree
|
|
- Delete local agent branch
|
|
- Keep the JSON report
|
|
|
|
### On ACCEPT_CANDIDATE
|
|
|
|
- Keep worktree + branch
|
|
- Print manual review instructions
|
|
- Human must cherry-pick / merge into a feature branch if desired
|
|
|
|
---
|
|
|
|
## Watchdog
|
|
|
|
| Check | Fail condition |
|
|
| ----- | -------------- |
|
|
| Lock | `agent/state/agent.lock` held by a live PID (second agent refused) |
|
|
| Kill switch | `agent/state/KILL` present |
|
|
| Disk | `df /` usage **> 85%** |
|
|
| Load | loadavg 1m **> nproc** |
|
|
| Memory | MemAvailable **< 1 GiB** |
|
|
|
|
```bash
|
|
node agent/cli.mjs stop # write KILL
|
|
node agent/cli.mjs resume # clear KILL
|
|
node agent/cli.mjs status # lock + watchdog snapshot
|
|
```
|
|
|
|
---
|
|
|
|
## Example task
|
|
|
|
`agent/tasks/demo-docs.json` — docs-only safe demo:
|
|
|
|
- Policy: `docs`
|
|
- Patch: create `docs/AGENT_CYCLE_DEMO.md`
|
|
- No source / physics / deploy / `.env` changes
|
|
|
|
---
|
|
|
|
## Limits (also in `LIMITS` in `cli.mjs`)
|
|
|
|
| Limit | Value |
|
|
| ----- | ----: |
|
|
| max cycle | 25 min |
|
|
| max files | 12 |
|
|
| max diff lines | 800 |
|
|
| parallel agents | 1 |
|
|
|
|
Hard forbids: merge to main, production deploy, push, secret/`.env` access.
|
|
|
|
---
|
|
|
|
## Manual review after ACCEPT
|
|
|
|
```bash
|
|
# Inspect
|
|
cat agent/reports/latest.json
|
|
git -C .agent/worktrees/<run-id> show HEAD
|
|
|
|
# Accept into your feature branch yourself (example)
|
|
git cherry-pick <agent-commit-sha>
|
|
|
|
# Or discard
|
|
git worktree remove --force .agent/worktrees/<run-id>
|
|
git branch -D agent/<run-id>/demo-docs
|
|
```
|
|
|
|
---
|
|
|
|
## What this MVP does **not** do
|
|
|
|
- Call external LLMs
|
|
- Modify production nginx/docker/deploy
|
|
- Touch `.env`
|
|
- Auto-merge or auto-deploy
|
|
- Change demo physics (prefer docs-only demo task)
|