@fenglimg/fabric-cli 2.2.0-rc.1 → 2.2.0-rc.3

package/templates/hooks/configs/claude-code.json

@@ -29,17 +29,32 @@
           {
             "type": "command",
             "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/knowledge-hint-narrow.cjs"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cite-policy-evict.cjs"
           }
         ]
       }
     ],
-    "UserPromptSubmit": [
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/post-tooluse-mutation.cjs"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cite-policy-evict.cjs"
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-end-marker.cjs"
           }
         ]
       }

package/templates/hooks/configs/codex-hooks.json

@@ -8,15 +8,27 @@
     "SessionStart": [
       {
         "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-broad.cjs\""
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-narrow.cjs\""
       },
       {
+        "matcher": "Edit|Write|MultiEdit",
         "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/cite-policy-evict.cjs\""
       }
     ],
-    "PreToolUse": [
+    "PostToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
-        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/knowledge-hint-narrow.cjs\""
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/post-tooluse-mutation.cjs\""
+      }
+    ],
+    "SessionEnd": [
+      {
+        "command": "\"$(git rev-parse --show-toplevel)/.codex/hooks/session-end-marker.cjs\""
       }
     ]
   }

package/templates/hooks/configs/cursor-hooks.json

@@ -5,14 +5,26 @@
       { "command": ".cursor/hooks/fabric-hint.cjs" }
     ],
     "sessionStart": [
-      { "command": ".cursor/hooks/knowledge-hint-broad.cjs" },
-      { "command": ".cursor/hooks/cite-policy-evict.cjs" }
+      { "command": ".cursor/hooks/knowledge-hint-broad.cjs" }
     ],
     "preToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
         "command": ".cursor/hooks/knowledge-hint-narrow.cjs"
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "command": ".cursor/hooks/cite-policy-evict.cjs"
       }
+    ],
+    "postToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "command": ".cursor/hooks/post-tooluse-mutation.cjs"
+      }
+    ],
+    "sessionEnd": [
+      { "command": ".cursor/hooks/session-end-marker.cjs" }
     ]
   }
 }

package/templates/hooks/fabric-hint.cjs

@@ -984,8 +984,34 @@ function readUnderseedThreshold(projectRoot) {
   return DEFAULT_UNDERSEED_NODE_THRESHOLD;
 }
 
-function readShownCache(projectRoot) {
-  const cachePath = join(projectRoot, SHOWN_CACHE_FILE);
+// F13 (ISS-20260531-038): the reminder cooldown sidecars were process-global
+// (one file per project, no session key), so in concurrent multi-window sessions
+// one window firing a nudge wrote the cooldown and silenced that nudge in EVERY
+// other window. Scope the sidecar filename by sessionId — mirrors the already-
+// session-scoped dismiss sidecar (sessionDismissFileName). Backward-compatible:
+// a null/absent sessionId falls back to the legacy non-scoped path (upgrade +
+// pre-session-id callers), so existing on-disk state and tests are unaffected;
+// the Stop hook always passes the real session_id from its stdin payload.
+function resolveHookSessionId(payload) {
+  return payload && typeof payload.session_id === "string" && payload.session_id.length > 0
+    ? payload.session_id
+    : null;
+}
+
+function sessionScopedCacheFile(baseRelPath, sessionId) {
+  if (sessionId === undefined || sessionId === null || String(sessionId).length === 0) {
+    return baseRelPath;
+  }
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "-");
+  const lastSlash = baseRelPath.lastIndexOf("/");
+  const dot = baseRelPath.lastIndexOf(".");
+  return dot > lastSlash
+    ? `${baseRelPath.slice(0, dot)}-${safe}${baseRelPath.slice(dot)}`
+    : `${baseRelPath}-${safe}`;
+}
+
+function readShownCache(projectRoot, sessionId) {
+  const cachePath = join(projectRoot, sessionScopedCacheFile(SHOWN_CACHE_FILE, sessionId));
   if (!existsSync(cachePath)) return {};
   try {
     const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
@@ -995,12 +1021,11 @@ function readShownCache(projectRoot) {
   }
 }
 
-function writeShownCache(projectRoot, cache) {
-  const cachePath = join(projectRoot, SHOWN_CACHE_FILE);
+function writeShownCache(projectRoot, cache, sessionId) {
+  const cachePath = join(projectRoot, sessionScopedCacheFile(SHOWN_CACHE_FILE, sessionId));
   try {
-    // ISS-016: atomic tmp+rename so concurrent windows / a crash never leave a
-    // truncated shown-cache (this file is NOT session-scoped). Falls back to a
-    // plain write only if the shared lib failed to load.
+    // ISS-016: atomic tmp+rename so a crash never leaves a truncated shown-cache.
+    // Falls back to a plain write only if the shared lib failed to load.
     if (stateStore && typeof stateStore.atomicWrite === "function") {
       stateStore.atomicWrite(cachePath, JSON.stringify(cache));
     } else {
@@ -1124,8 +1149,8 @@ function findLastDoctorRunTs(events) {
  * v2.0.0-rc.7 T10: read the Signal-D cooldown sidecar timestamp (epoch ms).
  * Missing file / parse failure → null (allow signal to fire).
  */
-function readMaintenanceLastEmit(projectRoot) {
-  const p = join(projectRoot, MAINTENANCE_HINT_LAST_EMIT_FILE);
+function readMaintenanceLastEmit(projectRoot, sessionId) {
+  const p = join(projectRoot, sessionScopedCacheFile(MAINTENANCE_HINT_LAST_EMIT_FILE, sessionId));
   if (!existsSync(p)) return null;
   try {
     const raw = readFileSync(p, "utf8").trim();
@@ -1140,8 +1165,8 @@ function readMaintenanceLastEmit(projectRoot) {
   return null;
 }
 
-function writeMaintenanceLastEmit(projectRoot, nowMs) {
-  const p = join(projectRoot, MAINTENANCE_HINT_LAST_EMIT_FILE);
+function writeMaintenanceLastEmit(projectRoot, nowMs, sessionId) {
+  const p = join(projectRoot, sessionScopedCacheFile(MAINTENANCE_HINT_LAST_EMIT_FILE, sessionId));
   try {
     // ISS-016: atomic tmp+rename (see writeShownCache).
     if (stateStore && typeof stateStore.atomicWrite === "function") {
@@ -1246,6 +1271,101 @@ function evaluateMaintenanceSignal(events, now, canonicalCount, lastEmitMs, thre
   };
 }
 
+// lifecycle-refactor W3-A2 (§7 graph generation signal): after a successful
+// archive the Stop hook REQUESTS edge extraction by emitting one
+// graph_edge_candidate_requested{stable_id, store?}. The hook never PRODUCES
+// edges (that is the archive/import skill's or doctor co-occurrence's job,
+// KT-DEC-0007) — it only flags "this entry just landed; someone should extract
+// its `related` edges". FROZEN-safe: O(1) tail scan, best-effort silent, single
+// advisory-locked appendLockedLine (same primitive the rest of this hook uses).
+//
+// HONEST stable_id sourcing — the deliberate limitation: pending entries (the
+// fabric-archive → extractKnowledge path) carry NO canonical stable_id (id is
+// late-bound at fab_review approve), so their knowledge_proposed event omits
+// stable_id (or sets the `pending:<key>` sentinel). A graph edge between
+// id-less pending drafts is meaningless, so we DO NOT fabricate one. We emit
+// ONLY when the most-recent knowledge_proposed event carries a real
+// K[TP]-XXX-NNNN stable_id (the approve/promote path) — i.e. an entry that
+// actually has a canonical node to attach edges to. When the latest proposed
+// is id-less we honestly skip; the request will fire on the approve event that
+// allocates the id. A session-scoped sidecar de-dupes so repeated Stop fires in
+// one session don't re-request the same id.
+const STABLE_ID_RE = /^K[TP]-[A-Z]{3}-\d{4}$/;
+const GRAPH_EDGE_REQUESTED_SIDECAR = ".fabric/.cache/graph-edge-requested";
+
+function emitGraphEdgeCandidateBestEffort(cwd, events, sessionId) {
+  try {
+    if (!Array.isArray(events) || events.length === 0) return;
+    const fabricDir = join(cwd, FABRIC_DIR);
+    if (!existsSync(fabricDir)) return;
+
+    // O(1)-amortized tail scan for the newest knowledge_proposed carrying a
+    // real (non-sentinel) stable_id. Stop at the first knowledge_proposed we
+    // see — if the latest archive is id-less, we honestly skip rather than
+    // reaching back to an older approved entry (that older entry's edges were
+    // already requested when IT landed).
+    let stableId = null;
+    let store;
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      const ev = events[i];
+      if (!ev || ev.event_type !== EVENT_TYPE_PROPOSED) continue;
+      const candidate = typeof ev.stable_id === "string" ? ev.stable_id : null;
+      if (candidate && STABLE_ID_RE.test(candidate)) {
+        stableId = candidate;
+        if (typeof ev.store === "string" && ev.store.length > 0) store = ev.store;
+      }
+      // First knowledge_proposed encountered (newest) decides; do not walk past
+      // it to an older one.
+      break;
+    }
+    if (stableId === null) return;
+
+    // Session-scoped de-dup: skip if we already requested edges for this exact
+    // stable_id this session. Sidecar is a single line holding the last id.
+    const sidecarPath = join(cwd, sessionScopedCacheFile(GRAPH_EDGE_REQUESTED_SIDECAR, sessionId));
+    try {
+      if (existsSync(sidecarPath)) {
+        const prev = readFileSync(sidecarPath, "utf8").trim();
+        if (prev === stableId) return;
+      }
+    } catch {
+      // unreadable sidecar → fall through and (re)emit; de-dup is best-effort.
+    }
+
+    let idSuffix;
+    try {
+      idSuffix = require("node:crypto").randomUUID();
+    } catch {
+      idSuffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+    const event = {
+      kind: "fabric-event",
+      id: `event:${idSuffix}`,
+      ts: Date.now(),
+      schema_version: 1,
+      event_type: "graph_edge_candidate_requested",
+      stable_id: stableId,
+    };
+    if (store !== undefined) event.store = store;
+    if (typeof sessionId === "string" && sessionId.length > 0) event.session_id = sessionId;
+    appendLockedLine(join(fabricDir, EVENT_LEDGER_FILE), JSON.stringify(event) + "\n");
+
+    // Record the de-dup marker (best-effort; atomic when state-store lib loaded).
+    try {
+      if (stateStore && typeof stateStore.atomicWrite === "function") {
+        stateStore.atomicWrite(sidecarPath, stableId);
+      } else {
+        mkdirSync(dirname(sidecarPath), { recursive: true });
+        writeFileSync(sidecarPath, stableId);
+      }
+    } catch {
+      // de-dup marker write failed — at worst we re-request next Stop; harmless.
+    }
+  } catch {
+    // best-effort §7 signal — never block the Stop hook (KT-DEC-0007).
+  }
+}
+
 // v2.1 NEW-N-3 (ADJ-NEWN-3): hook_signal_emitted instrumentation. Writes ONE
 // best-effort ledger row at the point a nudge is actually delivered (post-
 // cooldown), so the join key measures nudge-trigger logic (which signal fired,
@@ -1852,6 +1972,17 @@ function main(env, stdio) {
     );
 
     const events = readLedger(cwd);
+
+    // lifecycle-refactor W3-A2 (§7): request graph-edge extraction for a freshly
+    // archived canonical entry. Runs UNCONDITIONALLY here (before the nudge
+    // cooldown/dismiss early-returns) so the §7 signal is independent of whether
+    // a reminder banner is shown this Stop. Best-effort, never throws.
+    try {
+      emitGraphEdgeCandidateBestEffort(cwd, events, resolveHookSessionId(stdinPayload));
+    } catch {
+      // never block the Stop hook
+    }
+
     let pendingStats;
     try {
       pendingStats = readPendingStats(cwd, now);
@@ -1984,7 +2115,7 @@ function main(env, stdio) {
     // for the prompt to be actionable.
     if (result === null) {
       try {
-        const lastEmit = readMaintenanceLastEmit(cwd);
+        const lastEmit = readMaintenanceLastEmit(cwd, resolveHookSessionId(stdinPayload));
         result = evaluateMaintenanceSignal(
           events,
           now,
@@ -2041,7 +2172,7 @@ function main(env, stdio) {
       delete result.threshold;
       delete result.actual_value;
       out.write(JSON.stringify(result));
-      writeMaintenanceLastEmit(cwd, nowMs);
+      writeMaintenanceLastEmit(cwd, nowMs, resolveHookSessionId(stdinPayload));
       return;
     }
 
@@ -2049,7 +2180,7 @@ function main(env, stdio) {
     // archive_hint_cooldown_hours (default 12h) regardless of state drift.
     // Pure reminder-noise reduction; the underlying trigger logic is unchanged.
     const cooldownMs = readCooldownHours(cwd) * MS_PER_HOUR;
-    const cache = readShownCache(cwd);
+    const cache = readShownCache(cwd, resolveHookSessionId(stdinPayload));
     const lastShown = cache[result.signal];
     // rc.34 TASK-01 + review-fix (Gemini P1): future-stamped lastShown
     // (backward clock skew) bypasses cooldown — sidecar treated as expired.
@@ -2066,7 +2197,7 @@ function main(env, stdio) {
     delete result.actual_value;
     out.write(JSON.stringify(result));
     cache[result.signal] = nowMs;
-    writeShownCache(cwd, cache);
+    writeShownCache(cwd, cache, resolveHookSessionId(stdinPayload));
   } catch {
     // Silent — never block on hook failure.
   }
@@ -2121,6 +2252,9 @@ module.exports = {
   // of the contract-missing emission contract). The lib module itself is
   // also exported indirectly via the reminder helper.
   emitCiteContractRemindersBestEffort,
+  // lifecycle-refactor W3-A2 (§7): graph-edge-candidate request emitter
+  // (exported for unit testing of the honest stable_id-gating + de-dup).
+  emitGraphEdgeCandidateBestEffort,
   CONSTANTS: {
     FABRIC_DIR,
     EVENT_LEDGER_FILE,
@@ -2158,6 +2292,8 @@ module.exports = {
     // v2.0.0-rc.8 (TASK-002): in-flight import gate for Signal B.
     IMPORT_STATE_FILE_REL,
     IMPORT_IN_FLIGHT_MAX_AGE_HOURS,
+    // lifecycle-refactor W3-A2 (§7): graph-edge-request de-dup sidecar.
+    GRAPH_EDGE_REQUESTED_SIDECAR,
   },
 };
 

package/templates/hooks/knowledge-hint-broad.cjs

@@ -574,7 +574,18 @@ function truncateSummary(raw, maxLen) {
 function formatEntryLine(entry, maxLen) {
   const id = entry.id || "(no-id)";
   const summary = truncateSummary(entry.summary, maxLen);
-  return summary.length > 0 ? `    - ${id} · ${summary}` : `    - ${id}`;
+  // lifecycle-refactor W3-T2 (§7 图谱消费 / §5 hook 沿 related 二阶召回): when this
+  // entry was pulled in by following a surfaced entry's `related` graph edge,
+  // tag the line with its provenance so the agent knows it arrived via the graph,
+  // not its own ranking. Omitted entirely for ordinarily-ranked entries — no fake
+  // "related" annotation is ever synthesized (graph-empty honesty).
+  const provenance =
+    typeof entry.related_to === "string" && entry.related_to.length > 0
+      ? ` (related-to-${entry.related_to})`
+      : "";
+  return summary.length > 0
+    ? `    - ${id} · ${summary}${provenance}`
+    : `    - ${id}${provenance}`;
 }
 
 /**

package/templates/hooks/knowledge-hint-narrow.cjs

@@ -91,6 +91,9 @@ const { readJsonState, writeJsonState } = require("./lib/state-store.cjs");
 // and corrupt a line. Route every shared-file append through the advisory-lock
 // primitive (drop-on-contention, best-effort — matches injection-log).
 const { appendLockedLine } = require("./lib/injection-log.cjs");
+// lifecycle-refactor W1-T2: client discriminator for the hook_surface_emitted
+// event (schema requires the `client` enum). Mirrors the broad hook's import.
+const { detectClient } = require("./lib/client-adapter.cjs");
 // v2.1.0-rc.1 P4 (F4/S63): hook-side reader for the CLI pre-generated
 // resolved-bindings snapshot. Store-aware hint surfaces the write-target store
 // for the edited file WITHOUT re-resolving or walking store trees. Best-effort.
@@ -1169,7 +1172,15 @@ function formatEntryLine(entry, maxLen) {
   const maturity = entry.maturity || "unknown";
   const summary = truncateSummary(entry.summary, maxLen);
   const tail = summary.length > 0 ? ` ${summary}` : "";
-  return `  [${id}] (${type}/${maturity})${tail}`;
+  // lifecycle-refactor W3-T2 (§7 图谱消费 / §5 hook 沿 related 二阶召回): mark entries
+  // pulled in by a surfaced entry's one-hop `related` graph edge with their source
+  // provenance. Omitted for ordinarily-ranked entries — no fake graph annotation
+  // is ever synthesized (graph-empty honesty).
+  const provenance =
+    typeof entry.related_to === "string" && entry.related_to.length > 0
+      ? ` (related-to-${entry.related_to})`
+      : "";
+  return `  [${id}] (${type}/${maturity})${tail}${provenance}`;
 }
 
 function readSummaryMaxLen(projectRoot) {
@@ -1516,6 +1527,48 @@ function main(env, stdio) {
       err.write(`${line}\n`);
     }
 
+    // lifecycle-refactor W1-T2: hook_surface_emitted — record WHICH narrow-scoped
+    // stable_ids this PreToolUse fire surfaced into the edit, so doctor can join
+    // surfaced→edited (this is the join's LEFT half; the edit_intent_checked event
+    // appended above supplies the edited path / RIGHT half, keyed on the same
+    // real payload session_id). Fires only after all gates passed and lines were
+    // rendered (so it tracks genuinely-surfaced hints, never bloat). Best-effort,
+    // never blocks the edit (KT-DEC-0007); the schema's `client` is a required
+    // enum, so skip when the client is undetectable rather than emit an invalid
+    // row. Mirrors the broad SessionStart emit (knowledge-hint-broad.cjs).
+    try {
+      const surfaceClient = detectClient();
+      const fabricDir = join(cwd, FABRIC_DIR_REL);
+      if (surfaceClient !== undefined && existsSync(fabricDir)) {
+        const renderedIds = resolvedEntries
+          .map((e) => (e && typeof e.id === "string" ? e.id : null))
+          .filter((x) => x !== null);
+        const realSessionId =
+          payload &&
+          typeof payload === "object" &&
+          typeof payload.session_id === "string" &&
+          payload.session_id.length > 0
+            ? payload.session_id
+            : null;
+        const surfaceEvent = {
+          kind: "fabric-event",
+          id: `event:${randomUUID()}`,
+          ts: nowMs,
+          schema_version: 1,
+          ...(realSessionId ? { session_id: realSessionId } : {}),
+          event_type: "hook_surface_emitted",
+          hook_name: "knowledge-hint-narrow",
+          client: surfaceClient,
+          target_channel: "stderr",
+          rendered_ids: renderedIds,
+          delivery_status: "delivered",
+        };
+        appendLockedLine(join(fabricDir, EVENTS_LEDGER_FILE), JSON.stringify(surfaceEvent) + "\n");
+      }
+    } catch {
+      // best-effort telemetry — never block the edit
+    }
+
     // v2.0.0-rc.33 W2-6 (P0-7): stdout JSON envelope. When
     // hint_reminder_to_context is true (default), serialize the same banner
     // body as Claude Code's PreToolUse hookSpecificOutput shape so the model