Add contract-sized subtask guardrails#120
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a deterministic blueprint contract gate that prevents /map-plan and /map-efficient from proceeding to implementation with oversized, mixed-concern, malformed, duplicate-ID, dangling-dependency, or untraceable subtasks. The new validate_blueprint_contract function in map_step_runner.py is shipped as the runtime enforcement point, with corresponding metadata (expected_diff_size, concern_type, one_logical_step, split_rationale, concern_justification, coverage_map) wired through planner/decomposer prompts, Actor context, Monitor/FinalVerifier checks, and BLUEPRINT_SCHEMA. Docs and improvement-plan tracking are updated to mark this as the shipped first slice of item 2604.039.
Changes:
- Add
validate_blueprint_contract()to.map/scripts/map_step_runner.py(and the templated copy) with broad regression tests for sizing/concern/coverage rules, duplicate IDs, and bad dependencies. - Extend
BLUEPRINT_SCHEMAto require new contract metadata and support nested{"blueprint": {...}}payloads; surface contract fields in Actor XML packets and context block. - Align Claude/Codex planner skills, decomposer agents, Monitor, FinalVerifier, README, USAGE, ARCHITECTURE, and roadmap/improvement docs around the same contract.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/mapify_cli/templates/map/scripts/map_step_runner.py | Adds validate_blueprint_contract, CLI dispatch, Actor packet/context fields, and nested-blueprint unwrap in load_blueprint. |
| .map/scripts/map_step_runner.py | Mirror of the runtime script with the same additions. |
| src/mapify_cli/schemas.py | Adds contract fields, ST-NNN patterns, coverage_map, and blueprint-wrapper anyOf to BLUEPRINT_SCHEMA. |
| src/mapify_cli/templates/skills/map-plan/SKILL.md, .claude/skills/map-plan/SKILL.md | Require new metadata, replace inline validator with validate_blueprint_contract, surface fields in human plan. |
| src/mapify_cli/templates/codex/skills/map-plan/SKILL.md, .codex/skills/map-plan/SKILL.md | Same updates for the Codex skill. |
| src/mapify_cli/templates/skills/map-efficient/SKILL.md, .claude/skills/map-efficient/SKILL.md | Add contract metadata requirements and the validator call into the efficient flow. |
| src/mapify_cli/templates/agents/task-decomposer.md, .claude/agents/task-decomposer.md | Add coverage_map and contract metadata to the decomposer output schema and checklist. |
| src/mapify_cli/templates/codex/agents/decomposer.toml, .codex/agents/decomposer.toml | Codex decomposer equivalent. |
| src/mapify_cli/templates/agents/monitor.md, .claude/agents/monitor.md | Add subtask contract violation as an auto-reject signal. |
| src/mapify_cli/templates/agents/final-verifier.md, .claude/agents/final-verifier.md | Add blueprint contract row and verification step. |
| tests/test_map_step_runner.py | New regression coverage for validate_blueprint_contract and contract fields in the context block. |
| tests/test_decomposition.py | New schema tests for contract metadata, nested decomposer output, and dependency/coverage patterns. |
| tests/test_skills.py | Regression tests asserting planning prompts and decomposer agents reference the new fields. |
| README.md, docs/USAGE.md, docs/ARCHITECTURE.md, docs/roadmap.md, docs/improvement-plan.md, docs/improvement-done.md | Doc updates describing and tracking the shipped contract gate. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
/map-planand/map-efficientfail oversized, mixed-concern, malformed, duplicate-ID, dangling-dependency, or untraceable subtasks before implementation starts.BLUEPRINT_SCHEMAaround the same subtask contract metadata.2604.039as a shipped runtime slice while leaving hard/soft constraint typing and deeper artifact lineage as follow-up work.Validation
make lintpytest -m "not slow"uv run --no-sync mapify init /var/folders/3j/zmvdy5_56bjcg1kmrx05dltcf7yldq/T/opencode/mapify-contract-guardrails-2604-039-rerun4 --no-git --mcp nonepython3 .map/scripts/map_step_runner.py validate_blueprint_contract valid-blueprint.json