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

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

@@ -0,0 +1,147 @@
+---
+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.
+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, 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).
+
+## 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.
+
+## 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 `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).
+- **`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.
+- **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, never pushes |
+| `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 |
+| `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) |
+| `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 `integration → main` 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 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); `integration` moved → merge `origin/integration` |
+| 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` (`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.
+- 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
+
+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`.
+- 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).
+
+## 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.
+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
+
+- 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, 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.
+
+## 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,194 @@
+# 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` | `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 |
+| `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 --id <id> --state "<State Name>"`. Use the exact ADO state name.
+- Post a comment: `workitem_create_or_update --id <id> --comment "<text>"`.
+- 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`.
+
+## 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).

package/packages/agent-skills/assets/workitems-process/references/evidence.md

@@ -0,0 +1,74 @@
+# Run reports and evidence
+
+Part of [`workitems-process`](../SKILL.md). Tags: **[pending X]** = change row `X`, not built.
+
+## Principle
+
+- **The dispatcher parses nothing and writes nothing.** Whether a target is done is decided from the board and the PR (the target's done proof), not from a comment.
+- Evidence is for humans, for the next sub-agent, and for a resumed run. It binds to what it ran against: the head SHA, or plan revision N. A later commit voids earlier test and review evidence for what it touches; the Feature-final check at the final head is what the merge relies on.
+- **Evidence is the item comment plus the PR.** The run-level report is the run's last comment: on the Feature for a planning or implementation run, on the Bug for a per-Bug run, never on a PBI. Its first line is one machine line, `adl-evidence v1 <run> <verdict> <head_sha>` (e.g. `adl-evidence v1 implementation MERGED 3f9c2ab`), then the report.
+
+## Where evidence lives
+
+| Record | Written by | Where |
+|---|---|---|
+| Sub-agent report | the sub-agent returns it; the **lead** posts it | item comment (Feature comment for the Feature-final and finalize lanes) |
+| Run report, planning and implementation | the lead (`planner`, `lead`) | one comment as its last action: on the Feature, or on the Bug in a per-Bug run |
+| Run report, `workitem-triage` | `triager` | the activity log (`adl activity add`, pending A1) plus one comment on each touched item |
+| PR body | the lead; on an implementation PR the text comes from `writer` | the PR, five sections ([`ado-and-git.md` § Git](ado-and-git.md#7-git)) |
+| Plan snapshot, implementation report | content from the lead; attached by `pr_create_or_update` | Feature attachments ([`ado-and-git.md` § Plan files](ado-and-git.md#4-plan-files)) |
+| Review findings | review sub-agents via the lead | item comments and the implementation report; never PR threads or votes |
+
+- Reading earlier comments needs **T1 (pending)**. A resumed run that cannot read them works from the board states, `git log` and the PR, and re-runs any verify or review whose head is not the current head.
+- Evidence never holds secrets: links, repo-relative paths, commands with exit codes, run ids, SHAs.
+
+## Sub-agent report (the common shape)
+
+````yaml
+lane: validate | design-update | implement | fix-ci | verify | verify-final | review-code | review-architecture | finalize | review-plan-architect | review-plan-critic
+target: <item id | feature id>
+base_sha: <origin/integration sha>
+head_sha: <worktree HEAD the report applies to; plan reviews name revision N>
+verdict: <set per lane, below>
+findings:                    # required for every non-pass verdict
+  - id: F1
+    severity: critical | high | medium | low
+    where: path:line
+    what: "<issue and risk>"
+    fix: "<concrete change>"
+artifacts:                   # files reviewed, commands with exit codes, run ids, AC-n -> test map, commit SHAs
+  - ...
+````
+
+A negative verdict with empty `findings`, or a finding without `where` and `fix`, is invalid. `REQUEST_CHANGES` and `BLOCK` send the item back into the loop; `WATCH` and medium or low findings are recorded, not blocking. The Critic's verdict for revision N counts only after the Architect's review of the same revision.
+
+## Verdicts by lane and by run
+
+| Lane or run | Verdicts |
+|---|---|
+| plan review, architect and critic | `APPROVE` · `ITERATE` · `REJECT` |
+| validate (`design.md` and its `file-map-reference.md`) | `FRESH` · `DRIFT` (exact delta) |
+| design update (planner sub-agent) | `UPDATED` |
+| implement | `DONE` · `DRIFT` · `PARK` |
+| verify, verify-final | `PASS` · `FAIL` |
+| review, code | `APPROVE` · `REQUEST_CHANGES` |
+| review, architecture | `CLEAR` · `WATCH` · `BLOCK` |
+| finalize | `DONE` · `REWORK` (finding `docs-missing`) |
+| fix-ci | `FIXED` · `INFRA` |
+| run: workitem-triage | `TRIAGED` |
+| run: planning | `DONE` (every in-scope item at Awaiting Approval and the planning PR raised; the report names the critic outcome, `APPROVE` or the cap) · `PARK` (the work is obsolete: the planner moved the in-scope items to Parked for Removal, each with a reason comment; G3 decides) |
+| run: implementation | `MERGED` · `PR_OPEN` (CI unfinished at session end; the next dispatch resumes) |
+
+No lane or run has a `BLOCKED` verdict. A failed precondition, a tool refusal or a cap follows its path in [No block](../SKILL.md#no-block).
+
+## Run report content
+
+Posted by the lead as its last action, then the one-line handoff `<target> <verdict> <key kind> <id> @ <sha>`.
+
+| Target | The report holds |
+|---|---|
+| workitem-triage | per swept item: applied, proposed (comment posted, item unchanged) or unchanged, with reasoning and evidence (`file:line`, commit, test output); split-off ids; rolled-up Feature ids; Bugs filed through `report-bug`; Features at New with no plan yet (informational); base SHA |
+| planning | revision N, baseline SHA, plan hash, review rounds, critic outcome, open findings, planning PR URL, allocated item ids |
+| implementation | per item: final state, commits (`AB#` ids), sub-agent verdicts and head SHAs; design updates; Feature-final result at the final head; CI rounds; PR link; verdict |
+
+Every negative result names `where` and `fix`.

package/packages/agent-skills/assets/workitems-process/references/workitem-states.md

@@ -0,0 +1,92 @@
+# Work item states, moves and links
+
+Part of [`workitems-process`](../SKILL.md). Tags: **[live]** = enforced today; **[pending X]** = change row `X`, not built. Never act as if a pending change is live.
+
+## 1. PBI states
+
+| State | Owner | Entered when | Exit |
+|---|---|---|---|
+| New | planning run | the item is allocated under its Feature | → In Planning |
+| In Planning | planning run | the planner moves it, after allocating any new PBIs and before writing the files | → Awaiting Approval |
+| Awaiting Approval | Tarun (**G1**) | the planning PR is raised | → Approved, In Planning (rework) or New (requeue) |
+| Approved | implementation run | Tarun approves the plan revision | → Design Validation |
+| Design Validation | implementation run | the lead's first act; re-entered from In Implementation on drift | → In Implementation |
+| In Implementation, In Testing, In Review | implementation run | the loop | the loop |
+| Updating Docs | implementation run | the loop; the implementation PR is raised | the loop, or → Done |
+| Done | — | the Feature's implementation PR, linked to the item, merges into `integration` | terminal |
+| Parked for Removal | Tarun (**G3**) | a lead parks the item with a reason | → Removed, or → New (revive) |
+| Removed | — | Tarun confirms the removal | terminal |
+
+- Up to Design Validation the order is strict.
+- **The loop is non-linear.** After Design Validation, In Implementation, In Testing, In Review and Updating Docs are free moves in either direction, per PBI. The usual order is In Testing before In Review, so a reviewer sees green code; a default, not a rule.
+- **Fence today [live]:** among the loop states the fence allows only In Review → In Implementation (`workflow-rules.ts:81`). Every other loop move (In Testing → In Implementation, Updating Docs → In Implementation or In Review, the skips) is **[pending F1]**, as is the drift loop-back In Implementation → Design Validation (ADO allows it, the fence does not yet). On a refusal: post the exact text as an item comment and take the path the refusal names; do not work around it.
+- **Drift loops back; it never leaves the run.** In Implementation → Design Validation; the lead re-validates `design.md`; a drifted `design.md` is fixed in the run by a planner sub-agent. Items never go to New or In Planning for drift. Drift that would need an approved `AC-n` changed follows [No block](../SKILL.md#no-block).
+- Later commits void earlier test and review evidence, so the Feature-final check at the final head is what the merge relies on.
+
+## 2. Who moves what
+
+| Move | Who | Status |
+|---|---|---|
+| New → In Planning | planning lead: after allocating any new PBIs, it moves every in-scope PBI (existing and new), then writes the files; all are at In Planning before the planning PR is raised | live |
+| In Planning → Awaiting Approval | `pr_create_or_update`, when it raises the planning PR | pending P2 |
+| Awaiting Approval → Approved / In Planning (rework) / New (requeue) | Tarun (G1) | live |
+| Approved → Design Validation | implementation lead, first act | live |
+| Design Validation → In Implementation | implementation lead, when an item's build starts | live |
+| Free moves among the four loop states | implementation lead | pending F1 |
+| In Implementation → Design Validation | implementation lead, on mid-loop drift | pending F1 |
+| Loop → Updating Docs | `pr_create_or_update`, when it raises the implementation PR | pending P2 |
+| Updating Docs → Done | ADO completion of the linked implementation PR (`transitionWorkItems`) | pending P1, P2, V2 |
+| Any non-terminal → Parked for Removal | any lead, with a reason | live |
+| Parked for Removal → Removed | Tarun (G3) | live |
+| Parked for Removal → New (revive) | Tarun | human-only; the fence lets agents make it today, and agents never do |
+
+- Both G1 rejection paths force a new G1 pass.
+- **Agents never set Done, Approved or Removed.** Done follows the merge of the implementation PR, which `pr_create_or_update` links to the items ([`ado-and-git.md` § PR wiring](ado-and-git.md#6-pr-wiring)). A planning PR's merge never moves items.
+- **Agents pass nothing for the PR-time moves** and make none of them.
+- Feature roll-ups are `workitem-triage`'s (§3).
+
+## 3. Feature states
+
+`New → In Progress → Awaiting Release → Done`, plus `Removed`. Linear, one step at a time, never backward; Done only from Awaiting Release **[pending F3, F4]**.
+
+| State | Entered when | Moved by |
+|---|---|---|
+| New | the Feature is created, only at New | — |
+| In Progress | at least one child has left New | `workitem-triage` roll-up |
+| Awaiting Release | every child is Done or Removed (its implementation PR merged into `integration`) | `workitem-triage` roll-up |
+| Done | the `integration → main` PR carrying the children is merged (G2) | `workitem-triage` roll-up |
+| Removed | Tarun removes the Feature | Tarun, human-only |
+
+- **"Closed" = Awaiting Release or later.** No child may be added to a closed Feature **[pending L1]**; work found later goes into a new Feature or a Fixes Bug.
+- **`Fixes to closed Features`** (one per Epic, 548–554) stays **In Progress** permanently; agents may not move it **[pending F5]**. It is exempt from the predecessor rule and the roll-ups.
+
+## 4. Links
+
+- **Parent:** a PBI or Bug's parent is its Feature; a Feature's parent is an Epic. In an item file, `feature:` is the Feature's full board URL.
+- **Predecessors live on Features only:** at least 1, except the very first Feature. Soft warning first, hard refusal later **[pending L2]**. A Feature is **ready** when every predecessor is at Awaiting Release or Done.
+- **PBIs carry no predecessors** **[pending L3]**; item order inside a Feature is the implementation lead's choice.
+- **Fixes Bugs are the one exception:** a Bug under `Fixes to closed Features` has a predecessor (another Bug there) and a **Related** link to the Responsible Feature, in any state (a red pipeline's Responsible Feature can be open) **[pending L4]**. The first Bug in a Fixes Feature has no predecessor, and none is accepted; every later Bug needs one.
+- **Findings go through `report-bug`:** a defect in an open Feature (before Awaiting Release) updates that Feature's PBIs and creates no Bug; a defect in a closed Feature creates a Bug under that Epic's `Fixes to closed Features`.
+
+## 5. Bug states
+
+Every Bug is a Fixes Bug under a `Fixes to closed Features` Feature. **Never planned:** no In Planning, Awaiting Approval or Design Validation, no plan hash, no `requirements.md`, `design.md` or `file-map-reference.md`.
+
+`New → Approved → In Reproduction → In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs → Done`, plus `Parked for Removal → Removed` and `Parked for Removal → New`.
+
+| Move | Who |
+|---|---|
+| created at New | `report-bug`, on the board only; its Description holds the bugfix shape ([`ado-and-git.md` § Item files](ado-and-git.md#5-item-files)) |
+| New → Approved | Tarun (**G1**), approving that Description; human-only |
+| Approved → In Reproduction | implementation lead, first act of the per-Bug run **[pending L5, X2]** |
+| In Reproduction → In Fixing | implementation lead, once the executor (reproduce mode) has committed the item file and the regression test marked as an expected failure (the framework's xfail or `test.fails` form), with its unmarked run red on the base posted on the Bug as evidence; the reproduce commit stays green, and the fix commit removes the mark |
+| Free moves among In Fixing, In Testing, In Review, Updating Docs | implementation lead (the PBI loop with In Fixing in place of In Implementation) |
+| Loop → Updating Docs | `pr_create_or_update`, when it raises the Bug's implementation PR |
+| Updating Docs → Done | ADO completion of the linked implementation PR; agents never move to Done |
+| In Reproduction → Parked for Removal | implementation lead, when the Bug won't reproduce: it posts what was tried as a comment on the Bug |
+| Any non-terminal → Parked for Removal | any lead, with a reason (New and Approved included, to park a duplicate) |
+| Parked for Removal → Removed | Tarun (**G3**), human-only |
+| Parked for Removal → New (revive) | Tarun, human-only |
+
+- **Per-Bug run:** branch `fix/az<bug id>-<slug>`. The executor's first commit is the Bug's item file (the Description's sections plus `## Predecessors` mirroring the board link), with its LEDGER row `az<id>-bug`; then 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. The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception. The lead writes no files.
+- Every other Bug move is refused. The fence's Bug table is **[pending F9]**.

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

@@ -0,0 +1,95 @@
+---
+name: write-feature
+description: Live, human-attended session that creates a Feature on the ADO board, parent Epic chosen by the human and at least one predecessor Feature unless it is the very first, and writes its intent.md in the human's own words, then lands it through a docs branch and PR. Use when Tarun asks to start, create or write up a new Feature or its intent. Never dispatched.
+metadata:
+  step: "live"
+  role: "session agent with the human"
+  states: "Feature:New"
+---
+
+# Write Feature (live session)
+
+Load `workitems-process` first. This card adds only what the live Feature session does.
+
+## When to use
+
+- The human starts a new Feature in a session they attend. This is stage 1 of the Feature flow.
+- **Never dispatched.** No dispatch record, no worktree from the dispatcher, no run report. If you were started by the dispatcher, stop: this skill is wrong for the run.
+- Not for planning (`plan-feature`) and not for a Bug (`report-bug`).
+
+## Inputs (all from the human)
+
+| Input | Rule |
+|---|---|
+| The Feature in their words | Why, Outcome, Constraints, Non-goals; Open questions optional |
+| Parent Epic | **The human chooses.** Never guess, never create |
+| Predecessor Features | At least 1, unless the human says this is the very first Feature |
+| Title and slug | Human confirms both |
+
+## Preconditions
+
+1. `adl id whoami` reports `agent-tarun`. Mismatch → stop and say so.
+2. You are in a checkout of the repo that will hold the plan, `origin/integration` fetched, clean tree.
+3. The human gave an Epic id. Confirm it parents a Feature: a wrong-typed parent is refused by name at create. Do not read or edit the Epic.
+
+## Procedure
+
+Ask **one question at a time**. Lead with what you already know.
+
+1. **Listen.** Take the human's words. Do not rewrite, extend or "improve" them. Do not add a solution.
+2. **Fill gaps, not prose.** For each required section the human left empty (`## Why`, `## Outcome`, `## Constraints`, `## Non-goals`), ask for it. `## Open questions` is optional; add it only if the human has some.
+3. **Predecessors.** List candidate Features (`workitem_list_or_get --type Feature`) and let the human pick. A Feature needs at least 1 predecessor Feature; only the very first has none. The human says which case applies; you do not infer it. Enforcement is soft then hard: pending L2 in adl-agent-control.
+4. **Allocate the Feature on the board first.** `workitem_create_or_update --type Feature --title "<title>" --parent-id <epic> --predecessors <ids> --description "<Why, Outcome, Constraints, Non-goals>"`. State stays New (the tool refuses any other create state: pending F3). Read it back: type Feature, state New, parent = the Epic, predecessors present. A refusal is the answer: report the exact text, stop, create nothing.
+   - **Description = copy of `intent.md`.** Pass the human's own `## Why`, `## Outcome`, `## Constraints`, `## Non-goals` text, verbatim and identical to what step 5 writes, as `--description` at create. Written once, here. Agents never edit it afterwards, the same as `intent.md`. The approved plan lives in the `plan-r<N>-<sha7>.md` attachment, not in the Description.
+   - Do not touch Features 548-554 ("Fixes to closed Features"); their description is already set.
+   - Never create an Epic. Never set `epic:` from tool output; it is the human's value.
+5. **Write `plans/features/az<id>-<slug>/intent.md`.** The id is allocated before the file exists. Layout below. No other file in the folder.
+6. **Read it back to the human.** Commit only after an explicit yes. After that, agents never edit `intent.md`; only the human does.
+7. **Land it.** An ordinary docs change. You create the branch `docs/az<id>-<slug>` from `origin/integration`: the one exception to "agents never create a branch" ([ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git)). Add the `plans/LEDGER.md` row `az<id>-intent` ([LEDGER](../workitems-process/references/ado-and-git.md#4-plan-files)). Commit `docs(plans): add intent for az<id> <slug>`. Push with plain `git`. Open the PR to `integration` with `pr_create_or_update`, 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)". The branch has no `-plan` suffix and the Feature has no item at Approved or later (PBIs the human already made sit at New), so this is an ordinary PR: the tool links nothing, moves nothing, attaches nothing, and it needs no implementation report ([PR wiring](../workitems-process/references/ado-and-git.md#6-pr-wiring)). Never rebase or force-push. No reviewer, no vote ([Human gates](../workitems-process/SKILL.md#human-gates)).
+8. **Stop.** Report: Feature URL, branch, PR URL. Say the Feature is at New and the planning trigger ([Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers)) fires on it once the PR has merged. Do not start planning.
+
+## `intent.md` layout
+
+```markdown
+---
+type: intent
+title: <Feature title>
+status: New
+work_item: https://dev.azure.com/<org>/<project>/_workitems/edit/<feature id>
+last_update: <YYYY-MM-DDTHH:MM:SSZ>
+---
+
+## Why
+- <the human's words>
+
+## Outcome
+- <what is true when it is done>
+
+## Constraints
+- <...>
+
+## Non-goals
+- <...>
+
+## Open questions
+- <optional; omit the section if empty>
+```
+
+- Required sections: Why, Outcome, Constraints, Non-goals. Short bullets, the human's own wording.
+- `status` mirrors the Feature's board state (New). `work_item` URL id equals the folder id. Optional `sources:` only if the human names documents.
+- The check for these sections is pending R4; the Feature-state `status` values are pending R1.
+- Owner of the layout: [ado-and-git.md](../workitems-process/references/ado-and-git.md#4-plan-files).
+
+## Stop rules
+
+- Epic not given, or the human cannot say whether a predecessor exists → stop and ask; never default.
+- A refused create or a failed read-back → stop with the exact error; no file before the id.
+- Same command fails twice for the same reason → stop and report.
+
+## Never
+
+- Never write, extend or paraphrase the human's intent for them.
+- Never choose the Epic or a predecessor.
+- Never create PBIs here; planning creates them. PBIs the human already made stay at New and planning reads them.
+- Never move a state, never plan, never post a run report.
+- Never edit `intent.md` after the human approved it.