overleaf-review 0.4.0 → 0.6.0

package/README.md

@@ -128,8 +128,10 @@ first safe push. If an upgraded repository already has unpushed edits, copy or s
 | `pull [--out <dir>]` | Read comments + tracked changes into a sidecar |
 | `fetch [--file <f>] [--dry-run]` | Write Overleaf text locally, snapshot replaced files, and save Base (read-only on Overleaf) |
 | `review start [--file <f>] [--out <dir>]` | Fetch text, save the synchronization base, and pull the review sidecar |
-| `review plan --out <plan.json> [--file <f>] [--doc <name>] [--direct] [--allow-overlap] [--unsafe-no-base]` | Create a complete binding plan without changing Overleaf |
+| `review plan --out <plan.json> [--file <f>] [--edits <blocks.json>] [--doc <name>] [--direct] [--allow-overlap] [--unsafe-no-base]` | Create a complete binding plan without changing Overleaf |
 | `review submit --plan <plan.json> [--acknowledge-ambiguous]` | Submit that plan only if all recorded preconditions still match |
+| `review consolidate --doc <path> --author <user-id> --out <preview.json> [--change <id> …]` | Preview consolidation of existing suggestions and save a full backup; no Overleaf changes |
+| `review consolidate --apply --plan <plan.json>` | Apply and verify a checked consolidation plan for your own suggestions |
 | `upload <path…> [--folder <name>]` | Upload figures / new files into Overleaf |
 | `push [--file <f>] [--doc <name>] [--direct] [--dry-run] [--plan-out <path>] [--plan <path>] [--allow-overlap] [--unsafe-no-base] [--acknowledge-ambiguous]` | Safely merge and send local edits (all changed `.tex` if no `--file`) |
 | `comment --anchor <text> --message <text> [--doc <name>] [--nth <n>] [--force]` | Add an anchored comment; recent identical retries are skipped unless forced |
@@ -155,6 +157,183 @@ overlapping Base→Local and Base→Live edits abort instead of silently undoing
 work. A proposed edit that intersects an active tracked-change range is also blocked by default and
 the relevant change ids are listed.
 
+For intentional sentence or paragraph rewrites, agents should preserve their chosen edit boundaries
+with `--edits`, rather than relying on automatic diff grouping. Edit the local file normally, then
+describe every change in a JSON manifest:
+
+```json
+{
+  "replacements": [
+    {
+      "before": "This is the old paragraph. Its explanation is unclear.",
+      "after": "This is the revised paragraph. Its explanation is clearer."
+    }
+  ]
+}
+```
+
+```sh
+overleaf-review review plan --file main.tex --edits blocks.json --out plan.json
+overleaf-review review submit --plan plan.json
+```
+
+Each block becomes one deletion and/or insertion, even across multiple sentences or LaTeX markup.
+Overleaf controls the resulting review UI; a replacement is generally two tracked ranges, not a
+guaranteed single accept/reject button. Keep typo corrections small, group a coherent rewrite,
+and keep independent decisions separate. Author attribution remains unchanged.
+
+`before` must match the saved Base exactly. Repeated text requires a 1-based `occurrence`.
+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 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
+“old model predicts low” as “revised model explains high” produces one deletion and one insertion,
+instead of six separate word operations. Isolated corrections stay small. Grouping bridges at most
+three unchanged words (40 characters), limits combined spans to 320 characters, and stops at detected
+sentence/clause boundaries, paragraph breaks, and LaTeX markup. This is a deterministic readability
+heuristic; it does not infer which scientific claims should be accepted together. An existing
+multiword insertion remains a single insertion.
+
+Unchanged comment anchors, tracked ranges, and edits made on Live since Base prevent grouping across
+them. Overlap checks use the full grouped footprint, and submission reproduces the same grouping.
+`--direct` retains the narrower word-level operations. Plans from before this grouping change must
+be regenerated; submitting an old plan does not silently regroup its approved operations.
+
+Planning and submission check a conservative range budget: existing tracked ranges plus proposed
+insert/delete operations must not exceed 2,000 per document. The preview shows both counts.
+Overlap transformations can alter the actual count, so this is a preflight guard rather than an
+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.
+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`
+captures the live text, all document ranges, and project comment threads. It reconstructs the text
+with that author's selected suggestions rejected, then plans a grouped revision back to the current
+proposed text. By default it considers all current suggestions by that author, including older
+fragments; repeat `--change` to select a subset. Use the author user ID from range metadata.
+
+The artifact records both text hashes, a reverse/forward reconstruction proof, projected range
+counts, and any comment or unselected-suggestion blockers. It preserves the *current pending
+proposal*, not a historical review state before older suggestions were absorbed. Consolidation
+would assign new IDs and timestamps. Counts remain projections until server transformations are
+verified. Touching comment anchors or unselected changes blocks the candidate; these are not
+automatically removed or accepted.
+
+For offline analysis, use `--snapshot <file.json>` instead of `--doc`. The snapshot must contain
+`projectId`, `docId`, `docPath`, `version`, `text`, `ranges: { changes, comments }`, and `threads`;
+the preview embeds this complete object as `backup`. A normal review sidecar alone is insufficient.
+
+Planning sends nothing. Inspect the complete plan, then apply it separately:
+
+```sh
+overleaf-review review consolidate --apply --plan .overleaf/consolidation.json
+```
+
+Only suggestions owned by the authenticated account can be reapplied. Blocked/no-reduction plans
+cannot be submitted. The command reproduces the plan from its backup and requires unchanged text,
+document version, ranges, and project threads. It journals the full snapshot before sending undo
+and reapply operations together in one update. It never accepts suggestions as a prerequisite.
+
+Verification checks the proposed text, text with selected suggestions rejected, text with all
+suggestions rejected, disappearance of old IDs, new-ID attribution, reduced range count, and
+unchanged unselected ranges, comment anchors and thread messages. New IDs and timestamps are
+expected. Any uncertain send or failed verification quarantines subsequent attempts: inspect the
+receipt and live document before manually reconciling it; there is no automatic rollback/retry.
+Reusing an already successful plan reports its receipt without sending it again.
+
+Coordinate a quiet editing window for consolidation. Overleaf has no conditional transaction
+covering text, ranges and threads, so preflight cannot prevent every last-moment collaborator race;
+readback detects discrepancies but cannot make an already-sent operation un-happen. A backup is
+recovery evidence, not a promise of automatic review-history restoration.
+
+Development check `npm run probe:consolidation-model` exercises pinned upstream range logic in
+memory without accessing an Overleaf project. The opt-in `npm run probe:review-live -- --project
+<id> --confirm-test-project` creates and retains a new scratch document in the specified test
+project, verifies consolidation and protected review state, and checks that existing documents
+were unchanged. It does not require or spoof another account. Foreign-author preservation is also
+covered by the upstream model check. Never run this probe against a manuscript project.
+
+### Push overrides and submission
+
 Use `--allow-overlap` only after inspecting those tracked changes. `--unsafe-no-base` is a deliberate
 legacy escape hatch that treats the current Live document as Base; it loses the protection against
 co-author edits made since your local file was obtained. `--direct` changes how the validated ops