AGENTS.md

This repository uses persistent-agent-roles. At start, resume, handoff, or a new assignment, load the skill to verify your current Relay name and mapped guidance. If missing, install it globally from Collection.

Treat roadmap/ as the canonical repo-local roadmap workspace for humans and agents. Use docs/context/ for broader design context, but keep roadmap state and queue changes in the minimap files. For roadmap state or assigned Minimap roadmap work (pickup, resume, investigation, testing, substantive review, or completion), use the existing Minimap roadmap skill; do not create or install a duplicate.

If AGENTS.local.md exists at the repository root, read it as supplemental machine-local instructions; it is intentionally not versioned.

Repo-level non-negotiables:

• use README.md, docs/context/*, relevant docs/designs/*, and roadmap/* as the source of truth
• changes limited to the documentation-only allowlist in agent-workflow.yaml are eligible for exemption, but need no Work Record or pull request only when the workflow's whole-change applicability decision passes; direct commit and push to main additionally require that decision's fresh protection check to confirm eligibility. Any failed or indeterminate decision, or any other changed path, uses the normal isolated branch and pull-request workflow
• Windows service operations: always restart the installed service with scripts/restart-service.ps1. Do not invoke pallium service restart, Task Scheduler, or the launcher directly; the wrapper removes the full stale process tree. Then verify /health, /status, and /debug/queue/health on port 19836. See docs/context/operations.md for health-signal meaning and the silent embedding-provider degrade (check embedding_provider_ok when search returns too little).
• Local integration development: Claude Code and Codex setup commands embed absolute checkout paths, and OpenCode's loader points to a concrete plugin file. Before moving, deleting, or replacing an installed worktree, follow Developing integrations without leaving stale local installs, including old-checkout uninstall, stable-checkout reinstall, host restart, and installed-state verification.
• honor the two invariants at the top of docs/context/lessons.md on every retrieval / ranking / eval PR: (1) retrieval alone never updates accessibility state — verified downstream use only; (2) every eval number states whether it measures candidate-recovery, injection-precision, or downstream-task-effect
• every feature ships with end-to-end coverage of all edge cases. A feature is not done when the happy path works; it's done when every boundary (empty / max / over-max), every error path (missing entity, invalid enum, state conflict, permission), every state interaction (idempotence, cross-state combinations, chain length > 2), every locale (unicode, non-ASCII), and every full-lifecycle journey (create → mutate → dispose) has an E2E test asserting the observable contract. Unit + integration tests alone don't discharge this — an E2E test drives through the same surface the caller uses (HTTP, MCP, hook) and asserts state through the same read path (list endpoint, retrieval, audit). See tests/test_w3_memory_writes_e2e.py for the reference shape.
• keep the development test loop focused: while editing, run the exact test node or file with python -m pytest <node-or-file> -q -n 0; after a coherent change, run the affected subsystem files; rerun known failures with python -m pytest --lf --lfnf=none -q -n 0. Before review or PR, use python scripts/test-plan.py --base origin/main to select validation from the whole change, including dirty and untracked files, and run the reported checks. Documentation and supported governance-only changes do not require application tests; application, mixed, unknown, selector, CI, or shared-configuration changes require the full non-slow suite once. Keep workflow compliance checks and changed-feature E2E coverage. Add -m slow when the focused target is slow-marked. See docs/testing-conventions.md for lane boundaries and evidence reuse.
• protected behavior contracts: tests/behavior_contracts/** encodes accepted caller-visible requirements. Investigate a failure; do not skip, delete, or weaken a test merely to restore green. Classify every edit to that path through Agent Workflow and verify it in the existing PR test job. A genuine requirement change needs approval from the user as task owner for its exact before/after behavior; agent or plan review cannot substitute. Workflow-only evidence is not authenticated repository authority and does not prevent a GitHub merge. See tests/behavior_contracts/README.md.
• optimize for the smallest valuable slice that strengthens the current product claim
• protect the generic core, reusable capability, and package-specific semantic boundaries
• call out roadmap, docs, and code drift explicitly before endorsing a change
• treat concrete downstream incidents as bug sources, but generalize fixes into reusable Pallium capabilities before proposing roadmap or implementation work
• avoid proposing or implementing scenario-specific features keyed to product names, tool names, ticket ids, or one-off phrasing unless the work is explicitly integration-scoped
• keep new tests, fixtures, replay assets, and benchmark cases anonymized and domain-generic by default
• translate scenario-specific reproductions into generalized retrieval, routing, packaging, lifecycle, compatibility, or benchmark failure classes before defining the work
• delegated work is not complete until it has been reviewed, findings have been addressed, and roadmap/docs have been aligned when the feature status changed
• if apply_patch fails because of sandbox or environment limitations on this machine, delegated workers may use the smallest deterministic local file-write fallback and must report that fallback explicitly

Testing and eval conventions: see docs/testing-conventions.md.

agent-workflow

This repository uses agent-workflow with agent-redline risk classification.

Start: invoke /agent-workflow or the runtime's native command. If unavailable, read .claude/skills/agent-workflow/SKILL.md or .agents/skills/agent-workflow/SKILL.md.

Plan mode: for every non-exempt task, the plan's first implementation step must be "Invoke the /agent-workflow skill to create the Work Record and classify risk, before any code edit." Do that first on approval. The hook checks plans that touch configured hooks.guardedPaths (default src/) as supplemental enforcement; it is a nudge, not the applicability decision or CI gate.

Local check before pushing: POSIX: bash scripts/agent-workflow-runtime.sh codex check --repo-root . --slug <slug>. PowerShell: & scripts/agent-workflow-runtime.ps1 codex check --repo-root . --slug <slug>.

The adapter tries PYTHON, .venv, then platform fallbacks. Missing prerequisites block with guidance. Exit codes: 0 clean, 1 advisory, 2 blocking. CI posts it.

Native mutation coverage is version/surface/tool-specific: verified requires a denied operation with unchanged target; installation, trust, or a direct evaluator pass is insufficient. Record every other combination as degraded. Shell mutations bypass the guard; CI validates final artifacts/applicability, not pre-edit ordering or direct pushes. Evaluator failure returns deny; native prevention requires that evidence.

Known import-graph smells (not enforced as layer contracts)

These are real cross-layer couplings the code lives with today. One is tripwired in pyproject.toml via ignore_imports — adding a second offender fails CI. The rest are gated by red-zone classification on the relevant files. Captured here so the analysis isn't re-derived later:

• storage.sqlite_workstream → capabilities.workstreams — storage owning a capability-shaped store. Tripwired (one baselined import).
• core ↔ semantic peer tangle — core/{service,routing,query,processing,consolidation_runner}.py import from semantic; semantic imports core.models and core.contracts. Not enforceable as a layers contract; gated via red-zone on the relevant core/* files.
• core → capabilities — core/consolidation_runner.py and core/service.py import capabilities.*. Deliberate orchestration coupling, not an accident; gated via red-zone on those core/* files.

Agent Relay: hook delivery vs MCP receive

Relay deliveries reach an agent through two paths. Never mix them in the same session.

Hook delivery (normal path): The integration injects pending deliveries into the agent's context at turn start via the user_prompt_submit hook. The hook owns claim, emission, and ACK. The agent does not call any MCP tool for this — the delivery is already in its context. Calling pallium_relay_receive in the same session as a hook delivery creates a race and risks double-claim.

MCP receive (recovery / non-hook integrations): When the integration has no hook, or when a delivery was missed (e.g. crash-after-claim → lease expired → redelivery), the agent calls pallium_relay_receive to claim and retrieve pending deliveries. After processing each delivery, call pallium_relay_ack(delivery_id, receipt) to confirm. If replying, call pallium_relay_reply instead — it ACKs atomically; no separate ACK is needed.

Never use curl or HTTP directly for relay ACK. The /relay/deliveries/ack endpoint requires a claim_token that is never exposed to the model. Use pallium_relay_ack (receipt-based, no claim token) or pallium_relay_reply (atomic ACK + reply).

MCP identity (for relay receive to work): pallium_relay_receive accepts no model-supplied runtime or session identity. PALLIUM_AGENT_REF is static in the integration's MCP configuration. Session identity resolves from PALLIUM_THREAD_REF when a launcher supplies it, otherwise from the owning runtime: inherited CODEX_THREAD_ID / CODEX_SESSION_ID for Codex, or the parent Claude process's local session-registry entry for Claude Code. Resolution fails closed when no supported runtime-owned session identity is available.