traits 0.5.0 → 0.5.2

package/toolkit/CheckTraits.ts

@@ -1,10 +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 * 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"
 
@@ -21,7 +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.
+  | 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.
@@ -35,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,
@@ -70,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) => {
@@ -122,13 +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 activeTraits = pipe(traits, excludeIgnored(text))
         const chunks = Array.chunksOf(String.split(text, "\n"), 200)
         const sources = Array.map(chunks, (lines, index) =>
           Source.make({
@@ -136,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(traits, (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/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

@@ -0,0 +1,22 @@
+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 references = new Set<string>()
+  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>((trait) => !references.has(trait.name))
+)