FFFF feat: v0.11.0 — rename to aloop, first end-to-end live run, gate hardening by adeelahmad · Pull Request #7 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
d8c34e3
docs: project overview, milestone roadmap, CONTRIBUTING; mark design …
claude Oct 17, 2026
507f813
fix: quote ${CLAUDE_PLUGIN_ROOT} in hook commands
claude Oct 17, 2026
120aa94
docs: CLAUDE.md standing goal + autonomy flywheel
claude Oct 17, 2026
c3966b4
feat: v0.11.0 — rename to aloop (Aladdin's Loop), old names kept as a…
claude Oct 17, 2026
5cd6153
test: rename-compat leaves no __pycache__ in plugin/bin
claude Oct 17, 2026
ee7344c
chore: ignore __pycache__; tests run without bytecode
claude Oct 17, 2026
6d5fee3
test: ROADMAP §6 conformance fixtures on today's gates (M1 slice 1)
claude Oct 17, 2026
8c4aef8
fix: schema gates validate the written artifact, not its whole directory
claude Oct 17, 2026
6112d91
test: conformance pins RUSTUP_HOME/CARGO_HOME under the isolated HOME
claude Oct 17, 2026
0846d2f
fix: supervisor-scope blocked nothing on Linux for resumed sprints; a…
claude Oct 17, 2026
484e4cd
fix(security): parse task.env instead of sourcing it
claude Oct 17, 2026
2634127
feat: gates fail closed — a crashed gate blocks instead of allowing (…
claude Oct 17, 2026
b3130a2
fix(security): gates take the worker's role from the host, not task.env
claude Oct 17, 2026
106e246
Move the task contract to the main tree, keyed by TASK_ID (M0.7)
claude Oct 17, 2026
61c9909
Fire role gates for Claude Code's aloop:<role> agent names
claude Oct 17, 2026
ca70dec
Block uncommitted worker output; fix selfcheck role crash
claude Oct 17, 2026
fe0cc61
Never block a worker on the supervisor's own contract slips
claude Oct 17, 2026
fe44070
Copy the contract into Claude Code worktrees so selfcheck finds it
claude Oct 17, 2026
b64aead
RED and SCAFFOLD gates run the matrix's format check
claude Oct 17, 2026
b2fcaff
ROADMAP: record e2e run 4 (11/11, no block loops)
claude Oct 17, 2026
2c37d75
Block sub-agent Bash commands that rewrite the task contract
claude Oct 17, 2026
dd3881e
Gate Claude Code workers in their host worktree, not their last cwd
claude Oct 17, 2026
6781c76
Tell sub-agents not to read the plugin's own source
claude Oct 17, 2026
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
6 changes: 3 additions & 3 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "agentic-agile-marketplace",
"name": "aloop-marketplace",
"owner": { "name": "Adeel Ahmad" },
"description": "Agentic agile planning + autonomous TDD execution for Claude Code, Codex and OpenCode, with deterministic hook gates.",
"plugins": [
{
"name": "agentic-agile",
"name": "aloop",
"source": "./plugin",
"displayName": "Agentic Agile",
"displayName": "Aladdin (aloop)",
"description": "Two-stage planning + two-phase TDD execution with deterministic hook gates, per-task transcripts, and a memory-producing retrospective.",
"author": { "name": "Adeel Ahmad" },
"homepage": "https://github.com/adeelahmad/agentic-agile",
Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CI — the checks `make ci` + `make validate` run, mirrored on every push/PR.
# Documented in README.md ("Continuous integration"). Four independent jobs:
# rust — ctx-symbols + md-db: fmt-check, clippy -D warnings, tests
# rust — ctx-symbols + md-db: fmt-check, clippy -D warnings, tests; §6 conformance fixtures
# shellcheck — lints every gate script (errors fail the build)
# plugin — JSON sanity + eval-suite validation + `claude plugin validate --strict`
# hosts — Codex hooks emulation + OpenCode plugin end-to-end (no network, no tokens)
Expand Down Expand Up @@ -38,6 +38,8 @@ jobs:
run: make clippy
- name: test (ctx-symbols + md-db)
run: make test
- name: conformance fixtures (ROADMAP §6, real gates on a fixture crate)
run: make conformance

shellcheck:
name: shellcheck (gate scripts)
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,4 @@ target/
eval-workspace/
# release bundles built by `make package`
package/
__pycache__/
116 changes: 115 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## Versioning policy

`agentic-agile` versions the **plugin** (`plugin/.claude-plugin/plugin.json`) and the
`aloop` (formerly `agentic-agile`) versions the **plugin** (`plugin/.claude-plugin/plugin.json`) and the
bundled `ctx-symbols` crate together under one SemVer line:

- **MAJOR** — breaking changes to the gate contract (hook events/`agent_type`
Expand All @@ -20,6 +20,120 @@ bundled `ctx-symbols` crate together under one SemVer line:
Keep `plugin.json` `version`, the `ctx-symbols` `Cargo.toml` `version`, and the git
tag in lockstep. Tag releases as `vMAJOR.MINOR.PATCH`.

## [Unreleased]

### Added
- **End-to-end live run (north star).** `make e2e-live YES=1` turns a one-line intent
(a semver parser) into planned, tested, merged code in a real Claude Code session with
the plugin, then checks the artifacts, gate verdicts, merge, tests and cost. First run:
done end to end in 19 min for $1.15 (sonnet supervisor, haiku workers), 22 tests on main;
it found the gate-matcher, selfcheck and copy-merge bugs fixed below.
- **Conformance fixtures (ROADMAP §6, M1 slice 1).** `make conformance` runs the real RED
and GREEN gates on a fixture crate in linked worktrees: 16 checks over §6.3–6.9 (RED that
passes or edits `src/` is rejected, suppressions and out-of-scope diffs are blocked,
shared-tree workers are blocked, an accepted GREEN merges, a hard breach is released as
"not a pass"). Items not covered yet are printed with the reason. Runs in CI's rust job.
§6.2 adds 4 schema checks through the real md-db; task.env tampering adds 6 more (26 in all).

- **Live smoke test (M0).** `make smoke-live YES=1` runs one short real Claude Code
session with the plugin and checks the handoff injection, the supervisor-scope block,
transcripts and the token ledger (~$0.004 on haiku). Not run in CI (needs tokens).

- **Gates fail closed (M0.6).** A gate that crashes (exit other than 0 or 2) now blocks
with "the gate itself failed … failing closed" instead of being a non-blocking hook error
that lets the action through. Covers every sub-agent gate, and `gate-supervisor-scope`
once the repo has a sprint lock. `scripts/test/fail-closed.test.py`.

### Security
- **No role gate ran on Claude Code plugin installs.** Claude Code names a plugin's
sub-agents `aloop:<agent>`, and a plain-name hook matcher is an exact list, so the
`red-worker`, `green-worker`, … SubagentStop/SubagentStart matchers never matched: every
"gate" verdict came from the workers' own optional self-checks. Found by the first live
end-to-end run (all 7 verdicts were self-checks) and confirmed with a probe plugin.
Matchers now list both `<role>` and `aloop:<role>`; `scripts/test/hook-matchers.test.py`
failed before.
- **A worker could pass its own gate by editing `task.env`.** The gate library *sourced*
`.agentic/task.env`, which sits in the worker's worktree: appending `exit 0` passed a
failing GREEN, and `GATE_RUN_MATRIX=0` or `SKIP_HOOKS=1` switched checks off. The file
is now parsed as data and only the contract keys are read (`selfcheck` too). Four new
conformance cases cover it; they failed before the fix. Remaining exposure (a worker
rewriting its contract keys) is ROADMAP M0.7.
- **A worker could relabel its own role.** `AGENT_ROLE` came from `task.env`, so a RED
worker claiming `planner` skipped the worktree-isolation check. Gates now take the role
from the host's hook payload (`agent_type`) and block if `task.env` contradicts it.
2 conformance cases (26 in all) failed before.
- **The task contract is the supervisor's (M0.7).** The playbook told the supervisor to
write `task.env` into the worker's worktree before dispatch, but on Claude Code
`isolation: "worktree"` creates that worktree (`.claude/worktrees/agent-<id>`) at
dispatch (measured with a live probe), so the contract could only be missing or
worker-written. The supervisor now writes `.agentic/state/tasks/<TASK_ID>.env` in the main
tree and puts `TASK_ID: <id>` on the dispatch prompt's first line; gates and the time box
find the contract from that line in the host's transcript. A worktree copy that disagrees
with the contract blocks the gate, and `gate-supervisor-scope` stops sub-agents writing
`.agentic/state/` or `.agentic/task.env`. 4 conformance cases (30 in all) and 4 unit
checks failed before.
- **Workers could rewrite the contract through Bash.** `gate-supervisor-scope` now also
sees a sub-agent's Bash calls and blocks a command that names `.agentic/state/` or
`.agentic/task.env` together with a write (redirect, `tee`, `sed -i`, `cp`, `mv`, …);
reading it stays allowed. 2 checks failed before.

### Fixed
- **A Claude Code worker could get another task's budget.** With no `task.env` in its own
worktree, the time box guessed "the only green-worker worktree" and applied that task's
limits. It now takes the worker's own worktree from its cwd first.
- **A worker's `selfcheck <role>` crashed on good work** (`AGENT_ROLE: unbound variable`)
when the role came only from the argument; selfcheck now exports it. Found by the e2e run.
- **The supervisor merged by copying files out of worktrees.** Workers never committed, so
their branches were empty and the supervisor `cp`'d files into main, past the gate's
diff. RED/SCAFFOLD/GREEN gates now block uncommitted work, the worker prompts say to
commit, and the playbook says to `git merge --no-ff` the worktree branch. Found by the
e2e run.
- **Gates looped on the supervisor's own contract slips.** A comma-separated `SCOPE_GLOBS`
(34 blocks in e2e run 2) or a mistyped `AGENT_ROLE` in the main-tree contract blocked a
worker that cannot edit the contract, so it retried until it gave up. Lists now accept
commas, and the host's role wins over the contract's with a WARN (a contradicting
worktree copy still blocks).
- **A worker's `selfcheck` could not find its task on Claude Code** (`STORY_DIR unset`, once
per role in e2e run 2): the worktree is made at dispatch and has no `task.env`. The time
box's first tool-call hook now copies the supervisor's contract into the worktree (the
dispatch prompt's `TASK_ID` picks it); the gates still compare the copy to the contract.
- **GREEN looped on RED's formatting** (19 blocks in e2e run 3): RED's test file failed
`cargo fmt --check`, and GREEN may not touch tests. RED and SCAFFOLD gates now run the
matrix's format check, so the file is fixed by the role that wrote it.
- **False "isolation dropped" blocks** (27 in e2e run 5): a worker that `cd`s to the main
tree to read its story left the hook's cwd there. Gates now check the worktree Claude
Code made for that agent (`.claude/worktrees/agent-<agent_id>`) first. The Bash contract
guard is per simple command now (run 5 blocked a read-only probe), and RED's
out-of-scope message says how to undo the change.
- **The supervisor could write source mid-sprint on Linux.** `gate-supervisor-scope`'s
"recently refreshed lock" arm called `stat -f %m` first; on Linux that prints a
filesystem report instead of failing, the arithmetic crashed under `set -u`, and a
crashed hook does not block. GNU `stat -c %Y` now goes first and the value is checked.
Found by the live smoke test; `scripts/test/supervisor-scope.test.py` covers it.
- **Valid planner artifacts were blocked by the schema gate.** `gate-validate-artifact`,
`gate-intake` and `gate-memory` ran md-db on the written file's whole directory, and
`gate-stage2-complete` on the whole sprint tree. Those directories also hold the
`init.md`/`output.md` comms (and `stats.md`), which the schema does not know, so every
valid `tasks.md`/`validate.md`/`stories.md` write in a story that had comms was blocked.
They now validate only the written file (stage-2: only the planning artifacts). Found by
the new §6.2 fixture.

## [0.11.0] - 2026-10-17

### Changed
- **Renamed to aloop (Aladdin's Loop).** The plugin is `aloop@aloop-marketplace`, the
skill is `/aloop:aloop` (entry point `/aloop:init`), the CLI is `aloop <tool>` and
`aloop init`, and the OpenCode plugin file is `aloop.js`. Upgrade: uninstall
`agentic-agile@agentic-agile-marketplace`, then install `aloop@aloop-marketplace`
(README → *Upgrading from agentic-agile*).

### Compatibility
- `agentic`, `agentic init`, `agentic-init` and `agentic bind` still work as aliases.
- `aloop install opencode|codex` links both `~/.local/bin/aloop` and `~/.local/bin/agentic`,
and removes the pre-rename generated files (OpenCode would otherwise load both plugins).
- Project data is untouched: `.agentic/`, `docs/agents/`, `agentic/<task>` branches and the
`AGENTIC_*` settings keys keep their names (a migrated layout is planned for M1).

## [0.10.1] - 2026-09-23

### Fixed
Expand Down
17 changes: 17 additions & 0 deletions CLAUDE.md
8 10BC8
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Aloop: standing goal

**What it is.** **aloop** (Aladdin's Loop; formerly agentic-agile, heading for **Aladdin 1.0**) is a plugin for Claude Code, Codex and OpenCode that turns any intent into planned, test-first, gate-verified software. A human approves the plan, cheap workers build it in isolated worktrees, and deterministic hooks decide what is accepted. *Models explore. Gates decide.*

**North star.** A one-line intent becomes merged, tested, auditable code on any host, with no human help beyond approval, at the lowest token cost.

**Done means.** Every milestone's exit criterion is proven by a test or a measured run, CI is green, and `docs/OVERVIEW.md` and `docs/ROADMAP.md` match the code.

**Flywheel (every agent, every turn):**
1. **Orient:** read `docs/OVERVIEW.md`, ROADMAP §0, and open PRs.
2. **Pick** the highest-value unblocked item. Red CI and bugs come first, then the current milestone.
3. **Ship small:** branch, write tests first, open a draft PR, and drive it green.
4. **Measure:** put the evidence (tests, run stats) in the PR.
5. **Re-plan:** update ROADMAP status. Add any gap, risk or idea you found as an item with a one-line reason. Requirements are yours to maintain, not only the user's.
6. **Repeat** without waiting to be asked.

**Judgment.** Decide reversible things yourself and record the call. Ask only about irreversible, security-sensitive or goal-changing choices: one question, with a recommended option. Never weaken a gate, an invariant (ROADMAP §7) or a test to make progress. Prefer evidence to claims. Keep user-facing replies to 1–2 words unless more is needed.
26 changes: 26 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Contributing

Start with [docs/OVERVIEW.md](docs/OVERVIEW.md) (what the project is) and
[docs/ROADMAP.md](docs/ROADMAP.md) (where it is going).

## Before you open a PR

```bash
make hooks # install the tracked pre-commit / pre-push hooks
make ci # what CI runs, except the live `claude plugin validate`
make validate # `claude plugin validate --strict` (needs the claude CLI)
```

## Rules of the road

- **Gates are the product.** A change that weakens a gate, or turns a BLOCK into a WARN,
needs a stated reason and a test showing the old failure is still caught.
- **Edit `plugin/pipeline/` first.** Agent files in `plugin/agents/` are assembled from it.
- **Versions move together.** `plugin.json`, the `ctx-symbols` `Cargo.toml` and
`CHANGELOG.md` must agree (`make version-check`). See the versioning policy in the
[CHANGELOG](CHANGELOG.md).
- **`plugin/tools/md-db/` is vendored AGPL-3.0 code.** Keep changes there minimal and
note them in `plugin/tools/md-db/VENDOR.md`.

By contributing you agree your work is licensed under the repository's MIT license
(AGPL-3.0 for the `md-db` subtree).
27 changes: 27 additions & 0 deletions DEVLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,3 +172,30 @@ Two real defects caught and fixed: (1) gate scripts shipped non-executable; (2)
diff-scope filter counted the plugin's `.agentic/` control dir as worker scope.
Dynamic cargo/md-db/ctx-symbols branches WARN-degrade (no toolchain in the harness);
all structural checks ran for real.

## Rename to aloop (v0.11.0)
Decisions (reversible; recorded per CLAUDE.md):
- User-facing names move now (plugin, marketplace, skill, CLI, OpenCode file, docs); the
ROADMAP had the rebrand last, but the owner asked for it first.
- Old names stay as aliases (`agentic`, `agentic init`, `agentic-init`, `agentic bind`) so
existing prompts, scripts and worker transcripts keep working.
- On-disk layout (`.agentic/`, `docs/agents/`, `agentic/<task>` branches, `AGENTIC_*` keys)
is NOT renamed here: it would change live projects without conformance fixtures to prove
parity. Moved to M1, after those fixtures exist.
- GitHub repo slug stays `adeelahmad/agentic-agile` until the owner renames it (GitHub
redirects the old URL, so docs keep working either way).

## Supervisor-owned task contract (M0.7)
Probe (Claude Code 2.1.x, haiku, ~$0.005): an `isolation: worktree` dispatch creates
`<main>/.claude/worktrees/agent-<agent_id>` on branch `worktree-agent-<agent_id>` at dispatch.
SubagentStart/Stop payloads carry `agent_id`, `agent_type` and `cwd` = that worktree;
SubagentStop adds `agent_transcript_path`, whose first user turn is the dispatch prompt.
So the supervisor could never pre-write `task.env` into the worktree on Claude Code.
Decisions (reversible):
- Contract keyed by TASK_ID (known before dispatch), in the main tree:
`.agentic/state/tasks/<TASK_ID>.env`. The dispatch prompt's first line `TASK_ID: <id>`
links the agent to it through the host-written transcript, not through worker files.
- A worktree `task.env` stays as a fallback (Codex/OpenCode, older sprints); when both
exist, any differing key blocks. Not relying on the undocumented
`subagents/*.meta.json` (it does carry `toolUseId` and `worktreePath`).
- Open: Bash writes into `.agentic/state/` are not guarded yet.
Loading
Loading
0