@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.26 → 0.1.28

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
 size: 82912736 bytes
-sha256: 09177fe24ffc58ce3e4224020a520a03d35e9cb77882aa86c1b0e9396a84f6b9
+sha256: 1a2ae55423977502b4d00c4c8ba08eac8d3c2d4d9388c934b0ea1f7ff80efe72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

package/packages/agent-hooks/src/gating/config.ts

@@ -220,7 +220,9 @@ function rejectUnknownKeys(
  * Root tables this module accepts. It owns `version`/`hooks`/`rules`/`repo`
  * and never reads the rest — they belong to the other tools sharing this file:
  * `controls` to adl-repo-controls, `extensions` (formerly `skills`) to
- * adl-extensions, and `azdo` to shared Azure DevOps configuration.
+ * adl-extensions, `azdo` to shared Azure DevOps configuration, and `dispatch`
+ * to adl-dispatcher (the integration-base ref + per-checkout selector the
+ * dispatcher reads; this package neither reads nor validates its schema).
  *
  * `skills` is retained alongside `extensions` on purpose. adl-extensions
  * HARDCUT to `[extensions]` because an extension owns its skills rather than
@@ -229,7 +231,7 @@ function rejectUnknownKeys(
  * here would fail exactly those repos, the ones nobody has touched yet.
  */
 const KNOWN_ROOT_KEYS: ReadonlySet<string> = new Set([
-  'version', 'hooks', 'rules', 'repo', 'agent', 'controls', 'skills', 'extensions', 'azdo',
+  'version', 'hooks', 'rules', 'repo', 'agent', 'controls', 'skills', 'extensions', 'azdo', 'dispatch',
 ])
 
 /**

package/packages/agent-hooks/src/rules/impl/deny-allowlist.ts

@@ -14,9 +14,8 @@
  *   - `tool.find`'s deny text pointed at `search query "<text>"` for every
  *     path-pattern request, which is the wrong recommendation — `search`
  *     searches CONTENT, not paths; the right tool for `find -name '*.md'` is
- *     `rg --files -g '<glob>'` or `ctx_glob`.
- *   - `tool.native-search`'s deny text pointed at `ctx_search` /
- *     `ctx_compose` / `ctx_callgraph` / `rg / ast-grep`, never at `search
+ *     `rg --files -g '<glob>'.
+ *   - `tool.native-search`'s deny text pointed at `rg / ast-grep`, never at `search
  *     query` — the docs-and-plans case that 11 of 25 kimi denials actually were.
  *
  * Every entry here is the canonical name (matches the binary on PATH); the
@@ -72,9 +71,7 @@ export const ALLOWED_SEARCH_TOOLS: readonly AllowedTool[] = [
     purpose:
       'docs and plans by MEANING: hybrid semantic + keyword (enoted-search@0.2.2 at /usr/local/bin/search)',
     examples: [
-      'search query "how do I author a metric"    # hybrid (default)',
-      'search query "<text>" --mode keyword       # when you only want literal matches',
-      'search query "<text>" --mode semantic      # when the doc talks about it, not the word',
+      'search <semantic query | keywords> ',
     ],
   },
   {
@@ -97,33 +94,8 @@ export const ALLOWED_SEARCH_TOOLS: readonly AllowedTool[] = [
       'rg "pass|fail"                # stdin filter, NOT grep',
     ],
   },
-  {
-    binary: 'ctx_search',
-    purpose: 'lean-ctx MCP indexed code search (action=symbol for an exact symbol)',
-    examples: [
-      'ctx_search(action=symbol, handle="path#name@Lstart")',
-    ],
-  },
-  {
-    binary: 'ctx_glob',
-    purpose: 'lean-ctx MCP indexed file search (path patterns only, not content)',
-    examples: ['ctx_glob(pattern, path)'],
-  },
-  {
-    binary: 'ctx_read',
-    purpose: 'lean-ctx MCP indexed file read (compressed output, no token tax)',
-    examples: ['ctx_read(path, mode)'],
-  },
-  {
-    binary: 'ctx_compose',
-    purpose: 'lean-ctx MCP context compose (orient on a task without reading whole files)',
-    examples: ['ctx_compose(task)'],
-  },
-  {
-    binary: 'ctx_callgraph',
-    purpose: 'lean-ctx MCP callers/impact for callers and engines (crg also answers these, but via shell)',
-    examples: ['ctx_callgraph(symbol)'],
-  },
+
+
 ] as const
 
 /**
@@ -146,7 +118,7 @@ export function recommendationBlock(filter?: (tool: AllowedTool) => boolean): st
 
 /**
  * The set of paths where `search` (semantic + keyword) is the right tool
- * over `rg`/`crg`/`ctx_search`. A native `Grep` whose `tool_input.path`
+ * over `rg`/`crg` A native `Grep` whose `tool_input.path`
  * starts with one of these should redirect to `search`, not to `rg` — the
  * model is searching for the document that *talks* about X, not for the
  * literal text X.

package/packages/agent-hooks/src/rules/impl/tool-find.ts

@@ -16,7 +16,7 @@
  *     but every `find` denial that day was a path pattern (`find -name '*.md'
  *     -newermt '2026-10-01'`, `find ~/Documents -name 'code-review-graph*'`),
  *     never a content search. The right tool for path patterns is `rg --files
- *     -g '<glob>'` or `ctx_glob`. `search` only answers when the doc-tree case
+ *     -g '<glob>'`. `search` only answers when the doc-tree case
  *     is the question — and `find` can't tell which case it is, so we lead
  *     with `rg --files -g '<glob>'` (the most common case) and put `search`
  *     behind it as the docs/plans fallback.
@@ -42,7 +42,7 @@ export const toolFind: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked find. It emits PATHS, never contents — pipe it to grep and you filter filenames. Use instead: `rg --files -g "<glob>"` for path patterns, `ctx_glob` for indexed file search, or `search query "<text>"` only when the path is `docs/`, `plans/`, or `.scratchpad/`.',
+      user: 'Blocked find. It emits PATHS, never contents — pipe it to grep and you filter filenames. Use instead: `rg --files -g "<glob>"` for path patterns, or `search query "<text>"` only when the path is `docs/`, `plans/`, or `.scratchpad/`.',
       agent:
         'DENIED find. `find` emits PATHS, so piping it to grep (or any other text tool) filters FILENAMES, never ' +
         'file contents — that produces confidently wrong answers, not merely incomplete ones. For example, ' +
@@ -51,12 +51,12 @@ export const toolFind: RuleSpec = {
         'described the subject, while counting name-matches whose contents were irrelevant.\n' +
         'Match the tool to the question:\n' +
         '  rg --files -g "<glob>" -g "!node_modules/**"    path patterns (default)\n' +
-        '  ctx_glob(pattern, path)                          indexed file search\n' +
-        '  search query "<text>"                            only when the path is docs/, plans/, or .scratchpad/ and the doc TALKS about X\n' +
-        '  crg search "<text>" --kind File                  code-graph search by name or text\n' +
+        '  search query "<text>"                          only when the path is docs/, plans/, or .scratchpad/ and the doc TALKS about X\n' +
+        '  crg search "<text>" --kind File                code-graph search by name or text\n' +
+        'Worked example: `search query "how do I author a metric"` (correct subcommand form).\n' +
         'The full replacement table from `./deny-allowlist.ts`:\n' +
         recommendationBlock(
-          (row) => row.binary === 'rg' || row.binary === 'search' || row.binary === 'crg' || row.binary === 'ctx_glob',
+          (row) => row.binary === 'rg' || row.binary === 'search' || row.binary === 'crg',
         ) +
         `Blocked command: ${ctx.snippet}`,
     }
@@ -103,7 +103,7 @@ export const toolFind: RuleSpec = {
       'rg --files -g "*.md" -g "!node_modules/**"',
       'rg --files -g "*.test.ts"',
       'crg search "term" --kind File',
-      'ctx_glob "*.md"',
+
     ],
   },
 }

package/packages/agent-hooks/src/rules/impl/tool-grep.ts

@@ -2,15 +2,14 @@
  * `grep`, unconditionally.
  *
  * Owner decision, 2026-09-15: ban the grep family outright and steer at
- * `rg` / `ast-grep` / `search` / `crg` / `ctx_search`. Every replacement is
+ * `rg` / `ast-grep` / `search` / `crg`. Every replacement is
  * measured present and passing its respective allowlist:
  *
  *   rg        /opt/homebrew/bin/rg        stdin filter AND tree search
  *   fd        10.4.2                      replaces find
  *   ast-grep  0.45.3                      structural search neither ever did
- *   search    /usr/local/bin/search       hybrid semantic + keyword (per-repo allowlist)
+ *   search    /usr/local/bin/search       hybrid semantic + keyword
  *   crg       /usr/local/bin/crg          code-graph: callers/callees/impact
- *   ctx_search / ctx_glob / ctx_read       lean-ctx MCP (per-repo allowlist)
  *
  * BLANKET, including a pure stdin filter. An earlier proposal carved out
  * `npm test 2>&1 | grep -E '…'` as "reading output, not searching code". That
@@ -56,7 +55,7 @@ export const toolGrep: RuleSpec = {
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg / ctx_search (per-repo allowlist).',
+  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg (per-repo allowlist).',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'grep') return null
@@ -64,12 +63,12 @@ export const toolGrep: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked grep. Pick the tool for the question, in this order: `ast-grep` for code shapes, `search` for docs/plans by meaning, `crg` for code-graph, `rg` for literal text (incl. stdin), `ctx_search` for the indexed code search.',
+      user: 'Blocked grep. Pick the tool for the question, in this order: `ast-grep` for code shapes, `search` for docs/plans by meaning, `crg` for code-graph, `rg` for literal text (incl. stdin).',
       agent:
         'DENIED grep. A pure `something | grep -v <X>` is still a grep — refine the upstream command with ' +
         '`--glob \'!<X>\'` or `--type-not` instead of piping. Match the tool to the question - in this order:\n' +
         recommendationBlock(
-          (row) => row.binary !== 'ctx_glob' && row.binary !== 'ctx_read' && row.binary !== 'ctx_compose',
+          (row) => row.binary !== 'ctx_glob' && row.binary !== 'ctx_read' && row.binary !== 'ctx_compose' && row.binary !== 'ctx_search',
         ) +
         '\nA pure output filter is no exception: ripgrep filters stdin exactly as grep does. ' +
         `Blocked command: ${ctx.snippet}`,
@@ -101,7 +100,7 @@ export const toolGrep: RuleSpec = {
       "rg -n TODO src/ -g '!node_modules/**'",
       'fd -e ts src/',
       'ast-grep --version',
-      'search query "how do I author a metric"',
+      'search how do I author a metric',
       'crg search TODO --kind File',
       'ls -la',
       // The word `grep` is not the command `grep`.

package/packages/agent-hooks/src/rules/impl/tool-native-search.ts

@@ -20,7 +20,7 @@
  * Edit/Write are untouched — this rule is about search surfaces only.
  *
  * DENY TEXT (2026-10-03, after research-2026-10-02-search-tool-usage-across-surfaces
- * found a 3/95 pivot rate and zero pivots to `search query` / `crg`):
+ * found a 3/95 pivot rate and zero pivots to `search` / `crg`):
  *
  *   - Earlier this text recommended `ctx_search`/`ctx_compose`/`ctx_callgraph`
  *     and `rg / ast-grep` only. The model took the lean-ctx MCP path (3/3
@@ -56,7 +56,7 @@ export const toolNativeSearch: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the native Grep/Glob/Search tools; steer at search query (docs/plans), crg (code graph), ctx_search, rg, ast-grep.',
+  summary: 'Deny the native Grep/Glob/Search tools; steer at search <semantic query | keywords> (docs/plans), crg (code graph), rg, ast-grep.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'tool-call') return null
@@ -78,7 +78,7 @@ export const toolNativeSearch: RuleSpec = {
   message(finding: Finding, ctx: MessageContext) {
     const tool = typeof finding.detail.tool === 'string' ? finding.detail.tool : 'this tool'
     // Path-aware recommendation. Native Grep on docs/plans/.scratchpad ->
-    // lead with `search`; everywhere else -> lead with `crg`/`ctx_search`.
+    // lead with `search`; everywhere else -> lead with `crg`.
     const path = typeof finding.detail.path === 'string' ? finding.detail.path : ''
     const isDoc = DOC_TREES.some((prefix) => path.startsWith(prefix))
 
@@ -88,13 +88,13 @@ export const toolNativeSearch: RuleSpec = {
     const leadLines = leadExamples.map((e) => `    ${e}`).join('\n')
 
     const tail = recommendationBlock(
-      (row) => row.binary !== leadTool && row.binary !== 'ctx_compose' && row.binary !== 'ctx_callgraph',
+      (row) => row.binary !== leadTool,
     )
 
     return {
       user: isDoc
-        ? `Blocked the native ${tool} tool on \`${path}\` (a docs/plans/.scratchpad tree). The right answer is \`search query "<text>"\` — semantic + keyword, finds the doc that *talks* about X. \`rg\`/\`crg\`/\`ctx_search\` are the wrong tools here.`
-        : `Blocked the native ${tool} tool. Lead with \`crg search "<text>"\` for code-graph queries, fall back to \`rg\`/\`ast-grep\` for literal text, \`ctx_search\` for indexed code, \`search query "<text>"\` only when the path is docs/plans/.scratchpad.`,
+        ? `Blocked the native ${tool} tool on \`${path}\` (a docs/plans/.scratchpad tree). The right answer is \`search <semantic query | keywords>\` — semantic + keyword, finds the doc that *talks* about X. \`rg\`/\`crg\` are the wrong tools here.`
+        : `Blocked the native ${tool} tool. Lead with \`crg search "<text>"\` for code-graph queries, fall back to \`rg\`/\`ast-grep\` for literal text, \`search <semantic query | keywords>\` only when the path is docs/plans/.scratchpad.`,
       agent:
         `DENIED the native ${tool} tool. It is routed through the lean-ctx hook but NOT converted — ` +
         'the call still runs natively — so it is a way around the shell search ban rather than an ' +

package/packages/azdo/scripts/probe-ado-rules.ts

@@ -0,0 +1,311 @@
+#!/usr/bin/env bun
+// probe-ado-rules.ts — verify the LIVE Azure DevOps process rules against the
+// pinned expectation (src/workflow-ladder.csv). Read-only metadata first,
+// then an empirical matrix probe of a REAL item supplied by the operator
+// (default 546): the item is reset (→ Removed → New, both verified open)
+// and walked to each ladder state, where every CSV transition for that state
+// is attempted via RAW json-patch — bypassing this repo's own fence on
+// purpose (the probe tests ADO, not us). If an expected-refused edge turns
+// out allowed and moves the item, the walk returns and continues. The item
+// is restored to its original state at the end.
+//
+// Usage: bun packages/azdo/scripts/probe-ado-rules.ts [item-id] [--metadata-only]
+import { AdoClient } from "../src/lib/client.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ORG = "amsterdamdatalabs";
+const PROJECT = "Infrastructure-AzDo";
+const ORG_API = `https://dev.azure.com/${ORG}/_apis`;
+const PROJECT_API = `https://dev.azure.com/${ORG}/${PROJECT}/_apis`;
+const ITEM_ID = Number(process.argv.find((a) => /^\d+$/.test(a)) ?? 546);
+const METADATA_ONLY = process.argv.includes("--metadata-only");
+
+interface CsvRow {
+  workItemType: string;
+  fromState: string;
+  toState: string;
+  rule: string;
+  skippedStates: string;
+  owner: string;
+  note: string;
+  observed?: string;
+}
+
+const orgClient = new AdoClient({ baseUrl: ORG_API });
+const projectClient = new AdoClient({ baseUrl: PROJECT_API });
+
+function loadExpectations(type: string): CsvRow[] {
+  const csv = readFileSync(join(import.meta.dir, "../src/workflow-ladder.csv"), "utf8");
+  const rows: CsvRow[] = [];
+  for (const line of csv.trim().split("\n").slice(1)) {
+    const [workItemType, fromState, toState, rule, skippedStates, owner, note] = line.split(",");
+    if (workItemType !== type) continue;
+    rows.push({ workItemType, fromState, toState, rule, skippedStates, owner, note });
+  }
+  return rows;
+}
+
+async function authToken(): Promise<string> {
+  const raw = projectClient as unknown as { acquireAccessToken(): Promise<string> };
+  return raw.acquireAccessToken();
+}
+
+async function patchState(id: number, state: string): Promise<{ ok: boolean; status: number; message: string }> {
+  const token = await authToken();
+  const resp = await fetch(`${PROJECT_API}/wit/workitems/${id}?api-version=7.1`, {
+    method: "PATCH",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json-patch+json" },
+    body: JSON.stringify([{ op: "add", path: "/fields/System.State", value: state }]),
+  });
+  const text = await resp.text();
+  return { ok: resp.ok, status: resp.status, message: text.replace(/\s+/g, " ").slice(0, 200) };
+}
+
+async function currentState(id: number): Promise<string> {
+  const item = await projectClient.get<any>(`/wit/workitems/${id}`, { "api-version": "7.1" });
+  return item.fields?.["System.State"] ?? "?";
+}
+
+// forward main line per the CSV's edges — allowed AND human-only edges both
+// count for ordering: G1/G3 are fence-only, so ADO still permits them and
+// the walk uses them to traverse (their rows are probed like any other).
+function forwardOrder(rows: CsvRow[]): string[] {
+  const edges = new Map<string, string>();
+  for (const r of rows) {
+    if ((r.rule === "allowed" || r.rule === "human-only") && r.fromState !== r.toState && !edges.has(r.fromState)) {
+      edges.set(r.fromState, r.toState);
+    }
+  }
+  const order: string[] = [];
+  let s = "New";
+  const guard = new Set<string>();
+  while (s && !guard.has(s)) {
+    guard.add(s);
+    order.push(s);
+    s = edges.get(s) ?? "";
+  }
+  return order;
+}
+
+// The forward main line in order — the walk's map. ADO permits the fence-only
+// hops (G1 etc.) for this identity, so traversal may use every adjacent edge.
+const MAIN = [
+  "New",
+  "In Planning",
+  "Awaiting Approval",
+  "Approved",
+  "Spec Validation",
+  "In Implementation",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
+  "Done",
+];
+
+async function resetToNew(id: number): Promise<void> {
+  for (let i = 0; i < 6; i++) {
+    const here = await currentState(id);
+    if (here === "New") return;
+    await patchState(id, here === "Parked for Removal" ? "Removed" : "New");
+  }
+}
+
+async function walkTo(id: number, rows: CsvRow[], target: string): Promise<boolean> {
+  for (let guard = 0; guard < 30; guard++) {
+    const here = await currentState(id);
+    if (here === target) return true;
+    let next: string;
+    if (target === "Committed") next = "Committed"; // retired state: enter directly to probe its exits
+    else if (target === "Parked for Removal") next = "Parked for Removal"; // parkable from anywhere
+    else if (target === "Removed") next = here === "Parked for Removal" ? "Removed" : "Parked for Removal";
+    else if (here === "Parked for Removal" || here === "Removed") next = "New";
+    else if (MAIN.indexOf(here) === -1) return false; // retired/unknown — cannot walk
+    else {
+      const hi = MAIN.indexOf(here);
+      const ti = MAIN.indexOf(target);
+      next = hi < ti ? MAIN[hi + 1]! : "New";
+    }
+    const res = await patchState(id, next);
+    if (!res.ok) return false;
+  }
+  return false;
+}
+
+async function probeState(id: number, rows: CsvRow[], state: string): Promise<void> {
+  for (let round = 0; round < 24; round++) {
+    if ((await currentState(id)) !== state) {
+      if (!(await walkTo(id, rows, state))) {
+        for (const r of rows.filter((x) => x.fromState === state && x.toState !== "Committed" && x.observed === undefined)) {
+          r.observed = `UNREACHED (could not return to "${state}")`;
+        }
+        return;
+      }
+      continue;
+    }
+    // deferred: → Committed rows are probed in the epilogue (they can strand
+    // the walk in the ruleless retired state mid-pass)
+    const candidates = rows.filter(
+      (r) => r.fromState === state && r.toState !== "Committed" && r.observed === undefined && r.fromState !== r.toState
+    );
+    const refusedFirst = [
+      ...candidates.filter((r) => r.rule !== "allowed" && r.rule !== "human-only"),
+      ...candidates.filter((r) => r.rule === "allowed" || r.rule === "human-only"),
+    ];
+    const next = refusedFirst[0];
+    if (!next) return; // all rows for this state probed
+    const res = await patchState(id, next.toState);
+    next.observed = res.ok ? "allowed" : `refused ${res.status}: ${res.message}`;
+  }
+}
+
+function verdictClass(observed: string | undefined): string {
+  if (!observed) return "?";
+  if (observed.startsWith("allowed")) return "allowed";
+  if (observed.startsWith("refused")) return "refused";
+  if (observed.startsWith("identity")) return "identity";
+  return "unreached";
+}
+
+function report(name: string, rows: CsvRow[]) {
+  console.log(`\n---- ${name}: observed vs expected ----`);
+  const holes: string[] = []; // expected allowed but ADO refused → blocks real flow
+  const fenceOnly: string[] = []; // expected refused but ADO allows → our fence is the only guard
+  const unreached: string[] = [];
+  for (const r of rows) {
+    const obs = verdictClass(r.observed);
+    const exp = r.rule === "allowed" ? "allowed" : "refused";
+    let mark = "OK ";
+    if (obs === "unreached" || obs === "?") { mark = "?? "; unreached.push(`${r.fromState} → ${r.toState} (expected ${r.rule})`); }
+    else if (exp === "allowed" && obs !== "allowed") { mark = "!! "; holes.push(`${r.fromState} → ${r.toState}: expected allowed, ADO ${obs} — ${r.observed}`); }
+    else if (exp === "refused" && obs === "allowed") { mark = "!! "; fenceOnly.push(`${r.fromState} → ${r.toState} (expected ${r.rule})`); }
+    console.log(`${mark}${r.fromState.padEnd(18)} → ${r.toState.padEnd(18)} expected=${r.rule.padEnd(12)} observed=${r.observed ?? "?"}`);
+  }
+  console.log(`\nWHITE SPOTS (${name})`);
+  console.log(` blockers (expected allowed, ADO refused): ${holes.length}`);
+  for (const h of holes) console.log(`  !! ${h}`);
+  console.log(` our-fence-only (expected refused, ADO allows — ADO cannot enforce against this identity): ${fenceOnly.length}`);
+  for (const f of fenceOnly) console.log(`  ** ${f}`);
+  console.log(` unreached: ${unreached.length}`);
+  for (const u of unreached) console.log(`  ?? ${u}`);
+}
+
+// ---- Phase A: read-only metadata ----------------------------------------
+console.log("== Phase A: process metadata ==");
+let processId: string | null = null;
+try {
+  const processes = await orgClient.get<any>("/work/processes", { "api-version": "7.1" });
+  const list = processes.value ?? [];
+  const adl = list.find((p: any) => String(p.name ?? "").trim() === "ADL-Product");
+  processId = adl?.typeId ?? adl?.id ?? null;
+  console.log(`processes: ${list.map((p: any) => `${JSON.stringify(p.name)}(${p.id})`).join(", ")}`);
+  console.log(`ADL-Product id: ${processId ?? "NOT FOUND"}`);
+} catch (e) {
+  console.log(`processes list unreadable: ${String(e).slice(0, 140)}`);
+}
+
+if (processId) {
+  let wits: any[] = [];
+  try {
+    const list = await orgClient.get<any>(`/work/processes/${processId}/workitemtypes`, { "api-version": "7.1" });
+    wits = list.value ?? [];
+  } catch (e) {
+    console.log(`workitemtypes unreadable: ${String(e).slice(0, 140)}`);
+  }
+  for (const name of ["Bug", "Product Backlog Item"]) {
+    const wit = wits.find((w: any) => String(w.name).trim() === name);
+    if (!wit) { console.log(`${name}: NOT in workitemtypes list`); continue; }
+    const ref = encodeURIComponent(wit.referenceName ?? wit.id ?? name);
+    try {
+      const states = await orgClient.get<any>(`/work/processes/${processId}/workitemtypes/${ref}/states`, { "api-version": "7.1" });
+      const names = (states.value ?? []).map((s: any) => `${s.name}${s.isDisabled ? " (disabled)" : ""}`);
+      console.log(`${name} states (${names.length}): ${names.join(" | ")}`);
+    } catch (e) {
+      console.log(`${name} states unreadable: ${String(e).slice(0, 120)}`);
+    }
+    for (const api of ["7.2-preview.1", "7.1"]) {
+      try {
+        const rules = await orgClient.get<any>(`/work/processes/${processId}/workitemtypes/${ref}/rules`, { "api-version": api });
+        const rs = rules.value ?? [];
+        console.log(`${name} rules (${api}): READABLE, ${rs.length}`);
+        for (const r of rs.slice(0, 24)) console.log(` - [${r.isDisabled ? "off" : "on"}] ${r.name}`);
+        break;
+      } catch (e) {
+        console.log(`${name} rules (${api}): ${String(e).slice(0, 80)}`);
+      }
+    }
+  }
+}
+
+// ---- Phase B: empirical matrix probe of the operator-supplied item -------
+if (METADATA_ONLY) {
+  console.log("\n(metadata-only: skipping empirical probe)");
+} else try {
+  const item = await getItemAny(ITEM_ID);
+  const type: string = item.fields?.["System.WorkItemType"];
+  const startState: string = item.fields?.["System.State"];
+  console.log(`\n== Phase B: probing #${ITEM_ID} (${type}, started at "${startState}") ==`);
+  const rows = loadExpectations(type);
+  await resetToNew(ITEM_ID);
+  const probeTargets = [...MAIN, "Parked for Removal", "Removed"];
+  for (const state of probeTargets) {
+    await probeState(ITEM_ID, rows, state);
+    await resetToNew(ITEM_ID); // clean slate between states
+  }
+  // Epilogue: → Committed rows, then Committed exits (the retired state has
+  // no ADO rules, so entering/exiting behaves differently — probe it last,
+  // reset whenever the walk strands).
+  const parkedTargets = [...probeTargets, "Committed"];
+  for (const state of parkedTargets) {
+    const row = rows.find((r) => r.fromState === state && r.toState === "Committed" && r.observed === undefined);
+    if (!row) continue;
+    const reached = await walkTo(ITEM_ID, rows, state);
+    console.log(`(epilogue: at "${await currentState(ITEM_ID)}", probing ${state} → Committed — walk ${reached ? "ok" : "FAILED"})`);
+    if (reached) {
+      const res = await patchState(ITEM_ID, "Committed");
+      row.observed = res.ok ? "allowed" : `refused ${res.status}: ${res.message}`;
+      console.log(`(epilogue: ${state} → Committed observed=${row.observed.slice(0, 60)})`);
+    } else {
+      row.observed = `UNREACHED (could not reach "${state}")`;
+    }
+    await resetToNew(ITEM_ID);
+  }
+  // Committed exits: enter from Done (empirically reachable), probe each row,
+  // escaping to New after every successful move.
+  if (rows.some((r) => r.fromState === "Committed" && r.observed === undefined)) {
+    if (await walkTo(ITEM_ID, rows, "Done")) {
+      await patchState(ITEM_ID, "Committed");
+      for (let round = 0; round < 20; round++) {
+        if ((await currentState(ITEM_ID)) !== "Committed") {
+          const back = await patchState(ITEM_ID, "Committed");
+          if (!back.ok) break;
+        }
+        const next = rows.find((r) => r.fromState === "Committed" && r.observed === undefined && r.fromState !== r.toState);
+        if (!next) break;
+        const res = await patchState(ITEM_ID, next.toState);
+        next.observed = res.ok ? "allowed" : `refused ${res.status}: ${res.message}`;
+      }
+    } else {
+      for (const r of rows.filter((x) => x.fromState === "Committed" && x.observed === undefined)) {
+        r.observed = 'UNREACHED (could not reach "Done" to enter Committed)';
+      }
+    }
+  }
+  await resetToNew(ITEM_ID);
+  for (const r of rows.filter((x) => x.observed === undefined)) {
+    r.observed = "UNREACHED (state never visited)";
+  }
+  report(type, rows);
+  // restore
+  await resetToNew(ITEM_ID);
+  const finalState = await currentState(ITEM_ID);
+  console.log(finalState === startState
+    ? `\nrestored: #${ITEM_ID} back at "${startState}"`
+    : `\n!! RESTORE INCOMPLETE: at "${finalState}", expected "${startState}"`);
+} catch (e) {
+  console.log(`probe failed: ${String(e).slice(0, 240)}`);
+}
+
+async function getItemAny(id: number): Promise<any> {
+  return projectClient.get<any>(`/wit/workitems/${id}`, { "api-version": "7.1" });
+}

package/packages/azdo/src/azdo-wit.ts

@@ -2,7 +2,7 @@
 // mcp-server.ts — there is no CLI entry point here (nothing else in the
 // repo invoked this file as a CLI).
 import { AdoClient, adoProjectUrl, resolveProject } from './lib/client.ts'
-import { evaluateWorkflowState, formatWorkflowRefusal, pickWorkflowFlags, type WorkflowFlagRef } from './workflow-rules.ts'
+import { evaluateWorkflowTransition, formatWorkflowRefusal } from './workflow-rules.ts'
 
 // Work-item calls use the SAME org/project resolution as every other tool in
 // this package (`lib/client.ts`). They used to carry their own `config` object
@@ -116,12 +116,15 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     if (args.type !== 'Feature' && args.fields !== undefined && 'System.State' in args.fields) {
       throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
     }
-    // FENCE 2 (create): a new PBI/Bug starts in New with every flag false, so
-    // the gate on the resulting pair refuses any non-false flag or advanced
-    // state the same way an update would.
+    // FENCE 2 (create): a new PBI/Bug starts at New, so a create whose
+    // `state` lands anywhere past New is already a ladder refusal — G1
+    // approval, merge automation and human cancellation all happen after
+    // create.
     if (args.type !== 'Feature') {
-      const violations = evaluateWorkflowState(args.type, args.state ?? 'New', pickWorkflowFlags(args.fields));
-      if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+      if (args.state !== undefined && args.state !== 'New') {
+        const violations = evaluateWorkflowTransition(args.type, 'New', args.state)
+        if (violations.length) throw new Error(formatWorkflowRefusal(violations))
+      }
     }
     const ops = buildWriteOps(args);
     const c = await getClient();
@@ -150,14 +153,14 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     if (currentType === 'Feature') throw new Error(`fields may only set Custom.* fields; 'System.State' is managed by this tool`);
     throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
   }
-  // FENCE 2 (workflow matrix): evaluate the RESULTING (state, flags) pair on
-  // every write — a state move and a flag-only update are both writes, and a
-  // write that leaves the pair violating any yes/no row is refused.
+  // FENCE 2 (state ladder): evaluate the RESULTING transition on every write
+  // that moves System.State — a move that skips gates, reaches a human-owned
+  // state (Approved/Done/Removed) or walks off the ladder is refused. Writes
+  // that leave the state untouched are not gated.
   if (currentType !== 'Feature') {
-    const postState = args.state ?? current.fields?.['System.State'];
-    const postFlags: Partial<Record<WorkflowFlagRef, boolean>> = { ...pickWorkflowFlags(current.fields), ...pickWorkflowFlags(args.fields) };
-    const violations = evaluateWorkflowState(currentType, postState, postFlags);
-    if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+    const currentState = current.fields?.['System.State']
+    const violations = evaluateWorkflowTransition(currentType, currentState, args.state ?? currentState)
+    if (violations.length) throw new Error(formatWorkflowRefusal(violations))
   }
   if (args.parentId !== undefined) {
     // A parent is singular. Read the existing item so the write can remove all

package/packages/azdo/src/workflow-ladder.csv

@@ -0,0 +1,241 @@
+work_item_type,from_state,to_state,rule,skipped_states,owner,note
+Product Backlog Item,New,In Planning,allowed,,,
+Product Backlog Item,New,Awaiting Approval,skipped,In Planning,,
+Product Backlog Item,New,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,New,Spec Validation,skipped,In Planning;Awaiting Approval;Approved,,
+Product Backlog Item,New,In Implementation,skipped,In Planning;Awaiting Approval;Approved;Spec Validation,,
+Product Backlog Item,New,In Testing,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation,,
+Product Backlog Item,New,In Review,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing,,
+Product Backlog Item,New,Updating Docs,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Product Backlog Item,New,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,New,Parked for Removal,allowed,,,
+Product Backlog Item,New,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,New,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,In Planning,New,allowed,,,
+Product Backlog Item,In Planning,Awaiting Approval,allowed,,,
+Product Backlog Item,In Planning,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,In Planning,Spec Validation,skipped,Awaiting Approval;Approved,,
+Product Backlog Item,In Planning,In Implementation,skipped,Awaiting Approval;Approved;Spec Validation,,
+Product Backlog Item,In Planning,In Testing,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation,,
+Product Backlog Item,In Planning,In Review,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing,,
+Product Backlog Item,In Planning,Updating Docs,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Product Backlog Item,In Planning,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,In Planning,Parked for Removal,allowed,,,
+Product Backlog Item,In Planning,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,In Planning,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Awaiting Approval,New,allowed,,,
+Product Backlog Item,Awaiting Approval,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Awaiting Approval,Spec Validation,skipped,Approved,,
+Product Backlog Item,Awaiting Approval,In Implementation,skipped,Approved;Spec Validation,,
+Product Backlog Item,Awaiting Approval,In Testing,skipped,Approved;Spec Validation;In Implementation,,
+Product Backlog Item,Awaiting Approval,In Review,skipped,Approved;Spec Validation;In Implementation;In Testing,,
+Product Backlog Item,Awaiting Approval,Updating Docs,skipped,Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Product Backlog Item,Awaiting Approval,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Awaiting Approval,Parked for Removal,allowed,,,
+Product Backlog Item,Awaiting Approval,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Awaiting Approval,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Approved,New,allowed,,,
+Product Backlog Item,Approved,Spec Validation,allowed,,,
+Product Backlog Item,Approved,In Implementation,skipped,Spec Validation,,
+Product Backlog Item,Approved,In Testing,skipped,Spec Validation;In Implementation,,
+Product Backlog Item,Approved,In Review,skipped,Spec Validation;In Implementation;In Testing,,
+Product Backlog Item,Approved,Updating Docs,skipped,Spec Validation;In Implementation;In Testing;In Review,,
+Product Backlog Item,Approved,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Approved,Parked for Removal,allowed,,,
+Product Backlog Item,Approved,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Approved,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Spec Validation,New,allowed,,,
+Product Backlog Item,Spec Validation,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Spec Validation,In Implementation,allowed,,,
+Product Backlog Item,Spec Validation,In Testing,skipped,In Implementation,,
+Product Backlog Item,Spec Validation,In Review,skipped,In Implementation;In Testing,,
+Product Backlog Item,Spec Validation,Updating Docs,skipped,In Implementation;In Testing;In Review,,
+Product Backlog Item,Spec Validation,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Spec Validation,Parked for Removal,allowed,,,
+Product Backlog Item,Spec Validation,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Spec Validation,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,In Implementation,New,allowed,,,
+Product Backlog Item,In Implementation,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,In Implementation,In Testing,allowed,,,
+Product Backlog Item,In Implementation,In Review,skipped,In Testing,,
+Product Backlog Item,In Implementation,Updating Docs,skipped,In Testing;In Review,,
+Product Backlog Item,In Implementation,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,In Implementation,Parked for Removal,allowed,,,
+Product Backlog Item,In Implementation,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,In Implementation,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,In Testing,New,allowed,,,
+Product Backlog Item,In Testing,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,In Testing,In Review,allowed,,,
+Product Backlog Item,In Testing,Updating Docs,skipped,In Review,,
+Product Backlog Item,In Testing,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,In Testing,Parked for Removal,allowed,,,
+Product Backlog Item,In Testing,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,In Testing,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,In Review,New,allowed,,,
+Product Backlog Item,In Review,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,In Review,In Implementation,allowed,,,
+Product Backlog Item,In Review,Updating Docs,allowed,,,
+Product Backlog Item,In Review,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,In Review,Parked for Removal,allowed,,,
+Product Backlog Item,In Review,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,In Review,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Updating Docs,New,allowed,,,
+Product Backlog Item,Updating Docs,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Updating Docs,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Updating Docs,Parked for Removal,allowed,,,
+Product Backlog Item,Updating Docs,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Updating Docs,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Done,In Planning,allowed,,,
+Product Backlog Item,Done,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Done,Parked for Removal,allowed,,,
+Product Backlog Item,Done,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Done,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Parked for Removal,New,allowed,,,
+Product Backlog Item,Parked for Removal,In Planning,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,Awaiting Approval,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Parked for Removal,Spec Validation,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,In Implementation,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,In Testing,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,In Review,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,Updating Docs,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Product Backlog Item,Parked for Removal,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Parked for Removal,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Product Backlog Item,Parked for Removal,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Removed,New,allowed,,,
+Product Backlog Item,Removed,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Product Backlog Item,Removed,Done,human-only,,entered only by PR merge automation into integration,
+Product Backlog Item,Removed,Parked for Removal,allowed,,,
+Product Backlog Item,Removed,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,New,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,In Planning,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Awaiting Approval,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Approved,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Spec Validation,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,In Implementation,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,In Testing,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,In Review,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Updating Docs,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Done,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Parked for Removal,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Product Backlog Item,Committed,Removed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,New,In Planning,allowed,,,
+Bug,New,Awaiting Approval,skipped,In Planning,,
+Bug,New,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,New,Spec Validation,skipped,In Planning;Awaiting Approval;Approved,,
+Bug,New,In Implementation,skipped,In Planning;Awaiting Approval;Approved;Spec Validation,,
+Bug,New,In Testing,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation,,
+Bug,New,In Review,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing,,
+Bug,New,Updating Docs,skipped,In Planning;Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Bug,New,Done,human-only,,entered only by PR merge automation into integration,
+Bug,New,Parked for Removal,allowed,,,
+Bug,New,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,New,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,In Planning,New,allowed,,,
+Bug,In Planning,Awaiting Approval,allowed,,,
+Bug,In Planning,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,In Planning,Spec Validation,skipped,Awaiting Approval;Approved,,
+Bug,In Planning,In Implementation,skipped,Awaiting Approval;Approved;Spec Validation,,
+Bug,In Planning,In Testing,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation,,
+Bug,In Planning,In Review,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing,,
+Bug,In Planning,Updating Docs,skipped,Awaiting Approval;Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Bug,In Planning,Done,human-only,,entered only by PR merge automation into integration,
+Bug,In Planning,Parked for Removal,allowed,,,
+Bug,In Planning,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,In Planning,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Awaiting Approval,New,allowed,,,
+Bug,Awaiting Approval,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Awaiting Approval,Spec Validation,skipped,Approved,,
+Bug,Awaiting Approval,In Implementation,skipped,Approved;Spec Validation,,
+Bug,Awaiting Approval,In Testing,skipped,Approved;Spec Validation;In Implementation,,
+Bug,Awaiting Approval,In Review,skipped,Approved;Spec Validation;In Implementation;In Testing,,
+Bug,Awaiting Approval,Updating Docs,skipped,Approved;Spec Validation;In Implementation;In Testing;In Review,,
+Bug,Awaiting Approval,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Awaiting Approval,Parked for Removal,allowed,,,
+Bug,Awaiting Approval,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Awaiting Approval,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Approved,New,allowed,,,
+Bug,Approved,Spec Validation,allowed,,,
+Bug,Approved,In Implementation,skipped,Spec Validation,,
+Bug,Approved,In Testing,skipped,Spec Validation;In Implementation,,
+Bug,Approved,In Review,skipped,Spec Validation;In Implementation;In Testing,,
+Bug,Approved,Updating Docs,skipped,Spec Validation;In Implementation;In Testing;In Review,,
+Bug,Approved,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Approved,Parked for Removal,allowed,,,
+Bug,Approved,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Approved,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Spec Validation,New,allowed,,,
+Bug,Spec Validation,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Spec Validation,In Implementation,allowed,,,
+Bug,Spec Validation,In Testing,skipped,In Implementation,,
+Bug,Spec Validation,In Review,skipped,In Implementation;In Testing,,
+Bug,Spec Validation,Updating Docs,skipped,In Implementation;In Testing;In Review,,
+Bug,Spec Validation,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Spec Validation,Parked for Removal,allowed,,,
+Bug,Spec Validation,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Spec Validation,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,In Implementation,New,allowed,,,
+Bug,In Implementation,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,In Implementation,In Testing,allowed,,,
+Bug,In Implementation,In Review,skipped,In Testing,,
+Bug,In Implementation,Updating Docs,skipped,In Testing;In Review,,
+Bug,In Implementation,Done,human-only,,entered only by PR merge automation into integration,
+Bug,In Implementation,Parked for Removal,allowed,,,
+Bug,In Implementation,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,In Implementation,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,In Testing,New,allowed,,,
+Bug,In Testing,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,In Testing,In Review,allowed,,,
+Bug,In Testing,Updating Docs,skipped,In Review,,
+Bug,In Testing,Done,human-only,,entered only by PR merge automation into integration,
+Bug,In Testing,Parked for Removal,allowed,,,
+Bug,In Testing,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,In Testing,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,In Review,New,allowed,,,
+Bug,In Review,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,In Review,In Implementation,allowed,,,
+Bug,In Review,Updating Docs,allowed,,,
+Bug,In Review,Done,human-only,,entered only by PR merge automation into integration,
+Bug,In Review,Parked for Removal,allowed,,,
+Bug,In Review,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,In Review,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Updating Docs,New,allowed,,,
+Bug,Updating Docs,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Updating Docs,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Updating Docs,Parked for Removal,allowed,,,
+Bug,Updating Docs,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Updating Docs,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Done,In Planning,allowed,,,
+Bug,Done,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Done,Parked for Removal,allowed,,,
+Bug,Done,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Done,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Parked for Removal,New,allowed,,,
+Bug,Parked for Removal,In Planning,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,Awaiting Approval,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Parked for Removal,Spec Validation,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,In Implementation,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,In Testing,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,In Review,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,Updating Docs,no-transition,,,Parked for Removal exits only to New (re-plan) or Removed (G3 human)
+Bug,Parked for Removal,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Parked for Removal,Removed,human-only,,G3 — human removal only; agents cannot move items to Removed,
+Bug,Parked for Removal,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Removed,New,allowed,,,
+Bug,Removed,Approved,human-only,,G1 — human approval only; agents cannot move items to Approved,
+Bug,Removed,Done,human-only,,entered only by PR merge automation into integration,
+Bug,Removed,Parked for Removal,allowed,,,
+Bug,Removed,Committed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,New,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,In Planning,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Awaiting Approval,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Approved,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Spec Validation,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,In Implementation,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,In Testing,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,In Review,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Updating Docs,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Done,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Parked for Removal,no-transition,,,Committed is a retired state (UI-hidden; no route references it)
+Bug,Committed,Removed,no-transition,,,Committed is a retired state (UI-hidden; no route references it)

package/packages/azdo/src/workflow-rules.ts

@@ -1,128 +1,194 @@
-// Workflow gate matrix for the board's six Build flags (Custom.Planwritten,
-// Custom.Implementationcomplete, Custom.Reviewpassed, Custom.Testspassing,
-// Custom.Docsupdated, Custom.Mergedtointegration) against the seven
-// Product Backlog Item/Bug states. Rebuild (2026-10-02) of the gate lost in
-// the P4 port — the authoritative definition is
-// docs/operations/workflow-matrix.csv in the enact-combined repo, copied
-// verbatim to src/workflow-rules-matrix.csv next to this file. The unit test
-// tests/workflow-rules.test.ts asserts this embedded table agrees with that
-// CSV on all 84 rows, so the compiled binary needs no file access at runtime.
-// Features and Epics carry no flags ("A Feature carries neither") and are
-// exempt: evaluateWorkflowState returns no violations for them.
+// Workflow state ladder for the board's Product Backlog Item/Bug items. The
+// 2026-10-04 ADL-Product process cutover replaced the six boolean Build
+// flags (Custom.Planwritten, Custom.Implementationcomplete,
+// Custom.Reviewpassed, Custom.Testspassing, Custom.Docsupdated,
+// Custom.Mergedtointegration) with ordered item states; the flags were
+// removed from the process at the cutover and nothing here reads or writes
+// them. The routes below implement the owner's final state model (PBI and
+// Bug identical), carried as src/workflow-ladder.csv next to this file; the
+// unit test tests/workflow-rules.test.ts asserts the embedded table agrees
+// with that CSV on every type × from × to triple, so the compiled binary
+// needs no file access at runtime. Features and Epics walk no item ladder
+// and are exempt: evaluateWorkflowTransition returns no violations for
+// them.
 
-/** The six Build flags, in CSV column order. */
-export const WORKFLOW_FLAG_REFS = [
-  'Custom.Planwritten',
-  'Custom.Implementationcomplete',
-  'Custom.Reviewpassed',
-  'Custom.Testspassing',
-  'Custom.Docsupdated',
-  'Custom.Mergedtointegration',
+/**
+ * The thirteen recognized states: the twelve active states of the final
+ * model, plus Committed — retired (UI-hidden, no route references it) but
+ * still recognized so a transition touching it is refused with the retired
+ * note instead of passing through silently.
+ */
+export const WORKFLOW_STATES = [
+  'New',
+  'In Planning',
+  'Awaiting Approval',
+  'Approved',
+  'Spec Validation',
+  'In Implementation',
+  'In Testing',
+  'In Review',
+  'Updating Docs',
+  'Done',
+  'Parked for Removal',
+  'Removed',
+  'Committed',
 ] as const;
-export type WorkflowFlagRef = (typeof WORKFLOW_FLAG_REFS)[number];
+export type WorkflowState = (typeof WORKFLOW_STATES)[number];
 
-export const WORKFLOW_FLAG_LABELS: Record<WorkflowFlagRef, string> = {
-  'Custom.Planwritten': 'Plan written',
-  'Custom.Implementationcomplete': 'Implementation complete',
-  'Custom.Reviewpassed': 'Review passed',
-  'Custom.Testspassing': 'Tests passing',
-  'Custom.Docsupdated': 'Docs updated',
-  'Custom.Mergedtointegration': 'Merged to integration',
-};
+const GATED_TYPES = ['Product Backlog Item', 'Bug'] as const;
 
 /**
- * Only four flags carry a failure reason in the CSV; Implementation complete
- * and Docs updated have none.
+ * The main line, in route order — forward only. PBI and Bug share it (no
+ * type deltas in the final model).
  */
-export const WORKFLOW_FAILURE_REASONS: Partial<Record<WorkflowFlagRef, string>> = {
-  'Custom.Planwritten': 'Plan rejected',
-  'Custom.Reviewpassed': 'Reviewer rejected',
-  'Custom.Testspassing': 'Tests failed',
-  'Custom.Mergedtointegration': 'Build failed',
-};
+const MAIN_LINE: readonly WorkflowState[] = [
+  'New',
+  'In Planning',
+  'Awaiting Approval',
+  'Approved',
+  'Spec Validation',
+  'In Implementation',
+  'In Testing',
+  'In Review',
+  'Updating Docs',
+];
+const MAIN_LINE_INDEX = new Map<string, number>(MAIN_LINE.map((state, index) => [state, index]));
 
-/** The seven board states; the matrix has one rule vector per state. */
-const WORKFLOW_STATES = ['New', 'Approved', 'Committed', 'In Progress', 'In Testing', 'Done', 'Removed'] as const;
-export type WorkflowState = (typeof WORKFLOW_STATES)[number];
+/** The adjacent forward moves on the main line. */
+const LADDER_EDGES: readonly (readonly [WorkflowState, WorkflowState])[] = MAIN_LINE.slice(1).map(
+  (state, index) => [MAIN_LINE[index]!, state] as const,
+);
 
 /**
- * `yes` = flag must be true, `no` = flag must be false, `free` = either.
- * The Product Backlog Item and Bug rows are identical in the CSV, so one
- * table serves both types; per state the entries follow WORKFLOW_FLAG_REFS
- * order.
+ * The states that may move back to New — any active state (re-plan /
+ * unpark), plus Removed (recovery). Done is not active: its one recovery is
+ * In Planning (see RECOVERY_EDGES).
  */
-export const WORKFLOW_STATE_RULES: Record<WorkflowState, Record<WorkflowFlagRef, WorkflowRule>> = {
-  New: { 'Custom.Planwritten': 'no', 'Custom.Implementationcomplete': 'no', 'Custom.Reviewpassed': 'no', 'Custom.Testspassing': 'no', 'Custom.Docsupdated': 'no', 'Custom.Mergedtointegration': 'no' },
-  Approved: { 'Custom.Planwritten': 'yes', 'Custom.Implementationcomplete': 'no', 'Custom.Reviewpassed': 'no', 'Custom.Testspassing': 'no', 'Custom.Docsupdated': 'no', 'Custom.Mergedtointegration': 'no' },
-  Committed: { 'Custom.Planwritten': 'yes', 'Custom.Implementationcomplete': 'no', 'Custom.Reviewpassed': 'no', 'Custom.Testspassing': 'no', 'Custom.Docsupdated': 'no', 'Custom.Mergedtointegration': 'no' },
-  'In Progress': { 'Custom.Planwritten': 'yes', 'Custom.Implementationcomplete': 'free', 'Custom.Reviewpassed': 'no', 'Custom.Testspassing': 'free', 'Custom.Docsupdated': 'free', 'Custom.Mergedtointegration': 'no' },
-  'In Testing': { 'Custom.Planwritten': 'yes', 'Custom.Implementationcomplete': 'yes', 'Custom.Reviewpassed': 'free', 'Custom.Testspassing': 'free', 'Custom.Docsupdated': 'free', 'Custom.Mergedtointegration': 'no' },
-  Done: { 'Custom.Planwritten': 'yes', 'Custom.Implementationcomplete': 'yes', 'Custom.Reviewpassed': 'yes', 'Custom.Testspassing': 'yes', 'Custom.Docsupdated': 'yes', 'Custom.Mergedtointegration': 'yes' },
-  Removed: { 'Custom.Planwritten': 'free', 'Custom.Implementationcomplete': 'free', 'Custom.Reviewpassed': 'free', 'Custom.Testspassing': 'free', 'Custom.Docsupdated': 'free', 'Custom.Mergedtointegration': 'free' },
+const REPLAN_SOURCES: ReadonlySet<WorkflowState> = new Set([
+  'In Planning',
+  'Awaiting Approval',
+  'Approved',
+  'Spec Validation',
+  'In Implementation',
+  'In Testing',
+  'In Review',
+  'Updating Docs',
+  'Parked for Removal',
+  'Removed',
+]);
+
+/** The ONE sanctioned backward work-edge: review agent rejection. */
+const REJECTION_EDGE: readonly [WorkflowState, WorkflowState] = ['In Review', 'In Implementation'];
+/** The documented recovery out of the completed terminal. */
+const RECOVERY_EDGE: readonly [WorkflowState, WorkflowState] = ['Done', 'In Planning'];
+
+/**
+ * Targets no agent may set, with the owner named in the refusal: Approved is
+ * G1 (human approval, taken from Awaiting Approval), Removed is G3 (human
+ * removal, taken from Parked for Removal), Done is entered only by PR merge
+ * automation into integration (from Updating Docs).
+ */
+export const WORKFLOW_HUMAN_ONLY_TARGETS: Readonly<Record<'Approved' | 'Done' | 'Removed', string>> = {
+  Approved: 'G1 — human approval only; agents cannot move items to Approved',
+  Done: 'entered only by PR merge automation into integration',
+  Removed: 'G3 — human removal only; agents cannot move items to Removed',
 };
-export type WorkflowRule = 'yes' | 'no' | 'free';
 
-export interface WorkflowViolation {
-  flagRef: WorkflowFlagRef;
-  flagLabel: string;
-  required: 'true' | 'false';
-  state: string;
-  failureReason?: string;
-}
+const RETIRED_COMMITTED_NOTE = 'Committed is a retired state (UI-hidden; no route references it)';
+const PARKED_EXIT_NOTE = 'Parked for Removal exits only to New (re-plan) or Removed (G3 human)';
 
-const GATED_TYPES = ['Product Backlog Item', 'Bug'] as const;
+export type WorkflowViolation =
+  | { kind: 'skipped-gate'; fromState: WorkflowState; toState: WorkflowState; skippedState: WorkflowState }
+  | { kind: 'human-only'; fromState: WorkflowState; toState: WorkflowState; owner: string }
+  | { kind: 'no-transition'; fromState: WorkflowState; toState: WorkflowState; note?: string };
 
 /**
- * Evaluate the RESULTING (state, flags) pair against the matrix. One
- * violation per breached yes/no row; `free` rows and exempt types
- * (Feature/Epic) yield none. A flag absent from `flags` counts as false,
- * matching an unset Azure boolean. A state outside the seven board states
- * has no rows and yields no violations.
+ * Evaluate a state TRANSITION (from-state → to-state) against the final
+ * state model. One violation per refusal class:
+ *
+ * - `human-only` — the target is owned by G1 approval, PR merge automation
+ *   or G3 human removal; agents never set it.
+ * - `skipped-gate` — a forward jump over main-line states; one violation per
+ *   skipped state, in route order, so the refusal names every gate
+ *   bypassed. Approved is annotated "(G1: human approval)".
+ * - `no-transition` — anything off the model. Committed is retired: any
+ *   transition touching it names the retired state. Parked for Removal is
+ *   enterable from anywhere but exits only to New or Removed. Everything
+ *   else backward is refused flat — including In Implementation → Spec
+ *   Validation and In Testing → In Implementation (no special-casing; the
+ *   owner decision is "no backward rule, enforce forward").
+ *
+ * Allowed to writers: identity writes (from === to, never gated); the
+ * adjacent main-line forward moves; parking to Parked for Removal from any
+ * state; re-plan moves to New from any active state plus Removed; the
+ * review-rejection edge In Review → In Implementation; and the Done →
+ * In Planning recovery. Exits from Done other than In Planning and from
+ * Removed other than New/Parked keep the terminal notes ("completed items
+ * stay Done; a G2 rejection gets its own linked item" / "Removed is
+ * terminal"). A state outside the thirteen recognized states yields none —
+ * the ADO process template enforces server-side. Exempt types
+ * (Feature/Epic) yield none.
  */
-export function evaluateWorkflowState(
+export function evaluateWorkflowTransition(
   workItemType: string,
-  state: string,
-  flags: Partial<Record<WorkflowFlagRef, boolean>> = {},
+  fromState: string,
+  toState: string,
 ): WorkflowViolation[] {
   if (!(GATED_TYPES as readonly string[]).includes(workItemType)) return [];
-  const rules = WORKFLOW_STATE_RULES[state as WorkflowState];
-  if (!rules) return [];
-  const violations: WorkflowViolation[] = [];
-  for (const flagRef of WORKFLOW_FLAG_REFS) {
-    const rule = rules[flagRef];
-    if (rule === 'free') continue;
-    if ((flags[flagRef] ?? false) !== (rule === 'yes')) {
-      violations.push({
-        flagRef,
-        flagLabel: WORKFLOW_FLAG_LABELS[flagRef],
-        required: rule === 'yes' ? 'true' : 'false',
-        state,
-        ...(WORKFLOW_FAILURE_REASONS[flagRef] === undefined ? {} : { failureReason: WORKFLOW_FAILURE_REASONS[flagRef] }),
-      });
-    }
+  if (!(WORKFLOW_STATES as readonly string[]).includes(fromState)) return [];
+  if (!(WORKFLOW_STATES as readonly string[]).includes(toState)) return [];
+  const from = fromState as WorkflowState;
+  const to = toState as WorkflowState;
+  if (from === to) return [];
+  if (from === 'Committed' || to === 'Committed') {
+    return [{ kind: 'no-transition', fromState: from, toState: to, note: RETIRED_COMMITTED_NOTE }];
   }
-  return violations;
+  const owner = (WORKFLOW_HUMAN_ONLY_TARGETS as Partial<Record<WorkflowState, string>>)[to];
+  if (owner !== undefined) return [{ kind: 'human-only', fromState: from, toState: to, owner }];
+  if (to === 'Parked for Removal') return [];
+  if (to === 'New' && REPLAN_SOURCES.has(from)) return [];
+  if (from === REJECTION_EDGE[0] && to === REJECTION_EDGE[1]) return [];
+  if (from === RECOVERY_EDGE[0] && to === RECOVERY_EDGE[1]) return [];
+  if (from === 'Done' || from === 'Removed') {
+    return [{ kind: 'no-transition', fromState: from, toState: to, note: terminalSourceNote(from) }];
+  }
+  if (from === 'Parked for Removal') {
+    return [{ kind: 'no-transition', fromState: from, toState: to, note: PARKED_EXIT_NOTE }];
+  }
+  if (LADDER_EDGES.some(([edgeFrom, edgeTo]) => edgeFrom === from && edgeTo === to)) return [];
+  const fromIndex = MAIN_LINE_INDEX.get(from)!;
+  const toIndex = MAIN_LINE_INDEX.get(to)!;
+  if (toIndex > fromIndex) {
+    return MAIN_LINE.slice(fromIndex + 1, toIndex).map((skippedState) => ({
+      kind: 'skipped-gate',
+      fromState: from,
+      toState: to,
+      skippedState,
+    }));
+  }
+  return [{ kind: 'no-transition', fromState: from, toState: to }];
+}
+
+/** from is Done or Removed here; identity, parking and recoveries were handled by the caller. */
+function terminalSourceNote(from: WorkflowState): string {
+  return from === 'Done'
+    ? 'completed items stay Done; a G2 rejection gets its own linked item'
+    : 'Removed is terminal';
 }
 
 export function formatWorkflowViolation(violation: WorkflowViolation): string {
-  const reason = violation.failureReason === undefined ? '' : ` (${violation.failureReason})`;
-  return `fenced by workflow matrix: State '${violation.state}' requires '${violation.flagLabel}' to be ${violation.required}${reason}`;
+  if (violation.kind === 'skipped-gate') {
+    const g1 = violation.skippedState === 'Approved' ? ' (G1: human approval)' : '';
+    return `fenced by state ladder: '${violation.fromState}' → '${violation.toState}' skips '${violation.skippedState}'${g1}`;
+  }
+  if (violation.kind === 'human-only') {
+    return `fenced by state ladder: '${violation.fromState}' → '${violation.toState}' is ${violation.owner}`;
+  }
+  const note = violation.note === undefined ? '' : ` (${violation.note})`;
+  return `fenced by state ladder: no ladder transition '${violation.fromState}' → '${violation.toState}'${note}`;
 }
 
 /** One refusal line per violation, joined for a loud multi-line error. */
 export function formatWorkflowRefusal(violations: WorkflowViolation[]): string {
   return violations.map(formatWorkflowViolation).join('\n');
 }
-
-/**
- * Pick the workflow flags out of a raw fields record (an Azure work item's
- * `fields`, or a write's `fields` argument). Only strict booleans count;
- * anything else is coerced to false rather than guessed at.
- */
-export function pickWorkflowFlags(fields: Record<string, unknown> | undefined): Partial<Record<WorkflowFlagRef, boolean>> {
-  const flags: Partial<Record<WorkflowFlagRef, boolean>> = {};
-  for (const flagRef of WORKFLOW_FLAG_REFS) {
-    if (fields !== undefined && flagRef in fields) flags[flagRef] = fields[flagRef] === true;
-  }
-  return flags;
-}

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/open_work_cap/test_check.py

@@ -81,7 +81,7 @@ def test_the_committed_clean_corpus_is_silent() -> None:
 
 @pytest.mark.parametrize(
     "status",
-    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
 )
 def test_each_exact_active_plan_state_counts_as_open(
     tmp_path: pathlib.Path, status: str
@@ -179,7 +179,7 @@ def test_a_partial_file_set_counts_the_complete_plan_tree(
 
 @pytest.mark.parametrize(
     "status",
-    ("New", "Approved", "Committed", "In Progress", "In Testing"),
+    ("New", "In Planning", "Awaiting Approval", "Approved", "Spec Validation", "In Implementation", "In Testing", "In Review", "Updating Docs"),
 )
 def test_unraised_and_each_linked_active_gap_state_both_count_as_open(
     tmp_path: pathlib.Path, status: str

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plan_metadata.py

@@ -11,15 +11,20 @@ class PlanMetadata:
 
     WORK_ITEM_STATUSES: ClassVar[tuple[str, ...]] = (
         "New",
+        "In Planning",
+        "Awaiting Approval",
         "Approved",
-        "Committed",
-        "In Progress",
+        "Spec Validation",
+        "In Implementation",
         "In Testing",
+        "In Review",
+        "Updating Docs",
         "Done",
+        "Parked for Removal",
         "Removed",
     )
-    ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[:5])
-    TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[5:])
+    ACTIVE_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[:9])
+    TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset(WORK_ITEM_STATUSES[9:])
 
     STATUS_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^status:\s*(.+)$")
     WORK_ITEM_LINE: ClassVar[re.Pattern[str]] = re.compile(r"^work_item:\s*(.+)$")

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/check.py

@@ -67,7 +67,7 @@ class PlansLayout(Check):
     # you can tell what a file is from its name, in every feature, without opening
     # it. Adding a name here later is cheap; leaving the set open is how a tree
     # ends up with HANDOVER.md, handover-v2.md and channels-notes.md side by side.
-    SUPPORTING: ClassVar[tuple[str, ...]] = ("handoff.md", "review.md")
+    SUPPORTING: ClassVar[tuple[str, ...]] = ("handoff.md", "intent.md", "review.md")
 
     ROOT_DIRS: ClassVar[tuple[str, ...]] = ("features", "templates")
     # `GAPS-AND-FINDINGS.md` sits here because its own rows say where they go:

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/fixtures/plans-layout-clean/plans/features/az347-test-coverage/items/az351-restore-entrypoint.md

@@ -1,7 +1,7 @@
 ---
 type: bug
 title: "Restore the entrypoint"
-status: Committed
+status: Done
 work_item: https://dev.azure.com/org/proj/_workitems/edit/351
 last_update: 2026-09-15T03:20:00Z
 ---

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/layout/plans_layout/test_check.py

@@ -199,8 +199,8 @@ def test_an_extra_file_beside_spec_is_reported(tmp_path: pathlib.Path) -> None:
     # The message ENUMERATES what is allowed, so whoever hits it can correct the
     # file without opening the check. A bare "not allowed" sends the reader here.
     finding = next(f for f in verdict.findings if "Feature directory holds" in f.message)
-    assert finding.message == "a Feature directory holds spec.md, handoff.md, review.md, items/ only"
-    assert "rename it to one of handoff.md, review.md" in finding.fix
+    assert finding.message == "a Feature directory holds spec.md, handoff.md, intent.md, review.md, items/ only"
+    assert "rename it to one of handoff.md, intent.md, review.md" in finding.fix
 
 
 def test_supporting_documents_are_permitted_beside_spec(tmp_path: pathlib.Path) -> None: