@erclx/aitk 0.59.0 → 0.60.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-memory-capture/SKILL.md

@@ -9,6 +9,8 @@ Scan the current session for patterns worth persisting, send each to the surface
 
 A fact about a domain belongs in that domain's context entry, which the three-tier model already loads on demand. Writing it to memory instead puts it in a folder nothing opens. Routing is therefore the point of this skill and the memory file is the fallback.
 
+The filename and its type prefix, the frontmatter, the body shape each type carries, and the lifecycle are fixed by `.claude/standards/memory.md`, or `${CLAUDE_SKILL_DIR}/../../standards/memory.md` when the project does not have it. Read it before writing an entry and follow it rather than working the shape from memory.
+
 ## Guards
 
 - All `.claude/memory/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
@@ -20,7 +22,8 @@ A fact about a domain belongs in that domain's context entry, which the three-ti
 
 Read in parallel from the project root, skipping any that do not exist:
 
-- `CLAUDE.md`: Memory section rules, including save thresholds and file format overrides
+- `.claude/standards/memory.md`: the filename, frontmatter, body shape, and lifecycle every entry follows
+- `CLAUDE.md`: the project's write location and any rule it states over the folder
 - `.claude/memory/index.md`: existing index, to avoid duplicates
 - `.claude/context/index.md`: the domain catalog Step 3 routes against
 - `.claude/standards/prose.md`: voice and banned words applied to memory file bodies
@@ -30,14 +33,9 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
 
 ## Step 2: classify candidates
 
-Scan the session and group candidate patterns into four types:
-
-- **feedback**: explicit user corrections, stated preferences, or non-obvious confirmations
-- **project**: decisions, initiatives, deadlines, or motivations not derivable from git or code
-- **user**: role, expertise, responsibilities, or working preferences
-- **reference**: pointers to external systems (dashboards, trackers, channels)
+Scan the session and group candidate patterns as `feedback`, `project`, `user`, or `reference`. What each type holds and what makes one fire are the Types table in `.claude/standards/memory.md`. Read the table and classify against it rather than against a recollection of the four names.
 
-Apply the save threshold: a feedback memory only fires on explicit user correction, or on a pattern that repeated twice in the session. First-occurrence slips are noise. Project, user, and reference memories fire on first disclosure.
+Scan the whole session rather than its last exchange. A rule the user stated early and you followed since reads as settled and is exactly the one no file records.
 
 ## Step 3: route what a context entry owns
 
@@ -65,26 +63,14 @@ For each remaining candidate, grep `.claude/memory/` for an existing file on the
 
 ## Step 5: write the residue
 
-For each new memory, write to `.claude/memory/<type>-<slug>.md` with this frontmatter:
+Write each remaining candidate to `.claude/memory/<type>-<slug>.md`, following the template and the shape rules in `.claude/standards/memory.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every entry.
 
-```markdown
----
-title: <one-line human title, as it should read in the index>
-description: <one-line description per .claude/standards/prose.md § Frontmatter descriptions>
-category: <Feedback|Project|User|Reference>
----
-
-<memory body>
-```
-
-`category` is the type in sentence case, which is what the index renderer groups on, while the filename keeps the lowercase `<type>-` prefix. A description opening with a backtick or a colon needs single quotes, or the frontmatter fails to parse and the index goes stale.
-
-Feedback and project bodies must be three lines: the rule or fact on one line, a `**Why:**` line naming the session signal, and a `**How to apply:**` line for when the rule fires next. Keep each line tight. No narrative.
-
-User and reference bodies are a single sentence each.
+Two of its rules are the ones a capture pass gets wrong under time pressure. State the rule rather than the incident that produced it, since the session ending is the only reader who has the narrative. Write the `title` as the rule itself, never as the filename stem.
 
 Do not edit the index. `.claude/memory/index.md` is generated from sibling frontmatter by a `PostToolUse` hook, the same way the task board's index is, so a hand-appended row is drift the next regeneration discards.
 
+Run `aitk records validate memory` when the writes are done and fix what it names. It reads the whole pen rather than this session's writes, so treat a finding on a carried entry as one to fix in place rather than as a reason to stop.
+
 ## Output
 
 Respond with one line per fact routed, written, or updated:

package/claude/skills/claude-memory-review/SKILL.md

@@ -7,6 +7,8 @@ description: Reviews `.claude/memory/` and proposes per-entry actions (promote t
 
 This skill drives the full memory review lifecycle in five phases. Pick the phase from what the user said and whether a review receipt already exists at `<main-root>/.claude/review/memory-review-*.md`.
 
+What an entry looks like and why a retired one is moved rather than deleted are fixed by `.claude/standards/memory.md`, or `${CLAUDE_SKILL_DIR}/../../standards/memory.md` when the project does not have it. Read it before rewriting an entry, since a promotion rewrites the rule and a rewrite has to leave the entry conforming.
+
 | User intent                                                            | Phase     | Mutates                      |
 | ---------------------------------------------------------------------- | --------- | ---------------------------- |
 | "review memory", "promote memory", "sweep stale memories" (no receipt) | Propose   | review file only             |
@@ -68,7 +70,7 @@ For each in-scope entry (see Scope), pick one action:
 - **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. In the toolkit repo, point the user at `aitk-governance` and `.claude/standards/rule.md`, which own the source-of-truth rules under `governance/rules/`. In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`. Never edit the synced `.claude/rules/` copies of toolkit rules, because `aitk gov sync` overwrites them. Stop at handoff.
 - **Retire**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative. Apply moves the file to `.claude/.tmp/memory-archive/` rather than deleting it.
 
-Retire is an archive, not a deletion. `.claude/memory/` is gitignored with no history behind it, and a first pass over a folder this size is a bulk judgment with no undo. A plan and a task both archive rather than delete for the same reason, and this costs one `mv` against an unrecoverable wrong call. The archive is worth less than a plan's, since a promoted entry survives in its destination and a stale one is discarded on purpose, which is why it is cheap rather than free.
+Retire is an archive, not a deletion, which `.claude/standards/memory.md` states as the rule and this skill executes. The archive is worth less than a plan's, since a promoted entry survives in its destination and a stale one is discarded on purpose, which is why the move is cheap rather than free.
 
 When two or more memories collapse into one rule on the same target, propose them as a single merged edit under the matching promote category. The consolidate case is a variant of promote, not a separate action.
 

package/docs/agents/commands.md

@@ -28,7 +28,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
-| `aitk records validate`    | Report a plan, groundwork track, or intake dump against the standard governing it (`--json`)   |
+| `aitk records validate`    | Report a session record against the standard governing it, per kind (`--json`)                 |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git         |
 | `aitk context audit`       | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                 |

package/docs/agents/records.md

@@ -7,10 +7,11 @@ description: Validating the gitignored session records under .claude/, the per-k
 
 ## Validate
 
-`aitk records validate <kind>` reports where a session record and the standard governing it disagree. The three kinds are `plans`, `groundwork`, and `intake`, each a gitignored folder under `.claude/`.
+`aitk records validate <kind>` reports where a session record and the standard governing it disagree. The four kinds are `plans`, `groundwork`, `intake`, and `memory`, each a gitignored folder under `.claude/`.
 
 ```bash
 aitk records validate plans
+aitk records validate memory
 aitk records validate intake --json
 ```
 
@@ -30,10 +31,13 @@ Nothing fires it automatically. The folders are gitignored, so the standards-aud
 | `plans`      | A filename that is not `feature-<slug>.md`, a missing `# Feature:` heading, a missing required section, a files-to-touch entry naming no file or saying nothing about one, and a question carrying no suggestion or no answer slot    |
 | `groundwork` | A track with no `README.md` or no `01-current-state.md`, a file missing `title` or `description`, a `README.md` with no `date` as `YYYY-MM-DD`, an unnumbered file, and a track holding a decision without its handoff or the reverse |
 | `intake`     | A dump with no `00-overview.md`, the same frontmatter and numbering checks, an item missing any of `Problem`, `Fix`, `Worth it`, or `You`, and an item carrying `Open` with no `Suggested`                                            |
+| `memory`     | A filename whose prefix names none of the four types, an entry missing `title`, `description`, or `category`, a `category` disagreeing with that prefix, a title repeating the filename, and a rule-bearing body missing a part       |
 
 The half-closed track is the groundwork check a reader cannot run by eye. A folder holding `06` without `07` reads as closed to anyone scanning filenames while the file a returning session actually opens is absent.
 
-The item check skips `00-overview.md` and `99-next-session.md`, since neither holds items and running it over the handoff would report every heading it carries.
+The item check skips `00-overview.md` and `99-next-session.md`, since neither holds items and running it over the handoff would report every heading it carries. The memory walk skips `index.md` for the same reason, since the catalog is generated from its siblings rather than authored as an entry.
+
+A memory `category` is compared against the sentence-case form of the filename prefix rather than checked field by field, so one finding covers a prefix outside the four types, a field disagreeing with the prefix, and a casing drift that would open a second group in the catalog. The body check runs on `feedback` and `project` entries alone, because a `user` or `reference` entry is a single sentence by design and has no rule to apply.
 
 A plan section opens as a bold label or as an H2 and the check counts both, naming the standard's spelling when it reports one missing. The corpus splits roughly four to one between the two forms, so failing the variant would report nearly every plan on a rule that costs a reader nothing.
 
@@ -51,4 +55,4 @@ Skills branch on the findings rather than on the exit code:
 aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)"'
 ```
 
-For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, and `.claude/standards/intake.md`.
+For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, `.claude/standards/intake.md`, and `.claude/standards/memory.md`.

package/docs/ai-workflow.md

@@ -81,7 +81,7 @@ Before a handoff, the orchestrator checks the plan against the tree rather than
 
 The plan's shape is fixed by `.claude/standards/plan.md`: the section list, the filename, the lifecycle, and the contract its questions keep. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
-`aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork` and `intake`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all three folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
+`aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, and `memory`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all four folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
 A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 

package/governance/rules/claude/559-memory.md

@@ -0,0 +1,20 @@
+---
+description: Route .claude/memory/ edits to the memory standard for the filename, frontmatter, body shape, and lifecycle
+paths:
+  - '.claude/memory/**'
+---
+
+# Memory standards
+
+## Routing
+
+- Write no memory entry for a fact a per-domain context entry already owns. Memory keeps the residue, which in practice is feedback about how to work.
+
+## The pen
+
+- Never delete a memory entry. Retire one by moving it to an archive under its own name, since the folder is gitignored and a wrong call has no undo.
+- Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
+
+## Authority
+
+- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/records.ts

@@ -55,6 +55,7 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        '  memory      filename and type prefix, frontmatter, and the body shape each type carries',
         '',
         'Exit codes:',
         '  0  every check passed',
@@ -66,6 +67,7 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  aitk records validate plans',
+        '  aitk records validate memory',
         '  aitk records validate intake --json',
         '',
       ].join('\n'),

package/src/records/validate.ts

@@ -3,7 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 
-export const RECORD_KINDS = ['plans', 'groundwork', 'intake'] as const
+export const RECORD_KINDS = ['plans', 'groundwork', 'intake', 'memory'] as const
 
 export type RecordKind = (typeof RECORD_KINDS)[number]
 
@@ -11,6 +11,7 @@ const FOLDER_BY_KIND: Readonly<Record<RecordKind, string>> = {
   plans: join('.claude', 'plans'),
   groundwork: join('.claude', 'groundwork'),
   intake: join('.claude', 'intake'),
+  memory: join('.claude', 'memory'),
 }
 
 /**
@@ -26,6 +27,7 @@ export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 export const FINDING_KINDS = [
   'name-malformed',
   'title-missing',
+  'title-is-slug',
   'section-missing',
   'entry-unreasoned',
   'suggestion-missing',
@@ -36,6 +38,7 @@ export const FINDING_KINDS = [
   'state-missing',
   'closing-partial',
   'item-incomplete',
+  'category-mismatch',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -559,10 +562,175 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
+const MEMORY_INDEX = 'index.md'
+const MEMORY_FIELDS = ['title', 'description', 'category'] as const
+
+/**
+ * The filename prefix and the `category` field are one fact in two spellings,
+ * so the map is the whole type list and the comparison against it is what
+ * catches a prefix outside the set, a field disagreeing with the prefix, and a
+ * casing drift that would open a second group in the catalog.
+ */
+const CATEGORY_BY_TYPE = {
+  feedback: 'Feedback',
+  project: 'Project',
+  user: 'User',
+  reference: 'Reference',
+} as const
+
+type MemoryType = keyof typeof CATEGORY_BY_TYPE
+
+const MEMORY_TYPES = Object.keys(CATEGORY_BY_TYPE) as readonly MemoryType[]
+
+const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
+
+/** The two markers a rule-bearing body carries, on top of the rule line itself. */
+const MEMORY_MARKERS = ['**Why:**', '**How to apply:**'] as const
+
+function memoryType(value: string): MemoryType | undefined {
+  return MEMORY_TYPES.find((type) => type === value)
+}
+
+export function checkMemory(name: string, text: string): Finding[] {
+  const findings: Finding[] = []
+  const match = MEMORY_NAME.exec(name)
+  const named = match ? memoryType(match[1]) : undefined
+
+  if (!named) {
+    findings.push(
+      finding(
+        'name-malformed',
+        name,
+        name,
+        `is not named <type>-<slug>.md with a type of ${MEMORY_TYPES.join(', ')}.`,
+      ),
+    )
+  }
+
+  const frontmatter = parseFrontmatter(text)
+  const missing = MEMORY_FIELDS.filter(
+    (field) => !readField(frontmatter, field),
+  )
+
+  if (missing.length > 0) {
+    findings.push(
+      finding(
+        'frontmatter-incomplete',
+        name,
+        name,
+        `carries no ${missing.join(' and no ')}.`,
+      ),
+    )
+  }
+
+  // Its own kind rather than `title-missing`, which means an absent heading on a
+  // plan. One kind covering both leaves a caller filtering the JSON unable to
+  // tell a record with no title from one whose title is its own slug.
+  if (readField(frontmatter, 'title') === name.replace(/\.md$/, '')) {
+    findings.push(
+      finding(
+        'title-is-slug',
+        name,
+        name,
+        'is titled with its own filename, so the catalog renders a slug where the rule belongs.',
+      ),
+    )
+  }
+
+  const category = readField(frontmatter, 'category')
+
+  // Reported against the prefix alone. A name the prefix rule already failed
+  // has no type to compare against, and reporting it twice names one defect as
+  // two.
+  if (named && category && category !== CATEGORY_BY_TYPE[named]) {
+    findings.push(
+      finding(
+        'category-mismatch',
+        name,
+        category,
+        `is not ${CATEGORY_BY_TYPE[named]}, which the filename prefix declares.`,
+      ),
+    )
+  }
+
+  return [
+    ...findings,
+    ...checkMemoryBody(
+      name,
+      text.slice(frontmatter?.raw.length ?? 0),
+      named ?? category,
+    ),
+  ]
+}
+
+/**
+ * A `user` or `reference` entry is a single sentence by design, so the markers
+ * are checked only where a rule is being stated. The type is read off the
+ * prefix, falling back to the category so a misnamed file is still checked
+ * against the shape it claims.
+ */
+function checkMemoryBody(
+  name: string,
+  text: string,
+  claimed: string | undefined,
+): Finding[] {
+  const type = claimed && memoryType(claimed.toLowerCase())
+  if (type !== 'feedback' && type !== 'project') return []
+
+  const body = linesOutsideFences(text).filter((line) => line.trim().length > 0)
+
+  const findings: Finding[] = []
+  const opening = body[0]
+
+  if (!opening || MEMORY_MARKERS.some((marker) => opening.startsWith(marker))) {
+    findings.push(
+      finding(
+        'section-missing',
+        name,
+        'the rule line',
+        'is absent, so the entry carries a rationale with no rule to apply.',
+      ),
+    )
+  }
+
+  for (const marker of MEMORY_MARKERS) {
+    if (!body.some((line) => line.startsWith(marker))) {
+      findings.push(
+        finding(
+          'section-missing',
+          name,
+          marker,
+          `is required on a ${type} entry and the body carries no such line.`,
+        ),
+      )
+    }
+  }
+
+  return findings
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
 
+/** The walk for a kind whose records are files in one flat folder. */
+async function validateFiles(
+  dir: string,
+  kind: RecordKind,
+  check: (name: string, text: string) => Finding[],
+  skip: (file: string) => boolean = () => false,
+): Promise<ValidateReport> {
+  const files = (await listMarkdown(dir)).filter((file) => !skip(file))
+
+  const perFile = await Promise.all(
+    files.map(async (file) =>
+      check(file, await readFile(join(dir, file), 'utf8')),
+    ),
+  )
+
+  return { ok: true, kind, records: files.length, findings: perFile.flat() }
+}
+
 /**
  * Reports what every record in one gitignored folder claims against the shape
  * its standard fixes. It writes nothing: the folder is per-machine scratch with
@@ -578,15 +746,15 @@ export async function validateRecords(
     return refuse('no-folder', `No ${kind} folder at ${dir}.`)
   }
 
-  if (kind === 'plans') {
-    const files = await listMarkdown(dir)
-    const perFile = await Promise.all(
-      files.map(async (file) =>
-        checkPlan(file, await readFile(join(dir, file), 'utf8')),
-      ),
-    )
+  if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
 
-    return { ok: true, kind, records: files.length, findings: perFile.flat() }
+  if (kind === 'memory') {
+    return validateFiles(
+      dir,
+      kind,
+      checkMemory,
+      (file) => file === MEMORY_INDEX,
+    )
   }
 
   const folders = await listFolders(dir)

package/standards/index.md

@@ -14,6 +14,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
 - [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan run against finished text leaving through a channel no automated check covers

package/standards/memory.md

@@ -0,0 +1,131 @@
+---
+title: Memory reference
+description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+---
+
+# Memory reference
+
+Applies to a memory entry at `.claude/memory/<type>-<slug>.md`. One file holds one rule or one fact, written at the end of the session that produced it and read by a session that holds none of it. Which surface owns a given fact is settled before an entry is written at all, and that routing is project policy rather than a shape rule.
+
+The folder is gitignored and unbacked. Nothing recovers a deleted entry, which is why the retire step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a memory entry under `.claude/memory/<type>-<slug>.md`: the filename and its type prefix, the frontmatter, the body shape each type carries, links between entries, and the lifecycle from the first write to retirement.
+
+Does not govern:
+
+- The per-domain entry a domain fact is routed to instead of memory: `context.md`
+- The feature plan a session executes, and its answer contract: `plan.md`
+- The task file tracking what is being built: `tasks.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- Which facts a project captures at all, and where the folder sits, which are project policy
+
+## What a working entry looks like
+
+An entry works when a session holding none of the conversation that produced it can act on the rule from the file alone:
+
+- What is the rule or the fact, stated in one line?
+- What happened in a session to earn it, so a later reader can tell whether it still holds?
+- When does it fire next, and what does the reader do at that moment?
+- Does another surface already own this, which would make the entry a duplicate of something sessions trust more?
+
+An entry failing these is non-conforming even when it satisfies every shape rule below.
+
+## Types
+
+Four types, and the type decides both the filename prefix and the body shape.
+
+| Type        | Holds                                                                | Fires on                                    |
+| ----------- | -------------------------------------------------------------------- | ------------------------------------------- |
+| `feedback`  | a correction or a confirmed approach governing how the agent works   | explicit correction, or the same slip twice |
+| `project`   | a decision, constraint, or measured fact not derivable from the code | first disclosure                            |
+| `user`      | role, expertise, responsibilities, or working preferences            | first disclosure                            |
+| `reference` | a pointer to an external system, repository, or channel              | first disclosure                            |
+
+Hold a feedback entry to the higher bar. A first-occurrence slip is noise, and a folder that records every one of them buries the rules that were paid for.
+
+Write no entry for a fact another surface already owns. A fact about a domain belongs in that domain's entry, where sessions working the domain already read it, and the same fact in memory sits in a folder nothing opens. Memory keeps the residue, which in practice is feedback about how to work.
+
+## Filename
+
+- Name the file `<type>-<slug>.md`, with `<type>` one of the four above and `<slug>` kebab-case naming the rule rather than the incident.
+- Write one rule per file. Two rules under one slug cannot be retired or promoted separately, and one of them always outlives the other.
+- Keep the prefix and the `category` field the same fact in two spellings. A prefix outside the four types reads as a fifth type to anything grouping the folder, and it silently belongs to none.
+
+## Frontmatter
+
+Every entry carries all three fields.
+
+```yaml
+---
+title: A scope glob wide enough for a correct run can be wide enough for every wrong one
+description: Omit a declaration key whose only passing value admits the whole tree
+category: Project
+---
+```
+
+- `title` (required): the rule stated as a line a reader can act on, in sentence case.
+- `description` (required): one line naming what the entry settles, so a reader scanning the catalog decides whether to open it.
+- `category` (required): the type in sentence case, which is what groups the catalog.
+
+Never write the filename stem as the `title`. The stem is a slug, and an entry titled with it reads as an unwritten file in every catalog that renders the field.
+
+Quote a `description` opening with a backtick or a colon. An unquoted one fails to parse and takes the whole folder's catalog with it.
+
+## Body
+
+A `feedback` or `project` body carries three parts in this order. Blank lines between them are optional and the three parts are not.
+
+- The rule or the fact, stated in one or two sentences as something to do rather than something that happened.
+- A `**Why:**` line naming the session signal that earned it. This is what a later reader tests the rule against when the tree has moved.
+- A `**How to apply:**` line naming the next moment the rule fires and what to do then.
+
+A `user` or `reference` body is a single sentence and carries neither marker. There is no rule to apply and no signal to date, so the two lines would be filler.
+
+Capture the pattern rather than the recovery. What was tried, what failed, and who noticed belong to the session that is ending, and a body carrying them is a story where the next reader needs an instruction.
+
+## Links
+
+Link a related entry as `[[name]]`, where `name` is the target's filename stem without the extension. Link freely: the folder is flat and the links are the only structure it has.
+
+- Place links inside the body part they support, not in a list of their own at the end.
+- A link naming an entry nobody has written yet is legal, and it marks a rule worth writing rather than a defect.
+- A bracketed token inside a code span is not a link. Backticked syntax from another language routinely reads as one.
+
+## Lifecycle
+
+- Check the folder for an entry on the same topic before writing a new one, and update that entry in place when one exists. Two entries on one rule disagree the moment either is edited.
+- Rewrite an entry the tree has moved under rather than appending a second passage narrating the change. A reader cannot tell which of two claims is current.
+- Never delete an entry. Retire one by moving it to an archive under its own name, because the folder is unbacked and a bulk judgment has no undo behind it.
+- Treat the folder as a holding pen rather than a destination. An entry whose rule belongs on a durable surface is promoted there and retired here, and the rest is what the pen is for.
+
+The catalog is generated from sibling frontmatter rather than authored. Never hand-edit it, since the next regeneration discards whatever was added by hand.
+
+## Anti-patterns
+
+- **The domain fact filed as memory.** It reads as a capture and lands in the one folder no session opens while working that domain.
+- **The incident narrative.** A body recounting what went wrong states no rule, so the next reader has to infer one and infers a different one.
+- **The entry titled with its own slug.** Every catalog rendering the field shows a filename where the rule should be.
+- **The duplicate written beside the original.** Two entries on one topic drift, and nothing says which is current.
+- **The first-occurrence capture.** A folder recording every slip buries the rules that repeated.
+- **The entry deleted on retire.** The folder has no history, so the judgment that discarded it cannot be reviewed or reversed.
+
+## Template
+
+```markdown
+---
+title: <the rule, stated as a line a reader can act on>
+description: <one line naming what the entry settles>
+category: <Feedback|Project|User|Reference>
+---
+
+<the rule or fact, in one or two sentences, as something to do>
+
+**Why:** <the session signal that earned it, with the measurement where one exists>
+
+**How to apply:** <the next moment it fires, and what to do then> See [[related-entry]].
+```
+
+A `user` or `reference` entry carries the same frontmatter and a single sentence in place of the three parts.

package/tooling/claude/seeds/CLAUDE.md

@@ -73,11 +73,8 @@
 
 - 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/`.
+- Never delete a memory entry. Retire one by moving it to `.claude/.tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
+- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Run `aitk records validate memory` to check the pen against it.
 
 ## Scratch