@ansonlai/docx-redline-js 0.7.0 → 0.7.2

package/docs/AGENT_FAST_START.md

@@ -1,57 +1,55 @@
 # Agent Fast Start
 
-Use this page for ordinary `.docx` edits. For source changes or unusual Word structures, follow the links at the end.
+Use this page for ordinary `.docx` edits. For unusual Word structures or optional shortcuts, follow the links at the end.
 
 ## Structured agent tool
 
-If your host provides a document-session wrapper:
+If the host provides a document-session wrapper:
 
-1. Inspect/search once with enough surrounding context to draft the change.
-2. Apply with the revision-bound handle and complete desired text or exact replacements.
-3. Treat only `ok: true` as complete; refresh failed handles before reuse.
+1. Inspect once with enough surrounding context to draft the change.
+2. Apply once with the returned revision-bound handle.
+3. Accept only the wrapper's complete-success result; refresh failed handles.
 
-The repository's `examples/agent-session-wrapper.mjs` demonstrates this pattern.
-It is a development sample, not a package API.
+The repository's `examples/agent-session-wrapper.mjs` is a development sample, not a package API.
 
-## CLI fallback
+## CLI workflow
 
-1. For a literal mechanical edit with known old and new text, try one-turn apply:
-
-   ```bash
-   docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-   ```
-
-   The source must occur in one eligible paragraph. For text after a heading, add `--search "Section 4.1" --context-range 1:3`.
-   `--around 3` is symmetric; use it only when either side is eligible.
-
-2. For semantic drafting such as “make this provision mutual,” extract enough
-   context, then copy `exactText` with `paragraphId` or `fingerprint`:
+1. Extract the relevant clause or range:
 
    ```bash
    docx-redline extract contract.docx --search "termination" --around 3
    ```
 
-   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. Apply once with a UTF-8 operations file or serializer-backed stdin:
+   Search is case-insensitive. Follow `selection.nextAfter` when truncated. Preserve `selection`, `humanReference`, target descriptors, and revision cues when reshaping output. Report `humanReference`, not a machine paragraph number.
+
+2. Retain inspected `exactText` for drafting and target with its `paragraphId` plus `fingerprint`, then apply once with a UTF-8 operations file or serializer-backed stdin:
 
    ```bash
    node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
    ```
 
-   Use `JSON.stringify`, not shell interpolation. `modified` is the complete desired accepted-view paragraph.
+   Use complete `modified` text for a broad semantic revision. For a small literal change in that inspected target, use
+   `replacements: [{ "find": "old text", "replace": "new text" }]` instead.
+   Use `JSON.stringify`; never interpolate document text through shell quoting. Preserve intentionally relative wording unless the user asks for a concrete value.
+
+## Restore branch
 
-The `agent` profile preserves progressive execution and the ordinary revision policy while making incomplete work exit nonzero. Add `--atomic` deliberately; check `effectiveOptions`. Run `docx-redline apply --help` for redline, comment, and rejected-view restore shapes.
+If the user requests deleted text, search with `--view rejected` first. Otherwise follow `selection.hint` only when it identifies an alternate revision view. Restore the inspected strong target; do not infer adjacent content. Run `docx-redline apply --help` for canonical restore shapes.
 
-## Batch and result rules
+## Completion and recovery
 
-- Strong inspected targets bind to the batch start; independent edits need no bottom-up sorting.
-- Consolidate writes to one source; use captures for created-content dependencies.
-- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error. For localized edits also require `change.committed: true`
-  and `change.verification.acceptedViewMatchesCompiledText: true`. The source is
-  not overwritten unless `--in-place` is explicit.
-- On failure, follow `error.recovery.action`. Never retry unchanged arguments.
-- `retryPlan.base: "original"` means replay the batch; `"output"` means retain committed work and retry reported indexes.
-- Never accept/reject revisions or remove comments without user authorization. `slice-cross-author` preserves history for edits inside foreign insertions.
+- Require `completion: true` and a non-null `outputPath`; the CLI computes this from write, operation, commit, and localized-verification results.
+- On failure, follow `error.recovery.action`; never retry unchanged arguments.
+- Use `retryPlan.base: "original"` to replay a batch and `"output"` to retain
+  committed progressive work and retry the reported indexes.
+- The source is not overwritten unless `--in-place` is explicit.
+- Never accept/reject revisions or remove comments without authorization.
+- Add `--atomic` or a non-default revision policy only when deliberately needed;
+  confirm `effectiveOptions`.
+- Strong inspected targets bind to batch start. Consolidate writes to one source
+  and use captures only for intentional created-content dependencies.
 
-Advanced operations and recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md); canonical contract: [document-operations.schema.json](schemas/document-operations.schema.json)  
+Advanced speculative apply, directional scoping, operation constraints, and
+recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md). Canonical schema:
+[document-operations.schema.json](schemas/document-operations.schema.json).
 Wrapper design: [README](../README.md#example-agent-session-wrapper-development-only)

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -476,63 +476,41 @@ The canonical machine-readable contract is
 `docs/schemas/document-operations.schema.json`. Read that schema or the examples
 here instead of grepping bundled implementation code.
 
-#### Standard Workflow (Fast & Direct)
-
-Use this for everything by default. `apply` is fast, progressive, and self-validating by default—it validates the resulting package and revision markup internally before writing. **Do not insert a `preflight` or baseline `validate` step on top of it "to be safe"**; `apply` already covers that internally. It supports inline one-liners as well as batch operations files:
-
-The short route for a document-editing request is:
-
-1. For an exact mechanical change with known old and new literals, use localized
-   `--find`/`--replace`. Omit the target for global fail-closed resolution, or
-   scope a visible heading with `--search` and a directional range such as
-   `--context-range 1:3`. Repeated anchor matches are unioned; one eligible patch
-   paragraph is still required. `--occurrence` selects only within that paragraph.
-2. For semantic drafting, run one focused `extract`. Add `--around 3` when
-   surrounding context on either side is needed, then copy `exactText` plus
-   `paragraphId` or `fingerprint`.
-3. Build the final operations from the operation table above. Use one operation
-   per target paragraph, and consolidate multiple changes to that paragraph.
-4. Run `apply` once per stable batch. Strong inspected targets are bound against
-   the batch-start document, so independent operations do not need manual
-   bottom-up sorting around structural edits. Consolidate multiple complete
-   desired states for the same source. A unique exact reference to paragraph
-   text created elsewhere in the batch is scheduled automatically; use explicit
-   captures/selectors for non-unique or advanced created-content dependencies.
-5. Walk every result and require `completion: true`, `written: true`, and no
-   per-operation error. For localized patches also require committed `change`
-   evidence and positive accepted-view verification.
-6. Run a focused `extract` on changed clauses only when placement or list/table
-   structure needs confirmation.
-
-Do not probe operation behavior with disposable apply commands or read a vendor
-bundle before this route. If `apply` returns an error, use the recovery matrix
-below and make one cause-specific correction.
-
-```bash
-# 1. Globally unique mechanical edit in one call
-docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+#### Standard Workflow (Extract Then Apply)
+
+Use this for ordinary edits. `apply` validates the resulting package and
+revision markup internally before writing, so do not add `preflight` or baseline
+`validate` merely for reassurance.
+
+1. Run one focused `extract`. Add `--around 3` when surrounding context is
+   needed. Retain `exactText` for drafting and target with `paragraphId` plus
+   `fingerprint`.
+2. Build one final operation per target. Use complete `modified` text for broad
+   semantic revisions or localized `replacements` for small literal changes in
+   an inspected target. Consolidate multiple changes to one paragraph.
+3. Run `apply` once per stable batch. Independent strong targets bind against
+   the batch-start document and do not need bottom-up sorting. Use captures only
+   for intentional created-content dependencies.
+4. Require `completion: true` and a non-null `outputPath`. The CLI derives
+   completion from write status, operation outcomes, commit disposition, and
+   localized accepted-view verification.
+5. Run a focused post-apply extraction only when placement or structural output
+   needs confirmation.
+
+If `apply` returns an error, follow the recovery envelope below and make one
+cause-specific correction. Do not probe behavior with disposable mutations or
+read a vendor bundle.
 
-# 2. Mechanical edit strictly within three paragraphs after a visible heading
-docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# 3. Focused contextual discovery for semantic drafting
+```bash
+# 1. Focused contextual discovery
 docx-redline extract contract.docx --search "termination" --around 3
 
-# 4. Inline complete-paragraph edit
-docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
-
-# 5. Direct edit without tracked changes (clean text, no revision clutter)
-docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
-
-# 6. Cross-author edit inside another reviewer's pending insertion
-docx-redline apply contract.docx --target "Pending clause text" --modified "Updated clause text" --existing-revisions slice-cross-author --output reviewed.docx
-
-# 7. Batch operations with ops.json
-docx-redline apply contract.docx --operations operations.json --output reviewed.docx
-
-# 8. Serializer-backed stdin with compact stdout
+# 2. Serializer-backed apply against the inspected target
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+
+# Optional clean edit without tracked changes
+docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
+```
 
 Key CLI defaults and behaviors:
 - **Author**: Automatically defaults to `'AI Redliner'` (overridable via `--author` or `DOCX_REDLINE_AUTHOR` environment variable).
@@ -544,9 +522,36 @@ Key CLI defaults and behaviors:
 - **Agent profile**: `--profile agent` enables complete-success exit behavior but preserves progressive execution and the ordinary revision policy. Compose it with `--atomic` or an explicit `--existing-revisions` choice when intended; resolved values appear in `effectiveOptions`.
 - **Operation transport**: A UTF-8 operations file and serializer-backed `--operations -` are peers. Use whichever the host can construct without interpolating legal text in the shell.
 - **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML, full validation arrays, and duplicate nested receipts. Top-level `receipts` is authoritative. Pass `--compact` for one-line JSON; run `validate` for full issue records.
-- Check `completion: true`, `written: true`, and a non-null `outputPath` on stdout. `completion` is derived from the write result, top-level status, and every operation status, so failed, partial, and unwritten work cannot appear complete. If an error occurs, inspect `error.code` or `results[i].error.code` (e.g. `TARGET_NOT_FOUND`, `ANCHOR_NOT_FOUND`) before correcting the cause and re-applying.
+- Check `completion: true` and a non-null `outputPath` on stdout. Failed,
+  partial, rolled-back, unverified, and unwritten work cannot appear complete.
+  If an error occurs, follow `error.recovery.action` before correcting the cause.
 
-For multi-clause or multi-page reviews, apply edits **section-by-section** or clause-by-clause (e.g., using `--in-place` on a working copy) rather than bundling dozens of edits into one massive batch. This keeps context compact, simplifies error diagnosis, and prevents cascading anchor drift.
+For multi-clause or multi-page reviews, use focused batches rather than one
+massive batch. This keeps context compact and simplifies error diagnosis.
+
+#### Optional Speculative Localized Apply
+
+Targetless localized apply remains available to expert users and harnesses with
+a measured confidence policy. It is not the ordinary agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique phrase
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+Omitting a target asks the CLI to resolve one eligible paragraph. Generic or
+repeated anchors union their windows and may produce `AMBIGUOUS_TARGET`, costing
+a recovery turn. `--around 3` is symmetric; `--occurrence` disambiguates only
+inside an already selected paragraph. `anchorMatchCount > 1` signals a repeated
+anchor even after a successful edit. Matching is exact and case-sensitive first,
+then permits only ASCII-space/NBSP equivalence; ambiguity still fails closed.
+
+Localized `change` evidence retains bounded before/after excerpts, commit
+disposition, and accepted-view verification for audit consumers. Ordinary
+agents rely on the computed top-level `completion` signal.
 
 #### High-Assurance / Staged Verification Workflow (Optional)
 
@@ -590,6 +595,13 @@ Paragraph indexes are 1-based. Inspection filters are `--index 12`,
 case-insensitive. When a search returns 0 matches in the active view but matches
 exist in the alternate view (such as searching for a deleted clause to restore),
 `selection.hint` provides immediate guidance to re-run with `--view rejected`.
+Compact `extract --revised` results retain `hasRevisions`, `revisionAuthors`,
+and `deleted`/`inserted` cues, so an empty `exactText` is identifiable as content
+hidden by the selected revision view rather than a failed filter.
+For one strongly identified rejected-view paragraph, `apply --restore
+--target-id ID` restores the rejected text verbatim. One exact
+`--find`/`--replace` pair may adjust it without restating the paragraph. The
+shortcut refuses ranges, captures, weak targets, and inferred adjacent content.
 Add `--around N` (`--context N` or `-C N`) to a search;
 context records are labeled separately and do not consume the direct-hit
 `--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary

package/docs/SKILL_AUTHORING.md

@@ -1,86 +1,76 @@
 # Skill and Harness Authoring Contract
 
-Use this page when creating or updating an agent skill, MCP server, or custom
-harness for `@ansonlai/docx-redline-js`. Ordinary document-editing agents should
-load [Agent Fast Start](AGENT_FAST_START.md), not this design contract.
+Use this page to create or update an agent skill, MCP server, or custom harness
+for `@ansonlai/docx-redline-js`. Ordinary editing agents should load
+[Agent Fast Start](AGENT_FAST_START.md), not this design contract.
 
 > [!WARNING]
-> Before 1.0, every skill or harness must identify and pin its exact tested
-> library release and required CLI contract/capabilities. Treat any different
-> release or contract as unverified until compatibility tests pass.
+> Before 1.0, every integration must identify and pin its exact tested library
+> release and required CLI contract/capabilities. Treat any different release or
+> contract as unverified until compatibility tests pass.
 
-For example, an integration authored for the current contract-8 release should
-record a compatibility declaration equivalent to:
+Example declaration for a contract-8 shell integration that uses localized
+operations over stdin:
 
 ```json
 {
-  "testedLibraryRelease": "0.7.0",
+  "testedLibraryRelease": "0.7.1",
   "requiredCliContractVersion": 8,
   "requiredCapabilities": [
-    "command-help-v1",
+    "operations-stdin",
+    "agent-safety-profile-v2",
     "recovery-envelope-v1",
-    "localized-replacements-v1",
-    "speculative-search-apply-v1",
-    "localized-change-summary-v1"
+    "localized-replacements-v1"
   ]
 }
 ```
 
-The package pin anchors the release; runtime negotiation proves the executable
-exposes the required contract. A new release cannot inherit an old claim.
-
 ## Runtime negotiation
 
-Run this before the first document operation when the skill vendors or invokes
-the CLI:
-
-```bash
-docx-redline version
-```
+Run `docx-redline version` before the first document operation. Require CLI
+contract version 8 and only the capabilities the integration actually uses. Check once per stable
+runtime, fail closed when a requirement is absent, and never inspect bundles or
+ZIP parts as a fallback.
 
-Require contract version 8 (the currently declared contract) and only the
-capabilities the integration uses. A typical shell skill should require
-`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`recovery-envelope-v1`. Require other capabilities only when used. Fail closed
-when one is absent; never inspect bundles or ZIP parts as a fallback.
+Do not expose negotiated but unused capabilities as choices in the editing
+prompt. `command-help-v1`, restore shortcuts, speculative apply, and localized
+change summaries are optional requirements only for integrations that use them.
 
 ## Safety invariants
 
-Every generated integration must preserve these rules:
+Every generated integration must:
 
-- Inspect narrowly and copy `exactText` plus `paragraphId` or `fingerprint`.
-- Treat `modified` as the complete desired accepted-view target content.
-- Use strict targeting, package validation, and a derived output path; never
-  overwrite the source unless the caller explicitly requests `--in-place`.
-- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error before reporting completion.
-- Never accept or reject another reviewer's work or delete comments without
-  explicit user authorization.
-- Never retry unchanged failed arguments.
+- inspect narrowly, retain `exactText`, and target with `paragraphId` plus
+  `fingerprint`;
+- use strict targeting, package validation, and a derived output path;
+- never overwrite the source unless `--in-place` is explicitly requested;
+- require `completion: true` and a non-null `outputPath` before reporting
+  success;
+- follow `error.recovery.action` and never retry unchanged failed arguments; and
+- require explicit authorization before accepting/rejecting another reviewer's
+  work or deleting comments.
 
-The `agent` profile enables complete-success exit behavior and retains the
-ordinary progressive default. It does not select atomic execution or a special
-existing-revision policy. A skill must state those choices explicitly when its
-workflow needs them.
+The CLI computes `completion` from write status, operation outcomes, commit
+disposition, and localized accepted-view verification. Preserve the detailed
+results for audit and recovery, but do not make the editing agent re-evaluate
+those fields during ordinary success handling.
 
 ## Workflow policy choices
 
-Choose and document these separately from safety invariants:
+Keep these exceptions separate from the default workflow:
 
-| Choice | Options | Guidance |
+| Choice | Default | Override only when |
 |---|---|---|
-| Transaction | progressive default or `--atomic` | Use progressive for independent edits; use atomic when partial output is unacceptable. |
-| Existing revisions | `merge-same-author` default or explicit policy | Use `slice-cross-author` only when editing inside another reviewer's pending insertion is intended. |
-| Reviewer identity | flag, operation author, environment, or fallback | `AI Redliner` is a valid visible fallback. `DOCX_REDLINE_AUTHOR` is an optional harness preference, not a guard. |
-| Output naming | derived sibling or explicit destination | Keep source immutability unless in-place mutation is deliberately authorized. |
+| Transaction | progressive | Partial output is unacceptable (`--atomic`). |
+| Existing revisions | `merge-same-author` | Editing inside another reviewer's pending insertion is intended (`slice-cross-author`). |
+| Reviewer identity | `AI Redliner` is a valid visible fallback | The host supplies a preferred flag, operation author, or environment value. |
+| Output | derived sibling | The caller deliberately selects another destination. |
 
-Check `effectiveOptions` rather than assuming the resolved transaction,
-revision, author, or redline policy.
+Check `effectiveOptions` when an integration deliberately sets a policy.
 
 ## Transport choices
 
-A UTF-8 operations file and serializer-backed stdin are peer transports. Choose
-the form the host can construct safely:
+A UTF-8 operations file and serializer-backed stdin are peer transports:
 
 ```bash
 docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
@@ -88,45 +78,46 @@ node emit-operations.mjs | docx-redline apply input.docx --operations - --profil
 ```
 
 Use `JSON.stringify` or a structured tool API. Never demonstrate `echo`, a
-heredoc, or shell-interpolated legal text. `--compact` changes stdout formatting,
-not result semantics. A Node byte-oriented wrapper should call `openDocx` and
-return the full structured result rather than recreating the CLI serializer.
+heredoc, or shell-interpolated document text. A Node byte-oriented wrapper should
+call `openDocx` and return the structured result instead of recreating CLI
+serialization, ZIP handling, targeting, validation, or rollback.
 
 ## Ordinary generated workflow
 
-For an exact mechanical edit whose existing and replacement literals are known,
-the first executable example should use the one-turn fast path:
+The first executable editing example in a generated skill must be focused
+extraction:
 
 ```bash
-docx-redline apply input.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+docx-redline extract input.docx --search "renewal notice" --around 3
 ```
 
-If the literal is not globally unique, scope it with a meaningful visible
-anchor. A heading followed by a multi-paragraph provision should use a
-directional window such as `--search "Section 4.1" --context-range 1:3`;
-`--around 3` is symmetric and should be used only when either side is eligible.
-Require the returned localized `change` evidence, including `committed: true`
-and `verification.acceptedViewMatchesCompiledText: true`.
+Then apply once using the inspected strong target. Use complete `modified` text
+for a broad semantic revision or `replacements` for a small literal change in
+that target. Keep requested relative wording relative unless the user asks for
+a concrete value.
 
-Semantic requests such as “make this provision mutual” still begin with focused
-contextual extraction because the agent must identify and draft the complete
-legal change:
+Follow `selection.nextAfter` when extraction is truncated. Output projections must retain
+`selection`, target descriptors, `humanReference`, and revision
+cues.
 
-```bash
-docx-redline extract input.docx --search "termination" --around 3
-```
+### Observed restore branch
+
+If the user requests restoration, search `--view rejected` first. Otherwise
+follow an alternate-view `selection.hint` when returned. Restore only the
+inspected strong target. Require `restore-shortcuts-v1` only if the integration
+uses inline `--restore`; canonical operations remain available.
+
+### Optional speculative execution
 
-Use `selection.nextAfter` with `--after` when truncated. When a search for
-deleted or restorable content yields 0 matches in accepted view, follow
-`selection.hint` and re-run with `--view rejected`. Apply once per stable batch.
-Run `docx-redline apply --help` for canonical redline, whole-paragraph comment,
-and rejected-view restore shapes; CLI help documentation fields return canonical
-GitHub URLs. The operation schema remains
-[document-operations.schema.json](schemas/document-operations.schema.json).
+Do not make speculative apply part of an ordinary generated workflow. A harness
+may opt into `speculative-search-apply-v1` only when it owns a measured confidence
+policy and accepts the recovery cost of a miss. Keep anchor selection,
+directional windows, occurrence handling, and exact matching semantics out of
+the ordinary editing prompt; link to the knowledge base or CLI help instead.
 
 ## Recovery contract
 
-Lead error handling with exactly these runtime fields:
+Lead failure handling with these runtime fields:
 
 1. `error.recovery.action`
 2. `error.recovery.requiresReinspection`
@@ -134,32 +125,23 @@ Lead error handling with exactly these runtime fields:
 4. `error.recovery.sameArgumentsSafe`
 
 Use `retryPlan.base` and its operation indexes to select the original or partial
-output package. Do not generate a second prose decision tree for every error
-code; error messages and bounded diagnostics explain the cause, while the four
-fields above determine the next action.
+output package. Do not reproduce an error-code decision tree in the skill.
 
 ## Presentation rules
 
-Use `humanReference`, `provision`, or `nearestHeading` in user-facing completion
-reports. `P55`, `index: 55`, and phrases such as “the 55th paragraph” are machine
-targeting and pagination coordinates, not locations a Word user can follow.
-When no formal heading exists, use the returned short text lead. Never replace
-an exact machine target with a human-facing reference.
+Use `humanReference`, `provision`, or `nearestHeading` in completion reports.
+Paragraph indexes and `P55`-style references are machine coordinates, not
+locations a document user can follow. Keep the exact machine target internally.
 
 ## Generation checklist
 
-- The exact tested library release is recorded and pinned; floating installs
-  are rejected while the library remains before 1.0.
-- The required CLI contract version and minimum capability set are declared,
-  checked at runtime, and updated only after compatibility tests pass.
-- Runtime version and required capabilities are checked once.
-- Literal edits use localized replacements and one-turn speculative apply;
-  semantic drafting starts with focused extraction.
-- Successful localized edits require committed, post-mutation `change`
-  verification before completion is reported.
-- Safety invariants are not mixed with transaction or revision-policy choices.
-- Operations-file and stdin examples use structured serialization.
-- The four-field recovery contract precedes any diagnostic commentary.
-- Completion prose uses legal references rather than machine ordinals.
-- The wrapper delegates mutation, validation, rollback, comments, numbering,
-  receipts, and OOXML packaging to the library.
+- Exact tested release, contract 8, and the minimum capability set are pinned.
+- Runtime compatibility is checked once.
+- The first ordinary command is focused extraction.
+- Apply uses the inspected target with `modified` or localized `replacements`.
+- Restore appears only as a user-requested or observed-view branch.
+- Speculative execution is absent unless the harness owns a measured policy.
+- Ordinary success requires `completion: true` and a non-null `outputPath`.
+- Recovery, authorization, source immutability, and structured serialization
+  invariants are preserved.
+- Wrappers delegate mutation and OOXML packaging to the library.