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

package/packages/agent-skills/assets/tdd/references/tests.md

@@ -1,77 +0,0 @@
-# Good and Bad Tests
-
-## Good Tests
-
-**Integration-style**: Test through real interfaces, not mocks of internal parts.
-
-```typescript
-// GOOD: Tests observable behavior
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-Characteristics:
-
-- Tests behavior users/callers care about
-- Uses public API only
-- Survives internal refactors
-- Describes WHAT, not HOW
-- One logical assertion per test
-
-## Bad Tests
-
-**Implementation-detail tests**: Coupled to internal structure.
-
-```typescript
-// BAD: Tests implementation details
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-Red flags:
-
-- Mocking internal collaborators
-- Testing private methods
-- Asserting on call counts/order
-- Test breaks when refactoring without behavior change
-- Test name describes HOW not WHAT
-- Verifying through external means instead of interface
-
-```typescript
-// BAD: Bypasses interface to verify
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// GOOD: Verifies through interface
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```
-
-**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
-
-```typescript
-// BAD: Expected value is recomputed the way the code computes it
-test("calculateTotal sums line items", () => {
-  const items = [{ price: 10 }, { price: 5 }];
-  const expected = items.reduce((sum, i) => sum + i.price, 0);
-  expect(calculateTotal(items)).toBe(expected);
-});
-
-// GOOD: Expected value is an independent, known literal
-test("calculateTotal sums line items", () => {
-  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
-});
-```

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

@@ -1,54 +0,0 @@
----
-name: testing
-description: Select and prove unit, regression, or cross-service tests for a change.
-disable-model-invocation: false
----
-
-# Testing
-
-## Purpose
-
-Select the smallest test mode that proves the change, preserve a red-green regression trail for bug fixes, and run cross-service behavior through the project's CI-parity environment.
-
-## Use When
-
-- A change needs test coverage or a bug needs a regression proof.
-- Runtime, provider, database, broker, streaming, or end-to-end behavior is involved.
-
-## Do Not Use When
-
-- Behavior is still unknown; resolve the specification first.
-- The request is solely an external pre-landing review rather than test selection or proof.
-
-## Workflow
-
-1. Choose Mode 0 for isolated logic, Mode 1 for a bug-fix red-green cycle, and Mode 2 for cross-service or live behavior.
-2. For Mode 1, run the smallest failing regression test, implement the minimum change, rerun it, then refactor only while green.
-3. For Mode 2, run through the project's CI-parity entrypoint — `just check` in Adl repositories. Isolated containers are advisable in general and **mandatory** where a test crosses a service boundary or needs real runtime (provider, database, broker, streaming); pure/isolated logic may run in-window. Live or billable calls require an explicit project opt-in and must skip cleanly without credentials.
-4. Record the selected command, environment, and evidence in the current task artifact. A runtime bug requires a Mode-2 regression scenario.
-
-## Output
-
-Return the selected mode, changed test or scenario, red/green evidence where required, command output, and environment actually used.
-
-## State Contract
-
-Project repositories own harness paths, service names, credentials, URLs, and opt-in flags. Keep secrets out of fixtures and source; pass them only through environment variables.
-
-## Boundaries
-
-### In scope
-
-Mode selection, regression design, red-green-refactor, harness scenarios, and CI-parity evidence.
-
-### Out of scope
-
-Inventing unspecified behavior, reviewing code quality, or cleaning unrelated implementation residue.
-
-### Fog of war
-
-If behavior cannot be stated precisely, stop before writing a guessed test. If the isolation requirement is unclear, use the stricter Mode-2 path and record the uncertainty.
-
-## Completion
-
-Run the selected project test command in its required environment; `grep -q '^PASS:' <validator-output>` exits 0 for every harness scenario.

package/packages/agent-skills/assets/testing/references/e2e.md

@@ -1,37 +0,0 @@
-# End-to-end testing
-
-## Purpose
-
-End-to-end tests prove a complete business outcome from initiation to an
-observable completion across the integrated system. They validate outcomes and
-orchestration: UI state, sequencing, multi-system coordination, and the user
-journey. They do not provide exhaustive contract or error-path coverage for
-each boundary.
-
-## Use it for
-
-- Critical user journeys such as onboarding, checkout, order-to-cash, or
-  recovery flows.
-- Business workflows that span app UI, backend services, persistence, and
-  permitted external integrations.
-- Production-like load or timing scenarios where the complete workflow is the
-  thing being evaluated.
-
-Keep E2E scenarios few and outcome-oriented. Put contract variants, malformed
-data, retries, and service-boundary failures in integration tests unless the
-workflow itself changes their user-visible outcome.
-
-## Canonical location
-
-This repository has one cross-workspace E2E location: `tests/e2e/`.
-App workflows and package-contributed behaviour meet there; do not create
-`apps/<app>/tests/e2e/` or `packages/<package>/tests/e2e/`. App and package
-fixtures remain with their owning test trees unless they are shared fixtures
-owned by the E2E workspace.
-
-## Evidence
-
-Run the whole journey through its real runtime in the CI-parity environment,
-using production-like data and isolated dependencies. Assert the user-visible
-completion and the durable business result. External live or billable calls
-need explicit opt-in; without it, do not silently substitute a fake path.

package/packages/agent-skills/assets/testing/references/integration.md

@@ -1,37 +0,0 @@
-# Integration testing
-
-## Purpose
-
-Integration tests prove that two or more components communicate correctly at a
-real boundary. They validate connections: contracts, transformations,
-authentication, persistence, messages, retries, timeouts, and error handling.
-They do not replace a complete user or business workflow test.
-
-## Use it for
-
-- Service-to-service APIs, database adapters, queues, files, and external
-  provider boundaries.
-- Contract fields, response and error shapes, and data transformation edge
-  cases.
-- Failure modes that happy-path journeys rarely exercise: expired credentials,
-  timeouts, retries, duplicate delivery, and transaction coordination.
-
-Keep unrelated dependencies out of the scenario. A browser-driven checkout is
-not an integration test merely because it crosses an API; test the specific
-checkout-to-payment boundary directly when that contract is the subject.
-
-## Canonical location
-
-Place app-owned integration tests in `apps/<app>/tests/integration/` and
-package-owned integration tests in `packages/<package>/tests/integration/`.
-Use containerized or otherwise isolated real dependencies whenever the scenario
-crosses a service, database, broker, streaming, or provider boundary. Do not
-put integration scenarios in `tests/e2e/`; that workspace is reserved for
-complete workflows.
-
-## Evidence
-
-Exercise the real interface with controlled data and assert both the boundary
-response and the observable transformed result. Run through the repository's
-CI-parity entrypoint; live or billable services require an explicit opt-in and
-must fail loudly or skip cleanly when credentials are absent.

package/packages/agent-skills/assets/testing/references/unit.md

@@ -1,32 +0,0 @@
-# Unit testing
-
-## Purpose
-
-Unit tests prove one component's behaviour in isolation. They validate local
-logic and deterministic error handling; they do not prove an interface between
-independently deployed components or a user workflow.
-
-## Use it for
-
-- Pure transformations, validation, policy, parsing, and state transitions.
-- A component's behaviour at its public API with collaborators replaced only
-  when their real behaviour is outside the unit's responsibility.
-- Boundary values and error paths local to the component.
-
-Do not use a unit test as evidence that a request, query, message, file, or
-third-party contract works. That evidence belongs to an integration test.
-
-## Canonical location
-
-Place app-owned unit tests in `apps/<app>/tests/`. Place package-owned unit
-tests in `packages/<package>/tests/unit/`. Keep fixtures beside the owning
-test tree; do not put a package's unit test in an app or in `tests/e2e/`.
-
-Existing flat package test folders are not a reason to move unrelated tests;
-new unit tests use `tests/unit/` when introducing a new package test area.
-
-## Evidence
-
-Run the narrowest owner-level test command first. The test must have an
-independent expected result and fail when the component's promised behaviour
-is removed or changed.

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

@@ -1,91 +0,0 @@
----
-name: to-feature
-description: Turn the current conversation into a feature spec and open it as a Feature work item on Azure DevOps, parented to the plan's Epic — no interview, just synthesis of what you have already discussed.
-disable-model-invocation: true
----
-
-# To Feature
-
-Open a **Feature** on the board and give it a plan folder to live in.
-
-**A plan is a Feature, and a Feature is a directory** — `plans/features/az<id>-<slug>/spec.md`, named for the work item it is. This skill creates that Feature and that directory; `to-workitems` later fills its `items/` with PBIs and Bugs parented under it. Where the repo carries a `plans/AGENTS.md`, it governs; otherwise follow `## Plans and work items` in the repository's `CONTRIBUTING.md`.
-
-Do NOT interview the user — synthesize what you already know from the conversation and the codebase.
-
-## Use When
-
-- The current conversation, plus codebase exploration, already gives you enough to synthesize a feature spec, and the Epic it belongs under is known.
-
-## Do Not Use When
-
-- The user's intent is still unclear and needs an interview or clarifying questions first — this skill explicitly skips that; gather requirements before invoking it.
-- The way to the destination is not visible yet — chart the effort with `wayfinder` instead, and come back when the decisions are resolved.
-- `epic:` is unset. **Stop and ask.** `epic:` is authored, never tool-created, and the server refuses `Epic` as a creatable type outright — so a typo must fail here rather than hang the plan off the wrong portfolio branch.
-
-## Process
-
-### 1. Explore the repo
-
-Understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
-
-### 2. Sketch the seams
-
-Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better — the ideal number is one.
-
-Check with the user that these seams match their expectations.
-
-### 3. Have the human confirm the Epic
-
-**Stop here and ask.** Show the user the id in `epic:` and the title of the Feature you are about to create under it, and get an explicit confirmation before going on.
-
-This is a human step because **no agent-side check can establish which Epic is the right one — only that the parent named is an Epic at all.** Agents have no access to Epics: fetching one by id is refused, so there is no tool call that reads `epic:` back and confirms it names the Epic you intend. Do not go looking for one, and do not treat a successful create as agreement on identity — it proves the type, never the choice.
-
-Be careful with that refusal if you meet it — it reports only that the id is not a tracked type, which is equally true of a Task and of an id you cannot see. It does **not** say "this is an Epic", and reading it that way turns one observation into a proof it cannot carry.
-
-The access is asymmetric, and step 5 depends on the half that works: you cannot **read** an Epic, but you can **write** a parent link to one. The server checks that write's parent **type** — a PBI or Bug aimed at the wrong level is refused before the request is sent, and a Feature is no longer the exception: `workitem_create_or_update` refuses a wrong-typed parent by name, on create and on update alike (`Feature must be parented to a Epic; work item <id> is a <type>`). What that check cannot do is tell you whether `<id>` is the **right** Epic, only that it is *an* Epic — a Feature parented to the wrong Epic still creates cleanly, no error, silently on the wrong branch of the portfolio. The confirmation you get here is the only thing standing between you and that.
-
-`epic:` is **authored, never tool-created**. If it is unset, that is a stop — ask for it. Never create an Epic to fill the gap; the server refuses `Epic` as a creatable type outright, and a typo must fail loudly rather than quietly spawn a duplicate.
-
-### 4. Draft the spec, but do not write it yet
-
-Draft the spec against the template in [references/FEATURE-SPEC-TEMPLATE.md](references/FEATURE-SPEC-TEMPLATE.md). Hold it in the conversation — it has no folder to live in yet, because it has no id yet.
-
-**The id is the identity: allocate the work item first, then name the file.** A Feature is never written to disk under a placeholder and renamed afterwards. This skill allocates the id itself one step from now, so a placeholder would exist only for the length of a single tool call and buy nothing — it would be a second name for the same thing, and the rename is a step that can fail and leave the folder lying.
-
-### 5. Create the Feature
-
-```
-workitem_create_or_update({
-  type: 'Feature',
-  title: <the outcome, as it reads on the board>,
-  description: <the spec's ## Problem and ## Solution>,
-  acceptanceCriteria: <the spec's ## Acceptance criteria, verbatim>,
-  parentId: <the epic>,
-})
-```
-
-`description` and `acceptanceCriteria` are both advertised arguments — the plan's prose **is** those two fields, so send them on the create call rather than leaving the board holding a title and a parent. If the file and the field differ, the board is lying. `assignedTo`, `priority`, `startDate` and `targetDate` map the same way from the template's frontmatter when the plan sets them.
-
-`parentId` is **always** the Epic — the one adjacent level a Feature may hang from. Omitting it is refused as `requires parentId`, whatever the type; there is no root case to fall back on.
-
-**Set no state and no gate flags.** A Feature carries neither: the six Build flags apply only to Product Backlog Item and Bug, and a Feature's custom fields are empty. Do not carry a `fields: {...}` idiom across from a skill that works on PBIs — that raw-fields escape hatch reaches `System.State` without the dedicated `state` argument the gate matrix reads, which is the trap it exists to close. A new Feature lands in Azure DevOps's own default state, `New`, and moving it is a later, separate pass.
-
-### 6. Record the id, then verify the link landed
-
-Create `plans/features/az<id>-<slug>/` — named with the id the create call just returned, which is the only name it ever has — and write the drafted spec into its `spec.md` with `work_item:` set to that id and `epic:` carried through. Do this **immediately**, before anything else: a crash then leaves a folder that says what exists on the board, rather than a Feature nobody can trace back to a plan.
-
-Leave `items/` uncreated. A Feature whose items do not exist yet is the normal resting state of a fresh plan, not an unfinished one.
-
-Then read the Feature back and confirm `links.parent` is the `epic:` id:
-
-```
-workitem_list_or_get({ id: <the new feature>, raw: true })
-```
-
-`raw: true` is necessary rather than stylistic — the grouped view does not carry `System.WorkItemType` verbatim. This reads the **Feature**, never the Epic, so it stays inside what an agent can see.
-
-Be exact about what it proves: that the link landed on the id the human confirmed. The create having succeeded already proved that id is an Epic — a wrong type would have failed loudly at step 5 with `Feature must be parented to a Epic; work item <id> is a <type>`, before this read ever ran. What no agent-side check proves, here or at step 5, is that it is the **right** Epic. If `links.parent` is anything other than the `epic:` id, say so plainly rather than moving on; the plan is already on the board by then, and a wrong parent is worth raising immediately.
-
-### 7. Stop
-
-Slicing the feature into items is `to-workitems`' job, and it wants item files that do not exist yet. Tell the user the Feature is open and what its id is; do not start creating children in this run.

package/packages/agent-skills/assets/to-feature/references/FEATURE-SPEC-TEMPLATE.md

@@ -1,88 +0,0 @@
-# The plan document
-
-`plans/features/az<id>-<slug>/spec.md`. **This file IS the Feature** — the long form of its work
-item, not a parallel copy. `## Problem` and `## Solution` are its Description; `## Acceptance
-criteria` is its Acceptance Criteria field. If the two ever differ, the board is lying.
-
-Where the repo carries `plans/templates/feature.md`, that file is the source and this one is
-only its shape — author from the repo's copy.
-
-```markdown
----
-type: Feature
-title: "[the outcome, as it reads on the board]"
-description: "[one line — becomes System.Description]"
-status: draft
-created: YYYY-MM-DD
-epic: <id>
-work_item: <id>
-assigned_to: <email>
-priority: 2
-start_date: YYYY-MM-DD
-target_date: YYYY-MM-DD
----
-
-# [the outcome]
-
-## Problem
-
-What is wrong today, and what it costs. Evidence, not assertion — the command whose output
-shows it, the file and line, the number.
-
-## Solution
-
-The shape of the fix, from the outside in. What changes for whoever uses this. Not a
-layer-by-layer implementation list — that is the items' job.
-
-## Acceptance criteria
-
-Checkable statements. This is the same text as the work item's Acceptance Criteria field.
-
-- [ ] [something a reviewer can confirm without reading the diff]
-
-## Scope
-
-In: [paths or systems]
-
-Non-goals: [what a reader would wrongly assume is included]
-
-## Decisions
-
-- [decision, and what it rules out]
-
-## Items
-
-Order and dependencies. Each row is the complete source for an item that does not have a file
-until `to-workitems` allocates its id.
-
-| # | Title | Item type | Delivers | Verification | Work item | Predecessor |
-| --- | --- | --- | --- | --- | --- | --- |
-| 1 | [the outcome this slice delivers] | pbi | [the complete vertical slice] | [a falsifiable check] |  | — |
-
-## Verification
-
-The end-to-end check on the acceptance criteria above. Each item carries its own check — this
-is the one that only means anything once they have all landed.
-
-## Done when
-
-- [ ] Every item is Done on the board.
-- [ ] Acceptance criteria all met, with observed evidence.
-```
-
-## `status:` is about the document
-
-`status: draft` describes this file, not the work. The work's state is the Feature's board
-state, and it lives there alone — there is no `plan_state`, no `approval_state`, and no
-directory that moves to record progress.
-
-## Two rows to leave empty, and one to fill
-
-`work_item:` is filled from the create call's return, in the same step that names the folder.
-
-`epic:` was **authored before this skill ran** — it is never tool-created. If it is unset,
-that is a stop, not a value to allocate.
-
-The `## Items` table's `Work item` column stays empty here. `to-workitems` fills it when it
-creates the children, and that is the only join between the plan and its items: the link runs
-one way, each item naming its `feature:`, and the Feature never lists its items anywhere else.

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

@@ -1,90 +0,0 @@
----
-name: to-workitems
-description: Publish a change plan's backlog items to Azure DevOps — one PBI or Bug per item file, parented under the plan's Feature, with each id written back into the file it came from.
-disable-model-invocation: true
----
-
-# To Work Items
-
-Put a plan's **backlog items** on the board.
-
-**A plan is a Feature. An item file is a PBI or a Bug.** One file each. The plan and its `## Items` table are written before this skill runs; the item files are not, because each is named for an id only this skill allocates. Where the repo carries a `plans/AGENTS.md`, it governs the layout; otherwise follow `## Plans and work items` in the repository's `CONTRIBUTING.md`. [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md) carries the board rules both depend on.
-
-## Use When
-
-- A plan folder's `spec.md` is approved, its `## Items` table is filled in, and those items need to be on the board.
-
-## Do Not Use When
-
-- The plan has open decisions under `## Decisions` — resolve them first, or chart the effort with `wayfinder` if the destination itself is still unclear.
-- `epic:` or `work_item:` is unset. **Stop and ask.** Those are the plan's Epic id and Feature id respectively. Never create an Epic or Feature to fill the gap: a typo must fail here, not silently spawn a duplicate. The server refuses a stray Epic outright, and refuses a wrong-*typed* parent for any creatable type — but a right-typed id can still be the **wrong** one, and nothing on the board catches that. Identity is on you.
-
-## Process
-
-### 1. Read the plan and check the board
-
-`workitem_list_or_get({ id: <work_item>, raw: true })` and assert:
-
-- `fields['System.WorkItemType']` is `Feature`
-- `links.parent` is `epic`
-
-One call settles both — there is no need to fetch the Epic itself. `parentId` for every item this skill creates is **always** the Feature — never the Epic.
-
-### 2. Read the plan's `## Items` table
-
-**The rows are the source, not files.** A file under `items/` is named `az<work item id>-<slug>.md`, so **the id is the identity** — and it is always a real work item id. An item that has no id yet therefore has no file and cannot have one: allocate the work item first, then write the file. Nothing is drafted under a placeholder and renamed into truth later.
-
-Each row has to carry the whole item before the board sees it: its title, its `item_type` (`pbi` or `bug`), what it delivers, its falsifiable verification, and its predecessors. A row missing any of those is a stop, not a skip — fix the row first.
-
-A row whose `Work item` column is already filled is **already published**. Leave it alone, and confirm its file exists under `items/` with a matching `work_item:`. A filled column with no file means the ids were never written back; a file whose `feature:` names a different plan is a stop.
-
-### 3. Check the items are tracer bullets
-
-Fix the row if not — do not paper over it in the work item body.
-
-<vertical-slice-rules>
-
-- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
-- A completed slice is demoable or verifiable on its own
-- Each slice is sized to fit in a single fresh context window
-- Any prefactoring should be done first
-
-</vertical-slice-rules>
-
-**Wide refactors are the exception.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Sequence it as **expand–contract**: add the new form beside the old, migrate call sites in batches sized by blast radius (each batch its own item, blocked by the expand), then delete the old form in an item blocked by every batch.
-
-### 4. Quiz the user
-
-Present the items as a numbered list — title, blocked by, what it delivers. Ask whether the granularity and the blocking edges are right. Iterate until approved.
-
-### 5. Create the work items
-
-In `## Items` order, predecessors first — that is what makes `predecessors` expressible, since a row's blockers already have ids by the time it is reached.
-
-```
-workitem_create_or_update({
-  type: <item_type: pbi -> 'Product Backlog Item', bug -> 'Bug'>,
-  title: <the item's title>,
-  description: <the row's Delivers plus its source plan and row, per references/TICKET-TEMPLATES.md>,
-  acceptanceCriteria: <the row's Verification, verbatim>,
-  parentId: <the plan's work_item>,
-  predecessors: [<ids of the rows this one lists under Predecessor>],
-  related: [<for a Bug: the id of the PBI it was found in>],
-})
-```
-
-The row's delivery and source become `description`, shaped by [references/TICKET-TEMPLATES.md](references/TICKET-TEMPLATES.md). Its falsifiable verification becomes `acceptanceCriteria` verbatim. Both are advertised arguments and go on the create call, so the board receives the same fields as the row without a follow-up write.
-
-A Bug parents to the **Feature**, exactly as a PBI does, so `related` is the only way to record which item it was found while building.
-
-An item with no `parentId` is refused (`requires parentId`), and one parented to anything but the Feature is refused before the request is sent (see [references/AZURE-DEVOPS-HIERARCHY.md](references/AZURE-DEVOPS-HIERARCHY.md)) — so a wrong or missing feature id in the plan now stops the create rather than silently landing an orphan.
-
-Act on each returned id **immediately**, before creating the next — that is step 6, run once per row rather than once per plan. A crash then leaves a tree that says exactly what exists, rather than a board full of orphans nobody can trace.
-
-### 6. Write the item file the id now names
-
-The create call has returned an id, so the item finally has a name. Write `items/az<id>-<slug>.md` from the repo's `plans/templates/backlog-item.md`, with `work_item:` set to that id, `feature:` naming this plan, and `item_type:` the row's. Then fill that id into the plan's `## Items` row.
-
-The file is **born with its real id** and is never renamed. The `## Items` index is the only join between a plan and its items, and the link runs one way — the item names its `feature:`, the Feature never lists its items anywhere else.
-
-Nothing here moves between directories afterwards, and no directory name records progress. From here, progress lives on the work item as the six Build flags, and setting them is a later, separate pass — not this run, which already created the items and so is the wrong party to also confirm `Plan written` on them. That pass's own mechanics — reference names, what each state requires, who must set a flag independently of whom, and how to read a fenced-write refusal — belong to whichever skill runs it, not to this one.

package/packages/agent-skills/assets/to-workitems/references/AZURE-DEVOPS-HIERARCHY.md

@@ -1,121 +0,0 @@
-# How Azure DevOps organises Epic, Feature, PBI, Bug
-
-From the official docs, not inference:
-- [About work items and work item types](https://learn.microsoft.com/en-us/azure/devops/boards/work-items/about-work-items?view=azure-devops)
-- [Organize your product backlog](https://learn.microsoft.com/en-us/azure/devops/boards/backlogs/organize-backlog?view=azure-devops)
-
-## The hierarchy is four levels, by category
-
-| Category | Type (Scrum process) | Appears on |
-| --- | --- | --- |
-| Epic | `Epic` | Epic portfolio backlog |
-| Feature | `Feature` | Feature portfolio backlog |
-| Requirement | `Product Backlog Item` | Product backlog and Sprints backlog |
-| Task | `Task` | Sprint backlog and Taskboard |
-| Bug | `Bug` | **depends on a team setting** — see Rule 3 |
-
-> "Epics group Features, Features group Requirements (User Stories, Product
-> Backlog Items, Issues, or Requirements), and Requirements group Tasks."
-
-## Rule 1 — parenting is restricted to adjacent levels
-
-> "You can only reparent backlog items under other features, and features under
-> other epics."
-
-So `parentId` for a Product Backlog Item **or a Bug** is always a Feature,
-never an Epic. Creating either with an Epic's id as `parentId` is refused
-before the request is sent, naming the mismatch:
-
-```
-must be parented to a Feature; work item 320 is a Epic
-```
-
-Reaching the Epic is the Feature's job. In a plan, `feature:` is the parent
-link and `epic:` is a cross-check on that Feature's own parent — read the
-Feature once (`workitem_list_or_get({ id: feature, raw: true })`) and compare
-`links.parent` to `epic:`; there is no need for a second call that fetches the
-Epic directly.
-
-**Every tracked type requires a parent — there is no root case.** Omitting
-`parentId` on a Feature, a Product Backlog Item, or a Bug is refused as
-`requires parentId`, whatever the type.
-
-## Rule 2 — one parent per work item
-
-Parent-child is single-valued. Ordering and blocking therefore **cannot** be
-expressed by parenting; they need `System.LinkTypes.Dependency-Reverse` links,
-which `workitem_create_or_update`'s `predecessors` argument creates — one link
-per id, in the order given.
-
-Supplying `parentId` on an **update** moves the item: the old parent link is
-removed, never kept alongside the new one.
-
-`predecessors` is the only argument that creates them. It has no alias at the
-tool level: `blockedBy` is not read.
-
-The complete set of link kinds this server will write is `parent`,
-`predecessors`, `related` — nothing else, including `children` and
-`successors`, which the board derives from the other end of `parent` and
-`predecessors` and so are never a second way to say the same thing.
-
-## Rule 3 — a Bug parents to the Feature, the same as a Product Backlog Item
-
-Creating a Bug with the plan's Feature as `parentId` succeeds. A Bug can also
-carry `related: [<id>]` to record which item it was found while building,
-alongside its `System.LinkTypes.Hierarchy-Reverse` parent link.
-
-## Rule 4 — states are exact, and per work item type
-
-Product Backlog Item and Bug share one state list, in board order:
-
-| State | Category |
-| --- | --- |
-| New | Proposed |
-| Approved | Proposed |
-| Committed | InProgress |
-| In Progress | InProgress |
-| In Testing | InProgress |
-| Done | Completed |
-| Removed | Removed |
-
-This list was read from the board, not transcribed from generic Scrum
-documentation — treat it as exhaustive. A state outside this list is not a
-looser spelling of one of these; it is wrong. `Removed` hides the item from
-the backlog and is otherwise unconstrained. What each state requires of the
-six Build flags is out of scope here — to-workitems never sets a flag or
-changes state (see [`../SKILL.md`](../SKILL.md), Step 6); that belongs to
-whichever skill runs that pass. Read `System.State` verbatim — never infer a
-local status from a remote string.
-
-## What can be created, and what can only be a parent
-
-Creating a work item is restricted to `Feature`, `Product Backlog Item`,
-`Bug`. Both `Epic` and `Task` are refused with the same message:
-
-```
-type must be one of ...
-```
-
-Epic is still a **valid parent** — a Feature's own `parentId` — it simply
-cannot be the type of a new work item.
-
-**The parent-type rule covers all three creatable types**, Feature included:
-
-```js
-PARENT_TYPE_REQUIREMENT = { Feature: "Epic", "Product Backlog Item": "Feature", Bug: "Feature" }
-```
-
-So a Feature parented to anything but an Epic is refused by name, on create and
-on update alike — `Feature must be parented to a Epic; work item <id> is a
-<type>`. The check reads the parent through the raw work-item endpoint rather
-than the tracked-type tool, which is how it can inspect an Epic that
-`workitem_list_or_get` refuses to return.
-
-What the server still cannot check is **which** Epic. A Feature parented to the
-wrong Epic is the right type and creates cleanly, so an unset or mistyped
-`epic:` is caught by type but never by intent — that part stays on the agent,
-and on the human it asks. See [`../SKILL.md`](../SKILL.md)'s "Do Not Use When".
-
-`Task` stays out for a design reason, not just a server one: an Execution row
-is already sized to one item, and a fourth level would need a second place to
-record progress, which is the duplication this design exists to avoid.