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

package/packages/azdo/src/activity-log.ts

@@ -0,0 +1,118 @@
+/** A1 agent activity log — design: docs/research/adl-process-handover/process-design.md § Activity log. */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+
+export interface ActivityEntry {
+  time: string;
+  surface: string;
+  agent: string;
+  repo: string;
+  note: string;
+}
+
+/** Verified child-process surface markers, first match wins; a marker is listed only with a citation to the surface's own docs. */
+const SURFACE_MARKERS: ReadonlyArray<{ readonly surface: string; readonly env: string; readonly equals?: string }> = [
+  // Claude Code spawns set CLAUDECODE=1 (code.claude.com/docs/en/env-vars, verified 2026-10-12).
+  { surface: 'claude', env: 'CLAUDECODE', equals: '1' },
+];
+
+/** The surface this process runs under: first verified marker match, else 'cli' (no marker is not an error). */
+export function resolveSurface(env: NodeJS.ProcessEnv = process.env): string {
+  for (const marker of SURFACE_MARKERS) {
+    const value = env[marker.env];
+    if (value !== undefined && (marker.equals === undefined || value === marker.equals)) {
+      return marker.surface;
+    }
+  }
+  return 'cli';
+}
+
+/** The git work-tree top level of `cwd` (or the process's own), or a loud refusal outside a work tree — the log lives at `<repo>/.adl/agent-activity.sqlite`. */
+export function repoTopLevel(cwd?: string): string {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    ...(cwd === undefined ? {} : { cwd }),
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  const topLevel = result.status === 0 ? result.stdout.trim() : '';
+  if (!topLevel) {
+    throw new Error(
+      'the activity log lives at <repo>/.adl/agent-activity.sqlite, and this working directory is not a git work tree',
+    );
+  }
+  return topLevel;
+}
+
+/** The ONE place the log's path is built. */
+export function activityDbPath(cwd?: string): string {
+  return join(repoTopLevel(cwd), '.adl', 'agent-activity.sqlite');
+}
+
+function openDb(cwd?: string): DatabaseSync {
+  const path = activityDbPath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      time TEXT NOT NULL,
+      surface TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      repo TEXT NOT NULL,
+      note TEXT NOT NULL
+    )`,
+  );
+  return db;
+}
+
+function assertNote(note: unknown): asserts note is string {
+  if (typeof note !== 'string' || note.trim() === '') {
+    throw new Error('note must be a non-empty string');
+  }
+}
+
+/** Append one entry, filling time/surface/agent/repo; `env`/`now` keep tests hermetic. Returns the stored entry as JSON. */
+export function activityAdd(
+  note: unknown,
+  opts: { cwd?: string; env?: NodeJS.ProcessEnv; now?: Date } = {},
+): string {
+  assertNote(note);
+  const env = opts.env ?? process.env;
+  const entry: ActivityEntry = {
+    time: (opts.now ?? new Date()).toISOString(),
+    surface: resolveSurface(env),
+    agent: resolveAgentIdentity(env).agent,
+    repo: basename(repoTopLevel(opts.cwd)),
+    note,
+  };
+  const db = openDb(opts.cwd);
+  try {
+    db.prepare('INSERT INTO activity (time, surface, agent, repo, note) VALUES (?, ?, ?, ?, ?)').run(
+      entry.time,
+      entry.surface,
+      entry.agent,
+      entry.repo,
+      entry.note,
+    );
+  } finally {
+    db.close();
+  }
+  return JSON.stringify(entry, null, 2);
+}
+
+/** Every entry, oldest first (the reading order of the ledger this replaces). */
+export function activityList(opts: { cwd?: string } = {}): string {
+  const db = openDb(opts.cwd);
+  let entries: unknown[];
+  try {
+    entries = db
+      .prepare('SELECT time, surface, agent, repo, note FROM activity ORDER BY id ASC')
+      .all();
+  } finally {
+    db.close();
+  }
+  return JSON.stringify({ repo: basename(repoTopLevel(opts.cwd)), entries }, null, 2);
+}

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

@@ -0,0 +1,108 @@
+// T2 work-item attachments (board-rules.md § Attachments): Features only, frozen once attached — the one delete allowed is a mistaken upload in its own run, for a plan-r* file while every Feature item is still at or before Awaiting Approval. API facts (WIT REST 7.1): upload POSTs .../_apis/wit/attachments?fileName={name} (octet-stream, returns { id, url }); attach PATCHes the work item adding an AttachedFile relation (test/rev gives optimistic concurrency); Attachments-Delete is 7.2-preview only, so delete detaches and the stored file stays.
+import { AdoClient } from './lib/client.ts';
+
+let client: AdoClient | undefined
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient()
+  return client
+}
+
+/** Test seam: forget the cached client — see azdo-wit.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
+export type WorkitemAttachmentsArgs = {
+  id: number;
+  action: 'read' | 'upload' | 'delete';
+  /** upload/delete: the attachment file name. */
+  fileName?: string;
+  /** upload: the file content, sent as an octet-stream body. */
+  content?: string;
+};
+
+interface AttachmentRelation {
+  index: number;
+  name: string;
+  url: string;
+}
+
+function attachedFiles(item: any): AttachmentRelation[] {
+  return (item.relations ?? [])
+    .map((relation: any, index: number) => ({ relation, index }))
+    .filter(({ relation }: any) => relation.rel === 'AttachedFile')
+    .map(({ relation, index }: any) => ({
+      index,
+      name: relation.attributes?.name ?? relation.url,
+      url: relation.url,
+    }));
+}
+
+/** P4 reuses this upload when it attaches the mandatory plan/impl report at PR raise. */
+export async function uploadAttachment(c: AdoClient, workItemId: number, fileName: string, content: string): Promise<void> {
+  const uploaded = await c.post<any>(
+    '/wit/attachments',
+    content,
+    { fileName, 'api-version': '7.1' },
+    'application/octet-stream',
+  );
+  if (!uploaded?.url) throw new Error(`attachment upload for '${fileName}' returned no url`);
+  const item = await c.get<any>(`/wit/workitems/${workItemId}`, { 'api-version': '7.1' });
+  await c.patch<any>(
+    `/wit/workitems/${workItemId}`,
+    [
+      { op: 'test', path: '/rev', value: item.rev ?? item.fields?.['System.Rev'] },
+      { op: 'add', path: '/relations/-', value: { rel: 'AttachedFile', url: uploaded.url } },
+    ],
+    { 'api-version': '7.1' },
+    'application/json-patch+json',
+  );
+}
+
+/** The T2 guard (board-rules.md § Attachments): a plan-r* file refuses deletion once any item of its Feature has left Awaiting Approval — the plan G1 approved stays on the board. */
+async function assertPlanAttachmentDeletable(c: AdoClient, feature: any, fileName: string): Promise<void> {
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  const childIds = (feature.relations ?? [])
+    .filter((relation: any) => relation.rel === 'System.LinkTypes.Hierarchy-Forward')
+    .map((relation: any) => relationId(relation.url))
+    .filter((id: number) => Number.isInteger(id));
+  if (!childIds.length) return;
+  const children = await c.post<any>('/wit/workitemsbatch', { ids: childIds, $expand: 'all' }, { 'api-version': '7.1' });
+  const left = (children.value ?? []).find((child: any) => !['New', 'In Planning', 'Awaiting Approval'].includes(child.fields?.['System.State']));
+  if (left) {
+    throw new Error(`refusing to delete '${fileName}': an item of Feature ${feature.id} has left Awaiting Approval (item ${left.id} is at ${left.fields?.['System.State']}) — the approved plan stays on the board`);
+  }
+}
+
+export async function workitemAttachments(args: WorkitemAttachmentsArgs): Promise<string> {
+  const c = await getClient();
+  if (args.action === 'upload') {
+    if (!args.fileName) throw new Error('fileName is required for upload');
+    if (args.content === undefined || args.content === '') throw new Error('content is required for upload');
+    await uploadAttachment(c, args.id, args.fileName, args.content);
+    return JSON.stringify({ id: args.id, attached: args.fileName }, null, 2);
+  }
+  const item = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' });
+  const files = attachedFiles(item);
+  if (args.action === 'read') {
+    return JSON.stringify({ id: args.id, attachments: files.map(({ name, url }) => ({ name, url })) }, null, 2);
+  }
+  if (!args.fileName) throw new Error('fileName is required for delete');
+  const target = files.find((file) => file.name === args.fileName);
+  if (!target) throw new Error(`work item ${args.id} has no AttachedFile named '${args.fileName}'`);
+  if (target.name.startsWith('plan-r')) {
+    await assertPlanAttachmentDeletable(c, item, target.name);
+  }
+  // On 7.1 delete detaches: remove the relation, the stored file stays; test/rev gives the same optimistic concurrency as attach.
+  await c.patch<any>(
+    `/wit/workitems/${args.id}`,
+    [
+      { op: 'test', path: '/rev', value: item.rev ?? item.fields?.['System.Rev'] },
+      { op: 'remove', path: `/relations/${target.index}` },
+    ],
+    { 'api-version': '7.1' },
+    'application/json-patch+json',
+  );
+  return JSON.stringify({ id: args.id, deleted: target.name }, null, 2);
+}

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

@@ -9,10 +9,38 @@
  * automatically) falling back to the AdoClient defaults. Nothing is
  * hardcoded here.
  *
+ * buildRun carries the second half of H1
+ * (docs/research/adl-process-handover/board-rules.md § Hooks, row
+ * `adl.build-run-role`): the hook has no network access, so it grades only
+ * what the call itself proves and names this function as the re-verifier of
+ * the caller-declared claim. Before queuing, buildRun requires ALL of:
+ *   1. `branch` present (the hook requires it too; the tool refuses on its
+ *      own, never relying on the hook alone);
+ *   2. an OPEN pull request in this repository whose source branch equals
+ *      the call's `branch` (after `refs/heads/` removal);
+ *   3. that PR raised by the CALLING agent identity — `createdBy.id`
+ *      compared against lib/graph-identity.ts's resolveAgentIdentityId, the
+ *      ONE identity-form producer in this repo;
+ *   4. the named definition is that PR's validation pipeline: a run of
+ *      definition `id` exists on the PR's merge ref (`refs/pull/<id>/merge`,
+ *      the sourceBranch ADO queues PR validation builds under — the same ref
+ *      build_list_or_get's poll hint names).
+ *   RESIDUAL APPROXIMATION (stated, not silently widened): check 4 proves
+ *   the definition IS a validation pipeline of THIS PR via a run that
+ *   already exists; a definition whose policy would queue on the PR but has
+ *   never produced a run is refused. That is sound for the re-queue use case
+ *   (an expired check implies a run that existed) but stricter than "any
+ *   policy-bound definition" — the PR resource carries no build-policy
+ *   reference (`completionOptions` names no definition), so an existing run
+ *   on the merge ref is the strongest relationship the REST API exposes.
+ *
  * Timeline model: Stage → Phase → Job → Task, chained by parentId
  * (Checkpoint records carry no user-facing state and are skipped).
  */
-import { AdoClient } from './lib/client.ts'
+import { AdoClient, resolveRepository } from './lib/client.ts'
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+import { resolveAgentIdentityId } from './lib/graph-identity.ts';
+import { pullRequestsPath } from './azdo-pr.ts'
 
 let client: AdoClient | undefined
 
@@ -21,6 +49,11 @@ async function getClient(): Promise<AdoClient> {
   return client
 }
 
+/** Test seam: forget the cached client — see azdo-pr.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
 /** GET a JSON payload. */
 async function getJson<T>(c: AdoClient, path: string, params?: Record<string, string>): Promise<T> {
   return c.get<T>(path, { 'api-version': '7.1', ...params });
@@ -160,13 +193,77 @@ export async function buildListOrGet(args: BuildListOrGetArgs = {}): Promise<str
 
 export type BuildRunArgs = { id: string; branch?: string };
 
+function normalizeBranchRef(ref: string): string {
+  return ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : ref;
+}
+
+/**
+ * H1's azdo half — see this file's header. Queries (all read-only, all
+ * before the queue POST): the open PRs on the named source branch, the
+ * caller's own ADO identity id (Graph Subject Query → Storage Keys), and the
+ * validation runs on the PR's merge ref. Throws with the exact failed check;
+ * queues only when every check passes.
+ */
+async function assertOwnPrValidationBuild(c: AdoClient, definitionId: number, branch: string): Promise<void> {
+  const sourceBranch = normalizeBranchRef(branch.trim());
+  const repository = resolveRepository();
+  const { repositoryId } = await resolveRepositoryId(c);
+  const agent = resolveAgentIdentity().agent;
+
+  const prs = await getJson<any>(c, pullRequestsPath(repository), {
+    'searchCriteria.status': 'active',
+    'searchCriteria.sourceRefName': `refs/heads/${sourceBranch}`,
+    '$top': '100',
+  });
+  const candidates = (prs.value ?? []) as any[];
+  if (candidates.length === 0) {
+    throw new Error(
+      `build_run refused (H1): no open pull request in '${repository}' has source branch '${sourceBranch}' — ` +
+        'build_run may only re-queue the validation pipeline of your own open PR, on that PR\'s source branch',
+    );
+  }
+
+  const callerId = await resolveAgentIdentityId(agent);
+  const mine = candidates.filter((pr) => pr.createdBy?.id === callerId);
+  if (mine.length === 0) {
+    const authors = [...new Set(candidates.map((pr) => pr.createdBy?.displayName ?? 'unknown'))].join(', ');
+    throw new Error(
+      `build_run refused (H1): the open pull request on '${sourceBranch}' was raised by ${authors}, not ${agent} — ` +
+        'build_run may only re-queue the validation pipeline of a PR you raised yourself',
+    );
+  }
+
+  for (const pr of mine) {
+    const runs = await getJson<any>(c, '/build/builds', {
+      branchName: `refs/pull/${pr.pullRequestId}/merge`,
+      repositoryId,
+      repositoryType: 'TfsGit',
+      '$top': '50',
+    });
+    if ((runs.value ?? []).some((run: any) => run.definition?.id === definitionId)) {
+      return;
+    }
+  }
+  const prIds = mine.map((pr) => pr.pullRequestId).join(', ');
+  throw new Error(
+    `build_run refused (H1): build definition ${definitionId} is not a validation pipeline of your pull request(s) ${prIds} ` +
+      `(no run of it exists on refs/pull/<id>/merge) — pass the definition id of your PR's validation build, from build_list_or_get`,
+  );
+}
+
 export async function buildRun(args: BuildRunArgs): Promise<string> {
   if (!args.id) throw new Error('id is required');
   const definitionId = Number(args.id);
   if (!Number.isInteger(definitionId) || definitionId < 1) throw new Error(`id must be a positive integer definition id; got '${args.id}'`);
+  if (typeof args.branch !== 'string' || args.branch.trim() === '') {
+    throw new Error(
+      'branch is required: name the source branch of your own open PR — build_run may only re-queue that PR\'s ' +
+        'validation pipeline, on that PR\'s source branch (H1)',
+    );
+  }
   const c = await getClient()
-  const body: any = { definition: { id: definitionId } };
-  if (args.branch) body.sourceBranch = args.branch;
+  await assertOwnPrValidationBuild(c, definitionId, args.branch);
+  const body: any = { definition: { id: definitionId }, sourceBranch: args.branch };
   const build = await c.post<any>('/build/builds', body, { 'api-version': '7.1' });
   return JSON.stringify({
     id: build.id,

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

@@ -3,10 +3,11 @@
 // repo invoked this file as a CLI; see mcp-server.ts's runTool() history).
 import {
   validatePullRequestDescription,
-  validatePullRequestMetadata,
   validatePullRequestTitle,
 } from './lib/validate-pr-metadata.ts'
 import { AdoClient, PR_TARGET_BRANCH, adoProjectUrl, currentBranch, resolveRepository } from './lib/client.ts';
+import { uploadAttachment } from './azdo-attachments.ts';
+import { evaluateWorkflowTransition, formatWorkflowRefusal } from './workflow-rules.ts';
 
 let client: AdoClient | undefined
 
@@ -34,17 +35,22 @@ export function pullRequestWebUrl(repository: string, pullRequestId: number | st
  * the call succeeded, the tool reported success, and the PR stayed unarmed.
  * That silent no-op is why this is a named function with its own test rather
  * than an object literal at the call site.
+ *
+ * P2: `completionOptions.transitionWorkItems` is set by PR kind — true only
+ * for implementation and Fixes Bug PRs, where ADO moves the linked items to
+ * Done when the PR merges into integration (planning and ordinary PRs move
+ * nothing on merge).
  */
-export function autoCompleteBody(identityId: string): {
+export function autoCompleteBody(identityId: string, transitionWorkItems = false): {
   autoCompleteSetBy: { id: string }
-  completionOptions: { mergeStrategy: string; deleteSourceBranch: boolean }
+  completionOptions: { mergeStrategy: string; deleteSourceBranch: boolean; transitionWorkItems: boolean }
 } {
   if (!identityId) {
     throw new Error('cannot arm auto-complete: no identity to attribute it to')
   }
   return {
     autoCompleteSetBy: { id: identityId },
-    completionOptions: { mergeStrategy: 'squash', deleteSourceBranch: true },
+    completionOptions: { mergeStrategy: 'squash', deleteSourceBranch: true, transitionWorkItems },
   }
 }
 
@@ -147,8 +153,11 @@ export async function prListOrGet(args: PrListOrGetArgs): Promise<string> {
   return JSON.stringify(prs, null, 2);
 }
 
-function assertValidCreateMetadata(title: string, description: string) {
-  const metadataErrors = validatePullRequestMetadata(title, description)
+function assertValidCreateMetadata(title: string, description: string, docsOnlySections: boolean) {
+  const metadataErrors = [
+    ...validatePullRequestTitle(title),
+    ...validatePullRequestDescription(description, { docsOnlySections }),
+  ]
   if (metadataErrors.length === 0) return
   throw new Error(metadataErrors.map((error) => `pr-policy: FAIL — ${error}`).join('\n'))
 }
@@ -169,6 +178,8 @@ export type PrCreateOrUpdateArgs = {
   autoComplete?: boolean;
   mergeStrategy?: string;
   deleteSourceBranch?: boolean;
+  /** P4: the content of the kind's mandatory Feature attachment (planning/implementation PRs only). */
+  attachmentContent?: string;
   /** Overrides `AZURE_DEVOPS_REPO` for this call. */
   repository?: string;
   /** Rejected removed routing input; PRs always use the checked-out branch. */
@@ -184,8 +195,130 @@ export function assertPrSourceBranch(source: string | undefined): asserts source
   if (source === 'main') throw new Error(`a pull request is never opened from main; open a branch into ${PR_TARGET_BRANCH}`);
 }
 
+/**
+ * P1: the PR kind comes from the source branch naming a work item
+ * (azdo-git-process.md § PRs). `docs/az<id>-<slug>-plan` is a planning PR;
+ * `fix/az<bug id>-<slug>` is a Fixes Bug implementation PR naming one Bug;
+ * any other `<type>/az<id>-<slug>` branch names a Feature and is an
+ * implementation PR. Anything else is ordinary. The kind can still fall
+ * back to ordinary when the board holds no item in a wireable state.
+ */
+export type PrKind = 'planning' | 'implementation' | 'ordinary';
+
+export interface PrKindTarget {
+  kind: PrKind;
+  /** The work item the branch names (undefined for ordinary). */
+  itemId?: number;
+  itemType?: 'Feature' | 'Bug';
+}
+
+const PLANNING_BRANCH = /^docs\/az(\d+)-[a-z0-9-]+-plan$/;
+const FIXES_BUG_BRANCH = /^fix\/az(\d+)-[a-z0-9-]+$/;
+const FEATURE_BRANCH = /^(?:feat|chore|docs|perf|refactor)\/az(\d+)-[a-z0-9-]+$/;
+
+export function derivePrKind(sourceBranch: string): PrKindTarget {
+  const planning = PLANNING_BRANCH.exec(sourceBranch);
+  if (planning) return { kind: 'planning', itemId: Number(planning[1]), itemType: 'Feature' };
+  const fixes = FIXES_BUG_BRANCH.exec(sourceBranch);
+  if (fixes) return { kind: 'implementation', itemId: Number(fixes[1]), itemType: 'Bug' };
+  const feature = FEATURE_BRANCH.exec(sourceBranch);
+  if (feature) return { kind: 'implementation', itemId: Number(feature[1]), itemType: 'Feature' };
+  return { kind: 'ordinary' };
+}
+
+/** The board states P1 wires, per kind. Done is never wired (terminal); neither are the parked/removed states. */
+const PLANNING_WIREABLE: ReadonlySet<string> = new Set(['In Planning']);
+const PBI_IMPLEMENTATION_WIREABLE: ReadonlySet<string> = new Set(['Approved', 'Design Validation', 'In Implementation', 'In Testing', 'In Review', 'Updating Docs']);
+const BUG_IMPLEMENTATION_WIREABLE: ReadonlySet<string> = new Set(['Approved', 'In Reproduction', 'In Fixing', 'In Testing', 'In Review', 'Updating Docs']);
+
+/** P2's raise-time move targets: planning items → Awaiting Approval; loop items → Updating Docs. */
+const PBI_LOOP: ReadonlySet<string> = new Set(['In Implementation', 'In Testing', 'In Review', 'Updating Docs']);
+const BUG_LOOP: ReadonlySet<string> = new Set(['In Fixing', 'In Testing', 'In Review', 'Updating Docs']);
+
+export interface WiredItem {
+  id: number;
+  type: 'Product Backlog Item' | 'Bug';
+  state: string;
+}
+
+function relationIds(item: any, rel: string): number[] {
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  return (item.relations ?? [])
+    .filter((relation: any) => relation.rel === rel)
+    .map((relation: any) => relationId(relation.url))
+    .filter((id: number) => Number.isInteger(id));
+}
+
+/**
+ * P1: the items to wire, read from the board. Planning wires the Feature's
+ * in-scope items at In Planning; implementation wires the Feature's items
+ * (or the one Bug) at Approved or later. An empty result demotes the PR to
+ * ordinary — no links, no state moves, no attachment.
+ */
+export async function resolveWiredItems(c: AdoClient, target: PrKindTarget): Promise<WiredItem[]> {
+  if (target.itemId === undefined || target.itemType === undefined) return [];
+  const item = await c.get<any>(`/wit/workitems/${target.itemId}`, { 'api-version': '7.1', $expand: 'all' });
+  if (target.itemType === 'Bug') {
+    const state = item.fields?.['System.State'];
+    return BUG_IMPLEMENTATION_WIREABLE.has(state) ? [{ id: item.id, type: 'Bug', state }] : [];
+  }
+  const wireable = target.kind === 'planning' ? PLANNING_WIREABLE : PBI_IMPLEMENTATION_WIREABLE;
+  const childIds = relationIds(item, 'System.LinkTypes.Hierarchy-Forward');
+  if (!childIds.length) return [];
+  const batch = await c.post<any>('/wit/workitemsbatch', { ids: childIds, $expand: 'all' }, { 'api-version': '7.1' });
+  return (batch.value ?? [])
+    .filter((child: any) => ['Product Backlog Item', 'Bug'].includes(child.fields?.['System.WorkItemType']))
+    .filter((child: any) => wireable.has(child.fields?.['System.State']))
+    .map((child: any) => ({ id: child.id, type: child.fields['System.WorkItemType'], state: child.fields['System.State'] }));
+}
+
+/** P2's raise-time target state for one wired item, or undefined when the item stays where it is. */
+export function raiseMoveTarget(kind: PrKind, item: WiredItem): string | undefined {
+  if (kind === 'planning') return 'Awaiting Approval';
+  if (kind === 'implementation') {
+    const loop = item.type === 'Bug' ? BUG_LOOP : PBI_LOOP;
+    return loop.has(item.state) && item.state !== 'Updating Docs' ? 'Updating Docs' : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * P2: move the linked items themselves when the PR is raised. Every move is
+ * pre-checked against the workflow fence (the same rule an agent write
+ * faces) so a PR is never raised half-wired.
+ */
+async function moveWiredItems(c: AdoClient, kind: PrKind, items: WiredItem[]): Promise<void> {
+  for (const item of items) {
+    const to = raiseMoveTarget(kind, item);
+    if (to === undefined) continue;
+    const violations = evaluateWorkflowTransition(item.type, item.state, to);
+    if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+    await c.patch<any>(
+      `/wit/workitems/${item.id}`,
+      [{ op: 'add', path: '/fields/System.State', value: to }],
+      { 'api-version': '7.1' },
+      'application/json-patch+json',
+    );
+  }
+}
+
+/**
+ * P4: the work item the mandatory attachment hangs off — the named Feature,
+ * or, for a Fixes Bug PR, its Fixes Feature (board-rules.md § Attachments).
+ * The file name is completed by the caller once the PR id exists.
+ */
+async function attachmentTargetWorkItemId(c: AdoClient, target: PrKindTarget): Promise<number> {
+  if (target.itemType === 'Bug') {
+    const bug = await c.get<any>(`/wit/workitems/${target.itemId}`, { 'api-version': '7.1', $expand: 'all' });
+    const [parentId] = relationIds(bug, 'System.LinkTypes.Hierarchy-Reverse');
+    if (parentId === undefined) throw new Error(`Fixes Bug ${target.itemId} has no parent Fixes Feature to attach the implementation report to (P4)`);
+    return parentId;
+  }
+  return target.itemId!;
+}
+
 /** The exact next steps returned after PR creation, including live-stage failure polling. */
-export function prCreateResult(repository: string, pullRequestId: number, title: string, status: string, autoComplete: boolean): Record<string, unknown> {
+export function prCreateResult(repository: string, pullRequestId: number, title: string, status: string, autoComplete: boolean, kind: PrKind = 'ordinary', wiredItems: number[] = []): Record<string, unknown> {
   const prRef = `refs/pull/${pullRequestId}/merge`;
   return {
     id: pullRequestId,
@@ -193,6 +326,8 @@ export function prCreateResult(repository: string, pullRequestId: number, title:
     status,
     url: pullRequestWebUrl(repository, pullRequestId),
     autoComplete,
+    kind,
+    workItems: wiredItems,
     summary: 'Creating this pull request started a validation build.',
     poll: [
       `1. build_list_or_get({ branch: '${prRef}' }) — take builds[0].id.`,
@@ -258,9 +393,42 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
   assertPrSourceBranch(source);
   if (!title) throw new Error('title is required for create');
 
-  assertValidCreateMetadata(title, description)
-
   const c = await getClient()
+
+  // P1: derive the kind from the source branch AND the board. No item in a
+  // wireable state demotes the PR to ordinary — nothing links, moves or
+  // attaches (the intent.md PR is the standing example).
+  const kindTarget = derivePrKind(source);
+  const wired = kindTarget.kind === 'ordinary' ? [] : await resolveWiredItems(c, kindTarget);
+  const kind: PrKind = wired.length ? kindTarget.kind : 'ordinary';
+
+  // P3: a planning PR may write "none (docs-only)" in the last two sections.
+  assertValidCreateMetadata(title, description, kind === 'planning')
+
+  // P4: the agent supplies the mandatory attachment's content; a planning or
+  // implementation PR refuses to raise without it. The planning attachment's
+  // file name comes from the Feature's plan fields and is validated here,
+  // before any PR exists.
+  let planningAttachment: { workItemId: number; fileName: string } | undefined;
+  let implAttachmentTarget: number | undefined;
+  if (kind !== 'ordinary') {
+    if (args.attachmentContent === undefined || args.attachmentContent.trim() === '') {
+      const article = kind === 'implementation' ? 'an' : 'a';
+      throw new Error(`${article} ${kind} PR requires attachmentContent — the mandatory ${kind === 'planning' ? 'plan-r<N>-<sha7>.md plan attachment' : 'impl-report-pr<id>.md implementation report'} (P4); refusing to raise the PR without it`)
+    }
+    if (kind === 'planning') {
+      const feature = await c.get<any>(`/wit/workitems/${kindTarget.itemId}`, { 'api-version': '7.1' });
+      const revision = feature.fields?.['Custom.PlanRevision'];
+      const hash = feature.fields?.['Custom.PlanHash'];
+      if (typeof revision !== 'number' || typeof hash !== 'string' || !hash) {
+        throw new Error('a planning PR needs the Feature\'s Custom.PlanRevision and Custom.PlanHash to name the mandatory plan attachment (P4)')
+      }
+      planningAttachment = { workItemId: kindTarget.itemId!, fileName: `plan-r${revision}-${hash.slice(0, 7)}.md` };
+    } else {
+      implAttachmentTarget = await attachmentTargetWorkItemId(c, kindTarget);
+    }
+  }
+
   await assertBranchReadyForPr(c, repository, source, target)
   const body: any = {
     sourceRefName: `refs/heads/${source}`,
@@ -268,6 +436,9 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
     title,
     description,
   };
+  // P1: link the wired items at create, as `az repos pr create --work-items`
+  // does through workItemRefs on the create body.
+  if (wired.length) body.workItemRefs = wired.map((item) => ({ id: item.id }));
 
   const pr = await c.post<any>(
     pullRequestsPath(repository),
@@ -275,15 +446,27 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
     { 'api-version': '7.1' }
   );
 
+  // P2: the tool moves the linked items itself at raise — planning items to
+  // Awaiting Approval, loop items to Updating Docs. Implementation PRs also
+  // arm transitionWorkItems so ADO lands the linked items on Done at merge.
+  await moveWiredItems(c, kind, wired);
+
+  // P4: attach the mandatory Feature attachment now that the PR id exists.
+  if (planningAttachment) {
+    await uploadAttachment(c, planningAttachment.workItemId, planningAttachment.fileName, args.attachmentContent!);
+  } else if (implAttachmentTarget !== undefined) {
+    await uploadAttachment(c, implAttachmentTarget, `impl-report-pr${pr.pullRequestId}.md`, args.attachmentContent!);
+  }
+
   if (arm) {
     // The PR we just created was created BY us, so its `createdBy` is the
     // authenticated identity — no extra lookup needed to attribute the arming.
     await c.patch<any>(
       pullRequestsPath(repository, pr.pullRequestId),
-      autoCompleteBody(pr.createdBy?.id ?? ''),
+      autoCompleteBody(pr.createdBy?.id ?? '', kind === 'implementation'),
       { 'api-version': '7.1' }
     );
   }
 
-  return JSON.stringify(prCreateResult(repository, pr.pullRequestId, pr.title, pr.status, arm), null, 2);
+  return JSON.stringify(prCreateResult(repository, pr.pullRequestId, pr.title, pr.status, arm, kind, wired.map((item) => item.id)), null, 2);
 }