plan: re-evaluate against current sx (2026-06-11)
sx delivered most of the foundation since the plan was written: alias re-exports instead of pub, the modules/std.sx facade barrel, and native std fs/process/json/cli/hash/log/test/socket/mem. Replace the 'sx Foundation Work' section with as-built status + remaining gaps, mark Phase 0 done / Phase 1 partial, note the superseded subplan-01 slices, and drop the retired flow-harness execution contract (subplan 08, roles, checkpoint files).
This commit is contained in:
@@ -1,5 +1,16 @@
|
||||
# Subplan 01 - sx Language And Standard Library
|
||||
|
||||
> **Status (2026-06-11):** largely superseded by sx itself. Slice 1 shipped
|
||||
> as-built with a different design — there is no `pub`; aliases are the
|
||||
> re-export mechanism and `modules/std.sx` is the barrel. Slice 2 is settled
|
||||
> (`!` error channel, `catch (e)` bindings). Slices 5–7 partially shipped
|
||||
> (`std.fs`, `std.process`, `std.hash` SHA-256, `std.json`, `std.cli`,
|
||||
> `std.log`). Still open: Unicode/String model (Slice 3),
|
||||
> HashMap/StringBuilder (Slice 4), bytes/paths (Slice 5 remainder),
|
||||
> time/random/encoding (Slice 6 remainder), config (Slice 7 remainder), and
|
||||
> HTTP/TLS/SQLite/archive/testing helpers (Slice 8). See "sx Foundation
|
||||
> Status" in `PLAN.md`.
|
||||
|
||||
## Goal
|
||||
|
||||
Build the language and std primitives required before the distribution platform
|
||||
|
||||
@@ -1,200 +0,0 @@
|
||||
# Subplan 08 - Orchestration, Checkpoints, And QA
|
||||
|
||||
## Goal
|
||||
|
||||
Keep agent work resumable, auditable, and constrained.
|
||||
|
||||
## Required Files
|
||||
|
||||
- `.agents/ORCHESTRATION.md`
|
||||
- `.agents/CHECKPOINT.md`
|
||||
- `.agents/checkpoint.json`
|
||||
- `.agents/subplans/README.md`
|
||||
- `.agents/runs/<run-id>/...`
|
||||
|
||||
## Run Creation
|
||||
|
||||
For each substantial task:
|
||||
|
||||
1. Create `.agents/runs/<run-id>/`.
|
||||
2. Copy relevant acceptance criteria into `brief.md`.
|
||||
3. Record the active branch.
|
||||
4. Record allowed write paths.
|
||||
5. Update checkpoint before invoking Opus.
|
||||
|
||||
Manager planning sessions count as substantial tasks when the user expects
|
||||
observability. Create a run record for planning work too, with Codex manager as
|
||||
the active agent.
|
||||
|
||||
## Agent Liveness
|
||||
|
||||
Each active run should include:
|
||||
|
||||
```txt
|
||||
.agents/runs/<run-id>/
|
||||
state.json
|
||||
agents.json
|
||||
```
|
||||
|
||||
`state.json` records:
|
||||
|
||||
- run id
|
||||
- current phase
|
||||
- current branch
|
||||
- input artifact
|
||||
- input hash
|
||||
- expected output artifact
|
||||
- retry count
|
||||
- next action
|
||||
- blocker, if any
|
||||
|
||||
`agents.json` records:
|
||||
|
||||
- role
|
||||
- status: queued, running, completed, failed, dead, restarted
|
||||
- started_at
|
||||
- heartbeat_at
|
||||
- lease_expires_at
|
||||
- thread id, process id, or tool call id when available
|
||||
- last_error
|
||||
|
||||
## Status And Progress Tail
|
||||
|
||||
Use the local status command from the workspace root:
|
||||
|
||||
```sh
|
||||
node .agents/scripts/status.mjs --tail 40
|
||||
```
|
||||
|
||||
For a browser dashboard:
|
||||
|
||||
```sh
|
||||
node .agents/scripts/observe.mjs --port 4317
|
||||
```
|
||||
|
||||
Then open `http://127.0.0.1:4317`.
|
||||
|
||||
The command reads:
|
||||
|
||||
- `.agents/checkpoint.json`
|
||||
- every `.agents/runs/<run-id>/state.json`
|
||||
- every `.agents/runs/<run-id>/agents.json`
|
||||
|
||||
It prints:
|
||||
|
||||
- all known runs
|
||||
- current phase and branch
|
||||
- all recorded agents and their lease status
|
||||
- expired leases
|
||||
- blockers
|
||||
- the next action
|
||||
- the tail of the active run's progress file
|
||||
|
||||
Progress files are checked in this order:
|
||||
|
||||
- `progress.log`
|
||||
- `implementation-log.md`
|
||||
- `validation.md`
|
||||
- `opus-proposal.md`
|
||||
- `snarky-review.md`
|
||||
|
||||
Managers should append progress events to `progress.log` whenever possible.
|
||||
Human-readable phase artifacts still stay in their named markdown files.
|
||||
|
||||
## Agent Restart Policy
|
||||
|
||||
If an agent dies, the manager restarts the role from durable files, not memory.
|
||||
|
||||
Snarky restart:
|
||||
|
||||
- Read `PLAN.md`, `.agents/ORCHESTRATION.md`, checkpoint files, and active run
|
||||
artifacts.
|
||||
- Re-run the current Snarky phase using the same input artifact.
|
||||
- Replace only the expected Snarky output for that phase.
|
||||
|
||||
Opus proposal/review restart:
|
||||
|
||||
- Re-run the same `opus-runner` planning tool with the same input artifact.
|
||||
- Keep previous failed output, if any, as diagnostic context.
|
||||
- Do not advance until the expected output validates.
|
||||
- Use a lease and CLI/tool timeout of at least 30 minutes.
|
||||
|
||||
Opus implementation restart:
|
||||
|
||||
- Check current branch.
|
||||
- Check dirty state.
|
||||
- If the branch is clean, retry the same implementation instruction.
|
||||
- If the branch is dirty, manager must inspect the diff and decide whether to
|
||||
continue, ask Opus to repair, or ask the user.
|
||||
- Never auto-reset or discard partial Opus edits.
|
||||
- Use a lease and CLI/tool timeout of at least 30 minutes.
|
||||
|
||||
Retry limits:
|
||||
|
||||
- Retry a dead planning phase up to 2 times.
|
||||
- Retry an implementation phase up to 1 time without user input.
|
||||
- After the retry cap, record a blocker in checkpoint files.
|
||||
|
||||
## Checkpoint Policy
|
||||
|
||||
Update checkpoints:
|
||||
|
||||
- at the start of a run
|
||||
- after Snarky brief
|
||||
- after Opus proposal
|
||||
- after concern resolution
|
||||
- before Opus implementation
|
||||
- after implementation
|
||||
- after validation
|
||||
- before ending the turn
|
||||
|
||||
Checkpoint must include:
|
||||
|
||||
- timestamp
|
||||
- current phase
|
||||
- current branch
|
||||
- active run id
|
||||
- completed artifacts
|
||||
- next action
|
||||
- blockers
|
||||
- commands/checks already run
|
||||
|
||||
## Validation Layers
|
||||
|
||||
Manager validation:
|
||||
|
||||
- git branch and diff check
|
||||
- out-of-scope file check
|
||||
- syntax checks
|
||||
- unit/integration tests when available
|
||||
- browser/screenshot checks for UI work when available
|
||||
|
||||
Snarky validation:
|
||||
|
||||
- product requirements
|
||||
- acceptance criteria
|
||||
- install flow accuracy
|
||||
- scope discipline
|
||||
|
||||
Opus validation:
|
||||
|
||||
- layout/design quality
|
||||
- interaction clarity
|
||||
- technical design concerns
|
||||
|
||||
## Resume Procedure
|
||||
|
||||
After power loss or interruption:
|
||||
|
||||
1. Read `.agents/CHECKPOINT.md`.
|
||||
2. Read `.agents/checkpoint.json`.
|
||||
3. Check git branch and dirty state.
|
||||
4. Read the active run directory if present.
|
||||
5. Continue from `next_action`.
|
||||
6. Do not assume an Opus implementation completed unless validation is recorded.
|
||||
|
||||
## Current Known Setup Issue
|
||||
|
||||
The distribution workspace is not currently a git repository. Branch-based Opus
|
||||
implementation requires initializing git or moving these files into a repo with
|
||||
a clean baseline commit.
|
||||
@@ -1,31 +1,25 @@
|
||||
# Detailed Subplan Index
|
||||
|
||||
These subplans break `PLAN.md` into implementation slices that can be handed to
|
||||
Snarky and Opus without reloading the whole plan every time.
|
||||
These subplans break `PLAN.md` into implementation slices.
|
||||
|
||||
## Reading Order
|
||||
|
||||
1. `01-language-and-stdlib.md`
|
||||
1. `01-language-and-stdlib.md` (largely superseded — see "sx Foundation
|
||||
Status" in `PLAN.md` for the as-built state and remaining gaps)
|
||||
2. `02-domain-and-storage.md`
|
||||
3. `03-cli-and-ci.md`
|
||||
4. `04-http-api-and-install.md`
|
||||
5. `05-artifact-validation.md`
|
||||
6. `06-admin-ui.md`
|
||||
7. `07-packaging-nas.md`
|
||||
8. `08-orchestration-and-qa.md`
|
||||
|
||||
## Session Contract
|
||||
## Working Contract
|
||||
|
||||
- Read `PLAN.md`, `.agents/ORCHESTRATION.md`, `.agents/CHECKPOINT.md`, and
|
||||
the active subplan before doing work.
|
||||
- Keep work sequential. Do not use parallel implementation agents.
|
||||
- Use git branches for implementation. Do not use worktrees.
|
||||
- For product or UX scope, Snarky writes acceptance criteria and has final say.
|
||||
- For layout and visual design, Opus has final say.
|
||||
- For technical problems, consult Opus and resolve by consensus.
|
||||
- Opus is the only role that writes application code during Opus phases.
|
||||
- Update `.agents/CHECKPOINT.md` and `.agents/checkpoint.json` after every
|
||||
completed slice, before any risky handoff, and after validation.
|
||||
- The multi-agent flow harness is retired; work happens directly in-session.
|
||||
- Read `PLAN.md` and the active subplan before doing work. The active
|
||||
milestone slice plan and step progress live in `current/`.
|
||||
- Implementation is branch-based; `make test` must be green at each step
|
||||
boundary.
|
||||
|
||||
## Slice Exit Criteria
|
||||
|
||||
@@ -35,10 +29,3 @@ Every slice should finish with:
|
||||
- Tests/checks run listed.
|
||||
- Known risks listed.
|
||||
- Next slice named.
|
||||
- Checkpoint updated.
|
||||
|
||||
## Current Priority
|
||||
|
||||
The first blocking priority is `01-language-and-stdlib.md`. Product code should
|
||||
wait until the required `sx` primitives exist or an explicit temporary shim is
|
||||
approved.
|
||||
|
||||
Reference in New Issue
Block a user