ssm: Instructions file for Codex

SSM — Agent Working Instructions

This document exists to make AI coding agents (and humans) effective and safe when modifying the codebase. It prioritizes actionable rules, invariants, and verification steps over descriptive snapshots of the current state.

The Prime Directive

NEVER commit changes unless explicitly instructed.

Prepare the staging area (git add), show the plan and the full diff, and wait for the user to explicitly say "commit" or "go ahead". This rule overrides all other instructions. Do not ask the user whether they want to commit.

1. Verification — Run These Before Claiming Work Is Complete

An agent must produce clean results from the project's canonical checks before presenting changes as done.

Primary command (use this most often):

make check

make check runs (see Makefile):

• gofmt
• lint (golangci-lint if present, else go fmt + go vet)
• go-mod-tidy-check
• make test (go test -race -count=1 ./...)
• make build

Individual commands you will use constantly:

go build ./...
go vet ./...
go test -race -count=1 ./...
golangci-lint run ./...
govulncheck ./...
make build-static

When touching performance-sensitive code, also consider make bench (and the -cpu / -mem variants).

Rule: If you have not run the relevant verification commands and shown the output, you are not finished.

2. Non-Negotiable Rules

• Changelog discipline: Any commit that changes code, fixes bugs, adds features, or adjusts tests must also update CHANGELOG.md with a concise entry under the appropriate keepachangelog.com section (Security, Fix, Add, Refactor, Test, Docs, etc.).
• Injection prevention: The -- delimiter must appear before every hostname in all SSH, mosh, and syscall.Exec invocations. This is non-negotiable.
• SFTP connection flags: SFTP and certain remote operations deliberately use BatchMode=yes, RequestTTY=no, and StrictHostKeyChecking=no. These are intentional (users are connecting to their own servers). See SECURITY.md.
• Sensitive data handling: IdentityFile, ProxyCommand, CertificateFile, and similar keys must remain filtered from any configuration display/viewport.
• Parser thread-safety contract: See Architecture Contracts below. Do not regress the brief-publish-lock model.