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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.17.0
+Version: 3.17.1
 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

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

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

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

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

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-debug/SKILL.md

@@ -334,7 +334,7 @@ This is **completely optional**. Run it when debugging patterns are valuable for
 - Check for similar issues in other parts of the codebase when Predictor flags them or the root cause pattern is reusable.
 - Use the Task tool to call the specialized subagents in the sequence above.
 
-## Example
+## Examples
 
 User says: `/map-debug TypeError in authentication middleware`
 
@@ -349,12 +349,8 @@ You should:
 Begin debugging now.
 
 
-## Examples
-
-```
-/map-debug <typical args>
-```
-
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** A fix is applied before the root cause is identified. **Fix:** Stop and return to investigation — Debugging Constraints require root cause first.
+- **Issue:** The same bug pattern may exist elsewhere. **Fix:** Check sibling code when Predictor flags it or the root cause is reusable (see "Debugging Constraints").
+- **Issue:** The session was interrupted mid-workflow. **Fix:** Run `/map-resume` to recover.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-fast/SKILL.md

@@ -178,9 +178,12 @@ Begin now with minimal workflow.
 ## Examples
 
 ```
-/map-fast <typical args>
+/map-fast add a --verbose flag to the status command
+/map-fast fix the off-by-one error in the pagination offset
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** Task turns out risky, multi-stage, or ambiguous. **Fix:** Stop using `/map-fast`; switch to `/map-efficient` or `/map-plan` (see "When Not To Expand Scope").
+- **Issue:** A subtask exceeds 3 iterations without passing Monitor. **Fix:** Report it as a blocker/tradeoff — do not loop or fake-complete (see "Critical Constraints").
+- **Issue:** The session was interrupted mid-workflow. **Fix:** Run `/map-resume` to recover.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-memory-now/SKILL.md

@@ -32,6 +32,15 @@ as a maintenance sweep over multiple unfinalized scratches.
 
 ---
 
+## Constraints (NEVER)
+
+- **NEVER** edit code, run a workflow, or make commits beyond the digest from this skill — it only finalizes memory.
+- **NEVER** hand-write or edit a digest `.md` or scratch `.jsonl` directly; only `finalize_dirty` writes them (it is atomic — a failed digest is left unfinalized for retry, never half-written).
+- **NEVER** modify the user's `.gitignore` or flip `MAP_MEMORY_COMMIT_DIGESTS` for them — if the user wants digests kept local, instruct them; do not change it automatically.
+- **NEVER** let a digest carry secrets or credentials.
+
+---
+
 ## Arguments
 
 - `$ARGUMENTS` empty or `--finalize-all` — both run the full sweep (finalize ALL dirty

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-release/SKILL.md

@@ -1176,7 +1176,7 @@ Use these MCP tools throughout the workflow:
 | Gate # | Gate Name | Failure Impact | Can Proceed? | Fix Action |
 |--------|-----------|----------------|--------------|------------|
 | 1 | Pytest tests | High | ❌ NO | Fix failing tests |
-| 2 | Black format | Medium | ❌ NO | Run black --fix |
+| 2 | Pyright + hook lint | Medium | ❌ NO | Fix pyright / hook-lint errors (part of `make lint`) |
 | 3 | Ruff lint | Medium | ❌ NO | Fix linting errors |
 | 4 | Mypy types | Low | ⚠️ Review | Fix type errors (recommended) |
 | 5 | Package build | High | ❌ NO | Fix build config |
@@ -1265,9 +1265,11 @@ Begin now with the release request above.
 ## Examples
 
 ```
-/map-release <typical args>
+/map-release                            # full release workflow; bump type is chosen at the confirmation gate
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** `make check` (Gate 1) fails. **Fix:** Stop — fix every lint/type/test failure before any tag or publish step; the release gates are hard stops, not warnings.
+- **Issue:** `__version__` is out of sync after `bump-version.sh`. **Fix:** Apply the documented `__version__` sync workaround in Phase 1 before continuing.
+- **Issue:** A tag or PyPI publish step failed midway. **Fix:** Follow the rollback scenario for that phase; never re-run an irreversible step blindly.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-skill-eval/SKILL.md

@@ -12,6 +12,18 @@ Purpose: measure whether a `/map-*` skill fires on the right prompts and what it
 
 Requires the `claude` CLI (installed and on `$PATH`). The skill is skipped at install time on hosts without `claude`.
 
+## Constraints (NEVER)
+
+- **NEVER** plan or implement from this skill — it only measures trigger accuracy and cost. For work, use `/map-plan` or `/map-efficient`.
+- **NEVER** launch a non-dry-run `run`/`optimize` when the eval-set size or quota cost is unknown — run `--dry-run` first to see the call budget (each case spends a real `claude -p` call).
+- **NEVER** hand-edit the durable run log (`.map/eval-runs/<skill>/*.jsonl`) or `*-optimize.json` results — `--resume` and `view` depend on their integrity.
+- **NEVER** auto-commit an `--apply` change — `--apply` only stages the re-rendered description; review the diff, and patch `skill-rules.json` `description` by hand (it is not auto-patched).
+
+## Before reporting (self-check)
+
+- Confirm the run completed (not interrupted) — if it was, re-run with `--resume`; do not report a partial pass-rate.
+- Confirm the reported pass-rate equals passed/total and every case has a verdict.
+
 ## Invocation
 
 ```bash
@@ -83,7 +95,7 @@ mapify skill-eval run map-plan --eval-set .map/evals/map-plan.json --resume
 ## Troubleshooting
 
 - **`claude` not found** — `map-skill-eval` requires the `claude` CLI on `$PATH`. Install it and re-run `mapify init` to activate the skill.
-- **Eval-set validation error on `--dry-run`** — check that each case has a non-empty `id`, a `prompt`, and at least one `assertions` entry with a valid `type`.
+- **Eval-set validation error on `--dry-run`** — check that each case has a non-empty `prompt` (the only required field); that `should_trigger` / `should_not_trigger`, if present, are strings; and that every `assertions` entry has a valid `type`. Cases carry no user-supplied `id` — `cell_id`s like `p0-v1-r2` are derived automatically.
 - **Run log not found for `--resume`** — `--resume` looks for the latest `.map/eval-runs/<skill>/<timestamp>.jsonl`. If no prior run exists, omit `--resume` to start fresh.
 - **All cases report `not_trigger` unexpectedly** — verify the skill name matches exactly (e.g. `map-plan`, not `map_plan`) and that `.claude/` was seeded correctly in the temp cwd.
 

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: map-state
-version: "1.0.0"
+version: "3.1.0"
 description: >-
   Branch-scoped MAP planning in `.map/`. Use when the user needs a
   persistent task plan, progress tracking, or resume support across
@@ -147,6 +147,16 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 
 **Why**: Prevents race conditions, ensures consistent state, clear ownership.
 
+## Constraints (NEVER)
+
+These are hard rules — each one protects shared, persistent state. If a task seems to require violating one, STOP and ask the user.
+
+- **NEVER** write `task_plan` `**Status:**` from any agent other than Monitor. task-decomposer creates the plan; Monitor owns every subsequent status transition (see Single-Writer Governance). An agent that needs a status change must surface it, not write it.
+- **NEVER** hand-edit `step_state.json`. It is the canonical orchestrator state — mutate it only through `.map/scripts/` orchestrator calls. If the API cannot express what you need, STOP and ask; do not write the file as a fallback.
+- **NEVER** read, write, or delete another branch's `.map/<other-branch>/` tree. Scope is strictly the current branch.
+- **NEVER** set a `**Status:**` outside the defined vocabulary — phase statuses are `pending`, `in_progress`, `complete`; terminal states are listed under "Terminal States". Unknown values break the Stop-hook terminal-state check.
+- **NEVER** commit secrets, tokens, or credentials into plan / progress / research files.
+
 ## Best Practices
 
 - **Goal clarity**: Specific, measurable outcomes
@@ -154,14 +164,6 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 - **Checkpoint frequently**: Update status immediately after completion
 - **Terminal state early**: Mark `blocked` as soon as blocker identified
 
-## Error Handling
-
-| Issue | Fix |
-|-------|-----|
-| Plan not found | Run `init-session.sh` |
-| Stop hook warns "No terminal state" | Update `## Terminal State` section |
-| Branch name with `/` | Scripts sanitize: `feature/auth` → `feature-auth` |
-
 ## Terminal States
 
 | State | When |
@@ -223,7 +225,7 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 
 ---
 
-**Version**: 1.0.0 (2025-01-10)
+**Version**: 3.1.0
 
 **References**:
 - [planning-with-files](https://github.com/OthmanAdi/planning-with-files) - Original pattern

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-tdd/SKILL.md

@@ -37,7 +37,7 @@ parallel_tool_policy: sequential_red_green_gate
 ## Execution Flow
 
 ```
-Standard:          DECOMPOSE → ACTOR (code+tests) → MONITOR
+Non-TDD baseline:  DECOMPOSE → ACTOR (code+tests) → MONITOR   (= /map-efficient, shown for contrast — NOT a /map-tdd mode)
 Targeted TDD:      DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → CONTRACT_HANDOFF → STOP
 Targeted Resume:   /map-task ST-001 → ACTOR (code only) → MONITOR
 Full-workflow TDD: DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → ACTOR (code only) → MONITOR
@@ -281,7 +281,6 @@ Task(
   description="TDD: Implement subtask [ID] to make tests green",
   prompt=f"""You are in TDD CODE_ONLY mode.
 
-
 <MAP_Contract>
 [AAG contract from decomposition]
 </MAP_Contract>
@@ -289,21 +288,18 @@ Task(
 <TDD_Mode>code_only</TDD_Mode>
 
 <TDD_Tests>
-[List test files created by TEST_WRITER]
+{test_files_list}
 </TDD_Tests>
 
 STRICT RULES:
-1. Write ONLY implementation code. Do NOT modify test files.
+1. Write ONLY implementation code. Do NOT modify test files (the files in <TDD_Tests> are READ-ONLY).
 2. Your goal: make ALL existing tests pass (turn Red → Green).
 3. Read the test files first to understand what behavior is expected.
 4. Implement the minimum code needed to satisfy the tests.
 5. Follow the AAG contract as your specification.
 
-Test files (READ-ONLY):
-{test_files_list}
-
 Output: standard Actor output (approach + code + trade-offs)
-
+"""
 )
 ```
 
@@ -378,9 +374,12 @@ In TDD mode, `TEST_WRITER` and `TEST_FAIL_GATE` still write into the same branch
 ## Examples
 
 ```
-/map-tdd <typical args>
+/map-tdd ST-003                         # write spec-derived tests for one planned subtask, then stop
+/map-tdd add idempotency keys to the payment capture endpoint
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** Invoked without a spec or acceptance criteria. **Fix:** Run `/map-plan` first, or use `/map-efficient` (see "What this command does NOT do").
+- **Issue:** Tests pass trivially / mirror the implementation. **Fix:** Ensure TEST_WRITER derives tests from the spec only, before any implementation is in context (see "Key insight").
+- **Issue:** The session was interrupted between the red-phase contract and implementation. **Fix:** Resume with `/map-task ST-00N`.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates/skills/map-tokenreport/SKILL.md

@@ -13,6 +13,14 @@ run spent, attributed to the subtask, phase, and agent that spent them.
 Read-only reporting — this skill does not plan, implement, or run quality
 gates.
 
+## Constraints (NEVER)
+
+This skill is strictly read-only reporting.
+
+- **NEVER** edit code, state, or git from this skill — it renders an existing rollup and stops.
+- **NEVER** run or resume a MAP workflow here; if work is needed, hand off to `/map-efficient`.
+- **NEVER** present `est_cost_usd` as a billing source of truth — it is a per-model estimate.
+
 The numbers come from the `map-token-meter` hook (wired on `SubagentStop` and
 `Stop`), which reads each Claude Code transcript's per-turn `usage` block and
 appends attributed rows to `.map/<branch>/token_log.jsonl`, rolled up into
@@ -66,10 +74,16 @@ jq '{aggregate, by_agent, by_phase, research_roi}' ".map/${BRANCH}/token_account
 
 ### Step 4: Summarize
 
-Report the totals (input / output / cache), the cache-hit ratio, the research
-token share, and the estimated cost. Call out the most expensive subtask or
-agent, a low cache-hit ratio, or research cost that looks high relative to
-Actor/Monitor. Then STOP — do not change code from this skill.
+Emit exactly this report shape, then STOP (this skill never changes code):
+
+```text
+Tokens (<branch>): in <I> / out <O> / cache_rd <CR> / cache_cr <CC>
+Cache-hit ratio: <X>%   ·   Est. cost: $<C>   ·   Research share: <R>%
+Most expensive: <subtask|agent> ($<amount>)
+Flags: <low cache-hit | high research cost | none>
+```
+
+Fill every field from the `token_report` output. If a value is unavailable, write `n/a` — never omit a line or invent a number.
 
 ## Examples
 

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-debug/SKILL.md.jinja

@@ -334,7 +334,7 @@ This is **completely optional**. Run it when debugging patterns are valuable for
 - Check for similar issues in other parts of the codebase when Predictor flags them or the root cause pattern is reusable.
 - Use the Task tool to call the specialized subagents in the sequence above.
 
-## Example
+## Examples
 
 User says: `/map-debug TypeError in authentication middleware`
 
@@ -349,12 +349,8 @@ You should:
 Begin debugging now.
 
 
-## Examples
-
-```
-/map-debug <typical args>
-```
-
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** A fix is applied before the root cause is identified. **Fix:** Stop and return to investigation — Debugging Constraints require root cause first.
+- **Issue:** The same bug pattern may exist elsewhere. **Fix:** Check sibling code when Predictor flags it or the root cause is reusable (see "Debugging Constraints").
+- **Issue:** The session was interrupted mid-workflow. **Fix:** Run `/map-resume` to recover.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-fast/SKILL.md.jinja

@@ -178,9 +178,12 @@ Begin now with minimal workflow.
 ## Examples
 
 ```
-/map-fast <typical args>
+/map-fast add a --verbose flag to the status command
+/map-fast fix the off-by-one error in the pagination offset
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** Task turns out risky, multi-stage, or ambiguous. **Fix:** Stop using `/map-fast`; switch to `/map-efficient` or `/map-plan` (see "When Not To Expand Scope").
+- **Issue:** A subtask exceeds 3 iterations without passing Monitor. **Fix:** Report it as a blocker/tradeoff — do not loop or fake-complete (see "Critical Constraints").
+- **Issue:** The session was interrupted mid-workflow. **Fix:** Run `/map-resume` to recover.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-memory-now/SKILL.md.jinja

@@ -32,6 +32,15 @@ as a maintenance sweep over multiple unfinalized scratches.
 
 ---
 
+## Constraints (NEVER)
+
+- **NEVER** edit code, run a workflow, or make commits beyond the digest from this skill — it only finalizes memory.
+- **NEVER** hand-write or edit a digest `.md` or scratch `.jsonl` directly; only `finalize_dirty` writes them (it is atomic — a failed digest is left unfinalized for retry, never half-written).
+- **NEVER** modify the user's `.gitignore` or flip `MAP_MEMORY_COMMIT_DIGESTS` for them — if the user wants digests kept local, instruct them; do not change it automatically.
+- **NEVER** let a digest carry secrets or credentials.
+
+---
+
 ## Arguments
 
 - `$ARGUMENTS` empty or `--finalize-all` — both run the full sweep (finalize ALL dirty

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-release/SKILL.md.jinja

@@ -1176,7 +1176,7 @@ Use these MCP tools throughout the workflow:
 | Gate # | Gate Name | Failure Impact | Can Proceed? | Fix Action |
 |--------|-----------|----------------|--------------|------------|
 | 1 | Pytest tests | High | ❌ NO | Fix failing tests |
-| 2 | Black format | Medium | ❌ NO | Run black --fix |
+| 2 | Pyright + hook lint | Medium | ❌ NO | Fix pyright / hook-lint errors (part of `make lint`) |
 | 3 | Ruff lint | Medium | ❌ NO | Fix linting errors |
 | 4 | Mypy types | Low | ⚠️ Review | Fix type errors (recommended) |
 | 5 | Package build | High | ❌ NO | Fix build config |
@@ -1265,9 +1265,11 @@ Begin now with the release request above.
 ## Examples
 
 ```
-/map-release <typical args>
+/map-release                            # full release workflow; bump type is chosen at the confirmation gate
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** `make check` (Gate 1) fails. **Fix:** Stop — fix every lint/type/test failure before any tag or publish step; the release gates are hard stops, not warnings.
+- **Issue:** `__version__` is out of sync after `bump-version.sh`. **Fix:** Apply the documented `__version__` sync workaround in Phase 1 before continuing.
+- **Issue:** A tag or PyPI publish step failed midway. **Fix:** Follow the rollback scenario for that phase; never re-run an irreversible step blindly.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-skill-eval/SKILL.md.jinja

@@ -12,6 +12,18 @@ Purpose: measure whether a `/map-*` skill fires on the right prompts and what it
 
 Requires the `claude` CLI (installed and on `$PATH`). The skill is skipped at install time on hosts without `claude`.
 
+## Constraints (NEVER)
+
+- **NEVER** plan or implement from this skill — it only measures trigger accuracy and cost. For work, use `/map-plan` or `/map-efficient`.
+- **NEVER** launch a non-dry-run `run`/`optimize` when the eval-set size or quota cost is unknown — run `--dry-run` first to see the call budget (each case spends a real `claude -p` call).
+- **NEVER** hand-edit the durable run log (`.map/eval-runs/<skill>/*.jsonl`) or `*-optimize.json` results — `--resume` and `view` depend on their integrity.
+- **NEVER** auto-commit an `--apply` change — `--apply` only stages the re-rendered description; review the diff, and patch `skill-rules.json` `description` by hand (it is not auto-patched).
+
+## Before reporting (self-check)
+
+- Confirm the run completed (not interrupted) — if it was, re-run with `--resume`; do not report a partial pass-rate.
+- Confirm the reported pass-rate equals passed/total and every case has a verdict.
+
 ## Invocation
 
 ```bash
@@ -83,7 +95,7 @@ mapify skill-eval run map-plan --eval-set .map/evals/map-plan.json --resume
 ## Troubleshooting
 
 - **`claude` not found** — `map-skill-eval` requires the `claude` CLI on `$PATH`. Install it and re-run `mapify init` to activate the skill.
-- **Eval-set validation error on `--dry-run`** — check that each case has a non-empty `id`, a `prompt`, and at least one `assertions` entry with a valid `type`.
+- **Eval-set validation error on `--dry-run`** — check that each case has a non-empty `prompt` (the only required field); that `should_trigger` / `should_not_trigger`, if present, are strings; and that every `assertions` entry has a valid `type`. Cases carry no user-supplied `id` — `cell_id`s like `p0-v1-r2` are derived automatically.
 - **Run log not found for `--resume`** — `--resume` looks for the latest `.map/eval-runs/<skill>/<timestamp>.jsonl`. If no prior run exists, omit `--resume` to start fresh.
 - **All cases report `not_trigger` unexpectedly** — verify the skill name matches exactly (e.g. `map-plan`, not `map_plan`) and that `.claude/` was seeded correctly in the temp cwd.
 

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-state/SKILL.md.jinja

@@ -1,6 +1,6 @@
 ---
 name: map-state
-version: "1.0.0"
+version: "3.1.0"
 description: >-
   Branch-scoped MAP planning in `.map/`. Use when the user needs a
   persistent task plan, progress tracking, or resume support across
@@ -147,6 +147,16 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 
 **Why**: Prevents race conditions, ensures consistent state, clear ownership.
 
+## Constraints (NEVER)
+
+These are hard rules — each one protects shared, persistent state. If a task seems to require violating one, STOP and ask the user.
+
+- **NEVER** write `task_plan` `**Status:**` from any agent other than Monitor. task-decomposer creates the plan; Monitor owns every subsequent status transition (see Single-Writer Governance). An agent that needs a status change must surface it, not write it.
+- **NEVER** hand-edit `step_state.json`. It is the canonical orchestrator state — mutate it only through `.map/scripts/` orchestrator calls. If the API cannot express what you need, STOP and ask; do not write the file as a fallback.
+- **NEVER** read, write, or delete another branch's `.map/<other-branch>/` tree. Scope is strictly the current branch.
+- **NEVER** set a `**Status:**` outside the defined vocabulary — phase statuses are `pending`, `in_progress`, `complete`; terminal states are listed under "Terminal States". Unknown values break the Stop-hook terminal-state check.
+- **NEVER** commit secrets, tokens, or credentials into plan / progress / research files.
+
 ## Best Practices
 
 - **Goal clarity**: Specific, measurable outcomes
@@ -154,14 +164,6 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 - **Checkpoint frequently**: Update status immediately after completion
 - **Terminal state early**: Mark `blocked` as soon as blocker identified
 
-## Error Handling
-
-| Issue | Fix |
-|-------|-----|
-| Plan not found | Run `init-session.sh` |
-| Stop hook warns "No terminal state" | Update `## Terminal State` section |
-| Branch name with `/` | Scripts sanitize: `feature/auth` → `feature-auth` |
-
 ## Terminal States
 
 | State | When |
@@ -223,7 +225,7 @@ Only Monitor agent updates task_plan status (via `status_update` output field).
 
 ---
 
-**Version**: 1.0.0 (2025-01-10)
+**Version**: 3.1.0
 
 **References**:
 - [planning-with-files](https://github.com/OthmanAdi/planning-with-files) - Original pattern

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-tdd/SKILL.md.jinja

@@ -37,7 +37,7 @@ parallel_tool_policy: sequential_red_green_gate
 ## Execution Flow
 
 ```
-Standard:          DECOMPOSE → ACTOR (code+tests) → MONITOR
+Non-TDD baseline:  DECOMPOSE → ACTOR (code+tests) → MONITOR   (= /map-efficient, shown for contrast — NOT a /map-tdd mode)
 Targeted TDD:      DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → CONTRACT_HANDOFF → STOP
 Targeted Resume:   /map-task ST-001 → ACTOR (code only) → MONITOR
 Full-workflow TDD: DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → ACTOR (code only) → MONITOR
@@ -281,7 +281,6 @@ Task(
   description="TDD: Implement subtask [ID] to make tests green",
   prompt=f"""You are in TDD CODE_ONLY mode.
 
-
 <MAP_Contract>
 [AAG contract from decomposition]
 </MAP_Contract>
@@ -289,21 +288,18 @@ Task(
 <TDD_Mode>code_only</TDD_Mode>
 
 <TDD_Tests>
-[List test files created by TEST_WRITER]
+{test_files_list}
 </TDD_Tests>
 
 STRICT RULES:
-1. Write ONLY implementation code. Do NOT modify test files.
+1. Write ONLY implementation code. Do NOT modify test files (the files in <TDD_Tests> are READ-ONLY).
 2. Your goal: make ALL existing tests pass (turn Red → Green).
 3. Read the test files first to understand what behavior is expected.
 4. Implement the minimum code needed to satisfy the tests.
 5. Follow the AAG contract as your specification.
 
-Test files (READ-ONLY):
-{test_files_list}
-
 Output: standard Actor output (approach + code + trade-offs)
-
+"""
 )
 ```
 
@@ -378,9 +374,12 @@ In TDD mode, `TEST_WRITER` and `TEST_FAIL_GATE` still write into the same branch
 ## Examples
 
 ```
-/map-tdd <typical args>
+/map-tdd ST-003                         # write spec-derived tests for one planned subtask, then stop
+/map-tdd add idempotency keys to the payment capture endpoint
 ```
 
 ## Troubleshooting
 
-- **Issue:** Workflow doesn't behave as expected. **Fix:** Re-read the section above titled 'What this command CANNOT do' (if present) and ensure prerequisites are met. Run `/map-resume` to recover from interruptions.
+- **Issue:** Invoked without a spec or acceptance criteria. **Fix:** Run `/map-plan` first, or use `/map-efficient` (see "What this command does NOT do").
+- **Issue:** Tests pass trivially / mirror the implementation. **Fix:** Ensure TEST_WRITER derives tests from the spec only, before any implementation is in context (see "Key insight").
+- **Issue:** The session was interrupted between the red-phase contract and implementation. **Fix:** Resume with `/map-task ST-00N`.

{mapify_cli-3.17.0 → mapify_cli-3.17.1}/src/mapify_cli/templates_src/skills/map-tokenreport/SKILL.md.jinja

@@ -13,6 +13,14 @@ run spent, attributed to the subtask, phase, and agent that spent them.
 Read-only reporting — this skill does not plan, implement, or run quality
 gates.
 
+## Constraints (NEVER)
+
+This skill is strictly read-only reporting.
+
+- **NEVER** edit code, state, or git from this skill — it renders an existing rollup and stops.
+- **NEVER** run or resume a MAP workflow here; if work is needed, hand off to `/map-efficient`.
+- **NEVER** present `est_cost_usd` as a billing source of truth — it is a per-model estimate.
+
 The numbers come from the `map-token-meter` hook (wired on `SubagentStop` and
 `Stop`), which reads each Claude Code transcript's per-turn `usage` block and
 appends attributed rows to `.map/<branch>/token_log.jsonl`, rolled up into
@@ -66,10 +74,16 @@ jq '{aggregate, by_agent, by_phase, research_roi}' ".map/${BRANCH}/token_account
 
 ### Step 4: Summarize
 
-Report the totals (input / output / cache), the cache-hit ratio, the research
-token share, and the estimated cost. Call out the most expensive subtask or
-agent, a low cache-hit ratio, or research cost that looks high relative to
-Actor/Monitor. Then STOP — do not change code from this skill.
+Emit exactly this report shape, then STOP (this skill never changes code):
+
+```text
+Tokens (<branch>): in <I> / out <O> / cache_rd <CR> / cache_cr <CC>
+Cache-hit ratio: <X>%   ·   Est. cost: $<C>   ·   Research share: <R>%
+Most expensive: <subtask|agent> ($<amount>)
+Flags: <low cache-hit | high research cost | none>
+```
+
+Fill every field from the `token_report` output. If a value is unavailable, write `n/a` — never omit a line or invent a number.
 
 ## Examples