@fenglimg/fabric-cli 2.0.0-rc.36 → 2.0.0-rc.38

package/templates/hooks/lib/config-cache.cjs

@@ -0,0 +1,107 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared fabric-config reader for hook scripts.
+ *
+ * Before this lib, every hook re-implemented the same defensive
+ * `readFileSync(.fabric/fabric-config.json) → JSON.parse → validate one key →
+ * fall back to default` boilerplate, once PER KEY (knowledge-hint-broad alone
+ * read the file 5× per SessionStart fire: cooldown / top_k / underseed /
+ * summary_max_len / reminder_to_context). This module centralises the read +
+ * mtime-keyed memoisation so a single hook fire parses the config once.
+ *
+ * Provides:
+ *   - readConfig(projectRoot) → object
+ *       Parsed fabric-config.json (memoised on path+mtime). Returns `{}` on
+ *       any failure (missing file / parse error / non-object). Never throws.
+ *       mtime-keyed so a config rewrite mid-process (test harness) invalidates
+ *       the cached value automatically — production hooks are single-shot so
+ *       the common case is one stat + one parse.
+ *   - readConfigNumber(root, key, fallback, { min, max, integer }) → number
+ *   - readConfigBoolean(root, key, fallback) → boolean
+ *   - readConfigString(root, key, fallback) → string
+ *       Typed getters with inline range/shape validation; any miss → fallback.
+ *   - configPathFor(projectRoot) → absolute config path
+ *   - clearConfigCache() → void   (test helper)
+ *
+ * Never-throw contract: every export degrades to its fallback rather than
+ * throwing, preserving the reminder-layer hook invariant (KT-DEC-0007: hooks
+ * never block on their own malfunction).
+ */
+
+const { existsSync, readFileSync, statSync } = require("node:fs");
+const { join } = require("node:path");
+
+const FABRIC_DIR_REL = ".fabric";
+const FABRIC_CONFIG_FILE = "fabric-config.json";
+
+// path → { mtime, value }. Per-process; mtime-keyed for test-mutation safety.
+const _cache = new Map();
+
+function configPathFor(projectRoot) {
+  return join(projectRoot, FABRIC_DIR_REL, FABRIC_CONFIG_FILE);
+}
+
+function readConfig(projectRoot) {
+  const path = configPathFor(projectRoot);
+  let mtime;
+  try {
+    if (!existsSync(path)) {
+      _cache.delete(path);
+      return {};
+    }
+    mtime = statSync(path).mtimeMs;
+  } catch {
+    return {};
+  }
+  const cached = _cache.get(path);
+  if (cached && cached.mtime === mtime) return cached.value;
+  let value = {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw && typeof raw === "object") value = raw;
+  } catch {
+    value = {};
+  }
+  _cache.set(path, { mtime, value });
+  return value;
+}
+
+function clearConfigCache() {
+  _cache.clear();
+}
+
+// opts:
+//   min / max   — inclusive range; out-of-range → fallback
+//   integer     — require Number.isInteger; non-integer → fallback (strict)
+//   floor       — accept any in-range number, return Math.floor(v) (lenient)
+// `integer` and `floor` are independent: `integer` rejects fractional values,
+// `floor` truncates them. Pick whichever matches the caller's legacy contract.
+function readConfigNumber(projectRoot, key, fallback, opts) {
+  const { min, max, integer, floor } = opts || {};
+  const v = readConfig(projectRoot)[key];
+  if (typeof v === "number" && Number.isFinite(v)) {
+    if (integer && !Number.isInteger(v)) return fallback;
+    if (typeof min === "number" && v < min) return fallback;
+    if (typeof max === "number" && v > max) return fallback;
+    return floor ? Math.floor(v) : v;
+  }
+  return fallback;
+}
+
+function readConfigBoolean(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "boolean" ? v : fallback;
+}
+
+function readConfigString(projectRoot, key, fallback) {
+  const v = readConfig(projectRoot)[key];
+  return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+
+module.exports = {
+  readConfig,
+  clearConfigCache,
+  readConfigNumber,
+  readConfigBoolean,
+  readConfigString,
+  configPathFor,
+};

package/templates/hooks/lib/state-store.cjs

@@ -0,0 +1,84 @@
+/**
+ * v2.0.0-rc.37 NEW-19: shared `.fabric/.cache/` sidecar I/O for hook scripts.
+ *
+ * Hooks persist tiny per-session state (turn counters, last-emit timestamps,
+ * shown-hint sets) under `.fabric/.cache/`. Each hook had its own copy of the
+ * read-JSON-or-null / write-JSON-best-effort / read-text / write-text helpers
+ * (cite-policy-evict's readEvictState/writeEvictState, broad's
+ * readBroadLastEmit/writeBroadLastEmit, fabric-hint's shown-cache + edit-counter
+ * + maintenance-last-emit). This module is the single canonical implementation.
+ *
+ * Provides (all keyed on a bare `fileName` resolved under .fabric/.cache/):
+ *   - cachePath(projectRoot, fileName) → absolute path
+ *   - readJsonState(root, fileName, validate?) → parsed | null
+ *       null on missing / parse error / validate() === false. Never throws.
+ *   - writeJsonState(root, fileName, value) → boolean
+ *       mkdir -p + write; false on failure. Never throws.
+ *   - readTextState(root, fileName) → trimmed string | null
+ *   - writeTextState(root, fileName, text) → boolean
+ *
+ * Never-throw contract: write failures return false (counter loss is
+ * acceptable — the hook never blocks user flow on sidecar I/O, KT-DEC-0007).
+ */
+
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const CACHE_DIR_REL = join(".fabric", ".cache");
+
+function cachePath(projectRoot, fileName) {
+  return join(projectRoot, CACHE_DIR_REL, fileName);
+}
+
+function readJsonState(projectRoot, fileName, validate) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof validate === "function" && !validate(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonState(projectRoot, fileName, value) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readTextState(projectRoot, fileName) {
+  const path = cachePath(projectRoot, fileName);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeTextState(projectRoot, fileName, text) {
+  const path = cachePath(projectRoot, fileName);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(text));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  cachePath,
+  readJsonState,
+  writeJsonState,
+  readTextState,
+  writeTextState,
+  CACHE_DIR_REL,
+};

package/templates/skills/fabric-archive/SKILL.md

@@ -21,11 +21,17 @@ If none hold, stop the skill and tell the user (UX i18n Policy class 2):
 
 Render per `fabric_language` resolved in Phase 0.5.
 
-This skill is `Check-not-Ask`, not a preference interview. Phase 2 proactively gathers evidence; Phase 2.5 viability gate aborts if no archive signal exists; Phase 3 classifies / layers / slugs + batch-review; Phase 4 persists via `fab_extract_knowledge` (one call per candidate).
+This skill runs automatically — it does not interview the user for preferences. It gathers evidence, aborts if no archive signal exists, then classifies + persists.
 
 ## 执行流程 (1 User Review Round)
 
-Phase chain: `0 → 0.5 → 1 → [1.5] → 2 → 2.5 → 3 → 3.5 → 4 → 4.5`. Each phase below is a navigator stub — full procedure, decision tables, and worked examples live in `ref/`.
+v2.0.0-rc.37 NEW-9 collapsed the flow to **3 macro-phases**; the legacy fine-grained phases survive as labelled sub-steps (back-compat for `ref/` navigation + existing traces):
+
+- **GATHER** = Phase 0 (range) → 0.5 (config) → 1 (ledger scan via `fab_archive_scan`) → [1.5 onboard] → 2 (candidates). Resolve scope, load config, deterministically scan the ledger for in-scope sessions, collect candidate observations.
+- **REVIEW** = Phase 2.5 (viability gate — abort guard) → 3 (classify / layer / slug + batch review) → 3.5 (scope + relevance_paths). The single user review round lives here.
+- **PERSIST** = Phase 4 (`fab_extract_knowledge`, one call per candidate) → 4.5 (archive-attempt ledger).
+
+Sub-step chain: `0 → 0.5 → 1 → [1.5] → 2 → 2.5 → 3 → 3.5 → 4 → 4.5`. Each below is a navigator stub — full procedure, decision tables, and worked examples live in `ref/`.
 
 ### Phase 0 — Range Resolution
 
@@ -43,11 +49,19 @@ Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`); emi
 
 `Read ref/i18n-policy.md` for the full 5-class taxonomy + edge cases.
 
-### Phase 1 — Collect Cross-Session Digests
+### Phase 1 — Collect Cross-Session Digests (server-side ledger scan, rc.37 NEW-9)
+
+The deterministic ledger scan now runs **server-side** — call `fab_archive_scan({ range, session_id })` (range = Phase 0's `session_id[]` or `"all"`/omitted). It returns:
+
+- `anchor_ts` — ts of the last `knowledge_proposed` (the lower bound).
+- `session_ids[]` — distinct in-scope sessions since the anchor, ALREADY filtered through the outcome-ledger state machine (drops `user_dismissed`, sessions inside the 12h anti-loop cooldown, and watermarked sessions with no new high-value signal). First-seen order.
+- `dropped[]` — `{session_id, reason}` for transparency.
+- `covered_through_ts` — max ts examined (becomes the next watermark).
+- `already_proposed_keys[]` — idempotency keys already proposed but not yet reviewed; drop matching candidates in Phase 3 (cross-session pending dedupe).
 
-Stitch context from every session accumulated since the last `knowledge_proposed` event. Tail-scan `.fabric/events.jsonl` → find anchor → forward-collect distinct `session_id`s → load per-session digests from `.fabric/.cache/session-digests/<session_id>.md` → concatenate into `### Cross-session digest` block, populating `source_sessions[]` + `session_context` for Phase 4. Cap at `archive_digest_max_sessions`.
+Then (LLM side, Boundary B): for each returned `session_id`, load `.fabric/.cache/session-digests/<session_id>.md`, concatenate into a `### Cross-session digest` block, and populate `source_sessions[]` + `session_context` for Phase 4. Cap at `archive_digest_max_sessions`. Missing digest files degrade silently.
 
-`Read ref/phase-1-cross-session.md` for the Step 4.5 ledger filter state machine (rules a-f), `ANTI_LOOP_HOURS` / `HIGH_VALUE_EVENT_TYPES` / `NORMATIVE_KEYWORDS` constants, and 3 worked examples (user_dismissed / cooldown / re-scan-with-signal).
+`Read ref/phase-1-cross-session.md` for the (now server-side) filter state machine rules + the digest-stitch + graceful-degradation notes. The hand-rolled `tail -n 200` events.jsonl scan is retired — `fab_archive_scan` is the source of truth for which sessions to load.
 
 Graceful degradation: missing digest cache → single-session fallback. Missing `session_archive_attempted` events (pre-rc.25) → legacy "scan everything since anchor" behaviour.
 
@@ -63,7 +77,15 @@ Gather raw evidence: tail `.fabric/events.jsonl` since last `knowledge_proposed`
 
 ### Phase 2.5 — Viability Gate (Anti-Archive Guard)
 
-Coarse viability check. **PASS conditions**: user_explicit_invoke OR ≥1 archive signal hit (normative language, wrong-turn-and-revert, long diagnostic loop, new dependency, new pattern, decision confirmation, dismissal-with-reason, process formalization). **FAIL → branch by entry_point**: E1/E3/E5 silent-skip (emit Phase 4.5 event `outcome='skipped_no_signal'`); E2/E4 render gate-FAIL message (emit `outcome='viability_failed'`).
+Coarse viability check. **PASS conditions**: user_explicit_invoke OR ≥1 archive signal hit. v2.0.0-rc.37 NEW-4 simplifies the legacy 8-signal list into **3 major categories** (each maps to multiple legacy signals for back-compat scoring):
+
+1. **User-driven knowledge expression** — user message contains normative language (`always`/`never`/`from now on`/`下次注意`/`记一下`/`以后`/`永远不要`), OR user weighed ≥2 alternatives and gave rationale (decision confirmation), OR user explicitly dismissed an approach AND stated why (dismissal-with-reason). Legacy signals #1 + #6 + #7.
+2. **Reflective discovery** — AI tried path X, reflected, then took path Y (wrong-turn-and-revert); OR a long diagnostic loop (>15 min / >10 turns) surfaced a non-obvious cause; OR a reusable pattern was named in the session ("the X phase", "the Y pattern"). Legacy signals #2 + #3 + #5.
+3. **Concrete artifact change** — a new dependency was added (package.json/pyproject.toml/Cargo.toml diff), OR a load-bearing multi-step procedure was formalized in a specific order. Legacy signals #4 + #8.
+
+Pre-PASS MUST step (rc.37 NEW-4): for each candidate, run a quick `Glob` over `.fabric/knowledge/**/*.md` keyed on slug-stem to check for duplicate canonical entry. If duplicate found → drop candidate (treat as anti-signal #4 'duplicate of existing canonical'). This is a HARD gate, not advisory — silently writing a near-duplicate is the highest-noise failure mode.
+
+**FAIL → branch by entry_point**: E1/E3/E5 silent-skip (emit Phase 4.5 event `outcome='skipped_no_signal'`); E2/E4 render gate-FAIL message (emit `outcome='viability_failed'`). Gate-FAIL message for E2/E4 MUST include the "to force-archive, explicitly invoke fabric-archive" remediation pointer so the user has an unambiguous escape hatch when the gate misclassifies (zh-CN: `如需强制归档，请显式调用 fabric-archive` / en: `To force-archive, explicitly invoke fabric-archive`).
 
 `Read ref/phase-2-5-viability.md` for verbose signal definitions, zh-CN/en gate-FAIL message bodies, anti-archive signals (typo / refactor / rename / duplicate), and the events.jsonl 4KB POSIX atomicity constraint.
 
@@ -126,7 +148,7 @@ MANDATORY closing step on EVERY invocation (Phase 4 success path + every early-e
 - NEVER classify a candidate as `personal` when a 强 team signal applies. Default to team on ambiguity.
 - NEVER emit a non-empty `relevance_paths` when `relevance_scope=broad` — broad MUST always carry `relevance_paths=[]`.
 - NEVER emit a non-empty `relevance_paths` when `layer=personal` — personal forces `relevance_scope=broad` + `relevance_paths=[]`.
-- NEVER use multi-signal sources for relevance_paths in rc.5 — `edit_paths` is the SOLE source. `read_paths`, body regex, and symbol extraction are reserved for rc.7+.
+- v2.0.0-rc.37 NEW-7 widened Phase 3.5: `edit_paths` ∪ `user_mentioned_paths` drives `relevance_paths`; `read_paths` flows separately to `evidence_paths` (structured frontmatter, not body markdown). NEVER lift body regex / symbol extraction into `relevance_paths` — those remain reserved for v2.1+.
 - NEVER batch multiple candidates into a single fab_extract_knowledge call; one call per candidate.
 - NEVER paraphrase the verbatim layer heuristic block above — the Chinese text is contract-locked.
 - MUST preserve protected tokens exactly: `stable_id`, `knowledge_proposed`, `knowledge_archive_aborted`, `knowledge_scope_degraded`, `.fabric/knowledge/pending/`, `fab_extract_knowledge`, `relevance_paths`, `relevance_scope`, `narrow`, `broad`, `edit_paths`, `source_sessions`, `proposed_reason`, `session_context`, `intent_clues`, `tech_stack`, `impact`, `must_read_if`, `pending_path`, `layer`, `team`, `personal`, `MUST`, `NEVER`, `强 team`, `强 personal`, `默认 team`.

package/templates/skills/fabric-archive/ref/dry-run-scope.md

@@ -1,6 +1,6 @@
 # Dry-run Scope (unified)
 
-`dry_run = true` (per Phase 4.5 detection rule — substring match on `--dry-run` | `dry-run` | `dry_run` | `预览` token) suspends ALL side-effecting writes below; read-side machinery (Phase 1 digest collection, Phase 2.5 viability gate evaluation, Phase 3 candidate render) executes normally so the user can preview what WOULD happen.
+`dry_run = true` (per Phase 4.5 detection rule — invocation MUST carry the verbatim token `--dry-run`; v2.0.0-rc.37 NEW-10 dropped the legacy substring fallback on bare `dry-run` / `dry_run` / `预览` to eliminate false positives on incidental mentions of those words mid-prompt) suspends ALL side-effecting writes below; read-side machinery (Phase 1 digest collection, Phase 2.5 viability gate evaluation, Phase 3 candidate render) executes normally so the user can preview what WOULD happen.
 
 | Write operation | Normal mode | Dry-run mode |
 |---|---|---|

package/templates/skills/fabric-archive/ref/i18n-policy.md

@@ -1,5 +1,11 @@
 # UX i18n Policy — full reference
 
+> **Shared core (rc.37 NEW-13):** the cross-skill invariants — protected-token
+> NEVER-translate list, AskUserQuestion routing-key rule, layer heuristic, and
+> events-emit convention — live once in `../../lib/shared-policy.md`. This file
+> keeps only the fabric-archive-specific 5-class examples. Read the shared lib
+> for the common rules; do not fork them here.
+
 > **Loaded on demand.** Only consult when rendering bilingual output AND you're unsure which class a string belongs to. SKILL.md gives the operative rule: read `.fabric/fabric-config.json` → `fabric_language`, emit prose in resolved variant, never translate protected tokens. The 5-class taxonomy below disambiguates edge cases.
 
 ## UX i18n Policy (5-class bilingualization)

package/templates/skills/fabric-archive/ref/phase-1-5-onboard.md

@@ -23,7 +23,7 @@ is the canonical taxonomy for this gate.
 |-------|--------|-------------------------------------------------------|
 | **E1** | `hook_passive` | stdout JSON `{decision:'block', ...}` from `archive-hint.cjs` detected at skill entry (the Stop-hook reminder path). |
 | **E2** | `explicit_user_invoke` | User prompt is a direct invocation: `fabric archive` / `/fabric-archive` / `archive what we just did` / `归档一下` / similar imperative. |
-| **E3** | `ai_self_trigger` | AI internal marker `self-archive policy triggered by signal: <X>` present (substring match on the verbatim prefix `self-archive policy triggered by signal`; `<X>` is one of the 4 self-trigger signals from AGENTS.md E3 section: `Normative` / `Wrong-turn-and-revert` / `Decision confirmation` / `Explicit dismissal`). |
+| **E3** | `ai_self_trigger` | AI internal marker `self-archive policy triggered by signal: <X>` present (substring match on the verbatim prefix `self-archive policy triggered by signal` per AGENTS.md self-archive policy section; `<X>` is the signal name. v2.0.0-rc.37 NEW-2 simplified the AGENTS.md taxonomy to 2 categories: `User-driven normative` / `Wrong-turn-and-revert`. Back-compat: legacy 4-state names (`Normative` / `Decision confirmation` / `Explicit dismissal`) still route correctly because the substring gate only matches the verbatim prefix and treats any text after `signal:` as the signal label.) |
 | **E4** | `user_range_rollback` | Prompt contains a **range hint** (parsed in Phase 0 — e.g. `今日` / `上周` / `rc.20`) AND the user is invoking. Sub-mode of E2. |
 | **E5** | `cron` | Prompt contains literal `今日复盘` / `daily recap` / `daily-archive` AND no human is present (running under `/loop`, OS cron, or scheduled trigger). |
 

package/templates/skills/fabric-archive/ref/phase-1-cross-session.md

@@ -2,6 +2,8 @@
 
 > **Loaded on demand.** SKILL.md hot path retains Phase 1's purpose statement + 5-step summary + graceful-degradation note. This file holds Steps 1-5 detailed implementation (events.jsonl tail-scan, anchor-walk, digest load, rc.25 TASK-05 ledger filter algorithm + constants + worked examples, cross-session context build).
 
+> **v2.0.0-rc.37 NEW-9 — Steps 1-4.5 moved server-side.** The deterministic part of this algorithm (events.jsonl tail-scan, anchor-find, session forward-collect, and the Step 4.5 outcome-ledger filter state machine) now runs in the server and is exposed as the `fab_archive_scan` MCP tool — call it instead of hand-running `tail`/grep. The tool returns the already-filtered `session_ids[]` + `anchor_ts` + `covered_through_ts` + `already_proposed_keys[]`. Steps 1-4.5 below remain as the AUTHORITATIVE SPEC of what the server computes (and the contract tests pin it); the Skill no longer executes them by hand. Step 5 (digest load + cross-session context stitch) stays LLM-side per Boundary B.
+
 ## Step 1 — Read events.jsonl tail
 
 Use `Bash` with `tail -n 200 .fabric/events.jsonl` (tolerate ENOENT — empty ledger is a normal first-run state).

package/templates/skills/fabric-archive/ref/phase-2-5-viability.md

@@ -2,18 +2,32 @@
 
 > **Loaded on demand.** SKILL.md hot path retains the signal lists, gate decision pseudocode, and entry-point branching summary. This file holds the verbose explanations for each signal, gate-FAIL message variants (zh-CN/en), the events.jsonl 4KB atomicity constraint note, and rationale.
 
-## Archive signals — verbose explanation
+## Archive signals — verbose explanation (rc.37 NEW-4 simplified 8 → 3)
 
-Scan `user_messages_summary` + `recent_paths` + the events tail collected in Phase 2. Each signal listed in SKILL.md hot path is explained below:
+Scan `user_messages_summary` + `recent_paths` + the events tail collected in Phase 2. The legacy 8-signal list was simplified in v2.0.0-rc.37 NEW-4 to **3 major categories**, mirroring the AGENTS.md Self-archive policy rc.37 NEW-2 simplification. Legacy signal names remain valid scoring inputs for back-compat (any path that fires a legacy signal also fires the corresponding category):
 
-1. **Explicit normative language** — user said `always` / `never` / `from now on` / `下次注意` / `记一下` / `以后` / `永远不要`. Strongest single signal — even one normative cue is sufficient.
-2. **Wrong-turn-and-revert** — a path was edited, then reverted (or partially undone) after diagnosis. Indicates a pitfall worth recording (the why-not lives in the revert).
-3. **Long diagnostic loop** — an issue took > 15 minutes (or > ~10 tool turns) of debugging before resolution. Implies a non-obvious cause worth capturing.
-4. **New dependency adoption** — a new package / library / external tool was introduced (e.g. `package.json` / `pyproject.toml` / `Cargo.toml` diff adds a dep).
-5. **New pattern emergence** — a reusable abstraction or naming convention was named ("the X phase", "the Y pattern", "let's call this Z").
-6. **Decision confirmation** — ≥ 2 alternatives were weighed AND a rationale was given before settling. The rationale is the archivable knowledge.
-7. **Explicit dismissal-with-reason** — user rejected an approach AND stated why. The why is the archivable knowledge, not the dismissal itself.
-8. **Process formalization** — a multi-step procedure was executed in a specific order AND the order was identified as load-bearing.
+### Category 1 — User-driven knowledge expression
+
+Covers legacy signals #1 (normative language) + #6 (decision confirmation) + #7 (dismissal-with-reason). All three are "user message contains structured knowledge worth keeping":
+
+- **Normative language** — user said `always` / `never` / `from now on` / `下次注意` / `记一下` / `以后` / `永远不要`. Strongest single cue.
+- **Decision confirmation** — ≥ 2 alternatives were weighed AND a rationale was given before settling. The rationale is the archivable knowledge.
+- **Dismissal-with-reason** — user rejected an approach AND stated why. The why is archivable, not the dismissal itself.
+
+### Category 2 — Reflective discovery
+
+Covers legacy signals #2 (wrong-turn-and-revert) + #3 (long diagnostic loop) + #5 (new pattern emergence). All three are "AI execution surfaced a non-obvious insight":
+
+- **Wrong-turn-and-revert** — a path was edited, then reverted (or partially undone) after diagnosis. The why-not lives in the revert.
+- **Long diagnostic loop** — an issue took > 15 minutes (or > ~10 tool turns) of debugging before resolution. Non-obvious cause worth capturing.
+- **New pattern emergence** — a reusable abstraction or naming convention was named in-session ("the X phase", "the Y pattern", "let's call this Z").
+
+### Category 3 — Concrete artifact change
+
+Covers legacy signals #4 (new dependency) + #8 (process formalization). Both surface in tangible workspace artifacts:
+
+- **New dependency adoption** — a new package / library / external tool was introduced (`package.json` / `pyproject.toml` / `Cargo.toml` diff adds a dep).
+- **Process formalization** — a multi-step procedure was executed in a specific order AND the order was identified as load-bearing.
 
 ## Anti-archive signals — verbose explanation
 
@@ -22,7 +36,7 @@ These force the gate to FAIL **unless** an archive signal also fires (i.e. anti-
 1. **Typo-only edits** — the entire session is whitespace / spelling / formatting changes. No semantic content to archive.
 2. **Pure refactor** — rename / move / extract with no behavior change AND no naming convention being established.
 3. **Narrow rename request** — user asked to rename one symbol / file with no rationale. Zero generalization potential.
-4. **Duplicate of existing canonical** — the observation is already covered by an existing entry under `.fabric/knowledge/<type>/`. Do a quick Glob before deciding.
+4. **Duplicate of existing canonical** — v2.0.0-rc.37 NEW-4: this check is now **mandatory** (was "do a quick Glob before deciding"). Pre-PASS MUST step: for each candidate, `Glob('.fabric/knowledge/**/*.md')` keyed on slug-stem. If duplicate found → drop candidate. Silently writing a near-duplicate is the highest-noise failure mode and dwarfs the cost of one extra glob per candidate.
 
 ## Gate-FAIL user messages (E2 / E4 only)
 

package/templates/skills/fabric-archive/ref/phase-3-5-scope.md

@@ -1,45 +1,73 @@
 # Phase 3.5 — Scope Decision + relevance_paths Derivation (ref)
 
-> **Loaded on demand.** SKILL.md hot path retains the scope decision pseudocode, personal-layer-forces-broad rule, and brief examples. This file holds the rc.5 single-signal `edit_paths` derivation algorithm (Steps 1-6) + worked generalization example + inline-edit re-derivation rules.
+> **Loaded on demand.** SKILL.md hot path retains the scope decision pseudocode, personal-layer-forces-broad rule, and brief examples. This file holds the rc.37 multi-signal derivation algorithm (edit_paths + read_paths + user_mentioned_paths), Steps 1-6 + worked generalization example + inline-edit re-derivation rules + the frontmatter `evidence_paths` upgrade.
 
-## relevance_paths derivation algorithm (rc.5 single-signal: edit_paths only)
+## relevance_paths derivation algorithm (rc.37 multi-signal — NEW-7)
 
-rc.5 uses ONLY the `edit_paths` signal — list of paths modified by `Edit` / `Write` / `MultiEdit` tool calls in the current session. Multi-signal (read_paths + body regex + symbols) is explicitly deferred to rc.7 per design decision.
+rc.37 NEW-7 widens Step 1 from the rc.5 single-signal (`edit_paths` only) to three sources:
+
+1. **`edit_paths`** — files modified by `Edit` / `Write` / `MultiEdit` tool calls. The primary activation signal: if the agent CHANGED a file, the knowledge derived in this session most likely applies there.
+2. **`read_paths`** — files inspected via `Read` / `Grep` / `Glob` without modification. Secondary signal: read-only inspection often anchors the applicability surface even when no write happened (e.g. discovering that a pitfall surfaces in a getter that the agent only READ).
+3. **`user_mentioned_paths`** — paths the user typed verbatim in messages (`packages/server/src/foo.ts`, `\`packages/cli/**/*.ts\`` etc.). Strongest signal of all: an explicit user-named path is ground-truth applicability surface, independent of what the agent did.
 
 ```
-Step 1: COLLECT
+Step 1: COLLECT (rc.37 NEW-7 — three sources)
   edit_paths = []
+  read_paths = []
+  user_mentioned_paths = []
+
+  // 1a — edit signal (rc.5 primary)
   Scan session transcript for tool_use entries where
     tool_use.name ∈ {Edit, Write, MultiEdit}
   Extract the file_path argument from each, push into edit_paths.
 
-Step 2: DEDUPE
-  edit_paths = unique(edit_paths)
-
-Step 3: BLACKLIST FILTER
+  // 1b — read signal (rc.37 NEW-7 secondary)
+  Scan session transcript for tool_use entries where
+    tool_use.name ∈ {Read, Grep, Glob}
+  Extract the file_path / path / glob argument from each, push into read_paths.
+
+  // 1c — user-mentioned signal (rc.37 NEW-7 ground truth)
+  Scan user messages for token sequences matching workspace-relative
+  path patterns: `<segment>/<segment>/...<ext>` or `<segment>/**` or
+  ``<path>`` (backtick-quoted). De-dupe and push into user_mentioned_paths.
+
+Step 2: DEDUPE + CLASSIFY
+  // Union all three sources for the relevance_paths candidate set.
+  candidate_paths = unique(edit_paths ∪ user_mentioned_paths)
+  // read_paths stay separate — they become evidence_paths (Step 6) rather
+  // than activation triggers. A path that appears in BOTH edit_paths and
+  // read_paths goes to candidate_paths (writes dominate reads).
+  evidence_candidate_paths = unique(read_paths \ edit_paths)
+
+Step 3: BLACKLIST FILTER (applies to BOTH candidate sets)
   Drop paths matching any of:
     - **/*.<ext>          where <ext> is a single trivial extension on a single file
                           (i.e. avoid emitting bare **/*.md as a relevance pattern)
     - Repo-root single files: README.md, package.json, package-lock.json,
       pnpm-lock.yaml, tsconfig.json, .gitignore, LICENSE, CHANGELOG.md
-    - Read-only paths (never modified) — those go to ## Evidence, not relevance_paths
 
 Step 4: PUBLIC-PREFIX GENERALIZE (depth ≤ 2, minGroupSize = 2)
-  Group remaining paths by common prefix.
+  Group remaining candidate_paths by common prefix.
   For each group of ≥ 2 sibling paths sharing a prefix:
     - Compute longest common directory prefix
     - Limit generalization depth: at most 2 levels below the common prefix
     - Emit glob: <common-prefix>/**/*.<ext>  (or <common-prefix>/**/<filename>)
   Singleton paths (group size = 1) are kept as-is (literal path, no glob).
+  (Evidence paths are NOT generalized — they stay literal so plan-context
+  retrieval can do exact-match recall lookups.)
 
 Step 5: SCOPE GATE
-  IF relevance_scope == broad → relevance_paths = []  (force empty regardless of edit_paths)
+  IF relevance_scope == broad → relevance_paths = []  (force empty regardless of candidate_paths)
   IF relevance_scope == narrow → relevance_paths = result of Step 4
 
-Step 6: ATTACH READ-ONLY EVIDENCE
-  Read-only paths (filtered in Step 3) are emitted as a ## Evidence markdown
-  block in the pending entry body — NOT in relevance_paths. They document
-  what the agent consulted without making them part of the activation gate.
+Step 6: ATTACH evidence_paths to FRONTMATTER (rc.37 NEW-7 upgrade)
+  Pass evidence_candidate_paths (from Step 2, post-blacklist Step 3) to
+  fab_extract_knowledge as the `evidence_paths` input field. Server writes
+  them to frontmatter `evidence_paths: [...]` (NOT to body `## Evidence`).
+  This makes evidence consumable by plan-context retrieval as structured
+  data instead of forcing markdown re-parsing every recall. The legacy
+  body `## Evidence` block stays for back-compat readers but is no longer
+  the source of truth.
 ```
 
 ## Worked generalization example

package/templates/skills/fabric-import/SKILL.md

@@ -65,7 +65,7 @@ Classify each candidate into 5 types (decisions/pitfalls/guidelines/models/proce
 
 #### Mandatory Scope Rule — broad + empty paths (NON-NEGOTIABLE)
 
-Every call MUST `relevance_scope="broad"` AND `relevance_paths=[]`. No exceptions. Why: import is LLM-driven (not session-driven); LLM-inferred narrow → false-narrow that silently hides knowledge. Narrowing deferred to `fab_review.modify` post-import. Full rationale + prohibitions + doctor lint #23 → `Read .../ref/phase-2-mining.md`.
+Every call MUST `relevance_scope="broad"` AND `relevance_paths=[]`. No exceptions. Why: import is LLM-driven (not session-driven); LLM-inferred narrow lies about applicability. Post-rc.37 A1 the server returns every selectable entry regardless of scope, so false-narrow no longer hides knowledge — but it still poisons doctor lint accounting + downstream consumers that read `relevance_paths` literally. Narrowing deferred to `fab_review.modify` post-import when the user has the real applicability surface. Full rationale + prohibitions + doctor lint #23 → `Read .../ref/phase-2-mining.md`.
 
 #### Step 2.1 — Git Mining
 
@@ -85,7 +85,7 @@ Skip if: cosmetic-only / metadata-only / in baseline / not classifiable / slug n
 
 #### Dry-Run
 
-Keyword `dry-run` / `预览` / `--dry-run` → skip MCP, render bilingual preview table (every Scope row `broad+[]`). State NOT written. P3 skipped.
+Explicit token `--dry-run` in invocation → skip MCP, render bilingual preview table (every Scope row `broad+[]`). State NOT written. P3 skipped. v2.0.0-rc.37 NEW-10 dropped legacy substring fallback on bare `dry-run` / `预览` (false-positive on incidental mentions).
 
 Full MCP call shape, Step 2.1.5 table, dry-run templates, T5 idempotency → `Read .../ref/phase-2-mining.md`.
 
@@ -144,4 +144,4 @@ Roll-up sections (per `fabric_language`): `Phase 2 — Mining` | `Phase 3 — De
 - State corruption: P0 detects → rename `.json.corrupt-<ISO>` → restart P1.
 - MCP unreachable: halt + `MCP 工具未注册；请检查 fabric server 是否运行` / `MCP tool not registered; please check that the fabric server is running` → exit without state write.
 
-Check-not-Ask: inspect state, resume deterministically.
+Resume policy: inspect existing state and continue from the last completed phase — do not prompt the user mid-flow.

package/templates/skills/fabric-import/ref/i18n-policy.md

@@ -1,5 +1,11 @@
 # UX i18n Policy — fabric-import full reference
 
+> **Shared core (rc.37 NEW-13):** the cross-skill invariants — protected-token
+> NEVER-translate list, AskUserQuestion routing-key rule, layer heuristic, and
+> events-emit convention — live once in `../../lib/shared-policy.md`. This file
+> keeps only the fabric-import-specific 5-class examples. Read the shared lib
+> for the common rules; do not fork them here.
+
 > **Loaded on demand.** Only consult when you need to disambiguate which of the 5 classes a given string belongs to. SKILL.md gives the operative rule.
 
 ## UX i18n Policy (5-class bilingualization)

package/templates/skills/fabric-import/ref/phase-2-mining.md

@@ -15,7 +15,7 @@ This is non-negotiable and applies to BOTH Step 2.1 (git mining) AND Step 2.2 (d
 
 1. `fabric-import` is LLM-driven (mines git log + docs), not session-driven (no live `edit_paths` signal).
 2. `git diff --stat` lists files touched by a commit, but those files are the commit's **effect surface**, not the **applicability surface** of the underlying observation. A pitfall surfaced by a fix in `packages/server/src/retry.ts` may apply to every retry call-site in the repo, not just that one file.
-3. LLM-inferred `relevance_paths` from historical commit metadata produces false-narrow bindings — entries get filtered out for paths they actually govern. False-narrow is worse than broad because it silently hides knowledge during plan-context filtering.
+3. LLM-inferred `relevance_paths` from historical commit metadata produces false-narrow bindings — `relevance_paths` becomes a lie about applicability. Post-rc.37 A1 the server no longer filters by `relevance_scope`, so false-narrow does NOT hide knowledge from AI recall (every selectable entry is surfaced regardless of scope). The damage is now downstream: doctor lint accounting, future-AI judgment, and any consumer that reads `relevance_paths` literally treats the wrong globs as ground truth. Broad+[] keeps the metadata honest until the user has the real applicability surface in hand to declare narrow.
 4. Doc-mined observations are usually architectural / cross-cutting (a `docs/architecture.md` "Why a monolith?" decision applies to the whole codebase, not just to `docs/`).
 
 **Strict prohibitions — DO NOT attempt any of the following:**
@@ -174,7 +174,7 @@ After Step 2.2 completes (or hits the cap), update `.fabric/.import-state.json`:
 
 ## Dry-Run Mode
 
-When the user invocation includes `dry-run` / `预览` / `--dry-run` keywords, Phase 2 runs WITHOUT calling `fab_extract_knowledge`. Instead it prints a table. UX i18n Policy class 4 — header + column titles bilingualized; row content (slug / commit sha / doc path) NOT translated. Protected tokens `broad`, `relevance_scope`, `relevance_paths` appear verbatim:
+When the user invocation carries the verbatim token `--dry-run`, Phase 2 runs WITHOUT calling `fab_extract_knowledge`. Instead it prints a table. v2.0.0-rc.37 NEW-10 dropped the legacy substring fallback on bare `dry-run` / `预览` because those caused false positives on incidental mentions ("preview the table" / "do a dry run later"). UX i18n Policy class 4 — header + column titles bilingualized; row content (slug / commit sha / doc path) NOT translated. Protected tokens `broad`, `relevance_scope`, `relevance_paths` appear verbatim:
 
 ### zh-CN variant (`fabric_language === "zh-CN"`)
 

package/templates/skills/fabric-review/SKILL.md

@@ -48,46 +48,46 @@ Read `fabric_language` (`zh-CN` / `en` / `zh-CN-hybrid` / `match-existing`); emi
 
 ## Mode Inference (System Infers — NEVER Ask)
 
-> Verbatim from rc.3 locked decisions:
-> "review 永远走 fabric-review skill，**模式从上下文推断**（4 种 mode：pending queue / by topic / health overview / revisit existing）"
+> Locked decision (KT-DEC-0006): "Review mode inferred from context, not solicited via AskUserQuestion."
 > "**AskUserQuestion 仅在真有选择时用**——'何种 mode' 不是真选择（系统能推断），'approve/reject/modify 单条' 是真选择"
 
-The skill MUST infer one of {`pending`, `topic`, `health`, `revisit`} BEFORE any user-facing output.
+The skill MUST infer one of **2 modes** BEFORE any user-facing output (v2.0.0-rc.37 NEW-12 simplified 4 → 2):
 
-### 3-Step Inference Algorithm
+- **`pending`** — triage the write-side backlog (`.fabric/knowledge/pending/`): approve / reject / modify / defer per item. The dominant entry point.
+- **`maintain`** — sustain the EXISTING canonical KB: browse by topic (search), survey staleness/health, or revisit a specific entry. Merges the legacy `topic` + `health` + `revisit` modes — they are all "operate on already-canonical knowledge", distinct from triaging new drafts.
 
-**Step 1 — Recent user message keyword scan.** Match against priority order:
+### 2-Step Inference Algorithm
+
+**Step 1 — Recent user message keyword scan:**
 
 | Keywords (zh-CN + en) | Inferred mode |
 |---|---|
 | "approve", "review pending", "promote", "what's queued", "审核 pending", "通过" | `pending` |
-| "search for X about Y", "find entries about <topic>", "关于…的知识", "找一下 <topic>" | `topic` |
-| "what's stale", "demote old", "health check", "过期的", "陈旧的", "整理一下" | `health` |
-| "look at <id>", "revisit KT-…", "show <slug>", "再看下 <id>", "回顾" | `revisit` |
-
-Exactly one row matches → lock mode, skip to Step 3.
-
-**Step 2 — events.jsonl tail scan.** If Step 1 yielded 0 or >1 matches, tail (last 200 lines) `.fabric/events.jsonl`:
+| "search/find about <topic>", "what's stale", "demote old", "health check", "look at <id>", "revisit KT-…", "关于…的知识", "过期的", "陈旧的", "整理一下", "再看下 <id>", "回顾" | `maintain` |
 
-- `>5` recent `knowledge_proposed` since last `knowledge_promoted` → `pending` (write side piled up).
-- `≥1` `knowledge_demoted` or `lint` events in 24h → `health` (corpus quality signal).
-- Recent `knowledge_layer_changed` for the entry user referenced → `revisit`.
+A `maintain`-row match → lock `maintain`. A `pending`-row match (or 0/ambiguous) → fall to Step 2.
 
-**Step 3 — Pending count default.** Still ambiguous → glob `.fabric/knowledge/pending/**/*.md`:
+**Step 2 — Backlog default.** Glob `.fabric/knowledge/pending/**/*.md`:
 
 - Count ≥ `review_hint_pending_count` (default 10) OR oldest mtime > `review_hint_pending_age_days` (default 7) → `pending` (overflow, same threshold as Stop-hook).
 - Otherwise → default `pending` (most common review entry point).
 
-`Read ref/per-mode-flows.md` for 5 inference examples and anti-pattern restatement.
+> Back-compat: the legacy 4-mode names (`topic` / `health` / `revisit`) still resolve — they all map to `maintain`. Old session traces / muscle memory keep working.
+
+`Read ref/per-mode-flows.md` for inference examples and anti-pattern restatement.
 
 ## Per-Mode Flow
 
 Each mode produces user-facing output, then routes per-item or per-batch decisions through `fab_review` actions. Display body = zh-CN summaries (M3 style); section headings = EN.
 
-- **`pending`** — list pending entries → run Semantic Check (see `ref/semantic-check.md`) → per-item AskUserQuestion `{approve, reject, modify, defer, skip}` → route per choice (modify path = `ref/modify-flow.md`).
-- **`topic`** — extract keywords → `fab_review action="search"` → render top-N (cap `review_topic_result_cap`) → only AskUserQuestion when user signals action verb.
-- **`health`** — `fab_review action="list"` + tail events → compute stale → render dashboard → per-stale AskUserQuestion `{defer, demote, skip}`.
-- **`revisit`** — user referenced specific id/slug → `Read` canonical file directly OR `fab_review action="list"` with narrow filters → display body + history → AskUserQuestion only if pending.
+- **`pending`** — list pending entries → run Semantic Check (see `ref/semantic-check.md`) → per-item AskUserQuestion `{approve, reject, modify, defer, skip}` → route per choice. The modify branch chooses between two explicit actions (rc.37 NEW-12):
+  - `fab_review action="modify-content"` — edit scalars (title/summary/maturity/tags/relevance_*); NEVER flips layer.
+  - `fab_review action="modify-layer"` — the dedicated layer-flip path (`changes.layer` required); may reallocate the stable_id + emit an id-redirect.
+  - (Legacy `action="modify"` still works — it routes by whether `changes.layer` is present.) See `ref/modify-flow.md`.
+- **`maintain`** — sub-flow inferred from the same keywords:
+  - *browse-by-topic*: extract keywords → `fab_review action="search"` → render top-N (cap `review_topic_result_cap`) → AskUserQuestion only on an action verb.
+  - *health/staleness*: `fab_review action="list"` + tail events → compute stale → render dashboard → per-stale AskUserQuestion `{defer, demote, skip}`.
+  - *revisit*: user referenced a specific id/slug → `Read` canonical file directly OR `fab_review action="list"` with narrow filters → display body + history → AskUserQuestion only if actionable.
 
 `Read ref/per-mode-flows.md` for full step-by-step procedures, bilingual rendering blocks (en + zh-CN per-item display, AskUserQuestion templates, health dashboard format), and the rc.7 T6 `proposed_reason` + `## Why proposed` + `## Session context` rendering contract.
 
@@ -97,11 +97,17 @@ Each mode produces user-facing output, then routes per-item or per-batch decisio
 
 Semantic check is the LLM's job — the MCP tool does NOT compare meaning. Run during `pending` mode (and on demand during `topic`): for each pending entry, `fab_review action="search"` scoped by `filters.type` → LLM judges semantically against returned canonical entries → surface one of three flags as informational:
 
-- `⚠ Possible duplicate of <stable_id>` — same essential claim
-- `⚠ Contradicts <stable_id>` — opposing claims, same scope
-- `⚠ Subsumed by <stable_id>; consider modify-to-merge` — fully covered
+- `⚠ Possible duplicate of <stable_id> (overlap: high)` — same essential claim
+- `⚠ Contradicts <stable_id> (overlap: high)` — opposing claims, same scope
+- `⚠ Subsumed by <stable_id> (overlap: medium+); consider modify-to-merge` — fully covered
+
+**Quantified overlap band (rc.37 NEW-12).** The LLM still judges meaning (no embedding %), but MUST tag each flag with a 3-level band so the signal is comparable across entries and the user can triage at a glance:
+
+- `high` — ≥ ~80% of the candidate's essential claim is restated; near-certain dup/contradiction. Recommend reject-as-duplicate or modify-to-merge.
+- `medium` — substantial conceptual overlap but the new entry adds a distinct facet (different path scope, added caveat). Recommend modify-to-harmonize.
+- `low` — adjacent topic, not a real overlap. Do NOT raise a flag at `low` — it is below the surfacing threshold (suppresses noise).
 
-Thresholds intentionally NOT quantified (no similarity %). User decides: still-approve (flag informational), modify-to-harmonize, or reject-as-duplicate (reason MUST cite existing stable_id).
+Only `medium`+ flags are surfaced. User decides: still-approve (flag informational), modify-to-harmonize, or reject-as-duplicate (reason MUST cite existing stable_id).
 
 DO NOT AskUserQuestion "is this a duplicate?" — LLM already judged. User only chooses approve/reject/modify.