Skip to content

AGENTS.md

Latest commit

 

History

History
240 lines (219 loc) · 14 KB

AGENTS.md

File metadata and controls

240 lines (219 loc) · 14 KB
Raw

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."
  • 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/ (from the canonical operation registry) are generated. Never hand-edit them; regenerate both 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

  • Edition 2024, resolver 3. Use the toolchain pinned in rust-toolchain.toml. Run cargo <subcommand> normally.
  • pnpm (pinned by packageManager) manages the npm packages and the Cargo sources. Run pnpm install at the repository root after cloning and after any pnpm-lock.yaml or Cargo.lock change. The committed .cargo/config.toml replaces crates.io and the pinned git sources with .pnpm/crates, so cargo cannot resolve dependencies until that install has run. Two Cargo errors mean "run pnpm install": failed to read root of directory source <repo>/.pnpm/crates/git before any install, and no matching package named '<crate>' found with location searched: directory source '<repo>/.pnpm/crates/crates-io' when Cargo.lock names a crate that is not vendored yet. verifyDepsBeforeRun guards only the npm packages; pnpm reads Cargo.lock as it is and never rewrites it or fails on a manifest mismatch.
  • To add, remove, or bump a crate (member or [workspace.dependencies]), edit the manifests by hand, refresh the lock from outside the checkout with the pinned toolchain, cd / && cargo +<toolchain> update -w --manifest-path <repo>/Cargo.toml (-p <crate> for a targeted bump), then run pnpm install. Inside the checkout cargo update refuses the vendored git sources and cargo add sees only vendored crates. Do not use pnpm add crate:; from a member directory it regenerates the whole Cargo.lock, at the root it fails, and pnpm remove crate: is unsupported. pnpm install leaves unused .pnpm/crates directories in place; they are inert once the lock stops naming them. Cargo reads .cargo/config.toml from its working directory, so run sdks/codegen cargo commands from sdks/codegen.
  • 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, use the using-hotpath skill to measure the operation 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. Keep the observability layers distinct: tracing events are the always-compiled operator log surface, Hotpath macros the compile-to-no-op measurement surface (tracing bridges exist only for third-party emitters like sqlx, see the skill), 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.
  • Add a V2/V3 contract, compatibility alias, deprecation path, or data migration only after proving the prior shape shipped on origin/master, in a published package, or in a live persisted format. Branch-local and unreleased contracts change in place; a V1 suffix alone is not release evidence and does not justify compatibility shims.
  • 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.