mapify-cli 3.17.1__tar.gz → 3.18.0__tar.gz

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.17.1
+Version: 3.18.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
@@ -11,6 +11,7 @@ Requires-Python: >=3.11
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: jinja2<4,>=3.1
 Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: readchar>=4.0.0
 Requires-Dist: rich>=13.0.0
@@ -249,10 +250,10 @@ MAP is inspired by the [MAP cognitive architecture](https://github.com/Shanka123
 
 ```yaml
 # .map/config.yaml
-minimality: lite   # new installs default to lite; existing repos without the key stay off
+minimality: lite   # default for ALL projects incl. keyless configs (#183); set 'off' to opt out
 ```
 
-Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout readiness with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health samples before considering the Phase 3 default flip, reports missing sample gaps and cohort branch names, lists the next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist before promotion.
+Allowed values: `off`, `lite`, `full`, `ultra`. The global default is `lite` (Phase 3 flip, #183 — keyless configs included; set `off` to opt out). `lite` is conservative: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can still inspect local rollout telemetry with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health cohorts, reports sample gaps and cohort branch names, lists next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist.
 
 **Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):
 
@@ -263,7 +264,7 @@ mapify init . --compression aggressive            # nudge at 0.4 x threshold
 mapify init . --compression-threshold 250000      # Opus 1M / 50+ subtask plans
 ```
 
-Actor and reviewer prompts always carry the full bundled context — context-block truncation was removed. If the conversation grows beyond your model's window, opt into `/compact` via `--compression auto` or trigger it manually. See [docs/USAGE.md#context-budget-policy](docs/USAGE.md).
+Actor and reviewer prompts always carry the full bundled context — context-block truncation was removed. If the conversation grows beyond your model's window, opt into `/compact` via `--compression auto` or trigger it manually. When a policy other than `never` is active, MAP also offloads large tool outputs (grep/test/file-read results) to `.map/<branch>/compacted/` before `/compact` drops them, so a dropped output is re-read from its sidecar instead of re-running broad discovery (these sidecars can hold secrets — they are `0o600` and self-ignored from git; never push `.map/`). See [docs/USAGE.md#context-budget-policy](docs/USAGE.md).
 
 **Stack Overflow for Agents (SOFA)** read-only prior-art search — **off by default**, no network or credentials unless you enable it:
 

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/README.md

@@ -205,10 +205,10 @@ MAP is inspired by the [MAP cognitive architecture](https://github.com/Shanka123
 
 ```yaml
 # .map/config.yaml
-minimality: lite   # new installs default to lite; existing repos without the key stay off
+minimality: lite   # default for ALL projects incl. keyless configs (#183); set 'off' to opt out
 ```
 
-Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout readiness with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health samples before considering the Phase 3 default flip, reports missing sample gaps and cohort branch names, lists the next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist before promotion.
+Allowed values: `off`, `lite`, `full`, `ultra`. The global default is `lite` (Phase 3 flip, #183 — keyless configs included; set `off` to opt out). `lite` is conservative: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can still inspect local rollout telemetry with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health cohorts, reports sample gaps and cohort branch names, lists next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist.
 
 **Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):
 
@@ -219,7 +219,7 @@ mapify init . --compression aggressive            # nudge at 0.4 x threshold
 mapify init . --compression-threshold 250000      # Opus 1M / 50+ subtask plans
 ```
 
-Actor and reviewer prompts always carry the full bundled context — context-block truncation was removed. If the conversation grows beyond your model's window, opt into `/compact` via `--compression auto` or trigger it manually. See [docs/USAGE.md#context-budget-policy](docs/USAGE.md).
+Actor and reviewer prompts always carry the full bundled context — context-block truncation was removed. If the conversation grows beyond your model's window, opt into `/compact` via `--compression auto` or trigger it manually. When a policy other than `never` is active, MAP also offloads large tool outputs (grep/test/file-read results) to `.map/<branch>/compacted/` before `/compact` drops them, so a dropped output is re-read from its sidecar instead of re-running broad discovery (these sidecars can hold secrets — they are `0o600` and self-ignored from git; never push `.map/`). See [docs/USAGE.md#context-budget-policy](docs/USAGE.md).
 
 **Stack Overflow for Agents (SOFA)** read-only prior-art search — **off by default**, no network or credentials unless you enable it:
 

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.17.1"
+version = "3.18.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"
@@ -12,7 +12,13 @@ dependencies = [
     "jinja2>=3.1,<4",
     "platformdirs>=4.0.0",
     "readchar>=4.0.0",
-    "questionary>=2.0.0"
+    "questionary>=2.0.0",
+    # mapify is a config-driven CLI: project_config.py loads .map/config.yaml via
+    # PyYAML on every config-dependent path (minimality-report, init overrides).
+    # It MUST be a hard runtime dep — a normal install (uv tool / pipx / pip
+    # without dev/test extras) otherwise ships without yaml, hits ImportError,
+    # and silently falls back to default config, ignoring the user's settings (#245).
+    "pyyaml>=6.0.0"
 ]
 
 [project.optional-dependencies]

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/__init__.py

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

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/config/mcp.py

@@ -23,8 +23,6 @@ def create_mcp_config(project_path: Path, mcp_servers: List[str]) -> None:
             "evaluator": [],
             "reflector": [],
             "documentation-reviewer": [],
-            "debate-arbiter": [],
-            "synthesizer": [],
             "research-agent": [],
             "final-verifier": [],
         },
@@ -62,7 +60,6 @@ def create_mcp_config(project_path: Path, mcp_servers: List[str]) -> None:
             "monitor",
             "evaluator",
             "reflector",
-            "debate-arbiter",
         ]:
             if agent in config["agent_mcp_mappings"]:
                 config["agent_mcp_mappings"][agent].append("sequential-thinking")

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/config/project_config.py

@@ -16,6 +16,7 @@ except ImportError:
 logger = logging.getLogger(__name__)
 
 VALID_MINIMALITY = frozenset({"off", "lite", "full", "ultra"})
+VALID_PROMPT_LAYERING = frozenset({"docs_first", "stable_first"})
 
 
 @dataclass
@@ -79,9 +80,22 @@ class MapConfig:
     # Language preference for agent responses
     language: str = ""
 
-    # Minimality doctrine intensity. Existing projects that have no config key
-    # stay off; new generated configs opt into lite explicitly.
-    minimality: str = "off"
+    # Minimality doctrine intensity. Phase 3 (#183) flipped the global default
+    # off -> lite after the promotion gate (`mapify minimality-report`) reached
+    # `candidate` and the manual review gate passed: projects with no config key
+    # now default to `lite` (advisory complexity-lens; no behavior/verdict gating).
+    minimality: str = "lite"
+
+    # Agent-prompt layering for repeated same-workflow dispatches (#231).
+    # "docs_first"   (default) = variable <documents> first, stable contract
+    #                last — optimized for recency / "lost-in-the-middle".
+    # "stable_first" = stable contract first, variable <documents> last — a
+    #                byte-identical prefix across same-role dispatches. Resolved
+    #                cache-neutral at the Claude Code Task layer (the harness owns
+    #                cache_control and the seam is mid-block), but NOT a behavior
+    #                no-op: it changes token order / attention. Kept opt-in; never
+    #                remapped to docs_first. See docs/ARCHITECTURE.md (#231).
+    prompt_layering: str = "docs_first"
 
     # Context compression policy (see docs/context-compression-plan.md)
     # "never"      = never inject /compact nudge (default — user opts in by
@@ -167,6 +181,15 @@ def load_map_config(project_path: Path) -> MapConfig:
         if isinstance(data, dict) and "sofa.enabled" in data and "sofa_enabled" not in data:
             data["sofa_enabled"] = data.pop("sofa.enabled")
 
+        # YAML 1.1 parses bare ``off``/``on`` as booleans, so ``minimality: off``
+        # — the documented opt-out from the lite default (#183) — arrives as bool
+        # ``False``. Coerce it back to the string level before the type-check loop;
+        # otherwise the str field rejects the bool and silently falls back to the
+        # lite default, breaking opt-out. ``False`` -> ``"off"`` (valid opt-out);
+        # ``True`` -> ``"on"`` (not a real level -> rejected -> lite fallback).
+        if isinstance(data, dict) and isinstance(data.get("minimality"), bool):
+            data["minimality"] = "off" if data["minimality"] is False else "on"
+
         # Map YAML keys to MapConfig fields, filtering out unrecognized keys
         # and validating types against dataclass field annotations
         defaults = MapConfig()
@@ -216,12 +239,22 @@ def load_map_config(project_path: Path) -> MapConfig:
         if cfg.minimality not in VALID_MINIMALITY:
             logger.warning(
                 "Invalid minimality %r in %s (expected one of %s). "
-                "Using default 'off'.",
+                "Using default 'lite'.",
                 cfg.minimality,
                 config_file,
                 ", ".join(sorted(VALID_MINIMALITY)),
             )
-            cfg.minimality = "off"
+            cfg.minimality = "lite"
+
+        if cfg.prompt_layering not in VALID_PROMPT_LAYERING:
+            logger.warning(
+                "Invalid prompt_layering %r in %s (expected one of %s). "
+                "Using default 'docs_first'.",
+                cfg.prompt_layering,
+                config_file,
+                ", ".join(sorted(VALID_PROMPT_LAYERING)),
+            )
+            cfg.prompt_layering = "docs_first"
 
         return cfg
 
@@ -317,6 +350,16 @@ profile: full
 # Allowed: off, lite, full, ultra
 minimality: lite
 
+# Agent-prompt layering for repeated same-workflow dispatches (#231).
+# "docs_first" (default) orders the variable <documents> first and the stable
+# task/instructions/expected_output contract last — best for recency/attention.
+# "stable_first" puts the stable contract first (byte-identical prefix across
+# same-role dispatches). Resolved cache-neutral at the Claude Code Task layer
+# (harness owns cache_control; the seam is mid-block) but it still changes token
+# order/attention, so it is kept opt-in — see docs/ARCHITECTURE.md (#231).
+# Allowed: docs_first, stable_first
+# prompt_layering: docs_first
+
 # Context compression policy. Default is "never" — the /compact nudge is
 # opt-in. Uncomment and switch to "auto" or "aggressive" if you want the
 # meter to interrupt long workflows and ask Claude to compact.

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/schemas.py

@@ -684,6 +684,10 @@ WORKFLOW_FIT_DECISION_SCHEMA = {
                 "needs_independent_review": {"type": "boolean"},
                 "has_clear_acceptance_criteria": {"type": "boolean"},
                 "test_first_required": {"type": "boolean"},
+                # Optional (not required): pre-existing workflow-fit.json files
+                # written before this signal existed must still validate. New
+                # writes always emit it (record_workflow_fit defaults it False).
+                "depends_on_runtime_state": {"type": "boolean"},
             },
             "required": [
                 "expected_diff_size",

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/.gitignore

@@ -1,5 +1,8 @@
 # Phase E cross-session memory: scratch WAL is transient (never commit)
 .map/*/sessions/scratch/
+# Offloaded tool outputs (#232) may contain secrets — never commit. A
+# self-contained .map/<branch>/compacted/.gitignore enforces this too.
+.map/*/compacted/
 # Digests (.map/*/sessions/*.md) are committed by default. To keep them
 # local, set MAP_MEMORY_COMMIT_DIGESTS=0 and uncomment the next line:
 # .map/*/sessions/

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/agents/actor.md

@@ -74,43 +74,6 @@ You are a Protocol-Driven Code Execution System. Your objective: translate an AA
 - `{{variable}}` (lowercase): Pre-filled by MAP framework Orchestrator before you see them
 - `{{variable}}` (in generated code): Preserve exactly for runtime substitution when instructed
 
-### Self-MoA Support (Optional)
-
-When invoked in Self-MoA mode, Actor generates variants with specific optimization focus.
-
-| Field | Type | Description | Values |
-|-------|------|-------------|--------|
-| `approach_focus` | string | Primary optimization constraint | `"security"` \| `"performance"` \| `"simplicity"` |
-| `self_moa_mode` | boolean | Multiple variants indicator | `true` \| `false` |
-| `variant_id` | string | Variant identifier for synthesis | `"v1"`, `"v2"`, `"v3"` |
-
-**Behavior per focus:**
-- **security**: Prioritize input validation, OWASP compliance, defensive coding, parameterized queries
-- **performance**: Prioritize algorithm efficiency, caching strategies, async patterns, minimal allocations
-- **simplicity**: Prioritize the smallest sufficient safe change: stdlib/native/existing project patterns before new abstractions, with clarity over cleverness
-
-**CRITICAL:** Even with focus, NEVER compromise basic security or correctness. All variants must:
-- Validate input at boundaries
-- Handle errors explicitly (no silent failures)
-- Follow contract constraints (if provided)
-
-**Output in Self-MoA Mode:**
-When `self_moa_mode: true`, include additional field in output:
-```json
-{
-  "decisions_made": [
-    {
-      "category": "algorithm|error_handling|structure|security|performance|observability|readability",
-      "statement": "Use list comprehension instead of for-loop",
-      "rationale": "Better performance for this transformation",
-      "priority_class": "correctness|security|maintainability|performance"
-    }
-  ]
-}
-```
-
-This enables Synthesizer to extract and resolve decisions across variants.
-
 ---
 
 <Actor_MCP_Protocol>

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/agents/documentation-reviewer.md

@@ -2,10 +2,12 @@
 name: documentation-reviewer
 description: Reviews technical documentation for completeness, external dependencies, and architectural consistency
 model: sonnet
-version: 3.1.0
-last_updated: 2025-11-27
+version: 3.1.1
+last_updated: 2026-06-19
 ---
 
+> **Dispatch status:** Optional / user-dispatchable agent — not auto-wired into any shipped MAP skill pipeline (no `subagent_type="documentation-reviewer"` dispatch site exists). Invoke manually via `Task(subagent_type="documentation-reviewer", …)`. Retained per the Agent-Boundary Doctrine in `docs/ARCHITECTURE.md` because it emits a unique, non-relay verdict (docs-vs-source-architecture review).
+
 # QUICK REFERENCE (Read First)
 
 ```

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/agents/monitor.md

@@ -1602,7 +1602,6 @@ Do NOT invent issues to justify review effort. Empty `issues` array is valid.
   "type": "object",
   "required": ["valid", "summary", "issues", "passed_checks", "failed_checks", "feedback_for_actor", "estimated_fix_time", "mcp_tools_used"],
   "additionalProperties": true,
-  "description_note": "additionalProperties: true allows Self-MoA extension fields (variant_id, decisions_identified, compatibility_features, etc.) - see Self-MoA Output Extension section",
   "properties": {
     "valid": {
       "type": "boolean",
@@ -1873,93 +1872,6 @@ IF map-state workflow active AND valid === true:
 - **estimated_fix_time** (string): Realistic estimate
 - **mcp_tools_used** (array): Tools used for debugging
 
-### Self-MoA Output Extension
-
-When reviewing code in Self-MoA mode (variant validation), include additional fields to support Synthesizer:
-
-```json
-{
-  "variant_id": "v1",
-  "self_moa_mode": true,
-
-  "decisions_identified": [
-    {
-      "id": "dec-001",
-      "category": "performance",
-      "statement": "Use list comprehension for data transformation",
-      "rationale": "Better performance for this use case",
-      "source_variant": "v1",
-      "priority_class": "performance",
-      "conflicts_with": [],
-      "code_location": "process_data:45",
-      "confidence": 0.9
-    },
-    {
-      "id": "dec-002",
-      "category": "error_handling",
-      "statement": "Return Result type for explicit error handling",
-      "rationale": "Makes error cases visible in type system",
-      "source_variant": "v1",
-      "priority_class": "correctness",
-      "conflicts_with": ["dec-003"],
-      "code_location": "process_data:12",
-      "confidence": 0.85
-    }
-  ],
-
-  "compatibility_features": {
-    "error_paradigm": "Result",
-    "concurrency_model": "sync",
-    "state_management": "stateless",
-    "type_strictness": "strict",
-    "naming_convention": "snake_case",
-    "imports_used": ["typing", "dataclasses", "logging"]
-  },
-
-  "spec_contract_compliant": true,
-  "spec_contract_violations": [],
-
-  "strengths": [
-    "Excellent input validation",
-    "Clear error messages"
-  ],
-  "weaknesses": [
-    "O(n²) algorithm in main loop"
-  ],
-
-  "recommended_as_base": true
-}
-```
-
-**Self-MoA Field Descriptions:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `variant_id` | string | Identifier matching Actor's variant_id ("v1", "v2", "v3") |
-| `self_moa_mode` | boolean | Must be `true` when in Self-MoA mode |
-| `decisions_identified` | array | 3-8 key design decisions extracted from variant code |
-| `compatibility_features` | object | Features for orchestrator's deterministic compatibility scoring |
-| `spec_contract_compliant` | boolean | Whether variant follows SpecificationContract (if provided) |
-| `spec_contract_violations` | array | List of SpecificationContract violations (empty if compliant) |
-| `strengths` | array | Notable positive aspects of the variant |
-| `weaknesses` | array | Areas where variant is suboptimal |
-| `recommended_as_base` | boolean | True if variant has good structure for base_enhance strategy |
-
-**Decision Extraction Guidelines:**
-
-1. Extract 3-8 key decisions per variant (not every line of code)
-2. Focus on architectural and algorithmic choices
-3. Include explicit `conflicts_with` if decision contradicts common alternatives
-4. Set `confidence` based on clarity of decision in code (0.0-1.0)
-5. Use `priority_class` to categorize decision importance
-
-**Compatibility Features Purpose:**
-
-Monitor outputs FEATURES, orchestrator computes SCORES. This separation ensures:
-- Deterministic scoring (no LLM randomness in compatibility calculation)
-- Auditable decisions (features are inspectable)
-- Consistent pairwise comparison across variants
-
 </Monitor_Output_v2_9>
 
 

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -168,7 +168,10 @@ so Actor/Monitor can distinguish planner-wide context from current-subtask
 evidence. Use `researcher` when independent exploration is useful: cold-start
 repository exploration, 3+ existing files, high risk, unclear locations, or
 failed direct search. Otherwise research in the current session and save concise
-strict-JSON findings. If the subtask truly needs no Actor/Monitor, use
+strict-JSON findings — exact field table + copy-pasteable skeleton in
+[efficient-reference.md](efficient-reference.md) under "RESEARCH artifact schema"
+(`validate_research` also echoes that skeleton in its `skeleton` field on any
+failure). If the subtask truly needs no Actor/Monitor, use
 `mark_subtask_complete --reason` instead of closing RESEARCH. Validate the
 research contract, then close RESEARCH before Actor work:
 

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/codex/skills/map-efficient/efficient-reference.md

@@ -104,6 +104,54 @@ Final verification must prove the full plan:
 - Confirm Monitor artifacts do not contain unresolved valid=false findings.
 - Write `run_health_report.json` with `write_run_health_report`.
 
+## RESEARCH artifact schema (exact contract)
+
+`save_research` persists the bytes you pipe verbatim; `validate_research` then
+enforces the machine-checkable contract below before Actor consumes the artifact.
+Hand-author to this exact schema so the FIRST save validates.
+
+Top-level object — strict JSON only (no markdown, no ``` code fences, ≤ 64 KiB):
+
+| field | type | rule |
+| --- | --- | --- |
+| `status` | string | exactly one of `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED` (upper-case enum — NOT free text like `"complete"`/`"high"`) |
+| `confidence` | number | float in `[0, 1]` (NOT a word like `"high"`) |
+| `search_stats` | object | exactly `files_scanned` (int ≥ 0), `total_matches_found` (int ≥ 0), `results_truncated` (bool) — these exact field names |
+| `relevant_locations` | array | ≤ 5 entries; each is `{path, lines, relevance}` |
+
+Each `relevant_locations[]` entry:
+
+| field | type | rule |
+| --- | --- | --- |
+| `path` | string | safe relative repo path (no absolute, `~`, `\`, or `..`); must exist unless the entry is marked absent (`"exists": false`, `"absent": true`, or `"status"` ∈ `absent`/`missing`/`new`/`not_found`) |
+| `lines` | array | `[start, end]` — two positive ints, `start ≤ end`, span `end - start + 1 ≤ 200`, `end` within the file's line count (NOT a `"start-end"` string) |
+| `relevance` | string | non-empty; explain why the range matters. Never inline `content`/`file_contents`/`raw_code` |
+
+Copy-pasteable skeleton (a valid artifact — swap in your real values):
+
+```json
+{
+  "status": "OK",
+  "confidence": 0.8,
+  "search_stats": {
+    "files_scanned": 12,
+    "total_matches_found": 4,
+    "results_truncated": false
+  },
+  "relevant_locations": [
+    {
+      "path": "src/example/module.py",
+      "lines": [10, 42],
+      "relevance": "why this range matters to the current subtask"
+    }
+  ]
+}
+```
+
+`validate_research` echoes this exact skeleton in its `skeleton` field on ANY
+failure, so the first reject is self-correcting: copy the `skeleton`, swap your
+values, re-save. Extra fields beyond the contract are allowed and ignored.
+
 ## Troubleshooting
 
 - `resume_from_plan` fails: inspect the returned JSON and fix missing plan,

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/codex/skills/map-plan/SKILL.md

@@ -58,6 +58,7 @@ Assess whether MAP planning is warranted. Evaluate these signals:
 - `needs_independent_review`: risky enough to require review?
 - `has_clear_acceptance_criteria`: can be executed without a planning pass?
 - `test_first_required`: TDD warranted because behavior contract matters?
+- `depends_on_runtime_state`: does correctness depend on **current production/runtime state** (applied migration head, a table/column/index/enum value present in the live DB, current row counts / backfill volume, the actual value of a feature flag or config, runtime capacity/traffic)? Ask the operator when unsure — **if unsure, true.** False for refactors, tests, docs, static-config; "code will run in prod" is not runtime-dependence. When true, Step 0.6 runs.
 
 Pick one outcome:
 - `direct-edit` — tiny, isolated, clear acceptance criteria, no new invariants
@@ -71,9 +72,11 @@ shell_command:
   cmd: |
     python3 .map/scripts/map_step_runner.py record_workflow_fit \
       "<direct-edit|map-fast|map-plan>" \
-      "<tiny|small|medium|large>" \
-      "<true|false>" "<true|false>" "<true|false>" "<true|false>" \
-      "<one-sentence decision summary>"
+      --diff-size "<tiny|small|medium|large>" \
+      --has-new-invariants <0|1> --needs-independent-review <0|1> \
+      --has-clear-acceptance-criteria <0|1> --test-first-required <0|1> \
+      --depends-on-runtime-state <0|1> \
+      --summary "<one-sentence decision summary>"
 ```
 
 - Outcome `direct-edit`: print off-ramp explanation and STOP.
@@ -152,6 +155,22 @@ When unsure whether existing code truly satisfies the request, treat it as parti
 
 ---
 
+## Step 0.6: Verify Live/Runtime State Gate (MANDATORY when `depends_on_runtime_state=true`)
+
+The runtime analogue of Step 0.5. Step 0.5 stops you re-planning code that already exists; Step 0.6 stops you planning against **runtime facts that have drifted** from the design docs / memory the plan copied them from. Skip only when `depends_on_runtime_state=false`.
+
+Static discovery reads only the repo — it cannot see prod row counts, the enum labels actually present in a live DB, a column that already exists, the applied migration head, or a live feature-flag value. **Caution:** code can exist in the repo (Step 0.5 `file:line` proof) while its migration / feature flag is NOT yet applied in prod; verify runtime separately.
+
+Signals that arm the gate: a DB migration / data backfill; "measured on prod" / "currently" / "as of" numbers in the source; count-based acceptance criteria referencing current state ("migrate the 10k existing rows"), not a forward target ("1k RPS"); a feature-flag / config cutover; capacity / latency assumptions; "this column/table/enum value already exists".
+
+For each assumption the plan's correctness rests on:
+- **Verifiable read-only now** — confirm via an approved read-only source (read replica, dashboard, runbook, `INFORMATION_SCHEMA` / `pg_enum` / migration-head introspection). Record the **fact** + source, not the raw rows.
+- **Prod unreachable / unchecked** — record an `Unverified Runtime Assumption` under spec Open Questions / Risks with the **exact read-only check** + safe source, and mark dependent subtasks `provisional`. Do NOT bake the assumption in as fact.
+
+Safety: this skill is a planning-time gate, NOT a runtime tool — it suggests checks, it does not run them (defer to the operator or an authorized sub-agent). Prefer bounded / metadata queries over full scans / `COUNT(*)`; never write, mutate, or flip flags; never paste PII, secrets, or bulky prod output into the spec or `.map/<branch>/` artifacts (they may be committed); no isolation-level / `NOLOCK` hints. Do not hard-stop merely because prod is unreachable — record-the-check is the contract. If a runtime dependency surfaces later during decomposition, loop back and verify-or-record it.
+
+---
+
 ## Step 1: Assess Scope and Decide Interview Depth
 
 Read the user's requirements and decide if a deep interview is needed.

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/hooks/post-compact-context.py

@@ -200,6 +200,28 @@ def build_reprime(branch: str, branch_dir: Path) -> str | None:
     return truncate_text("\n".join(lines), REPRIME_LIMIT)
 
 
+def offloaded_outputs_pointer(branch: str, branch_dir: Path) -> str | None:
+    """Pointer to tool outputs offloaded before compaction, if any (#232).
+
+    Rebuilds the manifest from the append-only index and returns the recovery
+    line. Lazy-imports mapify_cli and degrades to ``None`` (silent) when it is
+    unavailable or nothing was offloaded.
+    """
+    try:
+        sys.path.insert(0, str(PROJECT_DIR / "src"))
+        try:
+            from mapify_cli.tool_output_offload import (
+                build_manifest,
+                recovery_pointer_text,
+            )
+        except ImportError:
+            return None
+        build_manifest(branch_dir / "compacted")
+        return recovery_pointer_text(branch, branch_dir)
+    except Exception:
+        return None
+
+
 def main() -> None:
     try:
         json.load(sys.stdin)
@@ -229,6 +251,12 @@ def main() -> None:
         except (IOError, OSError):
             pass
 
+    # Point at any tool outputs offloaded before compaction (#232) so the agent
+    # re-reads a sidecar instead of re-running broad discovery.
+    offload_pointer = offloaded_outputs_pointer(branch, branch_dir)
+    if offload_pointer:
+        parts.append(offload_pointer)
+
     # Check for workflow restore point
     restore = branch_dir / "restore_point.json"
     if restore.exists():

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/hooks/pre-compact-save-transcript.py

@@ -129,6 +129,37 @@ def parse_transcript(transcript_path: Path) -> str:
     return "\n".join(lines)
 
 
+def maybe_offload_tool_outputs(transcript_path: str, branch_dir: Path) -> None:
+    """Offload large tool-result bodies before compaction drops them (#232).
+
+    Only runs when ``compression_policy != never`` so a default install never
+    creates ``.map/<branch>/compacted/``. Lazy-imports mapify_cli and degrades
+    to a silent no-op if it is not importable. Never raises — a PreCompact hook
+    must not break compaction.
+    """
+    try:
+        sys.path.insert(0, str(PROJECT_DIR / "src"))
+        try:
+            from mapify_cli.config.project_config import load_map_config
+            from mapify_cli.tool_output_offload import (
+                offload_transcript_tool_outputs,
+            )
+        except ImportError:
+            return
+        config = load_map_config(PROJECT_DIR)
+        if config.compression_policy == "never":
+            return
+        summary = offload_transcript_tool_outputs(Path(transcript_path), branch_dir)
+        if summary.written:
+            print(
+                f"[pre-compact-save] Offloaded {summary.written} tool output(s) "
+                f"to {branch_dir / 'compacted'}",
+                file=sys.stderr,
+            )
+    except Exception:  # never break compaction
+        pass
+
+
 def main() -> None:
     if os.environ.get("MAP_INVOKED_BY"):
         sys.exit(0)
@@ -190,6 +221,10 @@ def main() -> None:
     except (IOError, OSError):
         pass
 
+    # Offload full-resolution tool-result bodies so dropped outputs stay
+    # recoverable instead of forcing a re-run of broad discovery (#232).
+    maybe_offload_tool_outputs(transcript_path, branch_dir)
+
     print("{}")
     sys.exit(0)
 

{mapify_cli-3.17.1 → mapify_cli-3.18.0}/src/mapify_cli/templates/map/scripts/map_orchestrator.py

@@ -3705,6 +3705,25 @@ def _emit_context_budget_warning(branch: str, transcript_path: Optional[str]) ->
         threshold=threshold,
         focus=_map_config_str(project_dir, "compression_focus", ""),
     )
+
+    # Offload large tool-result bodies before the (recommended) compaction drops
+    # them, then point the operator/agent at the sidecars (#232). Provider-
+    # agnostic: reuses the same transcript this warning already read. Lazy import
+    # with graceful fallback — never block the warning on a missing mapify_cli.
+    branch_dir = project_dir / ".map" / branch
+    try:
+        from mapify_cli.tool_output_offload import (  # noqa: PLC0415
+            offload_transcript_tool_outputs,
+            recovery_pointer_text,
+        )
+
+        offload_transcript_tool_outputs(path, branch_dir)
+        pointer = recovery_pointer_text(branch, branch_dir)
+        if pointer:
+            message = f"{message}\n\n{pointer}"
+    except Exception:  # noqa: BLE001 — warning must never raise
+        pass
+
     # stderr keeps stdout clean for JSON consumers (the orchestrator's
     # contract is JSON-on-stdout for every command).
     print(message, file=sys.stderr)