8000 M12.7, M12.8: modules and distros — build your own, plug into the kernel by adeelahmad · Pull Request #127 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content

Uh oh!

There was an error while loading. Please reload this page.

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
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,21 @@ tag in lockstep. Tag releases as `vMAJOR.MINOR.PATCH`.
## [Unreleased]

### Added

- **Kernel and user space (M12).** The loop's opinions (16 roles, skills, a kernel reference) are
ejected into `docs/agents/userspace/` (tracked in git) on the first session or `aloop init --apply`,
and changed freely. `aloop userspace` (`status`, `which`, `upgrade`, `diff`, `merge`, `accept`,
`reset`, `apply`): home (`~/.aloop/projects/<name>-<hash>/`) > repo > plugin, every run logs the copy
used (`userspace.applied`), and plugin upgrades never overwrite an edit (three-way merge). The kernel
(gates, hooks, audit log) is never overridden: reference copies change nothing, a role name with no
gates is never loaded, and no agent, worker or live-sprint supervisor writes user space.
- **Modules and distros (M12.7, M12.8).** The host harness is the hardware, aloop is the kernel, and
modules plug into it: `~/.aloop/modules/<name>/` adds checks (a fact check, a brand-voice check) on
SubagentStop and Stop once a project adds it (`aloop module add` pins its sha256 in
`docs/agents/userspace/distro.json`). Modules run beside the core gates; a changed, missing, crashing
or timed-out module blocks, and every run is logged (`module.run`). A distro bundles a domain's
modules, roles and skills (`software`, the TDD loop, is the default). Build and share your own:
`aloop module new`, `aloop distro new|check|install|use`; how-to in `docs/BUILD-A-MODULE.md`.
- A task's diff stays in its planned fileset, with worker-declared exemptions (ROADMAP M11.12): `targets diffscope` (GREEN and RED stop gates) judges the diff against the task's targets' paths and planned tests, literally. A new test file passes; an existing test outside the plan may only gain lines (GREEN and RED can no longer weaken or delete another task's test). A production file the plan missed passes only as a `### Scope exemptions` line (`- <path>: <reason>`) in the worker's output.md block: a literal path, a reason of 4+ words, at most 3 (`ALOOP_SCOPE_EXEMPT_MAX`), never a one-way path (CI, VCS config, agent settings, secrets, migrations, licences, run data); each one taken is a `scope.exempted` ledger row, with no human step. The contract's SCOPE_GLOBS can only narrow the plan, a task with no targets gets no free scope, `targets check` refuses a glob path, a production file under a nested `target/` (no Cargo.toml beside it) is judged, and non-ASCII paths are read unquoted. Test: `scripts/test/task-scope.test.py`.
- Plan approval is a gate (ROADMAP M0.9): `gate-dispatch` starts no execution role (RED, SCAFFOLD, GREEN, structural review, final gate) of a sprint until the human approved that sprint's plan as it is now. `events authority --sprint N` exits 3 with the line to type, `approve SN <code>` (reviewed, the code naming the sha256 of the sprint's plan files, its intake and standards included) or `autonomous SN <code>` (autonomy for that sprint, re-plans included, the code naming the authority record); the task contract's `STORY_DIR` and task must be a live story and task of that plan's frozen `ids.json`; the line must be among the human's captured prompts and typed after the sprint's last decision (M9.17's mechanism). A changed plan, a re-plan in reviewed mode, a roll-back to an old line, another sprint's line, a negated line and a hand-edited or emitted record all block (`plan.approved` and `human.approval` cannot be `events emit`ted); an approved autonomous mission grants its own sprints autonomy with no line. `events approval SPRINT|TASK_ID` is the check. Codex's `spawn_agent` (`agent_type`, `message`) and OpenCode's `task` now reach `gate-dispatch` too, and `claude -p`, `codex exec` and `opencode run` from a tool call are blocked in every aloop project, not only where a mission is set. `e2e-live.sh` pre-approves with an `autonomous S1 <code>` line in its prompt. Reason: the north star allows no human help beyond approval, and the approval was a playbook rule a supervisor could skip. A 4-lens adversarial review found 9 defects: 7 fixed with a check red on the first head (cross-sprint or unplanned `STORY_DIR`, a retyped line kept stale, mission autonomy over a non-mission sprint, `transcripts prune` dropping the prompts grants cite, `codex plugin add` refused, a code past column 200, a crash on a malformed run-log line), 2 in the playbook (intake reuses a mission's handed-off intent; a reviewed re-plan waits for the human's new line). `transcripts prune` now keeps the human's prompts. Test: `plan-approval.test.py` (20 checks, red on master), plus the host suites. The approved plan's files include the sprint's `intake.md` and `standards.md`, and a grant pins them file by file: GREEN's check for an unplanned dependency reads only the text the human's grant pins, the plan they approved or, under their autonomy grant, the plan as the planner's gate last passed it (`gate-stage2-complete` records `plan.gated` on the planner's stop), as it was then, so text added later names nothing and a re-plan does not undo an approved dependency.
- Core agent principles and the one-way / two-way door rule (ROADMAP §4.12, M9.30): seven core principles from Amazon's Leadership Principles, the door rule first, go to every aloop agent at session start (`aloop mission principles show --core`). A two-way door (a branch, a local edit, a test, a draft PR) is decided, not asked. A one-way door (`aloop mission doors list`: a push or merge to the default branch, a force-push, a release, a deploy, a message sent outside, a secret, dropped data, …) is stopped by a PreToolUse gate with `ASK[door] <id>` until the human records an authorization in their own terminal (`aloop mission doors authorize ID --by NAME --reason TEXT [--until DATE] [--once DIGEST]`, a hash-chained ledger row); a wall (switching a gate off, forging a human record) is never crossed. While a run is live, a question to the human must name a door the gate stopped and nobody authorized. Reason: Adeel's request that agents decide two-way doors themselves and ask only at a one-way door not already authorized. Test: `mission-doors.test.py`. Hardened by an adversarial review (15 findings, each a test): the gate reads Bash as the shell does (comments, line continuations, heredoc bodies, `xargs`, `find -exec`, `echo … | sh`), a branch condition reads the directory the command acts on (`git -C`, `cd`), settings are guarded wherever they live, dry runs and `command -v` are two-way, the newest decision by time counts and a revoke holds on every branch, a once-grant is crossed once under a lock, a broken ledger is named, and `doors authorize` refuses an agent's shell.
Expand Down
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ test-hosts: ## Budget/worktree regression + Codex hooks emulation + OpenCode and
python3 scripts/test/targets-scope.test.py
python3 scripts/test/task-scope.test.py
python3 scripts/test/userspace.test.py
python3 scripts/test/modules.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, 60 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, 61 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
125 changes: 125 additions & 0 deletions docs/BUILD-A-MODULE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# Build your own module

*Your host harness (Claude Code, Codex, OpenCode, dsh) is the hardware. aloop is the kernel. **Modules**
plug into the kernel, and a **distro** is a full user-space bundle for one domain. aloop ships one
distro, `software`, which is the test-first loop. This page shows how to use existing modules, build
your own, and bundle them into a distro for your kind of work, such as marketing, writing, research or ops.*

> *Models explore. Gates decide.* A module decides what "done" means for your work, and the kernel
> makes sure that decision is enforced.

## The model

| Layer | What it holds | Who changes it | Where |
|---|---|---|---|
| **Hardware** | The host harness that runs the models and tools | its vendor | Claude Code, Codex, OpenCode, dsh |
| **Kernel** | The gate engine, the core gates (scope, door, plan, final), the audit log, and the rule that whatever a project declares actually runs and is logged | aloop releases only | the plugin |
| **Modules** | Your own checks, added next to the core gates | you, or anyone you take one from | `~/.aloop/modules/<name>/` |
| **User space** | The loop's opinions: roles, prompts and skills, plus `distro.json` | you, between runs | `docs/agents/userspace/` (in git), with an optional personal copy in `~/.aloop/projects/` |
| **Distro** | A shareable bundle for a domain: modules, roles and skills | anyone | any folder or git repo |

A module can **add** checks. A distro can add modules and **re-shape** roles. Neither can remove or
weaken a core gate, and neither can add a role that runs without gates. Those limits are what make
them safe to share.

## 1. Build a module

aloop module new no-banned-words --on SubagentStop:green-worker --on Stop

This creates `~/.aloop/modules/no-banned-words/` with three files:

module.json when it runs, and what it runs
check the check: a commented example that works as written
README.md

`module.json`:

```json
{
"name": "no-banned-words",
"description": "refuses copy with banned words",
"on": ["SubagentStop:green-worker", "Stop"],
"command": "./check",
"timeout": 120
}
```

`on` names the events the module runs on:

- `SubagentStop` runs after any role finishes.
- `SubagentStop:<role>` runs after one role finishes, for example `green-worker` or `planner`.
- `Stop` runs when the session tries to stop.

`check` is any executable. It runs from the project root, gets the hook payload on stdin, and has
these variables set: `ALOOP_EVENT`, `ALOOP_ROLE`, `ALOOP_PROJECT`, `ALOOP_DISTRO` and `ALOOP_MODULE`.

- **Exit 0** passes.
- **Exit 2** blocks. Whatever the check writes to stderr is handed back to the agent as the reason.
- **Any other exit, a crash or a timeout** also blocks. A check the project declared always runs, or
the run stops.

```bash
#!/usr/bin/env bash
cd "$ALOOP_PROJECT" || exit 2
if git diff --name-only HEAD -- 'copy/*.md' | xargs -r grep -l -i 'synergy'; then
echo "no-banned-words: copy says 'synergy' (banned word list: docs/brand.md)" >&2
exit 2
fi
```

Ideas for modules: fact-checking against cited sources, brand voice, reading level, broken links,
legal disclaimers, image alt text, word counts per channel, a license header, a performance budget.

## 2. Add it to a project

aloop module add no-banned-words
aloop module list # added / CHANGED since added / missing

`add` pins the module's sha256 in `docs/agents/userspace/distro.json`, which you commit. If you change
the module later, the kernel refuses to run it until you look at the change and run `add` again.
Every run is written to the audit log as a `module.run` event, with the module's sha and its verdict.

## 3. Bundle a distro (optional)

When a domain needs several modules and re-shaped roles, bundle them:

aloop distro new marketing --dir ~/distros

This creates:

marketing/
distro.json {"name": "marketing", "description": "..."}
modules/marketing-check/ a working example module
userspace/ optional roles and skills
README.md

To re-shape a role, copy it from a project's `docs/agents/userspace/agents/<role>.md` into the
distro's `userspace/agents/<role>.md` and rewrite it. For example, the planner can plan campaigns
instead of code, and the green worker can write copy instead of functions. The role's name stays the
same, so its gates stay the same.

aloop distro check ~/distros/marketing # validate without installing
cd my-project
aloop distro install ~/distros/marketing # copies and adds its modules, copies its roles,
# makes it the project's distro
aloop distro # marketing, and the modules it runs

`install` keeps any role you have already customized (`--force` replaces it), and it refuses to
overwrite an installed module that differs from the distro's copy (`--force` replaces that too).

## 4. Share it

Modules and distros are just folders, so you can publish them as git repos. Other people clone one and
run `aloop distro install <dir>`, or copy a module into `~/.aloop/modules/` and run `aloop module add`.
Their own customizations are never overwritten, and nothing in a module or a distro can switch off a
core gate.

## Reference

aloop module new <name> [--on EVENT]... | aloop module add|remove <name> | aloop module list
aloop distro | aloop distro use <name> | aloop distro new <name> [--dir D]
aloop distro check <dir> | aloop distro install <dir> [--force]
aloop userspace status|diff|merge|accept|reset <rel>

Design and status: [ROADMAP §4.15](ROADMAP.md) (M12). Tests: `scripts/test/modules.test.py`,
`scripts/test/userspace.test.py`.
1 change: 1 addition & 0 deletions docs/OVERVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ The model can ignore a skill; it cannot ignore an exit code.
| `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) |
| Modules and distros | [`plugin/bin/module`](../plugin/bin/module), [`plugin/bin/distro`](../plugin/bin/distro), [`_kernel.py`](../plugin/bin/_kernel.py) | The host harness is the hardware and aloop the kernel; **modules** (`~/.aloop/modules/<name>/`) plug in add-only checks (a fact check, a brand-voice check) once the project adds them to `docs/agents/userspace/distro.json`, and never replace a gate (M12.7). A **distro** bundles a domain's modules, roles and skills (`software` is the default); anyone builds both ([Build your own module](BUILD-A-MODULE.md)) |
| Evals | [`plugin/evals/`](../plugin/evals/), [`scripts/eval/`](../scripts/eval/) | Per-agent eval suites + grader/aggregator |

## What it leaves on disk
Expand Down
Loading
Loading
0