horizun-pbi-mcp: Instructions file for Codex

Repository rules for agents

Operating instructions for any agent (or person) modifying Horizun PBI MCP. They take priority over any general convention.

---

1. Before touching anything

python -m pytest -q                    # must pass green
python scripts/doctor.py               # must exit with code 0

If the baseline is already broken, fix it or report it first. Don't build on red.

---

2. The MCP contract is untouchable

The 34 baseline tools are frozen in tests/golden/tools_v1.json.

Forbidden without explicit approval:

• removing a tool
• renaming a tool
• removing a parameter
• adding a required parameter
• changing a parameter's type
• changing a default value
• changing the response shape

Allowed:

• adding new tools
• adding optional parameters with a default
• adding new fields to the response dict
• improving descriptions

Adding a tool also means classifying it in src/tools/risk.py. The suite fails if you don't: an unclassified tool is announced to the client as destructive — which is the safe default, but the table has to say so out loud. Never declare as read_only anything that calls guard_mutation or writes a file; tests/test_tool_annotations.py checks that against the code, not against the docs.

Check at any time:

python -m tests.contract_utils

Returns 0 if there are no breaks, 1 if there are, with a report stating what changed and whether it breaks compatibility — not a dump of two JSONs.

After a deliberate, approved change:

python -m tests.contract_utils --write

---

3. Invariants no phase can break

1. stdout is the JSON-RPC channel. All logging goes to stderr or a file. A debug print() breaks the client connection.
2. Never overwrite JSON that doesn't parse. If it can't be read, abort.
3. Every write to the user's project: backup before, re-read after.
4. No write path leaves the active project. Use ensure_within_base().
5. No fields are invented that don't exist in the model. If a field doesn't exist, report it; don't guess.
6. Destructive tools require confirm=true.
7. Prefer cloning a real template over hand-building visual JSON.