Conversation
…t templates - Fix AskUserQuestionTool → AskUserQuestion in map-plan.md and map-efficient.md - Replace cat heredoc patterns with Write tool instructions - Add step to save research-agent findings to findings_<branch>.md - Add CODE CHANGES ONLY rule to task-decomposer (no operational subtasks) - Add resume_from_plan command to orchestrator for /map-plan handoff - Add set_subtasks command to orchestrator to register subtask sequence - Fix current_subtask: null by auto-selecting first subtask after INIT_STATE - Fix map_step_runner.py path: scripts/ → .map/scripts/ All changes synced between .claude/ and src/mapify_cli/templates/.
…nd validation scripts - Add Examples and Troubleshooting sections to all three skill SKILL.md files - Improve skill descriptions with explicit routing guidance (do/don't use for) - Add metadata (author, version, mcp-server) to skill frontmatter - Add map-planning and map-cli-reference entries to skill-rules.json - Add check-command.sh script for CLI error validation - Add validate-workflow-choice.py script for workflow selection logic - Add tests/test_skills.py with skill structure and content validation - Minor formatting cleanup in safety-guardrails.py and ralph-context-pruner.py
-7) - #1-3: Remove Actor "proposals only" section — Actor applies code directly with Edit/Write tools, consistent with map-efficient.md prompts - #4: Rename orchestrator phase 2.7 from APPLY_CHANGES to UPDATE_STATE (Actor applies code, 2.7 only updates state tracking) - #5: Implement check_circuit_breaker command in orchestrator (was referenced in map-efficient.md but missing from argparse) - #6: Replace non-existent map-efficient-step reference with /map-resume - #7: Fix STEP_ORDER index bug — used [3:] (starts at CHOOSE_MODE) instead of index("2.0") (starts at XML_PACKET) for subtask loop reset
…-35) MEDIUM fixes: - #8: Remove dead RETRY_LOOP phase from orchestrator STEP_PHASES - #10: Fix plan path to branch-scoped .map/<branch>/task_plan_<branch>.md - #11: Fix findings path to branch-scoped .map/<branch>/findings_<branch>.md - #12: Remove references to non-existent ralph-loop-config.json - #13/#14: Rewrite map-resume to use step_state.json instead of progress.md - #15: Fix INIT_PLAN heading format (### ST-XXX with - **Status:** prefix) - #16: Fix regex in step_runner to match plan format (### heading, - **Status:**) - #17: Fix map-learn contradiction about automatic learning LOW fixes: - #9/#31: Document dual state file system (step_state.json vs workflow_state.json) - #19: Document intentional Evaluator/Reflector/Curator omission in map-efficient - #20: Fix line count reference (~150 → ~540 lines) - #21: Standardize all AskUserQuestion to Python function call syntax - #22: Rename Steps 2.5/2.6 to 2a/2b to avoid phase number collision - #23/#24: Fix map-debate comparison table (map-efficient uses single Actor) - #25: Replace cat commands with Read tool comments in map-check - #28/#29: Replace undefined thrashing_detected()/max_redecompositions - #30: Add - **Status:** pending field to map-plan template - #32: Note map-fast max 3 vs map-efficient max 5 intentional difference - #33: Remove Evaluator from map-fast skipped agents list - #34: Move AskUserQuestion to "Built-in Tools" section in map-release - #35: Replace parallel bash & processes with sequential && in map-release Template sync: All .claude/ changes mirrored to src/mapify_cli/templates/
validate_step() now requires evidence files from Actor (2.3), Monitor (2.4), and Predictor (2.6) agents before accepting step completion. This prevents skipping agent phases by chaining validate_step calls. - Add EVIDENCE_REQUIRED constant mapping steps to agent phases - Validate evidence JSON: existence, structure, required fields (phase, subtask_id, timestamp), and subtask_id match - Create evidence/ directory in initialize_workflow and resume_from_plan - Add evidence file writing instructions to actor.md, monitor.md, predictor.md agent templates - Add execution rule 5 to map-efficient.md documenting the requirement - Fix unicode arrow (U+2192) in map_step_runner.py message output - Sync all templates via make sync-templates
…d commands
- Unify {{standards_url}} -> {{standards_doc}} in actor.md (3 places)
- Unify {{branch}} -> {{branch_name}} in actor.md to match reflector/curator
- Fix actor evidence files_changed from int to array (matches predictor input)
- Wrap {{evaluator_scores}} in {{#if}} in reflector.md (evaluator is optional)
- Add {{changed_files}} to monitor optional placeholder table
- Annotate {{solution}}/{{requirements}} in monitor with MAP workflow equivalents
- Fix map-efficient.md: top_k -> limit, user_id/run_id format for map_tiered_search
- Delete stale map-efficient.md.backup file
- Fix REVIEW_PLAN path: .map/task_plan_<branch>.md -> .map/<branch>/task_plan_<branch>.md - Fix "3-strike protocol" comment to "retry limit reached" (actual limit is 5) - Fix evidence subtask_id check indentation (was inside for-loop, now outside) - Add skip_step CLI command for conditional phases (2.2 RESEARCH, 2.6 PREDICTOR, 2.11 SUBTASK_APPROVAL) - Add SKIPPABLE_STEPS constant to orchestrator
Aligns documentation with the unified template variable name used across actor.md and monitor.md agents.
Three hooks (workflow-gate.py, workflow-context-injector.py,
post-edit-reminder.py) used simple replace("/", "-") while the
orchestrator uses full regex sanitization. This caused path mismatches
for branches with special characters (@, #, etc.).
- Add sanitize_branch_name() with full regex to all 3 hooks
- Add missing import re to post-edit-reminder.py
- Add missing timeout=1 to ralph-iteration-logger.py subprocess call
All commands used simple sed 's/\//-/g' while Python code uses full regex sanitization (strip special chars, collapse dashes, reject '..'). Updated map-efficient, map-resume, map-plan, map-check to match.
…mmon vars - documentation-reviewer.md: map_tiered_search parameter top_k=5 → limit=5 (matches actual mem0 MCP API) - lint-agent-templates.py: update common variable names list standards_url → standards_doc, branch → branch_name (matches fixes applied to agent templates in prior commits)
…nd MAP_Context - docs/WORKFLOW_FLOW.md: update 2 branch sanitization sed commands to full regex - .claude/references/workflow-state-schema.md: update branch sanitization sed - map-efficient.md: <MAP_Context> top_k="3" → limit="3" (matches mem0 API) - docs/ARCHITECTURE.md: top_k=N → limit=N in Pattern Limiting docs (4 places) - Template copies synced via make sync-templates
…ions - Changed _sanitize_branch_name to use dashes (not underscores) matching all other MAP framework sanitization functions - Added full regex sanitization: special chars, dash collapsing, path traversal prevention (../ and leading dot checks) - Added import re
…ntion All .map/ artifacts use nested directories (.map/<branch>/file.md), but several files referenced flat paths (.map/file_<branch>.md): - final-verifier.md: 7 path references corrected (task_plan, progress) - task-decomposer.md: 1 path reference corrected (task_plan) - map-planning/SKILL.md: file structure diagram + 6 path references corrected, added workflow_state.json and evidence/ to diagram - map_orchestrator.py: instruction string for step 1.5 corrected All template copies synced.
Updated remaining flat .map/task_plan_<branch>.md references to use nested .map/<branch>/task_plan_<branch>.md convention: - research-agent.md: findings file example path - docs/ARCHITECTURE.md: 5 path references - docs/COMPLETE_WORKFLOW.md: 2 path references - docs/USAGE.md: 4 path references (task_plan paths)
- get-plan-path.sh: output .map/<branch>/task_plan_<branch>.md (was flat) Also updated to full regex branch sanitization (was just tr '/' '-') - init-session.sh: create files in .map/<branch>/ subdirectory (was flat) Also updated to full regex branch sanitization - Both scripts now use git rev-parse --abbrev-ref HEAD (was git branch) - Template copies synced
The orchestrator has no step 2.5 (RETRY_LOOP) — retries are handled within MONITOR (2.4). Step 2.7 is UPDATE_STATE, not APPLY_CHANGES (Actor applies changes during 2.3). - step-state-schema.md: removed 2.5 RETRY_LOOP, renamed 2.7 to UPDATE_STATE, renumbered steps 11-16 - docs/ARCHITECTURE.md: same corrections in step listing - docs/WORKFLOW_FLOW.md: removed RETRY_LOOP row from table, renamed APPLY_CHANGES to UPDATE_STATE, added retry note to MONITOR row - map_orchestrator.py: fixed instruction string for step 1.5 path
Test expected Bash(go test:*) with colons but actual settings.local.json uses Bash(go test *) with spaces. Fixed 4 assertions: - Bash(go test:*) → Bash(go test *) - Bash(go vet :*) → Bash(go vet *) - Bash(go mod tidy:*) → Bash(go mod tidy *) - Bash(git worktree add:*) → Bash(git worktree add *)
…ted) These workflows were documented in the workflows guide as real commands but don't exist as actual .claude/commands/ files. Updated: - SKILL.md: comparison matrix, decision tree, examples, Q&A - validate-workflow-choice.py: removed non-existent workflow entries - Deep-dive resources: added PLANNED status banners - map-planning SKILL.md: removed /map-feature reference
- Sync workflows guide SKILL.md, validation script, deep-dive resources to src/mapify_cli/templates/skills/ - Merge map-feature and map-refactor triggers into map-efficient in workflow-rules.json (these commands don't exist) - Update schemas.py examples to only list implemented workflows
Was only doing branch.replace('/', '-'), now uses full regex pattern
matching all other MAP scripts (orchestrator, runner, hooks).
…and plugin metadata Presentation slides (en/ru) and .claude-plugin/ files listed /map-feature and /map-refactor as implemented commands. These workflows are planned but not yet available. Updated all references to use the actual implemented commands: /map-efficient, /map-debug, /map-fast, /map-review. Also fixed flat .map/progress.md path references to nested .map/<branch>/.
📝 WalkthroughWalkthroughThis PR expands MAP from 9→12 agents, renames core workflows (/map-feature→/map-efficient, /map-refactor→/map-fast), moves artifacts to branch-scoped paths (.map//...), adds evidence‑gated validation, extends orchestrator/state APIs (resume/set_subtasks/skip/check), tightens branch sanitization, and updates docs, hooks, templates, and tests. Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR updates MAP’s workflow/skill ecosystem to reflect the “map-efficient as default” model, introduces stricter skill structure validation, and standardizes branch-scoped state/artifacts under .map/<sanitized_branch>/ with improved sanitization and evidence-gated execution.
Changes:
- Add comprehensive tests enforcing skill folder structure, SKILL.md frontmatter/content requirements, and template sync between
.claude/skillsandsrc/.../templates/skills. - Standardize branch sanitization and migrate MAP artifacts to nested
.map/<branch>/...paths across scripts, hooks, and docs; add evidence-gated validation to the orchestrator. - Consolidate workflow selection rules (removing/renaming legacy workflows) and refresh docs/templates accordingly.
Reviewed changes
Copilot reviewed 106 out of 106 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_skills.py | New test suite enforcing skill structure/frontmatter/sections, skill-rules coverage, and template sync. |
| tests/test_mapify_cli.py | Updates expected permissions allowlist patterns to the new “space + wildcard” style. |
| src/mapify_cli/verification_recorder.py | Strengthens branch-name sanitization for verification result filenames. |
| src/mapify_cli/templates/workflow-rules.json | Consolidates workflow rules (e.g., map-efficient as primary). |
| src/mapify_cli/templates/skills/skill-rules.json | Updates skill triggers and adds new skills to rules. |
| src/mapify_cli/templates/skills/map-workflows-guide/scripts/validate-workflow-choice.py | New script for validating workflow choice based on task characteristics. |
| src/mapify_cli/templates/skills/map-workflows-guide/resources/map-refactor-deep-dive.md | Marks map-refactor as planned/not implemented. |
| src/mapify_cli/templates/skills/map-workflows-guide/resources/map-feature-deep-dive.md | Marks map-feature as planned/not implemented. |
| src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md | Updates workflow guidance, matrix, and adds Examples/Troubleshooting sections. |
| src/mapify_cli/templates/skills/map-planning/scripts/init-session.sh | Moves planning artifacts into .map/<branch>/ and updates sanitization approach. |
| src/mapify_cli/templates/skills/map-planning/scripts/get-plan-path.sh | Returns nested .map/<branch>/task_plan_<branch>.md path; updates sanitization. |
| src/mapify_cli/templates/skills/map-planning/SKILL.md | Updates docs to nested .map/<branch>/ structure and adds Examples/Troubleshooting. |
| src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh | New helper script to validate mapify subcommands and show usage. |
| src/mapify_cli/templates/skills/map-cli-reference/SKILL.md | Adds structured description plus Examples/Troubleshooting. |
| src/mapify_cli/templates/skills/README.md | Updates skill resource list to reflect planned workflows. |
| src/mapify_cli/templates/settings.json | Converts deny/allow command patterns to new format (space-separated). |
| src/mapify_cli/templates/settings.hooks.json | Increases hook timeouts from 1s to 3s. |
| src/mapify_cli/templates/references/workflow-state-schema.md | Updates branch sanitization example to stricter sed pipeline. |
| src/mapify_cli/templates/references/step-state-schema.md | Updates step list (removes retry loop step; renames apply changes to update state). |
| src/mapify_cli/templates/map/scripts/map_step_runner.py | Updates plan path and status update regex to match new plan formatting/location. |
| src/mapify_cli/templates/map/scripts/map_orchestrator.py | Adds evidence-gated step validation and new orchestrator helper commands (skip/resume/etc.). |
| src/mapify_cli/templates/map/scripts/diagnostics.py | Strengthens branch sanitization in diagnostics output path logic. |
| src/mapify_cli/templates/hooks/workflow-gate.py | Aligns branch sanitization and workflow_state.json location under .map/<branch>/. |
| src/mapify_cli/templates/hooks/workflow-context-injector.py | Adds shared sanitization helper and reduces git timeout to 1s. |
| src/mapify_cli/templates/hooks/safety-guardrails.py | Formatting-only refactor (list and tuple return formatting). |
| src/mapify_cli/templates/hooks/ralph-iteration-logger.py | Adds subprocess timeout. |
| src/mapify_cli/templates/hooks/ralph-context-pruner.py | Adds subprocess timeout and tightens print formatting. |
| src/mapify_cli/templates/hooks/post-edit-reminder.py | Adds shared branch sanitization helper and reduces git timeout to 1s. |
| src/mapify_cli/templates/commands/map-review.md | Updates evaluator scoring schema to 1–10 rubric and new output fields. |
| src/mapify_cli/templates/commands/map-release.md | Makes quality gates sequential; updates AskUserQuestion syntax examples. |
| src/mapify_cli/templates/commands/map-plan.md | Updates branch directory creation + Write-tool instructions for new .map/<branch>/ layout. |
| src/mapify_cli/templates/commands/map-learn.md | Clarifies learning is always a separate command (no automatic learning). |
| src/mapify_cli/templates/commands/map-fast.md | Updates skipped-agent list wording and removes evaluator references. |
| src/mapify_cli/templates/commands/map-efficient.md | Adds evidence-gating, dual-state-file explanation, and resume-from-plan behavior. |
| src/mapify_cli/templates/commands/map-debug.md | Clarifies Actor→Monitor retry iteration limit. |
| src/mapify_cli/templates/commands/map-debate.md | Normalizes AskUserQuestion formatting and updates comparison table text. |
| src/mapify_cli/templates/commands/map-check.md | Updates branch sanitization snippets and replaces raw cat guidance with Read-tool guidance. |
| src/mapify_cli/templates/agents/task-decomposer.md | Adds rule: subtasks must produce code diffs (no operational subtasks). |
| src/mapify_cli/templates/agents/research-agent.md | Updates findings file path example to .map/<branch>/.... |
| src/mapify_cli/templates/agents/reflector.md | Updates last_updated date and makes evaluator_scores section conditional. |
| src/mapify_cli/templates/agents/predictor.md | Updates pipeline position and adds evidence-file writing requirements. |
| src/mapify_cli/templates/agents/monitor.md | Clarifies placeholders used in MAP workflow and adds evidence-file writing requirements. |
| src/mapify_cli/templates/agents/final-verifier.md | Updates all paths to nested .map/<branch>/... layout. |
| src/mapify_cli/templates/agents/documentation-reviewer.md | Updates mem0 API usage from top_k to limit. |
| src/mapify_cli/templates/agents/actor.md | Changes Actor role to directly apply edits and adds evidence-file writing requirement. |
| src/mapify_cli/schemas.py | Removes legacy workflow examples (map-feature/map-refactor) from schema docs. |
| src/mapify_cli/init.py | Updates global/project permission templates to new Bash pattern format. |
| scripts/lint-agent-templates.py | Updates allowed template variables (standards_doc/branch_name). |
| presentation/ru/03-workflow.md | Updates workflow command list and references to match new workflows. |
| presentation/en/04-getting-started.md | Updates command list and examples to map-efficient/map-fast terminology. |
| presentation/en/03-workflow.md | Updates workflow command list and enforcement rules references. |
| presentation/en/02-architecture.md | Updates orchestrator command references to new workflow set. |
| docs/WORKFLOW_FLOW.md | Updates step naming and branch sanitization snippets. |
| docs/USAGE.md | Updates documentation paths to .map/*/task_plan_*.md convention. |
| docs/COMPLETE_WORKFLOW.md | Updates task plan paths to .map/<branch>/.... |
| docs/ARCHITECTURE.md | Updates task plan paths, step lists, and mem0 parameter naming (limit). |
| README.md | Replaces placeholder with full project README introducing map-efficient as primary command. |
| .map/scripts/map_step_runner.py | Mirrors template updates for plan path and status updates in local .map scripts. |
| .map/scripts/map_orchestrator.py | Mirrors template orchestrator changes (evidence-gating + new commands) in local .map scripts. |
| .map/scripts/diagnostics.py | Mirrors template diagnostics branch sanitization changes in local .map scripts. |
| .claude/workflow-rules.json | Updates workflow rule keys/definitions (map-efficient consolidation). |
| .claude/skills/skill-rules.json | Updates skill triggers and adds new skills entries in the live .claude tree. |
| .claude/skills/map-workflows-guide/scripts/validate-workflow-choice.py | Adds the workflow-choice validation script to the live .claude tree. |
| .claude/skills/map-workflows-guide/resources/map-refactor-deep-dive.md | Marks map-refactor as planned/not implemented in live .claude tree. |
| .claude/skills/map-workflows-guide/resources/map-feature-deep-dive.md | Marks map-feature as planned/not implemented in live .claude tree. |
| .claude/skills/map-workflows-guide/SKILL.md | Updates workflow guide skill content/sections in live .claude tree. |
| .claude/skills/map-planning/scripts/init-session.sh | Updates planning init script in live .claude tree for nested .map/<branch>/. |
| .claude/skills/map-planning/scripts/get-plan-path.sh | Updates plan-path script in live .claude tree for nested .map/<branch>/. |
| .claude/skills/map-planning/SKILL.md | Updates planning skill documentation in live .claude tree. |
| .claude/skills/map-cli-reference/scripts/check-command.sh | Adds CLI check script in live .claude tree. |
| .claude/skills/map-cli-reference/SKILL.md | Updates CLI reference skill content/sections in live .claude tree. |
| .claude/skills/README.md | Updates skill resource list in live .claude tree. |
| .claude/settings.json | Updates allow/deny patterns in live .claude settings. |
| .claude/settings.hooks.json | Increases hook timeouts in live .claude settings. |
| .claude/references/workflow-state-schema.md | Updates sanitization snippet in live .claude references. |
| .claude/references/step-state-schema.md | Updates step list in live .claude references. |
| .claude/hooks/workflow-gate.py | Updates sanitization logic and branch-scoped paths for live .claude hook. |
| .claude/hooks/workflow-context-injector.py | Adds sanitization helper and updates git timeout for live .claude hook. |
| .claude/hooks/ralph-iteration-logger.py | Adds subprocess timeout for live .claude hook. |
| .claude/hooks/ralph-context-pruner.py | Adds subprocess timeout for live .claude hook. |
| .claude/hooks/post-edit-reminder.py | Adds sanitization helper and updates git timeout for live .claude hook. |
| .claude/commands/map-review.md | Updates review scoring schema in live .claude command. |
| .claude/commands/map-release.md | Makes release checks sequential and updates AskUserQuestion formatting. |
| .claude/commands/map-plan.md | Updates planning command for nested .map/<branch>/ paths and Write-tool usage. |
| .claude/commands/map-learn.md | Clarifies learning is separated into /map-learn in live .claude command. |
| .claude/commands/map-fast.md | Updates skipped-agent list wording in live .claude command. |
| .claude/commands/map-efficient.md | Adds evidence-gating + dual-state-file docs in live .claude command. |
| .claude/commands/map-debug.md | Clarifies retry iteration limit in live .claude command. |
| .claude/commands/map-debate.md | Normalizes AskUserQuestion formatting in live .claude command. |
| .claude/commands/map-check.md | Updates sanitization snippets and tool guidance in live .claude command. |
| .claude/commands/map-resume.md | Reworks resume flow to use step_state.json/workflow_state.json under .map/<branch>/. |
| .claude/agents/task-decomposer.md | Adds “code changes only” constraint in live .claude agent template. |
| .claude/agents/research-agent.md | Updates findings file path example in live .claude agent template. |
| .claude/agents/reflector.md | Updates last_updated and conditional evaluator_scores section in live .claude agent template. |
| .claude/agents/predictor.md | Updates pipeline description and adds evidence-file requirements in live .claude agent template. |
| .claude/agents/monitor.md | Clarifies placeholders and adds evidence-file requirements in live .claude agent template. |
| .claude/agents/final-verifier.md | Updates branch-scoped artifact paths in live .claude agent template. |
| .claude/agents/documentation-reviewer.md | Updates mem0 parameter naming (limit) in live .claude agent template. |
| .claude/agents/actor.md | Changes Actor role to apply edits and adds evidence-file requirements in live .claude agent template. |
| .claude-plugin/plugin.json | Updates advertised slash commands to map-efficient/map-fast set. |
| .claude-plugin/marketplace.json | Updates marketplace description to new slash command set. |
| .claude-plugin/PLUGIN.md | Updates plugin documentation/examples to new slash command set. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Troubleshooting | ||
|
|
||
| | Issue | Cause | Solution | | ||
| |-------|-------|----------| | ||
| | Wrong workflow chosen mid-task | Cannot switch workflows during execution | Complete current workflow, then restart with correct one | | ||
| | Predictor never runs in /map-efficient | Subtasks assessed as low-risk | Expected behavior; Predictor is conditional. Use /map-feature if you need guaranteed analysis | | ||
| | No patterns stored after /map-fast | /map-fast skips learning agents | By design — use /map-efficient or /map-feature for pattern accumulation | | ||
| | mem0 search returns empty | mem0 MCP not configured or namespaces mismatch | Verify mem0 in `.claude/mcp_config.json`, check namespace conventions | | ||
| | Skill suggests wrong workflow | Description trigger mismatch | Check skill-rules.json triggers; refine query wording | |
There was a problem hiding this comment.
The Troubleshooting table recommends using /map-feature (e.g., when Predictor never runs or to accumulate patterns), but this same SKILL now states /map-feature is planned/not implemented. This is contradictory guidance. Update the troubleshooting entries to recommend an actually available action (e.g., add explicit risk context to force Predictor, or run /map-learn after completion for learning).
| "map-efficient": { | ||
| "priority": "high", | ||
| "description": "Implement new features (critical, full validation)", | ||
| "description": "Production features, refactoring, critical code (recommended default, 60-70% tokens)", | ||
| "promptTriggers": { | ||
| "keywords": [ | ||
| "implement", | ||
| "add feature", | ||
| "new feature", | ||
| "create", | ||
| "build", | ||
| "critical" | ||
| ], | ||
| "intentPatterns": [ | ||
| "(implement|add|create|build).*?(feature|functionality)", | ||
| "new.*?(feature|component|module)", | ||
| "critical.*?(feature|implementation)" | ||
| ] | ||
| } | ||
| }, | ||
| "map-efficient": { | ||
| "priority": "high", | ||
| "description": "Production features (optimized workflow, 60-70% tokens)", | ||
| "promptTriggers": { | ||
| "keywords": [ | ||
| "critical", | ||
| "production", | ||
| "optimize", | ||
| "enhance", | ||
| "improve", | ||
| "update feature" | ||
| ], | ||
| "intentPatterns": [ | ||
| "(optimize|enhance|improve).*?(feature|code|implementation)", | ||
| "production.*?(feature|deploy)", | ||
| "update.*?(feature|functionality)" | ||
| ] | ||
| } | ||
| }, | ||
| "map-refactor": { | ||
| "priority": "medium", | ||
| "description": "Refactor code, improve structure", | ||
| "promptTriggers": { | ||
| "keywords": [ | ||
| "update feature", | ||
| "refactor", | ||
| "restructure", | ||
| "reorganize", | ||
| "clean up", | ||
| "improve structure" | ||
| ], | ||
| "intentPatterns": [ | ||
| "(implement|add|create|build).*?(feature|functionality)", | ||
| "new.*?(feature|component|module)", | ||
| "critical.*?(feature|implementation)", | ||
| "(optimize|enhance|improve).*?(feature|code|implementation)", | ||
| "production.*?(feature|deploy)", | ||
| "update.*?(feature|functionality)", |
There was a problem hiding this comment.
workflow-rules.json removes/renames the map-feature workflow (and also drops map-refactor), but there are still codepaths that recognize these names (e.g., EntityExtractor.workflow_keywords includes 'map-feature' and 'map-refactor'). If these workflows are deprecated/removed, update the remaining mappings/tests accordingly or keep explicit aliases so workflow detection and entity extraction stay consistent.
| def _parse_frontmatter(self, skill_md_path: Path) -> dict: | ||
| """Parse YAML frontmatter from a SKILL.md file.""" | ||
| content = skill_md_path.read_text() | ||
| if not content.startswith("---"): | ||
| return {} | ||
| end = content.find("---", 3) | ||
| if end == -1: | ||
| return {} | ||
| frontmatter_str = content[3:end].strip() | ||
| return yaml.safe_load(frontmatter_str) or {} | ||
|
|
There was a problem hiding this comment.
_parse_frontmatter() calls yaml.safe_load() without handling yaml.YAMLError. If a skill has malformed frontmatter (the scenario this test is meant to detect), the test suite will error out instead of failing with a clear assertion message. Catch YAML parse errors and return {} (or call pytest.fail with a helpful message) so failures are reported deterministically.
| # Sanitize branch name (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi | ||
|
|
||
| # Create .map/<branch> directory (nested convention) | ||
| MAP_DIR=".map/${SANITIZED_BRANCH}" |
There was a problem hiding this comment.
Branch sanitization here claims to match the orchestrator convention, but it doesn't apply the same safety checks used elsewhere (e.g., rejecting '..' segments or branch names starting with '.'). A crafted branch name could still produce paths like .map/.. or hidden directories. Consider mirroring the Python sanitizer logic (collapse dashes + reject '..' / leading '.') and falling back to a safe default.
| # Sanitize branch name for filesystem safety (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
|
|
||
| # Output the plan file path | ||
| echo ".map/task_plan_${SANITIZED_BRANCH}.md" | ||
| # Fallback if sanitization produced empty string | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi | ||
|
|
||
| # Output the plan file path (nested directory convention) | ||
| echo ".map/${SANITIZED_BRANCH}/task_plan_${SANITIZED_BRANCH}.md" |
There was a problem hiding this comment.
Branch sanitization does not guard against '..' or leading '.' (unlike the Python sanitizers added elsewhere). Even if git rejects some ref formats, the script should defensively enforce the same rules before constructing .map/${SANITIZED_BRANCH}/... paths. Recommend adding the same '..'/leading-dot checks and default fallback used in verification_recorder/hooks.
| state_file = Path(f".map/{branch}/step_state.json") | ||
| state = StepState.load(state_file) | ||
|
|
||
| tool_count = len(state.completed_steps) | ||
| max_iterations = len(state.subtask_sequence) * len(STEP_ORDER) | ||
|
|
||
| return { | ||
| "tool_count": tool_count, | ||
| "max_iterations": max_iterations, | ||
| "triggered": tool_count >= max_iterations, | ||
| "retry_count": state.retry_count, | ||
| "max_retries": state.max_retries, | ||
| } |
There was a problem hiding this comment.
check_circuit_breaker() computes max_iterations as len(subtask_sequence) * len(STEP_ORDER). When subtask_sequence is empty (e.g., before set_subtasks runs), max_iterations becomes 0 and the circuit breaker will report triggered=true immediately. Add a guard for empty subtask_sequence (e.g., return triggered=false with a message, or set a minimum max_iterations) to avoid false positives.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 17
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (9)
src/mapify_cli/templates/commands/map-release.md (1)
79-88:⚠️ Potential issue | 🟡 MinorAlign the text with the sequential gate execution.
Line 79 still says gates run “in parallel,” but Gate 1–4 now run sequentially. This is misleading in a safety-critical release workflow. Update the sentence to reflect sequential execution.
🔧 Suggested fix
-Execute all validation gates in parallel where possible: +Execute all validation gates sequentially:src/mapify_cli/templates/commands/map-resume.md (1)
1-454:⚠️ Potential issue | 🟡 MinorAdd
/map-resumeto README.md Core Commands table.Documentation is partially updated:
docs/ARCHITECTURE.mdanddocs/USAGE.mdhave comprehensive coverage of the state-machine flow, checkpoint recovery, and new state files (step_state.json,workflow_state.json). However,README.mdis missing the/map-resumecommand from the Core Commands table. Since this is a significant user-facing recovery feature and README.md is the primary entry point, it should be listed alongside the other workflow commands.src/mapify_cli/templates/references/workflow-state-schema.md (1)
189-190:⚠️ Potential issue | 🟡 MinorBranch sanitization in the Python "State Update Pattern" example is weaker than the new standard.
Line 190 uses
.replace('/', '-')while the debugging snippet (Line 234) andworkflow-gate.pynow apply a stricter multi-step sanitization (non-alphanum replacement, dash collapsing, leading-dot handling). A branch likefeature/foo@barwould producefeature-foo@barhere butfeature-foo-barin the debugging command and in the hook.Consider aligning this example with the
sanitize_branch_name()logic or adding a note to use the helper:Suggested fix
-branch = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], - capture_output=True, text=True).stdout.strip().replace('/', '-') +import re + +def sanitize_branch_name(branch: str) -> str: + sanitized = branch.replace("/", "-") + sanitized = re.sub(r"[^a-zA-Z0-9_.-]", "-", sanitized) + sanitized = re.sub(r"-+", "-", sanitized).strip("-") + if ".." in sanitized or sanitized.startswith("."): + return "default" + return sanitized or "default" + +branch = sanitize_branch_name( + subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], + capture_output=True, text=True).stdout.strip() +)The same inconsistency exists in the "Recovery from Skipped Steps" examples at Lines 218 and 225 which assume
{branch}is already sanitized with only slash→hyphen replacement..claude/commands/map-learn.md (1)
48-48:⚠️ Potential issue | 🟡 MinorStale workflow type names in the "Required information" example.
Line 48 still references
"Workflow type (feature, debug, refactor, review, custom)"which uses the old command names. This should be updated to match the rename:Suggested fix
-- Workflow type (feature, debug, refactor, review, custom) +- Workflow type (efficient, debug, fast, review, custom)src/mapify_cli/verification_recorder.py (1)
128-130:⚠️ Potential issue | 🟡 MinorStale comment: says
feature_foobut code producesfeature-foo.Line 128 says "e.g., feature/foo -> feature_foo" (underscore), but
_sanitize_branch_namereplaces/with-, producingfeature-foo(dash).Proposed fix
- # Sanitize branch name to avoid nested paths (e.g., feature/foo -> feature_foo) + # Sanitize branch name to avoid nested paths (e.g., feature/foo -> feature-foo)src/mapify_cli/templates/commands/map-review.md (1)
53-57:⚠️ Potential issue | 🟠 MajorAlign Monitor schema usage (verdict → valid) to avoid broken aggregation.
Line 53-57 still instructs Monitor to output a
verdict, and Line 164-167 usesmonitor.verdictin the final decision. The Monitor template now emitsvalid(plussummary,issues, etc.), so this command will produce mismatched payloads. Please align the prompt and aggregation logic to the current schema.🔧 Suggested update
- Output JSON with: - - valid: boolean - - issues: array of {severity, category, description, file_path, line_range, suggestion} - - verdict: 'approved' | 'needs_revision' | 'rejected' - - summary: string" + Output JSON with: + - valid: boolean + - summary: string + - issues: array of {severity, category, title, description, location, suggestion} + - passed_checks: array + - failed_checks: array + - feedback_for_actor: string + - estimated_fix_time: string + - mcp_tools_used: array" @@ -- **Proceed if:** Monitor verdict = 'approved' AND Evaluator recommendation = 'proceed' -- **Revise if:** Monitor verdict = 'needs_revision' OR Evaluator recommendation = 'improve' -- **Block if:** Monitor verdict = 'rejected' OR Evaluator recommendation = 'reconsider' OR (Predictor risk_level = 'high' AND breaking_changes.length > 0) +- **Proceed if:** monitor.valid == true AND evaluator.recommendation == 'proceed' +- **Revise if:** monitor.valid == false OR evaluator.recommendation == 'improve' +- **Block if:** evaluator.recommendation == 'reconsider' OR (predictor.risk_level == 'high' AND breaking_changes.length > 0)Also applies to: 164-167
src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md (2)
448-459:⚠️ Potential issue | 🟡 MinorAuto-activation example suggests
/map-feature, which is documented as not yet implemented.The "Integration with Auto-Activation" section shows MAP suggesting
/map-featurefor critical features, but the document explicitly states/map-featureis "planned but not yet implemented" (line 60, 202-206). This will confuse users.Proposed fix
**Questions from MAP:**MAP: "Is this for production?"
User: "Yes, but critical feature"
-MAP: 🎯 Suggests /map-feature instead
+MAP: 🎯 Suggests /map-efficient with risk context
83-83:⚠️ Potential issue | 🟡 Minor"50-60% tokens vs /map-feature" references an unimplemented workflow.
Under
/map-fasttrade-offs, the token savings comparison is against/map-featurewhich isn't implemented. Consider comparing against/map-efficientinstead, which is the recommended baseline.Proposed fix
-- Saves 50-60% tokens vs /map-feature +- Saves 40-50% tokens vs /map-efficientsrc/mapify_cli/templates/map/scripts/map_orchestrator.py (1)
370-384:⚠️ Potential issue | 🟠 Major
completed_stepsreset on subtask transition makes the circuit breaker ineffective.At line 382,
completed_stepsis reset to[]when advancing to the next subtask. However,check_circuit_breaker(line 671) computesmax_iterations = len(subtask_sequence) * len(STEP_ORDER)(e.g., 3 subtasks × 16 steps = 48), whiletool_countcan never exceed ~16 (one subtask's worth of steps) because it's reset each time.The breaker will never trigger during normal multi-subtask execution. Either accumulate
completed_stepsacross subtasks, or scopemax_iterationsto a single subtask:- max_iterations = len(state.subtask_sequence) * len(STEP_ORDER) + max_iterations = len(STEP_ORDER) # per-subtask threshold
🤖 Fix all issues with AI agents
In @.claude/commands/map-efficient.md:
- Around line 164-165: Add a fenced code block language specifier for the
snippet that starts with AskUserQuestion(questions=[) so the markdown linter
MD040 stops flagging it; locate the block containing AskUserQuestion and prepend
a fence like ```python and ensure the closing ``` exists after the code block so
the snippet is properly marked as Python (reference the
AskUserQuestion(questions=[) token to find the exact location).
In @.claude/skills/map-cli-reference/scripts/check-command.sh:
- Around line 104-109: Update the help text for the mapify init command so the
--mcp option reflects the real CLI values (all|essential|docs|none and
comma-separated lists) instead of showing "essential|full"; specifically edit
the echo lines that print "Usage: mapify init [project-name] [--mcp
essential|full] [--force]" and the subsequent "--mcp ..." option descriptions in
.claude/skills/map-cli-reference/scripts/check-command.sh and make the identical
change in
src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh, then
run make sync-templates to propagate the .claude change to the template; ensure
the help text mentions comma-separated lists support (e.g., " --mcp
all|essential|docs|none Comma-separated list of MCP groups").
In @.claude/skills/map-planning/scripts/get-plan-path.sh:
- Around line 31-37: The sed sanitization leaves leading dots and double-dots
which can enable path traversal; after computing SANITIZED_BRANCH from BRANCH,
add an explicit check that if SANITIZED_BRANCH contains ".." or starts with "."
then set SANITIZED_BRANCH to the safe fallback (same fallback used already, e.g.
"main"). Update the post-sanitization block that currently handles empty string
to also handle these path-traversal conditions, referencing the SANITIZED_BRANCH
and BRANCH variables.
In @.claude/skills/map-planning/scripts/init-session.sh:
- Around line 30-34: After sanitizing into SANITIZED_BRANCH in init-session.sh,
add the same safety checks used by sanitize_branch_name: if SANITIZED_BRANCH is
equal to "." or ".." or begins with a leading dot (i.e., starts with "."), treat
it as invalid and set SANITIZED_BRANCH to "main" (or otherwise canonical
default) so you never end up with a current/parent directory name; implement
this as a simple conditional check immediately after the existing sanitization
so the variable mirrors the Python sanitize_branch_name behavior.
In @.claude/skills/map-planning/SKILL.md:
- Around line 43-54: The Markdown code fence that shows the directory layout
(the block starting with ".map/") must include a language identifier to avoid
MD040; update the triple-backtick opening for that fenced block to be ```text
(i.e., add "text" immediately after the backticks) in the SKILL.md snippet so
the block becomes a ```text fenced code block.
In @.claude/skills/map-workflows-guide/scripts/validate-workflow-choice.py:
- Around line 84-110: The validate function currently only checks
rules["forbidden_types"] and misses rules["allowed_types"], so task types that
are neither forbidden nor allowed are treated as valid; update validate (the
function using WORKFLOW_RULES, e.g., where rules = WORKFLOW_RULES[workflow]) to
also check if task_type is in rules["allowed_types"] and if not append an issue
like f"Task type '{task_type}' is not allowed for {workflow}"; keep the existing
forbidden_types check (so forbidden still reports as such), and ensure the
returned issues/recommendation logic (including RISK_OVERRIDES lookup) remains
unchanged.
In @.claude/skills/map-workflows-guide/SKILL.md:
- Around line 525-526: Update the guidance that currently recommends
"/map-feature" on the row describing Predictor behavior: do not instruct users
to use "/map-feature" since it's marked planned; instead either direct them to
"/map-efficient" (noting its conditional/ risk context) or explicitly label
"/map-feature" as "planned" in this table entry so users are not directed to an
unimplemented route; modify the table cell that mentions "/map-feature"
accordingly (referencing the strings "/map-feature", "/map-efficient", and
"/map-fast" to locate the entry).
- Around line 3-15: The update was made to
.claude/skills/map-workflows-guide/SKILL.md but the matching template copy under
src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md was not updated;
sync the change by copying the new .claude/skills/map-workflows-guide/SKILL.md
content into the corresponding template file (or run make sync-templates /
scripts/sync-templates.sh) so both files match before merging.
In `@docs/USAGE.md`:
- Around line 712-715: The fenced code block in USAGE.md that currently contains
the lines ".map/progress.md - Workflow state (YAML frontmatter +
markdown" and ".map/*/task_plan_*.md - Task decomposition with validation
criteria" should include a language identifier to satisfy markdownlint MD040;
update the opening fence from ``` to ```text so the block becomes ```text and
keep the content unchanged, which will silence the warning and preserve
readability.
In `@presentation/ru/04-начало-работы.md`:
- Around line 226-231: The tutorial incorrectly references the branch-scoped
progress file as `.map/<branch>/progress.md`; update that string to match the
rest of the PR by changing `.map/<branch>/progress.md` to
`.map/progress_<branch>.md` (i.e., replace the path literal in the Markdown at
the line that currently shows `.map/<branch>/progress.md` so users are pointed
to `progress_<branch>.md`).
In `@src/mapify_cli/__init__.py`:
- Around line 1196-1231: The global default_permissions dictionary (variable
default_permissions in src/mapify_cli/__init__.py) is advertised as "read-only"
but includes the mutating entry "Bash(chmod +x *)"; remove that entry from the
global allowlist so the global default remains read-only, or alternatively
relocate it into project-specific configuration (e.g., settings.local.json) if
some projects require it; update any accompanying comment/output text that
describes the global permissions to reflect the change.
In `@src/mapify_cli/templates/agents/final-verifier.md`:
- Around line 21-31: Update the mirrored template in
.claude/agents/final-verifier.md to match the changes made in
src/mapify_cli/templates/agents/final-verifier.md: replicate the branch-scoped
path references (e.g., use `.map/<branch>/task_plan_<branch>.md`,
`.map/<branch>/progress_<branch>.md`, `.map/<branch>/final_verification.json`)
and the OUTPUT Destinations table entries so the **final-verifier** agent
behavior is identical; ensure the "Verification Result" and "Structured Result"
destinations, formats, and "Written By" values match exactly, and follow the
repo guideline to keep .claude/agents/ in sync with
src/mapify_cli/templates/agents/.
In `@src/mapify_cli/templates/map/scripts/map_orchestrator.py`:
- Around line 670-676: The circuit breaker fires when state.subtask_sequence is
empty because max_iterations becomes 0, so change the logic in the block that
computes tool_count/max_iterations/triggered (using symbols tool_count,
max_iterations, triggered, state.subtask_sequence, set_subtasks, STEP_ORDER) so
max_iterations is not zero during init: either compute max_iterations = max(1,
len(state.subtask_sequence) * len(STEP_ORDER)) or keep the computed value but
set triggered = False when len(state.subtask_sequence) == 0 (i.e., only allow
triggered evaluation once set_subtasks has populated state.subtask_sequence);
update the triggered expression accordingly to prevent firing during
initialization.
In `@src/mapify_cli/templates/map/scripts/map_step_runner.py`:
- Around line 138-148: The regex in update_plan_status is too restrictive (uses
\w+ and requires a leading "- ") so it misses statuses like "won't_do" or
templates without the dash; update the pattern to allow an optional leading
"-\s*" before "**Status:**" and capture any non-newline sequence for the status
(e.g. use a group like ([^\r\n]+) instead of \w+), then update the replacement
to reference the captured prefix group (the existing RF group 1) and set the
new_status; modify the variables pattern and replacement where pattern and
replacement are defined (they reference subtask_id and new_status) so
update_plan_status will correctly match and replace statuses with punctuation
and underscores.
In `@src/mapify_cli/templates/skills/map-planning/scripts/get-plan-path.sh`:
- Around line 31-37: The sed sanitization for SANITIZED_BRANCH doesn't enforce
the Python guards against values containing ".." or starting with ".", so after
the existing sed pipeline that produces SANITIZED_BRANCH from BRANCH, add
checks: if SANITIZED_BRANCH contains the substring ".." or begins with a dot,
set SANITIZED_BRANCH to the Python fallback ("default"); retain the existing
empty-string fallback behavior. Reference SANITIZED_BRANCH and the current sed
pipeline that derives it from BRANCH when making the changes.
In `@src/mapify_cli/templates/skills/map-planning/scripts/init-session.sh`:
- Around line 25-34: The script sets BRANCH and SANITIZED_BRANCH fallback to
"main" which is inconsistent with get_branch_name()'s default "default" and can
cause mismatched paths; change the fallback values used in BRANCH and
SANITIZED_BRANCH to "default" (update the lines that set BRANCH=$(git ... ||
echo 'main') and the subsequent BRANCH="main" and SANITIZED_BRANCH="main") so
that when git isn't available or sanitization yields empty the script uses
"default" to match get_branch_name().
In `@src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md`:
- Around line 522-528: The doc references a non-existent `/map-feature`
workflow; update the two table cells that mention `/map-feature` (the "Predictor
never runs in /map-efficient" row and the "No patterns stored after /map-fast"
row) to remove `/map-feature` and instead reference implemented workflows—e.g.,
change "Use /map-feature if you need guaranteed analysis" to "Use /map-efficient
if you need guaranteed analysis" and change "use /map-efficient or /map-feature
for pattern accumulation" to "use /map-efficient for pattern accumulation" so
all workflow names in SKILL.md match implemented commands.
🧹 Nitpick comments (28)
src/mapify_cli/templates/agents/reflector.md (1)
6-6: Ensure.claude/template sync after this change.Since this change modifies a user-shipped template, please copy the update to the matching path under
.claude/agents/(or runmake sync-templates) and verify the template sync test as required. As per coding guidelines: “If you change anything under.claude/that is shipped to users, you MUST copy it to the matching path undersrc/mapify_cli/templates/…” and “Runpytest tests/test_template_sync.py -vto enforce agent template sync verification.”Also applies to: 211-216
src/mapify_cli/templates/commands/map-debug.md (2)
130-133: Sync.claude/commands/map-debug.mdwith this template change.This file is under
src/mapify_cli/templates/**, so any change here must be mirrored to the matching.claude/commands/path before finishing (or verified viamake sync-templates/git diff).
As per coding guidelines: “Keep.claude/configuration in sync withsrc/mapify_cli/templates/by syncing common paths:.claude/commands/→src/mapify_cli/templates/commands/…”.
130-133: Consider updating README/USAGE/ARCHITECTURE for the new retry cap.The max 5 Actor→Monitor retry limit is user-facing behavior; per project learnings, this should be reflected in
README.md,docs/USAGE.md, anddocs/ARCHITECTURE.mdif they describe the debugging workflow.
Based on learnings: “When changing user-facing behavior, update relevant documentation files:README.md,docs/USAGE.md,docs/ARCHITECTURE.md.”scripts/lint-agent-templates.py (1)
154-164:_common_varsis defined but never used.The list at lines 154–164 isn't referenced anywhere in the code. The comment above it suggests the intent was to validate variable names against common standards, but the check is missing—the variable tracking at line 174 records all encountered variables unconditionally without comparison to
_common_vars. Either implement the validation check, remove the unused list, or add a comment clarifying the intent if it's documentary.src/mapify_cli/templates/commands/map-resume.md (1)
153-153: Optional: Simplify wording.The phrase "exact same" could be shortened to just "same" for conciseness.
✍️ Proposed wording simplification
-For each step, route to the appropriate executor based on `$PHASE` (ACTOR, MONITOR, PREDICTOR, TESTS_GATE, etc.) following the exact same phase handlers documented in map-efficient.md. +For each step, route to the appropriate executor based on `$PHASE` (ACTOR, MONITOR, PREDICTOR, TESTS_GATE, etc.) following the same phase handlers documented in map-efficient.md.src/mapify_cli/templates/skills/map-workflows-guide/resources/map-refactor-deep-dive.md (1)
3-5: Good addition of the status banner.Clear deprecation/redirect notice. One minor observation: since
/map-refactorhas been renamed to/map-fastin this PR (per the README, line 50), consider updating the document title on line 1 from/map-refactor Deep Diveto/map-fast Deep Dive(or add a note about the rename) to avoid confusion for readers who land here.README.md (1)
37-39: Add language identifiers to fenced code blocks.Static analysis flags these code blocks as missing language specifiers (MD040). Since these represent interactive prompts/text output, adding
```textwould satisfy the linter.Also applies to lines 58-66.
🔧 Proposed fix
-``` +```text /map-efficient implement user authentication with JWT tokens```diff -``` +```text TaskDecomposer → breaks goal into subtasks ↓ Actor → generates code ↓ Monitor → validates quality (loop if needed) ↓ Predictor → analyzes impact (for risky changes)</details> </blockquote></details> <details> <summary>src/mapify_cli/templates/hooks/workflow-gate.py (1)</summary><blockquote> `57-64`: **Hook files are synced correctly.** `.claude/hooks/workflow-gate.py` and `src/mapify_cli/templates/hooks/workflow-gate.py` are identical. Consider extracting `sanitize_branch_name` to a shared utilities module—the same implementation is duplicated across five hook files (workflow-gate.py, workflow-context-injector.py, ralph-iteration-logger.py, ralph-context-pruner.py, post-edit-reminder.py) and should be centralized to reduce maintenance burden. </blockquote></details> <details> <summary>src/mapify_cli/templates/hooks/workflow-context-injector.py (1)</summary><blockquote> `77-84`: **Identical `sanitize_branch_name` is copy-pasted across 7+ files.** This exact function appears in `workflow-gate.py`, `post-edit-reminder.py`, `ralph-iteration-logger.py`, `ralph-context-pruner.py`, `diagnostics.py`, and their template counterparts. Since these are standalone hook scripts deployed independently, sharing code is harder, but consider extracting it to a small shared utility (e.g., `.map/scripts/branch_utils.py`) that hooks can import, to keep a single source of truth. </blockquote></details> <details> <summary>.map/scripts/diagnostics.py (1)</summary><blockquote> `39-45`: **Sanitization logic is inlined here but extracted as `sanitize_branch_name()` everywhere else.** Every other file in this PR extracts the branch sanitization into a named `sanitize_branch_name()` function. This file inlines it directly in `get_branch_name()`. For consistency and testability, consider extracting it to match the pattern used elsewhere. <details> <summary>♻️ Proposed refactor to extract helper</summary> ```diff +def sanitize_branch_name(branch: str) -> str: + """Sanitize branch name for safe filesystem paths.""" + sanitized = branch.replace("/", "-") + sanitized = re.sub(r"[^a-zA-Z0-9_.-]", "-", sanitized) + sanitized = re.sub(r"-+", "-", sanitized).strip("-") + if ".." in sanitized or sanitized.startswith("."): + return "default" + return sanitized or "default" + + def get_branch_name() -> str: try: result = subprocess.run( ["git", "rev-parse", "--abbrev-ref", "HEAD"], capture_output=True, text=True, timeout=2, check=False, ) if result.returncode == 0: - branch = result.stdout.strip() - sanitized = branch.replace("/", "-") - sanitized = re.sub(r"[^a-zA-Z0-9_.-]", "-", sanitized) - sanitized = re.sub(r"-+", "-", sanitized).strip("-") - if ".." in sanitized or sanitized.startswith("."): - return "default" - return sanitized or "default" + return sanitize_branch_name(result.stdout.strip()) except Exception: pass return "default"src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh (1)
38-59: Unquoted variable expansion for list iteration is fragile but functional here.Using
for dep in $DEPRECATED_COMMANDSrelies on word-splitting, which works for these simple single-word values but would break on entries containing spaces or glob characters. Since the values are controlled constants, this is acceptable — just noting for awareness if the lists grow.src/mapify_cli/templates/references/step-state-schema.md (1)
68-73: Step numbering gap: 2.4 → 2.6 (no 2.5).The removal of RETRY_LOOP leaves a gap in the step IDs. Since these IDs are persisted in
step_state.jsonand consumed by hooks/orchestrator, renumbering could be a breaking change — so the gap is understandable. Consider adding a brief note (e.g., "2.5 reserved/removed") to prevent confusion for future readers..claude/hooks/workflow-context-injector.py (1)
77-84: Extractsanitize_branch_nameinto a shared utility module to eliminate duplication across 5 hook files.This function is duplicated in
workflow-context-injector.py,workflow-gate.py,ralph-iteration-logger.py,ralph-context-pruner.py, andpost-edit-reminder.py. Create a shared utility (e.g.,.claude/hooks/_shared.py) and import it in all five files. Since these files are synced tosrc/mapify_cli/templates/hooks/per the coding guidelines, ensure the shared utility is also created in both locations..claude/skills/map-cli-reference/scripts/check-command.sh (1)
75-79: Nit: "fuzzy match" comment is misleading — this just lists all commands.The comment says "Simple fuzzy match" but the code just iterates all valid commands without any actual fuzzy matching (e.g., edit distance). Consider updating the comment to "Suggest available commands" or similar.
.map/scripts/map_step_runner.py (1)
35-56:get_branch_namespawns a subprocess on every call — consider caching.Each function call (e.g.,
update_plan_status,validate_checkpoint,get_plan_path) that omits thebranchargument triggers a separategit rev-parsesubprocess. In a hot path where multiple functions are called sequentially, this results in redundant subprocess spawns.Consider caching the result with
functools.lru_cacheor a module-level variable.Example using lru_cache
+import functools + +@functools.lru_cache(maxsize=1) def get_branch_name() -> str: """Get sanitized git branch name.""".map/scripts/map_orchestrator.py (3)
142-150:always_requiredflag is defined but never consulted during validation.The
EVIDENCE_REQUIREDmapping defines analways_requiredboolean per step, butvalidate_step(Line 447) checks evidence for any step in this dict without inspecting the flag. The predictor (2.6,always_required=False) will be evidence-gated exactly like actor/monitor whenevervalidate_step("2.6", ...)is called.In practice, since 2.6 can be skipped via
skip_step, the flag is effectively dead. Either remove the tuple's second element (simplify to justphase_name), or add a guard invalidate_stepthat respects it.Option A: Simplify to just phase name
-EVIDENCE_REQUIRED = { - "2.3": ("actor", True), # Always required - "2.4": ("monitor", True), # Always required - "2.6": ("predictor", False), # Only when 2.6 is in pending_steps -} +EVIDENCE_REQUIRED = { + "2.3": "actor", # Always required + "2.4": "monitor", # Always required + "2.6": "predictor", # Only reached if not skipped via skip_step +}And update the destructuring at Line 448:
- phase_name, always_required = EVIDENCE_REQUIRED[step_id] + phase_name = EVIDENCE_REQUIRED[step_id]
230-251:import reis done inside two functions instead of at module level.
reis imported locally inget_branch_name(Line 241) and again inresume_from_plan(Line 735). Sincereis a stdlib module used in multiple places, move it to the top-level imports alongsidejson,subprocess, etc.Move `re` to module-level imports
import argparse import json +import re import subprocess import sysThen remove the local
import reat Lines 241 and 735.Also applies to: 735-736
655-679: Circuit breakermax_iterationsis inflated — init steps count once, not per-subtask.
max_iterations = len(state.subtask_sequence) * len(STEP_ORDER)multiplies all steps (including one-time init steps 1.0–1.6) by the subtask count. For 3 subtasks and 15 total steps, this yields 45, but the realistic ceiling is ~5 (init) + 3×10 (per-subtask) = 35.Since this is a safety mechanism, being generous is the safer direction — but it means the circuit breaker may never trigger in practice. Consider using the per-subtask step count instead:
More accurate max_iterations
tool_count = len(state.completed_steps) - max_iterations = len(state.subtask_sequence) * len(STEP_ORDER) + # Init steps (1.x) run once; per-subtask steps (2.x) run N times + init_steps = sum(1 for s in STEP_ORDER if s.startswith("1.")) + per_subtask_steps = len(STEP_ORDER) - init_steps + max_iterations = init_steps + len(state.subtask_sequence) * per_subtask_steps.claude/commands/map-efficient.md (1)
541-555: Pseudocode conditions referencecheck_circuit_breaker()— clarify this is not executable.Lines 541–543 add a NOTE explaining these are pseudocode, which is helpful. However, Line 549 uses
check_circuit_breaker()["triggered"] == falsewhich mixes Python-like dict access with JavaScript-likefalse. Since the NOTE already says "pseudocode," this is minor, but usingFalse(Python) would be more consistent with the rest of the file.Use Python-style boolean
-elif check_circuit_breaker()["triggered"] == false: +elif check_circuit_breaker()["triggered"] == False:src/mapify_cli/templates/agents/predictor.md (1)
1787-1802: Ensure evidence directory exists before write.If
.map/<branch>/evidence/isn’t created yet, thecat >will fail andvalidate_step("2.6")will reject the step. Adding amkdir -pmakes the instruction robust.Suggested fix
```bash +mkdir -p .map/<branch>/evidence cat > .map/<branch>/evidence/predictor_<subtask_id>.json << 'EVIDENCE' {src/mapify_cli/templates/agents/monitor.md (1)
2499-2516: Harden evidence-file instructions and avoid drift.
- Add
mkdir -pso the evidence write doesn’t fail when the directory is missing.- Consider consolidating the evidence guidance into a single canonical block to prevent future divergence.
Suggested fix (mkdir)
```bash +mkdir -p .map/<branch>/evidence cat > .map/<branch>/evidence/monitor_<subtask_id>.json << 'EVIDENCE' {docs/ARCHITECTURE.md (1)
732-738: Step numbering gap: 2.4 jumps to 2.6 (no 2.5).The step phases skip from
2.4 MONITORto2.6 PREDICTOR. While this may be intentional (removing the old RETRY_LOOP step), it creates a non-sequential numbering that could confuse readers. Consider adding a brief note explaining the gap, or renumbering for continuity..claude/commands/map-plan.md (1)
96-119: Fenced code block missing language specifier.The code block at line 96 should have a language specified for consistency with the rest of the file and to satisfy markdown linting.
Proposed fix
-``` +```json AskUserQuestion(questions=[src/mapify_cli/templates/commands/map-efficient.md (1)
162-177: Fenced code block missing language specifier (line 164).The code block starting at line 164 for the
AskUserQuestionexample should have a language identifier.Proposed fix
-``` +```json AskUserQuestion(questions=[tests/test_skills.py (2)
262-276:import osshould be at module level.The
osmodule is imported inside the loop body at line 272. Move it to the top of the file with the other imports to follow Python conventions.Proposed fix
At the top of the file (after line 16):
+import osThen at line 272:
if script.suffix == ".sh": - import os assert os.access(script, os.X_OK), (
55-64: Frontmatter parser edge case: YAML containing---.
_parse_frontmatterusescontent.find("---", 3)to locate the closing delimiter. If the YAML content itself contains a line starting with---(e.g., a YAML document separator), this would prematurely truncate the frontmatter. In practice this is unlikely for skill files, but worth noting.src/mapify_cli/templates/map/scripts/map_orchestrator.py (2)
142-151:always_requiredflag is extracted but never used invalidate_step.At line 448,
always_requiredis unpacked fromEVIDENCE_REQUIRED[step_id]but the value is never read. The evidence check runs unconditionally for any step present inEVIDENCE_REQUIRED, making the boolean meaningless. If the intent is to skip evidence validation when a conditional step (e.g., 2.6) wasn't truly executed, this logic is missing.If the flag is genuinely unnecessary (because
validate_stepis only called for non-skipped steps), simplifyEVIDENCE_REQUIREDto just mapstep_id → phase_nameto avoid confusion.Option A: Use the flag
if step_id in EVIDENCE_REQUIRED: phase_name, always_required = EVIDENCE_REQUIRED[step_id] + # Skip evidence check for conditional steps that were skipped + if not always_required and step_id not in state.pending_steps and step_id not in [state.current_step_id]: + pass # no evidence needed for skipped conditional step + else: evidence_dir = Path(f".map/{branch}/evidence")Option B: Drop the unused flag
-# Format: step_id -> (agent_phase, always_required) -# If always_required is False, evidence is only checked when the step -# appears in pending_steps (i.e., it wasn't skipped). -EVIDENCE_REQUIRED = { - "2.3": ("actor", True), # Always required - "2.4": ("monitor", True), # Always required - "2.6": ("predictor", False), # Only when 2.6 is in pending_steps -} +# Steps that require evidence files from agents before validation. +# Format: step_id -> agent_phase +EVIDENCE_REQUIRED = { + "2.3": "actor", + "2.4": "monitor", + "2.6": "predictor", +}Also applies to: 446-468
735-735: Moveimport reto the top-level imports.
reis imported locally inside bothresume_from_plan(line 735) andget_branch_name(line 241). Consolidate to a single top-level import for clarity.import argparse import json +import re import subprocess import sys
| ``` | ||
| AskUserQuestionTool(questions=[ | ||
| AskUserQuestion(questions=[ |
There was a problem hiding this comment.
Fenced code block missing language specifier.
Static analysis (MD040) flags this code block as lacking a language identifier.
Add language specifier
-```
-AskUserQuestion(questions=[
+```python
+AskUserQuestion(questions=[🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 164-164: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.claude/commands/map-efficient.md around lines 164 - 165, Add a fenced code
block language specifier for the snippet that starts with
AskUserQuestion(questions=[) so the markdown linter MD040 stops flagging it;
locate the block containing AskUserQuestion and prepend a fence like ```python
and ensure the closing ``` exists after the code block so the snippet is
properly marked as Python (reference the AskUserQuestion(questions=[) token to
find the exact location).
| echo "Usage: mapify init [project-name] [--mcp essential|full] [--force]" | ||
| echo "" | ||
| echo "Options:" | ||
| echo " --mcp essential Install essential MCP tools only" | ||
| echo " --mcp full Install all MCP tools" | ||
| echo " --force Overwrite existing configuration" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find the actual mapify init implementation to see what --mcp options are accepted
find . -name "__init__.py" -path "*/mapify_cli/*" | head -5Repository: azalio/map-framework
Length of output: 127
🏁 Script executed:
# Search for --mcp option definitions
rg -n '\-\-mcp|mcp.*choices|add_argument.*mcp' --type py -C 3Repository: azalio/map-framework
Length of output: 9295
🏁 Script executed:
# Check if there's a corresponding template file for this skill script
find . -path "*/templates/skills/*" -name "check-command.sh" -o -path "*/templates/skills/*" -type f | head -20Repository: azalio/map-framework
Length of output: 1547
🏁 Script executed:
# List the skills directory structure to understand template mapping
ls -la src/mapify_cli/templates/skills/ 2>/dev/null || echo "Directory not found"Repository: azalio/map-framework
Length of output: 498
🏁 Script executed:
cat -n src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh | sed -n '100,115p'Repository: azalio/map-framework
Length of output: 598
Update --mcp option documentation to match actual CLI behavior in both .claude/ and templates/ locations.
The help text shows --mcp essential|full, but the actual mapify init CLI accepts --mcp all|essential|docs|none plus comma-separated lists. "full" is not a valid option. Both .claude/skills/map-cli-reference/scripts/check-command.sh and the corresponding template at src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh need the same fix. After updating the .claude/ version, ensure the template is synced via make sync-templates.
Proposed fix (apply to both files)
- echo "Usage: mapify init [project-name] [--mcp essential|full] [--force]"
+ echo "Usage: mapify init [project-name] [--mcp all|essential|docs|none] [--force]"
echo ""
echo "Options:"
- echo " --mcp essential Install essential MCP tools only"
- echo " --mcp full Install all MCP tools"
+ echo " --mcp all Install all MCP tools (default)"
+ echo " --mcp essential Install essential MCP tools only"
+ echo " --mcp docs Install documentation MCP tools"
+ echo " --mcp none Skip MCP tool installation"
echo " --force Overwrite existing configuration"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| echo "Usage: mapify init [project-name] [--mcp essential|full] [--force]" | |
| echo "" | |
| echo "Options:" | |
| echo " --mcp essential Install essential MCP tools only" | |
| echo " --mcp full Install all MCP tools" | |
| echo " --force Overwrite existing configuration" | |
| echo "Usage: mapify init [project-name] [--mcp all|essential|docs|none] [--force]" | |
| echo "" | |
| echo "Options:" | |
| echo " --mcp all Install all MCP tools (default)" | |
| echo " --mcp essential Install essential MCP tools only" | |
| echo " --mcp docs Install documentation MCP tools" | |
| echo " --mcp none Skip MCP tool installation" | |
| echo " --force Overwrite existing configuration" |
🤖 Prompt for AI Agents
In @.claude/skills/map-cli-reference/scripts/check-command.sh around lines 104 -
109, Update the help text for the mapify init command so the --mcp option
reflects the real CLI values (all|essential|docs|none and comma-separated lists)
instead of showing "essential|full"; specifically edit the echo lines that print
"Usage: mapify init [project-name] [--mcp essential|full] [--force]" and the
subsequent "--mcp ..." option descriptions in
.claude/skills/map-cli-reference/scripts/check-command.sh and make the identical
change in
src/mapify_cli/templates/skills/map-cli-reference/scripts/check-command.sh, then
run make sync-templates to propagate the .claude change to the template; ensure
the help text mentions comma-separated lists support (e.g., " --mcp
all|essential|docs|none Comma-separated list of MCP groups").
| # Sanitize branch name for filesystem safety (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
|
|
||
| # Output the plan file path | ||
| echo ".map/task_plan_${SANITIZED_BRANCH}.md" | ||
| # Fallback if sanitization produced empty string | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi |
There was a problem hiding this comment.
Missing path-traversal protection that the Python sanitize_branch_name includes.
The sed-based sanitization allows . through (it's in the allowed character class [a-zA-Z0-9_.-]), so a branch name like ..foo would produce ..foo, and .hidden would pass through unchanged. The Python counterpart explicitly guards against this:
if ".." in sanitized or sanitized.startswith("."):
return "default"Add equivalent checks in the shell script to prevent path traversal via crafted branch names.
🔒 Proposed fix to add path traversal checks
# Sanitize branch name for filesystem safety (matches MAP orchestrator convention)
SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
# Fallback if sanitization produced empty string
if [ -z "$SANITIZED_BRANCH" ]; then
SANITIZED_BRANCH="main"
fi
+# Prevent path traversal (matches Python sanitize_branch_name)
+if [[ "$SANITIZED_BRANCH" == *".."* ]] || [[ "$SANITIZED_BRANCH" == .* ]]; then
+ SANITIZED_BRANCH="main"
+fi
+
# Output the plan file path (nested directory convention)
echo ".map/${SANITIZED_BRANCH}/task_plan_${SANITIZED_BRANCH}.md"🤖 Prompt for AI Agents
In @.claude/skills/map-planning/scripts/get-plan-path.sh around lines 31 - 37,
The sed sanitization leaves leading dots and double-dots which can enable path
traversal; after computing SANITIZED_BRANCH from BRANCH, add an explicit check
that if SANITIZED_BRANCH contains ".." or starts with "." then set
SANITIZED_BRANCH to the safe fallback (same fallback used already, e.g. "main").
Update the post-sanitization block that currently handles empty string to also
handle these path-traversal conditions, referencing the SANITIZED_BRANCH and
BRANCH variables.
| # Sanitize branch name (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi |
There was a problem hiding this comment.
Same missing ../leading-. safety check as flagged in get-plan-path.sh.
Apply the same fix here to keep the shell sanitization consistent with the Python sanitize_branch_name.
🛡️ Proposed fix
SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
-if [ -z "$SANITIZED_BRANCH" ]; then
+if [ -z "$SANITIZED_BRANCH" ] || echo "$SANITIZED_BRANCH" | grep -qE '^\.|\.\.'; then
SANITIZED_BRANCH="main"
fi📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Sanitize branch name (matches MAP orchestrator convention) | |
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | |
| if [ -z "$SANITIZED_BRANCH" ]; then | |
| SANITIZED_BRANCH="main" | |
| fi | |
| # Sanitize branch name (matches MAP orchestrator convention) | |
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | |
| if [ -z "$SANITIZED_BRANCH" ] || echo "$SANITIZED_BRANCH" | grep -qE '^\.|\.\.'; then | |
| SANITIZED_BRANCH="main" | |
| fi |
🤖 Prompt for AI Agents
In @.claude/skills/map-planning/scripts/init-session.sh around lines 30 - 34,
After sanitizing into SANITIZED_BRANCH in init-session.sh, add the same safety
checks used by sanitize_branch_name: if SANITIZED_BRANCH is equal to "." or ".."
or begins with a leading dot (i.e., starts with "."), treat it as invalid and
set SANITIZED_BRANCH to "main" (or otherwise canonical default) so you never end
up with a current/parent directory name; implement this as a simple conditional
check immediately after the existing sanitization so the variable mirrors the
Python sanitize_branch_name behavior.
| All files reside in `.map/<branch>/` directory with branch-based naming: | ||
|
|
||
| ``` | ||
| .map/ | ||
| ├── task_plan_<branch>.md # Primary plan with phases and status | ||
| ├── findings_<branch>.md # Research findings, decisions, key files | ||
| └── progress_<branch>.md # Action log, errors, test results | ||
| └── <branch>/ | ||
| ├── task_plan_<branch>.md # Primary plan with phases and status | ||
| ├── findings_<branch>.md # Research findings, decisions, key files | ||
| ├── progress_<branch>.md # Action log, errors, test results | ||
| ├── workflow_state.json # Subtask completion tracking | ||
| ├── step_state.json # Orchestrator step state | ||
| └── evidence/ # Artifact-gated validation evidence | ||
| ``` |
There was a problem hiding this comment.
Add a language identifier to the file-structure fence.
This avoids MD040 warnings and improves readability.
Suggested fix
-```
+```text
.map/
└── <branch>/🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.claude/skills/map-planning/SKILL.md around lines 43 - 54, The Markdown code
fence that shows the directory layout (the block starting with ".map/") must
include a language identifier to avoid MD040; update the triple-backtick opening
for that fenced block to be ```text (i.e., add "text" immediately after the
backticks) in the SKILL.md snippet so the block becomes a ```text fenced code
block.
| tool_count = len(state.completed_steps) | ||
| max_iterations = len(state.subtask_sequence) * len(STEP_ORDER) | ||
|
|
||
| return { | ||
| "tool_count": tool_count, | ||
| "max_iterations": max_iterations, | ||
| "triggered": tool_count >= max_iterations, |
There was a problem hiding this comment.
Circuit breaker triggers immediately when subtask_sequence is empty.
When subtask_sequence is empty (before set_subtasks is called during init phases), max_iterations computes to 0. Since 0 >= 0 is True, the circuit breaker fires unconditionally during the entire initialization phase, and also fires if there's a single completed step.
Proposed fix
tool_count = len(state.completed_steps)
max_iterations = len(state.subtask_sequence) * len(STEP_ORDER)
+ # Guard against empty subtask sequence (init phases)
+ if max_iterations == 0:
+ return {
+ "tool_count": tool_count,
+ "max_iterations": 0,
+ "triggered": False,
+ "retry_count": state.retry_count,
+ "max_retries": state.max_retries,
+ }
+
return {
"tool_count": tool_count,
"max_iterations": max_iterations,
"triggered": tool_count >= max_iterations,🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/map/scripts/map_orchestrator.py` around lines 670 -
676, The circuit breaker fires when state.subtask_sequence is empty because
max_iterations becomes 0, so change the logic in the block that computes
tool_count/max_iterations/triggered (using symbols tool_count, max_iterations,
triggered, state.subtask_sequence, set_subtasks, STEP_ORDER) so max_iterations
is not zero during init: either compute max_iterations = max(1,
len(state.subtask_sequence) * len(STEP_ORDER)) or keep the computed value but
set triggered = False when len(state.subtask_sequence) == 0 (i.e., only allow
triggered evaluation once set_subtasks has populated state.subtask_sequence);
update the triggered expression accordingly to prevent firing during
initialization.
| plan_file = Path(f".map/{branch}/task_plan_{branch}.md") | ||
|
|
||
| if not plan_file.exists(): | ||
| return {"status": "error", "message": f"Plan file not found: {plan_file}"} | ||
|
|
||
| try: | ||
| content = plan_file.read_text(encoding="utf-8") | ||
|
|
||
| # Find subtask section (## ST-XXX: Title) | ||
| pattern = rf"(## {re.escape(subtask_id)}:.*?\n\*\*Status:\*\*\s+)\w+" | ||
| # Find subtask section (### ST-XXX: Title) | ||
| pattern = rf"(### {re.escape(subtask_id)}:.*?\n- \*\*Status:\*\*\s+)\w+" | ||
| replacement = rf"\g<1>{new_status}" |
There was a problem hiding this comment.
Fix status regex to handle terminal states and optional dash.
The current pattern uses \w+, which won’t match statuses like won't_do, and it requires - **Status:** even though templates/docs often use **Status:** without a dash. This can cause update_plan_status to miss matches and return a warning even when the subtask exists.
Proposed fix
- pattern = rf"(### {re.escape(subtask_id)}:.*?\n- \*\*Status:\*\*\s+)\w+"
+ pattern = rf"(### {re.escape(subtask_id)}:.*?\n(?:- )?\*\*Status:\*\*\s+)[^\s]+"🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/map/scripts/map_step_runner.py` around lines 138 -
148, The regex in update_plan_status is too restrictive (uses \w+ and requires a
leading "- ") so it misses statuses like "won't_do" or templates without the
dash; update the pattern to allow an optional leading "-\s*" before
"**Status:**" and capture any non-newline sequence for the status (e.g. use a
group like ([^\r\n]+) instead of \w+), then update the replacement to reference
the captured prefix group (the existing RF group 1) and set the new_status;
modify the variables pattern and replacement where pattern and replacement are
defined (they reference subtask_id and new_status) so update_plan_status will
correctly match and replace statuses with punctuation and underscores.
| # Sanitize branch name for filesystem safety (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
|
|
||
| # Output the plan file path | ||
| echo ".map/task_plan_${SANITIZED_BRANCH}.md" | ||
| # Fallback if sanitization produced empty string | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi |
There was a problem hiding this comment.
Shell sanitization is missing the .. and leading-. safety checks present in Python.
The Python sanitize_branch_name falls back to "default" when the result contains ".." or starts with ".". The sed pipeline here doesn't replicate those guards, which could produce unsafe directory names (e.g., a branch named ...foo would sanitize to ...foo → ...foo since . is in the allowed set).
🛡️ Proposed fix
# Sanitize branch name for filesystem safety (matches MAP orchestrator convention)
SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
# Fallback if sanitization produced empty string
-if [ -z "$SANITIZED_BRANCH" ]; then
+if [ -z "$SANITIZED_BRANCH" ] || echo "$SANITIZED_BRANCH" | grep -qE '^\.|\.\.'; then
SANITIZED_BRANCH="main"
fi🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/skills/map-planning/scripts/get-plan-path.sh` around
lines 31 - 37, The sed sanitization for SANITIZED_BRANCH doesn't enforce the
Python guards against values containing ".." or starting with ".", so after the
existing sed pipeline that produces SANITIZED_BRANCH from BRANCH, add checks: if
SANITIZED_BRANCH contains the substring ".." or begins with a dot, set
SANITIZED_BRANCH to the Python fallback ("default"); retain the existing
empty-string fallback behavior. Reference SANITIZED_BRANCH and the current sed
pipeline that derives it from BRANCH when making the changes.
| BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'main') | ||
| if [ -z "$BRANCH" ]; then | ||
| BRANCH="main" | ||
| fi | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | tr '/' '-') | ||
|
|
||
| # Create .map directory | ||
| MAP_DIR=".map" | ||
| # Sanitize branch name (matches MAP orchestrator convention) | ||
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | ||
| if [ -z "$SANITIZED_BRANCH" ]; then | ||
| SANITIZED_BRANCH="main" | ||
| fi |
There was a problem hiding this comment.
Align fallback branch name with other workflow components.
get_branch_name() defaults to "default" while this script falls back to "main". If git isn’t available, this can create .map/main/… while other components look under .map/default/…, causing “file not found” errors.
Suggested fix
-BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'main')
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'default')
if [ -z "$BRANCH" ]; then
- BRANCH="main"
+ BRANCH="default"
fi
...
if [ -z "$SANITIZED_BRANCH" ]; then
- SANITIZED_BRANCH="main"
+ SANITIZED_BRANCH="default"
fi📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'main') | |
| if [ -z "$BRANCH" ]; then | |
| BRANCH="main" | |
| fi | |
| SANITIZED_BRANCH=$(echo "$BRANCH" | tr '/' '-') | |
| # Create .map directory | |
| MAP_DIR=".map" | |
| # Sanitize branch name (matches MAP orchestrator convention) | |
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | |
| if [ -z "$SANITIZED_BRANCH" ]; then | |
| SANITIZED_BRANCH="main" | |
| fi | |
| BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'default') | |
| if [ -z "$BRANCH" ]; then | |
| BRANCH="default" | |
| fi | |
| # Sanitize branch name (matches MAP orchestrator convention) | |
| SANITIZED_BRANCH=$(echo "$BRANCH" | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||') | |
| if [ -z "$SANITIZED_BRANCH" ]; then | |
| SANITIZED_BRANCH="default" | |
| fi |
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/skills/map-planning/scripts/init-session.sh` around
lines 25 - 34, The script sets BRANCH and SANITIZED_BRANCH fallback to "main"
which is inconsistent with get_branch_name()'s default "default" and can cause
mismatched paths; change the fallback values used in BRANCH and SANITIZED_BRANCH
to "default" (update the lines that set BRANCH=$(git ... || echo 'main') and the
subsequent BRANCH="main" and SANITIZED_BRANCH="main") so that when git isn't
available or sanitization yields empty the script uses "default" to match
get_branch_name().
… implemented workflows - entity_extractor.py: replace map-feature/map-refactor keyword mappings with all implemented workflows (map-efficient, map-fast, map-debate, map-review, map-plan, map-check, map-release) - agent-architecture.md: update Evaluator/Predictor/Reflector "When it runs" sections to reference only implemented workflows; replace "Full Pipeline (map-feature)" with "Multi-Variant Pipeline (map-debate)" - SKILL.md: fix troubleshooting table that recommended using /map-feature (doesn't exist); update suggestion example to use --self-moa flag - docs/ARCHITECTURE.md: fix "After Evaluator approves" to "After Monitor validates" in map-efficient custom agent example - docs/USAGE.md: replace /map-feature comparison example with /map-debate - test_entity_extractor.py: update test to use map-efficient instead of map-feature
Replace "/map-feature: ~12k tokens" with "Full pipeline: ~12k tokens" in the token usage comparison example.
…low-rules - map_orchestrator.py: fix "STEP PHASES (13 total)" to "(16 total)" matching actual 16 phases defined in STEP_PHASES dict - WORKFLOW_FLOW.md: fix "17 фаз" to "16 фаз" and "14 фаз" to "16 фаз" matching the actual phase table - workflow-rules.json: add map-debate as auto-suggested workflow with trigger keywords (debate, compare approaches, trade-offs, reasoning)
- Update agent count from 8 or 11 to 12 across README, ARCHITECTURE, USAGE, INSTALL, SKILL.md, agent-architecture.md, presentations (EN/RU) - Add missing agents (debate-arbiter, synthesizer, research-agent, final-verifier) to SKILL.md and agent-architecture.md descriptions - Add missing commands (map-check, map-plan, map-resume) to INSTALL.md and presentation architecture pages - Fix debate-arbiter.md last_updated from 2025-01-08 to 2026-02-14 - Sync all template copies
…d presentations - Fix plugin.json, marketplace.json, PLUGIN.md: 9 agents → 12 (remove phantom "Orchestrator" agent, add debate-arbiter, synthesizer, research-agent, final-verifier); 4 commands → 10 - Fix INSTALL.md: 11 agents → 12, 7 commands → 10 - Fix __init__.py tracker output: 8 agents → 12, 4 commands → 10 - Fix EN getting-started presentation: 8 agents → 12, 4 commands → 10, add missing agents and commands to directory tree
…pings - Remove non-existent "orchestrator" from agent_mcp_mappings config (orchestrator is coordination logic in commands, not an agent) - Add missing agents to mappings: debate-arbiter, synthesizer, research-agent, final-verifier - Replace "orchestrator" in sequential-thinking mapping with debate-arbiter (needs reasoning capability) - Replace "orchestrator" in claude-reviewer mapping with final-verifier (needs code review capability)
…ation - Remove Evaluator from map-efficient-deep-dive pipeline and example (map-efficient.md explicitly omits Evaluator by design) - Fix Quality Preservation section: Reflector/Curator are in /map-learn, not in map-efficient's per-subtask loop - Add Final-Verifier and Tests/Linter gates to example walkthrough - Fix agent-architecture.md: remove Evaluator from map-fast pipeline (map-fast only uses TaskDecomposer → Actor → Monitor) - Fix agent-architecture.md: add Final-Verifier to map-efficient pipeline - Fix Evaluator token table: remove "map-fast" (only in map-debug) - Update EN/RU workflow presentations: 4 commands → 10 commands, add all missing commands to lists and exception sections
- map-fast-deep-dive: Evaluator marked as skipped (was incorrectly "✅ Runs") - map-fast-deep-dive: Remove Evaluator from example pipeline (Actor→Monitor→Apply) - map-fast-deep-dive: Add Evaluator to "Agents NOT Called" section - agent-architecture: Evaluator runs in map-debug/map-review (was map-fast/map-debug) - agent-architecture: Add map-review to Evaluator token usage row - SKILL.md: Add Evaluator workflow scope (only map-debug, map-review) - SKILL.md: Fix workflow count "4 implemented" → "10 workflow commands" - SKILL.md: Remove false Evaluator claim from map-efficient Q&A section
- Clarify Reflector/Curator are NOT called during map-efficient (decoupled to /map-learn) - Fix "Evaluator Skipped" → "Evaluator Not Invoked" with correct workflow scope - Update "Batched Learning" misconception → "/map-learn" terminology - Fix "Full learning cycle" → "Learning available via /map-learn" - Add Tests gate, Linter gate, Final-Verifier to "What's Preserved" list - Fix entity graph extraction: "automatically" → "via /map-learn" - Fix cost mitigation: "Batched Reflector/Curator at end" → "via /map-learn"
…ptual - EN/RU presentations: "Automatic learning from every task" → learning via /map-learn - EN/RU workflow diagrams: "Mandatory sequence" → "Full pipeline (conceptual)" to avoid implying all agents run in every workflow
- Fix agent line counts in 02-architecture.md (EN/RU) to match actual files TaskDecomposer: 1169→867, Actor: 641→1084, Monitor: 908→2521, Predictor: 898→2108, Evaluator: 843→1492, Reflector: 1004→851, Curator: 1145→1296 - Add missing mem0 to MCP server lists (was "5 servers" but only listed 4) - Fix MCP tool name: context7__resolve_library_id → context7__resolve-library-id - RU 04-начало-работы: expand file tree from 8→12 agents, 4→10 commands - EN/RU getting-started: "4 core commands" → "10 commands (4 primary + 6 supporting)"
- Predictor/Evaluator: haiku → sonnet in presentations (EN/RU) and ARCHITECTURE.md model table (matches agent frontmatter) - Model Strategy section: all agents now sonnet except DebateArbiter (opus) - MCP tool naming: add mcp__ prefixes for consistency in ARCHITECTURE.md - INSTALL.md: add 4 missing workflow commands (map-check, map-plan, map-release, map-resume) — now lists all 10
Previously only 4 of 10 commands were documented. Now includes map-debate, map-check, map-plan, map-release, map-resume, map-learn.
- EN/RU 01-introduction: model strategy now shows all agents on sonnet, DebateArbiter on opus (no more haiku claims) - EN/RU 02-architecture: YAML frontmatter description "sonnet/haiku" → "sonnet/opus" to match actual agent configurations
- ARCHITECTURE.md: map-efficient pipeline now shows ResearchAgent (conditional), FinalVerifier (mandatory), and correct agent count 4-6 - USAGE.md: workflow comparison table agent count 5-6 → 4-6 with explicit agent list; introductory text mentions supporting workflows
map-debate conditionally invokes ResearchAgent after TaskDecomposer, matching the actual command file. Agent count updated to 5-7.
FinalVerifier was referenced in map-efficient pipeline sequence but had no dedicated documentation section. Now documented as agent #12 with input/output format, verification process, and usage context.
…alVerifier to diagrams - test_template_sync.py: expected_agents expanded from 8 to all 12 - test_command_templates.py: expected_commands expanded from 5 to all 10 - test_mapify_cli.py: docstring corrected (fallback covers 8, not 12) - EN/RU 03-workflow.md: mermaid diagram now includes FinalVerifier as step 8 and shows subtask loop back to Actor
…Arbiter, ResearchAgent, FinalVerifier) Presentations claimed 12 agents but only documented 8. Added sections 9-12 with model, purpose, and output for the missing agents. Updated model strategy to include all agents with correct model assignments.
… link - EN/RU presentations: Predictor MCP tools 3 → 4 (add sequential-thinking) - EN/RU presentations: template version "2.2.0" → generic "version, last_updated" (actual agent versions range from 2.4.0 to 4.0.0) - ARCHITECTURE.md: remove broken MCP-PATTERNS.md link (file doesn't exist), replace with reference to inline MCP Tool Selection Matrix in agent templates
There was a problem hiding this comment.
Actionable comments posted: 8
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (8)
.map/scripts/map_orchestrator.py (1)
370-384:⚠️ Potential issue | 🟡 MinorResetting
completed_stepsto[]discards cross-subtask history.When advancing to the next subtask, all prior completion records are wiped. This is fine if tracking is purely per-subtask, but it conflicts with
check_circuit_breakerwhich useslen(completed_steps)as a cumulative measure. If per-subtask reset is intentional, the circuit breaker needs a separate cumulative counter (as noted above).src/mapify_cli/templates/skills/README.md (2)
35-57:⚠️ Potential issue | 🟠 MajorSync templates back to .claude equivalents.
This templates file must stay mirrored with
.claude/skills/README.md(or runmake sync-templates) to keep shipped content consistent.As per coding guidelines: "Keep
.claude/configuration in sync withsrc/mapify_cli/templates/by syncing common paths..."
35-56:⚠️ Potential issue | 🟡 MinorWorkflow/resource counts look inconsistent.
The text says “4 implemented + 2 planned” and “8 deep-dive resource files,” but the list doesn’t mention the new
map-debatedeep dive and appears to enumerate fewer than 8 resources. Consider adding the missing resource or adjusting the counts.src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md (2)
432-548:⚠️ Potential issue | 🟡 MinorDuplicate "Examples" sections with overlapping content.
Lines 432–467 ("Real-World Examples") and lines 515–548 ("Examples") both present three numbered examples covering nearly identical scenarios (OAuth/critical feature →
/map-efficient, quick fix →/map-fast, test failure →/map-debug). This creates unnecessary redundancy and potential for the two sections to drift out of sync.Consider consolidating into a single section.
316-341:⚠️ Potential issue | 🟡 MinorDecision Flowchart omits
/map-debate, inconsistent with Quick Decision Tree.The Quick Decision Tree (line 34-35) introduces
/map-debateas the answer to question 3. However, the Decision Flowchart (lines 316-341) has only three branches (/map-fast,/map-debug,/map-efficient) and collapses everything else into/map-efficient. Users referencing the flowchart will miss/map-debateentirely.docs/ARCHITECTURE.md (2)
1086-1088:⚠️ Potential issue | 🟠 MajorSynthesizer "Usage Context" contradicts the rest of the documentation.
Line 1088 states Synthesizer is "Only invoked in
/map-debateworkflow after DebateArbiter completes cross-evaluation", but:
- The workflow variant section (line 351) places Synthesizer in
/map-efficientSelf-MoA.- The
/map-debateworkflow (lines 430-453) explicitly states DebateArbiter "Synthesizes unified solution directly (no separate Synthesizer agent)".- SKILL.md and agent-architecture.md both say Synthesizer is for
/map-efficient --self-moa.Proposed fix
-**Usage Context:** Only invoked in `/map-debate` workflow after DebateArbiter completes cross-evaluation +**Usage Context:** Invoked in `/map-efficient` Self-MoA mode (--self-moa flag) to merge validated Actor variants. Not used in `/map-debate` (DebateArbiter handles synthesis directly).
1049-1053:⚠️ Potential issue | 🟡 MinorSynthesizer input description references DebateArbiter guidance, which is a
/map-debateconcept.The input says "Multiple Actor variants (typically 3) with different optimization focuses + DebateArbiter guidance", but Synthesizer operates in
/map-efficient --self-moawhere DebateArbiter is not involved. Consider updating to reference Monitor validations instead.Proposed fix
-**Input:** Multiple Actor variants (typically 3) with different optimization focuses + DebateArbiter guidance +**Input:** Multiple Actor variants (typically 3) with different optimization focuses + Monitor validationssrc/mapify_cli/templates/map/scripts/map_orchestrator.py (1)
376-384:⚠️ Potential issue | 🟠 MajorCircuit breaker only counts steps in current subtask, not entire workflow.
When advancing to the next subtask (line 382),
completed_stepsis reset to[]. Thecheck_circuit_breakerfunction then calculatestool_count = len(state.completed_steps)againstmax_iterations = len(state.subtask_sequence) * len(STEP_ORDER), which is a workflow-level threshold. This mismatch means the circuit breaker only ever counts steps within the current subtask, defeating the workflow-level limit. Either use per-subtask limits or accumulatecompleted_stepsacross all subtasks instead of resetting.
🤖 Fix all issues with AI agents
In @.claude/skills/map-workflows-guide/resources/agent-architecture.md:
- Around line 107-112: Replace the plain fenced-code blocks used for the
diagrams with language-marked fences to satisfy MD040: change the opening triple
backticks to "```text" for the short linear pipeline block containing
"TaskDecomposer → Actor → Monitor → Apply → Done (No Evaluator, no Predictor, no
learning)" and for the multi-line diagram that begins with "TaskDecomposer" and
lists the subtask flow (Actor×3 → Monitor×3 → debate-arbiter (Opus) ... Batch
learning (via /map-learn): Reflector (all subtasks) → Curator → Done); apply the
same "```text" change to the other similar fenced block noted in the comment so
all diagram fences are labeled as text.
- Around line 1-3: Update the shipped resource agent-architecture.md under
.claude into the matching templates copy so user-facing templates stay in sync:
copy the updated content for agent-architecture.md into the corresponding
template file and either run make sync-templates (or scripts/sync-templates.sh)
or manually verify the template update with git diff/git status so the change
appears under your templates area before finishing the PR.
In @.map/scripts/map_orchestrator.py:
- Around line 670-676: The circuit-breaker currently sets max_iterations =
len(state.subtask_sequence) * len(STEP_ORDER) which becomes 0 when
state.subtask_sequence is empty, causing triggered to be True; also
state.completed_steps is reset per-subtask so tool_count doesn't represent
cumulative progress. Fix by: 1) guard the trigger logic so if
len(state.subtask_sequence) == 0 then triggered = False (don't treat 0 as a real
limit), and 2) decide which counter you want — if the breaker should use
cumulative progress, introduce/use a persistent counter (e.g.,
state.cumulative_completed_steps) instead of state.completed_steps (which is
reset at the subtask transition), and compute tool_count =
len(state.cumulative_completed_steps) (or sum of completed counts) while leaving
the per-subtask reset intact; update references to tool_count, max_iterations,
and triggered accordingly.
- Around line 446-501: The code extracts always_required from EVIDENCE_REQUIRED
but never uses it; update the evidence gating in validate_step (the block that
handles EVIDENCE_REQUIRED for step_id) to only enforce evidence when either
always_required is True or the current step_id appears in state.pending_steps
(i.e., check state.pending_steps membership before requiring the evidence
directory/file and JSON fields), or if you prefer the opposite approach, remove
the always_required entry and related comment from EVIDENCE_REQUIRED so the
destructured variable is not misleading; use the symbols EVIDENCE_REQUIRED,
always_required, step_id, and state.pending_steps to locate and change the logic
accordingly.
In `@presentation/en/04-getting-started.md`:
- Around line 241-242: Update the path string used for the progress checkpoint:
change the reference from ".map/<branch>/progress.md" to ".map/progress.md" (the
literal path string appears on the line shown in the diff) so the guide points
to the branch-independent progress file used by the codebase and docs.
In `@src/mapify_cli/__init__.py`:
- Around line 2093-2102: The tracker currently reports hard-coded counts ("12
agents", "10 commands") which can diverge when create_agent_files or
create_command_files fallback to inline generation; change create_agent_files
and create_command_files to return the actual number of files/agents created
(e.g., return an int), then capture those returns where they are called and pass
the real counts into tracker.complete (e.g., tracker.complete("create-agents",
f"{agent_count} agents") and tracker.complete("create-commands",
f"{command_count} commands")), updating any callers of those functions as
needed.
In `@src/mapify_cli/entity_extractor.py`:
- Around line 286-293: workflow_keywords is missing entries for the two commands
listed in README/PLUGIN.md; update the mapping in
src/mapify_cli/entity_extractor.py (the workflow_keywords dict/object) to
include "map-resume": "map-resume-workflow" and "map-learn":
"map-learn-workflow" so the entity extractor recognizes those workflows
(preserve the existing key/value pattern and placement alongside other "map-*"
entries).
In `@src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md`:
- Around line 564-565: Update the stale "Last Updated" metadata in SKILL.md by
replacing the existing line "**Last Updated:** 2025-11-03" with the current date
(e.g., "**Last Updated:** 2026-02-14") so the header reflects the PR's changes;
locate the "**Last Updated:**" line in SKILL.md and update the date string
accordingly.
🧹 Nitpick comments (9)
.map/scripts/map_orchestrator.py (1)
735-735: Moveimport reto the top of the file.
reis a stdlib module with negligible import cost. Placing it at the top with the other imports (lines 93-100) follows Python conventions and avoids a repeated import on each call.README.md (1)
37-39: Add language specifiers to fenced code blocks.Lines 37 and 64 use fenced code blocks without a language identifier, which triggers markdownlint MD040. Use
textorbashas appropriate.Suggested fix
-``` +```text /map-efficient implement user authentication with JWT tokens -``` +```Similarly for line 64:
-``` +```text TaskDecomposer → breaks goal into subtaskstests/test_mapify_cli.py (1)
608-618: Consider adding a negative assertion for the template-only agents.The test verifies the 8 core agents are created via fallback, but doesn't assert that the 4 template-only agents are not created when templates are missing. Adding that would make the test more robust against accidental fallback generator additions that might produce incomplete agent files.
💡 Suggested assertion
for agent_file in expected_agents: agent_path = agents_dir / agent_file assert agent_path.exists(), f"Agent {agent_file} not created" + + # Verify template-only agents are NOT created via fallback + template_only_agents = [ + "debate-arbiter.md", + "synthesizer.md", + "research-agent.md", + "final-verifier.md", + ] + for agent_file in template_only_agents: + agent_path = agents_dir / agent_file + assert not agent_path.exists(), ( + f"Agent {agent_file} should not be created via fallback" + )docs/WORKFLOW_FLOW.md (1)
382-388: Complex one-liner may confuse users during debugging.The
sedpipeline for branch sanitization is correct but hard to read/type for someone in a debugging scenario. Consider adding a short comment or a simpler alias suggestion (e.g., referencing an orchestrator helper likemap_orchestrator.py branch_dir).src/mapify_cli/templates/skills/map-workflows-guide/resources/map-efficient-deep-dive.md (1)
39-57: Fenced code blocks missing language specifiers (MD040).Lines 40 and 48 open fenced code blocks without a language identifier. While these are diagram/pseudocode blocks, adding a language hint (e.g.,
text) improves rendering consistency and silences the linter.🔧 Add language specifier
-``` +```text Subtask 1 → Actor → Monitor → Predictor → Evaluator → Reflector → Curator-``` +```text Subtask 1 → Actor → Monitor → [Predictor if high risk] → Applypresentation/ru/02-архитектура.md (1)
149-175: New agents (9-12) have notably less detail than core agents (1-8).Agents 1-8 each document MCP integrations, critical protocols, and detailed output formats. The 4 new agents only list model, purpose, and output. If these agents do use MCP tools or have critical protocols, consider adding those details for consistency. If they intentionally have a simpler scope, this is fine as-is.
src/mapify_cli/templates/map/scripts/map_orchestrator.py (3)
142-150:always_requiredflag inEVIDENCE_REQUIREDis defined but never checked.The
EVIDENCE_REQUIREDmapping declares analways_requiredboolean (e.g.,("predictor", False)for step 2.6), and the comment at line 144-145 says it controls whether evidence is checked only when the step is inpending_steps. However,validate_step(lines 447-501) destructures this value but never branches on it — evidence is always required for any step that reachesvalidate_step.The current behavior happens to be correct because
skip_stepbypassesvalidate_stepentirely for skipped conditional steps. But the unused flag is misleading and suggests incomplete implementation.Either remove
always_requiredfrom the mapping (simplify to just the phase name) or implement the conditional check.Option A: Simplify — remove unused flag
-# Steps that require evidence files from agents before validation. -# Format: step_id -> (agent_phase, always_required) -# If always_required is False, evidence is only checked when the step -# appears in pending_steps (i.e., it wasn't skipped). -EVIDENCE_REQUIRED = { - "2.3": ("actor", True), # Always required - "2.4": ("monitor", True), # Always required - "2.6": ("predictor", False), # Only when 2.6 is in pending_steps -} +# Steps that require evidence files from agents before validation. +# Format: step_id -> agent_phase +# Evidence is required for any step that reaches validate_step. +# Conditional steps (2.6) bypass validation via skip_step instead. +EVIDENCE_REQUIRED = { + "2.3": "actor", + "2.4": "monitor", + "2.6": "predictor", +}Then update the destructuring at line 448:
- phase_name, always_required = EVIDENCE_REQUIRED[step_id] + phase_name = EVIDENCE_REQUIRED[step_id]Also applies to: 446-501
734-738:import reinside function body — move to module level.The
remodule is imported insideresume_from_plan. Sincereis a stdlib module with no side effects, it should be imported at the top of the file alongside the other imports (line 93-100).
503-506:pending_steps.remove(step_id)uses linear scan — consider deque or set for pending steps.
list.remove()is O(n) and is called on every step validation. With 16 steps and multiple subtasks this is negligible, but if the step count grows, switching to anOrderedDictor always popping from the front (since steps are processed in order) would be cleaner.Currently
get_next_stepalready usespending_steps[0]andpop(0)(line 367). Usingpop(0)here too (with an index check) would be consistent and avoid the linear scan.
| # Agent Architecture | ||
|
|
||
| MAP Framework orchestrates 8 specialized agents in a coordinated workflow. | ||
| MAP Framework orchestrates 12 specialized agents in a coordinated workflow. |
There was a problem hiding this comment.
Sync this .claude resource into templates.
This file is shipped to users; please mirror the change at src/mapify_cli/templates/skills/map-workflows-guide/resources/agent-architecture.md (or run make sync-templates) to keep templates in sync.
As per coding guidelines: "If you change anything under .claude/ that is shipped to users, you MUST copy it to the matching path under src/mapify_cli/templates/ before finishing. Sync via make sync-templates (runs scripts/sync-templates.sh) or verify with git diff/git status."
🤖 Prompt for AI Agents
In @.claude/skills/map-workflows-guide/resources/agent-architecture.md around
lines 1 - 3, Update the shipped resource agent-architecture.md under .claude
into the matching templates copy so user-facing templates stay in sync: copy the
updated content for agent-architecture.md into the corresponding template file
and either run make sync-templates (or scripts/sync-templates.sh) or manually
verify the template update with git diff/git status so the change appears under
your templates area before finishing the PR.
| ### Linear Pipeline (map-fast) | ||
|
|
||
| ``` | ||
| TaskDecomposer → Actor → Monitor → Evaluator → Done | ||
| (No learning, no impact analysis) | ||
| TaskDecomposer → Actor → Monitor → Apply → Done | ||
| (No Evaluator, no Predictor, no learning) | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced blocks (MD040).
markdownlint flags these fences; use text to keep the diagrams readable.
Suggested fix
-```
+```text
TaskDecomposer → Actor → Monitor → Apply → Done
(No Evaluator, no Predictor, no learning)@@
- +text
TaskDecomposer
↓
For each subtask:
Actor×3 → Monitor×3 → debate-arbiter (Opus)
↓ synthesized
Monitor → [Predictor if high risk] → Apply changes
↓
Batch learning (via /map-learn):
Reflector (all subtasks) → Curator → Done
Also applies to: 129-135
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 109-109: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.claude/skills/map-workflows-guide/resources/agent-architecture.md around
lines 107 - 112, Replace the plain fenced-code blocks used for the diagrams with
language-marked fences to satisfy MD040: change the opening triple backticks to
"```text" for the short linear pipeline block containing "TaskDecomposer → Actor
→ Monitor → Apply → Done (No Evaluator, no Predictor, no learning)" and for the
multi-line diagram that begins with "TaskDecomposer" and lists the subtask flow
(Actor×3 → Monitor×3 → debate-arbiter (Opus) ... Batch learning (via
/map-learn): Reflector (all subtasks) → Curator → Done); apply the same
"```text" change to the other similar fenced block noted in the comment so all
diagram fences are labeled as text.
| # Evidence-gated validation: require agent evidence files for key steps | ||
| if step_id in EVIDENCE_REQUIRED: | ||
| phase_name, always_required = EVIDENCE_REQUIRED[step_id] | ||
| evidence_dir = Path(f".map/{branch}/evidence") | ||
| if not evidence_dir.is_dir(): | ||
| return { | ||
| "valid": False, | ||
| "message": ( | ||
| f"Evidence directory missing: {evidence_dir}. " | ||
| f"Run initialize or resume_from_plan first." | ||
| ), | ||
| } | ||
| subtask_id = state.current_subtask_id or "unknown" | ||
| evidence_file = evidence_dir / f"{phase_name}_{subtask_id}.json" | ||
| if not evidence_file.exists(): | ||
| return { | ||
| "valid": False, | ||
| "message": ( | ||
| f"Evidence file missing: {evidence_file}. " | ||
| f"The {phase_name} agent must write this file before " | ||
| f"validate_step can accept step {step_id}." | ||
| ), | ||
| } | ||
| # Validate JSON structure | ||
| try: | ||
| evidence_data = json.loads( | ||
| evidence_file.read_text(encoding="utf-8") | ||
| ) | ||
| except (json.JSONDecodeError, OSError) as exc: | ||
| return { | ||
| "valid": False, | ||
| "message": ( | ||
| f"Evidence file {evidence_file} is not valid JSON: {exc}" | ||
| ), | ||
| } | ||
| # Check required fields | ||
| for required_field in ("phase", "subtask_id", "timestamp"): | ||
| if required_field not in evidence_data: | ||
| return { | ||
| "valid": False, | ||
| "message": ( | ||
| f"Evidence file {evidence_file} missing required " | ||
| f"field: '{required_field}'. " | ||
| f"Required fields: phase, subtask_id, timestamp." | ||
| ), | ||
| } | ||
| # Validate subtask_id matches current subtask | ||
| if evidence_data.get("subtask_id") != subtask_id: | ||
| return { | ||
| "valid": False, | ||
| "message": ( | ||
| f"Evidence file subtask_id mismatch: " | ||
| f"expected '{subtask_id}', " | ||
| f"got '{evidence_data.get('subtask_id')}'." | ||
| ), | ||
| } |
There was a problem hiding this comment.
always_required flag is extracted but never consulted.
Line 448 destructures always_required from EVIDENCE_REQUIRED, but the validation logic never branches on it. The comment at lines 143-145 states evidence should only be checked for non-always-required steps when they appear in pending_steps, but that conditional is missing.
Proposed fix
if step_id in EVIDENCE_REQUIRED:
phase_name, always_required = EVIDENCE_REQUIRED[step_id]
+ # Skip evidence check for optional steps that were not scheduled
+ if not always_required and step_id not in state.pending_steps:
+ pass # Step was skipped; no evidence needed
+ else:
- evidence_dir = Path(f".map/{branch}/evidence")
+ evidence_dir = Path(f".map/{branch}/evidence")Alternatively, if the current behavior (always check) is intentional, remove the always_required field and comment to avoid confusion.
🤖 Prompt for AI Agents
In @.map/scripts/map_orchestrator.py around lines 446 - 501, The code extracts
always_required from EVIDENCE_REQUIRED but never uses it; update the evidence
gating in validate_step (the block that handles EVIDENCE_REQUIRED for step_id)
to only enforce evidence when either always_required is True or the current
step_id appears in state.pending_steps (i.e., check state.pending_steps
membership before requiring the evidence directory/file and JSON fields), or if
you prefer the opposite approach, remove the always_required entry and related
comment from EVIDENCE_REQUIRED so the destructured variable is not misleading;
use the symbols EVIDENCE_REQUIRED, always_required, step_id, and
state.pending_steps to locate and change the logic accordingly.
| tool_count = len(state.completed_steps) | ||
| max_iterations = len(state.subtask_sequence) * len(STEP_ORDER) | ||
|
|
||
| return { | ||
| "tool_count": tool_count, | ||
| "max_iterations": max_iterations, | ||
| "triggered": tool_count >= max_iterations, |
There was a problem hiding this comment.
Circuit breaker always triggers when subtask_sequence is empty.
When called before set_subtasks (or early in the workflow), subtask_sequence is [], so max_iterations = 0. The check tool_count >= 0 is always True, making triggered a false positive.
Additionally, completed_steps is reset to [] on each subtask transition (line 382), so tool_count only reflects the current subtask's steps, not the cumulative total — contradicting the docstring's "total completed steps."
Proposed fix for the zero-subtask edge case
tool_count = len(state.completed_steps)
max_iterations = len(state.subtask_sequence) * len(STEP_ORDER)
+ # Avoid false trigger when subtasks haven't been set yet
+ if max_iterations == 0:
+ return {
+ "tool_count": tool_count,
+ "max_iterations": 0,
+ "triggered": False,
+ "retry_count": state.retry_count,
+ "max_retries": state.max_retries,
+ }
+
return {
"tool_count": tool_count,
"max_iterations": max_iterations,
"triggered": tool_count >= max_iterations,Consider also whether completed_steps reset per subtask is the intended counter for the breaker, or if a separate cumulative counter is needed.
🤖 Prompt for AI Agents
In @.map/scripts/map_orchestrator.py around lines 670 - 676, The circuit-breaker
currently sets max_iterations = len(state.subtask_sequence) * len(STEP_ORDER)
which becomes 0 when state.subtask_sequence is empty, causing triggered to be
True; also state.completed_steps is reset per-subtask so tool_count doesn't
represent cumulative progress. Fix by: 1) guard the trigger logic so if
len(state.subtask_sequence) == 0 then triggered = False (don't treat 0 as a real
limit), and 2) decide which counter you want — if the breaker should use
cumulative progress, introduce/use a persistent counter (e.g.,
state.cumulative_completed_steps) instead of state.completed_steps (which is
reset at the subtask transition), and compute tool_count =
len(state.cumulative_completed_steps) (or sum of completed counts) while leaving
the per-subtask reset intact; update references to tool_count, max_iterations,
and triggered accordingly.
| - Open `.map/<branch>/progress.md` | ||
| - Watch progress markers |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for progress file references across the codebase
echo "=== Searching for 'progress' references in markdown files ==="
rg -n 'progress' --type=md | head -50
echo -e "\n=== Searching for '.map' directory references ==="
rg -n '\.map' --type=md | head -30
echo -e "\n=== Looking for actual .map directories or files ==="
find . -type d -name '.map' 2>/dev/null | head -20
find . -type f -path '*/.map/*' 2>/dev/null | head -20
echo -e "\n=== Checking context around line 241 in the English file ==="
sed -n '235,250p' presentation/en/04-getting-started.mdRepository: azalio/map-framework
Length of output: 8796
Correct the path reference on line 241.
The path should be .map/progress.md, not .map/<branch>/progress.md. Branch-scoped paths are used for task plans (.map/<branch>/task_plan_*.md), but the progress checkpoint is stored directly in .map/progress.md as documented throughout the codebase (docs/USAGE.md, docs/ARCHITECTURE.md, and other presentation files).
🤖 Prompt for AI Agents
In `@presentation/en/04-getting-started.md` around lines 241 - 242, Update the
path string used for the progress checkpoint: change the reference from
".map/<branch>/progress.md" to ".map/progress.md" (the literal path string
appears on the line shown in the diff) so the guide points to the
branch-independent progress file used by the codebase and docs.
| tracker.add("create-agents", "Create MAP agents") | ||
| tracker.start("create-agents") | ||
| create_agent_files(project_path, selected_mcp_servers) | ||
| tracker.complete("create-agents", "8 agents") | ||
| tracker.complete("create-agents", "12 agents") | ||
|
|
||
| tracker.add("create-commands", "Create slash commands") | ||
| tracker.start("create-commands") | ||
| create_command_files(project_path) | ||
| tracker.complete("create-commands", "4 commands") | ||
| tracker.complete("create-commands", "10 commands") | ||
|
|
There was a problem hiding this comment.
Tracker counts can drift from actual files created.
create_agent_files/create_command_files fall back to inline generation if templates are missing, but the tracker now hard‑codes “12 agents” and “10 commands.” This can misreport results in fallback scenarios. Consider deriving the count from actual files created (e.g., return counts from the create_* functions).
🤖 Prompt for AI Agents
In `@src/mapify_cli/__init__.py` around lines 2093 - 2102, The tracker currently
reports hard-coded counts ("12 agents", "10 commands") which can diverge when
create_agent_files or create_command_files fallback to inline generation; change
create_agent_files and create_command_files to return the actual number of
files/agents created (e.g., return an int), then capture those returns where
they are called and pass the real counts into tracker.complete (e.g.,
tracker.complete("create-agents", f"{agent_count} agents") and
tracker.complete("create-commands", f"{command_count} commands")), updating any
callers of those functions as needed.
| "map-efficient": "map-efficient-workflow", | ||
| "map-fast": "map-fast-workflow", | ||
| "map-debug": "map-debug-workflow", | ||
| "map-refactor": "map-refactor-workflow", | ||
| "map-debate": "map-debate-workflow", | ||
| "map-review": "map-review-workflow", | ||
| "map-plan": "map-plan-workflow", | ||
| "map-check": "map-check-workflow", | ||
| "map-release": "map-release-workflow", |
There was a problem hiding this comment.
map-resume and map-learn are missing from workflow keywords.
The README and PLUGIN.md list 10 slash commands, but map-resume and map-learn are not present in workflow_keywords. The entity extractor won't recognize these as workflow entities.
Suggested fix
"map-check": "map-check-workflow",
"map-release": "map-release-workflow",
+ "map-resume": "map-resume-workflow",
+ "map-learn": "map-learn-workflow",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "map-efficient": "map-efficient-workflow", | |
| "map-fast": "map-fast-workflow", | |
| "map-debug": "map-debug-workflow", | |
| "map-refactor": "map-refactor-workflow", | |
| "map-debate": "map-debate-workflow", | |
| "map-review": "map-review-workflow", | |
| "map-plan": "map-plan-workflow", | |
| "map-check": "map-check-workflow", | |
| "map-release": "map-release-workflow", | |
| "map-efficient": "map-efficient-workflow", | |
| "map-fast": "map-fast-workflow", | |
| "map-debug": "map-debug-workflow", | |
| "map-debate": "map-debate-workflow", | |
| "map-review": "map-review-workflow", | |
| "map-plan": "map-plan-workflow", | |
| "map-check": "map-check-workflow", | |
| "map-release": "map-release-workflow", | |
| "map-resume": "map-resume-workflow", | |
| "map-learn": "map-learn-workflow", |
🤖 Prompt for AI Agents
In `@src/mapify_cli/entity_extractor.py` around lines 286 - 293, workflow_keywords
is missing entries for the two commands listed in README/PLUGIN.md; update the
mapping in src/mapify_cli/entity_extractor.py (the workflow_keywords
dict/object) to include "map-resume": "map-resume-workflow" and "map-learn":
"map-learn-workflow" so the entity extractor recognizes those workflows
(preserve the existing key/value pattern and placement alongside other "map-*"
entries).
| **Skill Version:** 1.0 | ||
| **Last Updated:** 2025-11-03 |
There was a problem hiding this comment.
Stale "Last Updated" date.
Last Updated: 2025-11-03 doesn't reflect the significant changes in this PR (Feb 2026). Update to the current date.
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/skills/map-workflows-guide/SKILL.md` around lines
564 - 565, Update the stale "Last Updated" metadata in SKILL.md by replacing the
existing line "**Last Updated:** 2025-11-03" with the current date (e.g.,
"**Last Updated:** 2026-02-14") so the header reflects the PR's changes; locate
the "**Last Updated:**" line in SKILL.md and update the date string accordingly.
Actor, Monitor, Predictor evidence JSON examples used lowercase "phase": "predictor" but orchestrator (map-efficient.md, map-resume.md) expects uppercase ACTOR, MONITOR, PREDICTOR. This caused recurring hook corrections at runtime.
azalio
changed the title
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/mapify_cli/templates/agents/actor.md`:
- Around line 505-527: Update the evidence file path in the actor.md template to
use the new branch placeholder: replace occurrences of
`.map/<branch>/evidence/actor_<subtask_id>.json` with
`.map/{{branch_name}}/evidence/actor_<subtask_id>.json` in the Evidence File
(Artifact-Gated Validation) block so it matches the MAP_Project_Context
placeholder convention; keep the rest of the heredoc and required fields
(`phase`, `subtask_id`, `timestamp`) unchanged so validate_step("2.3") continues
to succeed.
In `@src/mapify_cli/templates/agents/monitor.md`:
- Around line 2499-2521: Update the evidence file path placeholder in the
monitor template: replace the hardcoded
`.map/<branch>/evidence/monitor_<subtask_id>.json` pattern with
`.map/{{branch_name}}/evidence/monitor_<subtask_id>.json` (and any other
`.map/<branch>/...` occurrences) so it matches the `{{branch_name}}` convention
used elsewhere in this template (`monitor.md`) and avoids rendering mismatches
during validation.
| ### Evidence File (Artifact-Gated Validation) | ||
|
|
||
| After applying all code changes, write an evidence file so the orchestrator can verify this step ran. Use Bash (not Write tool) to create the file: | ||
|
|
||
| ```bash | ||
| cat > .map/<branch>/evidence/actor_<subtask_id>.json << 'EVIDENCE' | ||
| { | ||
| "phase": "ACTOR", | ||
| "subtask_id": "<subtask_id>", | ||
| "timestamp": "<ISO 8601 UTC>", | ||
| "summary": "<one-line description of what was implemented>", | ||
| "aag_contract": "<the AAG contract line>", | ||
| "files_changed": ["<list of modified file paths>"], | ||
| "status": "applied" | ||
| } | ||
| EVIDENCE | ||
| ``` | ||
|
|
||
| **Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`. | ||
| Other fields are informational but recommended for audit trail. | ||
|
|
||
| **CRITICAL**: Without this file, `validate_step("2.3")` will reject the step. | ||
|
|
There was a problem hiding this comment.
Align evidence path placeholder with {{branch_name}}.
The evidence path uses .map/<branch>/... while the rest of the template (and MAP_Project_Context) now uses {{branch_name}}. To avoid confusion or incorrect substitutions, please align the evidence path with the new placeholder name.
Proposed fix
-cat > .map/<branch>/evidence/actor_<subtask_id>.json << 'EVIDENCE'
+cat > .map/{{branch_name}}/evidence/actor_<subtask_id>.json << 'EVIDENCE'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Evidence File (Artifact-Gated Validation) | |
| After applying all code changes, write an evidence file so the orchestrator can verify this step ran. Use Bash (not Write tool) to create the file: | |
| ```bash | |
| cat > .map/<branch>/evidence/actor_<subtask_id>.json << 'EVIDENCE' | |
| { | |
| "phase": "ACTOR", | |
| "subtask_id": "<subtask_id>", | |
| "timestamp": "<ISO 8601 UTC>", | |
| "summary": "<one-line description of what was implemented>", | |
| "aag_contract": "<the AAG contract line>", | |
| "files_changed": ["<list of modified file paths>"], | |
| "status": "applied" | |
| } | |
| EVIDENCE | |
| ``` | |
| **Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`. | |
| Other fields are informational but recommended for audit trail. | |
| **CRITICAL**: Without this file, `validate_step("2.3")` will reject the step. | |
| ### Evidence File (Artifact-Gated Validation) | |
| After applying all code changes, write an evidence file so the orchestrator can verify this step ran. Use Bash (not Write tool) to create the file: | |
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/agents/actor.md` around lines 505 - 527, Update the
evidence file path in the actor.md template to use the new branch placeholder:
replace occurrences of `.map/<branch>/evidence/actor_<subtask_id>.json` with
`.map/{{branch_name}}/evidence/actor_<subtask_id>.json` in the Evidence File
(Artifact-Gated Validation) block so it matches the MAP_Project_Context
placeholder convention; keep the rest of the heredoc and required fields
(`phase`, `subtask_id`, `timestamp`) unchanged so validate_step("2.3") continues
to succeed.
| ### Evidence File (Artifact-Gated Validation) | ||
|
|
||
| **Exception to read-only rule**: Monitor writes evidence files to `.map/` artifacts directory via Bash (not Write tool). This does NOT violate the read-only-for-project-code rule — `.map/` is a workflow artifact directory, not project code. | ||
|
|
||
| After completing validation, write an evidence file: | ||
|
|
||
| ```bash | ||
| cat > .map/<branch>/evidence/monitor_<subtask_id>.json << 'EVIDENCE' | ||
| { | ||
| "phase": "MONITOR", | ||
| "subtask_id": "<subtask_id>", | ||
| "timestamp": "<ISO 8601 UTC>", | ||
| "valid": true, | ||
| "issues_found": <number of issues>, | ||
| "recommendation": "approve|reject|revise" | ||
| } | ||
| EVIDENCE | ||
| ``` | ||
|
|
||
| **Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`. | ||
| Other fields are informational but recommended for audit trail. | ||
|
|
||
| **CRITICAL**: Without this file, `validate_step("2.4")` will reject the step. |
There was a problem hiding this comment.
Align evidence path placeholder with {{branch_name}}.
This block still uses .map/<branch>/... while other sections now use {{branch_name}}. Align the placeholder to avoid mismatches in rendered instructions.
Proposed fix
-cat > .map/<branch>/evidence/monitor_<subtask_id>.json << 'EVIDENCE'
+cat > .map/{{branch_name}}/evidence/monitor_<subtask_id>.json << 'EVIDENCE'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Evidence File (Artifact-Gated Validation) | |
| **Exception to read-only rule**: Monitor writes evidence files to `.map/` artifacts directory via Bash (not Write tool). This does NOT violate the read-only-for-project-code rule — `.map/` is a workflow artifact directory, not project code. | |
| After completing validation, write an evidence file: | |
| ```bash | |
| cat > .map/<branch>/evidence/monitor_<subtask_id>.json << 'EVIDENCE' | |
| { | |
| "phase": "MONITOR", | |
| "subtask_id": "<subtask_id>", | |
| "timestamp": "<ISO 8601 UTC>", | |
| "valid": true, | |
| "issues_found": <number of issues>, | |
| "recommendation": "approve|reject|revise" | |
| } | |
| EVIDENCE | |
| ``` | |
| **Required fields** (orchestrator validates these): `phase`, `subtask_id`, `timestamp`. | |
| Other fields are informational but recommended for audit trail. | |
| **CRITICAL**: Without this file, `validate_step("2.4")` will reject the step. | |
| ### Evidence File (Artifact-Gated Validation) | |
| **Exception to read-only rule**: Monitor writes evidence files to `.map/` artifacts directory via Bash (not Write tool). This does NOT violate the read-only-for-project-code rule — `.map/` is a workflow artifact directory, not project code. | |
| After completing validation, write an evidence file: | |
🤖 Prompt for AI Agents
In `@src/mapify_cli/templates/agents/monitor.md` around lines 2499 - 2521, Update
the evidence file path placeholder in the monitor template: replace the
hardcoded `.map/<branch>/evidence/monitor_<subtask_id>.json` pattern with
`.map/{{branch_name}}/evidence/monitor_<subtask_id>.json` (and any other
`.map/<branch>/...` occurrences) so it matches the `{{branch_name}}` convention
used elsewhere in this template (`monitor.md`) and avoids rendering mismatches
during validation.
1 participant
Summary
Systematic audit of all MAP Framework instructions, fixing inconsistencies between documentation, agent templates, commands, and presentations. Prepared for Highload++ conference presentation.
46 commits across 121 files — all documentation/template fixes, no behavioral changes.
Key fixes by category:
Agent counts & references:
Command documentation:
Model claims:
Workflow accuracy:
Presentations (Highload++):
Agent templates:
Test coverage:
Test plan
Summary by CodeRabbit
New Features
Changes
Documentation
Tests