@erclx/aitk 0.44.0 → 0.46.0

package/src/sync/layout.ts

@@ -0,0 +1,139 @@
+import { existsSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { SUBDIRS } from '@/claude/seeds'
+import { snippetsSourceDir } from '@/snippets/categories'
+import { standardsSourceDir } from '@/standards/adapter'
+import type { StampDomain } from '@/sync/stamp'
+
+const CLAUDE_DIR = '.claude'
+
+/**
+ * Domains an older toolkit installed at the project root, each with the source
+ * folder naming what it owns. Governance is absent because its rules have always
+ * landed under `.claude/rules/`, so there is no earlier location to be stranded
+ * at.
+ *
+ * A tuple array rather than a partial record, so the domain key stays typed
+ * without asserting an `Object.entries` result back into the union.
+ */
+const ROOT_LAYOUTS: readonly (readonly [
+  StampDomain,
+  string,
+  (root: string) => string,
+])[] = [
+  ['standards', 'standards', standardsSourceDir],
+  ['snippets', 'snippets', snippetsSourceDir],
+]
+
+/**
+ * A target file that a shipped seed folder replaced. Carries no source and
+ * queues no change, because the file holds content the project wrote and only
+ * the user can decide where it moves.
+ */
+export interface SupersededEntry {
+  readonly rel: string
+  readonly replacedBy: string
+}
+
+/**
+ * A domain whose files sit at the root layout an older toolkit installed to,
+ * with nothing at the path the current one reads. Distinct from a domain that
+ * was never installed, which has neither.
+ */
+export interface UnmigratedDomain {
+  readonly domain: StampDomain
+  readonly rootPath: string
+  readonly installPath: string
+  /** Root files the toolkit ships under this domain, not every file present. */
+  readonly files: number
+}
+
+/**
+ * Pairs each seed subdirectory against an uppercase-stem sibling in the target,
+ * so a project still holding `.claude/TASKS.md` is reported against the
+ * `.claude/tasks/` folder that replaced it.
+ *
+ * Deriving from the seed tree rather than from a fixed list means a folder
+ * added later is covered without editing this file. The cost is that only an
+ * exact stem matches, so a suffixed variant such as `TASKS-ARCHIVE.md` is not
+ * reported.
+ */
+export function collectSuperseded(target: string): SupersededEntry[] {
+  const entries: SupersededEntry[] = []
+
+  for (const subdir of SUBDIRS) {
+    const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
+    if (!isFile(join(target, rel))) continue
+
+    entries.push({ rel, replacedBy: join(CLAUDE_DIR, subdir) })
+  }
+
+  return entries
+}
+
+/**
+ * Domains the target holds at the root rather than under `.claude/`. Reported
+ * separately from the per-domain scan because that scan lists only domains it
+ * finds installed, so an unmigrated project would otherwise read as one that
+ * never installed the domain at all.
+ *
+ * A root folder is claimed only when it holds a file the toolkit ships under
+ * that domain. Presence of the folder alone is not evidence: a project can
+ * carry its own `standards/` of project docs and never have installed the
+ * domain, and calling that unmigrated would fail `--exit-code` with no action
+ * that clears it.
+ */
+export function detectUnmigrated(
+  toolkitRoot: string,
+  target: string,
+): UnmigratedDomain[] {
+  const found: UnmigratedDomain[] = []
+
+  for (const [domain, rootPath, sourceDir] of ROOT_LAYOUTS) {
+    const installPath = join(CLAUDE_DIR, rootPath)
+    if (isDirectoryWithFiles(join(target, installPath))) continue
+
+    const files = countToolkitOwned(
+      join(target, rootPath),
+      sourceDir(toolkitRoot),
+    )
+    if (files === 0) continue
+
+    found.push({ domain, rootPath, installPath, files })
+  }
+
+  return found
+}
+
+/**
+ * Root files whose basename matches something the toolkit ships for this domain.
+ * Basenames rather than relative paths, because standards install flat while
+ * snippets nest by category, and the question here is only whether any file is
+ * toolkit-owned rather than which source each one came from.
+ */
+function countToolkitOwned(dir: string, sourceDir: string): number {
+  const owned = new Set(listMarkdown(sourceDir).map((rel) => basename(rel)))
+  if (owned.size === 0) return 0
+
+  return listMarkdown(dir).filter((rel) => owned.has(basename(rel))).length
+}
+
+function isFile(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile()
+}
+
+function isDirectoryWithFiles(path: string): boolean {
+  return listMarkdown(path).length > 0
+}
+
+function listMarkdown(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({
+      cwd: dir,
+      onlyFiles: true,
+      dot: true,
+    }),
+  ]
+}

package/src/sync/seeds-report.ts

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import { planSeeds, type Seed } from '@/claude/seeds'
+import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
+
+/**
+ * How an installed seed compares to the seed the toolkit currently ships.
+ *
+ * `missing` has no counterpart in the domain scan, which walks what a target
+ * installed and so cannot see a file that never arrived. Seeds are enumerated
+ * from the source instead, which is what makes the absence legible.
+ *
+ * There is no `customized` here. That verdict needs a stamp, and seeds carry
+ * none, so a file history cannot attribute stays `drifted` and a consumer reads
+ * it as the local edit it almost always is.
+ */
+export type SeedState = 'matching' | 'stale' | 'drifted' | 'missing'
+
+export interface SeedReportEntry {
+  readonly state: SeedState
+  readonly rel: string
+  /** Toolkit revision this file's content came from, when history proved it. */
+  readonly since?: string
+}
+
+export interface SeedsReport {
+  readonly entries: readonly SeedReportEntry[]
+  /** Set when a file needed history to attribute it and this toolkit has none. */
+  readonly historyUnavailable: boolean
+}
+
+/**
+ * Classifies every seed the toolkit ships against the target's copy, and never
+ * returns a change. Seeds are copy-once files a project is expected to edit, so
+ * the engine's copy path would overwrite `CLAUDE.md` wholesale. Reporting alone
+ * is what lets `claude-seed-sync` merge one section at a time instead.
+ *
+ * Attribution reuses the history reader rather than the engine's own recovery
+ * pass, which is private and takes a `SyncAdapter` seeds have no way to supply.
+ */
+export function buildSeedsReport(
+  toolkitRoot: string,
+  target: string,
+): SeedsReport {
+  const differing: DifferingSeed[] = []
+  const entries: SeedReportEntry[] = []
+
+  for (const { seed, present } of planSeeds(toolkitRoot, target)) {
+    const rel = relative(target, seed.dest)
+
+    if (!present) {
+      entries.push({ state: 'missing', rel })
+      continue
+    }
+
+    if (sameContent(seed.src, seed.dest)) {
+      entries.push({ state: 'matching', rel })
+      continue
+    }
+
+    differing.push({ index: entries.length, seed })
+    entries.push({ state: 'drifted', rel })
+  }
+
+  const historyUnavailable = attribute(toolkitRoot, entries, differing)
+
+  return { entries, historyUnavailable }
+}
+
+interface DifferingSeed {
+  readonly index: number
+  readonly seed: Seed
+}
+
+/**
+ * Second pass over the seeds that differ, matching installed content against
+ * every version the toolkit ever published. A match proves the file is
+ * untouched since it landed, so the toolkit is what moved and the entry becomes
+ * `stale`. Runs as one git call for the whole set rather than one per file.
+ */
+function attribute(
+  toolkitRoot: string,
+  entries: SeedReportEntry[],
+  differing: readonly DifferingSeed[],
+): boolean {
+  if (differing.length === 0) return false
+
+  const index = readHistoryIndex(
+    toolkitRoot,
+    differing.map((file) => relative(toolkitRoot, file.seed.src)),
+  )
+
+  if (index === undefined) return true
+
+  for (const file of differing) {
+    const since = findInstalledOrigin(
+      index,
+      relative(toolkitRoot, file.seed.src),
+      file.seed.dest,
+    )
+
+    if (since === undefined) continue
+    entries[file.index] = { ...entries[file.index], state: 'stale', since }
+  }
+
+  return false
+}
+
+function sameContent(source: string, dest: string): boolean {
+  return readFileSync(source).equals(readFileSync(dest))
+}

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/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