aloop v0.12.0

The first release of aloop (Aladdin's Loop), the plugin formerly published as agentic-agile.
It carries the 0.11.0 rename (below: Upgrading from agentic-agile) and everything the roadmap
shipped since v0.10.1: the intent contract and the aladdin.event/1 stream with events trace
(a commit on main answers with its task, gates, plan, intent and approver), sprint budget and
admission control, the planning feedback lifecycle, frozen ids, semantic targets, the stuck
release, the impact-provider seam, the portable host core (Claude Code, Codex, OpenCode), run
data under .aladdin/ with a .agentic/ fallback, and seventeen measured live runs of the
north-star loop (make e2e-live), each of which fixed a gate false positive or a dead path.

Upgrading from agentic-agile: uninstall agentic-agile@agentic-agile-marketplace, install
aloop@aloop-marketplace; agentic … commands keep working as aliases and existing .agentic/
project data is read as before (see 0.11.0 → Compatibility, and README → Upgrading).

Changed

• The README is tested (scripts/test/readme.test.py, in make test-hosts): the §4.11 section
  order, every aloop <tool> / aladdin <sub> it names exists, the install lines name this
  repo's plugin and marketplace, every relative link resolves, and every demo time/cost figure
  is one ROADMAP §0 records. Reason: the README was the last §4.11 row without a test.
• Run data moves to .aladdin/ (ROADMAP M1). Fresh projects keep transcripts, budgets,
  the ledger, logs, state, host records and task worktrees under .aladdin/, next to
  config.yaml; .aladdin/.gitignore (written by the plugin) keeps everything but
  config.yaml out of git. A project that already has .agentic/ keeps using it until
  aloop layout migrate moves it (refused while worker worktrees are live); aloop layout show says which dir is live and aloop layout check fails unless the run data is
  git-ignored. Every AGENTIC_<KEY> env var and settings key accepts ALADDIN_<KEY>
  (AGENTIC_ wins when both are set). The gates and budget find the task contract in
  either dir, so a supervisor that writes the old literal path is still understood. The
  worktree-local markers (task.env copy, budget-exceeded, scaffold-symbols) move with
  it: written to the worker worktree's .aladdin/ (guarded), read from .agentic/ too.
  Test: scripts/test/layout.test.py; every suite runs on the new layout.
• Workers append their output.md block before selfcheck (RED/SCAFFOLD/GREEN personas,
  agents and pipeline sources). Reason: the soft-limit line said "run selfcheck, append your
  report", so workers self-checked first and were blocked for a missing report block: 4 of
  run 16's 9 blocks, 3 of run 15's 6.
• The supervisor never commits on main (SKILL.md): every commit on main arrives through
  task-worktree merge. Reason: live run 16's one untraceable commit was the supervisor's own
  Track Cargo.lock; the e2e fixture now commits the lockfile in its seed.
• A wave with one dispatchable task runs in the foreground (SKILL.md orchestrator loop).
  Reason: live run 15 dispatched every single-task wave in the background and woke 16 times,
  each wake re-reading the supervisor's context (5.5M cached tokens, $1.26 of $1.42); run 14,
  foreground, woke twice for $0.75. Background dispatch + budget watch stays the rule for
  parallel waves. The host table's "merge a passed task" row names task-worktree merge.
• The soft token limit is telemetry only (ROADMAP §3.1). Crossing it no longer tells
  the worker to wrap up; budget records task.token_soft_limit once per attempt in
  .agentic/logs/events.jsonl, stats.md counts it, and NEXT.md lists those tasks as
  planner input. The soft time limit still warns.
• No post-kill narration (ROADMAP §3.5). At the hard limit the worker is stopped on
  the crossing call instead of being given a last call to write its report. The harness
  appends the gate-valid status: re-plan block to output.md itself (limits, worktree
  diff, transcript path) and records task.token_hard_limit / task.time_hard_timeout.
  A verdict reached before the worker's worktree is known still gets one call to find it.
• The token meter counts classes separately (ROADMAP §3.2). The budget charge is now
  fresh (uncached) input + output by default. Cache read and cache write are kept as
  their own classes in each attempt's state (usage), and context size is the latest
  call's, never cumulative cache traffic. TOKEN_METER=context in defaults.md (or
  BUDGET_TOKEN_METER=context in a task.env) keeps the previous context + output charge;
  budget resolve / status show the meter in force.
• Budgets cover every model role (ROADMAP §3.3). Intake, standards, planner,
  archivist, structural-reviewer and final-gate are metered against per-role profiles
  (overridable with AGENTIC_BUDGET_<ROLE> in defaults.md). They are observe-only:
  crossings are recorded as events, and the agent is never told or stopped.
• Hard breaches are classified, not always split (ROADMAP §3.4). The hook makes a
  deterministic first call (TASK_TOO_LARGE, AGENT_LOOPING, EXTERNAL_SERVICE,
  TEST_SUITE_SLOW, ENVIRONMENT_SLOW, CONTEXT_PATHOLOGY, HOST_FAILURE, UNKNOWN)
  from usage classes, tool calls and results, with its evidence in the output.md block,
  the event, budget watch and the new budget classify. The planner confirms or
  overrides it (breach: line) and acts per class (SKILL.md "Breach classes").

Added

• log-execution --help, a default ledger (the latest docs/agents/sprintN/execution.log) and
  exit 64 with the usage on a wrong call. Reason: it had no usage, so the supervisor read its
  source twice per live run to learn that the last argument is the file. SKILL.md now gives the
  exact call and says the init-block section list is the whole shape (the supervisor also read
  init.template.md four times per run). make e2e-live counts plugin-source reads precisely
  (tool calls naming a plugin path, --schema …/schemas/… excluded): runs 13–15 were 9, 8, 6.
• task-worktree merge <TASK_ID> <BRANCH> records the §4.7 lineage on Claude Code, where the
  host makes the worktree and the supervisor merges it (so task-worktree remove never runs): a
  --no-ff merge, then worktree.merged + one commit.created per merged commit. SKILL.md tells the
  supervisor to merge with it (a raw git merge left live runs 11–14 with no traceable commits), and
  make e2e-live now checks every merged commit answers events trace.
• Stuck release: a worker that hits the same gate block 3 times in a row (one gate, task,
  attempt and worktree; AGENTIC_STUCK_BLOCKS) is released unverified instead of
  looping until its time box (live run 10 lost 29 minutes to a RED worker that stopped 29
  times on one unchanged reason). The release is not a pass: the gate leaves
  .agentic/state/stuck/<task>.<attempt> with the reason, budget watch prints a STUCK
  line once, and the supervisor re-dispatches with feedback or re-plans. A different reason
  or a new attempt resets the count; a self-check never releases. Every gate verdict now
  logs its worktree and a checksum of the block reason. 7 conformance checks (§6.9).
• Portable project config (ROADMAP §4.9). .aladdin/config.yaml (budgets, context,
  semantic, models, provenance, memory, git, plus per-role budget profiles) replaces
  docs/agents/defaults.md as the human's file. aloop config migrate writes it from the
  current settings; when it exists it is authoritative and defaults.md is rendered from it
  (config sync, run by SessionStart and aloop-init --apply), so the bash gates read the
  same values. config check refuses unknown sections, keys, bad numbers and schema.
• The HostAdapter interface (ROADMAP §4.9). _host.py names, per host, the one place
  the harness does each thing: capabilities, the dispatch vocabulary (spawn / wait / send /
  cancel / subscribe), model and transcript resolution, usage and context pressure,
  compact / rotate, the worktree seam, gate install and enforcement, tool policy. Claude
  Code is the reference; Codex and OpenCode are adapters. aloop host describe prints the
  contract, host check (in make test-hosts) fails if an adapter is incomplete or would
  enforce a gate as a warning. What a host lacks raises Unsupported; nothing is faked.
• Abstract model routes (ROADMAP §3.6). Roles map to strongest | strong | economical
  and each host resolves the route to its own id (plugin/hosts/routes.json; Codex: the
  session's model). AGENTIC_MODEL_PLANNING / AGENTIC_MODEL_WORKER default to
  strongest / strong; a pinned id still passes through. aloop models resolve is what
  the supervisor passes on dispatch and what aloop install renders; --json makes the
  route observable (conformance 18).
• Sprint token envelope and admission control (ROADMAP §4.2). budget admit <task>
  runs before each dispatch. At SPRINT_TOKENS_SOFT it prints one rollover warning, and
  at SPRINT_TOKENS_HARD admission closes (exit 3). Refused tasks are carried over in
  sprintN/rollover.md with the reason, gate-final accepts unticked boxes only for those
  tasks (budget rollover-check), and NEXT.md lists them for the next planning cycle.
  Events: sprint.token_soft_limit, sprint.admission_closed, sprint.rolled_over.
• Planning feedback lifecycle (ROADMAP §4.3). budget envelope <task> prints the
  minimal failure envelope: limit, observed value, breach class, last gate, changed files
  and references, with nothing inlined. NEXT.md gains a "Planner feedback" section that
  applies the grace rule (0–1 failed or hard-breached tasks → no nudge; 2+ → one "plan
  smaller" nudge for the next cycle only) with a calibration verdict derived from the
  breach classes (plan-smaller, `raise-time...

agentic-agile v0.10.1

Fixed

• Time-box defaults were far too tight. 40k/60k tokens killed real RED/GREEN
  attempts (reading the style guide + running fmt/vet/lint/build/test uses 60–190k
  even when the attempt succeeds) before they wrote a line. Defaults are now
  150k / 250k tokens, 20 / 30 min.
• The per-task budget override was never found when a worker addressed its worktree
  with git -C <wt> or absolute paths instead of cd: the hook located the worktree
  from the tool call's cwd (the main repo), so it never read the worktree's
  .agentic/task.env and applied the default for the whole attempt. The hook now finds
  the worktree from a recorded binding, the paths a tool call names (-C, cd,
  --work-tree, absolute paths, file paths, patch headers), the cwd, or — for a first
  call that only reads main-tree files — the one unclaimed worktree whose task.env
  names this role. When the worktree becomes known later, the budget is re-resolved
  without resetting the attempt's clock, and a hard verdict reached under the wrong
  budget is withdrawn.

Added

• budget status shows each attempt's budget source (tasks.md line, task.env,
  defaults.md, built-in) and how its worktree was found; budget resolve --worktree WT
  prints the source too; soft/hard messages name the budget's source.
• Regression test scripts/test/budget-worktree.test.py (in make test-hosts / CI).

agentic-agile v0.10.0

Added

• Tools install themselves and are always on PATH. New SessionStart hook
  bin/ensure-tools builds md-db + ctx-symbols from the bundled source into the
  plugin data dir (background, once per plugin version; --sync to force) and tells the
  model where every tool is. bin/md-db / bin/ctx-symbols are PATH shims (the
  platform puts the plugin's bin/ on PATH for every session and sub-agent) that exec
  the real binary. Agents now call selfcheck, md-db, budget, … by bare name, and
  the prompts tell them never to search. gate-tooling tries to install before blocking.

• Per-attempt time box (tokens + wall clock). New bin/budget: soft limits (default
  40k tokens / 10 min) warn the worker inside its tool results; hard limits (60k / 15
  min) deny further tool calls except the output.md report, release the worker's
  SubagentStop gate unverified, and surface a KILL to the supervisor via budget watch.
  Configurable per project (docs/agents/defaults.md, via init) and per task
  (budget: line in tasks.md).

• Orchestrator loop: dispatch → sleep → sweep. The supervisor dispatches background
  workers, sleeps on budget watch, then TaskStops workers past their hard limit.

• Mid-sprint re-plan route. A task killed at its hard limit is not retried: the
  sprint pauses, the planner is dispatched with mode: replan
  (pipeline/planning/02-planner/replan.template.md) to split it (split_from:),
  leaving done tasks untouched, and the sprint resumes. Capped per task lineage
  (AGENTIC_MAX_REPLANS, default 2; budget replans). New execution.log phases
  budget and replan.

• Self-contained sprints. The planner prompt requires every sprint to be completable
  on its own (context is cleared between sprints); gate-stage2-complete blocks
  references to a later sprint's stories and work deferred into a later sprint. The
  harness asks for /clear at each sprint boundary.

• Init confirms the project setup with the human. /agentic-agile:init runs
  agentic-init --show (limits, models, the .gitignore edit, whether docs/agents/ is
  tracked — default no — and the commit author — default the human's git identity, no
  Claude trailers), asks, then agentic-init --apply writes docs/agents/defaults.md,
  the managed .gitignore lines and the repo-local git author. The hooks read limits
  from that file; the SessionStart hook re-applies the .gitignore lines every session.

• gate-commit-author (PreToolUse · Bash): denies commits with another author,
  identity overrides, or Claude co-author/attribution trailers (unless opted in).

• One fixed layout (bin/_paths.sh / _paths.py): run data lives only in
  <project>/.agentic/{transcripts,budget,ledger,logs,state}; no model-chosen or
  per-worktree path, no task.env override. Capture hooks write nothing in a repo that
  isn't an agentic-agile project.

• Token ledger + sprint stats + handoff, by the harness (bin/stats): Stop and
  SubagentStop rebuild .agentic/ledger/<session>.jsonl from the transcripts (main +
  sub-agents). When FINAL-GATE passes, gate-final runs stats sprint-close:
  sprintN/stats.md (tasks, attempts, gate passes/blocks, budget stops, re-plans,
  tokens per sprint/session/project, by role and model, human messages) and
  docs/agents/NEXT.md (orchestrator handoff). The next Stop shows the human the totals
  and asks for /clear; the SessionStart hook loads NEXT.md into the fresh context.
  stats show prints totals any time. Every gate verdict is logged to
  .agentic/logs/gates.jsonl.

• Codex and OpenCode support — full feature parity. agentic install codex|opencode [--project DIR|--global] [--uninstall] renders the 9 role agents (Codex TOML /
  OpenCode markdown), skills and the init command from this plugin's own sources.

  • Codex loads this repo's .claude-plugin manifests and hooks/hooks.json
    natively (same events, CLAUDE_PLUGIN_ROOT); hooks were made Codex-aware:
    apply_patch edits (supervisor scope, report-only writes at the hard limit),
    rollout token usage (.jsonl/.zst, cumulative totals), sub-agent rollouts found
    by thread id.
  • OpenCode gets a generated plugin (hosts/opencode/agentic-agile.js) that maps
    its hooks onto the same scripts: deny by throwing, context appended to tool output,
    session.abort for the hard stop, the role gate on the task result (a block
    re-prompts the sub-agent up to 3 rounds), usage written Claude-shaped for the ledger,
    the handoff in the system prompt, bin/ on PATH via shell.env.
  • Worker isolation without built-in worktrees: agentic task-worktree add <TASK_ID> + the worker's first command agentic bind <path>; host-adapter then
    confines it (Codex: commands/patches outside the worktree are denied; OpenCode:
    rewritten into it) and the SubagentStop gate runs inside the bound worktree.
  • agentic — one dispatcher for every tool (agentic selfcheck, agentic init …),
    linked into ~/.local/bin where the host has no plugin PATH.
  • _usage.py — one token reader for all three hosts (budget + ledger).
  • CI job hosts: Codex hook-runner emulation (14 checks) + OpenCode plugin against a
    mock client (18 checks) — make test-hosts.

Changed

• The hard-limit kill is deterministic: after one chance to write its report and 3
  refused calls, the time-box hook stops the worker itself (PostToolUse
  continue: false); budget watch reports STOPPED, with TaskStop only a backstop.
• gate-final also checks plan-ready.md in the sprint's main-tree docs (a worker
  worktree has docs/agents/ sparse-checked out).
• The supervisor may not hand-edit defaults.md, NEXT.md or stats.md.
• Models: planning agents (intake, standards, planner, archivist) default to
  claude-opus-5-5; execution agents and the orchestrator skill default to sonnet.
  Per-project override via AGENTIC_MODEL_PLANNING / AGENTIC_MODEL_WORKER in defaults.md.
• Gates detect backends with ensure-tools --resolve (the real binary), not
  command -v (which would now find the shim).

agentic-agile v0.9.0

Added

• bin/worktree-hygiene — new SubagentStart hook (exec roles) that sparse-checks
  docs/agents/ out of a worker's worktree. Workers already reach their story's docs via
  the absolute STORY_DIR path back into the main tree, so the tracked docs/agents/**
  checkout git worktree add puts in every worker worktree was pure, increasingly-stale
  redundancy. Runs regardless of whether the harness's built-in isolation: "worktree" or
  the optional bin/worktree-create made the worktree (the built-in path never calls
  worktree-create, so a fix scoped to that script alone wouldn't have fired for it).
• Same hook (and bin/worktree-create, for parity) bootstraps the main tree's
  .gitignore with .agentic//.transcripts/ the first time a worker runs against it
  — idempotent, mkdir-lock-guarded against concurrent first dispatches, and skipped
  entirely once the entries already exist.

Fixed

• Sparse-checkout now merges its !/docs/agents/ exclusion into any pre-existing
  sparse-checkout pattern file instead of overwriting it, in case a target repo already
  used sparse-checkout for its own reasons.

agentic-agile v0.8.3

Fixed

• Invalid plugin manifest: removed the WorktreeCreate/WorktreeRemove hooks. They
  were added in v0.6.0 based on bad research — newer Claude Code rejects them with
  "Unknown hook event(s)" (they are not valid plugin-manifest events; they only ever
  belonged in user settings.json). The plugin now relies on the harness's built-in
  isolation: "worktree" for git repos (the nesting symptom was in the custom hook, so
  this also removes that failure mode). bin/worktree-create/worktree-remove are kept
  as an optional user-settings.json mechanism for a non-git VCS, documented as such.
  assert_worktree_isolation still enforces a real linked worktree regardless of source.

Added

• make package — bundles the release (.claude-plugin + plugin + README +
  CHANGELOG + LICENSE) into package/agentic-agile-vX.Y.Z.tar.gz (+ SHA-256) and
  publishes it as the GitHub release for the current tag (via gh, --latest, notes
  from the matching CHANGELOG section). package/ is git-ignored.