Learn

Learn

Maintain a compact project knowledge base under .superharness/spec/learnings/.

Select material

Use this evidence order:

1. Start with the live session context because it preserves the user's exact intent.
2. Add unconsumed project observations from .superharness/trace.jsonl to recover earlier signals and supporting prompts.

Persist only durable information:

• user corrections that change future behavior
• verified conflicts between an assumption and the codebase
• project conventions or decisions that cannot be inferred reliably from code
• recurring pitfalls with a verified resolution

Exclude one-off task details, facts already obvious from code, and generic programming knowledge.

Admission gate

Verify every candidate against the repository before persisting. Search for existing coverage in skills/, docs/, AGENTS.md, CLAUDE.md, .superharness/spec/, and recent git history, then deliver one verdict per candidate:

• Save — durable and absent from the repo; create or merge a topic page.
• Improve then Save — durable but vague; sharpen the trigger and action wording, then save.
• Absorb into X — an existing topic page or spec file already covers it; merge the new evidence there instead of creating a page.
• Drop — readable from the repo, one-off, or generic knowledge; do not persist.

This gate also applies to the 0.9 fast path: when the user says "remember this" but the repo already covers the rule, absorb the evidence into the existing carrier instead of creating a page.

When a dropped or absorbed candidate shows that a proper document (docs/, AGENTS.md, spec files) should change, append one suggestion line to .superharness/spec/learnings/pending-doc-updates.md (create it when missing) instead of editing those documents directly; they change through setup-superharness review.

Claim project observations

Use the same single-flight protocol as learn-summarizer when a project trace exists:

1. Atomically create the directory .superharness/learn-summarizer.lock. If it already exists, report that learning is already in progress and stop.
2. Create .superharness/trace.archive/ when needed.
3. List existing processing-*.jsonl snapshots, oldest first. If any exist, resume those snapshots and leave the active trace for the next run.
4. When no processing snapshot exists, atomically move .superharness/trace.jsonl to .superharness/trace.archive/processing-<timestamp>.jsonl before reading it. Hooks can then create a fresh active trace for the next batch.
5. Treat every complete JSONL record in the selected processing snapshots as the current batch. Join learn:signal entries to user:prompt entries by their shared ref. Ignore a malformed final fragment and preserve it for inspection.

Continue with live session context when no project trace exists.

Merge topic pages

Choose a lowercase kebab-case topic name. Write or merge .superharness/spec/learnings/<topic>.md instead of creating duplicate pages.

Each topic page must use this frontmatter:

---
confidence: <0.3|0.5|0.7|0.85|0.9>
evidence: <integer>
last_seen: <YYYY-MM-DD>
tags:
  - <tag>
---

Structure the page body with four sections: ## Trigger (when the rule applies, one line), ## Action (what to do, 1-2 imperative sentences), ## Why (root cause or decision rationale), and ## Evidence (ref / commit / file references, one per line).

Derive confidence from the evidence count; never assign it by judgment alone:

• 0.3: tentative signal without a confirmed correction
• 0.5: exactly 1 confirmed evidence event (one explicit correction or clarification)
• 0.7: 2 independent evidence events
• 0.85: 3 or more independent evidence events
• 0.9: the user explicitly states a durable rule such as "remember this" or "always do this"

One contradicting evidence event or long-term lack of recurrence moves confidence down one band; record the event in ## Evidence either way.

Merge new evidence into the existing rule, remove superseded guidance, and keep the page denser than the source material. Add [[topic]] links when another learning directly explains or constrains the rule.

A promoted_to: <spec-file> frontmatter field marks a rule that setup-superharness has promoted into spec proper. Keep merging evidence into the page as usual and keep the field in place.

Maintain the injected index

Maintain the lowercase .superharness/spec/learnings/index.md. Include a concise link and one-line summary for every topic at confidence 0.7 or higher. Keep topics below 0.7 on their pages and out of the index; the index is the injection unit, so listing a topic is what feeds it back into future sessions.

Finish safely

When a processing snapshot was claimed:

1. Rename it to .superharness/trace.archive/processed-<timestamp>.jsonl after all writes succeed.
2. Update .superharness/learn-state.json with lastSummaryTs and clear nudgedAt.
3. Leave every failed processing snapshot unchanged so the next gate can retry it, and do not update lastSummaryTs after a failed write.
4. Remove .superharness/learn-summarizer.lock in a final cleanup step.

Remove the lock even when no durable learning qualifies. Summarize the affected topics and suggest committing the learning files; do not commit unless the user requested it.