opencode-skills-collection 4.0.42 → 4.0.43

package/bundled-skills/lore/references/compatibility.md

@@ -4,18 +4,18 @@ This document defines how `lore` evolves without breaking existing user projects
 
 ## Three principles
 
-1. **Add, never subtract.** New fields, scripts, sections, and reference docs always use new names. Removal happens only after the deprecation cycle (below).
+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/` runs a migration step before writing. It never overwrites old data with new defaults.
+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 field = bump `schema_version` to N+1; old fields stay; the field is added with its default value at first read.
-- Removing a field requires the deprecation cycle (one schema version's worth of warnings before hard removal).
-- Renaming a field: write the new field, copy the value, mark the old one with `_deprecated: "reason"`. The migration tool handles this in `migrate.py`.
+- 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
 
@@ -23,8 +23,8 @@ This document defines how `lore` evolves without breaking existing user projects
 - [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.
-- Tag set is a closed set today: `#added`, `#verified`, `#stale`, `#archived`. Adding a new tag is allowed; old skills' tag parsers (which match `(added|verified|stale|archived)`) silently ignore unknown tags.
+- 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
@@ -34,38 +34,40 @@ 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)
-└── archive/      (referenced in spec; reserved for future)
+└── 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 breaking unless that directory was never actually written (e.g., removing `archive/` today is non-breaking because nothing writes there yet).
+- 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`, plus planned `migrate.py`.
+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; deprecate and add a new one if needed.
-- **Removing is breaking.** A deprecated script stays on disk with a clear "Deprecated: use `migrate.py` instead" header for one schema version.
+- **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 `--v2-output` or a new flag; old flag keeps old behavior forever.
+- **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)
@@ -75,16 +77,18 @@ Mirror files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) follow this contra
 
 Rules:
 
-- `## Lore (auto-managed)` is a **contract string**. Never rename; never remove. Mirror detection regexes depend on it.
+- `<!-- 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` and `---` is lore's domain; content after `---` is the user's. Respect the boundary on every regeneration.
-- Adding a new auto-managed section (e.g., `## Sync history (auto-managed)`) is allowed; insert before `---`. Old skills ignore 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: `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).
+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:
 
@@ -93,122 +97,47 @@ Rules:
 - **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 tool
-
-`scripts/migrate.py` does not exist in v1. It will be added on the first `schema_version` bump.
-
-**Triggers that will ship the first migration:**
-
-- A new required field is added to `.lore/.config.json`.
-- A field is renamed or its accepted values are tightened.
-- The entry ID algorithm changes.
-
-Until any of these happen, `schema_version: 1` is the only version and no migration is possible or needed.
-
-Until the script ships, `list_entries.py` emits a one-time warning to stderr if `.lore/.config.json` is missing the `schema_version` field. This nudges users to add the field manually before the first breaking change ships, so future upgrades can detect the version mismatch correctly.
-
-**Template — to be implemented when the first migration is needed:**
-
-```python
-#!/usr/bin/env python3
-"""Migrate .lore/.config.json from version N to N+1.
-
-Idempotent: running twice produces no further changes.
-Refuses to run if schema_version > EXPECTED_FROM.
-"""
-import json, sys
-from pathlib import Path
-
-EXPECTED_FROM = 1   # versions this script can read
-TARGET = 2          # current schema version after migration
-
+## Migration
 
-def migrate(config: dict) -> tuple[dict, list[str]]:
-    msgs = []
-    # v1 → v2 transformations go here. Example:
-    # if config.get("mirror_mode") == "summary":
-    #     config.pop("mirror_mode", None)
-    #     msgs.append('removed deprecated "mirror_mode": "summary"')
-    config["schema_version"] = TARGET
-    return config, msgs
+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.
 
-def main() -> int:
-    cfg_path = Path(".lore/.config.json")
-    if not cfg_path.exists():
-        print(f"error: {cfg_path} not found", file=sys.stderr)
-        return 1
-    cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
-    current = cfg.get("schema_version", 1)
-    if current > EXPECTED_FROM:
-        print(
-            f"error: schema_version={current} is newer than this skill "
-            f"can read (max: {EXPECTED_FROM}). Pull latest lore.",
-            file=sys.stderr,
-        )
-        return 2
-    if current < TARGET:
-        print(f"migrating v{current} → v{TARGET}...")
-    cfg, msgs = migrate(cfg)
-    for m in msgs:
-        print(f"  - {m}")
-    cfg_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
-    print("done.")
-    return 0
+## Deprecation
 
-
-if __name__ == "__main__":
-    sys.exit(main())
-```
-
-## Deprecation workflow
-
-Any capability slated for removal follows a three-stage cycle. The minimum cycle is **two schema versions** (typically 6–12 months).
-
-| Stage | Schema version | Behavior |
-|---|---|---|
-| **Announce** | N | Add an entry to `references/deprecations.md` with the feature name, replacement, and removal target version. The skill prints a one-line notice when the feature is used. |
-| **Warn** | N+1 | The skill prints a louder warning (with remediation steps) and writes a `_deprecation_warnings_shown` array to `.lore/.config.json` so the warning doesn't repeat. |
-| **Remove** | N+2 | Hard delete. Old `.lore/` data is migrated by `migrate.py` to the new format. Users who skipped migrations will see explicit errors pointing at `migrate.py`. |
-
-Skipping a stage is allowed only for security fixes or unreleased features that were never shipped.
+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
 
-A compatibility CI job (planned for `.github/workflows/compat.yml`) verifies:
-
-1. **New skill reads old `.lore/`**: checkout a fixture project from `fixtures/v0-project/`, run `list_entries.py`, `history.py`, `find_stale.py` on it. Pass = no exceptions, correct counts.
-2. **Old skill reads new `.lore/`**: build a fixture with the latest schema, check out the previous release's scripts, run them. Pass = no exceptions on known fields; unknown fields silently ignored.
-3. **No rename or delete in `scripts/` or `references/`**: PR diff against `scripts/` and `references/` filenames; any removed file = failure.
-
-At least one fixture project must be checked in at `fixtures/v0-project/` and re-pinned to a known old schema version after each major release.
+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 `compress_thresholds.max_entries_per_scope` field:
+Adding a new optional field, for example `compress_thresholds.max_entries_per_scope` with default `100`:
 
-- Bump `schema_version` to 2.
-- `migrate.py` v1 → v2: add the new field with default `100` if absent.
-- Old skill reads v2 config: sees only the fields it knows; ignores `max_entries_per_scope`.
-- New skill reads v1 config: detects `schema_version` mismatch, refuses to write until migration runs.
+- 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`:
+Renaming `mirror_mode` to `render_mode` in a single release:
 
-- Every existing `.lore/.config.json` would silently lose its `mirror_mode: "index"` setting on next migration (old field dropped, new field absent → defaults kick in).
-- Bad. Instead: add `render_mode` as the new canonical field; mark `mirror_mode` as `_deprecated`; keep both for one schema version; eventually remove `mirror_mode` via the deprecation cycle.
+- 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 (deprecation cycle required)
+### Breaking change (commit message)
 
-Removing support for `mirror_mode: "full"`:
+Removing support for a config value such as `mirror_mode: "full"`:
 
-- v1: ship `mirror_mode: "full"` as deprecated; full mode still works.
-- v2: print warning when `"full"` is set; suggest migrating to `"index"`.
-- v3: hard reject `"full"`; `migrate.py` auto-converts to `"index"`.
-- Each version's release notes link to the deprecation entry in `references/deprecations.md`.
+- 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
 
@@ -216,13 +145,14 @@ Before merging any change to lore, answer these questions:
 
 1. Does this change add, modify, or remove anything in `.lore/`?
 2. Does this change add, modify, or remove any script in `scripts/`?
-3. Does this change add, modify, or remove any contract string (`## Lore (auto-managed)`, `## My notes (free edit)`, etc.)?
+3. Does this change add, modify, or remove any contract string (`## Lore (auto-managed)`, `## My notes (free edit)`, `<!-- LORE:START -->`, `<!-- LORE:END -->`, etc.)?
 4. Does this change add, modify, or remove any reference doc filename?
 5. Does this change add, modify, or remove any entry tag?
 
-If any answer is "modify" or "remove", the change requires either:
-- A migration step in `migrate.py` (for schema changes)
-- A deprecation cycle (for removals)
-- An entry in `references/deprecations.md`
+If any answer is "add" and the change is non-breaking (new optional field, new optional tag, new doc, new script), ship as-is with a regular commit prefix (`feat:`, `docs:`, `refactor:`).
+
+If any answer is "modify" or "remove", 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 "add" or "no", the change is non-breaking and can ship as a minor or patch release.
+If all answers are "add" or "no", the change is non-breaking and ships as a regular commit.

package/bundled-skills/lore/references/config.md

@@ -19,7 +19,8 @@
   "sync_thresholds": {
     "min_lines_changed": 50,
     "min_directories_changed": 2
-  }
+  },
+  "last_sync_sha": "f9ca271..."  // set automatically by sync; null on first run
 }
 ```
 
@@ -29,10 +30,9 @@
 
 - **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.
-- **Lower than expected** → refuse to write; ask the user to run the migration script shipped with that future release.
-- **Higher than expected** → refuse to read with an error; the user's skill is older than their `.lore/`. They need to upgrade lore (pull latest from upstream) before continuing.
+- **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 (migration tools, deprecation cycle, reader/writer contracts), see `references/compatibility.md`.
+For the full compatibility policy, see `references/compatibility.md`.
 
 ## Field semantics
 
@@ -40,10 +40,10 @@ For the full compatibility policy (migration tools, deprecation cycle, reader/wr
 
 Default: `false`.
 
-Controls whether `compress` and `lore mirror` regenerate platform mirrors automatically after the canonical change is accepted.
+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` — regenerate mirrors automatically
-- `false` — ask per target before writing
+- `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`).
 
@@ -63,8 +63,8 @@ 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, equivalent REFINEDs). `NEW`, `STALE`, and `ALERT` require confirmation.
-- `"low"` — every change requires confirmation, including de-duplicate hits and equivalent REFINEDs.
+- `"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`
 
@@ -88,7 +88,7 @@ When auto-detection is in effect, `lore init` populates this field with the user
 
 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 (~500 B) regardless of project size.
+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"`.
 
@@ -104,22 +104,21 @@ 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.
 
-## Editing the config
+### `last_sync_sha`
 
-Edit `.lore/.config.json` directly. After editing:
+Default: absent (treated as `null`).
 
-- `sync` and `compress` re-read the config on every run; no restart needed.
-- Invalid JSON → fall back to defaults + warn the user.
-- After editing, verify with `python scripts/list_entries.py --config-check` (added in a future migration).
-- For schema version changes, see `references/compatibility.md`.
+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.
 
-## Upgrade path
+- **Absent or `null`** — `sync` falls back to working-tree diff alone (`git diff`, working tree vs. `HEAD`). 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 working-tree diff for uncommitted 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`; only the working-tree diff applies.
 
-When a future lore release introduces the first `schema_version` bump:
+## Editing the config
 
-1. That release ships `scripts/migrate.py` for the specific version bump.
-2. The skill prompts: "Your `.lore/.config.json` is v1; lore now expects v2. Run `python scripts/migrate.py` to upgrade."
-3. `migrate.py` is idempotent — running it twice is a no-op.
-4. After migration, the file is updated in place; no manual editing needed.
+Edit `.lore/.config.json` directly. After editing:
 
-In v1, no migration has shipped and `scripts/migrate.py` does not exist. Add `"schema_version": 1` manually to old configs to silence the warning.
+- `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.

package/bundled-skills/lore/references/entry-format.md

@@ -27,14 +27,18 @@ The 4-char `xxxx` is the first 4 hex chars of `sha256(entry text)`. This makes I
 
 If two entries have identical content (hash collision, statistically rare), add a distinguishing word to one and recompute.
 
+### 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 superseded or contradicted; user decides keep/archive |
-| `#archived:YYYY-MM-DD` | Moved to `archive/` |
+| `#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`).
 
@@ -60,6 +64,32 @@ If a fact can't fit in ≤ 2 lines, split into multiple entries and cross-refere
 
 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 entry plus every successor along the chain (newest first).
+- `compress` — skips entries with `replaced_by` set 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: the ID is sufficient because the LAYER prefix plus hash makes collisions across files vanishingly rare. If two files contain the same ID, prefer the one in the same scope as the entry being read.
+
 ## What counts as "atomic"
 
 A fact is atomic if it answers exactly one question:
@@ -67,4 +97,4 @@ A fact is atomic if it answers exactly one question:
 - "What is the frontend framework?" → `ARCH` entry about Next.js
 - "Why Next.js not Remix?" → `DEC` entry referencing the `ARCH` entry
 
-If your entry answers two questions, split it.
+If your entry answers two questions, split it.

package/bundled-skills/lore/references/history-command.md

@@ -11,6 +11,7 @@ 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
 ```
 
@@ -19,9 +20,36 @@ lore history --json
 | 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. |
+| File  | contains `/` or starts with `.` | `lore history frontend/src/store/index.ts` | Run the full `git log` on the given path unless `--since` is provided. |
 | 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 not just the requested entry's git history, but the history of every entry in its `#superseded-by` chain (newest successor first). 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:
@@ -59,6 +87,7 @@ appears only when at least one commit is found.
   "code_file": "frontend/src/store/index.ts",
   "since": "2026-02-03",
   "since_source": "entry_added",
+  "chain": null,
   "commits": [
     {
       "hash": "...",
@@ -73,6 +102,8 @@ appears only when at least one commit is found.
 }
 ```
 
+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 |
@@ -103,4 +134,69 @@ appears only when at least one commit is found.
 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.
+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.
+
+File and scope forms without an explicit `--since`, and entry forms
+without an `#added` tag, omit Git's `--since` option so they truly scan
+the full history. Their JSON metadata retains
+`"1970-01-01T00:00:00"` as the backward-compatible default marker;
+that marker is not passed to Git because the exact Unix epoch can be
+treated as a sentinel and incorrectly return no commits.
+
+## 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.