mapify-cli 3.37.0__tar.gz → 3.38.0__tar.gz

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mapify-cli
-Version: 3.37.0
+Version: 3.38.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

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/pyproject.toml

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

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.37.0"
+__version__ = "3.38.0"
 
 # MUST stay the first import: it turns "this interpreter is older than 3.11" into
 # a message that says so, instead of the ImportError raised by `from datetime

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/src/mapify_cli/delivery/file_copier.py

@@ -14,6 +14,7 @@ import secrets
 import shutil
 import stat
 import subprocess
+import sys
 import tempfile
 import time
 from collections.abc import Generator
@@ -1266,6 +1267,31 @@ def _has_gitignore_marker(lines: list[bytes], marker: str) -> bool:
     return any(line == encoded or line.startswith(encoded + b" ") for line in lines)
 
 
+def _negation_defeats_exclude_entry(negation: bytes, required: bytes) -> bool:
+    """Return whether a ``.gitignore`` negation really overrides an exclude entry.
+
+    Literal entries keep ``_negation_targets_path`` semantics.  For wildcard
+    entries (``**/__pycache__/``, ``.map/**/sessions/``) a negation counts only
+    when it names the entry's basename (``!src/__pycache__/``) or is scoped in a
+    MAP-owned root the runtime block covers (``!.map/scripts/**``).  A blanket
+    re-include under an unrelated directory (``!trivy/bdu-db/data/**``) only
+    re-includes that user subtree and must not push the whole runtime block
+    into the tracked ``.gitignore`` (#649).
+    """
+    if not _negation_targets_path(negation, required):
+        return False
+    base = required.rstrip(b"/")
+    if b"*" not in base:
+        return True
+    pattern = _canonical_gitignore_line(negation[1:]).strip(b"/")
+    return base.rsplit(b"/", 1)[-1] in pattern or pattern.split(b"/", 1)[0] in (
+        b".map",
+        b".claude",
+        b".codex",
+        b".agents",
+    )
+
+
 def _merge_runtime_exclude(
     exclude: Path,
     gitignore_lines: list[bytes],
@@ -1291,7 +1317,7 @@ def _merge_runtime_exclude(
     if not missing:
         return False
     if any(
-        line.startswith(b"!") and _negation_targets_path(line, path.encode())
+        line.startswith(b"!") and _negation_defeats_exclude_entry(line, path.encode())
         for path in missing
         for line in gitignore_lines
     ):
@@ -1355,6 +1381,13 @@ def _merge_project_gitignore_locked(
             if outcome is not None:
                 exclude_changed = outcome
                 missing_runtime_paths = []
+            else:
+                print(
+                    "[mapify: a .gitignore negation overrides info/exclude for "
+                    "a runtime path; writing the runtime block to the tracked "
+                    ".gitignore instead]",
+                    file=sys.stderr,
+                )
         if missing_runtime_paths:
             runtime_lines: list[bytes] = []
             marker = _UPDATE_RUNTIME_GITIGNORE_MARKER.encode()
@@ -1430,6 +1463,13 @@ def _merge_project_gitignore(
         if include_runtime and runtime_to_git_exclude
         else None
     )
+    if include_runtime and runtime_to_git_exclude and runtime_exclude is None:
+        print(
+            "[mapify: info/exclude is unavailable for this project (not a "
+            "repository root, or the repository query failed); writing the "
+            "runtime block to .gitignore]",
+            file=sys.stderr,
+        )
     with _project_gitignore_lock(project_root) as (directory_fd, project_original):
         return _merge_project_gitignore_locked(
             project_root,

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/src/mapify_cli/templates/agents/review-reader.md

@@ -29,18 +29,33 @@ not prove a behavioral defect is pre-existing; require supporting context or mar
 attribution unknown. Request missing bundle content from the parent, never shell.
 
 When the prompt provides parent-served context, return its exact context_request
-JSON and consume context_chunk continuations in this same session. Follow
-next_offset through eof and check offsets, total size and hash metadata against the manifest before using it. Request
-permitted resources from the parent, never read context object paths directly.
+JSON and consume the parent's continuations in this same session. A context_file
+reply names one served file: Read exactly that `path` sequentially from the
+first line to the end (page with offset/limit; do not skip ranges), collect every
+proof fragment the file carries (line 2 states how many there are and how to
+recognise one; they are scattered through the body), then return ONLY a
+context_ack JSON echoing its session_id, context_id, resource_id and sha256 plus
+`nonce` set to all fragments concatenated in file order, or put that object as
+`ack` inside your next context_request. A context_file whose resource_id is `*required`
+holds every listed required resource in one file; one ack covers all of them. A context_chunk reply carries bytes: follow
+next_offset through eof and check offsets, total size and hash metadata against
+the manifest before using it. Read no other context store, object or ledger path;
+request permitted resources from the parent instead.
 These intermediate responses are not findings or final review envelopes.
 Wait for the parent's post-delivery finalization request before returning a final
 review. In structured final envelopes, echo its session_id and finalization_token
 in a context_receipt object.
+Order is fixed: ack, then finalization token, then final. Never return the final
+review before the parent sent its finalization request, and never skip the ack. A
+subagent's handback (the message you end your turn with) contains ONLY the JSON
+envelope the protocol asks for: no prose, no preamble, no code fence, so the parent
+can pipe it verbatim.
 Delivery is parent_acknowledged; it does not prove inspection or capability.
 After receiving needed evidence, return the role's envelope with an additional receipt object:
 `receipt={covered_files:[],skipped_files:[],denied_access:[],check_evidence:[check_id]}`.
 List only paths actually inspected in covered_files; report skipped scope and denied
-required access honestly. Reading claims are self_reported, not tool_witnessed.
+required access honestly. denied_access names only required review scope the parent
+refused to serve; an unread role rubric file is neither skipped nor denied scope. Reading claims are self_reported, not tool_witnessed.
 check_evidence contains only current runner-issued check IDs present in the prompt;
 never claim you ran tests, treat a proposed command as a result, or invent an ID.
 Keep findings even when collection is incomplete. Return output to the parent;

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/src/mapify_cli/templates/codex/agents/review-reader.toml

@@ -27,6 +27,11 @@ These are intermediate responses, not findings or final review envelopes.
 Wait for the parent's post-delivery finalization request before returning a final
 review. In structured final envelopes, echo its session_id and finalization_token
 in a context_receipt object.
+Order is fixed: ack, then finalization token, then final. Never return the final
+review before the parent sent its finalization request, and never skip the ack. A
+subagent's handback (the message you end your turn with) contains ONLY the JSON
+envelope the protocol asks for: no prose, no preamble, no code fence, so the parent
+can pipe it verbatim.
 Delivery is parent_acknowledged; it does not prove inspection or capability.
 After receiving needed evidence, return the role envelope plus
 receipt={covered_files:[],skipped_files:[],denied_access:[],check_evidence:[check_id]}.

{mapify_cli-3.37.0 → mapify_cli-3.38.0}/src/mapify_cli/templates/codex/skills/map-review/review-reference.md

@@ -14,6 +14,10 @@ Admission reports the hold as `human_consent: {status, hold_id, reason, enforcem
 
 Admission and `run_test_gate` stdout are compact: the target omits trusted-policy file contents and lists `context_files_count` instead of the repository inventory, and a check reports `target_unchanged` instead of full `before`/`after` targets. Full rows stay in `review-verdict-ledger.json`.
 
+Resolutions in `resolved_findings` are matched by `finding_id` plus exact `bug_class` and `cause` (copy them verbatim from the carried finding, or omit them). A restated `failure_scenario` is accepted and kept as `resolution_scenario_note`; describe the re-check in `evidence`. An invalid resolution (unknown id, missing evidence, non-originating reviewer, `bug_class`/`cause` mismatch) is rejected on its own: the finding stays open and the ledger lists it under `rejected_resolutions` with the offending `fields`; the rest of the round is still recorded.
+
+Recovery after a failed `write_review_verdict_ledger`: fix or re-capture the offending reviewer output and re-run `write_review_verdict_ledger` for the same round. Only rounds that reached a computed verdict count toward the three-attempt cap; the cap counts rounds where a verdict was recorded in the ledger (including an input-error write that recorded BLOCK). Abandoning a round before any ledger write (recorded as `abandoned_without_verdict`) is an explicit operator choice that costs no attempt; the captured reviewer feedback stays visible in the ledger. A resolution rejected while another resolution for the same finding was accepted is listed with `superseded: true`.
+
 If reviewers could not run for an admitted round, `abandon_review_round` it. A review then done outside the harness is reported as such in the summary; it never produces a ledger verdict or approval.
 
 ## Section Rubrics
@@ -61,12 +65,34 @@ windows, so a line outside every window is unknown, not new. `base:<path>` / `cu
 mapping. A renamed file is windowed against its old blob (`renamed_from`); the old path is a `renamed_to` stub.
 The complete `shadow_risk` record is the optional resource `risk:shadow`.
 
+## Carried Findings
+
+Findings carried from an earlier round are listed compactly (#664): one JSON line each with id, severity,
+`file:line`, a claim cut to 200 characters and status in the diff's review-scope trailer (anything shortened is
+named in a `shortened` field). The originating reviewer's `<carried_findings_for_this_reviewer>` section is the
+complete, untruncated record needed to resolve or re-report: every `affected_files` path, claim, `bug_class`,
+`cause` and `failure_scenario`; a value too long for one line is `{"parts": [...]}` (join without a separator).
+It works without a context server. A shard lists only the findings whose affected
+files it owns, plus findings with no affected file or none inside the admitted scope (every shard lists those,
+compactly). The full ledger row (evidence, validation, reachability, `bug_class`, `cause`) is the optional lazy
+resource `finding:<id>`, frozen and digest-checked like the others; a diff-only reviewer may fetch it only for
+a finding whose evidence it authored. Resolve through `resolved_findings` exactly as before; copy `bug_class`/`cause` from
+the full row or omit them. No published context line exceeds 2,000 characters.
+
 ## Shard Capacity
 
 Shards are packed to the per-reviewer budget minus a measured overhead (the worst scheduled reviewer's
-rendered prompt, inventory, frozen task artifacts and, for Codex, inlined role rubrics, plus a margin;
+rendered prompt, inventory, the `artifacts` index with a bounded spec and, for Codex, inlined role rubrics, plus a margin;
 never below 64 KiB), also for unsharded rounds.
 
+## Task Artifacts
+
+Only a bounded specification (16 KiB, whole lines) is inline in the required `artifacts` resource, with an
+index of every frozen task artifact (`resource_id`, `bytes`, `sha256`, purpose). Plan, blueprint,
+verification summary and test contracts/handoffs are optional lazy resources `artifact:<file name>`: request
+one only when the review needs it. They are frozen from the admitted bundle on first use and digest-checked
+like `repo:`; a reviewer without artifact access (diff-only, user experience, maintainer) cannot fetch them.
+
 ## Windowed Large Files
 
 A changed text file whose full base+current source resource would exceed `review.full_source_max_bytes`
@@ -82,9 +108,13 @@ shard capacity fails admission with `file_too_large`; split that change.
 ## Sharded Rounds
 
 When the required scope does not fit one reviewer's budget, admission plans `row.shards`
-(deterministic, directory-aware, disjoint; at most `review.max_shards`, default 8; the operator-local env `MAP_REVIEW_MAX_SHARDS` (positive int, invalid values ignored) overrides the trusted config and the default, and the `too_many_shards` error hints the exact count needed) and returns
-`shard_ids`. A single file above the per-shard capacity or more than `max_shards` shards fails
-admission with `review_context_budget_exceeded` (`reason: file_too_large | too_many_shards`).
+(deterministic, directory-aware, disjoint) and returns `shard_ids`, `shard_count` and `reviewer_sessions` (shards x scheduled roles x orderings, the native sessions the round runs). The
+shard count is whatever the measured plan needs; only a safety ceiling of 64 stops a runaway
+plan. An explicit operator cap replaces that ceiling: the operator-local env `MAP_REVIEW_MAX_SHARDS`
+(positive int, invalid values ignored), else the trusted `review.max_shards`. A single file above
+the per-shard capacity, or a plan above the cap or ceiling, fails admission with
+`review_context_budget_exceeded` (`reason: file_too_large | too_many_shards`); `too_many_shards`
+reports `max_shards`, `max_shards_source` (`explicit` or `ceiling`) and hints the exact count needed.
 Unsharded rounds never see any of this.
 
 - Every scheduled role reviews every shard; there is no per-role coverage exemption. Loop
@@ -385,21 +415,64 @@ bind its new ID and redeliver all required resources. Another role, agent or
 ordering cannot borrow delivery progress.
 
 Apply this loop before final-schema validation for every reviewer, including
-retries, both ordering collections and the advisory complexity lens:
+retries, both ordering collections and the advisory complexity lens.
+
+`serve_review_context` has two delivery modes, chosen with `--delivery`; the CLI default `auto` picks `file` for
+rounds admitted with file-aware prompts and `chunk` for rounds admitted by an older runner (3.37.0 and earlier), whose
+frozen prompts only know `context_chunk`, and for Codex:
+
+- `file` (for readers with a Read tool such as Claude `review-reader`):
+  the whole resource is served as a small pointer, so its bytes never pass through
+  the parent:
+  `{"status":"context_response","type":"context_file","context_id":"<id>","resource_id":"<rid>","session_id":"<sid>","path":"<abs path>","sha256":"<file sha256>","bytes":<file bytes>,"resource_sha256":"<frozen sha256>","resource_bytes":<frozen bytes>}`.
+  The path is `.map/<branch>/review-context-files/<session-id>/<view-sha256>.txt`:
+  a line-oriented view of the frozen object (JSON expanded, multi-line or long
+  strings printed verbatim as numbered `TEXT` blocks, long blocks cut into
+  `part=n/total` pieces; an overlong single line is cut into pieces flagged `cont=true`,
+  whose first line continues the previous piece's last line with no newline). `sha256`/`bytes` cover the file exactly as published.
+  The proof is k hex fragments, k = ceil(bytes / 16 KiB) clamped to [4, 64], written
+  as ordinary pair lines (`"<key from the view>": "<hex>",`) at runner-chosen random
+  places spread through the body, one per equal byte band of the file (text-heavy
+  files are covered as densely as metadata-heavy ones): before pair lines of the JSON section and between
+  text parts or blocks, never on the first or last lines. There is no fixed prefix,
+  marker, announced position or layout hint; the file's line 2 gives only the
+  fragment count and the per-file token length (the length is chosen so no
+  ordinary content of the file has that shape). Fragments are not stored: the
+  ledger keeps `sha256(concatenation)` only, compared in constant time. The reviewer
+  reads the whole file in order, collects every fragment and returns
+  `{"type":"context_ack","session_id":"<sid>","context_id":"<id>","resource_id":"<rid>","sha256":"<file sha256>","nonce":"<fragments concatenated in file order>"}`,
+  or sends the same object as `ack` inside its next `context_request`.
+  At ACK the runner re-reads the file and requires the exact published bytes
+  (`sha256`), so a body rewritten after serving cannot advance delivery. A pending
+  file answered wrongly three times is invalidated and must be served again, which
+  publishes fresh fragments. Threat model: the proof is reviewer-or-parent-witnessed
+  (the parent can read the file too) and raises the cost of acknowledging unread
+  context; it does not prove comprehension, and a reader that deliberately scans
+  for the stated token shape can still collect the fragments without reading the
+  content.
+  A request for `resource_id` `"*required"` (file delivery only) serves one such
+  file holding every still-unacknowledged required resource; the response adds
+  `resources` (their ids) and one proof ACK marks all of them delivered. Prompts for
+  file readers ask for it first, so delivery takes one round trip per reviewer.
+- `chunk` (fallback for readers without file Read, such as Codex): byte ranges of
+  at most `--chunk-bytes` are relayed through the parent as `context_chunk` JSON.
 
 1. Use `review_context_status` to recover pending work. An existing `pending_chunk`
-   takes priority over `remaining`: replay its resource and offset with
-   `--chunk-bytes` equal to `next_offset - offset` (or smaller), even if another
-   resource appears first in `remaining`. For an agent's
-   `context_request`, call `serve_review_context` with its payload on stdin and
-   `--reviewer <original-role> --round-id <round> --session-id <session> --agent-id <bound-agent>`.
+   takes priority over `remaining`. A pending `context_file` is replayed with
+   `--delivery file` (same path and proof); a pending byte range is replayed at its
+   resource and offset with `--delivery chunk --chunk-bytes` equal to
+   `next_offset - offset` (or smaller), even if another resource appears first in
+   `remaining`. For an agent's `context_request`, call `serve_review_context` with
+   its payload on stdin and
+   `--reviewer <original-role> --round-id <round> --session-id <session> --agent-id <bound-agent>`
+   `--delivery chunk` (native Codex readers cannot be trusted to Read files).
    For an early final response, retain no final capture: create the same request
    shape from the status's next `remaining` resource/offset and continue delivery.
    Required resources include the manifest, full original prompt (unless initially
    inline), the `diff` resource, inventory and source resources marked `required`. Unchanged
    repository files are optional: fetch `repo:<path>` only when needed. Blind stays diff-only
    (prompt and `diff` only).
-2. Store the exact returned chunk JSON in a session-specific pending file under
+2. Store the exact returned JSON in a session-specific pending file under
    `.map/<branch>/review-context-delivery/<session-id>/`, then pass that JSON
    verbatim to the **same agent**:
 
@@ -407,12 +480,20 @@ retries, both ordering collections and the advisory complexity lens:
 followup_task(target=<same agent_id>, message=<context_response JSON>)
 ```
 
-3. Only after the host accepts that followup, pipe the exact stored chunk JSON to
-   `ack_review_context --session-id <session> --agent-id <bound-agent> --round-id <round>`.
-   Serving bytes alone never advances delivery. Do not ACK failed, truncated or
-   unconfirmed host submissions. Crash after acceptance but before ACK: replay the
-   same frozen chunk to the same agent, then ACK; duplicate bytes are identified by
-   offsets/hashes. An ACK replay is idempotent. Continue until `context_ready`.
+3. Acknowledge with `ack_review_context --session-id <session> --agent-id <bound-agent> --round-id <round>`.
+   For a `context_file`, pipe the reviewer's own `context_ack` (or its next
+   `context_request` carrying `ack`) to it; the runner checks the fragment proof against
+   the served file, so a wrong proof or another session's proof is rejected. When the
+   reviewer's reply is a `context_request` with `ack`, run `ack_review_context` first
+   and then `serve_review_context` on the same payload; when it is a bare
+   `context_ack` (`serve_review_context` classifies it as `status:"context_ack"`),
+   serve the next `remaining` resource yourself. For a `context_chunk`, only after
+   the host accepts the followup, pipe the exact stored chunk JSON. Serving bytes
+   alone never advances delivery. Do not ACK failed, truncated or unconfirmed host
+   submissions. Crash after acceptance but before ACK: replay the same pending file
+   or chunk to the same agent, then ACK. An ACK replay is idempotent. Continue until
+   `context_ready`; no `finalization_token` exists before every required resource
+   is acknowledged.
 4. The ready result includes a persisted `finalization_token`. Send a NEW request
    to the same agent: all required context has arrived; finalize now and include
    `context_receipt={session_id,finalization_token}` in the final JSON envelope.
@@ -425,7 +506,7 @@ followup_task(target=<same agent_id>, message=<context_response JSON>)
    The runner independently fences capture and ledger
    completeness; delivery does not prove source inspection or grant approval.
 
-Use `--chunk-bytes 8192` with a shell-tool output budget of at least 65536 tokens
+In chunk mode, use `--chunk-bytes 8192` with a shell-tool output budget of at least 65536 tokens
 (roughly 50 KiB worst-case JSON escaping); use 1024 for a 10000-token capture
 budget. Never forward truncated tool output. A smaller same-offset retry atomically
 replaces the pending chunk without advancing progress; ACK of the superseded
@@ -433,7 +514,7 @@ larger chunk is rejected. The CLI allows 4–65536 source bytes and keeps the 51
 serialized-response limit. Preserve the currently pending tuple on recovery.
 
 `not_context_request` classifies a response; it does NOT prove delivery complete.
-Context requests and queued early finals never consume a malformed-final retry or a
+Context requests, context ACKs and queued early finals never consume a malformed-final retry or a
 review round. A malformed response to the finalization request consumes the one
 malformed-final retry; it cannot be captured without valid receipts.
 Do not increment the dispatch counter for same-agent continuations.
@@ -628,3 +709,9 @@ large and quote-heavy; prefer the file flags written in Step A.2c.
 - Missing bundle: rerun `create_review_bundle` before agents.
 - Oversized reviewer prompt: nothing is clipped and no `token_budget.json` entry is written for review — `MAP_REVIEW_PROMPT_BUDGET_TOKENS` is reported, not enforced. Admitted rounds deliver the full prompt through the context manifest (Step A.2a). Legacy builder calls without an admitted bundle retain the oversized-prompt error; run `begin_review_run` and `create_review_bundle` first.
 - Monitor invalid: treat as hard stop and record `REVISE` or `BLOCK`.
+
+### Delivery protocol notes (#655-#657)
+
+- Order is fixed: ack, then finalization token, then final. A reviewer's handback is only the JSON envelope. A refused final names what to send back (the `context_ack` JSON, the next `context_request` or the `context_receipt`).
+- A `context_request` may carry the previous `context_ack` as `ack`; the runner applies it before serving. Optional resources (`repo:`, `artifact:`, `base:`, `current:`, `risk:`, `check:`) never reset an issued token.
+- `denied_access` blocks only for required files/resources; other entries are informational. For readers with sources an added file's diff hunks are a stub pointing at its `source_*` resource.