liteagents 2.12.1 → 2.15.0

package/packages/claude/commands/{friction → remember}/friction.js

@@ -6,7 +6,7 @@
  *     node friction.js <sessions-directory>
  *     node friction.js ~/.claude/projects/-home-hamr-PycharmProjects-liteagents/
  *
- * Outputs (all in .claude/friction/):
+ * Outputs (all in .claude/remember/friction/):
  *     friction_analysis.json   - Per-session analysis
  *     friction_summary.json    - Aggregate stats
  *     friction_raw.jsonl       - Raw signals
@@ -1483,7 +1483,7 @@ function analyzeMain(sessionsDir) {
   }
 
   // Create output dir
-  const outputDir = '.claude/friction';
+  const outputDir = '.claude/remember/friction';
   fs.mkdirSync(outputDir, { recursive: true });
 
   // Process each session
@@ -1641,12 +1641,12 @@ function analyzeMain(sessionsDir) {
 
   // Output files
   console.log('Outputs:');
-  console.log('  \uD83D\uDCCA .claude/friction/report.md (detailed analysis)');
-  console.log('  \uD83D\uDCCB .claude/friction/antigen_review.md (clustered failure patterns)');
-  console.log(`  \uD83D\uDCC1 .claude/friction/*.json (raw data: ${allSignals.length} signals, ${analyses.length} sessions)`);
+  console.log('  \uD83D\uDCCA .claude/remember/friction/report.md (detailed analysis)');
+  console.log('  \uD83D\uDCCB .claude/remember/friction/antigen_review.md (clustered failure patterns)');
+  console.log(`  \uD83D\uDCC1 .claude/remember/friction/*.json (raw data: ${allSignals.length} signals, ${analyses.length} sessions)`);
   console.log();
 
-  console.log('Next: Review .claude/friction/report.md');
+  console.log('Next: Review .claude/remember/friction/report.md');
   console.log('='.repeat(60));
 
   if (errors.length > 0) {
@@ -2196,9 +2196,9 @@ function clusterCandidates(allCandidates) {
 
 function extractMain(sessionsDir) {
   // Load friction analysis
-  const analysisFile = '.claude/friction/friction_analysis.json';
+  const analysisFile = '.claude/remember/friction/friction_analysis.json';
   if (!fs.existsSync(analysisFile)) {
-    console.log('Error: Run friction analysis first to generate .claude/friction/friction_analysis.json');
+    console.log('Error: Run friction analysis first to generate .claude/remember/friction/friction_analysis.json');
     return 1;
   }
 
@@ -2211,7 +2211,7 @@ function extractMain(sessionsDir) {
   }
 
   // Load raw signals
-  const rawFile = '.claude/friction/friction_raw.jsonl';
+  const rawFile = '.claude/remember/friction/friction_raw.jsonl';
   let signals = [];
   if (fs.existsSync(rawFile)) {
     const rawContent = fs.readFileSync(rawFile, 'utf-8');
@@ -2266,7 +2266,7 @@ function extractMain(sessionsDir) {
   console.log();
 
   // Save outputs
-  const outputDir = '.claude/friction';
+  const outputDir = '.claude/remember/friction';
   fs.mkdirSync(outputDir, { recursive: true });
 
   // Raw candidates (kept for debugging)
@@ -2340,7 +2340,7 @@ function extractMain(sessionsDir) {
   });
 
   fs.writeFileSync(path.join(outputDir, 'antigen_review.md'), reviewLines.join(''));
-  console.log('Output: .claude/friction/antigen_review.md\n');
+  console.log('Output: .claude/remember/friction/antigen_review.md\n');
 
   return 0;
 }
@@ -2358,7 +2358,7 @@ Usage:
     node friction.js <sessions-directory>
     node friction.js ~/.claude/projects/-home-hamr-PycharmProjects-liteagents/
 
-Outputs (all in .claude/friction/):
+Outputs (all in .claude/remember/friction/):
     friction_analysis.json   - Per-session analysis
     friction_summary.json    - Aggregate stats
     friction_raw.jsonl       - Raw signals
@@ -2385,7 +2385,7 @@ Outputs (all in .claude/friction/):
   analyzeMain(sessionsDir);
 
   // Check if analysis produced output
-  const analysisFile = '.claude/friction/friction_analysis.json';
+  const analysisFile = '.claude/remember/friction/friction_analysis.json';
   if (!fs.existsSync(analysisFile)) {
     console.log('\nNo analysis output. Check session directory.');
     return 1;
@@ -2401,7 +2401,7 @@ Outputs (all in .claude/friction/):
   console.log(' DONE');
   console.log('='.repeat(60));
 
-  const reviewFile = '.claude/friction/antigen_review.md';
+  const reviewFile = '.claude/remember/friction/antigen_review.md';
   if (fs.existsSync(reviewFile)) {
     console.log('\nReview your antigens:');
     console.log(`  cat ${reviewFile}`);

package/packages/claude/commands/remember.md

@@ -10,10 +10,17 @@ Run friction analysis, then consolidate session stashes + friction antigens into
 - Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
 - **Precision over recall for hot memory.** A false antigen loaded into `@MEMORY.md` steers every future session. When unsure, record as a low-confidence episode — do not promote.
+- **Mid-tier model, not hardcoded.** Steps 2/3/4a delegate to a mid-tier model — capable of
+  semantic judgment, cheaper/faster than your top reasoning tier (e.g. Claude's Sonnet vs
+  Opus). Use whatever your tool designates as that balanced default; never hardcode a
+  vendor-specific model name.
+- **Batch independent subagent calls.** Step 2's per-stash extractions are independent of
+  each other — spawn them concurrently (parallel/background subagent calls in one turn)
+  where your tool supports it, instead of processing stashes one at a time.
 
 **What it does**
 
-Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_clusters.json`), extracts durable facts, episodes, and behavioral antigens into a single `.claude/memory/MEMORY.md`, then injects a managed memory section into `CLAUDE.md`.
+Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antigen_clusters.json`), extracts durable facts, episodes, and behavioral antigens into a single `.claude/remember/MEMORY.md`, then injects a managed memory section into `CLAUDE.md`.
 
 **Steps**
 
@@ -23,7 +30,7 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    project are behavioral lessons worth keeping everywhere. So point it at the tool's
    **global sessions root** (all projects), not a per-project directory.
 
-   - **Locate `friction.js`** — it is bundled next to this command at `friction/friction.js`
+   - **Locate `friction.js`** — it is bundled next to this command at `remember/friction.js`
      (the same directory as `remember.md`, whether installed or run from the package). If it
      exists nowhere, skip to step 1 (stash-only) and tell the user friction.js is missing.
    - **Resolve the global sessions root** — probe this list top-to-bottom, use the first that
@@ -41,7 +48,7 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
      > will resolve but yield no signals until friction learns their formats — open an issue
      > to request one: https://github.com/hamr0/liteagents/issues
    - **Run** `node <friction.js> "<resolved-root>"`. friction writes its output to
-     `.claude/friction/` in the current project.
+     `.claude/remember/friction/` in the current project.
    - **On any miss — loud, never silent.** If no root resolves, or friction errors, or it
      finds no usable sessions, print this and continue with stash-only consolidation:
      > ⚠️ Friction didn't run — no sessions found. To enable it, open this command file
@@ -49,27 +56,41 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
      > list in step 0, then re-run `/remember`. Consolidating stashes only this time.
 
 1. **Gather sources**
+   - **Legacy layout migration (one-time, loud).** Older versions used `.claude/memory/` and
+     `.claude/friction/`. If either exists: move the pipeline files
+     `.claude/memory/{MEMORY.md,ledger.json,.processed}` → `.claude/remember/`, and **discard**
+     the old `.claude/friction/` contents entirely — friction regenerates all of its output
+     fresh every run (step 0 has already rebuilt it in `.claude/remember/friction/` by the time
+     migration runs; stale copies carry no unique information and moving them would overwrite
+     fresh output). **Move only those pipeline files** — anything else in `.claude/memory/`
+     (e.g. user-owned rule files) stays where it is. Remove the old dirs only if empty, update the managed MEMORY section in CLAUDE.md to
+     the new reference (step 5), and tell the user exactly what moved.
+   - **Bootstrap `AGENT_RULES.md` (one-time, silent-if-present).** If
+     `.claude/remember/AGENT_RULES.md` does not exist, copy it from the bundled template next
+     to this command (`remember/AGENT_RULES.md`, same directory as `friction.js`). If it
+     already exists, leave it untouched — never overwrite, even if the bundled template
+     changes in a later version; it becomes user-owned the moment it lands in the project.
    - Read all `.claude/stash/*.md` files in the current project
-   - Read friction output written in step 0: `.claude/friction/antigen_clusters.json` (preferred) or `.claude/friction/antigen_review.md` (fallback)
-   - Read existing `.claude/memory/MEMORY.md` if it exists — create dir if missing
-   - Read processed manifest at `.claude/memory/.processed` — skip already-processed stashes
+   - Read friction output written in step 0: `.claude/remember/friction/antigen_clusters.json` (preferred) or `.claude/remember/friction/antigen_review.md` (fallback)
+   - Read existing `.claude/remember/MEMORY.md` if it exists — create dir if missing
+   - Read processed manifest at `.claude/remember/.processed` — skip already-processed stashes
    - If no unprocessed stashes AND friction produced no new antigens, report "nothing to consolidate" and stop
 
-2. **Extract from unprocessed stashes** (use Task tool with sonnet model for each)
-   - For each unprocessed stash, call sonnet to extract:
+2. **Extract from unprocessed stashes** (spawn one subagent per stash, in parallel — see Guardrails)
+   - For each unprocessed stash, call the mid-tier model (see Guardrails) to extract:
      - **FACTS** (atomic, one-line): stable preferences, decisions, corrections, explicit "remember this"
      - **EPISODE** (3-5 bullet narrative): what was the goal, what was tried, outcome, lesson
      - **SKIP**: code details, file paths, errors, mechanical steps, LLM responses
    - Collect all new facts and episodes
 
 3. **Merge into MEMORY.md**
-   - Read existing `.claude/memory/MEMORY.md` and parse its sections (## Facts, ## Episodes, ## Antigens)
-   - **Facts section**: call sonnet with existing facts + newly extracted facts
+   - Read existing `.claude/remember/MEMORY.md` and parse its sections (## Facts, ## Episodes, ## Antigens)
+   - **Facts section**: call the mid-tier model with existing facts + newly extracted facts
      - Rules: new updates replace old, contradictions keep new version, duplicates dropped
      - Keep facts atomic, one line each
    - **Episodes section**: append new episode entries (append-only, timestamped, no dedup)
    - **Antigens section**: only update from friction output (step 4)
-   - Write merged result to `.claude/memory/MEMORY.md` in the format under step 6.
+   - Write merged result to `.claude/remember/MEMORY.md` in the format under step 6.
 
 4. **Distill friction into antigens** (only if friction output exists)
 
@@ -83,9 +104,9 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    > *themselves*). **You work from these short quotes — never re-read the session
    > logs.** Friction's lexical grouping and flags are hints, not the verdict.
 
-   - Read `.claude/friction/antigen_clusters.json`.
+   - Read `.claude/remember/friction/antigen_clusters.json`.
    - **4a. Classify target, then semantically consolidate** (the parts lexical matching can't do).
-     Call sonnet with the cluster quotes + their `preceding`/`projects`/`sessions`/`self_suspect`
+     Call the mid-tier model with the cluster quotes + their `preceding`/`projects`/`sessions`/`self_suspect`
      (NOT the logs), and have it:
      1. **Decide the target of each reaction — agent or self.** Drop *self/context*
         corrections where the user redirected themselves ("wrong project", "wrong window",
@@ -114,21 +135,80 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
        - **High** (5+ sessions) → loaded hot via `@MEMORY.md`
        - **Medium** (3-4 sessions) → recorded under Antigens, *not* loaded hot
        - **Low** (<3 sessions) → keep as Episode only
+   - **Recurrence tiers bind everything, including LLM-merged groups:** merging consolidates
+     evidence, it never elevates it — a merged group's tier comes from its combined
+     distinct-session count (e.g. a 2-session merged group is still Low → Episode + ledger
+     `observing`, not an antigen entry in MEMORY.md).
    - **Never auto-promote.** Only High-confidence (5+ sessions) antigens load hot. A
      single dramatic correction is an Episode, not an antigen.
    - Update the Antigens section in MEMORY.md (promote/demote based on new recurrence).
+   - **4c. Update the antigen ledger** (`.claude/remember/ledger.json`) — the evidence trail
+     linking each rule to the mistake it targets and whether it is working. Create it as
+     `{"version": 1, "entries": []}` if missing. It is JSON for exact matching — bookkeeping
+     only, never injected into context as guidance (MEMORY.md is what gets read; the ledger
+     is what gets checked).
 
-5. **Inject memory reference into CLAUDE.md**
+     Entry shape:
+     ```json
+     { "id": "ag-001", "class": "claimed-done-not-verified",
+       "class_hints": ["says pushed but", "none got it"],
+       "status": "observing|hot|rejected|escalated",
+       "rule": "<current phrasing>",
+       "attempts": [{ "n": 1, "rule": "<phrasing>", "adopted": "YYYY-MM-DD", "outcome": "active|failed" }],
+       "evidence": { "sessions": 0, "projects": [], "quotes": [], "last_seen": "YYYY-MM-DD" },
+       "recurred_while_hot": 0,
+       "history": [{ "date": "YYYY-MM-DD", "event": "<transition>" }] }
+     ```
+
+     For each surviving antigen from 4a/4b, match against existing entries by `class_hints`
+     (the mistake class, not the rule wording — rules change, the class doesn't):
+     - **No match** → new entry, `status: "observing"`, attempt 1, history "candidate (N sessions)".
+     - **Match, `observing`** → merge evidence (sessions, quotes, projects, last_seen).
+       Crosses the 4b hot threshold → `status: "hot"`, history "promoted to hot (N sessions)".
+     - **Match, `hot`** → the mistake happened *while its rule was loaded*:
+       `recurred_while_hot += 1`, merge evidence, history "recurred while hot (count)".
+       - At `recurred_while_hot >= 2`: the phrasing failed. Mark the current attempt
+         `outcome: "failed"`, draft attempt n+1 — it must differ from **every** prior
+         attempt's text in this entry (failed attempts are the rejected-edit buffer: never
+         re-propose one verbatim) — replace `rule`, update MEMORY.md's Antigens section,
+         reset `recurred_while_hot` to 0.
+       - If 2 attempts have already failed and the antigen persists → `status: "escalated"`:
+         remove the rule from MEMORY.md's hot section, record a Fact instead ("persistent
+         failure mode: <class> — no phrasing reduces it"), and flag it in the step-7 report.
+         **Flag, don't act** — the user decides: enforcement (a hook, where the tool has
+         them) or accepted limit.
+     - **Match, `escalated`/`rejected`** (rejected = user veto) → merge evidence only; never re-propose.
+
+     Consistency: MEMORY.md's Antigens section is the render; the ledger is the record —
+     after 4c every hot antigen in MEMORY.md has a matching `hot` ledger entry. Mutations
+     are append-friendly: merge evidence and change status, never delete entries or history
+     lines. If ledger.json is malformed, say so loudly, move it aside as
+     `ledger.json.bad-<date>`, and start fresh — never silently overwrite.
+
+5. **Inject memory + rules references into CLAUDE.md**
    - Compose the section between `<!-- MEMORY:START -->` and `<!-- MEMORY:END -->` markers:
      ```
      <!-- MEMORY:START -->
-     @MEMORY.md
+     @.claude/remember/MEMORY.md
      <!-- MEMORY:END -->
      ```
-   - The `@MEMORY.md` reference points to `.claude/memory/MEMORY.md` — Claude loads the full file directly, so no inline duplication is needed
-   - If CLAUDE.md already has MEMORY markers, replace the section between them
-   - If CLAUDE.md has no MEMORY markers, append the section at the end
-   - If no CLAUDE.md exists, create one with just the memory section
+   - The reference is an **explicit path** (`@.claude/remember/MEMORY.md`) — `@`-references
+     resolve relative to the file containing them, so a bare `@MEMORY.md` in the project root
+     would point at a nonexistent root-level file. Claude loads the full file directly, so no
+     inline duplication is needed
+   - If `.claude/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
+     independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
+     markers:
+     ```
+     <!-- AGENT_RULES:START -->
+     Consult when building something new or adding a feature — a standards guide, not hot
+     context like MEMORY.md above:
+     @.claude/remember/AGENT_RULES.md
+     <!-- AGENT_RULES:END -->
+     ```
+   - Each marker pair is independent: if CLAUDE.md already has a given pair, replace the
+     section between them; if not, append it at the end; if no CLAUDE.md exists, create one
+     containing whichever section(s) apply
 
    ```markdown
    # Project Memory
@@ -153,19 +233,31 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/friction/antigen_cluster
    ```
 
 6. **Update processed manifest**
-   - Append paths of newly processed stashes to `.claude/memory/.processed`
+   - Append paths of newly processed stashes to `.claude/remember/.processed`
 
-7. **Report to user**
+7. **Report to user** — print it AND write the same content to `.claude/remember/report.md`
+   (overwritten each run; the ledger keeps history — the report is just the latest snapshot)
    - Number of stashes processed
    - Facts count (total, new)
    - Episodes count (total, new)
    - Antigens count by confidence tier, with how many newly promoted to hot
+   - Ledger lines — one per non-observing entry: id, short rule, status, recurrences since
+     adoption. Highlight rephrased (RECURRED) and ESCALATED entries; escalations need a
+     user decision, e.g.:
+     ```
+     ledger: ag-001 "verify live after publish"  hot, 0 recurrences since 2026-07-10
+     ledger: ag-003 "don't commit per change"    RECURRED while hot (2/2) → rephrased, attempt 2
+     ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
+     ```
+   - If AGENT_RULES.md was bootstrapped this run, say so (one line)
    - Confirm MEMORY.md and CLAUDE.md updated
 
-**File locations (all project-local)**
-- Memory file: `.claude/memory/MEMORY.md` (single source of truth, referenced as @MEMORY.md)
+**File locations (all project-local — two dirs: `/stash` owns `.claude/stash/`, `/remember` owns `.claude/remember/`)**
 - Stash files: `.claude/stash/*.md`
-- Friction output: `.claude/friction/antigen_clusters.json` (observed-reaction clusters: theme, suggested_artifact, confidence, severity, sessions, projects, contexts)
-- Friction fallback: `.claude/friction/antigen_review.md` (human-readable clusters)
-- Processed manifest: `.claude/memory/.processed`
-- Output: `CLAUDE.md` (managed MEMORY section with @MEMORY.md reference)
+- Memory file: `.claude/remember/MEMORY.md` (single source of truth, referenced as `@.claude/remember/MEMORY.md`)
+- Rules template: `.claude/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced as `@.claude/remember/AGENT_RULES.md`)
+- Antigen ledger: `.claude/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
+- Consolidation report: `.claude/remember/report.md` (latest step-7 report, overwritten each run)
+- Processed manifest: `.claude/remember/.processed`
+- Friction output (transient, regenerated each run): `.claude/remember/friction/` — `antigen_clusters.json` (preferred input), `antigen_review.md` (fallback), plus raw analysis files
+- Output: `CLAUDE.md` (managed MEMORY section, plus an AGENT_RULES section once bootstrapped)

package/packages/claude/commands/stash.md

@@ -10,15 +10,26 @@ Save session context for compaction recovery or handoffs.
 **Guardrails**
 - Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
+- **Mid-tier model, not hardcoded.** The write-up subagent (step 2) uses a mid-tier model —
+  capable of semantic judgment, cheaper/faster than your top reasoning tier (e.g. Claude's
+  Sonnet vs Opus). Use whatever your tool designates as that balanced default; never hardcode
+  a vendor-specific model name.
+- **Background dispatch where supported.** Run the write-up subagent in the background
+  (non-blocking) so the session isn't held up waiting on formatting/file I/O. Fall back to
+  writing inline (today's behavior) if your tool has no subagent or background-dispatch
+  mechanism.
 
 **What it does**
-1. Captures current conversation context and key decisions
-2. Records active work in progress
-3. Stores important findings and insights
-4. Creates stash file in `.claude/stash/`
-5. Enables context restoration after compaction
-6. **Consolidation nudge** — after saving, count the unprocessed backlog:
-   `unprocessed = (files in .claude/stash/*.md) − (entries in .claude/memory/.processed)`
+1. Drafts a compact brief of current conversation context, key decisions, active work in
+   progress, and findings/insights — done inline, since only the running session holds full
+   conversation context
+2. Hands the brief to a subagent on the mid-tier model (see Guardrails) to expand into the
+   full stash file at `.claude/stash/<name>.md`, dispatched in the background where the tool
+   supports it. Falls back to writing inline if subagent/background dispatch isn't available
+3. Enables context restoration after compaction
+4. **Consolidation nudge** — whichever actor wrote the file (the subagent, or the session
+   itself on the inline fallback) counts the unprocessed backlog after saving:
+   `unprocessed = (files in .claude/stash/*.md) − (entries in .claude/remember/.processed)`
    (a missing `.processed` manifest means 0 processed). If `unprocessed >= 5`, end with one line:
    > 📝 N stashes since last consolidation — run `/remember` to fold them into memory.
 
@@ -50,3 +61,5 @@ cat .claude/stash/<name>.md
 - Stashes stored in `.claude/stash/` (project-local)
 - Automatically includes: timestamp, active plan, recent decisions
 - Maximum context retention with minimal token usage
+- When dispatched in the background, the "Stashed to X" confirmation and consolidation nudge
+  arrive as the subagent's completion notification rather than inline in the same turn