@fenglimg/fabric-cli 2.0.0-rc.30 → 2.0.0-rc.34

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

@@ -0,0 +1,16 @@
+# 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.
+
+| Write operation | Normal mode | Dry-run mode |
+|---|---|---|
+| `fab_extract_knowledge` MCP call (Phase 4) | One call per confirmed candidate, writes to `.fabric/knowledge/pending/<slug>.md` | SKIPPED. Phase 4 renders "would write N pending entries" preview table instead. |
+| `session_archive_attempted` event (Phase 4.5) | Appended to `.fabric/events.jsonl` for every session in scope | SKIPPED entirely. No ledger entry. |
+| `fab_review reject` (Phase 3 user-dismissed branch) | Invoked when user types `撤销` / `reject` after self-archive proposal | SKIPPED. The dismissal is rendered to console but no MCP write occurs. |
+| `fab onboard-coverage` slot writes (Phase 1.5 fill-all / dismiss-all) | Each `Bash("fab config dismiss-slot <slot>")` invocation runs | SKIPPED. Slot decisions are shown as "would dismiss/propose" preview. |
+| `.fabric/.cache/session-digests/<session_id>.md` reads | Read freely (read-side, safe) | Read freely — same as normal. |
+| Stop-hook / archive-hint stdin/stdout | Read-only inspection of `.fabric/events.jsonl` | Same — no change. |
+
+All user-facing output in dry-run mode MUST prefix `[DRY-RUN]` at the start of each Phase header (e.g. `[DRY-RUN] Phase 3 — Batch Review`). Exit message: `[DRY-RUN complete] would have written N entry/entries; no .fabric/ files were modified. Re-invoke without --dry-run to commit.`
+
+Cross-reference: Phase 4.5 `Dry-run override` section in SKILL.md holds the rationale. When adding a new write side-effect to any phase, update BOTH the phase section AND this table.

package/templates/skills/fabric-archive/ref/e5-cron-recap.md

@@ -1,12 +1,12 @@
 # E5 Scheduled Daily Recap — full reference
 
-> **Loaded on demand.** Only relevant when invocation context = `cron` / `/loop` (E5 entry). SKILL.md's Phase -0.5 already gates this — if the user just typed `/fabric-archive`, none of the below applies.
+> **Loaded on demand.** Only relevant when invocation context = `cron` / `/loop` (E5 entry). SKILL.md's Phase 0 already gates this — if the user just typed `/fabric-archive`, none of the below applies.
 
 ## E5 周期触发 (Scheduled Daily Recap)
 
 ## Overview
 
-`今日复盘` = E5 entry point. Default scope = today. Falls back to historical scan if today yields no candidates (silent-skip per Phase 2.5).
+`今日复盘` = E5 entry point. Default scope = today. Falls back to historical scan if today yields no candidates (silent-skip per Phase 4.5).
 
 E5 是 5 入口模型中唯一由 OS 调度器或 Claude Code `/loop` 周期触发的入口形态。fab 端**零代码**——不提供 `fab schedule` 子命令,亦不内嵌 daemon。用户基于自己的执行环境二选一接入: `/loop`(Claude Code 原生,推荐) 或 OS cron(跨平台 fallback)。
 
@@ -36,9 +36,9 @@ macOS 用户可改用 `launchd` plist;Linux 用户直接 `crontab -e`。命令
 
 当用户或 cron 以 `今日复盘` / `daily recap` 字面短语触发 fabric-archive 时,skill 应按以下契约处理:
 
-- **Phase -0.5 Range Resolution**: 识别 `今日复盘` / `daily recap` 为 magic phrase, 直接设置 `time_window = today` (00:00 local timezone → current ts), 无需 AskUserQuestion 兜底。
-- **Phase 0.4 Onboard Coverage**: 跳过 (entry_point = E5_cron, 非 E2_explicit, 不弹 onboard 弹问)。
-- **Phase 2.5 Persist Archive Attempt**: 始终写入 `session_archive_attempted` event。当今日无 archive 信号触发 viability gate FAIL 时,走 silent-skip 路径(outcome = `skipped_no_signal`),skill 静默退出,cron 日志为空。
+- **Phase 0 Range Resolution**: 识别 `今日复盘` / `daily recap` 为 magic phrase, 直接设置 `time_window = today` (00:00 local timezone → current ts), 无需 AskUserQuestion 兜底。
+- **Phase 1.5 Onboard Coverage**: 跳过 (entry_point = E5_cron, 非 E2_explicit, 不弹 onboard 弹问)。
+- **Phase 4.5 Persist Archive Attempt**: 始终写入 `session_archive_attempted` event。当今日无 archive 信号触发 viability gate FAIL 时,走 silent-skip 路径(outcome = `skipped_no_signal`),skill 静默退出,cron 日志为空。
 
 ### Trade-off table (/loop vs OS cron)
 

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

@@ -12,7 +12,7 @@ following 5 categories MUST be rendered in the resolved language:
 
 1. **Roll-up templates** — the `# Archive Review — N candidates` batch
    review block (one per candidate) AND any final session summary the
-   skill emits after Phase 2 completes. zh-CN ↔ en mirror.
+   skill emits after Phase 4 completes. zh-CN ↔ en mirror.
 2. **Errors / Preconditions warnings** — abort + gate-fail messages (e.g.
    the "没有触发归档信号…" trigger-miss and the "本次会话为常规执行…"
    viability-gate-FAIL message). zh-CN ↔ en mirror.
@@ -20,13 +20,13 @@ following 5 categories MUST be rendered in the resolved language:
    edit … inline, N to skip)` line in the batch review template. zh-CN
    ↔ en mirror.
 4. **Dry-run table headers** — v2.0.0-rc.27 TASK-007 added a dry-run
-   override path (see Phase 2.5 "dry-run") so users can preview the
+   override path (see Phase 4.5 "dry-run") so users can preview the
    archive proposal without writing pending entries. The dry-run summary
    header and per-candidate preview labels MUST be bilingualized per
    this policy. zh-CN ↔ en mirror.
 5. **AskUserQuestion** — `header` + `question` fields (NOT `options[]`).
    zh-CN ↔ en mirror. fabric-archive itself does not surface
-   AskUserQuestion in the current contract (Phase 1 batch review is a
+   AskUserQuestion in the current contract (Phase 3 batch review is a
    single markdown screen, not a structured question), but if a future
    version adds one — e.g. to confirm layer flip — this rule applies.
 

package/templates/skills/fabric-archive/ref/phase-0-range-resolution.md

@@ -0,0 +1,156 @@
+# Phase 0 — Range Resolution (ref)
+
+> **Loaded on demand.** SKILL.md hot path retains the Phase 0 intro, the Confidence decision rule, and Step 1 (invocation context inspection). This file holds Steps 2-6 (parsing tables, session_id resolution algorithm, AskUserQuestion fallback, carry-forward contract) + worked examples. Read when entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND the user prompt likely carries a range hint that needs parsing.
+
+## Step 2 — Time-window parsing
+
+Match the user prompt against the following bilingual patterns (case-insensitive substring match, leftmost-longest wins). The matched span yields a `[ts_start, ts_end]` pair in Unix milliseconds. `now` = the skill invocation timestamp.
+
+### zh-CN pattern table
+
+| Pattern | ts_start | ts_end |
+|---|---|---|
+| `今日` / `今天` | `floor(now, day)` (本地时区 00:00) | `now` |
+| `上周` / `过去一周` | `now - 7d` | `now` |
+| `过去 N 天` / `近 N 天` (N ∈ 1..30) | `now - N*24h` | `now` |
+| `自上次归档` / `自上次 archive` | tail-scan events.jsonl → most recent `knowledge_proposed.ts` (fallback `events[0].ts`) | `now` |
+
+### en pattern table
+
+| Pattern | ts_start | ts_end |
+|---|---|---|
+| `today` | `floor(now, day)` (local TZ 00:00) | `now` |
+| `last week` / `past week` | `now - 7d` | `now` |
+| `past N days` / `last N days` (N ∈ 1..30) | `now - N*24h` | `now` |
+| `since last archive` / `since last archived` | tail-scan events.jsonl → most recent `knowledge_proposed.ts` (fallback `events[0].ts`) | `now` |
+
+Notes:
+
+- Patterns are non-exclusive — if the prompt matches multiple (e.g. "今日 cite policy"), apply time-window THEN topic-keyword as AND.
+- Numeric N must parse as a positive integer ≤ 30; reject anything else as parse-miss.
+- All other date phrasings (specific dates like `5月10日`, relative phrasings like `三天前下午`) are NOT handled here — emit parse-miss and let Step 5 fallback collect a structured answer.
+
+## Step 3 — Topic-keyword extraction
+
+After time-window matching (or alongside it when both apply), extract content keywords from the prompt:
+
+1. Strip recognised time-window tokens (e.g. remove `今日` / `last week` from the residual prompt).
+2. Tokenize residual on whitespace + CJK boundary. Combine adjacent CJK characters into one token; split en words on spaces.
+3. Filter **stop-words**: skill control verbs (`archive`, `归档`, `下`, `的`), articles / particles (`the`, `a`, `an`, `了`, `吧`), pronouns (`it`, `this`, `that`, `这个`, `那个`), and 1-character en tokens.
+4. Retain **2-5 word tokens** (or 1-token CJK content words ≥ 2 chars like `rc.20`, `cite`). Cap at 8 keywords; drop weaker (later-position) ones.
+
+The retained set is `topic_keywords[]`. Empty set = no keyword filter.
+
+## Step 4 — session_id resolution algorithm
+
+Given `time_window = [ts_start, ts_end] | null` and `topic_keywords[] | []`:
+
+```
+Step a — Read events.jsonl tail (last 500 events) via `Bash: tail -n 500
+         .fabric/events.jsonl`. ENOENT → empty list (no resolution possible
+         → emit parse-miss → Step 5 fallback).
+
+Step b — Per distinct session_id present in the tail, compute:
+           ts_min      = min(ts) over events with this session_id
+           ts_max      = max(ts) over events with this session_id
+           digest_path = .fabric/.cache/session-digests/<session_id>.md
+           digest_body = Read(digest_path) if exists, else ""
+
+Step c — TIME-WINDOW FILTER (skip when time_window is null):
+           Keep session_id IFF [ts_min, ts_max] intersects [ts_start, ts_end]
+           (i.e. ts_max >= ts_start AND ts_min <= ts_end).
+           Multiple time intervals are OR'd within the time-window filter
+           category (none currently supported; reserved for future ranges).
+
+Step d — TOPIC-KEYWORD FILTER (skip when topic_keywords is empty):
+           Keep session_id IFF digest_body (case-insensitive) contains
+           AT LEAST ONE keyword from topic_keywords[].
+           Multiple keywords are OR'd within the keyword filter category.
+
+Step e — AND across filter categories:
+           A session must pass BOTH filters when BOTH are present.
+           Pass either filter alone when only one is present.
+           Pass-through (all sessions) when neither is present.
+
+Step f — Result: distinct session_id[] (preserve event-order); if empty AND
+         a parse hit was claimed → degrade to Step 5 fallback (user wanted a
+         range that resolved to zero sessions).
+```
+
+## Step 5 — AskUserQuestion fallback (E2 / E4 only)
+
+When Step 2/3 emit parse-miss OR Step 4 resolves to zero sessions AND the invocation type permits prompting (E2 user-active or E4 user回溯-active — NEVER E1 hook / E3 AI-self / E5 cron), surface a structured question. UX i18n Policy class 5 applies: `header` + `question` translate per `fabric_language`; `options[]` routing keys stay English.
+
+```ts
+AskUserQuestion({
+  header: "Archive range",                              // zh-CN: "归档范围"
+  question:
+    "Which session range should this archive cover? " +
+    "(today = current calendar day; last-week = past 7 days; " +
+    "since-last-archive = newer than last knowledge_proposed event; " +
+    "custom = type a free-form range)",
+  options: ["today", "last-week", "since-last-archive", "custom"]
+})
+```
+
+Routing:
+
+| Choice | Action |
+|---|---|
+| `today` | Re-enter Step 2 with synthetic prompt `今日` / `today` (per `fabric_language`); resolve session_ids; proceed to Phase 0.5. |
+| `last-week` | Re-enter Step 2 with synthetic prompt `上周` / `last week`; proceed to Phase 0.5. |
+| `since-last-archive` | Re-enter Step 2 with synthetic prompt `自上次归档` / `since last archive`; proceed to Phase 0.5. |
+| `custom` | Surface a one-line text prompt to the user ("type a range, e.g. 'rc.20', 'past 3 days', '上周 cite policy'"). Re-enter Phase 0 Step 1 with the user-typed sub-prompt. Loop max 1 time — second parse-miss falls through to `range = "all"` with a warning. |
+
+## Step 6 — Carry-forward contract
+
+Phase 0 produces ONE of:
+
+- `session_id[]` (non-empty array of distinct session_ids) — passed to Phase 1 as the explicit scope filter; Phase 1 skips its own anchor-walk and uses this list directly.
+- `"all"` (sentinel string) — no range hint detected; Phase 1 falls back to the legacy anchor-walk behaviour ("all distinct sessions since last `knowledge_proposed`").
+
+NEVER pass an empty `session_id[]` forward — that case must degrade to Step 5 fallback (or, when fallback is forbidden by invocation type, to `"all"` with a one-line stderr warning).
+
+## Worked examples
+
+### Example A — time-only: `今日复盘`
+
+```
+Step 1: prompt = "今日复盘"; user_invocation_type = E2.
+Step 2: matches `今日` → time_window = [floor(now, day), now].
+Step 3: residual "复盘" survives stop-word filter → topic_keywords = ["复盘"].
+        (Edge case: the residual content word may also filter; if 复盘 is
+        in the stop list it becomes []. Treat as topic-keyword empty.)
+Step 4: tail-scan events.jsonl; keep sessions whose [ts_min, ts_max]
+        intersects today's window. Say 3 sessions match.
+Step 5: skipped (resolution succeeded).
+Step 6: emit session_id[] = ["sess-a", "sess-b", "sess-c"] → Phase 0.5.
+```
+
+### Example B — keyword-only: `rc.20 的归档下`
+
+```
+Step 1: prompt = "rc.20 的归档下"; user_invocation_type = E2.
+Step 2: no time pattern matches → time_window = null.
+Step 3: strip "归档"/"下"/"的" stop-words → topic_keywords = ["rc.20"].
+Step 4: tail-scan events.jsonl; for each session_id, Read its digest;
+        keep those whose digest body matches /rc\.20/i. Say 2 sessions
+        match (one was the rc.20 grilling session, one had a tangential
+        mention).
+Step 5: skipped.
+Step 6: emit session_id[] = ["sess-x", "sess-y"] → Phase 0.5.
+```
+
+### Example C — combined: `上周 rc.20`
+
+```
+Step 1: prompt = "上周 rc.20"; user_invocation_type = E4.
+Step 2: matches `上周` → time_window = [now - 7d, now].
+Step 3: strip "上周" → topic_keywords = ["rc.20"].
+Step 4: AND filter — keep sessions whose [ts_min, ts_max] intersects last
+        week AND whose digest matches /rc\.20/i. Say 1 session matches.
+Step 5: skipped.
+Step 6: emit session_id[] = ["sess-z"] → Phase 0.5.
+```
+
+If Example C had resolved to zero sessions (e.g. user types `上周 rc.99`), Step 4 would degrade into Step 5 — surfacing AskUserQuestion since E4 permits prompting.

package/templates/skills/fabric-archive/ref/{phase-0-4-onboard.md → phase-1-5-onboard.md}

@@ -1,20 +1,20 @@
-# Phase 0.4 — First-run Onboard Phase (ref)
+# Phase 1.5 — First-run Onboard Phase (ref)
 
 > **Loaded on demand.** SKILL.md hot path only runs this when entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback} AND `fab onboard-coverage --json` reports `missing.length > 0`. For E1/E3/E5 entries OR fully-covered workspaces, this entire phase is skipped — no reason to load.
 
-## Phase 0.4 — First-run Onboard Phase
+## Phase 1.5 — First-run Onboard Phase
 
-#### Phase 0.4 Trigger Gate (rc.25 — entry-context aware)
+#### Phase 1.5 Trigger Gate (rc.25 — entry-context aware)
 
 Before running ANY of the onboard coverage steps below, evaluate the
 **entry-context gate**. Onboard slot collection is an interactive,
 one-time project-tone capture flow that REQUIRES live user dialogue.
 Non-user-active entries (hook / AI self-trigger / cron) either interrupt
 the user mid-work or run unattended where dialogue is impossible, so
-they MUST skip Phase 0.4 entirely and fall through to Phase 0.
+they MUST skip Phase 1.5 entirely and fall through to Phase 0.
 
-Read `context.entry_point` — already determined in **Phase -0.5 Range
-Resolution** (see TASK-04 / Phase -0.5 section above). The 5-entry model
+Read `context.entry_point` — already determined in **Phase 0 Range
+Resolution** (see TASK-04 / Phase 0 section above). The 5-entry model
 is the canonical taxonomy for this gate.
 
 ##### Entry-context detection rules
@@ -24,7 +24,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`). |
-| **E4** | `user_range_rollback` | Prompt contains a **range hint** (parsed in Phase -0.5 — e.g. `今日` / `上周` / `rc.20`) AND the user is invoking. Sub-mode of E2. |
+| **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). |
 
 ##### Gate decision
@@ -35,8 +35,8 @@ IF context.entry_point ∈ {E2_explicit_user_invoke, E4_user_range_rollback}:
     → continue to Step 1 (Check coverage) below
 ELSE (E1_hook_passive | E3_ai_self_trigger | E5_cron):
     → gate = SKIP           # no live user, onboard prompting would misfire
-    → emit one-line log: "Phase 0.4 skipped (entry=<E1|E3|E5>, no live user)"
-    → proceed directly to Phase 0
+    → emit one-line log: "Phase 1.5 skipped (entry=<E1|E3|E5>, no live user)"
+    → proceed directly to Phase 2
 ```
 
 ##### Rationale
@@ -44,7 +44,7 @@ ELSE (E1_hook_passive | E3_ai_self_trigger | E5_cron):
 Onboard slot collection is a one-time project-tone capture flow that
 requires user dialogue. Non-user-active entries (hook / AI / cron)
 interrupt the user mid-work or run unattended where dialogue is
-impossible, so they MUST skip Phase 0.4. The S5 slot semantics
+impossible, so they MUST skip Phase 1.5. The S5 slot semantics
 (`tech-stack-decision`, `architecture-pattern`, ...) are user-validated
 baselines — populating them from a hook fire-and-forget or a cron daily
 recap would defeat the purpose of capturing _user-confirmed_ project
@@ -63,11 +63,11 @@ baseline.
 ```
 $ /loop 24h /fabric-archive 今日复盘
   → cron context, no live user
-  → Phase -0.5 detects literal "今日复盘" + no-human marker
+  → Phase 0 detects literal "今日复盘" + no-human marker
   → context.entry_point = E5_cron
-  → Phase 0.4 Trigger Gate evaluates: E5 ∉ {E2, E4} → SKIP
-  → emit log "Phase 0.4 skipped (entry=E5, no live user)"
-  → proceed directly to Phase 0 (collect candidates for daily window)
+  → Phase 1.5 Trigger Gate evaluates: E5 ∉ {E2, E4} → SKIP
+  → emit log "Phase 1.5 skipped (entry=E5, no live user)"
+  → proceed directly to Phase 2 (collect candidates for daily window)
 ```
 
 Contrast with E2:
@@ -75,8 +75,8 @@ Contrast with E2:
 ```
 $ /fabric-archive
   → user typed explicit invocation
-  → Phase -0.5: context.entry_point = E2_explicit_user_invoke
-  → Phase 0.4 Trigger Gate evaluates: E2 ∈ {E2, E4} → PROCEED
+  → Phase 0: context.entry_point = E2_explicit_user_invoke
+  → Phase 1.5 Trigger Gate evaluates: E2 ∈ {E2, E4} → PROCEED
   → run Step 1 (Check coverage) below
 ```
 
@@ -93,7 +93,7 @@ for high-quality plan_context retrieval from day one:
 - `build-system-idiom` — build tool quirks, scripts, deploy pipeline shape
 - `domain-vocabulary` — business / product terminology that names code entities
 
-This phase runs ONCE per archive-skill invocation, BEFORE Phase 0 evidence
+This phase runs ONCE per archive-skill invocation, BEFORE Phase 2 evidence
 gathering, so coverage state is fresh for the session.
 
 #### Step 1 — Check coverage
@@ -119,7 +119,7 @@ Expected shape:
 
 ```
 IF missing.length === 0:
-    → skip Phase 0.4 entirely; proceed to Phase 0.
+    → skip Phase 1.5 entirely; proceed to Phase 0.
 ELSE:
     → ask the user how to handle the missing slots (Step 3).
 ```
@@ -146,7 +146,7 @@ proposed entry counts toward coverage once approved via fab_review.
 
 | User choice    | Action |
 |----------------|--------|
-| `fill-all`     | For EACH slot in `missing`, run Step 4 (Tour-and-propose). All proposals share session_id; one batch review at the end (Phase 1). |
+| `fill-all`     | For EACH slot in `missing`, run Step 4 (Tour-and-propose). All proposals share session_id; one batch review at the end (Phase 3). |
 | `fill-each`    | Loop slot-by-slot through `missing`. Per slot: ask user `confirm | dismiss | skip` (per-slot AskUserQuestion); `confirm` → run Step 4; `dismiss` → `fab config dismiss-slot <slot>`; `skip` → leave for next archive run. |
 | `dismiss-all`  | For EACH slot in `missing`, invoke `Bash("fab config dismiss-slot <slot>")`. Print a one-line confirmation each. Skip to Phase 0. |
 | `skip`         | No-op. Slots remain in `missing` for the next archive run. Skip to Phase 0. |
@@ -199,7 +199,7 @@ mcp__fabric__fab_extract_knowledge({
 
 #### Onboard phase constraints (DO NOT TRANSLATE)
 
-- MUST run BEFORE Phase 0 evidence gathering — onboard is a separate flow,
+- MUST run BEFORE Phase 2 evidence gathering — onboard is a separate flow,
   not interleaved with session-archive candidates.
 - MUST call `fab onboard-coverage --json` before deciding; never assume
   coverage state.
@@ -208,7 +208,7 @@ mcp__fabric__fab_extract_knowledge({
   even if the user asks "fill all of them" — the dismiss is intentional.
 - NEVER prompt the user when `missing.length === 0` — silent skip.
 - NEVER set `onboard_slot` on a regular session-archive candidate in
-  Phase 2 — that field is RESERVED for the onboard phase. Mixing the
+  Phase 4 — that field is RESERVED for the onboard phase. Mixing the
   two would let session-archive proposals masquerade as onboard
   coverage and let any random pending file claim a slot.
 - MUST emit `onboard_slot: <slot>` verbatim — the slot name is one of

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

@@ -0,0 +1,60 @@
+# Phase 1 — Collect Cross-Session Digests (ref)
+
+> **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).
+
+## 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).
+
+## Step 2 — Find the anchor
+
+Walk the tail backwards to locate the most recent `knowledge_proposed` event (`event_type === "knowledge_proposed"`). The anchor's `ts` becomes the lower bound for digest selection. If NO anchor exists, treat all digests in the cache as in-scope.
+
+## Step 3 — Collect session_ids since anchor
+
+Scan the tail forward from the anchor and collect every distinct `session_id` field that appears on any event newer than the anchor. Distinct ordering preserved.
+
+## Step 4 — Load digests
+
+For each collected `session_id`, read `.fabric/.cache/session-digests/<session_id>.md`. Missing digest files degrade silently (the digest write was best-effort, so a Stop hook crash can produce a session_id without a digest). Cap the loaded digest set at `archive_digest_max_sessions` most-recent sessions (config-resolved, default 10) to bound LLM context (~50KB worst-case at default).
+
+## Step 4.5 — Filter via session_archive_attempted ledger (rc.25 TASK-05)
+
+Before Step 5 builds the cross-session context, drop sessions that the outcome ledger says we should not re-scan. For each `session_id` collected in Steps 1-3, scan `.fabric/events.jsonl` for events where `event_type === "session_archive_attempted"` AND `session_id` matches, keep the most-recent one by `ts`, and apply this state machine:
+
+- **(a) Look up the most recent `session_archive_attempted`** event for this `session_id` (none found → fall through to (e)).
+- **(b) `outcome === "user_dismissed"` → drop (permanent skip).** The user explicitly rejected this session's candidates; never auto-re-scan it. Respect the dismissal forever — re-scanning would re-propose the same content the user already declined.
+- **(c) `(nowMs - attempted_event.ts) < ANTI_LOOP_HOURS * 3_600_000` → drop (cooldown skip).** Anti-loop window: even if outcome is otherwise re-scannable, never re-scan a session within 12 hours of the last attempt. Aligns 心智 with the Stop-hook cooldown so a single user does not see the same session repeatedly within one work day.
+- **(d) `covered_through_ts` present → check for high-value signal in `ts > covered_through_ts` events for this `session_id`.** Tail-scan `events.jsonl` for events newer than the watermark whose `session_id` matches. A session passes this gate iff at least ONE of:
+  - ≥1 event with `event_type ∈ HIGH_VALUE_EVENT_TYPES` (`knowledge_context_planned`, `edit_paths_recorded`), OR
+  - the latest `assistant_turn_observed` event body contains ≥1 of `NORMATIVE_KEYWORDS` (substring match, case-insensitive for English entries).
+
+  No high-value signal → drop (no new content worth re-scanning, even though the cooldown has expired). Has signal → keep for re-scan.
+- **(e) Never attempted (no `session_archive_attempted` event found for this `session_id`) → keep.** First-time scan; nothing to filter against.
+- **(f) Cross-session pending dedupe** (operates on candidate observations, not on `session_id` filter): gather all `knowledge_proposed_ids` from `session_archive_attempted` events with `outcome === "proposed"` across ALL sessions in the recent window (NOT just the current candidate session). This builds a global set of idempotency keys already proposed by prior archive runs but not yet reviewed by the user (`.fabric/knowledge/pending/` may still contain them). When classifying new observations in Phase 3, drop any candidate whose computed `idempotency_key` matches an id already in this set — it was already proposed by an earlier archive run, the user just hasn't reviewed it yet, so re-proposing would duplicate pending entries and inflate `candidates_proposed` counts. Per Phase 4.5 dedupe consumer of `knowledge_proposed_ids`.
+
+The resulting filtered `session_id[]` proceeds into Step 5's digest concatenation. Sessions filtered out in this step do NOT contribute to `### Cross-session digest`, are NOT included in `source_sessions` on any fab_extract_knowledge call, and are NOT referenced in `session_context` bodies.
+
+### Constants (rc.25 — verbatim)
+
+- `ANTI_LOOP_HOURS = 12` — cooldown window in hours between consecutive re-scans of the same `session_id`. Rationale: 心智对齐 hook cooldown (`stop_hook_cooldown_hours = 12`); identical mental model avoids user confusion when a session shows up in both hook reminders and archive re-scan candidates.
+- `HIGH_VALUE_EVENT_TYPES = ['knowledge_context_planned', 'edit_paths_recorded']` — event types that count as "new substantive activity worth re-scanning" past `covered_through_ts`. Chat accumulation (`assistant_turn_observed` alone) does NOT count — it would let mere conversation noise trigger re-scans.
+- `NORMATIVE_KEYWORDS = ['以后','always','never','from now on','下次','记一下','永远不要']` — substring patterns scanned against the latest `assistant_turn_observed` body for the session. Mixed CN/EN to cover bilingual users. If any keyword hits, the session is flagged as having high-value chat-only signal even without code edits.
+
+### Worked examples
+
+- **Session X (user_dismissed)** — last `session_archive_attempted` ts = 3 days ago, outcome = `user_dismissed`. Rule (b) fires → permanent skip. Session X is dropped even if 50 new `knowledge_context_planned` events have accumulated since.
+- **Session Y (proposed 6h ago)** — last `session_archive_attempted` ts = 6h ago, outcome = `proposed`. Rule (c) fires: 6h < 12h cooldown window → drop (cooldown skip). Y becomes eligible again after the 12h window closes, provided high-value signal accumulates by then.
+- **Session Z (viability_failed 14h ago + 3 new plan_context)** — last `session_archive_attempted` ts = 14h ago, outcome = `viability_failed`, `covered_through_ts` = T₀. Rules (b)(c) pass. Rule (d) tail-scans for `session_id === Z AND ts > T₀`: finds 3 `knowledge_context_planned` events. HIGH_VALUE_EVENT_TYPES match → keep Z for re-scan. The previous viability failure does not block a re-scan once new substantive activity has accumulated.
+
+## Step 5 — Build cross-session context
+
+Concatenate the loaded digests into a single `### Cross-session digest` block to carry into Phase 2.5 + Phase 1. Use this block to:
+
+- Detect session-spanning patterns (e.g. a discussion that started in session A and continued in session B).
+- Populate the `source_sessions` array on every fab_extract_knowledge call — the array form (T5) replaces the legacy `source_session` string.
+- Inform the `session_context` blob written to each pending entry's body (3-5 lines summarizing goal + key turning point, per T6).
+
+## Graceful degradation
+
+If `.fabric/.cache/session-digests/` is missing entirely, this phase reports an empty context and Phase 2 falls back to the single-session behaviour. Tests that synthesize events.jsonl without populating the digest cache continue to work. If `session_archive_attempted` events are missing entirely (pre-rc.25 ledger or rotation has trimmed older events), treat all sessions as never-attempted (current default behavior) — Step 4.5 rule (e) applies uniformly, so the filter degrades to the legacy "scan everything since anchor" semantics without raising errors.

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

@@ -0,0 +1,54 @@
+# Phase 2.5 — Viability Gate (ref)
+
+> **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
+
+Scan `user_messages_summary` + `recent_paths` + the events tail collected in Phase 2. Each signal listed in SKILL.md hot path is explained below:
+
+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.
+
+## Anti-archive signals — verbose explanation
+
+These force the gate to FAIL **unless** an archive signal also fires (i.e. anti-signals are dominated by any archive signal per the gate decision rules):
+
+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.
+
+## Gate-FAIL user messages (E2 / E4 only)
+
+For the user-active branch, the gate-FAIL message variants are:
+
+### zh-CN variant
+
+```
+本次会话为常规执行，无新知识可归档（gate=<reason>）。如需强制归档，请显式调用 fabric-archive。
+```
+
+### en variant
+
+```
+Current session is routine execution; no new knowledge to archive (gate=<reason>). To force-archive, explicitly invoke fabric-archive.
+```
+
+In BOTH branches: do NOT proceed to Phase 3, do NOT call any MCP tool. The legacy `knowledge_archive_aborted` event line (`{"ts":"...","kind":"knowledge_archive_aborted","reason":"<reason>","session":"<id>"}`) MAY be appended in addition to the mandatory Phase 4.5 `session_archive_attempted` event — they serve different audit purposes (legacy abort reason vs new outcome state machine) and the two coexist during the rc.25 transition window.
+
+## events.jsonl Constraint Note (POSIX 4KB atomicity)
+
+Event lines appended to `.fabric/events.jsonl` are subject to POSIX single-write atomicity: only writes ≤ 4KB (`PIPE_BUF`) are guaranteed atomic via `Bash: echo "..." >> file`. Lines exceeding 4KB risk interleaved corruption under concurrent skill + server writes to the same ledger.
+
+Skills MUST ensure:
+
+- Each event JSON line is a **single line** (no embedded newlines; escape `\n` in any string value).
+- `session_context` and other free-form text fields **self-truncate** to keep the entire serialized line under 4KB. Suggested per-field caps: `session_context` first 500 chars; `source_sessions` cap at 5 entries; `recent_paths` cap at 20 entries; `user_messages_summary` first 500 chars.
+- If approaching the 4KB ceiling after the per-field caps, drop optional fields (e.g. tags / extra metadata) **before** truncating semantic content (the summary / context that carries the actual observation).
+- This constraint applies to any event the skill itself appends (e.g. the abort signal above); MCP-server-side appends (via `appendEventLedgerEvent`) are already line-length-bounded server-side.

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

@@ -0,0 +1,80 @@
+# 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.
+
+## relevance_paths derivation algorithm (rc.5 single-signal: edit_paths only)
+
+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.
+
+```
+Step 1: COLLECT
+  edit_paths = []
+  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
+  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.
+  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).
+
+Step 5: SCOPE GATE
+  IF relevance_scope == broad → relevance_paths = []  (force empty regardless of edit_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.
+```
+
+## Worked generalization example
+
+Edit history during session:
+
+```
+packages/server/src/services/extract.ts
+packages/server/src/services/review.ts
+packages/server/src/services/promote.ts
+packages/cli/src/commands/plan.ts
+README.md
+```
+
+Step 1-2 (collect + dedupe): all 5 unique.
+Step 3 (blacklist): drop `README.md` (repo-root single file).
+Step 4 (generalize, depth ≤ 2, minGroupSize = 2):
+- `packages/server/src/services/{extract,review,promote}.ts` → group size 3 ≥ 2, common prefix `packages/server/src/services/`, glob: `packages/server/src/services/**/*.ts`
+- `packages/cli/src/commands/plan.ts` → group size 1, kept literal.
+
+Step 5 (assume `relevance_scope=narrow`):
+
+```json
+"relevance_paths": [
+  "packages/server/src/services/**/*.ts",
+  "packages/cli/src/commands/plan.ts"
+]
+```
+
+If `relevance_scope=broad` had been chosen instead, `relevance_paths` would be `[]` regardless of the above.
+
+## Inline-edit support during batch review
+
+The user MAY inline-edit `[relevance_scope=...]` in the batch review. When this happens:
+
+- Edit changes `narrow → broad`: clear `relevance_paths` to `[]`.
+- Edit changes `broad → narrow`: re-run Steps 1-4 of the derivation algorithm to recompute.
+- The user MAY also directly inline-edit `relevance_paths` to a custom array; treat this as authoritative and skip auto-derivation.

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

@@ -0,0 +1,63 @@
+# Phase 3 — Classify, Layer, Slug, Review (ref)
+
+> **Loaded on demand.** SKILL.md hot path retains the contract (type/layer/slug/summary fields), the verbatim layer heuristic block (protected tokens — NEVER paraphrased), and brief slug rules + decision tree. This file holds verbose 5-type explanations, slug examples, and the bilingual batch review templates.
+
+## Five Knowledge Types (verbose)
+
+- **model** — A reusable mental abstraction or domain object schema. Worth-archive signal: the user names something ("the X pattern", "the Y phase"). Skip-it signal: ad-hoc terminology used once. Positive: "Wave-1/Wave-2 task DAG decomposition for parallel-safe planning". Negative: "the thing we did just now" (too thin, no reusable abstraction).
+- **decision** — A choice between alternatives with rationale. Worth-archive signal: ≥2 options were weighed AND a rationale was given. Skip-it signal: the choice was forced by external constraint with no real alternative. Positive: "Single .cjs hook script over three per-client scripts — rationale: identical stdout JSON shape across Claude/Codex". Negative: "Used the existing fab_extract_knowledge schema" (no alternative was considered).
+- **guideline** — A normative rule for future similar situations. Worth-archive signal: the user said "always" / "never" / "from now on". Skip-it signal: a one-off preference that won't generalize. Positive: "Slug naming: kebab-case, 2-5 words, 20-40 chars, semantic core only". Negative: "Use 4-space indent in this one file" (too narrow).
+- **pitfall** — A trap that wasted time and is non-obvious. Worth-archive signal: a bug took >15 min to diagnose AND is repeatable. Skip-it signal: a typo or one-time API quirk. Positive: "deepMerge replaces arrays — hooks.Stop[] needs special-case append-with-dedupe". Negative: "Forgot a comma in JSON" (too obvious).
+- **process** — A multi-step procedure with a stable shape. Worth-archive signal: the steps were executed in a specific order AND the order matters. Skip-it signal: a one-shot script with no reusable structure. Positive: "fab_review approve = counter++ → frontmatter inject → git mv → meta rebuild → event append (5 atomic steps)". Negative: "Ran the tests, then committed" (trivial, no reusable shape).
+
+## Slug Naming — examples
+
+Passing examples: `wave-1-parallel-task-dag` (4 words, 24 chars), `deepmerge-array-replace-trap` (4 words, 28 chars).
+
+Failing examples: `the_solution` (underscore + article), `fix` (1 word, too short), `how-we-decided-to-handle-the-merge-conflict-in-stop-hook-config` (overlong).
+
+## Batch Review Template (bilingual)
+
+Present all candidates in a single screen. UX i18n Policy classes 1 + 3 — the roll-up structure AND the per-candidate `Confirm?` prompt are bilingualized; protected tokens (`relevance_scope`, `relevance_paths`, `narrow`, `broad`, `layer`, `team`, `personal`, `pending_path`, etc.) appear verbatim in BOTH variants. Field VALUES (slugs, file paths, type/layer enum strings like `decision` / `team`) are data and are NOT translated.
+
+### en variant (`fabric_language === "en"`)
+
+```md
+# Archive Review — N candidates
+
+## C1 [type=decision] [layer=team] [relevance_scope=narrow] slug=wave-1-parallel-task-dag
+Summary: <1-2 sentences capturing the observation>
+Layer reasoning: <which 强 team / 强 personal signal applied, or default team>
+Scope reasoning: <why narrow or broad — see Phase 3.5>
+relevance_paths: ["packages/cli/src/commands/plan.ts", "packages/cli/templates/**/*.md"]
+Confirm? (Y to accept, edit type/layer/slug/relevance_scope/relevance_paths inline, N to skip)
+
+## C2 [type=pitfall] [layer=team] [relevance_scope=broad] slug=deepmerge-array-replace-trap
+Summary: ...
+Layer reasoning: ...
+Scope reasoning: ...
+relevance_paths: []
+Confirm? ...
+```
+
+### zh-CN variant (`fabric_language === "zh-CN"`)
+
+```md
+# 归档 Review — N 条候选
+
+## C1 [type=decision] [layer=team] [relevance_scope=narrow] slug=wave-1-parallel-task-dag
+摘要: <1-2 句捕捉该观察>
+Layer 判定: <命中哪条 强 team / 强 personal 信号，或默认 team>
+Scope 判定: <为什么 narrow 或 broad — 见 Phase 3.5>
+relevance_paths: ["packages/cli/src/commands/plan.ts", "packages/cli/templates/**/*.md"]
+确认？(Y 接受 / 内联编辑 type/layer/slug/relevance_scope/relevance_paths / N 跳过)
+
+## C2 [type=pitfall] [layer=team] [relevance_scope=broad] slug=deepmerge-array-replace-trap
+摘要: ...
+Layer 判定: ...
+Scope 判定: ...
+relevance_paths: []
+确认？...
+```
+
+The user MAY edit type/layer/slug/relevance_scope/relevance_paths inline before confirming. The user MAY skip individual candidates without rejecting the whole batch. Inline-editing `[relevance_scope=...]` triggers a re-derivation of `relevance_paths` per the Phase 3.5 rules (narrow ⇒ recompute from edit_paths; broad ⇒ force `[]`).