traits 0.4.0 → 0.5.1

package/main.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Effect, Layer, Logger, Option, Schema as S, String } from "effect"
+import { McpProtocol, McpServer } from "effect/ai"
+import { Command, Flag } from "effect/cli"
+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 { toolkit } from "./toolkit/toolkit.ts"
+import * as TraitsConfig from "./TraitsConfig.ts"
+import * as TraitStore from "./TraitStore.ts"
+
+Command.make("traits", {
+  otlpEndpoint: Flag.String("otlp-endpoint").pipe(
+    Flag.withSchema(
+      S.URLFromString.check(
+        S.makeFilter(
+          (url) => url.protocol === "http:" || url.protocol === "https:" || "Use an HTTP(S) collector base URL."
+        )
+      )
+    ),
+    Flag.withDescription(
+      "Export traces and logs as OTLP/HTTP JSON to this collector base URL (for example, http://127.0.0.1:4318). Disabled when omitted."
+    ),
+    Flag.optional
+  )
+}).pipe(
+  Command.withDescription("Run the traits MCP server over stdio"),
+  Command.withHandler((params) =>
+    McpServer.layerStdio({
+      name: "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>.
+      | 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.
+      | If coverage is uncertain, propose the rule rather than silently assuming a broad trait covers it. If clearer wording is needed, propose a clarification.
+      | Call the mutation tool with the drafted proposal first, leaving approved unset. Do not ask separately beforehand: native clients get an approval form.
+      | derive_trait uses native MCP forms when usable, or returns ApprovalRequired with the complete proposal for that same interactive question flow.
+      | Only on ApprovalRequired, show the full message using the interactive question tool: Save, Revise, Skip, plus its automatic free-text option. Use plain text only if that UI is unavailable.
+      | Retry an identical approved proposal with approved: true; do not assert approval for changed wording or targets. Native forms still apply on supported clients.
+      | RevisionRequired contains feedback to incorporate before requesting approval again; Declined means stop without writing.
+      | Revise without actionable feedback requires an immediate interactive question asking what to change; never guess or treat it as Save.
+      | Keep a revision pending across related audits or follow-up tasks. Complete that work, then return to the proposal unless explicitly cancelled.
+      | Show the complete revised proposal and obtain fresh approval before saving; a findings summary does not resolve a pending revision.
+      | 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.
+      | 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.
+      | 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.
+      | 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.
+      | 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.
+      | Inspect each finding against its trait, scope, exceptions, and surrounding source; confirmed violations must be fixed without waiting for another user request.
+      | Make minimal behavior-preserving edits to the implementation, not to the trait merely to silence a finding. Do not stop at a findings summary.
+      | Rerun check_traits on every corrected file, then run relevant formatting, type, and behavior checks; repeat for remaining confirmed violations.
+      | Triage raw findings against the exact rule, scope, exceptions, and source before reporting or editing. Do not blindly change correct code.
+      | Routine user summaries should report confirmed issues, meaningful unresolved uncertainty, operational failures, and blockers requiring a decision.
+      | Do not repeat rejected, irrelevant false positives as caveats or make them sound actionable. Keep raw results available in tool output and telemetry.
+      | Discuss a rejected finding when the user requests audit details or it reveals a new material reliability problem; explain why it was rejected.
+      | Never suppress actionable findings based only on confidence, assume a finding is false because similar ones were wrong, or claim an automated clean pass when raw findings remain.
+      | If a fix requires a behavior change, broader authorization, or an ambiguous interpretation, ask a focused question and report the blocker.
+      | Do not claim compliance while confirmed violations remain. Report model errors as incomplete reviews, not passes.
+      | An empty result only means no failures for the selected files and traits; empty selections or an empty store perform no assessments.
+      | On mutation errors, inspect the store before retrying: writes and removals are not transactional, and retries may duplicate saved traits.
+      `)
+    }).pipe(
+      Layer.provide(
+        toolkit.pipe(
+          Layer.provide(TraitStore.layerFileSystem(".agents/traits")),
+          Layer.provide(TraitsConfig.layer),
+          Layer.provideMerge(McpServer.McpServer.layer)
+        )
+      ),
+      Layer.launch,
+      Effect.withSpan("traits.server"),
+      Effect.provide(
+        TraitsTelemetry.layer(Option.getOrUndefined(params.otlpEndpoint)).pipe(
+          Layer.provideMerge(TraitsConfigProvider.layer),
+          Layer.provideMerge(FetchHttpClient.layer)
+        )
+      )
+    )
+  ),
+  Command.run({ version: PackageJson.version }),
+  Effect.provide(NodeServices.layer),
+  Effect.tapCause(Effect.logError),
+  Effect.provideService(Logger.LogToStderr, true),
+  NodeRuntime.runMain({ disableErrorReporting: true })
+)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "traits",
+  "version": "0.5.1",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crosshatch/traits.git",
+    "directory": "traits"
+  },
+  "bin": {
+    "traits": "./dist/bin.js"
+  },
+  "files": [
+    "*.ts",
+    "!vite.config.ts",
+    "_util/**/*.ts",
+    "skills/**/*.md",
+    "toolkit/**/*.ts",
+    "dist/package.json",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "!dist/vite.config.*"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js",
+    "./_util/*": null,
+    "./index": null
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0",
+    "effect": "4.0.0"
+  },
+  "peerDependencies": {
+    "@effect/platform-node": "4.0.0",
+    "effect": "4.0.0"
+  }
+}

package/skills/traits/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: traits
+description: >-
+  Use when the user corrects an approach, expresses a reusable coding
+  preference, approves an alternative idiom, or asks to remember a convention;
+  when reconciling conflicting traits; and after generating or editing
+  TypeScript files or before committing them.
+---
+
+# 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.
+
+## Capture a reusable insight
+
+### Required pre-response preference check
+
+Before finishing a response to a correction, preference, or approved alternative
+idiom, evaluate the exchange for a reusable rule. Read the conversation across
+turns: "Can we use the case guard?" followed by "Excellent. Please do"
+establishes a candidate preference even without the words "always", "prefer", 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 scope. Do not silently assume a
+broad convention covers a specific idiom. If coverage is uncertain, propose the
+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.
+
+### Shared approval protocol
+
+`derive_trait` uses `_util/Approval.request` for creation, clarification, and
+reconciliation. Clients with usable MCP form elicitation receive
+approve/revise/skip choices and an optional feedback field. OpenCode currently
+routes native forms globally, so the helper returns `ApprovalRequired`; clients
+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
+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.
+
+Selecting **Revise** is not approval and does not cancel the proposal. If no
+specific revision feedback was supplied, immediately ask what wording, scope, or
+exception the user wants changed using the interactive question tool with
+free-text input. Do not guess a revision or retry the mutation with
+`approved: true`. Native `RevisionRequired` without actionable feedback follows
+the same procedure.
+
+Keep the original proposal and its pending revision in the conversation until
+the user approves a replacement or explicitly skips/cancels it. A related audit,
+code change, or follow-up question does not silently resolve the pending choice:
+complete that work and then return to the revision request. If that request
+already supplies the desired change, incorporate it, present the complete
+revised proposal through the approval flow, and obtain fresh approval. Do not
+finish by only reporting an audit while forgetting the pending proposal.
+
+The fallback approval flag applies to creation, clarification, and resolution.
+It does not bypass relationship checks or suppress native forms on capable
+clients. Pending, revision, and decline outcomes never write files. Resolution
+approval covers the displayed originals, their deletion, the proposal, and
+model-generated reconciliation; inspect returned replacements after saving. The
+flag relies on the agent honoring exact user approval; it is not an
+authenticated consent token.
+
+1. Notice user corrections and recurring preferences without waiting for an
+   explicit mention of traits. Also handle explicit requests to remember a rule.
+2. Distinguish a durable convention from a one-off task, transient fact, or
+   vague reaction. Read existing traits and reuse covered rules rather than
+   duplicating them. Clarify ambiguous scope before drafting.
+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.
+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.
+
+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.
+
+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.
+
+## 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
+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.
+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,
+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.
+
+Inspect those replacements. Do not call `derive_trait` again for the same
+proposal: resolution has already saved its content. The initial comparison
+covers all stored traits, but generated replacements are not automatically
+revalidated against unaffected traits; review the replacements and check the
+relevant code.
+
+Writes and removals are not transactional. If resolution fails, inspect the
+store before retrying; some changes may already be present.
+
+## Check the implementation
+
+### Required review procedure
+
+1. Before editing, read the stored trait bodies and identify which apply to the
+   planned work. Do not rely on filenames, remembered summaries, or examples
+   alone; preserve each rule's scope and exceptions.
+2. Track every TypeScript file you generate or modify, including files changed
+   while fixing findings. Review the final on-disk contents, not an earlier
+   version or only the initial set of files.
+3. Independently inspect each changed section against every applicable trait. An
+   empty tool result does not replace direct inspection against the trait text.
+   Formatting, lint, and type checks do not establish trait compliance.
+4. For recognizable patterns, search explicitly and inspect matches. For the
+   curried-call rule, look for nested calls such as `fn(args)(value)`, including
+   multiline forms and `yield* S.decodeUnknownEffect(schema)(input)`. Check the
+   actual signature before deciding whether a match is a violation. Also inspect
+   parameter destructuring, manually constructed tagged-union members, wrapped
+   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;
+   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
+   file changes again, its earlier result is stale and it must be rechecked.
+7. Keep automated results and manual triage distinct. Routine summaries should
+   report confirmed issues, meaningful unresolved uncertainty, operational
+   failures, and blockers requiring a user decision—not every raw finding.
+   Preserve the reviewed scope and raw results for audit without repeating
+   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 <full-trait-id>: 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.
+
+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,
+  especially the replacements returned by resolution. An empty array selects no
+  traits; unknown IDs 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
+  traversal always excludes dependencies, Git metadata, and nested worktrees.
+  `TraitsConfig.excludes` adds filenames or native filesystem glob patterns,
+  relative to the directory containing `traits.ts` or absolute. Use
+  `directory/**` to exclude a subtree; bare directories are not expanded
+  automatically. Escape glob characters in literal filenames using native glob
+  syntax. This repository configures `repos/**` and `**/dist/**` in `traits.ts`.
+  No custom path classification or glob expansion semantics are imposed.
+- Assess only project-owned source and relevant authored configuration or
+  documentation. For whole-project audits, prefer an explicit project-file
+  manifest. Never submit third-party/reference code, generated output or
+  lockfiles, secrets, `.env` files, credentials, or binary assets. Reading a
+  dependency's source to verify an API does not make it part of the audit scope.
+- The tool checks current full files in 200-line chunks, including unstaged
+  content. It does not inspect the Git index or compute a diff.
+- Each expression finding contains the trait and source excerpt with a file path
+  and 1-based chunk starting line. That line is not an exact violation location.
+  Its `assessment` includes classification and probabilities. `inconclusive` is
+  not a confirmed violation. Inspect the full distribution; probabilities are
+  not calibrated guarantees.
+- Inspect the code and trait before fixing a finding. Respect scope and
+  exceptions; missing context is not proof of a violation.
+- Own the remediation loop whenever you discover an applicable violation,
+  whether from this tool or your own inspection. Automatically make minimal,
+  behavior-preserving fixes without waiting for another user request; a findings
+  summary alone is not completion. This tool diagnoses; the agent makes edits.
+- Recheck every corrected file and run relevant formatting, type, and behavior
+  checks. Repeat for remaining confirmed violations. Do not weaken or rewrite
+  traits merely to silence findings, and do not change correct code for false
+  positives or inapplicable rules.
+- Do not repeat rejected, irrelevant false positives or already-justified
+  exceptions in routine user summaries. Explain them when the user requests an
+  audit, needs a decision, or a new material reliability problem is discovered.
+  If a fix requires changed behavior, broader authorization, or resolving
+  ambiguity, ask a focused question and report the blocker rather than silently
+  expanding scope. Do not claim compliance while confirmed violations remain;
+  model errors make the review incomplete, not passing.
+
+### Reporting triage
+
+Before presenting a finding, establish that the rule applies and identify the
+actual offending code. A helper parameter is not a model-visible tool parameter;
+local destructuring is not parameter destructuring. Check the exact scope and
+exceptions rather than treating a matching topic as a violation.
+
+Fix confirmed applicable violations within scope and verify the fix. Surface
+remaining actionable issues, material uncertainty, failed/incomplete checks, and
+decisions the user must make. Routine completion messages can state which build,
+lint, and type checks passed without adding distracting checker false positives.
+Do not imply that a rejected finding requires work or that the automated trait
+review returned no findings when it did.
+
+Keep unmodified raw assessments available in tool output or configured
+telemetry; do not change tool filtering or introduce probability cutoffs to hide
+inconvenient results. Low confidence alone is not grounds for dismissal, and
+earlier false positives do not justify rejecting a new finding without
+inspecting it. A newly discovered systemic reliability issue remains worth
+reporting. When asked for audit details, distinguish confirmed, unresolved, and
+rejected findings and give the rejection rationale. Quiet reporting is not
+skipped remediation or lost signal.
+
+- Before committing or opening a PR, review the changed TypeScript files against
+  all traits. An empty result means no failures for the selection; empty
+  selections, unmatched patterns, or an empty trait store perform no
+  assessments.
+
+## 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.
+
+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
+from repository-root `traits.ts`. Import the `TraitsConfig` type from `traits`
+and use `export default { ... } satisfies TraitsConfig`. Specify
+`layerDecisionModel` and `layerLanguageModel`; `excludes` is optional. The CLI
+supplies platform/HTTP services. Storage remains local and has no source
+configuration. The current configuration uses TypeSafe for decisions and OpenAI
+for generation, requiring `TYPESAFE_API_KEY` and `OPENAI_API_KEY`. Configuration
+precedence is process environment, worktree-root `.env`, then main-checkout
+`.env`. Reconnect the MCP server after changing credentials. A failed model
+request is an incomplete review, not a pass.
+
+The project MCP command leaves telemetry disabled. For optional OTLP telemetry,
+launch with `npx traits --otlp-endpoint http://127.0.0.1:4318`. The flag is an
+OTLP/HTTP collector base URL; traces and logs go to `/v1/traces` and `/v1/logs`
+beneath it using JSON, with service name `traits` and the package version.
+Metrics are not exported. Omit the flag to disable exports. URLs must use
+HTTP(S). Base paths and query parameters are preserved; fragments are ignored.
+Avoid credentials in command-line URLs. Stderr logging remains enabled; stdout
+stays reserved for MCP.
+
+The CLI does not start a collector or persist telemetry locally. Configure the
+collector's storage, rotation, retention, and access controls separately. Use a
+loopback collector for local debugging and read its configured output files; do
+not assume an output directory exists. Treat telemetry as potentially sensitive:
+spans and logs can include file paths and error text. No full trait bodies,
+source bodies, or authorization headers are intentionally attached by this
+integration, but that is not a blanket redaction guarantee. Do not publish
+collector output without inspection and redaction.

package/toolkit/CheckTraits.ts

@@ -0,0 +1,154 @@
+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 { Source, SourceLocation } from "../Source.ts"
+import { TraitId } from "../Trait.ts"
+import { evaluate, requiresReview, TraitEvaluation } from "../TraitEvaluation.ts"
+import { traitIgnores } from "../traitIgnores.ts"
+import { TraitsContext } from "../TraitsContext.ts"
+import { TraitStore, TraitStoreError } from "../TraitStore.ts"
+
+export const CheckTraits = Tool.make("check_traits", {
+  description: String.stripMargin(`
+  | Use after generating or editing TypeScript files, after saving or resolving a relevant trait, and before committing or opening a PR.
+  | Assess only project-owned source files and relevant authored configuration or documentation. Do not audit third-party or generated code.
+  | For a whole-project review, prefer an explicit project-file manifest rather than a filesystem-wide glob.
+  | Never submit secrets, .env files, credentials, binary assets, generated lockfiles, dependency trees, or reference repositories for assessment.
+  | Supply include as TypeScript file paths or glob patterns relevant to the work, relative to the MCP working directory or absolute.
+  | Globs are expanded and overlapping matches are checked once. Directories are not reviewed as files; use patterns such as traits/**/*.ts.
+  | Built-in exclusions cover dependency trees, Git metadata, and nested worktrees. Configure project-specific exclusions through TraitsConfig.excludes.
+  | Configured exclusions are filenames or native filesystem glob patterns, resolved beside traits.ts. Use directory/** to exclude a subtree; bare directories are not expanded.
+  | 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.
+  | 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.
+  | Act on the results: inspect every finding and automatically fix confirmed, applicable violations without waiting for a separate request.
+  | Make minimal behavior-preserving code changes, then rerun this tool on the corrected files and run relevant project checks.
+  | Repeat for remaining confirmed violations; returning a findings summary alone does not complete the review.
+  | Do not weaken a trait to make code pass or change correct code for an inapplicable or inconclusive finding.
+  | Triage each finding before reporting it. Routine summaries should surface confirmed issues, meaningful unresolved uncertainty, errors, and decision blockers.
+  | Do not distract the user with rejected, irrelevant false positives; retain raw results in tool output for audit and explain them when requested or materially significant.
+  | Do not hide actionable findings based only on probability/confidence or claim the automated check was clean when raw findings remain.
+  | 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.
+  `),
+  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."
+    })
+  }),
+  success: S.Array(TraitEvaluation),
+  failure: S.Union([AiError.AiError, TraitStoreError]),
+  dependencies: [
+    DecisionModel.DecisionModel,
+    TraitStore,
+    FileSystem.FileSystem,
+    Path.Path,
+    ChildProcessSpawner.ChildProcessSpawner,
+    TraitsContext
+  ]
+})
+  .annotate(Tool.Title, "Check Traits")
+  .annotate(Tool.Readonly, true)
+  .annotate(Tool.Destructive, false)
+
+export const toolkit = Toolkit.make(CheckTraits)
+
+export const layer = toolkit.toLayer({
+  check_traits: Effect.fn("CheckTraits.check")(function* (params) {
+    const store = yield* TraitStore
+    const context = yield* TraitsContext
+    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
+      ? store.ls
+      : Effect.forEach(Array.dedupe(params.traitIds), store.get, { concurrency: "unbounded" })
+    const matches = yield* Effect.forEach(
+      params.include,
+      (pattern) => {
+        const absolute = path.isAbsolute(pattern) ? pattern : `${cwd}${path.sep}${pattern}`
+        return fs.glob(absolute, {
+          root: context.configRoot,
+          exclude: context.excludes
+        })
+      },
+      { concurrency: "unbounded" }
+    )
+    const resolved = pipe(
+      matches,
+      Array.flatten,
+      Array.map((file) => path.resolve(context.configRoot, file)),
+      Array.dedupe
+    )
+    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")),
+      { concurrency: "unbounded" }
+    )
+    const results = 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 chunks = Array.chunksOf(String.split(text, "\n"), 200)
+        const sources = Array.map(chunks, (lines, index) =>
+          Source.make({
+            text: Array.join(lines, "\n"),
+            location: SourceLocation.cases.File.make({ path: file, startLine: index * 200 + 1 })
+          })
+        )
+        const results = yield* Effect.forEach(
+          sources,
+          (source) => Effect.forEach(activeTraits, (trait) => evaluate(trait, source), { concurrency: "unbounded" }),
+          { concurrency: "unbounded" }
+        )
+        return pipe(results, Array.flatten, Array.filter(requiresReview))
+      }),
+      { concurrency: "unbounded" }
+    )
+    return Array.flatten(results)
+  })
+})