overleaf-review 0.5.0 → 0.6.1

package/README.md

@@ -186,7 +186,8 @@ and keep independent decisions separate. Author attribution remains unchanged.
 Blocks must be separated and must explain the entire local diff. The plan embeds the resolved
 blocks; it never rereads or silently reinterprets the manifest during submission. Concurrent edits
 outside blocks are preserved; any comment, pending suggestion, or concurrent edit touching a block
-stops planning rather than silently fragmenting it. Narrow the block or resolve the conflict.
+stops ordinary block planning rather than silently fragmenting it. For deliberately reviewed
+overlaps, use the manifest fields below; otherwise narrow the block or resolve the conflict.
 `--edits` requires `--file` and a saved base; it cannot be combined with `--direct` or `--unsafe-no-base`.
 
 Without explicit blocks, tracked suggestions group nearby word edits into phrase replacements. For example, rewriting
@@ -208,6 +209,87 @@ Overlap transformations can alter the actual count, so this is a preflight guard
 exact prediction. Splitting a revision into batches does not remove accumulated pending ranges.
 Grouping applies to new pushes; it does not consolidate or accept suggestions already on Overleaf.
 
+### Holistic paragraph rewrites over reviewed suggestions and comments
+
+Use this when a paragraph rewrite intentionally incorporates or supersedes existing suggestions.
+
+To regroup existing fragmented suggestions **without changing their proposed wording**, set
+`before` and `after` to the same paragraph text and explicitly list the suggestion IDs in
+`supersedes`. Keep the local file unchanged for that block. This is supported from v0.6.1;
+the proposal must still differ from the underlying text obtained by rejecting those suggestions.
+Affected comments still require explicit anchor mappings, and all stale-plan and verification
+checks still apply. Ordinary replacements without selected suggestions cannot be no-ops.
+It differs from consolidation: the proposed text may change, and selected older suggestion cards
+are replaced by a new pending revision under the authenticated account.
+
+Fetch the current text/review state, edit the local file, and extend the normal block manifest:
+
+```json
+{
+  "replacements": [
+    {
+      "before": "The current paragraph, including pending suggestions.",
+      "after": "The coherently rewritten paragraph. Its explanation incorporates the correction.",
+      "supersedes": ["existing-change-id-1", "existing-change-id-2"],
+      "reason": "Incorporates the correction into a more coherent explanation.",
+      "comments": [
+        {
+          "thread": "existing-thread-id",
+          "anchorAfter": "Its explanation incorporates the correction.",
+          "reply": "Rewritten to incorporate your correction and clarify the explanation."
+        }
+      ]
+    }
+  ]
+}
+```
+
+```sh
+overleaf-review review plan --file main.tex --edits blocks.json --out reviewed-plan.json
+overleaf-review review submit --plan reviewed-plan.json
+```
+
+The `supersedes`, `comments`, or `reason` fields select reviewed-overlap planning automatically.
+Every block needs a paragraph-level `reason`. Omit `supersedes`/`comments` or use empty arrays
+when that block has no corresponding overlaps. `reply` is optional. Use `occurrence` in a comment
+mapping when `anchorAfter` occurs more than once in the revised block. To highlight the entire
+revised paragraph, set `anchorAfter` equal to `after`.
+
+The tool lists unapproved overlapping IDs and threads. All fragments of each selected suggestion
+and the full affected comment anchor must be contained in its approved block; it will not silently
+expand the scope. Suggestions from other authors may be explicitly superseded. Their original
+content and attribution are retained in the full plan/receipt, not falsely attributed to the new
+revision. Existing thread IDs, messages, author metadata, and resolution state are preserved;
+only approved anchors move. Suggestions and comments outside the blocks retain their identities
+and content, with positions shifted as needed.
+
+The plan shows **underlying**, **current**, and **proposed** text for each block. The underlying
+text excludes the selected pending suggestions. Submission undoes those ranges and writes the
+new whole-block revision, then reanchors the existing threads in the same OT update. It does
+not accept older suggestions first. Rejecting the new revision restores that underlying text;
+it does not recreate the old suggestion cards. Later manual review uses Overleaf's native anchor
+behavior; this command is not a background service that restores anchors after future rejections.
+
+Reviewed rewrites require a saved plan and synchronization base, use a separate plan kind, and
+cannot be forced with `--allow-overlap`, `--direct`, `--unsafe-no-base` or `--acknowledge-ambiguous`.
+Any unapproved overlap, changed local intent, or changed document/review state before submission
+blocks the write. Coordinate a quiet editing window: the server does not provide a conditional
+transaction spanning text, ranges and threads, and post-write verification is not a rollback.
+
+Replies are posted only after the manuscript, anchors, range identities, author attribution and
+rejection baseline have been verified. A receipt separately tracks text verification and each
+reply. If a definite reply failure leaves follow-up pending, resubmitting the same plan resumes
+without rewriting the manuscript. A lost reply acknowledgement can be reconciled from its new
+message ID or an unambiguous new same-author message; without proof it remains quarantined and
+is not automatically reposted. An uncertain text update always requires manual reconciliation.
+Keep the plan and receipts when resuming; do not use a fresh plan to bypass an uncertain attempt.
+
+Verification: `npm run probe:reviewed-model` covers other-author suggestions and existing-thread
+reanchoring against pinned upstream range logic. The opt-in
+`npm run probe:reviewed-live -- --project <test-id> --confirm-test-project` creates a new scratch
+document and threads, verifies anchor movement, a reviewed rewrite, explanatory reply and retry,
+and checks existing documents were unchanged. It does not impersonate another account.
+
 ### Consolidation of existing suggestions
 
 `review consolidate --doc main.tex --author <user-id> --out .overleaf/consolidation.json`