@erclx/aitk 3.6.0 → 3.7.0

package/src/demo/drive.ts

@@ -0,0 +1,256 @@
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { chromium } from 'playwright-core'
+import type { Browser, BrowserContext, Page } from 'playwright-core'
+import type { DemoPlan, DemoStep } from '@/demo/compile'
+import type { CursorSet } from '@/demo/pointer'
+import { pointerSource } from '@/demo/pointer'
+
+/**
+ * Drives a running application and records what it did. Every browser reference
+ * the demo feature adds lives here, and `src/commands/demo.ts` reaches it
+ * through a dynamic import so no other command resolves the engine at startup.
+ *
+ * Unlike `@/capture/render`, this module ships. The capture command is excluded
+ * from the published package because it regenerates images committed to this
+ * repository, and that reason does not transfer to a command whose whole
+ * purpose is running in someone else's project.
+ *
+ * It imports `playwright-core` rather than `@playwright/test`, which stays a
+ * development dependency for the capture module. Shipping puts the import in
+ * every target's dependency tree, and a target needs the driver rather than a
+ * test runner and an assertion library. Both are pinned to one version rather
+ * than a range, because `bunx playwright install chromium` fetches the browser
+ * revision the installed engine expects and a float would leave a target
+ * resolving a binary its engine cannot launch.
+ */
+
+const POINTER_SIZE = 32
+/**
+ * Where the pointer starts. Any position inside the viewport works, since the
+ * point is giving it one move to install and paint before it travels to the
+ * first target. A corner keeps that first move out of the way of the content.
+ */
+const START = { x: 8, y: 8 }
+const SETTLE_MS = 250
+
+/**
+ * The two output paths arrive resolved rather than as a root this re-resolves
+ * against, because the plan already carries a directory and resolving it twice
+ * nests the whole path inside itself.
+ *
+ * An absent path means the caller asked for that artifact not to be produced.
+ */
+export interface DriveOptions {
+  readonly plan: DemoPlan
+  readonly cursors: CursorSet
+  readonly videoPath?: string
+  readonly stillPath?: string
+}
+
+export type DriveResult =
+  | {
+      status: 'recorded'
+      videoPath?: string
+      stillPath?: string
+      steps: number
+      durationMs: number
+    }
+  | { status: 'failed'; reason: DriveRefusal; message: string }
+
+export type DriveRefusal = 'browser-missing' | 'drive-failed'
+
+interface DriveFailure {
+  readonly status: 'failed'
+  readonly reason: DriveRefusal
+  readonly message: string
+}
+
+type Launch = { status: 'launched'; value: Browser } | DriveFailure
+
+export async function drive(options: DriveOptions): Promise<DriveResult> {
+  const { plan } = options
+
+  const browser = await launch()
+  if (browser.status === 'failed') return browser
+
+  let videoDir: string | undefined
+  let context: BrowserContext
+  const started = Date.now()
+  try {
+    // Created after the launch, so a target with no browser binary does not
+    // leave an empty directory behind for a run that never started, and inside
+    // the try so a failure here closes the browser rather than leaking it.
+    videoDir = options.videoPath
+      ? mkdtempSync(join(tmpdir(), 'aitk-demo-'))
+      : undefined
+
+    context = await browser.value.newContext({
+      viewport: plan.viewport,
+      // Pointed the opposite way from a test. A recording wants the motion the
+      // interface was designed with, where a test wants it suppressed.
+      reducedMotion: 'no-preference',
+      ...(videoDir
+        ? {
+            recordVideo: {
+              dir: videoDir,
+              size: plan.viewport,
+              showActions: {
+                duration: plan.annotations.durationMs,
+                position: plan.annotations.position,
+                fontSize: plan.annotations.fontSize,
+              },
+            },
+          }
+        : {}),
+    })
+  } catch (error) {
+    await browser.value.close()
+    if (videoDir) rmSync(videoDir, { recursive: true, force: true })
+    return failed('drive-failed', error)
+  }
+
+  let stillPath: string | undefined
+  let videoPath: string | undefined
+
+  try {
+    await context.addInitScript({
+      content: pointerSource(options.cursors, POINTER_SIZE),
+    })
+    const page = await context.newPage()
+    const video = page.video()
+
+    // The opening navigate is skipped when the plan already starts with one,
+    // because a draft written around an opening verb compiles to a `navigate`
+    // step for the same URL and the second load is a visible reload.
+    if (plan.steps[0]?.kind !== 'navigate') {
+      await page.goto(plan.url)
+      await page.mouse.move(START.x, START.y, { steps: 2 })
+    }
+
+    for (const step of plan.steps) {
+      await runStep(page, plan, step)
+      // The first marked step wins. One file holds one frame, so a plan a
+      // person edited to mark several would otherwise write each over the last
+      // and keep whichever ran last, with nothing saying so.
+      if (step.still && options.stillPath && !stillPath) {
+        stillPath = options.stillPath
+        mkdirSync(dirname(stillPath), { recursive: true })
+        await page.screenshot({ path: stillPath })
+      }
+    }
+
+    await context.close()
+
+    if (video && options.videoPath) {
+      videoPath = options.videoPath
+      mkdirSync(dirname(videoPath), { recursive: true })
+      await video.saveAs(videoPath)
+      // The engine keeps the auto-named recording beside the saved copy, so a
+      // run that skipped this would leave two files for every demo.
+      await video.delete()
+    }
+  } catch (error) {
+    return failed('drive-failed', error)
+  } finally {
+    await browser.value.close()
+    if (videoDir) rmSync(videoDir, { recursive: true, force: true })
+  }
+
+  return {
+    status: 'recorded',
+    ...(videoPath ? { videoPath } : {}),
+    ...(stillPath ? { stillPath } : {}),
+    steps: plan.steps.length,
+    durationMs: Date.now() - started,
+  }
+}
+
+/**
+ * Separates a browser binary that was never installed from every other launch
+ * failure, because the first is a setup step the operator has to run and the
+ * second is a defect. A target inherits that setup step, which is the stated
+ * cost of shipping this command outside the toolkit.
+ */
+async function launch(): Promise<Launch> {
+  try {
+    return { status: 'launched', value: await chromium.launch() }
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error)
+    return failed(
+      /executable doesn't exist|playwright install/i.test(text)
+        ? 'browser-missing'
+        : 'drive-failed',
+      error,
+    )
+  }
+}
+
+async function runStep(
+  page: Page,
+  plan: DemoPlan,
+  step: DemoStep,
+): Promise<void> {
+  switch (step.kind) {
+    case 'navigate':
+      await page.goto(step.target || plan.url)
+      await page.mouse.move(START.x, START.y, { steps: 2 })
+      break
+    case 'click':
+      await moveTo(page, plan, step)
+      await page.mouse.down()
+      await page.mouse.up()
+      break
+    case 'fill':
+      await moveTo(page, plan, step)
+      await page.mouse.down()
+      await page.mouse.up()
+      await page.keyboard.type(step.text, { delay: plan.pointer.typeDelayMs })
+      break
+    case 'hover':
+      await moveTo(page, plan, step)
+      break
+    case 'scroll':
+      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      await page.waitForTimeout(SETTLE_MS)
+      await moveTo(page, plan, step)
+      break
+    case 'wait':
+    case 'hold':
+      break
+  }
+
+  if (step.waitFor) await page.locator(step.waitFor).first().waitFor()
+  await page.waitForTimeout(step.holdMs)
+}
+
+/**
+ * Travel is the whole point of driving the engine's pointer rather than calling
+ * the element-clicking helper, which resolves a target and jumps to it. The
+ * step count is what separates a cursor that glides from one that teleports.
+ *
+ * Resolving through a bounding box assumes the target is in the viewport, so a
+ * target below the fold needs a `scroll` step ahead of it.
+ */
+async function moveTo(
+  page: Page,
+  plan: DemoPlan,
+  step: DemoStep,
+): Promise<void> {
+  const locator = page.locator(step.target).first()
+  await locator.waitFor()
+  const box = await locator.boundingBox()
+  if (!box) throw new Error(`${step.target} has no box to point at`)
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, {
+    steps: plan.pointer.steps,
+  })
+}
+
+function failed(reason: DriveRefusal, error: unknown): DriveFailure {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}

package/src/demo/pointer.ts

@@ -0,0 +1,178 @@
+/**
+ * The pointer the recording shows. The browser engine's own annotation draws a
+ * dot at the moment of a click and paints no cursor, so a run without this
+ * looks like the pointer teleports between targets.
+ *
+ * Nothing here touches a browser. `pointerSource` returns the script text that
+ * `@/demo/drive` installs before navigation, which keeps the hotspot arithmetic
+ * and the state table testable without launching anything.
+ */
+
+export interface CursorHotspot {
+  readonly width: number
+  readonly height: number
+  readonly hotspotX: number
+  readonly hotspotY: number
+}
+
+export interface Cursor {
+  readonly image: string
+  readonly hotspot: CursorHotspot
+}
+
+export type CursorSet = Readonly<Record<string, Cursor>>
+
+const HEADER_BYTES = 6
+const ENTRY_BYTES = 16
+const CURSOR_TYPE = 2
+/** The format stores 256 as a zero, since the field is one byte wide. */
+const SIZE_256 = 256
+
+/**
+ * Reads the directory of a Windows cursor resource and returns the hotspot of
+ * its largest entry. A resource carries several sizes with a hotspot each, and
+ * taking the largest is what matches the artwork the recorder draws at.
+ *
+ * Only the header and directory are read. The pixel payload is left to the
+ * browser, which spike 3 measured as decoding the format directly with no
+ * conversion step and no image tooling on the machine.
+ */
+export function cursorHotspot(bytes: Uint8Array): CursorHotspot | undefined {
+  if (bytes.byteLength < HEADER_BYTES + ENTRY_BYTES) return undefined
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (view.getUint16(2, true) !== CURSOR_TYPE) return undefined
+
+  const count = view.getUint16(4, true)
+  if (count === 0) return undefined
+
+  let largest: CursorHotspot | undefined
+  for (let index = 0; index < count; index += 1) {
+    const at = HEADER_BYTES + index * ENTRY_BYTES
+    if (at + ENTRY_BYTES > bytes.byteLength) break
+
+    const entry: CursorHotspot = {
+      width: bytes[at] === 0 ? SIZE_256 : (bytes[at] ?? 0),
+      height: bytes[at + 1] === 0 ? SIZE_256 : (bytes[at + 1] ?? 0),
+      hotspotX: view.getUint16(at + 4, true),
+      hotspotY: view.getUint16(at + 6, true),
+    }
+    if (!largest || entry.width * entry.height > largest.width * largest.height)
+      largest = entry
+  }
+  return largest
+}
+
+/**
+ * Converts a hotspot stated against the source artwork into an offset in the
+ * size the pointer is drawn at. Skipping this puts the artwork's top left where
+ * the click lands instead of its tip, which offsets every action by roughly a
+ * third of a cursor.
+ */
+export function scaleHotspot(
+  hotspot: CursorHotspot,
+  drawnSize: number,
+): { x: number; y: number } {
+  const scale = drawnSize / hotspot.width
+  return {
+    x: hotspot.hotspotX * scale,
+    y: hotspot.hotspotY * (drawnSize / hotspot.height),
+  }
+}
+
+interface PointerState {
+  readonly image: string
+  readonly x: number
+  readonly y: number
+}
+
+/**
+ * Returns the script installed before navigation. It is a string rather than a
+ * function reference because the cursor payload is data resolved on this side,
+ * and passing artwork through an argument would still need serializing.
+ *
+ * The element inherits the page's world, so a site with its own element at this
+ * id, a stacking context that outranks it, or a style rule reaching it will
+ * interfere. That is the cost of drawing the pointer inside the page rather
+ * than reaching for a desktop recorder.
+ */
+export function pointerSource(cursors: CursorSet, size: number): string {
+  const states: Record<string, PointerState> = {}
+  for (const [name, cursor] of Object.entries(cursors)) {
+    const offset = scaleHotspot(cursor.hotspot, size)
+    states[name] = { image: cursor.image, x: offset.x, y: offset.y }
+  }
+
+  const config = JSON.stringify({ size, states })
+
+  return `(() => {
+  const CONFIG = ${config};
+  const ID = '__aitk_demo_pointer__';
+  if (window[ID]) return;
+  window[ID] = true;
+
+  let node;
+  let state = 'default';
+  let pressed = false;
+  let x = -9999;
+  let y = -9999;
+
+  const install = () => {
+    if (node || !document.body) return;
+    node = document.createElement('img');
+    node.id = ID;
+    node.setAttribute('aria-hidden', 'true');
+    node.style.cssText = [
+      'position:fixed',
+      'left:0',
+      'top:0',
+      'width:' + CONFIG.size + 'px',
+      'height:' + CONFIG.size + 'px',
+      'z-index:2147483647',
+      'pointer-events:none',
+      'user-select:none',
+      'will-change:transform',
+      'transition:transform 90ms ease-out',
+    ].join(';');
+    document.body.appendChild(node);
+    paint();
+  };
+
+  const paint = () => {
+    if (!node) return;
+    const cursor = CONFIG.states[state] || CONFIG.states.default;
+    if (!cursor) return;
+    if (node.getAttribute('src') !== cursor.image) node.setAttribute('src', cursor.image);
+    const scale = pressed ? 0.88 : 1;
+    node.style.transform =
+      'translate(' + (x - cursor.x) + 'px,' + (y - cursor.y) + 'px) scale(' + scale + ')';
+  };
+
+  const stateAt = (target) => {
+    if (!(target instanceof Element)) return 'default';
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || target.isContentEditable) return 'text';
+    const style = getComputedStyle(target).cursor;
+    if (style === 'pointer' && CONFIG.states.pointer) return 'pointer';
+    if (style === 'text' && CONFIG.states.text) return 'text';
+    return 'default';
+  };
+
+  addEventListener('mousemove', (event) => {
+    x = event.clientX;
+    y = event.clientY;
+    state = stateAt(event.target);
+    install();
+    paint();
+  }, true);
+
+  addEventListener('mousedown', () => { pressed = true; paint(); }, true);
+  addEventListener('mouseup', () => { pressed = false; paint(); }, true);
+
+  if (document.readyState === 'loading') {
+    addEventListener('DOMContentLoaded', install, { once: true });
+  } else {
+    install();
+  }
+})();`
+}

package/src/demo/theme.ts

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cursorHotspot, type Cursor, type CursorSet } from '@/demo/pointer'
+
+/**
+ * Reads a cursor theme folder so `--cursor` can point at one. Spike 3 measured
+ * the browser decoding a Windows cursor resource directly, so nothing here
+ * converts anything: the bytes go into a data URI and the header supplies the
+ * hotspot.
+ *
+ * Three of the nineteen states a theme carries are read. A drag, a resize, or a
+ * wait shows the default arrow where a real session would show something else,
+ * and the two animated states have no still frame to draw at all.
+ */
+
+const CURSOR_MIME = 'image/x-icon'
+const EXTENSION = /\.cur$/i
+
+/** Ordered per state, most specific first, so an exact name beats a longer one. */
+const NAMES: Record<string, readonly string[]> = {
+  default: ['arrow', 'normal', 'default'],
+  pointer: ['link', 'hand', 'pointer'],
+  text: ['ibeam', 'beam', 'text'],
+}
+
+export type CursorFiles = Partial<Record<string, string>>
+
+/**
+ * Picks one file per state out of a directory listing. Matching runs on the
+ * name rather than on the contents because a theme states its intent there, and
+ * a shorter match wins so `Arrow.cur` beats `Arrow Alternate.cur`.
+ */
+export function matchCursorFiles(files: readonly string[]): CursorFiles {
+  const cursors = files.filter((file) => EXTENSION.test(file))
+  const matched: CursorFiles = {}
+
+  for (const [state, names] of Object.entries(NAMES)) {
+    const found = names
+      .flatMap((name) =>
+        cursors.filter((file) => file.toLowerCase().includes(name)),
+      )
+      .sort((left, right) => left.length - right.length)[0]
+    if (found) matched[state] = found
+  }
+
+  return matched
+}
+
+export type ThemeLoad =
+  | { status: 'loaded'; cursors: CursorSet; states: string[] }
+  | { status: 'failed'; reason: string }
+
+/**
+ * Falls back to the bundled artwork per state rather than per theme, so a
+ * folder carrying an arrow and no hand still contributes its arrow.
+ */
+export function loadCursorTheme(dir: string, fallback: CursorSet): ThemeLoad {
+  let listing: string[]
+  try {
+    listing = readdirNames(dir)
+  } catch (error) {
+    return {
+      status: 'failed',
+      reason: `${dir} could not be read: ${message(error)}`,
+    }
+  }
+
+  const matched = matchCursorFiles(listing)
+  const states = Object.keys(matched)
+  if (!states.length) {
+    return {
+      status: 'failed',
+      reason: `${dir} holds no .cur file named after a pointer, link, or text state`,
+    }
+  }
+
+  const cursors: Record<string, Cursor> = { ...fallback }
+  for (const [state, file] of Object.entries(matched)) {
+    if (!file) continue
+    const loaded = readCursor(join(dir, file))
+    if (loaded) cursors[state] = loaded
+  }
+
+  return { status: 'loaded', cursors, states }
+}
+
+function readCursor(path: string): Cursor | undefined {
+  let bytes: Uint8Array
+  try {
+    bytes = readFileSync(path)
+  } catch {
+    return undefined
+  }
+
+  const hotspot = cursorHotspot(bytes)
+  if (!hotspot) return undefined
+
+  return {
+    image: `data:${CURSOR_MIME};base64,${Buffer.from(bytes).toString('base64')}`,
+    hotspot,
+  }
+}
+
+function readdirNames(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/records/backup.ts

@@ -8,14 +8,19 @@ import { gitEnv } from '@/git-env'
  * group the claude manifest ships, minus three: `.claude/.tmp`, which is
  * defined as deletable without loss, `.claude/worktrees/`, whose contents
  * belong to the enclosing repository already, and `.claude/.records.git/`,
- * which is the history the other ten are pushed into. The list is spelled out
+ * which is the history the other seven are pushed into. The list is spelled out
  * rather than read off that group so adding an ignore entry cannot silently
  * enlarge the payload.
  *
  * The manifest group is the one this reads rather than the enclosing
  * repository's own `.gitignore`, which spreads the same entries across two
  * headers and carries `.claude/README.md` that no target receives. Subtracting
- * three from that file instead yields eleven names against this list of ten.
+ * three from that file instead yields eight names against this list of seven.
+ *
+ * Each entry is a top-level record folder and every archive sits inside the one
+ * it archives, so the three former archive entries are covered by their parents
+ * rather than named here. That is what keeps this list at one line per surface
+ * as archives spread, which a sibling-per-archive layout could not.
  *
  * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a
@@ -27,14 +32,31 @@ export const BACKED_FOLDERS = [
   'intake',
   'memory',
   'plans',
-  'plans-archive',
   'review',
-  'review-archive',
-  'task-archive',
   'tasks',
   'teach',
 ] as const
 
+/**
+ * Names that have left `BACKED_FOLDERS` and whose removal still has to reach a
+ * records history once.
+ *
+ * Dropping a name from the list above stops it entering the pathspec, so `add`
+ * never stages its deletion, the remote keeps the folder forever, and a `pull`
+ * onto another machine restores it beside whatever replaced it. These three are
+ * the archives that moved inside the records they archive, so the same files
+ * are already on the remote under their new paths.
+ *
+ * Retire a name here once no records history still carries it. Nothing measures
+ * that, so the cost of leaving one is three pathspec entries that match nothing
+ * and are filtered out before `add` ever sees them.
+ */
+const RETIRED_FOLDERS = [
+  'plans-archive',
+  'review-archive',
+  'task-archive',
+] as const
+
 /** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
 const RECORDS_GIT_DIR = join('.claude', '.records.git')
 
@@ -233,14 +255,18 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
 }
 
 /**
- * The subset of the eight a pathspec can name: on disk, or already in the
- * records index.
+ * The subset of the backed and retired names a pathspec can name: on disk, or
+ * already in the records index.
  *
  * A pathspec matching neither fails the whole `add`, which is why the subset
  * exists. The index half is what covers a folder deleted in full. Reading disk
  * alone drops it from the pathspec, so its deletion never stages, the remote
  * keeps it forever, and a later `pull` restores it past the gate that refuses
  * every other unpushed deletion.
+ *
+ * The retired names are the same case one level up, where the folder left the
+ * backed list rather than the disk, and the index is the only side that still
+ * knows it existed.
  */
 async function scopedFolders(root: string): Promise<string[]> {
   const tracked = await records(root, ['ls-files'])
@@ -248,7 +274,7 @@ async function scopedFolders(root: string): Promise<string[]> {
     tracked.ok ? tracked.text.split('\n').filter(Boolean).map(topSegment) : [],
   )
 
-  return BACKED_FOLDERS.filter(
+  return [...BACKED_FOLDERS, ...RETIRED_FOLDERS].filter(
     (folder) =>
       existsSync(join(root, WORK_TREE, folder)) || indexed.has(folder),
   )

package/src/tasks/archive.ts

@@ -4,9 +4,9 @@ import { join, relative, resolve, sep } from 'node:path'
 import { regenOne } from '@/indexes/regen'
 
 const TASKS_DIR = join('.claude', 'tasks')
-const ARCHIVE_DIR = join('.claude', 'task-archive')
+const ARCHIVE_DIR = join(TASKS_DIR, 'archive')
 const PLANS_DIR = join('.claude', 'plans')
-const PLANS_ARCHIVE_DIR = join('.claude', 'plans-archive')
+const PLANS_ARCHIVE_DIR = join(PLANS_DIR, 'archive')
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -198,6 +198,10 @@ function isUnder(path: string, dir: string): boolean {
  * count below compares two tasks by where their targets land and not by the
  * strings they wrote. A target outside the live plans folder yields nothing,
  * which is an archived plan or a pointer into somewhere else entirely.
+ *
+ * The archive sits inside the folder it archives, so containment alone reads an
+ * archived plan as live. Subtracting it is what keeps a closed task from being
+ * counted as a citation the sweep has yet to make.
  */
 export function resolveLivePlan(
   target: string,
@@ -205,11 +209,14 @@ export function resolveLivePlan(
   root: string,
 ): string | undefined {
   const plans = join(root, PLANS_DIR)
+  const archive = join(root, PLANS_ARCHIVE_DIR)
   const fromBoard = resolve(dir, target)
   const fromRoot = resolve(root, target)
 
-  if (isUnder(fromBoard, plans)) return fromBoard
-  if (isUnder(fromRoot, plans)) return fromRoot
+  if (isUnder(fromBoard, plans) && !isUnder(fromBoard, archive)) {
+    return fromBoard
+  }
+  if (isUnder(fromRoot, plans) && !isUnder(fromRoot, archive)) return fromRoot
   return undefined
 }
 

package/standards/bundled/pr.md

@@ -54,6 +54,9 @@ Does not govern:
 - Quote the count or output the run reported, never a figure carried from elsewhere.
 - Leave a box unchecked only when a human is required, and name which human and why on the same line.
 - Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
+- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
+- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
+- A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
 - Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
 
 ## Formatting

package/standards/plan.md

@@ -123,7 +123,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.claude/plans-archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
+- Move the plan to `.claude/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
 ## Anti-patterns