pmacs/AGENTS.md

pmacs agent instructions

Start here: read docs/agent-handoff.md, then docs/active-work.md, before taking on any work. The handoff carries durable project state, working method, substrate invariants, and the standing backlog. The active-work ledger carries volatile branches, checkpoints, verification, and exact cross-machine recovery commands. Keep both updated according to their own update protocols.

Always true, independent of the handoff:

• Rust core + Lua runtime (builtin/runtime/*.lua), TUI + GPU (pmacs-gpu) frontends over a versioned semantic protocol (pmacs-protocol). #![forbid(unsafe_code)].
• Workflow: framing doc in docs/ -> user approval -> branch -> implement -> full gate suite -> PR -> user review rounds -> user says when to merge. Never merge unprompted. One feature, one branch, one PR.
• Gates before any PR: cargo fmt --check; cargo clippy --workspace --all-targets -- -D warnings (as its own step); cargo test --lib; cargo test --lib --features crdt; the touched acceptance suites; cargo test --test m4_acceptance -- --skip basedpyright; PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu; git diff --check.
• The checkout may be shared with the user: check git status for foreign uncommitted work before stash, checkout, or branch operations, and never delete untracked files you did not create.
• The canonical development URL is https://github.com/levineuwirth/pmacs.git; recovery docs normalize it to the local alias githubsucks. Remote names such as origin are machine-local and carry no authority by themselves. Bootstrap/verify the alias via docs/active-work.md before basing new work.
• Work is portable only after it is committed and pushed. Uncommitted worktree changes, untracked files, and /tmp dependencies do not travel to another machine.
• Write commit messages with git commit -F <file>. Never use git add ..