Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (88 loc) · 5.58 KB

AGENTS.md

File metadata and controls

103 lines (88 loc) · 5.58 KB
Raw

Engineering agent contract

This repository publishes public LCP documentation. Treat .lit/repository.yml, RELEASE.md, TESTING.md, SECURITY.md, and the accepted Lightning IT Engineering ADRs as the governing repository contract.

  • Work through a pull request into develop; promote reviewed develop to main.
  • Validate Markdown, internal links, navigation, and repository structure.
  • Do not publish credentials, internal-only endpoints, personal data, or customer information.
  • Keep external GitHub Actions pinned to full commit SHAs and permissions least-privilege.
  • Preserve managed-file headers and change shared policy at lightning-it/shared-assets-lit.
  • Run python3 scripts/lit-push-ready.py push-ready before pushing.
  • Required remote checks and branch protection must not be bypassed.
  • ADR 70 temporarily allows zero human/CODEOWNER approvals and separately documented protected-environment self-approval for immutable exact-SHA plan/apply evidence; it does not allow PR self-review or check bypass.

REP-60 current-revision review governance

  • Local validation is deterministic only. It must never invoke Codex, GitHub Copilot, another model, or an external AI endpoint. Authoritative AI review runs only in the protected GitHub pipeline and binds the exact PR head.
  • Lightning IT automation may request and fund one GitHub Copilot review only when the exact PR author is litroc, and only at the finalization boundary; intermediate synchronize pushes must not trigger AI review. Any finding requires correction and a final current-head re-review. The request is consumed once per head; unavailable or quota-blocked reviews fail closed without an automatic retry. Organization-funded Codex remediation and its single re-review are likewise restricted to litroc.
  • Every other human or external contributor supplies any required current-head Copilot review under their own entitlement and cost. Lightning IT verifies valid evidence but never requests or funds that review, and personal tokens or provider keys never enter Actions.
  • A same-repository PR authored exactly by lightning-it-release-automation[bot] uses only the protected MLX-90 §7.2 Exact-Revision Codex check. It must never request Copilot or synthesize a Copilot success.
  • A proven ancestry-only main-to-develop backmerge uses the deterministic evidence-bound exemption and performs zero AI calls. Unknown automation identities fail closed.
  • The only neutral merge-gate result is Current revision review. Missing, stale, ambiguous, or unresolved review evidence blocks the merge.

Devtools container execution boundary

  • Every deterministic lint, format, type-check, test, build, packaging, policy, and validation workload runs in the digest-pinned Lightning IT Devtools image, locally and in CI. Host-language runtimes never provide acceptance evidence.
  • The host boundary is limited to Git, the supported container engine, and the centrally managed Devtools, push-ready, and pre-commit dispatchers. A dispatcher may inspect Git state and start the pinned container, but it must not execute a repository validator through host Python, Node.js, Ansible, Ruff, a Python type checker, markdownlint, Renovate, or a comparable host runtime.
  • If a required command or compatible version is absent, fail closed. Add and pin it in container-ee-wunder-devtools-ubi9, release that image normally, update the centrally managed digest, and rerun the gate. Host fallbacks, ad-hoc virtual environments, and unpinned helper images are forbidden.
  • Defaults stay read-only, offline, socket-free, capability-dropped, and non-privileged. A gate may opt into only its explicit tested minimum. Linked Git metadata remains read-only and container Git may trust only /workspace, never *. Executable temporary fixtures use the isolated container home while generic /tmp remains non-executable.
  • The Devtools boundary never makes local Codex, Copilot, or other model calls and never receives personal AI credentials.

AI model and token governance

Apply LIT-GEN-GDR-GOV-30-Budget-Conscious-AI-Model-Selection to every substantive Codex or ChatGPT-assisted task. Before investigation, planning, tool use, implementation, or delegation, record a compact task profile in the task chat: work item, risk (low, normal, or high), smallest sufficient model/reasoning choice, rationale, and a concrete escalation condition.

  • Use the balanced, lowest reliable capability by default. Escalate to a premium/frontier model or higher reasoning only for a high-risk decision, complex architecture/debugging/dependencies, or a documented focused failure of the standard approach. Restrict that escalation to the difficult subtask.
  • Never use Speed Mode. Do not replace verification with a more expensive model or sacrifice quality to reduce elapsed time.
  • Retrieve only relevant issue, files, logs, and source records; avoid broad repository or chat-history loading, speculative analysis, and unbounded retry loops. Delegate only independent, bounded work that reduces total effort.
  • For GitHub or Jira work, include the task profile in the issue/task record when AI assistance materially affects execution. Close with verification and remaining risks; preserve durable decisions in Confluence, Jira, or GitHub.