truf-server/AGENTS.md

Engineering Decisions

Provider Source Execution

• Keep source adapters minimal. The server validates assignment shape, canonical target identity, and the immutable identity required by the protocol.
• Git planning may bind an exact commit. Docker planning may resolve a mutable tag to an immutable digest. These are identity operations, not provider-access proofs.
• The worker is the final authority for real provider access. It reports success, a permanent target failure, or a retryable provider failure; the server settles or retries from that result.
• Discovery credentials are not assignment fields unless a separately approved capability explicitly defines credential delivery.
• Do not add per-target server preflight requests, durable public-access proofs, proof TTL/freshness columns, access-evidence migrations, broad child-environment credential scrubbing, credential sandboxes, or post-hoc redaction pipelines by default.
• Before adding any such defensive or security-specific mechanism, stop and obtain explicit user approval. Record the approved behavior in an OpenSpec requirement and task before implementation.
• Do not treat existing defensive code as precedent for duplicating the same machinery for another source.
• The worker machine's ambient environment belongs to its operator. Assignment code must not silently rewrite HOME, XDG, Git, Docker, or provider environments merely to enforce a nominally tokenless assignment.
• Prefer direct, bounded provider-error classification over preventive infrastructure: authentication/access/not-found failures are permanent when target-scoped; rate limits, network failures, and provider 5xx responses are retryable.

These rules apply to future source adapters and to changes in worker_assignment.py, scan_execution.py, remote_worker_client.py, scanner.py, scanner_db.py, and discovery producers.