8000 M12.1–M12.6: kernel and user space — eject, layers, upgrades, kernel protection by adeelahmad · Pull Request #124 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ test-hosts: ## Budget/worktree regression + Codex hooks emulation + OpenCode and
plugin/bin/host check
python3 scripts/test/targets-scope.test.py
python3 scripts/test/task-scope.test.py
python3 scripts/test/userspace.test.py
python3 scripts/test/plan-render.test.py
python3 scripts/test/persona-shapes.test.py
python3 scripts/check-tracking.py
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@ structural, not luck:
blocking it from doing the context-heavy work itself.

Live runs: `make smoke-live YES=1` (hook wiring, ~$0.004) and `make e2e-live YES=1` (the whole
loop, ~$1; each run writes `summary.json` and a row for [docs/evidence/](docs/evidence/README.md)). Offline: `make ci`, which runs Rust fmt/clippy/tests, shellcheck, 59 Python/Node suites plus every `mission-*.test.py`,
loop, ~$1; each run writes `summary.json` and a row for [docs/evidence/](docs/evidence/README.md)). Offline: `make ci`, which runs Rust fmt/clippy/tests, shellcheck, 60 Python/Node suites plus every `mission-*.test.py`,
the gate conformance fixtures (`make conformance`) and eval-suite validation. Every ROADMAP
requirement is tracked with its test in [docs/TRACKING.md](docs/TRACKING.md).

Expand Down
2 changes: 2 additions & 0 deletions docs/OVERVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ The model can ignore a skill; it cannot ignore an exit code.
| `ctx-symbols` | [`plugin/tools/ctx-symbols/`](../plugin/tools/ctx-symbols/) | Rust, tree-sitter symbol resolver (Rust, Python, JS/TS, Go): count, locate, conflicts |
| `md-db` | [`plugin/tools/md-db/`](../plugin/tools/md-db/) | Vendored Rust markdown-as-database validator (AGPL-3.0 subtree) |
| Other hosts | [`plugin/hosts/opencode/`](../plugin/hosts/opencode/), [`plugin/hosts/dsh/`](../plugin/hosts/dsh/), `bin/install` | Generates agents/skills for Codex and OpenCode, and the `aloop` profile (role presets, delegation tools, the native plugin) for DeepSeek Harness; same gates via `host-adapter` |
| User space | [`plugin/bin/userspace`](../plugin/bin/userspace), [`_userspace.py`](../plugin/bin/_userspace.py) | The loop's opinions (roles, prompts, skills) ejected into the project's git on the first run and changed freely; home > repo > plugin; upgrades never overwrite an edit; the kernel (gates, hooks, audit log) is never overridden (M12, ROADMAP §4.15) |
| Evals | [`plugin/evals/`](../plugin/evals/), [`scripts/eval/`](../scripts/eval/) | Per-agent eval suites + grader/aggregator |

## What 8000 it leaves on disk
Expand All @@ -93,6 +94,7 @@ The model can ignore a skill; it cannot ignore an exit code.
|---|---|---|
| `.aladdin/config.yaml` | project | The portable config (budgets, context, semantic, models, provenance, git); authoritative when present (`aloop config migrate`) |
| `docs/agents/defaults.md` | project | Limits, models, author — set at init, or rendered from `.aladdin/config.yaml` |
| `docs/agents/userspace/` | project, **in git** | The loop's user space: `agents/`, `skills/`, a `reference/` copy of the kernel (read-only in effect), `.base/` + `manifest.json` for upgrades. A personal layer above it: `~/.aloop/projects/<name>-<hash>/` |
| `docs/agents/memory.md` | project | Lessons promoted by the retrospective; injected into contracts |
| `stories.md`, `sprintN/plan.md` | sprint | Stage-1 contract |
| `sN-NN-<slug>/targets.json` | story | The semantic plan: tasks, tests, change targets (shadow workspace) |
Expand Down
32 changes: 32 additions & 0 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ original plan.
| **M9 — Mission layer** | v0.13 | The "Missionary Aladdin Genie" spec (2026-10-17): a human-set mission above goals; fixed roles (research, product testing, state, evaluation, planning, ethics) build a confirmed baseline and a reproducible evaluation layer from user journeys; goals derived from the gap list become Aladdin intents; re-evaluate on a cadence and after each sprint; GA4 usage informs goals and is never a gate; every element has a deterministic check (§4.12). Reason: the owner's mission-driven loop, stacked on Aladdin | in progress: M9.0 core (`aloop mission init / check / approve / status`, sealed mission + approval events, area discovery, test glob; test: `mission-core.test.py`); M9.2 baseline, M9.3 journeys and M9.10 assess/evaluate (`mission-{baseline,journeys,evaluate}.test.py`). Open tracks: M9.1, M9.4–M9.9; the task graph is in §4.12, track notes in `plugin/mission/README.md`; hardened after an adversarial review (ledger records over status fields) |
| **M10 — Agent habitat** | v1.1 | Containment around the gates (§4.13): contained workers, a security and supply-chain gate, fetched content treated as data, one stop for a whole project. Reason: a 2026-10-20 comparison with Replit's "agent habitat" (orchestration, error recovery, safety and sandboxing, networking, identity) found aloop strong on orchestration, recovery and gates but missing containment | in progress: M10.2 dependency and secret halves done: GREEN refuses a dependency added to a manifest (Cargo.toml, package.json, requirements*.txt, pyproject.toml, go.mod) that the approved plan does not name (`bin/deps`), and a credential (private key, fixed-prefix token) in the lines it adds; `gate-final` refuses one anywhere in the project (`bin/secrets`, built in rather than a matrix line so it runs on every stack with no install; test: `supply-chain.test.py`); live run 51: no refusal, 13/13, $0.94). M10.2b dependency audit done (the human chose "Required", 2026-10-21): `gate-final` runs `bin/audit`, which runs the stack's own tool for each manifest that declares a dependency (`cargo audit`, `npm audit --audit-level=high`, `pip-audit`, `govulncheck`) and blocks on a finding and on a tool that is not installed, naming the install command; built in rather than a matrix line so it needs no standards role and runs on every stack (test: `dependency-audit.test.py`, tools stubbed). Open: a host that lacks the tool blocks every sprint with dependencies until it is installed (the run's cost to measure), and an advisory the human accepts is waived only in the tool's own ignore list; M10.4 done: `aloop stop [REASON]` stops every agent of the project at its next tool call on every host (the check sits in `budget hook pre`), `mission tick` answers STOPPED, and only the human's own terminal clears it (`stop --clear`; events `run.stopped`/`run.resumed`; test: `project-stop.test.py`). `--clear` refuses the agent shells of all four hosts (`CLAUDECODE`, `DSH_SHELL`, `CODEX_THREAD_ID`, and `ALOOP_AGENT_SHELL` once M9.31 makes the OpenCode plugin export it). With a mission ledger the stop and its clear are ledger rows too (`run.stopped`, `run.resumed`), so a fresh clone stays stopped (hooks and `tick`) until the human clears it there (`project-stop.test.py` check 8); M10.3 first part done: the market-researcher (roles.json `"web": "archive"`) reads a page only as the snapshot `mission research archive` records: `budget hook pre` refuses its WebFetch (`webfetch` on OpenCode) and a Bash fetcher (curl, wget, httpie, a text browser; through wrappers, `bash -c` and `$(…)`, read by the door gate's shell reader, failing closed), the three web personas say fetched text is data, and its eval suite has an injected-page case (test: `fetched-data.test.py`). Next (M10.3b): the ethics-reviewer and product-tester still WebFetch (they cannot write research/, so the archive needs a shared snapshot store first), and a fetch from an interpreter (`python - 8000 c urllib`) is not refused yet; M10.1 is BLOCKED_HOST (2026-11-19): containment cannot be proven where there is no sandbox runtime. This container has no `bwrap` or `socat` (`which bwrap socat` is empty), so Claude Code's sandbox cannot start here; the owner's Mac (Seatbelt) or a Linux host with `apt install bubblewrap socat` can. Design call to settle first: workers with the network off cannot fetch a crate, so SCAFFOLD (after `deps` has checked that the plan names it) prefetches the plan's dependencies and RED and GREEN run offline; plan approval as a gate is M0.9 |
| **M11 — Autonomous by default** | v0.14 | The human gives the intent (and any specifics) once; everything after it runs with no approval, question or restart from them. The typed intent is the grant (the same captured-prompt proof M0.9 uses), deterministic gates plus a plan judge replace plan sign-off, and every remaining human decision (one-way doors, the spend cap) parks only its own item while the rest keeps running (§4.14). Reason: 2026-11-19 audit, the owner's top complaint: today a run stops for the human at init, at intake questions, at plan approval, at every sprint boundary and on most mission stalls | in progress: M11.1, M11.2, M11.4 done (autonomous default; the typed intent is the grant; a recommended two-way ask is taken; tests: `plan-approval.test.py`, `intent-contract.test.py`); M11.10 door-classifier and M11.11 consented override done (`mission-door-plan.test.py`, `mission-doors-reclassify.test.py`); M11.6 init asks nothing by default (skill text, untested until a live run). Call: an untagged task is two-way at dispatch (the door gate is the backstop), so older plans and fixtures keep running; the classifier's stop gate is what requires every tag. M11.9 first measurement: live run 54 (slugify), the prompt carried only the intent, the recorded grant was the typed intent (no approval line), the door-classifier tagged the one task, 12/12, 7m26s, $0.82 (docs/evidence). Next: M11.5 sprint chaining (the two-sprint half of M11.9), M11.3 plan judge, M11.7, M11.8 |
| **M12 — Kernel and user space** | v0.15 | aloop as an operating system for agent work. The **kernel** (the gate engine and gates, the audit log, the rule that what a project declares runs and is logged) stays in the plugin and is never overridden. **User space** (the agents, prompts, skills, checks, models and workflow: TDD is one opinion, the default `software` profile) is ejected into the project's git on its first run and changed freely; a personal home layer sits above it (home > repo > plugin), and every run logs the copy it used. **Kernel extensions** (`~/.aloop/kernel/`, hash-pinned, add-only) add gate types such as a fact check or a brand-voice check, never remove one; a **domain pack** is an extension plus a profile, so the loop can serve marketing or writing, not only code. The kernel stays host-neutral so it can later run as its own harness (§4.15). Reason: the owner, 2026-11-20: "a user can customize the hell out of a loop", "TDD is one opinion" | in progress: M12.1–M12.6 (eject, layers, upgrade, kernel protection; test: `userspace.test.py`, 48 checks). Next: M12.7 kernel extensions, M12.8 profiles |

**Order rationale:** identity and conformance fixtures first, so every later change is
measured against today's behaviour; budgets and handoff next, because they shape every run;
Expand Down Expand Up @@ -591,6 +592,36 @@ Kept human on purpose (security or the human's own limits; they stop only their
authorizations, spend past the cap, a hard ethics line, `aloop stop --clear`, and changing the intent.
Removing any of these from the human needs the owner's explicit call.

### 4.15 Kernel and user space (M12)

Asked by the owner on 2026-11-20: copy the plugin's agents, hooks and other parts into the project on the
first run "so a user can customize the hell out of a loop"; keep it in git "so you could evolve the harness
itself as the project progresses, but you could go back as well"; gates and the other important parts "live
outside"; and kernel extensions, so a project that is not software (marketing, writing) gets checks that suit
it. The model is an operating system:

| Layer | Where | Who changes it | Can it weaken a gate? |
|---|---|---|---|
| Kernel | the plugin: `bin/gate-*`, `hooks/hooks.json`, the event log, `_userspace` itself | a plugin release | — |
| Kernel extensions (M12.7) | `~/.aloop/kernel/<name>/`, pinned by sha256 in the project's user space | the human | no: add-only, run after the core gate, a failure blocks, a pass never overrides a core block |
| User space, home | `~/.aloop/projects/<name>-<hash>/` (personal; CI and teammates never see it) | the human | no |
| User space, repo | `docs/agents/userspace/` (in git) | the human, between runs | no |
| Plugin defaults | `plugin/agents`, `plugin/skills` | a plugin release | — |

| # | Item | Status |
|---|---|---|
| M12.1 | Eject on the first run: `aloop userspace eject` (run by the first session's SessionStart and by `aloop init --apply`) copies the 16 roles, the skills and a kernel reference (`reference/`: the pipeline sources, `hooks.json`, every gate) into `docs/agents/userspace/`, never overwriting; `AGENTIC_NO_EJECT=1` opts out; a repo with no `docs/agents/` gets nothing | ✅ `userspace.test.py` |
| M12.2 | Layers and the log: home > repo > plugin per file (`aloop userspace which`); `apply` renders each customized role as `.claude/agents/<role>.md` (name forced to the kernel's role, a marker makes it ours to replace or remove, a file we did not write is left alone) and logs `userspace.applied` with each file's layer and sha256 (gate-owned: `events emit` refuses it); `aloop install codex\|opencode\|dsh` renders the winning copies; a customized skill is named to the session as superseding the plugin's | ✅ `userspace.test.py`. Call: on Claude Code a skill override is advisory (the plugin's skill still loads; the session is told to follow the project's copy): M12.9 |
| M12.3 | Upgrades never clobber an edit: `.base/` holds the plugin text each file was synced from; untouched files follow a release, new files are ejected, an edited file the release changed is kept with `<rel>.plugin-new` beside it and named to the session; `diff`, `merge` (three-way, `git merge-file`; a conflict writes `<rel>.merge` and leaves the copy), `accept`, `reset` | ✅ `userspace.test.py` |
| M12.4 | User space cannot weaken the kernel: a `reference/` edit changes nothing (the hooks run only the plugin's gates); an agent file for a role name the kernel has no gates for is never loaded (the hooks match role names); `gate-dispatch` refuses `aloop:<role>` for a customized role, so the customization is not silently skipped | ✅ `userspace.test.py` |
| M12.5 | Nobody inside a run rewrites the loop: a dispatched agent never writes user space or `~/.aloop` (`gate-supervisor-scope`), the supervisor not while a sprint is live, a worker's diff that touches it is blocked by `targets diffscope` (it is no longer hidden as run data) and `task-worktree merge` never merges a branch that touches it | ✅ `userspace.test.py`. Gap: a Bash write is judged only by the diff and merge checks, not at the call (with M11.13) |
| M12.6 | User space is in git: the managed `.gitignore` is `docs/agents/*` + `!docs/agents/userspace/` (a project's pre-M12 `docs/agents/` line under the managed header is rewritten in place) | ✅ `userspace.test.py` |
| M12.7 | Kernel extensions: `~/.aloop/kernel/<name>/` with a manifest (the gate events it hooks, its command), enabled by the project's user space naming it with its sha256 (a changed extension is refused until re-pinned); run by the kernel after the core gate on the same event; exit 2 blocks with its reason, exit 0 never overrides a core block; every run logged. Reason: checks that suit non-software work (fact check, brand voice) without forking the kernel | next |
| M12.8 | Profiles and domain packs: `docs/agents/userspace/profile` names the opinion set (`software` = today's TDD loop, the default); a domain pack = kernel extensions + a profile. Ship the interface and the software pack only | next |
| M12.9 | A customized skill is loaded, not only named, on Claude Code (today the plugin skill loads and the session is told the project's copy supersedes it). Reason: a soft override is weaker than the agent render | open |
| M12.10 | A planner-proposed user-space change: the planner may propose an opinion change as a one-way door for the human (today only the human edits user space, between runs) | open |
| M12.11 | Host-neutral kernel: the gate engine callable without any host (`aloop kernel run <event>`), so aloop can later be its own harness. Reason: the owner wants Claude Code to be one host, not the base | open |

## 5. Delivery sessions

Each session starts from accepted git state and its own contract, ends with accepted commits plus a handoff, and rotates context.
Expand Down Expand Up @@ -663,6 +694,7 @@ New with this roadmap:
- Execution starts only on the human's own word: no execution role of a sprint is dispatched before the human approved that sprint's plan as it is now (their typed `approve SN <code>`), or granted that sprint autonomy (their typed `autonomous SN <code>`, an approved autonomous mission for its own sprints, or, by default, their typed intent the sprint was planned from, M11.2), and only on that plan's own stories and tasks (M0.9).
- A one-way door is crossed only under the human's recorded authorization, and a wall never; a two-way door is decided, not asked (M9.30).
- The human is asked only for a one-way door, the cap or a changed intent, and that question stops only its own item (M11).
- User space never weakens the kernel: a gate runs from the plugin whatever the project copies, a role the kernel has no gates for is never loaded, and nothing inside a run rewrites the loop (M12).

## 8. Tracking

Expand Down
8 changes: 8 additions & 0 deletions docs/TRACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,3 +120,11 @@ Status of every requirement in [ROADMAP.md](ROADMAP.md), in the four states §8
| M11.10 | A door-classifier tags every planned task one-way or two-way before execution; only one-way tasks wait, asked together | IMPLEMENTED_TESTED | `scripts/test/mission-door-plan.test.py` |
| M11.11 | A door is made two-way only by an env var plus the human's typed consent | IMPLEMENTED_TESTED | `scripts/test/mission-doors-reclassify.test.py` |
| M11.12 | A task's diff stays in its planned fileset; a worker steps out only by a declared, reasoned two-way exemption the gate decides and records | IMPLEMENTED_TESTED | `scripts/test/task-scope.test.py` |
| M12.1 | The first run ejects the loop's user space (roles, skills, kernel reference) into docs/agents/userspace/ | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.2 | home > repo > plugin per file; customized roles rendered for every host; each run logs the copy used | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.3 | A plugin upgrade never overwrites an edit: three-way diff/merge/accept/reset | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.4 | User space cannot replace a gate or add an ungated role; dispatch uses the customized copy | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.5 | No agent, worker or live-sprint supervisor rewrites user space | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.6 | User space is tracked in git; run docs stay ignored | IMPLEMENTED_TESTED | `scripts/test/userspace.test.py` |
| M12.7 | Kernel extensions: hash-pinned, add-only gate checks from ~/.aloop/kernel/ | NOT_IMPLEMENTED | §4.15 |
| M12.8 | Profiles and domain packs (software = the default TDD profile) | NOT_IMPLEMENTED | §4.15 |
Loading
Loading
0