lab/distribution
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plan: re-evaluate against current sx (2026-06-11)

Browse Source 
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:
agra
2026-06-11 23:04:10 +03:00
parent 59b77729bb
commit 7176e63503
4 changed files with 61 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.agents/subplans/01-language-and-stdlib.md
View File

@@ -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

200
.agents/subplans/08-orchestration-and-qa.md
View File

@@ -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.

31
.agents/subplans/README.md
View File

@@ -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.

88
PLAN.md
View File

@@ -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.