traits 0.5.1 → 0.5.3

package/dist/toolkit/DeriveTrait.d.ts

@@ -1,107 +1,199 @@
 import { Schema as S } from "effect";
-import { AiError, DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai";
+import { DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai";
 import { TraitsContext } from "../TraitsContext.ts";
 import { TraitStore } from "../TraitStore.ts";
 export declare const DeriveTrait: Tool.Tool<"derive_trait", {
     readonly parameters: S.Struct<{
+        readonly diff: S.optional<S.String>;
+        readonly name: S.brand<S.String, "traits/TraitName">;
         readonly proposedTrait: S.String;
         readonly approved: S.optional<S.Boolean>;
     }>;
     readonly success: S.toTaggedUnion<"_tag", readonly [S.TaggedStruct<"Created", {
-        readonly trait: S.Struct<{
-            readonly id: S.brand<S.String, "traits/Trait">;
+        readonly trait: S.StructWithRest<S.Struct<{
             readonly body: S.String;
-        }>;
+            readonly diff: S.optional<S.String>;
+            readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly skip: S.optional<S.String>;
+            readonly when: S.optional<S.String>;
+        }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
     }>, S.TaggedStruct<"Covered", {
-        readonly traits: S.$Array<S.Struct<{
-            readonly id: S.brand<S.String, "traits/Trait">;
+        readonly traits: S.$Array<S.StructWithRest<S.Struct<{
             readonly body: S.String;
-        }>>;
+            readonly diff: S.optional<S.String>;
+            readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly skip: S.optional<S.String>;
+            readonly when: S.optional<S.String>;
+        }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
     }>, S.TaggedStruct<"Clarification", {
-        readonly traits: S.$Array<S.Struct<{
-            readonly id: S.brand<S.String, "traits/Trait">;
+        readonly traits: S.$Array<S.StructWithRest<S.Struct<{
             readonly body: S.String;
-        }>>;
+            readonly diff: S.optional<S.String>;
+            readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly skip: S.optional<S.String>;
+            readonly when: S.optional<S.String>;
+        }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
         readonly proposedTrait: S.String;
     }>, S.TaggedStruct<"Inconclusive", {
         readonly findings: S.$Array<S.TaggedStruct<"Fail", {
-            readonly existing: S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly existing: S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
             readonly proposed: S.String;
-            readonly reason: S.Literals<readonly ["conflict", "inconclusive"]>;
+            readonly reason: S.Literals<readonly ["conflict", "coverage_gap", "inconclusive"]>;
         }>>;
     }>, S.TaggedStruct<"Updated", {
-        readonly trait: S.Struct<{
-            readonly id: S.brand<S.String, "traits/Trait">;
+        readonly trait: S.StructWithRest<S.Struct<{
             readonly body: S.String;
-        }>;
+            readonly diff: S.optional<S.String>;
+            readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly skip: S.optional<S.String>;
+            readonly when: S.optional<S.String>;
+        }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
     }>, S.TaggedStruct<"Resolved", {
-        readonly traits: S.$Array<S.Struct<{
-            readonly id: S.brand<S.String, "traits/Trait">;
+        readonly traits: S.$Array<S.StructWithRest<S.Struct<{
             readonly body: S.String;
-        }>>;
+            readonly diff: S.optional<S.String>;
+            readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly skip: S.optional<S.String>;
+            readonly when: S.optional<S.String>;
+        }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
     }>, S.TaggedStruct<"ApprovalRequired", {
         readonly message: S.String;
     }>, S.TaggedStruct<"RevisionRequired", {
         readonly feedback: S.String;
     }>, S.TaggedStruct<"Declined", {}>]>;
-    readonly failure: S.Union<readonly [typeof AiError.AiError, S.TaggedStruct<"PlatformError", {
+    readonly failure: S.Union<readonly [S.TaggedStruct<"AiError", {
+        readonly message: S.String;
+    }>, S.Union<readonly [S.Struct<{
+        readonly _tag: S.tag<"TraitNotFoundError">;
+        readonly name: S.brand<S.String, "traits/TraitName">;
+        readonly message: S.String;
+    }>, S.Struct<{
+        readonly _tag: S.tag<"TraitAlreadyExistsError">;
+        readonly name: S.brand<S.String, "traits/TraitName">;
+        readonly message: S.String;
+    }>, S.Struct<{
+        readonly _tag: S.tag<"TraitFilenameMismatchError">;
+        readonly path: S.String;
+        readonly expectedFilename: S.String;
+        readonly message: S.String;
+    }>, S.Struct<{
+        readonly _tag: S.tag<"TraitParseError">;
+        readonly path: S.String;
+        readonly cause: S.Defect;
         readonly message: S.String;
-    }>, typeof McpSchema.ElicitationDeclined]>;
-    readonly failureMode: "error";
+    }>, S.TaggedStruct<"PlatformError", {
+        readonly message: S.String;
+    }>]>, typeof McpSchema.ElicitationDeclined]>;
+    readonly failureMode: "return";
 }, DecisionModel.DecisionModel | LanguageModel.LanguageModel | TraitStore | TraitsContext>;
 export declare const toolkit: Toolkit.Toolkit<{
     readonly derive_trait: Tool.Tool<"derive_trait", {
         readonly parameters: S.Struct<{
+            readonly diff: S.optional<S.String>;
+            readonly name: S.brand<S.String, "traits/TraitName">;
             readonly proposedTrait: S.String;
             readonly approved: S.optional<S.Boolean>;
         }>;
         readonly success: S.toTaggedUnion<"_tag", readonly [S.TaggedStruct<"Created", {
-            readonly trait: S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly trait: S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
         }>, S.TaggedStruct<"Covered", {
-            readonly traits: S.$Array<S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly traits: S.$Array<S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
         }>, S.TaggedStruct<"Clarification", {
-            readonly traits: S.$Array<S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly traits: S.$Array<S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
             readonly proposedTrait: S.String;
         }>, S.TaggedStruct<"Inconclusive", {
             readonly findings: S.$Array<S.TaggedStruct<"Fail", {
-                readonly existing: S.Struct<{
-                    readonly id: S.brand<S.String, "traits/Trait">;
+                readonly existing: S.StructWithRest<S.Struct<{
                     readonly body: S.String;
-                }>;
+                    readonly diff: S.optional<S.String>;
+                    readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                    readonly name: S.brand<S.String, "traits/TraitName">;
+                    readonly skip: S.optional<S.String>;
+                    readonly when: S.optional<S.String>;
+                }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
                 readonly proposed: S.String;
-                readonly reason: S.Literals<readonly ["conflict", "inconclusive"]>;
+                readonly reason: S.Literals<readonly ["conflict", "coverage_gap", "inconclusive"]>;
             }>>;
         }>, S.TaggedStruct<"Updated", {
-            readonly trait: S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly trait: S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>;
         }>, S.TaggedStruct<"Resolved", {
-            readonly traits: S.$Array<S.Struct<{
-                readonly id: S.brand<S.String, "traits/Trait">;
+            readonly traits: S.$Array<S.StructWithRest<S.Struct<{
                 readonly body: S.String;
-            }>>;
+                readonly diff: S.optional<S.String>;
+                readonly mime: S.optional<S.Union<readonly [S.String, S.$Array<S.String>]>>;
+                readonly name: S.brand<S.String, "traits/TraitName">;
+                readonly skip: S.optional<S.String>;
+                readonly when: S.optional<S.String>;
+            }>, readonly [S.$Record<S.String, S.Codec<S.Json, S.Json, never, never>>]>>;
         }>, S.TaggedStruct<"ApprovalRequired", {
             readonly message: S.String;
         }>, S.TaggedStruct<"RevisionRequired", {
             readonly feedback: S.String;
         }>, S.TaggedStruct<"Declined", {}>]>;
-        readonly failure: S.Union<readonly [typeof AiError.AiError, S.TaggedStruct<"PlatformError", {
+        readonly failure: S.Union<readonly [S.TaggedStruct<"AiError", {
+            readonly message: S.String;
+        }>, S.Union<readonly [S.Struct<{
+            readonly _tag: S.tag<"TraitNotFoundError">;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly message: S.String;
+        }>, S.Struct<{
+            readonly _tag: S.tag<"TraitAlreadyExistsError">;
+            readonly name: S.brand<S.String, "traits/TraitName">;
+            readonly message: S.String;
+        }>, S.Struct<{
+            readonly _tag: S.tag<"TraitFilenameMismatchError">;
+            readonly path: S.String;
+            readonly expectedFilename: S.String;
+            readonly message: S.String;
+        }>, S.Struct<{
+            readonly _tag: S.tag<"TraitParseError">;
+            readonly path: S.String;
+            readonly cause: S.Defect;
+            readonly message: S.String;
+        }>, S.TaggedStruct<"PlatformError", {
             readonly message: S.String;
-        }>, typeof McpSchema.ElicitationDeclined]>;
-        readonly failureMode: "error";
+        }>]>, typeof McpSchema.ElicitationDeclined]>;
+        readonly failureMode: "return";
     }, DecisionModel.DecisionModel | LanguageModel.LanguageModel | TraitStore | TraitsContext>;
 }>;
 export declare const layer: import("effect/Layer").Layer<Tool.Handler<"derive_trait">, never, never>;

package/dist/toolkit/DeriveTrait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeriveTrait.d.ts","sourceRoot":"","sources":["../../toolkit/DeriveTrait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC,EAAU,MAAM,QAAQ,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAG3F,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAA;AAE9D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0FA6CW,CAAA;AAEnC,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAA;AAEhD,eAAO,MAAM,KAAK,0EAEhB,CAAA"}
+{"version":3,"file":"DeriveTrait.d.ts","sourceRoot":"","sources":["../../toolkit/DeriveTrait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC,EAAU,MAAM,QAAQ,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAIlF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAA;AAE9D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0FAyDW,CAAA;AAEnC,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAA;AAEhD,eAAO,MAAM,KAAK,0EAEhB,CAAA"}

package/dist/toolkit/DeriveTrait.js

@@ -1,6 +1,7 @@
 import { Schema as S, String } from "effect";
-import { AiError, DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai";
-import { derive, TraitDerivation } from "../TraitDerivation.js";
+import { DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai";
+import * as Trait from "../Trait.js";
+import * as Derivation from "../TraitDerivation.js";
 import { TraitsContext } from "../TraitsContext.js";
 import { TraitStore, TraitStoreError } from "../TraitStore.js";
 export const DeriveTrait = Tool.make("derive_trait", {
@@ -15,40 +16,51 @@ export const DeriveTrait = Tool.make("derive_trait", {
   | If Revise supplies no concrete feedback, ask for revision details with the interactive question UI and free text. Do not guess or set approved: true.
   | Keep the proposal pending through related work and return to it afterward unless cancelled; obtain fresh approval of the complete revised body.
   | First decide whether the feedback generalizes beyond the current task and inspect existing trait files for coverage.
-  | Supply a concise, standalone rule as proposedTrait, preserving its scope and exceptions; omit headings and unnecessary examples.
+  | Supply a concise, standalone rule as proposedTrait, preserving its scope and exceptions; omit headings.
+  | Include a separate diff showing BAD (-) versus GOOD (+) code whenever a useful example applies. Omit it only when a code example is not meaningful. Approval covers the exact diff as well as the body.
+  | Supply a unique descriptive kebab-case name without a redundant trait- prefix for a newly created trait; it is the canonical identity, frontmatter name, and Markdown filename stem. Duplicate names are rejected.
+  | Avoid repeated requirements and duplicate traits. Keep bodies standalone; do not strip essential scope or exceptions just to shorten them.
+  | When authoring trait frontmatter, let mime restrict file types and when define positive semantic scope. Include skip only for an independent exception within that scope, never its negation or a repetition of another field.
+  | Write when values without a leading When, for example when: editing React state.
   | Compare against all stored traits. Only a distinct proposal is saved as a new trait.
   | Inconclusive returns relationship findings and blocks all writes; clarify ambiguity or revise the proposal before retrying.
-  | Confirmed conflicts enter reconciliation within this tool. Approval shows affected trait IDs/bodies, removals, the proposal, and replacement policy.
-  | Nothing is replaced before approval. After approval, generate compatible standalone replacements, save them, then delete only the conflicting originals.
+  | Confirmed conflicts and independently verified coverage gaps enter reconciliation within this tool. Approval shows affected trait names, bodies, applicability metadata, removals, the proposal, and replacement policy.
+  | Nothing is replaced before approval. After approval, validate unique replacement names against unaffected traits, update reused selected names, save new names, then delete only selected originals whose names were not reused.
   | The proposal takes precedence only in direct conflicts; preserve unrelated requirements, scopes, and exceptions. Resolved returns saved replacements.
   | Do not submit the same proposal again after Resolved: it is already incorporated. Inspect replacements and check relevant TypeScript files.
   | Reconciliation is not transactional; on an error, inspect the store before retrying because some writes or removals may have completed.
-  | Covered returns the existing traits representing the proposal; reuse them without writing a duplicate.
+  | Covered requires a second independent decision-model assessment of the saved body and when/mime/skip metadata against every proposed requirement. Similar intent or partial overlap is insufficient. Coverage gaps require approval-gated revision; inconclusive verification blocks writes.
+  | Covered returns only independently verified existing traits; reuse them without writing a duplicate.
   | A single clarification candidate is selected automatically for approval; provide a complete replacement body preserving existing requirements and exceptions.
   | Multiple clarification candidates return Clarification with those traits and the proposal without writing. Refine the proposal or clarify intent.
   | The shared approval flow shows the existing and proposed bodies; ask in the client UI only if ApprovalRequired is returned.
-  | The tool rechecks all traits before updating, preserving the selected ID. Updated returns the saved trait.
+  | The tool rechecks all traits before updating, preserving the selected name on clarification. Updated returns the saved trait.
   | Never use approved: true for an unapproved replacement, and never resolve a mere clarification by deleting traits.
-  | Created returns the saved trait including its generated ID. Every response is one tagged TraitDerivation outcome, never a bare array or void.
-  | Then call check_traits on relevant TypeScript files, using returned trait IDs for focused reviews when appropriate.
+  | Created returns the saved trait including its unique name. Every response is one tagged TraitDerivation outcome, never a bare array or void.
+  | Then call check_traits on relevant TypeScript files, using returned trait names for focused reviews when appropriate.
   `),
     parameters: S.Struct({
+        diff: Trait.TraitDiff.pipe(S.optional),
+        name: Trait.TraitName.annotate({
+            description: "Unique descriptive kebab-case identity and Markdown filename stem without a redundant trait- prefix for a newly created trait. Existing names are preserved on clarification."
+        }),
         proposedTrait: S.String.annotate({
-            description: "The complete reusable rule to save, including scope and exceptions, rather than raw conversation text."
+            description: "A concise, standalone reusable rule with its essential scope and exceptions, not raw conversation text or repeated restatements of the same requirement."
         }),
         approved: S.Boolean.pipe(S.optional).annotate({
             description: "Fallback approval for the exact proposal and automatically selected action shown to the user, including any existing trait being updated. Set true only after approval; native clients still receive a form. Does not bypass relationship checks."
         })
     }),
-    success: TraitDerivation,
-    failure: S.Union([AiError.AiError, TraitStoreError, McpSchema.ElicitationDeclined]),
-    dependencies: [DecisionModel.DecisionModel, LanguageModel.LanguageModel, TraitStore, TraitsContext]
+    success: Derivation.TraitDerivation,
+    failure: S.Union([S.TaggedStruct("AiError", { message: S.String }), TraitStoreError, McpSchema.ElicitationDeclined]),
+    failureMode: "return",
+    dependencies: [DecisionModel.DecisionModel, LanguageModel.LanguageModel, TraitsContext, TraitStore]
 })
     .annotate(Tool.Title, "Derive Trait")
     .annotate(Tool.Readonly, false)
     .annotate(Tool.Destructive, true);
 export const toolkit = Toolkit.make(DeriveTrait);
 export const layer = toolkit.toLayer({
-    derive_trait: derive
+    derive_trait: Derivation.derive
 });
 //# sourceMappingURL=DeriveTrait.js.map

package/dist/toolkit/DeriveTrait.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeriveTrait.js","sourceRoot":"","sources":["../../toolkit/DeriveTrait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE3F,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;IACnD,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2B/B,CAAC;IACF,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC/B,WAAW,EACT,wGAAwG;SAC3G,CAAC;QACF,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC;YAC5C,WAAW,EACT,mPAAmP;SACtP,CAAC;KACH,CAAC;IACF,OAAO,EAAE,eAAe;IACxB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IACnF,YAAY,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,aAAa,CAAC,aAAa,EAAE,UAAU,EAAE,aAAa,CAAC;CACpG,CAAC;KACC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC;KACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;KAC9B,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;AAEnC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;AAEhD,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IACnC,YAAY,EAAE,MAAM;CACrB,CAAC,CAAA"}
+{"version":3,"file":"DeriveTrait.js","sourceRoot":"","sources":["../../toolkit/DeriveTrait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAElF,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AACpC,OAAO,KAAK,UAAU,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;IACnD,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiC/B,CAAC;IACF,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;QACtC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC7B,WAAW,EACT,+KAA+K;SAClL,CAAC;QACF,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC/B,WAAW,EACT,0JAA0J;SAC7J,CAAC;QACF,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC;YAC5C,WAAW,EACT,mPAAmP;SACtP,CAAC;KACH,CAAC;IACF,OAAO,EAAE,UAAU,CAAC,eAAe;IACnC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,eAAe,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IACpH,WAAW,EAAE,QAAQ;IACrB,YAAY,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,aAAa,CAAC,aAAa,EAAE,aAAa,EAAE,UAAU,CAAC;CACpG,CAAC;KACC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,cAAc,CAAC;KACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;KAC9B,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;AAEnC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;AAEhD,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IACnC,YAAY,EAAE,UAAU,CAAC,MAAM;CAChC,CAAC,CAAA"}

package/dist/traitIgnores.d.ts

@@ -1,3 +1,21 @@
 /** File-scoped exceptions must appear in the leading line-comment header and include a reason. */
 export declare const traitIgnores: (text: string) => ReadonlySet<string>;
+/** References match unique trait names exactly. */
+export declare const excludeIgnored: (text: string) => (self: Iterable<{
+    readonly [x: string]: import("effect/Schema").Json;
+    readonly body: string;
+    readonly diff?: string | undefined;
+    readonly mime?: string | readonly string[] | undefined;
+    readonly name: string & import("effect/Brand").Brand<"traits/TraitName">;
+    readonly skip?: string | undefined;
+    readonly when?: string | undefined;
+}>) => {
+    readonly [x: string]: import("effect/Schema").Json;
+    readonly body: string;
+    readonly diff?: string | undefined;
+    readonly mime?: string | readonly string[] | undefined;
+    readonly name: string & import("effect/Brand").Brand<"traits/TraitName">;
+    readonly skip?: string | undefined;
+    readonly when?: string | undefined;
+}[];
 //# sourceMappingURL=traitIgnores.d.ts.map

package/dist/traitIgnores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traitIgnores.d.ts","sourceRoot":"","sources":["../traitIgnores.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,WAAW,CAAC,MAAM,CAU7D,CAAA"}
+{"version":3,"file":"traitIgnores.d.ts","sourceRoot":"","sources":["../traitIgnores.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,WAAW,CAAC,MAAM,CAW7D,CAAA;AAED,mDAAmD;AACnD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;GAE1B,CAAA"}

package/dist/traitIgnores.js

@@ -1,17 +1,20 @@
-import { pipe, String } from "effect";
+import { Array, flow, String } from "effect";
 /** File-scoped exceptions must appear in the leading line-comment header and include a reason. */
 export const traitIgnores = (text) => {
-    const ids = new Set();
+    const references = new Set();
     for (const line of String.split(text, "\n")) {
         const trimmed = String.trim(line);
-        if (trimmed === "" || pipe(trimmed, String.startsWith("#!")))
+        if (trimmed === "" || trimmed.startsWith("#!"))
             continue;
-        if (!pipe(trimmed, String.startsWith("//")))
+        if (!trimmed.startsWith("//"))
             break;
         const match = /^\/\/\s*traits-ignore-file\s+(\S+)\s*:\s*(\S.*)$/.exec(trimmed);
-        if (match?.[1] !== undefined)
-            ids.add(match[1]);
+        const reference = match?.[1];
+        if (reference !== undefined)
+            references.add(reference);
     }
-    return ids;
+    return references;
 };
+/** References match unique trait names exactly. */
+export const excludeIgnored = flow(traitIgnores, (references) => Array.filter((trait) => !references.has(trait.name)));
 //# sourceMappingURL=traitIgnores.js.map

package/dist/traitIgnores.js.map

@@ -1 +1 @@
-{"version":3,"file":"traitIgnores.js","sourceRoot":"","sources":["../traitIgnores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAErC,kGAAkG;AAClG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAuB,EAAE;IAChE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,OAAO,KAAK,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAAE,SAAQ;QACtE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAAE,MAAK;QAClD,MAAM,KAAK,GAAG,kDAAkD,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC9E,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACjD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA"}
+{"version":3,"file":"traitIgnores.js","sourceRoot":"","sources":["../traitIgnores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAI5C,kGAAkG;AAClG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAuB,EAAE;IAChE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAA;IACpC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAQ;QACxD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAK;QACpC,MAAM,KAAK,GAAG,kDAAkD,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC9E,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,IAAI,SAAS,KAAK,SAAS;YAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACxD,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC,CAAA;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,EAAE,CAC9D,KAAK,CAAC,MAAM,CAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC5D,CAAA"}

package/getIncludedFiles.ts

@@ -0,0 +1,42 @@
+import { Array, Effect, Equal, Path, pipe, Schema as S, Stream, String } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
+
+import { TraitsContext } from "./TraitsContext.ts"
+
+export class GitFileListingError extends S.TaggedError<GitFileListingError>()("GitFileListingError", {
+  directory: S.String,
+  exitCode: S.Int.check(S.isGreaterThan(0))
+}) {
+  override get message() {
+    return `git ls-files exited with code ${this.exitCode}`
+  }
+}
+
+export const getIncludedFiles = Effect.gen(function* () {
+  const context = yield* TraitsContext
+  if (!context.config.excludeGitignored) return undefined
+
+  const path = yield* Path.Path
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+  const process = yield* spawner.spawn(
+    ChildProcess.make`git ls-files --cached --others --exclude-standard --full-name -z`.pipe(
+      ChildProcess.setCwd(context.configRoot)
+    )
+  )
+  const output = yield* process.stdout.pipe(Stream.decodeText(), Stream.mkString)
+  yield* process.exitCode.pipe(
+    Effect.filterOrFail(Equal.equals(0), (exitCode) =>
+      GitFileListingError.make({
+        directory: context.configRoot,
+        exitCode
+      })
+    )
+  )
+  return pipe(
+    output,
+    String.split("\0"),
+    Array.filter(String.isNonEmpty),
+    Array.map((file) => path.resolve(context.configRoot, file)),
+    (files) => new Set(files)
+  )
+}).pipe(Effect.scoped, Effect.withSpan("getIncludedFiles"))

package/main.ts

@@ -8,6 +8,7 @@ import { FetchHttpClient } from "effect/http"
 import * as TraitsConfigProvider from "./_util/TraitsConfigProvider.ts"
 import * as TraitsTelemetry from "./_util/TraitsTelemetry.ts"
 import PackageJson from "./package.json" with { type: "json" }
+import * as ConfigurationError from "./toolkit/ConfigurationError.ts"
 import { toolkit } from "./toolkit/toolkit.ts"
 import * as TraitsConfig from "./TraitsConfig.ts"
 import * as TraitStore from "./TraitStore.ts"
@@ -34,8 +35,8 @@ Command.make("traits", {
       version: PackageJson.version,
       protocols: [McpProtocol.v2025_11_25],
       instructions: String.stripMargin(`
-      | Traits are durable, reusable coding preferences stored as .agents/traits/<three_words-uuid>.md in the working directory.
-      | The full filename stem is the trait ID; use it in tool calls, for example rose_karate_frog-<uuid>.
+      | Traits are durable, reusable coding preferences. The filesystem adapter stores each as .agents/traits/<name>.md, with a unique descriptive kebab-case name (no redundant trait- prefix) in frontmatter and no separate id.
+      | The unique name is the canonical identity across storage backends. Use exact names for focused traitNames selections and ignore directives, not filenames. Update references after renaming. Duplicate names are rejected.
       | Before completing a response to a user correction, coding preference, or approved alternative idiom, check whether it expresses a reusable rule.
       | Treat multi-turn exchanges as a whole: asking about a better idiom and then approving it can establish a preference without saying "always" or "trait".
       | Err on the side of proposing a concise trait unless you have read an existing trait that clearly covers the exact rule and its scope.
@@ -51,24 +52,27 @@ Command.make("traits", {
       | Approval to edit code alone is not approval to persist a trait. Make the requested edit, but also propose the reusable rule before your final response.
       | Also act on explicit requests to remember a convention. Skip one-off requirements, transient facts, and preferences already covered.
       | Read existing trait files before drafting. Keep each trait concise and independently applicable, preserving scope and exceptions.
+      | Keep frontmatter complementary: mime restricts file types, when defines positive semantic scope, and skip is only an independent exception within that scope. Omit redundant fields; never repeat when's negation as skip. Keep bodies standalone without repeated requirements or duplicate traits.
+      | Write when values as conditions without a redundant leading When, for example when: editing React state.
       | Call derive_trait with the drafted body as proposedTrait. It saves only distinct rules; Covered means reuse an existing trait.
       | A single clarification candidate is selected automatically and shown for approval; supply a complete replacement preserving the existing rule.
-      | Multiple candidates return Clarification entries without writing: refine the proposal or clarify intent. Do not supply a target ID.
-      | After fallback approval, retry with the same proposedTrait and approved: true; Updated preserves the selected existing ID.
-      | Every derive_trait response is one tagged TraitDerivation outcome. Created returns the saved trait and ID; Updated and Resolved return saved replacements.
+      | Multiple candidates return Clarification entries without writing: refine the proposal or clarify intent. Do not supply a clarification target.
+      | After fallback approval, retry with the same name, proposedTrait and approved: true; Updated preserves the selected existing name.
+      | Every derive_trait response is one tagged TraitDerivation outcome. Created returns the saved trait with its unique name; Updated and Resolved return saved replacements.
       | Covered and Clarification return existing traits without writing. Inconclusive returns relationship findings and blocks all writes.
-      | Each inconclusive outcome's findings distinguish conflict from inconclusive via reason; clarify ambiguity before retrying.
-      | Confirmed conflicts enter reconciliation inside derive_trait, selecting only the conflicting originals for an explicit replacement approval.
-      | Approval must cover affected IDs/bodies, removals, the proposal, and generated reconciliation. Nothing is replaced silently.
-      | After approval, reconciliation gives the proposal precedence in direct conflicts, saves generated replacements, then removes the conflicting originals.
-      | Resolved returns saved replacement bodies and IDs. Review them and check relevant code; do not derive the same proposal again.
+      | Inconclusive outcome findings use reason to distinguish conflict, coverage_gap, and inconclusive; clarify ambiguity before retrying.
+      | Covered requires independent second-pass verification of the saved body and applicability metadata against the complete proposal. Similar intent is insufficient; coverage gaps enter approval-gated reconciliation and inconclusive verification blocks writes.
+      | Confirmed conflicts and verified coverage gaps enter reconciliation inside derive_trait, selecting only the affected originals for an explicit replacement approval.
+      | Approval must cover affected names, bodies, removals, the proposal, and generated reconciliation. Nothing is replaced silently.
+      | After approval, reconciliation gives the proposal precedence in direct conflicts, updates selected names reused by replacements, saves new names, then removes only originals whose names were not reused. Unaffected names and duplicate generated names cannot be overwritten.
+      | Resolved returns saved replacement bodies and unique names. Review them and check relevant code; do not derive the same proposal again.
       | After generating or changing TypeScript files, call check_traits on those files.
       | check_traits accepts include as file paths or glob strings, for example include: ["traits/**/*.ts"]. Overlapping matches are deduplicated.
       | Restrict assessments to project-owned source and relevant authored configuration/docs. Prefer an explicit project-file manifest for whole-project audits.
       | Never submit dependency/reference code, generated build output or lockfiles, Git metadata, secrets, .env files, credentials, or binary assets for assessment.
       | Unmatched patterns select nothing. Built-in exclusions cover dependencies, Git metadata, and nested worktrees; configure project-specific filenames or native glob patterns through TraitsConfig.excludes.
       | After saving or resolving a trait, check the relevant TypeScript files explicitly; creation does not run that review for you.
-      | Omit traitIds for all traits; use specific IDs for focused follow-ups. Before committing or opening a PR, review the changed TypeScript files.
+      | Omit traitNames for all traits; use specific names for focused follow-ups. Before committing or opening a PR, review the changed TypeScript files.
       | Checks read current full files in 200-line chunks, not Git diffs. A finding's startLine locates a chunk, not an exact violation.
       | Each finding includes assessment.classification and probabilities: inconclusive is unresolved context, not a confirmed violation. Probabilities are not calibrated guarantees.
       | Take responsibility for trait compliance whenever a violation is discovered, through tool findings or your own inspection.
@@ -90,6 +94,8 @@ Command.make("traits", {
         toolkit.pipe(
           Layer.provide(TraitStore.layerFileSystem(".agents/traits")),
           Layer.provide(TraitsConfig.layer),
+          Layer.provide(TraitsConfigProvider.layer),
+          Layer.catchCause(ConfigurationError.layer),
           Layer.provideMerge(McpServer.McpServer.layer)
         )
       ),
@@ -97,7 +103,6 @@ Command.make("traits", {
       Effect.withSpan("traits.server"),
       Effect.provide(
         TraitsTelemetry.layer(Option.getOrUndefined(params.otlpEndpoint)).pipe(
-          Layer.provideMerge(TraitsConfigProvider.layer),
           Layer.provideMerge(FetchHttpClient.layer)
         )
       )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traits",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -21,7 +21,8 @@
     "dist/**/*.js.map",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
-    "!dist/vite.config.*"
+    "!dist/vite.config.*",
+    "!dist/integration/**"
   ],
   "type": "module",
   "exports": {
@@ -34,8 +35,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
   "devDependencies": {
     "@effect/platform-node": "4.0.0",
+    "@effect/vitest": "4.0.0",
     "effect": "4.0.0"
   },
   "peerDependencies": {