@erclx/aitk 3.12.0 → 3.13.0

package/src/demo/compile.ts

@@ -5,7 +5,7 @@ import type { Beat, Draft } from '@/demo/beats'
  * separate artifacts on purpose: a beat carries no target, no wait condition,
  * and no timing, and putting those four fields on every beat would destroy the
  * property the draft was designed around. See
- * `.claude/groundwork/demo-recorder/06-decision.md`.
+ * `.claude/groundwork/38-demo-recorder/06-decision.md`.
  *
  * A compiled plan is committed rather than scratch, because the timing below is
  * a starting point the operator tunes and the draft cannot reproduce a tuned

package/src/gov/adapter.ts

@@ -1,6 +1,8 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
+import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
+import { readStamp, stampedChain } from '@/sync/stamp'
 
 const RETIRED_GOV_FILE = join('.claude', 'GOV.md')
 
@@ -54,11 +56,38 @@ export function createGovAdapter(root: string): SyncAdapter {
     locateSource: (file: InstalledFile) =>
       index.get(basename(file.path, '.md')),
     collectRetired: (target: string) => collectRetiredGov(target),
+    collectMissing: (target: string) => collectMissingGov(root, target),
     projectSubdir: 'project',
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }
 
+/**
+ * Rules the target's recorded chain entitles it to and its tree does not
+ * hold. Reports as `notice` text through the same shape `collectRetired`
+ * already returns, since both are surfaces the file walk cannot see: one an
+ * absence to remove, this one an absence to add.
+ */
+function collectMissingGov(root: string, target: string): RetiredSurface[] {
+  const chain = stampedChain(readStamp(target), 'governance')
+
+  return resolveMissingRules(root, target, chain).map((source) => {
+    const dest = join(
+      target,
+      '.claude',
+      'rules',
+      source.subdir,
+      `${source.rule}.md`,
+    )
+    const rel = relative(target, dest)
+    return {
+      path: dest,
+      rel,
+      notice: `${rel} (listed by ${chain[0]}, not installed. Run aitk gov install ${chain[0]} to add it.)`,
+    }
+  })
+}
+
 function collectRetiredGov(target: string): RetiredSurface[] {
   const path = join(target, RETIRED_GOV_FILE)
   if (!existsSync(path)) return []

package/src/gov/install.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
+import { basename, dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/copy'
 
 export interface RuleSource {
@@ -21,6 +21,27 @@ export function installedRulesDir(target: string): string {
   return join(target, '.claude', 'rules')
 }
 
+/**
+ * Rule names a target already holds, read off the installed tree by basename
+ * rather than off a recorded stack, since a target may hold rules `--add`
+ * layered on that no stack lists.
+ */
+export function installedRuleNames(target: string): Set<string> {
+  const dir = installedRulesDir(target)
+  const names = new Set<string>()
+  if (!existsSync(dir)) return names
+
+  for (const rel of new Bun.Glob('**/*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    names.add(basename(rel, '.md'))
+  }
+
+  return names
+}
+
 /**
  * Mirrors `rule_subdir` in `scripts/lib/gov.sh`, which stays in bash for the
  * sandbox loops. A rule sitting directly under `governance/rules/` has no

package/src/gov/stacks.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import {
+  installedRuleNames,
+  listRuleSourcePaths,
+  lookupRules,
+  type RuleSource,
+  rulesSourceDir,
+} from '@/gov/install'
 
 export interface GovStack {
   readonly name: string
@@ -151,6 +157,32 @@ export function unreferencedRules(root: string): string[] {
     .sort()
 }
 
+/**
+ * Rules the target's recorded chain entitles it to that its installed tree
+ * does not hold. `resolveRules` already walks a stack's `extends` ancestors,
+ * so reading its leaf entry is enough; no second walk resolves the chain
+ * itself. A stack the toolkit no longer ships resolves to nothing rather than
+ * throwing, the same way `readNewRules`'s band fallback already treats it.
+ */
+export function resolveMissingRules(
+  root: string,
+  target: string,
+  chain: readonly string[],
+): readonly RuleSource[] {
+  const stack = chain[0]
+  if (stack === undefined) return []
+
+  const resolution = resolveRules(root, stack)
+  if (!resolution.ok) return []
+
+  const { found } = lookupRules(root, resolution.rules)
+  const held = installedRuleNames(target)
+
+  return found
+    .filter((source) => !held.has(source.rule))
+    .sort((left, right) => left.rule.localeCompare(right.rule))
+}
+
 /**
  * Layers `--add` names on top of a resolved stack. The bash trimmed a single
  * leading and trailing space per entry; trimming fully is the same result for

package/src/intake/folder.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { readdir, readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import {
   INDEX_FILE,
   type IntakeItem,
@@ -13,6 +13,7 @@ import {
 export const INTAKE_REFUSALS = [
   'no-intake',
   'no-folder',
+  'ambiguous-slug',
   'no-cluster',
   'no-item',
   'answered',
@@ -110,6 +111,36 @@ async function listSlugs(dir: string): Promise<string[]> {
     .sort()
 }
 
+type SlugMatch =
+  | { readonly kind: 'matched'; readonly name: string }
+  | { readonly kind: 'ambiguous'; readonly names: readonly string[] }
+  | { readonly kind: 'none' }
+
+/**
+ * A folder carries a `<nn>-<slug>` name, but a caller names the topic alone.
+ * An exact match wins first, since it is what a name with no ordinal, or one
+ * already copied in full from a listing, resolves against. Otherwise the one
+ * entry whose name is an ordinal ahead of the given slug wins, which is what
+ * lets a topic keep working as its folder's identity gains a prefix. Two or
+ * more such entries is a collision the caller needs told apart from a typo,
+ * not a folder silently picked or silently missing.
+ */
+function matchSlug(names: readonly string[], slug: string): SlugMatch {
+  if (names.includes(slug)) return { kind: 'matched', name: slug }
+
+  const suffixed = names.filter(
+    (name) => name === `${extractOrdinal(name)}-${slug}`,
+  )
+
+  if (suffixed.length === 1) return { kind: 'matched', name: suffixed[0] }
+  if (suffixed.length > 1) return { kind: 'ambiguous', names: suffixed }
+  return { kind: 'none' }
+}
+
+function extractOrdinal(name: string): string {
+  return /^\d{2,}-/.exec(name)?.[0].slice(0, -1) ?? ''
+}
+
 async function openFolder(
   root: string,
   slug: string,
@@ -120,17 +151,22 @@ async function openFolder(
     return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
   }
 
-  const folder = join(dir, slug)
+  const names = await listSlugs(dir)
+  const match = matchSlug(names, slug)
+
+  if (match.kind === 'none') {
+    return refuse('no-folder', `No intake folder named ${slug}.`, names)
+  }
 
-  if (!existsSync(folder)) {
+  if (match.kind === 'ambiguous') {
     return refuse(
-      'no-folder',
-      `No intake folder named ${slug}.`,
-      await listSlugs(dir),
+      'ambiguous-slug',
+      `More than one intake folder matches ${slug}.`,
+      match.names,
     )
   }
 
-  return folder
+  return join(dir, match.name)
 }
 
 /** Counts per folder, which is what a session picks a folder to work from. */
@@ -180,7 +216,11 @@ export async function readFolder(
   const opened = await openFolder(root, slug)
   if (typeof opened !== 'string') return opened
 
-  return { ok: true, slug, clusters: await readClusters(opened) }
+  return {
+    ok: true,
+    slug: basename(opened),
+    clusters: await readClusters(opened),
+  }
 }
 
 /**
@@ -272,7 +312,7 @@ export async function answerItems(
 
   return {
     ok: true,
-    slug,
+    slug: basename(opened),
     cluster: name,
     path,
     answered: selections,

package/src/sync/check.ts

@@ -3,7 +3,7 @@ import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
 import { gitEnv } from '@/git-env'
 import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
-import { loadGovStack } from '@/gov/stacks'
+import { loadGovStack, resolveMissingRules, resolveRules } from '@/gov/stacks'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
@@ -19,6 +19,7 @@ import {
 } from '@/sync/reverse'
 import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
+  isLegacyStamped,
   readStamp,
   type Stamp,
   stampedChain,
@@ -71,6 +72,7 @@ export interface StateCounts {
   readonly drifted: number
   readonly orphaned: number
   readonly stranded: number
+  readonly missing: number
 }
 
 export interface DomainReport {
@@ -139,6 +141,12 @@ const UNMEASURED_TOOLING: ToolingReport = {
 
 export interface CheckReport {
   readonly covers: readonly StampDomain[]
+  /**
+   * True when the stamp `readStamp` found sits at the retired
+   * `.claude/aitk.json` path rather than the current one. Read only: nothing
+   * in the check migrates a target's config as a side effect of reporting it.
+   */
+  readonly stampAtLegacyPath: boolean
   /** False when the target is not a toolkit project, so every section stays empty. */
   readonly managed: boolean
   readonly domains: readonly DomainReport[]
@@ -204,7 +212,7 @@ export function buildToolingReport(
   target: string,
   stamp: Stamp | undefined,
 ): ToolingReport {
-  const chain = stampedChain(stamp)
+  const chain = stampedChain(stamp, 'tooling')
   const manifests = chain
     .map((name) => loadManifest(toolkitRoot, name))
     .filter((manifest) => manifest !== undefined)
@@ -270,6 +278,7 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
     drifted: count(entries, 'drifted'),
     orphaned: count(entries, 'orphaned'),
     stranded: count(entries, 'stranded'),
+    missing: count(entries, 'missing'),
   }
 }
 
@@ -293,6 +302,11 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * a file the project may own. `detectUnmigrated` already shipped that exact
  * false positive once, failing a push with no action that cleared it, and a
  * walk that reports `unattributed` by design would repeat it.
+ *
+ * `missing` is excluded on the same grounds `newRules` already reports on: a
+ * sync that adds a rule silently changes what a project is governed by, and
+ * nobody chose that, so gating CI on the count would pressure a target into
+ * adopting a rule nobody picked.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -338,6 +352,7 @@ export async function buildCheckReport(
   if (!managed) {
     return {
       covers: [],
+      stampAtLegacyPath: isLegacyStamped(target),
       managed,
       domains: [],
       tooling: UNMEASURED_TOOLING,
@@ -353,6 +368,7 @@ export async function buildCheckReport(
 
   return {
     covers: stamp?.covers ?? [],
+    stampAtLegacyPath: isLegacyStamped(target),
     managed,
     domains,
     tooling: buildToolingReport(toolkitRoot, target, stamp),
@@ -360,11 +376,7 @@ export async function buildCheckReport(
     superseded: collectSuperseded(target),
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
-    newRules: await readNewRules(
-      toolkitRoot,
-      target,
-      stampedCommit(stamp, 'governance'),
-    ),
+    newRules: await readNewRules(toolkitRoot, target, stamp),
     reverse: buildReverseReport(toolkitRoot, target),
     skew: await skewRead,
   }
@@ -529,14 +541,23 @@ export function baseBands(root: string): Set<string> {
 }
 
 /**
- * Rules are domain-scoped, so this measures from governance's own anchor rather
- * than from the oldest anchor across domains the way `readNewSkills` does. A
- * shared anchor would let a snippets sync move the revision rules are measured
- * from and drop a rule out of the read.
+ * A recorded chain answers this without the anchor at all: `resolveMissingRules`
+ * compares the entitled set against what the target holds right now, so a rule
+ * that shipped before the target's anchor is not a permanent blind spot the
+ * way the diff below leaves it. This is the primary path, and it is also what
+ * `collectMissing` reports per file through the domain scan, so a rule the
+ * chain names and the target lacks reaches both surfaces the same way.
+ *
+ * The diff-and-bands path stays as the fallback for a target stamped before
+ * governance recorded a chain. Rules are domain-scoped there too, so it
+ * measures from governance's own anchor rather than from the oldest anchor
+ * across domains the way `readNewSkills` does. A shared anchor would let a
+ * snippets sync move the revision rules are measured from and drop a rule out
+ * of the read.
  *
- * A target carrying no governance anchor reports nothing. It has no date to
- * measure against, and diffing from the beginning of history would read every
- * rule the toolkit ships as new.
+ * A target carrying no chain and no governance anchor reports nothing. It has
+ * no date to measure against, and diffing from the beginning of history would
+ * read every rule the toolkit ships as new.
  *
  * An anchor this clone cannot resolve reports nothing by a different route and
  * says so nowhere. `read` yields an empty string on a non-zero exit, so a stamp
@@ -544,12 +565,29 @@ export function baseBands(root: string): Set<string> {
  * as a target holding everything. `readNewSkills` carries the same gap, and
  * neither has the `historyUnavailable` flag the per-domain scan uses to tell an
  * unmeasured result from a clean one.
+ *
+ * A recorded chain naming a stack the toolkit no longer ships falls through to
+ * the band-based path below rather than reporting the empty list an
+ * unresolved chain would otherwise produce. That empty list reads exactly
+ * like a target holding everything, which is the same failure this function
+ * exists to close, so a retired stack name is read the same as no chain at
+ * all instead of reintroducing it.
  */
 export async function readNewRules(
   root: string,
   target: string,
-  since: string | undefined,
+  stamp: Stamp | undefined,
 ): Promise<string[]> {
+  const chain = stampedChain(stamp, 'governance')
+  const stack = chain[0]
+
+  if (stack !== undefined && resolveRules(root, stack).ok) {
+    return resolveMissingRules(root, target, chain)
+      .map((source) => source.rule)
+      .sort()
+  }
+
+  const since = stampedCommit(stamp, 'governance')
   if (since === undefined) return []
 
   const paths = await read(root, [

package/src/sync/engine.ts

@@ -61,6 +61,10 @@ export type SyncChange =
  * separate because they need opposite treatment. A project-authored file is
  * orphaned and stays that way forever. A stamped file the toolkit no longer
  * installs to is stranded, which is a relocation waiting on a decision.
+ *
+ * `missing` is the one state the walk cannot produce on its own, since the
+ * walk only iterates files that exist. It comes from `collectMissing`
+ * instead, an adapter naming an entitled file the target does not hold.
  */
 export type EntryState =
   | 'matching'
@@ -69,12 +73,19 @@ export type EntryState =
   | 'drifted'
   | 'orphaned'
   | 'stranded'
+  | 'missing'
 
 export interface ScanEntry {
   readonly state: EntryState
   readonly rel: string
   /** Toolkit revision this file's content came from, when history proved it. */
   readonly since?: string
+  /**
+   * Overrides `report`'s generic text for this entry's state. `collectMissing`
+   * is the one producer: a stack name is only known to the adapter that
+   * resolved it, and the generic `missing` line cannot carry one.
+   */
+  readonly notice?: string
 }
 
 export interface SyncPlan {
@@ -119,6 +130,12 @@ export interface SyncAdapter {
   locateSource(file: InstalledFile): string | undefined
   /** Surfaces the file walk cannot see, such as a retired doc to delete. */
   collectRetired?(target: string): RetiredSurface[]
+  /**
+   * Entitled files the walk cannot see because they do not exist yet.
+   * Reported as `missing` and queued as no change, since installing one
+   * changes what the project is governed by and stays a separate command.
+   */
+  collectMissing?(target: string): RetiredSurface[]
   /** Dropped from the walk, so neither matching nor orphaned. */
   isExcluded?(file: InstalledFile): boolean
   /**
@@ -210,6 +227,10 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
 
   entries.push(...strandedByRelocation(target, hashes, walked))
 
+  for (const surface of adapter.collectMissing?.(target) ?? []) {
+    entries.push({ state: 'missing', rel: surface.rel, notice: surface.notice })
+  }
+
   const retired = adapter.collectRetired?.(target) ?? []
   for (const surface of retired) {
     changes.push({ kind: 'delete', dest: surface.path, rel: surface.rel })
@@ -394,6 +415,10 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
       logWarn(`${entry.rel} (locally customized)`)
     else if (entry.state === 'stranded')
       logWarn(`${entry.rel} (installed here by an older toolkit, now moved)`)
+    else if (entry.state === 'missing')
+      logWarn(
+        entry.notice ?? `${entry.rel} (listed by the stack, not installed)`,
+      )
     else logWarn(`${entry.rel} (not in toolkit source, skipping)`)
   }
 

package/src/sync/stamp.ts

@@ -38,10 +38,12 @@ export interface DomainStamp {
   readonly syncedAt: string
   readonly files: DomainHashes
   /**
-   * Stack names the install resolved, nearest stack first. Present only for
-   * tooling. An ordered chain rather than the leaf name, because a stack that
-   * extends another cannot be reinstalled from its leaf alone, and a `--skip`
-   * run installs fewer layers than the leaf's own chain would reproduce.
+   * Stack names the install resolved. Tooling records the full ancestor chain,
+   * nearest stack first, because a stack that extends another cannot be
+   * reinstalled from its leaf alone, and a `--skip` run installs fewer layers
+   * than the leaf's own chain would reproduce. Governance records the single
+   * stack `aitk gov install` was given, since `resolveRules` walks its
+   * ancestors internally and a reader needs only the leaf to ask it again.
    */
   readonly chain?: readonly string[]
 }
@@ -56,6 +58,24 @@ export function stampPath(target: string): string {
   return join(target, '.claude', 'aitk', 'config.json')
 }
 
+/**
+ * Where `106115ba` moved the stamp from. No migration shipped with that move,
+ * so a target stamped before it still carries its config here, and `readStamp`
+ * falls back to this path when the current one is absent.
+ */
+export function legacyStampPath(target: string): string {
+  return join(target, '.claude', 'aitk.json')
+}
+
+/**
+ * Whether `readStamp` would resolve to the retired path, so a caller can
+ * report that a target's config still sits there. False when neither path
+ * exists, since there is nothing to migrate off of.
+ */
+export function isLegacyStamped(target: string): boolean {
+  return !existsSync(stampPath(target)) && existsSync(legacyStampPath(target))
+}
+
 export function hashContent(content: Buffer | string): string {
   return `sha256:${createHash('sha256').update(content).digest('hex')}`
 }
@@ -75,9 +95,22 @@ export function toStampKey(rel: string): string {
 /**
  * A missing or corrupt stamp reads as absent rather than failing, which is what
  * keeps every unstamped target on the existing unattributed path.
+ *
+ * Falls back to the retired path only when the current one does not exist,
+ * read only: nothing here migrates a target's config as a side effect of a
+ * report. The check is existence rather than a successful parse, so a
+ * corrupt current stamp reads as absent rather than silently serving the
+ * retired one beside it. `isLegacyStamped` tests the same existence check,
+ * which is what keeps the two agreeing on which path a corrupt current file
+ * was read from.
  */
 export function readStamp(target: string): Stamp | undefined {
-  const path = stampPath(target)
+  return existsSync(stampPath(target))
+    ? readStampFile(stampPath(target))
+    : readStampFile(legacyStampPath(target))
+}
+
+function readStampFile(path: string): Stamp | undefined {
   if (!existsSync(path)) return undefined
 
   try {
@@ -105,17 +138,22 @@ export function stampedHashes(
 }
 
 /**
- * The stack chain tooling last installed. An empty result is the state every
- * target predating the tooling record sits in, and the report reads it as
- * unmeasured rather than as clean.
+ * The stack chain a domain's install last recorded. An empty result is the
+ * state every target predating that domain's chain recording sits in, and a
+ * reader treats it as unmeasured rather than as clean.
  */
-export function stampedChain(stamp: Stamp | undefined): readonly string[] {
-  return stamp?.domains.tooling?.chain ?? []
+export function stampedChain(
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): readonly string[] {
+  return stamp?.domains[domain]?.chain ?? []
 }
 
 /**
- * Replaces one domain's record and leaves the others untouched, because domains
- * install and sync independently but share the one file.
+ * Replaces one domain's file hashes and leaves the others, including that
+ * domain's own chain, untouched. Domains install and sync independently but
+ * share the one file, and a chain an install recorded is a separate fact a
+ * later file-only sync must not erase.
  */
 export async function writeStamp(
   target: string,
@@ -127,37 +165,35 @@ export async function writeStamp(
 }
 
 /**
- * Records what tooling installed. `files` stays empty because `src/tooling/`
- * never runs the sync engine, so there is no per-file attribution to store and
- * the chain is the whole record.
+ * Records the stack chain an install resolved and leaves that domain's file
+ * hashes untouched. Tooling calls this with no files ever recorded, since
+ * `src/tooling/` never runs the sync engine and the chain is its whole record.
+ * Governance calls it alongside `writeStamp`, since it records both.
  */
 export async function writeChainStamp(
   target: string,
-  toolkitRoot: string,
+  source: StampSource,
   chain: readonly string[],
   now: Date,
 ): Promise<void> {
-  await putDomain(
-    target,
-    { domain: 'tooling', toolkitRoot },
-    { files: {}, chain: [...chain] },
-    now,
-  )
+  await putDomain(target, source, { chain: [...chain] }, now)
 }
 
 async function putDomain(
   target: string,
   source: StampSource,
-  payload: Pick<DomainStamp, 'files' | 'chain'>,
+  payload: Partial<Pick<DomainStamp, 'files' | 'chain'>>,
   now: Date,
 ): Promise<void> {
   const previous = readStamp(target)
+  const previousRecord = previous?.domains[source.domain]
   const commit = await toolkitCommit(source.toolkitRoot)
 
   const record: DomainStamp = {
     ...(commit === undefined ? {} : { commit }),
     syncedAt: now.toISOString(),
-    ...payload,
+    files: payload.files ?? previousRecord?.files ?? {},
+    ...resolveChainField(payload.chain, previousRecord?.chain),
   }
 
   const domains = sortDomains({
@@ -203,6 +239,19 @@ async function readCommit(root: string): Promise<string | undefined> {
     : undefined
 }
 
+/**
+ * A write naming no chain keeps the domain's previous one rather than dropping
+ * it, since `writeStamp` and `writeChainStamp` each touch one half of a
+ * governance record and neither should erase what the other wrote.
+ */
+function resolveChainField(
+  chain: readonly string[] | undefined,
+  previous: readonly string[] | undefined,
+): Pick<DomainStamp, 'chain'> {
+  const resolved = chain ?? previous
+  return resolved === undefined ? {} : { chain: resolved }
+}
+
 /** Deterministic key order keeps a re-sync diff empty and a merge conflict local. */
 function sortKeys(hashes: DomainHashes): DomainHashes {
   return Object.fromEntries(

package/src/tooling/stamp.ts

@@ -32,7 +32,7 @@ export async function recordToolingChain(
 
   await writeChainStamp(
     target,
-    toolkitRoot,
+    { domain: 'tooling', toolkitRoot },
     chain.map((manifest) => manifest.name),
     now,
   )

package/standards/groundwork.md

@@ -1,17 +1,17 @@
 ---
 title: Groundwork reference
-description: Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
+description: Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 ---
 
 # Groundwork reference
 
-Applies to a groundwork track at `.claude/groundwork/<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
+Applies to a groundwork track at `.claude/groundwork/<nn>-<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering inside the folder is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
 
 The folder is gitignored and unbacked. No check reaches its contents and no history recovers a deleted one, so every rule here holds only while a session reads it, and the handoff file has to be self-contained.
 
 ## Scope
 
-Governs a groundwork track under `.claude/groundwork/<slug>/`: folder layout, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
+Governs a groundwork track under `.claude/groundwork/<nn>-<slug>/`: folder layout, ordinal naming, reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps.
 
 Does not govern:
 
@@ -22,6 +22,13 @@ Does not govern:
 - Headings, punctuation, word choice, and file references: `markdown.md`
 - When a project opens a track at all, and the procedure that runs one, which belong to the surface driving it
 
+## Folder name
+
+- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
+- Take the ordinal from the highest one already present across both `.claude/groundwork/` and `.claude/intake/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
+- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
 ## What a working track looks like
 
 A track works when a session that has never seen it re-enters from the folder alone and can answer each of these: