opencode-skills-collection 4.0.42 → 4.0.43

package/bundled-skills/lore/references/platform-mirrors.md

@@ -121,6 +121,7 @@ Both paths use the same function. Once `init` has run, `mirror_targets` is set,
 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)
@@ -131,6 +132,7 @@ Every mirror file is split into two sections by a `---` separator. The top secti
 ## Global
 - Monorepo with pnpm workspaces + Turborepo — [_global/ARCHITECTURE.md#ARCH-2026-01-15-d7a3]
 ...
+<!-- LORE:END -->
 
 ---
 
@@ -141,7 +143,7 @@ Every mirror file is split into two sections by a `---` separator. The top secti
 - Prefer English
 ```
 
-The `---` separator is a literal Markdown horizontal rule. Both sections are plain Markdown so any agent or editor can render them normally.
+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
 
@@ -151,6 +153,30 @@ When syncing a mirror file:
 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
 
@@ -196,7 +222,7 @@ The `init` command extends the resolution algorithm above with classification an
 
    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.
+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).
@@ -208,7 +234,7 @@ The `init` command extends the resolution algorithm above with classification an
 6. **Write `.lore/.config.json`** with `mirror_targets` populated.
 
 7. **Generate initial mirror files** for each target:
-   - File absent → full template (`## Lore` + `---` + empty `## My notes`).
+   - 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.
@@ -216,9 +242,11 @@ The `init` command extends the resolution algorithm above with classification an
 For each generated mirror file, the section template is:
 
 ```
+<!-- LORE:START -->
 ## Lore (auto-managed)
 
 <initial or refreshed Lore content>
+<!-- LORE:END -->
 
 ---
 
@@ -229,16 +257,17 @@ For each generated mirror file, the section template is:
 
 ## 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 (~500 B 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 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. Read deeper on demand.
+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)
@@ -249,13 +278,14 @@ Project memory. Read deeper on demand.
   ...
 
 **Query**: `lore query <term>` or `lore query <scope>:<term>`
-**Update**: see the `lore` skill (init / sync / query / audit / compress / mirror)
+**Update**: see the `lore` skill (init / sync / query / audit / compress / mirror / history)
+<!-- LORE:END -->
 
 ---
 ## My notes (free edit)
 ```
 
-The `## Lore (auto-managed)` opener, `---` separator, and `## My notes (free edit)` closer are **always present** — only the `**Structure**:` body varies with adaptive rendering. Agent preserves the My notes section verbatim across regenerations.
+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
 
@@ -276,20 +306,24 @@ The index does **not** track the project's source-directory mapping for each sco
 
 ### Adaptive renderings
 
-Only the `**Structure**:` body varies. The `## Lore (auto-managed)` opener, `---` separator, and `## My notes (free edit)` closer are always present and unchanged.
+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. Read deeper on demand.
+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)
@@ -359,12 +393,7 @@ Index content changes require regeneration when:
 
 ## Manual operations
 
-| Command | Effect |
-|---|---|
-| `lore mirror` | Force-regenerate all configured platform mirrors from current `.lore/*` state. Content-based dedup: skips targets whose new Lore section matches the existing one. |
-| `lore mirror reset <file>` | Archive current My notes content to `.lore/.archive/<file>-<date>.md`, then write a clean mirror with only the Lore section. User must confirm. |
-| `lore mirror show <file>` | Print the file with the two sections clearly delimited in the output. Pure read. |
-| `lore mirror check` | For each configured target, verify it has a `---` separator and a `## My notes` section. Report any structural problems. Read-only. |
+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
 
@@ -373,5 +402,5 @@ Index content changes require regeneration when:
 | `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` | Force-regenerate all configured targets with content-based dedup. |
+| `lore mirror` | Regenerate all configured targets with content-based dedup. |
 | `query` / `audit` | Never touches mirrors. |

package/bundled-skills/lore/references/stale-new-markers.md

@@ -8,7 +8,7 @@ When `sync` proposes a change, it never silently mutates files. Instead it emits
 |---|---|
 | `[NEW]` | Propose adding a new entry |
 | `[STALE]` | Propose marking an existing entry as superseded/contradicted |
-| `[REFINED]` | Propose updating an existing entry's text in place |
+| `[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 |
 
@@ -19,12 +19,14 @@ When `sync` proposes a change, it never silently mutates files. Instead it emits
 - [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 archive
-- [scopes/frontend/ARCHITECTURE.md] [ARCH-2026-01-15-d7a3] Use Pages Router (Next.js). #stale: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") → "use Zustand v4+ with slices pattern" #verified:2026-07-09
+- [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.
@@ -50,13 +52,13 @@ For partial acceptance, the user should explicitly list which items to apply.
 | Marker | File action |
 |---|---|
 | `[NEW]` | Append a new bullet to the named file, with `#added:<today>` |
-| `[STALE]` | Append `#stale:<today>` tag to the existing entry; entry stays in the file |
-| `[REFINED]` | Replace the entry text in place, keep the ID, update `#verified:<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 a `#stale` tag until the user (or a later sync) explicitly moves it to `archive/`. This keeps the rollback path clean.
+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]`) 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.
+`audit` does **not** use these markers. It writes its own severity tags (`[CONFLICT]`, `[STALE]`, `[UNVERIFIED]`) 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.

package/bundled-skills/lore/references/summary-template.md

@@ -9,6 +9,7 @@
 
 > 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/`)
 
@@ -41,6 +42,7 @@
 
 For each (scope, layer) tuple, pick entries by this priority:
 
+0. **Skip entries with `#superseded-by:<id>`.** These are historical entries replaced by a newer one; the SUMMARY should reflect current state, not chain history.
 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
@@ -56,6 +58,7 @@ If a (scope, layer) is empty, omit the subsection entirely.
 
 > 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/`)
 
@@ -93,6 +96,10 @@ If a (scope, layer) is empty, omit the subsection entirely.
 - 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.
+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.

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

@@ -0,0 +1,192 @@
+# 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` (working tree vs. `HEAD`) — always included. Catches uncommitted changes that are not yet in any commit.
+   - **Re-scan any new files**.
+   - **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`; only the working tree diff applies.
+2. **Determine target scope(s)** for each change. Use `git diff --name-only` paths (over the combined commit + working-tree diff) to 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: the choice itself ("we use X") -> `ARCHITECTURE.md`; the reasoning ("why X over Y") -> `DECISIONS.md`. If both apply, write two entries and cross-reference them by ID.
+   - **Decision check (mandatory before step 4).** Ask explicitly for every change: did we pick one option over an alternative ("use X instead of Y", "we chose X over Y", "reason: ..."), or does any draft `ARCHITECTURE` text explain *why* (signals: `reason:`, `because`, `for <purpose>`, any mention of an alternative)? If yes, that reasoning is a `DEC` candidate and must not be silently folded into an ARCH entry — emit the fact in `ARCHITECTURE.md` and the reasoning in `DECISIONS.md`, cross-referenced by ID. If you conclude no DEC is warranted, state that explicitly in the proposal so the user can veto.
+   - **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, run `python skill/scripts/find_duplicates.py --json` (when lore is installed as a skill the path is `<skill>/scripts/find_duplicates.py`) to identify any candidate entry that overlaps with existing entries (same hash, or Jaccard >= `--threshold`). For each match, skip the new entry and bump `#verified` on the existing one. If the new entry is genuinely different in meaning (the script flags but doesn't decide), keep both.
+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 silently 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.
+   - **Skip entries with `#superseded-by:<id>`.** The replacement is current; the superseded entry is historical. Same filter `compress` applies (see `references/summary-template.md` selection rule 0). If the user's question is about how something evolved ("why did we switch from X to Y?"), use the `history` workflow instead — `history --follow-superseded <id>` walks the chain.
+   - **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. Optionally run `python skill/scripts/find_stale.py --json` to identify entries that shouldn't anchor the summary (recently-stale or long-unverified).
+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 never happens silently:** file mutation (sync proposes; user accepts/rejects); platform mirror rewrite on every sync (separate command); `compress` deleting entries (only writes SUMMARY.md); entry marked as `[STALE]` without proposal; `init` overwriting 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`).

package/bundled-skills/lore/scripts/README.md

@@ -1,6 +1,6 @@
 # lore scripts
 
-Cross-platform Python 3.6+ helpers that reduce repetitive mechanical work. No third-party dependencies. Called by `init` / `sync` / `audit` / `compress` / `lore mirror`; can also be run standalone for ad-hoc inspection.
+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.
 
@@ -10,7 +10,7 @@ The script list and quick-reference command examples live in the project root `R
 
 **JSON-friendly output.** Every script supports `--json` for machine consumption. Agent callers parse the output; humans pipe to `less` or `jq` (if available).
 
-**Composition.** `find_duplicates.py` and `find_stale.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.
+**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.
 
@@ -20,35 +20,36 @@ The script list and quick-reference command examples live in the project root `R
 
 | Script | Call site | Purpose |
 |---|---|---|
-| `history.py` | lore history | List git commits related to a memory entry / file / scope |
+| `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 | Enumerate all entries as JSON for downstream processing |
+| `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; lore mirror (optional) | Identify entries past the verified-date threshold or already marked `#stale` |
+| `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 |
 
 ## 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. Currently `list_entries.py` is the only script that emits a warning:
+**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` is the only script that emits warnings, all 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`.
 
-Both 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.
+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.
 
 ## Testing
 
-Without a real `.lore/`, you can sanity-check that imports and argument parsing work:
+Regression tests live in `tests/` (stdlib-only `unittest`, black-box subprocess runs of the real scripts). Run from the repo root:
 
 ```bash
-python scripts/id_hash.py "test entry"
-python scripts/list_entries.py   # should print "(no entries)" or exit with a clear error
+python -m unittest discover -s tests -v
 ```
 
-`list_entries.py`, `find_duplicates.py`, and `find_stale.py` require a populated `.lore/` to produce meaningful output. Set one up via `lore init` first.
+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 archive promotion.** The script reports pending-archive entries but does not move them. Use `lore sync` to actually relocate to `.lore/archive/`.
-- **Hash collisions on identical text are theoretically possible** (4 hex chars = 16 bits = 1 in 65536). In practice a lore project will not hit this. If it does, slightly edit the entry text to bump the hash.
+- **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.
+- **Hash collisions on identical text are theoretically possible** (4 hex chars = 16 bits = 1 in 65536). In practice a lore project will not hit this. If it does, slightly edit the entry text to bump the hash.

package/bundled-skills/lore/scripts/README.zh-CN.md

@@ -1,6 +1,6 @@
 # lore 脚本
 
-跨平台 Python 3.6+ 辅助脚本，减少重复的机械工作。无第三方依赖。被 `init` / `sync` / `audit` / `compress` / `lore mirror` 调用，也可独立运行做临时检查。
+跨平台 Python 3.6+ 辅助脚本，减少重复的机械工作。无第三方依赖。被 `init` / `sync` / `query` / `audit` / `compress` / `history` 调用，也可独立运行做临时检查。
 
 脚本清单和命令速查在仓库根 `README.md` 的"Scripts"章节里。本文件覆盖根 README 不适合放的内容：设计意图、集成点、局限。
 
@@ -10,7 +10,7 @@
 
 **JSON 友好输出。** 每个脚本都支持 `--json` 便于机器消费。Agent 调用方解析输出；人类可以直接 `less` 或 `jq`（如果装了）。
 
-**组合而非重复。** `find_duplicates.py` 和 `find_stale.py` 通过 `list_entries.py --json` 复用解析器，不重复实现 entry 格式解析。Entry 格式只在一处定义——将来格式变更只需改 `list_entries.py`。
+**组合而非重复。** `find_duplicates.py`、`find_stale.py` 和 `history.py` 通过 `list_entries.py --json` 复用解析器，不重复实现 entry 格式解析。Entry 格式只在一处定义——将来格式变更只需改 `list_entries.py`。
 
 **默认只读。** 这些脚本不写 `.lore/`，只观察。Agent 决定如何处理发现的问题。
 
@@ -20,35 +20,36 @@
 
 | 脚本 | 调用点 | 用途 |
 |---|---|---|
-| `history.py` | lore history | 列出与 memory entry / file / scope 相关的 git commits |
+| `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 的预步骤 | 把所有 entry 枚举为 JSON 供后续处理 |
+| `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；lore mirror（可选）| 找出过期 entry 或已标记 `#stale` 的 entry |
+| `find_stale.py` | audit 步骤 2；compress 步骤 2 | 找出参考日期（有 `#verified` 用 `#verified`，否则用 `#added`）过期的 entry，或已被取代的 entry（带 `#stale` 或 `#superseded-by`，后者隐式表示过时）；按 `#superseded-by` 目标对 pending-review 分组，并报告 `BROKEN_CHAIN` 孤儿 |
 
 ## 输出通道
 
-**stdout 是数据通道；stderr 是警告通道。** 所有脚本遵循这个分离，这样 `--json` 消费者就不必从解析结果里过滤噪音。当前只有 `list_entries.py` 会发警告：
+**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`。
+所有警告都是告知性质；`list_entries.py` 不管配置状态如何，stdout 输出始终一致。完整 schema 版本策略见 `references/compatibility.md`。
 
 ## 测试
 
-没有真实 `.lore/` 时，可以快速验证 import 和参数解析是否正常：
+回归测试在 `tests/`（纯 stdlib `unittest`，以子进程黑盒方式调用真实脚本）。在仓库根目录运行：
 
 ```bash
-python scripts/id_hash.py "test entry"
-python scripts/list_entries.py   # 应输出 "(no entries)" 或清晰报错
+python -m unittest discover -s tests -v
 ```
 
-`list_entries.py`、`find_duplicates.py`、`find_stale.py` 需要有内容的 `.lore/` 才能产出有意义的输出。先用 `lore init` 建一个。
+套件会在临时目录里搭建独立的 `.lore/` 夹具；`history.py` 的用例会创建一次性 git 仓库（PATH 上没有 git 时自动跳过）。
 
 ## 局限
 
 - **去重只到词袋重叠程度。** Jaccard 相似度能抓到词汇相似的改写，但抓不到语义等价（如 "use TypeScript" vs "TypeScript-only codebase"）。更深的检查仍需 LLM 介入。
 - **日期计算比较朴素。** `find_stale.py` 直接用 `#verified` / `#added` 标签的日期。如果系统时钟不对，结果会偏差。
-- **不自动 archive。** 脚本会报告待 archive 的 entry，但不会移动它们。实际搬迁到 `.lore/archive/` 仍需通过 `lore sync` 完成。
-- **理论上可能有 hash 冲突**（4 个十六进制字符 = 16 位 = 1/65536 概率）。实际项目基本不会遇到。如果遇到了，对 entry 文本做微调以改变 hash。
+- **不自动 archive。** 脚本会报告已被取代的 entry（带 `#stale`，或带 `#superseded-by`）和坏链，但不会移动或删除任何东西。过期的 entry 留在原 scope 文件、保留原 tag；git 历史保留全部。
+- **理论上可能有 hash 冲突**（4 个十六进制字符 = 16 位 = 1/65536 概率）。实际项目基本不会遇到。如果遇到了，对 entry 文本做微调以改变 hash。