traits 0.5.1 → 0.5.3

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
@@ -186,13 +230,15 @@ For a justified file-scoped exception, add a line comment in the leading header,
 before any code:
 
 ```ts
-// traits-ignore-file <full-trait-id>: Explain why this trait cannot apply here.
+// traits-ignore-file <trait-name>: Explain why this trait cannot apply here.
 ```
 
-Each directive requires a nonempty reason and exactly one full trait ID. 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.
+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
@@ -205,9 +251,9 @@ their preference. Respect existing justified exceptions during manual review.
   `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
@@ -288,11 +334,21 @@ 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.
+Configuration and providers initialize at server startup. If setup fails, the
+connection stays alive with `traits_configuration_error` instead of the normal
+tools. Call it for the original error diagnostics, help the user fix the
+reported error, then restart the Traits MCP server. Diagnostics include the full
+Effect cause and may contain sensitive values embedded in errors. Never ask for
+credentials in chat. Expected tool failures use MCP error results; unexpected
+runtime defects receive a generic internal error rather than implementation
+details.
+
+Stored trait parsing failures return `TraitParseError` with the file path,
+original diagnostic, and migration guidance. Update all stored traits to the
+currently installed package's `Trait` schema and `serialize` format, preserving
+their intent and metadata, then retry. Do not treat the failed operation as a
+successful check. The server stays connected; a restart is not needed for file
+repairs, and no automatic migration is performed.
 
 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

package/toolkit/CheckTraits.ts

@@ -1,11 +1,12 @@
-import { Array, Effect, FileSystem, Path, pipe, PlatformError, Schema as S, Stream, String } from "effect"
-import { AiError, DecisionModel, Tool, Toolkit } from "effect/ai"
-import { ChildProcess, ChildProcessSpawner } from "effect/process"
+import { Array, Effect, FileSystem, flow, Path, pipe, Schema as S, String } from "effect"
+import { DecisionModel, Tool, Toolkit } from "effect/ai"
+import { ChildProcessSpawner } from "effect/process"
 
+import { getIncludedFiles, GitFileListingError } from "../getIncludedFiles.ts"
 import { Source, SourceLocation } from "../Source.ts"
-import { TraitId } from "../Trait.ts"
-import { evaluate, requiresReview, TraitEvaluation } from "../TraitEvaluation.ts"
-import { traitIgnores } from "../traitIgnores.ts"
+import * as Trait from "../Trait.ts"
+import * as Evaluation from "../TraitEvaluation.ts"
+import { excludeIgnored } from "../traitIgnores.ts"
 import { TraitsContext } from "../TraitsContext.ts"
 import { TraitStore, TraitStoreError } from "../TraitStore.ts"
 
@@ -22,8 +23,8 @@ export const CheckTraits = Tool.make("check_traits", {
   | Git-ignored files are excluded by default, with ignore rules refreshed on every call. Untracked files do not need to be added to Git to be evaluated. Tracked files remain eligible even if ignore rules match them. Set excludeGitignored: false in traits.ts to disable this filter; explicit excludes still apply. Git failures fail the check.
   | All entries follow native glob syntax, including escaping filenames with glob characters. No custom directory expansion or literal-path classification is applied.
   | Reads current full file contents, including unstaged edits, and checks each 200-line chunk against the selected traits in parallel.
-   | Omit traitIds to check all stored traits; supply trait ids for a focused check of one or more traits. Unknown IDs fail the call.
-   | A leading // traits-ignore-file <trait-id>: <reason> comment skips only that trait for the entire file, including focused checks. Directives require a reason and must precede code.
+  | Omit traitNames to check all stored traits; supply unique trait names for a focused check. Unknown names fail the call.
+  | A leading // traits-ignore-file <trait-name>: <reason> comment skips that trait for the entire file, including focused checks. Names are case-sensitive and must be updated after renaming. Directives require a reason and must precede code.
   | Returns findings with the trait, source text, absolute path, 1-based chunk startLine, and assessment classification and probabilities.
   | Classification distinguishes violation from inconclusive; probabilities are not calibrated guarantees. No exact offending lines are provided.
   | Diagnose uncertainty using the full distribution, not the selected label alone; inspect source and trait before changing code.
@@ -37,19 +38,26 @@ export const CheckTraits = Tool.make("check_traits", {
   | Ask for clarification when a fix changes behavior or exceeds authorized scope.
   | The tool diagnoses only; the calling agent is responsible for edits, verification, and reporting unresolved blockers.
   | Unmatched patterns select no files. An empty result means no failures for this selection, not a repository-wide guarantee.
-  | Empty include/traitIds lists, no matched files, or an empty store check no pairs.
+  | Empty include/traitNames lists, no matched files, or an empty store check no pairs.
   `),
   parameters: S.Struct({
     include: S.Array(S.String).annotate({
       description:
         "Project-owned source, configuration, or documentation paths/globs, absolute or relative to the MCP working directory. Exclude third-party/generated files, secrets, and binaries. Overlapping matches are deduplicated; unmatched patterns select no files."
     }),
-    traitIds: S.Array(TraitId).pipe(S.optional).annotate({
-      description: "Optional trait ids for a focused review. Omit for all stored traits; an empty array selects none."
+    traitNames: S.Array(Trait.TraitName).pipe(S.optional).annotate({
+      description:
+        "Optional unique trait names for a focused review. Omit for all stored traits; an empty array selects none."
     })
   }),
-  success: S.Array(TraitEvaluation),
-  failure: S.Union([AiError.AiError, TraitStoreError]),
+  success: S.Array(Evaluation.TraitEvaluation),
+  failure: S.Union([
+    S.TaggedStruct("AiError", { message: S.String }),
+    TraitStoreError,
+    S.Struct({ ...Evaluation.TraitAssessmentTooLargeError.fields, message: S.String }),
+    S.Struct({ ...GitFileListingError.fields, message: S.String })
+  ]),
+  failureMode: "return",
   dependencies: [
     DecisionModel.DecisionModel,
     TraitStore,
@@ -72,39 +80,10 @@ export const layer = toolkit.toLayer({
     const fs = yield* FileSystem.FileSystem
     const path = yield* Path.Path
     const cwd = path.resolve()
-    const includedFiles = context.excludeGitignored
-      ? yield* Effect.scoped(
-          Effect.gen(function* () {
-            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)
-            const exitCode = yield* process.exitCode
-            if (exitCode !== 0) {
-              return yield* PlatformError.systemError({
-                _tag: "Unknown",
-                module: "ChildProcess",
-                method: "git ls-files",
-                description: `Process exited with code ${exitCode}`
-              })
-            }
-            return new Set(
-              pipe(
-                output,
-                String.split("\0"),
-                Array.filter(String.isNonEmpty),
-                Array.map((file) => path.resolve(context.configRoot, file))
-              )
-            )
-          })
-        )
-      : undefined
-    const traits = yield* params.traitIds === undefined
+    const includedFiles = yield* getIncludedFiles
+    const traits = yield* params.traitNames === undefined
       ? store.ls
-      : Effect.forEach(Array.dedupe(params.traitIds), store.get, { concurrency: "unbounded" })
+      : Effect.forEach(Array.dedupe(params.traitNames), store.get, { concurrency: "unbounded" })
     const matches = yield* Effect.forEach(
       params.include,
       (pattern) => {
@@ -124,15 +103,17 @@ export const layer = toolkit.toLayer({
     )
     const paths = yield* Effect.filter(
       includedFiles === undefined ? resolved : Array.filter(resolved, (file) => includedFiles.has(file)),
-      (file) => fs.stat(file).pipe(Effect.map((info) => info.type === "File")),
+      flow(
+        fs.stat,
+        Effect.map((info) => info.type === "File")
+      ),
       { concurrency: "unbounded" }
     )
-    const results = yield* Effect.forEach(
+    return yield* Effect.forEach(
       paths,
       Effect.fn("CheckTraits.file")(function* (file) {
         const text = yield* fs.readFileString(file)
-        const ignored = traitIgnores(text)
-        const activeTraits = Array.filter(traits, (trait) => !ignored.has(trait.id))
+        const activeTraits = pipe(traits, excludeIgnored(text))
         const chunks = Array.chunksOf(String.split(text, "\n"), 200)
         const sources = Array.map(chunks, (lines, index) =>
           Source.make({
@@ -140,15 +121,13 @@ export const layer = toolkit.toLayer({
             location: SourceLocation.cases.File.make({ path: file, startLine: index * 200 + 1 })
           })
         )
-        const results = yield* Effect.forEach(
+        return yield* pipe(
           sources,
-          (source) => Effect.forEach(activeTraits, (trait) => evaluate(trait, source), { concurrency: "unbounded" }),
-          { concurrency: "unbounded" }
+          Effect.forEach((source) => Evaluation.evaluateAll(activeTraits, source), { concurrency: "unbounded" }),
+          Effect.map(flow(Array.flatten, Array.filter(Evaluation.requiresReview)))
         )
-        return pipe(results, Array.flatten, Array.filter(requiresReview))
       }),
       { concurrency: "unbounded" }
-    )
-    return Array.flatten(results)
+    ).pipe(Effect.map(Array.flatten))
   })
 })

package/toolkit/ConfigurationError.ts

@@ -0,0 +1,27 @@
+import { Cause, Effect, Layer, Schema as S } from "effect"
+import { McpServer, Tool, Toolkit } from "effect/ai"
+
+const toolkit = Toolkit.make(
+  Tool.make("traits_configuration_error", {
+    description:
+      "Traits failed to initialize. Call this tool to learn where configuration failed. Help the user fix setup, then restart the Traits MCP server before using Traits. Never ask the user to paste credentials into chat.",
+    parameters: Tool.EmptyParams,
+    success: S.Never,
+    failure: S.String,
+    failureMode: "return"
+  }).annotate(Tool.Readonly, true)
+)
+
+export const layer = (cause: Cause.Cause<unknown>) =>
+  Cause.hasInterruptsOnly(cause)
+    ? Layer.effectDiscard(Effect.interrupt)
+    : McpServer.toolkit(toolkit).pipe(
+        Layer.provide(
+          toolkit.toLayer({
+            traits_configuration_error: () =>
+              Effect.fail(
+                `${Cause.pretty(cause)}\n\nFix the reported error, then restart the Traits MCP server and retry. Do not paste credentials into chat.`
+              )
+          })
+        )
+      )

package/toolkit/DeriveTrait.ts

@@ -1,7 +1,8 @@
 import { Schema as S, String } from "effect"
-import { AiError, DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai"
+import { DecisionModel, LanguageModel, McpSchema, Tool, Toolkit } from "effect/ai"
 
-import { derive, TraitDerivation } from "../TraitDerivation.ts"
+import * as Trait from "../Trait.ts"
+import * as Derivation from "../TraitDerivation.ts"
 import { TraitsContext } from "../TraitsContext.ts"
 import { TraitStore, TraitStoreError } from "../TraitStore.ts"
 
@@ -17,36 +18,48 @@ 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."
+        "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)
@@ -55,5 +68,5 @@ export const DeriveTrait = Tool.make("derive_trait", {
 export const toolkit = Toolkit.make(DeriveTrait)
 
 export const layer = toolkit.toLayer({
-  derive_trait: derive
+  derive_trait: Derivation.derive
 })

package/traitIgnores.ts

@@ -1,14 +1,22 @@
-import { pipe, String } from "effect"
+import { Array, flow, String } from "effect"
+
+import type { Trait } from "./Trait.ts"
 
 /** File-scoped exceptions must appear in the leading line-comment header and include a reason. */
 export const traitIgnores = (text: string): ReadonlySet<string> => {
-  const ids = new Set<string>()
+  const references = new Set<string>()
   for (const line of String.split(text, "\n")) {
     const trimmed = String.trim(line)
-    if (trimmed === "" || pipe(trimmed, String.startsWith("#!"))) continue
-    if (!pipe(trimmed, String.startsWith("//"))) break
+    if (trimmed === "" || trimmed.startsWith("#!")) continue
+    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>((trait) => !references.has(trait.name))
+)