Reviewed Rule Agent Pack

Agent Workflow

• AGENT-BUDGET-FOR-FEEDBACK-LOOPS: Budget tokens and time for reading, editing, checks, failure inspection, and proof reporting.
• AGENT-DEFINE-GOOD-BEFORE-JUDGMENT-HEAVY-WORK: Before naming, grouping, documentation voice, API shape, or rule IDs, define the quality bar so the agent has concrete goalposts.
• AGENT-DISTILL-FROM-BLESSED-ARTIFACTS: Distill conventions, principles, and review expectations from accepted artifacts before inventing style; adapt the accepted pattern to the current task.
• AGENT-ENCODE-NONFUNCTIONAL-REQUIREMENTS: Encode nonfunctional requirements that may not appear in the diff, such as latency, accessibility, security, privacy, determinism, and compatibility.
• AGENT-GIVE-OBJECTIVES-WITH-BOUNDARIES: Give agents objectives with boundaries so they can adapt to real repo structure without following brittle step lists.
• AGENT-GRANT-SCOPED-CAPABILITIES: Grant scoped agent capabilities because agents with broad authority can accidentally mutate external systems, publish state, delete files, or read secrets unrelated to the task.
• AGENT-ISOLATE-WORKSPACES-BY-TASK: Isolate workspaces for parallel agent tasks so diffs, validation, and ownership stay unambiguous.
• AGENT-KEEP-DURABLE-CONTEXT-ON-DISK: Keep durable context on disk because prompt context disappears, compacts, or becomes invisible to future sessions.
• AGENT-KEEP-SECRETS-OUT-OF-CONTEXT: Keep secrets out of context because secrets pasted into prompts, docs, logs, or test output can be retained, repeated, or committed accidentally.
• AGENT-MAKE-BAD-OUTPUT-HARD: Make bad output mechanically hard because repeated prompt reminders are weaker than a repo that rejects bad output mechanically.
• AGENT-PREFER-BUILD-PRESERVING-EDITS: Prefer build-preserving edits on natural paths so failures stay close to the edit that caused them.
• AGENT-PREFER-IN-DISTRIBUTION-TOOLS: Prefer in-distribution tools for agent-facing work because trained and tested tool paths tend to be more reliable.
• AGENT-PREFER-TOOLS-OVER-PROMPTS: Prefer tools and checks over repeated prompting; put repeated instructions in a tool, check, template, or guide.
• AGENT-PRESENT-CONCRETE-NEXT-OPTIONS: After a validated chunk, name the next concrete chunk and why to choose it so the maintainer controls scope cheaply.
• AGENT-PRESERVE-HUMAN-WORK: Preserve unrelated human work because agents share a working tree with human edits and sometimes other agents.
• AGENT-PRESERVE-INTENT: Preserve intent over literalism because literal execution can satisfy the words while missing the goal.
• AGENT-PRODUCE-REVIEW-PACKETS: Produce review packets for agent output because agent output often spans code, docs, generated artifacts, and validation logs.
• AGENT-PROVE-SECURITY-IMPACT: Prove security impact separately from hypotheses because security claims are easy to overstate.
• AGENT-REPORT-PROOF-IN-HANDOFFS: Report proof in handoffs instead of confidence language, because confidence is not evidence.
• AGENT-REVIEW-OUTPUT-AS-FUTURE-MAINTAINER: Review agent output as a future maintainer: check correctness, edge cases, API clarity, documentation truthfulness, readable ownership, focused tests, validation proof, and residual risk.
• AGENT-SEPARATE-NOTES-FROM-CORRECTIONS: Separate note capture from correction during fast review so clustered feedback becomes cleaner edits or durable guidance.
• AGENT-SPEND-HUMAN-ATTENTION-ON-AMBIGUITY: Spend human attention on ambiguity because agents can spend a lot of effort executing through an unresolved decision.
• AGENT-SUGGEST-LOCAL-OVERRIDE-FILES: Suggest ignored override files for checkout-only facts such as local jj topology, plan directories, machine paths, or temporary repo notes.
• AGENT-TURN-FEEDBACK-INTO-GUIDANCE: Turn repeated feedback into durable guidance because repeated corrections such as "show why," "name the next thing," or "do not use abstract rule names" are process bugs.
• AGENT-USE-AGENTS-MD-AS-MAP: Use AGENTS.md to route agents to deeper guides because a full rule set would make the file hard to scan.
• AGENT-VERIFY-RISKY-CHANGES-WITH-CANARIES: Use canaries for changes that can pass local tests but fail under real traffic, docs rendering, provider state, or users.

Explicit Boundaries Preserve Correctness

• BOUNDARY-AVOID-GLOBAL-MUTABLE-STATE: Avoid global mutable state because it hides ownership, ordering, reset, and concurrency requirements.
• BOUNDARY-CHOOSE-RESOURCE-IDENTITY-MODEL: Choose the resource identity model up front because a system that mutates individual records behaves differently from one that mutates record sets, files, sessions, handles, or whole documents.
• BOUNDARY-DEFINE-COMPACTION-INVARIANTS: Define explicit budget and cut-point invariants before compaction deletes, summarizes, or moves information.
• BOUNDARY-DEFINE-HOOK-FAILURE-POLICY: Define hook failure policy because hooks can fail before, during, or after the main operation.
• BOUNDARY-DISTINGUISH-INPUT-CLASSES: Keep unknown, unsupported, denied, and preserved inputs distinct because each class needs different treatment.
• BOUNDARY-EXPOSE-PARTIAL-STREAM-OUTPUT: Expose partial provider-stream output without making it authoritative before the final result arrives.
• BOUNDARY-GIVE-TOOLS-IDENTITY-POLICY-AND-LIMITS: Give tool boundaries typed identity, authorization policy, cancellation, and output limits before crossing into filesystem, shell, network, provider, or user-visible effects.
• BOUNDARY-GROUND-INTEGRATIONS-IN-PRIMARY-SOURCES: Ground integration behavior in primary source documentation because provider and platform behavior changes.
• BOUNDARY-IDENTIFY-ANEMIC-STATE-MACHINES: Identify anemic state machines in auth flows, UI state, async routing, setup wizards, and lifecycle code.
• BOUNDARY-KEEP-BACKEND-ADAPTERS-AT-EDGE: Keep backend adapters at the edge because backend-specific APIs for terminals, storage, network providers, or runtimes spread quickly if they enter core logic.
• BOUNDARY-MAKE-AMBIENT-INPUTS-EXPLICIT: Make ambient inputs explicit because time, randomness, environment variables, current directories, locale, terminal size, network clients, and process state can change behavior without appearing in function signatures.
• BOUNDARY-MAKE-DYNAMIC-CONFLICTS-DETERMINISTIC: Make dynamic registration conflicts deterministic and explicit because dynamic registration from plugins, generated code, guests, or config can produce duplicate names, ordering conflicts, or shadowed handlers.
• BOUNDARY-MAKE-EXEC-TOOLS-NONINTERACTIVE: Make exec-like tools noninteractive by default because exec-like tools called by agents, CI, or background tasks cannot safely wait for prompts, editors, pagers, or credential UI.
• BOUNDARY-MAKE-POLICY-BOUNDARIES-EXPLICIT: Route policy-sensitive side effects through an explicit policy boundary before execution, and make allowed, denied, redacted, fallback, preserved, and unsupported outcomes visible to callers.
• BOUNDARY-MODEL-REAL-UPSTREAM-SURFACE: Model each integration as the real upstream surface it exposes because adapters should not pretend a provider supports a cleaner or broader API than it actually does.
• BOUNDARY-NAME-LIFECYCLE-TRANSITIONS: Treat lifecycle transitions as named operations because creation, activation, cancellation, teardown, reload, and promotion are different operations with different invariants.
• BOUNDARY-PARSE-UNCERTAINTY-AT-EDGE: Push uncertainty to the boundary, then pass trusted values inward from parsed strings, JSON, CLI args, provider responses, and user input.
• BOUNDARY-READ-NORMALIZE-COMPARE-MUTATE: Reconcile external state by reading, normalizing, comparing, then mutating so formatting, ordering, defaults, and outside actors do not hide drift.
• BOUNDARY-REJECT-UNSUPPORTED-SHAPES: Reject unsupported shapes early with clear errors because unsupported names, values, TTLs, targets, record families, protocols, or config modes should fail at the boundary with a clear error.
• BOUNDARY-REPORT-PROVIDER-DIAGNOSTICS: Report provider freshness, permissions, budget, load, cache, and degradation diagnostics so callers know how trustworthy the data is.
• BOUNDARY-SEPARATE-PURE-CORE-FROM-EFFECTS: Separate pure computation from I/O, rendering, mutation, and global state because that gives tests a stable behavior surface.
• BOUNDARY-SEPARATE-UI-AND-APP-STATE: Keep UI state separate from application-owned state because UI state such as selection, scroll offset, focus, expanded rows, or transient input mode changes at a different rate than application-owned data.
• BOUNDARY-STAGE-GENERATED-BEHAVIOR: Stage generated or reloadable behavior before promotion because generated, reloadable, or plugin-provided behavior can be malformed, stale, or incompatible with the current runtime.
• BOUNDARY-TRACK-DYNAMIC-REGISTRATION-PROVENANCE: Track provenance for extension, guest, generated-code, or config registrations so conflicts and failures identify their source.
• BOUNDARY-TREAT-TERMINAL-UI-AS-PRODUCT-SURFACE: Treat terminal UI as a product surface with platform-specific contracts because terminal UI is not just debug output.
• BOUNDARY-USE-CONSERVATIVE-TERMINAL-DEFAULTS: Use conservative terminal defaults because terminals vary in color support, width, input behavior, fonts, and accessibility settings.

Change Shape

• CHANGE-AVOID-SPECULATIVE-PUBLIC-API: Avoid speculative public API; add public names, types, extension points, and compatibility promises only for concrete current needs or explicitly accepted near-term requirements.
• CHANGE-AVOID-UNNECESSARY-DEPENDENCY-CHURN: Avoid dependency churn unless it is necessary for the task; dependency updates change lockfiles, feature graphs, minimum versions, build output, and downstream compatibility.
• CHANGE-IDENTIFY-OWNING-MODULE-BEFORE-EDITING: Identify the owning module before editing because editing the first file that mentions a behavior can put new logic in a caller, facade, test helper, or adapter that does not own the concept.
• CHANGE-ISOLATE-CONTROVERSIAL-CHANGES: Isolate controversial changes because formatting, renames, API breaks, dependency changes, unsafe code, large rewrites, and behavior changes all invite different review questions.
• CHANGE-MINIMAL-BUT-COMPLETE: Keep each change minimal but complete because a change that is too large hides risk, but a change that is too small can leave reviewers with an unexplained half-step.
• CHANGE-PIN-BEHAVIOR-WITH-EARLY-TESTS: Use early tests to pin current behavior before changing messy behavior so reviewers can separate existing behavior from the intended change.
• CHANGE-PREFER-SMALL-FOLLOW-UPS: Prefer small follow-ups for adjacent cleanup, docs drift, naming issues, or broader refactoring so the current diff keeps its purpose.
• CHANGE-PRESERVE-UNOWNED-WORK: Preserve unowned work because a working tree can contain edits from the user, another agent, generated state, or an earlier in-progress change.
• CHANGE-RESPECT-GENERATED-ARTIFACT-OWNERSHIP: Edit the source input, template, release metadata, or generator config for generated artifacts; hand edit generated output only for tool workflows that make curation durable.
• CHANGE-SEPARATE-STRUCTURE-FROM-BEHAVIOR: Separate structure and behavior changes because the combined diff makes reviewers prove both meaning preservation and new behavior.
• CHANGE-SYNC-GENERATED-ARTIFACTS: Update them with the source change because checked-in generated files, lockfiles, snapshots, API listings, or agent packs are review surfaces.
• CHANGE-TREAT-AND-AS-SCOPE-WARNING: Treat and in a change description as a scope warning because a change titled "fix parser and update docs and clean API" often contains multiple review units.
• CHANGE-USE-ONE-PURPOSE-PER-CHANGE: Use one purpose per change so reviewers can ask one main question: did this accomplish the stated goal?

Docs Are Contracts

• DOCS-ALIGN-README-AND-CRATE-RUSTDOC: Keep crate README and crate-level Rustdoc aligned because crate users often meet the README on GitHub and the crate-level Rustdoc on docs.rs.
• DOCS-AVOID-GENERATED-PROSE-TELLS: Avoid generated-prose tells, including component-centered navigation copy, that replace concrete behavior, evidence, tradeoffs, or direct labels. During prose review, check word choice, sentence templates, evidence-disclaimer cadence, empty state scaffolding, paragraph roles, tone, formatting, and repeated composition patterns.
• DOCS-AVOID-UNEARNED-PRAISE: Avoid unearned ranking and vague praise because words such as "simple," "powerful," "best," and "easy" are often unearned unless the doc states the comparison or tradeoff.
• DOCS-BUILD-DOCS-LIKE-USERS-READ-THEM: Build Rust docs the way users will read them because rust docs are consumed through rendered Rustdoc, docs.rs feature configuration, intra-doc links, search, and examples.
• DOCS-CHOOSE-DOCUMENT-TYPE: Choose the document type before editing because a page that mixes tutorial, reference, explanation, decision record, and changelog work makes every reader pay for every mode.
• DOCS-COMPARE-LIBRARIES-ACCURATELY: Compare nearby libraries accurately and charitably; inaccurate comparisons undermine trust.
• DOCS-DISTINGUISH-EXAMPLE-ROLES: Name the example's primary role before expanding it; keep focused, canonical, survey, integration, and showcase examples from collapsing into one generic snippet.
• DOCS-DOCUMENT-LIFECYCLE-AND-SIDE-EFFECTS: Document lifecycle, ownership, side effects, feature flags, platform assumptions, and compatibility for APIs that create caller obligations.
• DOCS-EXPOSE-MOVE-RISK-AND-EXAMPLE-IN-PATTERNS: For pattern-style guidance, include the recognizable situation, preferred move, risk, example, and agent instruction.
• DOCS-FRONT-LOAD-USEFUL-POINT: Front-load the useful point because readers scan docs for the decision, command, invariant, or warning that matters.
• DOCS-GROUP-RELATED-LIST-ITEMS: Group long lists into named clusters for distinct rule families, reader tasks, or decision surfaces; keep short homogeneous lists flat.
• DOCS-HIDE-CATALOG-MECHANICS: Lead with reader-facing work areas and artifacts; mention rule IDs, prefixes, domains, generated indexes, source layout, or UI containers only for citation, automation, or contribution workflow.
• DOCS-KEEP-MARKDOWN-LINTABLE: Keep Markdown lintable because formatting drift adds review noise and makes generated or agent-edited docs harder to maintain.
• DOCS-MAKE-GUIDANCE-REVIEW-STATE-VISIBLE: Keep guidance status visible on reusable rules, patterns, principles, and mechanisms; route drafts to review queues before copying them into execution packs.
• DOCS-MAKE-REVIEW-EASY-TO-INSPECT: Make documentation review easy to inspect because docs are often reviewed as Markdown diffs even though users read rendered pages, generated Rustdoc, examples, screenshots, or command output.
• DOCS-MARK-NONCOMPILING-EXAMPLES-HONESTLY: Prefer compiling Rust examples, and mark noncompiling examples honestly because users and doctests often copy them directly.
• DOCS-MATCH-PAGE-SHAPE-TO-READER-TASK: For documentation sites that render Markdown, choose a page shape for the reader task before exposing the content. Use catalogs for choosing, prose pages for explanation, rule layouts for instructions, mechanism layouts for runnable checks, and reference layouts for source catalogs.
• DOCS-NAME-DESTINATION-NOT-DIRECTION: Write navigation and index copy as destination, decision, artifact, or work-area labels; avoid directive phrases such as "start here," "use this guide," and "open this guide" on reference surfaces.
• DOCS-ONE-DOMINANT-MODE-PER-PAGE: Pick one dominant documentation mode per page because a page with competing modes forces readers to switch mental models.
• DOCS-PROSE-FOR-RELATIONSHIPS-LISTS-FOR-ENUMERATION: Use prose for relationships and lists for enumeration because lists are good for fields, steps, options, and checks, but weak for explaining causality.
• DOCS-PROVE-REAL-USE-WITH-EXAMPLES: Prove real use with examples because examples that only construct a type or call the happy-path function do not prove that the API works in the way users need.
• DOCS-PUT-UNCERTAINTY-IN-TRACKED-PLACES: Put uncertainty in issues, ADRs, or roadmaps rather than user docs that should describe current truth.
• DOCS-README-AS-ENTRY-POINT: Keep README files as entry points because a README is usually the first page for humans and agents.
• DOCS-REVIEW-CORRECTNESS-AND-RISK-FIRST: Review docs for correctness, contract ambiguity, risk, drift, and operability before style polish; use severity labels to separate blocking misunderstandings from wording cleanup.
• DOCS-SHOW-SIDE-EFFECTS-IN-LIVE-EXAMPLES: Show side effects and cleanup in examples that create files, hit networks, write records, open terminals, spawn tasks, or mutate services.
• DOCS-STATE-CURRENT-BEHAVIOR-NOT-ASPIRATION: State current behavior, not aspiration, because aspirational docs become false contracts.
• DOCS-TREAT-DOCS-AS-CONTRACTS: Treat docs as contracts because humans and agents use them to infer supported behavior.
• DOCS-USE-CONCRETE-DETAILS: Use concrete nouns, real paths, defaults, commands, examples, and named work areas so readers do not infer the actual object.
• DOCS-USE-DESCRIPTIVE-HEADINGS: Use descriptive headings for reference and landing pages so the heading names the destination, content, or decision area, not a slogan-like instruction or next-step direction.
• DOCS-USE-SOURCE-LINKS-AS-SUPPORT: Write a locally sufficient explanation, then use direct stable links to help readers verify or compare judgment. Do not make discovery tools, private archives, or inaccessible discussion part of the reader's required path.
• DOCS-VERIFY-COMMANDS-PATHS-AND-LINKS: Verify example commands, file paths, and linked references because they act like executable instructions.
• DOCS-WRITE-FOR-NON-LINEAR-READERS: Write docs for non-linear readers. Give each likely entry point enough subject and prerequisite context to stand alone, then link to the nearest owning explanation instead of repeating it.
• DOCS-WRITE-TECHNICAL-PROSE: Write technical docs, not marketing, coaching, or chat, so readers can make correct decisions.

Observability And Failure

• OBSERVABILITY-DISTINGUISH-FAILURE-STATES: Distinguish partial, aborted, timed-out, denied, failed, and completed states because they need different recovery paths.
• OBSERVABILITY-KEEP-DIAGNOSTICS-RETENTION-SAFE: Keep diagnostics safe for their retention boundary, especially telemetry, CI artifacts, PR comments, and user-visible reports.
• OBSERVABILITY-LOG-AT-OWNED-BOUNDARIES: Log at owned boundaries because the best diagnostic point is usually where code still knows the operation, caller intent, input class, and external system boundary.
• OBSERVABILITY-PRESERVE-OPERATION-CONTEXT-IN-ERRORS: Preserve operation context in errors because an error such as "not found" or "permission denied" is rarely enough.
• OBSERVABILITY-SURFACE-DURABLE-FAILURES: Do not hide durable failures only in UI logs because a durable failure that only appears in an ephemeral UI log can disappear before a maintainer or user can act.

Measure Before Optimizing

• PERF-AVOID-SINGLE-RUN-CONCLUSIONS: Do not decide performance from one short benchmark run because one short benchmark run can be dominated by warmup, scheduling, cache state, background load, or measurement noise.
• PERF-JUSTIFY-COMPLEXITY-CHURN-AND-DEPENDENCIES: Justify complexity, churn, and dependency cost because performance work adds branches, unsafe code, caching, data structure churn, or dependencies.
• PERF-MEASURE-GOAL-CHANGE-COMPARE: State the performance goal, measurement, change, and comparison so reviewers can evaluate the patch.
• PERF-OPTIMIZE-MEASURED-HOTSPOTS: Optimize measured hotspots, not interesting code that runs once, is off the critical path, or is invisible to users.
• PERF-RECORD-BENCHMARK-PROVENANCE: Record benchmark provenance so timing numbers remain comparable later.
• PERF-RUN-CORRECTNESS-FIRST: Run correctness before performance timing because fast wrong code is still wrong, and correctness failures can invalidate timing data.
• PERF-RUN-TIMING-BENCHMARKS-SEQUENTIALLY: Run timing benchmarks sequentially so CPU, cache, memory, disk, and thermal contention do not distort results.

Local Reasoning And Refactoring

• REFACTORING-ALIGN-SEAMS-WITH-REAL-VARIATION: Align seams with observed variation such as backends, policies, protocols, test doubles, or ownership boundaries, not hypothetical variation.
• REFACTORING-DO-NOT-OVER-APPLY-DRY: Do not over-apply DRY because two blocks that look similar may change for different reasons.
• REFACTORING-EXTRACT-CONCEPT-HELPERS: Extract helpers only for real concept boundaries, not just to hide a few lines from the reader.
• REFACTORING-KEEP-LINEAR-STORY-VISIBLE: Keep linear work visible because the clearest story is read input, validate, transform, then emit result.
• REFACTORING-KEEP-WEAK-ABSTRACTIONS-CLOSE-TO-THEIR-USE: Keep weak abstractions close to their use because new abstractions are often tentative.
• REFACTORING-MAKE-EDGE-CASES-EXPLICIT: Make edge-case behavior visible near correctness-sensitive branches, calculations, or returns; prefer stronger types for reusable invariants.
• REFACTORING-PREFER-LOCAL-REASONING: Prefer designs where readers can see relevant state, invariants, and effects nearby instead of reconstructing distant context.
• REFACTORING-PREFER-LOOPS-FOR-SIDE-EFFECTS: Prefer loops over combinators for business-logic side effects because iterator chains are compact, but business-logic side effects often need named steps, early exits, logging, error handling, or comments.
• REFACTORING-USE-WHITESPACE-AS-FUNCTION-PARAGRAPHS: Use whitespace as function paragraphs because blank lines can show that a function has phases: gather inputs, validate, calculate, perform effects, return.

Private Context And Review Artifacts

• REVIEW-ANSWER-QUESTIONS-BEFORE-CODE: Answer reviewer questions before or with code updates so intent, tradeoffs, and remaining choices are visible instead of buried in a new patch.
• REVIEW-CLASSIFY-PROTOTYPE-REUSE: Classify prototype reuse as behavior, evidence, replaceable shape, or load-bearing boundary before changing the boundary.
• REVIEW-DEFINE-SLICES-IN-ISSUES: Define review-sized slices in issues because issues are often the first place a future PR gets shaped.
• REVIEW-EXPLAIN-CONTROVERSIAL-CHOICES-INLINE: Use capable reviewer questions about non-obvious code as documentation signals. Prefer clearer code; otherwise preserve the durable answer in the nearest comment, test, Rustdoc, module docs, or change narrative that owns it.
• REVIEW-EXPLAIN-PR-PROBLEM-MODEL-AND-PROOF: Explain the problem, mental model, tradeoffs, validation, and docs impact so reviewers do not reverse-engineer intent from the diff.
• REVIEW-LABEL-SPECULATION-AS-INFERRED-OR-UNKNOWN: Label speculation as inferred or unknown because review notes often mix facts, traces, guesses, and model-based conclusions.
• REVIEW-LET-REVIEWERS-RESOLVE-THREADS: Let reviewers resolve review threads unless resolution is unambiguous; thread resolution is a communication act, not just a UI cleanup.
• REVIEW-MAKE-REVIEW-ARTIFACTS-STANDALONE: Make issues, PRs, commit messages, and handoffs stand alone for readers who did not see the chat, notes, plan, or discarded attempts.
• REVIEW-SEPARATE-DISCOVERY-SELECTION-IMPLEMENTATION: Separate discovery, solution selection, and implementation review for unsettled scope or design; use issues, design notes, or ADRs before asking reviewers to judge a patch.
• REVIEW-UPDATE-SOURCE-OF-TRUTH: Update the owning issue, PR description, checklist, plan, or handoff for durable status changes; avoid comments that only nudge reviewers or restate current progress.
• REVIEW-USE-ADRS-FOR-BOUNDARIES-AND-OWNERSHIP: Use ADRs for decisions that outlive a PR, such as ownership, API boundaries, storage formats, runtime responsibility, and service or crate boundaries.

Rust API And Crate Shape

• RUST-ADD-BENCHMARKS-FOR-PERFORMANCE-CLAIMS: Benchmark Rust hot paths or allocation-sensitive changes before making or preserving performance claims.
• RUST-ALIGN-RELEASE-SUPPORT-CLAIMS: Keep release claims aligned across Cargo.toml, README, Rustdoc, changelog, docs.rs metadata, examples, and CI support matrices.
• RUST-AVOID-BROAD-CONTEXT-AND-CALLBACKS: Avoid broad context objects and callback-heavy control flow because broad context objects and callback-heavy flows hide which inputs, effects, and ordering a function needs.
• RUST-AVOID-EMPTY-WRAPPER-TYPES: Avoid wrapper types that add no invariant, behavior, or ownership clarity; a wrapper should earn its name.
• RUST-AVOID-GIANT-CRATE-ROOTS: Avoid giant crate roots because a giant lib.rs or main.rs makes the crate root carry every concept, helper, import, and re-export.
• RUST-AVOID-GLOB-REEXPORTS: Use explicit public re-exports in Rust facades so the exported API is reviewable at the facade.
• RUST-AVOID-INLINE-MODULES: Avoid inline modules except for tests, preludes, and generated code because named files improve navigation, search, and ownership.
• RUST-AVOID-MOD-RS-BY-DEFAULT: Prefer named Rust module root files over mod.rs for module concepts that benefit from a filename.
• RUST-AVOID-OVERCOMMENTING-TRIVIAL-CODE: Remove Rust comments that merely restate obvious code; keep comments for invariants, tradeoffs, contracts, and safety.
• RUST-AVOID-PATH-ATTRIBUTE: Avoid #[path] in Rust modules unless an unusual generated or platform layout is genuinely clearer.
• RUST-AVOID-PUBLIC-DEPENDENCY-COUPLING: Avoid leaking dependency types in public APIs unless integration is the point; exposed dependency types make downstream users care about that dependency's version, features, and semantics.
• RUST-AVOID-TINY-MODULE-MAZES: Keep Rust helpers near their use unless splitting a file gives a real concept its own home.
• RUST-AVOID-VAGUE-DOCS-AND-GENERIC-EXAMPLES: Replace vague Rustdoc and generic examples with contract details and examples that prove realistic use.
• RUST-CENTRAL-ITEM-FIRST: Put the main Rust type, trait, enum, or function before helpers so readers find the module concept first.
• RUST-CHOOSE-GENERICS-AND-TRAIT-OBJECTS-DELIBERATELY: Choose generics, stored type parameters, and trait objects deliberately because they trade off monomorphization, object safety, compile time, and ergonomics.
• RUST-COMPARE-CRATES-BY-FIT-AND-TRADEOFF: Compare Rust crates accurately and charitably by fit, scope, and tradeoff, not universal superiority.
• RUST-CONFIGURE-DOCS-RS: Configure docs.rs metadata intentionally because docs.rs is often the rendered documentation users see first.
• RUST-CONSIDER-DOWNSTREAM-API-IMPACT: Consider downstream impact before changing public API because changing a public Rust API can break external imports, trait impls, type inference, docs, examples, and semver expectations.
• RUST-CONTAIN-UNSAFE: Keep unsafe small, wrapped, documented, and tested through the safe API because unsafe concentrates obligations the compiler cannot check.
• RUST-DENY-ACCIDENTAL-UNSAFE: Deny accidental unsafe code in crates that do not need unsafe so unsafe blocks fail loudly.
• RUST-DO-NOT-DEFAULT-PUB-CRATE: Do not default to pub(crate) because crate-wide visibility still expands the internal surface and lets modules reach into each other.
• RUST-DO-NOT-PIN-PATCH-VERSIONS: Avoid patch-pinned Cargo.toml requirements unless the patch supplies an API, behavior, or fix the crate actually needs.
• RUST-DOCUMENT-CURRENT-IMPLEMENTED-BEHAVIOR: Write Rust public docs in present tense for implemented behavior; label planned behavior as future work or scope.
• RUST-DOCUMENT-FEATURE-CONTRACTS: Document Rust feature flags by naming the public API, runtime behavior, dependencies, platform support, or docs coverage they enable.
• RUST-DOCUMENT-LIFECYCLE-SIDE-EFFECTS: Document startup, shutdown, cleanup, cancellation, ordering, and coexistence for Rust APIs with host, process, runtime, terminal, network, or UI side effects.
• RUST-DOCUMENT-PERFORMANCE-CONTRACTS: Document blocking behavior, allocation expectations, buffering, clone cost, and runtime constraints that callers may reasonably depend on.
• RUST-DOCUMENT-PUBLIC-PANIC-CONTRACTS: Document public panic contracts as precondition violations because a public panic is a contract boundary: the caller violated a precondition or the crate has a bug.
• RUST-DOCUMENT-SCHEDULING-FOR-LONG-ASYNC: Document scheduling expectations for async work that can starve executors, ignore cancellation, hold locks, or rely on runtime assumptions.
• RUST-DOCUMENT-VISIBILITY-OWNERSHIP: Update names and docs while widening Rust visibility so the owning concept and intended callers are clear.
• RUST-ENCODE-DURABLE-RULES-IN-LINTS: Use lint configuration for durable project policy, not transient taste or migration states that need frequent exceptions.
• RUST-EXPOSE-PRIMARY-PATH-FROM-CRATE-ROOT: Make lib.rs teach and expose the primary crate path while pointing readers to deeper modules.
• RUST-FORMAT-DOCS-AND-COMMENTS-CONSISTENTLY: Format Rust doc-comment code, doc attributes, grouped imports, and prose comments with the project's formatter conventions.
• RUST-GROUP-MODULE-IMPORTS: Prefer grouped module imports over one-import-per-line style because grouped module imports keep related names together and make dependencies easier to scan.
• RUST-GROUP-PRIVATE-IMPORTS-BEFORE-PUBLIC-RE-EXPORTS: Group private imports before public re-exports because private imports and public re-exports answer different questions.
• RUST-HIDE-TEST-ONLY-HELPERS: Keep test-only helpers out of the normal public API because test-only helpers should not become production API or crate-wide concepts by accident.
• RUST-IMPLEMENT-DEBUG-FOR-PUBLIC-TYPES: Implement Debug for public types unless that is unsafe or misleading; Debug is the baseline diagnostic trait for Rust values.
• RUST-IMPLEMENT-STANDARD-TRAITS-FOR-PUBLIC-ERRORS: Implement Debug, Display, and std::error::Error for public errors that cross into callers, logs, tests, and user messages.
• RUST-INJECT-HOST-INTERACTIONS-AT-BOUNDARIES: Inject Rust host dependencies at boundaries for tests or alternate environments that need deterministic control.
• RUST-KEEP-CI-HIGH-SIGNAL: Keep Rust PR CI focused on fast deterministic gates, and move expensive checks to scheduled, manual, or release workflows.
• RUST-KEEP-COMPATIBLE-UPDATES-IN-LOCKFILE: Keep compatible dependency updates in the lockfile, not the manifest requirement, unless the crate actually needs the newer version.
• RUST-KEEP-CONCEPTS-COHERENT: Keep Rust modules, types, and helpers centered on one recognizable concept so readers can find the owner of behavior.
• RUST-KEEP-CRATE-BOUNDARIES-NARROW: Put Rust code and tests in the owning crate or module, and expose shared helpers only for intentional shared concepts.
• RUST-KEEP-DEPENDENCY-UPDATES-INTENTIONAL: Group routine Rust dependency updates, separate behavior-affecting updates, and use Cargo-aware commands to preserve manifest consistency.
• RUST-KEEP-EDITS-SCOPED-TO-OWNING-CONCEPT: Before editing Rust code, identify the owning module or crate and keep unrelated cleanup out of the change.
• RUST-KEEP-LINTS-ACTIONABLE: Enable Rust lints only for durable policy, and keep suppressions narrow with a reason.
• RUST-KEEP-MARKDOWN-OUTSIDE-RUSTDOC-PURPOSEFUL: Keep Rust API contracts in Rustdoc, README entry points in README, and use Markdown guides for long-form workflow, architecture, or process material.
• RUST-KEEP-PRE-RELEASE-COMPATIBILITY-INTENTIONAL: Clean up accidental pre-release Rust API compatibility after the intended API becomes clearer and the crate has not promised the old shape.
• RUST-KEEP-PRELUDES-REEXPORT-ONLY: Keep Rust prelude modules as import surfaces that re-export owned items from their real modules.
• RUST-KEEP-PUBLIC-API-SHAPE-INTENTIONAL: Keep public API shape intentional because every public item becomes something users can import, name, document, and depend on.
• RUST-KEEP-RUSTDOC-AND-README-EXAMPLES-ALIGNED: Update README, crate Rustdoc, doctests, and example projects together for Rust public example changes that teach the same contract.
• RUST-MAKE-FEATURE-FLAGS-ADDITIVE-WHERE-POSSIBLE: Make feature flags additive where possible because Rust feature unification means enabling a feature in one dependency path can affect the whole build.
• RUST-MAKE-PUBLIC-API-BROWSEABLE-FROM-LAYOUT: Align Rust public modules, files, and re-exports so readers can browse from public API to owning source without translation.
• RUST-MAKE-SIDE-EFFECTS-EXPLICIT: Expose Rust side effects in names, call sites, and Rustdoc for calls that mutate state, perform I/O, register globally, or start background work.
• RUST-NAME-AUDITABLE-INTERMEDIATES: Name intermediate Rust values because they expose ownership, parsing, validation, rendering, or side-effect policy decisions.
• RUST-NAME-TESTS-BY-BEHAVIOR: Name Rust tests for the behavior, boundary, or regression they protect, not just the function under test.
• RUST-NON-EXHAUSTIVE-PUBLIC-ERRORS: Use #[non_exhaustive] for public error enums unless exhaustive matching is intentional; integrations, validation, and provider behavior often add variants over time.
• RUST-ORDER-CODE-FOR-READING: Arrange Rust modules so public or central items appear before helpers and reading order follows execution or conceptual dependency.
• RUST-ORDER-ITEMS-FOR-API-READING: Order Rust imports, public items, inherent impls, trait impls, and helpers to make the file's API story easy to scan.
• RUST-PREFER-BORING-DIRECT-CODE: Prefer boring direct Rust over clever framework-shaped code because boring Rust makes ownership, error handling, and control flow visible.
• RUST-PREFER-CONCEPT-OWNED-MODULES-AND-NAMED-FILES: Prefer concept-owned modules and named files because modules should be owned by concepts, not by miscellaneous implementation layers.
• RUST-PREFER-CONSTRUCTORS-AND-CONVERSION-TRAITS: Prefer constructors or conversion traits that show whether callers are building, validating, converting, or borrowing values.
• RUST-PREFER-EXPECT-FOR-LINT-SUPPRESSIONS: Use #[expect] for lint suppressions that should disappear once the warning is fixed.
• RUST-PREFER-SMALL-CLEAR-SHAPES: Prefer small functions, narrow structs, and simple enums to reduce live fields, branches, lifetimes, and invariants.
• RUST-PRESERVE-ERROR-CONTEXT: Preserve Rust error source, operation, and recoverable context while wrapping or mapping failures.
• RUST-PRESERVE-VALID-STATE-ON-FAILURE: Stage fallible Rust refresh, parse, I/O, or render work before mutating usable state.
• RUST-REEXPORT-FOR-DISCOVERY: Use re-exports for discovery, not ownership hiding, so users find APIs without losing where concepts live.
• RUST-RELEASE-ONLY-AFTER-ARTIFACT-VALIDATION: Before publishing or tagging a Rust release, dry-run and inspect the package artifact, metadata, docs, examples, license files, and generated content.
• RUST-REVIEW-AS-FUTURE-MAINTAINER: Review Rust changes for the future maintainer: name readability causes, public API risks, docs truth, and validation gaps concretely.
• RUST-RUN-FEATURE-GATED-VALIDATION: Validate the feature combinations affected by a Rust change, including docs for features that change public items.
• RUST-SHAPE-EXPRESSIONS-FOR-AUDITABILITY: Use named locals, visible branches, whitespace paragraphs, and loops for side-effectful Rust logic that dense expressions would hide.
• RUST-TEACH-CRATE-FROM-CRATE-ROOT: Teach the crate from the crate root because the crate root is the first Rustdoc page and often the first source file a reader opens.
• RUST-TIE-OPTIONAL-DEPENDENCIES-TO-NAMED-FEATURES: Keep optional dependencies tied to clearly named features because they become part of the feature contract.
• RUST-USE-BUILDERS-FOR-OPTIONAL-OR-VALIDATED-FIELDS: Use builders for many optional fields or cross-field validation because constructors with many optional arguments or cross-field validation become hard to call correctly and hard to extend compatibly.
• RUST-USE-DEBUG-ASSERT-FOR-INTERNAL-INVARIANTS: Use debug_assert! for internal Rust invariants, not for public validation or safety requirements.
• RUST-USE-DIRECTORY-MODULES-AS-TABLES-OF-CONTENTS: Use directory-root modules as tables of contents because a directory-root module should orient readers to the submodules it owns.
• RUST-USE-DOC-INLINE-FOR-CANONICAL-REEXPORTS: Use #[doc(inline)] only for Rust re-exports whose facade path is the canonical public landing point.
• RUST-USE-FIELD-INIT-SHORTHAND: Use Rust field init shorthand for same-name fields unless explicit mapping clarifies conversion or meaning.
• RUST-USE-FUNCTIONS-FOR-INCIDENTAL-TYPES: Prefer regular functions because a type name is incidental and does not own the operation or invariant.
• RUST-USE-HONEST-MINIMUM-DEPENDENCIES: Use the lowest honest compatible dependency requirement because the manifest should state the lowest compatible dependency versions the crate honestly supports.
• RUST-USE-MEANINGFUL-STANDARD-TYPES: Use standard library types that carry meaning because standard library types such as PathBuf, NonZeroUsize, Duration, Cow, Arc, and Result carry familiar ownership and invariant signals.
• RUST-USE-SEND-STATIC-ACROSS-TASKS: Use Send + static bounds for values, futures, errors, and handles that cross task or thread boundaries.
• RUST-VALIDATE-BUILDERS-ON-BUILD: Validate Rust builder cross-field invariants in build and return an error for fallible construction.
• RUST-VALIDATE-PACKAGE-CONTENTS-BEFORE-RELEASE: Validate package contents before release because the crate package is what users receive, not the working tree.
• RUST-VALIDATE-RUST-DOCS-AS-CODE: After Rust documentation changes, run the relevant docs build, doctests, feature-gated checks, and Markdown lint for the changed surface.
• RUST-VALIDATE-SEMVER-BREAKS-AGAINST-EXTERNAL-USE: Validate semver-breaking changes against real external use because semver tools can detect many API breaks, but real downstream code shows how the public surface is actually used.
• RUST-VALIDATE-UNSAFE-THROUGH-SAFE-API: Validate Rust unsafe code through its safe API wrapper, with internal tests only as supporting evidence.
• RUST-WORKING-RUST-CODE-NOT-ENOUGH: Working Rust code is not enough because rust code can compile while still being hard to read, poorly documented, wrongly public, feature-fragile, or painful for downstream users.
• RUST-WRITE-ACTIONABLE-ERROR-DISPLAY: Write human-oriented and actionable error Display output because Display is often what users, CLIs, logs, and support messages show.
• RUST-WRITE-PUBLIC-DOCS-FOR-CALLER-TASKS: Write Rustdoc for caller tasks: begin with a concise behavior sentence, use prose for arguments, and cross-link only to improve understanding or auditability.
• RUST-WRITE-RUSTDOC-AS-API-CONTRACT: Write Rustdoc as caller-facing contract text, not decoration or generic prose.

Source And Context Hygiene

• SOURCE-GENERALIZE-PROJECT-SPECIFIC-RULES: Generalize project-specific rules before promotion because local mining often starts from one repository, tool, provider, or incident.
• SOURCE-KEEP-BINARIES-OUT-OF-SOURCE-CONTROL: Keep binary artifacts out of Git history; use Git LFS, release assets, PR uploads, CI artifacts, or external storage instead.
• SOURCE-MAKE-SHARED-ARTIFACTS-STANDALONE: Make shared docs, templates, generated packs, and reusable guidance stand alone because they leave the development session.
• SOURCE-PREFER-PRIMARY-STABLE-SOURCES: Use primary or stable sources because a reader needs to verify, compare, or challenge durable guidance.

Tests Should Explain Failures

• TEST-AVOID-OPAQUE-BOOLEAN-ASSERTIONS: Avoid boolean assertions for values with multiple failure causes because an assertion like assert!(items.contains(x)) or assert!(result.is_ok()) can fail for many reasons while showing little useful state.
• TEST-OPTIMIZE-FAILURE-OUTPUT: Optimize tests for useful failure output because a passing test is useful, but a failing test is where maintainers and agents spend repair time.
• TEST-SPLIT-UNRELATED-ASSERTIONS: Split unrelated assertions because one failing check would hide the real scope or cause of a regression.

Testing And Verification

• TEST-CHECK-IMPORTANT-FEATURE-COMBINATIONS: Test all features and important feature combinations because rust feature flags can change public API, optional dependencies, cfg-gated docs, and compile paths.
• TEST-CHECK-MAINTAINER-COMMANDS-IN-CI: If the README or maintainer guide says to run cargo test, cargo doc, markdownlint-cli2, or a release check, CI should exercise the same command or an intentionally stronger equivalent, check the same commands in CI that maintainers are expected to run locally.
• TEST-CHECK-MSRV-AND-PLATFORMS: Run MSRV and platform checks for crates that publish those compatibility claims.
• TEST-CHOOSE-VALIDATION-BY-RISK: Choose validation by risk because different changes need different proof.
• TEST-COVER-ASYNC-ROUTING-EDGE-CASES: Cover async routing cases for unrelated input, late replies, timeouts, unmatched responses, and wrong-request matches.
• TEST-COVER-LOCAL-LOGIC-WITH-UNIT-TESTS: Cover local logic with unit tests because small pure logic is cheapest to test close to where it lives.
• TEST-COVER-NAVIGATION-BOUNDARIES: Cover navigation and scroll boundaries in tests because navigation and scrolling bugs usually happen at the edges: empty lists, first item, last item, small viewport, oversized content, saturating offsets, and repeated key presses.
• TEST-COVER-POLICY-OUTCOMES: Cover allowed, denied, redacted, fallback, preserved, and unsupported outcomes in policy tests.
• TEST-COVER-PUBLIC-BOUNDARIES-WITH-INTEGRATION-TESTS: Use integration tests for public behavior that can break across modules, crates, features, or adapters despite passing unit tests.
• TEST-COVER-PUBLIC-EXAMPLES-WITH-DOCTESTS: Use doctests for public examples that teach humans and agents how to call the API and can compile without fragile assumptions.
• TEST-FUZZ-PARSERS-FORMATTERS-AND-STATE-MACHINES: Use fuzzing or property tests for parsers, formatters, decoders, state machines, and untrusted input with large edge-case spaces.
• TEST-KEEP-DRIFT-CLAIMS-ALIGNED: Use drift tests to keep support claims, fixtures, docs, examples, and public API paths aligned.
• TEST-KEEP-SLOW-CHECKS-OUT-OF-PR-CI: Keep slow fuzzing, long benchmarks, and exhaustive compatibility checks outside required PR CI unless they are fast and deterministic.
• TEST-MATCH-EVIDENCE-TO-SURFACE: Match validation evidence to the changed surface because a change to rendered docs, terminal layout, parser output, public API, or performance needs evidence from that surface.
• TEST-PREFER-DETERMINISTIC-TESTS: Prefer deterministic tests over timing or external-state tests because tests that depend on timing, network state, random ordering, real clocks, or external services fail for reasons unrelated to the code under review.
• TEST-PROVE-COMMAND-CONSTRUCTION-AND-DISPLAY: Prove command construction and display behavior in tests because command-building code can be wrong in quoting, argument order, display redaction, environment handling, or platform formatting while still invoking a happy path locally.
• TEST-PROVE-CONTRACTS-NOT-TRIVIA: Prove contracts with tests, not implementation trivia that makes refactoring expensive without proving user-visible behavior.
• TEST-RUN-DOCS-AS-FIRST-CLASS-GATE: Run docs as a first-class validation job because docs contain commands, examples, feature claims, public API paths, and Rustdoc links.
• TEST-RUN-FAST-FORMAT-AND-LINT-GATES-EARLY: Run formatting and clippy early because those failures are cheap to find and noisy to review.
• TEST-USE-REALISTIC-PARSER-SAMPLES: Use realistic samples and safe degradation cases in parser tests because parser tests built only from idealized examples miss real whitespace, ordering, partial data, unknown fields, legacy formats, invalid input, and safe degradation behavior.
• TEST-VALIDATE-DECLARED-MINIMUM-DEPENDENCY-VERSIONS: Validate declared minimum dependency versions because cargo manifests communicate the minimum compatible versions a downstream project may resolve.
• TEST-WRITE-REGRESSION-TESTS-FOR-BUG-FIXES: Write regression tests for bug fixes that could silently revert, especially edge cases, integration paths, and user-reported behavior.

JJ Topology And Source Control

• VCS-ASK-BEFORE-REPAIRING-JJ-ALIASES: Ask before repairing jj aliases that encode remote or bookmark assumptions, especially trunk() and publish helpers.
• VCS-AVOID-INTERACTIVE-JJ-IN-AGENT-WORK: Avoid interactive-by-default jj commands in unattended agent work because interactive jj commands can open editors, prompts, merge tools, or pagers that unattended agents cannot handle reliably.
• VCS-CONFIGURE-JJ-PAGER: Configure JJ_PAGER for agent tooling so paged output does not block or truncate command results.
• VCS-CONFIRM-BROAD-JJ-OPERATIONS: Treat broad jj operations as confirmation-worthy because commands that abandon, rebase, squash, split, restore, publish, or affect many revisions can rewrite a large part of the graph.
• VCS-CONFIRM-GITHUB-REMOTE-TOPOLOGY: Confirm GitHub origin and upstream topology before publication because forks and GitHub defaults can make origin mean the user fork while upstream means the canonical repo, or vice versa in owned repos.
• VCS-CREATE-OPERATION-LOG-POINT-BEFORE-RESHAPING: Before risky jj stack reshaping, run harmless inspection so there is a recent operation-log point for recovery.
• VCS-DO-NOT-FALL-BACK-TO-GIT-FOR-JJ-ISSUES: Stay in jj for transient jj lock or sandbox issues; Git does not represent the full jj change graph.
• VCS-DRY-RUN-SURPRISING-PUBLICATION: Use dry-run for surprising jj publication: ambiguous remote, new bookmark, force-like update, fork topology, or unclear PR base.
• VCS-DUPLICATE-FOR-ALTERNATIVE-CANDIDATES: Use jj duplicate for alternative fixes or refactor shapes so the original candidate stays available.
• VCS-INSPECT-SPARSE-STATE: Inspect sparse state before treating a missing path as missing history; sparse patterns can hide files that still exist.
• VCS-INSPECT-STATE-BEFORE-MUTATING: Before creating, squashing, rebasing, publishing, or editing files, the agent needs to know the current working copy, parent, bookmarks, conflicts, and unowned changes, inspect working-copy and stack state before mutating.
• VCS-JJ-AS-SOURCE-OF-TRUTH: Use jj as the source of truth in .jj repositories because a .jj repo has jj changes, operation log, working-copy state, and bookmarks layered over Git storage.
• VCS-JJ-NEW-FOR-REVIEW-LANES: Use jj new for separate review lanes because a new task needs a separate review lane before unrelated edits accumulate.
• VCS-MAKE-GITHUB-HANDOFF-EXPLICIT: Make GitHub handoff explicit after jj state is coherent because jj state and GitHub state are related but not identical.
• VCS-MATCH-JJ-TOPOLOGY-TO-REPO-ROLE: Match jj remote topology to the repository role because owned repos, maintainer-access repos, and fork-only contributor repos need different remote and bookmark topology.
• VCS-NAME-EXACT-JJ-MUTATION-TARGETS: Name exact revisions, filesets, bookmarks, and destinations for mutating jj commands instead of relying on stack-sensitive defaults.
• VCS-QUOTE-REVSETS-AND-SHELL-SYNTAX: Quote revsets and shell-sensitive syntax because revsets and bookmark syntax often contain characters such as @, |, &, ~, parentheses, or spaces that shells can interpret.
• VCS-RECOVER-WITH-OPERATION-LOG: Use operation-log recovery instead of destructive cleanup because jj records repository operations so many mistakes are recoverable without destructive Git reset or stash habits.
• VCS-REPAIR-REMOTE-TOPOLOGY-COHERENTLY: Repair remote topology coherently because remote topology has several coupled pieces: fetch remote, push remote, tracked bookmark, trunk alias, PR base, and PR head.
• VCS-RUN-JJ-MUTATIONS-SEQUENTIALLY: Run jj mutations sequentially because jj mutating commands update working-copy and operation state.
• VCS-SCOPE-JJ-FILE-TRACKING: Scope jj file track and untrack commands to intended paths because jj file track and jj file untrack can affect more files than intended if paths are omitted or globbed too broadly.
• VCS-STOP-REPEATED-JJ-RETRIES-AND-LOCALIZE-STATE: Stop repeated jj retries and localize state because repeating a failing jj command without new information usually compounds confusion.
• VCS-TRACK-REMOTES-EXPLICITLY: Track remotes explicitly for bookmark names that exist on multiple remotes so source and publication targets are clear.
• VCS-TREAT-BOOKMARK-REMOTE-SYNTAX-AS-VERSION-SENSITIVE: Treat bookmark@remote command syntax as version-sensitive because jj command syntax around bookmark@remote and remote bookmark handling can vary by version and command.
• VCS-USE-EVOLOG-AND-OPERATION-LOG: Use jj evolog for one change's evolution and jj op log for repository operations because jj evolog answers how one change evolved; jj op log answers how the repository state changed.
• VCS-USE-GIT-FORMATTED-DIFFS-FOR-AGENTS: Use Git-formatted diffs for agents and review tools that understand patch format better than native jj summaries.
• VCS-USE-IGNORE-WORKING-COPY-CAREFULLY: Use --ignore-working-copy only for lock-safe inspection or intended metadata work because it may skip current file snapshots.
• VCS-WORKSPACE-ADD-FOR-SECOND-CHECKOUTS: Use jj workspace add only for a second filesystem checkout; use jj new for another change in the same checkout.