mapify-cli 3.6.0__tar.gz → 3.8.0__tar.gz

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/.gitignore

@@ -42,11 +42,13 @@ coverage.json
 .claude/sessions/
 .claude/metrics/
 .claude/cache/
+.claude/worktrees/
 
 # MAP runtime files (but keep static-analysis and orchestrator scripts)
 .map/*
 !.map/static-analysis/
 !.map/scripts/
+.map/scripts/.map/
 
 # Temporary verification files
 mapify_cli_verification_*.json

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.6.0
+Version: 3.8.0
 Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
 Project-URL: Homepage, https://github.com/azalio/map-framework
 Project-URL: Repository, https://github.com/azalio/map-framework.git
@@ -80,7 +80,6 @@ claude
 | `/map-efficient` | Production features, refactoring, complex tasks (recommended) |
 | `/map-debug` | Bug fixes and debugging |
 | `/map-fast` | Small, low-risk changes |
-| `/map-debate` | Complex decisions with multi-variant synthesis |
 | `/map-review` | Pre-commit code review |
 | `/map-check` | Quality gates and verification |
 | `/map-plan` | Task decomposition without implementation |
@@ -88,17 +87,21 @@ claude
 | `/map-tdd` | Test-first implementation workflow |
 | `/map-release` | Package release workflow |
 | `/map-resume` | Resume interrupted workflows |
-| `/map-learn` | Extract lessons after workflow completion |
+| `/map-learn` | Extract lessons after workflow completion; optional `[workflow-summary]` |
 
 [Detailed usage and options →](docs/USAGE.md)
 
 Canonical MAP flows:
 
-- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review`
-- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review`
-- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review`
+- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review` -> `/map-learn` (when you want to pay the learning cost)
+- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review` -> `/map-learn`
+- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review` -> `/map-learn`
 
-These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, and run dossiers under `.map/<branch>/`.
+`/map-plan` now records a workflow-fit decision first, so trivial work can exit early with a direct edit or `/map-fast` recommendation instead of forcing full MAP planning.
+
+These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, `artifact_manifest.json`, and run dossiers under `.map/<branch>/`. Targeted TDD flows also persist `test_contract_ST-00N.md` and `test_handoff_ST-00N.json` so `/map-task` can resume implementation from a clean red-phase handoff.
+
+`LEARN` is still the philosophical end of the MAP cycle, but runtime keeps it soft: `/map-efficient`, `/map-debug`, `/map-check`, and `/map-review` now write `learning-handoff.md` / `.json` under `.map/<branch>/`, so `/map-learn [workflow-summary]` can run immediately with an explicit summary or later with no argument by auto-loading the generated handoff.
 
 ## How It Works
 
@@ -127,6 +130,10 @@ The orchestration lives in `.claude/commands/map-*.md` prompts created by `mapif
 | [Architecture](docs/ARCHITECTURE.md) | Agents, MCP integration, customization |
 | [Platform Spec](docs/MAP_PLATFORM_SPEC.md) | Platform refactor roadmap, codebase analysis |
 
+## Case Study
+
+- [DevOpsConf 2026 case study](https://github.com/azalio/devopsconf-ai-develop) — real production case: SPEC -> PLAN -> TEST -> CODE -> REVIEW -> LEARN
+
 ## Trouble?
 
 - **Command not found** → Run `mapify init` in your project first

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/README.md

@@ -48,7 +48,6 @@ claude
 | `/map-efficient` | Production features, refactoring, complex tasks (recommended) |
 | `/map-debug` | Bug fixes and debugging |
 | `/map-fast` | Small, low-risk changes |
-| `/map-debate` | Complex decisions with multi-variant synthesis |
 | `/map-review` | Pre-commit code review |
 | `/map-check` | Quality gates and verification |
 | `/map-plan` | Task decomposition without implementation |
@@ -56,17 +55,21 @@ claude
 | `/map-tdd` | Test-first implementation workflow |
 | `/map-release` | Package release workflow |
 | `/map-resume` | Resume interrupted workflows |
-| `/map-learn` | Extract lessons after workflow completion |
+| `/map-learn` | Extract lessons after workflow completion; optional `[workflow-summary]` |
 
 [Detailed usage and options →](docs/USAGE.md)
 
 Canonical MAP flows:
 
-- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review`
-- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review`
-- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review`
+- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review` -> `/map-learn` (when you want to pay the learning cost)
+- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review` -> `/map-learn`
+- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review` -> `/map-learn`
 
-These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, and run dossiers under `.map/<branch>/`.
+`/map-plan` now records a workflow-fit decision first, so trivial work can exit early with a direct edit or `/map-fast` recommendation instead of forcing full MAP planning.
+
+These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, `artifact_manifest.json`, and run dossiers under `.map/<branch>/`. Targeted TDD flows also persist `test_contract_ST-00N.md` and `test_handoff_ST-00N.json` so `/map-task` can resume implementation from a clean red-phase handoff.
+
+`LEARN` is still the philosophical end of the MAP cycle, but runtime keeps it soft: `/map-efficient`, `/map-debug`, `/map-check`, and `/map-review` now write `learning-handoff.md` / `.json` under `.map/<branch>/`, so `/map-learn [workflow-summary]` can run immediately with an explicit summary or later with no argument by auto-loading the generated handoff.
 
 ## How It Works
 
@@ -95,6 +98,10 @@ The orchestration lives in `.claude/commands/map-*.md` prompts created by `mapif
 | [Architecture](docs/ARCHITECTURE.md) | Agents, MCP integration, customization |
 | [Platform Spec](docs/MAP_PLATFORM_SPEC.md) | Platform refactor roadmap, codebase analysis |
 
+## Case Study
+
+- [DevOpsConf 2026 case study](https://github.com/azalio/devopsconf-ai-develop) — real production case: SPEC -> PLAN -> TEST -> CODE -> REVIEW -> LEARN
+
 ## Trouble?
 
 - **Command not found** → Run `mapify init` in your project first

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.6.0"
+version = "3.8.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.6.0"
+__version__ = "3.8.0"
 
 import os
 import subprocess

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/delivery/file_copier.py

@@ -184,16 +184,6 @@ $ARGUMENTS
 
 Implement quickly with basic monitor validation only. No learning, no predictor.
     Use for small, low-risk changes where speed matters.
-""",
-            "map-learn": """---
-description: Extract lessons from completed workflows
----
-
-Extract and preserve lessons from recent workflow:
-
-$ARGUMENTS
-
-Call Reflector to extract patterns from recent workflow.
 """,
         }
 
@@ -312,14 +302,16 @@ This directory contains custom slash commands for Claude Code.
 - `/map-task` - Execute a single subtask from an existing plan
 - `/map-tdd` - Run a test-first workflow for one task or plan
 - `/map-debug` - Debug issues using MAP analysis
-- `/map-debate` - Generate variants and synthesize the best result
 - `/map-review` - Run a structured review workflow
 - `/map-check` - Run workflow quality gates and verification
 - `/map-fast` - Quick implementation with minimal validation
-- `/map-learn` - Extract lessons from completed workflows
 - `/map-release` - Execute MAP Framework package release workflow
 - `/map-resume` - Resume an interrupted workflow from `.map/`
 
+## Skill-Backed Slash Surfaces
+
+- `/map-learn` - Extract lessons from completed workflows (implemented via `.claude/skills/map-learn/SKILL.md`)
+
 ## Creating Custom Commands
 
 Create a new `.md` file in this directory with the following format:

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/delivery/managed_file_copier.py

@@ -103,6 +103,17 @@ def inject_metadata(content: str, ext: str, version: str, template_hash: str) ->
 
     if ext == ".md":
         header = f"<!-- {_MANAGED_TAG}: {meta_json} -->\n"
+        # If content has YAML frontmatter (starts with ---), insert after
+        # closing --- to preserve frontmatter parsing by tools like Claude Code.
+        if content.startswith("---\n"):
+            end_idx = content.find("\n---\n", 3)
+            if end_idx != -1:
+                insert_pos = end_idx + 5  # after \n---\n
+                return content[:insert_pos] + header + content[insert_pos:]
+            # Edge case: closing --- at very end (no trailing newline)
+            end_idx = content.find("\n---", 3)
+            if end_idx != -1 and end_idx + 4 == len(content):
+                return content + "\n" + header
         return header + content
 
     if ext == ".py":
@@ -135,6 +146,7 @@ def extract_metadata(content: str, ext: str) -> tuple[Optional[dict[str, Any]],
     Returns (None, original_content) if no metadata found.
     """
     if ext == ".md":
+        # Try at start of file (non-frontmatter .md files)
         m = _MD_PATTERN.match(content)
         if m:
             try:
@@ -142,6 +154,27 @@ def extract_metadata(content: str, ext: str) -> tuple[Optional[dict[str, Any]],
                 return meta, content[m.end() :]
             except json.JSONDecodeError:
                 pass
+        # Try after YAML frontmatter (agent .md files with ---)
+        if content.startswith("---\n"):
+            end_idx = content.find("\n---\n", 3)
+            if end_idx != -1:
+                after_fm = end_idx + 5
+                rest = content[after_fm:]
+                m = _MD_PATTERN.match(rest)
+                if m:
+                    try:
+                        meta = json.loads(m.group(1))
+                        clean = content[:after_fm] + rest[m.end() :]
+                        # If nothing followed the MAP-MANAGED comment (it was
+                        # at EOF) and clean ends with "\n---\n", the trailing
+                        # newline was injected by inject_metadata for the
+                        # frontmatter-at-EOF edge case.  Strip it to restore
+                        # the original content that had no trailing newline.
+                        if not rest[m.end() :] and clean.endswith("\n---\n"):
+                            clean = clean[:-1]
+                        return meta, clean
+                    except json.JSONDecodeError:
+                        pass
         return None, content
 
     if ext == ".py":

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/repo_insight.py

@@ -7,6 +7,7 @@ and key directories for workflow initialization.
 from pathlib import Path
 from typing import List
 import json
+import subprocess
 
 
 def detect_language(project_root: Path) -> str:
@@ -201,3 +202,78 @@ def _validate_repo_insight_schema(data: dict) -> None:
     for dir_path in data["key_dirs"]:
         if dir_path.startswith("/"):
             raise ValueError(f"key_dirs must be relative paths: {dir_path}")
+
+
+def compute_differential_insight(project_root: Path, since_sha: str | None) -> dict:
+    """Compute file changes since a given git SHA.
+
+    Used for context-aware injection: shows Actor only files
+    that changed since the last subtask completed.
+
+    Args:
+        project_root: Path to project root
+        since_sha: Git SHA to diff against (None = no baseline)
+
+    Returns:
+        Dict with changed_files, deleted_files. On success also includes
+        since_sha and current_sha. On error: empty lists and error key.
+        When since_sha is None: empty lists and note key.
+    """
+    if since_sha is None:
+        return {"changed_files": [], "deleted_files": [], "note": "no baseline SHA"}
+
+    try:
+        # Get changed/added/modified/renamed files
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=ACMR", since_sha, "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=project_root,
+            timeout=2,
+        )
+        if result.returncode != 0:
+            return {
+                "changed_files": [],
+                "deleted_files": [],
+                "error": f"git diff failed: {result.stderr.strip()}",
+            }
+        changed = [f for f in result.stdout.strip().split("\n") if f]
+
+        # Get deleted files
+        result_del = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=D", since_sha, "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=project_root,
+            timeout=2,
+        )
+        deleted = (
+            [f for f in result_del.stdout.strip().split("\n") if f]
+            if result_del.returncode == 0
+            else []
+        )
+
+        # Get current HEAD SHA
+        head_result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=project_root,
+            timeout=2,
+        )
+        current_sha = (
+            head_result.stdout.strip() if head_result.returncode == 0 else "unknown"
+        )
+
+        return {
+            "changed_files": changed,
+            "deleted_files": deleted,
+            "since_sha": since_sha,
+            "current_sha": current_sha,
+        }
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
+        return {
+            "changed_files": [],
+            "deleted_files": [],
+            "error": str(e),
+        }

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/schemas.py

@@ -464,3 +464,159 @@ REPO_INSIGHT_SCHEMA = {
     "required": ["language", "suggested_checks", "key_dirs"],
     "additionalProperties": True,
 }
+
+
+WORKFLOW_FIT_DECISION_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/workflow-fit-decision.json",
+    "title": "MAP Workflow Fit Decision",
+    "description": "Preflight workflow-fit decision stored in .map/<branch>/workflow-fit.json",
+    "type": "object",
+    "properties": {
+        "version": {"type": "string"},
+        "recommended_workflow": {
+            "type": "string",
+            "enum": [
+                "direct-edit",
+                "map-fast",
+                "map-efficient",
+                "map-tdd",
+                "map-plan",
+            ],
+        },
+        "needs_map": {"type": "boolean"},
+        "decision_summary": {"type": "string"},
+        "signals": {
+            "type": "object",
+            "properties": {
+                "expected_diff_size": {
+                    "type": "string",
+                    "enum": ["tiny", "small", "medium", "large"],
+                },
+                "has_new_invariants": {"type": "boolean"},
+                "needs_independent_review": {"type": "boolean"},
+                "has_clear_acceptance_criteria": {"type": "boolean"},
+                "test_first_required": {"type": "boolean"},
+            },
+            "required": [
+                "expected_diff_size",
+                "has_new_invariants",
+                "needs_independent_review",
+                "has_clear_acceptance_criteria",
+                "test_first_required",
+            ],
+            "additionalProperties": False,
+        },
+        "updated_at": {"type": "string", "format": "date-time"},
+    },
+    "required": [
+        "version",
+        "recommended_workflow",
+        "needs_map",
+        "decision_summary",
+        "signals",
+        "updated_at",
+    ],
+    "additionalProperties": False,
+}
+
+
+ARTIFACT_STAGE_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/artifact-stage.json",
+    "title": "MAP Artifact Stage",
+    "description": "One stage entry inside artifact_manifest.json",
+    "type": "object",
+    "properties": {
+        "status": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "artifacts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "kind": {"type": "string"},
+                },
+                "required": ["path", "kind"],
+                "additionalProperties": False,
+            },
+        },
+        "metadata": {"type": "object"},
+    },
+    "required": ["status", "updated_at", "artifacts", "metadata"],
+    "additionalProperties": False,
+}
+
+
+ARTIFACT_MANIFEST_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/artifact-manifest.json",
+    "title": "MAP Artifact Manifest",
+    "description": "Branch-scoped artifact manifest stored in .map/<branch>/artifact_manifest.json",
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "branch": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "stages": {
+            "type": "object",
+            "properties": {
+                "workflow_fit": ARTIFACT_STAGE_SCHEMA,
+                "spec": ARTIFACT_STAGE_SCHEMA,
+                "plan": ARTIFACT_STAGE_SCHEMA,
+                "test_contract": ARTIFACT_STAGE_SCHEMA,
+                "implementation": ARTIFACT_STAGE_SCHEMA,
+                "review": ARTIFACT_STAGE_SCHEMA,
+                "verification": ARTIFACT_STAGE_SCHEMA,
+                "learn_handoff": ARTIFACT_STAGE_SCHEMA,
+            },
+            "required": [
+                "workflow_fit",
+                "spec",
+                "plan",
+                "test_contract",
+                "implementation",
+                "review",
+                "verification",
+                "learn_handoff",
+            ],
+            "additionalProperties": False,
+        },
+    },
+    "required": ["schema_version", "branch", "updated_at", "stages"],
+    "additionalProperties": False,
+}
+
+
+TEST_HANDOFF_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/test-handoff.json",
+    "title": "MAP Test Handoff",
+    "description": "Persisted TDD handoff stored in .map/<branch>/test_handoff_<subtask>.json",
+    "type": "object",
+    "properties": {
+        "subtask_id": {"type": "string"},
+        "status": {"type": "string", "enum": ["contract_ready"]},
+        "contract_path": {"type": "string"},
+        "failing_test_command": {"type": ["string", "null"]},
+        "test_files": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "contract_summary": {"type": "string"},
+        "notes": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+    },
+    "required": [
+        "subtask_id",
+        "status",
+        "contract_path",
+        "failing_test_command",
+        "test_files",
+        "contract_summary",
+        "notes",
+        "updated_at",
+    ],
+    "additionalProperties": False,
+}

{mapify_cli-3.6.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/agents/actor.md

@@ -200,10 +200,15 @@ Task(
    - Use Read(path, offset=lines[0], limit=lines[1]-lines[0]+1)  # lines = [start, end], inclusive
    - Don't read all locations — only what you actually need
 
-## Skip Research If
+## Research Usage
 
-- Task is self-contained (new file, no dependencies)
-- Existing patterns from context already cover the need
+Research is run by the orchestrator BEFORE Actor is invoked. The findings file
+(`.map/<branch>/findings_<branch>.md`) contains distilled context. If it exists,
+read it before implementation — it has import patterns, module structure, and
+build configuration that prevent integration failures.
+
+Do NOT skip reading the findings file even for "new file" tasks — new files still
+need correct imports, types, and build configuration from the existing project.
 
 ---
 
@@ -276,6 +281,9 @@ Rules:
 5. Include edge cases from the spec's `## Edge Cases` section if available in the packet.
 6. Use standard test patterns for the project's language and framework.
 7. Tests SHOULD fail when run (implementation doesn't exist yet). This is expected.
+8. Do NOT add temporal comments about test failure status (e.g., "currently FAILS",
+   "expected to FAIL", "will PASS once fix is applied"). Write tests as permanent,
+   clean code — the Red/Green state is transient and must not leak into comments.
 
 Output:
 - Test files created via Write tool
@@ -408,7 +416,17 @@ VC1: <criterion text>
 - Tests: path/to/test_file.ext::test_name (or N/A with reason)
 ```
 
-## 7. Integration Notes (If Applicable)
+## 7. Downstream Consumption Check
+
+When implementing a component whose output is consumed by another component:
+
+- **Identify the consumer**: What reads your output? Verify your output populates ALL fields it expects.
+- **Self-bootstrap**: Does your code load its own dependencies from config/storage, or does it silently return empty results when input is not pre-populated by the caller?
+- **Stub replacement**: If implementing a real version of a placeholder, verify it is wired into the runtime — not just available as a standalone function.
+
+Skip this section for leaf components with no downstream consumers.
+
+## 8. Integration Notes (If Applicable)
 
 Only include if changes affect:
 - Database schema (migrations needed?)