@erclx/aitk 0.59.0 → 0.61.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.61.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/claude/skills/claude-orchestrate/SKILL.md

@@ -37,6 +37,8 @@ The roadmap is optional and this skill does not require it. It carries why a seq
 
 A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do. On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
 
+The review trigger takes the same shape. `references/orchestrator-poll.md` holds the loop prompt and the condition under which the poll runs, and `scripts/poll.sh` is what the prompt invokes. Nothing starts or stops that loop on its own, so the condition holds only while a session applies it.
+
 That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction is when a long session is likeliest to have dropped it, which is the same moment the handoff exists for. Re-invoke `/aitk:claude-orchestrate` first whenever the session has run long or the ask goes unanswered. The two runbooks sit at `references/orchestrator-handoff.md` and `references/orchestrator-resume.md` inside this skill's own folder, so a person who knows their plugin root opens either one directly and follows it without this skill loaded at all.
 
 ## Output
@@ -96,7 +98,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 3. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 4. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
 5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
-6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
+6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate. Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. It routes a moved or answered pull request straight to a re-review and reports an opened one without acting, which keeps every first pass a batched judgment this session triggers.
 7. Close the loop. After the worker runs `claude-address-review`, re-review if needed, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
 
 ## Boundaries

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -0,0 +1,44 @@
+---
+title: Orchestrator poll runbook
+description: The review trigger, the condition under which it runs, and how to read what it reports
+---
+
+Run the orchestrator's review trigger. The poll reports pull request movement and the session acts on what it reports. It reads only, and it never starts a first-pass review.
+
+`${CLAUDE_SKILL_DIR}/scripts/poll.sh` is the script. It needs `gh` authenticated against the remote and `jq` on the path, and it reads the base branch from `origin/HEAD` rather than assuming a name.
+
+## When to run it
+
+Start the poll on a dispatch and stop it when the last pull request merges with nothing else out. An open pull request or a dispatched worker is the condition, and both resolve from the board plus `gh pr list` without asking the operator. A release pull request alone does not qualify, since its sweep carries no findings.
+
+Nothing enforces this. No hook starts the poll and no check stops it, so the condition holds only while a session applies it. Left always-on it fires into an empty board through every gap between a dispatch and its push, which leaves stopping it to the operator.
+
+The poll is session-scoped and dies with the session that started it. Restart it after a compaction, and take the prompt from this file rather than from a transcript, since a running loop holds whatever wording it was started with and a correction here does not reach it.
+
+## The prompt
+
+Resolve `${CLAUDE_SKILL_DIR}/scripts/poll.sh` to an absolute path and paste that in place of `<POLL_SCRIPT>` below. The variable expands while this runbook renders and not in a `/loop` turn, which arrives as a standalone prompt, so a block carrying the variable reaches the session as a literal string and the run improvises a substitute.
+
+```plaintext
+/loop 3m Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what it reports.
+
+- MOVED or RESPONSE on a pull request I have already reviewed: run the aitk:claude-pr-review skill on it immediately, narrow pass. Re-reviews read prior..head and gain nothing from waiting.
+- OPENED, or a pull request with no prior review pass: report it and stop. First passes wait for the operator, because reading several together is what surfaces cross-PR findings.
+- SEEN: report it and stop. A pass already covers that head, whether it arrived out of band or before the poll first saw the pull request, so no review follows.
+- CONFLICT: report it and stop. The branch owner rebases, not this session.
+- GONE: report it, then sweep the board by invoking the aitk:claude-orchestrate skill and following its queue-refill sweep.
+- A line starting `poll:`: report it verbatim and treat that pull request as unread this run. It is a failed query, not a state.
+- Nothing changed: say exactly "No movement." and nothing else.
+
+Never start a first-pass review on your own.
+```
+
+## Reading the output
+
+Every classification line names a pull request and a state. A line starting `poll:` is not a classification. It means a query failed and the script declined to guess, so that pull request keeps its last known state and is neither reported as moved nor swept as merged. Treat it as unread and let the next run classify it.
+
+The script exits non-zero and classifies nothing when the open pull request list itself fails to load. That case would otherwise report every tracked pull request as merged, so the baseline is left untouched and the run says so.
+
+The baseline lives at `.claude/.tmp/pr-poll/baseline.txt` under the main worktree root and is per-machine. A first run against a board already in flight reports each open pull request once before it settles.
+
+The four review headings the script matches are written by `claude-pr-review` and `claude-address-review`. A project that posts its reviews under different headings edits the two jq filters in the script to match, or every pull request reads as never reviewed.

package/claude/skills/claude-orchestrate/scripts/poll.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# Reports pull request movement since the last run. Reads only.
+#
+# The shebang is load-bearing. An earlier version ran under the operator's zsh,
+# where an unquoted parameter expansion does not word-split, so `set -- $line`
+# left every field but the first empty and every head compared unequal. The
+# poll reported movement that had not happened, which is the one failure that
+# makes a detection tool worth less than no tool.
+set -e
+set -o pipefail
+
+# The baseline is per-machine mutable state, so it stays in gitignored scratch
+# even though the script is tracked. Resolving the main worktree root rather
+# than this file's own folder keeps a poll started from a linked worktree
+# reading the baseline a poll started from main wrote.
+MAIN_ROOT="$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')"
+if [ -z "$MAIN_ROOT" ]; then
+  echo "poll: not a git repository, so nothing is classified" >&2
+  exit 1
+fi
+STATE_DIR="$MAIN_ROOT/.claude/.tmp/pr-poll"
+mkdir -p "$STATE_DIR"
+STATE="$STATE_DIR/baseline.txt"
+touch "$STATE"
+
+# The base branch is read rather than assumed, since this ships to projects that
+# do not all call it `main`. A wrong base is not a visible failure: merge-tree
+# reports every pull request as conflicted against a ref that does not resolve.
+BASE_REF="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+if [ -z "$BASE_REF" ]; then
+  BASE_REF="origin/$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null || echo main)"
+fi
+BASE_BRANCH="${BASE_REF#origin/}"
+
+# These four strings are owned elsewhere and pinned here. `claude-pr-review`
+# writes `## Review` and `## Review closed`, and `claude-address-review` writes
+# `## Review response` and `## Rebase`. All three surfaces ship separately, so a
+# heading added in either skill breaks a test here that no check reaches across.
+#
+# Both families match on the first line alone so the two tests stay symmetric.
+# The reply family carries `## Rebase` because a run sent straight to the rebase
+# step posts under a heading deliberately kept outside the `## Review` family.
+# Widening one family without the other is what left the reply test narrow, so
+# a fifth heading is added here beside its sibling.
+JQ_LAST_REVIEWED_HEAD='
+  [ .reviews[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review" or . == "## Review closed")
+  ] | last | .commit.oid // empty
+'
+JQ_REPLY_COUNT='
+  [ .comments[]
+    | select((.body // "") | split("\n")[0] | rtrimstr("\r")
+             | . == "## Review response" or . == "## Rebase")
+  ] | length
+'
+
+# A pull request this run could not read keeps the line it had, so the GONE
+# sweep below does not read the gap as a merge and the baseline does not lose
+# the head it already knew. Saying so on stderr is the point: a silent skip is
+# how the failure this script was fixed for went unnoticed for a session.
+carry_forward() {
+  local n=$1 reason=$2 old
+  old=$(grep "^$n " "$STATE" || true)
+  if [ -n "$old" ]; then
+    echo "$old"
+    echo "poll: #$n $reason, so it keeps its last known state and goes unclassified" >&2
+  else
+    echo "poll: #$n $reason, and it has no last known state, so it goes unclassified" >&2
+  fi
+}
+
+snapshot() {
+  local numbers n payload head prior resp merges
+  git fetch -q origin "$BASE_BRANCH" 2>/dev/null || true
+
+  # A failed list reaches the caller as no open pull requests, and that reports
+  # every tracked one as GONE. It is a louder wrong answer than the one this
+  # script was fixed for, so the run aborts rather than classify on it.
+  if ! numbers=$(gh pr list --state open --json number --jq '.[].number' 2>/dev/null); then
+    echo "poll: the open pull request list could not be read" >&2
+    return 1
+  fi
+
+  for n in $numbers; do
+    # A query that failed and a pull request with genuinely no reviews both
+    # arrive as an empty result. Reading the first as the second reported a
+    # reviewed pull request as never reviewed, which routes the re-review to
+    # the first-pass branch, where it reports and stops, so the movement sits
+    # unreviewed until a person notices. One query per pull request gives that
+    # failure a single place to surface.
+    if ! payload=$(gh pr view "$n" --json headRefOid,reviews,comments 2>/dev/null); then
+      carry_forward "$n" "could not be read"
+      continue
+    fi
+
+    head=$(jq -r '.headRefOid // empty' <<<"$payload")
+    if [ -z "$head" ]; then
+      carry_forward "$n" "returned no head"
+      continue
+    fi
+
+    prior=$(jq -r "$JQ_LAST_REVIEWED_HEAD" <<<"$payload")
+    resp=$(jq -r "$JQ_REPLY_COUNT" <<<"$payload")
+
+    # `gh pr view --json mergeable` reports UNKNOWN until GitHub finishes
+    # computing it, which is exactly when a poll asks. merge-tree answers
+    # locally against the base this machine has, so it never returns UNKNOWN.
+    git fetch -q origin "pull/$n/head" 2>/dev/null || true
+    if ! git cat-file -e "${head}^{commit}" 2>/dev/null ||
+      ! git rev-parse --verify -q "$BASE_REF" >/dev/null; then
+      # merge-tree exits non-zero on a ref it cannot resolve as well as on a
+      # real conflict, and the two are indistinguishable from its status. Both
+      # sides are checked, because an unresolvable base reports every pull
+      # request as conflicted rather than one, which is the louder half.
+      merges=unknown
+    elif git merge-tree --write-tree "$BASE_REF" "$head" >/dev/null 2>&1; then
+      merges=clean
+    else
+      merges=conflict
+    fi
+
+    echo "$n $head ${prior:-none} $resp $merges"
+  done
+}
+
+# The reason is printed by whichever branch failed, since this one cannot tell
+# a list query from a parse and naming either would misattribute the other.
+if ! NEW=$(snapshot); then
+  echo "poll: nothing is classified this run and the baseline is unchanged" >&2
+  exit 1
+fi
+CHANGED=0
+
+while read -r n head prior resp merges; do
+  [ -z "$n" ] && continue
+  old=$(grep "^$n " "$STATE" || true)
+  if [ -z "$old" ]; then
+    # A pull request first seen here may already carry a pass, when it opened
+    # and was reviewed between two runs. Reporting it as new invites a first
+    # pass the thread already has.
+    if [ "$prior" = "$head" ]; then
+      echo "SEEN      #$n at ${head:0:7}, first sighting, already covered by a pass"
+    elif [ "$merges" = unknown ]; then
+      # `unknown` means no merge was attempted, so it is left off the line
+      # rather than printed where a verdict belongs.
+      echo "OPENED    #$n at ${head:0:7}"
+    else
+      echo "OPENED    #$n at ${head:0:7}, $merges against $BASE_BRANCH"
+    fi
+    CHANGED=1
+    continue
+  fi
+  old_head=$(echo "$old" | cut -d' ' -f2)
+  old_resp=$(echo "$old" | cut -d' ' -f4)
+  old_merges=$(echo "$old" | cut -d' ' -f5)
+
+  # A conflict arrives from the base moving, not from the branch, so it is
+  # reported on the transition rather than only when the head changes.
+  if [ "$merges" = conflict ] && [ "$old_merges" != conflict ]; then
+    echo "CONFLICT  #$n no longer merges into $BASE_BRANCH"
+    CHANGED=1
+  fi
+
+  if [ "$head" != "$old_head" ]; then
+    if [ "$prior" = "none" ]; then
+      echo "MOVED     #$n -> ${head:0:7}, never reviewed"
+    elif [ "$prior" = "$head" ]; then
+      # An out-of-band pass reviewed this head before the poll saw it move, so
+      # the range is empty because it is covered rather than because it broke.
+      # Without this the force-push branch below claims a rewrite that never
+      # happened, which is the class of false report the shebang note names.
+      echo "SEEN      #$n -> ${head:0:7}, already covered by the last pass"
+    else
+      # The range needs both commits local, and a force-push leaves the prior
+      # one unreachable. Count what resolves and say nothing when it does not,
+      # rather than reporting a zero that reads as no new work.
+      git fetch -q origin "pull/$n/head" 2>/dev/null || true
+      since=$(git log --oneline "${prior}..${head}" 2>/dev/null | wc -l | tr -d ' ' || true)
+      if [ -n "$since" ] && [ "$since" != "0" ]; then
+        echo "MOVED     #$n -> ${head:0:7}, $since commit(s) since your last pass"
+      else
+        echo "MOVED     #$n -> ${head:0:7}, range unresolved, likely force-pushed"
+      fi
+    fi
+    CHANGED=1
+  elif [ "$resp" -gt "$old_resp" ]; then
+    echo "RESPONSE  #$n answered with no new commit"
+    CHANGED=1
+  fi
+done <<<"$NEW"
+
+while read -r n _rest; do
+  [ -z "$n" ] && continue
+  echo "$NEW" | grep -q "^$n " || {
+    echo "GONE      #$n merged or closed"
+    CHANGED=1
+  }
+done <"$STATE"
+
+[ "$CHANGED" -eq 0 ] && echo "No movement."
+echo "$NEW" >"$STATE"

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.61.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -27,9 +27,9 @@
   },
   "scripts": {
     "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/",
-    "check:shell": "find scripts tooling .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
+    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
+    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
+    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} +",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",

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