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

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

@@ -1,100 +1,118 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
-disable-model-invocation: false
+description: Run a comprehensive code review
 ---
 
-# Code Review
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+# Code Review Task Card
 
-- **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+Use this explicit opt-in for a merge-readiness review. Shared operating invariants
+live in `templates/AGENTS.md`; this card only defines review-specific behavior.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+## When to use
 
-## Use When
+- The user asks for a code review or quality/security assessment.
+- A change is ready for review before merge, or a major feature needs an independent review.
+- Do not activate this card for implementation, broad planning, or automatic cleanup.
 
-- The user wants to review a branch, a PR, or work-in-progress changes against a fixed point.
-- The user asks to "review since X" (a commit, branch, tag, or merge-base).
+## Inputs
 
-## Do Not Use When
+- Scope: the requested files, commit, PR, or whole diff.
+- Requirements/specification, acceptance criteria, and relevant test/CI evidence.
+- Existing review artifacts and known risks, if any.
+- If the user says `continue`, advance the current verified review step rather than restarting discovery.
 
-- There is no fixed point to diff against and the user won't supply one (pin one first, see Process step 1), or the work isn't implemented yet so there's no diff to review — use `implement` first.
+Start by recording the scope:
 
-The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+```sh
+git status --short
+git diff --stat
+git diff -- <scope>
+```
 
-## Process
+## Execution
 
-### 1. Pin the fixed point
+1. Identify changed files and review boundaries; do not silently widen the scope.
+2. Launch the `code-reviewer` and `architect` agents in parallel. Both lanes run in parallel on a clean context with explicit scope and artifacts. If either lane cannot be launched or does not return evidence, report `independent review unavailable`; do **not** substitute the current/authoring lane, and do **not** approve or mark the review merge-ready.
+3. Respect the user's current model and reasoning/effort selection. Do not pass `model` or `reasoning_effort` overrides in review-lane calls.
 
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+```text
+task(
+  agent_type="code-reviewer",
+  prompt="CODE REVIEW TASK
 
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+Review the supplied scope for spec compliance, security, quality, performance, and maintainability.
+Return files reviewed, severity-rated findings with file:line evidence and concrete fixes,
+and a recommendation: APPROVE / REQUEST CHANGES / COMMENT. Do not review architecture.
+Scope: [scope and artifacts]"
+)
 
-Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+task(
+  agent_type="architect",
+  prompt="ARCHITECTURE / DEVIL'S-ADVOCATE REVIEW TASK
 
-### 2. Identify the spec source
+Review the same scope for boundaries, interfaces, hidden coupling, long-term tradeoffs,
+and the strongest counterargument against approval. Return file:line evidence,
+recommendations, and Architectural Status: CLEAR / WATCH / BLOCK.
+Scope: [scope and artifacts]"
+)
+```
 
-Look for the originating spec, in this order:
+## Review taxonomy
 
-1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
-2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.adl/` matching the branch name or feature.
-4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+- `code-reviewer` checks **Security**, **Code Quality**, **Performance**, **Best Practices**, and **Maintainability**.
+- Rate each finding: **CRITICAL** (security or data-loss blocker), **HIGH** (bug/major smell), **MEDIUM** (important improvement), or **LOW** (style/suggestion).
+- `architect` checks explicit boundaries/interfaces, hidden coupling, long-horizon tradeoffs, and devil's-advocate concerns. Status is **CLEAR**, **WATCH** (non-blocking concern), or **BLOCK** (merge blocker).
+- Every finding names `file:line`, issue, risk, and a concrete fix; distinguish facts from suggestions.
 
-### 3. Identify the standards sources
+## State/HUD Phase Contract
 
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+- Standalone `$code-review` relies on hook-owned `skill-active-state.json` (`skill:"code-review"`, `phase:"planning"`); do not create `code-review-state.json`.
+- Inside Autopilot, keep `mode:"autopilot"` active with `current_phase:"code-review"` / skill-active `phase:"code-review"`; do not activate a peer workflow.
+- On clean review, persist the artifact under Autopilot `handoff_artifacts.code_review` before moving to `ultraqa`. On non-clean review, persist findings and use `rework` or `ralplan` as appropriate.
 
-On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+```sh
+adw state write --input '{"mode":"autopilot","active":true,"current_phase":"code-review"}' --json
+```
 
-- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
-- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+## Final Synthesis and gate
 
-Each smell reads *what it is* → *how to fix*; match it against the diff:
+### Architectural Status Contract
 
-- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
-- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
-- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
-- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
-- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
-- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
-- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
-- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
-- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
-- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
-- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
-- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+Combine the `code-reviewer` recommendation and architect status. Approval requires explicit evidence from both independent lanes; missing or failed delegation is a blocking unavailable-review state, not an approval fallback. The final report must make architect blockers impossible to miss.
 
-### 4. Spawn both sub-agents in parallel
+- If architect status is **BLOCK**, final recommendation is **REQUEST CHANGES**.
+- Else if `code-reviewer` recommendation is **REQUEST CHANGES**, final recommendation is **REQUEST CHANGES**.
+- Else if architect status is **WATCH**, final recommendation is **COMMENT**.
+- Else final recommendation follows the `code-reviewer` lane.
 
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+Approval criteria: **APPROVE** only when `code-reviewer` returns APPROVE, architect status is `CLEAR`, and both independent lanes returned evidence. **REQUEST CHANGES** for a blocker, unresolved high/critical finding, or unavailable lane. **COMMENT** may record non-blocking findings.
 
-**Standards sub-agent prompt** — include:
+Do not self-review as a fallback. If the `code-reviewer` or `architect` path is missing, unavailable, skipped, or fails, block approval until independent lane evidence exists. Plain `code-review` itself remains read-only and does **not** promise auto-fix.
 
-- The full diff command and commit list.
-- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
-- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+## Evidence/output contract
 
-**Spec sub-agent prompt** — include:
+Return a concise report containing:
 
-- The diff command and commit list.
-- The path or fetched contents of the spec.
-- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+```text
+CODE REVIEW REPORT
+Files Reviewed: <count>
+Total Issues: 0
+Architectural Status: CLEAR | WATCH | BLOCK
+CRITICAL (0) | HIGH (0) | MEDIUM (0) | LOW (0)
+Findings: file:line -> issue, risk, concrete fix (or none)
+ARCHITECTURE WATCHLIST: concern, status, recommendation (or none)
+- code-reviewer recommendation: COMMENT
+- architect status: WATCH
+- final recommendation: COMMENT
+RECOMMENDATION: COMMENT
+```
 
-If the spec is missing, skip the Spec sub-agent and note this in the final report.
+Replace the illustrative counts and verdict with observed values. Include scope,
+lane evidence/artifact references, unresolved risks, and validation gaps.
 
-### 5. Aggregate
+## Exit condition
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
-
-End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
-
-## Why two axes
-
-A change can pass one axis and fail the other:
-
-- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
-- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
-
-Reporting them separately stops one axis from masking the other.
+Stop when the scoped diff has two independent lane results and a deterministic final
+recommendation. Report `APPROVE` only under the approval criteria; otherwise leave a
+bounded `REQUEST CHANGES`, `COMMENT`, or unavailable-review result. Never claim
+merge-ready without the required evidence.

package/packages/agent-skills/assets/diagnosing-bugs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: diagnosing-bugs
-description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", reports something broken/throwing/failing/slow, or asks to trace a crash or root cause through the call chain.
+keywords: trace crash root cause call chain execution flow callers callees failing throwing regression diagnose debug
 disable-model-invocation: false
 ---
 
@@ -53,6 +54,24 @@ Once it's red, shrink the repro to the **smallest scenario that still goes red**
 
 Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green. Do not proceed until you have reproduced **and** minimised.
 
+## Trace with the knowledge graph
+
+When the symptom names a code area, or a recent change is the suspect, trace
+the call structure with the knowledge graph instead of reading file by file —
+this is how Phase 3 hypotheses get built fast:
+
+1. Run `crg search "<query>"` to find code related to the issue.
+2. Run `crg query callers_of <target>` and `crg query callees_of <target>` to trace call chains.
+3. Run `crg flow --name <n>` to see full execution paths through suspected areas.
+4. Run `crg detect-changes --base <ref>` to check if recent changes caused the issue.
+5. Run `crg impact --files <f…>` on suspected files to see what else is affected.
+
+- Check both callers and callees to understand the full context.
+- Look at affected flows to find the entry point that triggers the bug.
+- Recent changes are the most common source of new issues.
+- Trace efficiently: capped output (`--limit`, `--brief`), a handful of commands,
+  then verify the suspected cause against real source before proposing a fix.
+
 ## Phase 3 — Hypothesise
 
 Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
@@ -99,10 +118,12 @@ Required before declaring done:
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
 
-## HITL loop script
+## HITL loop script — live sessions only
 
 `scripts/hitl-loop.template.sh` is the human-in-the-loop reproduction loop (usage notes moved out of the script so the deployed copy has no multi-line comment run).
 
+**Live sessions only** — a session where the human is present (`write-feature`-style live work, or this skill invoked interactively). Never inside a dispatched run: No block forbids waiting on a person, and run evidence must be machine-checkable. In a dispatched run a human-only repro is automated instead (Playwright drives the clicks — tactic 4) or, if that genuinely fails, the lead posts the attempt as a finding and parks the item with proof. In a live session the captured `KEY=VALUE` pairs are the human's testimony, and the regression test built from them still lands before the fix.
+
 - Copy the file, edit the steps in it, and run it. The agent runs the script; the user follows prompts in their terminal.
 - Usage: `bash hitl-loop.template.sh`
 - Two helpers: `step "<instruction>"` shows the instruction and waits for Enter; `capture VAR "<question>"` shows the question and reads the response into `VAR`.

package/packages/agent-skills/assets/diagnosing-bugs/references/FEEDBACK-LOOP-TACTICS.md

@@ -11,7 +11,7 @@
 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+10. **HITL bash script.** If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. **Live sessions only** — never inside a dispatched run (No block: never wait on a person; run evidence must be machine-checkable). In a run, automate the human instead (Playwright, tactic 4); if that genuinely fails, the lead parks the item with proof. Captured output feeds back to you.
 
 Build the right feedback loop, and the bug is 90% fixed.
 

package/packages/agent-skills/assets/explore-codebase/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: explore-codebase
 description: Navigate and understand codebase structure using the knowledge graph
+keywords: navigate orient structure understand unfamiliar get oriented modules
 disable-model-invocation: false
 ---
 
@@ -16,8 +17,8 @@ relationships before making a change, or locating where a concept lives.
 ## Do Not Use When
 
 You already know where the problem is and need to trace a bug — use
-`debug-issue`. You are about to refactor a known target — use
-`refactor-safely`. You are reviewing a pending diff — use `review-changes`.
+`diagnosing-bugs`. You are about to refactor a known target — use
+`refactor-safely`. You are reviewing a pending diff — use `code-review`.
 
 ## Steps
 

package/packages/agent-skills/assets/finalize-feature/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: finalize-feature
+description: Assemble the content for the one Feature implementation PR without pushing - the five-section PR body and the implementation report for all items - and check that the design's docs impact is in the diff. Returns text to the lead. Use when the implementation lead spawns writer after the Feature-final check passed at the final head.
+metadata:
+  step: "finalize"
+  role: "writer"
+  states: "Updating Docs"
+---
+
+# Finalize Feature (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). Evidence assembly only. Docs were written in `implement-item` and reviewed with the code; you make **no pushes, commits, file edits or board writes**, because any push voids the Feature-final evidence. The lead raises the PR; `pr_create_or_update` links the items, moves them and attaches the report **[pending P1/P2/P4]**. You supply content only.
+
+## When to use
+
+- The lead holds a Feature-final verify `PASS` and both review lanes passing at the final head `H`, and items are code-complete (Updating Docs or about to be).
+- Also on a CI round: the lead asks you to append that round to the report.
+- Not for writing docs, fixing code or resolving conflicts.
+
+## Inputs (from the brief)
+
+- Final head `H`, `base_sha`, all per-item sub-agent reports (implement, verify, review) and their finding resolutions, the Feature-final reports, design-update commits, CI rounds so far.
+- Plan folder: `requirements.md`, `design.md` (`## Docs impact`), item files.
+
+## Preconditions
+
+1. `git rev-parse HEAD` equals `H` and the worktree is clean; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+2. The Feature-final verify is `PASS` and code is `APPROVE` and architecture `CLEAR`/`WATCH`, all at `H`; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Procedure
+
+1. **Docs check.** For each entry in `design.md` `## Docs impact` (per-Bug run: the docs the fix touches), find the matching path in `git diff --name-only origin/integration...H` and read the hunk, not just the filename. "No docs impact" counts as covered. Any missing entry: verdict `REWORK`, finding `docs-missing` (`where`: doc path or section; `fix`: what to write). Stop.
+2. **PR body.** The five non-empty sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git), filled as below. Every claim links to evidence (a report, a commit, a run); no unverified statements.
+   - `## Summary`: what the Feature delivers, by item (id, title).
+   - `## Why`: from `intent.md` and `requirements.md`, in the plan's words, not new claims.
+   - `## Changes`: per item, the files and behaviour changed; design updates made during the run; docs touched.
+   - `## Test plan`: per `AC-n`, the test and its result; Feature-final verify run at `H`; CI status as known.
+   - `## Security impact considered`: what the code reviewer examined and found; "none" only with the reviewer's report as the source.
+   The title is `<type>(<scope>): <lowercase subject>`.
+3. **Implementation report** (becomes `impl-report-pr<id>.md`). Per item: changes, tests (`AC-n` → test, red then green), review findings (id, severity, resolution or accepted WATCH), rounds used. Then: design updates, Feature-final heads and results, CI rounds. Facts only, from the reports.
+4. **Return** `lane: finalize`, `head_sha` = `H`, `verdict`, and in the reply the PR body, the report text and the docs-impact table (entry → doc path), each in its own fenced block. Write them nowhere.
+
+## Verdicts
+
+| Verdict | When | Lead does |
+|---|---|---|
+| `DONE` | Docs covered; body and report complete | Pushes and raises the PR |
+| `REWORK` + `docs-missing` | Docs impact not in the diff | Executor writes it; Feature-final repeats |
+
+## Stop rules
+
+- One pass, against the `head_sha` recorded at start. If HEAD moves while you work, finish against that `head_sha` and say so; never restart. The lead re-runs you at the new head ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+
+## Never
+
+- Never push, commit, rebase or edit files. Never write the body or report to disk.
+- Never call `pr_create_or_update` or any board tool; never link items, set auto-complete, vote or merge.
+- Never include a claim without a source, or a PR link that does not resolve.
+- Never write the docs yourself.
+
+## Parked
+
+`prepare-promotion` (integration to main, G2) is parked: no target fires it. It stays with `writer`, for later.

package/packages/agent-skills/assets/fix-ci/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: fix-ci
+description: Make the smallest fix for a red CI run on the run's implementation PR (a Feature's, or a Fixes Bug's) - read the failing job, reproduce it locally, fix at the cause, commit on the run's branch, no skips and no masking. Use when the implementation lead spawns executor for the CI stage after the PR checks went red.
+metadata:
+  step: "fix-ci"
+  role: "executor"
+  states: "CI stage"
+---
+
+# Fix CI (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`), the fix lane of the CI stage (ADR-019). CI is the last gate before the implementation PR (the Feature's, or the Fixes Bug's) merges to `integration`. A hard cut: the fix is the smallest change that makes the real check pass.
+
+## When to use
+
+- The PR's required check failed at head `H`. The lead names the PR id, the failed build and job ids, and the related item.
+- A merge-conflict round is not yours; the lead sends an executor with `implement-item`.
+
+## Inputs (from the brief)
+
+- PR id, build id, failed job(s), head SHA, related item id (the item whose commits touch the failing paths; else the lowest-id item; in a per-Bug run, the Bug), plan folder (in a per-Bug run, the Bug's item file).
+
+## Preconditions
+
+1. Worktree toplevel and HEAD equal the brief's; tree is clean; branch is the run's branch (the Feature branch, or `fix/az<bug id>-<slug>` in a per-Bug run).
+2. The failing job log is readable (`build_list_or_get --build-id <id>`, with `--tail`). Unreadable: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Procedure
+
+1. **Read the log.** Find the first failing step, its command and its error. Quote the failing line.
+2. **Classify.**
+   - Code or test failure: continue.
+   - Infrastructure failure (agent lost, cancelled, network, queue timeout) with log proof and no code cause: return `INFRA` with the proof. The lead may re-queue the PR's own validation (pending H1). Do not change code.
+3. **Reproduce locally** with the same command. A failure you cannot reproduce is reported with both outputs, not "fixed" by guessing.
+4. **Fix at the cause.** Test first when the failure exposes a missing test. Smallest change; no unrelated cleanup; no new abstraction.
+5. **Checks.** Run the failing command and the repo's lint, typecheck, build and the relevant tests locally. Green.
+6. **Commit** on the run's branch: `fix(ci): <lowercase subject>`, `AB#<item id>` in the body (the Bug's id in a per-Bug run), naming the build and job. Do not push.
+7. **Return the report**: `lane: fix-ci`, `head_sha` = your commit, `verdict`, `findings` (the cause: `where`, `what`, `fix`), `artifacts` = failing log line, local red and green runs, commit SHA.
+
+## Verdicts
+
+| Verdict | When |
+|---|---|
+| `FIXED` | Reproduced, fixed at the cause, local checks green, committed |
+| `INFRA` | Not a code failure; log proof included; nothing changed |
+
+The lead then has `verifier` and `code-reviewer` re-check the delta at the new head. A fix is not done until they pass.
+
+## Stop rules
+
+- The same check fails after three distinct fixes: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never skip, disable, quarantine or loosen a test or check. Never `|| true`. Never `--no-verify`. Never delete a failing test.
+- Never re-run until green and call it fixed; a flaky result is reported with both runs.
+- Never push, force-push, re-queue a build, move an item or touch the PR.
+- Never edit `requirements.md` or `design.md`.

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

@@ -21,7 +21,7 @@ Write a handoff document summarising the current conversation so a fresh agent c
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 
-Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+Do not duplicate content already captured in other artifacts (docs, plans, ADRs, commits, diffs). Reference them by path or URL instead.
 
 Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
 

package/packages/agent-skills/assets/implement-feature/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: implement-feature
+description: "Run the implementation target for one Feature as its lead - move Approved items to Design Validation, have design.md checked against the repo, run the non-linear item loop: In Implementation, In Testing, In Review, Updating Docs, through sub-agents, run the Feature-final check, raise the one implementation PR to integration, and carry it through CI to the merge. Use when the adl dispatcher starts an implementation session, lead lead for a Feature whose in-scope items are all Approved or later."
+metadata:
+  step: "implementation"
+  role: "lead"
+  states: "Approved, Design Validation, In Implementation, In Testing, In Review, Updating Docs"
+---
+
+# Implement Feature (run skill of the lead)
+
+Load `workitems-process` first. This card is the lead's whole procedure. Sub-agents run their own skills; the briefs you give them are in `references/briefs.md`. Tags: **[pending Fx/Px/Hx]** = an adl-agent-control change that is not built. Never act as if a pending change is live.
+
+## When to use
+
+- The dispatcher started you for one Feature: every in-scope item (not Parked/Removed) is at Approved or later, at least one is not Done, every predecessor Feature is at Awaiting Release or Done.
+- **Per-Bug run.** The dispatcher may instead start you for one Fixes Bug at Approved through Updating Docs, until its PR merges, keyed by the Bug **[pending L5, X2]**, on branch `fix/az<bug id>-<slug>`. A Bug has no plan folder, no Plan Hash and no Design Validation: skip only Preconditions 4-5 and procedure step 1. Preconditions 1-3 apply in their per-Bug form (below). The Bug's ladder and moves are in [Bug states](../workitems-process/references/workitem-states.md#5-bug-states). A Bug at In Reproduction or later is a resumed run: continue from its state (Resume, below). On a fresh run (Bug at Approved) your first board write is Approved → **In Reproduction**. Then spawn `executor` (`implement-item`, reproduce mode, `reproduce` brief in `references/briefs.md`): its first commit is the Bug's item file, written from the G1-approved Bug Description, with its LEDGER row; its next commit is the regression test, proved red on the base and committed marked as an expected failure so the commit stays green, and that brief writes nothing else. Post the executor's unmarked red run on the base as a comment on the Bug, as evidence. Then move In Reproduction → **In Fixing**; the `fix` brief (bug mode) writes the minimal fix until green, in the loop, and its fix commit removes the expected-failure mark. Every commit stays independently green, with no exception. Run the loop and the one PR as usual. You write no file yourself. Won't reproduce: post what you tried as a comment on the Bug and move it to Parked for Removal (G3 is the human's). You resolve everything else in the run ([No block](../workitems-process/SKILL.md#no-block)).
+- One run = one worktree, one branch, one lead session (you), **one implementation PR** to `integration`.
+- Resume is not a separate mode: if the trigger still holds on a later tick you are started again in the **same worktree on the same branch**. Read the board and the branch, continue (Resume, below).
+
+## Inputs
+
+| Field | Meaning |
+|---|---|
+| `feature_id` | The Feature (the run key) |
+| `worktree` | Dispatcher-created checkout on branch `feat/az<id>-<slug>` (or the fitting `<type>/`); per-Bug run: `fix/az<bug id>-<slug>`. Agents never create worktrees |
+| Plan folder | `plans/features/az<id>-<slug>/`: `intent.md`, `requirements.md` (EARS criteria `AC-n`, `## Items`), `design.md`, `file-map-reference.md`, `items/az<id>-<slug>.md` |
+| Feature fields | `BaselineSha`, `PlanHash`, `PlanRevision` **[pending T3: named arguments; reference names not yet confirmed through the API]** |
+
+Identity `agent-tarun`.
+
+## Preconditions
+
+1. `git rev-parse --show-toplevel` equals `worktree`; the branch is the Feature's `<type>/az<id>-<slug>` (per-Bug run: `fix/az<bug id>-<slug>`); `git status --porcelain` is empty, or the dirt is your own previous attempt.
+2. `adl id whoami` reports `agent-tarun`.
+3. Read the Feature's children (`workitem_list_or_get`). Every in-scope item is at Approved or later; if not, the trigger does not hold: report the item and its state on the Feature and end the run. Per-Bug run: read only the Bug; it must be at Approved through Updating Docs with its PR not merged (other Bugs in the Fixes Feature do not matter); if not, report its state on the Bug and end the run.
+4. The plan folder is on the branch (planning PR merged into `integration`): the four plan documents and every `items/az<id>-*.md` exist. If the planning PR is not merged yet, end the run and report it; the next tick re-evaluates.
+5. `sha256` of `requirements.md` equals `PlanHash` (the hash covers `requirements.md` only). On a mismatch, post both hashes as a Feature comment and do not start Design Validation: the approved plan is not the one on the branch. **[pending F7: the tool will refuse the Design Validation move on a mismatch; the field reference name is not yet confirmed through the API.]**
+
+## Procedure
+
+### 1. Design Validation
+
+1. The run starts by merging `origin/integration` into its branch: `git fetch origin`, then `git merge origin/integration` (a fast-forward on a fresh start; never rebase, never force). The worktree `HEAD` then contains the current `integration`, and Design Validation diffs `<BaselineSha>..HEAD`.
+2. Move every Approved item → **Design Validation** (adjacent forward move; the fence allows it). This is your first board write.
+3. Spawn `architect` with the `validate-design` brief. It checks `design.md` and its `file-map-reference.md` by diffing `<BaselineSha>..HEAD`, records `head_sha`, and rules `FRESH`, or `DRIFT` (with the exact delta). `requirements.md` is **not** re-validated: it was validated in planning and approved at G1.
+4. `FRESH`: continue. `DRIFT`: **drift never leaves the run**. Spawn `planner` (skill `plan-feature`, Mode B: design update) with the delta. It updates `design.md`, `file-map-reference.md` (the `## Map` rows the drift moves, and the `## Baseline` section) and the Feature's Baseline Sha to the new `integration` base, adds the LEDGER row `az<id>-design-update`, and commits on the Feature branch; Plan Hash is unchanged. You write no file: record the update in the implementation report and the PR. Then re-validate once. Items never go to New or In Planning.
+5. A delta that would change an approved `AC-n`: `requirements.md` stays frozen. Deliver every other AC, comment the reason on that PBI and move it to Parked for Removal (G3); the next Feature plans the outcome if it is still wanted ([No block](../workitems-process/SKILL.md#no-block)).
+6. Design-update cap: 2 rounds. Past it, post the reason as a Feature comment and change approach ([No block](../workitems-process/SKILL.md#no-block)).
+
+### 2. The item loop (non-linear)
+
+The four states **In Implementation, In Testing, In Review, Updating Docs** are a **non-linear loop**: free moves among them in either direction, per item. **You move the items**; sub-agents move nothing. **[pending F1: until it ships the fence refuses some loop moves (e.g. In Testing → In Implementation). Post the refusal text as an item comment and take the path the refusal names. Never work around it.]**
+
+- **Order is yours.** Pick the item order from `design.md` (shared files, risk first). Default staffing is conservative: one executor at a time on the shared branch. Fan out only items with disjoint file scopes in `file-map-reference.md`, as native sub-agents of this session, never the adl-workflow `team` worker pool. You may also spawn read-only explore sub-agents on the fast tier.
+- The usual order is In Testing before In Review (green code before a reviewer's time). A default, not a rule.
+- **Every commit is on the run's one branch** (the Feature branch, or `fix/az<bug id>-<slug>` in a per-Bug run). No per-item branch, worktree or PR. Commits carry `AB#<item id>`.
+
+Per item, in the order you chose:
+
+| Step | You do | Sub-agent (skill) | Item state |
+|---|---|---|---|
+| Build | Give the item, its `AC-n` list and its design section | `executor` (`implement-item`) | → In Implementation |
+| Test | Give the item, `AC-n`, the head SHA | `verifier` (`verify-item`) | → In Testing |
+| Review | Run both lanes at the head SHA, in parallel, preferably a different model family from the executor (not required) | `code-reviewer` + `architect` (`review-change`) | → In Review |
+| Docs | A docs gap (finding `docs-missing`, or an item with docs still open) goes to an executor, docs only | `executor` (`implement-item`) | → Updating Docs |
+
+- **TDD:** each EARS criterion becomes a failing test first, then minimal code. The executor's report names the red run and the green run per `AC-n`. A report without the red run is not accepted.
+- **A finding goes back, inside the run:** post it as an item comment (`id`, `severity`, `where`, `what`, `fix`), move the item → In Implementation (a Bug: → In Fixing), send the executor **only the listed findings**. Cap: **3 rounds per item**; past it, post the reason as an item comment and change approach ([No block](../workitems-process/SKILL.md#no-block)).
+- **Mid-loop drift** (executor returns `DRIFT`): the item moves In Implementation → **Design Validation** **[pending F1]** ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance)), run step 1.3 to 1.6 for that item, then back to In Implementation.
+- **In Review** = reviewer sub-agents in fresh contexts. No PR reviewer, no votes, no PR threads before the merge ([Human gates](../workitems-process/SKILL.md#human-gates)). Findings go to **item comments and the implementation report**. `REQUEST_CHANGES` or `BLOCK` sends the item back. `WATCH` and medium/low are recorded, not blocking.
+- Sub-agents return a report (format in `references/briefs.md`). **You** post it on the item as a comment and keep it for the implementation report.
+- Push the branch (plain `git push`, never force) after each item's executor reports `DONE` so that heads are durable for resume. Verifiers, reviewers, the validate lane and the writer record `head_sha` at their start and finish against it; compare each report's `head_sha` with the branch head, and re-run the lane at the new head when the head moved ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+- A later commit voids earlier test and review evidence for what it touches. The Feature-final check is the evidence the merge relies on.
+
+### 3. Feature-final check
+
+When every item has been through Build, Test and Review and the tree is clean and pushed:
+
+1. Record the final head `H`.
+2. Spawn `verifier` in **Feature-final mode** (every `AC-n` of `requirements.md`, the full suite; in a per-Bug run, the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`, base = the `integration` SHA the `fix/` branch was created from) and both review lanes (code, architecture) over `origin/integration...H`.
+3. All pass at `H` → continue. Any finding → fix loop as above (the same 3-round cap, counted per finding), then repeat this step at the new head. Evidence binds to the head it ran at.
+
+### 4. Finalize and raise the PR
+
+1. Spawn `writer` (`finalize-feature`): docs-impact check against `design.md`, then the **PR body** (five sections) and the **implementation report** content. It returns text; it pushes and writes nothing. Finding `docs-missing` → an executor writes it, then repeat 3.
+2. PR body: the five sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git). Title in commit grammar. Branch `feat/az<id>-<slug>`, or `fix/az<bug id>-<slug>` in a per-Bug run (the `-plan` suffix marks a planning PR and is never used here).
+3. `git push` the branch. `pr_create_or_update` (action create, target `integration`) with the body and the report content. **The tool does the wiring [pending P1/P2/P4]** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)); you pass nothing for it. Until built, report which parts you could not observe.
+4. Read the PR and the items back: items at Updating Docs, PR linked. A mismatch is reported in the Feature comment, never patched by hand-linking or hand-moving to Done.
+
+### 5. CI stage (the last gate)
+
+CI is the gate before the merge (ADR-019). Poll `pr_list_or_get` and `build_list_or_get` for the head, every 60 s, printing status each poll.
+
+| Result | You do |
+|---|---|
+| Green, PR completes | Read the items back; they should be **Done** with the PR link (V2 not yet verified on a real PR). Never set Done yourself. End `MERGED` |
+| Red | Spawn `executor` (`fix-ci`): smallest fix, no skip, no `\|\| true`, no loosened test. Push. Then `verifier` and `code-reviewer` re-check the **delta** at the new head. Append the round to the implementation report (`pr_create_or_update` update). Cap **3** rounds; past it, post the reason as a Feature comment and change approach. Expired check: scoped `build_run` (pending H1). Integration moved: merge `origin/integration` |
+| Cancelled or infrastructure failure with log proof | Re-queue only your own PR's validation on the PR's source branch with `build_run` **[pending H1; refusal = report it, stop]**. A failing test or check is never re-queued to get a lucky green |
+| Merge conflict | Executor merges `origin/integration` into the branch (`git merge`, never a force-push), re-runs checks, then the delta is re-verified and re-reviewed as for red |
+
+## Board moves (yours)
+
+| Move | When | Status |
+|---|---|---|
+| Approved → In Reproduction | Per-Bug run: first act | **pending F9** |
+| In Reproduction → In Fixing | Per-Bug run: the reproduce brief returned `DONE` (the regression test proved red on the base, that run output posted as a Bug comment, and the test committed marked as an expected failure, so the commit is green) | **pending F9** |
+| Bug: In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs | Free moves | **pending F9** |
+| Bug: In Reproduction → Parked for Removal | Won't reproduce, with a comment of what was tried | **pending F9** |
+| Approved → Design Validation | First act, all PBIs (not Bugs) | live |
+| Design Validation → In Implementation | Item's Build starts | live |
+| In Implementation ↔ In Testing ↔ In Review ↔ Updating Docs | Free moves, per item, your call | **pending F1** |
+| In Implementation → Design Validation | Mid-loop drift | **pending F1** |
+| Any → Parked for Removal | Work provably obsolete, or a PBI whose AC drift needs a changed approved AC, with proof | live |
+
+Never move an item to Approved, Done or Removed. Never move a Feature. `pr_create_or_update` moves items to Updating Docs when it raises the PR **[pending P2]**; ADO completion moves them to Done on the merge **[verify V2]**.
+
+## Resume
+
+The trigger holds until the merge, so you may be restarted in the same worktree on the same branch (session died, run ended with the PR open, merge conflict). Do not restart finished work.
+
+1. Read every child's board state and its comments (the earlier sub-agent reports are there) **[pending T1: no comment-read tool yet; without it, work from board states, `git log` and the PR, and re-run any evidence whose head is stale]**.
+2. `git log origin/integration..HEAD` with `AB#` ids shows which items have commits. `pr_list_or_get` shows whether the PR exists.
+3. PR open: go to step 5. No PR: for each item resume from its board state (In Testing means run Test at the current head; In Review means run Review; and so on). Evidence at an older head is stale: re-run. Per-Bug run: a Bug at In Reproduction gets the `reproduce` brief again (it keeps the commits already made); a Bug at In Fixing or later resumes from its state in the loop.
+4. Reuse the branch and the PR. Never recreate either.
+
+## Verdicts
+
+| Verdict | When |
+|---|---|
+| `MERGED` | PR completed into `integration` |
+| `PR_OPEN` | PR raised and CI not finished when the session must end; the next tick resumes at step 5 |
+
+## Stop rules
+
+- One Feature, one PR. Do not start another Feature.
+- Never spin: the same command failing twice for the same reason means stop retrying it and take a different path.
+- Never wait on a person inside the session; only the planned gates G1, G2 and G3 wait on a person.
+- Keep producing output while you wait (a 60 s poll prints status); 20 min of silence gets the session restarted.
+- Sub-agents are leaves. You may spawn them; they spawn nothing.
+
+## Terminal handoff
+
+Post the run-level report as the run's last comment: on the Feature, or on the Bug in a per-Bug run, never on a PBI. Its first line is the `adl-evidence v1` machine line ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)); then per item the final state, the commits, the sub-agent verdicts and head SHAs; design updates; CI rounds; PR link; verdict. Then one line: `implementation <verdict> feature <id> @ <sha>`, or `implementation <verdict> bug <id> @ <sha>` in a per-Bug run. Never end with an offer or a question.
+
+## Never
+
+- Never write code, tests, docs or specs yourself. Never review. Your files are the run branch's push and scratch only; the design-update LEDGER row is the planner sub-agent's.
+- Never force-push. Never `--no-verify`. Never create a worktree or another branch.
+- Never skip, loosen or delete a test; never accept a sub-agent report without its evidence.
+- Never hand-link items to the PR, hand-move items to Done, set a vote or a PR reviewer.
+- Never send an item to New or In Planning for drift.
+- Never edit `requirements.md` or `intent.md`.