@fenglimg/fabric-cli 2.0.0 → 2.1.0-rc.2

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

@@ -0,0 +1,68 @@
+# 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 (rc.37 NEW-4 simplified 8 → 3)
+
+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):
+
+### 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
+
+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** — 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)
+
+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,108 @@
+# 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.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.37 multi-signal — NEW-7)
+
+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 (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.
+
+  // 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
+
+Step 4: PUBLIC-PREFIX GENERALIZE (depth ≤ 2, minGroupSize = 2)
+  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 candidate_paths)
+  IF relevance_scope == narrow → relevance_paths = result of Step 4
+
+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
+
+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 `[]`).

package/templates/skills/fabric-archive/ref/phase-4-5-emit.md

@@ -0,0 +1,78 @@
+# Phase 4.5 — Persist Archive Attempt (ref)
+
+> **Loaded on demand.** SKILL.md hot path retains the MANDATORY-on-every-invocation rule, the dry-run cross-reference, and the outcome enum. This file holds the full event emission jsonc schema, outcome decision matrix, covered_through_ts watermark spec, multi-session emission rule, append-pattern reference, and the E5-cron-silent-skip worked example.
+
+## What to emit
+
+For EACH `session_id` in the run's scope (multi-session E4 runs emit MULTIPLE events — one per session_id; single-session E1/E2/E3/E5 runs emit ONE event), append ONE `session_archive_attempted` line to `.fabric/events.jsonl`:
+
+```jsonc
+{
+  "kind": "fabric-event",
+  "id": "<uuid or ts-derived>",
+  "ts": <epoch ms>,
+  "schema_version": 1,
+  "session_id": "<the session this event pertains to>",
+  "event_type": "session_archive_attempted",
+  "outcome": "proposed" | "viability_failed" | "user_dismissed" | "skipped_no_signal",
+  "covered_through_ts": <max event ts scanned for this session>,
+  "candidates_proposed": <integer, default 0>,
+  "knowledge_proposed_ids": ["<idempotency_key_1>", "..."]   // default []
+}
+```
+
+## Outcome decision matrix
+
+| Skill terminal state                                                 | outcome              | candidates_proposed | knowledge_proposed_ids                          |
+|----------------------------------------------------------------------|----------------------|---------------------|-------------------------------------------------|
+| Phase 4 wrote ≥ 1 pending entry                                      | `proposed`           | N (count written)   | `[idempotency_key_1, idempotency_key_2, ...]` (from each fab_extract_knowledge response) |
+| Phase 2.5 viability_failed AND entry_point ∈ {E2_explicit, E4_user_range} AND user saw + accepted the gate-FAIL message | `viability_failed`   | 0                   | `[]`                                            |
+| Phase 3 batch review — user dismissed ALL presented candidates       | `user_dismissed`     | 0                   | `[]`                                            |
+| Phase 1 filter dropped every session in scope OR Phase 2.5 silent-skip path (E1_hook / E3_ai_self_trigger / E5_cron) | `skipped_no_signal`  | 0                   | `[]`                                            |
+
+Rationale highlights:
+- `user_dismissed` is the ONLY outcome that suppresses future auto-rescan (respects user decision per Q3.4).
+- `proposed` populates `knowledge_proposed_ids` so the cross-session digest in Phase 1 can dedupe future runs against already-proposed entries.
+- `viability_failed` vs `skipped_no_signal` distinguishes "user was prompted but the gate stopped us" from "we never bothered the user" — both allow rescan but the doctor history report differentiates them.
+
+## covered_through_ts watermark
+
+```
+covered_through_ts = max(events_in_scope[*].ts)
+```
+
+where `events_in_scope` is the set of events the skill actually examined for THAT session_id (Phase 2 + Phase 1 digest input). On rescan, Phase 1 compares the current `max(ts)` against this stored watermark — only sessions with new events past the watermark are eligible candidates.
+
+## Multi-session emission rule
+
+When the run scope spans multiple session_ids (E4 user-range with `--since` / topic-keyword matching multiple sessions), emit ONE `session_archive_attempted` event PER session_id. Each event's `covered_through_ts` is computed against that session's own event subset. The `knowledge_proposed_ids` for a multi-session `proposed` run lists ALL idempotency_keys produced by the run; ledger consumers that want per-session breakdown should join against `source_sessions` on each pending entry.
+
+## Append pattern (Bash echo, 4KB-safe, fail-tolerant)
+
+Reuse the Phase 2.5 `events.jsonl Constraint Note` pattern: single-line JSON ≤ 4KB, no embedded newlines. Best-effort write — if the append fails (disk full, permission denied, race), the skill MUST still exit successfully. Log the failure to stderr only; do NOT surface it to the user. Rationale: a missing `session_archive_attempted` event degrades gracefully — the next Phase 1 digest treats the session as "never archived" and re-evaluates it, which is the safe-default behavior.
+
+```bash
+# Pseudo — actual implementation uses the same pattern as the legacy
+# knowledge_archive_aborted emit at the end of Phase 2.5.
+echo '{"kind":"fabric-event","id":"...","ts":..., "schema_version":1, "session_id":"...", "event_type":"session_archive_attempted","outcome":"...","covered_through_ts":...,"candidates_proposed":0,"knowledge_proposed_ids":[]}' >> .fabric/events.jsonl
+```
+
+The per-field caps from Phase 2.5's constraint note carry over: `knowledge_proposed_ids` capped at 20 entries (drop tail with `...` marker in `id` field if truncated); other fields are bounded by schema.
+
+## Worked example: E5 cron silent-skip
+
+Setup: An OS cron job runs `fabric-archive` at 03:00 daily for the "today" range (E5 entry_point). Today's session was routine config edits — no archive signals fire.
+
+Trace:
+1. Phase 0 resolves `entry_point=E5_cron`, range = "today" → 1 session_id in scope.
+2. Phase 1 digest collects events for that session_id; nothing dropped.
+3. Phase 1.5 onboard is skipped (E5 is not E2).
+4. Phase 2.5 viability gate runs — `archive_signals_hit=0` → `gate=FAIL (reason=no_signal)`.
+5. `entry_point=E5_cron` ∈ {E1, E3, E5} → SILENT-SKIP branch. No message rendered.
+6. Phase 4.5 (mandatory) appends ONE event:
+   ```
+   {"kind":"fabric-event","id":"...","ts":<now>,"schema_version":1,"session_id":"<today-session-id>","event_type":"session_archive_attempted","outcome":"skipped_no_signal","covered_through_ts":<max ts of today's events>,"candidates_proposed":0,"knowledge_proposed_ids":[]}
+   ```
+7. Skill exits silently. Cron output is empty.
+
+Next day's cron rescan: Phase 1 sees `covered_through_ts < max(ts of session's new events)` → session is rescan-eligible → loop continues without `user_dismissed` block.

package/templates/skills/fabric-archive/ref/phase-4-mcp-persist.md

@@ -0,0 +1,89 @@
+# Phase 4 — Persist via MCP (ref)
+
+> **Loaded on demand.** SKILL.md hot path retains the per-candidate one-call rule + brief mention of `proposed_reason` enum + session_context format. This file holds the full MCP call shape (with all rc.7/rc.23 optional fields), the C1 triage-field inference table, the proposed_reason mapping table, and the T5 array-form idempotency notes.
+
+## Full MCP tool call shape
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["<session id1>", "<session id2>", ...],  // T5: array form (Phase 1)
+  recent_paths: ["<path1>", "<path2>", ...],   // capped at archive_max_recent_paths (config-resolved, default 20)
+  user_messages_summary: "<compact prose ≤500 chars>",
+  type: "decisions" | "pitfalls" | "guidelines" | "models" | "processes",
+  slug: "<kebab-case-2-to-5-words>",
+  layer: "team" | "personal",
+  relevance_scope: "narrow" | "broad",         // from Phase 3.5
+  relevance_paths: ["<glob1>", "<literal2>", ...],  // narrow ⇒ derived; broad ⇒ []
+  // v2.0.0-rc.7 T6: required fields for future-self reviewability.
+  proposed_reason:
+    "explicit-user-mark"      // user said "always / never / 下次注意" etc.
+    | "diagnostic-then-fix"   // long debug loop surfaced a new pattern/pitfall
+    | "decision-confirmation" // ≥2 options weighed AND rationale stated → decision/model
+    | "wrong-turn-revert"     // tried path X, reverted → pitfall
+    | "new-dependency-or-pattern" // new dep/lib/abstraction introduced
+    | "dismissal-with-reason",    // user rejected approach AND said why
+  session_context: "<3-5 line markdown: session goal + key turning point>",
+  // v2.0.0-rc.23 TASK-006 (a-C1): four OPTIONAL structured triage fields.
+  // Lift implicit signals out of `## Session context` prose so future-self
+  // reviewers / plan-context retrievers can triage relevance from
+  // frontmatter alone, without re-reading the body. Omit any field the
+  // skill cannot infer cleanly — guessing is worse than omitting.
+  intent_clues: ["<short trigger>", "<negative trigger e.g. 'NOT for X'>"],  // when this rule applies / when NOT
+  tech_stack: ["<lang/framework>", "..."],  // inferred from recent_paths (see table below)
+  impact: ["<consequence of ignoring>"],    // why future-self should care
+  must_read_if: "<one-line strong trigger>" // single condition; if it holds, the entry is required reading
+  // tags? — NOT in current schema; reserved for future
+})
+```
+
+## C1 triage-field inference table
+
+| Field          | Inference source                                                                 | Skip when                          |
+|----------------|----------------------------------------------------------------------------------|------------------------------------|
+| `intent_clues` | Pull from `session_context` turning point + negative phrasing in the transcript ("not for", "don't do X when") | No clear trigger phrasing surfaced |
+| `tech_stack`   | Map `recent_paths` extensions: `.ts`→`typescript`, `.tsx`→`typescript`+`react`, `.go`→`go`, `package.json`→`nodejs`, `pyproject.toml`→`python`, `Cargo.toml`→`rust`. Add framework markers from path heuristics (`cocos`→`cocos-creator`, `next.config`→`nextjs`) | Rule is stack-agnostic            |
+| `impact`       | Pull from the diagnostic-loop body — "wasted 30 min", "production outage", "silent data loss" | No observable consequence stated   |
+| `must_read_if` | Strongest single trigger from the worth-archive signal: a file path, a routine, a recurring condition; ≤160 chars | No single dominant trigger fits    |
+
+All four fields are STRICTLY OPTIONAL. The schema accepts the call without any of them — omit rather than guess. None of the four participate in the idempotency_key hash (server formula at `extract-knowledge.ts:100-106` is frozen to `{source_session, type, slug}`), so partial-vs-full fill of these fields on the same triple is safe.
+
+## proposed_reason → classification mapping
+
+The skill infers `proposed_reason` from the classification + viability-gate signal that fired:
+
+| Signal fired (Phase 2.5)       | Classification | Default proposed_reason     |
+|--------------------------------|----------------|-----------------------------|
+| Explicit normative language    | guideline      | `explicit-user-mark`        |
+| Wrong-turn-and-revert          | pitfall        | `wrong-turn-revert`         |
+| Long diagnostic loop           | pitfall/model  | `diagnostic-then-fix`       |
+| New dependency adoption        | decision/model | `new-dependency-or-pattern` |
+| New pattern emergence          | model          | `new-dependency-or-pattern` |
+| Decision confirmation          | decision       | `decision-confirmation`     |
+| Explicit dismissal-with-reason | decision       | `dismissal-with-reason`     |
+| Process formalization          | process        | `new-dependency-or-pattern` |
+
+## session_context format
+
+```
+Session goal: <one-line of what the user was trying to accomplish>
+Turning point: <one-line of the key moment that produced the worth-archive observation>
+[optional 1-3 more lines of supporting context]
+```
+
+Future-self reviewing the pending entry MUST be able to understand WHY this entry was proposed without conversation transcript access — `proposed_reason` is the structured why; `session_context` is the narrative why.
+
+Note on type plurality: the MCP enum uses plural directory-form (decisions / pitfalls / guidelines / models / processes), while the conceptual classification uses singular nouns (decision / pitfall / guideline / model / process). They map 1:1.
+
+The server returns `{ pending_path, idempotency_key }`. Display `pending_path` to the user so they can `Read` the persisted entry if they wish.
+
+## Idempotency Notes (T5 array-form, rc.7+)
+
+The MCP tool derives `idempotency_key = sha256({source_session, type, slug})`. Calling `fab_extract_knowledge` twice with the same `(source_session, type, slug)` triple is SAFE: the server appends new evidence to the existing pending file rather than overwriting or producing duplicates. The skill MAY be re-invoked on the same session without producing junk.
+
+If the skill needs to record a genuinely separate observation in the same session+type, the slug MUST differ.
+
+**T5 array-form**: when `source_sessions` is passed as an array (rc.7 T5 contract), only `source_sessions[0]` participates in the server-side idempotency hash. Server formula at `packages/server/src/services/extract-knowledge.ts:78` is `sha256(JSON.stringify({source_session: sourceSessions[0], type, slug}))`. Implications:
+
+- Same `(type, slug)` but a different **first** session → distinct idempotency key → produces two pending files.
+- Same first session but different tail sessions → evidence-merge into the SAME pending file; tail `session_id`s are NOT recorded as independent evidence keys.
+- The formula is intentionally stable across the rc.5 → rc.7 migration; adding or removing tail entries does NOT change the idempotency key, preserving rc.5 single-session compat.

package/templates/skills/fabric-archive/ref/rc-history.md

@@ -0,0 +1,38 @@
+# rc-history — version landmarks for fabric-archive
+
+> **Loaded on demand.** SKILL.md hot path does NOT need this file. It exists so when you encounter an inline comment like `(rc.25 TASK-01)` and wonder "what changed then?", you can `Read` here without polluting routine archive invocations.
+
+## v2.0.0-rc.7 (T5)
+
+Cross-session digest mechanism introduced. Stop hook writes per-session digest to `.fabric/.cache/session-digests/<session_id>.md`. fabric-archive Phase 1 reads these to stitch context across sessions since the last `knowledge_proposed` event.
+
+## v2.0.0-rc.20 (TASK-02 / TASK-03)
+
+`assistant_turn_observed` event + cite-policy observability landed. KB-line parsing surfaces `cite_ids` / `cite_tags`. fabric-archive doesn't directly consume — see fabric-hint for the parser.
+
+## v2.0.0-rc.23 (F8c / a-C2)
+
+- **F8c**: Phase 1.5 first-run onboard phase added. S5 slots (`tech-stack-decision`, `architecture-pattern`, `code-style-tone`, `build-system-idiom`, `domain-vocabulary`) baseline the workspace tone for plan_context retrieval.
+- **a-C2**: knowledge_enriched event for description-grade frontmatter back-fill.
+
+## v2.0.0-rc.24 (TASK-01 / TASK-04)
+
+`cite_contract_policy_activated` marker + per-cite `cite_commitments` parallel array. CJS twin of shared cite-line-parser shipped to hooks.
+
+## v2.0.0-rc.25 (TASK-01 / E4 / Q3.3 / Q3.4)
+
+Major fabric-archive overhaul:
+
+- **TASK-01**: `session_archive_attempted` event — drives Phase 1 cross-session digest rescan filter (outcome state machine: proposed / viability_failed / user_dismissed / skipped_no_signal).
+- **TASK-05**: 5-entry model (E1 hook / E2 explicit / E3 AI-self / E4 user-range / E5 cron). Phase 0 Range Resolution parses time-window + topic-keyword hints into a `session_id[]` scope filter. Anti-loop constants (12h cooldown, normative-keyword scan) landed here.
+- **Q3.4**: outcome-based rescan suppression — `user_dismissed` permanently skips a session.
+
+## v2.0.0-rc.27 (TASK-007 / TASK-011 / TASK-012)
+
+- **TASK-007**: Phase 4.5 dry-run override path (Codex audit §2.25).
+- **TASK-011** (Codex review fix): cite_commitments index-aligned with cite_ids on multi-id parses (audit §2.18 follow-up).
+- **TASK-012** (Codex review fix): dropped stale "no dry-run mode" prose that conflicted with TASK-007.
+
+## v2.0.0-rc.28 (this release)
+
+SKILL.md split into entry (hot path) + `ref/` (this file + i18n-policy + phase-1-5-onboard + worked-examples + e5-cron-recap). 1343 → ~950 lines for the hot path (~29% reduction). Active flow logic unchanged; reference-only content (almost-never-loaded i18n class taxonomy, Phase 1.5 onboard, end-to-end examples, E5 cron setup) moved out.

package/templates/skills/fabric-archive/ref/worked-examples.md

@@ -0,0 +1,78 @@
+# Worked Examples — full reference
+
+> **Loaded on demand.** SKILL.md gives the operative contract (the 5 types + layer heuristic + slug rules + MCP call shape). These end-to-end examples illustrate the integration — load when you want to see all fields filled out together.
+
+## Worked Examples
+
+## Example 1 — decision (team)
+
+Session: User and agent debated whether the Stop-hook should be one .cjs script or three per-client scripts. Settled on one because stdout JSON shape `{"decision":"block","reason"}` is identical across Claude / Codex.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: ["templates/claude-hooks/", "packages/cli/src/commands/hooks.ts"],
+  user_messages_summary: "User pushed back on three-script proposal; agreed single .cjs because stdout JSON shape is universal across Claude Code and Codex CLI.",
+  type: "decisions",
+  slug: "single-cjs-hook-script",
+  layer: "team",
+  relevance_scope: "narrow",
+  relevance_paths: [
+    "templates/claude-hooks/**/*.cjs",
+    "packages/cli/src/commands/hooks.ts"
+  ],
+  proposed_reason: "decision-confirmation",
+  session_context: "Session goal: ship Stop-hook for v2 release.\nTurning point: user rejected 3-script proposal after seeing identical stdout JSON across Claude / Codex.\nResult: single .cjs path locked in."
+})
+```
+
+Layer = team (引用本项目代码 + fabric-import 路径产物 signals). Scope = narrow (tied to hook templates + hooks command module; single-module evidence in edit_paths).
+
+### Example 2 — pitfall (team)
+
+Session: deepMerge silently replaced the existing `hooks.Stop[]` array in `.claude/settings.json` instead of appending. Cost ~30 min to diagnose.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: ["packages/cli/src/config/json.ts"],
+  user_messages_summary: "deepMerge default behavior REPLACES arrays. hooks.Stop[] needs an array-append-with-dedupe special case keyed on .command string match.",
+  type: "pitfalls",
+  slug: "deepmerge-array-replace-trap",
+  layer: "team",
+  relevance_scope: "broad",
+  relevance_paths: [],
+  proposed_reason: "diagnostic-then-fix",
+  session_context: "Session goal: wire hook installer for v2.\nTurning point: spent ~30 min chasing why prior Stop[] entries vanished — root cause was deepMerge replacing arrays silently.\nResult: array-append-with-dedupe special case added."
+})
+```
+
+Layer = team (绑定本项目代码的 pitfall signal). Scope = broad (deepMerge gotcha is cross-cutting — applies anywhere JSON merge is used, not just `json.ts`).
+
+### Example 3 — guideline (personal)
+
+Session: User mentioned across three projects that they prefer 2-space indent in TypeScript and 4-space in Python.
+
+Skill output:
+
+```ts
+mcp__fabric__fab_extract_knowledge({
+  source_sessions: ["WFS-2026-05-10-rc2"],
+  recent_paths: [".editorconfig"],
+  user_messages_summary: "Personal indent preference: 2-space TS / 4-space Py. Stable across multiple projects, not project-specific.",
+  type: "guidelines",
+  slug: "indent-style-by-language",
+  layer: "personal",
+  relevance_scope: "broad",
+  relevance_paths: [],
+  proposed_reason: "explicit-user-mark",
+  session_context: "Session goal: align editor config.\nTurning point: user said '一直 prefer 2-space TS / 4-space Py，across projects'.\nResult: personal-layer guideline; not bound to this project."
+})
+```
+
+Layer = personal (跨项目通用 + 工具/编辑器偏好 signals dominate; no 强 team signal applies). Scope = broad with `relevance_paths=[]` (personal layer ALWAYS forces broad — paths don't generalize across projects per Phase 3.5 special case).
+