@fenglimg/fabric-shared 2.1.0-rc.2 → 2.2.0-rc.3

package/dist/schemas/api-contracts.d.ts

@@ -104,6 +104,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             relevance_scope: z.ZodOptional<z.ZodEnum<["narrow", "broad"]>>;
             relevance_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         }, "strip", z.ZodTypeAny, {
             summary: string;
             intent_clues: string[];
@@ -120,6 +121,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         }, {
             summary: string;
             intent_clues: string[];
@@ -136,6 +138,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
         description: {
@@ -154,6 +157,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }, {
@@ -173,9 +177,11 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }>, "many">;
+    omitted_candidate_count: z.ZodOptional<z.ZodNumber>;
     preflight_diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<["missing_description", "empty_shell_suppressed"]>;
         severity: z.ZodLiteral<"warn">;
@@ -214,6 +220,7 @@ declare const planContextOutputSchema: z.ZodObject<{
     auto_healed: z.ZodOptional<z.ZodBoolean>;
     previous_revision_hash: z.ZodOptional<z.ZodString>;
     redirects: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    related_appended: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     entries: {
         path: string;
@@ -244,6 +251,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }[];
@@ -254,6 +262,7 @@ declare const planContextOutputSchema: z.ZodObject<{
         path?: string | undefined;
         stable_ids?: string[] | undefined;
     }[];
+    omitted_candidate_count?: number | undefined;
     warnings?: {
         code: string;
         file: string;
@@ -263,6 +272,7 @@ declare const planContextOutputSchema: z.ZodObject<{
     auto_healed?: boolean | undefined;
     previous_revision_hash?: string | undefined;
     redirects?: Record<string, string> | undefined;
+    related_appended?: Record<string, string> | undefined;
 }, {
     entries: {
         path: string;
@@ -293,6 +303,7 @@ declare const planContextOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }[];
@@ -303,6 +314,7 @@ declare const planContextOutputSchema: z.ZodObject<{
         path?: string | undefined;
         stable_ids?: string[] | undefined;
     }[];
+    omitted_candidate_count?: number | undefined;
     warnings?: {
         code: string;
         file: string;
@@ -312,6 +324,7 @@ declare const planContextOutputSchema: z.ZodObject<{
     auto_healed?: boolean | undefined;
     previous_revision_hash?: string | undefined;
     redirects?: Record<string, string> | undefined;
+    related_appended?: Record<string, string> | undefined;
 }>;
 declare const planContextAnnotations: {
     readonly readOnlyHint: true;
@@ -383,7 +396,7 @@ declare const planContextHintOutputSchema: z.ZodObject<{
 declare const knowledgeSectionsInputSchema: z.ZodObject<{
     selection_token: z.ZodString;
     ai_selected_stable_ids: z.ZodArray<z.ZodString, "many">;
-    ai_selection_reasons: z.ZodRecord<z.ZodString, z.ZodString>;
+    ai_selection_reasons: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
     correlation_id: z.ZodOptional<z.ZodString>;
     session_id: z.ZodOptional<z.ZodString>;
     client_hash: z.ZodOptional<z.ZodString>;
@@ -397,10 +410,10 @@ declare const knowledgeSectionsInputSchema: z.ZodObject<{
 }, {
     selection_token: string;
     ai_selected_stable_ids: string[];
-    ai_selection_reasons: Record<string, string>;
     client_hash?: string | undefined;
     correlation_id?: string | undefined;
     session_id?: string | undefined;
+    ai_selection_reasons?: Record<string, string> | undefined;
 }>;
 declare const knowledgeSectionsOutputSchema: z.ZodObject<{
     revision_hash: z.ZodString;
@@ -422,17 +435,17 @@ declare const knowledgeSectionsOutputSchema: z.ZodObject<{
         body: string;
     }>, "many">;
     diagnostics: z.ZodArray<z.ZodObject<{
-        code: z.ZodLiteral<"missing_knowledge_metadata">;
+        code: z.ZodEnum<["missing_knowledge_metadata", "unresolved_selected_id"]>;
         severity: z.ZodLiteral<"warn">;
         stable_id: z.ZodString;
         message: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
     }, {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
@@ -470,7 +483,7 @@ declare const knowledgeSectionsOutputSchema: z.ZodObject<{
         body: string;
     }[];
     diagnostics: {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
@@ -494,7 +507,7 @@ declare const knowledgeSectionsOutputSchema: z.ZodObject<{
         body: string;
     }[];
     diagnostics: {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
@@ -527,6 +540,7 @@ declare const recallInputSchema: z.ZodObject<{
     layer_filter: z.ZodOptional<z.ZodEnum<["team", "personal", "both"]>>;
     target_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    include_related: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     paths: string[];
     known_tech?: string[] | undefined;
@@ -538,6 +552,7 @@ declare const recallInputSchema: z.ZodObject<{
     layer_filter?: "personal" | "team" | "both" | undefined;
     target_paths?: string[] | undefined;
     ids?: string[] | undefined;
+    include_related?: boolean | undefined;
 }, {
     paths: string[];
     known_tech?: string[] | undefined;
@@ -549,6 +564,7 @@ declare const recallInputSchema: z.ZodObject<{
     layer_filter?: "personal" | "team" | "both" | undefined;
     target_paths?: string[] | undefined;
     ids?: string[] | undefined;
+    include_related?: boolean | undefined;
 }>;
 declare const recallOutputSchema: z.ZodObject<{
     revision_hash: z.ZodString;
@@ -607,6 +623,7 @@ declare const recallOutputSchema: z.ZodObject<{
             tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             relevance_scope: z.ZodOptional<z.ZodEnum<["narrow", "broad"]>>;
             relevance_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         }, "strip", z.ZodTypeAny, {
             summary: string;
             intent_clues: string[];
@@ -623,6 +640,7 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         }, {
             summary: string;
             intent_clues: string[];
@@ -639,6 +657,7 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
         description: {
@@ -657,6 +676,7 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }, {
@@ -676,9 +696,11 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }>, "many">;
+    omitted_candidate_count: z.ZodOptional<z.ZodNumber>;
     preflight_diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodEnum<["missing_description", "empty_shell_suppressed"]>;
         severity: z.ZodLiteral<"warn">;
@@ -703,30 +725,43 @@ declare const recallOutputSchema: z.ZodObject<{
         level: z.ZodEnum<["L0", "L1", "L2"]>;
         path: z.ZodString;
         body: z.ZodString;
+        store: z.ZodOptional<z.ZodObject<{
+            alias: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            alias: string;
+        }, {
+            alias: string;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         path: string;
         stable_id: string;
         level: "L0" | "L1" | "L2";
         body: string;
+        store?: {
+            alias: string;
+        } | undefined;
     }, {
         path: string;
         stable_id: string;
         level: "L0" | "L1" | "L2";
         body: string;
+        store?: {
+            alias: string;
+        } | undefined;
     }>, "many">;
     selected_stable_ids: z.ZodArray<z.ZodString, "many">;
     diagnostics: z.ZodArray<z.ZodObject<{
-        code: z.ZodLiteral<"missing_knowledge_metadata">;
+        code: z.ZodEnum<["missing_knowledge_metadata", "unresolved_selected_id"]>;
         severity: z.ZodLiteral<"warn">;
         stable_id: z.ZodString;
         message: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
     }, {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
@@ -750,6 +785,18 @@ declare const recallOutputSchema: z.ZodObject<{
     auto_healed: z.ZodOptional<z.ZodBoolean>;
     previous_revision_hash: z.ZodOptional<z.ZodString>;
     redirects: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    directive: z.ZodString;
+    next_steps: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    truncation: z.ZodOptional<z.ZodObject<{
+        omitted_candidate_count: z.ZodNumber;
+        returned_candidate_count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        omitted_candidate_count: number;
+        returned_candidate_count: number;
+    }, {
+        omitted_candidate_count: number;
+        returned_candidate_count: number;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     entries: {
         path: string;
@@ -780,6 +827,7 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }[];
@@ -796,13 +844,18 @@ declare const recallOutputSchema: z.ZodObject<{
         stable_id: string;
         level: "L0" | "L1" | "L2";
         body: string;
+        store?: {
+            alias: string;
+        } | undefined;
     }[];
     diagnostics: {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
     }[];
+    directive: string;
+    omitted_candidate_count?: number | undefined;
     warnings?: {
         code: string;
         file: string;
@@ -812,6 +865,11 @@ declare const recallOutputSchema: z.ZodObject<{
     auto_healed?: boolean | undefined;
     previous_revision_hash?: string | undefined;
     redirects?: Record<string, string> | undefined;
+    next_steps?: string[] | undefined;
+    truncation?: {
+        omitted_candidate_count: number;
+        returned_candidate_count: number;
+    } | undefined;
 }, {
     entries: {
         path: string;
@@ -842,6 +900,7 @@ declare const recallOutputSchema: z.ZodObject<{
             knowledge_layer?: "personal" | "team" | undefined;
             layer_reason?: string | undefined;
             tags?: string[] | undefined;
+            related?: string[] | undefined;
         };
         stable_id: string;
     }[];
@@ -858,13 +917,18 @@ declare const recallOutputSchema: z.ZodObject<{
         stable_id: string;
         level: "L0" | "L1" | "L2";
         body: string;
+        store?: {
+            alias: string;
+        } | undefined;
     }[];
     diagnostics: {
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         message: string;
         stable_id: string;
         severity: "warn";
     }[];
+    directive: string;
+    omitted_candidate_count?: number | undefined;
     warnings?: {
         code: string;
         file: string;
@@ -874,6 +938,11 @@ declare const recallOutputSchema: z.ZodObject<{
     auto_healed?: boolean | undefined;
     previous_revision_hash?: string | undefined;
     redirects?: Record<string, string> | undefined;
+    next_steps?: string[] | undefined;
+    truncation?: {
+        omitted_candidate_count: number;
+        returned_candidate_count: number;
+    } | undefined;
 }>;
 declare const recallAnnotations: {
     readonly readOnlyHint: true;
@@ -973,7 +1042,7 @@ declare const ProposedReasonSchema: z.ZodEnum<["explicit-user-mark", "diagnostic
 type ProposedReason = z.infer<typeof ProposedReasonSchema>;
 declare const PROPOSED_REASON_DESCRIPTIONS: Record<ProposedReason, string>;
 declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
-    source_sessions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    source_sessions: z.ZodArray<z.ZodString, "many">;
     recent_paths: z.ZodArray<z.ZodString, "many">;
     user_messages_summary: z.ZodString;
     type: z.ZodEnum<["decisions", "pitfalls", "guidelines", "models", "processes"]>;
@@ -992,6 +1061,7 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     evidence_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     type: "models" | "decisions" | "guidelines" | "pitfalls" | "processes";
+    source_sessions: string[];
     proposed_reason: "explicit-user-mark" | "diagnostic-then-fix" | "decision-confirmation" | "wrong-turn-revert" | "new-dependency-or-pattern" | "dismissal-with-reason";
     session_context: string;
     recent_paths: string[];
@@ -999,7 +1069,6 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     slug: string;
     relevance_scope?: "narrow" | "broad" | undefined;
     relevance_paths?: string[] | undefined;
-    source_sessions?: string[] | undefined;
     layer?: "personal" | "team" | undefined;
     intent_clues?: string[] | undefined;
     tech_stack?: string[] | undefined;
@@ -1010,6 +1079,7 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     evidence_paths?: string[] | undefined;
 }, {
     type: "models" | "decisions" | "guidelines" | "pitfalls" | "processes";
+    source_sessions: string[];
     proposed_reason: "explicit-user-mark" | "diagnostic-then-fix" | "decision-confirmation" | "wrong-turn-revert" | "new-dependency-or-pattern" | "dismissal-with-reason";
     session_context: string;
     recent_paths: string[];
@@ -1017,7 +1087,6 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     slug: string;
     relevance_scope?: "narrow" | "broad" | undefined;
     relevance_paths?: string[] | undefined;
-    source_sessions?: string[] | undefined;
     layer?: "personal" | "team" | undefined;
     intent_clues?: string[] | undefined;
     tech_stack?: string[] | undefined;
@@ -1028,6 +1097,7 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     evidence_paths?: string[] | undefined;
 }>, {
     type: "models" | "decisions" | "guidelines" | "pitfalls" | "processes";
+    source_sessions: string[];
     proposed_reason: "explicit-user-mark" | "diagnostic-then-fix" | "decision-confirmation" | "wrong-turn-revert" | "new-dependency-or-pattern" | "dismissal-with-reason";
     session_context: string;
     recent_paths: string[];
@@ -1035,7 +1105,6 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     slug: string;
     relevance_scope?: "narrow" | "broad" | undefined;
     relevance_paths?: string[] | undefined;
-    source_sessions?: string[] | undefined;
     layer?: "personal" | "team" | undefined;
     intent_clues?: string[] | undefined;
     tech_stack?: string[] | undefined;
@@ -1046,6 +1115,7 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     evidence_paths?: string[] | undefined;
 }, {
     type: "models" | "decisions" | "guidelines" | "pitfalls" | "processes";
+    source_sessions: string[];
     proposed_reason: "explicit-user-mark" | "diagnostic-then-fix" | "decision-confirmation" | "wrong-turn-revert" | "new-dependency-or-pattern" | "dismissal-with-reason";
     session_context: string;
     recent_paths: string[];
@@ -1053,7 +1123,6 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     slug: string;
     relevance_scope?: "narrow" | "broad" | undefined;
     relevance_paths?: string[] | undefined;
-    source_sessions?: string[] | undefined;
     layer?: "personal" | "team" | undefined;
     intent_clues?: string[] | undefined;
     tech_stack?: string[] | undefined;
@@ -1064,7 +1133,7 @@ declare const FabExtractKnowledgeInputSchema: z.ZodEffects<z.ZodObject<{
     evidence_paths?: string[] | undefined;
 }>;
 declare const FabExtractKnowledgeInputShape: {
-    source_sessions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    source_sessions: z.ZodArray<z.ZodString, "many">;
     recent_paths: z.ZodArray<z.ZodString, "many">;
     user_messages_summary: z.ZodString;
     type: z.ZodEnum<["decisions", "pitfalls", "guidelines", "models", "processes"]>;
@@ -2061,6 +2130,42 @@ declare const citeCoverageReportSchema: z.ZodObject<{
         compliant_cites: z.ZodOptional<z.ZodNumber>;
         noncompliant_cites: z.ZodOptional<z.ZodNumber>;
         uncorrelatable_edits: z.ZodOptional<z.ZodNumber>;
+        recall_backed_edits: z.ZodOptional<z.ZodNumber>;
+        recall_coverage_rate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        exposed_and_mutated: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+            ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            ids?: string[] | undefined;
+        }, {
+            count: number;
+            ids?: string[] | undefined;
+        }>>;
+        mutations_observed: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+        }, {
+            count: number;
+        }>>;
+        mutation_pool: z.ZodOptional<z.ZodObject<{
+            attributed: z.ZodNumber;
+            unattributed_workspace_dirty: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        }, {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        }>>;
+        sessions_closed: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+        }, {
+            count: number;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         edits_touched: number;
         qualifying_cites: number;
@@ -2071,6 +2176,22 @@ declare const citeCoverageReportSchema: z.ZodObject<{
         compliant_cites?: number | undefined;
         noncompliant_cites?: number | undefined;
         uncorrelatable_edits?: number | undefined;
+        recall_backed_edits?: number | undefined;
+        recall_coverage_rate?: number | null | undefined;
+        exposed_and_mutated?: {
+            count: number;
+            ids?: string[] | undefined;
+        } | undefined;
+        mutations_observed?: {
+            count: number;
+        } | undefined;
+        mutation_pool?: {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        } | undefined;
+        sessions_closed?: {
+            count: number;
+        } | undefined;
     }, {
         edits_touched: number;
         qualifying_cites: number;
@@ -2081,6 +2202,22 @@ declare const citeCoverageReportSchema: z.ZodObject<{
         compliant_cites?: number | undefined;
         noncompliant_cites?: number | undefined;
         uncorrelatable_edits?: number | undefined;
+        recall_backed_edits?: number | undefined;
+        recall_coverage_rate?: number | null | undefined;
+        exposed_and_mutated?: {
+            count: number;
+            ids?: string[] | undefined;
+        } | undefined;
+        mutations_observed?: {
+            count: number;
+        } | undefined;
+        mutation_pool?: {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        } | undefined;
+        sessions_closed?: {
+            count: number;
+        } | undefined;
     }>;
     per_client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         edits_touched: z.ZodOptional<z.ZodNumber>;
@@ -2157,6 +2294,22 @@ declare const citeCoverageReportSchema: z.ZodObject<{
         compliant_cites?: number | undefined;
         noncompliant_cites?: number | undefined;
         uncorrelatable_edits?: number | undefined;
+        recall_backed_edits?: number | undefined;
+        recall_coverage_rate?: number | null | undefined;
+        exposed_and_mutated?: {
+            count: number;
+            ids?: string[] | undefined;
+        } | undefined;
+        mutations_observed?: {
+            count: number;
+        } | undefined;
+        mutation_pool?: {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        } | undefined;
+        sessions_closed?: {
+            count: number;
+        } | undefined;
     };
     generated_at: string;
     layer_filter?: "personal" | "team" | "all" | undefined;
@@ -2200,6 +2353,22 @@ declare const citeCoverageReportSchema: z.ZodObject<{
         compliant_cites?: number | undefined;
         noncompliant_cites?: number | undefined;
         uncorrelatable_edits?: number | undefined;
+        recall_backed_edits?: number | undefined;
+        recall_coverage_rate?: number | null | undefined;
+        exposed_and_mutated?: {
+            count: number;
+            ids?: string[] | undefined;
+        } | undefined;
+        mutations_observed?: {
+            count: number;
+        } | undefined;
+        mutation_pool?: {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        } | undefined;
+        sessions_closed?: {
+            count: number;
+        } | undefined;
     };
     generated_at: string;
     layer_filter?: "personal" | "team" | "all" | undefined;

package/dist/schemas/api-contracts.js

@@ -42,7 +42,7 @@ import {
   recallInputSchema,
   recallOutputSchema,
   structuredWarningSchema
-} from "../chunk-WVPDH4BF.js";
+} from "../chunk-355LUDLW.js";
 export {
   FabExtractKnowledgeInputSchema,
   FabExtractKnowledgeInputShape,

package/dist/templates/bootstrap-canonical.d.ts

@@ -51,6 +51,6 @@ declare const LEGACY_KB_REGEX: RegExp;
  *
  * Length guarantee: ≥ 800 bytes (rc.24: grew from ≥400 with cite-contract syntax).
  */
-declare const BOOTSTRAP_CANONICAL = "# Fabric Bootstrap\n\n\u672C\u9879\u76EE\u4F7F\u7528 Fabric \u7BA1\u7406\u8DE8\u5BA2\u6237\u7AEF AI \u77E5\u8BC6\u4E0E\u884C\u4E3A\u89C4\u5219\u3002\u672C\u6587\u4EF6\u7531 `fabric install` \u540C\u6B65\u5230\u4E09\u7AEF managed block,**\u4E0D\u8981\u624B\u52A8\u7F16\u8F91\u4E09\u7AEF\u7684 block**,\u53EA\u6539\u8FD9\u91CC + \u91CD\u8DD1 `fabric install`\u3002\n\n## For Developers\n\n\u8FD9\u4E2A\u6587\u4EF6\u662F **AI \u5BA2\u6237\u7AEF\u7684\u7B56\u7565\u4E0E\u89C4\u7EA6\u914D\u7F6E**,\u4E0D\u662F dev onboarding\u3002\u4F60\u4E0D\u9700\u8981\u8BFB Self-archive / Cite / Phase 0.4 \u7B49\u7EC6\u8282\u3002\n\u4F5C\u4E3A dev \u4F60\u53EA\u9700\u8981:\u5728\u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 `fabric install`,\u51FA\u95EE\u9898\u8DD1 `fabric doctor`,\u5728 `.fabric/knowledge/<type>/` \u4E0B\u5199 markdown\u3002\n**\u4E25\u7981\u624B\u52A8\u7F16\u8F91 `.fabric/agents.meta.json`** \u2014 \u6D3E\u751F\u72B6\u6001\u7531 engine \u91CD\u5EFA\u3002\n\n## 5 \u5206\u949F\u4E0A\u624B (Dev Quickstart)\n\n**Fabric \u662F\u4EC0\u4E48**:\u8DE8\u5BA2\u6237\u7AEF(Claude Code / Codex CLI / Cursor)\u7684 AI \u77E5\u8BC6\u5C42\u3002\u628A\u56E2\u961F/\u9879\u76EE\u7684 **decisions / pitfalls / guidelines / models / processes** \u5B58\u4E3A markdown,hook \u81EA\u52A8 surface \u7ED9 AI,\u8BA9 AI \u4E0D\u7528\u6BCF\u6B21\u91CD\u5B66\u3002\n\n**\u4F60\u8981\u505A\u7684 (DO)** vs **engine \u81EA\u52A8\u7684 (DON'T \u624B\u52A8)**:\n\n| \u4F60 DO | \u4F60 DON'T |\n| --- | --- |\n| \u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 `fabric install` | \u624B\u7F16 `.fabric/agents.meta.json` |\n| \u5F02\u5E38\u65F6\u8DD1 `fabric doctor` (--fix \u81EA\u6108) | \u624B\u7F16 `.claude/hooks/` \u4E0B `.cjs` |\n| \u5728 `.fabric/knowledge/<type>/` \u4E0B\u5199 markdown | \u64CD\u5FC3 Phase 0.4 / E3 / cite policy |\n| `npm install -g @fenglimg/fabric-cli@latest` \u5347\u7EA7 | \u80CC 35 \u6761 doctor lint \u4EE3\u7801 |\n\n**4 \u6B65\u5FAA\u73AF**: `fabric install` (\u4E00\u6B21) \u2192 AI \u6B63\u5E38\u5DE5\u4F5C (hook on session start + edit) \u2192 AI \u63D0\u8BAE\u6761\u76EE\u5165 `.fabric/knowledge/pending/` \u2192 \u7528 `fabric-review` skill \u6216 `fabric doctor --fix` \u5BA1\u6838\u5F52\u6863\u3002\n\n**\u771F\u4F8B**:\u67D0 sprite \u9ED1\u8FB9 root cause \u662F `atlas.premultiplyAlpha` flag \u53CD\u5411 \u2014 \u5199\u8FDB `.fabric/knowledge/pitfalls/` \u540E,\u4E0B\u6B21\u540C\u7C7B\u95EE\u9898 AI \u81EA\u52A8 reference\u3002\n\n\u5B8C\u6574 maintainer \u7248\u89C1 `docs/USER-QUICKSTART.md`\u3002\n\n## \u884C\u4E3A\u89C4\u5219\n- **\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\u524D**:\u4F18\u5148\u5355\u6B65 `fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])` \u2014\u2014 \u4E00\u6B21\u8C03\u7528\u76F4\u63A5\u62FF\u56DE\u6240\u6709\u76F8\u5173 KB \u6B63\u6587(rc.37+ \u9ED8\u8BA4\u8DEF\u5F84,\u7701\u6389\u624B\u52A8\u6311 id \u7684\u73AF\u8282)\u3002**\u4EC5\u5F53\u5355\u6B65\u62C9\u56DE\u7684\u6B63\u6587\u8FC7\u591A\u3001\u5BFC\u81F4\u4E0A\u4E0B\u6587\u8FC7\u8F7D\u9700\u7CBE\u786E\u88C1\u526A\u566A\u97F3\u65F6**\u624D\u8D70\u4E24\u6B65:\u5148 `fab_plan_context(paths=[...])` \u62FF `selection_token` + \u9876\u5C42 `candidates[]`(\u4ECE `candidates[].stable_id` \u6311),\u518D `fab_get_knowledge_sections({ selection_token, ai_selected_stable_ids: [<id>...] })` \u53D6\u6B63\u6587\u3002\n- **`.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\n\n## \u77E5\u8BC6\u5E93(KB)\n- **Discovery**:SessionStart hook \u5217 broad-scoped \u6761\u76EE(\u542B personal layer `KP-*` \u6761\u76EE,\u5F15\u7528\u65B9\u5F0F\u76F8\u540C);edit \u6587\u4EF6\u65F6 PreToolUse hook \u53EF\u80FD\u89E6\u53D1 narrow hint\u3002\n- **Usage**:\u5E38\u6001\u8D70\u5355\u6B65 `fab_recall(paths=[...])` \u4E00\u6B21\u62FF\u56DE\u76F8\u5173 KB \u6B63\u6587\u3002\u4EC5\u5F53\u5355\u6B65\u6B63\u6587\u8FC7\u591A\u81F4\u4E0A\u4E0B\u6587\u8FC7\u8F7D\u3001\u9700\u7CBE\u786E\u88C1\u526A\u566A\u97F3\u65F6\u624D\u4E24\u6B65:`fab_plan_context(paths=[...])` \u8FD4\u56DE `selection_token` + \u9876\u5C42 `candidates[]`,\u518D `fab_get_knowledge_sections({ selection_token, ai_selected_stable_ids: [<\u4ECE candidates[].stable_id \u6311>...] })` \u62C9\u5168\u6587;`selection_token` \u5FC5\u987B\u6765\u81EA\u6700\u8FD1\u4E00\u6B21 `fab_plan_context`,\u4E0D\u53EF\u51ED\u7A7A\u7F16\u9020\u3002\n- **session_id**: \u8C03\u7528 `fab_recall` / `fab_plan_context` \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 archive-hint hook \u51C6\u786E\u8BC6\u522B\u8DE8\u4F1A\u8BDD debt \u72B6\u6001\u3002\n- **Write flows**:`fabric-archive` / `fabric-review` / `fabric-import` \u4E09\u4E2A Skills\u3002\n- **Language**:\u6E32\u67D3\u6309 `.fabric/fabric-config.json` \u7684 `fabric_language` \u5B57\u6BB5\u3002\n- **Archive cadence nudge** (rc.36): \u6BCF\u5B8C\u6210 5+ \u6B21 Edit / \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\n- **Review backlog nudge** (rc.36): `.fabric/knowledge/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\n\n## Self-archive policy (v2.0.0-rc.37 NEW-2: \u7B80\u5316 4 \u4FE1\u53F7 \u2192 2 \u5927\u7C7B)\n\n- **\u89E6\u53D1** (\u672C\u4F1A\u8BDD\u51FA\u73B0\u4EE5\u4E0B\u4EFB\u4E00\u4FE1\u53F7, \u5728\u8BE5 turn \u56DE\u590D\u672B\u5C3E\u81EA\u4E3B\u8C03\u7528 `fabric-archive` skill, \u8D70 AI \u81EA\u89E6\u53D1\u5165\u53E3 E3_ai_self_trigger):\n  1. **User-driven normative** \u2014 \u7528\u6237\u6D88\u606F\u4E2D\u663E\u5F0F\u8868\u8FBE normative \u610F\u56FE: `\u4EE5\u540E` / `always` / `never` / `from now on` / `\u4E0B\u6B21\u6CE8\u610F` / `\u8BB0\u4E00\u4E0B` / `\u6C38\u8FDC\u4E0D\u8981`, OR \u7528\u6237\u5728 \u22652 \u5019\u9009\u95F4\u6743\u8861\u540E\u7ED9\u51FA rationale \u9501\u5B9A\u65B9\u5411, OR \u7528\u6237\u62D2\u4E86\u67D0\u5EFA\u8BAE**\u5E76**\u8BF4\u4E86\u539F\u56E0 (\u62D2\u7EDD\u7406\u7531\u672C\u8EAB\u662F\u77E5\u8BC6)\n  2. **Wrong-turn-and-revert** \u2014 AI \u5C1D\u8BD5 path X, \u53CD\u601D\u540E\u6539\u8D70 path Y (\u5C24\u5176\u5F53 path X \u662F\u975E\u663E\u7136\u8E29\u5751); \u6DB5\u76D6\u6280\u672F\u51B3\u7B56\u53CD\u8F6C + \u5DE5\u5177/\u8303\u5F0F\u5207\u6362 + \u5931\u8D25\u91CD\u8BD5\u3002Anchor: \u4E00\u5B9A\u6709\"\u5426\u5B9A+\u66FF\u4EE3\"\u7684\u4E24\u6B65\u7ED3\u6784, \u4E0D\u662F\u5355\u7EAF\u63A2\u7D22\u5931\u8D25\n\n  \u8001 4-state (Normative / Decision-confirmation / Explicit-dismissal / Wrong-turn) \u73B0\u5408\u5E76: \u524D 3 \u4E2A\u5168\u662F\"\u7528\u6237\u6D88\u606F\u4E2D\u663E\u5F0F\u8868\u8FBE\"\u6027\u8D28, \u6298\u6210 1 \u7C7B; \u7B2C 4 \u662F\"AI \u81EA\u5DF1\u7684\u53CD\u601D\u8DEF\u5F84\", \u72EC\u7ACB 1 \u7C7B\u3002\u4E24\u7C7B\u5404\u81EA\u7684\u672C\u8D28\u5224\u522B\u4E0D\u53D8, \u89E6\u53D1\u9762\u6CA1\u53D8\u7A84\u3002\n\n- **Anti-trigger** (\u660E\u786E\u4E0D\u89E6\u53D1):\n  - \u7528\u6237\u7EAF\u8BE2\u95EE (\u65E0 normative \u8868\u8FBE)\n  - \u7B80\u5355 refactor / typo fix\n  - AI \u81EA\u5DF1\u4EA7\u751F\u7684'\u6D1E\u5BDF' (\u5FC5\u987B\u7531\u7528\u6237\u6D88\u606F\u4E2D\u4FE1\u53F7\u6216 AI \u81EA\u5DF1\u7684 wrong-turn \u89E6\u53D1, \u4E0D\u662F\u51ED\u7A7A\"\u6211\u5B66\u5230\u4E86\"\u6027\u8D28)\n\n- **Anti-loop \u4E09\u6761\u9632\u62A4**:\n  - \u540C turn \u6700\u591A\u81EA\u8C03 1 \u6B21\n  - \u540C session \u540C outcome \u4E0D\u91CD\u590D (\u82E5 user_dismissed, \u672C\u4F1A\u8BDD\u4E0D\u518D\u81EA\u8C03\u76F8\u540C\u4E3B\u9898)\n  - Phase 2.5 viability gate \u515C\u5E95 (skill \u5185\u90E8\u4ECD\u8DD1 gate, AI \u5224\u9519\u4E0D\u4F1A\u4E71\u5199 pending)\n\n- **\u5448\u73B0\u6A21\u677F** (turn \u672B\u5C3E\u63D2\u5165, \u4E24\u884C: \u5148 marker \u884C\u4F9B Phase 1.5 \u68C0\u6D4B, \u518D user-facing \u63D0\u793A):\n  ```\n  self-archive policy triggered by signal: <User-driven normative|Wrong-turn-and-revert>\n  \u987A\u624B\u5F52\u6863: \u6CE8\u610F\u5230\u4F60\u8BF4 `<\u89E6\u53D1\u77ED\u8BED>`, \u5DF2\u8C03\u7528 fabric-archive \u6293 N \u6761\u5019\u9009 \u2192 .fabric/knowledge/pending/...\n  \u82E5\u4E0D\u8BE5\u8BB0, \u7B54 '\u64A4\u9500' \u6211\u4F1A\u8C03 fab_review reject\u3002\n  ```\n  \u7B2C\u4E00\u884C\u662F Phase 1.5 Trigger Gate \u8BC6\u522B E3 \u5165\u53E3\u7684 structured marker (verbatim \u5B57\u7B26\u4E32 `self-archive policy triggered by signal`, \u540E\u63A5\u5192\u53F7 + \u89E6\u53D1\u4FE1\u53F7\u540D)\u3002\u7B2C\u4E8C\u884C\u8D77\u662F\u7ED9\u7528\u6237\u770B\u7684\u4E2D\u6587\u63D0\u793A\u3002\u4E24\u884C\u90FD\u5FC5\u987B\u51FA\u73B0; \u7F3A marker \u884C Phase 1.5 \u65E0\u6CD5\u8DEF\u7531\u5230 E3_ai_self_trigger\u3002\n\n  Backward compat: Phase 1.5 entry-point regex \u540C\u65F6\u8BC6\u522B\u8001 4 \u4E2A\u4FE1\u53F7\u540D (Normative / Wrong-turn-and-revert / Decision confirmation / Explicit dismissal) \u4E0E\u65B0 2 \u5927\u7C7B\u540D, \u65E7 session marker \u4ECD\u80FD\u6B63\u786E\u8DEF\u7531\u3002\n\n## Cite policy (v2.0.0-rc.37 NEW-1: \u7B80\u5316 4-state \u2192 2-state)\n\n- **\u89E6\u53D1**: \u505A edit / decide / propose plan \u4E4B\u524D,**\u56DE\u590D\u9996\u884C**\u5FC5\u987B\u5199 `KB: <id> (<\u22648\u5B57 \u7528\u6CD5>) [applied|dismissed:<reason>]` \u6216 `KB: none [<reason>]`\u3002\n- **`[applied]` \u9A8C\u8BC1\u4E49\u52A1**: \u5F15\u7528\u4EFB\u4F55 id \u524D\u5FC5\u987B\u5148\u7528 fab_recall (\u6216\u4E24\u6B65 fab_plan_context \u2192 fab_get_knowledge_sections) \u5B9E\u9645\u6293 KB body, \u9632\u6B62\u7F16\u9020 id\u3002\u9A8C\u8BC1\u4E0D\u901A\u8FC7 = \u4E0D\u80FD cite\u3002\n- **store \u524D\u7F00 (v2.1, \u591A store)**: \u5F53 read-set \u542B\u591A\u4E2A store \u4E14\u540C\u4E00 local id \u5728\u591A store \u95F4 shadow \u65F6,cite \u5FC5\u987B store-qualified: `KB: <store-alias>:<id> ...`(\u5982 `KB: team:KT-DEC-0001 (auth) [applied]`);alias \u7528\u6237\u81EA\u5B9A/canonical,\u5E95\u5C42 UUID\u3002\u5355 store \u6216\u65E0\u6B67\u4E49\u65F6\u88F8 `KB: <id>` \u4ECD valid\u3002personal-only \u6761\u76EE cite \u8FDB\u56E2\u961F\u4EA7\u7269=\u5F3A warning(\u63A5 P2 \u5199\u8DEF\u5F84\u9632\u6CC4\u6F0F R5#3)\u3002\n- **contract \u8BED\u6CD5**: decisions/pitfalls \u7C7B `[applied]` cite \u5C3E\u6BB5\u52A0 contract: `\u2192 <operator> [<operator> ...]`,operator \u2208 {`edit:<glob>` `!edit:<glob>` `require:<symbol>` `forbid:<symbol>` `skip:<reason>`}\u3002\u4F8B:`KB: K-001 (auth) [applied] \u2192 edit:src/auth/**/*.ts !edit:src/legacy/**`\u3002\n- **skip reason \u8BCD\u5178**: `sequencing | conditional | semantic | aesthetic | architectural | other:<text>`\u3002\n- **type \u8DEF\u7531**: models \u7C7B\u5F15\u7528\u4E3A reference cite,\u4E0D\u9700\u8981 contract;guidelines/processes \u7C7B\u6682\u4E0D\u5F3A\u5236,\u63A8\u540E LLM-judge\u3002\n- **\u7528\u6237\u53E3\u5934\u63D0\u89C4\u5219\u6CA1\u7ED9 id**: \u5148\u8C03 `fab_recall(paths)` \u6216 `fab_extract_knowledge` \u53CD\u67E5\u3002\n- **dismissed reason**: \u679A\u4E3E `scope-mismatch | outdated | not-applicable | other:<text>`\u3002\n- **`KB: none` sentinel**: \u679A\u4E3E\u4E24\u79CD\u5408\u89C4\u7406\u7531\u2014\u2014`[no-relevant]` \u5DF2\u8C03 `fab_recall` / `fab_plan_context`(\u6216 hook \u8F93\u51FA\u53EF\u89C1)\u4F46\u65E0\u53EF\u7528\u6761\u76EE;`[not-applicable]` \u5F53\u524D\u52A8\u4F5C\u4E0D\u5728 cite \u8303\u56F4(\u7EAF\u63A2\u7D22 / Bash \u53EA\u8BFB / \u7528\u6237\u95EE\u7B54)\u3002\u88F8 `KB: none`(\u65E0\u540E\u7F00)\u4ECD\u7136 valid,\u5F52\u7C7B\u4E3A `[unspecified]`(legacy \u517C\u5BB9,\u9F13\u52B1\u540E\u7EED\u8865\u6CE8)\u3002\n- **\u7A3D\u6838**: `fabric doctor --cite-coverage [--since=7d] [--client=cc|codex|all]` \u8F93\u51FA cite \u8986\u76D6\u7387,\u542B `KB: none` sentinel \u62C6\u5206\u3002\u672C\u89C4\u5219\u4E0D\u963B\u65AD\u4F60\u5DE5\u4F5C,\u53EA\u8BB0\u5F55\u3002\n- **Backward compat**: \u89E3\u6790\u5668\u540C\u65F6\u63A5\u53D7\u8001 4-state tags (`planned` / `recalled` / `chained-from <id>`) \u2014 \u90FD\u6620\u5C04\u5230 `[applied]` \u8BED\u4E49,gradually \u8FC1\u5230\u65B0\u7B80\u5316\u5F62\u6001\u5373\u53EF,\u65E7 session \u7559\u4E0B\u7684 cite \u4ECD\u7136\u8BA1\u5165 cite-coverage\u3002\n";
+declare const BOOTSTRAP_CANONICAL = "# Fabric Bootstrap\n\n\u672C\u9879\u76EE\u4F7F\u7528 Fabric \u7BA1\u7406\u8DE8\u5BA2\u6237\u7AEF AI \u77E5\u8BC6\u4E0E\u884C\u4E3A\u89C4\u5219\u3002\u672C\u6587\u4EF6\u7531 `fabric install` \u540C\u6B65\u5230\u4E09\u7AEF managed block,**\u4E0D\u8981\u624B\u52A8\u7F16\u8F91\u4E09\u7AEF\u7684 block**,\u53EA\u6539\u8FD9\u91CC + \u91CD\u8DD1 `fabric install`\u3002\n\n## For Developers\n\n\u8FD9\u4E2A\u6587\u4EF6\u662F **AI \u5BA2\u6237\u7AEF\u7684\u7B56\u7565\u4E0E\u89C4\u7EA6\u914D\u7F6E**,\u4E0D\u662F dev onboarding\u3002\u4F60\u4E0D\u9700\u8981\u8BFB Self-archive / Cite / Phase 0.4 \u7B49\u7EC6\u8282\u3002\n\u4F5C\u4E3A dev \u4F60\u53EA\u9700\u8981:\u5728\u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 `fabric install`,\u51FA\u95EE\u9898\u8DD1 `fabric doctor`,\u5728 `.fabric/knowledge/<type>/` \u4E0B\u5199 markdown\u3002\n**\u4E25\u7981\u624B\u52A8\u7F16\u8F91 `.fabric/agents.meta.json`** \u2014 \u6D3E\u751F\u72B6\u6001\u7531 engine \u91CD\u5EFA\u3002\n\n## 5 \u5206\u949F\u4E0A\u624B (Dev Quickstart)\n\n**Fabric \u662F\u4EC0\u4E48**:\u8DE8\u5BA2\u6237\u7AEF(Claude Code / Codex CLI / Cursor)\u7684 AI \u77E5\u8BC6\u5C42\u3002\u628A\u56E2\u961F/\u9879\u76EE\u7684 **decisions / pitfalls / guidelines / models / processes** \u5B58\u4E3A markdown,hook \u81EA\u52A8 surface \u7ED9 AI,\u8BA9 AI \u4E0D\u7528\u6BCF\u6B21\u91CD\u5B66\u3002\n\n**\u4F60\u8981\u505A\u7684 (DO)** vs **engine \u81EA\u52A8\u7684 (DON'T \u624B\u52A8)**:\n\n| \u4F60 DO | \u4F60 DON'T |\n| --- | --- |\n| \u6BCF\u4E2A repo \u8DD1\u4E00\u6B21 `fabric install` | \u624B\u7F16 `.fabric/agents.meta.json` |\n| \u5F02\u5E38\u65F6\u8DD1 `fabric doctor` (--fix \u81EA\u6108) | \u624B\u7F16 `.claude/hooks/` \u4E0B `.cjs` |\n| \u5728 `.fabric/knowledge/<type>/` \u4E0B\u5199 markdown | \u64CD\u5FC3 Phase 0.4 / E3 / cite policy |\n| `npm install -g @fenglimg/fabric-cli@latest` \u5347\u7EA7 | \u80CC 35 \u6761 doctor lint \u4EE3\u7801 |\n\n**4 \u6B65\u5FAA\u73AF**: `fabric install` (\u4E00\u6B21) \u2192 AI \u6B63\u5E38\u5DE5\u4F5C (hook on session start + edit) \u2192 AI \u63D0\u8BAE\u6761\u76EE\u5165 `.fabric/knowledge/pending/` \u2192 \u7528 `fabric-review` skill \u6216 `fabric doctor --fix` \u5BA1\u6838\u5F52\u6863\u3002\n\n**\u771F\u4F8B**:\u67D0 sprite \u9ED1\u8FB9 root cause \u662F `atlas.premultiplyAlpha` flag \u53CD\u5411 \u2014 \u5199\u8FDB `.fabric/knowledge/pitfalls/` \u540E,\u4E0B\u6B21\u540C\u7C7B\u95EE\u9898 AI \u81EA\u52A8 reference\u3002\n\n\u5B8C\u6574 maintainer \u7248\u89C1 `docs/USER-QUICKSTART.md`\u3002\n\n## \u884C\u4E3A\u89C4\u5219\n- **\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\u524D**:\u4F18\u5148\u5355\u6B65 `fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])` \u2014\u2014 \u4E00\u6B21\u8C03\u7528\u76F4\u63A5\u62FF\u56DE\u6240\u6709\u76F8\u5173 KB \u6B63\u6587(rc.37+ \u9ED8\u8BA4\u8DEF\u5F84,\u7701\u6389\u624B\u52A8\u6311 id \u7684\u73AF\u8282)\u3002**\u4EC5\u5F53\u5355\u6B65\u62C9\u56DE\u7684\u6B63\u6587\u8FC7\u591A\u3001\u5BFC\u81F4\u4E0A\u4E0B\u6587\u8FC7\u8F7D\u9700\u7CBE\u786E\u88C1\u526A\u566A\u97F3\u65F6**\u624D\u8D70\u4E24\u6B65:\u5148 `fab_plan_context(paths=[...])` \u62FF `selection_token` + \u9876\u5C42 `candidates[]`(\u4ECE `candidates[].stable_id` \u6311),\u518D `fab_get_knowledge_sections({ selection_token, ai_selected_stable_ids: [<id>...] })` \u53D6\u6B63\u6587\u3002\n- **`.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\n\n## \u77E5\u8BC6\u5E93(KB)\n- **Discovery**:SessionStart hook \u5217 broad-scoped \u6761\u76EE(\u542B personal layer `KP-*` \u6761\u76EE,\u5F15\u7528\u65B9\u5F0F\u76F8\u540C);edit \u6587\u4EF6\u65F6 PreToolUse hook \u53EF\u80FD\u89E6\u53D1 narrow hint\u3002\n- **Usage**:\u5E38\u6001\u8D70\u5355\u6B65 `fab_recall(paths=[...])` \u4E00\u6B21\u62FF\u56DE\u76F8\u5173 KB \u6B63\u6587\u3002\u4EC5\u5F53\u5355\u6B65\u6B63\u6587\u8FC7\u591A\u81F4\u4E0A\u4E0B\u6587\u8FC7\u8F7D\u3001\u9700\u7CBE\u786E\u88C1\u526A\u566A\u97F3\u65F6\u624D\u4E24\u6B65:`fab_plan_context(paths=[...])` \u8FD4\u56DE `selection_token` + \u9876\u5C42 `candidates[]`,\u518D `fab_get_knowledge_sections({ selection_token, ai_selected_stable_ids: [<\u4ECE candidates[].stable_id \u6311>...] })` \u62C9\u5168\u6587;`selection_token` \u5FC5\u987B\u6765\u81EA\u6700\u8FD1\u4E00\u6B21 `fab_plan_context`,\u4E0D\u53EF\u51ED\u7A7A\u7F16\u9020\u3002\n- **session_id**: \u8C03\u7528 `fab_recall` / `fab_plan_context` \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 archive-hint hook \u51C6\u786E\u8BC6\u522B\u8DE8\u4F1A\u8BDD debt \u72B6\u6001\u3002\n- **Skills (7)**:\u5199\u6D41\u7A0B `fabric-archive` / `fabric-review` / `fabric-import`;store \u6D41\u7A0B `fabric-store` / `fabric-sync` / `fabric-connect`;\u8BCA\u65AD `fabric-audit`\u3002\n- **Language**:\u6E32\u67D3\u6309 `.fabric/fabric-config.json` \u7684 `fabric_language` \u5B57\u6BB5\u3002\n- **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\n- **Review backlog nudge** (rc.36): `.fabric/knowledge/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\n\n## Self-archive policy (v2.0.0-rc.37 NEW-2: \u7B80\u5316 4 \u4FE1\u53F7 \u2192 2 \u5927\u7C7B)\n\n- **\u89E6\u53D1** (\u672C\u4F1A\u8BDD\u51FA\u73B0\u4EE5\u4E0B\u4EFB\u4E00\u4FE1\u53F7, \u5728\u8BE5 turn \u56DE\u590D\u672B\u5C3E\u81EA\u4E3B\u8C03\u7528 `fabric-archive` skill, \u8D70 AI \u81EA\u89E6\u53D1\u5165\u53E3 E3_ai_self_trigger):\n  1. **User-driven normative** \u2014 \u7528\u6237\u6D88\u606F\u4E2D\u663E\u5F0F\u8868\u8FBE normative \u610F\u56FE: `\u4EE5\u540E` / `always` / `never` / `from now on` / `\u4E0B\u6B21\u6CE8\u610F` / `\u8BB0\u4E00\u4E0B` / `\u6C38\u8FDC\u4E0D\u8981`, OR \u7528\u6237\u5728 \u22652 \u5019\u9009\u95F4\u6743\u8861\u540E\u7ED9\u51FA rationale \u9501\u5B9A\u65B9\u5411, OR \u7528\u6237\u62D2\u4E86\u67D0\u5EFA\u8BAE**\u5E76**\u8BF4\u4E86\u539F\u56E0 (\u62D2\u7EDD\u7406\u7531\u672C\u8EAB\u662F\u77E5\u8BC6)\n  2. **Wrong-turn-and-revert** \u2014 AI \u5C1D\u8BD5 path X, \u53CD\u601D\u540E\u6539\u8D70 path Y (\u5C24\u5176\u5F53 path X \u662F\u975E\u663E\u7136\u8E29\u5751); \u6DB5\u76D6\u6280\u672F\u51B3\u7B56\u53CD\u8F6C + \u5DE5\u5177/\u8303\u5F0F\u5207\u6362 + \u5931\u8D25\u91CD\u8BD5\u3002Anchor: \u4E00\u5B9A\u6709\"\u5426\u5B9A+\u66FF\u4EE3\"\u7684\u4E24\u6B65\u7ED3\u6784, \u4E0D\u662F\u5355\u7EAF\u63A2\u7D22\u5931\u8D25\n\n  \u8001 4-state (Normative / Decision-confirmation / Explicit-dismissal / Wrong-turn) \u73B0\u5408\u5E76: \u524D 3 \u4E2A\u5168\u662F\"\u7528\u6237\u6D88\u606F\u4E2D\u663E\u5F0F\u8868\u8FBE\"\u6027\u8D28, \u6298\u6210 1 \u7C7B; \u7B2C 4 \u662F\"AI \u81EA\u5DF1\u7684\u53CD\u601D\u8DEF\u5F84\", \u72EC\u7ACB 1 \u7C7B\u3002\u4E24\u7C7B\u5404\u81EA\u7684\u672C\u8D28\u5224\u522B\u4E0D\u53D8, \u89E6\u53D1\u9762\u6CA1\u53D8\u7A84\u3002\n\n- **Anti-trigger** (\u660E\u786E\u4E0D\u89E6\u53D1):\n  - \u7528\u6237\u7EAF\u8BE2\u95EE (\u65E0 normative \u8868\u8FBE)\n  - \u7B80\u5355 refactor / typo fix\n  - AI \u81EA\u5DF1\u4EA7\u751F\u7684'\u6D1E\u5BDF' (\u5FC5\u987B\u7531\u7528\u6237\u6D88\u606F\u4E2D\u4FE1\u53F7\u6216 AI \u81EA\u5DF1\u7684 wrong-turn \u89E6\u53D1, \u4E0D\u662F\u51ED\u7A7A\"\u6211\u5B66\u5230\u4E86\"\u6027\u8D28)\n\n- **Anti-loop \u4E09\u6761\u9632\u62A4**:\n  - \u540C turn \u6700\u591A\u81EA\u8C03 1 \u6B21\n  - \u540C session \u540C outcome \u4E0D\u91CD\u590D (\u82E5 user_dismissed, \u672C\u4F1A\u8BDD\u4E0D\u518D\u81EA\u8C03\u76F8\u540C\u4E3B\u9898)\n  - Phase 2.5 viability gate \u515C\u5E95 (skill \u5185\u90E8\u4ECD\u8DD1 gate, AI \u5224\u9519\u4E0D\u4F1A\u4E71\u5199 pending)\n\n- **\u5448\u73B0\u6A21\u677F** (turn \u672B\u5C3E\u63D2\u5165, \u4E24\u884C: \u5148 marker \u884C\u4F9B Phase 1.5 \u68C0\u6D4B, \u518D user-facing \u63D0\u793A):\n  ```\n  self-archive policy triggered by signal: <User-driven normative|Wrong-turn-and-revert>\n  \u987A\u624B\u5F52\u6863: \u6CE8\u610F\u5230\u4F60\u8BF4 `<\u89E6\u53D1\u77ED\u8BED>`, \u5DF2\u8C03\u7528 fabric-archive \u6293 N \u6761\u5019\u9009 \u2192 .fabric/knowledge/pending/...\n  \u82E5\u4E0D\u8BE5\u8BB0, \u7B54 '\u64A4\u9500' \u6211\u4F1A\u8C03 fab_review reject\u3002\n  ```\n  \u7B2C\u4E00\u884C\u662F Phase 1.5 Trigger Gate \u8BC6\u522B E3 \u5165\u53E3\u7684 structured marker (verbatim \u5B57\u7B26\u4E32 `self-archive policy triggered by signal`, \u540E\u63A5\u5192\u53F7 + \u89E6\u53D1\u4FE1\u53F7\u540D)\u3002\u7B2C\u4E8C\u884C\u8D77\u662F\u7ED9\u7528\u6237\u770B\u7684\u4E2D\u6587\u63D0\u793A\u3002\u4E24\u884C\u90FD\u5FC5\u987B\u51FA\u73B0; \u7F3A marker \u884C Phase 1.5 \u65E0\u6CD5\u8DEF\u7531\u5230 E3_ai_self_trigger\u3002\n\n  Backward compat: Phase 1.5 entry-point regex \u540C\u65F6\u8BC6\u522B\u8001 4 \u4E2A\u4FE1\u53F7\u540D (Normative / Wrong-turn-and-revert / Decision confirmation / Explicit dismissal) \u4E0E\u65B0 2 \u5927\u7C7B\u540D, \u65E7 session marker \u4ECD\u80FD\u6B63\u786E\u8DEF\u7531\u3002\n\n## Cite policy (v2.1 \u2464 recall-based: \u81EA\u52A8\u8BB0\u8D26\u4F18\u5148, \u9996\u884C KB: \u53EF\u9009 override)\n\n- **\u6838\u5FC3 (recall-first \u81EA\u52A8\u8BB0\u8D26)**: \u6539\u4EFB\u4F55\u6587\u4EF6\u524D\u5148 `fab_recall(paths=[<\u88AB\u6539\u6587\u4EF6>])`\u3002\u7CFB\u7EDF\u6309\"\u672C session \u8FD1\u671F recall \u547D\u4E2D\u7684 path \u4E0E\u7F16\u8F91\u76EE\u6807\u91CD\u53E0\"\u81EA\u52A8\u628A\u53EC\u56DE\u7684 KB \u5173\u8054\u4E3A\u8BE5\u6B21 edit \u7684\u5F15\u7528 \u2014\u2014 **\u65E0\u9700\u624B\u5199\u56DE\u590D\u9996\u884C**\u3002PreToolUse hook \u5728\u68C0\u6D4B\u4E0D\u5230\u76F8\u5173 recall \u65F6\u7ED9\u4E00\u6761\u8F6F nudge(nudge \u975E gate,\u5B88 KT-DEC-0007);\u6539\u524D recall \u8FC7(\u6216\u5DF2\u624B\u5199 cite)\u5373\u9759\u9ED8\u3002\u4E3A\u4EC0\u4E48\u4E0D\u518D\u903C\u9996\u884C:\u5148\u60F3\u540E\u8BF4,recall \u624D\u662F\u5F15\u7528\u53D1\u751F\u7684\u771F\u5B9E\u4FE1\u53F7,\u624B\u5199\u9996\u884C\u8FDD\u80CC CoT \u4E14 `KB: none` \u9003\u9038\u4F7F\u65E7\u89C4\u5219\u5F62\u540C\u865A\u8BBE\u3002\n- **\u53EF\u9009 override (\u9996\u884C KB:)**: \u4ECD\u53EF\u5728\u56DE\u590D\u9996\u884C\u624B\u5199 `KB: <id> (<\u22648\u5B57 \u7528\u6CD5>) [applied|dismissed:<reason>]` \u6216 `KB: none [<reason>]` \u6765\u663E\u5F0F\u6807\u6CE8/\u7CBE\u786E\u5316\u5F15\u7528;cite-line \u89E3\u6790\u5668\u4FDD\u7559(\u5411\u540E\u517C\u5BB9),\u65E7\u4E60\u60EF\u4E0D\u7834\u3002\n- **`[applied]` \u9A8C\u8BC1\u4E49\u52A1**: \u5F15\u7528\u4EFB\u4F55 id(\u81EA\u52A8\u6216\u624B\u5199)\u7684\u524D\u63D0\u662F\u5148\u7528 fab_recall (\u6216\u4E24\u6B65 fab_plan_context \u2192 fab_get_knowledge_sections) \u5B9E\u9645\u6293 KB body, \u9632\u6B62\u7F16\u9020 id\u3002\u9A8C\u8BC1\u4E0D\u901A\u8FC7 = \u4E0D\u80FD cite\u3002\n- **store \u524D\u7F00 (v2.1, \u591A store)**: \u5F53 read-set \u542B\u591A\u4E2A store \u4E14\u540C\u4E00 local id \u5728\u591A store \u95F4 shadow \u65F6,cite \u5FC5\u987B store-qualified: `KB: <store-alias>:<id> ...`(\u5982 `KB: team:KT-DEC-0001 (auth) [applied]`);alias \u7528\u6237\u81EA\u5B9A/canonical,\u5E95\u5C42 UUID\u3002\u5355 store \u6216\u65E0\u6B67\u4E49\u65F6\u88F8 `KB: <id>` \u4ECD valid\u3002personal-only \u6761\u76EE cite \u8FDB\u56E2\u961F\u4EA7\u7269=\u5F3A warning(\u63A5 P2 \u5199\u8DEF\u5F84\u9632\u6CC4\u6F0F R5#3)\u3002\n- **contract \u8BED\u6CD5**: decisions/pitfalls \u7C7B `[applied]` cite \u5C3E\u6BB5\u52A0 contract: `\u2192 <operator> [<operator> ...]`,operator \u2208 {`edit:<glob>` `!edit:<glob>` `require:<symbol>` `forbid:<symbol>` `skip:<reason>`}\u3002\u4F8B:`KB: K-001 (auth) [applied] \u2192 edit:src/auth/**/*.ts !edit:src/legacy/**`\u3002\n- **skip reason \u8BCD\u5178**: `sequencing | conditional | semantic | aesthetic | architectural | other:<text>`\u3002\n- **type \u8DEF\u7531**: models \u7C7B\u5F15\u7528\u4E3A reference cite,\u4E0D\u9700\u8981 contract;guidelines/processes \u7C7B\u6682\u4E0D\u5F3A\u5236,\u63A8\u540E LLM-judge\u3002\n- **\u7528\u6237\u53E3\u5934\u63D0\u89C4\u5219\u6CA1\u7ED9 id**: \u5148\u8C03 `fab_recall(paths)` \u6216 `fab_extract_knowledge` \u53CD\u67E5\u3002\n- **dismissed reason**: \u679A\u4E3E `scope-mismatch | outdated | not-applicable | other:<text>`\u3002\n- **`KB: none` sentinel**: \u679A\u4E3E\u4E24\u79CD\u5408\u89C4\u7406\u7531\u2014\u2014`[no-relevant]` \u5DF2\u8C03 `fab_recall` / `fab_plan_context`(\u6216 hook \u8F93\u51FA\u53EF\u89C1)\u4F46\u65E0\u53EF\u7528\u6761\u76EE;`[not-applicable]` \u5F53\u524D\u52A8\u4F5C\u4E0D\u5728 cite \u8303\u56F4(\u7EAF\u63A2\u7D22 / Bash \u53EA\u8BFB / \u7528\u6237\u95EE\u7B54)\u3002\u88F8 `KB: none`(\u65E0\u540E\u7F00)\u4ECD\u7136 valid,\u5F52\u7C7B\u4E3A `[unspecified]`(legacy \u517C\u5BB9,\u9F13\u52B1\u540E\u7EED\u8865\u6CE8)\u3002\n- **\u7A3D\u6838**: `fabric doctor --cite-coverage [--since=7d] [--client=cc|codex|all]` \u8F93\u51FA cite \u8986\u76D6\u7387,\u542B `KB: none` sentinel \u62C6\u5206\u3002\u672C\u89C4\u5219\u4E0D\u963B\u65AD\u4F60\u5DE5\u4F5C,\u53EA\u8BB0\u5F55\u3002\n- **Backward compat**: \u89E3\u6790\u5668\u540C\u65F6\u63A5\u53D7\u8001 4-state tags (`planned` / `recalled` / `chained-from <id>`) \u2014 \u90FD\u6620\u5C04\u5230 `[applied]` \u8BED\u4E49,gradually \u8FC1\u5230\u65B0\u7B80\u5316\u5F62\u6001\u5373\u53EF,\u65E7 session \u7559\u4E0B\u7684 cite \u4ECD\u7136\u8BA1\u5165 cite-coverage\u3002\n- **\u5B8C\u6574\u53C2\u8003\u4E0B\u6C89** (v2.2 SK5): contract operator / skip\u00B7dismissed \u8BCD\u5178 / \u7C7B\u578B\u8DEF\u7531 / \u7A3D\u6838\u53E3\u5F84 / **\u88C1\u51B3\u9636\u68AF** (AI\u81EA\u51B3 \u2192 \u591A-LLM \u542B\u96F6\u4E0A\u4E0B\u6587\u51B7\u8BC4 \u2192 \u975E\u963B\u585E\u961F\u5217) \u7684\u6743\u5A01\u8BE6\u53C2\u5728 `fabric-review` skill \u7684 `ref/cite-contract.md` \u2014\u2014 bootstrap \u53EA\u7559\u53EF\u6267\u884C core,\u6CBB\u7406\u7EC6\u8282\u5F52 ref \u4E0D\u518D\u6491\u5927 bootstrap\u3002\n";
 
 export { BOOTSTRAP_CANONICAL, BOOTSTRAP_MARKER_BEGIN, BOOTSTRAP_MARKER_END, BOOTSTRAP_REGEX, LEGACY_KB_MARKER_BEGIN, LEGACY_KB_MARKER_END, LEGACY_KB_REGEX };

package/dist/templates/bootstrap-canonical.js

@@ -6,7 +6,7 @@ import {
   LEGACY_KB_MARKER_BEGIN,
   LEGACY_KB_MARKER_END,
   LEGACY_KB_REGEX
-} from "../chunk-MDWTGOAY.js";
+} from "../chunk-AFT7DB4P.js";
 export {
   BOOTSTRAP_CANONICAL,
   BOOTSTRAP_MARKER_BEGIN,

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export { e as AgentsActivationTier, a as AgentsIdentitySource, b as AgentsLayer, d as AgentsMeta, g as AgentsMetaCountersEnvelope, h as AgentsMetaKnowledgeTypeCounters, A as AgentsMetaNode, i as AgentsMetaNodeActivation, c as AgentsTopologyType, j as AiLedgerEntry, k as AuditMode, C as ClientPaths, D as DefaultLayerFilter, F as FabricConfig, l as FabricLanguage, m as HumanLedgerEntry, H as HumanLockEntry, L as LedgerEntry, M as McpPayloadLimits, R as RuleDescription, n as RuleDescriptionIndexItem } from '../index-GQpaWTm-.js';
+export { e as AgentsActivationTier, a as AgentsIdentitySource, b as AgentsLayer, d as AgentsMeta, g as AgentsMetaCountersEnvelope, h as AgentsMetaKnowledgeTypeCounters, A as AgentsMetaNode, i as AgentsMetaNodeActivation, c as AgentsTopologyType, j as AiLedgerEntry, k as AuditMode, C as ClientPaths, D as DefaultLayerFilter, F as FabricConfig, l as FabricLanguage, m as HumanLedgerEntry, H as HumanLockEntry, L as LedgerEntry, M as McpPayloadLimits, R as RuleDescription, n as RuleDescriptionIndexItem } from '../index-Dm4IJWwB.js';
 import 'zod';