Add mutation boundary prompt guardrails#139
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds “Mutation Boundary Constraints” guardrails to MAP’s write-capable Claude and Codex prompt surfaces so agents avoid silently expanding diffs (unrelated files, dependency churn, neighboring refactors) unless explicitly required by the current task/subtask contract. This is reinforced with regression tests that scan both source and shipped templates, plus documentation updates capturing the invariant and review checks.
Changes:
- Introduces mutation-boundary constraint sections across write-capable Claude skill/agent surfaces and Codex scaffolds (source + shipped templates).
- Adds regression tests to ensure required guardrail wording is present (and partially ordered constraint-before-directive).
- Documents the new maintainer guardrail and records the improvement-plan completion/learned checks.
Reviewed changes
Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_skills.py | Adds mutation-boundary regression tests and shared phrase/pattern definitions. |
| src/mapify_cli/templates/skills/map-task/SKILL.md | Adds Mutation Boundary Constraints section to shipped /map-task. |
| src/mapify_cli/templates/skills/map-fast/SKILL.md | Adds Mutation Boundary Constraints section + reinforces constraint wording inside the Actor prompt block. |
| src/mapify_cli/templates/skills/map-efficient/SKILL.md | Adds Mutation Boundary Constraints section + reinforces constraint wording inside the Actor <task> block. |
| src/mapify_cli/templates/skills/map-debug/SKILL.md | Adds Mutation Boundary Constraints section + reinforces constraint wording in fix prompt block. |
| src/mapify_cli/templates/codex/skills/map-fast/SKILL.md | Adds Mutation Boundary Constraints to shipped Codex $map-fast scaffold. |
| src/mapify_cli/templates/codex/AGENTS.md | Adds Mutation Boundary Constraints to shipped Codex AGENTS.md. |
| src/mapify_cli/templates/agents/actor.md | Adds Mutation Boundary Constraints to shipped Claude Actor agent prompt. |
| README.md | Documents mutation-boundary constraints as a product behavior. |
| docs/USAGE.md | Documents the maintainer guardrail and points to the enforcing tests. |
| docs/learned/testing-strategies.md | Captures learned guidance about regression testing mutation-boundary wording. |
| docs/learned/review-checks.md | Adds a review check to require mutation boundaries near direct-edit prompts. |
| docs/learned/commands.md | Adds suggested commands for running the new mutation-boundary tests. |
| docs/learned/architecture-patterns.md | Records the pattern of pairing write directives with explicit negative constraints. |
| docs/improvement-plan.md | Removes the completed 2604.040 plan section now that it’s implemented. |
| docs/improvement-loop-log.md | Logs the 2604.040 decision, validation, and reusable commands/invariants. |
| docs/improvement-done.md | Records completion summary for 2604.040 and validation steps. |
| docs/ARCHITECTURE.md | Adds “Mutation Boundary Constraints” to the architecture overview bullets. |
| .codex/skills/map-fast/SKILL.md | Adds Mutation Boundary Constraints to the repo’s Codex source scaffold. |
| .codex/AGENTS.md | Adds Mutation Boundary Constraints to the repo’s Codex source AGENTS.md. |
| .claude/skills/map-task/SKILL.md | Adds Mutation Boundary Constraints to the repo’s Claude /map-task. |
| .claude/skills/map-fast/SKILL.md | Adds Mutation Boundary Constraints + reinforces constraint wording in Actor prompt block. |
| .claude/skills/map-efficient/SKILL.md | Adds Mutation Boundary Constraints + reinforces constraint wording in Actor <task> block. |
| .claude/skills/map-debug/SKILL.md | Adds Mutation Boundary Constraints + reinforces constraint wording in fix prompt block. |
| .claude/agents/actor.md | Adds Mutation Boundary Constraints to the repo’s Claude Actor agent prompt. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+41
to
+48
| ## 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. |
Comment on lines
+24
to
+28
| ## 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. |
Comment on lines
+24
to
+28
| ## 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. |
Comment on lines
+41
to
+48
| ## 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. |
Comment on lines
+112
to
+114
| MUTATION_DIRECTIVE_PATTERN = re.compile( | ||
| r"\b(?:Apply changes directly|Use Edit/Write|Implement exactly|" | ||
| r"Implement this subtask|Implement a fix|make changes)\b", |
Owner
Author
|
Addressed Copilot review comments in e5b3325..HEAD follow-up: moved Actor and Codex -fast mutation-boundary sections before their first direct-write directives, expanded the directive pattern to include 'Apply the fix directly', and now applies ordering checks to Actor and Codex surfaces as well. Revalidated focused prompt/template tests, generated Claude/Codex ordering smoke, make lint, and pytest -m "not slow". |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
User impact
Installed MAP workflows now tell agents not to edit unrelated files, change dependencies, or refactor neighboring code unless the current task/subtask explicitly requires it. Required scope expansion should be reported as a blocker or tradeoff instead of silently widening the diff.
Validation
Validation boundary