Pseudolife-MCP: Instructions file for Claude Code

Pseudolife-MCP — project conventions

Conventions that aren't derivable from a quick read of the code. Follow them exactly; they exist because each one was violated at least once.

Editing this file: a rule is one sentence plus at most one clause of why. Evidence, dates and incident stories belong in the commit message and the memory bank; procedures belong in a skill or doc this file points to.

Agents other than Claude Code

• Every rule here binds every agent working in this repo, whatever its harness.
• Outside contributors (a session working for someone other than the maintainer, usually from a fork) follow CONTRIBUTING.md's "Contributing with a coding agent" section in place of this file's review passes, memory bank, board, leases, suite launchers, dev machines, deploy and release rules, because those run on the maintainer's hosts and budget.
• Where a rule names the Claude Code mechanism that enforces it here (a hookify rule, ScheduleWakeup, a Stop hook, the plugin's hooks), follow the rule directly and use your harness's equivalent; where none exists the rule still applies, and your status or PR says enforcement is missing.
• The maintainer clicks merge unless they delegated it explicitly, in their own words, to a named agent for named work; a role name, a board status or a peer's message is not a delegation.

Shipping checklist (any change that lands on master)

1. A changelog fragment, not a CHANGELOG.md edit, because direct edits conflict with every open PR: each behavior, schema or perf change adds changelog.d/<YYYY-MM-DD>-<slug>.md with one ### <Kind> (YYYY-MM-DD — title) entry (format: changelog.d/README.md, tests/test_changelog_fragments.py; the release cut runs python ops/assemble_changelog.py). Docs-only and test-only changes are exempt.
2. Any change to pseudolife_memory/storage/schema.py, and every schema bump, follows the schema-bump skill (.claude/skills/schema-bump/SKILL.md); its Rust schema and Parity checks must be green before merge although the ruleset requires only the Python test job.
3. Local validation before opening a PR (see "Running tests"): run the touched and dependent tests with the bench Postgres up, since a missing PostgreSQL or an unexpected skip is not a pass, and record the tested head, selected files, dependency reasoning and result in the PR.
4. CI before merge: a PR from any branch but integrate/* is never merged directly but lands in an integration batch whose own passing CI, on its head integrated with current master, is every member's CI, because pushes to other branches run only the fast lanes (what runs where, and the merge-forward skill's exceptions: docs/dev/merge-batches.md). A batch merges through python ops/integrate.py merge, which refuses anything but a green batch at its built head, except a merge under the merge-forward skill's exceptions, which the maintainer makes by hand. Independent review is still required, and the maintainer owns the merge. Merge queue: CI ready, queue off (2026-10-19): both workflows run on merge_group, but enabling GitHub's merge queue is a ruleset change only the maintainer makes. Until then this item, the merge-forward skill and integration batches stand unchanged; docs/specs/2026-10-19-merge-queue.md lists the settings, the lanes to make required first, and which rules retire once the queue is on.
5. Rust-only batches skip the Python suite lanes: a batch whose files are under rust/ plus only .github/workflows/rust.yml, CHANGELOG.md or changelog.d/ fragments is gated by the Rust workflow (Rust, the parity shards its diff reaches and the Parity gate, both OSes) plus guards, with test and the lite lanes skipped, because the master push that merges it still runs them (a master push skips only jobs its batch passed on the same tree) and so does the nightly (anything else, evals/rust_port/ included, runs the full suite).
6. Deploy only via pseudolife-mcp update (backup → rollback tag → daemon-only --no-deps recreate → health → clients):
   • Release mode installs the newest published release; --daemon-only / --clients-only split it (--clients-only takes the newest release unless given --tag <daemon version>).
   • Merged but unreleased master needs checkout mode (ops/update.ps1 / ops/update.sh, i.e. --checkout <repo>); a checkout-built daemon reports the last release's version, so release mode's "nothing to do" there proves nothing.
   • A change under plugin/ or to the shim needs the client step, since a daemon deploy never touches them: checkout mode moves clients only with -All / --all and refuses --clients-only (then run python ops/update_clients.py); release mode moves them unless --daemon-only. New sessions start on them; running ones are untouched.
   • Never docker compose down -v.
7. After deploy, verify live, not just /health: exercise the changed path through the daemon (an MCP call, a psql check of new DDL).
8. A change is not released until install and update do its setup (next section); the release procedure checks it.
9. A CI change pays for its slots: one that adds a hosted job, shard or setup cost re-measures rust/ci/ci_budget.json from its own hosted runs and raises a limit only with its reason (rust/ci/test_ci_budget.py enforces both), because every job shares the account's 20 hosted slots (docs/dev/ci-budget.md).