diff --git a/.agents/subplans/01-language-and-stdlib.md b/.agents/subplans/01-language-and-stdlib.md index 51e3592..9f85fdd 100644 --- a/.agents/subplans/01-language-and-stdlib.md +++ b/.agents/subplans/01-language-and-stdlib.md @@ -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 diff --git a/.agents/subplans/08-orchestration-and-qa.md b/.agents/subplans/08-orchestration-and-qa.md deleted file mode 100644 index 192eed5..0000000 --- a/.agents/subplans/08-orchestration-and-qa.md +++ /dev/null @@ -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 Creation - -For each substantial task: - -1. Create `.agents/runs//`. -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// - 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//state.json` -- every `.agents/runs//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. diff --git a/.agents/subplans/README.md b/.agents/subplans/README.md index fc97f0b..fd7fdf1 100644 --- a/.agents/subplans/README.md +++ b/.agents/subplans/README.md @@ -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. diff --git a/PLAN.md b/PLAN.md index b05f9a5..4c1ce0e 100644 --- a/PLAN.md +++ b/PLAN.md @@ -156,48 +156,53 @@ Deployment direction: - UGREEN NAS deployment through Docker/Container Manager is a first-version requirement. -## sx Foundation Work +## sx Foundation Status -Before the product can be implemented well, `sx` needs a stronger language and -standard library foundation. +Re-evaluated 2026-06-11 against the current sx tree. The original foundation +asks have largely landed, with one design difference: sx has no `pub` keyword. +Visibility is import-scoped; aliases are the re-export mechanism +(`print :: core.print`), and a module's namespace tail carries one level into +flat importers. `modules/std.sx` is the curated barrel this plan asked for. -Language/module needs: +Delivered in sx and used by this repo: -- `pub` exports so std modules do not leak private helpers. -- Alias imports and curated namespace barrels. -- Namespace member re-export syntax such as `pub print :: core.print`. -- Error handling that follows the real sx model. `!` is an error channel, not a - generic result wrapper. +- Module system: alias imports, alias re-exports, namespace barrels, + one-level carry, dir-vs-file ambiguity rejection. +- Error handling: the `!` error channel with `raise`/`catch`/`onfail` + (bindings take parens), `?T` optionals. +- `std` modules under `modules/std/`: core, fmt, list, mem (typed allocator + helpers over `alloc_bytes`/`dealloc_bytes`), fs, process, socket (raw TCP), + json, xml, cli, hash (streaming SHA-256), log (leveled, no timestamps yet), + test (bare assert). -Standard library needs, at overview level: +Still missing from sx — the forward wishlist; each item either blocks a later +subplan or has an explicit local workaround: -- Collections: extended `List`, `HashMap` +- Collections: `HashMap` (linear scan over `List` pairs meanwhile). - Strings: validated UTF-8 `String`, `StringBuilder`, explicit Unicode model -- Bytes and paths -- Filesystem and process APIs -- Time, random, hashing, and encoding -- JSON, URL, MIME, config, CLI, and logging -- HTTP server/client and TLS boundary -- SQLite -- Archive inspection -- Testing helpers - -Unicode must be specified precisely: - -- `String` is validated UTF-8 bytes. -- Byte length, scalar values, grapheme clusters, and display width are distinct. -- APIs must clearly say which unit they operate on. -- Invalid UTF-8 must not silently become a `String`. + (byte length, scalar values, grapheme clusters, and display width are + distinct; invalid UTF-8 must not silently become a `String`). +- Bytes and a full path module (only `path_join`/`basename`/`dirname` today). +- Time/clock (publish shims `time(2)` via FFI), random, encodings + (base64url, percent). +- HTTP server/client and TLS boundary — blocks subplan 04 and remote publish + (subplan 03 Slice 3). +- SQLite — blocks subplan 02 Slice 2 (`db.json` stands in). +- Archive inspection — blocks deep IPA/APK validation (subplan 05). +- Config layering (env/file/CLI) and richer testing helpers. ## Implementation Phases -Phase 0 - sx language/module prerequisites: +Phase 0 - sx language/module prerequisites (done, as-built): -- Add `pub` support, alias imports, and namespace member re-exports. +- Delivered in sx via alias re-exports and namespace barrels; there is no + `pub` keyword. -Phase 1 - standard library foundation: +Phase 1 - standard library foundation (partial): -- Build the std primitives needed for CLI, HTTP, storage, validation, and tests. +- Delivered: fs, process, json, cli, hash, log, test, socket, mem. +- Outstanding: HashMap, StringBuilder/Unicode model, time, random, encodings, + HTTP/TLS, SQLite, archive (see "sx Foundation Status"). Phase 2 - product domain: @@ -305,21 +310,10 @@ verifiable from the repo: ## Detailed Execution -`PLAN.md` is the overview. Detailed implementation breakdowns live in -`.agents/subplans/`. +`PLAN.md` is the overview. Slice breakdowns live in `.agents/subplans/` +(01–07). The active milestone slice plan and step progress live in `current/` +(`PLAN.md`, `CHECKPOINT-DISTRIBUTION.md`). -Before starting or resuming work, read: - -- `.agents/ORCHESTRATION.md` -- `.agents/CHECKPOINT.md` -- `.agents/checkpoint.json` -- the active `.agents/subplans/*.md` file - -The workflow is sequential and branch-based: - -- Codex manages orchestration and validation. -- Snarky owns product briefs and final product acceptance. -- Opus owns layout/design decisions. -- Opus is the only role that writes code during Opus implementation phases. -- Implementation uses git branches, not worktrees. -- Checkpoints are updated after every completed slice and before stopping work. +The multi-agent flow harness that originally executed this plan is retired; +work proceeds directly in-session, branch-based, with `make test` green at +each step boundary.