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

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

@@ -4,53 +4,58 @@
 // 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
+// them. The routes below implement the owner's final state model: PBIs
+// walk the item ladder; Bugs walk their own shorter ladder (F9 — never
+// planned, reproducing before fixing); both are 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.
+// them (the Feature ladder lives in evaluateFeatureTransition).
 
 /**
- * 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.
+ * The fifteen recognized states: the twelve active states of the final
+ * model, plus In Reproduction and In Fixing (Bug-only ladder states, F9),
+ * 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',
+  "New",
+  "In Planning",
+  "Awaiting Approval",
+  "Approved",
+  "Design Validation",
+  "In Implementation",
+  "In Reproduction",
+  "In Fixing",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
+  "Done",
+  "Parked for Removal",
+  "Removed",
+  "Committed",
 ] as const;
 export type WorkflowState = (typeof WORKFLOW_STATES)[number];
 
-const GATED_TYPES = ['Product Backlog Item', 'Bug'] as const;
+const GATED_TYPES = ["Product Backlog Item", "Bug"] as const;
 
 /**
  * The main line, in route order — forward only. PBI and Bug share it (no
  * type deltas in the final model).
  */
 const MAIN_LINE: readonly WorkflowState[] = [
-  'New',
-  'In Planning',
-  'Awaiting Approval',
-  'Approved',
-  'Spec Validation',
-  'In Implementation',
-  'In Testing',
-  'In Review',
-  'Updating Docs',
+  "New",
+  "In Planning",
+  "Awaiting Approval",
+  "Approved",
+  "Design Validation",
+  "In Implementation",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
 ];
 const MAIN_LINE_INDEX = new Map<string, number>(MAIN_LINE.map((state, index) => [state, index]));
 
@@ -60,27 +65,82 @@ const LADDER_EDGES: readonly (readonly [WorkflowState, WorkflowState])[] = MAIN_
 );
 
 /**
- * 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).
+ * The non-linear loop (F1): every ordered pair among these four states is
+ * allowed, in either direction and with skips — the implementation lead
+ * moves items around the loop freely. In Implementation → Design Validation
+ * (DRIFT_EDGE) is the one sanctioned exit backward out of the loop, on
+ * mid-loop drift.
  */
-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',
+const LOOP_STATES: ReadonlySet<WorkflowState> = new Set([
+  "In Implementation",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
+]);
+/**
+ * The drift loop-back: mid-loop drift returns through Design Validation.
+ * (PBI only — Bugs have no Design Validation, F9.)
+ */
+const DRIFT_EDGE: readonly [WorkflowState, WorkflowState] = ["In Implementation", "Design Validation"];
+
+/**
+ * The Bug ladder (F9): Bugs no longer share the PBI ladder. A Bug is never
+ * planned — no In Planning, Awaiting Approval or Design Validation — and
+ * reproduces before it is fixed. Allowed agent moves: New → Parked for
+ * Removal; Approved → In Reproduction; In Reproduction → In Fixing;
+ * In Reproduction → Parked for Removal (won't reproduce); the non-linear
+ * loop over In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs (every
+ * ordered pair); and parking from any non-terminal Bug state. Everything
+ * else is refused, including targets of Awaiting Approval, In Planning and
+ * Design Validation. The human-only targets (Approved, Done, Removed, the
+ * parked revive) and the terminals are handled by the shared front matter
+ * of evaluateWorkflowTransition.
+ */
+const BUG_LOOP_STATES: ReadonlySet<WorkflowState> = new Set(["In Fixing", "In Testing", "In Review", "Updating Docs"]);
+/** Any non-terminal Bug state may park (New and Approved included, to park a duplicate). */
+const BUG_PARKING_SOURCES: ReadonlySet<WorkflowState> = new Set([
+  "New",
+  "Approved",
+  "In Reproduction",
+  "In Fixing",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
 ]);
 
-/** 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'];
+/** The Bug transition table itself, after the shared human-only/terminal front matter. */
+function evaluateBugTransition(from: WorkflowState, to: WorkflowState): WorkflowViolation[] {
+  if (from === "Parked for Removal") {
+    // to New (human-only revive) and to Removed (G3) were handled by the
+    // shared front matter; every other exit keeps the parked note.
+    return [{ kind: "no-transition", fromState: from, toState: to, note: PARKED_EXIT_NOTE }];
+  }
+  if (to === "Parked for Removal") {
+    return BUG_PARKING_SOURCES.has(from)
+      ? []
+      : [{ kind: "no-transition", fromState: from, toState: to, note: PARKED_EXIT_NOTE }];
+  }
+  if (from === "Approved" && to === "In Reproduction") return [];
+  if (from === "In Reproduction" && to === "In Fixing") return [];
+  if (BUG_LOOP_STATES.has(from) && BUG_LOOP_STATES.has(to)) return [];
+  return [{ kind: "no-transition", fromState: from, toState: to }];
+}
+
+/**
+ * The states that may move back to New for a re-plan — any active state.
+ * Parked for Removal is deliberately absent: its → New revive is human-only
+ * (F10). Done and Removed are terminal (F10) and absent too.
+ */
+const REPLAN_SOURCES: ReadonlySet<WorkflowState> = new Set([
+  "In Planning",
+  "Awaiting Approval",
+  "Approved",
+  "Design Validation",
+  "In Implementation",
+  "In Testing",
+  "In Review",
+  "Updating Docs",
+]);
 
 /**
  * Targets no agent may set, with the owner named in the refusal: Approved is
@@ -88,46 +148,68 @@ const RECOVERY_EDGE: readonly [WorkflowState, WorkflowState] = ['Done', 'In Plan
  * 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 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",
 };
 
-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 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 (human-only revive) or Removed (G3 human)";
+/** F10: the parked revive is Tarun's alone, like the G3 removal it precedes. */
+export const PARKED_REVIVE_OWNER = "human revive only; agents cannot move items from Parked for Removal back to New";
 
 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 };
+  | { 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 };
+
+/**
+ * The Feature ladder's violation shape (F3). Mirrors WorkflowViolation but uses
+ * FeatureState literals so `evaluateFeatureTransition`'s output is honest about
+ * what states it carries, instead of casting every Feature-state literal to
+ * WorkflowState at the function boundary.
+ */
+export type FeatureViolation =
+  | { kind: "skipped-gate"; fromState: FeatureState; toState: FeatureState; skippedState: FeatureState }
+  | { kind: "human-only"; fromState: FeatureState; toState: FeatureState; owner: string }
+  | { kind: "no-transition"; fromState: FeatureState; toState: FeatureState; note?: string };
 
 /**
  * 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.
+ *   or G3 human removal; agents never set it. Checked before the
+ *   from-state recognition (F2), so an off-ladder from-state cannot smuggle
+ *   an agent into a human-owned target. Parked for Removal → New is a
+ *   human-only revive (F10) with its own owner text.
  * - `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").
+ *   transition touching it names the retired state. Done and Removed are
+ *   terminal for agents (F10): every exit is refused with the terminal
+ *   note. Parked for Removal is enterable from anywhere and exits only to
+ *   New (human-only revive) or Removed (G3).
+ *
+ * The loop is non-linear (F1): every ordered pair among In Implementation,
+ * In Testing, In Review and Updating Docs is allowed, and In
+ * Implementation → Design Validation is the drift loop-back. Backward
+ * moves outside the loop are refused flat — no special-casing.
+ *
+ * F9: Bugs walk their own ladder — New → Approved (G1, human-only) →
+ * In Reproduction → In Fixing, then the same non-linear loop with
+ * In Fixing in place of In Implementation; parking from any non-terminal
+ * Bug state; never In Planning, Awaiting Approval or Design Validation.
  *
  * 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.
+ * state; re-plan moves to New from any active state; the 12 loop pairs and
+ * the drift loop-back. A state outside the thirteen recognized states
+ * yields none — except the human-only targets, refused first (F2) — the
+ * ADO process template enforces server-side. Exempt types (Feature/Epic)
+ * yield none.
  */
 export function evaluateWorkflowTransition(
   workItemType: string,
@@ -135,60 +217,135 @@ export function evaluateWorkflowTransition(
   toState: string,
 ): WorkflowViolation[] {
   if (!(GATED_TYPES as readonly string[]).includes(workItemType)) return [];
+  if (fromState === toState) return [];
+  if (fromState === "Committed" || toState === "Committed") {
+    return [
+      {
+        kind: "no-transition",
+        fromState: fromState as WorkflowState,
+        toState: toState as WorkflowState,
+        note: RETIRED_COMMITTED_NOTE,
+      },
+    ];
+  }
+  // F2: the human-only targets are refused BEFORE the from-state
+  // recognition, so an off-ladder from-state cannot smuggle an agent into
+  // a human-owned target.
+  const owner = (WORKFLOW_HUMAN_ONLY_TARGETS as Partial<Record<string, string>>)[toState];
+  if (owner !== undefined) {
+    return [
+      { kind: "human-only", fromState: fromState as WorkflowState, toState: toState as WorkflowState, owner },
+    ];
+  }
   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 }];
+  if (from === "Parked for Removal" && to === "New") {
+    return [{ kind: "human-only", fromState: from, toState: to, owner: PARKED_REVIVE_OWNER }];
   }
-  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 === "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 }];
+  // F9: Bugs walk their own ladder from here on.
+  if (workItemType === "Bug") return evaluateBugTransition(from, to);
+  if (to === "Parked for Removal") return [];
+  if (to === "New" && REPLAN_SOURCES.has(from)) return [];
+  if (LOOP_STATES.has(from) && LOOP_STATES.has(to)) return [];
+  if (from === DRIFT_EDGE[0] && to === DRIFT_EDGE[1]) return [];
+  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',
+      kind: "skipped-gate",
       fromState: from,
       toState: to,
       skippedState,
     }));
   }
-  return [{ kind: 'no-transition', fromState: from, toState: to }];
+  return [{ kind: "no-transition", fromState: from, toState: to }];
 }
 
-/** from is Done or Removed here; identity, parking and recoveries were handled by the caller. */
+/** from is Done or Removed here; identity, parking and human-only targets 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';
+  return from === "Done" ? "completed items stay Done; a G2 rejection gets its own linked item" : "Removed is terminal";
 }
 
-export function formatWorkflowViolation(violation: WorkflowViolation): string {
-  if (violation.kind === 'skipped-gate') {
-    const g1 = violation.skippedState === 'Approved' ? ' (G1: human approval)' : '';
+/** A printable violation: either WorkflowViolation or FeatureViolation. Both shapes carry
+ *  the same {kind, fromState, toState} skeleton so the formatter can render either. */
+export type AnyWorkflowViolation = WorkflowViolation | FeatureViolation;
+
+export function formatWorkflowViolation(violation: AnyWorkflowViolation): string {
+  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') {
+  if (violation.kind === "human-only") {
     return `fenced by state ladder: '${violation.fromState}' → '${violation.toState}' is ${violation.owner}`;
   }
-  const note = violation.note === undefined ? '' : ` (${violation.note})`;
+  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');
+export function formatWorkflowRefusal(violations: readonly AnyWorkflowViolation[]): string {
+  return violations.map(formatWorkflowViolation).join("\n");
+}
+
+/**
+ * The Feature ladder (F3): linear, one step at a time, never backward —
+ * New → In Progress → Awaiting Release → Done. Only a human moves a
+ * Feature to Removed (G3). 'Awaiting Release' exists only on Features, so
+ * this table is deliberately separate from evaluateWorkflowTransition,
+ * which stays pure on the item-ladder vocabulary; the Feature
+ * preconditions against children live in azdo-wit.ts (F4).
+ */
+const FEATURE_STATES = ["New", "In Progress", "Awaiting Release", "Done", "Removed"] as const;
+type FeatureState = (typeof FEATURE_STATES)[number];
+
+const FEATURE_MAIN_LINE: readonly FeatureState[] = ["New", "In Progress", "Awaiting Release", "Done"];
+const FEATURE_MAIN_LINE_INDEX = new Map<string, number>(FEATURE_MAIN_LINE.map((state, index) => [state, index]));
+const FEATURE_LADDER_EDGES: readonly (readonly [FeatureState, FeatureState])[] = FEATURE_MAIN_LINE.slice(1).map(
+  (state, index) => [FEATURE_MAIN_LINE[index]!, state] as const,
+);
+const FEATURE_REMOVED_OWNER = "G3 — human removal only; agents cannot move Features to Removed";
+const FEATURE_BACKWARD_NOTE = "the Feature ladder is linear: never backward";
+
+/**
+ * Evaluate a Feature state TRANSITION against the Feature ladder. Like the
+ * item fence: identity writes are never gated; the human-only target
+ * (Removed) is refused before the from-state recognition; unknown states
+ * stay silent (the ADO process enforces server-side); forward skips name
+ * every skipped state; backward moves refuse flat.
+ */
+export function evaluateFeatureTransition(fromState: string, toState: string): FeatureViolation[] {
+  if (fromState === toState) return [];
+  if (toState === "Removed") {
+    // An off-ladder fromState still trips the human-only refusal here (the
+    // Removed check fires before from-state recognition, see comment at
+    // the function head). We normalize fromState to "Removed" so the
+    // violation shape stays in FeatureState terms; the human-only owner
+    // note names Removed at the G3 boundary.
+    return [{ kind: "human-only", fromState: "Removed", toState: "Removed", owner: FEATURE_REMOVED_OWNER }];
+  }
+  if (!(FEATURE_STATES as readonly string[]).includes(fromState)) return [];
+  if (!(FEATURE_STATES as readonly string[]).includes(toState)) return [];
+  const from = fromState as FeatureState;
+  const to = toState as FeatureState;
+  if (FEATURE_LADDER_EDGES.some(([edgeFrom, edgeTo]) => edgeFrom === from && edgeTo === to)) return [];
+  const fromIndex = FEATURE_MAIN_LINE_INDEX.get(from)!;
+  const toIndex = FEATURE_MAIN_LINE_INDEX.get(to)!;
+  if (toIndex > fromIndex) {
+    return FEATURE_MAIN_LINE.slice(fromIndex + 1, toIndex).map((skippedState) => ({
+      kind: "skipped-gate",
+      fromState: from,
+      toState: to,
+      skippedState,
+    }));
+  }
+  return [{ kind: "no-transition", fromState: from, toState: to, note: FEATURE_BACKWARD_NOTE }];
 }

package/packages/fleet/src/install-adl-package.ts

@@ -19,15 +19,16 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 // import cross-package by relative path — a package added to those imports
 // but not here breaks every managed repo's git hooks with "Cannot find module"
 // the next time reconcile projects this payload.
-// Every package apps/cli reads from /usr/local/libexec/adl (hooks.ts, skills.ts, settings.ts,
+// Every package apps/cli reads from /usr/local/libexec/adl (hooks.ts, settings.ts,
 // repo-controls.ts: DEFAULT_LIBEXEC_DIR) plus azdo, which they import by relative path.
+// skills.ts dropped its libexec fallback for agent-skills as part of az697
+// (fleet does not install skills; every skill comes from `adl skills deploy`).
 // install-adl-package.test.ts pins both against the real sources.
-export const payloadDirectories = ['packages/agent-skills', 'packages/repo-controls', 'packages/agent-hooks', 'packages/agent-settings', 'packages/azdo']
+export const payloadDirectories = ['packages/repo-controls', 'packages/agent-hooks', 'packages/agent-settings', 'packages/azdo']
 const payloadScripts = ['bin/git', 'bin/git-ado']
 const requiredFiles = [
   'bin/reconcile',
   'packages/fleet/manifest.json',
-  'packages/agent-skills/dist/index.js',
   'packages/repo-controls/bin/adl-repo-controls.ts',
   'packages/agent-hooks/src/log/writer.ts',
   'packages/agent-settings/deploy-profile.json',

package/packages/repo-controls/README.md

@@ -538,7 +538,10 @@ doctor report and never repairs or stages the managed surface: run
   Armed from the first commit with NO ratchet baseline for existing violations, so an
   existing repository reports its violations as guidance. Measured on a fresh install
   (see "Fresh-install result" below), the one gate this package's own install leaves
-  failing is `repository.license-declared` (REP-001: no `license` declared). An existing `enabled` key, even `[]`, is never rewritten, and
+  failing is `repository.license-declared` (REP-001: no `license` declared), and
+  `docs.okf-profile`, `docs.filename` and `docs.directory-size` are could-not-run until
+  the first real docs page lands — the fresh scaffold's `docs/` holds only
+  `AGENTS.md`/`CLAUDE.md`/`decisions/index.md`, all outside their scope. An existing `enabled` key, even `[]`, is never rewritten, and
   switching a gate off is the repository's own decision, made by removing its one line
   from `enabled`
   ([`#strict-activation-and-switching-a-gate-off`](../../docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off)).
@@ -598,7 +601,7 @@ truthful. A `uv`-less machine errors out of the grade step, after everything is
 
 Install bootstraps the minimal skeleton of `docs`, `plans` and `workflows` from the
 package's `assets/scaffold/<tree>/` (Bug 570, Tarun 2026-10-08):
-`docs/{AGENTS.md,CLAUDE.md,notes.md,decisions/index.md}`,
+`docs/{AGENTS.md,CLAUDE.md,decisions/index.md}`,
 `plans/{AGENTS.md,CLAUDE.md,GAPS-AND-FINDINGS.md,LEDGER.md,features/.gitkeep}`, and
 `workflows/{AGENTS.md,CLAUDE.md,pipelines/.gitkeep,scripts/.gitkeep}`. Rules:
 
@@ -630,8 +633,13 @@ package's `assets/scaffold/<tree>/` (Bug 570, Tarun 2026-10-08):
 
 The scaffold gates (DOC-001, DOC-002, DOC-004 to DOC-012, LAY-002, LAY-004, LAY-009,
 LAY-011, LAY-014, LAY-016, LFS-001) pass on a fresh install
-(`tests/install-scaffold.test.ts`). Of the 29 enabled gates, the package-level result of a
-fresh install is exactly one failing gate, REP-001 `repository.license-declared`
+(`tests/install-scaffold.test.ts`), except DOC-006, DOC-011 and DOC-012, which are
+could-not-run there: the fresh scaffold's `docs/` holds only
+`AGENTS.md`/`CLAUDE.md`/`decisions/index.md`, all outside their scope, and a scope
+that selects nothing is could-not-run, never a clean pass (Bug 597). They start
+grading with the first real docs page. Of the 29 enabled gates, the package-level
+result of a fresh install is exactly one failing gate, REP-001
+`repository.license-declared`, plus those three could-not-run
 (`tests/install-strict.test.ts`). `adl install` also deploys skills, hooks and plugins into
 the repository, and any of their files with consecutive comment lines fail REP-007
 `repository.no-multiline-comments`; that is a defect of the deployed assets, not an expected

package/packages/repo-controls/assets/promote.ts

@@ -1,5 +1,6 @@
 // Managed by adl-repo-controls, do not edit; regenerate with: adl-repo-controls install --repo . (README "Managed workflow scripts").
 
+
 /** Promote one branch to another through an Azure DevOps pull request; see README "Managed workflow scripts". */
 
 /** Azure DevOps' `mergeStrategy` by name; see README "Managed workflow scripts". */

package/packages/repo-controls/assets/scaffold/docs/AGENTS.md

@@ -10,16 +10,16 @@ the way it is.
 - Sub-directories group related pages (for example `decisions/` for
   architecture decision records, `research/` for dated investigations). Add one
   only when it has pages to hold.
-- `notes.md` is the repository's task ledger: one line when an agent starts a
-  task and one when it finishes.
+- The agent activity log lives at `.adl/agent-activity.sqlite` (gitignored,
+  local only): agents write with `adl activity add "<note>"` and read with
+  `adl activity list`.
 
 ## Conventions
 
 - Every page carries YAML frontmatter with at least `type`, `title`,
   `description`, `status` and `last_update` (ISO-8601 UTC,
   `YYYY-MM-DDTHH:MM:SSZ`).
-- `notes.md` is append-only: newest line at the bottom, earlier lines are never
-  rewritten. Format `YYYY-MM-DD HH:MM <surface> <note>`, at most 100
-  characters per line.
+- Activity entries are append-only, oldest first, and the tool fills time
+  (UTC), surface, agent identity and repo — only the note is caller-supplied.
 - A page that is catalogued in an index stays listed there; add the entry in
   the same change that adds or renames the page.

package/packages/repo-controls/assets/scaffold/plans/AGENTS.md

@@ -5,19 +5,45 @@ board is the only place status lives; the files here describe the work.
 
 ## Layout
 
-- `plans/features/az<id>-<slug>/spec.md` — one Feature, one file, for its whole
-  life. Frontmatter: `type: feature`, `title`, `status` (the board state),
-  `epic:` (the parent Epic's board URL), `work_item:` (this Feature's own board
-  URL), `last_update`. The Feature's own `## Items` table is the one place it
-  may list its children.
-- `plans/features/az<id>-<slug>/items/az<item-id>-<slug>.md` — one PBI or Bug.
-  Frontmatter: `type: pbi` or `type: bug`, `title`, `status`, `feature:` (the
-  parent Feature's slug), `work_item:`, `last_update`.
-- `plans/GAPS-AND-FINDINGS.md` — a register of gaps found while planning or
-  building something else. A row is deleted, not marked done, once its linked
-  item closes.
-- `plans/LEDGER.md` — the plan-event ledger, a Markdown table, newest entry
-  first.
+```text
+plans/
+  LEDGER.md
+  features/
+    az<feature id>-<slug>/
+      intent.md                 # required — lands with the Feature
+      requirements.md           # the planning run (approved at G1)
+      design.md                 # optional — the planning run
+      file-map-reference.md     # optional — the planning run
+      items/
+        az<item id>-<slug>.md   # one PBI or Bug
+```
+
+- `plans/features/az<id>-<slug>/intent.md` — the WHY, written by the human
+  with the Feature. Frontmatter: `type: intent`, `title`, `status` (the
+  Feature's board state), `work_item:` (the Feature's full board URL; its id
+  equals the folder id), `last_update`. Sections: `## Why`, `## Outcome`,
+  `## Constraints`, `## Non-goals`, optional `## Open questions`.
+- `plans/features/az<id>-<slug>/requirements.md` — the what and why, frozen
+  at G1. Frontmatter: `type: feature`, `title`, `status` (the Feature's
+  board state), `epic:` (the parent Epic's board URL), `work_item:` (the
+  Feature's full board URL), `last_update`, `sources:` listing `intent.md`
+  first. Sections: `## Problem`, `## Acceptance criteria` (`AC-1…`, EARS),
+  `## Scope`, `## Predecessors`, `## Items` (`Id | Title | Type | Delivers |
+  Verification`), `## Open questions for G1`, `## Revision log`.
+- `plans/features/az<id>-<slug>/items/az<item-id>-<slug>.md` — one PBI or
+  Bug. Frontmatter: `type: pbi` or `type: bug`, `title`, `status` (the
+  item's board state), `work_item:` (the item's full board URL), `feature:`
+  (the Feature's full board URL), `last_update`. A PBI carries `## What it
+  delivers` and `## Verification` naming its `AC-n`; a Fixes Bug carries the
+  bugfix sections (`## Current behaviour`, `## Expected behaviour`,
+  `## Behaviour that must not change`, `## Responsible Feature`,
+  `## Predecessors`, `## Verification`).
+- `plans/LEDGER.md` — the plan-event ledger: `Date | Id | Area | Event |
+  Refs`, newest first, Event ≤ 99 characters. There is no `Next` table;
+  Feature order comes from the board's predecessor links.
+
+The templates ship with the `adl-workitems-process` skill
+(`references/templates/`); there is no per-repo `plans/templates/`.
 
 ## Conventions
 
@@ -26,3 +52,6 @@ board is the only place status lives; the files here describe the work.
 - An item is allocated on the board first; the file is named `az<id>-<slug>`
   only once that id exists. Files never move between directories.
 - `epic:` and `feature:` are authored by hand, never tool-generated.
+- An item names its `feature:` as the Feature's full board URL.
+- A gap found along the way is filed through `report-bug`, never a register
+  file; findings enter only that way.

package/packages/repo-controls/assets/scaffold/root/CONTRIBUTING.md

@@ -4,10 +4,10 @@ How to contribute to THIS repository. Orientation is in `AGENTS.md`; what must n
 
 ## Plans and work items
 - A plan is a Feature; a backlog item is a PBI or a Bug. One file each; the board is the only place their state lives.
-- Layout: `plans/features/az<feature id>-<slug>/spec.md`, items under `items/az<id>-<slug>.md`.
+- Layout: `plans/features/az<feature id>-<slug>/` with `intent.md`, `requirements.md` (plan files `design.md`/`file-map-reference.md` optional), items under `items/az<id>-<slug>.md`.
 - The id is the identity: allocate the item on the board first, then name the file. Until then it is a row in the plan's `## Items` table.
-- Nothing moves between directories; the spec text is the item's fields.
-- A gap found along the way goes in `plans/GAPS-AND-FINDINGS.md` and becomes a Bug under the same Feature.
+- Nothing moves between directories; the plan text is the work item's fields.
+- An item names its `feature:` as the Feature's full board URL; a gap found along the way is filed through `report-bug`, never a register file.
 
 ## Commits and PRs
 - Each commit is independently green and on one topic. Never `git stash`. Green wins over one topic, and say so.
@@ -21,8 +21,8 @@ How to contribute to THIS repository. Orientation is in `AGENTS.md`; what must n
 - A repository that differs states it under "Release flow of this repository".
 
 ## Tasks ledger
-- At the start and the end of a task, append one line to `docs/notes.md` (create it if missing, with YAML frontmatter and a `## Lines` section).
-- Format `YYYY-MM-DD HH:MM <surface> <note>`, whole line ≤100 characters. Append-only, newest last, never rewrite earlier lines. One ledger per repository.
+- At the start and the end of a task, log with `adl activity add "<note>"` and read the log with `adl activity list`. The MCP tools `activity_add`/`activity_list` are the same storage; the CLI is the documented fallback.
+- The log is `.adl/agent-activity.sqlite` — gitignored, local only. One ledger per repository; the tool fills time, surface, agent and repo, and only the note is caller-supplied.
 
 ## Release flow of this repository
 - <!-- Owner: state any difference from the flow above; delete this section if none. -->