10 added, 57 removed. Audit B to A.
- # MASC-MCP Agent Instructions
-
- Shared agent entrypoint for this repo.
- Keep this file short. If guidance conflicts, prefer the linked runbooks and specs.
-
- ## Read First
-
- - `docs/COMMON-PITFALLS.md` — refactor/deletion traps and dashboard gotchas
- - `README.md` — public overview and dashboard entrypoints
- - `docs/QUICK-START.md` — install, run, health check
- - `docs/MCP-SURFACE-AUDIT.md` — current public MCP surface
- - `docs/spec/SPEC-INDEX.md` — spec suite front door
- - `docs/COMMAND-PLANE-RUNBOOK.md` — CPv2 direct control path
- - `docs/BENCHMARK-RUNBOOK.md` — benchmark and swarm recipes
- - `docs/SUPERVISOR-MODE.md` — supervisor/operator path
-
- ## Common Commands
-
- ```bash
- dune build --root .
- dune runtest --root .
- make test
-
- ./start-masc-mcp.sh --http
- PORT="$(./start-masc-mcp.sh --print-port)"
- curl "http://127.0.0.1:${PORT}/health"
-
- cd dashboard && MASC_DASHBOARD_PROXY_TARGET="http://127.0.0.1:${PORT}" npm run dev
- cd dashboard && npm run build
- ```
-
- - Repo root checkout default port: `8935`
- - Git worktrees use a derived port; query it with `./start-masc-mcp.sh --print-port`
- - Prefer script-based local start flows; do not treat `launchd` as the default path
-
- ## Working Rules
-
- - Run `dune build --root .` after `.ml` changes
- - Run `cd dashboard && npm run build` after dashboard changes
- - Use newtype modules for IDs; do not pass raw strings across typed boundaries
- - Protect shared mutable state with `Eio.Mutex`
- - Use established Eio cleanup/resource patterns already present in the touched module
- - Use GraphQL access paths; do not add direct Neo4j calls
- - Keep provider/model selection in cascade config or env, not hardcoded in feature code
- - Treat `README.md`, `docs/QUICK-START.md`, and the runbooks as front-door usage SSOTs, not this file
+ # MASC Agent Instructions
- ## Ask First
+ ## Required Contract
- - `room.ml` state machine changes
- - `keeper_keepalive.ml` tick logic changes
- - new public MCP tool registrations
- - `config/cascade.json` ordering changes
- - board post ID generation changes
+ - Before planning or changing MASC, read `docs/constitution.xml` in full.
+ - For MASC coding-agent work, its `<execution_protocol>` is the repository-specific workflow authority. It overrides parent or general contributor guidance, including `CONTRIBUTING.md`, only where those sources would require local Dune builds, CI watch/wait loops, or a different default for parallel review agents.
+ - System, developer, and explicit user instructions still take precedence. The execution protocol does not relax safety, scope, destructive-action, or evidence-honesty rules.
+ - Keep this file as a thin entrypoint. Do not duplicate the full constitution here.
- ## Never Do
+ ## Keeper Runtime Boundary
- - use `Obj.magic`
- - add blocking I/O inside Eio fibers
- - commit secrets or tokens
- - force-push `main`
- - remove mutex protection around shared runtime state
+ - `docs/constitution.xml` is a product and development contract, not a Keeper runtime system prompt.
+ - The shared Keeper runtime prompt is `config/prompts/keeper.md`. Per-Keeper behavior also comes from the resolved `<base-path>/.masc/config/keepers/<name>.toml` `keeper.instructions`.
+ - Edit the contract and runtime prompts independently; changing one does not implicitly change the other.