AGENTS.md
+61 −19
https://raw.githubusercontent.com/raccioly/docguard/HEAD/AGENTS.md
− <!-- docguard:last-reviewed 2026-09-30 -->− `explain` (explain a validator/warning), `verify` (declared evidence; `--semantic` claims), `feedback` (report false positives), `mcp` (MCP server; stdio or loopback HTTP), `report` (compliance bundle), `ci` (guard + score gate), `memory` (what DocGuard− remembers; `--pack [--symbols]` for the context pack), `trace` (requirements traceability; `--reverse`; `--owners` for the doc ownership map), `upgrade` (check npm for a newer− release and migrate the config schema; `--apply --schema-only` stays offline), `watch` (live re-guard).− --write`; never edit generated intent/evidence fields or treat bare requirement− IDs as completion proof.− ### Automated agents / bots (Jules "Sentinel", "Bolt", "Palette", and any auto-PR agent)− - **Never open a duplicate PR.** Before opening ANY PR, search existing **open− AND closed** PRs and issues for the same topic/title. If it exists, STOP — do− not open another. (Dozens of duplicate command-injection and diff-optimization− PRs were closed as noise.)− - **Do not re-open resolved work.** See `.jules/sentinel.md` (execSync/command− injection — RESOLVED in v0.21.1 + #296) and `.jules/bolt.md` (diff/scan− micro-optimizations — already applied; code refactored since). These are− historical learnings, **not** standing mandates to re-scan every run.− - **Bar for a new PR:** a genuinely new, unaddressed finding, with evidence — a− concrete exploit path / failing test (security) or a benchmark showing >20%− real-workload improvement (performance). A Big-O note alone is insufficient.− - This repo has **no web UI and no VS Code extension** — skip all UX tasks.+ <!-- docguard:last-reviewed 2026-10-13 -->+ `anchors` (code→requirement links and whether each changed since review; `accept` records a review),+ `explain` (explain a validator/warning), `verify` (declared evidence; `--semantic` claims), `ignore` (every suppression with its reason and expiry), `feedback` (report false positives), `mcp` (MCP server; stdio or loopback HTTP; tool calls stay inside the served directory and each `--root`), `report` (compliance bundle), `ci` (guard + score gate), `memory` (what DocGuard+ remembers; `--pack [--symbols]` for the context pack), `trace` (requirements traceability; `--reverse`; `--owners` for the doc ownership map; `--matrix` exports requirement → anchor → test), `upgrade` (check npm for a newer+ release and migrate the config schema; `--apply` also refreshes out-of-date agent files and the registered Spec Kit extension; `--apply --schema-only` stays offline), `watch` (live re-guard).+ --write` and record approval with `specs approve --id <id> --write`; never edit+ generated intent/evidence fields or treat bare requirement IDs as completion proof.+ The CI test job fails any single test over 100 seconds at reference-runner+ speed (`TEST_CEILING_MS`, `tools/suite-runtime-budget.mjs`); the suite total+ is reported, not gated (specs/051-release-cut-green FR-007, TEST-SPEC.md).+ - Regenerate checked-in generated files in the same change; each has a drift test+ that fails and names its command: `npm run llms` after editing a canonical or+ optional doc (`llms.txt`, `llms-full.txt`), `npm run docs:reference` after+ changing a finding code or a validator's display name (the docs site's+ finding-code reference), and `npm run generate:precision-evidence` after+ a reviewed benchmark baseline change (`cli/precision-evidence-data.mjs`).+ - **Tests that build Git repositories pass the fixture options per call.** Every+ fixture `git` call goes through `tests/helpers/git.mjs` (`FIXTURE_GIT`,+ `fixtureGit`): hooks and signing off for that call, never for the whole+ environment, so DocGuard's own Git calls still meet the machine's config. A+ scan test rejects a direct `git` spawn without a `fixture-git-exempt:`+ reason, and the CI `hermeticity` job runs the suite under a hostile global+ config (specs/066-test-git-hermeticity).+ - **Workflow jobs run code without a repository write token.** Workflows default+ to `contents: read`; a job asks for its own scope. A job that runs tests or+ DocGuard holds no write permission and checks out with+ `persist-credentials: false`; a job holding `contents`, `actions`,+ `pull-requests` or `issues` write runs no package manager, build tool or test.+ `tests/workflow-permissions.test.mjs` enforces it+ (specs/068-release-least-privilege).+ - **A changed requirement link is reviewed, not silenced.** This repository+ commits `.docguard-anchor-lock.jsonl`, so guard reports a link whose code or+ requirement changed since its review (ANC001, ANC002) or whose tag is gone+ (ANC003); ANC001 and ANC003 fail guard for a link accepted as reviewed. Read+ the change, then run `docguard anchors accept --link '<key>'` (or+ `--file <path> --bulk` for a file you changed) with a `--reason` that says+ what you checked. Accept only links in files your change touched. The lock+ merges with `merge=union`: after a rebase, ANC009 means two lines for one+ link, so restore `origin/main`'s lock and re-accept only your own files.+ CODEOWNERS sends every lock change to a maintainer
