chore: update AGENTS.md files

AGENTS.md

@@ -2,7 +2,7 @@
 
 **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.
+**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. 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.
 
 ## 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/*`.
@@ -115,37 +115,29 @@ zai-code-bot/
 ## 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.
+- Use marker-based idempotent comments; preserve marker constants (`COMMENT_MARKER`, `PROGRESS_MARKER`, `AUTH_MARKER`, `GUIDANCE_MARKER`) and update semantics.
+- Command responses must stay threaded to the invoking comment via `replyToId`; never post top-level comments for command replies.
+- Keep prompts bounded via `src/lib/code-scope.js` and `src/lib/context.js`; never pass raw unbounded patches into Z.ai prompts.
+- Return user-safe error messages; route internal details through `src/lib/logging.js` categorized safe errors.
+- Reactions (`eyes`, `thinking`, `rocket`, `x`) indicate lifecycle: acknowledge → work → success/failure.
 
-## 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)
-```
-After source changes: run `npm run build` and commit `dist/index.js` + `dist/licenses.txt` (CI fails on dist drift).
+## ANTI-PATTERNS
+- Hand-editing `dist/index.js` instead of rebuilding from `src/`.
+- Running command handlers before `enforceCommandAuthorization` succeeds.
+- Posting unthreaded command replies (breaks conversational threading and duplicates context).
+- Passing unbounded diffs or full-file dumps into Z.ai prompts.
+- Surfacing raw exception internals or secrets in PR comments.
+- Introducing ad-hoc GitHub/Z.ai I/O calls in handlers instead of routing through `src/lib/api.js` and `src/lib/pr-context.js`.
+- Creating non-`AGENTS.md` files or out-of-scope writes in the scheduled `update-agents` task (rejected by `validateGeneratedAgentFiles`).
 
 ## 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`.
+- Build: `npm run build` (ncc bundles `src/index.js` → `dist/index.js` + `dist/licenses.txt`).
+- Test: `npm test` → `vitest run --coverage`.
+- CI gates: test, build, dist-drift (fails on uncommitted `dist/` changes), security audit (`.github/workflows/ci.yml`).
+- Action runtime: Node 20 (`action.yml` `using: "node20"`, `main: "dist/index.js"`).
+- Scheduled config: `.zai-scheduled.yml` (this repo), `.zai-scheduled.yml.template` (consumer template).
+- Gist URL priority for `update-agents`: task config `gist_url` > defaults `gist_url` > `ZAI_AGENTS_GIST_URL` action input.
+- Default model: `glm-5.2` (overridable via `ZAI_MODEL`).
+- See `ARCHITECTURE.md` for layered architecture, dependency direction, and life-of-request flows.
+- See `RUNBOOK.md` for rollback and incident response.
+- See `SECURITY.md` for authorization rules and the fork-PR permission model.

tests/AGENTS.md

@@ -8,8 +8,8 @@ Repository test coverage mixes module-focused tests in `tests/*.test.js` and sce
 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
+├── helpers/         # Shared mocks and fixtures utilities (mocks.js)
+├── lib/             # Shared test helpers + code-scope tests (code-scope.test.js)
 ├── fixtures/        # Static test payloads (issue-comment-event.json, pr-event.json)
 └── integration/     # End-to-end command/review pipeline checks
 ```
@@ -19,28 +19,30 @@ tests/
 |------|----------|-------|
 | 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 |
-| API and logging resilience | `tests/api.test.js`, `tests/logging.test.js` | Retry/error categorization |
+| API and logging resilience | `tests/api.test.js`, `tests/logging.test.js` | Retry/error categorization, progressive timeout, fallback prompt |
 | 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 |
-| Continuity and events | `tests/continuity.test.js`, `tests/events.test.js` | Hidden-marker state, event-type detection |
+| Continuity and events | `tests/continuity.test.js`, `tests/events.test.js` | Hidden-marker state, event-type detection incl. `schedule` |
 | Code scope and window extraction | `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 |
+| 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 e2e schedule-event integration is not yet wired. |
+| 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 |
 
 ## CONVENTIONS
 - Test framework: Vitest v3 (uses vitest globals: describe/test/expect); configured via `vitest.config.js`.
 - 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.
+- Handler unit tests inject mock dependencies (octokit, apiClient) via constructor or `deps` parameter — do not wire real HTTP calls.
 
 ## 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.
+- Duplicating large fixtures inline when reusable fixtures already exist in `tests/fixtures/` or `tests/integration/fixtures/`.
 
 ## NOTES
 - Test command: `npm test` → `vitest run --coverage`.
 - Coverage uploaded to Codecov.
 - Integration tests are the safety net for command threading and marker idempotency.
+- `tests/helpers/mocks.js` provides shared mock factories; prefer it over ad-hoc inline mocks.