@erclx/aitk 3.6.0 → 3.8.0

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/gov/adapter.ts

@@ -54,6 +54,7 @@ export function createGovAdapter(root: string): SyncAdapter {
     locateSource: (file: InstalledFile) =>
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
+    projectSubdir: 'project',
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }

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/snippets/adapter.ts

@@ -21,6 +21,7 @@ export function createSnippetsAdapter(root: string): SyncAdapter {
     unit: 'snippets',
     installedRoot: (target: string) => join(target, '.claude', 'snippets'),
     locateSource: (file: InstalledFile) => locateSource(sourceDir, file),
+    projectSubdir: 'project',
     stamp: { domain: 'snippets', toolkitRoot: root },
   }
 }

package/src/sync/engine.ts

@@ -121,6 +121,13 @@ export interface SyncAdapter {
   collectRetired?(target: string): RetiredSurface[]
   /** Dropped from the walk, so neither matching nor orphaned. */
   isExcluded?(file: InstalledFile): boolean
+  /**
+   * Top-level folder under `installedRoot` that is project-authored by
+   * location rather than by the name inference `locateSource` runs.
+   * Checked before `locateSource`, so a file here is orphaned even when its
+   * name also matches a toolkit source, and never enters the stamp.
+   */
+  readonly projectSubdir?: string
   /** Defaults to applying. */
   readonly nonInteractive?: NonInteractivePolicy
   /** Runs on a completed sync, including one with no changes. */
@@ -168,6 +175,11 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     if (adapter.isExcluded?.(file) === true) continue
     walked.add(toStampKey(file.rel))
 
+    if (isProjectAuthored(adapter, file)) {
+      entries.push({ state: 'orphaned', rel: file.rel })
+      continue
+    }
+
     const source = adapter.locateSource(file)
 
     if (source === undefined || !existsSync(source)) {
@@ -439,6 +451,16 @@ function strandedByRelocation(
   return entries
 }
 
+/**
+ * `Bun.Glob` reports `relToRoot` with `/` separators regardless of platform,
+ * so the declared subfolder is compared against the walk's first segment
+ * rather than through a path-aware join.
+ */
+function isProjectAuthored(adapter: SyncAdapter, file: InstalledFile): boolean {
+  if (adapter.projectSubdir === undefined) return false
+  return file.relToRoot.split('/')[0] === adapter.projectSubdir
+}
+
 function isInside(target: string, path: string): boolean {
   const rel = relative(target, path)
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
@@ -457,7 +479,8 @@ function hasUnattributedDrift(plan: SyncPlan): boolean {
 /**
  * Records what the toolkit placed, after the copies land, so a partial apply
  * that throws leaves the previous stamp rather than a claim the target does not
- * meet. Files with no source are project-authored and stay out.
+ * meet. A file with no source, or one orphaned by location, is
+ * project-authored and stays out.
  *
  * Reads the installed tree rather than the caller's file list, so a partial
  * install still stamps the domain's whole installed set.
@@ -474,6 +497,7 @@ export async function recordStamp(
 
   for (const file of listInstalled(adapter.installedRoot(target), target)) {
     if (adapter.isExcluded?.(file) === true) continue
+    if (isProjectAuthored(adapter, file)) continue
 
     const source = adapter.locateSource(file)
     if (source === undefined || !existsSync(source)) continue

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

package/standards/tasks.md

@@ -215,9 +215,9 @@ An intake folder answers that direction at folder scope rather than item scope,
 
 Phase-label format and where labels may appear are governed by `standards/versioning.md`.
 
-`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans-archive/feature-<slug>.md`. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
+`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans/archive/feature-<slug>.md`, and at `../../plans/archive/feature-<slug>.md` once the task itself is archived a folder deeper. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
 
-A project that archived plans before the folder moved out of `.claude/.tmp/` holds closed tasks pointing at `../.tmp/plans-archive/`, and both forms resolve against the files each names, so leave those pointers where they are. Nothing migrates them, and a task retargeted without its plan moving leads nowhere.
+A project that archived plans before the folder nested under `.claude/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. Nothing migrates them, and a task retargeted without its plan moving leads nowhere.
 
 One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
@@ -247,11 +247,11 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 
 ## Archiving
 
-Never delete a task file. A shipped task moves to `.claude/task-archive/` under its own name, and the live index regenerates without it. `aitk tasks archive` owns the move, the ordering-row removal, and the index regen as one unit.
+Never delete a task file. A shipped task moves to `.claude/tasks/archive/` under its own name, and the live index regenerates without it. `aitk tasks archive` owns the move, the ordering-row removal, and the index regen as one unit.
 
 Two callers reach that command. The `claude-tasks` skill runs it inside a session, and the `post-merge` hook runs it unattended after a pull that merged the work. Both go through the command rather than moving the file themselves, so the two paths cannot drift into archiving differently. Every gate the command applies refuses with a non-zero exit rather than reporting, because a caller with nobody watching cannot act on a warning.
 
-One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans-archive/` and stays gitignored, so an archived task does not start appearing in diffs. The cost is that the folder is unbacked, which is the same cost the plans archive already carries.
+One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
 
 The archive clears a row from `priority.md` and reads no other surface, which holds because a task reaches a merge by being planned and handed out, and both steps move it onto the board first. A task archived straight off the backlog therefore leaves its line standing, and the validator reports that line as naming a file that is gone rather than the board losing it silently.
 

package/tooling/claude/manifest.toml

@@ -8,4 +8,4 @@ runtime = ""
 scaffold = ""
 
 [gitignore]
-"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/plans-archive/", ".claude/review/", ".claude/review-archive/", ".claude/task-archive/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]
+"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/review/", ".claude/worktrees/", ".claude/tasks/", ".claude/teach/"]

package/tooling/claude/reference.md

@@ -9,7 +9,7 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ```plaintext
 .claude/
 ├── CLAUDE.md          ← seeded. Project context and rules, auto-loaded by Claude Code each session
-├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only
+├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
 ├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
@@ -17,9 +17,8 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── GOV.md             ← retired. Removed by `aitk gov sync` if present from a prior install
 ├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `aitk claude setup`.
-├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs.
-├── review/            ← scratch for claude-review and claude-ui-test output, gitignored
-├── review-archive/    ← memory-review receipts a triage took out of review/, gitignored
+├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs into `archive/`.
+├── review/            ← gitignored, one subfolder per producer. `branch/` for claude-review, `feedback/` for aitk feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for aitk design render.
 ├── .tmp/              ← ephemeral scratch space, gitignored
 └── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
 ```
@@ -50,7 +49,9 @@ A project installed before the diagram surface became a folder still holds `.cla
 
 ## Gitignore
 
-- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/plans-archive/`, `.claude/review/`, `.claude/review-archive/`, `.claude/task-archive/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
+- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`
+
+Each entry is a top-level record folder, and an archive sits inside the folder it archives, so one line covers a record and everything it retires.
 
 ## CLI
 

package/tooling/claude/seeds/.claude/hooks/tasks-index.sh

@@ -30,8 +30,11 @@ case "$file_path" in
 *) exit 0 ;;
 esac
 
+# The board index covers the live folder alone. A shell pattern's wildcard
+# crosses a separator, so the guard above matches an archived task as well and
+# a regen fired on one would rebuild the index the archive was taken out of.
 case "$file_path" in
-*/.claude/tasks/index.md) exit 0 ;;
+*/.claude/tasks/index.md | */.claude/tasks/archive/*) exit 0 ;;
 esac
 
 # Report a missing CLI rather than exiting quietly. The path guard above already

package/tooling/claude/seeds/CLAUDE.md

@@ -74,7 +74,7 @@
 - `.claude/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.
 - Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
 - Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- When a task needs execution detail beyond its own file, create a plan in `.claude/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.claude/plans-archive/`. Never delete it.
+- When a task needs execution detail beyond its own file, create a plan in `.claude/plans/` and link to it from the task's intro paragraph. When that task ships, move its plan file to `.claude/plans/archive/`. Never delete it.
 - Write the plan in the same session as the task file. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.
 
 ## Memory