Skip to content

AGENTS.md

Latest commit

 

History

History
119 lines (79 loc) · 7.62 KB

AGENTS.md

File metadata and controls

119 lines (79 loc) · 7.62 KB
Raw

Agent Instructions

These instructions apply repository-wide.

Skills System

Canonical AI-facing engineering skills live under docs/engineering/skills/. Use those files as the source of truth across Codex, Claude, Copilot, and other AI tools.

When adding an HTTP route or changing an existing route's query-parameter contract, read docs/engineering/skills/api-routes.md.

When changing API v2 migration contracts, route-group migration metadata, PR cutover plans, generated migration docs, or migration guard scripts, read docs/engineering/skills/migration_contracts.md.

When adding, moving, or reviewing tests, read docs/engineering/skills/testing.md.

When changing SQLAlchemy models, Alembic configuration, database schemas, or migration revisions, read docs/engineering/skills/alembic-migrations.md.

When adding or moving API v2 route, service, or database-access modules, read docs/engineering/skills/v2-code-organization.md.

When changing correlation identifiers, telemetry transport, spans, stage names, logging, or observability failure handling, read docs/engineering/skills/observability.md.

When modifying the Makefile, read docs/engineering/skills/repository-maintenance.md.

When adding or changing a GitHub Actions workflow step or a script under .github/scripts/, read docs/engineering/skills/ci-workflows.md.

When adding, changing, or removing a rule, a guard test, a checker configuration, or a CI job that enforces one, read docs/engineering/skills/rules-registry.md.

GitHub PRs

Read docs/engineering/skills/github-prs.md before opening, replacing, or sharing any pull request. Every PR needs a tracking issue and Fixes #ISSUE_NUMBER as the first line of its description. Agents must never bypass branch rules (for example with gh pr merge --admin).

Before creating or sharing a migration PR, run the focused migration guards:

python scripts/run_quality_guards.py
python scripts/export_migration_contracts.py

Safety Boundaries

Do not claim a route, database table, compute path, or deployment surface has migrated unless the relevant contract tests, migration flags, and generated migration docs identify that state.

Rules

Every rule for this repository lives in rules/registry.toml and is rendered, with its enforcement and gaps, in docs/generated/rules.md. Blocking rules fail CI. Doc-only rules are not checked automatically, so follow them yourself. To add or change a rule, read docs/engineering/skills/rules-registry.md.

API v2 layer boundaries

  • Checked: api.v2.connectors-mutations-no-reads, api.v2.connectors-reads-no-mutations, api.v2.crud-checks-cover-every-resource, api.v2.session-modules-no-queries, api.v2.user-services-no-sql, api.v2.validators-transformations-no-db
  • api.routes.shared-query-parameters: Routes that accept query parameters define them through the shared typed query models, never with a second manual parser. (doc-only, not checked: follow it yourself)
  • api.v2.connectors-never-commit: v2 connectors receive a session from the service and never open, commit, roll back or close it. (doc-only, not checked: follow it yourself)
  • api.v2.connectors-no-cross-calls: v2 connector modules never call one another to sequence a workflow; the service does the sequencing. (doc-only, not checked: follow it yourself)
  • api.v2.routes-no-sessions-or-sql: v2 route modules never open database sessions or construct SQL; they call one service method and map typed failures to HTTP. (doc-only, not checked: follow it yourself)
  • api.v2.services-no-sql: v2 services sequence work but never construct SQL expressions, call Session.exec, or define HTTP response models. (doc-only, not checked: follow it yourself)

Runtime persistence and route boundaries

  • Checked: api.data.runtime-sql-confined, api.legacy.removed-layers-stay-removed, api.routes.flask-blueprints-own-urls, api.routes.no-domain-logic-in-http, api.routes.no-inline-json-errors, api.services.no-direct-queries, api.services.session-ownership

Import and startup side effects

  • Checked: api.catalog.initializer-not-at-startup, api.startup.fail-closed-configuration, api.startup.no-import-side-effects, api.startup.no-runtime-sqlite-modules

Data source isolation

  • Checked: api.catalog.extractor-import-isolation, api.metadata.read-modules-isolated, api.reports.v1-persistence-only, api.stage12.comparison-tables-isolated, api.stage12.retirement-owned, api.v2.single-orm-layer

Migration and schema

  • Checked: api.migration.alembic-v1-qualified, api.migration.alembic-v2-qualified, api.migration.bundle-supported-by-simulation-api, api.migration.contracts-consistent, api.migration.cross-database-integration, api.v2.deployed-privileges-match, api.v2.runtime-privileges-declared, api.v2.runtime-privileges-tested-as-runtime-role
  • api.migration.alembic-autogenerated-only: Alembic revisions are autogenerated against an explicitly selected v1 or v2 configuration; never hand-written DDL or data operations. (doc-only, not checked: follow it yourself)

Code quality and types

  • Checked: api.quality.alembic-revisions-unused-imports, api.quality.ci-cd-scripts-ruff-exemptions, api.quality.command-line-modules-ruff-exemptions, api.quality.command-line-scripts-ruff-exemptions, api.quality.environment-variables-load, api.quality.mypy-v2, api.quality.ruff-format, api.quality.ruff-lint, api.quality.runtime-evaluated-models-resolve, api.quality.tests-pass, api.quality.tests-ruff-exemptions, api.quality.unittest-ruff-exemptions

Observability

  • api.observability.id-is-diagnostic-only: observability_id is used only to query diagnostic records, never for idempotency, cache ownership, authorization, database identity, routing or calculation behavior. (doc-only, not checked: follow it yourself)
  • api.observability.registered-stages-only: Span names come from the stage plans in policyengine_api.observability.stages; route and service code never adds span-name string literals. (doc-only, not checked: follow it yourself)

CI workflows and scripts

  • Checked: api.ci.multiline-run-is-script, api.ci.shell-scripts-pass-shellcheck, api.ci.workflow-scripts-tested

Process and repository hygiene

  • Checked: api.agents.adapters-point-to-agents-md, api.process.changelog-fragment, api.process.cloud-run-image-builds, api.process.docker-image-builds, api.process.rules-registry, api.process.stacked-prs-full-ci-at-bottom
  • api.process.agents-never-bypass: Agents never bypass branch rules, even with admin credentials: no gh pr merge --admin and no bypass option; a blocked merge is reported to a human. (doc-only, not checked: follow it yourself)
  • api.process.agents-suppress-as-last-resort: Agents add an inline ruff suppression (noqa) only when neither a code change nor a ruff setting removes the finding, and a PR lists every inline suppression it adds, with the reason. (doc-only, not checked: follow it yourself)
  • api.process.makefile-phony: Command-only Makefile targets are declared in .PHONY, and .PHONY stays in sync when targets are renamed or removed. (doc-only, not checked: follow it yourself)
  • api.process.pr-tracking-issue: Every PR has a tracking issue in this repository, and the first line of its description is Fixes #ISSUE_NUMBER. (doc-only, not checked: follow it yourself)
  • api.process.rule-machinery-code-owned: Changes to the rule machinery (rules/, scripts/rules/, scripts/guards/, scripts/run_quality_guards.py and CODEOWNERS) need approval from a core developer other than the author. (doc-only, not checked: follow it yourself)