mapify-cli 3.32.0__tar.gz → 3.34.0__tar.gz

mapify_cli-3.34.0/.claude/skills/README.md

@@ -0,0 +1,82 @@
+# MAP Skills System
+
+MAP ships Claude Code skills as the runtime slash surface for MAP workflows and as supporting reference material. Skills are not agents, but they are not all passive documentation either: some skills define task procedures that call agents, run scripts, or write workflow artifacts.
+
+## Skill Classes
+
+MAP uses `skillClass` in `skill-rules.json` to make the runtime role explicit.
+
+| Class | Use For | Runtime Boundary |
+|-------|---------|------------------|
+| `reference` | Conventions, heuristics, explanations, and decision support | Loads knowledge into the current session; should not own a deterministic workflow |
+| `task` | Manual slash workflows such as `/map-efficient`, `/map-review`, and `/map-learn` | May orchestrate agents, run validation, and write artifacts when invoked |
+| `hybrid` | Operational guidance with supporting hooks/scripts, currently `map-state` | Provides reference guidance and declares explicit `runtimeEffects` for hook or artifact side effects |
+
+`type` and `enforcement` still describe activation behavior. `skillClass` describes what the skill is allowed to do after it is invoked.
+
+## Current Classification
+
+| Skill | Class | Notes |
+|-------|-------|-------|
+| `map-state` | `hybrid` | Explains branch-scoped planning and ships hooks/scripts that surface focus and completion checks |
+| `map-learn` | `task` | Model-invocable slash workflow; writes learned rules from a completed workflow handoff |
+| `map-plan`, `map-efficient`, `map-fast`, `map-debug`, `map-tdd`, `map-task`, `map-check`, `map-review`, `map-resume`, `map-release`, `map-explain` | `task` | Skill-backed slash workflows invoked directly by the user |
+
+## Skills vs Agents
+
+| Skills | Agents |
+|--------|--------|
+| Loaded through the Skill surface or invoked as slash workflows | Launched through the Task tool by a workflow |
+| Define instructions, policies, hooks, scripts, and supporting files | Perform specialized analysis, implementation, review, or learning work |
+| Own provider-facing runtime contracts under `.claude/skills/` | Own role-specific prompts under `.claude/agents/` |
+| May call agents when the skill is a task workflow | Do not define slash surfaces themselves |
+
+## File Structure
+
+```text
+.claude/skills/
+├── skill-rules.json                  # Activation and skillClass metadata
+├── README.md                         # This file
+├── map-state/
+│   ├── SKILL.md
+│   └── scripts/
+├── map-learn/
+│   ├── SKILL.md
+│   └── templates/
+└── map-*/SKILL.md                    # Skill-backed MAP slash workflows
+```
+
+## Authoring Guidance
+
+Use a `reference` skill when the content is mostly durable knowledge: conventions, decision trees, examples, troubleshooting, or domain guidance. Reference skills should be safe to load opportunistically and should avoid owning multi-step mutation procedures.
+
+Use a `task` skill when the skill behaves like a workflow: it has required steps, validation gates, agent calls, file writes, commits, releases, or other deterministic procedures. Task skills advertise an `argument-hint` and retain `enforcement: manual` as routing metadata, not a model-invocation block. All MAP skills are model-invocable except `map-release`, which alone keeps `disable-model-invocation: true`. Descriptions and negative triggers control routing; in-skill confirmation gates still apply, including version-specific major-upgrade consent in `map-upgrade`.
+
+Use `hybrid` only when both are true: the skill is useful as reference material, and it also ships runtime helpers such as hooks or scripts. Hybrid skills must list `runtimeEffects` in `skill-rules.json` so users can tell which behavior comes from reading instructions and which behavior comes from installed hooks or scripts.
+
+Keep `SKILL.md` focused on invocation policy, decision rules, and navigation to supporting files. Move long examples, troubleshooting matrices, and templates into supporting files so invoked skill content stays compact.
+
+## Template Sync
+
+The development copy under `.claude/skills/` must stay byte-for-byte synced with `src/mapify_cli/templates/skills/`, because `mapify init` installs the template copy into user projects.
+
+Use:
+
+```bash
+make render-templates
+pytest tests/test_skills.py tests/test_template_render.py -v
+```
+
+## Troubleshooting
+
+### Skill metadata drift
+
+Run `pytest tests/test_skills.py -v`. The suite checks frontmatter, direct invocation metadata, skillClass values, hybrid runtime effects, trigger rules, supporting-file links, hook script paths, and template sync.
+
+### Generated project does not match this branch
+
+Run `uv run mapify init <new-temp-path> --no-git --mcp none` from this repo. Do not use a globally installed `mapify` binary for branch validation because it can lag behind local templates.
+
+### New task skill is not invocable
+
+Check that the skill has `argument-hint`, the direct `map-*` name appears in `skill-rules.json` keywords and intent patterns, and `skillClass` is `task`.

mapify_cli-3.34.0/PKG-INFO

@@ -0,0 +1,382 @@
+Metadata-Version: 2.5
+Name: mapify-cli
+Version: 3.34.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
+Project-URL: Issues, https://github.com/azalio/map-framework/issues
+Author: MAP Framework Contributors
+License-File: LICENSE
+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
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: truststore>=0.9.0; extra == 'dev'
+Provides-Extra: ssl
+Requires-Dist: truststore>=0.9.0; extra == 'ssl'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.0.0; extra == 'test'
+Requires-Dist: jsonschema>=4.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.26.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Requires-Dist: pyyaml>=6.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="MAP Framework — Plan-then-build AI coding. You approve the plan before the model writes a line of code.">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/mapify-cli/"><img src="https://badge.fury.io/py/mapify-cli.svg" alt="PyPI version"></a>
+  <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
+  <a href="https://github.com/azalio/map-framework"><img src="https://img.shields.io/github/stars/azalio/map-framework?style=social" alt="GitHub stars"></a>
+</p>
+
+After `mapify upgrade`, Claude can invoke any MAP skill through the Skill tool on your behalf except `/map-release`, which remains manual-only. Workflow confirmation gates still apply; `/map-upgrade` requires explicit consent for a major version.
+
+## Why MAP Exists
+
+Most AI agents rush straight to code — fast wrong answers, silent rework.
+
+<p align="center">
+  <img src="./assets/readme/loop.svg" width="100%" alt="Without MAP: idea, prompt, code, hope. With MAP: SPEC, PLAN, TEST, CODE, REVIEW, LEARN — a closed loop.">
+</p>
+
+Common failure modes MAP eliminates:
+
+- AI silently makes architecture decisions you did not approve.
+- One prompt produces a large diff that is hard to review.
+- Tests are written around the generated implementation, including its mistakes.
+- The output compiles, but you cannot explain why the design is correct.
+- The next session forgets the gotchas you already paid to discover.
+
+MAP moves engineering judgment earlier: write down the behavior, split the work into small contracts, verify each stage, review against the spec, and save lessons for the next run.
+
+Skill maintainers can use `mapify skill-eval optimize <skill> --provider claude|codex --apply`
+to update only the selected provider's description in the shared template source;
+the opposite provider stays unchanged ([details](docs/USAGE.md#skill-description-optimization)).
+
+## Quick Start
+
+<p align="center">
+  <img src="./assets/readme/section-quickstart.svg" width="100%" alt="Quick Start — install, init, run the loop">
+</p>
+
+**1. Install**
+
+```bash
+uv tool install mapify-cli
+
+# or with pip
+pip install mapify-cli
+```
+
+Requires Python 3.11+, and `python3` on your `PATH` must be that interpreter — the
+installed hooks and `.map/scripts/` runners execute through a `#!/usr/bin/env
+python3` shebang, not through the interpreter that ran `mapify`. `mapify init`
+checks it up front and tells you what to fix ([details](docs/INSTALL.md#why-python3-on-path-matters)).
+For Go projects requiring build tags, set `checks.go.tags: integration,netgo` in
+`.map/config.yaml` for the Stop hook's build check ([configuration](docs/USAGE.md#end-of-turnsh-stop)).
+
+**2. Initialize your project**
+
+Claude Code is the default provider. Cross-AI review compares explicit host and
+reviewer adapter vendors; same-vendor or unknown provenance is not labeled
+independent ([details](docs/USAGE.md#cross-ai-peer-review---cross-ai-runtime)).
+An [offline historical review corpus](docs/USAGE.md#offline-historical-review-corpus)
+provides pinned introducing diffs, adjudicator-only labels and audited controls.
+It starts no reviewers and makes no evaluation or policy-promotion claims.
+An opt-in [bounded subscription pilot](docs/USAGE.md#bounded-subscription-review-pilot)
+adds offline preparation/reporting and a separately acknowledged, at-most-six-call
+Claude CLI runner. Its v2 inputs are complete allowlisted `-U30` diffs; prompts
+estimated above 60,000 tokens are excluded, never truncated. Results require
+manual adjudication; historical v1 runs cannot be resumed.
+
+Claude Code:
+
+```bash
+cd your-project
+mapify init
+claude
+```
+
+Codex CLI:
+
+```bash
+cd your-project
+mapify init . --provider codex
+codex
+```
+
+The generated `.codex/config.toml` enables hooks. On first use, review and trust
+the project hook configuration when Codex prompts you; `/hooks` shows the eight
+installed lifecycle event groups.
+
+**3. Run the loop**
+
+Claude Code:
+
+```text
+/map-plan → /map-efficient → /map-check → /map-review → /map-learn
+```
+
+Codex CLI:
+
+```text
+$map-plan → $map-efficient → $map-check → $map-review → $map-learn
+```
+
+That's the whole golden path.
+
+Need to reorder unstarted work in an active run? Use the audited
+[`resequence_pending` command](docs/USAGE.md#reorder-pending-subtasks)
+without resetting the current step, retries, results or baselines.
+
+- **Start with `/map-plan`** for anything non-trivial — it clarifies behavior and splits the work into contract-sized subtasks.
+- **Starting from a PRD?** Run `/map-prd-review` directly, or accept `/map-plan`'s optional readiness preflight. A non-ready result shows the gaps and asks whether to revise or continue planning anyway.
+- **Already scoped?** Go straight to `/map-efficient`.
+- **Tiny edit?** `/map-plan` off-ramps you to a direct edit or `/map-fast` instead of forcing full planning.
+- **Too foggy to plan?** `/map-wayfind` resolves open design decisions on a durable map. Evidence-first research is on by default: factual lookups stay light; uncertain decisions get independent investigations and targeted checks, with no default attempt cap for authorized read-only work. Opt in at task start with `configure_research --budget-limit N`; existing caps remain binding and extensions require scoped user approval. Consequential or genuinely expensive actions still need separate consent. Stale open-ticket evidence can be explicitly refreshed without erasing history or resetting that budget. Research handoffs are checked before `/map-plan`; historical decisions retain explicit legacy provenance.
+- **Want one entry point?** `/map-auto` routes and drives the chain autonomously; hard-stops only on `dangerous_action`/`safety_guardrail` holds.
+
+> Codex CLI ships the same 23 MAP skill entry points and invokes them with `$`:
+> `$map-plan`, `$map-efficient`, `$map-check`, and so on. See the
+> [Usage Guide](docs/USAGE.md#codex-cli-provider).
+
+**Framework updates.** Automatic stable updates are enabled by default. Normal
+MAP skills check at most once per project every 24 hours, apply eligible patch
+and minor releases, and ask before a major release after showing its official
+feature highlights. Rejecting a major offer is remembered per project for that
+exact version, so it is not offered again; any different patch, minor, or major
+version is offered normally. Use these project controls and provider-specific
+manual skills when needed:
+
+```text
+mapify init . --no-auto-update   # persist updates.auto: false
+mapify init . --auto-update      # re-enable automatic checks
+/map-upgrade                     # Claude manual check/upgrade
+$map-upgrade                     # Codex manual check/upgrade
+```
+
+Automatic failures stay silent so they do not block the requested workflow;
+manual checks report errors explicitly. The public `mapify upgrade` command is
+separate and unchanged: it upgrades only the CLI and does not refresh project
+files. See [Automatic and manual framework updates](docs/USAGE.md#automatic-and-manual-framework-updates).
+
+If a legacy `map-debug` skill cannot load its `../../references/` documents, refresh
+the project after upgrading the CLI:
+`mapify init . --force --no-git --provider codex --refresh-existing`
+(use `--provider claude` for Claude). This restores missing managed references;
+upgrading the CLI alone does not.
+
+## Case Study: 90 days → 7 days
+
+The DevOpsConf 2026 case study applies this process to a production Kubernetes Project Operator:
+
+- human estimate: **90 days**
+- MAP-style delivery: **7 days**
+- workflow: `SPEC → PLAN → TEST → CODE → REVIEW → LEARN`
+- small reviewable PRs instead of one giant generated diff
+- tests before implementation for critical pieces
+- semantic bugs caught in review before merge
+
+[DevOpsConf 2026 case study →](https://github.com/azalio/devopsconf-ai-develop)
+
+## When To Use MAP
+
+| Good fits | Poor fits |
+|-----------|-----------|
+| Complex backend features | Typos and tiny edits |
+| Kubernetes controllers and operators | Small one-off scripts |
+| Internal platform tooling | Product ideas where behavior is still unknown |
+| API, CRD, or domain-model changes with invariants | Broad rewrites without clear boundaries |
+| Refactoring with a meaningful test harness | Tasks cheaper to do directly than to plan |
+
+## Core Commands
+
+| Command | Use For |
+|---------|---------|
+| `/map-auto` | Single-entry autonomous autopilot: routes a task through existing MAP workflows and drives the chain to a committed branch |
+| `/map-plan` | **Start here** for non-trivial work; clarify behavior and decompose tasks |
+| `/map-prd-review` | Review a PRD with a 0-10 readiness score, strengths, risks, and uncovered edge cases |
+| `/map-wayfind` | Too foggy to plan? Resolve design decisions on a durable map *before* `/map-plan` |
+| `/map-efficient` | **Implement** an approved plan or already-scoped task |
+| `/map-fast` | Small, low-risk changes where full planning is overhead |
+| `/map-check` | Quality gates, verification, and artifact checks |
+| `/map-review` | Pre-commit semantic review against the plan, tests, and diff |
+| `/map-learn` | Capture project memory and reusable lessons |
+| `/map-understand` | Interactive teaching and quiz mode for code, diffs, and workflow results |
+| `/map-debug` | Bug fixes and debugging |
+| `/map-task` | Execute a single subtask from an existing plan |
+| `/map-tdd` | Test-first implementation workflow |
+| `/map-release` | Package release workflow; Codex `$map-release` shares the same commit-bound CI gates |
+| `/map-resume` | Resume interrupted workflows |
+
+For stacked PRs, use `/map-review --base-ref runtime` (Codex: `$map-review --base-ref runtime`) to review only the child branch's changes against its parent's merge-base, including dirty work. Trusted review policy still comes from the default branch.
+
+[Detailed usage and options →](docs/USAGE.md)
+
+## Why Engineers Stick With It
+
+- **Daily-driver speed** — optimized for repeated use, not occasional demos. Structured enough to prevent chaos, lightweight enough to keep token and time cost under control.
+- **Reviewable diffs** — `/map-plan` and `/map-efficient` require per-subtask size, concern, and constraint metadata, then validate `blueprint.json` *before* implementation, so oversized or mixed-concern plans fail early.
+- **Gates that check the plan, not vibes** — `/map-check` and `/map-review` validate against the spec, tests, and diff instead of asking whether code "looks fine".
+- **Clean-room review** — `/map-review` auto-bundles available spec, plan, tests, verification, and coverage evidence into a single durable input (`.map/<branch>/review-bundle.json`); standalone external-PR review needs no Actor blueprint. `--detached` opens a read-only worktree for inspection without touching your branch.
+- **Bounded review/fix cycles** — `/map-review` retains round history and unresolved findings across restarts, suppresses acknowledged repeat publications, and stops after three unsuccessful attempts for reconsideration—not approval. Explicit abandonment recovers stale pending rounds without resetting that budget. Incremental re-review falls back to full review when baseline or dependency coverage is uncertain.
+- **Snapshot-bound review receipts** — review completeness, code approval, runner-executed checks and human consent are separate records. Missing reviewers, scope gaps or stale evidence cannot approve a changed snapshot. Read-only reviewers receive base/current source and attribution in the bundle; Codex findings remain available with explicit `INCOMPLETE` status until capability enforcement is verified.
+- **Trusted review policy (shadow rollout)** — root and applicable ancestor `REVIEW.md` guidance comes from pinned default-branch Git objects, not proposed head content. Its hash joins the existing runtime/capability fingerprint; unknown authority prevents approval. New security/consent gates default to **shadow**: record diagnostics and pending snapshot/policy/action-bound holds without new blockers or weakening existing checks. Opt into **strict** with `review: {security_gates: strict}` in trusted-default `.map/config.yaml`; sensitive/unknown changes then require full coverage and independent security receipts regardless of auto/quick or disabled ledger enforcement. Human provenance is not yet verifiable: holds never become consent, and strict review-ready stays blocked. Corpus and evaluated promotion remain later #523 stages.
+- **Evidence-backed findings** — the existing Step A.3 separates confirmed defects, refuted claims and insufficient evidence. Validation checks the failure scenario, reachability and baseline; remediation searches a bounded scope for the same bug class. Adversarial agreement requires independent evidence-backed validations, not votes. Author reactions cannot close findings on their own.
+- **Project memory** — `/map-learn` turns hard-won fixes and gotchas into reusable context, so the next session doesn't relearn them. Automatic session memory also records bounded, redacted prompt topics and conservative tool observations, even outside a MAP workflow; observed references are not proof of successful outcomes. See [session memory](docs/USAGE.md#session-memory) for limits and recovery behavior.
+
+<details>
+<summary><b>More under the hood</b> — calibrated effort, mutation boundaries, token budgets, retry quarantine, run-health diagnostics, skill IR audit</summary>
+
+- **Calibrated workflow effort** — each shipped slash skill declares a `thinking_policy` and `parallel_tool_policy`, so lightweight commands stay direct while planning, review, and release workflows reserve deeper reasoning and parallel fan-out for the stages that benefit.
+- **Mutation boundary constraints** — write-capable Claude and Codex surfaces tell agents not to edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask requires it. With `worktree.isolation: off`, Actor write checks inspect main even when a recovery worktree remains on disk.
+- **Live isolation dispatch gate** — before concurrent Actor fan-out, `auto` isolation falls back to sequential on dirty or unsupported checkouts; `required` isolation stops dispatch instead. Wave guidance forwards the live decision and warning.
+- **Context-first prompt envelopes** — high-context prompts wrap branch artifacts in XML-style `<documents>`, then state the `<task>` and `<expected_output>`, so specs, diffs, logs, and schemas stay separated for the model.
+- **Contract-sized subtasks** — blueprints require `expected_diff_size`, `concern_type`, `one_logical_step`, `hard_constraints`, `soft_constraints`, and `coverage_map`. Hard constraints must be owned in `coverage_map` and cited in the owning subtask.
+- **Token budget and research ROI reports** — Actor and review prompt builders append active-path budget decisions to `.map/<branch>/token_budget.json`, while `token_accounting.json` and `/map-tokenreport` separate research-agent/researcher cost from Actor/Monitor cost.
+- **Clean retry quarantine** — after repeated Monitor rejection, write-capable workflows switch the next attempt into clean-retry mode using `.map/<branch>/retry_quarantine.json` instead of raw failed-session context.
+- **Run health report** — workflows write `.map/<branch>/run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status, and advisory signals. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`. All runner subcommands support read-only `--help` / `-h`; for example, `python3 .map/scripts/map_step_runner.py write_run_health_report --help`.
+- **Lossless serial blocker repair** — standalone repositories and linked Git worktrees are supported; independently approved repairs run in a private checkout with their own Monitor and full gate, preserving the paused task's phase, results, retries and dirty files. Concurrent waves and overlapping repair paths fail closed; see [the repair protocol](docs/USAGE.md#independent-serial-blocker-repair).
+- **Compact recovery surface** — `/map-resume` keeps the active recovery flow short and moves low-frequency notes to `resume-reference.md`, so recovery after `/clear` or context exhaustion gives the next checkpoint action without loading the whole appendix.
+- **Skill IR audit** — release checks lower shipped Claude and Codex `SKILL.md` files into a typed `SkillIR`, verify content hashes, catch unsupported frontmatter, reject missing supporting-file links, and block injection-like instructions before `mapify init` copies surfaces into user repos.
+
+</details>
+
+## How It Works
+
+MAP orchestrates specialized roles through slash commands and skills:
+
+```text
+TaskDecomposer → breaks goals into subtasks
+Actor          → implements scoped tasks
+Monitor        → validates quality and blocks invalid output
+Predictor      → analyzes impact for risky changes
+Learner        → captures reusable project memory
+```
+
+For Claude Code, MAP slash surfaces live in `.claude/skills/map-*/SKILL.md` files
+created by `mapify init`. For Codex CLI, `mapify init . --provider codex` creates
+the matching 23 `.agents/skills/` entries, nine `.codex/agents/*.toml` roles,
+eight lifecycle event groups under `.codex/hooks.json`, and the same shared
+`.map/scripts/` runtime. The only provider-specific UI exception is Claude's
+command-driven dynamic status-line renderer. Codex supports project-level
+`[tui].status_line`, but only as an ordered list of built-in item identifiers,
+so MAP does not install the Claude renderer there.
+
+MAP is inspired by the [MAP cognitive architecture](https://github.com/Shanka123/MAP) (Nature Communications, 2025), which reported a 74% improvement on planning tasks. The CLI turns that idea into a practical software-development workflow.
+
+[Architecture deep-dive →](docs/ARCHITECTURE.md)
+
+## What Success Looks Like
+
+After a good first workflow, you should see:
+
+- a written plan or spec before implementation starts;
+- small implementation contracts instead of one giant AI diff;
+- verification and review artifacts under `.map/<branch>/`, including runner-executed acceptance proofs rather than self-reported AC checkboxes;
+- review comments focused on correctness and semantics, not formatting noise;
+- `/map-learn` preserving project rules, gotchas, and handoffs for future sessions.
+
+MAP review is useful, but it is not a replacement for engineering judgment. Serious changes still need human review. The goal is to make that review smaller, earlier, and better grounded.
+
+## Options
+
+<details>
+<summary>Minimality doctrine, context-compression policy, SOFA, and other init flags</summary>
+
+**Minimality doctrine** (controls how strongly MAP pushes Actor/Monitor/Evaluator toward the smallest sufficient safe change):
+
+```yaml
+# .map/config.yaml
+minimality: lite   # default for ALL projects; set 'off' to opt out
+```
+
+Allowed values: `off`, `lite`, `full`, `ultra`. The global default is `lite`. `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 with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout telemetry with `mapify minimality-report --json`.
+
+**Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):
+
+```bash
+mapify init . --compression never                 # default — no nudge
+mapify init . --compression auto                  # nudge at threshold
+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. When a policy other than `never` is active, MAP offloads large tool outputs 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:
+
+```bash
+mapify init . --sofa            # opt-in: enable the map-so-search skill
+```
+
+This writes `sofa.enabled: true` to `.map/config.yaml` and adds `.sofa/` to your `.gitignore`. Without the flag, no SOFA code path runs. See the [SOFA usage guide](docs/USAGE.md#stack-overflow-for-agents-sofa).
+
+**Autonomy posture** (`--autonomy`, claude provider) — **off by default**, opt-in "YOLO-minus-git":
+
+```bash
+mapify init . --autonomy        # auto-approve most tools; keep git commit/push for the human
+mapify init . --no-autonomy     # remove the autonomy posture
+```
+
+`--autonomy` writes a broad auto-approve allowlist plus a `git commit`/`push` deny into the **per-user, gitignored** `.claude/settings.local.json` (the committed team `.claude/settings.json` stays the secure baseline). The git block is enforced by the `safety-guardrails.py` PreToolUse hook. Omit the flag to leave existing local settings untouched on re-init. See the [autonomy usage guide](docs/USAGE.md#autonomy-posture-yolo-minus-git).
+
+</details>
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Installation](docs/INSTALL.md) | All install methods, PATH setup, troubleshooting |
+| [Usage Guide](docs/USAGE.md) | Workflows, examples, cost optimization, playbook |
+| [Prompt Library](docs/PROMPT_LIBRARY.md) | Copyable prompt recipes by SDLC phase and role |
+| [Architecture](docs/ARCHITECTURE.md) | Agents, MCP integration, customization |
+| [Platform Spec](docs/MAP_PLATFORM_SPEC.md) | Platform refactor roadmap, codebase analysis |
+
+## Trouble?
+
+- **Static analysis reports `local: -n: invalid option` on macOS** → Update MAP and refresh your provider's installed project files (`mapify init . --refresh-existing`, adding `--provider codex` for Codex). The Go/mypy diagnostic parser supports system Bash 3.2; upgrading Bash is not required for this parser. Re-run analysis rather than trusting an earlier empty report.
+
+- **Command not found** → Run `mapify init` in your project first.
+- **`init` stops on a Python version** → `python3` on your `PATH` is older than 3.11; the hooks run under it. Install 3.11+ (`brew install python@3.12` / `uv python install 3.12`), then `mapify check`. To install anyway, pass `--skip-python-check` or set `MAPIFY_SKIP_PYTHON_CHECK=1` — hooks stay non-functional until `python3` is upgraded ([details](docs/INSTALL.md#why-python3-on-path-matters)).
+- **A hook printed "MAP requires Python 3.11 or newer"** → same cause, detected at run time; the message names the interpreter it ran under. Context hooks report and let the session continue; the two PreToolUse gates (`safety-guardrails.py`, `workflow-gate.py`) deny the tool call instead of allowing it unguarded, so fix `python3` in another terminal to unblock.
+- **Agent errors** → Check `.claude/agents/` has all shipped agent `.md` files, or run `mapify doctor`.
+- **Poor output on a complex task** → Start with `/map-plan` and feed `/map-efficient` the approved plan instead of asking it to infer the architecture.
+- [More help →](docs/INSTALL.md#troubleshooting)
+
+## Contributing
+
+Improvements welcome: prompts for specific languages, new agents, provider integrations, and CI/CD workflow support.
+
+## License
+
+MIT
+
+---
+
+Start with `/map-plan`. Keep the model inside your engineering process, not the other way around.