AGENTS.md ยท diff
git:20261110.554e6ef to git:20261110.f89f036
9 added, 5 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: doops-development-contract
scope: repository
owner: doops-maintainers
---
# DoOps Development Contract
This file records repository-specific rules that are easy to miss during DoOps development.
General engineering rules belong in the caller's global `AGENTS.md`; keep this file focused on
DoOps architecture, security, release, and verification boundaries.
## Repository Map
| Component | Source | Notes |
|---|---|---|
| Gateway + Agent runtime | `backend/agent/internal/server/` | One shared package; see its `README.md` for the file-prefix index |
| Gateway entrypoint | `backend/gateway/main.go` | 11-line wrapper that calls `backend/agent/pkg/gatewaycmd` |
| Agent entrypoint | `backend/agent/cmd/agent/` | Imports `internal/server` and `internal/dispatcher` |
| CLI | `backend/cli/cli/doops/` | Separate Go module named `doops` |
| Agent-side skills | `backend/agent/skills/` | Copied into the Agent image; includes `dosql/` and `doweb/` |
| Operator Skill | `backend/skills/SKILL.md` + `backend/docs/*.md` | Installed into projects by `backend/scripts/install.sh` |
| Helm Charts | `backend/deploy/helm/` | Runtime assets only |
| Release scripts | `backend/scripts/` | Python contract tests live in `backend/test/` |
| Web console | `app/`, `components/`, `lib/` (Next.js) | Built from `Dockerfile.web` |
`bin/`, `backend/bin/`, `DoSuite/`, `DoSecurity/`, `.next/`, and `node_modules/` are ignored local
artifacts. Do not read, search, or execute them; they include stale binaries.
## Topic Ownership
Each topic has one authoritative document. Expand a rule only there; elsewhere, link to it.
| Topic | Authoritative document |
|---|---|
| Workload delivery (`ask --apply`, Helm assets) | `backend/docs/NATURAL_LANGUAGE_DEPLOYMENT.md` |
| Credentials | `backend/docs/CREDENTIAL_RESOURCES.md` |
| Harbor image replication | `backend/docs/HARBOR_REPLICATION_SPEC.md` |
| Agent and Gateway release | `backend/docs/BUILD_DEPLOY_SOP.md` |
| Gateway protocol and lifecycle | `backend/docs/DOOPS_GATEWAY_TUNNEL.md` |
| External API | `backend/docs/DOOPS_API_GUIDE.md` |
| Installation and onboarding | `backend/docs/CLUSTER_INSTALL_GUIDE.md` |
| Day-to-day commands | `backend/docs/DOOPS_USAGE_GUIDE.md` |
## Canonical Architecture
- Ordinary workload delivery uses an explicit natural-language task:
`doops -session <s> ask --target <t> --apply [--credential <name>...] --msg '<facts>'`.
- The task must state target, workload/service scope, reason, authorized Helm assets, and
machine-checkable acceptance criteria. Business image versions must come from the task or
read-only evidence from its task-specified repository, Chart, values, or existing release;
never guess them or require facts already in those assets to be pasted into the prompt.
Do not impose business-specific image keys, tag formats, CORS, repository, or directory gates.
- Ordinary `upgrade-install` uses `--reset-values` with explicit Chart defaults, ordered optional
values overlays, and non-sensitive Chart-specific string overrides, never implicit historical
values inheritance. Keep managed Helm authentication, target authority, staged package identity,
session path isolation, and dry-run/final Deployment verification intact. Full asset, optional
`expected_image`, and migration contracts belong in
[NATURAL_LANGUAGE_DEPLOYMENT.md](backend/docs/NATURAL_LANGUAGE_DEPLOYMENT.md).
- - CNB CI tests, builds, scans, and publishes immutable artifacts. Gateway authenticates users,
- authorizes targets and credentials, routes traffic, and audits. The selected target Agent
- performs the actual Kubernetes or Helm mutation and returns live evidence.
+ - CNB CI tests, builds, scans, and publishes immutable artifacts. GitHub Actions publishes the
+ public tag release assets (CLI and Gateway binaries) from tags on `main`, gated by the same CI
+ workflow and re-verified after publishing; CNB remains the production image and deployment path.
+ Gateway authenticates users, authorizes targets and credentials, routes traffic, and audits. The
+ selected target Agent performs the actual Kubernetes or Helm mutation and returns live evidence.
- For image/version inputs, the publisher must establish
the exact CI source-commit and registry-digest provenance before invoking the command. The CLI
and Agent validate the allowed input form and live result; they do not verify CI origin.
- Do not add or restore `EnvironmentRegistry`, `EnvironmentDefinition`, `DeploymentTemplate`,
`deploy/environments.yaml`, `doops cicd run`, prompt-derived deployment scope, `CICDReport`, or
`doops_cicd_result` as a deployment root or compatibility path.
- A DoOps Agent (one cluster/instance target) is the authorization unit: Gateway authorization
is (user, cluster, instance) only, and a grant opens every operation on that target and its
bound credentials. Openness is the default: do not add per-action or per-operation restrictions
and do not narrow what a target grant covers. Platform admin is a user flag. Gateway has no
per-action grants, execution quotas, operation admin, unlock, audit-optimize, scheduler, or repo
registry; do not reintroduce them.
- `deploy/helm/<name>/` contains runtime assets only. It must not become an environment registry,
credential store, target selector, or deployment authorization source.
- Agent upgrade has one hard constraint: an Agent cannot replace its own workload from its own
process, because the rollout kills that process. The replacement always runs in a separate
controller: an in-cluster Job started by `doops upgrade` (or, for a first upgrade the old Agent
cannot start itself, the same Job started through `doops exec`), or an external script.
Every path, whatever starts it, must:
1. back up what it changes (Helm revision, or the exported Deployment/ConfigMaps when the
workload is not yet Helm-managed);
2. verify the result: new Pod Ready on the pinned image digest, Gateway reconnect, and the
reported `release_commit`;
3. restore the backup automatically when verification fails;
4. run through the audited Gateway path, never with credential payloads in arguments or output.
Bringing an unmanaged Agent Deployment under Helm is allowed under the same four rules. The
procedure and per-runtime details (Helm, unmanaged Deployment, standalone Docker) live in
[BUILD_DEPLOY_SOP.md](backend/docs/BUILD_DEPLOY_SOP.md).
## Credential Security
- Public CLI arguments, natural-language prompts, doagent context, Git, issues, logs, audit output,
and remote workspaces must never contain credential payloads.
- CLI payload input is stdin-only. Gateway encrypts payloads at rest and must fail closed when its
configured master key or credential audit persistence is unavailable.
- `credential configure` orchestrates the existing lifecycle; do not create a second store or
bypass grant/verify/promote. Platform-admin Secret import accepts exact references only and
transfers selected values from Agent to Gateway on the private control channel, never via exec.
- Gateway may send decrypted payload only through the internal credential materialization call to
the granted target Agent. Public prompt and metadata bindings contain names,
scopes, Secret names/types/key sets, resource versions, digests, status, and stable error
categories only.
- Runtime credential use requires only the user's grant on that target. Do not
add a credential action or a per-operator credential grant. Active grants identify
which target/use owns a credential; management still belongs to its owner or platform admin.
Database bindings resolve directly from stored target metadata, without a model-generated scope;
the saved namespace is used for materialization. DoSql/Agent owns database assets and SQL policy.
Namespace, workload, release, image and repository paths are execution metadata, not credential
permission dimensions. Resolve explicit names directly from stored target bindings, without a
model scope-planning request. Credential management uses owner/admin; personal credential APIs
do not require separate credential actions. Target Secret import requires a grant on that target.
Keep HTTPS origin protection, package validation and immutable staging for Helm. Do not add
wildcard, prefix, inferred, project, environment, template, or workflow-path grants to the
Gateway layer.
- A project may declare metadata-only development requirements in
`.agent/doops-credentials.yaml`. Before Git, registry, Helm, TLS, or API development work that
depends on managed credentials, run
`doops -session <s> credential preflight --manifest .agent/doops-credentials.yaml`.
The manifest is only a fail-closed checklist of `credentialRef` plus `use`; it must never contain
payloads, grant authority, materialization instructions, local secret paths, or fallback values.
Credential references must be lowercase resource names, not URLs, paths, tokens, or arbitrary
scalars. It only checks that the named credential is active and bound to the selected target.
- The lifecycle is `create -> put staged version -> grant -> verify every active grant -> promote`.
Rotation repeats put/verify/promote. Grant or resource revocation must clean materializations
before reaching the terminal revoked state.
- Promotion must require at least one current active grant and a successful verification for every
current active grant. Historical or revoked grants and their verifications must not satisfy or
block promotion.
- User-facing output and tests must use synthetic canaries and assert that payload values are never
returned. Never request or store a real credential in fixtures, documentation, issues, or commits.
## CLI And Skill Distribution
- The only supported installed CLI path is `~/.local/bin/doops`.
- Build-tree binaries such as `backend/cli/bin/*` and binaries embedded inside a Skill
directory are development artifacts, not supported user entrypoints.
- - Users install a checksummed, versioned CNB Release Asset through
- `backend/scripts/install.sh --version <tag> --project <absolute-project-path>`.
+ - Users install a checksummed, versioned release asset through
+ `backend/scripts/install.sh --version <tag> --project <absolute-project-path>`. CNB Release
+ Assets stay the default source; `DOOPS_RELEASE_ASSET_BASE` points the same sha256, identity and
+ contract checks at the GitHub Release mirror.
- Before replacement, the installer must validate an existing config with the downloaded release
CLI's own Go parser. Do not maintain a second Python, Node, jq, or shell JSON schema.
- The canonical Skill source is `backend/skills/SKILL.md`. The installer copies it and
`backend/docs/*.md` from the exact commit embedded in the downloaded CLI into
the project and global `.agent/skills/doops/` plus existing Codex/Agents copies, never from the
current working tree. Missing release source must fail before replacement; the install receipt
records `skill_commit` and every `skill_path`. Preserve runtime config/auth when replacing
Skill/docs. Installation scope is documented in `backend/docs/CLUSTER_INSTALL_GUIDE.md`.
Do not edit installed copies first.
- One `doops login` is shared by configured targets on the same normalized Gateway URL. Target
credential listing and use inherit target operation authority; management enforces ownership.
## Required Documentation
A behavior change updates, in the same change, the one authoritative document that owns its topic
(see Topic Ownership), plus CLI `--help` text and README when user-visible commands change.
`backend/skills/SKILL.md` keeps only red lines, command selection, and links; update it only when a
red line or a command entry changes. Other documents link to the owner instead of restating it.
Do not document intended behavior that the current CLI and Gateway do not implement.
## Verification And Delivery
Pick the highest tier the change touches:
| Tier | Applies to | Done when |
|---|---|---|
| T0 | Docs, tests, or refactors with no behavior change | Relevant local tests pass, `git diff --check` is clean, the branch is pushed, and required CI passes |
| T1 | CLI, Agent, Gateway, or Web behavior | T0, plus the checks below for the touched components, published release assets, `backend/scripts/install.sh` installing the released CLI and Skill, and touched components deployed from the matching immutable CI artifact |
| T2 | Credentials, CI/CD, permissions, payload boundaries, release contracts | T1, plus the full Given/When/Then matrix and the online synthetic credential lifecycle below |
Skill and docs changes reach user projects with the next release; a T0 change does not need its own
release.
- Credential and CI/CD changes require Given/When/Then coverage for success, denied authority,
unavailable/wrong target, unavailable audit/key, verification failure, revocation, and payload
redaction. Do not weaken expected HTTP status or output assertions to make tests pass.
- Development credential preflight changes additionally require strict manifest parsing, missing
reference, wrong use, revoked grant, target mismatch, required session, and payload-field
rejection coverage.
- Run Agent and CLI package tests, Python contract tests, `git diff --check`, stale-contract scans,
and a compiled CLI help/argument smoke test.
- Web changes require production build plus browser testing of login, target/managed credential
views, loading/empty/error/forbidden states, payload submission, navigation, console, and network
failures. Use synthetic credentials only.
- T2 delivery is incomplete until an online synthetic credential lifecycle verifies create, list
isolation, persistence, verify, promote, and revoke against the deployed Gateway.
- Do not use fallback, silent downgrade, manual hotfix, or an old CLI to bypass a failing contract.
Fix the root cause and rerun the failed evidence path.