@fenglimg/fabric-shared 2.3.0-rc.8 → 2.3.0

package/dist/{chunk-CVNJCAC7.js → chunk-5M3HB554.js}

@@ -49,16 +49,24 @@ var _knowledgeTypeEnum = z3.enum(["models", "decisions", "guidelines", "pitfalls
 var _maturityEnum = z3.enum(["draft", "verified", "proven"]);
 var _ruleDescriptionSchema = z3.object({
   summary: z3.string(),
-  intent_clues: z3.array(z3.string()),
+  // TASK-005 wire thinning: intent_clues dropped from recall wire (0 hook
+  // consumers grep-verified). Selection signal is summary + must_read_if
+  // (when distinct) + knowledge_type; intent_clues is preserved in the on-disk
+  // .md frontmatter (KB source-of-truth) and reachable via read_path.
+  intent_clues: z3.array(z3.string()).optional(),
   // wire-slim (payload): fab_recall projects a LEAN description (summary +
-  // must_read_if + intent_clues + knowledge_type — the selection signal), leaving
-  // tech_stack/impact to be Read on demand via read_path (KT-DEC-0026 lean
+  // must_read_if + knowledge_type — the selection signal), leaving tech_stack/
+  // impact/intent_clues to be Read on demand via read_path (KT-DEC-0026 lean
   // contract at the field level). So they are optional on the wire. plan-context
-  // still returns them in full — zod keeps optional-present values, only ABSENT is
-  // now allowed, so no plan-context consumer regresses.
+  // still returns them in full — zod keeps optional-present values, only ABSENT
+  // is now allowed, so no plan-context consumer regresses.
   tech_stack: z3.array(z3.string()).optional(),
   impact: z3.array(z3.string()).optional(),
-  must_read_if: z3.string(),
+  // TASK-002 wire dedup: omitted when identical to `summary` (~40% of KB entries
+  // — knowledge-meta-builder.ts:212/:248 `?? summary` fallback). Consumers may
+  // fall back to `summary` when absent. KB source-of-truth (the .md frontmatter)
+  // stays unchanged; this optionality is a WIRE-only projection.
+  must_read_if: z3.string().optional(),
   // v2.0: optional knowledge-entry fields. Absent for v1.x rules; present for
   // entries that declare frontmatter `id/type/maturity`. W4/Track1: the redundant
   // `knowledge_layer` field was removed — a candidate's layer is derived from its
@@ -310,28 +318,40 @@ var recallInputSchema = z3.object({
   // W1-3 / KT-DEC-0031: graph expansion (surface related read paths, no body).
   include_related: z3.boolean().optional().describe(
     "When true, also surface the one-hop `related` graph neighbours (of the surfaced entries) that are present in the candidate set \u2014 their descriptions and read paths, NOT their bodies."
+  ),
+  // TASK-006 (KT-PIT-0036 observability opt-in): score_breakdown carries the
+  // numbers-only signal decomposition (bm25/vector/salience/recency/locality/
+  // proximity/credibility → final). Emitted per-entry ONLY when this flag is
+  // true — the debug/tuning surface. Steady-state recall omits it to stay lean
+  // (~4.8KB saved on a 24-entry sample). final===score invariant still enforced
+  // at the plan-context service layer (candidate_scores Map) regardless.
+  include_score_breakdown: z3.boolean().optional().describe(
+    "When true, populate `entry.score_breakdown` (numbers-only signal decomposition \u2014 bm25/vector/salience/recency/locality/proximity/credibility \u2192 final). Off by default for wire efficiency. Enable when debugging ranking or tuning scoring weights."
   )
 });
+var _recallEntryDescriptionSchema = z3.object({
+  summary: z3.string(),
+  // TASK-002: omitted when identical to summary (~40% dedup).
+  must_read_if: z3.string().optional(),
+  // Semantic-preservation (PLN-002 F1 restored): knowledge-hint-narrow.cjs
+  // consumes this for the "⚠️ 后果" narrow-hint line.
+  impact: z3.array(z3.string()).optional(),
+  // Semantic-preservation (PLN-002): cite-contract-reminder.cjs consumes it.
+  knowledge_type: _knowledgeTypeEnum.optional()
+});
 var _recallEntrySchema = z3.object({
   stable_id: z3.string(),
-  // 1-based relevance rank (entries are returned best-first). The surfaced
-  // ranking signal — entries are already sorted, rank makes the order explicit.
-  rank: z3.number().int().positive(),
-  // The DESCRIPTION (summary / intent_clues / must_read_if / related ...). No body.
-  description: _ruleDescriptionSchema,
+  // The projected DESCRIPTION (recall-specific slim contract, not the shared
+  // frontmatter shape). Codex review F6: dedicated schema locks the wire contract.
+  description: _recallEntryDescriptionSchema,
   // on-disk knowledge file to Read for the full body. Omitted when the entry has
   // no resolvable file (description-only discovery) or was scoped out by `ids`.
   read_path: z3.string().optional(),
   // originating store alias (omitted for unqualified / single-store entries).
-  store: z3.object({ alias: z3.string() }).optional(),
+  store_alias: z3.string().optional(),
   // true when this entry's body is ALSO injected at SessionStart (broad
   // model/guideline "ALWAYS-ACTIVE") — skip the Read, it is already in context.
   body_in_context: z3.boolean().optional(),
-  // P1 recall-observability: the fused relevance score this entry scored during
-  // the plan-context sort (was computed internally but dropped before this wave).
-  // Optional + additive — backward-compatible. MUST be declared here or zod
-  // .strip() silently drops it at the MCP boundary (KT-PIT-0005).
-  score: z3.number().optional(),
   // P1 recall-observability: numbers-only decomposition of `score` into its
   // weighted signal contributions. NEVER carries body/description text — preserves
   // the lean read_path contract (KT-DEC-0019 / KT-GLD-0005). bm25_rank/vector_rank
@@ -355,25 +375,24 @@ var _recallEntrySchema = z3.object({
   }).optional()
 });
 var recallOutputSchema = z3.object({
+  // Retained: client hook cache key (packages/cli/.claude/hooks/knowledge-hint-narrow.cjs)
   revision_hash: z3.string(),
-  stale: z3.boolean(),
   // ux-w2-4: single unified entry list (was candidates[] + paths[] + per-path
   // requirement-profile entries[]). Each item carries description + read_path +
   // rank + body_in_context, so the agent never joins two arrays on stable_id.
   entries: z3.array(_recallEntrySchema),
-  // v2.2 payload de-dup: single top-level echo of the caller's `intent`.
-  // Omitted when no intent.
-  intent: z3.string().optional(),
   // K6 (W3-K): structured list of lower-ranked candidates dropped by the
-  // retrieval pipeline, each tagged with WHY (`retrieval_budget` = top_k cap +
-  // ratio-to-top floor; `payload_budget` = MCP payload-byte trim). Present (and
-  // non-empty) ONLY when truncation fired — keeps the steady-state wire shape
-  // unchanged while signalling which entries exist ("narrow your intent"), now
-  // with a controlled reason instead of a bare count. Reuses the archive-scan
-  // {key,reason} omission convention (_recallDropReasonSchema, keyed on id).
-  dropped: z3.array(z3.object({ id: z3.string(), reason: _recallDropReasonSchema })).optional(),
-  preflight_diagnostics: z3.array(_preflightDiagnosticSchema),
+  // retrieval pipeline. dropped_ids preserves per-id transparency (KT-DEC-0028);
+  // dropped_reasons hoists the reason to a top-level count map (68/68 same-reason
+  // observation from ANL-002). Present ONLY when truncation fired.
+  dropped_ids: z3.array(z3.string()).optional(),
+  dropped_reasons: z3.object({
+    retrieval_budget: z3.number().int().nonnegative().optional(),
+    payload_budget: z3.number().int().nonnegative().optional()
+  }).optional(),
+  preflight_diagnostics: z3.array(_preflightDiagnosticSchema).optional(),
   warnings: z3.array(structuredWarningSchema).optional(),
+  // Auto-heal banner pair (consumed by knowledge-hint-broad.cjs:711-729).
   auto_healed: z3.boolean().optional(),
   previous_revision_hash: z3.string().optional(),
   // v2.0.0-rc.37 NEW-24: parallel to planContextOutputSchema.redirects — stale
@@ -384,9 +403,6 @@ var recallOutputSchema = z3.object({
   // (appended id → surfaced source id). Present only when include_related
   // appended an in-corpus neighbour. Omitted on the steady-state path.
   related_appended: z3.record(z3.string()).optional(),
-  // v2.2 MC1-recall-pack: standing behavioral directive (cite-before-edit) +
-  // dynamic discovery hints, so the one-call recall is self-describing.
-  directive: z3.string(),
   next_steps: z3.array(z3.string()).optional()
 });
 var recallAnnotations = {
@@ -681,7 +697,30 @@ var _fabReviewModifyChangesSchema = z3.object({
   // edges via fab_recall and sends the merged set. Absent this field the modify
   // path silently dropped `related` via zod .strip() (KT-PIT-0005 recurrence),
   // leaving the only programmatic related-write path non-functional.
-  related: z3.array(z3.string()).optional()
+  related: z3.array(z3.string()).optional(),
+  // rc.9 (2026-07-06): discovery-signal scalar patches — must_read_if triggers
+  // Reference-type entry surfacing; intent_clues drives the AI's "should I Read
+  // the body?" judgment; impact enumerates consequence prose surfaced in the
+  // BM25F body slot. Before rc.9 these three fields were undeclared here, so
+  // fab_review modify silently .strip()'d them (KT-PIT-0005 recurrence) and the
+  // only path to fix a bad-shape must_read_if / missing intent_clues was direct
+  // Edit — bypassing the skill audit trail. All three are REPLACE semantics
+  // (mirror tags/related). must_read_if is a scalar string; intent_clues +
+  // impact are flow-arrays.
+  must_read_if: z3.string().optional(),
+  intent_clues: z3.array(z3.string()).optional(),
+  impact: z3.array(z3.string()).optional(),
+  // ISS-20260711-180: propose writes these; without them here zod .strip()
+  // silently drops modify patches (KT-PIT-0005 recurrence).
+  tech_stack: z3.array(z3.string()).optional(),
+  evidence_paths: z3.array(z3.string()).optional(),
+  onboard_slot: z3.enum([
+    "tech-stack-decision",
+    "architecture-pattern",
+    "code-style-tone",
+    "build-system-idiom",
+    "domain-vocabulary"
+  ]).optional()
 });
 var FabReviewInputSchema = z3.discriminatedUnion("action", [
   z3.object({
@@ -716,11 +755,45 @@ var FabReviewInputSchema = z3.discriminatedUnion("action", [
       layer: z3.enum(["team", "personal"])
     })
   }),
+  // v2.3 batch content-modify: array-native flush for the fabric-review maintain
+  // loop. Each item is an INDEPENDENT content edit — unlike approve/reject/defer
+  // (which share one reason/until over pending_paths[]), modify needs its OWN
+  // changes per entry, so the shape is items[] not paths[]. Layer is stripped
+  // per item (content-only; layer-flips stay on the single interactive
+  // modify-layer path). Per-item failure is isolated: a bad item reports
+  // {ok:false, error} in modified[] without aborting its siblings.
+  z3.object({
+    action: z3.literal("modify-content-batch"),
+    items: z3.array(
+      z3.object({
+        pending_path: z3.string().min(1),
+        changes: _fabReviewModifyChangesSchema
+      })
+    ).min(1)
+  }),
   z3.object({
     action: z3.literal("defer"),
     pending_paths: z3.array(z3.string()).min(1),
     until: z3.string().datetime().optional(),
     reason: z3.string().optional()
+  }),
+  // retire (W3-C: fabric-review retire-mode landing surface). Semantically
+  // deprecates one or more CANONICAL knowledge entries so they stop surfacing in
+  // recall candidates / broad SessionStart indexes — WITHOUT deleting the file
+  // (red line: deprecate-over-delete). The service writes `deprecated: true`
+  // (+ `superseded_by: <id>` when the entry is replaced) into the entry's
+  // frontmatter via the same in-place merge path modify uses; body + stable_id
+  // are preserved so the "当时为什么这么决策" rationale stays inspectable.
+  z3.object({
+    action: z3.literal("retire"),
+    // Canonical entry paths (store-absolute, from fab_pending list/search).
+    pending_paths: z3.array(z3.string()).min(1),
+    // Optional stable_id of the entry that supersedes these (bare `KT-DEC-0001`
+    // or store-qualified `alias:KT-DEC-0001`). Written as `superseded_by`
+    // frontmatter so the supersession chain is recoverable.
+    superseded_by: z3.string().optional(),
+    // Optional human reason recorded on the knowledge_modified ledger event.
+    reason: z3.string().optional()
   })
 ]);
 var FabPendingInputSchema = z3.discriminatedUnion("action", [
@@ -746,11 +819,20 @@ var FabPendingInputShape = {
   )
 };
 var FabReviewInputShape = {
-  action: z3.enum(["approve", "reject", "modify", "modify-content", "modify-layer", "defer"]).describe(
-    "Action selector. Discriminates the per-action fields below; required. modify-content edits scalars (no layer); modify-layer is the layer-flip path (changes.layer required); modify is the legacy combined alias. (list/search moved to the read-only fab_pending tool.)"
+  action: z3.enum([
+    "approve",
+    "reject",
+    "modify",
+    "modify-content",
+    "modify-layer",
+    "modify-content-batch",
+    "defer",
+    "retire"
+  ]).describe(
+    "Action selector. Discriminates the per-action fields below; required. modify-content edits scalars (no layer); modify-layer is the layer-flip path (changes.layer required); modify is the legacy combined alias; modify-content-batch flushes an array of independent content edits (items[]) in one call; retire marks canonical entries deprecated (deprecate-over-delete) so they stop surfacing. (list/search moved to the read-only fab_pending tool.)"
   ),
   pending_paths: z3.array(z3.string()).min(1).optional().describe(
-    "Workspace-relative pending entry paths. Required when action=approve|reject|defer (non-empty array)."
+    "Workspace-relative pending entry paths (or canonical entry paths for action=retire). Required when action=approve|reject|defer|retire (non-empty array)."
   ),
   pending_path: z3.string().min(1).optional().describe(
     "Workspace-relative pending OR canonical entry path. Required when action=modify."
@@ -761,8 +843,19 @@ var FabReviewInputShape = {
   changes: _fabReviewModifyChangesSchema.optional().describe(
     "Frontmatter scalar patches (title/summary/layer/maturity/tags/relevance_*/semantic_scope/related). Required when action=modify. semantic_scope re-scopes the entry's resolution coordinate in place (e.g. team \u2192 project:<id>) without moving stores; personal-root coordinates are rejected (use modify-layer)."
   ),
+  items: z3.array(
+    z3.object({
+      pending_path: z3.string().min(1),
+      changes: _fabReviewModifyChangesSchema
+    })
+  ).min(1).optional().describe(
+    "Batch of independent content edits \u2014 required (non-empty) when action=modify-content-batch. Each item {pending_path, changes} is applied content-only (layer stripped); per-item failures surface in modified[] without aborting siblings."
+  ),
   until: z3.string().datetime().optional().describe(
     "ISO-8601 datetime upper bound for the deferral. Optional; used only when action=defer."
+  ),
+  superseded_by: z3.string().optional().describe(
+    "Stable_id (bare or store-qualified) of the entry that supersedes the retired one, written as `superseded_by` frontmatter. Optional; used only when action=retire."
   )
 };
 var _fabReviewListItemSchema = z3.object({
@@ -781,6 +874,8 @@ var _fabReviewListItemSchema = z3.object({
   tags: z3.array(z3.string()).optional(),
   title: z3.string().optional(),
   summary: z3.string().optional(),
+  // ISS-20260712-011: triage UI needs proposed_reason without a second Read.
+  proposed_reason: z3.string().optional(),
   // Store-only cutover: origin reflects the resolved store audience where the
   // pending file lives; layer reflects the declared classification that will
   // drive approval semantics.
@@ -820,10 +915,16 @@ var _fabReviewSearchItemSchema = z3.object({
   // hits in the same array.
   stable_id: z3.string().optional()
 });
+var _fabReviewFailedItemSchema = z3.object({
+  pending_path: z3.string(),
+  reason: z3.string()
+});
 var FabReviewOutputSchema = z3.discriminatedUnion("action", [
   z3.object({
     action: z3.literal("approve"),
     approved: z3.array(z3.object({ pending_path: z3.string(), stable_id: z3.string() })),
+    // ISS-20260712-012: partial-failure surface so empty approved[] is not false-success.
+    failed: z3.array(_fabReviewFailedItemSchema).optional(),
     warnings: z3.array(structuredWarningSchema).optional()
   }),
   z3.object({
@@ -839,10 +940,41 @@ var FabReviewOutputSchema = z3.discriminatedUnion("action", [
     new_stable_id: z3.string().optional(),
     warnings: z3.array(structuredWarningSchema).optional()
   }),
+  // v2.3 batch content-modify result: per-item {pending_path, ok, error?}. No
+  // prior/new_stable_id — content edits strip layer, so no id reallocation can
+  // occur. ok=false items carry the failure message; siblings still applied
+  // (partial failure is reported per-item, never thrown for the whole batch).
+  z3.object({
+    action: z3.literal("modify-content-batch"),
+    modified: z3.array(
+      z3.object({
+        pending_path: z3.string(),
+        ok: z3.boolean(),
+        error: z3.string().optional()
+      })
+    ),
+    warnings: z3.array(structuredWarningSchema).optional()
+  }),
   z3.object({
     action: z3.literal("defer"),
     deferred: z3.array(z3.string()),
     warnings: z3.array(structuredWarningSchema).optional()
+  }),
+  z3.object({
+    action: z3.literal("retire"),
+    // Each retired canonical entry: its echoed path + (when the frontmatter
+    // carried one) its stable_id, plus the superseded_by id when supplied. The
+    // file is NOT deleted — only marked `deprecated: true` in place.
+    retired: z3.array(
+      z3.object({
+        path: z3.string(),
+        stable_id: z3.string().optional(),
+        superseded_by: z3.string().optional()
+      })
+    ),
+    // ISS-20260712-012: partial-failure surface for skipped/unresolvable paths.
+    failed: z3.array(_fabReviewFailedItemSchema).optional(),
+    warnings: z3.array(structuredWarningSchema).optional()
   })
 ]);
 var FabPendingOutputSchema = z3.discriminatedUnion("action", [
@@ -867,12 +999,15 @@ var FabPendingOutputShape = {
   warnings: z3.array(structuredWarningSchema).optional()
 };
 var FabReviewOutputShape = {
-  action: z3.enum(["approve", "reject", "modify", "defer"]).describe(
+  action: z3.enum(["approve", "reject", "modify", "modify-content-batch", "defer", "retire"]).describe(
     "Echoes the input action; clients can switch on it for per-variant fields below. (list/search results moved to the read-only fab_pending tool.)"
   ),
   approved: z3.array(z3.object({ pending_path: z3.string(), stable_id: z3.string() })).optional().describe(
     "Allocated stable ids paired with their original pending paths. Present when action=approve."
   ),
+  failed: z3.array(z3.object({ pending_path: z3.string(), reason: z3.string() })).optional().describe(
+    "Paths that did not apply (approve/retire). Present when any path was skipped or failed."
+  ),
   rejected: z3.array(z3.string()).optional().describe(
     "Pending paths that were rejected (files retained on disk; doctor owns vacuum). Present when action=reject."
   ),
@@ -885,9 +1020,27 @@ var FabReviewOutputShape = {
   new_stable_id: z3.string().optional().describe(
     "New stable id after reallocation. Present when action=modify AND a layer-flip reallocated the id."
   ),
+  modified: z3.array(
+    z3.object({
+      pending_path: z3.string(),
+      ok: z3.boolean(),
+      error: z3.string().optional()
+    })
+  ).optional().describe(
+    "Per-item results for action=modify-content-batch: {pending_path, ok, error?}. ok=false items carry the error; siblings still applied."
+  ),
   deferred: z3.array(z3.string()).optional().describe(
     "Pending paths that were deferred (files retained on disk). Present when action=defer."
   ),
+  retired: z3.array(
+    z3.object({
+      path: z3.string(),
+      stable_id: z3.string().optional(),
+      superseded_by: z3.string().optional()
+    })
+  ).optional().describe(
+    "Canonical entries marked deprecated in place (files retained \u2014 deprecate-over-delete). Present when action=retire."
+  ),
   // v2.0.0-rc.23 TASK-009 (d): optional warnings surface for the first-reconcile
   // gate (`meta_stale` / `reconcile_failed`). Absent on the steady-state path.
   warnings: z3.array(structuredWarningSchema).optional()

package/dist/{chunk-ASS2KBB7.js → chunk-OX6DWUK4.js}

@@ -1,3 +1,8 @@
+import {
+  atomicWriteJson,
+  withFileLock
+} from "./chunk-C7WZPYZE.js";
+
 // src/i18n/normalize-locale.ts
 function normalizeLocale(raw) {
   if (typeof raw !== "string") {
@@ -189,7 +194,8 @@ var globalConfigSchema = z.object({
 }).passthrough();
 
 // src/store/global-config-io.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { mkdir } from "fs/promises";
 import { homedir } from "os";
 import { join } from "path";
 function isTestRuntime() {
@@ -210,6 +216,9 @@ function resolveGlobalRoot() {
 function globalConfigPath(globalRoot = resolveGlobalRoot()) {
   return join(globalRoot, "fabric-global.json");
 }
+function globalConfigLockPath(globalRoot) {
+  return `${globalConfigPath(globalRoot)}.lock`;
+}
 function loadGlobalConfig(globalRoot = resolveGlobalRoot()) {
   const path = globalConfigPath(globalRoot);
   if (!existsSync(path)) {
@@ -217,11 +226,30 @@ function loadGlobalConfig(globalRoot = resolveGlobalRoot()) {
   }
   return globalConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
 }
+async function saveGlobalConfigAsync(config, globalRoot = resolveGlobalRoot()) {
+  const validated = globalConfigSchema.parse(config);
+  await mkdir(globalRoot, { recursive: true });
+  const path = globalConfigPath(globalRoot);
+  await withFileLock(globalConfigLockPath(globalRoot), async () => {
+    await atomicWriteJson(path, validated, { indent: 2 });
+  });
+}
 function saveGlobalConfig(config, globalRoot = resolveGlobalRoot()) {
   const validated = globalConfigSchema.parse(config);
   mkdirSync(globalRoot, { recursive: true });
-  writeFileSync(globalConfigPath(globalRoot), `${JSON.stringify(validated, null, 2)}
+  const path = globalConfigPath(globalRoot);
+  const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(tmpPath, `${JSON.stringify(validated, null, 2)}
 `, "utf8");
+    renameSync(tmpPath, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+    }
+    throw error;
+  }
 }
 
 // src/i18n/resolve-global-locale.ts
@@ -269,6 +297,7 @@ export {
   resolveGlobalRoot,
   globalConfigPath,
   loadGlobalConfig,
+  saveGlobalConfigAsync,
   saveGlobalConfig,
   resolveGlobalLocale
 };

package/dist/{chunk-KFFBQRL5.js → chunk-V7IUN5U2.js}

@@ -1,6 +1,6 @@
 import {
   resolveGlobalLocale
-} from "./chunk-ASS2KBB7.js";
+} from "./chunk-OX6DWUK4.js";
 
 // src/templates/bootstrap-canonical.ts
 var BOOTSTRAP_MARKER_BEGIN = "<!-- fabric:bootstrap:begin -->";
@@ -36,8 +36,9 @@ var BOOTSTRAP_CANONICAL_ZH = `# Fabric Bootstrap
 \u5B8C\u6574 maintainer \u7248\u89C1 \`docs/USER-QUICKSTART.md\`\u3002
 
 ## \u884C\u4E3A\u89C4\u5219
-- **\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\u524D**:\u5148 \`fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])\` \u2014\u2014 \u4E00\u6B21\u8C03\u7528\u62FF\u56DE\u76F8\u5173 KB \u7684\u63CF\u8FF0 + \u539F\u751F\u8BFB\u53D6\u8DEF\u5F84(\`entries[].read_path\`)\u3002\`fab_recall\` \u4E0D\u518D\u6295\u9012\u6B63\u6587;\u9700\u8981\u67D0\u6761\u6B63\u6587\u65F6\u76F4\u63A5\u5BF9\u5176 \`entries[].read_path\` \u505A\u539F\u751F Read(\`Read <store>/knowledge/<type>/<id>--*.md\`),\u8FD9\u4F1A\u88AB PostToolUse hook \u8BB0\u4E3A \`knowledge_body_read\`\u3002lean \u9ED8\u8BA4:\u63CF\u8FF0+\u7D22\u5F15\u5DF2\u591F\u53D1\u73B0\u6761\u76EE,\u6B63\u6587\u6309\u9700\u8BFB\u4E00\u6B21,\u4E0D\u6BCF\u8F6E\u91CD\u704C(KT-GLD-0005)\u3002
-- **\`.fabric/agents.meta.json\` \u4E25\u7981\u624B\u52A8\u7F16\u8F91**;engine \u4F1A\u81EA\u52A8\u540C\u6B65\u6D3E\u751F\u72B6\u6001,\u663E\u5F0F reconcile \u8DD1 \`fabric doctor --fix\`\u3002
+- **Pre-action gating (\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\u524D MUST)**: \u2460 \u5148 \`fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>], session_id=<client-session-id>)\`\uFF1B\u2461 \u6309\u9700\u539F\u751F Read \u547D\u4E2D\u7684 \`entries[].read_path\` \u6B63\u6587(PostToolUse \u8BB0\u4E3A \`knowledge_body_read\`)\uFF1B\u2462 \u8DF3\u8FC7\u4E0D\u9002\u7528\u547D\u4E2D\u65F6\u8BF4 \`dismissed: <id> (<reason>)\`\u3002\`fab_recall\` \u4E0D\u518D\u6295\u9012\u6B63\u6587;lean \u9ED8\u8BA4\u63CF\u8FF0+\u7D22\u5F15\u5DF2\u591F\u53D1\u73B0\u6761\u76EE(KT-GLD-0005)\u3002PreToolUse \u4EC5\u8F6F nudge,\u5B88 KT-DEC-0007(\u975E permanent gate / \u65E0 \`decision:block\`)\u3002
+- **Archive-as-truth**: \u8FDB canonical **\u552F\u4E00\u8DEF\u5F84** \u662F \`fab_propose\` \u2192 pending \u2192 \`fabric-review\`/\`fab_review\` \u5BA1\u6279\uFF1B\u7981\u6B62\u628A chat/log \u81EA\u52A8 promote \u8FDB canonical\u3002
+- **\`.fabric/agents.meta.json\` \u4E25\u7981\u624B\u52A8\u7F16\u8F91**\uFF08co-location index \u5DF2\u9000\u5F79;\u77E5\u8BC6\u5728 mounted stores\uFF09\u3002\u5F02\u5E38\u65F6\u8DD1 \`fabric doctor\` / \`fabric doctor --fix\` \u81EA\u6108\u53EF\u4FEE\u590D\u9879\u3002
 
 ## \u77E5\u8BC6\u5E93(KB)
 - **Discovery**:SessionStart hook \u5217 broad-scoped \u6761\u76EE(\u6761\u76EE\u6309 \`semantic_scope\` \u5206\u4E09\u5C42:\`team\` \u56E2\u961F\u901A\u7528 / \`project:<id>\` \u672C\u9879\u76EE\u4E13\u5C5E(\u4EC5\u5728\u7ED1\u5B9A\u8BE5\u9879\u76EE\u7684\u4ED3\u5E93\u6D6E\u73B0)/ \`personal\` \u4E2A\u4EBA \`KP-*\`,\u4E09\u8005\u5F15\u7528\u65B9\u5F0F\u76F8\u540C);edit \u6587\u4EF6\u65F6 PreToolUse hook \u53EF\u80FD\u89E6\u53D1 narrow hint\u3002
@@ -46,7 +47,7 @@ var BOOTSTRAP_CANONICAL_ZH = `# Fabric Bootstrap
 - **session_id**: \u8C03\u7528 \`fab_recall\` \u65F6, \u52A1\u5FC5\u628A\u5F53\u524D client session id \u4F5C\u4E3A \`session_id\` \u53C2\u6570\u4F20\u5165(Claude Code \u7684 session id \u5728 stdin payload \u4E2D, Codex \u7684\u5BF9\u5E94 identifier \u540C\u7406)\u3002\u8FD9\u80FD\u8BA9 \`fabric doctor --archive-history\` \u4E0E \`fabric-hint.cjs\` Stop hook \u51C6\u786E\u8BC6\u522B\u8DE8\u4F1A\u8BDD debt \u72B6\u6001\u3002
 - **Skills (4)**:\u5199\u6D41\u7A0B \`fabric-archive\`(\u542B source mode \u51B7\u542F\u52A8\u4ECE git/docs \u56DE\u704C)/ \`fabric-review\`(\u542B retire \u8BED\u4E49\u6DD8\u6C70 + relate \u5173\u8054\u5EFA\u8FB9 \u5B50\u6D41\u7A0B);store \u8FD0\u7EF4 \`fabric-store\` / \`fabric-sync\`\u3002
 - **Language**:\u6E32\u67D3\u6309 \`~/.fabric/fabric-global.json\` \u7684 \`language\` \u5B57\u6BB5(machine-wide tone)\u3002
-- **Archive cadence nudge** (rc.36): \u6BCF\u5B8C\u6210\u4E00\u6279 Edit(\u9ED8\u8BA4 ~20 \u6B21, \u4E0E Stop hook \u9608\u503C config \`archive_edit_threshold\` \u4E00\u81F4)/ \u663E\u8457 decision \u540E,\u5728\u5408\u9002\u56DE\u5408\u4E3B\u52A8 propose \u8C03 \`fabric-archive\` skill \u2014 archive \u6CA1\u5EFA\u7ACB\u9891\u7387\u4F1A\u8BA9 KB \u6162\u901F\u6B7B\u6389\u3002
+- **Archive cadence nudge** (rc.36 / finish\u2192archive): \u663E\u8457 decision \u6536\u53E3\u6216\u4E00\u6279 Edit \u8FBE\u5230 config \`archive_edit_threshold\`(\u9ED8\u8BA4 20) \u540E,\u5728\u5408\u9002\u56DE\u5408\u8F7B\u91CF\u81EA\u8C03 \`fabric-archive\`(\u540C turn \u6700\u591A 1 \u6B21;\u975E task engine / \u975E Stop-hook flood)\u3002Stop hook \u4EC5 soft threshold nudge,\u5B88 KT-DEC-0007 \u2014 archive \u6CA1\u5EFA\u7ACB\u9891\u7387\u4F1A\u8BA9 KB \u6162\u901F\u6B7B\u6389\u3002
 - **Review backlog nudge** (rc.36): \u9700\u8981\u5224\u65AD pending backlog \u65F6\u8D70 \`fab_pending action="list"\` \u6216 \`fabric-review\` \u8FD4\u56DE\u7684 \`pending_path\`;\u4E0D\u8981 glob \u9879\u76EE\u672C\u5730 \`.fabric/knowledge/pending\`\u3002\u5F53\u53EF\u89C1 pending \u7D2F\u79EF >10 \u6761\u65F6,\u5728\u5408\u9002\u56DE\u5408\u4E3B\u52A8 propose \u8C03 \`fabric-review\` skill \u6279\u91CF\u5BA1,\u907F\u514D draft \u5361\u6B7B\u3002
 
 ## Self-archive policy (v2.2 C1: \u7CBE\u7B80\u8BF4\u660E\u4E66)
@@ -95,8 +96,9 @@ As a dev you only need to: run \`fabric install\` once per repo, use \`fabric st
 See \`docs/USER-QUICKSTART.md\` for the full maintainer version.
 
 ## Behavior Rules
-- **Before modifying any file**: first \`fab_recall(paths=[<file-being-edited>])\` \u2014\u2014 a single call returns the relevant KB descriptions + native read paths (\`entries[].read_path\`). \`fab_recall\` no longer delivers bodies; when you need a body, do a native Read of its \`entries[].read_path\` (\`Read <store>/knowledge/<type>/<id>--*.md\`), which the PostToolUse hook records as \`knowledge_body_read\`. Lean default: descriptions + index already suffice to discover entries; read a body once on demand, don't re-inject it every turn (KT-GLD-0005).
-- **Never hand-edit \`.fabric/agents.meta.json\`**; the engine syncs derived state automatically \u2014 run \`fabric doctor --fix\` for an explicit reconcile.
+- **Pre-action gating (MUST before Edit/Write)**: (1) call \`fab_recall(paths=[<file-being-edited>], session_id=<client-session-id>)\`; (2) optionally native-Read selected \`entries[].read_path\` bodies (PostToolUse records \`knowledge_body_read\`); (3) when skipping a hit, say \`dismissed: <id> (<reason>)\`. \`fab_recall\` no longer delivers bodies; lean default is description+index discovery (KT-GLD-0005). PreToolUse is soft nudge only per KT-DEC-0007 (never permanent gate / no \`decision:block\`).
+- **Archive-as-truth**: the **only** path into canonical is \`fab_propose\` \u2192 pending \u2192 \`fabric-review\`/\`fab_review\` approve; never auto-promote chat/logs into canonical.
+- **Never hand-edit \`.fabric/agents.meta.json\`** (co-location index retired; knowledge lives in mounted stores). For anomalies run \`fabric doctor\` / \`fabric doctor --fix\` on fixable state.
 
 ## Knowledge Base (KB)
 - **Discovery**: the SessionStart hook lists broad-scoped entries (scoped by \`semantic_scope\` across three tiers: \`team\` team-wide / \`project:<id>\` this-project-only (surfaces only in repos bound to that project) / \`personal\` \`KP-*\`, all three referenced the same way); editing a file may trigger a narrow hint via the PreToolUse hook.
@@ -105,7 +107,7 @@ See \`docs/USER-QUICKSTART.md\` for the full maintainer version.
 - **session_id**: when calling \`fab_recall\`, always pass the current client session id as the \`session_id\` argument (Claude Code's session id is in the stdin payload; Codex's corresponding identifier likewise). This lets \`fabric doctor --archive-history\` and the \`fabric-hint.cjs\` Stop hook track cross-session debt accurately.
 - **Skills (4)**: write flow \`fabric-archive\` (with source-mode cold-start backfill from git/docs) / \`fabric-review\` (with retire-deprecation + relate-edge sub-flows); store ops \`fabric-store\` / \`fabric-sync\`.
 - **Language**: rendered per the \`language\` field in \`~/.fabric/fabric-global.json\` (machine-wide tone).
-- **Archive cadence nudge** (rc.36): after each batch of edits (default ~20, matching the Stop hook threshold config \`archive_edit_threshold\`) / a significant decision, proactively propose the \`fabric-archive\` skill at a suitable turn \u2014 without an archive cadence the KB slowly dies.
+- **Archive cadence nudge** (rc.36 / finish\u2192archive): after a significant decision lands or an edit batch reaches config \`archive_edit_threshold\` (default 20), lightly self-trigger \`fabric-archive\` at a suitable turn (max 1 per turn; not a task engine / not Stop-hook flood). Stop hook remains a soft threshold nudge per KT-DEC-0007 \u2014 without an archive cadence the KB slowly dies.
 - **Review backlog nudge** (rc.36): to judge the pending backlog, go through \`fab_pending action="list"\` or the \`pending_path\` returned by \`fabric-review\`; don't glob the project-local \`.fabric/knowledge/pending\`. When the visible pending count exceeds 10, proactively propose the \`fabric-review\` skill at a suitable turn to batch-review and avoid draft deadlock.
 
 ## Self-archive policy (v2.2 C1: lean spec)