Add mutation boundary prompt guardrails

.claude/agents/actor.md

@@ -6,6 +6,15 @@ version: 3.1.0
 last_updated: 2025-11-27
 ---
 
+## Mutation Boundary Constraints
+
+Every write must stay inside the current subtask contract.
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the current contract explicitly names that dependency change.
+- Do not refactor neighboring code unless the validation criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, stop and report it as a blocker/tradeoff instead of doing it silently.
+
 # QUICK REFERENCE (Read First)
 
 ```

.claude/skills/map-debug/SKILL.md

@@ -41,6 +41,15 @@ parallel_tool_policy: sequential_root_cause_first
 - Do not add extra agents beyond the documented debugging sequence; switch workflows only if the task stops being a debugging task.
 - Do not continue polishing after the original symptom is reproduced, fixed, and verified.
 
+## Mutation Boundary Constraints
+
+These constraints apply to every fix subtask:
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the root cause evidence explicitly requires that dependency change.
+- Do not refactor neighboring code unless the bug cannot be fixed and verified without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff instead of doing it silently.
+
 ## Workflow Overview
 
 Debugging workflow focuses on analysis before implementation:
@@ -144,6 +153,7 @@ Task(
 **Root Cause:** [identified root cause]
 
 Apply the fix directly with Edit/Write tools.
+Do not edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the root cause evidence explicitly requires it. Report any required scope expansion as a blocker/tradeoff.
 
 JSON contract reference: [Actor Change Summary](../../references/map-json-output-contracts.md#actor-change-summary).
 

.claude/skills/map-efficient/SKILL.md

@@ -36,6 +36,15 @@ parallel_tool_policy: guarded_wave_only
 5. After Monitor pass, record files changed in `step_state.json` for guard isolation.
 6. Validate planning metadata before Actor starts: `expected_diff_size`, `concern_type`, `one_logical_step`, `split_rationale`, `concern_justification`, `coverage_map`, `hard_constraints`, `soft_constraints`, `validation_criteria`, `[AC-1]` bracket tags, and `tradeoff_rationale`.
 
+## Mutation Boundary Constraints
+
+These constraints apply to every write-capable Actor or fix phase:
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the current subtask contract explicitly names that dependency change.
+- Do not refactor neighboring code unless the current validation criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff and wait for the contract to change instead of doing it silently.
+
 ## Intentional Agent Omissions
 
 /map-efficient does not run Evaluator or Reflector during normal execution. Monitor validates correctness directly, and learning is deferred to `/map-learn`.
@@ -187,6 +196,7 @@ Task(
 </documents>
 <task>
 Implement exactly the current subtask. Preserve validation_criteria, coverage_map tags, hard_constraints, and soft_constraints tradeoffs. Do not expand scope.
+Do not edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask contract explicitly requires it. Report any required scope expansion as a blocker/tradeoff.
 </task>
 <expected_output>
 Return files_changed, tests_run, validation_notes, and any blocker.

.claude/skills/map-fast/SKILL.md

@@ -33,8 +33,18 @@ parallel_tool_policy: sequential_by_default
 
 - Do not add discovery, design review, impact analysis, or learning steps to keep this workflow busy.
 - Do not refactor nearby code unless the selected small task cannot work without that exact change.
+- Do not edit unrelated files or add, remove, or upgrade dependencies unless the task explicitly requires that exact change.
 - If the task becomes risky, multi-stage, or ambiguous, stop using `/map-fast` and switch to `/map-efficient` or `/map-plan` instead.
 
+## Mutation Boundary Constraints
+
+These constraints apply to the Actor implementation prompt:
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the current task explicitly names that dependency change.
+- Do not refactor neighboring code unless the acceptance criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff instead of doing it silently.
+
 ## Workflow Overview
 
 Minimal agent sequence (token-optimized, reduced analysis depth):
@@ -102,7 +112,8 @@ Output JSON with:
   - trade_offs: array of strings
   - remaining_risks: array of strings
 
-Apply changes directly with Edit/Write tools. Do not serialize full file contents in your response."
+Apply changes directly with Edit/Write tools. Do not serialize full file contents in your response.
+Do not edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask explicitly requires it. Report any required scope expansion as a blocker/tradeoff."
 )
 ```
 

.claude/skills/map-task/SKILL.md

@@ -37,6 +37,15 @@ parallel_tool_policy: single_subtask_sequential
 - Do not re-plan the selected subtask unless its stored contract is missing or contradictory.
 - Do not add Predictor, Evaluator, or learning work unless the shared state machine requires it for this subtask.
 
+## Mutation Boundary Constraints
+
+These constraints apply to the selected subtask's write-capable phases:
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the selected subtask contract explicitly names that dependency change.
+- Do not refactor neighboring code unless the selected subtask's validation criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff and stop for a contract update instead of doing it silently.
+
 ---
 
 ## Step 0: Parse Arguments

.codex/AGENTS.md

@@ -31,6 +31,15 @@ research and review phases. This prevents accidental edits while exploring.
 **Note:** Hooks require `hooks = true` in config.toml and are not
 supported on Windows.
 
+## Mutation Boundary Constraints
+
+For write-capable MAP skills and agents:
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the current task or subtask explicitly names that dependency change.
+- Do not refactor neighboring code unless the acceptance criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff instead of doing it silently.
+
 ## Getting Started
 
 1. Trust this project in Codex settings

.codex/skills/map-fast/SKILL.md

@@ -13,6 +13,13 @@ Minimal MAP workflow for small changes. Skips planning and learning phases.
 $map-fast <task description>
 ```
 
+## Mutation Boundary Constraints
+
+- Do not edit unrelated files, even if they are nearby or easy to clean up.
+- Do not add, remove, or upgrade dependencies unless the task explicitly names that dependency change.
+- Do not refactor neighboring code unless the acceptance criteria cannot pass without that exact refactor.
+- If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff instead of doing it silently.
+
 ## Workflow
 
 1. Research: `shell_command` to explore relevant files

README.md

@@ -131,6 +131,7 @@ MAP review is useful, but it is not a replacement for engineering judgment. Seri
 - **Low overhead** - structured enough to prevent chaos, lightweight enough to keep token and time cost under control.
 - **Compact high-traffic playbooks** - `/map-plan`, `/map-efficient`, `/map-check`, and `/map-review` keep their active `SKILL.md` bodies focused on the next workflow action, with detailed examples and troubleshooting in bundled supporting files that load only when needed.
 - **Calibrated workflow effort** - each shipped slash skill declares a `thinking_policy` and `parallel_tool_policy`, so lightweight commands stay direct while planning, review, and release workflows reserve deeper reasoning and parallel fan-out for the stages that benefit from it. Non-release prompts use targeted guardrails instead of blanket all-caps prohibition blocks, reducing over-triggered agents and tool calls while keeping true hard stops explicit.
+- **Mutation boundary constraints** - write-capable Claude and Codex provider surfaces tell agents not to edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current task/subtask explicitly requires it. If broader scope is necessary, agents should report it as a blocker or tradeoff instead of silently expanding the diff.
 - **Context-first prompt envelopes** - high-context `/map-plan`, `/map-efficient`, `/map-debug`, and `/map-review` agent prompts wrap branch artifacts in XML-style `<documents>`, then state the `<task>` and `<expected_output>`, so specs, review bundles, diffs, logs, and schemas stay visually and machine-semantically separated.
 - **Skill IR audit** - release checks can lower shipped Claude and Codex `SKILL.md` files into a typed `SkillIR`, verify content hashes, catch unsupported frontmatter, reject missing supporting-file links, and block injection-like instructions before `mapify init` copies provider surfaces into user repos.
 - **Reviewable diffs** - planning and task contracts keep changes small enough to inspect.

docs/ARCHITECTURE.md

@@ -82,6 +82,7 @@ Claude skill metadata includes `skillClass` in `.claude/skills/skill-rules.json`
 
 - **Context Budgeting & Compression**: MAP exposes compression policies and thresholds and treats budget control as a first-class workflow concern. Generated Actor `<map_context>` blocks and `/map-review` reviewer fan-out prompts are capped by deterministic estimated-token budgets before prompt injection so long plans or raw diffs cannot silently crowd out current-subtask, review-bundle, and dependency context. Active budgeted prompt paths append before/after estimates and clipped section labels to `.map/<branch>/token_budget.json` so users can diagnose missing-context reports without transcript inspection.
 - **Effort & Parallelism Calibration**: Each task skill declares a `thinking_policy` and `parallel_tool_policy` so provider runtimes know when to stay direct, when to use adaptive reasoning, and when parallel fan-out is safe. Prompt-tone regression tests keep non-release skills on targeted guardrails instead of blanket prohibition blocks, which protects lightweight workflows from unnecessary subagent/tool expansion.
+- **Mutation Boundary Constraints**: Write-capable provider surfaces include explicit negative constraints at the point where agents can edit files. Actor, `/map-fast`, `/map-efficient`, `/map-task`, `/map-debug`, and Codex quick-implementation scaffolds tell agents not to edit unrelated files, change dependencies, or refactor neighboring code unless the current contract requires it; necessary scope expansion must be reported as a blocker/tradeoff.
 - **Compact Skill Playbooks**: High-traffic task skills keep `SKILL.md` focused on active next-action flow and move examples, troubleshooting, and low-frequency rationale into bundled supporting files. This reduces recurring context cost after invocation and compaction without deleting the reference material needed for edge cases.
 - **Context-First Prompt Envelopes**: High-context skill prompts use a shared XML-style envelope so persisted artifacts appear in `<documents>` before `<task>`, instructions, and `<expected_output>`. This keeps specs, review bundles, diffs, logs, and output schemas distinct when provider runtimes receive long subagent prompts.
 - **Skill IR Audit**: `src/mapify_cli/skill_ir.py` lowers hand-authored Claude and Codex `SKILL.md` files into provider-neutral `SkillIR` records with content hashes, invocation mode, supporting-file links, and extracted safety constraints. The audit fails unsupported frontmatter, unresolved bundled references, and hidden instruction-override wording before provider surfaces are installed.

docs/USAGE.md

@@ -75,6 +75,8 @@ Maintainer guardrail: every skill prompt section that says `Output JSON with:` m
 
 Maintainer prompt-tone guardrail: non-release MAP skills should use targeted workflow guardrails and explicit off-ramps instead of blanket all-caps prohibition blocks. `tests/test_skills.py::TestPromptToneCalibration` keeps `/map-fast`, `/map-check`, `/map-resume`, and `/map-task` focused on their intended scope and reserves aggressive hard-stop wording for release safety and irreversible operations.
 
+Maintainer mutation-boundary guardrail: write-capable Claude and Codex provider surfaces must include `Mutation Boundary Constraints` before broad write prompts. `tests/test_skills.py::TestSkillStructure::test_write_capable_claude_surfaces_have_constraint_first_boundaries` and `test_write_capable_codex_surfaces_have_mutation_boundaries` keep installed agents from losing the explicit “do not edit unrelated files / do not change dependencies / report scope expansion” rule.
+
 Maintainer provider-surface guardrail: shipped Claude and Codex skills can be audited as typed `SkillIR` records before release. Run `python -m mapify_cli.skill_ir src/mapify_cli/templates/skills src/mapify_cli/templates/codex/skills` to parse every `SKILL.md`, print deterministic content hashes, and fail unsupported frontmatter, missing bundled Markdown references, or injection-like phrases such as “ignore previous instructions.”
 
 Maintainer skill-lifecycle guardrail: high-traffic workflow skills (`/map-plan`, `/map-efficient`, `/map-check`, and `/map-review`) keep the active `SKILL.md` body under 500 lines and link to bundled supporting files for examples, troubleshooting, and low-frequency reference details. This keeps invoked skill content cheaper to carry through long sessions and compaction while preserving full reference material for ambiguous or failing runs.

docs/improvement-done.md

@@ -1,5 +1,15 @@
 # MAP Framework Improvement Done
 
+## Constraint-first provider rule templates [2604.040]
+
+- Date: 2026-05-20
+- Added `Mutation Boundary Constraints` to write-capable Claude provider surfaces: `.claude/agents/actor.md`, `/map-fast`, `/map-efficient`, `/map-task`, and `/map-debug`, plus the shipped template copies.
+- Added matching Codex constraints to `.codex/AGENTS.md` and `$map-fast`, plus the shipped template copies, so installed Codex projects get the same unrelated-edit/dependency-change boundary.
+- The constraints tell agents not to edit unrelated files, add/remove/upgrade dependencies, or refactor neighboring code unless the current task/subtask explicitly requires it; required scope expansion must be reported as a blocker/tradeoff instead of done silently.
+- Added regression tests that scan source and generated Claude/Codex provider surfaces for the mutation-boundary section and required phrases before release.
+- Updated README, usage, and architecture docs to describe the installed-user behavior and maintainer guardrail.
+- Verified with focused mutation-boundary prompt tests, full skill/template-sync tests, generated Claude and Codex `mapify init` smokes that inspected installed provider files, Skill IR audit, `make lint`, `pytest -m "not slow"`, and no-LLM e2e artifact tests. Full `pytest` and the slow Claude SDK module were attempted, but each exceeded the 30-minute tool timeout without a deterministic failure message.
+
 ## Compact high-traffic workflow playbooks [2604.033-2]
 
 - Date: 2026-05-20

docs/improvement-loop-log.md

@@ -372,3 +372,18 @@
   - invariant: `High-traffic workflow SKILL.md files should keep active next-action flow under 500 lines and link bundled supporting files for examples/troubleshooting/reference material.`
   - review-check: `When compacting task skills, verify source and template SKILL.md files still preserve state-machine commands, output contracts, closeout artifact writes, and prompt-contract markers before moving detail into references.`
   - gotcha: `Tests that assert a command appears before first Task( can fail if prose mentions Task( earlier than the real launch; keep literal launch markers out of preflight prose.`
+
+## 2026-05-20 - Constraint-first provider rule templates [2604.040]
+
+- Decision: `implemented`
+- Branch: `codex/2604-040-constraint-provider-rules`
+- Baseline: The active plan identified that generated provider rules lacked a structural guardrail against broad positive write directives. Claude write-capable surfaces already had scattered scope wording, but there was no uniform installed-project constraint that blocked unrelated edits, dependency churn, or neighboring refactors at mutation boundaries.
+- Forward Change: Added `Mutation Boundary Constraints` to the Actor agent, `/map-fast`, `/map-efficient`, `/map-task`, `/map-debug`, `.codex/AGENTS.md`, and Codex `$map-fast`, then synced the shipped templates. The constraints require agents to report dependency changes, broad refactors, or scope expansion as blockers/tradeoffs instead of doing them silently.
+- Decisive Validation: Focused prompt regression tests now scan source and shipped Claude/Codex provider surfaces for the mutation-boundary section and required unrelated-file/dependency/refactor/blocker phrases. Generated-project smokes inspected installed `.claude/` files, root `AGENTS.md` for Codex, and `.codex/skills/map-fast/SKILL.md`.
+- Validation Boundary: `pytest` and `pytest tests/integration/test_e2e_claude_sdk.py -v -m slow` were both attempted and exceeded the 30-minute tool timeout without a deterministic failure message. Deterministic validation passed via `make lint`, `pytest -m "not slow"`, focused skill/template tests, no-LLM e2e artifact tests, Skill IR audit, and generated-project smokes.
+- Next Trigger: Reuse this when adding a write-capable provider surface, changing Actor/fix prompts, or introducing any prompt that says to apply edits directly.
+- Reusable Learnings:
+  - command: `pytest tests/test_skills.py::TestSkillStructure::test_write_capable_claude_surfaces_have_constraint_first_boundaries tests/test_skills.py::TestSkillStructure::test_write_capable_codex_surfaces_have_mutation_boundaries -v`
+  - command: `uv run --no-sync mapify init <new-dir> --no-git --mcp none`
+  - invariant: `Every write-capable provider surface should include Mutation Boundary Constraints that block unrelated edits, dependency changes, and neighboring refactors unless the current contract explicitly requires them.`
+  - review-check: `When a prompt says Actor/fix/apply_patch should edit files directly, verify the same prompt or its enclosing skill tells the agent to report required scope expansion as a blocker/tradeoff.`