# Audit report template

`audit` writes its output to `.lore/audit/audit-YYYY-MM-DD.md`. This file is read-only with respect to `.lore/*.md` (see main `SKILL.md` Conflict resolution — audit never mutates and never ALERTs).

## Template

```markdown
# Memory Audit Report

> Date: 2026-07-09
> Total entries audited: <N>
> Findings: <X> CONFLICT, <Y> STALE, <Z> UNVERIFIED, <W> BROKEN_CHAIN

## Global (`_global/`)

### CONFLICT
- [DEC-2026-01-20-b1e8] claims "all packages TypeScript strict mode"
  Evidence: `packages/legacy/tsconfig.json` has `"strict": false`
  Note: entry `DEC-2026-01-20-b1e8` carries `#superseded-by:DEC-2026-03-15-c5e1`; if the chain is intact, treat the conflict as a chain-resolution case (see `references/entry-format.md#superseded-by-chain`).

### STALE
- [ARCH-2026-01-15-d7a3] references `nx.json`
  Evidence: file no longer exists at repo root

### UNVERIFIED
- [DEC-2026-02-03-7c19] last verified 2025-09-12 (>90 days)

## Scope: frontend

### CONFLICT
- ...

### STALE
- ...

### UNVERIFIED
- ...

## Summary

Recommended action: run `lore sync` to address these findings.
Audit itself does not modify any entry.
```

## Severity definitions

| Severity | Meaning |
|---|---|
| `CONFLICT` | Code/config directly contradicts the entry content (e.g. memory says `react@18`, `package.json` says `16`). If the entry is in a `#superseded-by` chain, check whether the chain resolves the conflict before reporting. |
| `STALE` | Entry references a resource (file, API, version) that no longer exists |
| `UNVERIFIED` | Entry's reference date — `#verified` if present, else `#added` — is >90 days; needs re-confirmation |
| `BROKEN_CHAIN` | Entry carries `#superseded-by:<id>` but `<id>` is not present in `.lore/` |

## Broken chains

If `audit` finds an entry tagged `#superseded-by:<id>` but `<id>` does not exist anywhere in `.lore/`, surface as a `BROKEN_CHAIN` finding under the scope containing the orphan. Example:

```markdown
## Scope: backend

### BROKEN_CHAIN
- [DEC-2026-07-10-ee31] carries `#superseded-by:DEC-2026-07-10-e45d`
  Evidence: target ID `DEC-2026-07-10-e45d` not found in any `.lore/*.md`. The replacement entry was never written (or was deleted, which lore does not normally do).
  Recommended action: write the replacement entry, or remove the `#superseded-by:` tag.
```

This severity is distinct from `CONFLICT` because the entries don't disagree — one is just orphaned.

## Required rules

- The audit report **never** modifies any `.lore/*.md` file.
- The audit report **never** emits ALERT blocks (ALERT noise is contained to `sync` and `query`).
- Audit is a pure read-and-report operation. To act on findings, the user runs `sync`.

## Evidence format

Each finding includes a one-line `Evidence:` reference pointing to the file path and (when possible) line number that triggered the finding. The agent must verify the evidence exists before writing the report.

# Compatibility policy

This document defines how `lore` evolves without breaking existing user projects. It is the contract between current users and future maintainers. Any change to `.lore/` structure, file formats, Python scripts, mirror templates, or this skill's reference docs must conform to these rules.

## Three principles

1. **Add, never subtract.** New fields, scripts, sections, and reference docs always use new names. Removal is a breaking change: the commit message must be prefixed `BREAKING:` and explain what users need to change.
2. **Readers are forward-compatible.** An older skill reading a newer `.lore/` ignores unknown fields, unknown files, and unknown tags. It never errors on unfamiliar content.
3. **Writers are backward-compatible (during transition).** A newer skill detecting an older `.lore/` reads the older shape, fills missing fields with defaults, and writes only what it intended to change. It never overwrites old data with new defaults.

## Layer-specific rules

### Layer 1: `.lore/.config.json` schema

- `schema_version` is **required** (integer). See `references/config.md` for handling missing/newer/older values.
- Adding a new optional field does not require a schema bump: old readers ignore unknown fields, new readers fill missing fields with defaults. See "Rule of thumb" under Examples below.
- Removing a field is a breaking change. The commit must be prefixed `BREAKING:` and name the field and the migration step the user must take.
- Renaming a field: keep both fields for one release, mark the old field as deprecated in the commit message, and remove in the next breaking release. The user edits their config by hand.

### Layer 2: Entry format

```
- [ARCH-2026-07-10-a3f2] Entry text; reason. #added:2026-07-10 #verified:2026-07-15
```

- IDs (`LAYER-DATE-HASH`) are stable as long as the entry text is unchanged. Editing an entry produces a new ID; old ID stays in history (via git) for `history` queries. `sync`'s `[REFINED]` respects this: tags-only updates keep the ID, body rewrites create a new ID and link the old entry via `#superseded-by`.
- Tag set is a closed set today: `#added`, `#verified`, `#stale`, `#superseded-by`. Adding a new tag is allowed; old skills' tag parsers (which match `(added|verified|stale|superseded-by)`) silently ignore unknown tags. The previous `#archived` tag is no longer part of the vocabulary; old entries carrying it are treated as unknown tags (still parse, semantic meaning is lost — use `#superseded-by` going forward).
- **Never make a tag required.** Required tags break every old entry in every old `.lore/`.

### Layer 3: `.lore/` directory structure

Current canonical layout:

```
.lore/
├── SUMMARY.md
├── .config.json
├── _global/
├── scopes/
├── .archive/      (My notes backups before a user-requested wipe)
├── draft/        (init only — temporary)
└── audit/        (audit only)
```

Rules:
- Adding a new top-level directory (e.g., `rejected/` for rejected entries) is non-breaking.
- Renaming an existing directory is breaking — every reference in `references/*.md`, every script, and every user's project breaks.
- Removing a directory is non-breaking if it was never actually written. The previous `archive/` directory fell into this category and has been removed from the layout. Note: when the user asks to wipe a mirror's My notes, lore archives the old content to `.lore/.archive/` first (see `references/platform-mirrors.md`); that directory is part of the layout above and is **not** an entries archive — it is a user-confirmed backup location only.

### Layer 4: Python scripts

Current scripts: `id_hash.py`, `list_entries.py`, `find_stale.py`, `find_duplicates.py`, `history.py`.

Rules:

- **Renaming is breaking.** All names are part of the public surface; they're referenced from `SKILL.md`, `references/*.md`, and downstream tooling. Don't rename; add a new one with a different name if needed.
- **Removing is breaking.** When a script is removed, the commit is prefixed `BREAKING:` and names the replacement. The removed file is deleted in the same commit.
- **Adding a new script is non-breaking.** Reference it from `SKILL.md` reference index on introduction.
- **Changing output format is breaking for `--json` consumers.** Add a new flag (e.g. `--v2-output`) rather than changing existing output; the old flag keeps old behavior forever.

### Layer 5: Platform mirror files

Mirror files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) follow this contract:

```markdown
<!-- LORE:START -->
## Lore (auto-managed)

... lore content ...
<!-- LORE:END -->

---
## My notes (free edit)

... user content (preserved verbatim) ...
```

Rules:

- `<!-- LORE:START -->` and `<!-- LORE:END -->` are **contract strings** for new mirrors (post-v1). Never rename; never remove. They are the authoritative boundary the skill uses for detection.
- `## Lore (auto-managed)` is a **contract string**. Never rename; never remove. Mirror detection regexes depend on it as a secondary signal.
- `## My notes (free edit)` is a **contract string**. Never rename; never remove. User-written content depends on it.
- The content between `<!-- LORE:START -->` and `<!-- LORE:END -->` is lore's domain; content after `<!-- LORE:END -->` and `---` is the user's. Respect the boundary on every regeneration.
- Pre-v1 mirrors without HTML comments are still detected and preserved via the `---` separator and `## My notes` header. The first `lore mirror` run on such a file offers the user an upgrade prompt (see `references/platform-mirrors.md` rule 5b).
- Adding a new auto-managed section (e.g., `## Sync history (auto-managed)`) is allowed; insert before `<!-- LORE:END -->`. Old skills ignore it.
- Changing the index template body (e.g., adding a "Last mirror:" line) is non-breaking: content-based dedup means unchanged mirrors are not rewritten, so old mirrors stay valid.
- **Backward-write safety**: if the existing mirror has no `## My notes (free edit)` section (e.g., a legacy single-section mirror from a pre-v1 project), the first `lore mirror` run must **append** an empty My notes section rather than overwriting the file.

### Layer 6: reference docs

Current docs: `workflows.md`, `entry-format.md`, `summary-template.md`, `audit-template.md`, `monorepo-detection.md`, `stale-new-markers.md`, `platform-mirrors.md`, `config.md`, `history-command.md`, `compatibility.md` (this file).

Rules:

- **Renaming a reference doc is breaking.** Every external link (issue trackers, blog posts, README badges) breaks. Add a redirect stub instead.
- **Splitting a doc** (e.g., `platform-mirrors.md` → `mirror-index.md` + `mirror-takeover.md`) requires a stub at the old path that points to the new location. Update `SKILL.md` reference index on the same commit.
- **Removing a doc** is breaking. Mark it `<!-- DEPRECATED: see new-location.md -->` for one schema version, then move to `archive/` (in `references/`, not in `.lore/`).
- **Adding a doc** is non-breaking. Add to `SKILL.md` reference index on introduction.

## Migration

There is no automatic migration tool in v1. Upgrades are `git pull` + read the commit history for any `BREAKING:` commits. The user edits their config by hand if a field was renamed or removed.

`list_entries.py` emits a one-time `[WARN]` to stderr if `.lore/.config.json` is missing the `schema_version` field. Add `"schema_version": 1` manually to silence it.

## Deprecation

There is no deprecation registry in v1. A capability slated for removal ships in a commit prefixed `BREAKING:` that names the capability and the migration step. The previous release may emit a one-line `[WARN]` notice when the deprecated capability is used, but there is no automated reminder system.

## CI enforcement

There is no compatibility CI in v1. Verification is the author's responsibility before each release: run `list_entries.py`, `history.py`, `find_stale.py` against a `.lore/` populated by the author's own work, and confirm the output is sensible.

## Examples

### Compatible change (additive)

Adding a new optional field, for example `compress_thresholds.max_entries_per_scope` with default `100`:

- Old configs continue to operate; the new field reads as the default.
- Old skill reading a new config: sees only the fields it knows; ignores the new field.
- New skill reading an old config: detects the missing field and uses the default.
- No upgrade notes needed; the change is invisible to existing users.

**Rule of thumb.** An additive optional change is non-breaking: ship it without bumping anything, no migration steps, no warnings.

### Incompatible change (avoid)

Renaming `mirror_mode` to `render_mode` in a single release:

- Every existing `.lore/.config.json` would silently lose its `mirror_mode: "index"` setting (old field dropped, new field absent → defaults kick in).
- Bad. Instead: keep both fields for one release, mark `mirror_mode` as deprecated in the commit message, then remove `mirror_mode` in the next breaking release.

### Breaking change (commit message)

Removing support for a config value such as `mirror_mode: "full"`:

- The release prints a warning when the value is set; suggests `"index"`.
- A future release hard-rejects `"full"`. Users edit their config by hand.
- The breaking commit message names the change and the manual edit.

## Decision checklist

Before merging any change to lore, answer these questions about its public compatibility surface:

1. Does this change remove or alter an existing `.lore/` field, file format, or directory meaning?
2. Does this change remove or alter a script name, argument, exit code, stdout/JSON shape, or documented behavior that callers may depend on? Internal bug fixes that preserve these contracts are not breaking.
3. Does this change remove or alter any contract string (`## Lore (auto-managed)`, `## My notes (free edit)`, `<!-- LORE:START -->`, `<!-- LORE:END -->`, etc.)?
4. Does this change remove or rename any reference doc filename?
5. Does this change remove or alter the meaning or syntax of an existing entry tag?

Additive changes that leave existing contracts intact (new optional field, optional tag, doc, script, or flag) are non-breaking and ship with a regular commit prefix (`feat:`, `docs:`, `refactor:`).

If any answer above is "yes", the change is breaking and the commit must:
- Be prefixed `BREAKING:` instead of `feat:` / `refactor:`.
- Name what changed and what the user must do in the commit body.

If all answers are "no", the change is non-breaking and ships as a regular commit. This includes implementation-only fixes, corrections to documentation text, and additive optional behavior that follows the layer-specific rules above.

# Configuration reference

`.lore/.config.json` holds user-tunable settings. The file is optional; without it, the skill uses sensible defaults.

## Schema

```json
{
  "schema_version": 1,
  "auto_mirror": true | false,
  "sync_updates_mirror": true | false,
  "sync_trust": "high" | "medium" | "low",
  "mirror_targets": ["CLAUDE.md"], // optional — auto-detected if absent
  "mirror_mode": "index",
  "compress_thresholds": {
    "max_entries": 500,
    "max_days_since_compress": 30
  },
  "sync_thresholds": {
    "min_lines_changed": 50,
    "min_directories_changed": 2
  },
  "last_sync_sha": "f9ca271..."  // set automatically by sync; null on first run
}
```

## Schema version (`schema_version`)

**Required for new configs** (set automatically by `lore init`). Tracks the schema version of `.lore/.config.json` so future releases can detect old configs before writing.

- **Missing** → treated as `schema_version: 1`. A `[WARN]` notice is printed to stderr by `list_entries.py`; add the field manually to silence it.
- **Equal to skill's expected version** → use as-is.
- **Higher than expected** → warn and continue: `list_entries.py` prints a `[WARN]` to stderr and proceeds with best-effort reads (readers are forward-compatible — see `references/compatibility.md`). The user's skill is older than their `.lore/`; recommend pulling the latest lore from upstream.

For the full compatibility policy, see `references/compatibility.md`.

## Field semantics

### `auto_mirror`

Default: `false`.

Controls whether `compress` regenerates platform mirrors automatically after it writes `SUMMARY.md`. It does **not** gate the explicit `lore mirror` command — `lore mirror` always regenerates (with content-based dedup) once `mirror_targets` is resolved.

- `true` — `compress` regenerates mirrors automatically
- `false` — `compress` asks per target before writing

Note: this flag does **not** affect `sync`. By default `sync` does not touch mirrors at all (see `sync_updates_mirror`).

### `sync_updates_mirror`

Default: `false`.

Controls whether `sync` regenerates platform mirrors as a side effect.

- `false` — `sync` only writes `.lore/*.md`. Mirrors are updated by `compress` or explicit `lore mirror`. This is the recommended setting to avoid cluttering `git log` of mirror files.
- `true` — `sync` regenerates mirrors (with content-based dedup) after the canonical change is accepted. Restore this setting if the old "update everything on every sync" behavior is preferred.

### `sync_trust`

Default: `"medium"`.

Controls how much confirmation `sync` requires for individual change types.

- `"high"` — auto-apply everything, including `NEW` and `STALE`. Only `ALERT` blocks interrupt.
- `"medium"` — auto-apply low-risk changes (de-duplicate hits, tags-only REFINEDs). Body-changing REFINEDs, `NEW`, `STALE`, and `ALERT` require confirmation.
- `"low"` — every change requires confirmation, including de-duplicate hits and tags-only REFINEDs.

### `mirror_targets`

Default: auto-detected at runtime (see "If absent" below).

Array of file paths (relative to project root) that should be kept in sync with `.lore/*`. Path must match one of the platform entries in `references/platform-mirrors.md`. Unsupported paths trigger a warning at config-load time.

If absent: mirror targets are auto-detected at runtime by scanning the project root for existing platform files. If no platform files exist, the user is asked via a multi-select question during `init`, the first `mirror` call, or `compress` (when `auto_mirror: true`). See `references/platform-mirrors.md` for the resolution algorithm.

If present: used verbatim. Empty array `[]` is valid and disables mirror generation.

When auto-detection is in effect, `lore init` populates this field with the user's selections so subsequent runs are silent.

### `mirror_mode`

Default: `"index"`.

Only `"index"` is accepted. The mirror renders a small index structure pointing into `.lore/` (see `references/platform-mirrors.md` for the template and adaptive rendering rules). Per-session token cost stays flat (~600 B worst case, including a one-line operational opening and per-scope descriptions) regardless of entry count.

Any other value (e.g., the historical `"summary"` or `"full"`) is rejected at config-load time with an error. Remove the field, or set it to `"index"`.

### `compress_thresholds`

Defaults: `{"max_entries": 500, "max_days_since_compress": 30}`.

`sync` checks these silently and emits a `[COMPRESS NOTICE]` when tripped. See `SKILL.md` sync procedure.

### `sync_thresholds`

Defaults: `{"min_lines_changed": 50, "min_directories_changed": 2}`.

`sync` only proposes an update when at least one trigger threshold is met (see `SKILL.md` sync trigger threshold). Lowering these values means `sync` proposes updates more often.

### `last_sync_sha`

Default: absent (treated as `null`).

The git commit SHA from which the next `sync` will compute its delta. Written automatically by `sync` after every successful `.lore/*` update. Optional and additive — old configs without it keep working.

- **Absent or `null`** — when HEAD exists, `sync` falls back to `git diff HEAD` (net staged and unstaged changes). Already-committed changes between two syncs are invisible.
- **Set to a reachable SHA** — `sync` uses `git diff <last_sync_sha>..HEAD` for committed changes plus `git diff HEAD` for net staged and unstaged changes. This is the recommended state and lets batched commits be captured by a single later sync.
- **Set to an unreachable SHA** (e.g., after `git rebase` or a force-push that orphaned the SHA) — `sync` prints a `[WARN]` to stderr and falls back to the working-tree diff alone. The next successful sync resets the baseline.
- **Empty repo** (no commits yet) — the field is `null`; skip HEAD-based diffs. Enumerate indexed and untracked paths with `git ls-files --cached --others --exclude-standard` and scan their current working-tree contents, as described in `references/workflows.md` sync step 1.

With an existing HEAD, also enumerate untracked files via `git ls-files --others --exclude-standard` and scan them separately; diffs do not include these files.

## Editing the config

Edit `.lore/.config.json` directly. After editing:

- `sync` and `compress` re-read the config on every run; no restart needed.
- Invalid JSON → fall back to defaults + warn the user.
- For breaking-config changes, see `references/compatibility.md` and look for the `BREAKING:` commit in the project's git history.

# Entry format reference

Detailed specification for `.lore/` entries. The main `SKILL.md` covers entry structure briefly; this file is the full spec.

## Bullet structure

Each entry is a Markdown bullet (≤ 2 lines), containing:

- **Layer prefix**: `ARCH`, `DEC`, or `CONV`
- **ID**: `LAYER-YYYY-MM-DD-xxxx` where `xxxx` is a 4-char content hash
- **Inline status tags** (at the end of the entry)

```markdown
- [ARCH-2026-07-09-a3f2] Use Next.js App Router; reason: streaming + RSC. #added:2026-07-09
- [DEC-2026-02-03-7c19] Chose Zustand over Redux; reason: 60% less boilerplate. Alternatives: Redux Toolkit, Jotai. #added:2026-02-03
- [CONV-2026-01-20-b1e8] Never commit secrets; use `dotenv` + `.env.local` (gitignored). #added:2026-01-20
- [ARCH-2026-03-10-a1b2] Use TanStack Query for all server state. #added:2026-03-10 #verified:2026-06-15
```

## ID generation

The 4-char `xxxx` is the first 4 hex chars of `sha256(entry text)`. This makes IDs:

- **Deterministic**: the exact same entry text produces the same hash
- **Coordination-light**: concurrent agents can compute IDs independently, with the collision check below as the safeguard
- **Searchable**: tools can locate stored entries by their IDs

Identical text producing the same hash is a duplicate, not a collision. A collision is when two different entry bodies produce the same 4-character hash. If that would create the same full ID, keep the existing entry unchanged, add a meaningful qualifier (such as scope, object, or applicability) to the new body, and recompute its hash. Do not resolve collisions with invisible whitespace.

### Updating an entry (REFINED)

Because the ID hashes the body, **any body change produces a new ID**. `sync`'s `[REFINED]` proposal follows this rule: tags-only updates (body unchanged) keep the ID; body rewrites create a new entry with a freshly hashed ID and link the old one via `#superseded-by:<new-id>` (see `references/stale-new-markers.md`).

## Tag specification

| Tag | Meaning |
|---|---|
| `#added:YYYY-MM-DD` | When the entry was created |
| `#verified:YYYY-MM-DD` | Last time a human or audit confirmed the entry is still true |
| `#stale:YYYY-MM-DD` | Flagged by `sync` as no longer accurate. Two cases: (a) the entry was superseded — pair with `#superseded-by:<new-id>`; (b) deprecated with no successor — alone. |
| `#superseded-by:LAYER-YYYY-MM-DD-xxxx` | Points to the entry that replaces this one. When present, it implies staleness; the `#stale:<date>` tag is optional but encouraged for clarity. The `xxxx` is the 4-hex content hash of the replacement. |

Multiple tags can co-exist on one entry (e.g. `#added:2026-01-15 #verified:2026-06-01`).

**Active-entry rule:** an entry is active when it has neither `#stale:<date>` nor `#superseded-by:<id>`. In `list_entries.py --json`, check that `"stale"` is absent from `tags` and `replaced_by` is unset. Apply this rule to current-state `query` answers, `compress` selection, and sync's verification-only duplicate handling. It excludes stale entries even without a successor. Entries with no tags remain eligible; age alone is a review signal, not proof of invalidity. Historical queries and audits may still read inactive entries and must identify their status. This is a consumer rule; `list_entries.py` continues to enumerate all entries.

## Cross-file references

When `SUMMARY.md` or another file references an entry, qualify it with the file path to avoid ID collisions across scopes:

```
[scopes/frontend/DECISIONS.md#DEC-2026-02-03-7c19]
[_global/CONVENTIONS.md#CONV-2026-01-20-b1e8]
```

The path is relative to `.lore/`.

## Splitting vs. single entries

If a fact can't fit in ≤ 2 lines, split into multiple entries and cross-reference them by ID:

```markdown
- [ARCH-2026-07-09-a3f2] Use Next.js App Router. #added:2026-07-09
- [DEC-2026-07-09-b1e8] Reason: streaming + RSC, see [ARCH-2026-07-09-a3f2]. #added:2026-07-09
```

Instead of stuffing them into a single overly long bullet.

## Superseded-by chain

When an entry is replaced by another (e.g. a tech-stack swap, a convention reversal), the old entry carries `#superseded-by:<new-id>` alongside `#stale:<date>`. This turns the replacement relationship from prose into data that scripts can walk.

Syntax: `#superseded-by:LAYER-YYYY-MM-DD-xxxx` — the replacement entry's full ID. The replacement entry itself carries no back-reference; its `#verified:DATE` and `#added:DATE` are sufficient.

Worked example — bcrypt replaces SHA-256 in `scopes/backend/DECISIONS.md`:

```markdown
- [DEC-2026-07-10-ee31] SHA-256 + salt for password hashing; reason: no native dep, deterministic. #added:2026-07-10 #stale:2026-07-10 #superseded-by:DEC-2026-07-10-e45d
- [DEC-2026-07-10-e45d] Use bcrypt (rounds=12) for password hashing; reason: industry standard, built-in salt. #added:2026-07-10
```

Consumers:

- `find_stale.py --json` — groups stale entries by their `replaced_by` target; flags chains where the target ID does not exist (broken chain).
- `history.py --follow-superseded <id>` — prints the requested entry first, followed by each successor in chain order.
- `compress` — applies the active-entry rule above when selecting the 3–5 entries per (scope, layer).
- `audit` — when reporting CONFLICT between two entries, surfaces the chain if both belong to one.

Constraints:

- The tag is **optional**. Old entries without it continue to work; old skills ignore it.
- **At most one `#superseded-by` tag per entry.** Successive replacements form a chain (A → B → C), never a fork: an entry is replaced by one successor at a time. If an entry carries more than one tag, `list_entries.py` warns and keeps the first.
- Cross-file references: qualify the ID with its `.lore/`-relative file path whenever the target file is known. If a legacy bare-ID reference matches more than one file, prefer the entry in the same scope and report the ambiguity rather than guessing silently.

## What counts as "atomic"

A fact is atomic if it answers one primary question. A brief inline reason may qualify the same ARCH fact within the two-line limit; it does not by itself require a separate DEC entry. Follow the Layer semantics in `SKILL.md`:

- "What is the frontend framework?" → `ARCH` entry about Next.js
- "Why Next.js not Remix?" → `DEC` entry referencing the `ARCH` entry

Split independent facts, alternatives, or tradeoffs into separate entries; detailed rationale that needs its own entry belongs in DEC. The presence of `reason:` or `because` alone does not require a split.

# `lore history` — full specification

Read-only command. Lists git commits related to a memory entry, a file,
or a scope, since the entry's `#added` date. Output to stdout only;
never writes to `.lore/`.

## Synopsis

```
lore history <entry-id>
lore history <file-path>
lore history --scope=<name>
lore history --since=<YYYY-MM-DD>
lore history --follow-superseded
lore history --json
```

## Forms

| Form | Argument shape | Example | Behavior |
|---|---|---|---|
| Entry | `[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}` | `lore history DEC-2026-02-03-7c19` | Locate entry in `.lore/`, derive its `#added` date and code file, then `git log` since that date. |
| File  | contains `/` or starts with `.` | `lore history frontend/src/store/index.ts` | Run `git log --since=1970-01-01` on the given path. |
| Scope | `--scope=<name>` only | `lore history --scope=frontend` | For each `*.md` in `.lore/scopes/<name>/`, run file form on the lore file path itself. |

### `--follow-superseded`

When set on the entry form, prints the requested entry's git history followed by every successor in `#superseded-by` chain order. Stops when an entry has no `#superseded-by` tag or the chain reaches a non-existent ID. Output prepends a `## Chain` section listing each entry's ID and file path before the per-entry `git log` blocks.

Example:

```
$ lore history --follow-superseded DEC-2026-07-10-ee31

# history: [DEC-2026-07-10-ee31] --follow-superseded

## Chain
1. [DEC-2026-07-10-ee31] (scopes/backend/DECISIONS.md) — SHA-256 + salt
   → superseded-by → DEC-2026-07-10-e45d
2. [DEC-2026-07-10-e45d] (scopes/backend/DECISIONS.md) — bcrypt (rounds=12)
   → no successor

# history: [DEC-2026-07-10-ee31]

> Entry: scopes/backend/DECISIONS.md
> Since: 2026-07-10
> File: backend/app/auth.py
> Commits: 3 (showing all)

...
```

## Code-file resolution (entry form)

Priority:

1. First backtick-quoted path in entry.text that looks like a file
   (e.g. `src/store/index.ts`).
2. Scope directory at the project root (e.g. entry scope `frontend` →
   `frontend/`).
3. Project root `.` for entries in `_global/`.

If the regex finds no path, falls back to the scope directory.

## Data source

`git` CLI only. No network calls. Requires:

- A git repository at or above the current working directory.
- The `git` executable on `PATH`.

## Output

### Markdown (default)

Header block: `Entry`, `Since`, `File`, `Commits`. One section per
commit with `## <short-hash> (<date>, <author>)`, subject, optional
`Body:` line, optional `Refs:` line. A "Suggested next step" footer
appears only when at least one commit is found.

### JSON (`--json`)

```json
{
  "entry_id": "DEC-2026-02-03-7c19",
  "lore_file": "scopes/frontend/DECISIONS.md",
  "code_file": "frontend/src/store/index.ts",
  "since": "2026-02-03",
  "since_source": "entry_added",
  "chain": null,
  "commits": [
    {
      "hash": "...",
      "short": "abc1234",
      "author": "alice",
      "date": "2026-04-12",
      "subject": "Use Zustand v4",
      "body": "Migrate notes here.",
      "refs": ["#234"]
    }
  ]
}
```

When `--follow-superseded` is set, `chain` is an array of `{entry_id, lore_file, code_file, since}` for each successor; otherwise `null`.

## Error handling

| Condition | Exit code | Message |
|---|---|---|
| No argument | 2 | `error: missing argument` |
| Unrecognized argument | 2 | `error: unrecognized argument: <arg>` |
| `.lore/` not found | 2 | `error: .lore/ not found. Run 'lore init' first.` |
| Entry not in index | 3 | `error: Entry <id> not found. Available: ...` |
| Not a git repo | 4 | `error: Not a git repository. ...` |
| `git` missing | 5 | `error: git executable not found on PATH.` |
| Bad scope name | 6 | `error: Scope '<name>' not found. Available: ...` |
| `git log` failure | 7 | `error: git log failed: <stderr>` |
| Entry missing `#added` | 0 (warning) | `warning: entry has no #added tag; using full history` |

## Exit codes summary

- `0` — success (including "0 commits found" case)
- `2` — usage / configuration error
- `3` — entry lookup failure
- `4` — not a git repo
- `5` — git CLI missing
- `6` — invalid scope
- `7` — git command failed

## Why this exists

`lore sync` reads `git diff` (working-tree deltas). It never reads
commit history. `lore history` fills that gap: given a memory entry,
it shows the commits that introduced or modified the underlying code,
letting the agent answer "why does this decision exist?" with a pointer
to the original commit instead of an LLM-generated guess.

## `--since` normalization (same-day commit safety)

`git log --since=YYYY-MM-DD` interpretation is version-dependent.
Older git versions parse a bare date as the user's local-timezone
midnight; newer versions parse it as UTC midnight. A commit made early
in the day can therefore be silently dropped when filtering by a
same-day `#added` tag.

To avoid this, `lore history` normalizes date-only inputs to an explicit
ISO-8601 timestamp before passing them to `git log`. The transformation
is `YYYY-MM-DD` → `YYYY-MM-DD T 00:00:00`, applied at the entry-form
extraction point and at the file-form `--since` argument. Strings that
already contain a time component (a `T` or a space) are passed through
unchanged.

This means the JSON output's `since` field will show e.g.
`"2026-07-13T00:00:00"` for a date-only `#added`, not `"2026-07-13"`.
The same-day commit you want to surface is now guaranteed to be in the
result, regardless of the host's git version or the user's timezone.

## Known issues

### Cross-timezone `#added` interpretation (unfixed)

The normalization in the previous section only resolves the *git version*
ambiguity. A second, deeper ambiguity remains: `#added` is a date-only
string written by the **author** of the entry, but `git log --since=`
interprets it in the **runner's** local timezone.

**Scenario** (uncovered, not yet reproduced in a real project):

1. Author in `+0800` commits at 2026-07-13 02:00 `+0800`
   (= 2026-07-12 18:00 UTC) and adds an entry with
   `#added: 2026-07-13` (their local date).
2. Runner in `PST (UTC-8)` invokes `lore history DEC-…`.
3. `git log --since=2026-07-13T00:00:00` is interpreted in the
   runner's PST as 2026-07-13 00:00 PST (= 2026-07-13 08:00 UTC).
4. The commit at 2026-07-12 18:00 UTC is **before** 2026-07-13 08:00
   UTC, so the commit is **excluded** from history.
5. From the runner's perspective, the commit looks "older than the
   entry" even though both occurred on the same calendar day in the
   author's timezone.

This is a real bug, but it is **not fixed** in this release because:

- No cross-timezone reproduction has been reported.
- Fixing it would require either (a) subtracting one day from
  `#added` before passing to `git log`, which occasionally over-includes
  the previous day, or (b) capturing the exact UTC time of `#added` in
  the entry format, which is a breaking change to the entry schema.

**Workaround today**: pass `--since=<#added - 1 day>` explicitly when
the runner is in a timezone west of the author's.

**Trigger to fix**: any user report of "history missed a commit that I
know is related" with cross-timezone evidence. Until then, the field
remains a known issue rather than a known fix.

# Monorepo detection rules

`init` needs to identify whether the project is a monorepo and how to split scopes. This file lists the detection rules per tool.

## Detection order

Check markers in this order; the first match determines scope layout:

1. pnpm workspaces
2. Yarn workspaces
3. npm workspaces
4. Lerna
5. Nx
6. Rush
7. Cargo workspaces
8. Go workspaces
9. Bazel

No monorepo marker → fall back to `_global/` only (single-scope project).

## Per-tool rules

### pnpm workspaces
- Marker: `pnpm-workspace.yaml` at repo root
- Read: `packages:` field, e.g. `packages: [frontend, backend, shared/*]`
- One scope per listed package directory

### Yarn workspaces (classic / berry)
- Marker: `package.json` top-level `workspaces` field
- Example: `"workspaces": ["packages/*"]`
- One scope per glob-resolved directory

### npm workspaces
- Same as Yarn (npm 7+ uses the same `package.json#workspaces` field)

### Lerna
- Marker: `lerna.json`
- Read: `packages` field (array of paths)
- One scope per path

### Nx
- Marker: `nx.json` or `workspace.json`
- Nx typically delegates package discovery to npm/yarn workspaces — read both
- One scope per resolved package

### Rush
- Marker: `rush.json`
- Read: `projects` array (each entry has a `packageName` and directory)

### Cargo workspaces
- Marker: `Cargo.toml` top-level `[workspace]` table
- Read: `members` array
- One scope per member crate

### Go workspaces
- Marker: `go.work`
- Read: `use` directives (one per module)
- One scope per module

### Bazel
- Marker: `MODULE.bazel` or `WORKSPACE`
- Bazel repos are deeply nested; precise extraction is fragile. Fallback: collapse to one scope per top-level directory and let the user override.

## Scope naming

- Default: directory name (`frontend/` → scope `frontend`)
- If multiple directories belong to one logical scope (e.g. `packages/web` and `packages/mobile` are both "frontend"), agent should ask the user whether to merge
- Nested monorepos (`packages/web/components/`) are **not** supported as nested scopes. Flatten to `web`.

## When detection fails

If detection succeeds but the resulting scopes don't match the user's mental model, agent should:

1. Show the proposed scope list
2. Let the user rename / merge / split scopes
3. Proceed with the corrected list

This is part of the init confirmation step (see main `SKILL.md` init step 2).

# Platform mirrors reference

How `.lore/*` content gets mirrored to platform-specific config files. The main `SKILL.md` covers the high-level rules; this file holds the per-platform mapping, the two-section file structure, and the algorithm that resolves which files to generate (auto-detect by default, explicit override available).

## Platform → file mapping

| Platform | File (default) | Also accepted |
|---|---|---|
| Claude Code | `CLAUDE.md` (root) | `.claude/CLAUDE.md` |
| Cursor | `.cursorrules` (root) | `.cursor/rules/*.mdc` |
| Cline | `.clinerules` (root) | — |
| Aider | `AGENTS.md` (root) | `CONVENTIONS.md` |
| OpenAI Codex | `AGENTS.md` (root) | — |
| OpenCode | `AGENTS.md` (root) | — |
| Windsurf | `.windsurfrules` (root) | — |
| GitHub Copilot | `.github/copilot-instructions.md` | — |
| Continue.dev | `.continue/rules/lore.md` | — |
| LangGraph / DeepAgents | (no file — inject at runtime) | — |

For LangGraph and DeepAgents, the skill does not produce a mirror file. Read `.lore/*.md` directly or ingest into the system prompt at runtime — that ingestion is the user's responsibility.

## Resolution: how `mirror_targets` is computed

When the skill needs to know which platform files to generate (during `init`, `mirror`, and `compress` when `auto_mirror: true`), it runs the following procedure:

```
resolve_mirror_targets(config, repo_root):

    # 1. If config has mirror_targets set, use it verbatim (auto-detect skipped)
    if "mirror_targets" in config:
        return list(config["mirror_targets"])

    # 2. Scan repo root for existing platform files (see Scan candidates)
    detected = scan_existing_platform_files(repo_root)
    if detected:
        return detected

    # 3. Nothing detected → ask user via multi-select, persist to config, return
    selected = ask_user_multi_select(AGENT_CHOICES)
    write_mirror_targets_to_config(selected)
    return selected
```

This is the core resolution used by all three commands. `init` extends it with classification and per-file takeover steps — see "Init-time behavior (full procedure)" below.

### Scan candidates

The auto-detect step checks for the following paths at `repo_root`:

```
CLAUDE.md
.claude/CLAUDE.md
.cursorrules
.clinerules
AGENTS.md
CONVENTIONS.md
.windsurfrules
.github/copilot-instructions.md
.continue/rules/lore.md
.cursor/rules/*.mdc        # glob: any .mdc file under .cursor/rules/
```

These match the platform table above (default + "Also accepted" filenames). The `.cursor/rules/*.mdc` entry is a glob — it's a hit if `.cursor/rules/` exists and contains at least one `.mdc` file.

### Multi-select agent choices

When Step 3 fires, present this question to the user:

| Choice | Primary file written |
|---|---|
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursorrules` |
| Cline | `.clinerules` |
| Aider | `AGENTS.md` |
| Codex | `AGENTS.md` |
| OpenCode | `AGENTS.md` |
| Windsurf | `.windsurfrules` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Continue.dev | `.continue/rules/lore.md` |

Aider, Codex, and OpenCode all map to `AGENTS.md`. Selecting any combination produces one entry. Selecting nothing is valid — writes `mirror_targets: []` (no mirrors generated).

### When this runs

- `lore init` — always interactive.
- `lore mirror` when `mirror_targets` is absent — also interactive (skill is invoked through chat).
- `lore compress` (when `auto_mirror: true`) — also goes through this resolution if `mirror_targets` is absent.

Both paths use the same function. Once `init` has run, `mirror_targets` is set, so subsequent `mirror` calls hit Step 1 and are silent.

## Two-section file structure

Every mirror file is split into two sections by a `---` separator. The top section is Skill-managed and rewritten on mirror regeneration. The bottom section is user-editable and preserved verbatim.

```markdown
<!-- LORE:START -->
## Lore (auto-managed)

# .lore SUMMARY (synced 2026-07-09)

> Last compressed: 2026-07-09
> Total entries: 247 across 3 scopes

## Global
- Monorepo with pnpm workspaces + Turborepo — [_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3]
...
<!-- LORE:END -->

---

## My notes (free edit)

- Keep answers concise
- Currently refactoring the user auth module
- Prefer English
```

The `<!-- LORE:START -->` and `<!-- LORE:END -->` HTML comments are the canonical boundary markers for new mirrors (see rule 5a). The `---` separator is a literal Markdown horizontal rule. Both sections are plain Markdown so any agent or editor can render them normally.

### Section detection rules

When syncing a mirror file:

1. If the file contains `---` on its own line, that line is the boundary. Everything above is the Lore section, everything below is My notes.
2. If the file contains a `## My notes` header, the My notes section starts at that header and goes to EOF.
3. If neither marker is present, the entire file is treated as the Lore section (i.e. no My notes section). Subsequent sync appends a separator + empty My notes section.
4. If the file is missing the `## Lore` header but has `## My notes`, the entire file is treated as user notes. Skill does not write to it. User is asked to confirm before sync restructures the file.
5. **Section boundary markers (canonical form is HTML comments)**:

   a) **New mirrors (post-v1 skill release)**: the canonical boundary is
      `<!-- LORE:START -->` and `<!-- LORE:END -->` HTML comments. The
      skill emits these on every regeneration. The `## Lore (auto-managed)`
      header inside the start marker and the `---` separator after the
      end marker are still required for human readers and as secondary
      signals, but the HTML comments are the **authoritative** boundary
      the skill uses for detection. New mirrors **must** include the HTML
      comment markers.

   b) **Existing pre-v1 mirrors (legacy form)**: the `---` line and
      `## My notes (free edit)` header form continues to be detected
      and preserved by rules 1–4. The skill does **not** restructure
      an existing mirror that lacks HTML comments. The first
      `lore mirror` run on such a file asks the user once:
      "Add HTML markers (recommended)" or "Keep legacy form". The user
      can upgrade a legacy mirror later by running `lore mirror` and
      accepting the prompt, or by manually adding the HTML comments.

   c) **Detection priority when both forms are present**: HTML comments
      win. The skill uses them as the authoritative boundary; the `---`
      and `## My notes` are not consulted for boundary detection but are
      still respected for content placement.

## Sync-time behavior

**`sync` does not regenerate platform mirrors.** This is intentional — see the "Mirror update triggers" section in `SKILL.md`. The skill only writes `.lore/*.md` during `sync`. To update mirrors after `sync`, the user runs `lore mirror` (or `compress`, which calls mirror generation as a side effect).

If a project needs the old behavior (mirror updates on every `sync`), set `sync_updates_mirror: true` in `.lore/.config.json`.

## Mirror-time behavior (`lore mirror`)

This is the actual write step for platform mirrors.

1. Read the current state of `.lore/SUMMARY.md` and the scope-tagged index.
2. For each configured mirror target, read the existing file and detect the section boundary.
3. Compute the new Lore section content.
4. **Content-based dedup**: if the new Lore section content is byte-identical to the existing one, skip writing. Report "No changes needed: `<file>`".
5. If different, replace the Lore section (full rewrite, no merge with previous content). Preserve the My notes section verbatim.
6. Write the file back. Report "Mirror updated: `<file>`".

The content-based dedup step (4) is the key reason `mirror` can be run frequently without polluting `git log` — most invocations will be no-ops once the mirror is in sync.

## Init-time behavior (full procedure)

The `init` command extends the resolution algorithm above with classification and per-file takeover steps. The full procedure:

1. **Check whether `.lore/` exists.**
   - Absent → create `.lore/` and write an initial empty config.
   - Present → load existing `.lore/.config.json` (use defaults if missing).

2. **Scan existing platform files** in repo root using the same candidate list as the resolution algorithm. Result: list of paths that exist.

3. **Classify each detected file** into one of three classes:
   - **Class (a)** — already a lore mirror: contains `## Lore` section.
   - **Class (b)** — user-written: contains `## My notes` but no `## Lore`.
   - **Class (c)** — unmarked: neither header present.

   For class (b) and (c) files, present a per-file choice:
   - **Take over**: file becomes a two-section mirror; existing content is preserved as My notes.
   - **Preserve as-is**: file is left alone; NOT added to `mirror_targets`.
   - **Abort**: exit init entirely. `.lore/` may exist (from Step 1) but no `mirror_targets` is written.

   Class (a) files are auto-included in `mirror_targets`.

4. **Multi-select question.** "Which agents do you use in this project?" Default pre-selection: every agent corresponding to a class (a) file. Empty selection is allowed — but class (a) files still get included via Step 5. Unlike `mirror` / `compress` (which follow the resolution algorithm's silent return-on-detect), `init` always asks — this is how the user adds agents whose files don't exist yet.

5. **Compute final `mirror_targets`** by combining three sources and deduplicating:
   - All class (a) files from Step 3 (always included, regardless of Step 4 selection).
   - Files chosen via "take over" in Step 3.
   - Primary files for additional agents the user selected in Step 4 that aren't already covered.

   Dedup: Aider and Codex both map to `AGENTS.md` and collapse to one entry.

6. **Write `.lore/.config.json`** with `mirror_targets` populated.

7. **Generate initial mirror files** for each target:
   - File absent → full template (`<!-- LORE:START -->` + `## Lore` + content + `<!-- LORE:END -->` + `---` + empty `## My notes`).
   - File present with `## Lore` → refresh Lore section, preserve My notes verbatim.
   - File present and "take over" chosen → old content becomes My notes, new `## Lore` above.
   - File present and "preserve" chosen → no write.

For each generated mirror file, the section template is:

```
<!-- LORE:START -->
## Lore (auto-managed)

<initial or refreshed Lore content>
<!-- LORE:END -->

---

## My notes (free edit)

<preserved or empty>
```

## What gets mirrored

The mirror's Lore section is an **index** into `.lore/` — not a copy of its content. This keeps per-session token cost flat (~600 B worst case, regardless of project size) and aligns with how platform instruction files (`CLAUDE.md`, `.cursorrules`, etc.) are designed to be used: as small pointers that tell the agent where to find detail on demand.

The agent generating the mirror walks `.lore/` and emits the structure below. Sections appear only when their content exists (adaptive rendering).

### Index template

```
<!-- LORE:START -->
## Lore (auto-managed)

Project memory at `.lore/`. Before project-specific questions, read `.lore/SUMMARY.md` as the digest, then open the referenced entries (`.lore/_global/`, `.lore/scopes/`) for the full text before answering or deciding; cite entry IDs (e.g. `_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3`) when using memory.

**Structure**:
- Digest: `.lore/SUMMARY.md` (top-level overview)
- Global: `.lore/_global/` (architecture, decisions, conventions)
- Scopes: `.lore/scopes/`
  - `.lore/scopes/<scope_name>/` (<description>)
  - `.lore/scopes/<scope_name>/`
  ...

**Query**: `lore query <term>` or `lore query <scope>:<term>`
**Update**: see the `lore` skill (init / sync / query / audit / compress / mirror / history)
<!-- LORE:END -->

---
## My notes (free edit)
```

The `<!-- LORE:START -->` / `<!-- LORE:END -->` markers, `## Lore (auto-managed)` opener, `---` separator, and `## My notes (free edit)` closer are **always present** in new mirrors — only the `**Structure**:` body varies with adaptive rendering. Agent preserves the My notes section verbatim across regenerations.

### Field sources

- `<scope_name>` — directory name under `.lore/scopes/`. Each scope's full path is `.lore/scopes/<scope_name>/`.
- `<description>` — extracted from `.lore/scopes/<scope_name>/ARCHITECTURE.md` via the HTML comment `<!-- description: ... -->`. See "Scope description extraction" below. If absent, the description is omitted (scope row still appears, just without parenthetical).

The index does **not** track the project's source-directory mapping for each scope (e.g. `packages/frontend/` for the `frontend` scope). Source paths are detected by `references/monorepo-detection.md` at init time but not persisted in `.lore/`. If a user needs source paths surfaced in the mirror, that mapping belongs in the project's own docs.

### Section visibility rules

| Section | Visible when |
|---|---|
| `Digest:` line | always |
| `Global:` line | `.lore/_global/` exists and has any entry |
| `Scopes:` block | at least one scope directory exists under `.lore/` |
| `Query:` line | always |
| `Update:` line | always |

### Adaptive renderings

Only the `**Structure**:` body varies. The `<!-- LORE:START -->` / `<!-- LORE:END -->` markers, `## Lore (auto-managed)` opener, the **first-line instruction** (see below), `---` separator, and `## My notes (free edit)` closer are always present and unchanged in new mirrors.

**First-line instruction.** The opening sentence after `## Lore (auto-managed)` is the agent-facing imperative that triggers memory lookup (e.g. "Before project-specific questions, read `.lore/SUMMARY.md` as the digest, then open the referenced entries for the full text before answering or deciding."). It is constant across all renderings (empty / single-scope / multi-scope) because the agent's responsibility is the same regardless of project shape. Editing this sentence is a template-body change (non-breaking per `references/compatibility.md`); content-based dedup means existing mirrors keep their old opening until regenerated.

**Empty project** (just initialized, no entries yet):

```
<!-- LORE:START -->
## Lore (auto-managed)

Project memory at `.lore/`. Before project-specific questions, read `.lore/SUMMARY.md` as the digest, then open the referenced entries (`.lore/_global/`, `.lore/scopes/`) for the full text before answering or deciding; cite entry IDs (e.g. `_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3`) when using memory.

**Structure**:
- Digest: `.lore/SUMMARY.md` (top-level overview)

**Query**: `lore query <term>`
**Update**: see the `lore` skill
<!-- LORE:END -->

---
## My notes (free edit)
```

`Global:` and `Scopes:` blocks omitted.

**Single-scope project**:

```
**Structure**:
- Digest: `.lore/SUMMARY.md`
- Global: `.lore/_global/`
- Scopes: `.lore/scopes/`
  - `.lore/scopes/frontend/` (React 18 + TypeScript)
```

`Scopes:` block has one entry.

**Monorepo with multiple scopes**:

```
**Structure**:
- Digest: `.lore/SUMMARY.md`
- Global: `.lore/_global/`
- Scopes: `.lore/scopes/`
  - `.lore/scopes/frontend/` (React 18 + TypeScript)
  - `.lore/scopes/backend/` (PostgreSQL + Prisma)
  - `.lore/scopes/shared/`
```

### Scope description extraction

The agent scans `.lore/scopes/<scope_name>/ARCHITECTURE.md` for the **first line matching** `<!-- description: <text> -->` (anchored to start of line; `description:` literal). Rules:

- **First match wins.** If multiple `<!-- description: ... -->` lines exist, only the first is used.
- **`<text>` is single-line.** A comment must not contain a newline before `-->`. Multi-line comments are ignored.
- **Whitespace trimmed.** Leading and trailing whitespace inside `<text>` is stripped.
- **No match → no description.** The scope row appears without parenthetical; the row is not removed.

Example `ARCHITECTURE.md` with description:

```
<!-- description: React 18 + TypeScript frontend -->
# Frontend Architecture

All UI code lives here. ...
```

### Scope ordering

Scope rows in the `Scopes:` block are emitted in **alphabetical order** by `<scope_name>`. Pinning order is important: the content-based dedup step compares byte-for-byte, so any order change between runs causes spurious "Mirror updated" reports.

### What does NOT trigger mirror regeneration

Index content does not change when:
- Individual entries are edited
- `SUMMARY.md` content is updated (the index only points to its path)
- Entry counts change
- A scope's `ARCHITECTURE.md` content changes (only the `<!-- description: -->` comment affects the index)

Index content changes require regeneration when:
- A new scope directory is added under `.lore/`
- A scope is removed
- A scope's `ARCHITECTURE.md` `<!-- description: -->` line changes
- `.lore/_global/` gains or loses its first entry (Global section visibility flips)

## Manual operations

Regeneration is not a blind rewrite: each target's two-section structure is validated first, and anomalies are reported to the user instead of overwritten (see "Section detection rules" above). My notes is preserved verbatim across regenerations; if the user asks to wipe a target's My notes, archive the old content to `.lore/.archive/<file>-<date>.md` first, then write a clean mirror.

## Trigger rules

| Trigger | Behavior |
|---|---|
| `init` confirms draft | Auto-generate mirrors for all configured targets using the init-time rules above. |
| `sync` proposal accepted | Writes to `.lore/*.md` only. Does **not** touch mirrors. User runs `lore mirror` separately to publish. (Override: set `sync_updates_mirror: true` in config to restore old behavior.) |
| `compress` completes | If `auto_mirror: true`, regenerate mirrors (with content-based dedup). Otherwise ask per target. |
| `lore mirror` | Regenerate all configured targets with content-based dedup. |
| `query` / `audit` | Never touches mirrors. |

# Stale / New marking convention

For changes that require confirmation under `sync_trust`, `sync` emits one or more of these markers and waits for the user to accept or reject them. Changes permitted for automatic application are written without per-item confirmation and reported in the sync result.

## Marker types

| Marker | Purpose |
|---|---|
| `[NEW]` | Propose adding a new entry |
| `[STALE]` | Propose marking an existing entry as superseded/contradicted |
| `[REFINED]` | Propose updating an existing entry: a tags-only refresh (body unchanged), or a wording/scope refinement that rewrites the body |
| `[ALERT]` | Conflicting signal detected during sync that needs human resolution |
| `[COMPRESS NOTICE]` | Threshold tripped; suggest running `compress` after this sync |

## Full example

```markdown
## [NEW] Proposed additions
- [scopes/frontend/ARCHITECTURE.md] [ARCH-2026-07-09-b4d2] Use `react-hook-form` for all forms. #added:2026-07-09
- [scopes/frontend/CONVENTIONS.md] [CONV-2026-07-09-c5e1] Never use `any` in TypeScript; prefer `unknown` + narrowing. #added:2026-07-09

## [STALE] Candidates for review
- [scopes/frontend/ARCHITECTURE.md] [ARCH-2026-01-15-d7a3] Use Pages Router (Next.js). #stale:2026-07-09 #superseded-by:ARCH-2026-07-09-b4d2
  Evidence: `frontend/package.json` shows `"next": "^14.0.0"` with `app/` directory present.
  Replaced by: `[ARCH-2026-07-09-b4d2] Use App Router (Next.js 14)` (new entry in this proposal).

## [REFINED] Existing entries updated
- [scopes/frontend/DECISIONS.md] [DEC-2026-02-03-7c19] (was: "use Zustand") → body rewritten; old entry gets `#stale:2026-07-09 #superseded-by:DEC-2026-07-09-e3f7` in this same proposal.
- [scopes/frontend/DECISIONS.md] [DEC-2026-07-09-e3f7] "use Zustand v4+ with slices pattern" #added:2026-07-09

## [ALERT] Conflicting signals detected during sync
- Sync proposes `[CONV-2026-07-09-c5e1]` (no `any`), but `[CONV-2026-06-01-f0a1]` already says "use `any` sparingly in test mocks". Resolution: refined entry above clarifies the exception.

## [COMPRESS NOTICE]
- Memory bank has 612 entries; last compression 47 days ago. Consider running `lore compress` after this sync.
```

## User reply semantics

The user can reply with:

- `"accept all"` — apply every `[NEW]`, `[STALE]`, and `[REFINED]` in the proposal
- `"accept only NEW"` — add new entries, leave existing untouched
- `"accept NEW + REFINE"` — add new and refine, do not mark anything stale
- `"drop STALE #d7a3"` — skip one specific stale entry
- `"reject all"` — discard the entire proposal

For partial acceptance, the user should explicitly list which items to apply.

## Marker → file operation mapping

| Marker | File action |
|---|---|
| `[NEW]` | Append a new bullet to the named file, with `#added:<today>` |
| `[STALE]` | Append `#stale:<today>` and (if a replacement exists) `#superseded-by:<replacement-id>` to the existing entry; entry stays in the file. Two cases: (a) the entry was superseded by a `[NEW]` entry in the same proposal — set both tags and carry the new ID forward; (b) the entry is deprecated with no successor — set `#stale:<today>` only; the user can backfill the chain later if a replacement appears. |
| `[REFINED]` | Body unchanged → update tags only (e.g. bump `#verified:<today>`), keep the ID. Body changed → write a new entry with a freshly hashed ID and mark the old entry `#stale:<today>` + `#superseded-by:<new-id>` (the ID is the content hash, so a rewritten body can never keep its old ID) |
| `[ALERT]` | No direct file change; only marks the conflict for user resolution |
| `[COMPRESS NOTICE]` | No file change; advisory only |

Note: `[STALE]` does not delete or move anything. The entry remains in its file with `#stale` (and optionally `#superseded-by`) tags. There is no `archive/` step — git history is the archive, and `#superseded-by` (when present) tells `compress`/`audit`/`history` how to walk the replacement chain.

## When audit uses these markers

`audit` does **not** use these markers. It writes its own severity tags (`[CONFLICT]`, `[STALE]`, `[UNVERIFIED]`, `[BROKEN_CHAIN]`) into the audit report file under `.lore/audit/`. The naming overlap (`[STALE]` in sync vs `[STALE]` severity in audit) is intentional — both refer to the same concept (entry no longer accurate) but operate in different files with different downstream actions.

# SUMMARY.md template

`compress` generates/refreshes `SUMMARY.md` from existing entries. This file holds the schema and worked example.

## Skeleton

```markdown
# .lore SUMMARY

> Last compressed: <YYYY-MM-DD>
> Total entries: <N> across <M> scopes
> This digest highlights key entries — open the referenced files under `_global/` and `scopes/` for the full text.

## Global (`_global/`)

### Architecture
- <bullet> — [_global/ARCHITECTURE.md#<ID>]
- ...

### Decisions
- ...

### Conventions
- ...

## Scope: <name>

### Architecture
- ...

### Decisions
- ...

### Conventions
- ...

## Scope: <name2>
...
```

## Selection rule (3–5 entries per scope per layer)

For each (scope, layer) tuple, pick entries by this priority:

0. **Keep only active entries** per `references/entry-format.md`: exclude any entry with `#stale:<date>` or `#superseded-by:<id>`, including stale entries with no successor. Entries with no tags remain eligible; age alone does not exclude an entry.
1. Most recent `#verified` date wins
2. Tiebreaker: most recent `#added` date
3. Tiebreaker: entries that contain "primary" / "main" / "core" / "use <X>" — these are typically the anchor facts

If a (scope, layer) has fewer than 3 active entries, include all of those active entries.

If a (scope, layer) has no active entries, omit the subsection entirely.

## Worked example

```markdown
# .lore SUMMARY

> Last compressed: 2026-07-09
> Total entries: 247 across 3 scopes
> This digest highlights key entries — open the referenced files under `_global/` and `scopes/` for the full text.

## Global (`_global/`)

### Architecture
- Monorepo with pnpm workspaces + Turborepo — [_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3]
- Node.js 20 baseline — [_global/ARCHITECTURE.md#ARCH-2026-02-01-9b1c]

### Decisions
- Rejected Nx → chose Turborepo (faster builds, simpler config) — [_global/DECISIONS.md#DEC-2026-02-03-7c19]

### Conventions
- All packages use TypeScript strict mode — [_global/CONVENTIONS.md#CONV-2026-01-20-b1e8]

## Scope: frontend

### Architecture
- Next.js 14 App Router — [scopes/frontend/ARCHITECTURE.md#ARCH-2026-03-10-a1b2]
- TanStack Query for server state — [scopes/frontend/ARCHITECTURE.md#ARCH-2026-03-15-e5f6]

### Decisions
- Zustand over Redux (60% less boilerplate) — [scopes/frontend/DECISIONS.md#DEC-2026-02-03-7c19]

### Conventions
- No default exports — [scopes/frontend/CONVENTIONS.md#CONV-2026-04-12-c3d4]

## Scope: backend

### Architecture
- Node.js + Fastify + PostgreSQL — [scopes/backend/ARCHITECTURE.md#ARCH-2026-01-15-e5f6]

### Decisions
- Fastify over Express (3x throughput in our benchmarks) — [scopes/backend/DECISIONS.md#DEC-2026-02-10-a8c9]

### Conventions
- All DB queries go through repository pattern — [scopes/backend/CONVENTIONS.md#CONV-2026-03-01-b1d2]
```

## Staleness note

Between a `sync` and the next `compress`, `SUMMARY.md` may lag behind `.lore/*`. Treat entry files as source of truth; SUMMARY is a locating index only (see `references/workflows.md#query`).

## Idempotency

Running `compress` twice without intervening `sync`s produces identical content (modulo the `Last compressed:` date). This is intentional — compress is a pure projection of the underlying entries.

# lore workflows — operational specification

The step-by-step procedures for all seven lore commands. Load this file when executing any `lore <command>`; [`SKILL.md`](../SKILL.md) routes each user request to the section below. Each section also points to the reference that backs it (entry format, marker conventions, summary/audit templates, config, platform mirrors, history).

### `init` — Initialize the memory bank

Runs once per project (or to start over).

0. **Resolve targets and takeover check.** Targets are determined by the resolution algorithm — see `references/platform-mirrors.md`. `init` **always** asks the user via multi-select which agents they use (pre-selected: agents whose platform files already exist or are already lore mirrors), so additional agents can be added even when files were detected; the resolution algorithm's silent return-on-detect applies to `mirror` / `compress`, not `init`. Explicit `mirror_targets` in `.lore/.config.json` overrides auto-detect (Replace semantics). For each resolved target:
   - If the file does not exist -> no action; it will be created later in step 7.
   - If the file exists AND contains a `## Lore` section -> it's already a lore mirror; note it and continue (its My notes will be processed as seed in step 5).
   - If the file exists AND does NOT contain a `## Lore` section -> it's likely from the agent's native `/init` or hand-written. Show the user:
     - (a) **Take over** — rewrite the file as a two-section mirror. The existing content becomes the My notes section (preserved verbatim, treated as seed knowledge in step 5).
     - (b) **Preserve as-is** — leave the file alone. Remove it from `mirror_targets` for this project (lore won't write to it). `.lore/` is still generated normally; the user can read `SUMMARY.md` directly or merge manually later.
     - (c) **Abort** — exit init. Nothing is created. The user can decide later.
   - Repeat for each resolved target before proceeding.
1. Check if `.lore/` already exists. If yes, warn and ask: archive the current one and re-init, or abort?
2. Detect monorepo structure (per `references/monorepo-detection.md`). Propose scope list to the user; let them rename / merge / split before proceeding. No monorepo -> `_global/` only.
3. Scan the project (per scope if applicable):
   - Top-level structure, entry points, package manager, language version
   - Config files: `package.json`, `pyproject.toml`, `Cargo.toml`, `tsconfig.json`, `Dockerfile`, `Makefile`, CI
   - `README*`, `CONTRIBUTING*`, existing docs
   - Key dependencies from lockfiles
4. Write proposals to `.lore/draft/` mirroring the target layout (`_global/` and per-scope subdirs). Classify scanned facts per the Layer semantics table in `SKILL.md`, and apply the same layer checks as sync step 3: a picked-over-alternative with a reason is a `DEC` entry, not ARCH; a rule future agents must follow is a `CONV` entry, not ARCH or code comments. Every entry gets `#added:<today>` and a deterministic hash-based ID (see `references/entry-format.md`).
5. For any mirror file that already has a `## Lore` section (from step 0), read its My notes section as user-supplied seed knowledge. Parse as atomic bullets into the right layer/scope.
6. **Stop and show the user a summary**: which scopes, how many entries per layer per scope, sample of 5-10 entries, and what mirror files will be (re)generated (or skipped per step 0).
7. On user confirmation: `mv .lore/draft/* .lore/`, run an initial `compress` to generate `SUMMARY.md`, then (re)generate platform mirrors per the two-section structure — auto-create missing files, refresh Lore sections, leave My notes sections intact. Skip any target the user chose "preserve as-is" in step 0.
8. On user rejection: `rm -rf .lore/draft/`. Nothing persists.

The `draft/` directory gives a clean rollback path: nothing in `.lore/` is real until the user approves.

### `sync` — Update after a change

Runs after the user completes a feature, refactor, or bug fix.

**Trigger threshold — only propose sync when at least one is true:**
- `git diff --stat HEAD` shows 50+ changed lines across 2+ directories
- A new top-level module / directory / dependency was added or removed
- A new convention was explicitly discussed (e.g. user said "from now on we use X")
- The user explicitly invokes `sync` regardless of diff size

Pure typo fixes, lockfile-only changes, README rewording, or tweaks below the 50-line / 2-directory threshold do **not** warrant `sync`.

**Compress threshold check (silent, runs before sync proposal):**
- Total entry count across all files > 500, **or**
- `SUMMARY.md` is missing, **or**
- `SUMMARY.md` last `Last compressed:` date is > 30 days ago

If any of these are true, the skill appends a `[COMPRESS NOTICE]` to the sync proposal. It does not block the sync — the user can defer.

**Procedure:**

1. **Detect the delta** from two sources, combined and de-duplicated:
   - `git diff <last_sync_sha>..HEAD` if `.lore/.config.json#last_sync_sha` is set and reachable from any local ref. This captures every commit since the last successful `sync`.
   - `git diff HEAD` (current working tree vs. `HEAD`) — always included when HEAD exists. Captures the net uncommitted changes to tracked files, including staged and unstaged changes. Bare `git diff` compares the working tree to the index and misses staged-only changes.
   - **Re-scan new files**: inspect added paths in the diffs and enumerate untracked files with `git ls-files --others --exclude-standard`. Read their current contents; untracked files are not included in `git diff HEAD`.
   - **Fallback** when `last_sync_sha` is absent (older config) or no longer reachable (e.g. after `git rebase` or a force-push that orphaned the SHA): use `git diff HEAD` alone and emit a one-line `[WARN]` to stderr noting that incremental sync is degraded. Working tree alone will not pick up commits made before the next sync ran — the user should re-run `sync` after `git pull --rebase` to re-establish the baseline.
   - **Empty repo** (no commits yet): `last_sync_sha` is `null`; do not run HEAD-based diffs. Enumerate files with `git ls-files --cached --others --exclude-standard`, de-duplicate paths, and scan existing files from the working tree. This includes staged and untracked files and reads the latest content if a file changed again after staging; an indexed path missing from the working tree is not a current fact.
2. **Determine target scope(s)** for each change. Use `git diff --name-only <last_sync_sha>..HEAD` (when the baseline is valid) plus `git diff --name-only HEAD` and the untracked paths from step 1; for an empty repo, use its enumerated paths. Map files -> scopes (e.g. `frontend/src/...` -> `scopes/frontend/`). Cross-scope changes (root config files) -> `_global/`. If a change introduces a scope with no directory under `.lore/scopes/` yet, create `scopes/<name>/ARCHITECTURE.md`, `DECISIONS.md`, and `CONVENTIONS.md` (same layout as `init`) and route the entries there.
3. **Classify each change** into one layer:
   - New module, new dependency, new file structure -> `ARCHITECTURE.md`
   - "We picked X over Y because Z" -> `DECISIONS.md`
   - New lint rule, new naming pattern, new "we never do X" -> `CONVENTIONS.md`
   - Boundary: follow the Layer semantics in `SKILL.md`. The choice itself ("we use X") -> `ARCHITECTURE.md`; a short inline reason may stay with that fact within the entry length limit. Alternatives or tradeoffs ("why X over Y") -> `DECISIONS.md`. When recording both the fact and a separate decision, cross-reference their IDs.
   - **Decision check (mandatory before step 4).** Check whether the change records an alternative considered or a tradeoff made. If so, emit that rationale as a `DEC` candidate and keep the architectural fact in ARCH, cross-referenced by ID. Words such as `reason:`, `because`, and `for <purpose>` are prompts to inspect the meaning, not automatic split triggers: "Use Next.js App Router; reason: streaming + RSC" may remain one ARCH entry. Detailed rationale that needs its own entry belongs in DEC. Do not invent alternatives or reasoning absent from the sources. If no DEC is warranted, state that in the proposal so the user can review the classification.
   - **Convention check (mandatory before step 4).** Ask explicitly for every change: does it introduce or change a *rule* future agents must follow — a lint/format/tool-config policy, a naming or structural pattern ("every X must Y"), a "we never do X", or an implicit rule visible in code (guard/validation logic, `must`/`required` checks, new or updated tool config)? If yes, that rule is a `CONV` candidate; it must not be silently folded into an ARCH entry or left only in code and comments. Signals: `must`/`never`/`always`/`required`, changes to lint or tool config (e.g. `.eslintrc*`, `pyproject.toml` tool sections, `tsconfig.json` compiler options), repeated structural patterns, "from now on..." statements. If you conclude no CONV is warranted, state that explicitly in the proposal so the user can veto.
4. **For each candidate entry**:
   - **Contradicts an existing entry** in the same scope/layer -> mark the old one `#stale:<today>` and `#superseded-by:<new-id>` (where `<new-id>` is the entry in this proposal that replaces it). Emit an `ALERT`.
   - **No replacement entry exists yet** (user is removing a fact without substituting) -> mark the old one `#stale:<today>` only; the chain can be backfilled later.
   - **Refines an existing entry** -> if the body is unchanged, update tags only (bump `#verified:<today>`) and keep the ID. If the body changes, write a new entry with a freshly hashed ID and mark the old one `#stale:<today>` + `#superseded-by:<new-id>` — the ID hashes the body, so a body rewrite always produces a new ID (see `references/entry-format.md`).
   - **Genuinely new** -> append with `#added:<today>` and a new hash ID.
5. **De-duplicate before appending**: for each candidate, run `python skill/scripts/find_duplicates.py --json --candidate "<entry body>"` (when installed, use `<skill>/scripts/find_duplicates.py`). Pass only the body, without its ID or status tags, using safe argument quoting. For text that is awkward to quote, use `--candidate-file <utf8-text-file>`. Without a candidate argument, the script compares only entries already on disk.
   - Inspect pairs containing `CANDIDATE-unsaved`; the output can also contain existing-vs-existing pairs. Compare candidates in the same proposal with each other as well, since unsaved candidates are not in the script's entry index.
   - Treat matches as hints, not proof of equivalence. Only skip a candidate and bump an existing entry's `#verified` when they express the same fact in the applicable scope and the existing entry is active (see `references/entry-format.md`). A match to a stale or superseded entry must not suppress a current candidate or revive the old entry via a tags-only update. Apply the trust rules in step 6; keep meaningfully different facts.
6. **Apply trust level** (controlled by `.lore/.config.json#sync_trust`, default `"medium"`):

   | Change type | `high` | `medium` (default) | `low` |
   |---|---|---|---|
   | De-duplicate hit (same fact already present) | auto-apply | auto-apply | confirm |
   | REFINED, tags only (body unchanged) | auto-apply | auto-apply | confirm |
   | REFINED, body changed (new ID + supersede link) | auto-apply | confirm | confirm |
   | `NEW` entry | auto-apply | confirm | confirm |
   | `STALE` mark | auto-apply | confirm | confirm |
   | `ALERT` | confirm | confirm | confirm |

   Auto-applied changes are written without per-change confirmation and reported at the end. Confirmation-required changes are bundled into a single diff proposal and shown together.
7. **Generate the proposed diff** (for any confirmation-required changes) using the `[NEW]/[STALE]/[REFINED]/[ALERT]/[COMPRESS NOTICE]` markers. See `references/stale-new-markers.md` for the full convention and user reply semantics.
8. **Stop and wait for user confirmation** for any pending changes. Auto-applied changes need no confirmation.
9. After the user accepts, write to `.lore/*` only. **Do not** regenerate platform mirrors from `sync` (unless `sync_updates_mirror: true` is set in `.lore/.config.json`) — this is intentional. See "Mirror update triggers" in `SKILL.md` and the dedicated `lore mirror` command.
10. **Update `.lore/.config.json#last_sync_sha`** to the current `git rev-parse HEAD`. Idempotent: re-running sync without new commits writes the same SHA. If HEAD does not exist (empty repo), set to `null`. The field is optional and additive; older configs without it keep working through the fallback in step 1.

**Source priority** (when sources disagree):

1. Git diff of changed code (most reliable — shows what actually happened)
2. Static scan of new files (reliable for facts, not for intent)
3. Conversation context (lowest priority — see below)
4. Test/build output (auxiliary — only consulted if 1-3 are ambiguous)

**Conversation context is opt-in.** The skill does **not** automatically mine chat messages for memory updates. It only extracts from conversation when the user explicitly says things like "note this down" / "remember this" / "this is important". Reason: chat context is high-noise, and silent extraction creates false entries.

### `query` — Answer from memory

Read-only.

1. Determine which scope(s) the question targets:
   - "this project" / "the whole codebase" / unspecified -> `_global/` first, then SUMMARY.md
   - "frontend" / "in the web app" / "the React side" -> `scopes/frontend/`
   - "backend" / "the API" -> `scopes/backend/`
   - If ambiguous, search SUMMARY.md for clues.
2. Grep the target files for relevant entries. If multi-layer or multi-scope, check all relevant ones.
   - **For current-state answers, skip entries with `#stale:<date>` or `#superseded-by:<id>`.** Apply the active-entry rule in `references/entry-format.md`, also used by `compress`. A stale entry without a successor is still excluded. For explicit historical questions, read it as historical evidence and label its status; use `history` for commit context and `history --follow-superseded <id>` when a replacement chain exists.
   - **SUMMARY is an index, not a source of truth for a claim.** A one-line summary is a locating hint; when citing a fact or making a decision, read the full referenced entry (including its tags) in `_global/` or `scopes/` first.
3. If found: answer concisely, citing fully-qualified entry IDs (e.g. `[scopes/frontend/DECISIONS.md#DEC-2026-02-03-7c19]`). Mention `#verified` date.
4. If not found but inferable from the code: say so explicitly ("Not in memory, but inferable from `frontend/src/store/index.ts`..."). Offer to add it.
5. Never fabricate an entry. If memory doesn't have it, say it doesn't have it.

### `audit` — Check memory vs. reality

Read-only with respect to canonical memory. It reports drift without changing entries or `SUMMARY.md`, but it does write the dated report described below.

1. For each entry in `_global/*` and `scopes/*/*`, find the code/config it claims to describe (scoped to the relevant scope's source tree) and compare against current state.
2. Also flag: entries whose reference date — `#verified` if present, else `#added` — is older than 90 days. Run `python skill/scripts/find_stale.py --days=90 --json` (or `<skill>/scripts/find_stale.py` when installed) to enumerate them mechanically.
3. Write the report to `.lore/audit/audit-YYYY-MM-DD.md`, organized by scope. **Do not** mark anything as stale in the main files. **Do not** emit ALERT blocks. See `references/audit-template.md` for the full report format and severity definitions.
4. **Stop.** User reviews the report and decides what to do. To act on findings, the user runs `sync`.

This separation keeps `audit` honest: it observes, it does not edit. ALERT noise is contained to `sync` and `query`, where the agent is about to act on the memory.

### `compress` — Build the top-level summary

Long-term compression. Generates `SUMMARY.md` and, when `auto_mirror: true` (or the user accepts the per-target prompt), regenerates platform mirrors. Underlying ARCHITECTURE / DECISIONS / CONVENTIONS files are untouched.

1. Run `python skill/scripts/list_entries.py --json` (or `<skill>/scripts/list_entries.py` when installed) to enumerate every entry. Use the JSON output as the input for the selection step.
2. Exclude entries with `#stale:<date>` or `#superseded-by:<id>` using the active-entry rule in `references/entry-format.md`. Optionally run `python skill/scripts/find_stale.py --json` to highlight long-unverified entries for review; age alone does not make an entry inactive.
3. For each (scope, layer) pair, pick 3-5 most important entries using the selection rule in `references/summary-template.md`.
4. Write `SUMMARY.md` per the template in `references/summary-template.md`. (This is the only file written on the canonical `.lore/` side.)
5. If `auto_mirror: true` in config, regenerate platform mirrors (this is one of the three mirror update triggers — see "Mirror update triggers" in `SKILL.md`). If `auto_mirror: false`, ask per target and only write the mirrors the user accepts. Content-based dedup: if the new Lore section equals the current one, skip the write. The My notes section is always preserved.
6. **Stop.** Once mirror regeneration has either written or been declined per target, `compress` is done.

**Compress is idempotent.** Running it twice produces the same `SUMMARY.md` content (modulo the date stamp). Re-running after new `sync`s picks up new entries automatically.

### `mirror` — Regenerate platform mirrors

Regenerate all configured platform mirrors from the current state of `.lore/*`. Content-based dedup skips targets whose Lore section is unchanged.

1. Read current `.lore/SUMMARY.md` and the scope-tagged index.
2. For each configured mirror target (per `references/platform-mirrors.md`), read the existing file and detect the section boundary.
3. **Validate the two-section structure** for each target: if it lacks the `---` separator, lacks a `## My notes` section, or is a user-notes-only file without `## Lore`, stop for that target and ask the user how to proceed — never overwrite an anomalous file silently (section detection rules: `references/platform-mirrors.md`).
4. For each target, compare the new Lore section content against the existing one. **Skip writing if content is identical** (content-based dedup; avoids empty `git diff`).
5. If different, replace the Lore section; preserve the My notes section verbatim. If the user asked to wipe My notes, archive it to `.lore/.archive/<file>-<date>.md` first.
6. **Stop.** Report: "Mirror updated: `<file>`" or "No changes needed: `<file>`" per target.

This command exists because most users want `sync` to be fast and unobtrusive, but occasionally need the agent-facing files to reflect recent knowledge. `mirror` is that explicit "publish to agent view" step. Structure validation happens automatically during each regeneration (step 3), and a user-requested My notes wipe is handled as a normal conversation request.

### `history` — Show git commits related to a memory entry

Read-only. Surfaces the git history that backs a memory entry, a file, or a scope, so the agent can answer "why does this decision exist?" with a pointer to the actual commits rather than a guess.

**When to trigger:** only when the user explicitly invokes `lore history` or names a subcommand ("show me the git history", "show me the commits behind this entry"). Generic "history" or "git log" alone does not trigger — defer to the user's intent.

| User says (examples) | Command |
|---|---|
| "lore history DEC-2026-02-03-7c19" | `lore history <entry-id>` |
| "lore history frontend/src/store/index.ts" | `lore history <file-path>` |
| "lore history --scope=frontend" | `lore history --scope=<name>` |

**Procedure (entry form):**

1. Resolve project root (`.lore/` must exist), confirm git repo + git CLI on PATH.
2. Load the entry index (`list_entries.py --json`), locate the entry, derive `#added` as the default `--since` (fallback `1970-01-01`).
3. Resolve the code file (backtick path in entry text -> scope directory -> project root), run `git log`, render Markdown or JSON, print to stdout.
4. **Stop.** No files are written.

**Data source contract:** local git CLI only. No GitHub / GitLab API. No LLM call. The agent invoking the command does the semantic work (interpreting commit messages, deciding relevance).

**Relationship to other commands:** fills the previously-empty cell of "read git history" (other commands read either the current file system or `git diff` only).

Supported flags: `--since=<YYYY-MM-DD>`, `--follow-superseded`, `--json`. Full dispatch rules, `--since` normalization (same-day commit safety), output format, and the error/exit-code table live in `references/history-command.md`.

## Cross-workflow notes

**Who writes what:**

| File | Written by |
|---|---|
| `.lore/SUMMARY.md` | `compress` (and by `init`, via its initial compress) |
| `.lore/{_global,scopes/<scope>}/<LAYER>.md` | `init`, `sync`, manual edits |
| `.lore/.config.json` | `init`, manual edits |
| `.lore/audit/audit-<date>.md` | `audit` |
| `.lore/draft/` | `init` (proposals; moved into `.lore/` on confirm, removed on reject) |
| `<project-root>/<platform files>` | `init`, `mirror`, `compress` (if `auto_mirror: true`), `sync` (if `sync_updates_mirror: true`) |

**What remains protected:** changes outside the configured `sync_trust` allowance wait for confirmation; auto-applied sync changes are reported; platform mirrors are not rewritten on every sync by default; `compress` never deletes entries; `init` never overwrites user-written platform files without explicit takeover.

**Typical sequence:** `init` -> `[sync <-> query <-> audit]` (interchangeable, agent picks by context) -> `compress` (when SUMMARY.md grows stale) -> `mirror` (or auto via `compress` if `auto_mirror: true`).

#!/usr/bin/env python3
"""Find potential duplicate entries in .lore/.

Usage:
    python find_duplicates.py                       # default threshold 0.7
    python find_duplicates.py --threshold=0.85
    python find_duplicates.py --json
    python find_duplicates.py --candidate "<text>"
    python find_duplicates.py --candidate-file path/to/candidate.txt
    echo '<text>' | python find_duplicates.py --candidate-stdin

Detection strategies:
    1. Identical hash suffix (4 chars after the date) — this may indicate
       an exact-text duplicate or a collision between different bodies.
       Always reported for agent review.
    2. Token-based Jaccard similarity above `--threshold` on the entry
       text. Catches rewrites that mean the same thing but produce a
       different hash (e.g. "use Zustand" vs "we chose Zustand").

Output is sorted by similarity (descending). Run from the project root.

This script is the mechanical part of `sync` step 5 (de-duplication).
The agent still decides what to do with each pair.

When a candidate is supplied (via --candidate, --candidate-file, or
--candidate-stdin), the candidate is also included in the comparison
set so sync step 5 can detect "this proposed entry duplicates an
existing one" before appending. Without a candidate, only
already-appended entries are compared.
"""
import json
import re
import subprocess
import sys
from pathlib import Path


def get_entries():
    """Invoke list_entries.py --json to get parsed entries."""
    script = Path(__file__).parent / "list_entries.py"
    r = subprocess.run(
        [sys.executable, str(script), "--json"],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        universal_newlines=True,
        encoding="utf-8",
        errors="replace",
    )
    if r.returncode != 0:
        print(r.stderr, file=sys.stderr)
        sys.exit(1)
    return json.loads(r.stdout)


def read_candidate(args):
    """Return the candidate text or None.

    Sources, in priority order:
      1. --candidate "<text>"
      2. --candidate-file <path>
      3. --candidate-stdin (reads entire stdin)
    """
    inline = None
    file_path = None
    use_stdin = False
    i = 0
    while i < len(args):
        a = args[i]
        if a.startswith("--candidate="):
            inline = a.split("=", 1)[1]
        elif a.startswith("--candidate-file="):
            file_path = a.split("=", 1)[1]
        elif a in ("--candidate", "--candidate-file"):
            if i + 1 >= len(args) or args[i + 1].startswith("--"):
                die(2, f"{a} requires a value")
            i += 1
            if a == "--candidate":
                inline = args[i]
            else:
                file_path = args[i]
        elif a == "--candidate-stdin":
            use_stdin = True
        i += 1
    if inline is not None:
        return inline
    if file_path is not None:
        try:
            return Path(file_path).read_text(encoding="utf-8")
        except OSError as exc:
            die(2, f"failed to read candidate file {file_path}: {exc}")
    if use_stdin:
        if sys.stdin.isatty():
            die(2, "--candidate-stdin given but stdin is a TTY")
        return sys.stdin.read()
    return None


def die(code, message):
    print(f"error: {message}", file=sys.stderr)
    sys.exit(code)


def synthetic_candidate_entry(text):
    """Build a candidate entry dict shaped like list_entries.py output.

    The synthetic entry has layer "CANDIDATE" so it compares only against
    existing entries on the same layer when the agent supplies --layer.
    """
    return {
        "id": "CANDIDATE-unsaved",
        "layer": "CANDIDATE",
        "scope": "_candidate",
        "file": "<candidate>",
        "text": text.strip(),
        "tags": {},
    }


def tokenize(text: str):
    return set(re.findall(r"\w+", text.lower()))


def jaccard(a: set, b: set):
    if not a or not b:
        return 0.0
    return len(a & b) / len(a | b)


def hash_suffix(eid: str):
    return eid.split("-")[-1]


def main():
    try:
        sys.stdout.reconfigure(encoding="utf-8")
    except AttributeError:  # Python < 3.7
        pass

    args = sys.argv[1:]
    threshold = 0.7
    json_output = "--json" in args
    layer_filter = None

    for arg in args:
        if arg.startswith("--threshold="):
            threshold = float(arg.split("=", 1)[1])
        elif arg.startswith("--layer="):
            layer_filter = arg.split("=", 1)[1]

    candidate_text = read_candidate(args)

    entries = get_entries()
    if layer_filter is not None:
        entries = [e for e in entries if e.get("layer") == layer_filter]

    candidates = []
    if candidate_text:
        candidates.append(synthetic_candidate_entry(candidate_text))

    pairs = []

    # existing-vs-existing pairs (unchanged behavior)
    for i, a in enumerate(entries):
        for b in entries[i + 1:]:
            # Matching hash suffixes are reported across layers. They may
            # be exact-text duplicates or collisions; fuzzy Jaccard
            # comparisons stay within the same layer.
            if hash_suffix(a["id"]) == hash_suffix(b["id"]):
                pairs.append((a, b, 1.0, "identical hash"))
                continue
            if a["layer"] != b["layer"]:
                continue
            sim = jaccard(tokenize(a["text"]), tokenize(b["text"]))
            if sim >= threshold:
                pairs.append((a, b, sim, f"similar text (>= {threshold})"))

    # candidate-vs-existing pairs
    if candidates:
        # --layer narrows entries above; without it, compare the proposed
        # entry with every layer because the candidate has not been assigned
        # a canonical layer yet.
        compare_set = entries
        for a in compare_set:
            sim = jaccard(
                tokenize(candidates[0]["text"]),
                tokenize(a["text"]),
            )
            if sim >= threshold:
                pairs.append((candidates[0], a, sim,
                              f"candidate similar to existing (>= {threshold})"))

    pairs.sort(key=lambda x: -x[2])

    if json_output:
        out = [
            {
                "similarity": round(sim, 3),
                "reason": reason,
                "a": a,
                "b": b,
            }
            for a, b, sim, reason in pairs
        ]
        print(json.dumps(out, indent=2, ensure_ascii=False))
        return

    if not pairs:
        if candidate_text:
            print("No potential duplicates found for the candidate.")
        else:
            print("No potential duplicates found.")
        return

    for a, b, sim, reason in pairs:
        print(f"[{sim:.2f}] {reason}")
        print(f"  A: [{a['file']}] {a['id']} {a['text']}")
        print(f"  B: [{b['file']}] {b['id']} {b['text']}")
        print()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Find stale entries in .lore/.

Usage:
    python find_stale.py                  # default: 90-day threshold
    python find_stale.py --days=180
    python find_stale.py --json

Reports two categories:

  Stale           : entry has not been `#verified` within the threshold
                    (or has no #verified at all, and was added > threshold
                    days ago).
  Pending review  : entry is superseded (carries `#stale`, or carries
                    `#superseded-by` which implies staleness). (The skill
                    does not auto-archive; this category is a heads-up that
                    the entry is no longer accurate and should be reviewed
                    or left as historical record.)

Output is plain text by default, JSON with --json.

Used by:
    - `audit` workflow (read-only)
    - `compress` workflow (advisory)
"""
import json
import os
import subprocess
import sys
from datetime import date, datetime, timedelta
from pathlib import Path


def get_entries():
    script = Path(__file__).parent / "list_entries.py"
    r = subprocess.run(
        [sys.executable, str(script), "--json"],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        universal_newlines=True,
        encoding="utf-8",
        errors="replace",
    )
    if r.returncode != 0:
        print(r.stderr.strip(), file=sys.stderr)
        sys.exit(1)
    try:
        return json.loads(r.stdout)
    except json.JSONDecodeError as exc:
        print(f"error: list_entries.py returned invalid JSON: {exc}",
              file=sys.stderr)
        sys.exit(1)


def parse_date(s: str):
    try:
        return datetime.strptime(s, "%Y-%m-%d").date()
    except (ValueError, TypeError):
        return None


def main():
    try:
        sys.stdout.reconfigure(encoding="utf-8")
    except AttributeError:  # Python < 3.7
        pass

    days = 90
    json_output = "--json" in sys.argv[1:]

    for arg in sys.argv[1:]:
        if arg.startswith("--days="):
            days = int(arg.split("=", 1)[1])

    today = date.today()
    cutoff = today - timedelta(days=days)

    entries = get_entries()
    stale = []
    pending_review = []

    # Build a quick lookup for chain validation.
    by_id = {e["id"]: e for e in entries}

    broken_chains = []
    pending_by_chain = {}  # replaced_by -> [entry, ...]

    for e in entries:
        # Superseded (tagged #stale, or carrying #superseded-by which
        # implies staleness per references/entry-format.md) -> pending
        # review (and maybe broken chain)
        if "stale" in e["tags"] or e.get("replaced_by"):
            target = e.get("replaced_by")
            if target and target not in by_id:
                broken_chains.append({
                    "id": e["id"],
                    "file": e["file"],
                    "text": e["text"],
                    "missing_target": target,
                })
            if target:
                pending_by_chain.setdefault(target, []).append(e)
            else:
                # No chain info — keep under a sentinel so the existing
                # output still includes it.
                pending_by_chain.setdefault(None, []).append(e)
            pending_review.append(e)
            continue

        # Determine the entry's freshness date
        last_v = parse_date(e["last_verified"])
        added = parse_date(e["tags"].get("added"))
        ref_date = last_v or added

        if ref_date is None:
            continue  # no date info, can't decide

        if ref_date < cutoff:
            stale.append(e)

    if json_output:
        out = {
            "threshold_days": days,
            "as_of": today.isoformat(),
            "stale": stale,
            "pending_review": pending_review,
            "chains": {target: [e["id"] for e in entries_]
                       for target, entries_ in pending_by_chain.items()
                       if target is not None},
            "broken_chains": broken_chains,
        }
        print(json.dumps(out, indent=2, ensure_ascii=False))
        return

    print(f"=== Stale (unverified > {days} days, as of {today}) ===")
    if not stale:
        print("  (none)")
    for e in stale:
        ref = e["last_verified"] or e["tags"].get("added", "unknown")
        print(f"  [{e['file']}] {e['id']} {e['text']}")
        print(f"    ref date: {ref}")

    print()
    print("=== Pending review (tagged #stale, grouped by replacement) ===")
    if not pending_by_chain:
        print("  (none)")
    for target, entries_ in sorted(
        pending_by_chain.items(), key=lambda kv: (kv[0] is None, kv[0] or "")
    ):
        if target is None:
            print("  (no #superseded-by chain):")
        else:
            print(f"  -> superseded-by {target}:")
        for e in entries_:
            chain = (
                f" -> {e['replaced_by']}" if e.get("replaced_by") else ""
            )
            print(f"    [{e['file']}] {e['id']} {e['text']}{chain}")

    if broken_chains:
        print()
        print("=== Broken chains (#superseded-by target not found) ===")
        for b in broken_chains:
            print(f"  [{b['file']}] {b['id']} {b['text']}")
            print(f"    missing: {b['missing_target']}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""`lore history` — list git commits related to an entry, file, or scope.

Usage:
    lore history <entry-id>
    lore history <file-path>
    lore history --scope=<name>
    lore history --since=<YYYY-MM-DD>
    lore history --json

See references/history-command.md for the full specification.
"""
import re
import subprocess
import sys
from pathlib import Path
import os as _os
import json as _json  # standard library; aliased to avoid clashing with future vars


# Entry ID pattern: LAYER-YYYY-MM-DD-xxxx (4 hex chars)
ENTRY_ID_RE = re.compile(r"^[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}$")


# Date-only ISO pattern (YYYY-MM-DD). Used to detect inputs that need
# normalization before being passed to `git log --since=` (see below).
_DATE_ONLY_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")


def normalize_since(value):
    """Normalize a `--since` value to a precise timestamp before git log.

    `git log --since=YYYY-MM-DD` interpretation is version-dependent:
    older git versions parse it as the user's local-timezone midnight,
    newer versions as UTC midnight. A commit made early in the day in
    any timezone can therefore be silently dropped when filtering by a
    same-day `#added` tag.

    Defense: when the input is date-only (no time component), append
    `T00:00:00` so git's date parser treats it as a precise timestamp.
    Strings that already contain a time component (T or space) are
    passed through unchanged. None passes through unchanged.

    Refs: https://git-scm.com/docs/git-log#_date_formats
    """
    if value is None or not isinstance(value, str):
        return value
    if not _DATE_ONLY_RE.match(value):
        return value
    return value + "T00:00:00"


def parse_arg(arg: str):
    """Dispatch the first positional argument to entry / file / scope form.

    Returns a dict {"form": "entry"|"file"|"scope", "value": str}, or None
    if the argument matches none of the recognized patterns.
    """
    if not arg:
        return None
    if arg.startswith("--scope="):
        return {"form": "scope", "value": arg.split("=", 1)[1]}
    if ENTRY_ID_RE.match(arg):
        return {"form": "entry", "value": arg}
    if "/" in arg or arg.startswith("."):
        return {"form": "file", "value": arg}
    return None


def find_entry(entries, entry_id):
    """Look up an entry by ID in the list from list_entries.py --json.

    Returns the entry dict, or None if not found.
    """
    for e in entries:
        if e.get("id") == entry_id:
            return e
    return None


def extract_added_date(tags):
    """Return the value of the 'added' tag, or None if absent.

    The entry dict's `tags` field is {name: value, ...} as produced
    by list_entries.py.
    """
    if not tags:
        return None
    return tags.get("added")


# Match a backtick-quoted path inside an entry's text. The path must
# contain at least one slash OR start with a dot OR end with a common
# code extension, to avoid false positives like `Zustand`.
BACKTICK_PATH_RE = re.compile(
    r"`([^\s`]+\.[a-zA-Z0-9]{1,8}(?:\.[a-zA-Z0-9]{1,8})*"
    r"|[^\s`]+/[^\s`]+"
    r"|\.[a-zA-Z][^\s`]*)`"
)


def resolve_code_file(entry):
    """Decide which file path to git-log for this entry.

    Priority:
      1. First backtick-quoted path in entry.text (looks like a file).
      2. Scope directory at project root (e.g. "frontend" for scope "frontend").
      3. "." for the _global scope (project root).

    The path returned is relative to the project root. git log handles
    "." to mean the whole repo.
    """
    if entry.get("text"):
        m = BACKTICK_PATH_RE.search(entry["text"])
        if m:
            return m.group(1)
    scope = entry.get("scope", "_global")
    if scope == "_global":
        return "."
    return scope


# Single-line per commit. The trailing %s for body is multi-line content
# that we capture separately (not in the delimited format string) by
# running a second pass with a different format. For v1 we use a simple
# format and parse body via a follow-up `git show` only if needed.
#
# To keep parsing simple, we use a delimiter unlikely to appear in real
# commit metadata: ASCII Unit Separator (\x1f).
COMMIT_DELIM = "\x1f"

# git log format: hash\x1fauthor\x1fdate(iso)\x1fsubject
# We use %x1f (the same delimiter) inline so the format string is portable.
# The body is fetched separately via the second invocation below.
FORMAT_STRING = "%H%x1f%an%x1f%ai%x1f%s"


def run_git_log(project_root, since, code_file, n=None):
    """Run `git log` and return a list of commit dicts.

    Args:
        project_root: Path to the git repo root.
        since: ISO date string, or None for full history.
        code_file: Path relative to project_root to filter by.
        n: Optional int cap on number of commits.

    Returns:
        List of dicts as produced by parse_commit_line + body-fetch.

    Raises:
        RuntimeError: if git exits non-zero or is missing.
    """
    cmd = [
        "git",
        "-C", str(project_root),
        "log",
        f"--pretty=format:{FORMAT_STRING}",
    ]
    if since:
        cmd.append(f"--since={since}")
    if n is not None:
        cmd.append(f"-n{n}")
    cmd.extend(["--", code_file])

    try:
        proc = subprocess.run(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            universal_newlines=True,
            encoding="utf-8",
            errors="replace",
            check=False,
        )
    except FileNotFoundError as exc:
        raise RuntimeError(f"git executable not found on PATH: {exc}")

    if proc.returncode != 0:
        raise RuntimeError(f"git log failed: {proc.stderr.strip()}")

    commits = []
    for line in proc.stdout.splitlines():
        if not line:
            continue
        parsed = parse_commit_line(line)
        if parsed is None:
            continue
        parsed["body"] = ""  # filled in by fetch_body if requested later
        commits.append(parsed)
    return commits


def parse_commit_line(line):
    """Parse one delimited git log line. Returns dict or None on malformed input."""
    parts = line.split(COMMIT_DELIM)
    if len(parts) != 4:
        return None
    full_hash, author, date, subject = parts
    if len(full_hash) < 7:
        return None
    return {
        "hash": full_hash,
        "short": full_hash[:7],
        "author": author,
        "date": date[:10],  # take YYYY-MM-DD from full ISO timestamp
        "subject": subject,
        "body": "",  # populated by fetch_commit_body
    }


# Match PR/issue references. Order matters: longer keywords first so
# "Closes" doesn't get eaten by "#NNN" alone. We require word boundary
# (or start of string) before the keyword to avoid matching substrings
# like "address#N" mid-word.
REFS_RE = re.compile(
    r"(?:\(|\b(?:Closes|Refs|Fixes|Resolves)\s+)"
    r"(#\d+)",
    re.IGNORECASE,
)


def extract_refs(message):
    """Return a list of PR/issue references found in a commit message.

    Each item is either "#NNN" (from parens form) or "Keyword #NNN"
    (from Closes/Refs/Fixes/Resolves form). Duplicates are removed
    in order of appearance.
    """
    matches = []
    seen = set()
    for m in REFS_RE.finditer(message):
        prefix = m.group(0).split("#")[0]
        ref = "#" + m.group(1)[1:]  # normalize to "#NNN"
        if ref in seen:
            continue
        seen.add(ref)
        if prefix.startswith("("):
            matches.append(ref)
        else:
            matches.append(f"{prefix.strip()} {ref}")
    return matches


def truncate_body(body, max_lines=3):
    """Trim a multi-line string to at most `max_lines`, stripping blank tails.

    Used to keep commit bodies short in the Markdown output. The subject
    is already shown separately; the body is supplementary context.
    """
    lines = body.splitlines()
    trimmed = lines[:max_lines]
    while trimmed and not trimmed[-1].strip():
        trimmed.pop()
    return "\n".join(trimmed)


def fetch_commit_body(project_root, commit_hash):
    """Fetch the full commit message (subject + body) via `git show`.

    Returns a string with the subject as the first line and the body
    (if any) following a blank line. Trailing blank lines are removed.
    """
    cmd = [
        "git", "-C", str(project_root),
        "show", "-s", "--format=%B", commit_hash,
    ]
    try:
        proc = subprocess.run(
            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
            universal_newlines=True,
            encoding="utf-8", errors="replace", check=False,
        )
    except FileNotFoundError:
        return ""
    if proc.returncode != 0:
        return ""
    return proc.stdout.rstrip()


def render_json(meta, commits):
    """Render the JSON output for a `lore history` invocation.

    Output matches the schema documented in the spec.
    """
    payload = {
        "entry_id": meta["entry_id"],
        "lore_file": meta["lore_file"],
        "code_file": meta["code_file"],
        "since": meta["since"],
        "since_source": meta["since_source"],
        "chain": meta.get("chain"),
        "commits": commits,
    }
    return _json.dumps(payload, indent=2, ensure_ascii=False)


def render_markdown(meta, commits):
    """Render the Markdown output for a `lore history` invocation.

    Args:
        meta: dict with keys entry_id, lore_file, code_file, since,
              since_source, and optionally _chain_entries (raw entry dicts).
        commits: list of commit dicts (see parse_commit_line + extract_refs).

    Returns:
        Markdown string ready for stdout.
    """
    lines = []
    title_suffix = ""
    if meta.get("_chain_entries"):
        title_suffix = " --follow-superseded"
    lines.append(f"# history: [{meta['entry_id']}]{title_suffix}")
    lines.append("")

    chain_entries = meta.get("_chain_entries")
    if chain_entries:
        lines.append("## Chain")
        for idx, e in enumerate(chain_entries, start=1):
            next_link = (
                f"\n   -> superseded-by -> {e.get('replaced_by')}"
                if e.get("replaced_by") else "\n   -> no successor"
            )
            lines.append(
                f"{idx}. [{e['id']}] ({e['file']}) - {e['text']}{next_link}"
            )
        lines.append("")

    lines.append(f"> Entry: {meta['lore_file']}")
    since_suffix = " (entry #added date)" if meta.get("since_source") == "entry_added" else ""
    lines.append(f"> Since: {meta['since']}{since_suffix}")
    lines.append(f"> File: {meta['code_file']}")
    lines.append(f"> Commits: {len(commits)} (showing all)")
    lines.append("")

    if not commits:
        return "\n".join(lines) + "\n"

    for c in commits:
        lines.append(f"## {c['short']} ({c['date']}, {c['author']})")
        lines.append(c["subject"])
        if c.get("body"):
            body = truncate_body(c["body"], max_lines=3)
            lines.append(f'  Body: "{body}"')
        if c.get("refs"):
            lines.append(f"  Refs: {', '.join(c['refs'])}")
        lines.append("")

    lines.append("## Suggested next step")
    lines.append("Run `lore sync` to check whether any of these commits")
    lines.append("introduce a [REFINED] candidate for this entry.")
    lines.append("")
    return "\n".join(lines)


# Exit codes per spec section "Error handling".
ERR_USAGE      = 2  # no arg / unrecognized arg (also used by argparse path)
ERR_NO_LORE    = 2  # .lore/ not found
ERR_NO_ENTRY   = 3  # entry ID not in index
ERR_NOT_GIT    = 4  # not a git repository
ERR_NO_GIT     = 5  # git CLI missing
ERR_BAD_SCOPE  = 6  # scope name not in scopes/
ERR_GIT_FAIL   = 7  # git log returned non-zero for other reasons


def die(code, message):
    """Print message to stderr and exit with the given code."""
    print(f"error: {message}", file=sys.stderr)
    sys.exit(code)


def _load_entries_via_subprocess():
    """Run scripts/list_entries.py --json and return the parsed list.

    Mirrors the pattern in find_duplicates.py / find_stale.py.
    Returns [] if no entries.
    """
    here = Path(__file__).resolve().parent
    cmd = [sys.executable, str(here / "list_entries.py"), "--json"]
    try:
        proc = subprocess.run(
            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
            universal_newlines=True,
            encoding="utf-8", errors="replace", check=False,
        )
    except FileNotFoundError as exc:
        die(ERR_NO_GIT, f"python executable not found: {exc}")
    if proc.returncode != 0:
        die(ERR_NO_LORE, f"list_entries.py failed: {proc.stderr.strip()}")
    try:
        return _json.loads(proc.stdout)
    except _json.JSONDecodeError as exc:
        die(ERR_NO_LORE, f"list_entries.py returned invalid JSON: {exc}")


def _find_lore_root_or_die():
    """Walk up from CWD to find .lore/. Die with ERR_NO_LORE if not found."""
    p = Path(".").resolve()
    while p != p.parent:
        if (p / ".lore").is_dir():
            return p
        p = p.parent
    die(ERR_NO_LORE, ".lore/ not found. Run 'lore init' first.")


def _build_meta_entry(entry, code_file, since, since_source):
    return {
        "entry_id": entry["id"],
        "lore_file": entry["file"],
        "code_file": code_file,
        "since": since,
        "since_source": since_source,
    }


def _resolve_scope_to_md_files(project_root, scope_name):
    """For scope form: list the (layer_file, md_path) tuples under the scope."""
    scopes_dir = project_root / ".lore" / "scopes" / scope_name
    if not scopes_dir.is_dir():
        available = sorted(
            p.name for p in (project_root / ".lore" / "scopes").iterdir()
            if p.is_dir()
        ) if (project_root / ".lore" / "scopes").is_dir() else []
        available_display = ", ".join(available) if available else "(none)"
        die(ERR_BAD_SCOPE, f"Scope '{scope_name}' not found. Available: {available_display}")
    files = []
    for md in sorted(scopes_dir.glob("*.md")):
        files.append((md.stem, md))
    return files


def _is_git_repo(project_root):
    try:
        proc = subprocess.run(
            ["git", "-C", str(project_root), "rev-parse", "--git-dir"],
            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
            universal_newlines=True, encoding="utf-8", errors="replace",
            check=False,
        )
    except FileNotFoundError:
        die(ERR_NO_GIT, "git executable not found on PATH.")
    return proc.returncode == 0


def _enrich_commits_with_body_and_refs(project_root, commits):
    """For each commit, fetch body and extract refs. Mutates in place."""
    for c in commits:
        msg = fetch_commit_body(project_root, c["hash"])
        if msg:
            # Body is everything after the first line.
            parts = msg.split("\n", 1)
            subject = parts[0]
            body = parts[1].strip() if len(parts) > 1 else ""
            c["subject"] = subject
            c["body"] = truncate_body(body, max_lines=3)
            c["refs"] = extract_refs(msg)


def walk_supersede_chain(entries_by_id, start_id, max_depth=20):
    """Follow #superseded-by links forward from start_id.

    Returns a list of entry dicts [start, successor1, successor2, ...].
    Stops when an entry has no replaced_by tag, the target is missing,
    or max_depth is reached (cycle protection).

    `entries_by_id` is a dict {id: entry_dict} from list_entries.py --json.
    """
    chain = []
    seen = set()
    current_id = start_id
    for _ in range(max_depth):
        if current_id in seen:
            break  # cycle; don't loop forever
        seen.add(current_id)
        entry = entries_by_id.get(current_id)
        if entry is None:
            break
        chain.append(entry)
        next_id = entry.get("replaced_by")
        if not next_id:
            break
        current_id = next_id
    return chain


def main():
    args = sys.argv[1:]
    try:
        sys.stdout.reconfigure(encoding="utf-8")
    except AttributeError:  # Python < 3.7
        pass
    json_mode = "--json" in args
    follow_superseded = "--follow-superseded" in args
    since_override = None
    for a in args:
        if a.startswith("--since="):
            since_override = a.split("=", 1)[1]

    positional = [
        a for a in args
        if a != "--json"
        and a != "--follow-superseded"
        and not a.startswith("--since=")
    ]
    if not positional:
        print(
            "usage: lore history <entry-id|file-path|--scope=NAME> "
            "[--follow-superseded] [--since=YYYY-MM-DD] [--json]",
            file=sys.stderr,
        )
        die(ERR_USAGE, "missing argument")

    parsed = parse_arg(positional[0])
    if parsed is None:
        die(ERR_USAGE, f"unrecognized argument: {positional[0]}")

    if follow_superseded and parsed["form"] != "entry":
        print("[WARN] --follow-superseded only applies to the entry form; ignored.",
              file=sys.stderr)

    project_root = _find_lore_root_or_die()

    if not _is_git_repo(project_root):
        die(ERR_NOT_GIT,
            "Not a git repository. 'lore history' requires git; "
            "use 'lore query' for in-memory answers.")

    if parsed["form"] == "entry":
        entries = _load_entries_via_subprocess()
        entries_by_id = {e["id"]: e for e in entries}
        entry = find_entry(entries, parsed["value"])
        if entry is None:
            ids = ", ".join(e["id"] for e in entries[:20])
            more = "" if len(entries) <= 20 else f" (and {len(entries)-20} more)"
            die(ERR_NO_ENTRY,
                f"Entry {parsed['value']} not found. Available: {ids}{more}")

        chain = ([entry] if not follow_superseded
                 else walk_supersede_chain(entries_by_id, entry["id"]))

        if not follow_superseded:
            since = since_override or extract_added_date(entry.get("tags", {}))
            if since is None:
                print("warning: entry has no #added tag; using full history",
                      file=sys.stderr)
                since = "1970-01-01"
            since = normalize_since(since)
            code_file = resolve_code_file(entry)
            try:
                commits = run_git_log(project_root, since, code_file)
            except RuntimeError as exc:
                die(ERR_GIT_FAIL, str(exc))
            _enrich_commits_with_body_and_refs(project_root, commits)
            since_source = "user_arg" if since_override else "entry_added"
            meta = _build_meta_entry(entry, code_file, since, since_source)
            meta["chain"] = None
            meta["_chain_entries"] = None
            out = render_json(meta, commits) if json_mode else render_markdown(meta, commits)
            print(out)
            return

        # --follow-superseded: iterate over the entire chain and collect
        # per-entry logs. Each successor may point at a different file/date.
        per_entry = []
        for idx, e in enumerate(chain):
            if idx == 0 and since_override is not None:
                e_since_raw = since_override
                e_since_source = "user_arg"
            else:
                e_since_raw = extract_added_date(e.get("tags", {}))
                if e_since_raw is None:
                    print(f"warning: entry {e['id']} has no #added tag; using full history",
                          file=sys.stderr)
                    e_since_raw = "1970-01-01"
                e_since_source = "entry_added"
            e_since = normalize_since(e_since_raw)
            e_code_file = resolve_code_file(e)
            try:
                e_commits = run_git_log(project_root, e_since, e_code_file)
            except RuntimeError as exc:
                die(ERR_GIT_FAIL, str(exc))
            _enrich_commits_with_body_and_refs(project_root, e_commits)
            per_entry.append((e, e_since, e_code_file, e_since_source, e_commits))

        if json_mode:
            chain_meta = [
                {
                    "entry_id": e["id"],
                    "lore_file": e["file"],
                    "code_file": cf,
                    "since": s,
                }
                for (e, s, cf, _, _) in per_entry
            ]
            results = [
                {
                    "entry_id": e["id"],
                    "lore_file": e["file"],
                    "code_file": cf,
                    "since": s,
                    "since_source": ss,
                    "commits": commits,
                }
                for (e, s, cf, ss, commits) in per_entry
            ]
            # Top-level keeps first entry's fields for backward compat
            first_e, first_since, first_cf, first_ss, first_commits = per_entry[0]
            payload = {
                "entry_id": first_e["id"],
                "lore_file": first_e["file"],
                "code_file": first_cf,
                "since": first_since,
                "since_source": first_ss,
                "chain": chain_meta,
                "commits": first_commits,
                "results": results,
            }
            # Preserve _chain_entries style for any downstream that expects it
            payload["_chain_entries"] = None
            print(_json.dumps(payload, indent=2, ensure_ascii=False))
            return

        # Markdown: Chain section then per-entry blocks
        out_lines = []
        out_lines.append(f"# history: [{chain[0]['id']}] --follow-superseded")
        out_lines.append("")
        out_lines.append("## Chain")
        for idx, (e, _, _, _, _) in enumerate(per_entry, start=1):
            next_link = (
                f"\n   -> superseded-by -> {e.get('replaced_by')}"
                if e.get("replaced_by") else "\n   -> no successor"
            )
            out_lines.append(
                f"{idx}. [{e['id']}] ({e['file']}) - {e['text']}{next_link}"
            )
        out_lines.append("")
        for (e, e_since, e_code_file, e_since_source, e_commits) in per_entry:
            meta = _build_meta_entry(e, e_code_file, e_since, e_since_source)
            meta["_chain_entries"] = None
            # Render each entry's block without re-adding the Chain header
            block = render_markdown(meta, e_commits)
            # render_markdown starts with "# history: [id]" — keep it, but
            # the top already has the --follow-superseded title.
            out_lines.append(block.rstrip())
            out_lines.append("")
        print("\n".join(out_lines).rstrip() + "\n")
        return

    if parsed["form"] == "file":
        since = since_override or "1970-01-01"
        since = normalize_since(since)
        code_file = parsed["value"]
        try:
            commits = run_git_log(project_root, since, code_file)
        except RuntimeError as exc:
            die(ERR_GIT_FAIL, str(exc))
        _enrich_commits_with_body_and_refs(project_root, commits)
        meta = {
            "entry_id": f"<file:{code_file}>",
            "lore_file": "(direct file query)",
            "code_file": code_file,
            "since": since,
            "since_source": "user_arg" if since_override else "default",
        }
        out = render_json(meta, commits) if json_mode else render_markdown(meta, commits)
        print(out)
        return

    if parsed["form"] == "scope":
        layer_files = _resolve_scope_to_md_files(project_root, parsed["value"])
        scope_payloads = []  # only used when json_mode is True
        scope_since = normalize_since("1970-01-01")
        for layer_name, md_path in layer_files:
            # For scope form we treat each .md file as a "code file" stand-in:
            # we git log the md file's project-relative path to find commits
            # that touched that lore file. (Useful for tracking lore edits.)
            rel = str(md_path.relative_to(project_root)).replace(
                _os.sep, "/"
            )
            try:
                commits = run_git_log(project_root, scope_since, rel)
            except RuntimeError as exc:
                die(ERR_GIT_FAIL, str(exc))
            _enrich_commits_with_body_and_refs(project_root, commits)
            if json_mode:
                meta = {
                    "entry_id": f"<scope:{parsed['value']}/{layer_name}>",
                    "lore_file": rel,
                    "code_file": rel,
                    "since": scope_since,
                    "since_source": "scope_form",
                }
                scope_payloads.append({
                    "layer": layer_name,
                    "payload": _json.loads(render_json(meta, commits)),
                })
            else:
                print(f"## Scope: {parsed['value']} / {layer_name}")
                print("")
                if not commits:
                    print("(no commits)")
                    print("")
                    continue
                for c in commits:
                    print(f"### {c['short']} ({c['date']}, {c['author']})")
                    print(c["subject"])
                    if c.get("body"):
                        print(f'  Body: "{c["body"]}"')
                    if c.get("refs"):
                        print(f"  Refs: {', '.join(c['refs'])}")
                    print("")
        if json_mode:
            print(_json.dumps(
                {
                    "form": "scope",
                    "scope": parsed["value"],
                    "layers": [item["layer"] for item in scope_payloads],
                    "results": scope_payloads,
                },
                indent=2,
                ensure_ascii=False,
            ))
        return


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Compute the 4-char content hash for a lore entry ID.

Usage:
    python id_hash.py "Use Next.js App Router; reason: streaming + RSC"

Output:
    The 4-char lowercase hex hash that goes into an entry's ID, e.g. `a3f2`.

The hash is `sha256(text).hexdigest()[:4]`. This matches the algorithm
in `references/entry-format.md` and what `list_entries.py` uses when
re-reading an entry from disk (it strips `#tag:value` pairs before
hashing). To stay consistent, **pass the entry body WITHOUT the inline
tags** — i.e. the text that goes between the `[ID]` and the first `#`.
Including tags in the input here will produce a different hash than the
file's stored ID, breaking round-trip verification.

Cross-platform: works on Windows / Linux / macOS with Python 3.6+.
"""
import sys
import hashlib


def main():
    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
        print(__doc__, file=sys.stderr)
        sys.exit(0)

    text = sys.argv[1]
    h = hashlib.sha256(text.encode("utf-8")).hexdigest()[:4]
    print(h)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""List all lore entries in `.lore/` as JSON or human-readable text.

Usage:
    python list_entries.py                 # human-readable
    python list_entries.py --json          # JSON output
    python list_entries.py --scope=frontend
    python list_entries.py --layer=ARCH

Walks `.lore/_global/*` and `.lore/scopes/*/*` and parses every
Markdown bullet that matches the entry format. Output is one record per
entry with these fields:

    id              full ID, e.g. "ARCH-2026-07-09-a3f2"
    layer           prefix, e.g. "ARCH" / "DEC" / "CONV"
    layer_file      source file stem, e.g. "ARCHITECTURE"
    scope           scope name, or "_global"
    file            path relative to .lore/, e.g. "scopes/frontend/ARCHITECTURE.md"
    text            entry body, with tags stripped
    tags            dict of tag name -> value, e.g. {"added": "2026-07-09", "verified": "2026-07-15"}
    last_verified   value of #verified tag, or None
    replaced_by     value of #superseded-by tag (replacement entry ID), or None

Used by:
    - query / audit / compress / history workflows (pre-step enumeration)
    - find_duplicates.py
    - find_stale.py
"""
import json
import os
import re
import sys
from pathlib import Path


# Schema version this skill understands. Bumped only on breaking
# config changes; see references/compatibility.md.
KNOWN_SCHEMA_VERSION = 1


def check_schema_version(lore_root: Path) -> None:
    """Warn if .lore/.config.json is missing or has an unknown schema_version.

    Output goes to stderr so it does not pollute --json consumers.
    Idempotent and best-effort: any failure (missing file, malformed
    JSON, permission error) is silent — config is optional and the
    user can address it separately.
    """
    cfg_path = lore_root / ".config.json"
    if not cfg_path.exists():
        return
    try:
        cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError):
        return

    version = cfg.get("schema_version")
    if version is None:
        print(
            "[WARN] .lore/.config.json has no schema_version field. "
            "Add \"schema_version\": 1 so future lore upgrades can detect "
            "this config and prompt for migrations when they exist.",
            file=sys.stderr,
        )
    elif isinstance(version, int) and version > KNOWN_SCHEMA_VERSION:
        print(
            f"[WARN] .lore/.config.json#schema_version={version} is newer "
            f"than this lore skill expects (max: {KNOWN_SCHEMA_VERSION}). "
            "Pull the latest lore from upstream.",
            file=sys.stderr,
        )


def find_lore_root(start: Path) -> Path:
    """Walk up from start to find the project root containing .lore/."""
    p = start.resolve()
    while p != p.parent:
        if (p / ".lore").is_dir():
            return p / ".lore"
        p = p.parent
    return None


def parse_entry(line: str):
    """Parse one Markdown bullet line. Returns dict or None if not an entry."""
    m = re.match(
        r"^\s*-\s*\[([A-Z]+)-(\d{4}-\d{2}-\d{2})-([a-f0-9]{4})\]\s+(.*?)\s*$",
        line,
    )
    if not m:
        return None

    layer, date, h, rest = m.group(1), m.group(2), m.group(3), m.group(4)
    eid = f"{layer}-{date}-{h}"

    # Extract #tag:value pairs.
    # #superseded-by:<id> is special: its value is an entry ID, not a date,
    # so we keep it on a separate `replaced_by` field rather than in `tags`.
    ENTRY_ID = r"[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}"
    tag_re = re.compile(
        r"#(added|verified|stale):(\S+)"
        r"|#superseded-by:(" + ENTRY_ID + r")"
    )
    tags = {}
    replaced_by = None
    for m in tag_re.finditer(rest):
        if m.group(1):
            tags[m.group(1)] = m.group(2)
        elif m.group(3):
            if replaced_by is None:
                replaced_by = m.group(3)
            else:
                print(
                    f"[WARN] entry {eid} carries multiple #superseded-by "
                    "tags; keeping the first only.",
                    file=sys.stderr,
                )
    text = tag_re.sub("", rest).strip()
    # Any #superseded-by still present after the valid-tag strip is
    # malformed (value is not LAYER-YYYY-MM-DD-xxxx). Warn instead of
    # dropping it silently: the entry stays intact in the file, but the
    # chain cannot be resolved and replaced_by stays None.
    for m in re.finditer(r"#superseded-by:(\S+)", text):
        print(
            f"[WARN] entry {eid} has a malformed #superseded-by value "
            f"'{m.group(1)}' (expected LAYER-YYYY-MM-DD-xxxx); chain not "
            "resolved.",
            file=sys.stderr,
        )

    return {
        "id": eid,
        "layer": layer,
        "layer_file": None,  # filled in by caller
        "scope": None,       # filled in by caller
        "file": None,        # filled in by caller
        "text": text,
        "tags": tags,
        "last_verified": tags.get("verified"),
        "replaced_by": replaced_by,
    }


def collect_entries(root: Path):
    entries = []
    layers_dirs = [("_global", root / "_global"), ("scopes", root / "scopes")]

    for section_name, section_path in layers_dirs:
        if not section_path.exists():
            continue
        for md_file in sorted(section_path.rglob("*.md")):
            if section_name == "_global":
                scope = "_global"
            else:
                scope = md_file.parent.name
            layer_file = md_file.stem
            try:
                with open(md_file, encoding="utf-8") as f:
                    lines = f.readlines()
                if lines:
                    # Strip a UTF-8 BOM (Windows editors / PowerShell
                    # Set-Content add one); otherwise the first entry of
                    # the file would fail to parse and be silently skipped.
                    lines[0] = lines[0].lstrip("\ufeff")
                i = 0
                while i < len(lines):
                    # Join wrapped continuation lines into one logical
                    # bullet before parsing. A continuation is a non-blank
                    # line starting with 2+ spaces (or a tab) that is not
                    # itself a new entry bullet. This matches the documented
                    # "2 lines or fewer" bullet format without silently
                    # truncating the entry text.
                    joined = lines[i].rstrip("\n")
                    j = i + 1
                    while j < len(lines):
                        nxt = lines[j].rstrip("\n")
                        if nxt.strip() == "":
                            break
                        if not re.match(r"^\s{2,}", nxt):
                            break
                        if re.match(r"^\s*-\s*\[", nxt):
                            break
                        joined += " " + nxt.strip()
                        j += 1
                    e = parse_entry(joined)
                    if e is None:
                        i += 1
                        continue
                    e["scope"] = scope
                    e["layer_file"] = layer_file
                    e["file"] = str(md_file.relative_to(root)).replace(
                        os.sep, "/"
                    )
                    entries.append(e)
                    i = j
            except OSError as exc:
                print(f"warning: cannot read {md_file}: {exc}", file=sys.stderr)
    return entries


def main():
    args = sys.argv[1:]
    try:
        sys.stdout.reconfigure(encoding="utf-8")
    except AttributeError:  # Python < 3.7
        pass

    scope_filter = None
    layer_filter = None
    json_output = "--json" in args

    for arg in args:
        if arg.startswith("--scope="):
            scope_filter = arg.split("=", 1)[1]
        elif arg.startswith("--layer="):
            layer_filter = arg.split("=", 1)[1]

    root = find_lore_root(Path("."))
    if root is None:
        print("error: .lore/ not found (run from project root or below)",
              file=sys.stderr)
        sys.exit(1)

    check_schema_version(root)
    entries = collect_entries(root)

    if scope_filter:
        entries = [e for e in entries if e["scope"] == scope_filter]
    if layer_filter:
        entries = [e for e in entries if e["layer"] == layer_filter]

    if json_output:
        print(json.dumps(entries, indent=2, ensure_ascii=False))
        return

    if not entries:
        print("(no entries)")
        return

    for e in entries:
        verified = (
            f" [verified:{e['last_verified']}]" if e["last_verified"] else ""
        )
        stale = " [STALE]" if "stale" in e["tags"] else ""
        chain = (
            f" -> {e['replaced_by']}" if e.get("replaced_by") else ""
        )
        print(f"[{e['file']}] {e['id']} {e['text']}{verified}{stale}{chain}")


if __name__ == "__main__":
    main()

# lore scripts

Cross-platform Python 3.6+ helpers that reduce repetitive mechanical work. No third-party dependencies. Called by `init` / `sync` / `query` / `audit` / `compress` / `history`; can also be run standalone for ad-hoc inspection.

The script list and quick-reference command examples live in the project root `README.md` "Scripts" section. This file covers the things that don't fit there: design intent, integration points, and limits.

## Design notes

**Cross-platform first.** Python standard library only. No `bash`, no `jq`, no platform-specific tools. The same invocation works on Windows, Linux, macOS.

**JSON-friendly output.** The entry-inspection scripts (`list_entries.py`, `find_duplicates.py`, `find_stale.py`, and `history.py`) support `--json` for machine consumption. `id_hash.py` emits only the four-character hash. Agent callers parse the output; humans pipe JSON results to `less` or `jq` (if available).

**Composition.** `find_duplicates.py`, `find_stale.py`, and `history.py` shell out to `list_entries.py --json` rather than re-implementing the parser. One source of truth for entry format — if the format ever changes, only `list_entries.py` needs updating.

**Read-only by default.** None of these scripts write to `.lore/`. They observe; the agent decides what to do with findings.

**Run from project root.** `list_entries.py` walks up the directory tree looking for `.lore/`. The other scripts depend on it via subprocess, so the same constraint applies transitively.

## When each script is called

| Script | Call site | Purpose |
|---|---|---|
| `history.py` | lore history | List git commits related to a memory entry / file / scope; with `--follow-superseded`, walks the `#superseded-by` chain forward |
| `id_hash.py` | Any time a new entry is written (init / sync) | Compute the 4-char content hash for the entry ID |
| `list_entries.py` | Pre-step of query / audit / compress / history | Enumerate all entries as JSON for downstream processing; emits `replaced_by` per entry when `#superseded-by` is present |
| `find_duplicates.py` | sync step 5 (de-duplication) | Identify candidate duplicate entries before writing |
| `find_stale.py` | audit step 2; compress step 2 | Identify entries past the reference-date threshold (`#verified` if present, else `#added`) or superseded (carrying `#stale` or `#superseded-by`, which implies staleness); groups pending-review entries by their `#superseded-by` target and reports `BROKEN_CHAIN` orphans |

## Workflow integration

The agent routes memory-specific natural-language requests as well as explicit lore commands; these helpers do not decide when the skill loads or which layer a fact belongs to. For classification, follow `SKILL.md`: ARCH may include a brief reason, while comparisons, tradeoffs, and detailed standalone rationale belong in DEC.

Before appending a candidate, run `python <skill>/scripts/find_duplicates.py --json --candidate "<entry body>"`, passing the body without its ID or tags as one safely quoted argument. Use `--candidate-file <utf8-text-file>` when quoting is awkward; it explicitly reads UTF-8, while the existing `--candidate-stdin` option depends on the host's stdin encoding. With no candidate input, only saved entries are compared. For this check, inspect pairs containing `CANDIDATE-unsaved` and confirm semantic equivalence and scope before skipping a candidate; also compare unsaved candidates with each other.

`list_entries.py --json` intentionally returns active and inactive entries. Current-state query and compress consumers must exclude entries with `"stale"` in `tags` or a non-empty `replaced_by`; the same filter applies before sync bumps `#verified` on a duplicate. A stale entry without a successor is still inactive. Untagged entries remain eligible, and date-based age warnings alone do not exclude entries. `find_stale.py` reports explicitly inactive entries under `pending_review`; its `stale` list is the separate age-based review list. Historical queries and audits retain access to all entries.

## Output channels

**stdout is the data channel; stderr is the warning channel.** All scripts follow this split so `--json` consumers never have to filter noise out of their parsers. `list_entries.py` emits config and entry-parse warnings on stderr:

- `[WARN] .lore/.config.json has no schema_version field.` — fires once per invocation when the config file exists but lacks the version field. Add `"schema_version": 1` to silence it.
- `[WARN] .lore/.config.json#schema_version=N is newer than this lore skill expects (max: 1).` — fires when the config version exceeds what this skill understands. Pull the latest lore from upstream.
- `[WARN] entry <id> carries multiple #superseded-by tags; keeping the first only.` — fires when one entry has more than one valid `#superseded-by` tag.
- `[WARN] entry <id> has a malformed #superseded-by value '<value>' (expected LAYER-YYYY-MM-DD-xxxx); chain not resolved.` — fires when a `#superseded-by` value is not a valid entry ID. The tag stays in the entry text and `replaced_by` stays `None`.

All warnings are informational; `list_entries.py` always produces the same stdout regardless of config state. See `references/compatibility.md` for the full schema versioning policy.

`history.py` can also warn on stderr when an entry has no `#added` tag or when `--follow-superseded` is supplied to a non-entry query. Its stdout remains valid Markdown or JSON.

## Testing

Regression tests live in `tests/` (stdlib-only `unittest`, black-box subprocess runs of the real scripts). Run from the repo root:

```bash
python -m unittest discover -s tests -v
```

The suite builds isolated `.lore/` fixtures in temp directories; the `history.py` cases create throwaway git repos and skip automatically when git is not on PATH.

## Limitations

- **Token-overlap dedup, not semantic.** Jaccard similarity catches rewrites with similar words but misses semantic equivalence (e.g. "use TypeScript" vs "TypeScript-only codebase"). Deeper checks still need an LLM pass.
- **Naive date math.** `find_stale.py` uses wall-clock dates from `#verified` / `#added` tags. If the system's clock is wrong, results will be off.
- **No automatic archival.** The script reports superseded entries (tagged `#stale`, or carrying `#superseded-by`) and broken chains but does not move or delete anything. Outdated entries stay in their scope file with their tags; git history preserves the rest.
- **Different texts can share a hash.** Four hex characters provide 16 bits, so any specific pair of different bodies has a 1-in-65,536 chance of sharing the suffix. If two bodies would produce the same full ID, preserve the existing entry, add a meaningful qualifier to the new body, and recompute; identical text is a duplicate, not a collision.

# lore 脚本

跨平台 Python 3.6+ 辅助脚本，减少重复的机械工作。无第三方依赖。被 `init` / `sync` / `query` / `audit` / `compress` / `history` 调用，也可独立运行做临时检查。

脚本清单和命令速查在仓库根 `README.md` 的"Scripts"章节里。本文件覆盖根 README 不适合放的内容：设计意图、集成点、局限。

## 设计要点

**优先跨平台。** 仅使用 Python 标准库，不依赖 `bash`、`jq` 或任何平台特定工具。Windows / Linux / macOS 行为完全一致。

**JSON 友好输出。** 条目检查脚本（`list_entries.py`、`find_duplicates.py`、`find_stale.py` 和 `history.py`）都支持 `--json`，便于机器消费。`id_hash.py` 只输出四字符 hash。Agent 调用方解析输出；人类可以把 JSON 结果交给 `less` 或 `jq`（如果装了）。

**组合而非重复。** `find_duplicates.py`、`find_stale.py` 和 `history.py` 通过 `list_entries.py --json` 复用解析器，不重复实现 entry 格式解析。Entry 格式只在一处定义——将来格式变更只需改 `list_entries.py`。

**默认只读。** 这些脚本不写 `.lore/`，只观察。Agent 决定如何处理发现的问题。

**从项目根目录运行。** `list_entries.py` 向上遍历定位 `.lore/`。其他脚本通过 subprocess 调用它，所以这个约束会传递生效。

## 何时调用

| 脚本 | 调用点 | 用途 |
|---|---|---|
| `history.py` | lore history | 列出与 memory entry / file / scope 相关的 git commits；带 `--follow-superseded` 时沿 `#superseded-by` 链向前遍历 |
| `id_hash.py` | 写新 entry 时（init / sync）| 计算 entry ID 的 4 字符内容 hash |
| `list_entries.py` | query / audit / compress / history 的预步骤 | 把所有 entry 枚举为 JSON 供后续处理；当 entry 含 `#superseded-by` 时额外输出 `replaced_by` 字段 |
| `find_duplicates.py` | sync 步骤 5（去重）| 写之前找出可能的重复 entry |
| `find_stale.py` | audit 步骤 2；compress 步骤 2 | 找出参考日期（有 `#verified` 用 `#verified`，否则用 `#added`）过期的 entry，或已被取代的 entry（带 `#stale` 或 `#superseded-by`，后者隐式表示过时）；按 `#superseded-by` 目标对 pending-review 分组，并报告 `BROKEN_CHAIN` 孤儿 |

## 工作流集成

Agent 会路由明确针对项目记忆的自然语言请求和显式 lore 命令；这些脚本不决定 skill 何时加载，也不负责条目分层。分类遵循 `SKILL.md`：ARCH 可附简短理由，方案比较、权衡及需要独立展开的详细理由归入 DEC。

追加候选前，运行 `python <skill>/scripts/find_duplicates.py --json --candidate "<entry body>"`，把不含 ID 和标签的正文作为一个安全引用的参数传入。正文不便转义时使用 `--candidate-file <utf8-text-file>`，它明确按 UTF-8 读取，而现有的 `--candidate-stdin` 选项依赖宿主的标准输入编码。不传候选时，只比较已保存条目。检查包含 `CANDIDATE-unsaved` 的结果对，并确认语义和 scope 后再决定是否跳过候选；尚未写入的候选之间也要互相比较。

`list_entries.py --json` 保持枚举有效与失效的全部条目。查询当前状态和 compress 的调用方必须排除 `tags` 中包含 `"stale"` 或 `replaced_by` 非空的条目；sync 为重复条目更新 `#verified` 前也使用同一过滤条件。没有后继的 stale 条目仍然失效。无标签条目仍可使用，单纯的日期久远警告不会使条目被排除。`find_stale.py` 把明确失效的条目放在 `pending_review`，其 `stale` 列表则单独列出因日期久远而需复查的条目。历史查询和 audit 仍可读取全部条目。

## 输出通道

**stdout 是数据通道；stderr 是警告通道。** 所有脚本遵循这个分离，这样 `--json` 消费者就不必从解析结果里过滤噪音。`list_entries.py` 的配置与条目解析警告全部走 stderr：

- `[WARN] .lore/.config.json has no schema_version field.` —— 配置文件存在但缺 `schema_version` 字段时，每个调用触发一次。加 `"schema_version": 1` 即可消除。
- `[WARN] .lore/.config.json#schema_version=N is newer than this lore skill expects (max: 1).` —— 配置版本超过本 skill 能理解的范围时触发。从上游 pull 最新 lore。
- `[WARN] entry <id> carries multiple #superseded-by tags; keeping the first only.` —— 一个 entry 上出现多个合法的 `#superseded-by` 标签时触发。
- `[WARN] entry <id> has a malformed #superseded-by value '<value>' (expected LAYER-YYYY-MM-DD-xxxx); chain not resolved.` —— `#superseded-by` 的值不是合法 entry ID 时触发；标签保留在文本里，`replaced_by` 保持 `None`。

所有警告都是告知性质；`list_entries.py` 不管配置状态如何，stdout 输出始终一致。完整 schema 版本策略见 `references/compatibility.md`。

当条目缺少 `#added` 标签，或对非 entry 查询使用 `--follow-superseded` 时，`history.py` 也可能向 stderr 输出警告；stdout 仍保持为合法 Markdown 或 JSON。

## 测试

回归测试在 `tests/`（纯 stdlib `unittest`，以子进程黑盒方式调用真实脚本）。在仓库根目录运行：

```bash
python -m unittest discover -s tests -v
```

套件会在临时目录里搭建独立的 `.lore/` 夹具；`history.py` 的用例会创建一次性 git 仓库（PATH 上没有 git 时自动跳过）。

## 局限

- **去重只到词袋重叠程度。** Jaccard 相似度能抓到词汇相似的改写，但抓不到语义等价（如 "use TypeScript" vs "TypeScript-only codebase"）。更深的检查仍需 LLM 介入。
- **日期计算比较朴素。** `find_stale.py` 直接用 `#verified` / `#added` 标签的日期。如果系统时钟不对，结果会偏差。
- **不自动 archive。** 脚本会报告已被取代的 entry（带 `#stale`，或带 `#superseded-by`）和坏链，但不会移动或删除任何东西。过期的 entry 留在原 scope 文件、保留原 tag；git 历史保留全部。
- **不同文本可能得到相同 hash。** 4 个十六进制字符提供 16 位空间，任意一对不同正文共享后缀的概率为 1/65536。如果它们会形成相同完整 ID，保留已有 entry，为新正文补充有意义的 scope、对象或适用条件后重新计算；相同正文属于重复，不是碰撞。