@mutmutco/cli 4.5.229 → 4.5.231

package/README.md

@@ -58,6 +58,50 @@ Run `mmi-cli --help` for the task map, `mmi-cli commands --json` for bounded mac
 `mmi-cli commands --all --json` manifest names every implementation module and consumer. That inventory
 is checked when the runtime tree is assembled, so a sixth command domain cannot land ownerless.
 
+## Preparing a PR and reading status
+
+`mmi-cli devops pr create` collects independent issue, claim, docs-index, test-policy and ref findings
+in one preparation report. Fix all listed findings before retrying. The read phase never posts claim
+markers. A same-branch resume restamps only after every required check passes; an unsuccessful restamp
+stops creation and is not retried automatically.
+
+Preparation binds the head and target base commits and checks their identity again before
+writes. Docs and policy checks read those committed objects, including the candidate's policy and
+commit trailers, so a dirty local repair cannot certify the pushed branch. A different checkout or
+candidate objects unavailable locally produce an explicit skip; failed reads produce unavailable
+findings. These checks do not replace required CI or verification of the eventual combined candidate.
+
+An absent same-repository head still publishes automatically when this checkout owns that exact branch
+and commit and its push target matches. Preparation observes that proof without writing; after every
+check passes, one push creates the absent ref and verifies the published commit. A competing ref,
+changed proof or ambiguous push stops creation without overwriting or retrying. When `--base` is
+omitted, `branch.<head>.gh-merge-base` wins over the repository default, matching `gh pr create`.
+
+`mmi-cli status --json` retains successful legacy fields and adds typed `observations` for each source.
+An unavailable collection is `null`, never an empty array; unavailable stage state is `null`, never
+`running: false`. A successful empty read stays `[]`. Board observations preserve source, build time,
+event cursor, credential provenance, partial-read warnings and explicit stale age. Text status labels
+unavailable and stale answers. A missing stage file means not running; malformed or unreadable state
+means unavailable. Repair the named read before treating a status count as current.
+
+## Auditing test-policy trailers
+
+`mmi-cli tests policy --json --base <base>` uses the same override reader as the test-command gate.
+Its `overriddenBy` receipt retains the original commit SHA, complete Git-unfolded reason and scope.
+Ordinary trailers agree with `git log --format='%(trailers:key=Test-Policy-Override,valueonly,unfold)'`.
+If a final contiguous `Co-authored-by:` paragraph hides the prior trailer block, the reader removes
+only that paragraph and its optional `---------` separator before running
+`git interpret-trailers --parse --unfold`. The receipt records `messageTransform` as
+`strip-terminal-coauthors` or `strip-squash-separator-coauthors`; the source commit is never rewritten.
+To audit that case, inspect the receipt's SHA with `git show -s --format=%B <sha>`, remove exactly the
+recorded terminal footer, and pass the remaining message to Git's interpreter. That message shape
+alone does not establish GitHub provenance. Intervening prose, mixed footer text, malformed wrapped
+reasons, unknown scopes and untrusted ranges remain subject to the existing refusals.
+
+Native queues can append this footer even for a single source commit. Source preparation is not
+combined-message verification: install the matching shared reader in the CI consumer, then require
+the actual queue candidate to pass test policy and all other required checks.
+
 ## Capability seams — mmi-cli vs jerv-cli (#3000)
 
 `mmi-cli` is the **org** CLI (rules delivery, board/issue/PR work, registry, secrets, release train,