diff --git a/AGENTS.md b/AGENTS.md index fb6d9bd..7db6e5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,151 +1,98 @@ -# PROJECT KNOWLEDGE BASE +# AGENTS.md -**Generated:** 2025-01-20T00:00:00Z -**Branch:** main -**Refresh:** reconciled against actual file tree and `plans/*`; verified scheduled event routing, config loader, handler symbols, manual `/zai update-agents` command, action.yml inputs, and test coverage. Fixed stale workflow filenames (replaced nonexistent `code-review.yml` with actual `zai-code-bot.yml`, `zai-agents-init-example.yml`). Confirmed: scheduled test coverage exists (`tests/handlers/scheduled.test.js`, `tests/scheduled-config.test.js`, `tests/repository-context.test.js`, `tests/agents-validation.test.js`); `docs/scheduled-tasks.md` present; README updated with scheduled-tasks section and `/zai update-agents` command. +## Repository overview -## OVERVIEW -JavaScript GitHub Action with three event flows: (1) PR auto-review, (2) collaborator-gated `/zai` PR comment commands, and (3) cron-triggered scheduled tasks (`.zai-scheduled.yml`) that regenerate AGENTS.md files and open PRs. Runtime executes bundled `dist/index.js`; maintained logic lives in `src/index.js` plus modular services in `src/lib/*`. +JavaScript GitHub Action (Node 20 runtime) with three event flows: +1. **PR auto-review** — automatic review on `opened`/`synchronize` events +2. **`/zai` PR comment commands** — collaborator-gated, parsed and authorized before dispatch +3. **Cron-triggered scheduled tasks** (`.zai-scheduled.yml`) that regenerate `AGENTS.md` files and open PRs + +Runtime executes `dist/index.js` (generated ncc bundle); maintained logic lives in `src/`. + +## Repository shape -## STRUCTURE ```text -zai-code-bot/ -├── src/index.js # Runtime orchestration and event dispatch -├── src/lib/ # Commands/auth/context/comments/api/services -├── src/lib/events.js # Event-type detection incl. `schedule` (cron) routing -├── src/lib/commands.js # `/zai` parser + allowlist (incl. `update-agents`) -├── src/lib/auto-review.js # Large PR batching and synthesis -├── src/lib/changed-files.js # Paginated changed-files fetch (3000 file limit) -├── src/lib/pr-context.js # Shared PR context fetch (files, content at ref, refs) -├── src/lib/code-scope.js # Token-budget calculation for prompt sizing -├── src/lib/context.js # Changed-file fetch + truncation/range helpers -├── src/lib/config/scheduled-config.js # Scheduled-task config loader (.zai-scheduled.yml) -├── src/lib/repository-context.js # Real repo context collection (tree + AGENTS.md discovery + key files) -├── src/lib/agents-validation.js # Hallucination guard: validates generated AGENTS.md vs real repo -├── src/lib/handlers/ # Command + scheduled handlers (ask/review/explain/describe/impact/help/scheduled) -├── tests/ # Unit and integration coverage (Vitest v3) -├── dist/index.js # Generated ncc bundle executed by GitHub -├── dist/licenses.txt # Generated third-party licenses -├── action.yml # Action inputs (incl. ZAI_SCHEDULED_*, ZAI_AGENTS_GIST_URL) -├── .zai-scheduled.yml # Scheduled-task config for THIS repo (AGENTS.md upkeep) -├── .zai-scheduled.yml.template # Consumer template for scheduled tasks -├── .github/workflows/ci.yml # Test/build/dist-drift/audit gates -├── .github/workflows/zai-agents-update.yml # Self-hosted scheduled AGENTS.md upkeep -├── .github/workflows/zai-code-bot.yml # Bot execution on this repo's own PRs -├── .github/workflows/zai-agents-init-example.yml # Example workflow for AGENTS.md init -├── docs/scheduled-tasks.md # Scheduled-tasks configuration reference -├── plans/ # Planning docs (scheduled-tasks integration) -├── ARCHITECTURE.md # Layered architecture and invariants catalog -├── CONTRIBUTING.md # Contribution guide and review checklists -├── RUNBOOK.md # Operational runbook and rollback procedures -├── SECURITY.md # Security policies and authorization rules -├── README.md # User-facing inputs, commands, quickstart -└── vitest.config.js # Vitest configuration +src/index.js # Runtime entrypoint: event dispatch + all pipelines +src/lib/ # Services layer (events, commands, auth, api, context, comments) +src/lib/handlers/ # Per-command handler modules +src/lib/config/scheduled-config.js # Scheduled-task config loader (.zai-scheduled.yml) +tests/ # Vitest v3 suite (unit + integration) +dist/ # Generated ncc bundle — CI runs this, not src/ +action.yml # Action manifest + input definitions +.zai-scheduled.yml # Scheduled-task config for this repo +.zai-scheduled.yml.template # Consumer template for scheduled tasks +plans/ # Planning docs (scheduled-tasks integration) ``` -## WHERE TO LOOK -| Task | Location | Notes | -|------|----------|-------| -| Route events and command execution | `src/index.js` | `run()`, pull_request path, issue_comment command path, schedule path | -| Schedule event detection | `src/lib/events.js` | `getEventType` returns `schedule`; `shouldProcessEvent` always processes cron events | -| Parse commands and enforce allowlist | `src/lib/commands.js` | `/zai` parser, command normalization, help fallback; `update-agents` in allowlist | -| Authorization and fork policy | `src/lib/auth.js` | Collaborator checks and fork-safe behavior | -| Comment/reaction behavior | `src/lib/comments.js` | Marker-based upsert, threaded reply (`replyToId`), reactions | -| API retry/error handling | `src/lib/api.js`, `src/lib/logging.js` | Retry policy, categorized safe errors | -| Large PR batching and synthesis | `src/lib/auto-review.js` | Batch creation, context limit handling, synthesis prompt | -| Paginated changed-files fetch | `src/lib/changed-files.js` | Handles GitHub's 3000 file API limit | -| Shared PR context fetch | `src/lib/pr-context.js` | `fetchPrFiles`, `fetchFileAtRef`, `resolvePrRefs`; user-safe fallbacks, size limits | -| Token budget calculation | `src/lib/code-scope.js` | Window extraction, enclosing block detection for prompt sizing | -| Scheduled-task config loading | `src/lib/config/scheduled-config.js` | `loadScheduledConfig`, `getTasksToRun`, `validateAndNormalizeConfig`, `validateAgentsConfig`, `getGistUrl`; scoping fields (`context_paths`/`target_paths`/`exclude_paths`/budgets) | -| Scheduled-task execution | `src/lib/handlers/scheduled.js` | `handleScheduledEvent`, `handleUpdateAgentsTask` (grounded flow: context→prompt→validate→PR), `SCHEDULED_HANDLERS`; see child `src/lib/handlers/AGENTS.md` | -| Repository context for AGENTS.md gen | `src/lib/repository-context.js` | `collectRepositoryContext` (git tree + existing AGENTS.md discovery + key files, budgeted), `renderRepositoryContext` | -| AGENTS.md output validation | `src/lib/agents-validation.js` | `validateGeneratedAgentFiles` — rejects non-AGENTS paths, out-of-scope writes, and hallucinated content referencing non-existent files | -| Manual `/zai update-agents` | `src/index.js` (`dispatchCommand`) | Reuses `handleUpdateAgentsTask` for ad-hoc AGENTS.md updates | -| Command-specific behavior | `src/lib/handlers/AGENTS.md` | Local guide for each handler module | -| Test strategy and fixtures | `tests/AGENTS.md` | Test map and suite conventions | -| Scheduled-tasks reference | `docs/scheduled-tasks.md` | Configuration reference, cron syntax, troubleshooting | -| Architecture and invariants | `ARCHITECTURE.md` | Layered architecture, dependency direction, life-of-request flows | -| Operational procedures | `RUNBOOK.md` | Rollback and incident response | -| Security policies | `SECURITY.md` | Authorization rules and permission model | -| Action runtime contract | `action.yml` | Node 20 runtime + dist entrypoint | -| Build and drift policy | `package.json`, `.github/workflows/ci.yml` | `ncc` build and `dist/` drift gate | - -## CODE MAP -| Symbol | Type | Location | Refs | Role | -|--------|------|----------|------|------| -| `run` | function | `src/index.js` | high | Top-level event gate + dispatcher | -| `handlePullRequestEvent` | function | `src/index.js` | medium | PR auto-review flow | -| `handleIssueCommentEvent` | function | `src/index.js` | high | Command parse/auth/progress/dispatch flow | -| `handlePullRequestReviewCommentEvent` | function | `src/index.js` | high | Inline review comment command flow | -| `dispatchCommand` | function | `src/index.js` | high | Handler selection and response management | -| `enforceCommandAuthorization` | function | `src/index.js` | medium | Auth gate before command dispatch | -| `parseCommand` | function | `src/lib/commands.js` | high | Command extraction and validation | -| `checkForkAuthorization` | function | `src/lib/auth.js` | medium | Fork-aware security policy | -| `buildHandlerContext` | function | `src/lib/context.js` | medium | Shared context for handlers | -| `upsertComment` | function | `src/lib/comments.js` | high | Marker idempotency + threaded reply support | -| `callWithRetry` | function | `src/lib/api.js` | medium | API retry/backoff wrapper | -| `saveContinuityState` | function | `src/lib/continuity.js` | medium | Hidden state persistence across turns | -| `createReviewBatches` | function | `src/lib/auto-review.js` | medium | Large PR file chunking | -| `fetchAllChangedFiles` | function | `src/lib/changed-files.js` | medium | Paginated file list (3000 limit) | -| `fetchPrFiles` | function | `src/lib/pr-context.js` | medium | PR file list with size limits + fallbacks | -| `fetchFileAtRef` | function | `src/lib/pr-context.js` | medium | File content at base/head ref, sliding-window scoping | -| `resolvePrRefs` | function | `src/lib/pr-context.js` | low | Resolves base/head refs for diff context | -| `MAX_PR_FILES_API_LIMIT` | constant | `src/lib/changed-files.js` | low | GitHub API ceiling (3000) | -| `calculateTokenBudget` | function | `src/lib/code-scope.js` | medium | Token/char budget sizing for prompts | -| `getEventType` | function | `src/lib/events.js` | low | Event-type detection for routing (incl. `schedule`) | -| `shouldProcessEvent` | function | `src/lib/events.js` | low | Event filter; always-process gate for cron events | -| `loadScheduledConfig` | function | `src/lib/config/scheduled-config.js` | low | Parses `.zai-scheduled.yml` task config | -| `validateAndNormalizeConfig` | function | `src/lib/config/scheduled-config.js` | low | Schema validation + default-merging for tasks | -| `getTasksToRun` | function | `src/lib/config/scheduled-config.js` | low | Filters tasks whose schedule matches the event | -| `getGistUrl` | function | `src/lib/config/scheduled-config.js` | low | Resolves gist URL priority: task > defaults > env | -| `handleScheduledEvent` | function | `src/lib/handlers/scheduled.js` | medium | Scheduled pipeline entry: load config, run matching tasks | -| `executeScheduledTask` | function | `src/lib/handlers/scheduled.js` | medium | Per-task executor; builds context, dispatches via registry | -| `handleUpdateAgentsTask` | function | `src/lib/handlers/scheduled.js` | medium | AGENTS.md regeneration: gist → collect repo context → grounded Z.ai prompt → validate → JSON diff → PR | -| `SCHEDULED_HANDLERS` | constant | `src/lib/handlers/scheduled.js` | low | Command→handler registry; `getScheduledHandler`/`registerScheduledHandler` extend it | -| `buildAgentsUpgradePrompt` | function | `src/lib/handlers/scheduled.js` | low | Grounded prompt: embeds real tree + existing AGENTS.md + key files; tells model it has NO live repo access | -| `parseFileUpdatesFromResponse` | function | `src/lib/handlers/scheduled.js` | low | Multi-format JSON extraction from Z.ai output | -| `callZaiApiWithRetry` | function | `src/lib/handlers/scheduled.js` | low | Z.ai HTTP client (native https) with retry for scheduled tasks | -| `fetchFromUrl` | function | `src/lib/handlers/scheduled.js` | low | HTTP GET for gist command text (30s timeout) | -| `createPR` | function | `src/lib/handlers/scheduled.js` | low | Branch + multi-file commit + PR open for scheduled changes | -| `collectRepositoryContext` | function | `src/lib/repository-context.js` | medium | git.getTree → existing AGENTS.md discovery + key-file contents, budgeted + glob-excluded | -| `renderRepositoryContext` | function | `src/lib/repository-context.js` | low | Renders collected context into a compact prompt block | -| `validateGeneratedAgentFiles` | function | `src/lib/agents-validation.js` | medium | Pre-PR guard: rejects non-AGENTS paths, out-of-scope/target writes, and hallucinated content | -| `validateAgentsConfig` | function | `src/lib/config/scheduled-config.js` | low | Validates scoping/budget config fields (`context_paths`, `target_paths`, etc.) | - -## CONVENTIONS -- Edit maintained code in `src/`; do not hand-edit generated `dist/index.js`. -- After source changes, run `npm run build` and commit `dist/index.js` + `dist/licenses.txt`. -- Use marker-based idempotent comments; preserve marker constants and update semantics. -- Command responses should stay threaded to the invoking comment via `replyToId`. -- Keep security posture strict: collaborator/fork checks before command execution, no secret leakage. - -## ANTI-PATTERNS (THIS PROJECT) -- Bypassing authorization/fork checks for command handlers. -- Executing command logic for non-PR issue comments. -- Allowing unbounded context payloads into prompts. -- Asking an LLM to "scan the repo" without providing real repo context (causes hallucinated AGENTS.md — PR #15 bug). -- Committing AGENTS.md output that references files/languages not present in the repo. -- Editing `dist/` manually or shipping source changes without rebuilt artifacts. -- Confusing consumer-facing workflow examples (README snippet) with this repo's own `.github/workflows/` runtime logic. - -## UNIQUE STYLES -- Event-first architecture: `src/index.js` orchestrates; `src/lib/*` isolates concerns. -- Reactions communicate command lifecycle (`eyes`/`thinking`/`rocket`/`x`). -- Continuity is encoded with hidden markers in comments, not external storage. - -## COMMANDS -```bash -npm install -npm test # vitest run --coverage -npm run build # ncc build src/index.js -o dist --license licenses.txt -npm audit --audit-level=moderate # security audit gate (CI) +## Architecture and boundaries + +Strict downward dependency direction: + ``` -After source changes: run `npm run build` and commit `dist/index.js` + `dist/licenses.txt` (CI fails on dist drift). - -## NOTES -- CI (`.github/workflows/ci.yml`) enforces tests, build, dist drift, and security audit across Node 20 + 22. -- No linting/formatting configs (ESLint, Prettier) — rely on code review and CI gates. -- 7 command handlers + scheduled pipeline: `ask`, `review`, `explain`, `describe`, `impact`, `help`, plus `scheduled` (largest handler, drives cron tasks via `.zai-scheduled.yml`). -- Scheduled test coverage: `tests/handlers/scheduled.test.js`, `tests/scheduled-config.test.js`, `tests/repository-context.test.js`, `tests/agents-validation.test.js` (unit-level); end-to-end schedule integration test is still a gap. -- Scheduled-tasks configuration reference: `docs/scheduled-tasks.md`. -- Architecture and invariants catalog: `ARCHITECTURE.md`. +src/index.js (orchestration) → src/lib/*.js (services) → src/lib/handlers/*.js (commands) +``` + +Non-negotiable invariants: +- GitHub executes `dist/index.js` only; all maintained logic lives in `src/`. +- After source changes: `npm run build` → commit `dist/index.js` + `dist/licenses.txt`. +- Command handlers run only after `enforceCommandAuthorization` succeeds. +- Automated comments are marker-idempotent (``, ``, etc.) and threaded via `replyToId`. +- Prompts use bounded context via `code-scope.js` / `context.js`; never raw unbounded patches. +- No raw exceptions or secrets surfaced in PR comments; use `src/lib/logging.js` for safe errors. + +## Context routing + +Read only when relevant: +- Architectural changes, dependency direction, data flows → `ARCHITECTURE.md` +- Rollback and incident response → `RUNBOOK.md` +- Authorization rules and permission model → `SECURITY.md` +- Contribution guide and review checklists → `CONTRIBUTING.md` +- Scheduled-tasks configuration reference → `docs/scheduled-tasks.md` +- Services-layer module guide → `src/lib/AGENTS.md` +- Per-command handler details → `src/lib/handlers/AGENTS.md` +- Test strategy and suite layout → `tests/AGENTS.md` +- Integration test guide → `tests/integration/AGENTS.md` + +## Key symbols + +| Symbol | Location | Role | +|--------|----------|------| +| `run` | `src/index.js` | Top-level event gate + dispatcher | +| `dispatchCommand` | `src/index.js` | Handler selection and response management | +| `enforceCommandAuthorization` | `src/index.js` | Auth gate before command dispatch | +| `handlePullRequestEvent` | `src/index.js` | PR auto-review flow | +| `handleIssueCommentEvent` | `src/index.js` | Issue comment command flow | +| `handleScheduledEvent` | `src/lib/handlers/scheduled.js` | Scheduled pipeline entry | +| `handleUpdateAgentsTask` | `src/lib/handlers/scheduled.js` | Grounded AGENTS.md regen: context → prompt → validate → PR | +| `parseCommand` | `src/lib/commands.js` | `/zai` parser + command allowlist | +| `checkForkAuthorization` | `src/lib/auth.js` | Fork-aware collaborator auth policy | +| `upsertComment` | `src/lib/comments.js` | Marker upsert + threaded replies + reactions | +| `callWithRetry` | `src/lib/api.js` | Z.ai API retry/backoff/timeout/fallback | +| `createReviewBatches` | `src/lib/auto-review.js` | Large PR file chunking + synthesis | +| `fetchAllChangedFiles` | `src/lib/changed-files.js` | Paginated fetch (3000-file API limit) | +| `collectRepositoryContext` | `src/lib/repository-context.js` | Real repo context for AGENTS.md generation | +| `validateGeneratedAgentFiles` | `src/lib/agents-validation.js` | Hallucination guard: rejects non-AGENTS paths, out-of-scope writes, fabricated content | +| `loadScheduledConfig` | `src/lib/config/scheduled-config.js` | `.zai-scheduled.yml` parser + task filter | + +## Change rules + +- Edit source in `src/`; never hand-edit `dist/index.js`. +- Handler-specific logic belongs in `src/lib/handlers/`, not in services or `src/index.js`. +- Services-layer modules stay policy-centric; orchestration stays in `src/index.js`. +- Preserve comment marker constants and their update semantics. +- Return user-safe failures; log internal details via `src/lib/logging.js`. + +## Validation + +- `npm test` → `vitest run --coverage` +- `npm run build` → `ncc build src/index.js -o dist --license licenses.txt` +- CI (`.github/workflows/ci.yml`) gates: test, build, dist-drift, security audit. + +## Gotchas + +- **dist drift**: CI fails if `dist/index.js` doesn't match a fresh `ncc` build of `src/`. +- **Two `fetchChangedFiles`**: `src/lib/changed-files.js` exports the paginated fetcher; `src/lib/context.js` also exports a `fetchChangedFiles` with truncation/range helpers. `src/index.js` imports both (aliasing the paginated one as `fetchChangedFilesPaginated`). +- **3000-file ceiling**: `changed-files.js` caps at GitHub's API limit; auto-review coverage notes flag incomplete reviews beyond that. +- **Silent fork block**: Non-collaborator commands on fork PRs are silently blocked by design (see `SECURITY.md`). +- **`scheduled` handler routing**: Not in the `/zai` command dispatcher switch; runs via cron events and the `/zai update-agents` manual command path in `src/index.js`. +- **Grounded AGENTS.md generation**: `handleUpdateAgentsTask` embeds real repo tree + existing AGENTS.md + key files into the prompt, validates output against the actual tree, and rejects hallucinated files before creating a PR. diff --git a/tests/AGENTS.md b/tests/AGENTS.md index 4fb56f8..572f5ce 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -1,46 +1,53 @@ -# TEST SUITE GUIDE +# AGENTS.md -## OVERVIEW -Repository test coverage mixes module-focused tests in `tests/*.test.js` and scenario-driven flows in `tests/integration/*`. +## Scope and inheritance + +Applies to: `tests/`. + +Inherits repository-wide guidance from `AGENTS.md`. + +This file defines only local differences for the test suite. + +## What lives here -## STRUCTURE ```text tests/ -├── *.test.js # Module-level tests for lib/runtime units -├── handlers/ # Handler-focused test cases (ask, explain, impact, review, scheduled) -├── helpers/ # Shared mocks and fixtures utilities -├── lib/ # Shared test helpers + code-scope tests -├── fixtures/ # Static test payloads (issue-comment-event.json, pr-event.json) -└── integration/ # End-to-end command/review pipeline checks +├── *.test.js # Module-level tests (commands, auth, api, context, etc.) +├── handlers/ # Handler-focused tests (ask, explain, impact, review, scheduled) +├── helpers/mocks.js # Shared mock utilities +├── lib/code-scope.test.js # Token budget and window extraction tests +├── fixtures/ # Static payloads (issue-comment-event.json, pr-event.json) +└── integration/ # End-to-end pipeline tests (see child AGENTS.md) ``` -## WHERE TO LOOK -| Task | Location | Notes | +## Test layout and coverage + +| Area | Location | Notes | |------|----------|-------| -| Parser/auth/comment unit behavior | `tests/commands.test.js`, `tests/auth.test.js`, `tests/comments.test.js` | Fast regression checks | -| Runtime orchestration checks | `tests/action.test.js`, `tests/handlers.test.js`, `tests/index.test.js` | Entry flow and dispatch behavior | +| Parser/auth/comment units | `tests/commands.test.js`, `tests/auth.test.js`, `tests/comments.test.js` | Fast regression checks | +| Runtime orchestration | `tests/action.test.js`, `tests/handlers.test.js`, `tests/index.test.js` | Entry flow and dispatch behavior | | API and logging resilience | `tests/api.test.js`, `tests/logging.test.js` | Retry/error categorization | -| Context, PR fetch, and batching | `tests/context.test.js`, `tests/pr-context.test.js`, `tests/changed-files.test.js`, `tests/auto-review.test.js` | Diff scoping, file-at-ref fetch, paginated/batched review | +| Context, PR fetch, batching | `tests/context.test.js`, `tests/pr-context.test.js`, `tests/changed-files.test.js`, `tests/auto-review.test.js` | Diff scoping, file-at-ref, pagination, batched review | | Continuity and events | `tests/continuity.test.js`, `tests/events.test.js` | Hidden-marker state, event-type detection | -| Code scope and window extraction | `tests/lib/code-scope.test.js` | Token budget, enclosing block, window extraction | +| Code scope | `tests/lib/code-scope.test.js` | Token budget, enclosing block, window extraction | | Describe handler | `tests/describe.test.js` | PR description generation | -| Scheduled pipeline | `tests/handlers/scheduled.test.js`, `tests/scheduled-config.test.js`, `tests/repository-context.test.js`, `tests/agents-validation.test.js` | Config load + `validateAgentsConfig` scoping; `parseFileUpdatesFromResponse`; grounded `handleUpdateAgentsTask` flow incl. hallucination rejection; repo-context collection (tree/budgets/globs); validation guards incl. PR #15 regression | -| Scheduled pipeline (integration) | (pending) | End-to-end schedule event → context → Z.ai mock → validated PR is still a gap; unit coverage of the grounded flow exists via the `handleUpdateAgentsTask` seam (`__callZaiForTest`). | -| Full command pipeline | `tests/integration/command-pipeline.test.js` | Parse -> auth -> handler -> output contract | -| PR auto-review behavior | `tests/integration/pr-auto-review.test.js` | Marker upsert and PR event lifecycle | +| Scheduled pipeline | `tests/handlers/scheduled.test.js`, `tests/scheduled-config.test.js`, `tests/repository-context.test.js`, `tests/agents-validation.test.js` | Config, scoping, grounded flow, hallucination rejection | +| Full command pipeline | `tests/integration/command-pipeline.test.js` | Parse → auth → handler → output contract | +| PR auto-review | `tests/integration/pr-auto-review.test.js` | Marker upsert and PR event lifecycle | + +Note: End-to-end scheduled event → context → Z.ai mock → validated PR integration test is still a gap; unit coverage of the grounded flow exists via the `handleUpdateAgentsTask` seam. + +## Conventions -## CONVENTIONS -- Test framework: Vitest v3 (uses vitest globals: describe/test/expect); configured via `vitest.config.js`. +- Test framework: Vitest v3 (globals: `describe`/`test`/`expect`); configured via `vitest.config.js`. +- Test command: `npm test` → `vitest run --coverage`. +- Coverage uploaded to Codecov. - Keep tests deterministic with explicit mock payloads and marker assertions. - Prefer scenario names that encode trigger + expected visible outcome. -- When changing comment markers or command UX, update integration snapshots/assertions immediately. +- When changing comment markers or command UX, update integration assertions immediately. + +## Anti-patterns -## ANTI-PATTERNS - Deleting integration assertions to make behavior changes pass. - Asserting only internal calls without validating user-visible output. - Duplicating large fixtures inline when reusable fixtures already exist. - -## NOTES -- Test command: `npm test` → `vitest run --coverage`. -- Coverage uploaded to Codecov. -- Integration tests are the safety net for command threading and marker idempotency.