traits 0.5.0 → 0.5.2

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

@@ -0,0 +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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,20 @@
+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 references = new Set();
+    for (const line of String.split(text, "\n")) {
+        const trimmed = String.trim(line);
+        if (trimmed === "" || trimmed.startsWith("#!"))
+            continue;
+        if (!trimmed.startsWith("//"))
+            break;
+        const match = /^\/\/\s*traits-ignore-file\s+(\S+)\s*:\s*(\S.*)$/.exec(trimmed);
+        const reference = match?.[1];
+        if (reference !== undefined)
+            references.add(reference);
+    }
+    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

@@ -0,0 +1 @@
+{"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

@@ -7,7 +7,6 @@ import { FetchHttpClient } from "effect/http"
 
 import * as TraitsConfigProvider from "./_util/TraitsConfigProvider.ts"
 import * as TraitsTelemetry from "./_util/TraitsTelemetry.ts"
-import { init } from "./commands/init.ts"
 import PackageJson from "./package.json" with { type: "json" }
 import { toolkit } from "./toolkit/toolkit.ts"
 import * as TraitsConfig from "./TraitsConfig.ts"
@@ -35,8 +34,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.
@@ -52,24 +51,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.
@@ -104,7 +106,6 @@ Command.make("traits", {
       )
     )
   ),
-  Command.withSubcommands([init]),
   Command.run({ version: PackageJson.version }),
   Effect.provide(NodeServices.layer),
   Effect.tapCause(Effect.logError),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traits",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -8,13 +8,12 @@
     "directory": "traits"
   },
   "bin": {
-    "traits": "./dist/main.js"
+    "traits": "./dist/bin.js"
   },
   "files": [
     "*.ts",
     "!vite.config.ts",
     "_util/**/*.ts",
-    "commands/**/*.ts",
     "skills/**/*.md",
     "toolkit/**/*.ts",
     "dist/package.json",
@@ -22,7 +21,8 @@
     "dist/**/*.js.map",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
-    "!dist/vite.config.*"
+    "!dist/vite.config.*",
+    "!dist/integration/**"
   ],
   "type": "module",
   "exports": {
@@ -35,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": {

package/skills/traits/SKILL.md

@@ -10,10 +10,39 @@ description: >-
 # Traits
 
 Traits are concise, durable coding rules. The filesystem implementation stores
-each body in `.agents/traits/<three_words-uuid>.md`, relative to its working
-directory. The full filename stem is the trait ID, for example
-`rose_karate_frog-2535ceab-5702-4ab4-932a-f87362adf8c6`. Read these files to
-discover existing rules and IDs; pass the full ID, not just the words, to tools.
+each body in `.agents/traits/<name>.md`, relative to its working directory.
+Frontmatter contains a unique descriptive kebab-case `name` without a redundant
+`trait-` prefix and no separate `id`. The name is the canonical identity across
+backends: use exact names for focused `check_traits({ traitNames: [...] })`
+selections and ignore directives, not filenames. Duplicate names are rejected.
+Renaming changes identity and requires updating references. Construct complete
+records with the schema's `Trait.Trait.make`. `TraitStore` persists complete
+traits and uses names for get, update, and remove. Updates retain the name; a
+rename requires adding the new name and removing the old one after saving. The
+`TraitStore` service class declares its shape inline; use
+`TraitStore["Service"]` for its implementation type. Its filesystem layer is
+colocated in the same module. Only the filesystem adapter builds `<name>.md`
+paths.
+
+Include a concise BAD-to-GOOD code example whenever meaningful. Pass its raw
+unified diff as `diff` to `derive_trait` (removed `-` lines are BAD, added `+`
+lines are GOOD), separately from `proposedTrait`. Omit it only when a code
+example does not apply. Approval and retries cover the exact diff too. On disk,
+`diff` is not frontmatter: put it in a Markdown `diff` fence directly after the
+frontmatter, followed by a blank line, `---`, and the standalone body. Keep
+examples out of the body and preserve them when updating a trait unless the
+updated rule needs a changed example.
+
+Keep frontmatter fields complementary. `mime` restricts file types; `when`
+defines positive semantic scope. Write `when` values without a leading "When",
+such as `when: editing React state`. Add `skip` only for an independent
+exception inside that scope, not for its negation or a restriction already
+expressed by another field. For example,
+`when: importing from local project modules` already excludes external packages;
+do not repeat that as a skip. Leave unnecessary optional fields absent. Keep the
+body concise and standalone, preserving essential scope and exceptions without
+repeated restatements. Reuse existing traits that already cover the same rule
+rather than creating duplicates.
 
 ## Capture a reusable insight
 
@@ -32,15 +61,23 @@ rule; if an existing rule needs clearer wording, propose a clarification. Skip
 only clearly one-off requests, transient facts, or rules you can identify as
 already covered.
 
-Call `derive_trait` with the drafted rule first, leaving `approved` unset. Do
-not ask for approval separately before invoking: capable clients receive a
-native MCP form. Only if `ApprovalRequired` is returned, show the complete
-message in the interactive question tool with **Save trait**, **Revise**, and
-**Skip** and its automatic free-text option. Do not add a duplicate "Other"
-option. Use plain text only if that UI is unavailable. Approval to edit code
-alone does not approve persisting a trait: make the requested edit and propose
-the reusable rule before the final response. Do not stop after implementing an
-idiom and running code checks; preference capture is a separate responsibility.
+When coverage is uncertain, call `derive_trait` with the specific preference; do
+not skip capture because a broad trait or a combination of general traits seems
+related. Let the tool assess coverage or clarification. For example, “prefer
+Effect utilities” and “pass callbacks directly” are not sufficient grounds to
+skip proposing “prefer native inline checks and use Effect predicate helpers
+directly in callbacks or existing pipelines.”
+
+Call `derive_trait` with the drafted rule and a descriptive kebab-case `name`
+first, leaving `approved` unset. Do not ask for approval separately before
+invoking: capable clients receive a native MCP form. Only if `ApprovalRequired`
+is returned, show the complete message in the interactive question tool with
+**Save trait**, **Revise**, and **Skip** and its automatic free-text option. Do
+not add a duplicate "Other" option. Use plain text only if that UI is
+unavailable. Approval to edit code alone does not approve persisting a trait:
+make the requested edit and propose the reusable rule before the final response.
+Do not stop after implementing an idiom and running code checks; preference
+capture is a separate responsibility.
 
 ### Shared approval protocol
 
@@ -52,7 +89,7 @@ without form support use the same fallback.
 
 On `ApprovalRequired`, show its complete message in the interactive question UI
 with Save/Revise/Skip and free text. Save permits retrying the identical body
-and target IDs with `approved: true`. Revision or free-text input requires
+and target names with `approved: true`. Revision or free-text input requires
 drafting the changed proposal and asking approval again, not silently setting
 approved. Skip means stop. Native `RevisionRequired` and `Declined` have the
 same meanings. Transport errors are failures, never declines or approvals.
@@ -88,45 +125,50 @@ authenticated consent token.
 3. Draft the complete rule as `proposedTrait`. Preserve essential requirements,
    scopes, and exceptions. Keep independently applicable rules separate; omit
    headings, repetition, and unnecessary explanation or examples.
-4. Call `derive_trait({ proposedTrait })` first, without a separate approval
-   prompt. This checks existing traits and writes only when the proposal is
-   distinct from all of them. It does not independently decide whether the
-   conversation contains a generalizable insight.
-5. `Created` means the trait was saved and includes its body and generated ID.
-   Do not submit it again. Use that ID for focused checks when needed.
+4. Call `derive_trait({ name, proposedTrait })` first, without a separate
+   approval prompt. This checks existing traits and writes only when the
+   proposal is distinct from all of them. It does not independently decide
+   whether the conversation contains a generalizable insight.
+5. `Created` means the trait was saved and includes its body and unique name. Do
+   not submit it again. Use that name for focused checks when needed.
 6. `Inconclusive` means nothing was saved and contains relationship findings;
    each finding's `reason` distinguishes conflict from inconclusive. Any
    inconclusive comparison blocks all writes. Inspect the existing bodies and
-   IDs, clarify ambiguity, or revise the proposal. Confirmed conflicts otherwise
-   enter approval-gated reconciliation within this same tool.
-
-`Covered.traits` means existing traits already express the proposal; reuse them
-without creating a duplicate. When there is exactly one clarification candidate
-and no covered or blocking result, the tool selects it automatically and
-requests approval of its current body and complete replacement. The proposal
-must preserve the existing rule's intent, requirements, scope, and exceptions;
-the tool does not generate a merged replacement from an incremental hint.
+   names, clarify ambiguity, or revise the proposal. Confirmed conflicts
+   otherwise enter approval-gated reconciliation within this same tool.
+
+`Covered.traits` requires an independent second decision-model check of the
+saved body and when, mime, and skip metadata against the entire proposal.
+Partial overlap or similar intent is insufficient. Verified coverage gaps enter
+approval-gated reconciliation, including needed applicability updates;
+inconclusive verification blocks writes. `Covered.traits` means existing traits
+already express the proposal; reuse them without creating a duplicate. When
+there is exactly one clarification candidate and no covered or blocking result,
+the tool selects it automatically and requests approval of its current body and
+complete replacement. The proposal must preserve the existing rule's intent,
+requirements, scope, and exceptions; the tool does not generate a merged
+replacement from an incremental hint.
 
 Multiple candidates return `Clarification` with `traits` and `proposedTrait`
 without writing. Refine the proposal or clarify intent rather than choosing an
-ID arbitrarily. Do not supply a clarification target parameter.
+name arbitrarily. Do not supply a clarification target parameter.
 
 Use the interactive question UI only on `ApprovalRequired`, then retry the same
 `proposedTrait` with `approved: true` after Save. The tool rechecks every
-existing trait and preserves the selected ID on update. If the store or selected
-action changes between approval and retry, obtain fresh approval rather than
-reusing the flag. `Updated` returns the saved trait. Never claim approval not
-given by the user or delete a trait merely needing clearer wording.
+existing trait and preserves the selected name on clarification. If the store or
+selected action changes between approval and retry, obtain fresh approval rather
+than reusing the flag. `Updated` returns the saved trait. Never claim approval
+not given by the user or delete a trait merely needing clearer wording.
 
 ## Reconcile conflicting traits
 
 `derive_trait` checks the proposal against every stored trait and automatically
 selects confirmed conflicts for reconciliation. There is no separate resolution
-tool and no ID-selection parameter. Inconclusive comparisons block
+tool and no trait-selection parameter. Inconclusive comparisons block
 reconciliation rather than authorizing deletion.
 
 Before writing, the shared approval flow shows the selected originals with their
-IDs and bodies, the proposal, the removal plan, and the replacement policy.
+names and bodies, the proposal, the removal plan, and the replacement policy.
 Approval authorizes model-generated reconciliation, not silent deletion. On
 `ApprovalRequired`, ask through the interactive UI and retry the same proposal
 with `approved: true` only after Save. If relationships or originals change,
@@ -135,8 +177,10 @@ obtain fresh approval.
 After approval, the tool evaluates each body and the proposal for decomposition,
 then generates standalone replacements. The proposal takes precedence in direct
 conflicts; unrelated requirements, scopes, and exceptions should be preserved.
-It saves the replacements before deleting the selected originals and returns
-`Resolved` with the saved traits and their new IDs.
+It validates replacement names against each other and unaffected traits before
+writing. It updates selected names reused by replacements, adds new names, then
+deletes only selected originals whose names were not reused. It returns
+`Resolved` with the saved traits and their unique names.
 
 Inspect those replacements. Do not call `derive_trait` again for the same
 proposal: resolution has already saved its content. The initial comparison
@@ -168,7 +212,7 @@ store before retrying; some changes may already be present.
    schema modifiers, and misplaced imports when their traits apply. Searches
    support review; a lack of matches is not proof that every trait is satisfied.
 5. Call `check_traits` on all changed TypeScript files after the latest edits.
-   Before a commit or PR, omit `traitIds` so every stored trait is checked;
+   Before a commit or PR, omit `traitNames` so every stored trait is checked;
    focused checks supplement rather than replace that final review.
 6. Inspect findings, fix confirmed violations, and repeat direct inspection,
    tool checks, and relevant project verification after fixes. If any reviewed
@@ -180,15 +224,36 @@ store before retrying; some changes may already be present.
    rejected false positives as caveats. Never claim an automated clean pass when
    raw findings remain, or turn an empty result into unconditional compliance.
 
+### Targeted trait exceptions
+
+For a justified file-scoped exception, add a line comment in the leading header,
+before any code:
+
+```ts
+// traits-ignore-file <trait-name>: Explain why this trait cannot apply here.
+```
+
+Each directive requires a nonempty reason and exactly one unique trait name.
+Names are case-sensitive; update directives after renaming a trait. Filenames
+and partial names are not selectors. Repeat the comment for additional
+exceptions. Only the referenced traits are skipped; other traits remain checked.
+Exceptions apply to all file chunks and focused checks. Comments after code are
+ignored.
+
+Read the referenced trait and verify the reason before adding or retaining an
+exception. Do not add directives merely to silence findings: fix applicable
+violations, and ask the user before introducing an exception that overrides
+their preference. Respect existing justified exceptions during manual review.
+
 ### Tool behavior and remediation
 
 - After generating or editing TypeScript files, select those files and call
   `check_traits({ include: files })`.
 - After creating or resolving traits, explicitly review relevant TypeScript
   files. Saving traits does not automatically check code.
-- Omit `traitIds` for the full trait set. Supply IDs for focused follow-ups,
+- Omit `traitNames` for the full trait set. Supply names for focused follow-ups,
   especially the replacements returned by resolution. An empty array selects no
-  traits; unknown IDs fail the call.
+  traits; unknown names fail the call.
 - `include` accepts file paths or glob patterns, absolute or relative to the MCP
   working directory. Overlapping matches are deduplicated; unmatched patterns
   select no files. Use `traits/**/*.ts` rather than a bare directory. Glob
@@ -259,22 +324,35 @@ skipped remediation or lost signal.
 
 ## Operation
 
+The CLI launcher installs project dependencies in its current directory before
+importing the MCP server. Run it from the checkout/workspace root. It selects
+the package manager from `package.json#packageManager` or an unambiguous
+lockfile; the selected executable must be on PATH. Installation preserves
+lockfiles but can execute lifecycle scripts, so only launch in trusted
+checkouts. Allow enough MCP startup time for a cold install and avoid
+simultaneous installations in the same worktree. During development, use
+`node traits/bin.ts` with a Node version supporting native TypeScript execution;
+pass server flags after the filename.
+
+Configuration and providers currently initialize at server startup. Startup
+failures go to stderr and require fixing setup and reconnecting; whether the
+agent can see these diagnostics depends on its MCP client. Expected tool
+failures use MCP error results; unexpected defects receive a generic internal
+error rather than implementation details.
+
 Git-ignored files are excluded by default, with ignore rules refreshed on every
 check. Untracked files do not need to be added to Git to be evaluated. Tracked
 files stay eligible even if ignore rules match them. Set
 `excludeGitignored: false` in `traits.ts` to disable this filter; explicit
 excludes still apply. Git failures fail checks.
 
-Run `npx traits init` from inside the Git checkout to create `traits.ts` at the
-current checkout root. Existing files are preserved; init does not install
-skills. Install this bundled skill with pnpm 12.11+ (`pnpm add -D traits`, then
-approve skills with `pnpm approve`) or, after installing Traits locally, run
-`npx skills add ./node_modules/traits --skill traits` to choose your agents.
-pnpm may need explicit `skills.dirs`; dlx and global installs do not link
-skills. The skills CLI installs a snapshot; rerun after updating Traits.
-Preserve any customizations in older copies and avoid loading duplicate Traits
-skills. Launch the MCP server with `npx traits` from the project root. Configure
-the server in your coding agent and discover its `derive_trait` and
+For setup, follow the canonical guide at
+https://github.com/crosshatch/traits/blob/main/SETUP.md. Respect the consumer's
+package manager and workspace dependency conventions, ask about providers and
+models before writing configuration, and preserve existing settings. The guide
+covers dependencies, credentials, skill installation, MCP connection, and
+troubleshooting. The agent creates traits.ts using the selected providers; there
+is no init command. Discover the connected server's `derive_trait` and
 `check_traits` tools through the client's tool catalog.
 
 The CLI's configuration layer loads and validates the default-exported object