smol-symphony 0.2.0 → 0.3.0

package/AGENTS.md

@@ -5,35 +5,54 @@ OpenCode, etc.) working on this repo. Keep it short.
 
 ## Where things live
 
-- `src/orchestrator.ts` — top-level wiring; per-issue dispatch lifecycle entry.
-- `src/agent/runner.ts` — per-issue runner; owns the running-entry state the
-  Done-state action context is built from.
-- `src/mcp.ts` — MCP tools exposed to in-VM agents (`symphony.transition`,
-  `symphony.request_human_steering`, `symphony.propose_issue`).
-- `src/workflow.ts` — workflow file parser; the contract `WORKFLOW.template.md`
-  documents.
-- `src/trackers/local.ts` — local markdown tracker (only kind today).
-- `src/acp-bridge.ts` + `scripts/vm-agent.mjs` — host↔VM ACP transport.
+Layout is functional-core / imperative-shell (FCIS): pure decision logic in
+`src/core/`, all effects + wiring in `src/shell/`, shared types in `src/types/`.
+`npm run lint:arch` enforces the import direction (core never reaches the shell;
+only the composition root `src/shell/main.ts` may import core).
+
+- `src/shell/main.ts` — the composition root (top-level wiring). The per-issue
+  dispatch lifecycle runs in `src/shell/orchestrator-loop.ts` (poll-and-dispatch;
+  owns the live RunningEntry map the Done-state action context is built from) and
+  the reconcilers (`src/shell/main-reconcilers*.ts`, `reconciler-loop.ts`); pure
+  scheduling/reconcile decisions live in `src/core/schedule/` + `src/core/reconcile/`.
+- `src/shell/runner-loop.ts` (+ `runner-loop-turn.ts`) — the per-issue attempt
+  pipeline (imperative shell); pure turn / dispatch-config / injection logic lives
+  in `src/core/runner/`, and the typed `actions:` block runs through
+  `src/core/actions/` + `src/shell/actions-runner.ts`.
+- `src/core/mcp/` + `src/shell/main-mcp.ts` (runtime in
+  `src/shell/server/mcp-runtime.ts`) — MCP tools exposed to in-VM agents
+  (`symphony.transition`, `symphony.request_human_steering`,
+  `symphony.propose_issue`).
+- `src/core/workflow/parse.ts` (+ `derive.ts`, `validate.ts`) — workflow file
+  parser, loaded via `src/shell/adapter/workflow-loader.ts`; the contract
+  `WORKFLOW.template.yaml` documents.
+- `src/core/issue/` + `src/shell/interp/tracker*.ts` — local markdown tracker
+  (pure front-matter parse in core; disk scan/read/write in the shell
+  interpreters). Only kind today.
+- `src/shell/interp/acp*.ts` + `scripts/vm-agent.mjs` — host↔VM ACP transport
+  (host-side interpreter over the `/acp` WebSocket served by
+  `src/shell/server/http.ts`; `vm-agent.mjs` is the in-VM guest launcher).
 - `images/agents/` — the agent rootfs image (Node + the ACP coding-agent CLIs +
   the in-VM `/opt/symphony/vm-agent.mjs` launcher), built **once** via
-  `npm run build:image`. Selected by `WORKFLOW.md`'s `gondolin.image` (a build
+  `npm run build:image`. Selected by `WORKFLOW.yaml`'s `gondolin.image` (a build
   id or `name:tag` ref). See `images/agents/README.md`.
-- `src/http.ts` — HTTP dashboard + MCP endpoint listener.
-- `WORKFLOW.md` — canonical workflow this repo dispatches against itself.
-- `WORKFLOW.template.md` — annotated reference for workflow file syntax.
+- `src/core/http/` + `src/shell/main-http*.ts` (listener in
+  `src/shell/server/http.ts`) — HTTP dashboard + MCP endpoint listener.
+- `WORKFLOW.yaml` — canonical workflow this repo dispatches against itself.
+- `WORKFLOW.template.yaml` — annotated reference for workflow file syntax.
 - Handoff (push + PR) is documented in `README.md` § "After-run handoff".
 
 ## Workflow template stays in sync
 
 **When you change anything that affects workflow file syntax or semantics,
-update `WORKFLOW.template.md` in the same commit.** Concretely:
+update `WORKFLOW.template.yaml` in the same commit.** Concretely:
 
 - Adding a new YAML key under `tracker:`, `polling:`, `workspace:`, `hooks:`,
   `agent:`, `acp:`, `gondolin:`, `server:`, or `mcp:` → document it in the
   matching section of the template.
 - Renaming or removing a key → rename or remove it in the template too.
-- Changing a default value in `src/workflow.ts` → update the `Default:`
-  annotation in the template.
+- Changing a default value in `src/core/workflow/parse.ts` → update the
+  `Default:` annotation in the template.
 - Adding a new typed action-context variable (`$branch`, `$pr_title`, …) or
   Liquid prompt-context field → list it in the template alongside the existing
   ones.
@@ -46,15 +65,15 @@ paperwork.
 
 State-machine logic — new transitions, anything that mutates tracker files the
 orchestrator wrote, anything the runner must re-detect afterward — belongs in
-the orchestrator (runner / MCP / `src/orchestrator.ts`) behind typed APIs with
-tests. It is not an extension point you bolt on from the outside.
+the orchestrator (the runner / MCP deciders in `src/core/**`, wired through
+`src/shell/**`) behind typed APIs with tests. It is not an extension point you bolt on from the outside.
 
 Repo-local glue that fires on a transition (push the branch, open a PR) belongs
 in a state's typed `actions:` block — declarative records like `push_branch`,
 `create_pr_if_missing`, and `run_in_vm` that the action executor runs against a
 fixed context (`$branch`, `$base_branch`, `$pr_title`, `$pr_body_file`,
-`$repo`). See `states.Done.actions` in `WORKFLOW.md` for the canonical
-push-branch + open-PR pair, and `WORKFLOW.template.md` for the full kind list.
+`$repo`). See `states.Done.actions` in `WORKFLOW.yaml` for the canonical
+push-branch + open-PR pair, and `WORKFLOW.template.yaml` for the full kind list.
 
 Per-VM tooling — the CLIs and runtimes the agent needs at runtime — belongs in
 the agent image under `images/agents/`, baked once via `npm run build:image`.
@@ -94,7 +113,7 @@ curl -s -X POST http://127.0.0.1:8787/api/v1/issues \
   --data-binary @/tmp/issue.json
 ```
 
-Body shape (from `decideCreateIssue` in `src/http-handlers.ts`):
+Body shape (from `decideCreateIssue` in `src/core/http/decisions.ts`):
 
 ```json
 {
@@ -115,7 +134,7 @@ allocates the next free numeric identifier when one isn't supplied, and writes
 `{ path, identifier, state }`. Conflicts (duplicate identifier, bad state) come
 back as `400`/`409` with a typed error code.
 
-The HTTP server (`server.port` in `WORKFLOW.md`, currently `8787`) is unauthenticated
+The HTTP server (`server.port` in `WORKFLOW.yaml`, currently `8787`) is unauthenticated
 inside the trusted tailscale boundary — no bearer, no CSRF on JSON POSTs from curl.
 If the server isn't running, hand-writing `~/.symphony/trackers/smol-symphony/<state>/<n>.md`
 with the same YAML front-matter shape (`id`, `identifier`, `title`, `created_at`,