@erclx/aitk 0.43.0 → 0.45.0

package/src/tasks/validate.ts

@@ -0,0 +1,401 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { RESERVED_STEMS, tasksDir } from '@/tasks/archive'
+
+const ORDERING_FILE = 'priority.md'
+
+/**
+ * The readiness headings `.claude/standards/tasks.md` fixes. The names are the
+ * contract rather than a suggestion, so a board grouping under names of its own
+ * reads as carrying no group at all and the run refuses instead of reporting a
+ * clean board it never parsed.
+ */
+export const BOARD_GROUPS = ['Run now', 'Up next', 'Needs a plan'] as const
+
+export type BoardGroup = (typeof BOARD_GROUPS)[number]
+
+export const VALIDATE_REFUSALS = [
+  'no-board',
+  'no-ordering',
+  'no-groups',
+] as const
+
+export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
+
+export const FINDING_KINDS = [
+  'plan-unstated',
+  'plan-unresolved',
+  'task-unresolved',
+  'row-missing',
+  'row-duplicated',
+  'touches-unstated',
+  'touches-collided',
+] as const
+
+export type FindingKind = (typeof FINDING_KINDS)[number]
+
+export interface Finding {
+  readonly kind: FindingKind
+  readonly group: BoardGroup | undefined
+  readonly subject: string
+  readonly message: string
+}
+
+export interface BoardRow {
+  readonly group: BoardGroup
+  readonly label: string
+  readonly stem: string | undefined
+  readonly plan: string | undefined
+  /** Absent when the group fixes no `Touches` column, empty when it read none. */
+  readonly touches: readonly string[] | undefined
+}
+
+export interface ValidateReport {
+  readonly ok: true
+  readonly rows: number
+  readonly tasks: number
+  readonly findings: readonly Finding[]
+}
+
+export interface ValidateRefused {
+  readonly ok: false
+  readonly reason: ValidateRefusal
+  readonly message: string
+}
+
+export type ValidateOutcome = ValidateReport | ValidateRefused
+
+export function orderingPath(root: string): string {
+  return join(tasksDir(root), ORDERING_FILE)
+}
+
+/**
+ * Pulls the target out of a markdown link, which is how both the `Task` and the
+ * `Plan` column spell their pointer. A cell carrying prose instead of a link
+ * yields nothing, and that absence is the finding rather than a parse failure.
+ */
+function linkTarget(cell: string): string | undefined {
+  const match = /\[[^\]]*\]\(([^)]+)\)/.exec(cell)
+  return match ? match[1].trim() : undefined
+}
+
+function linkText(cell: string): string {
+  const match = /\[([^\]]*)\]\([^)]+\)/.exec(cell)
+  return (match ? match[1] : cell).trim()
+}
+
+function stemOf(target: string): string | undefined {
+  const name = target.split('/').pop()
+  if (!name || !name.endsWith('.md')) return undefined
+  return name.slice(0, -'.md'.length)
+}
+
+/**
+ * Reads the file set out of a `Touches` cell written as prose. Paths are the
+ * backticked spans, which is the only marker the column carries, and a span
+ * naming a skill or a command rather than a file is dropped by the same test.
+ *
+ * An extension opens with a letter, which is what separates `commands.md` from
+ * a task version like `v40.2`. Reading the version as a path would collide two
+ * rows that merely cite the same task.
+ */
+export function readPaths(cell: string): string[] {
+  const spans = cell.match(/`[^`]+`/g) ?? []
+  const paths = spans
+    .map((span) => span.slice(1, -1).trim())
+    .filter(
+      (span) => span.includes('/') || /\.[A-Za-z][A-Za-z0-9]*$/.test(span),
+    )
+    .map((span) => span.replace(/^\.\//, '').replace(/\/+$/, ''))
+
+  return [...new Set(paths)]
+}
+
+/**
+ * Two paths touch the same work when they are equal or one contains the other.
+ * A row naming a directory and a row naming a file inside it collide, which a
+ * set intersection on the written strings alone would miss.
+ */
+function sharesPath(left: string, right: string): boolean {
+  return (
+    left === right ||
+    left.startsWith(`${right}/`) ||
+    right.startsWith(`${left}/`)
+  )
+}
+
+function splitCells(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map((cell) => cell.trim())
+}
+
+function isSeparator(cells: readonly string[]): boolean {
+  return cells.every((cell) => /^:?-{3,}:?$/.test(cell))
+}
+
+function columnIndex(header: readonly string[], name: string): number {
+  return header.findIndex((cell) => cell.toLowerCase() === name)
+}
+
+function isGroup(heading: string): heading is BoardGroup {
+  return (BOARD_GROUPS as readonly string[]).includes(heading)
+}
+
+/**
+ * Parses the ordering file into rows keyed by readiness group. Columns are read
+ * from each table's own header rather than by position, so a group whose shape
+ * differs from this repository's is reported for what it lacks instead of
+ * having its second cell read as something it never was.
+ */
+export function readBoard(text: string): {
+  readonly rows: readonly BoardRow[]
+  readonly groups: readonly BoardGroup[]
+} {
+  const rows: BoardRow[] = []
+  const groups: BoardGroup[] = []
+
+  let group: BoardGroup | undefined
+  let header: string[] | undefined
+
+  for (const line of text.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line)
+    if (heading) {
+      const title = heading[1]
+      group = isGroup(title) ? title : undefined
+      header = undefined
+      if (group && !groups.includes(group)) groups.push(group)
+      continue
+    }
+
+    if (!group || !line.trimStart().startsWith('|')) continue
+
+    const cells = splitCells(line)
+    if (isSeparator(cells)) continue
+
+    if (!header) {
+      header = cells
+      continue
+    }
+
+    const taskAt = columnIndex(header, 'task')
+    const planAt = columnIndex(header, 'plan')
+    const touchesAt = columnIndex(header, 'touches')
+
+    const task = taskAt >= 0 ? (cells[taskAt] ?? '') : ''
+    const target = linkTarget(task)
+    const plan = planAt >= 0 ? linkTarget(cells[planAt] ?? '') : undefined
+
+    rows.push({
+      group,
+      label: linkText(task) || task,
+      stem: target ? stemOf(target) : undefined,
+      plan,
+      touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
+    })
+  }
+
+  return { rows, groups }
+}
+
+async function listTaskStems(dir: string): Promise<string[]> {
+  const entries = await readdir(dir)
+  const reserved: readonly string[] = RESERVED_STEMS
+
+  return entries
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => entry.slice(0, -'.md'.length))
+    .filter((stem) => !reserved.includes(stem))
+    .sort()
+}
+
+/**
+ * Resolves a pointer against the board and against the project root both, the
+ * way `claude-docs` reads the same line. A fragment is dropped first, since an
+ * anchor is part of the link and never part of the path.
+ */
+function resolves(target: string, dir: string, root: string): boolean {
+  const path = target.split('#')[0]
+  if (!path) return false
+
+  return existsSync(resolve(dir, path)) || existsSync(resolve(root, path))
+}
+
+function checkMapping(
+  rows: readonly BoardRow[],
+  stems: readonly string[],
+  dir: string,
+): Finding[] {
+  const findings: Finding[] = []
+  const seen = new Map<string, number>()
+
+  for (const row of rows) {
+    if (!row.stem) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: row.group,
+        subject: row.label,
+        message: 'names no task file, so the row points at nothing.',
+      })
+      continue
+    }
+
+    seen.set(row.stem, (seen.get(row.stem) ?? 0) + 1)
+
+    if (!existsSync(join(dir, `${row.stem}.md`))) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: row.group,
+        subject: row.stem,
+        message: 'has a row and no task file.',
+      })
+    }
+  }
+
+  for (const [stem, count] of seen) {
+    if (count > 1) {
+      findings.push({
+        kind: 'row-duplicated',
+        group: undefined,
+        subject: stem,
+        message: `carries ${count} rows. A task belongs to exactly one group.`,
+      })
+    }
+  }
+
+  for (const stem of stems) {
+    if (!seen.has(stem)) {
+      findings.push({
+        kind: 'row-missing',
+        group: undefined,
+        subject: stem,
+        message: 'is a task file with no row on the board.',
+      })
+    }
+  }
+
+  return findings
+}
+
+function checkPlans(
+  rows: readonly BoardRow[],
+  dir: string,
+  root: string,
+): Finding[] {
+  const findings: Finding[] = []
+
+  for (const row of rows) {
+    if (row.group !== 'Run now') continue
+
+    if (!row.plan) {
+      findings.push({
+        kind: 'plan-unstated',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message:
+          'states no plan pointer, so the readiness claim cannot be checked.',
+      })
+      continue
+    }
+
+    if (!resolves(row.plan, dir, root)) {
+      findings.push({
+        kind: 'plan-unresolved',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message: `points at ${row.plan}, which resolves to no file.`,
+      })
+    }
+  }
+
+  return findings
+}
+
+/**
+ * The half of the `## Run now` test a person cannot check by eye. Two rows a
+ * worker may be handed at once must touch disjoint files, and the `Touches`
+ * column is the only place either set is written down.
+ */
+function checkCollisions(rows: readonly BoardRow[]): Finding[] {
+  const findings: Finding[] = []
+  const ready = rows.filter((row) => row.group === 'Run now')
+
+  for (const row of ready) {
+    // An absent column and an unreadable one both leave the row untested by
+    // the loop below, so reporting only the second would pass a board whose
+    // `## Run now` table declares no file set at all.
+    if (!row.touches || row.touches.length === 0) {
+      findings.push({
+        kind: 'touches-unstated',
+        group: row.group,
+        subject: row.stem ?? row.label,
+        message: 'names no file, so its collisions cannot be read.',
+      })
+    }
+  }
+
+  for (let i = 0; i < ready.length; i += 1) {
+    for (let j = i + 1; j < ready.length; j += 1) {
+      const left = ready[i]
+      const right = ready[j]
+      const shared = (left.touches ?? []).filter((path) =>
+        (right.touches ?? []).some((other) => sharesPath(path, other)),
+      )
+
+      if (shared.length === 0) continue
+
+      findings.push({
+        kind: 'touches-collided',
+        group: 'Run now',
+        subject: `${left.stem ?? left.label} and ${right.stem ?? right.label}`,
+        message: `both touch ${shared.join(', ')}.`,
+      })
+    }
+  }
+
+  return findings
+}
+
+function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
+  return { ok: false, reason, message }
+}
+
+/**
+ * Reports what every board row claims against what the tree holds. It writes
+ * nothing: a row is a session's claim about readiness, and a validator that
+ * repaired one would be asserting the claim it exists to test.
+ */
+export async function validateBoard(root: string): Promise<ValidateOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${dir}.`)
+  }
+
+  const ordering = orderingPath(root)
+  if (!existsSync(ordering)) {
+    return refuse('no-ordering', `No ordering file at ${ordering}.`)
+  }
+
+  const { rows, groups } = readBoard(await readFile(ordering, 'utf8'))
+
+  if (groups.length === 0) {
+    return refuse(
+      'no-groups',
+      `No readiness group in ${ORDERING_FILE}. Expected one of: ${BOARD_GROUPS.join(', ')}.`,
+    )
+  }
+
+  const stems = await listTaskStems(dir)
+
+  const findings = [
+    ...checkMapping(rows, stems, dir),
+    ...checkPlans(rows, dir, root),
+    ...checkCollisions(rows),
+  ]
+
+  return { ok: true, rows: rows.length, tasks: stems.length, findings }
+}

package/src/ui.ts

@@ -59,6 +59,11 @@ export function pipeOutput(text: string): void {
   )
 }
 
+/** Counts a noun for a report line, where the plural is the bare `s` form. */
+export function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
 export function frameError(message: string): void {
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,

package/standards/tasks.md

@@ -26,12 +26,15 @@ Does not govern:
 .claude/tasks/
 ├── index.md              ← generated, never hand-edited
 ├── priority.md           ← hand-maintained execution order
+├── session.md            ← optional, what a compaction is about to destroy
 ├── v09.0-sync-paths.md
 └── v13.0-toolkit-drift.md
 ```
 
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
+Three siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md` and `priority.md` are governed here. `session.md` is the pre-compaction handoff, written by `orchestrator-handoff` and read by `orchestrator-resume`, and it is optional: a project running no orchestrator carries no such file. Anything reading the folder as a task list skips all three, so a name outside the set is a task whatever it holds.
+
 `index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
 
 The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
@@ -50,6 +53,8 @@ Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and
 
 Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task. The blocker column under `## Up next` names whether a collision or a dependency holds the row. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
 
+`aitk tasks validate` reads those columns and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a row and a task file that do not map one to one, a task in two groups, and two `## Run now` rows touching a path in common. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+
 ```markdown
 ---
 title: Priority

package/tooling/claude/reference.md

@@ -20,7 +20,7 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ├── 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
 ├── .tmp/              ← ephemeral scratch space, gitignored
-└── memory/            ← session memory files, gitignored
+└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
 ```
 
 ## Upgrading from a single-file board
@@ -33,6 +33,16 @@ Convert by hand, once per project:
 2. Run `aitk indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
 
+## Upgrading a hand-appended memory index
+
+A project installed before the memory folder gained a generated index still holds `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
+
+Convert by hand, once per project:
+
+1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
+2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
+3. Run `aitk indexes regen --no-stage --root . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
+
 ## Upgrading from a single-file diagram set
 
 A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+# Regenerates .claude/memory/index.md after a memory file changes.
+#
+# The memory folder is gitignored, so the whole-repo walk in `bun run check`
+# drops it and never regenerates this index. A positional path bypasses that
+# filter, which makes this hook the only trigger that reaches the folder.
+
+input=$(cat)
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit | MultiEdit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/memory/*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file_path" in
+*/.claude/memory/index.md) exit 0 ;;
+esac
+
+# Report a missing CLI rather than exiting quietly. The path guard above already
+# scopes this to a memory-file edit, so the message only fires where the stale
+# index it warns about is the actual outcome.
+if ! command -v aitk >/dev/null 2>&1; then
+  jq -nc --arg msg 'aitk is not on PATH, so .claude/memory/index.md was not regenerated and is now stale. Install the toolkit CLI or run aitk indexes regen by hand.' \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+  exit 0
+fi
+
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+root="${file_path%/.claude/memory/*}"
+[ -n "$root" ] || exit 0
+
+# `--no-stage` because a hook has no business touching the index. On a project
+# whose memory folder is not gitignored, the default auto-stage would silently
+# add memory files to whatever commit is being assembled.
+output=$(aitk indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
+
+# Regen failed, which on this folder means a memory file is missing `title` or
+# `description`. Report it. Nothing else can: the folder is gitignored, so the
+# whole-repo walk never reaches it and no gate stage will ever fail on a stale
+# index. Staying quiet here is what makes the drift permanent.
+errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
+[ -n "$errors" ] || errors="$output"
+
+msg="Memory index regen failed, so .claude/memory/index.md is now stale. Fix the frontmatter and save again. $errors"
+jq -nc --arg msg "$msg" \
+  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+exit 0

package/tooling/claude/seeds/.claude/memory/index.md

@@ -0,0 +1,8 @@
+---
+title: Memory
+subtitle: Session facts with no owning surface, grouped by kind. Feedback is the working set.
+---
+
+# Memory
+
+Session facts with no owning surface, grouped by kind. Feedback is the working set.

package/tooling/claude/seeds/.claude/settings.json

@@ -31,6 +31,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tasks-index.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-index.sh"
           }
         ]
       }

package/tooling/claude/seeds/CLAUDE.md

@@ -72,9 +72,12 @@
 ## Memory
 
 - Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
+- A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `claude-memory-capture` routes it there and `claude-docs` folds it in. Memory keeps only what no context entry owns.
 - Save a feedback memory only when the same mistake happens twice in the session, or when the user explicitly corrects you. First-occurrence slips are noise.
 - Keep feedback memories to 3 lines: the rule, a one-line Why, and a one-line How to apply. Capture the pattern, not the recovery narrative.
 - Before creating a new memory file, check for an existing one on the same topic. Update rather than duplicate.
+- Give every entry `title`, `description`, and a sentence-case `category`. Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
+- Never delete a memory entry. `claude-memory-review` moves a retired one to `.claude/.tmp/memory-archive/`.
 
 ## Scratch