AGENTS.md

Agent Notes

TraceDecay is a code-intelligence tool (Rust workspace + TypeScript dashboard) that builds a semantic knowledge graph from many languages and serves it to agent hosts through MCP, hooks, LSP, and an embedded dashboard.

Overall Objective

Deliver a fully integrated final-V2 product through real production journeys, truthful typed states, maintainable crate/module boundaries, and direct behavioral evidence, not PR choreography, gates built only to be checked, or code that merely compiles.

Task completion

Carry the requested change through implementation and relevant verification; fix failures introduced by the change before reporting completion. Use focused checks for affected behavior and broaden only for unresolved risk. Documentation-only edits do not require application builds. Pause for a missing decision or an unauthorized external action after completing independent, authorized work.

Working checkout authority

• Use the checkout supplied by the current task. Resolve its root with git rev-parse --show-toplevel; never assume a machine-specific absolute path.
• Inspect git status --short, git branch --show-current, and git worktree list before changing branches or files. Honor an explicit task branch; otherwise stay on the current branch. For a PR, resolve its head with gh pr view <number> --json headRefName,headRepositoryOwner,headRepository.
• Do not switch branches, merge other work, or create linked worktrees merely because an old plan names them. If the requested checkout or branch is unavailable, report the mismatch instead of substituting an unrelated tree.
• Keep commands and maintained instructions repo-relative. Put machine-local build caches and host settings in local configuration, not mandatory repository guidance.
• Multiple agents may work concurrently in a checkout; preserve peer edits and stage only the paths owned by the current task.

No secondary copies

• Never create or retain rollback copies, profile backups, old databases, old binaries, snapshot clones, or any other secondary copy of project or operator data or installed artifacts. Do not keep a prior version "just in case."
• This includes agent-host configuration. Never copy ~/.claude, ~/.codex, ~/.agents, or their settings, config, plugin, or marketplace files before tracedecay install, update, uninstall, or a manual edit. Preview with --dry-run and rely on the receipt-backed host lifecycle instead.
• An operation that inherently requires temporary staging must remove that staging when it finishes; it must not leave a recoverable old copy behind. Never delete the sole active durable copy under the guise of this cleanup.

Layout

• The repository root is a virtual workspace. It has no package of its own. Every crate lives under crates/.
• crates/tracedecay/, the composition-root library (daemon, MCP tools, global DB, sessions, code index, application services). Its integration suites are crates/tracedecay/tests/, and the ones that use the fixture surface in tests/common/ require test-helpers. Check the selected test target's required-features in Cargo.toml; mcp_suite also requires test-transport.
• crates/tracedecay-cli/, the package that produces the shipped tracedecay binary.
• crates/, the remaining workspace member crates (tracedecay-api, -application, -contracts, -domain, -store, -hooks, -policy, -tool-catalog, rusqlite parity/runtime crates).
• dashboard/, the single embedded dashboard (React + rsbuild + vitest). dashboard/src/contracts/ (from Rust schemas via schemars), and the TypeScript SDK sources in sdks/typescript/src/ plus the Rust descriptors in crates/tracedecay-sdk/src/operations.rs (from the canonical operation registry) are generated. Never hand-edit them; regenerate all of them with the dashboard contracts:generate script and verify with contracts:check.
• plugin/, host bundles (Claude, Codex, Cursor, Kimi, opencode).
• tests/, shared fixtures, distribution suites, and shell/Python gates that no single crate owns; crate-level integration suites and criterion benches live under that crate's own tests/ and benches/.
• benchmark_data/, benchmark fixtures, harnesses, and provenance; evals/, memory, hermetic, and agent-adoption evals; docs/, plans and guides.
• scripts/. CI/dev gates (commit-msg check, bundle checks, release drift).

Build & test

• Bazel is the sole workspace build, test, check, run, benchmark, and code-generation authority. Run bazel build //..., bazel test //... --test_output=errors, bazel run //crates/..., and bazel test //crates/<crate>:<benchmark> --test_arg=--bench for an explicit benchmark target. Benchmarks with Cargo test = false remain compiled by default builds but run only when selected explicitly. Edition 2024, resolver 3, and the toolchain pinned in rust-toolchain.toml remain canonical inputs. Never invoke cargo directly; route every build, test, check, run, bench, and codegen through Bazel.
• pnpm (pinned by packageManager) manages JavaScript packages only. Run pnpm install after cloning and after pnpm-lock.yaml changes. Bazel resolves Rust dependencies from the workspace manifests and Cargo.lock.
• After changing Rust dependencies, run CARGO_BAZEL_REPIN=workspace bazel fetch --repo=@c. Then run bazel run //scripts:gen_builds. Use CARGO_BAZEL_REPIN=<crate> for a targeted dependency update. Commit the refreshed lockfile and generated targets together.
• Code generation: bazel run //sdks/codegen:generate -- <output-root> exports SDK sources; bazel run //sdks/codegen:dashboard_schema -- <output-file> exports the dashboard schema. Dashboard contracts:generate and contracts:check invoke these targets from the repository root.
• Dashboard: pnpm run build (rsbuild), pnpm run typecheck (tsc --noEmit), pnpm test (vitest) from dashboard/.
• libtest --exact requires the full module path and exits 0 when a filter matches nothing. That is a vacuous "0 passed" green. For name-filtered runs prefer the ad-hoc anti-vacuity helper scripts/require-exact-test.sh; it is not a reason to ossify CI or test names. Otherwise pass the full path (module::path::test_name) and confirm the reported count is non-zero before treating a run as evidence.
• The CLI build script is the sole dashboard embedder and stages an immutable bundle under its OUT_DIR; ordinary builds need no environment. When using prebuilt dashboard/app-dist, set TRACEDECAY_SKIP_DASHBOARD_BUILD=1 and the digest from scripts/check-dashboard-bundle.py in TRACEDECAY_DASHBOARD_BUNDLE_SHA256; missing or stale digests fail closed.
• Existing linked worktrees may be cleaned up only through scripts/worktree-gc.py (install its hourly user timer with scripts/install-worktree-gc-timer.sh), or by unlocking and removing the exact owned path. Never remove another lane, select cleanup targets by name prefix, or treat a clean integration-tip lane as abandoned.
• Never re-run tests that are known-red under another active lane; cite the owner instead.

Conventions

• Commits: <type>(<scope>): <subject> (scope optional; full header ≤ 72 chars) with one of build, chore, ci, docs, feat, fix, perf, refactor, revert, simplify, style, test. simplify is a behavior-preserving deletion or dedup; like refactor it is hidden from generated release notes. Every non-merge commit message must pass commitlint (pnpm run lint:commit, configured in commitlint.config.cjs; the .githooks/commit-msg hook runs it locally via scripts/install-git-hooks.sh).
• Integration branch is master (GitHub: ScriptedAlchemy/tracedecay); CI lives in .github/workflows (hidden, search with rg --hidden).
• .github/, .githooks/, and nested AGENTS.md files may carry more specific guidance; the deeper file wins.

Engineering Hygiene

• When ripwire is installed, use its CLI where it shortens the work: orient in unfamiliar subsystems, find and reuse existing symbols, trace callers and impact, select relevant tests, and check a diff before landing (--pr-context, --edit-check, or --quality-delta as appropriate). Ripwire's static graph is coverage-bounded navigation and risk evidence, not final correctness; confirm decisions with focused source reads, compiler checks, and production-behavior tests. Do not block work when it is absent or stale.
• Limits are symptoms, not knobs. For a deadline, admission, memory, or backoff failure, measure the operation (the workspace's tracing spans are the instrumentation surface, and TRACEDECAY_SPAN_TIMINGS=1 logs their close timings) and fix mis-sized work such as N+1 queries, unbatched writes, or accidental serialization. Change a budget only when measurement shows the cost is irreducible, in its own commit with the evidence. Remove investigative overrides before merge. tracing events are the always-compiled operator log surface, tracing spans are the measurement surface, and eprintln! scaffolds never merge.
• Reuse canonical TraceDecay authorities and maintained libraries first. Custom parsers, cursors, caches, retries, transports, registries, schedulers, crypto/auth/policy stores, or filesystem durability layers require a concrete TraceDecay-specific boundary and must delete more complexity than they add; otherwise skip the machinery. Prefer existing workspace dependencies, add a maintained dependency only for clear deletion/complexity benefit, avoid overlapping libraries, and remove a dependency with its last production caller.
• Do not create parallel or shadow authorities, contract-only phases, test-only production ports, mountless features, or availability claims without a real production caller and user journey.
• Accept direct behavior, not bureaucracy. Do not use source-shape/string scans, exact-test-name inventories, PR-specific snapshots/receipts/manifests/attestations, synthetic provider lookalikes, giant Cartesian matrices, or hard-coded gate counts as acceptance. Preserve runtime receipts, migration journals, compare-and-swap, hosted release provenance, and --no-tests=fail.
• Complete cutovers in one delivery slice: migrate every caller and datum, then delete compatibility façades, duplicate routes, old flags, dead aliases, and support code left from the move.
• Keep no legacy or backward-compatibility code. When a shape changes, migrate every caller and delete the old one in the same slice. Old stores, clients, and hosts are refused through the typed reset and refusal paths, never shimmed: no compatibility aliases, deprecation paths, version floors that branch to old behavior, or data migrations.
• Keep boundaries explicit: use top-level explicit imports/reexports, avoid wildcard parent-child cycles and inline imports, maintain one generated wire authority, and do not hand-write duplicate DTOs.
• Keep production failures typed: add no unwrap, expect, panic, silent fallback, fabricated timestamp/default, empty success, or swallowed error. Tests may use assertions and unwraps where appropriate.
• Do not stage dead code or fake readiness with allow(dead_code), placeholders, unreachable enum variants, or feature flags for unfinished production behavior. Wire it now or omit it truthfully.
• Comments and docs explain invariants and why; remove narration, stale PR language, and superseded plan authority. 00-plan-set-index.md is the sole roadmap precedence; historical plans and benchmarks are archival.
• Name production modules, APIs, tests, scripts, and CI jobs for durable product capabilities, not PR numbers, milestones, phases, or temporary gates. Keep PR/milestone labels only in clearly archival plans and benchmark provenance.
• Tests must be falsifiable and cover failure, denial, staleness, isolation, cancellation, and rollback where relevant, without duplicating the same base across every host × OS combination.

Shared work

• Honor active file ownership, preserve peer edits, and stage only coherent owned paths. Coordinate overlap with the owner.
• For shared host behavior, audit every supported integration. For divergent lanes, recover intent from relevant transcripts, plans, and history; compare patch identities and owned paths, discard superseded duplicates, and regenerate canonical outputs after integration.
• Preserve byte-exact identity contracts. Do not weaken assertions, raise timeouts, ignore tests, or mask gate failures.

Learned Workspace Facts

• Durable facts are project-wide and must survive branch or worktree deletion; branch stores are not their authoritative home.
• Linked worktrees share the primary checkout's project/store identity while retaining exact worktree snapshot authority.
• Historical convergence, repair/rebuilds, semantic model acquisition, and indexing run as bounded background work after required fail-closed checks; they must not block admission or exact, lexical, graph, or ordinary retrieval.
• Test fixtures must use shared production identity and enrollment authorities, isolate home, profile, project, and session inputs, and never read or mutate the operator's real TraceDecay or agent-host data.
• Missing registries and unavailable authorities are typed states, not transport errors or successful empty results.
• LCM retrieval, including paginated summary sources, hydrates through canonical redaction/content authority from each message's owning store; raw rows and ranked candidate metadata are not authoritative backfill.
• Cross-project memory selectors open the selected registered project's durable store with exact project/profile/store identity; they never alias the active project's memory database.
• workspaceOpen follow-up reads use daemon-wide typed route authority; linked-worktree requests retain registered identity and never fall back to the active graph.
• Recovery may clear only the exact dirty marker adopted under its sync lease; compare-and-swap must preserve foreign or newer markers.