Smelt

---
metadata:
  category: memory
  order: 1
name: smelt
description: "Consolidate one project's repository memory, pruning stale or contradicted claims, without proposing rules. Use to tidy accumulated memory; not for new facts (/roar)."
user-invocable: true
argument-hint: "[<project-repository>] [--dry-run]"
---

# Smelt — project memory consolidation

Use `/smelt [<project-repository>] [--dry-run]`. With no argument the project
is the repository of the current working directory, resolved to its primary
checkout, never a worktree path:
`PROJECT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")`.
Outside a git repository that command fails: refuse and write nothing. The
report's first line names the resolved project. An explicit argument selects
another project. The selected project
repository is the destination; the installed skill directory is never a
destination. Read its AGENTS.md and inspect its memory convention. Missing
paths or permissions are visible failures; do not create a replacement store
in the harness or use retired shared/native-store helpers.

For helper commands, set `IDH_ROOT="${IDH_ROOT:-$(p="<loaded-SKILL.md>"; [ -d "$p" ] || p=$(dirname "$p"); cd -P "$p/../.." && pwd -P)}"`
in the same shell call. Substitute the absolute SKILL.md path or skill directory supplied by the
runtime (a pre-set `IDH_ROOT` wins); this physically resolves the installed projection to its canonical
checkout. Never derive the helper root from the selected project's cwd.

## Migration preflight

Run sequentially: preflight, isolate, migrate, then consolidate. Migration must
finish successfully before any consolidation is read or written.

Set `PROJECT` to the selected repository's absolute path. Inventory additional
active reference files explicitly as project-relative paths; start with
`REFERENCES=(--reference AGENTS.md)` and add only inspected active references.
The helper already includes the index and Markdown topics. Do not
inventory journal entries, accepted reports, historical ledgers or ciphertext;
never sweep other projects or the installed harness.

Preflight reads inputs and describes the one-way migration:

```bash
python3 "$IDH_ROOT/scripts/smelt_migrate.py" "$PROJECT" "${REFERENCES[@]}" --dry-run
```

Stop visibly on a conflict, unreadable input, filesystem indirection or helper
failure; preserve both conflicting paths. If invoked with `--dry-run`, report
this plan and stop here without writes, branches or commits. Old names are
recognized only by this migration preflight, never as consolidation inputs.

For a writing run, enter an isolated checkout and dedicated branch of the
selected project, leaving its primary checkout and unrelated changes alone.
Set `PROJECT` to that isolated checkout; retain the inspected relative
`REFERENCES` inventory. Apply the migration there:

```bash
python3 "$IDH_ROOT/scripts/smelt_migrate.py" "$PROJECT" "${REFERENCES[@]}"
```

A project needs no consolidation prompt: the editorial detail is
`references/consolidation.md`, and its revision
is this skill's. The helper retires any per-project `memory/DREAM.md`,
`HOARD.md` or `SMELT.md` and prints `Retired prompt:` for each and
`Names a retired prompt:` for each active file still pointing at one; it
refuses a prompt that HEAD does not hold unchanged. Before
committing, read each retired prompt (`git show HEAD:./<path>`), carry its local
location facts (rules paths, native store, import annex) into
`memory/MEMORY.md`, or a `SOURCES.md` it links, within the index cap, and edit
the named mentions that still point at it; a line recording its retirement
stays, and a re-run names it again. Its generic text is dropped. If the project memory
convention is missing, report it and stop. Already migrated projects are a
no-op. Report/journal bytes and provenance remain preserved; review all
migration edits before committing. There is no old command alias, compatibility
symlink or old-format consolidation branch.

## Three main functions

Apply these to consolidated `memory/topics/` and the index:

- **Pruning:** remove outdated, irrelevant or superseded information from the
  current memory. Record the reason and retained source references in the report.
- **Merging:** combine duplicate or overlapping entries into one accurate record,
  preserving source links, conditions, exceptions and unresolved contradictions.
  Carry quotations from manuscript sources, verified on the page, and their
  locators (page, folio, note number) verbatim into topics; never paraphrase,
  condense or merge them away. Keep conflicting recorded locators as an
  unresolved contradiction. Operational memory is condensed freely.
- **Refreshing:** update stale context that remains relevant using current
  evidence; flag uncertainty when it cannot be verified.

The raw journal stays append-only: a correction is a new entry linking
the one it corrects. Pruning a consolidated claim never deletes
its source experience. One carve-out: legacy review-attribution records move
once, by `git mv` with their bytes intact, to `memory/evidence/attribution/`.
`memory/MEMORY.md` has **at most 40 lines**, counting headings and blank
lines. Keep details in the journal, linked from the department page, rather
than expanding the index.

Maintain each selected project’s ruling register and retirement records by
`references/consolidation.md` § Ruling register and retirement, preserving that
project’s rulings and author edits. Brood primarily handles integration and
retirement of integrated rulings.

A topic is the as-built guide to one department (current claims, each linked
to its journal episode) and holds at most 4 KB outside its Sources
section. Details: `references/consolidation.md`
§ Job of a topic and caps.

## Coherence across indexed memories and harness rules

Pay particular attention to coherence among all memories referenced by the
index, not just duplicate wording. Compare their claims, scope, conditions and
exceptions with each other and with applicable harness rules, read as authority
sources. Refreshing, merging or pruning must not leave contradictory current
advice in another indexed topic.

A memory cannot override a harness rule. Correct or withdraw conflicting
consolidated claims when the evidence and applicable rule are clear. Preserve
the factual episode and explain the change in the report. If scope, authority or
evidence is ambiguous, mark the conflict explicitly and avoid presenting either
claim as settled advice. Reading harness rules never authorizes editing them.
Do not infer a new rule from a repeated experience or manufacture agreement.

Every contradiction left exposed gets a ticket in the selected project's ticket
store, for later discussion with the author (author's order, 2026-10-30): one
per contradiction, naming both claims, their sources and the exposing page;
reuse an open ticket on the same contradiction. The page and the report link
it. The ticket states the question; it picks no side and proposes no rule.
A project without a ticket store lists them in the report as unfiled.

## Native-note triage lane

Claude Code keeps its own auto-memory outside the repository, and the author
keeps it on purpose (ticket 1350, option b, 2026-11-01): dictated notes land
there, and about 41% of them are working rules (brood run
`design/2026-11-01-brood-harness-run.md`). Smelt therefore ends every
writing run with a listing for the author. Run, with `PROJECT` the project's
primary checkout (the store is keyed by the path Claude Code ran in, so an
isolated worktree resolves to another, usually absent, store):

```bash
python3 "$IDH_ROOT/scripts/smelt_native_notes.py" "$PROJECT"
```

The helper is read-only: file, type, blob sha, description per note, and the
resolved store path. A missing store is reported as unavailable, never
created. Read each note, then put in the smelt report a table with one row per
note: file, one-line substance, and a proposed disposition, exactly one of

- **nominate as a rule candidate for Brood**, with a one-line reason the note
  reads as a working rule, without a destination file, section, or proposed wording;
- **promote to repo memory**, naming the topic (an experience or a project fact);
- **delete** (stale, done, or already in force), saying where it is in force.

The author decides. Smelt writes no rule, edits no native note and deletes none;
the disposition column is a proposal, not an action. Notes already carried in a
previous accepted report with an unchanged sha are listed as "unchanged" without
a new proposal. Rule nominations reach the author only through the report;
Brood takes up any promotion discussion on a separate explicit request. A
nomination proposes no rule and is no exception to this skill's boundary.

## Case-note curation lane

Skill case notes (`memory/skills/<skill>.md`) are pushed at skill load, and
nothing else maintains them (tickets 1431, 1432; principle in
`design/2026-10-31-skill-case-notes.md`). At each writing run, for every
existing note and for any skill whose memory shows recurring observed episodes,
re-select its cases by judged usefulness: one to four observed cases, each
dated, sourced to a journal episode or topic, ending in a `Use:` line, the
whole under the ~400-word cap. Prefer the cases most likely to change a
decision at the next load; drop stale, superseded or merely illustrative ones.
`memory/skills/merge.md` is the worked example. The report lists each case
added or dropped with one line of why. Smelt proposes; the author's acceptance
of the smelt merge request is the review. This lane writes no rule.

## Procedure

After the writing run's migration succeeds, continue sequentially:

1. Read the sources and keep the blob ledger as
   `references/consolidation.md` § Read states;
   never treat a skipped or unavailable source as empty. Native notes are not
   the canonical reference or a write destination; the § Native-note triage
   lane lists them for the author.
2. Re-derive each topic from its previous page and the journal, by
   department (references § Rebuild), instead of appending; apply pruning,
   merging and refreshing in the rewrite. Link source episodes. Update the
   `memory/MEMORY.md` index within its 40-line maximum. Never rewrite, move or
   delete existing journal entries. Append retirement records as specified in
   references § Ruling register and retirement. Do not propose rules.
3. Write a report in `memory/smelts/` with the fields of references § Report:
   skill revision, ledger, changes, net change in bytes measured by
   `"$IDH_ROOT/scripts/memory_sizes.py"`, unresolved questions, the lanes'
   tables, and the second pass.
4. Check coherence across all indexed memories and applicable harness rules,
   links, provenance, the migration/consolidation diff and the index line count.
   Reduce the index if it exceeds 40 lines before committing. Ticket each
   exposed contradiction (§ Coherence). Commit the
   authorized migration edits and memory outputs on the project branch and
   submit a merge request following its integration policy. Do not merge
   automatically. Preserve and report the branch if submission fails. Only
   accepted reports count as completed processing on subsequent runs.

## Encrypted entries

Uncleared material lives in the project repository as `.age` ciphertext,
read with capture's key and commands and never written as plaintext to the
working tree. The key scheme, the scope of re-encryption (consolidated
topics only, never a journal entry), the atomic re-encryption and the three
failure modes (authentication, malformed ciphertext, re-encryption) are in
`references/consolidation.md` § Encrypted entries.

## Authority and invocation

The explicit invocation authorizes the migration helper's one-way path moves,
its retirement of a per-project prompt, and mechanical path/command
substitutions in the index, topics and inventoried active references,
including the selected project's AGENTS.md, where a mention of the retired
prompt is repointed at the smelt skill or dropped.
This exception is limited to migration in its isolated branch: no policy
rewriting, rule promotion, historical-ledger edits or cross-project writes.

Consolidation writes only `memory/MEMORY.md`, `memory/topics/`,
`memory/skills/`, `memory/smelts/`, new append-only retirement records in
`memory/journal/YYYY/`, and, for exposed contradictions only, new tickets within the
selected project repository. Uncleared material stays in that same
repository as age-encrypted `.age` ciphertext — there is no separate
companion store. It does not
modify AGENTS.md, rules, skills, runbooks or tests, open crystallisation issues,
propose promotions, or write cross-project provenance into the harness. The native-note triage
table lists rule candidates for Brood, without proposing rules or promotions.
Crystallisation requires a separate explicit user request naming its scope and
destination. A useful pattern or a reviewed memory PR is not that request.

Lair completes its work and suggests smelt in its conclusion after 5 or more
new experiences. It neither waits nor launches smelt. Smelt runs when explicitly
invoked as a separate follow-up, in a new `/clear` session — a fresh context,
not the wrapping session's compacted residue.
There is no timer or automatic periodic launch. Use an isolated project checkout. Missing paths or permissions are visible
failures; never fall back to the harness or restore/change its primary branch.