@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

package/packages/agent-skills/assets/ralplan/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ralplan
+description: Consensus planning stage for Planner -> Architect -> Critic handoff to $ultragoal
+---
+
+# Ralplan (Consensus Planning Alias)
+
+Ralplan is the canonical consensus-planning stage used by Autopilot between `$deep-interview` and `$ultragoal`. It drives Planner, Architect, and Critic planning and records their review lifecycle with **RALPLAN-DR structured deliberation** (short mode by default, deliberate mode for high-risk work). Local lifecycle evidence is not host-issued security authority, but ordinary progression to Ultragoal must remain reachable after the execution-ready plan and sequential review evidence are durable; missing host provenance must not terminalize Ralplan or block cancel, clear, or recovery.
+
+## Usage
+
+```
+$ralplan "task description"
+```
+
+Standalone advisory planning is explicitly opt-in:
+
+```text
+$ralplan --advisory "task description"
+```
+
+Advisory runs the same sequential Planner → Architect → Critic review lifecycle, binds the plan and both review artifacts to exact bytes and one tracker-backed iteration, then returns to the caller with `active:false`. It is a cooperative workflow pause, not a security fence or permission system. It never emits a `PreToolUse` allow/block decision, never completes the host consensus gate, never authorizes execution, and never suppresses unrelated host behavior. Terminal state must carry explicit `false` values for the consensus gate, host verification, and execution handoff rather than omitting them. A later concrete affirmative execution request may produce non-authoritative routing context, but it does not persist a permission, rewrite terminal evidence, or create an automatic handoff; quotations, code, examples, documentation, questions, modal requests, negations, and vague approval remain classifier negatives. `approved+proven` requires complete lifecycle digests plus post-write revalidation. Administrative abandonment is append-only, idempotent for prepared or committed journals, and records a separate byte-bound admin event without rewriting the original closeout journal. Real enforcement requires an explicit host-issued, host-verified receipt or capability on a non-user-mintable surface; local Advisory files, prompts, session/thread fields, tracker records, and HERDR observability cannot substitute for it. On Darwin, each Advisory evidence artifact is limited to 128 KiB by the pinned-directory reader; other supported platforms allow up to 8 MiB.
+
+## Flags
+
+- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — and outputs the final plan without asking for confirmation.
+- `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
+- `--advisory`: Standalone only. It cannot be combined with Autopilot, Team, Ultragoal, execution flags, or unknown flags. Activation requires canonical session, root thread, and turn identity.
+
+## Ontology-heavy review
+
+For requirements semantics, taxonomy, prompt/spec design, policy distinctions, or category-risk architecture, cite the `architect` role agent's read-only review as advisory evidence. Its findings can inform the plan or follow-up evidence when explicitly used, but `$ralplan` itself records Architect→Critic lifecycle evidence only, and advisory review is never a durable execution authorization.
+
+## Usage with interactive mode
+
+```
+$ralplan --interactive "task description"
+```
+
+## Behavior
+
+## GPT-5.6 Guidance Alignment
+
+Use the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step planning, local overrides for the active workflow branch, evidence-backed planning and validation expectations, explicit stop rules, right-sized implementation/PRD shape, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+
+This skill runs its own consensus runtime; it does not delegate to a nonexistent Plan consensus mode:
+
+```
+adw ralplan run --task <arguments> [--session <id>]
+```
+
+The consensus workflow:
+1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review. Current `[main]` vs `[planner]` behavior: standalone `$ralplan` may be authored by the active main planning lane unless the caller/runtime supplies a dedicated planner routing record; inside `$autopilot`, state field `planning_routing.owner:"planner"` means the initial Planner draft/decomposition must use dedicated `[planner]`. Set `.adw-config.json` `agentModels.planner` to opt into a specific planner model and force dedicated planner ownership for complex Autopilot planning even when `[main]` is not cheap/mini. The RALPLAN-DR summary includes:
+   - Principles (3-5)
+   - Decision Drivers (top 3)
+   - Viable Options (>=2) with bounded pros/cons
+   - If only one viable option remains, explicit invalidation rationale for alternatives
+   - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
+2. **User feedback** *(--interactive only)*: If `--interactive` is set, use the structured question UI (`adw question` in attached tmux; native structured input outside tmux when available) to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
+**Native role-routing preflight:** Keyword routing may already have selected Ralplan, but it is not authority. Run `adw ralplan preflight --json` only when the native task surface reports `role_routing_unavailable` and this workflow attempts adapted Ralplan Planner, Architect, or Critic authority, adapted role-intent, or adapted consensus authority. On `unsupported_documented_leader_proof`, stop before that adapted authority and use a Codex surface with documented root proof or a reviewed alternative workflow. Do not infer root identity from `session_id`, undocumented `thread_id`, session/pointer/transcript/cwd state, absence of child data, or a prompt label. Ordinary native planning, lifecycle, state, status, health, HUD, runtime, setup, install, sync, and unrelated delegation are outside this preflight boundary and remain governed by existing controls.
+
+**Native role-routing rule:** When the native surface exposes `agent_type` role routing, set `agent_type` to an installed ADW role and never omit it for ADW work. When it does not (`role_routing_unavailable`), do not fabricate `agent_type`. On the exact reviewed Codex releases 0.144.5, 0.145.0, 0.146.1, and 0.148.0-alpha.5, adapted Ralplan Planner, Architect, Critic, role-intent, and consensus authority are unavailable because they lack documented root proof; every other version remains unknown and fails closed. Do not silently weaken routing with a prompt role label or inferred carrier. Use a Codex surface with documented root proof or a reviewed alternative workflow for that authority. A direct `adw ralplan role-intent write` attempt is denied with machine reason `unsupported_documented_leader_proof`.
+
+3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. Launch this as a subsequent role-specific `Architect` subagent and pass the full task statement, context snapshot, PRD/test-spec paths, and relevant prior findings; do not substitute an unvalidated reviewer identity or a short improvised reviewer prompt. In deliberate mode, Architect should explicitly flag principle violations.
+4. **Critic** evaluates against quality criteria — run only after step 3 completes. Launch this as a subsequent role-specific `Critic` subagent with the full task statement, context snapshot, PRD/test-spec paths, and the completed Architect review; do not ask the Architect subagent to perform the Critic gate and do not substitute an unvalidated reviewer identity or a short improvised reviewer prompt. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
+5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   a. Collect Architect and Critic feedback
+   b. Revise the plan with Planner
+   c. Return to Architect review
+   d. Return to Critic evaluation
+   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
+   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
+6. On Critic approval, persist the execution-ready planning artifacts and sequential Architect→Critic evidence. In standalone interactive Ralplan, present the requested future execution lane. Inside Autopilot, the existing explicit `$autopilot` invocation authorizes the supervised transition to its defining next stage, `$ultragoal`; persist an Autopilot-owned `ralplan_execution_handoff` bound to the same session and review cycle.
+7. Record `ralplan_execution_handoff` with `{authorized: true, reason, authorized_at, session_id, review_cycle, source: "autopilot"|"user"}`. `source:"autopilot"` is valid only for a supervised active Autopilot run whose current phase is `ralplan`; it does not claim host-consensus authority.
+8. Transition to `$ultragoal` after the durable plan, sequential approvals, and bound execution handoff exist. Do not implement directly inside Ralplan.
+
+> **Important:** Steps 3 and 4 MUST run sequentially as role-specific subagents. Do NOT issue both agent calls in the same parallel batch. Always await the subsequent `Architect` result before invoking the subsequent `Critic`; their completed approvals establish local lifecycle evidence only and cannot satisfy the durable execution gate.
+
+## Planning/Execution Boundary
+
+`$ralplan` is a planning mode. While ralplan is active and no explicit execution handoff is active, implementation-focused write tools are out of scope. Ralplan may inspect the repository and may write only planning artifacts such as `.adw/context/`, `.adw/plans/`, `.adw/specs/`, and required `.adw/state/` records.
+
+The canonical flow is:
+
+```
+$ralplan -> local Architect→Critic lifecycle evidence -> bound execution handoff -> $ultragoal
+```
+
+Before any execution lane begins, ralplan must emit terminal planning state (complete, paused, failed, or waiting for input) and the durable handoff record below. Do not continue from consensus planning into direct code edits in the same ralplan session.
+
+## Durable Consensus Handoff Contract
+
+Ralplan is not complete, skippable, or ready for execution merely because `.adw/plans/prd-*.md` and `.adw/plans/test-spec-*.md` exist. Those files are planning artifacts, not consensus evidence.
+
+Before any Autopilot, Ultragoal, Team, or implementation handoff, persist a durable handoff record that distinguishes:
+
+- `planning_artifacts`: PRD/test-spec paths.
+- `ralplan_architect_review`: the completed Architect review with an approving verdict.
+- `ralplan_critic_review`: the completed Critic review with an approving verdict, recorded only after the Architect review.
+- `ralplan_execution_handoff`: persist `{authorized: true, reason: "<rationale>", authorized_at: "<ISO timestamp>", session_id: "<current session>", review_cycle: <matching lifecycle cycle>, source: "autopilot"|"user"}`. Autopilot may issue this only for its own supervised `ralplan` phase; standalone Ralplan uses `source:"user"`.
+- `ralplan_consensus_gate.complete` records lifecycle completion after the sequential Architect and Critic approvals. It is not a host-security claim. Locally authored JSON/env/prompt/tracker/transcript/receipt-shaped evidence must never be described as host-issued authority.
+
+If Architect is missing/blocked, keep the workflow in Architect review or report that blocker. If Critic is missing/blocked/non-approving, keep the workflow in Critic/re-review or report the max-iteration outcome. After both reviews approve, execution begins only when the matching `ralplan_execution_handoff` is durable. Existing plan/test-spec files alone are never permission to skip Ralplan or execute.
+
+Follow the Plan skill's full documentation for consensus mode details.
+
+## Goal-Mode Follow-up Suggestions
+
+When a bound `ralplan_execution_handoff` permits execution, include product-facing goal-mode suggestions alongside coordinated Team execution. Record the requested lane and persist the handoff without claiming host-issued authority.
+
+- `$ultragoal` — **default goal-mode follow-up** for implementation or general goal-oriented follow-up plans that should become durable Codex/ADW goals with sequential completion tracking.
+- `$autoresearch` — research-project follow-up when the plan centers on a question, literature/reference gathering, evaluator-backed research, or a professor/critic-style research deliverable.
+- `$performance-goal` — optimization/performance follow-up when the plan centers on speed, latency, throughput, memory, benchmark, or other measurable performance work.
+
+Use `$ultragoal` for durable goal tracking and `$team` for coordinated parallel implementation. When combined, Ultragoal owns the ledger and Team returns checkpoint-ready execution evidence.
+Use the available-agent-types roster to produce explicit role/staffing allocation, reasoning-by-lane guidance, concrete launch hints (including `adw team` when parallel delivery is justified), and team verification responsibilities for any future receipt-authorized execution path.
+
+## Pre-context Intake
+
+Before consensus planning or execution handoff, ensure a grounded context snapshot exists:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.adw/context/{slug}-*.md` when available.
+3. If none exists, create `.adw/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, gather brownfield facts first. `adw explore` is deprecated; use normal repository inspection tools/subagents for simple read-only repository lookups and `adw sparkshell` only for explicit shell-native read-only evidence. Then run `$deep-interview --quick <task>` before continuing.
+5. If the plan depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, use `$best-practice-research` as the bounded evidence wrapper and auto-delegate `researcher` for the official/upstream lookup before finalizing the planning handoff so execution does not start from repo-local recall alone.
+6. If a prior `$autoresearch` run exists, treat its approved artifact as evidence for the plan. Do not include Autoresearch as a final architecture or runtime component unless the user explicitly requested ongoing research automation; otherwise synthesize the evidence into the `$ralplan` ADR, risks, and verification steps.
+
+Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
+
+## Routing boundary
+
+Ordinary scoped tasks stay in the direct execution lane described by `templates/AGENTS.md`.
+Explicit workflow requests follow the keyword registry (`src/hooks/keyword-registry.ts`) and their owning skill contracts; this card does not define a second activation table.
+Once Ralplan is active, preserve the planning/execution and consensus handoff requirements above. A conversational “just do it” is not a substitute for the required review evidence.
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.

package/packages/agent-skills/assets/refactor-safely/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: refactor-safely
-description: "Use when the user wants to plan or execute a refactor — a rename, dead-code removal, decomposition, or restructuring — with dependency-aware confidence before touching code. USE FOR: renaming a function or symbol, checking the impact radius of a change before applying it, previewing every call site an edit touches, decomposing a large function, removing dead code, seeing what breaks before refactoring. DO NOT USE FOR: orienting in an unfamiliar codebase with no refactor in mind (use explore-codebase), chasing the cause of a live bug (use debug-issue), or reviewing someone else's pending diff (use review-changes)."
+description: "Use when the user wants to plan or execute a refactor — a rename, dead-code removal, decomposition, or restructuring — with dependency-aware confidence before touching code. USE FOR: renaming a function or symbol, checking the impact radius of a change before applying it, previewing every call site an edit touches, decomposing a large function, removing dead code, seeing what breaks before refactoring. DO NOT USE FOR: orienting in an unfamiliar codebase with no refactor in mind (use explore-codebase), chasing the cause of a live bug (use diagnosing-bugs), or reviewing someone else's pending diff (use code-review)."
+keywords: rename impact radius call sites decomposition dead code restructure
 disable-model-invocation: false
 ---
 
@@ -19,8 +20,8 @@ edit location before applying a change.
 
 You are only orienting in an unfamiliar codebase with no refactor in mind —
 use `explore-codebase`. You are chasing the cause of a live bug — use
-`debug-issue`. You are reviewing someone else's pending diff — use
-`review-changes`.
+`diagnosing-bugs`. You are reviewing someone else's pending diff — use
+`code-review`.
 
 ## Steps
 

package/packages/agent-skills/assets/report-bug/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: report-bug
+description: Classify a finding and record it on the board - a defect in an open Feature updates that Feature's PBIs (a comment on each affected PBI, or the needed PBI created at New), no new Bug; a defect in a closed Feature at Awaiting Release or later becomes a Bug under the Epic's Fixes to closed Features Feature, whose Description holds the bugfix shape the human approves at G1, with a predecessor Bug (none if first) and a Related link to the responsible Feature. Board only, never a file or a push. Usable by any agent that finds a bug, including workitem-triage for a red pipeline; the only intake for findings.
+metadata:
+  step: "report-bug"
+  role: "any"
+  states: "none (intake)"
+---
+
+# Report a bug
+
+Load `workitems-process` first. Any agent may use this card; it is the only intake for findings. The Bug's ladder, its item file and who writes it are in [Bug states](../workitems-process/references/workitem-states.md#5-bug-states).
+
+**Board only.** This card writes work items, links and comments. It never writes a file, commits or pushes. The per-Bug run's executor writes the Bug's item file later.
+
+## When to use
+
+- You found behaviour that is wrong, with a reproduction or a source-level proof.
+- workitem-triage found the latest completed run of the `integration` or `main` pipeline red (after its roll-ups): always a Bug, whatever the merged Feature's state (step 4), and only when that run's build id is named in no Bug's `## Failing builds` (any state) ([Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers)).
+- Not for fixing it, planning it or moving existing items.
+
+## Procedure
+
+1. **Verify.** Reproduce it (command + actual output, or the failing pipeline run and its log) or prove it in source (`file:line`). Cannot -> do not file; report "unverified" to your caller.
+2. **Find the responsible Feature.** The Feature whose scope should have got this right (work item links, the commit log and annotation, `requirements.md`; for a red pipeline, the merged Feature, or for a per-Bug PR the merged Bug's Responsible Feature). Unclear -> report it to your caller as a finding; never guess.
+3. **Duplicate check.** Re-runs never add duplicate comments.
+   - **Red pipeline:** a red pipeline is filed only when the LATEST completed run of the `integration` or `main` pipeline is red AND its build id is named in no Bug's `## Failing builds` (any state). Search every Bug, in any state, for this build id first: named -> stop, with nothing to do. Then search open Bugs (New through Updating Docs) for the same failure (same failing test or job). Found -> append the build id to that Bug's `## Failing builds` in its board Description (that section only; the approved sections stay unchanged), post no comment, and stop. Otherwise file a new Bug (step 5) with the same Responsible Feature; if an earlier Bug (Done or Parked for Removal) names the same failure, that Bug is its predecessor. Older runs are never filed. A run already named never files again. Once named, a red `main` run waiting for promotion and the last red `integration` run before the fix's next run both stay quiet.
+   - **Finding:** search open PBIs/Bugs covering the same behaviour. Found -> add a comment citing your repro, unless a comment there already cites the same repro, and stop.
+4. **Classify.** A red `integration` or `main` pipeline after a merge is always filed as a Bug under the Epic's `Fixes to closed Features` Feature, whatever the merged Feature's state: go to step 5. The open-versus-closed rule below applies to findings only, not to red pipelines. A finding is classified by the responsible Feature's state:
+
+   | Feature state | Action |
+   |---|---|
+   | New, In Progress (open) | **Update that Feature's PBIs; create no Bug.** On the board only: comment on each affected existing PBI (the repro and the acceptance criterion it breaks or lacks), or create the needed PBI at New under that Feature. A new or changed acceptance criterion goes through the Feature's next planning run, where the planner writes the item file (the requeue re-fire). A defect inside the current approved criteria is a loop finding the executor fixes, with no item-file change. |
+   | Awaiting Release, Done (closed) | **Create a Bug** under the Epic's `Fixes to closed Features` Feature (step 5). A child may never be added to a closed Feature [pending L1]. |
+
+5. **Create the Bug (closed case, or a red pipeline).**
+   1. Find the Fixes Feature: the Feature titled exactly `Fixes to closed Features` under the same Epic as the responsible Feature. Missing or several -> report it to your caller as a finding; never create one.
+   2. Allocate on the board: `workitem_create_or_update_bug --title ... --parent-id <Fixes Feature> --description "..." --effort <days>`. State stays New. Mandatory at create: `title`, `parentId` (a Feature — typically the Fixes Feature), `description` (must carry the five bugfix headings `## Current behaviour` / `## Expected behaviour` / `## Behaviour that must not change` / `## Responsible Feature` / `## Verification`), and `effort` (number, days, ≥0; float accepted). Plan fields are forbidden (T3 — hard). `comment` is mandatory on every update (on create `comment` is optional). Predecessor: at most one, only when the Fixes Feature already holds another Bug (L4); none for the first Bug. Related: required when the parent is the Fixes Feature (the related link points to the Responsible Feature) (L4). The Description must carry the bugfix shape:
+
+      | Section | Holds |
+      |---|---|
+      | `## Current behaviour` | what happens now, with the repro and its output; for a red pipeline it cites the first failing build id once |
+      | `## Expected behaviour` | what should happen, one EARS sentence per criterion ("THE SYSTEM SHALL ..."; WHEN/WHILE/IF-THEN/WHERE) |
+      | `## Behaviour that must not change` | what the fix must leave alone |
+      | `## Responsible Feature` | the responsible Feature (board URL) and why it owns this: the closed Feature, or for a red pipeline the merged Feature (for a `fix/` PR, the merged Bug's Responsible Feature) |
+      | `## Verification` | a regression test that fails before the fix |
+      | `## Failing builds` | for a red pipeline only: the build id of each red run it covers, one per line, appended by later runs; it lives only in the board Description, never in the item file; absent for a finding |
+
+   3. Links:
+
+      | Link | Target | Rule |
+      |---|---|---|
+      | Parent | the Fixes Feature | required |
+      | Predecessor | another Bug in the same Fixes Feature | **none if it is the first Bug there** (a predecessor is refused then); every later Bug needs one [soft/hard check pending L4]; a red pipeline whose same failure an earlier Bug (Done or Parked for Removal) names takes that earlier Bug |
+      | Related | the responsible Feature | required [pending L4] |
+
+6. **Lifecycle.** The Bug starts at New. The human approves the Description at G1 (New -> Approved); from there the per-Bug run takes it ([Bug states](../workitems-process/references/workitem-states.md#5-bug-states)). You do none of that.
+
+## Output
+
+Return to the caller: the classification, the commented PBI id, the new Bug id or the Bug a build id was added to, the links made, the repro (for a red pipeline, its build id). A report only when the dispatching step requires one.
+
+## Never
+
+- Never fix the defect, edit product code, write a file, commit or push.
+- Never create a Bug for an open Feature, or a child under a closed Feature.
+- Never move a `Fixes to closed Features` Feature (stays In Progress; the tool refuses, pending F5).
+- Never create a Feature or Epic; never invent a parent.
+- Never put a predecessor on the first Bug, or on a PBI.
+- Never file an unverified finding.
+- Never file a red run older than the latest, never file or append a build id any Bug's `## Failing builds` already names (any state), and never repeat a comment a re-run already posted.
+- Never write a finding to `plans/GAPS-AND-FINDINGS.md`; removing that file is pending R7.

package/packages/agent-skills/assets/review-change/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: review-change
+description: "Independent read-only review of the run's branch, the Feature branch or the fix/ branch, at an exact head SHA in one of two lanes - code: correctness, security, tests, maintainability, docs, ruling APPROVE or REQUEST_CHANGES or architecture: boundaries, coupling, design fidelity, tradeoffs, ruling CLEAR, WATCH or BLOCK - for one item's commits or, in Feature-final mode, the whole diff. No PR threads and no votes. Use when the implementation lead spawns code-reviewer or architect for the In Review step."
+metadata:
+  step: "review-code, review-architecture"
+  role: "code-reviewer, architect"
+  states: "In Review"
+---
+
+# Review Change (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`), one lane of a two-lane review. The other lane runs in a separate sub-agent; never cover for it. In Review is a step of a **non-linear loop**: the item may come back after a fix, at a new head, and be reviewed again.
+
+There is **no PR reviewer, no vote and no PR thread** before the merge ([Human gates](../workitems-process/SKILL.md#human-gates)). Your findings go in your report; the lead posts them as item comments and keeps them for the implementation report. Independence is a fresh context, and the reviewer model family preferably differs from `executor`'s when the surface allows (config; not required).
+
+## When to use
+
+| Mode | Scope |
+|---|---|
+| **item** | The commits carrying `AB#<item id>`, read in the context of the branch |
+| **final** (Feature-final) | The full diff against the integration base, every item |
+| **delta** | After a CI fix: the fix commits only, plus what they touch |
+
+- `lane: code` → role `code-reviewer`. `lane: architecture` → role `architect`.
+- Not for fixing, re-verifying, or reviewing a plan (that is `review-plan`).
+
+## Inputs (from the brief)
+
+- Lane, mode, head SHA, `base_sha`, item id and `AC-n` (item/delta), `design.md` and `file-map-reference.md`, the verify report at this head.
+
+## Preconditions
+
+1. `lane` is `code` or `architecture`; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+2. The worktree toplevel equals the worktree; record the branch head as `head_sha` and review that SHA (diff `<base_sha>..<head_sha>`, read `<head_sha>:<path>`). A HEAD that differs from the named head SHA, or moves during the review, never stops or restarts it: say so in the report; the lead re-runs you at the new head ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+3. A verify `PASS` at this head exists in the brief; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Procedure
+
+1. **Scope.** Diff the file set against `<base_sha>..<head>` (item mode: the item's commits); read every changed file in full, plus callers and tests of changed symbols. Do not widen into unrelated code.
+2. **Criteria map.** For each `AC-n` in scope, find the code and the test that covers it. An unmapped `AC-n` is a finding.
+3. **Review your lane** (below). Every finding gets `id`, `severity`, `where` (path:line), `what` (issue and risk), `fix` (concrete). Separate fact from suggestion.
+4. **Verdict** by the lane rule. No partial or conditional approvals.
+5. **Return the report** (`lane: review-code` or `review-architecture`): `head_sha`, `verdict`, all findings, `artifacts` = files reviewed, `AC-n` → test map. Leave the worktree untouched.
+
+### Code lane (code-reviewer)
+
+- **Correctness**: logic, edge cases, error paths, concurrency, resource cleanup, idempotence.
+- **Security**: injection, path traversal, secrets in code or logs, authz checks, unsafe deserialization. Feeds the PR's `## Security impact considered`.
+- **Tests vs `AC-n`**: each criterion has a test that would fail without the change; no skipped, loosened or tautological assertions; a test changed to match buggy behaviour is a critical finding (fake-green).
+- **Maintainability**: dead code, needless abstraction, swallowed errors, masking fallbacks, naming.
+- **Docs impact**: every doc `design.md` `## Docs impact` lists for the item is changed in this diff and is accurate; a gap is a `docs-missing` finding. Per-Bug run: the docs the Bug's fix touches.
+- Severity: critical (security, data loss, fake-green), high (bug, `AC-n` unmet, missing test or doc), medium, low.
+- **REQUEST_CHANGES** if any critical or high finding exists; else **APPROVE** (medium/low ride along).
+
+### Architecture lane (architect)
+
+- **Boundaries and interfaces**: wrong-layer imports, leaked responsibilities, public surface changes.
+- **Coupling**: hidden shared state, new cross-module dependencies, ordering assumptions.
+- **Design fidelity**: the change matches `design.md` (as updated); no unapproved scope added or dropped; no `AC-n` bent.
+- **Long-horizon tradeoffs**: migration, compatibility, operability, cost of reversal.
+- **Devil's advocate**: write the strongest argument against merging and answer it.
+- **BLOCK** for a merge blocker (boundary break, design deviation, irreversible risk); **WATCH** for a real but non-blocking concern; **CLEAR** otherwise.
+
+## Verdicts
+
+| Lane | Verdict | Lead does |
+|---|---|---|
+| code | `APPROVE` | Counts toward moving on |
+| code | `REQUEST_CHANGES` | Item comment; a PBI → In Implementation (In Testing → In Implementation pending F1; In Review → In Implementation allowed today), a Bug → In Fixing (pending F9); executor gets the findings |
+| architecture | `CLEAR` / `WATCH` | Counts toward moving on; WATCH goes in the report |
+| architecture | `BLOCK` | As `REQUEST_CHANGES` |
+
+## Stop rules
+
+- One review per call, finished against the `head_sha` recorded at start. Re-read HEAD immediately before returning; if it moved, say so in the report and do not restart: the lead compares your `head_sha` with the branch head and re-runs the review at the new head.
+- Diff unreadable after the tool fallback (`adl mcp cli`): return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never edit, commit, push, merge or move an item. Never comment on a PR or cast a vote.
+- Never review the other lane, or approve because the other lane approved.
+- Never review a head you did not read in full.

package/packages/agent-skills/assets/review-plan/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: review-plan
+description: "Read-only review of one Feature plan revision: requirements.md, design.md, file-map-reference.md and item files in two sequential lanes chosen by the brief - architect: steelman antithesis, tradeoff tension, boundaries, principle violations then critic: EARS and testable criteria, fair options, mitigated risks, concrete verification, sizing gate - each ending in APPROVE, ITERATE or REJECT. Use when the planning lead spawns architect or critic inside a planning run."
+metadata:
+  step: "planning (sub-agent lanes)"
+  role: "architect, critic"
+  states: "Feature plan; items In Planning"
+---
+
+# Review Plan
+
+Load `workitems-process` first. One skill, two lanes; the brief's `lane` picks one. Mirrors adl-workflow's `$ralplan` (`adl/skills/ralplan/SKILL.md`): Architect first, Critic only after the Architect has finished, both read-only. You are a sub-agent of the planning run, spawned by `planner`; you are a leaf.
+
+## When to use
+
+- `lane: architect`: the planner finished a draft of revision N and wants the soundness review.
+- `lane: critic`: an Architect review of revision N exists and is in your brief.
+- Not dispatched on its own and not per item: the unit is the Feature's plan revision. There are no votes and no vote-refresh ([Human gates](../workitems-process/SKILL.md#human-gates)).
+
+## Inputs (from the planner's brief)
+
+| Field | Meaning here |
+|---|---|
+| `feature_id`, `worktree` | The Feature and the read-only checkout of the planning branch |
+| `plan_commit` | The commit holding revision N of the plan folder |
+| `revision` | N |
+| `plan_hash` | sha256 of `requirements.md` at `plan_commit` |
+| `base_sha` | The integration SHA the plan is written against |
+| `lane` | `architect` or `critic` |
+| `architect_review` | Critic only: the Architect's full review for N |
+| `round` | review round within revision N, 1..3 |
+| `prior_findings` | Earlier findings (earlier rounds of N, G1 findings) and how each was answered |
+
+Independence is a fresh context, not another identity. The reviewer model family preferably differs from the executor's when the surface allows (config; not required).
+
+## Preconditions
+
+1. `workitems-process` universal preconditions that apply (identity; the worktree check is on the read-only checkout).
+2. The sha256 of `requirements.md` at `plan_commit` equals `plan_hash`, and its Revision log last row is N. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+3. All of `intent.md`, `requirements.md`, `design.md`, `file-map-reference.md` and `items/*.md` are readable at `plan_commit`. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+4. Critic only: `architect_review` is in the brief and is for revision N. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)). The Critic never reviews first.
+
+## Procedure
+
+Common to both lanes:
+1. Read `intent.md` first (the human's words), then `requirements.md`, `design.md`, `file-map-reference.md` and every item file, the Revision log, and `prior_findings`.
+2. Read the baseline code `design.md` `## Solution` names: read `<base_sha>:<path>`. Each ref exists at `base_sha` or is marked `(new)`. Use `crg impact` / `crg query callers_of <target>` for blast radius, else `rg`.
+3. Prior findings: every finding id an earlier round or G1 raised is `addressed` or `declined` with a reason (the planner's round comment for review findings, the Revision log for G1 findings). A silently dropped finding is a finding.
+4. Fidelity to the intent: nothing in `requirements.md` contradicts or exceeds `intent.md`'s Constraints and Non-goals.
+
+### Lane: architect
+
+5. **Steelman antithesis.** The strongest case against the chosen approach: the best alternative and why a good engineer would pick it. Not a strawman.
+6. **Tradeoff tension.** At least one real tension the plan trades (scope vs safety, local patch vs fix at source), and whether the plan resolves it explicitly.
+7. **Boundaries and coupling.** Modules, contracts and data shapes crossed; new coupling; whether the fix sits at the source (shared layer) or patches downstream; blast radius.
+8. **Item split.** Items are cut on real seams; items carry no predecessors; the loop is described as non-linear.
+9. **Principle violations** (deliberate mode: flag explicitly): silent fallbacks, swallowed errors, fake-green tests, scope creep past Non-goals, docs not in the same change.
+10. **Synthesis.** When possible, the adjustment that keeps the plan's strengths and answers the antithesis. Put it in `fix`.
+
+### Lane: critic
+
+5. Read the Architect's review for N.
+6. **EARS.** Every acceptance criterion is one EARS sentence ("THE SYSTEM SHALL ...", optionally WHEN, WHILE, IF ... THEN, WHERE), observable, with an expected result.
+7. **Testable and traced.** Each `AC-n` maps to a `design.md` `## Verification` line with a runnable command. Every AC is verified by at least one item; every item's Verification names its `AC-n`. A Bug is never reviewed here: Bugs are not planned, and the item file is the whole plan.
+8. **Fair options.** RALPLAN-DR: 3-5 principles, top 3 drivers, >= 2 real options (or a sound invalidation); the chosen option is consistent with them. Deliberate mode: pre-mortem (3 scenarios) and an expanded `## Verification`, else `REJECT`.
+9. **Risks mitigated.** Each risk has a concrete mitigation, not "be careful". `## Docs impact` lists every doc the change touches.
+10. **Open questions for G1** are true decisions, each with a recommendation. Nothing undecided is written as fact. A hit cap lists the open findings here.
+11. **Records.** Feature predecessors are listed (at least 1 unless the very first); Revision log is append-only; `file-map-reference.md` `## Baseline` is an exact SHA; no plan hash, revision or baseline sits in frontmatter.
+12. **Sizing gate.** All must hold:
+    - <= 6 items;
+    - ~<= 40 touchpoints (count `change` and `new` rows in `file-map-reference.md`; `read` rows are free);
+    - ~<= 1,500 changed lines (`design.md` `## Size estimate`, with its working shown);
+    - no shims or compatibility layers (hard cut);
+    - one coherent outcome: the `intent.md` `## Outcome`, expressed by the AC set.
+    Over the gate is `REJECT` with the split as the `fix`.
+13. **Architect carry-forward.** Every Architect finding of severity medium or higher that revision N does not already answer becomes a Critic finding (same `where`/`fix`, `what` prefixed `architect:`).
+
+### Verdict rules
+
+| Verdict | Use when |
+|---|---|
+| `APPROVE` | No finding of severity medium or higher remains. Low findings may be listed. Critic: also no carried-forward Architect finding, and the Architect verdict is not `REJECT` |
+| `ITERATE` | The approach is sound; findings must be fixed in the next revision |
+| `REJECT` | The approach or scope is wrong (misses the intent, wrong layer, unbounded, over the sizing gate) and needs a fresh approach |
+
+Severity: `critical` breaks correctness, data or security; `high` makes an AC unverifiable or the approach unsafe; `medium` is a gap a reviewer at G1 would ask about; `low` is wording or polish.
+
+## Output
+
+Return one review to the planner as your final message. You never post a comment or write to the board; the planner posts one combined comment per round. Prose first, then the block:
+
+```yaml
+lane: architect | critic
+feature: <id>
+revision: <N>
+round: <1..3>
+plan_commit: <sha>
+plan_hash: <sha256>
+base_sha: <sha>
+verdict: APPROVE | ITERATE | REJECT
+findings:                  # required for ITERATE, REJECT
+  - id: A1                 # A1... architect, C1... critic
+    severity: critical | high | medium | low
+    where: <file + section, or path:line>
+    what: <the problem>
+    fix: <the concrete change to the plan>
+```
+
+- Architect prose carries the antithesis, the tradeoff and the synthesis. Critic prose carries the checklist outcome and the sizing numbers.
+- Finding ids are unique per lane, revision and round. Comment format and evidence home: [Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports); comment-read tool pending T1.
+
+## Stop rules
+
+- One lane per spawn. The Architect never writes the Critic verdict; the Critic never re-runs the Architect review.
+- Stop after the review. Never wait for the planner.
+- Cannot read the plan at `plan_commit` twice in a row, or the hash mismatches -> return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never edit a plan file, branch or PR; never commit or push. Read-only. You write nothing, to files or to the board.
+- Never move any state. Never cast a vote.
+- Never `APPROVE` with an open finding of severity medium or higher.
+- Never review a revision other than N, or reuse a verdict from an earlier revision.
+- Never spawn anything. You are a leaf.

package/packages/agent-skills/assets/triage-workitems/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: triage-workitems
+description: "The workitem-triage run, rank 0, - reason over every open PBI, Bug and Feature, compare the board state with the real state in code, branches and PRs, then propose and when the fence allows apply states, splits, merges and predecessor links, roll Features up: New to In Progress to Awaiting Release to Done, file a red integration or main pipeline through report-bug, and report unplanned Features as informational. Board only, never a file or a push. Use when the adl dispatcher starts the workitem-triage target; every later target trusts the board this run leaves behind."
+metadata:
+  step: "workitem-triage"
+  role: "triager"
+  states: "all open PBI/Bug states, Feature states"
+---
+
+# Triage work items
+
+Load `workitems-process` first ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance), [Human gates](../workitems-process/SKILL.md#human-gates), [Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). This card adds only what `workitem-triage` does.
+Findings enter through `report-bug` only.
+
+**Board only.** Triage writes states, splits, merges, comments and predecessor links. It never writes a file, commits or pushes. Item-file changes a triage write implies are made by the planner in the Feature's next planning run; a PBI that triage creates is at New, which re-fires the planning trigger (the requeue re-fire).
+
+## When to use
+
+- The dispatcher starts the `workitem-triage` target (rank 0, one run per tick, whole repo). It reasons; it is not mechanical.
+- Triggers (any): an open PBI/Bug off the ladder (e.g. `Committed`, which is not a ladder state); an item whose state may not match its evidence; a Feature roll-up due; a Feature with no parent Epic or (all but the first) no predecessor Feature; the LATEST completed run of the `integration` or `main` pipeline is red AND its build id is named in no Bug's `## Failing builds` (any state).
+- Not for planning, implementing, reviewing or filing a finding of your own outside `report-bug`.
+
+## Inputs
+
+Run record (`prompts/workitem-triage.md`): `key` = repo, `feature_id` null, `worktree` = the repo worktree for the run, `identity` `agent-tarun`, `resume_notes`.
+
+## Preconditions
+
+1. `workitems-process` universal preconditions (the key is the repo; no item state check).
+2. The integration base is current. Evidence is read from the integration base, not from a branch you happen to be on.
+3. Board reads work (`workitem_list_or_get`, then `adl mcp cli` as fallback). Cannot read the board on either route: report both errors and end the run; the next tick re-dispatches.
+
+## Procedure
+
+1. **List.** Every open PBI and Bug, every Feature not Done/Removed, and the latest `integration` and `main` pipeline runs (`build_list_or_get`).
+2. **Read evidence per item** (spawn read-only explore sub-agents on the fast tier for breadth):
+   - item file and acceptance criteria (`requirements.md`, `design.md` of its Feature; for a Bug, its Description);
+   - code on the integration base: what exists, what tests cover;
+   - the Feature implementation branch, the per-Bug branch, or the planning branch, plus the PR, merge commit and CI state;
+   - the item's comments (comment read: pending T1 in adl-agent-control);
+   - its Feature, parent Epic and the Feature's predecessors.
+3. **Judge the true state.** Partly done is a valid answer (some criteria met on `integration`, others not). No blanket "unknown -> New".
+4. **Propose** per item: target state, reasoning, evidence (`file:line`, commit, test output). Unchanged is a proposal too.
+   - **Choosing a target state for an off-ladder or mismatched item: move backward only, to the earliest state the evidence supports.** When two targets fit, take the earlier one; with no usable evidence, New. Never forward past what the evidence shows, and never into a human-only state. If the board refuses a backward jump, post the refusal text as an item comment, take the path the refusal names, and do not fall back to a different state.
+5. **Reshuffle when the evidence says so** (board only):
+
+   | Move | How |
+   |---|---|
+   | Split | Narrow the original to what is done or in flight; create a new PBI on the board under the **same Feature** for the rest; when the split yields a Bug, create it through `report-bug`. A new PBI is at New, so the planner writes its item file in the Feature's next planning run, which the requeue re-fire triggers; a new Bug's item file comes in its own per-Bug run. No predecessor links on items. |
+   | Merge / supersede | Move duplicates to Parked for Removal with the reason and the surviving item id. |
+   | Re-order | Only Feature predecessor links. Item order inside a Feature is the implementation lead's choice. |
+
+6. **Apply or propose.**
+   - Apply yourself when the fence allows the move.
+   - Propose only (post the full proposal as an item comment and leave the item unchanged) when: the target is human-only; the fence refuses it; the item is `Committed`; the Feature is parentless; the evidence is thin.
+7. **Feature roll-ups** (Features only, linear, one step, never backward):
+
+   | Move | Do it when | Precondition [fence pending F3/F4] |
+   |---|---|---|
+   | New -> In Progress | at least one child has left New | same |
+   | In Progress -> Awaiting Release | every child is Done or Removed (merged to `integration`) | same |
+   | Awaiting Release -> Done | the `integration -> main` PR carrying the children is merged | that PR merged |
+
+   - Never roll up or move a Feature titled exactly `Fixes to closed Features`; it stays In Progress.
+   - Never add a child to a Feature at Awaiting Release or Done.
+8. **Red pipeline**, after the roll-ups of step 7. The LATEST completed `integration` or `main` run is red AND its build id is named in no Bug's `## Failing builds` (any state): hand it to `report-bug`. If an open Bug (New through Updating Docs) names the same failure, it appends the build id to it, with no comment; otherwise it files a new Bug, and an earlier Bug (Done or Parked for Removal) naming the same failure is its predecessor. Older runs are never filed. A run already named never files again. Once named, a red `main` run waiting for promotion and the last red `integration` run before the fix's next run both stay quiet. A new Bug is always a Bug under the Epic's `Fixes to closed Features` Feature, whatever the merged Feature's state. Responsible Feature: the merged Feature, or for a `fix/` PR the merged Bug's Responsible Feature. That card is board only, so filing it never pushes.
+9. **Unplanned Features are informational.** List the Features the planning trigger should fire on ([Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers)) in the report; write no marker.
+10. **Report** (below).
+
+## Rules on targets
+
+| Target | Rule |
+|---|---|
+| Approved, Done, Removed | Never. Human-only (G1, merge, G3). **Never from an unknown/off-ladder state**: the fence does not guard it today (F2 pending). |
+| Done on an item | Never claimed. Merged work with a non-Done item is reported with the merge commit; only the implementation PR's completion sets Done. |
+| In Planning, Awaiting Approval | Only where evidence exists (plan revision, planning PR). `pr_create_or_update` moves Awaiting Approval itself when the planning PR is raised. |
+| In Implementation .. Updating Docs | Only to match a live branch/PR; loop moves are free-move (F1 pending: report a refusal, do not work around it). |
+| Parked for Removal | Allowed for duplicates/obsolete items, with a reason. |
+| Parent | Never invent one. A parentless Feature is proposed only: comment naming the missing Epic, item unchanged; the human sets the parent |
+
+## Verdict and report
+
+- Verdict `TRIAGED`: every swept item has a recorded proposal: applied, proposed or unchanged. Done proof: every swept item reads back on a legal state, and each latest completed `integration` and `main` run is green or its build id is named by a Bug. Verdict sets: [Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports).
+- One comment per touched item, carrying that item's proposal, reasoning and evidence.
+- The run report, as the last action, goes to the activity log with `adl activity add` ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). Content: `base_sha` = integration base SHA, counts (applied / proposed / unchanged), the id lists, split-off ids, rolled-up Feature ids, Bugs filed for red pipelines, unplanned Features (informational).
+
+## Stop rules
+
+- Sub-agents: you are the session lead and may spawn **read-only explore** sub-agents on the fast tier for codebase understanding. They write nothing and spawn nothing. All board writes are yours.
+- Same tool failure twice: stop retrying it; record the item as unchanged with the error, and go on with the next item.
+- Stop after the report. Never start planning or implementation.
+
+## Never
+
+- Never write, commit or push a file: no code, no plan files, no item files, no reviews.
+- Never move to Approved/Done/Removed.
+- Never create a Feature or Epic; `epic:` and `feature:` are authored by a human.
+- A new finding goes through `report-bug`, never into a file of your own.
+- Never act as if a pending change in adl-agent-control is live.