@erclx/aitk 0.44.0 → 0.45.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.44.0",
+  "version": "0.45.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-autoship/SKILL.md

@@ -101,12 +101,15 @@ Do not auto-fix findings. The stop here is deliberate.
 
 Invoke each sub-skill in order via the Skill tool. After each returns, invoke the next immediately. Do not output text between steps.
 
-1. `aitk:claude-docs`: sync `.claude/` planning docs against session decisions
-2. `aitk:docs-sync`: sync public docs against changes since main
-3. Run `git add -A` to stage files the sync skills wrote
-4. `aitk:git-stage`: group staged changes and commit by concern
-5. `aitk:git-branch`: rename the branch to conventional format
-6. `aitk:git-pr`: push and open the pull request
+1. `aitk:claude-memory-capture`: route what this session learned to the context entries that own it, and write the residue to `.claude/memory/`
+2. `aitk:claude-docs`: sync `.claude/` planning docs against session decisions, folding in the routed facts
+3. `aitk:docs-sync`: sync public docs against changes since main
+4. Run `git add -A` to stage files the sync skills wrote
+5. `aitk:git-stage`: group staged changes and commit by concern
+6. `aitk:git-branch`: rename the branch to conventional format
+7. `aitk:git-pr`: push and open the pull request
+
+Capture runs first because a routed fact lands in a context entry, which is a tracked file. Running it after `git-pr`, where it used to sit, leaves that edit outside the branch and outside the pull request, so the fact reaches nothing. Memory files stay gitignored either way, which is why the old order was invisible.
 
 After the PR is created, mark it as draft:
 
@@ -116,23 +119,25 @@ gh pr ready --undo
 
 After marking draft, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop and report the failing check with its URL. Do not auto-fix.
 
-7. `aitk:claude-memory-capture`: extract durable patterns from the session into `.claude/memory/`
-8. `aitk:claude-memory-review`: if `claude-memory-capture` wrote or updated at least one entry this session, propose fixes scoped to those entries, writing the decision-ready receipt while session context is fresh. Skip when capture wrote nothing.
+8. `aitk:claude-memory-review`: if step 1's capture wrote or updated at least one memory file, propose fixes scoped to those entries, writing the decision-ready receipt while session context is fresh. Skip when capture wrote nothing to the folder, which is the ordinary outcome once routing has taken the domain facts.
+
+Review stays last because its receipt is gitignored and needs nothing from the commit, and because a proposal is worth more once CI has said whether the branch stands.
 
 Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body mutates how the agent operates and ships as its own change, separate from this feature.
 
 ## Output
 
-Respond with up to four lines:
+Respond with up to five lines:
 
 ```plaintext
 ✅ Autoshipped (draft): <PR url>
 <N minor findings kept in .claude/review/review-<slug>.md>
+<N facts routed to context entries>
 <N memories captured in .claude/memory/>
 <Memory proposal at .claude/review/memory-review-<slug>.md>
 ```
 
-Omit the second line if there were no minor findings. Omit the third and fourth lines if `claude-memory-capture` wrote nothing this session, since no captures means no scoped review and no proposal.
+Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
 
 ## Failure recovery
 

package/claude/skills/claude-docs/SKILL.md

@@ -77,7 +77,7 @@ Then run Steps 4 through 8. Step 3 is the only one this skips, because it is the
 Three of the steps that follow write, so each earns the reach separately:
 
 - Steps 4 and 5 stub against the diff. These are why the skip is not a stop. A session that changed no docs is exactly when an uncovered surface or diagram kind goes unnoticed.
-- Step 7 rewrites context entries against the diff. The Diff baseline section above already groups it with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it.
+- Step 7 rewrites context entries against the diff and against the facts `claude-memory-capture` routed. The Diff baseline section above groups its diff half with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it. The routed half reads a named file and runs whatever the diff shows.
 - Step 8 reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
 
 This changes which steps the skill reaches. It does not widen what any of them reads. Steps 4, 5, and 7 still take the same scoped set the Diff baseline section defines, and that section's rule is about the input a write is handed rather than about which writes run.
@@ -201,7 +201,17 @@ Do not edit `CLAUDE.md` inline. Every `CLAUDE.md` change goes through the show-d
 
 ## Step 7: refresh context entries
 
-Read `.claude/context/index.md` at `pwd` to see which domain entries exist. Skip this step silently if the directory does not exist or has no entries. When the baseline is unusable, scope it to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.`
+Read `.claude/context/index.md` at `pwd` to see which domain entries exist. Skip this step silently if the directory does not exist or has no entries.
+
+Two sources feed this step, the same split Step 2 runs on. The diff carries what the repository changed. The routed facts carry what the session learned, which a diff cannot show.
+
+**Routed facts.** Derive `<slug>` per `.claude/standards/slug.md`, falling back to `latest` on an empty result, and read `.claude/.tmp/memory-routing/<slug>.md` at the main worktree root. `claude-memory-capture` writes it, one H2 per target entry naming the path, with the fact underneath. Fold each fact into the entry its heading names, then delete the handoff file so a later run does not fold it twice.
+
+This half is not diff-scoped and must not be. A gotcha a session hit while working is exactly the fact the diff never shows, and scoping it to changed files would drop the entries worth keeping. The handoff is a named input rather than a scan, so the reach stays bounded to what capture decided.
+
+Skip this half silently when the file is absent, which is every run where nothing routed.
+
+**The diff.** When the baseline is unusable, scope this half to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.` The routed half still runs, since it reads a file rather than a diff.
 
 Reuse the diff from the baseline above, names and content both. For each existing `.claude/context/<domain>.md`:
 
@@ -214,6 +224,10 @@ Write each updated entry immediately. Output one line per file:
 
 `✅ Context: .claude/context/<domain>.md`
 
+Add a line naming the handoff when one was consumed:
+
+`🧹 Folded: .claude/.tmp/memory-routing/<slug>.md`
+
 The base lint-staged config runs `aitk indexes regen` on every committed `*.md`, so `.claude/context/index.md` refreshes automatically on commit. No manual step needed.
 
 ## Step 8: sweep consumed scratch

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

@@ -1,6 +1,6 @@
 ---
 name: claude-memory-capture
-description: What earns a memory file at the end of a session, the threshold that keeps the folder signal-bearing, and why capture never curates
+description: Which surface a session fact is owed to, what earns a memory file once routing has run, and why capture never edits a context entry itself
 ---
 
 # Claude memory capture requirement
@@ -9,20 +9,28 @@ description: What earns a memory file at the end of a session, the threshold tha
 
 Without this skill, what a session learned dies with it, and the correction the user made in message four is re-earned next week. What does get written is a narrative of how the session went wrong rather than a rule that fires again, so a reader gets a story and no instruction. A new file lands beside one already holding the same topic, and the folder grows two entries per subject until nothing in it can be trusted as current.
 
-The threshold is what the folder lives or dies on. A first-occurrence slip saved as feedback is noise that costs every later session a read, and a fact the repository already records is worse, because it duplicates a source that will be updated without it. From a linked worktree, writes resolved against `pwd` land in a second memory folder nothing else reads.
+Writing every fact to one folder is the deeper gap, because the folder has no reader. A fact about a domain has an owning surface already, the context entry the three-tier model loads on demand, and filing it in memory instead puts it where only a deliberate sweep will ever find it. The measured outcome is a store that grows on every ship and is drained by nothing.
+
+The threshold is what the remaining folder lives or dies on. A first-occurrence slip saved as feedback is noise that costs every later session a read, and a fact the repository already records is worse, because it duplicates a source that will be updated without it. From a linked worktree, writes resolved against `pwd` land in a second memory folder nothing else reads.
 
 ## Must
 
 - Resolve every read and write at the main worktree root, so parallel worktrees write one folder
-- Classify each candidate as feedback, project, user, or reference before writing
+- Classify each candidate as feedback, project, user, or reference before routing or writing
+- Route a project candidate whose subject names an entry in `.claude/context/index.md` to that entry, and hand it off as a file rather than an edit
+- Keep a candidate that matches no entry, or two entries with no clear owner, as a memory file
 - Apply the save threshold, firing feedback only on an explicit correction or a pattern that repeated twice
 - Grep the folder for an existing file on the topic and update it in place rather than adding a second
 - Keep a feedback or project body to the rule, one line of why, and one line of when it fires next
-- Append the row to the index so the entry is discoverable
+- Write frontmatter the index renderer can read, so the generated catalog stays current
 - Report that nothing was worth capturing rather than manufacturing an entry to show work
 
 ## Must not
 
+- Edit a context entry, which `claude-docs` owns
+- Route a feedback, user, or reference candidate, since no context entry owns how to work or who to ask
+- Route anything when the caller does not commit, because a context entry is a tracked file
+- Hand-append a row to the memory index, which is generated from sibling frontmatter
 - Write a session narrative or a recovery account in place of the pattern
 - Save a first-occurrence slip as feedback
 - Create a second file on a topic the folder already holds
@@ -33,8 +41,10 @@ The threshold is what the folder lives or dies on. A first-occurrence slip saved
 
 - No correction, confirmation, or context disclosure worth persisting: stop with a pass
 - Memory folder absent at the main root: create it rather than stopping
+- Session in the main worktree, or a caller that does not commit: skip routing and write every candidate as a memory file
 
 ## Out of scope
 
+- Editing the context entries themselves, which `claude-docs` owns on its own pass
 - Curating what is already in the folder, which `claude-memory-review` owns
 - Promoting an entry into an instruction file or a skill body, which mutates how the agent operates and ships as its own change

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

@@ -1,24 +1,28 @@
 ---
 name: claude-memory-capture
-description: Extracts durable patterns from the current session and writes them to `.claude/memory/` as feedback, project, user, or reference memory files. Use when asked to "capture memory", "capture lessons", "wrap up the session", "end of session memory", or as the final step in autoship. Do NOT use to curate existing memory. Use `claude-memory-review` for that.
+description: Extracts durable patterns from the current session, routes a domain fact to the context entry that owns it, and writes the residue to `.claude/memory/` as feedback, project, user, or reference files. Use when asked to "capture memory", "capture lessons", "wrap up the session", "end of session memory", or as a step in autoship. Do NOT use to curate existing memory. Use `claude-memory-review` for that.
 ---
 
 # Claude memory capture
 
-Scan the current session for patterns worth persisting, write them as memory files, and update the index. Pair with `claude-memory-review` for later curation.
+Scan the current session for patterns worth persisting, send each to the surface that owns it, and leave in `.claude/memory/` only what no surface owns. Pair with `claude-memory-review` for later curation.
+
+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.
 
 ## Guards
 
 - All `.claude/memory/` reads and writes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
-- If `.claude/memory/` does not exist at the main worktree root, create it.
+- If `.claude/memory/` does not exist at the main worktree root, create it, along with an `index.md` carrying `title` and `subtitle` frontmatter. `aitk claude init` seeds both, and a project predating that seed has neither. Regeneration errors without the index, so the first write into a bare folder would report a frontmatter failure against a file that is fine.
 - If the session produced no user corrections, confirmations, or context disclosures worth persisting, stop: `✅ Nothing worth capturing.`
+- Routing edits a tracked file, so it runs only where the caller commits. When the session is in the main worktree, or the caller states it does not commit, skip Step 3 and write every candidate as a memory file. `claude-orchestrate` is the caller this covers.
 
 ## Step 1: read context
 
 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/memory/MEMORY.md`: existing index, to avoid duplicates
+- `.claude/memory/index.md`: existing index, to avoid duplicates
+- `.claude/context/index.md`: the domain catalog Step 3 routes against
 - `.claude/standards/prose.md`: prose conventions applied to memory file bodies
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
@@ -34,42 +38,67 @@ Scan the session and group candidate patterns into four types:
 
 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.
 
-## Step 3: dedupe
+## Step 3: route what a context entry owns
+
+Only a **project** candidate is routable. Feedback, user, and reference describe how to work or who to ask rather than how a domain behaves, and no context entry owns them.
+
+For each project candidate, match its subject against `.claude/context/index.md`. The test is a named entry, not a judgment about fit: the fact names a surface that already has an entry in the catalog. Route it to that entry.
+
+Fail closed. A project candidate matching no entry stays a memory file, and so does one matching two entries where neither is clearly the owner. The residue is what the folder is for, and a fact filed under the wrong entry is worse than one in memory because a context entry is a surface sessions trust.
+
+Do not edit a context entry here. `claude-docs` owns those edits and folds the routed facts in on its own pass, or two skills write one file at the same step. Write each routed fact to `.claude/.tmp/memory-routing/<slug>.md` at the main worktree root instead, appending when the file exists:
+
+```markdown
+## .claude/context/<domain>.md
+
+<the fact in one or two sentences, stated as a fact about the domain rather than as a session narrative>
+```
+
+Derive `<slug>` per `.claude/standards/slug.md`, or `${CLAUDE_SKILL_DIR}/../../standards/slug.md` when the project does not have it. Fall back to `latest` on an empty result.
 
-For each candidate, grep `.claude/memory/` for an existing file on the same topic. If one exists, update it in place rather than create a new file.
+The handoff is a file rather than a spoken result so the routed fact survives a compaction between this step and the `claude-docs` pass, and so the standalone caller leaves something behind for a later `/claude-docs` to consume.
 
-## Step 4: write
+## Step 4: dedupe
+
+For each remaining candidate, grep `.claude/memory/` for an existing file on the same topic. If one exists, update it in place rather than create a new file.
+
+## Step 5: write the residue
 
 For each new memory, write to `.claude/memory/<type>-<slug>.md` with this frontmatter:
 
 ```markdown
 ---
-name: <memory name>
+title: <one-line human title, as it should read in the index>
 description: <one-line description per .claude/standards/prose.md § Frontmatter descriptions>
-type: <feedback|project|user|reference>
+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.
 
-Then append a row to the matching table in `.claude/memory/MEMORY.md`:
-
-```markdown
-| <name> | <file> | <description> |
-```
+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.
 
 ## Output
 
-Respond with one line per memory written or updated:
+Respond with one line per fact routed, written, or updated:
 
+- `➡️ Routed: <fact subject> → .claude/context/<domain>.md`
 - `✅ Wrote: .claude/memory/<file> (<type>)`
 - `✏️ Updated: .claude/memory/<file> (<type>)`
 
-When at least one entry was written or updated, add a closing line so the standalone caller proposes fixes while context is fresh:
+When anything routed, add a line naming the handoff so the caller knows a `claude-docs` pass is owed:
+
+`→ Routed facts wait at .claude/.tmp/memory-routing/<slug>.md. Run /claude-docs to fold them in.`
+
+Omit that line when the caller runs `claude-docs` itself later in its own chain.
+
+When at least one memory file was written or updated, add a closing line so the standalone caller proposes fixes while context is fresh:
 
 `→ Run /claude-memory-review to propose fixes for the pen before the session ends.`
 

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

@@ -9,9 +9,13 @@ description: What memory review is for, the gaps it closes, and why every action
 
 Without this skill, the memory folder grows and never drains. Entries pile up restating rules a durable surface already carries, nothing decides which memory has earned a place in one, and a rule that does get promoted arrives verbatim in a file whose voice it does not match. The folder then reads as a second source of truth that no surface points at.
 
+A pen the caller cannot face is the same gap wearing a different shape. Once routing at capture takes the domain facts, what reaches this skill is feedback about how to work, which is a working set rather than a backlog, and the proposal is a size a person actually reads. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
+
 ## Must
 
-- Treat the folder as a holding pen, so every entry in scope leaves it as a promotion, a handoff, or a deletion rather than surviving by default
+- Treat the folder as a holding pen, so every entry in scope leaves it as a promotion, a handoff, or an archive rather than surviving by default
+- Archive an entry out of the pen rather than deleting it, since nothing recovers a file from a gitignored folder
+- Hand a fact a context entry owns to `claude-docs` through the routing file, rather than editing the entry here
 - Verify the rule is not already stated or implied in the target before proposing a promotion, by reading the target rather than trusting the memory's claim about it
 - Rewrite a rule into the destination's voice instead of moving it unchanged
 - Write the proposal to a receipt on disk and take no action until the user decides per item
@@ -25,7 +29,9 @@ Without this skill, the memory folder grows and never drains. Entries pile up re
 - Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
 - Mutate tracked files from the main worktree
 - Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
-- Delete a memory entry outside the approved-per-item pass. The folder is gitignored with no history behind it, so a removal any other phase makes has no undo and no record of what it took.
+- Delete a memory entry at all. Every exit from the pen is a move into the archive.
+- Move an entry out of the pen outside the approved-per-item pass. The folder is gitignored with no history behind it, so a removal any other phase makes leaves no record of what it took.
+- Edit a context entry, or hand-edit the generated memory index
 
 ## Guards
 

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

@@ -1,6 +1,6 @@
 ---
 name: claude-memory-review
-description: Reviews `.claude/memory/` and proposes per-entry actions (promote to `CLAUDE.md`, move into a skill body, hand off to governance, or delete as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
+description: Reviews `.claude/memory/` and proposes per-entry actions (promote to `CLAUDE.md`, move into a skill body, route to a context entry, hand off to governance, or retire as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
 ---
 
 # Claude memory review
@@ -19,9 +19,9 @@ If the user re-pings the skill with no new phrase and a receipt exists, default
 
 ## Guards
 
-- All `.claude/memory/` reads, edits, and deletes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+- All `.claude/memory/` reads, edits, and archive moves resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
 - If no `.claude/memory/` directory exists at the main worktree root, stop: `❌ No .claude/memory/ directory found.`
-- If `.claude/memory/` contains no `*.md` entries other than `MEMORY.md`, stop: `✅ No memory entries to review.`
+- If `.claude/memory/` contains no `*.md` entries other than `index.md`, stop: `✅ No memory entries to review.`
 - Cleanup is exempt from the two stops above. It works on receipts in `.claude/review/`, and a drained pen is the normal state once Apply has run, so a pen-shaped stop would strand the receipt it exists to delete.
 - Resolve the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. All review and memory reads anchor here.
 
@@ -38,8 +38,8 @@ Propose is the ship-time entry point. The ship skills run it right after capture
 
 Read in parallel from the project root:
 
-- `.claude/memory/MEMORY.md`: the index
-- every other `*.md` file under `.claude/memory/`: individual entries with frontmatter (`name`, `description`, `type`)
+- `.claude/memory/index.md`: the generated index
+- every other `*.md` file under `.claude/memory/`: individual entries with frontmatter (`title`, `description`, `category`)
 
 ### Step 2: read promotion targets
 
@@ -55,27 +55,32 @@ Read any authoring reference the project does not have from `${CLAUDE_SKILL_DIR}
 
 ### Step 3: classify each entry
 
-`.claude/memory/` is a holding pen. Default every entry to promote or delete on review. Skip is the rare exception, reserved for active task overlap or user-type memories with no in-repo target.
+`.claude/memory/` is a holding pen. Default every entry to promote or retire on review. Skip is the rare exception, reserved for active task overlap or user-type memories with no in-repo target.
+
+`claude-memory-capture` routes a project fact naming a domain with a context entry to that entry, so a pen filled since routing shipped is mostly feedback: rules about how to work, which no context entry owns. Propose against what the pen holds rather than expecting the older mix. An entry carried from before routing may still name a domain that has a context entry, and that entry's action is **Promote to a context entry**, which hands it to `claude-docs` the same way capture does rather than editing the entry here.
 
 For each in-scope entry (see Scope), pick one action:
 
 - **Promote to `CLAUDE.md`**: the rule is cross-domain behavior or a design principle applied across the whole project.
 - **Promote to a skill body**: the rule fires only when editing a specific path-scoped domain. Name the target skill.
 - **Promote to a standards file**: the rule is an authoring reference that belongs in `.claude/standards/<domain>.md`.
+- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `.claude/context/index.md`. Append it to `.claude/.tmp/memory-routing/<slug>.md` in the format `claude-memory-capture` writes, and tell the user to run `/claude-docs` from a branch. Do not edit the context entry here.
 - **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.
-- **Delete**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative.
+- **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.
 
 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.
 
 #### Absorbed-already check
 
-Before proposing promote, grep the target surface for the rule's keywords. If the rule is already stated there, the action is **Delete**, not promote. Do not rely on memory-file claims that a rule is documented elsewhere. Verify.
+Before proposing promote, grep the target surface for the rule's keywords. If the rule is already stated there, the action is **Retire**, not promote. Do not rely on memory-file claims that a rule is documented elsewhere. Verify.
 
 The check covers implication, not only keyword match. If an adjacent bullet in the target section already implies the rule, merge into that bullet rather than append a second.
 
 #### Crispness check
 
-Rules that resist crisp one-line phrasing default to **Delete** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use terser phrasing for `CLAUDE.md` and imperative phrasing for skill bodies.
+Rules that resist crisp one-line phrasing default to **Retire** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use terser phrasing for `CLAUDE.md` and imperative phrasing for skill bodies.
 
 ### Step 4: write the proposal to the review file
 
@@ -90,7 +95,7 @@ Structure: a summary block at the top, a legend, then one H2 per numbered item.
 
 **Pending:** <all numbers>
 
-Legend: ✅ applied · ⏭ skipped · 🗑 deleted · 🤝 handed off · 📝 pending
+Legend: ✅ applied · ⏭ skipped · 📦 retired · 🤝 handed off · 📝 pending
 
 How to respond: fill in `Decision:` per item (`apply`, `skip`, `defer`, or a question with `?`), then re-ping the skill. Say "discuss" for question rounds, "apply" to commit. Chat shortcut: `all`, `none`, or a list of numbers.
 
@@ -106,7 +111,7 @@ Why: <one-line pulled from the memory's Why>
 
 Decision:
 
-## 2. 📝 Delete
+## 2. 📝 Retire
 
 `<memory-file>`
 
@@ -115,7 +120,7 @@ Reason: <one-line reason>
 Decision:
 ````
 
-For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `aitk-governance` and `.claude/standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Delete items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.
+For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `aitk-governance` and `.claude/standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.
 
 Tell the user `✅ Wrote proposal to .claude/review/memory-review-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping with "discuss" for question rounds or "apply" to commit.
 
@@ -127,9 +132,9 @@ Trigger: user says "challenge the promotes", "challenge before apply", or asks f
 
 1. Read the latest `.claude/review/memory-review-*.md` at the main root.
 2. For each promote item, apply three tests:
-   - **Absorbed**: grep the target surface for the rule's keywords. If already stated or implied, flip to delete.
-   - **Delta**: if the rule is a nice-to-have next to existing bullets, flip to delete.
-   - **Generality**: if the rule fires only on one literal trigger phrase, rewrite broader or flip to delete.
+   - **Absorbed**: grep the target surface for the rule's keywords. If already stated or implied, flip to retire.
+   - **Delta**: if the rule is a nice-to-have next to existing bullets, flip to retire.
+   - **Generality**: if the rule fires only on one literal trigger phrase, rewrite broader or flip to retire.
 3. Rewrite the review file in place with the updated actions and a one-line reason under each flip.
 
 ## Discuss phase
@@ -139,16 +144,16 @@ Trigger: user says "discuss", "respond to questions", or any `Decision:` value c
 1. Read the latest `.claude/review/memory-review-*.md` at the main root.
 2. For each item whose `Decision:` contains `?` or any unrecognized verb (anything other than `apply`, `skip`, `defer`):
    - Write a `Take:` line under `Decision:`, separated by exactly one blank line. If a `Take:` line already exists, overwrite it.
-   - Format: pick + one-line reason. Max 2 sentences. Decision-help style. State the recommendation (`apply` / `skip` / `delete` / specific alternative) first, then the reason. Do not enumerate tradeoffs unless one changes the call.
+   - Format: pick + one-line reason. Max 2 sentences. Decision-help style. State the recommendation (`apply` / `skip` / `retire` / specific alternative) first, then the reason. Do not enumerate tradeoffs unless one changes the call.
    - Leave the H2 emoji as 📝 pending.
 3. Skip items whose `Decision:` is `apply`, `skip`, `defer`, or empty.
 4. End with: `💬 Discussed: <nums> | ⏩ Skipped (committed or empty): <nums>`. Remind the user to refine `Decision:` lines and re-ping with "discuss" for another round, or "apply" when ready to commit.
 
-Do not act on any item. Do not delete memory files. Do not edit MEMORY.md. Do not edit promotion targets. Discuss only.
+Do not act on any item. Do not archive memory files. Do not edit promotion targets. Discuss only.
 
 ## Apply phase
 
-Trigger: user says "apply", "commit", "ship the review", or re-pings with no question items remaining. Mutates tracked files (target surfaces, memory files, `MEMORY.md`).
+Trigger: user says "apply", "commit", "ship the review", or re-pings with no question items remaining. Mutates tracked promotion targets and moves memory files into the archive.
 
 Before applying any item, check the worktree state:
 
@@ -173,13 +178,24 @@ Free-form text after the verb is a reason. Capture it in the receipt but do not
 
 Action by action type:
 
-- **Promote**: use `Edit` to insert the rewritten rule into the target surface. Then delete the memory file and remove its row from `.claude/memory/MEMORY.md`.
-- **Hand off**: do not edit governance. Delete the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
-- **Delete**: remove the memory file and its row from `.claude/memory/MEMORY.md`.
+- **Promote**: use `Edit` to insert the rewritten rule into the target surface, then archive the memory file.
+- **Promote to a context entry**: append the fact to `.claude/.tmp/memory-routing/<slug>.md`, then archive the memory file. `claude-docs` folds it in on its next run from a branch, which is what keeps one skill writing context entries.
+- **Hand off**: do not edit governance. Archive the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
+- **Retire**: archive the memory file.
+
+Archiving means creating `.claude/.tmp/memory-archive/` at the main worktree root and moving the file there under its original name, overwriting any file already at that name. Never delete a memory entry. Nothing recovers one from a gitignored folder.
+
+Do not hand-edit `.claude/memory/index.md`. Once every archive move is done, regenerate it instead:
+
+```bash
+aitk indexes regen --no-stage --root <main-root> <main-root>/.claude/memory/index.md
+```
+
+The `PostToolUse` hook that keeps the index current matches `Write|Edit|MultiEdit`, and an archive move is a shell `mv`, so nothing fires on it. Without this call the index keeps a row per archived entry and drifts exactly the way the hand-appended one did. Run it once after the last move rather than per item.
 
 Apply edits one at a time via `Edit`. Claude Code's tool permission dialog is the confirmation gate per edit. Never rewrite a whole file.
 
-As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied, ⏭ for skipped, 🗑 for deleted, or 🤝 for handed off. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until Cleanup runs or the next Propose pass overwrites it.
+As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied, ⏭ for skipped, 📦 for retired, or 🤝 for handed off. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until Cleanup runs or the next Propose pass overwrites it.
 
 **Chat shortcut:** the user replies with `all`, `none`, a comma-separated list of numbers, or `skip <nums>`. Write the matching verb into the `Decision:` slot of every item the reply names, `apply` for `all` or a bare list and `skip` for a `skip` reply, then run the parse above against the file. A reply of `none` writes nothing. A slot the reply does not name keeps its own value, so the receipt stays the source of truth and an empty slot still means take no action.
 
@@ -189,7 +205,7 @@ End with: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Om
 
 Trigger: user says "cleanup" or "delete the receipt" after Apply has run.
 
-Cleanup removes one receipt and nothing else. Apply is the only phase that deletes a memory entry, and it does so per approved item against a folder that is gitignored with no history behind it, so a deletion made anywhere else has no undo and leaves no record of what it took. A user asking to sweep stale memories wants Propose, which classifies entries and writes a decision slot per entry.
+Cleanup removes one receipt and nothing else. Apply is the only phase that moves a memory entry out of the pen, and it does so per approved item into `.claude/.tmp/memory-archive/`. A user asking to sweep stale memories wants Propose, which classifies entries and writes a decision slot per entry.
 
 If no `.claude/review/memory-review-*.md` exists at the main root, stop: `✅ No review receipt to clean up.` Every other refusal in this skill carries a message, and the phase reads a receipt before it does anything else.
 
@@ -197,7 +213,7 @@ If no `.claude/review/memory-review-*.md` exists at the main root, stop: `✅ No
 2. Delete that one file. Leave every other receipt beside it in place, because the pending test above covers the file it read and nothing has tested the rest.
 3. Leave every memory entry in place. A `Skip` decision is terminal, and applied promotions, governance handoffs, and user-type memories each stay as the review left them.
 
-Do not promote, rewrite, or delete a memory entry. Receipts only.
+Do not promote, rewrite, or archive a memory entry. Receipts only.
 
 ## After completion
 
@@ -205,7 +221,7 @@ Output one line per action taken in the most recent phase:
 
 - `✅ Promoted: .claude/memory/<memory-file> → <target>`
 - `✅ Handed off: .claude/memory/<memory-file> → governance`
-- `🗑  Deleted: .claude/memory/<memory-file>`
+- `📦 Retired: .claude/memory/<memory-file> → .claude/.tmp/memory-archive/`
 - `🗑  Swept: .claude/review/<review-file>`
 
 If the user accepted nothing, output: `✅ No changes applied.`

package/claude/skills/claude-orchestrate/SKILL.md

@@ -112,6 +112,10 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 
 Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge and whenever the ready list thins. `@.claude/snippets/claude/orchestrator-sweep.md` fires this procedure after a batch of merges and adds the plan re-verification that a merge invalidates.
 
+Open the sweep by invoking `aitk:claude-memory-capture`. Both other callers are ship-chain skills and this session never ships, so without this the session that receives every operator correction is the one session that records none. The sweep is the closest bounded moment this session has to a ship, and it already runs once per batch of merges, which beats an end-of-session moment a compaction can cut short.
+
+Capture is told this session does not commit, so it skips routing and writes memory files alone. A routed fact lands in a context entry, which is a tracked file, and Boundaries below forbids writing one from here. That is the correct split rather than a limitation: a domain fact belongs to the task that owns the surface and goes in that task's Findings, while what this session produces is feedback about how to work, which is exactly the class the memory folder keeps.
+
 1. Run `gh pr list --state open` and `git log --oneline -8`. Report any pull request whose review has not been posted and stop for that one first.
 2. For each pull request merged since the last sweep, place every finding it produced. Route a finding that changes a rule to the standard or rule that states it, one that changes another task to that task's Findings, and one that overturns a groundwork lean to that folder marked answered. Never leave a finding in a pull request thread alone.
 3. Archive what closed. A task whose outcomes are all `[x]` runs `claude-docs` for the plan sweep, then `claude-tasks` to archive. A task whose outcomes describe standing policy rather than a deliverable never closes on its own, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason recorded and archive once that branch merges. Encoding it from this session would write a tracked file, which Boundaries forbids.
@@ -121,6 +125,7 @@ Keep enough planned, non-conflicting tasks available that a free worker never wa
 7. Write a plan for each newly promoted task with `claude-feature`, then report:
 
 ```plaintext
+Captured: <memory file> (<type>), or "nothing worth capturing"
 Findings placed: <finding> → <destination>
 Archived: <task>
 Promoted: <task>, touches <surfaces>, parallel with <task> because <disjoint sets>

package/claude/skills/git-ship/SKILL.md

@@ -14,26 +14,29 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 
 ## Sequence
 
-1. Invoke `aitk:claude-docs` to sync internal planning docs against session decisions
-2. Invoke `aitk:docs-sync` to sync public docs against changes since main
-3. Run `git add -A` to stage any files the sync skills wrote
-4. Invoke `aitk:git-stage` to group staged changes and commit by concern
-5. Invoke `aitk:git-branch` to rename branch to match conventional format
-6. Invoke `aitk:git-pr` to push branch and open pull request
-7. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
-8. Invoke `aitk:claude-memory-capture` to extract durable patterns from the session into `.claude/memory/`
-9. If `claude-memory-capture` wrote or updated at least one entry this session, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If capture wrote nothing, skip this step.
+1. Invoke `aitk:claude-memory-capture` to route what this session learned to the context entries that own it and write the residue to `.claude/memory/`
+2. Invoke `aitk:claude-docs` to sync internal planning docs against session decisions, folding in the routed facts
+3. Invoke `aitk:docs-sync` to sync public docs against changes since main
+4. Run `git add -A` to stage any files the sync skills wrote
+5. Invoke `aitk:git-stage` to group staged changes and commit by concern
+6. Invoke `aitk:git-branch` to rename branch to match conventional format
+7. Invoke `aitk:git-pr` to push branch and open pull request
+8. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. If step 1 wrote or updated at least one memory file, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
+
+Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
 
 Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
 
 ## After completion
 
-Output up to three lines:
+Output up to four lines:
 
 ```plaintext
 ✅ Shipped
+<N facts routed to context entries>
 <N memories captured in .claude/memory/>
 <Memory proposal at .claude/review/memory-review-<slug>.md>
 ```
 
-Omit the second and third lines if `claude-memory-capture` wrote nothing this session, since no captures means no scoped review and no proposal.
+Omit the second line if nothing routed. Omit the third and fourth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.

package/claude/skills/session-resume/SKILL.md

@@ -13,7 +13,7 @@ Read these in parallel, skipping any that do not exist:
 
 - `.claude/tasks/index.md`: the backlog, one line per task. Read this before any individual task file.
 - `.claude/plans/*.md`: execution detail for in-progress tasks
-- `.claude/memory/MEMORY.md` and any memory files relevant to the top backlog item
+- `.claude/memory/index.md` and any memory files relevant to the top backlog item
 
 Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
 
@@ -33,4 +33,4 @@ Output three sections:
 
 End with one line: `Start with: <first Up next item>` and note whether it has a linked plan.
 
-Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`. Memory is updated only when a recorded fact becomes wrong, never on resume.
+Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`. Memory is updated only when a recorded fact becomes wrong, never on resume. A domain fact reaches a session through `.claude/context/`, which `claude-memory-capture` routes to and the three-tier model loads on demand, so the memory folder read here is the residue no context entry owns.