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

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

@@ -4,7 +4,7 @@
 
 ## 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 0.0 reads these to stitch context across sessions since the last `knowledge_proposed` event.
+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)
 
@@ -12,7 +12,7 @@ Cross-session digest mechanism introduced. Stop hook writes per-session digest t
 
 ## v2.0.0-rc.23 (F8c / a-C2)
 
-- **F8c**: Phase 0.4 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.
+- **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)
@@ -23,16 +23,16 @@ Cross-session digest mechanism introduced. Stop hook writes per-session digest t
 
 Major fabric-archive overhaul:
 
-- **TASK-01**: `session_archive_attempted` event — drives Phase 0.0 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.5 Range Resolution parses time-window + topic-keyword hints into a `session_id[]` scope filter. Anti-loop constants (12h cooldown, normative-keyword scan) landed here.
+- **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 2.5 dry-run override path (Codex audit §2.25).
+- **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-0-4-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 0.4 onboard, end-to-end examples, E5 cron setup) moved out.
+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

@@ -74,5 +74,5 @@ mcp__fabric__fab_extract_knowledge({
 })
 ```
 
-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 1.5 special case).
+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).