docs: sync PRD status table and lifecycle section with post-de57f72 implementation

This commit is contained in:
sam committed 2026-07-22 02:45:48 +10:00
1 parent de57f72cce
commit 121dd7d815
1 file changed
+26 -38
+26 -38
View File
@@ -6,33 +6,26 @@
---
## 0. Implementation status (as of 2026-07-22)
## 0. Implementation status (as of 2026-07-22, updated 2026-07-22)
This document describes a target end state. A parallel exploration of the codebase found that most of it is greenfield
-- not a delta from current code. The table below is the ground truth; read it before treating any section as already
built.
This document describes a target end state. The table below is the ground truth; read it before treating any section as already built.
| Area | Status | What actually exists today |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Daemon/agent binary split | **Partial** | `cmd/archied` and `cmd/archie-agent` both exist, but `archied` owns task discovery, routing, and full multi-stage workflow sequencing. `archie-agent` is a 28-line stdin/stdout worker invoked once **per stage**, not a persistent per-task process. See sec.1. |
| Sandbox / "daemon never runs untrusted code" | **Not true today** | Default `[agent] mode = "inprocess"` runs the LLM agent loop, and therefore all tool calls, inside `archied` itself. `subprocess` mode exists but its own code comment says explicitly it is "not an OS security boundary." No Docker sandbox exists. See sec.1, sec.4. |
| NATS / JetStream messaging | **Aspirational -- zero code** | No `nats`/`jetstream` dependency, no subject hierarchy, no pub/sub anywhere. Task distribution today is GitHub polling -> SQLite `tasks` table used as a queue (`ClaimNext` claims the oldest row) -> fully sequential, single-goroutine, in-process execution. Results flow through an in-process `internal/events.Bus` (Go channels) feeding SQLite + SSE. See sec.2. |
| Docker container sandbox | **Aspirational -- zero code** | No Docker/container code anywhere (grep confirms zero implementation hits; the only "container" matches are comments contrasting today's subprocess approach with a hypothetical future runner). `config.example.toml` itself says: _"The worker still runs as the daemon user until the Docker sandbox phase lands."_ See sec.4. |
| `/data/` volume, `task.json` | **Aspirational -- zero code** | No file named `task.json` exists anywhere. The closest analog, `store.Task`, is a SQLite-row Go struct with a materially different shape (flat comma-separated `labels`, no nested `config`/`nats` objects) passed by function call, never serialized to a volume. See sec.3. |
| `[containers]` config block | **Aspirational -- zero code** | `internal/config/config.go` has no `[containers]`, `[containers.image]`, or `[containers.persistent_storage]` sections, and `Repo` has no `persistent_storage` override field. See sec.4. |
| Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** -- but scoped differently than sec.5 describes | Three surfaces are real, working, and production-tested today: `.archie/gate.go` (custom gates), `.archie/stages/*.go` (custom workflow stages, auto-discovered and run in filename order -- no `config.toml`-driven named routing), and skill-local `scripts/*.go` via a `run_go_script` agent tool. All run in-process inside `archied`, re-read from disk every call (no caching layer needed). Full detail lives in the sibling PRD `docs/prds/yaegi-plugin-system.md`, whose Phases 1--3 are marked implemented and match disk state 1:1. See sec.5, and the reconciliation note there. |
| Layer 1: skill-bundled plugins (`metadata.archie.plugins`, `/data/plugins/`) | **Aspirational -- zero code** | No skill currently ships a `plugins/` directory, no code reads `metadata.archie.plugins`, no daemon-side staging to `/data/plugins/`, no volume-precedence conflict resolution. See sec.5. |
| Layer 2: core daemon plugins (`~/.config/archie/plugins/`, `Plugin` interface) | **Aspirational -- zero code** | No `Plugin` interface, no `Register(daemon *Daemon)`, no plugin registry, no loader for `~/.config/archie/plugins/`. Grepped for `Plugin`/plugin registry/`Register(daemon` -- zero matches anywhere in the repo. See sec.5. |
| Skills (`archie-wf-*`, agentskills.io spec) | **Cosmetic only** | Five `SKILL.md` files exist (`ecosystem-node`, `ecosystem-python`, `go-quality-gate`, `security-audit`, `tdd-bugfix`) with a `metadata.archie` block (`tools`, `engine` -- no `plugins` or `budget_usd` keys). None use the `archie-wf-*` naming convention. **No Go code parses SKILL.md frontmatter, loads it, or does progressive disclosure at all** -- they are documentation of existing hardcoded Go workflow stages, not a loaded specification. One drift found: `tdd-bugfix/SKILL.md` names the final stage "deliver"; the code calls it `open-pr`. See sec.5. |
| Worktree/repo management | **Implemented, but ephemeral, not volume-based** | `internal/worktree.Manager` does a full fresh `git clone` per task attempt (removing any prior directory first) -- no shared object cache, no persistence, no TTL. This answers PRD open question 3: today it is 100% per-task, daemon-owned, non-reusable. See sec.3, sec.9. |
| Config schema | **Simpler than sec.4 describes** | Current `[agent]` block is just `mode` (`inprocess`/`subprocess`) + `command` + `env` -- no image registry, no volume TTL, no concurrency cap. See sec.4. |
| Area | Status | What actually exists today (post-e4d11b1) |
|---|---|---|
| Daemon/agent binary split | **Implemented** | `cmd/archied` and `cmd/archie-agent` both exist. `archie-agent` is a 189-line NATS-connected per-task worker that subscribes to task subjects, runs the full multi-stage workflow, and reports results. Workflow routing and sequencing (`workflow.Route`, `workflow.Run`) now run inside the agent, not the daemon. Three agent modes: `inprocess`, `subprocess`, `nats`. |
| Sandbox / "daemon never runs untrusted code" | **Partial** | Default mode is still `inprocess` for development. Docker sandbox mode (`agent.mode = "nats"` + `containers.enabled = true`) runs each task in an ephemeral Docker container with workspace bind-mounted at `/workspace`. `internal/container/pool.go` manages full lifecycle: pull, create, start, release, orphan recovery. `max_concurrency` enforced. |
| NATS / JetStream messaging | **Implemented** | `internal/nats/client.go` (176 lines): JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), `PublishTask`, `Fetch`, `NewReplyInbox`. Subject hierarchy in `internal/nats/subjects.go`. `[nats]` config block in config.go. `internal/agentexec/nats.go` implements NATS-based agent runner. |
| Docker container sandbox | **Implemented** | `internal/container/pool.go` (210 lines): Docker API client, image pull (always/missing/never), container create with workspace bind mount, start, release (stop+remove), orphan recovery on daemon restart. `Dockerfile` at repo root builds archie-agent fat image. `[containers]` config block: enabled, image, max_concurrency, max_uptime, pull_policy. `agent.mode = "nats"` required when containers enabled. |
| `/data/` volume, `task.json` | **Partial** | No `/data/task.json` file convention exists. Containers mount a workspace directory at `/workspace` (bind mount, host path). Task payload travels over NATS, not a volume file. Worktrees are still ephemeral fresh clones per task. |
| `[containers]` config block | **Implemented** | `ContainerConfig` struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load. |
| Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** | Three surfaces: `.archie/gate.go`, `.archie/stages/*.go`, skill scripts via `run_go_script` tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in `docs/prds/yaegi-plugin-system.md`. |
| Layer 1: skill-bundled plugins | **Aspirational** | No skill ships a `plugins/` directory. No code reads `metadata.archie.plugins`. No volume-staged plugin loading. |
| Layer 2: core daemon plugins | **Aspirational** | No `Plugin` interface, no registry, no `~/.config/archie/plugins/` loader. |
| Skills (agentskills.io spec) | **Partial** | `internal/skill/skill.go` (116 lines): parses SKILL.md YAML frontmatter, discovers skills from `.agents/skills/*/SKILL.md`, extracts body. Skills moved from `.archie/skills/` to `.agents/skills/`. No `archie-wf-*` naming convention yet. No progressive disclosure -- body injected directly. |
| Worktree/repo management | **Implemented, ephemeral** | Fresh `git clone` per task attempt, no shared cache, no persistence, no TTL. |
| Config schema | **Closer to sec.4** | `[agent]` block: mode (inprocess/subprocess/nats) + command + env. `[nats]` block: url + token_env. `[containers]` block: enabled, image, max_concurrency, max_uptime, pull_policy. No per-repo persistent_storage override yet. |
**Net read:** the two things that are genuinely further along than a plain reading of this doc's phase list would
suggest are (a) the Yaegi extension surfaces (real, tested, in production -- just narrower and differently-shaped than
sec.5's Layer 1/2 split), and (b) the `agentexec.Runner` interface (`InProcessRunner`/`SubprocessRunner`), which its own
doc comments describe as deliberately designed so a future container runner is a drop-in swap rather than a rewrite.
Everything else in this document -- NATS, Docker, `/data/` volumes, core plugin registry, agentskills.io loading -- is a
from-scratch build, not a refactor.
**Net read post-e4d11b1:** Phases 1 and 2 are substantially implemented -- NATS, Docker sandbox, skill parsing all landed in three commits. The remaining aspirational work is core plugin registry (Layer 2), skill-bundled plugins (Layer 1), skill progressive disclosure, and pluggable storage backends. The PRD is now more "current state with aspirational sections" than "entirely aspirational."
---
@@ -391,21 +384,16 @@ logged and skipped -- the daemon starts with remaining plugins.
## 6. Task lifecycle (v2)
> **Status: aspirational shape, real states.** The status values (`pr_open`, `merged`, `rejected`, `parked`, etc.) and
> stage names are real -- they're the actual `store.Task.Status`/`Stage` values used today. What's aspirational is the
> _execution model_ implied by this diagram: today there is no JetStream publish step, and "Agent consumes" is really
> "the daemon's single poll-loop goroutine claims the next queued row from SQLite and runs the whole workflow
> synchronously in-process" (`daemon.Cycle()` -> `store.ClaimNext` -> `process()` -> `workflow.Run()`). There is no
> concurrent multi-agent consumption today -- see sec.0 and sec.2.
> **Status: implemented.** NATS JetStream is now the task distribution path (`internal/nats/client.go`, `internal/daemon/daemon.go:drainNATS()`). Docker containers spawn per task (`internal/container/pool.go`). The flow below matches the running code post-e4d11b1.
```flow
Discover -- -> Publish to JetStream -- -> Agent consumes -- -> running(workflow:stage)
v
pr_open -> merged | rejected
v
waiting_human -> (approved) -> requeue
v
parked
```
Discover -> Publish to JetStream -> Agent consumes -> running(workflow:stage)
v
pr_open -> merged | rejected
v
waiting_human -> (approved) -> requeue
v
parked
```
### Detailed flow