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

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, `git log`/`git blame`, `requirements.md`; for a red pipeline, the merged Feature, or for a `fix/` 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 --type Bug`, state New, parent = the Fixes Feature, with the Description in 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) | `git diff origin/integration...<head>`, 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. `git rev-parse --show-toplevel` equals the worktree; record `git rev-parse HEAD` as `head_sha` and review that SHA (`git diff <base_sha>...<head_sha>`, `git show <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.** `git diff --stat <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 `origin/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 |
+
+Identity: `agent-tarun`. 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. `git show <plan_commit>:plans/features/az<feature>-<slug>/requirements.md | shasum -a 256` 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: `git show <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. `git fetch origin`. Evidence is read from `origin/integration`, 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 `origin/integration`: what exists, what tests cover;
+   - branch `feat/az<id>-<slug>`, `fix/az<bug id>-<slug>` or `docs/az<id>-<slug>-plan`, PR, merge commit, 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` (pending A1; [Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). Content: `base_sha` = `origin/integration` 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.

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

@@ -0,0 +1,77 @@
+---
+name: ultragoal
+description: Create and execute durable repo-native multi-goal plans over Codex goal mode artifacts.
+---
+
+# Ultragoal Workflow
+
+## When to use
+
+Use for `ultragoal`, `create-goals`, `complete-goals`, durable multi-goal planning, or sequential execution over Codex `/goal`. Read `AGENTS.md#durable-runtime-invariants-canonical-ssot` for state ownership and goal-tool boundaries.
+
+## Inputs and preconditions
+
+- Durable artifacts are `.adw/ultragoal/brief.md`, `.adw/ultragoal/goals.json`, and `.adw/ultragoal/ledger.jsonl`.
+- New plans use aggregate Codex goal mode by default: one stable pointer objective for the plan while ADW tracks individual stories. Use `--codex-goal-mode per-story` only when explicitly requested.
+- Do not call `/goal clear` from shell or this skill. After a completed run, the operator may clear the interactive Codex goal in the Codex UI before another same-thread run.
+
+## Operational steps: create
+
+Run one command, then inspect the generated plan:
+```bash
+adw ultragoal create-goals --brief "<brief>"
+adw ultragoal create-goals --brief-file <path>
+cat <brief> | adw ultragoal create-goals --from-stdin
+adw ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"
+```
+If refinement is needed, use explicit supported steering rather than editing durable artifacts by hand.
+
+## Operational steps: execute
+
+Repeat until `adw ultragoal status` reports all goals complete:
+
+1. Run `adw ultragoal complete-goals` and read its handoff.
+2. Call `get_goal`. Call `create_goal` with the printed payload only when no active Codex goal exists; otherwise continue the matching aggregate objective.
+3. Complete one ADW story and audit its objective against real artifacts and verification evidence.
+4. For intermediate aggregate stories, keep the Codex goal active and checkpoint:
+   ```bash
+   adw ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <fresh-get-goal-json-or-path>
+   ```
+5. For a blocked/failed story, use `--status blocked|failed` with evidence; resume failed work with `adw ultragoal complete-goals --retry-failed`.
+6. On the final story, complete the final gate below before `update_goal({status: "complete"})`; then call `get_goal` again and checkpoint the fresh complete snapshot.
+
+## Explicit steering
+
+Use evidence-backed directives only when the decomposition must change:
+```bash
+adw ultragoal steer --kind add_subgoal --title "<title>" --objective "<objective>" --evidence "<evidence>" --rationale "<reason>" --json
+adw ultragoal steer --directive-json ./steering.json --json
+```
+Supported kinds: `add_subgoal`, `split_subgoal`, `reorder_pending`, `revise_pending_wording`, `annotate_ledger`, and `mark_blocked_superseded`. Ordinary prose does not mutate the plan; repeated structured directives dedupe.
+
+## Phase/HUD handoff
+
+At standalone activation, declare the smallest accurate phase (`planning`, `executing`, `verifying`, `reviewing`, `checkpointing`, or `blocked`):
+```bash
+adw state write --input '{"mode":"ultragoal","active":true,"current_phase":"planning"}' --json
+```
+Inside Autopilot, keep the parent mode active and set `current_phase:"ultragoal"`; persist Ultragoal evidence under `handoff_artifacts.ultragoal` before a code-review handoff. Mark standalone Ultragoal complete only when every durable goal is complete.
+
+## Optional Team bridge
+
+For parallel story execution, use the separate Team command. The leader records the Ultragoal checkpoint with a fresh `get_goal` snapshot; see the Team skill for the bridge details.
+
+## Final gate and exit evidence
+
+Before final completion:
+
+1. Run targeted story verification.
+2. Run `ai-slop-cleaner` on changed files, then rerun verification.
+3. Audit every architecture/domain invariant from the brief/spec/accepted steering against implementation, test, and review evidence.
+4. Run `$code-review` through independent `code-reviewer` and `architect` lanes. If review or invariant proof is not clean, do not update the Codex goal; record durable blockers:
+   ```bash
+   adw ultragoal record-review-blockers --goal-id <id> --title "Resolve final code-review blockers" --objective "<objective>" --evidence "<findings>" --codex-goal-json <active-get-goal-json-or-path>
+   ```
+5. If clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with `--quality-gate-json` containing cleaner, verification, review, and architecture-invariant evidence.
+
+Report goal ids/statuses, ledger/checkpoint paths, fresh goal snapshot evidence, review verdicts, and any blocker. Never claim completion from ADW state alone.

package/packages/agent-skills/assets/validate-design/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: validate-design
+description: Read-only check that a Feature's design.md still matches the repo - compare the Feature's baseline SHA with the worktree HEAD over the files and symbols design.md and file-map-reference.md name, and rule FRESH or DRIFT with the exact design delta. Use when the implementation lead spawns it at Design Validation, or again after mid-loop drift. requirements.md is not re-validated.
+metadata:
+  step: "validate"
+  role: "architect"
+  states: "Design Validation"
+---
+
+# Validate Design (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). You check **`design.md` and its `file-map-reference.md`** against the repo. `requirements.md` was validated in planning and approved at G1; do not re-validate it. Drift never leaves the run: the lead sends a planner to update `design.md` and continues ([No block](../workitems-process/SKILL.md#no-block)). You never edit anything.
+
+## When to use
+
+- Lead call 1: all items just moved Approved → Design Validation. Scope = the whole Feature.
+- Lead call 2: after a planner updated `design.md` (re-check, once).
+- Lead call 3: mid-loop drift (In Implementation → Design Validation **[pending F1]**). Scope = the item, seeded by the executor's `DRIFT` finding.
+- **Not for Bugs.** A Fixes Bug has no `design.md` and no Design Validation state; its per-Bug run goes Approved → In Reproduction. If handed a Bug, return that and stop.
+
+## Inputs (from the brief)
+
+- Plan folder `plans/features/az<id>-<slug>/`: `design.md`, `file-map-reference.md`; `BaselineSha` (the `integration` SHA the plan was written against); `against` = worktree `HEAD`; optional `scope` and seed finding. The run starts by merging `origin/integration` into its branch, so the worktree `HEAD` contains the current `integration`: you diff `<BaselineSha>..HEAD` and record `head_sha`.
+
+## Preconditions
+
+1. Worktree toplevel equals the brief's worktree; `git rev-parse HEAD` printed and recorded as `head_sha`.
+2. `git fetch origin`; `git merge-base --is-ancestor <BaselineSha> HEAD` succeeds. If not, return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+3. `git status --porcelain` is empty (you read a committed state).
+
+## Procedure
+
+1. **Collect the surface.** From `design.md` (`## Solution`, `## Decisions`, `## Verification`, `## Risks`, `## Docs impact`) and `file-map-reference.md`, list every file path, directory and symbol named (`FILES`, `DIRS`, `SYMBOLS`). Add the seed finding's `where` paths.
+2. **Measure change since baseline.**
+   ```
+   git diff --stat <BaselineSha>..HEAD -- <FILES>
+   git diff --name-status -M <BaselineSha>..HEAD -- <FILES> <DIRS>
+   git log --oneline <BaselineSha>..HEAD -- <FILES> <DIRS>
+   ```
+   For each symbol: `git grep -n '<symbol>' HEAD -- <path>` and at `<BaselineSha>`; compare signatures.
+3. **Judge each design claim** (`file:line` refs, signatures, "X calls Y", chosen option, the AC → test map): still true at HEAD, or moved, renamed, removed, already done by someone else?
+4. **Classify.**
+
+   | Ruling | Condition |
+   |---|---|
+   | `FRESH` | No change to `FILES`/`SYMBOLS`, or changes provably irrelevant to every claim (say why per commit) |
+   | `DRIFT` | Something design.md names changed, and design.md can be corrected without changing any `AC-n`. Delta required |
+
+   Neither fits (a correct design would have to change an `AC-n` or the scope, or a named contract is gone): rule `DRIFT` with a separate finding that names the `AC-n` or scope; the lead's path for AC drift is in [No block](../workitems-process/SKILL.md#no-block).
+5. **Write findings.** `DRIFT`: one finding per design passage. `where` = design section + path (`Item az9002 › src/x.ts:40`); `what` = the commit(s) that moved it (`<sha7> <subject>`); `fix` = the exact replacement text. Severity low/medium.
+6. **Return the report** (format in `implement-feature` › `references/briefs.md`): `lane: validate`, `target`, `base_sha` = `BaselineSha`, `head_sha`, `verdict`, `findings`, `artifacts` (diff range, files in the surface, commands run).
+
+## Verdicts
+
+| Verdict | Lead does |
+|---|---|
+| `FRESH` | Continues |
+| `DRIFT` | Sends `planner` (design-update mode) with your delta, then asks you again once |
+
+## Stop rules
+
+- One ruling per call, at the `head_sha` you recorded at start ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule). If HEAD moves while you work, finish against the one you recorded (diff `<BaselineSha>..<head_sha>`, not `..HEAD`) and say so; never stop or restart. The lead compares your `head_sha` with the branch head and re-runs you at the new head when it moved.
+- Same git or tool failure twice: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never edit `design.md`, `requirements.md` or any file; never commit, push or move an item.
+- Never rule `FRESH` without running the step 2 commands.
+- Never fold an `AC-n` change into a `DRIFT` design delta; name it as its own finding (step 4).
+- Never recommend sending items to New or In Planning.

package/packages/agent-skills/assets/verify-item/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: verify-item
+description: Independently verify one item - or, in Feature-final mode, the whole Feature - at an exact head SHA against its EARS acceptance criteria and adversarial scenarios, read-only, in a fresh context. Use when the implementation lead spawns verifier for the In Testing step of an item, for the Feature-final check, or to re-check a CI-fix delta.
+metadata:
+  step: "verify"
+  role: "verifier"
+  states: "In Testing"
+---
+
+# Verify Item (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). Prove or disprove that the head meets the criteria. Bounded adversarial QA, one pass, no fixing. The item loop is non-linear: you may be called for the same item again after a fix, at a new head.
+
+## When to use
+
+| Mode | Scope |
+|---|---|
+| **item** | One item's `AC-n` list, at the head SHA the lead names. For a Bug the criteria are the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change` |
+| **final** (Feature-final) | Every `AC-n` in `requirements.md`, the full suite, at the final head. In a per-Bug run the criteria are the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`. This is the evidence the merge relies on |
+| **delta** | After a CI fix: the changed paths plus the `AC-n` they touch, at the new head |
+
+Not for fixing code or reviewing style.
+
+## Inputs (from the brief)
+
+- Mode, item id (item/delta), the `AC-n` list with the item's `## Verification` lines, the head SHA, `base_sha` (for Bug proof: the `integration` SHA the `fix/` branch was created from).
+- There is no PR yet in item and final modes: required checks are the repo's own commands, run locally. In delta mode the PR exists; read its failing check's job for what to re-run.
+
+## Preconditions
+
+1. `git rev-parse --show-toplevel` equals the brief's worktree; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)). Record `git rev-parse HEAD` as `head_sha` and finish against it ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule): if HEAD differs from the named head SHA, or moves during the run, run in an export of `head_sha` under `.scratchpad/`, say so in the report, and never stop or restart; the lead re-runs you at the new head.
+2. `git status --porcelain` is empty before you start.
+3. You are a fresh context. You never read the executor's transcript, only its committed work and the plan.
+
+## Procedure
+
+1. **Build the matrix** before running anything: scenario id, `AC-n` or risk it covers, setup, command, expected signal, actual result, cleanup. Every `AC-n` in scope gets at least one row.
+2. **Acceptance checks.** For each `AC-n` run the mapped test or command. Capture command, exit code and the line that proves the signal. An `AC-n` with no runnable check is a FAIL finding (`fix`: add the test), not a pass by reading. Final mode also runs the full suite, lint, typecheck and build.
+3. **Bug regression proof** (Bug items). You must not change HEAD in the shared worktree. Export the base: `mkdir -p .scratchpad/base && git archive <base_sha> | tar -x -C .scratchpad/base`; copy the regression test from head into it; run it and confirm it **fails for the reported defect**. Then run it at head and confirm it passes normally: at head it carries no expected-failure mark (the fix commit removes the mark the reproduce commit added); a mark left at head is a FAIL finding. If the exported copy cannot run the test, the proof is not PASS: FAIL with a finding naming what the copy lacks.
+4. **Adversarial scenarios** relevant to the change only:
+   - malformed input: missing fields, invalid flags, oversized or unusual-Unicode strings, path-like values;
+   - failure paths: dependency down, permission denied, non-zero child exit, timeouts;
+   - repeated and interrupted runs: run twice, kill mid-run, re-run; idempotence and partial state;
+   - misleading success: success text with non-zero exit, skipped tests counted as passes, swallowed errors;
+   - dirty state: pre-existing untracked files or stale state.
+   Bound every command with a timeout. A flaky result is reported with rerun counts and both run outputs, never a lucky green.
+5. **Harness hygiene.** Temporary tests, fixtures and scripts live only in `.scratchpad/` (gitignored), are never committed, and are deleted before you stop. A harness bug is fixed and rerun before calling it a product defect.
+6. **Clean up.** Remove temp files and processes; `git status --porcelain` is empty and HEAD unchanged. Record before and after.
+7. **Verdict.** `PASS` only when every `AC-n` in scope passed, the bug proof (if any) holds, and no high/critical adversarial finding exists. Otherwise `FAIL`.
+8. **Return the report**: `lane: verify` (or `verify-final`), `target`, `head_sha`, `verdict`, `findings` (each `id`, `severity`, `where` file:line or check, `what`, `fix`), `artifacts` = matrix summary (scenario → `AC-n` → result), commands with exit codes, bug proof runs, cleanup status.
+
+## Verdicts
+
+| Verdict | When | Lead does |
+|---|---|---|
+| `PASS` | All of step 7 holds at the head | Moves the item on (to In Review by default) |
+| `FAIL` | Any `AC-n`, check, bug proof or high/critical scenario fails | Posts findings as an item comment, moves the item → In Implementation (a Bug: → In Fixing) (In Testing → In Implementation pending F1; In Review → In Implementation allowed today) |
+
+Medium/low adversarial findings ride along on `PASS` as notes; they do not block.
+
+## Stop rules
+
+- One pass. Do not loop fix-and-retest.
+- Same scenario errors three times for harness reasons: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never edit product code, tests in the branch, or the plan; never commit, push or change HEAD.
+- Never move an item or post on the board.
+- Never PASS an `AC-n` by reading code alone, or with skipped, quarantined or retried-until-green tests.
+- Never wait unbounded or leave temp harnesses, processes or a dirty worktree behind.