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

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

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

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

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

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

@@ -0,0 +1,71 @@
+---
+name: verify-item
+description: Independently verify one item - or, in Feature-final mode, the whole Feature - at an exact head SHA against its EARS acceptance criteria and adversarial scenarios, read-only, in a fresh context. Use when the implementation lead spawns verifier for the In Testing step of an item, for the Feature-final check, or to re-check a CI-fix delta.
+metadata:
+  step: "verify"
+  role: "verifier"
+  states: "In Testing"
+---
+
+# Verify Item (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). Prove or disprove that the head meets the criteria. Bounded adversarial QA, one pass, no fixing. The item loop is non-linear: you may be called for the same item again after a fix, at a new head.
+
+## When to use
+
+| Mode | Scope |
+|---|---|
+| **item** | One item's `AC-n` list, at the head SHA the lead names. For a Bug the criteria are the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change` |
+| **final** (Feature-final) | Every `AC-n` in `requirements.md`, the full suite, at the final head. In a per-Bug run the criteria are the Bug item file's `## Expected behaviour` (EARS) plus `## Behaviour that must not change`. This is the evidence the merge relies on |
+| **delta** | After a CI fix: the changed paths plus the `AC-n` they touch, at the new head |
+
+Not for fixing code or reviewing style.
+
+## Inputs (from the brief)
+
+- Mode, item id (item/delta), the `AC-n` list with the item's `## Verification` lines, the head SHA, `base_sha` (for Bug proof: the integration SHA the 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. 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 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;
+   - repeated and interrupted runs: run twice, kill mid-run, re-run; idempotence and partial state;
+   - misleading success: success text with non-zero exit, skipped tests counted as passes, swallowed errors;
+   - dirty state: pre-existing untracked files or stale state.
+   Bound every command with a timeout. A flaky result is reported with rerun counts and both run outputs, never a lucky green.
+5. **Harness hygiene.** Temporary tests, fixtures and scripts live only in `.scratchpad/` (gitignored), are never committed, and are deleted before you stop. A harness bug is fixed and rerun before calling it a product defect.
+6. **Clean up.** Remove temp files and processes; 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.
+
+## Verdicts
+
+| Verdict | When | Lead does |
+|---|---|---|
+| `PASS` | All of step 7 holds at the head | Moves the item on (to In Review by default) |
+| `FAIL` | Any `AC-n`, check, bug proof or high/critical scenario fails | Posts findings as an item comment, moves the item → In Implementation (a Bug: → In Fixing) (In Testing → In Implementation pending F1; In Review → In Implementation allowed today) |
+
+Medium/low adversarial findings ride along on `PASS` as notes; they do not block.
+
+## Stop rules
+
+- One pass. Do not loop fix-and-retest.
+- Same scenario errors three times for harness reasons: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never edit product code, tests in the branch, or the plan; never commit, push or change HEAD.
+- Never move an item or post on the board.
+- Never PASS an `AC-n` by reading code alone, or with skipped, quarantined or retried-until-green tests.
+- Never wait unbounded or leave temp harnesses, processes or a dirty worktree behind.

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

@@ -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

@@ -0,0 +1,145 @@
+---
+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, 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"
+  states: "all"
+---
+
+# ADL work items process (shared reference)
+
+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 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.
+
+## Targets and triggers
+
+| Rank | Target | Key | Skill | Lead | Done proof |
+|---|---|---|---|---|---|
+| 0 | `workitem-triage` | repo | `triage-workitems` | `triager` | 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 |
+| 1 | `planning` | Feature (never a Bug) | `plan-feature` | `planner` | every in-scope item at Awaiting Approval **and** the planning PR raised; the run pauses at G1 |
+| 2 | `implementation` | Feature, or one Fixes Bug (Approved through Updating Docs) keyed by the Bug **[pending L5, X2]** | `implement-feature` | `lead` | the one implementation PR merged into `integration` |
+
+- 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 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, 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).
+
+## The run record
+
+Rendered by `prompts/_envelope.md`. Fields: `target`, `agent`, `skill`, `key`, `key_kind` (`repo` | `Feature` | `Fixes Bug`), `feature_id`, `worktree`, `base_sha`, `head_sha`, `identity`, `run_id`. Optional: `findings`, `resume_notes`. Fields that do not apply are `null`.
+
+- Scope is the run key. Touch nothing outside it.
+- `workitem-triage`: `feature_id` is null; the whole open board is in scope.
+- `identity` is always `agent-tarun`.
+- Resume is not a mode. A key whose trigger still holds is re-dispatched in the same worktree and branch: read the board, the branch and any open PR, and continue. Never redo finished work.
+
+## Roles
+
+| Agent | Kind | Write scope |
+|---|---|---|
+| `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. Writes no files, never reviews |
+| `architect`, `critic`, `code-reviewer` | leaf | none; returns a report |
+| `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 |
+
+- **Leads never write files.** File changes are made by `executor` (code, docs, tests, the Bug item file) or by `planner` (plan files).
+- **Spawning:** only the dispatched session lead (`triager`, `planner`, `lead`) spawns sub-agents; sub-agents are leaves. Any lead may spawn read-only explore sub-agents on the fast tier to read the codebase in parallel.
+- **Tiers:** `frontier` = strongest reasoning, `standard` = strong coding, `fast` = cheap and quick. The tier → harness and model mapping is `[tiers]` in `adl/dispatcher.toml`; the agent → tier mapping is `tier:` in each agent file, mirrored in `[roles]`.
+- Reviewer sub-agents preferably run on a different model family from `executor` when the surface allows. Not required: author and reviewer are separated by fresh sub-agent context.
+
+## States at a glance
+
+PBI: `New → In Planning → Awaiting Approval → Approved → Design Validation → In Implementation / In Testing / In Review / Updating Docs → Done`, plus `Parked for Removal → Removed` and `Parked for Removal → New` (revive, human-only).
+
+Bug: `New → Approved → In Reproduction → In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs → Done`, plus `Parked for Removal → Removed` and `Parked for Removal → New` (revive, human-only). Never planned. Detail: [`references/workitem-states.md` § Bug states](references/workitem-states.md#5-bug-states).
+
+Feature: `New → In Progress → Awaiting Release → Done`, plus `Removed`; linear, never backward, rolled up by `workitem-triage`.
+
+- Up to Design Validation the order is strict. The four loop states are a **non-linear loop**: free moves among them, in either direction, per item. The usual order is In Testing before In Review; a default, not a rule.
+- **Fence today [live]:** among the loop states only In Review → In Implementation is allowed (`workflow-rules.ts:81`). Every other loop move, and the drift loop-back In Implementation → Design Validation, are **[pending F1]**. On a refusal: post the exact refusal text as an item comment and take the path the refusal names; never work around it.
+- Who moves what, Feature roll-ups and links: [`references/workitem-states.md`](references/workitem-states.md).
+
+## Human gates
+
+| 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 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.** 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
+
+- Nothing in a run ends blocked or waits on a person. Only G1, G2 and G3 wait on a person, and they are decided on the board. No tag and no state signals a stuck item.
+- When an architect, critic, reviewer, verifier, check or tool stops progress, the **lead resolves it inside the run**: it fixes the cause through a sub-agent, re-runs a sub-agent, sends a planner sub-agent to update `design.md`, or loops the item back. A blocking finding stays valid until the re-run clears it.
+- A sub-agent that cannot proceed returns its report with the obstacle as a finding (`where`, `fix`) and stops. It never decides the path itself.
+
+| Obstacle | Path |
+|---|---|
+| 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) |
+| 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 |
+| Session dies, or run ends with the PR open | The next tick resumes the same worktree and branch |
+| Work already done, partly done or a duplicate | Inside a run: the sub-agent reports it as a finding with proof (a build returns `PARK`), and the lead decides. Outside a run: `workitem-triage` proposes the state, split or merge |
+| Mismatch before the run starts (worktree, board state, identity) | The run does not start; the next tick re-evaluates |
+| A round cap is hit (3 plan-review rounds, 3 finding rounds per item, 3 CI rounds, 2 design-update rounds) | Plan review: the best version goes to G1 with its open findings. Otherwise the lead posts the reason as an item comment and still resolves it in the run with a different approach; an item that cannot be delivered goes to Parked for Removal with proof |
+
+## Evidence and reports
+
+- 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` 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 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_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.
+- Activity log: `adl activity add "<note>"` at start and finish.
+
+## Universal preconditions (every run)
+
+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.
+
+## Universal stop rules
+
+- One run = one target and one key. Finish with its done proof or an explicit verdict; never start another target.
+- 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. 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
+
+End with the run report ([`references/evidence.md`](references/evidence.md)), then one line: `<target> <verdict> <key kind> <id> @ <sha>`. Never end with an offer or a question.

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

@@ -0,0 +1,227 @@
+# ADO tools, identity, plan and item files, git
+
+Part of [`workitems-process`](../SKILL.md). CLI facts are from the installed `adl mcp cli` usage text.
+Tags: **[pending X]** = change row `X`, not built. Never act as if it is live.
+
+## 1. ADO tools
+
+Use the `adl` MCP server tool. If the server is unavailable or errors for a reason other than a refusal, run the same command through `adl mcp cli <command>`. A **refusal** (wrong parent type, route not allowed, fence) is an answer, not an outage: do not retry it through the CLI.
+
+| 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_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` |
+| `build_list_or_get` | `adl mcp cli build-list-or-get [--build-id ID] [--branch B] [--top N] [--tail N]` | Pipeline runs and logs |
+| `build_run` | `adl mcp cli build-run --id ID [--branch B]` | Re-queue only the lead's own PR validation on its source branch **[pending H1]**; denied today |
+
+Tools not built yet (never act as if live):
+
+| Need | Row | Until built |
+|---|---|---|
+| Read a work item's comments | T1 | Not readable by tool (`--raw` shows only the latest History value). A run that cannot read earlier reports works from board states, `git log` and the PR, and re-runs evidence whose head is stale |
+| Attachments on a Feature (read, upload, delete) | T2 | `pr_create_or_update` attaches the mandatory ones itself once P4 ships |
+| Named Feature plan fields | T3 | Pass `Custom.PlanRevision`, `Custom.PlanHash`, `Custom.BaselineSha` through `--fields` (reference names and agent writability not yet confirmed through the API); a refusal: post the exact error as an item comment and take the path it names |
+| 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_<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.
+- Check it with `adl id whoami`. Never override the identity the session was started with.
+- Never read vault files. Never pass a token on a command line or in a file. Never set `ADL_HUMAN_AZDO`.
+- Plain `git` handles Azure DevOps credentials through the managed front controller; never configure credentials yourself.
+
+## 3. Hierarchy
+
+- **Epic > Feature > PBI/Bug.** A PBI or Bug parents to a Feature; a Feature parents to an Epic. The server refuses a wrong-typed parent by name. A Bug never parents directly to an Epic.
+- A work item has exactly one parent. Ordering is never expressed by parenting.
+- Predecessors, Related links and readiness: [`workitem-states.md` § Links](workitem-states.md#4-links).
+- Agents never create Epics or Features in a run (a Feature is created in the live `write-feature` session). `epic:` and `feature:` are authored values; a missing Feature is never a create: report it with the id you looked for.
+- Tracked types: Feature, Product Backlog Item, Bug. No Tasks.
+
+## 4. Plan files
+
+One folder per Feature: `plans/features/az<feature id>-<slug>/` holding `intent.md`, `requirements.md`, `design.md`, `file-map-reference.md` and `items/az<id>-<slug>.md`. Git holds the plan; the board holds state, links, plan fields, attachments and comments.
+
+- **The id is the identity.** Allocate the item on the board first, then create its file. No placeholder files, no renames. An item not yet allocated is a row in `requirements.md`'s `## Items` table with an empty id cell.
+- **Nothing moves between directories.** State lives on the board, never in a folder or filename.
+- Frontmatter `status` mirrors the board state; the board is authoritative. Plan Revision, Plan Hash and Baseline Sha are never frontmatter.
+- The file contracts (frontmatter + sections) are the tables below; there is no per-repo `plans/templates/`.
+
+**`intent.md`** (Tarun, live `write-feature` session; agents never edit it). Frontmatter: `type: intent`, `title`, `status`, `work_item` (the Feature's board URL), `last_update`, optional `sources`.
+
+| Section | Rule |
+|---|---|
+| `## Why` | required |
+| `## Outcome` | required; what is true when it's done |
+| `## Constraints` | required |
+| `## Non-goals` | required |
+| `## Open questions` | optional |
+
+**`requirements.md`** (the what and why; frozen at G1 under the plan hash). Frontmatter: `type: feature`, `title`, `status`, `epic` (the Epic's board URL), `work_item` (the Feature's board URL), `last_update`, `sources` (lists `intent.md` first).
+
+| Section | Rule |
+|---|---|
+| `## Problem` | required; holds the user stories |
+| `## Acceptance criteria` | required; numbered `AC-1…`, each one EARS sentence, each checkable by a test |
+| `## Scope` | required; In and Non-goals |
+| `## Predecessors` | the Feature's predecessor Features, mirrored as board links |
+| `## Items` | `Id \| Title \| Type \| Delivers \| Verification` (by AC ids); no Predecessor column |
+| `## Open questions for G1` | required; may say "none" |
+| `## Revision log` | required, append-only: `Rev \| Date \| Baseline \| Trigger \| Changes` |
+
+**`design.md`** (the how; outside the plan hash; a planner sub-agent may update it in the implementation run). Frontmatter: `type: design`, `title`, `status`, `work_item`, `last_update`, and `sources` listing `requirements.md`.
+
+| Section | Rule |
+|---|---|
+| `## Solution` | required; the approach per item, with `file:line` read at the Baseline Sha |
+| `## Decisions` | required; includes the RALPLAN-DR summary: principles, decision drivers, ≥ 2 options; deliberate mode for high-risk work |
+| `## Verification` | required; every `AC-n` → its test, tests first |
+| `## Docs impact` | required; each doc path or section the change updates, with its item, or "No docs impact" |
+| `## Size estimate` | required; items, touchpoints and changed lines, with the working shown, against the sizing gate |
+| `## Risks` | required; each with a concrete mitigation |
+
+**`file-map-reference.md`**. Frontmatter: `type: file-map`, `title`, `status`, `work_item`, `last_update`. Sections: `## Baseline` (the `integration` SHA; equals the Feature's Baseline Sha) and `## Map` (`Path | Kind (read / change / new) | Why | Items`).
+
+**Touchpoint.** A touchpoint is a `## Map` row of Kind `change` or `new`. A `read` row is not a touchpoint. The sizing gate counts touchpoints.
+
+- **EARS:** every acceptance criterion is one sentence "THE SYSTEM SHALL …", optionally opened by WHEN, WHILE, IF … THEN or WHERE. Each becomes one test, written first **[check pending R4]**.
+- **Sizing gate:** ≤ 6 items, ≤ ~40 touchpoints, ≤ ~1,500 changed lines, no shims, one coherent outcome. Over it: split or cut.
+
+**Feature plan fields** (on the board, written by the planner):
+
+| Field | Rule |
+|---|---|
+| Plan Revision | increments once per G1 submission; the review rounds inside one planning run share it |
+| Plan Hash | sha256 of `requirements.md` only. Readers recompute `shasum -a 256 requirements.md` and compare; on a mismatch, name both hashes in a Feature comment and stop the step that needed it. The check at the Design Validation move is **[pending F7]** |
+| Baseline Sha | the `integration` commit the plan was written against; a design update in the implementation run sets it to the new base |
+
+**Attachments** (on the Feature only, both mandatory, attached by `pr_create_or_update` **[pending P4, needs T2]**): `plan-r<N>-<sha7>.md` with the planning PR (`requirements.md`, `design.md`, `file-map-reference.md` and every item file, in one file; `<N>` = Plan Revision, `<sha7>` = first 7 of Plan Hash); `impl-report-pr<id>.md` with the implementation PR (per item: what changed, tests run, review findings and their resolution, docs touched; design updates). A Fixes Bug's report attaches to its Fixes Feature. The implementation run adds no `plan-r*`. PBIs and Bugs carry no attachments. An attachment is never edited or replaced. The one delete allowed is of a mistaken upload, in the run that made it; it is refused for a `plan-r*` file once an item of that Feature has left Awaiting Approval (pending T2). On API 7.1, delete means removing the `AttachedFile` relation; the stored file stays.
+
+**LEDGER.** Every agent commit that touches `plans/` adds one `plans/LEDGER.md` row, written by whoever commits. Table `Date | Id | Area | Event | Refs`, newest first; Event ≤ 99 characters.
+
+| Event | Row id | Written by |
+|---|---|---|
+| Intent | `az<id>-intent` | the agent in Tarun's live `write-feature` session |
+| Plan revision | `az<id>-plan-r<N>` | the planner, planning run |
+| Design update | `az<id>-design-update` | the planner sub-agent, implementation run |
+| Fixes Bug item file | `az<id>-bug` | the executor, per-Bug run |
+
+## 5. Item files
+
+One file per PBI or Bug, `items/az<id>-<slug>.md` in its Feature's folder. The item file text **is** the work item's fields: keep the ADO Description and Acceptance Criteria in sync with it.
+
+Frontmatter (both types):
+
+```yaml
+---
+type: pbi                 # pbi | bug
+title: Parse the dispatcher config
+status: Awaiting Approval # board state
+work_item: https://dev.azure.com/<org>/<project>/_workitems/edit/<item id>
+feature: https://dev.azure.com/<org>/<project>/_workitems/edit/<Feature id>   # the Feature's full board URL
+last_update: 2026-10-10T12:00:00Z
+---
+```
+
+**PBI** (written by the planner in the planning run; a PBI that triage creates (a split) is at New, so it goes through planning: the planner writes its item file in the Feature's next planning run, which the requeue re-fire triggers). Sections: `## What it delivers`, `## Verification` (each line names its `AC-n`), optional `## Related`. No `## Predecessors`.
+
+**Fixes Bug.** `report-bug` creates the Bug on the board only, at New, under the Epic's `Fixes to closed Features` Feature. Its **Description** holds the bugfix shape:
+
+| Section | Holds |
+|---|---|
+| `## Current behaviour` | what happens now, with the repro and its output; for a red pipeline it cites the first failing build id once |
+| `## Expected behaviour` | one EARS sentence per criterion |
+| `## Behaviour that must not change` | what the fix must leave alone |
+| `## Responsible Feature` | required; the closed Feature that should have got it right, or for a red pipeline the merged Feature (for a `fix/` PR, the merged Bug's Responsible Feature) |
+| `## Verification` | a regression test that fails before the fix |
+
+G1 approves that Description. In the per-Bug run the **executor** commits the item file as the first commit on `fix/az<bug id>-<slug>`: frontmatter with `type: bug` and `feature:` = the Fixes Feature, the five sections above, plus `## Predecessors` mirroring the board predecessor link (L4: the predecessor Bug in that Fixes Feature, or `none` for the first), and the LEDGER row `az<id>-bug`. Location: `plans/features/az<fixes id>-fixes-to-closed-features/items/az<id>-<slug>.md`; the first Bug of a Fixes Feature creates the folder. The Fixes Feature is never planned and never rolled up; the item file is the Bug's whole plan.
+
+## 6. PR wiring
+
+`pr_create_or_update` does all PR-to-board wiring **[pending P1, P2, P4]**. One rule decides the kind, from the source branch and the board:
+
+- A source branch `docs/az<id>-<slug>-plan` (the `-plan` suffix) means a **planning PR**. It wires the Feature's in-scope items at In Planning.
+- Any other `<type>/az<id>-<slug>` branch means an **implementation PR**. It wires the in-scope items at Approved or later: the Feature's items, or, for a Bug branch `fix/az<bug id>-<slug>`, that one Bug.
+- Items at Parked for Removal or Removed are never wired.
+- A PR with no item in a wireable state is **ordinary**: no work-item links, no state moves, no attachment, no impl-report. So the `intent.md` PR from `docs/az<id>-<slug>` stays ordinary even when PBIs already exist at New, because none is at Approved or later.
+
+Agents pass nothing, add no item links or `AB#` references to PRs by hand, and make none of these moves.
+
+| PR | Source branch | Linked items | `transitionWorkItems` | Raised → | Merged → | Attachment |
+|---|---|---|---|---|---|---|
+| Planning | `docs/az<id>-<slug>-plan` | the Feature's in-scope items at In Planning | false | items → Awaiting Approval | nothing | `plan-r<N>-<sha7>.md`, on the Feature |
+| Implementation (Feature) | `<type>/az<id>-<slug>`, the id a Feature | the Feature's in-scope items at Approved or later | true | items → Updating Docs | items → Done | `impl-report-pr<id>.md`, on the Feature |
+| Implementation (Fixes Bug) | `fix/az<bug id>-<slug>` | that Bug, at Approved or later | true | Bug → Updating Docs | Bug → Done | `impl-report-pr<id>.md`, on the Fixes Feature |
+| Ordinary | any branch with no item in a wireable state (e.g. the `intent.md` PR on `docs/az<id>-<slug>`, even with PBIs at New), or a branch that names no work item | none | false | nothing | nothing | none; no impl-report |
+
+- A planning PR's merge never moves items to Done; only the implementation PR's merge does (verify V2 on a real PR).
+- Today `pr_create_or_update` links no items and moves nothing.
+
+## 7. Git
+
+| Branch | Name | Rules |
+|---|---|---|
+| Planning | `docs/az<feature id>-<slug>-plan` | Created by adl-dispatcher, pushed once. Holds the plan folder edits; docs-only planning PR to `integration`. Re-entry reuses the existing branch: bring it current with `git merge --no-edit origin/integration`. Never rebase, never force-push, never recreate it |
+| Implementation | `feat/az<feature id>-<slug>` (or the fitting type) | Created by adl-dispatcher, pushed once. One branch, one PR per Feature; every item's commits go on it. Never force-push; every implementation run starts by merging `origin/integration` into it (`git merge origin/integration`), before Design Validation |
+| Fixes Bug | `fix/az<bug id>-<slug>` | Created by adl-dispatcher, pushed once. One branch and one PR per Approved Fixes Bug; same rules as implementation |
+| `intent.md` | `docs/az<feature id>-<slug>` | Created by the agent in Tarun's live `write-feature` session, from `origin/integration`. Ordinary docs PR; no wiring |
+| Triage worktree | `workitem-triage` | Repo-wide run; pushes no branch, raises no PR |
+
+- Branch names follow the global `<type>/<kebab>` rule. Only adl-dispatcher creates worktrees, at most 3 checkouts per repo; agents never `git worktree add`. 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.
+- Commits: `<type>(<scope>): <lowercase subject>`, type ∈ `feat|fix|docs|refactor|perf|chore`. No `!`. Never `release:`. Each commit independently green, one topic. Never `git stash`.
+- **`AB#<id>` goes in the commit body**, never the subject, on implementation and Fixes Bug commits only (the item's id). Planning commits carry none: a hand-written reference would let ADO move items when a planning PR completes.
+- PR title follows the commit grammar, at most 80 characters. PR body, five sections (the first three enforced today, all five pending P3):
+
+  | Section | Content |
+  |---|---|
+  | `## Summary` | what the PR does |
+  | `## Why` | the reason |
+  | `## Changes` | the changes |
+  | `## Test plan` | one line per EARS criterion → its test; a planning PR writes "none (docs-only)" |
+  | `## Security impact considered` | the ISMS consideration; a planning PR writes "none (docs-only)" |
+
+  An `## Evidence` section is optional; the full record is the `impl-report-pr<id>.md` attachment.
+- Every PR targets `integration`. CI plus auto-complete (squash, source branch deleted) merges it. The `integration → main` promotion PR is opened by the pipeline and approved only by Tarun (G2).