npm - @amsterdamdatalabs/adl-agent-control-linux-x64 - Versions diffs - 0.1.37 → 0.1.46 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/packages/agent-skills/assets/implement-feature/references/briefs.md CHANGED Viewed

@@ -6,7 +6,7 @@ Used by the lead (`implement-feature`). The sub-agent loads `workitems-process`
 ```text
 You are a leaf sub-agent of the implementation lead for <Feature or Bug> <id>. Spawn nothing.
-Worktree: <worktree> (the run's branch <branch>: the Feature branch, or fix/az<bug id>-<slug> in a per-Bug run). Head: <sha>. Run as agent-tarun.
+Worktree: <worktree> (the run's branch <branch>: the Feature branch, or the per-Bug branch in a per-Bug run). Head: <sha>.
 You start with no memory of earlier sub-agents. Read the plan folder, not their transcripts.
 You move no work item state and post nothing on the board. Return one report (format below).
 Skill: <skill name>. Follow it exactly. If this brief and the skill disagree, the skill wins; say so in a finding.
@@ -36,7 +36,7 @@ The lead posts the report as an item comment (Feature comment for `-final`/`fina
 ## validate (architect, skill validate-design)
-- Inputs: plan folder, `BaselineSha`, `against` (`HEAD` of the worktree, which contains the current `integration`: the run starts by merging `origin/integration` into its branch), optional `scope` (one item, for mid-loop drift) and the executor's `DRIFT` finding when there is one.
+- Inputs: plan folder, `BaselineSha`, `against` (`HEAD` of the worktree, which contains the current `integration`: the run starts by merging the integration base into its branch), optional `scope` (one item, for mid-loop drift) and the executor's `DRIFT` finding when there is one.
 - Check **`design.md` and its `file-map-reference.md`** by diffing `<BaselineSha>..HEAD`; record `head_sha`. Do not re-validate `requirements.md`.
 - Read-only. Edit nothing, including `design.md`.
 - Verdicts: `FRESH` · `DRIFT` (exact delta in `findings`: `where` = design section + path, `fix` = replacement text).
@@ -58,7 +58,7 @@ The lead posts the report as an item comment (Feature comment for `-final`/`fina
 ## reproduce, per-Bug run (executor, skill implement-item, reproduce mode)
-- Inputs: Bug id, its G1-approved Description, branch `fix/az<bug id>-<slug>`, the base (the `integration` SHA the branch was created from). The Bug is at In Reproduction.
+- Inputs: Bug id, its G1-approved Description, the per-Bug branch, the base (the integration SHA the branch was created from). The Bug is at In Reproduction.
 - First commit: the Bug's item file `plans/features/az<fixes id>-fixes-to-closed-features/items/az<bug id>-<slug>.md`, with the five bugfix sections of the approved Description plus `## Predecessors` mirroring the board link ([Item files](../../workitems-process/references/ado-and-git.md#5-item-files)), plus its LEDGER row `az<bug id>-bug`. Next: the regression test. **The reproduce commit stays green.** The executor runs the regression test unmarked on the base and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass (`fix(<scope>): add failing regression test for az<bug id> (expected failure)`). Nothing else: no fix in this brief.
 - Verdicts: `DONE` (the item file and the regression test committed, the unmarked test red on the base with that run output, the test committed marked as an expected failure, every commit green, no fix) · `PARK` (won't reproduce, with what was tried).

package/packages/agent-skills/assets/implement-item/SKILL.md CHANGED Viewed

@@ -33,15 +33,15 @@ Not for planning, verifying, reviewing, or CI logs (CI is `fix-ci`).
 ## Preconditions
-1. Worktree toplevel equals the brief's worktree; the branch is the run's branch; `git status --porcelain` is empty or is your own previous attempt.
+1. Worktree toplevel equals the brief's worktree; the branch is the run's branch; the tree is clean or only your own previous attempt.
 2. Every `AC-n` is one unambiguous EARS sentence you can turn into a test. If not, return the one concrete question to the lead and stop. Never pick a conservative reading and carry on.
 3. `design.md` still fits the code for your files. If a named file or symbol is gone or the approach breaks a boundary: `DRIFT`, before any edit.
 ## Procedure
-0. **Bug item file (reproduce mode).** Write `plans/features/az<fixes id>-fixes-to-closed-features/items/az<bug id>-<slug>.md` from the G1-approved Bug Description, with the Bug item-file sections: the Description's five bugfix sections plus `## Predecessors` mirroring the board link, always present and reading `none` for the first Bug ([Item files](../workitems-process/references/ado-and-git.md#5-item-files)), and its `plans/LEDGER.md` row `az<bug id>-bug`. Commit it first (`docs(plans): add item file for az<bug id> <slug>`, `AB#<bug id>` in the body). Change nothing the Description does not say; a gap is a question to the lead.
+0. **Bug item file (reproduce mode).** Write `plans/features/az<fixes id>-fixes-to-closed-features/items/az<bug id>-<slug>.md` from the G1-approved Bug Description, with the Bug item-file sections: the Description's five bugfix sections plus `## Predecessors` mirroring the board link, always present and reading `none` for the first Bug ([Item files](../workitems-process/references/ado-and-git.md#5-item-files)), and its `plans/LEDGER.md` row `az<bug id>-bug`. Commit it first (`docs(plans): add item file for az<bug id> <slug>`). Change nothing the Description does not say; a gap is a question to the lead.
 1. **Mode.** Rework: list the exact finding ids you will fix; nothing else is in scope.
-2. **Tests first.** For each `AC-n` write or extend the test the design names, with the `AC-n` in the test name or a comment. Run it. It must be **red for the right reason** (assertion on the missing behaviour, not an import or syntax error). Reproduce mode: the regression test reproduces the reported defect; the Bug's item file is the plan (no `AC-n` from `requirements.md`; the file's EARS criteria stand in). **The reproduce commit stays green.** The executor runs the regression test unmarked on the base (the `integration` SHA the `fix/` branch was created from) and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass (`fix(<scope>): add failing regression test for az<bug id> (expected failure)`, `AB#<bug id>` in the body). The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception. Then skip to step 8: reproduce mode writes no fix, no docs and no other code.
+2. **Tests first.** For each `AC-n` write or extend the test the design names, with the `AC-n` in the test name or a comment. Run it. It must be **red for the right reason** (assertion on the missing behaviour, not an import or syntax error). Reproduce mode: the regression test reproduces the reported defect; the Bug's item file is the plan (no `AC-n` from `requirements.md`; the file's EARS criteria stand in). **The reproduce commit stays green.** The executor runs the regression test unmarked on the base (the integration SHA the per-Bug branch was created from) and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass (`fix(<scope>): add failing regression test for az<bug id> (expected failure)`). The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception. Then skip to step 8: reproduce mode writes no fix, no docs and no other code.
 3. **Minimal code** until those tests pass (bug mode: until the committed regression test, with its expected-failure mark removed in the fix commit, and the item file's EARS criteria pass normally). No speculative options, no unrelated refactors, no new abstraction unless the code needs it.
 4. **Docs in the same change.** Write every doc `design.md` `## Docs impact` lists for this item (per-Bug run: every doc the fix makes wrong).
 5. **Slop pass** on changed files only: dead code, debug leftovers, needless wrappers, duplication, swallowed errors, masking fallbacks, stray TODOs. Delete rather than wrap. Then re-run step 6.

package/packages/agent-skills/assets/mechanics/SKILL.md CHANGED Viewed

@@ -23,7 +23,7 @@ How adl behaves on every machine and in every repository it controls.
 ## Git and Azure DevOps operations
 - Use ordinary `git` for every Git operation. The managed `/usr/local/bin/git` front controller hands local and non-Azure DevOps work to the system Git, and routes HTTPS Azure DevOps network commands through `adl-agent-id exec --agent "$ADL_AGENT_ID_AGENT"`. `git-ado` handles the credential boundary; there is no second account or secret location.
-- PRs, work items and builds go through the `adl` MCP server (`adl mcp serve`): `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update`. If the server is not working, fall back to `adl mcp cli <command>`.
+- PRs, work items and builds go through the `adl` MCP server (`adl mcp serve`): `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update_feature`, `workitem_create_or_update_pbi`, `workitem_create_or_update_bug`. If the server is not working, fall back to `adl mcp cli <command>`.
 ## Repository controls

package/packages/agent-skills/assets/plan-feature/SKILL.md CHANGED Viewed

@@ -26,12 +26,12 @@ Load `workitems-process` first. This card adds only what the planning run does.
 | `worktree` | `docs/az<feature>-<slug>-plan`, made by adl-dispatcher |
 | `resume_notes` | The previous session's tail, if any |
-Branch: `docs/az<feature>-<slug>-plan`, created by adl-dispatcher. A re-entry reuses the same branch. Identity: `agent-tarun`.
+Branch: the planning branch, created by adl-dispatcher. A re-entry reuses the same branch.
 ## Preconditions
 1. `workitems-process` universal preconditions (worktree, board state, identity). The state check is on the Feature: New or In Progress.
-2. `plans/features/az<feature>-<slug>/intent.md` exists on `origin/integration` and its `work_item` id equals the folder id. If not, the trigger does not hold: report the mismatch on the Feature and end the run; the next tick re-evaluates.
+2. `plans/features/az<feature>-<slug>/intent.md` exists on the integration base and its `work_item` id equals the folder id. If not, the trigger does not hold: report the mismatch on the Feature and end the run; the next tick re-evaluates.
 3. The Feature has an Epic parent and at least one predecessor Feature (the very first Feature has none), and every predecessor is at Awaiting Release or Done. If not, report what is missing on the Feature and end the run; the Epic and the links are authored by the human, never created or guessed by you.
 4. Resume: read the board and the branch first. Reuse allocated ids; never allocate twice.
@@ -41,10 +41,10 @@ Branch: `docs/az<feature>-<slug>-plan`, created by adl-dispatcher. A re-entry re
 ### 1. Orient and pin the baseline
-1. Read `intent.md`, the predecessor Features' plan folders on `origin/integration`, the existing plan folder if any, and every G1 finding or reviewer finding left on the Feature and its items (comment read tool pending T1).
+1. Read `intent.md`, the predecessor Features' plan folders on the integration base, the existing plan folder if any, and every G1 finding or reviewer finding left on the Feature and its items (comment read tool pending T1).
 2. Understand the code: `crg architecture`, `crg query callers_of|tests_for <symbol>`, `crg impact`. You may spawn read-only explore sub-agents on the fast tier; they write nothing.
-3. Re-entry on an existing plan branch: `git fetch origin integration` and `git merge --no-edit origin/integration` into it. Never recreate, rebase or force-push it.
-4. **Baseline Sha** = the exact `origin/integration` SHA you read. It goes in `file-map-reference.md` `## Baseline` and in the Feature's Baseline Sha field.
+3. Re-entry on an existing plan branch: bring it current with the integration base. Never recreate, rebase or force-push it.
+4. **Baseline Sha** = the exact integration SHA you read. It goes in `file-map-reference.md` `## Baseline` and in the Feature's Baseline Sha field.
 5. **Revision N.** The revision increments once per G1 submission: N = current `Plan Revision` + 1 when this run follows a G1 decision (rework or requeue) or is the first run (N = 1). A resumed or re-dispatched run with no G1 decision since the last revision keeps N. The review rounds inside one planning run share N. Read the board fields; named arguments are pending T3, so until then they pass through `--fields` as `Custom.PlanRevision`, `Custom.PlanHash`, `Custom.BaselineSha` (reference names not yet confirmed through the API).
 ### 2. Draft
@@ -59,7 +59,7 @@ Branch: `docs/az<feature>-<slug>-plan`, created by adl-dispatcher. A re-entry re
    - A touchpoint in `## Size estimate` is a `file-map-reference.md` row of Kind `change` or `new`.
 3. **`file-map-reference.md`**: every path the plan touches: read / change / new, why, items. `## Baseline` = Baseline Sha.
 4. **`## Revision log`** row for revision N, written once per revision (Trigger: first plan, `G1 rework` or `G1 requeue`; Changes: what changed since N-1, including every added or dropped item and changed AC). Review rounds of N update that row's Changes cell, never add a row.
-5. **Items.** First match every existing child PBI of the Feature to the planned items (by id, then by title or slug). Never allocate a second item for work already on the board. Then allocate each planned item with no board item **before** its file: `workitem_create_or_update --type 'Product Backlog Item' --title ... --parent-id <feature>`. Then move every in-scope PBI (existing and new) New -> In Planning. Only then, in the write-files step, write the ids into `## Items` and write `items/az<id>-<slug>.md` with the item-file sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#5-item-files). Items that already exist are updated, not duplicated. If allocation fails partway, move the PBIs you did allocate New -> In Planning and stop; nothing is committed before the move. The lead re-allocates the rest on the next tick, in the same worktree and branch.
+5. **Items.** First match every existing child PBI of the Feature to the planned items (by id, then by title or slug). Never allocate a second item for work already on the board. Then allocate each planned item with no board item **before** its file: `workitem_create_or_update_pbi --title ... --parent-id <feature> --description "## What it delivers\n…\n\n## Verification\n…" --effort <days>`. Mandatory at create: `title`, `parentId` (Feature), `description` (must carry `## What it delivers` + `## Verification` headings), `effort` (number, days, ≥0; float accepted). Then move every in-scope PBI (existing and new) New -> In Planning. Only then, in the write-files step, write the ids into `## Items` and write `items/az<id>-<slug>.md` with the item-file sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#5-item-files). Items that already exist are updated, not duplicated. If allocation fails partway, move the PBIs you did allocate New -> In Planning and stop; nothing is committed before the move. The lead re-allocates the rest on the next tick, in the same worktree and branch.
    - **Item-split rules.** One PBI = one observable outcome from `intent.md` that fits one PR and can be specified, tested and reviewed on its own. Never split by layer (no "backend item" plus "frontend item" for one outcome). Slug is kebab (`^[a-z0-9]+(-[a-z0-9]+)*$`, <= 40 chars); title is written as an outcome. Prefer fewer, larger-than-trivial items over fragments. Cover every goal in `intent.md`; respect every non-goal. Items carry no predecessors; the lead orders items inside the loop.
 6. **Describe the loop as non-linear.** Where a plan mentions In Implementation, In Testing, In Review and Updating Docs, it says they are free moves ([States at a glance](../workitems-process/SKILL.md#states-at-a-glance)).
@@ -83,14 +83,14 @@ Branch: `docs/az<feature>-<slug>-plan`, created by adl-dispatcher. A re-entry re
 1. Check the `## Revision log` row for N names every change of the rounds.
 2. **Plan Hash = sha256 of `requirements.md` only**: `shasum -a 256 plans/features/az<feature>-<slug>/requirements.md` at the commit you push. The hash lives on the board, never inside a file.
-3. Write the Feature fields: `Plan Revision` = N, `Plan Hash`, `Baseline Sha` (`workitem_create_or_update --id <feature> ...`; named arguments pending T3, writability by this identity unconfirmed). A refused write: post the exact refusal text as a Feature comment and take the path the refusal names; never work around it.
+3. Write the Feature fields: `Plan Revision` = N, `Plan Hash`, `Baseline Sha` (`workitem_create_or_update_feature --id <feature> --state 'In Progress' --plan-revision N --plan-hash S --baseline-sha S --acceptance-criteria "..." --comment "..."`; the move to `In Progress` triggers the state-conditional gate, so `acceptanceCriteria`, the three plan fields, and a non-empty `comment` are all mandatory). A refused write: post the exact refusal text as a Feature comment and take the path the refusal names; never work around it.
 4. Prepare the plan snapshot `plan-r<N>-<sha7>.md` (`<sha7>` = first 7 chars of Plan Hash) in `.scratchpad/`: `requirements.md`, `design.md`, `file-map-reference.md`, then every item file, in one file ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). How the content reaches the tool is pending P4: the tool attaches it and refuses to raise the PR without it.
 5. Append one row per `plans/` commit to `plans/LEDGER.md`.
 6. Every in-scope PBI is at In Planning before the planning PR is raised: after allocating any new PBIs you moved every in-scope PBI (existing and new) New -> In Planning, then wrote the files (§2 step 5). Do nothing else to item states.
 ### 6. Raise the planning PR
-- `pr_create_or_update`: title `docs(plans): plan az<feature> <slug>`, head `docs/az<feature>-<slug>-plan`, target `integration`, with the five PR body sections ([ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git)); `## Test plan` and `## Security impact considered` say "none (docs-only)".
+- `pr_create_or_update`: title `docs(plans): plan az<feature> <slug>`, on the planning branch, targeting integration, with the five PR body sections (Summary, Why, Changes, Test plan, Security impact considered); `## Test plan` and `## Security impact considered` say "none (docs-only)".
 - **The tool does the board wiring; you pass nothing and move nothing** ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)).
 - No reviewer, no vote. Never force-push.
 - Read back every item: state Awaiting Approval. If the tool did not move them (it cannot until P2 ships), report the gap and end the run. Do not move them by hand and do not work around it.
@@ -115,14 +115,14 @@ A Fixes Bug has its own ladder and no plan folder ([Bug states](../workitems-pro
 ## Mode B: design update (sub-agent)
 - Brief from the implementation lead: the Feature, the branch head, the drift (`design.md` vs the repo).
-- Your write scope is exactly four things: `design.md` (`file:line` refs, `## Solution`, `## Verification` rows, `## Docs impact`, `## Size estimate`); `file-map-reference.md` (its `## Map` where the map changed, and its `## Baseline` section, set to the new `origin/integration` base); the Feature's `Baseline Sha` field, set to the same base; and the `plans/LEDGER.md` row `az<id>-design-update`. Plan Revision and Plan Hash are unchanged: the hash covers `requirements.md` only, which you never touch, nor item files.
+- Your write scope is exactly four things: `design.md` (`file:line` refs, `## Solution`, `## Verification` rows, `## Docs impact`, `## Size estimate`); `file-map-reference.md` (its `## Map` where the map changed, and its `## Baseline` section, set to the new integration base); the Feature's `Baseline Sha` field, set to the same base; and the `plans/LEDGER.md` row `az<id>-design-update`. Plan Revision and Plan Hash are unchanged: the hash covers `requirements.md` only, which you never touch, nor item files.
 - Commit on the lead's Feature branch as one docs commit carrying the LEDGER row. The lead writes no file; it records the update in the implementation report and the PR.
 - Drift that would need an approved `AC-n` changed: do not edit; return it to the lead as a finding. The lead's path is in [No block](../workitems-process/SKILL.md#no-block).
 - Return a summary to the lead (files changed, new baseline, what moved). You are a leaf: spawn nothing.
 ## Commits
-`<type>(<scope>): <lowercase subject>`, type `docs` for plan files. Each commit green. One topic per commit. Never `git stash`. Planning commits carry no `AB#` (the tool links the items).
+`<type>(<scope>): <lowercase subject>`, type `docs` for plan files. Each commit green. One topic per commit. Planning commits carry no `AB#` (the tool links the items).
 ## Stop rules

package/packages/agent-skills/assets/prepare-promotion/SKILL.md CHANGED Viewed

@@ -31,11 +31,11 @@ pipeline opens the promotion PR; you only write its description. G2 is human. Lo
 1. Exactly one open PR with source `integration` and target `main` (`pr_list_or_get`). Never open one yourself. None or several: report what you found and stop.
 2. `main` equals `base_sha`; else write the summary against the current `main` and record it as `base_sha`. If the PR head differs from `head_sha`, write the summary against the current head and record it as `head_sha`.
-3. `worktree` is `none` (skip the check), or `git rev-parse --show-toplevel` equals it.
+3. `worktree` is `none` (skip the check), or the worktree toplevel equals it.
 ## Procedure
-1. **Range.** Commits in `<base_sha>..<head_sha>` (PR commits, or `git log --oneline` in a read-only
+1. **Range.** Commits in `<base_sha>..<head_sha>` (PR commits, or the commit log in a read-only
    checkout). Collect work items: PR-linked items plus every `AB#<id>` in commit messages.
 2. **Included items.** For each id (`workitem_list_or_get`): type, title, state, link, the merged Feature
    PR link. Any item not Done → list it under risks with its state (it rode in on a shared commit).
@@ -55,8 +55,7 @@ pipeline opens the promotion PR; you only write its description. G2 is human. Lo
    table: id, type, title, state, PR; then the notable risks and the rollback note), `## Test plan`
    (the integration validation runs), `## Security impact considered` (security notes from the
    included items' code reviews, or "none" with those reports as the source), and a footer line
-   `release-summary @ <head_sha>`. These are the five PR body sections in
-   [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git). Keep any text a human added above the summary.
+   `release-summary @ <head_sha>`. These are the five PR body sections. Keep any text a human added above the summary.
 7. Read the PR back and confirm the description saved with the footer SHA.
 8. Post the report (see below).

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

@@ -22,7 +22,7 @@ Load `workitems-process` first. Any agent may use this card; it is the only inta
 ## 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.
+2. **Find the responsible Feature.** The Feature whose scope should have got this right (work item links, the commit log and annotation, `requirements.md`; for a red pipeline, the merged Feature, or for a per-Bug PR the merged Bug's Responsible Feature). Unclear -> report it to your caller as a finding; never guess.
 3. **Duplicate check.** Re-runs never add duplicate comments.
    - **Red pipeline:** a red pipeline is filed only when the LATEST completed run of the `integration` or `main` pipeline is red AND its build id is named in no Bug's `## Failing builds` (any state). Search every Bug, in any state, for this build id first: named -> stop, with nothing to do. Then search open Bugs (New through Updating Docs) for the same failure (same failing test or job). Found -> append the build id to that Bug's `## Failing builds` in its board Description (that section only; the approved sections stay unchanged), post no comment, and stop. Otherwise file a new Bug (step 5) with the same Responsible Feature; if an earlier Bug (Done or Parked for Removal) names the same failure, that Bug is its predecessor. Older runs are never filed. A run already named never files again. Once named, a red `main` run waiting for promotion and the last red `integration` run before the fix's next run both stay quiet.
    - **Finding:** search open PBIs/Bugs covering the same behaviour. Found -> add a comment citing your repro, unless a comment there already cites the same repro, and stop.
@@ -35,7 +35,7 @@ Load `workitems-process` first. Any agent may use this card; it is the only inta
 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:
+   2. Allocate on the board: `workitem_create_or_update_bug --title ... --parent-id <Fixes Feature> --description "..." --effort <days>`. State stays New. Mandatory at create: `title`, `parentId` (a Feature — typically the Fixes Feature), `description` (must carry the five bugfix headings `## Current behaviour` / `## Expected behaviour` / `## Behaviour that must not change` / `## Responsible Feature` / `## Verification`), and `effort` (number, days, ≥0; float accepted). Plan fields are forbidden (T3 — hard). `comment` is mandatory on every update (on create `comment` is optional). Predecessor: at most one, only when the Fixes Feature already holds another Bug (L4); none for the first Bug. Related: required when the parent is the Fixes Feature (the related link points to the Responsible Feature) (L4). The Description must carry the bugfix shape:
       | Section | Holds |
       |---|---|

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

@@ -18,7 +18,7 @@ There is **no PR reviewer, no vote and no PR thread** before the merge ([Human g
 | 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 |
+| **final** (Feature-final) | The full diff against the integration base, every item |
 | **delta** | After a CI fix: the fix commits only, plus what they touch |
 - `lane: code` → role `code-reviewer`. `lane: architecture` → role `architect`.
@@ -31,12 +31,12 @@ There is **no PR reviewer, no vote and no PR thread** before the merge ([Human g
 ## 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).
+2. The worktree toplevel equals the worktree; record the branch head as `head_sha` and review that SHA (diff `<base_sha>..<head_sha>`, read `<head_sha>:<path>`). A HEAD that differs from the named head SHA, or moves during the review, never stops or restarts it: say so in the report; the lead re-runs you at the new head ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
 3. A verify `PASS` at this head exists in the brief; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 ## Procedure
-1. **Scope.** `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.
+1. **Scope.** Diff the file set against `<base_sha>..<head>` (item mode: the item's commits); read every changed file in full, plus callers and tests of changed symbols. Do not widen into unrelated code.
 2. **Criteria map.** For each `AC-n` in scope, find the code and the test that covers it. An unmapped `AC-n` is a finding.
 3. **Review your lane** (below). Every finding gets `id`, `severity`, `where` (path:line), `what` (issue and risk), `fix` (concrete). Separate fact from suggestion.
 4. **Verdict** by the lane rule. No partial or conditional approvals.

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

@@ -25,18 +25,18 @@ Load `workitems-process` first. One skill, two lanes; the brief's `lane` picks o
 | `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 |
+| `base_sha` | The integration SHA the plan is written against |
 | `lane` | `architect` or `critic` |
 | `architect_review` | Critic only: the Architect's full review for N |
 | `round` | review round within revision N, 1..3 |
 | `prior_findings` | Earlier findings (earlier rounds of N, G1 findings) and how each was answered |
-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).
+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)).
+2. The sha256 of `requirements.md` at `plan_commit` equals `plan_hash`, and its Revision log last row is N. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 3. All of `intent.md`, `requirements.md`, `design.md`, `file-map-reference.md` and `items/*.md` are readable at `plan_commit`. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 4. Critic only: `architect_review` is in the brief and is for revision N. Else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)). The Critic never reviews first.
@@ -44,7 +44,7 @@ Identity: `agent-tarun`. Independence is a fresh context, not another identity.
 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`.
+2. Read the baseline code `design.md` `## Solution` names: read `<base_sha>:<path>`. Each ref exists at `base_sha` or is marked `(new)`. Use `crg impact` / `crg query callers_of <target>` for blast radius, else `rg`.
 3. Prior findings: every finding id an earlier round or G1 raised is `addressed` or `declined` with a reason (the planner's round comment for review findings, the Revision log for G1 findings). A silently dropped finding is a finding.
 4. Fidelity to the intent: nothing in `requirements.md` contradicts or exceeds `intent.md`'s Constraints and Non-goals.

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

@@ -27,7 +27,7 @@ Run record (`prompts/workitem-triage.md`): `key` = repo, `feature_id` null, `wor
 ## 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.
+2. The integration base is current. Evidence is read from the integration base, not from a branch you happen to be on.
 3. Board reads work (`workitem_list_or_get`, then `adl mcp cli` as fallback). Cannot read the board on either route: report both errors and end the run; the next tick re-dispatches.
 ## Procedure
@@ -35,8 +35,8 @@ Run record (`prompts/workitem-triage.md`): `key` = repo, `feature_id` null, `wor
 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;
+   - code on the integration base: what exists, what tests cover;
+   - the Feature implementation branch, the per-Bug branch, or the planning branch, plus the PR, merge commit and CI state;
    - the item's comments (comment read: pending T1 in adl-agent-control);
    - its Feature, parent Epic and the Feature's predecessors.
 3. **Judge the true state.** Partly done is a valid answer (some criteria met on `integration`, others not). No blanket "unknown -> New".
@@ -82,7 +82,7 @@ Run record (`prompts/workitem-triage.md`): `key` = repo, `feature_id` null, `wor
 - 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).
+- The run report, as the last action, goes to the activity log with `adl activity add` ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports)). Content: `base_sha` = integration base SHA, counts (applied / proposed / unchanged), the id lists, split-off ids, rolled-up Feature ids, Bugs filed for red pipelines, unplanned Features (informational).
 ## Stop rules

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

@@ -20,24 +20,18 @@ Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-f
 ## 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`.
+- 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 the integration base 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).
+1. Worktree toplevel equals the brief's worktree; the branch head is printed and recorded as `head_sha`.
+2. `<BaselineSha>` is an ancestor of `HEAD`. If not, return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+3. The tree is clean (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.
+2. **Measure change since baseline.** Diff the file set against `<BaselineSha>..HEAD`; the per-path rename and status view; the commit log over the surface. For each symbol, find it at `HEAD` 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.**
@@ -60,7 +54,7 @@ Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-f
 ## 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)).
+- Same tool failure twice: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
 ## Never

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

@@ -23,20 +23,20 @@ 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).
+- 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 per-Bug 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.
+1. The worktree 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 the branch 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. The tree is clean 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.
+3. **Bug regression proof** (Bug items). You must not change HEAD in the shared worktree. Export the base into `.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;
@@ -45,7 +45,7 @@ Not for fixing code or reviewing style.
    - 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.
+6. **Clean up.** Remove temp files and processes; the tree is clean 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.

package/packages/agent-skills/assets/wayfinder/SKILL.md CHANGED Viewed

@@ -15,7 +15,7 @@ The destination varies per effort, and naming it is the first act of charting
 ## Do Not Use When
-- The work is already small enough for one session, or is execution-shaped (slicing an already-decided plan into build tickets) rather than decision-shaped — use `to-workitems` instead.
+- The work is already small enough for one session, or is execution-shaped (slicing an already-decided plan into build tickets) rather than decision-shaped — use `workitems-process` instead.
 ## Plan, don't do

package/packages/agent-skills/assets/workitems-process/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: workitems-process
-description: Shared reference every adl run loads first - the three dispatcher targets and their triggers, the run record, roles and write scopes, work item states, the human gates, the no-block rule, run evidence, adl MCP/CLI commands, identity, plan and item files, branch, commit and PR grammar. Load it at the start of every session, before the target skill, and whenever a run must decide a transition or write a report.
+description: Shared reference every adl run loads first - the three dispatcher targets and their triggers, the run record, roles and write scopes, work item states, the human gates, the no-block rule, run evidence, adl MCP/CLI commands, plan and item files. Load it at the start of every session, before the target skill, and whenever a run must decide a transition or write a report.
 metadata:
   step: "shared"
   role: "all"
@@ -12,13 +12,13 @@ metadata:
 This skill is the package's single owner of the process rules. Every other skill, agent and prompt in the package links to a section here and does not restate it.
 Tags: **[live]** = enforced today. **[pending X]** = change row `X` that is not built yet: rows F, L, P, T, H, R, S, A, V are adl-agent-control changes; rows X are adl-dispatcher changes. Never act as if a pending change is live.
-Sections: [Targets and triggers](#targets-and-triggers) · [The run record](#the-run-record) · [Roles](#roles) · [States at a glance](#states-at-a-glance) · [Human gates](#human-gates) · [No block](#no-block) · [Evidence and reports](#evidence-and-reports) · [ADO, identity, files, git](#ado-identity-files-git) · [Universal preconditions](#universal-preconditions-every-run) · [Universal stop rules](#universal-stop-rules) · [Terminal handoff](#terminal-handoff).
-References: [`references/workitem-states.md`](references/workitem-states.md) (states, moves, links), [`references/evidence.md`](references/evidence.md) (reports, verdicts), [`references/ado-and-git.md`](references/ado-and-git.md) (tools, identity, plan and item files, git, PR wiring).
+Sections: [Targets and triggers](#targets-and-triggers) · [The run record](#the-run-record) · [Roles](#roles) · [States at a glance](#states-at-a-glance) · [Human gates](#human-gates) · [No block](#no-block) · [Evidence and reports](#evidence-and-reports) · [ADO and files](#ado-and-files) · [Universal preconditions](#universal-preconditions-every-run) · [Universal stop rules](#universal-stop-rules) · [Terminal handoff](#terminal-handoff).
+References: [`references/workitem-states.md`](references/workitem-states.md) (states, moves, links), [`references/evidence.md`](references/evidence.md) (reports, verdicts), [`references/ado-and-git.md`](references/ado-and-git.md) (tools, plan and item files, PR wiring).
 ## When to use
 - At the start of every dispatched session, before the target skill's procedure.
-- Whenever you must choose a transition, write a report, call ADO, or name a file, branch, commit or PR.
+- Whenever you must choose a transition, write a report, call ADO, or name a file.
 ## Targets and triggers
@@ -31,10 +31,10 @@ References: [`references/workitem-states.md`](references/workitem-states.md) (st
 - A Feature takes two runs: one planning run, then one implementation run. A Fixes Bug takes one run: the per-Bug implementation run. One run = one worktree, one terminal, one lead session that orchestrates its sub-agents.
 - **Ready:** a Feature is ready when every predecessor Feature is at Awaiting Release or Done.
 - **`workitem-triage` fires on any of:** an open PBI or Bug off the ladder (`Committed` included); an item whose state may not match its evidence; a Feature roll-up is due; a Feature with no parent Epic, or (all but the first) no predecessor Feature; a red pipeline **[pending X4]**. 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). Then: if an open Bug (New through Updating Docs) names the same failure, append the build id to it, with no comment. Otherwise file a new Bug through `report-bug`; 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. Done proof: each latest completed run is green or its build id is named by a Bug.
-- **`planning` fires on either:** a Feature at New whose `intent.md` is on `origin/integration` and which is ready; or a Feature at In Progress with any child at New or In Planning (the G1 rework or requeue re-fire) **[pending X1]**. Nothing queues it. It never fires on a Bug, and never on a `Fixes to closed Features` Feature: its Bugs at New are not planned (G1 approves each Bug's Description, then X2).
+- **`planning` fires on either:** a Feature at New whose `intent.md` is on the integration base and which is ready; or a Feature at In Progress with any child at New or In Planning (the G1 rework or requeue re-fire) **[pending X1]**. Nothing queues it. It never fires on a Bug, and never on a `Fixes to closed Features` Feature: its Bugs at New are not planned (G1 approves each Bug's Description, then X2).
 - **`implementation` fires per Feature on all of:** every in-scope item (not Parked for Removal or Removed) is at Approved or later; at least one in-scope item is not Done; the Feature is ready; the Feature's planning PR is merged into `integration` **[pending X5]**. A `Fixes to closed Features` Feature never fires it under the Feature key; each of its Bugs fires alone, keyed by the Bug, at Approved through Updating Docs, until its PR merges (the X12 done proof) **[pending X2]**. A Bug at Approved starts a fresh run; a Bug at In Reproduction through Updating Docs is a died or `PR_OPEN` run, resumed from the Bug's state.
 - CI is not a target; it is the last stage of implementation (ADR-019).
-- **The dispatcher is a trigger:** code, no LLM. It reads the board, PRs, pipelines and branches, picks targets in rank order, creates the branch and worktree, and starts one session. It writes nothing to ADO. Every board write is made by the session it starts or by adl-agent-control.
+- **The dispatcher is a trigger:** code, no LLM. It reads the board, PRs, pipelines and branches, picks targets in rank order, and starts one session. It writes nothing to ADO. Every board write is made by the session it starts or by adl-agent-control.
 - **No attempt cap.** While a key's trigger holds, the same key is re-dispatched into the same worktree and branch, and the lead resolves the cause. A session silent for 20 min is interrupted; the trigger still holds, so the key is re-dispatched.
 - Live-session skills are never dispatched: `write-feature` (creates a Feature with its `intent.md`), `report-bug` (the only intake for findings, usable by any agent).
@@ -51,11 +51,11 @@ Rendered by `prompts/_envelope.md`. Fields: `target`, `agent`, `skill`, `key`, `
 | Agent | Kind | Write scope |
 |---|---|---|
-| `triager` | lead, `workitem-triage` | the board only: states, splits, merges, comments and predecessor links. Never writes files, never pushes |
+| `triager` | lead, `workitem-triage` | the board only: states, splits, merges, comments and predecessor links. Never writes files |
 | `planner` | lead, `planning`; sub-agent in `implementation` (design update) | the Feature's plan folder, the Feature plan fields, item fields; as a sub-agent only `design.md`, `file-map-reference.md` (its `## Baseline` section and the map rows), the Feature's Baseline Sha and the LEDGER row `az<id>-design-update` |
-| `lead` | lead, `implementation` | board moves; pushes the run branch. Writes no files, never reviews |
+| `lead` | lead, `implementation` | board moves. Writes no files, never reviews |
 | `architect`, `critic`, `code-reviewer` | leaf | none; returns a report |
-| `executor` | leaf | commits on the run branch, in its assigned files only (in a per-Bug run: the Bug's item file and the regression test, marked as an expected failure, first) |
+| `executor` | leaf | commits in its assigned files only (in a per-Bug run: the Bug's item file and the regression test, marked as an expected failure, first) |
 | `verifier` | leaf | scratch test harness only, never committed |
 | `writer` | leaf | none; returns the PR body and implementation report text |
 | explore sub-agent | leaf, read-only, fast tier | none |
@@ -82,11 +82,11 @@ Feature: `New → In Progress → Awaiting Release → Done`, plus `Removed`; li
 | Gate | Decision | Who |
 |---|---|---|
 | **G1** | PBIs: Awaiting Approval → Approved (rework → In Planning, requeue → New), on the exact plan revision. Bugs: New → Approved, on the Bug's Description. After the planning cap the best version goes to G1 with its open findings | Tarun, on the board |
-| **G2** | the `integration → main` promotion PR (not an item state) | Tarun |
+| **G2** | the promotion PR (not an item state) | Tarun |
 | **G3** | Parked for Removal → Removed (revive → New) | Tarun |
 Agents NEVER: move an item to Approved, Done or Removed; set Awaiting Approval by hand (`pr_create_or_update` does, pending P2); revive a parked item; approve or merge the promotion PR; auto-approve on human silence.
-**No reviewer and no vote on any PR before the merge to `integration`.** CI plus auto-complete merges the PR. Review is the loop's In Review state inside the run; findings go to item comments and the implementation report.
+**No reviewer and no vote on any PR before the merge.** CI plus auto-complete merges the PR. Review is the loop's In Review state inside the run; findings go to item comments and the implementation report.
 ## No block
@@ -99,7 +99,7 @@ Agents NEVER: move an item to Approved, Done or Removed; set Awaiting Approval b
 | Design drift | A planner sub-agent updates `design.md`, `file-map-reference.md` (its `## Baseline` section and the map rows) and the Feature's Baseline Sha (the new `integration` base), and adds the LEDGER row `az<id>-design-update`; Plan Hash is unchanged, since it covers `requirements.md` only. Validation runs again; nothing moves to New or In Planning |
 | Code drift in the loop | In Implementation → Design Validation, re-validate, continue (pending F1) |
 | Drift that would need an approved `AC-n` changed | `requirements.md` stays frozen. The lead delivers every other `AC-n`, comments the reason on that PBI and moves it to Parked for Removal (G3). If the outcome is still wanted, the next Feature plans it |
-| CI red | `fix-ci`, smallest fix; expired or cancelled check → scoped `build_run` (pending H1); `integration` moved → merge `origin/integration` |
+| CI red | `fix-ci`, smallest fix; expired or cancelled check → scoped `build_run` (pending H1) |
 | Finding in review or verify | Back into the loop, only the listed findings |
 | Bug in a closed Feature | `report-bug` |
 | Tool refusal (fence or hook) | Post the refusal text as an item comment; take the path the refusal names |
@@ -112,27 +112,25 @@ Agents NEVER: move an item to Approved, Done or Removed; set Awaiting Approval b
 - Every run ends with a report as its last action; format, verdicts and per-target content: [`references/evidence.md`](references/evidence.md).
 - Sub-agents return a report to the lead; the lead posts it. Sub-agents post nothing and move nothing.
-- **One head rule for every lane.** A lane that judges the branch (validate, verify, verify-final, review-code, review-architecture, finalize) records `head_sha` (`git rev-parse HEAD`) at its start and finishes against it: it reads, diffs and tests that SHA (`git show <head_sha>:<path>`, `git diff <base>..<head_sha>`, or an export of `head_sha` under `.scratchpad/` to run code), never a later worktree state, and reports it as `head_sha`. A head that moves during the lane, or differs at start from the head the brief named, never stops or restarts the lane; the lane says so in its report. The lead compares the reported `head_sha` with the branch head and re-runs the lane at the new head when the head moved.
+- **One head rule for every lane.** A lane that judges the branch (validate, verify, verify-final, review-code, review-architecture, finalize) records `head_sha` at its start and finishes against it: it reads, diffs and tests that SHA, never a later worktree state, and reports it as `head_sha`. A head that moves during the lane, or differs at start from the head the brief named, never stops or restarts the lane; the lane says so in its report. The lead compares the reported `head_sha` with the branch head and re-runs the lane at the new head when the head moved.
 - Every negative result names `where` and `fix`. A negative verdict without findings is invalid.
 - A run that ends without its done proof leaves the trigger holding; the next tick re-dispatches the key.
-## ADO, identity, files, git
+## ADO and files
 Detail: [`references/ado-and-git.md`](references/ado-and-git.md).
-- ADO goes through the `adl` MCP server: `workitem_list_or_get`, `workitem_create_or_update`, `pr_list_or_get`, `pr_create_or_update`, `pr_review` (no role uses it before the merge), `build_list_or_get`, `build_run` (scoped to the lead's own PR, pending H1). If the server fails, use `adl mcp cli <command>`.
-- Identity is `agent-tarun` for every session. Never read vault files. Never pass a token. Never set `ADL_HUMAN_AZDO`.
+- ADO goes through the `adl` MCP server: `workitem_list_or_get`, `workitem_create_or_update_feature`, `workitem_create_or_update_pbi`, `workitem_create_or_update_bug`, `pr_list_or_get`, `pr_create_or_update`, `pr_review` (no role uses it before the merge), `build_list_or_get`, `build_run` (scoped to the lead's own PR, pending H1). If the server fails, use `adl mcp cli <command>`.
+- Per-type mandatory fields (the agent gate enforces these per type): **Feature** — title + parentId (Epic) + description (must carry the four intent.md headings `## Why` / `## Outcome` / `## Constraints` / `## Non-goals`) + `priority` (literal set `{1, 2, 3, 4}`: 1=Very High, 2=High, 3=Medium, 4=Low); when moving off `New` (e.g. to `In Progress`), additionally `acceptanceCriteria` + `planRevision` + `planHash` + `baselineSha`; `comment` mandatory on every update. **PBI** — title + parentId (Feature) + description (must carry `## What it delivers` + `## Verification`) + `effort` (number, days, ≥0); `comment` mandatory on update. **Bug** — title + parentId (Feature) + description (must carry the five bugfix headings `## Current behaviour` / `## Expected behaviour` / `## Behaviour that must not change` / `## Responsible Feature` / `## Verification`) + `effort` (number, days, ≥0); `comment` mandatory on update. Per-type detail: [`references/ado-and-git.md` §1a](references/ado-and-git.md).
 - Plans: `plans/features/az<feature id>-<slug>/{intent.md,requirements.md,design.md,file-map-reference.md,items/az<id>-<slug>.md}`. The id is allocated on the board **before** its file exists.
 - Findings enter through `report-bug` only.
-- Branches: planning `docs/az<id>-<slug>-plan`, implementation `feat/az<id>-<slug>` (or the fitting type), Fixes Bug `fix/az<bug id>-<slug>`, `intent.md` `docs/az<id>-<slug>`.
-- Activity log: `adl activity add "<note>"` at start and finish (pending A1).
+- Activity log: `adl activity add "<note>"` at start and finish.
 ## Universal preconditions (every run)
-1. `git rev-parse --show-toplevel` equals the record's `worktree`. Mismatch: the run does not start; report expected and actual, and the next tick re-evaluates.
+1. The worktree matches the run record. Mismatch: the run does not start; report expected and actual, and the next tick re-evaluates.
 2. Read the board for the key (`workitem_list_or_get --raw`). It must satisfy the target's trigger. If not, the run does not start; report the state seen. A resumed run (a died or `PR_OPEN` run, re-dispatched into the same worktree and branch) satisfies it while its done proof is unmet: a Feature's items at Approved or later with one not Done, or a Fixes Bug at Approved through Updating Docs until its PR merges. Resume from the board states, never by moving an item back.
 3. Read the key's latest comments for the earlier run's report **[comments readable: pending T1]**; do not repeat an earlier run unchanged.
-4. `adl id whoami` reports `agent-tarun`. Mismatch: the run does not start; report the identity seen.
 ## Universal stop rules
@@ -140,7 +138,7 @@ Detail: [`references/ado-and-git.md`](references/ado-and-git.md).
 - Never spin: if the same command fails twice for the same reason, stop retrying it and take a different path ([No block](#no-block)).
 - Never wait on a person inside a session.
 - Never go silent: 20 min with no streamed output → the session is interrupted and the key re-dispatched, with your session tail as `resume_notes`. Keep producing output; a polling loop prints status.
-- Never create a worktree; only adl-dispatcher does, at most 3 checkouts per repo. Agents never create a branch, with one exception: in Tarun's live `write-feature` session the agent creates the intent branch `docs/az<id>-<slug>` from `origin/integration`. Every other branch, and every worktree, is adl-dispatcher's to create; no agent ever recreates one.
+- Never create a worktree; only adl-dispatcher does. Agents never create a branch, with one exception: in Tarun's live `write-feature` session the agent creates the intent branch from the integration base. Every other branch, and every worktree, is adl-dispatcher's to create; no agent ever recreates one.
 ## Terminal handoff

package/packages/agent-skills/assets/workitems-process/references/ado-and-git.md CHANGED Viewed

@@ -10,7 +10,9 @@ Use the `adl` MCP server tool. If the server is unavailable or errors for a reas
 | MCP tool | CLI fallback | Use for |
 |---|---|---|
 | `workitem_list_or_get` | `adl mcp cli workitem-list-or-get [--id ID] [--ids IDS] [--type TYPE] [--state STATE] [--assigned-to IDENTITY] [--limit N] [--raw]` | Read an item (state, fields, relations, tags); list by type/state |
-| `workitem_create_or_update` | `adl mcp cli workitem-create-or-update [--id ID] [--type 'Feature'\|'Product Backlog Item'\|'Bug'] [--title T] [--description D] [--parent-id ID] [--predecessors ID[,ID…]] [--related ID[,ID…]] [--fields JSON] [--state STATE] [--comment TEXT] [--assigned-to I] [--acceptance-criteria TEXT] [--priority N] [--start-date D] [--target-date D]` | Create items, move state, set fields and links, post comments |
+| `workitem_create_or_update_feature` | `adl mcp cli workitem-create-or-update-feature [--id ID] --title T --parent-id ID --priority 1\|2\|3\|4 --description D [--predecessors ID[,ID…]] [--related ID[,ID…]] [--remove-predecessor ID] [--remove-related ID] [--fields JSON] [--state STATE] [--comment TEXT] [--assigned-to I] [--acceptance-criteria TEXT] [--start-date D] [--target-date D] [--plan-revision N] [--plan-hash S] [--baseline-sha S]` | Create or update a Feature; see §1a below for the per-type mandatory fields |
+| `workitem_create_or_update_pbi` | `adl mcp cli workitem-create-or-update-pbi [--id ID] --title T --parent-id ID --description D --effort FLOAT [--related ID[,ID…]] [--remove-related ID] [--fields JSON] [--state STATE] [--comment TEXT] [--assigned-to I] [--acceptance-criteria TEXT] [--priority 1\|2\|3\|4] [--start-date D] [--target-date D]` | Create or update a PBI; see §1a below |
+| `workitem_create_or_update_bug` | `adl mcp cli workitem-create-or-update-bug [--id ID] --title T --parent-id ID --description D --effort FLOAT [--predecessors ID] [--related ID[,ID…]] [--remove-predecessor ID] [--remove-related ID] [--fields JSON] [--state STATE] [--comment TEXT] [--assigned-to I] [--acceptance-criteria TEXT] [--priority 1\|2\|3\|4] [--start-date D] [--target-date D]` | Create or update a Bug; see §1a below |
 | `pr_list_or_get` | `adl mcp cli pr-list-or-get [--id ID] [--status active\|completed\|abandoned\|all] [--repository R]` | Find the PR, read head SHA, status, merge state |
 | `pr_create_or_update` | `adl mcp cli pr-create-or-update --action create\|update [--pull-request-id ID] [--title T] [--description D] [--auto-complete\|--no-auto-complete] [--merge-strategy Squash] [--delete-source-branch] [--repository R]` | Open or update a PR; also does the PR wiring (§6) **[pending P1/P2/P4]** |
 | `pr_review` | `adl mcp cli pr-review …` | **Not used.** No reviewer and no vote on any PR before the merge to `integration` |
@@ -27,11 +29,42 @@ Tools not built yet (never act as if live):
 | Activity log | A1 | `adl activity add "<note>"` / `adl activity list` write and read `.adl/agent-activity.sqlite` (local, gitignored) |
 Patterns:
-- Move state: `workitem_create_or_update --id <id> --state "<State Name>"`. Use the exact ADO state name.
-- Post a comment: `workitem_create_or_update --id <id> --comment "<text>"`.
+- Move state: `workitem_create_or_update_<type> --id <id> --state "<State Name>"` (the right one per type: `-feature`, `-pbi`, `-bug`). Use the exact ADO state name.
+- Post a comment: `workitem_create_or_update_<type> --id <id> --comment "<text>"`. Comments are mandatory on every update.
 - Supplying `--parent-id` on an update **moves** the item to that parent; the old parent link is removed.
 - The installed CLI accepts only `--merge-strategy Squash`.
+### 1a. Per-type mandatory fields (the canonical reference)
+Use the type-named tool. The agent gate enforces the rules below — calls that violate them are refused, not silently dropped.
+**Feature** — `workitem_create_or_update_feature` / `adl mcp cli workitem-create-or-update-feature`
+- Required on create, and on any update while the Feature is at `New`: `title` (non-empty); `parentId` (must be an Epic); `description` (non-empty AND must carry the four intent.md headings `## Why`, `## Outcome`, `## Constraints`, `## Non-goals`); `priority` (literal set `{1, 2, 3, 4}`: 1=Very High, 2=High, 3=Medium, 4=Low — not any integer). `comment` non-empty on every update.
+- Past `New`, an update carries the `comment` (and whatever it actually changes) — the create fields are not re-sent.
+- State-conditional: when the existing state is `New` and the call moves to `In Progress`, additionally `acceptanceCriteria` (non-empty), `planRevision` (positive integer), `planHash` (non-empty string), `baselineSha` (non-empty string). Without those, the move is refused.
+- Create state is always `New`. Cannot create at any other state.
+- Predecessors: ≥1 unless the project has no non-Fixes Feature yet (L2 soft warning kept).
+**PBI (`Product Backlog Item`)** — `workitem_create_or_update_pbi` / `adl mcp cli workitem-create-or-update-pbi`
+- Required on create: `title` (non-empty); `parentId` (must be a Feature); `description` (non-empty AND must carry `## What it delivers` + `## Verification` headings); `effort` (number, ≥0, days; float accepted).
+- On update: `comment` non-empty — and nothing else. The create fields are not re-sent.
+- Predecessors are forbidden (L3 — soft, via a `warnings` field rather than a hard refusal).
+- Plan fields (`plan-revision`, `plan-hash`, `baseline-sha`) are forbidden (T3 — hard).
+**Bug** — `workitem_create_or_update_bug` / `adl mcp cli workitem-create-or-update-bug`
+- Required on create: `title` (non-empty); `parentId` (must be a Feature, typically a Fixes Feature); `description` (non-empty AND must carry the five bugfix headings `## Current behaviour`, `## Expected behaviour`, `## Behaviour that must not change`, `## Responsible Feature`, `## Verification`); `effort` (number, ≥0, days; float accepted).
+- On update: `comment` non-empty — and nothing else. The create fields are not re-sent.
+- Predecessors: at most one, only when the parent is the `Fixes to closed Features` Feature (L4); for the first Bug in a Fixes Feature, none.
+- `related` is required when the parent is the Fixes Feature (the related link points to the Responsible Feature) (L4).
+- Plan fields are forbidden (T3 — hard).
+**Cross-cutting**
+- `priority` is the literal set `{1, 2, 3, 4}`. Named: 1=Very High, 2=High, 3=Medium, 4=Low. Stored as `Microsoft.VSTS.Common.Priority` (int). Surfaces on the read shape as `priority: number | null`.
+- `effort` is in days, accepts floats. Stored as `Microsoft.VSTS.Scheduling.Effort` (number, ≥0). Surfaces on the read shape as `effort: number | null`.
+- `comment` is mandatory on every update (tarun: "comments field is also mandatory"). Even no-op-shaped updates must carry a comment. On create, `comment` is optional.
+- `AC` is required on Feature only (state-conditional, see above). PBI/Bug read also embeds it; they just don't require it at create.
+- The tool name IS the type. Passing an id of another type (a PBI id to `workitem_create_or_update_feature`, say) is refused by name — there is no blanket write tool to fall back on.
 ## 2. Identity
 - Every session runs as `agent-tarun`; `ADL_AGENT_ID_AGENT` is set when the session starts and selects the identity for every ADO and git network call. `agent-reviewer` exists only for the `integration → main` promotion (G2); no run uses it.