docs: align HPATCH contracts with current grammar

Update documentation and tests for destination-based `add` mutations,
EOF appends, and target-based terminology. Remove obsolete HPATCH/1
state, compatibility, and recovery payload references.

Author: yusing

doc/architecture/index.md

@@ -33,8 +33,7 @@ The workspace owner retains each touched file's invocation-original identity and
 current logical path, pending lifecycle action, and ordered pending splices. Returning to
 a file reuses those values. A successful script orders the splices once and renders one
 original-to-final content value. No command materializes an intermediate baseline, and
-the engine owns no selection, cursor, clipboard, generation, mutable shadow buffer, or
-script-level commit state.
+all targets continue to resolve against the invocation-original content.
 
 One shared pure verified-row owner computes and renders `LINE:HASH` identity for routed
 reads under `REQ-READ-001`, target validation, repair context, and final-state previews.
@@ -97,10 +96,9 @@ and moved paths, last-edit summaries, net file counts, empty-file rows, and cont
 before any external effect. Apply and translation paths share this projection.
 
 The projection borrows completed editor content during rendering and retains no additional
-original or final content copy, routed-read history, translated patch, word diff, selection,
-cursor, clipboard, target, generation, or resume state. Its rows describe only successful
-completed state. The router consumes the rendered report and does not compute coordinates,
-hashes, command extents, or formatting adjustments.
+original or final content copy. Its rows describe only successful completed state. The router
+consumes the rendered report and does not compute coordinates, hashes, command extents, or
+formatting adjustments.
 
 ## CTR-BOUNDARY-001 — Filesystem and output boundary
 

doc/brief.md

@@ -3,10 +3,8 @@
 ## Problem
 
 Agents describe edits with line-oriented diffs that repeat old content and unchanged
-context. HPATCH/1 reduces that repetition, but its separate selector, cursor, clipboard,
-and generation state makes simple mutations multi-command programs. A failed selector or
-state precondition discards the complete atomic script and can consume more output and
-model turns than the successful encoding saves.
+context. Repeating that context increases output, while ambiguous mutation boundaries can
+discard a complete atomic script and consume extra model turns.
 
 ## Outcome
 
@@ -60,8 +58,8 @@ wall time must remain close to control.
 - Private hgrep commands accept familiar ripgrep matching, context, and file-selection arguments
   and emit complete UTF-8 result rows as copyable path-and-`LINE:HASH` results.
 - Mutation-owned complete-line, inclusive line-range, and anchored literal targets.
-- Replacement, insertion immediately before or after a target, and deletion without a
-  separate selection, cursor, or clipboard protocol.
+- Replacement, insertion immediately before a line or text destination, EOF append, and
+  deletion.
 - Optional positive multiplicity for repeated anchored literal mutations.
 - File creation, movement, and deletion.
 - One immutable baseline per touched existing file for the complete script; overlapping
@@ -114,10 +112,6 @@ wall time must remain close to control.
 
 ## Non-goals
 
-- Compatibility aliases or legacy support for `tsel`, `rsel`, `copy`, `cut`, `paste`, or
-  script-level `commit`.
-- A persistent selection, cursor, clipboard, mutable shadow buffer, undo history, or
-  resume protocol.
 - Content movement without re-emitting the moved content; `mv` moves complete files only.
 - Selecting content introduced earlier in the same script. Dependent edits use a later
   inspected invocation.
@@ -139,7 +133,6 @@ wall time must remain close to control.
 
 ## Constraints
 
-- The HPATCH/2 grammar replaces HPATCH/1; compatibility is not required.
 - A routed row reference combines a positive one-based logical-line hint with a lowercase
   four-digit content hash. The hash verifies complete logical-line bytes, including
   indentation and excluding its terminator. A shifted row resolves only when the hash is unique.

doc/codex-router-e2e.md

@@ -10,7 +10,7 @@ upgrade before changing routing assumptions.
 - A Codex session started in a directory inside this Git repository declares the enclosing repository root as its base directory. A nested `-C` directory does not create another hpatch base directory.
 - In the Codex CLI 0.145.0 observation, `--add-dir` added a sandbox-writable root but did not add that directory to the `x-codex-turn-metadata` `workspaces` map. This metadata observation predates directory-based translation and must be rerun after Codex or router changes; it is not evidence of router confinement.
 - A standalone non-repository `/tmp` workdir, even with `--skip-git-repo-check`, supplied no usable base directory in that observation. The router now forwards such a turn; without a selected directory, absolute hpatch operands work and relative operands reject without falling back to the router process CWD.
-- Hpatch has no base-directory selection command. Scripts contain ordinary hpatch commands only; do not introduce `workspace_id`, workspace lists, dynamic workspace developer messages, patch rebasing, or multi-directory routing unless a real Codex request demonstrates that requirement.
+- Hpatch receives its base directory outside the script. Do not introduce `workspace_id`, workspace lists, dynamic workspace developer messages, patch rebasing, or multi-directory routing unless a real Codex request demonstrates that requirement.
 
 The router validates and canonicalizes the optional declared base-directory string for normal server-side translation. It does not open a pinned engine root, impose filesystem confinement, or check directory identity before and after evaluation. Relative, `..`, symlink, and absolute operands use ordinary host path resolution when a directory is selected. Without one, only absolute operands are valid and router cwd is never used. Current Codex emits zero or one workspace entry. Codex remains responsible for permission checks when it executes the generated patch carrier.
 

doc/spec/comparison.md

@@ -7,7 +7,7 @@ The comparison program emulates at least these equivalent edit scenarios:
 1. Replace a small expression on a long line.
 2. Delete the last literal occurrence on a line.
 3. Duplicate a multi-line implementation block.
-4. Apply independent edits whose selectors retain original baseline coordinates.
+4. Apply independent edits whose targets retain original baseline coordinates.
 5. Create a file with one complete-content write.
 6. Edit and move a file, and delete another file, in one script.
 

doc/spec/interface.md

@@ -576,9 +576,8 @@ line  range  text-single  text-multiple
 Targetless `type VALUE` initialization has no target counter. Anchored and unanchored text
 targets use the same counters. A text target with omitted count or count one is
 `text-single`; an explicit count intended to exceed one is
-`text-multiple`, including an invalid multiple count. Unsupported HPATCH/1 commands and
-unknown future commands are syntax failures but do not receive supported-command or
-target attribution.
+`text-multiple`, including an invalid multiple count. Unknown commands are syntax failures
+but do not receive supported-command or target attribution.
 
 Terminal command errors carry stable internal reason identifiers grouped as:
 
@@ -650,8 +649,7 @@ Acceptance:
 5. The input-overhead table has no plugin child rows. Net added input includes the signed difference
    between current and stock tool-result estimates.
 6. The six supported hpatch command counters and four target counters reconcile with
-   aggregate command attempts and errors. No selector, clipboard, editor-generation, or
-   script-level commit counter remains.
+   aggregate command attempts and errors.
 7. Every definition-bearing request increments the definition-request counter, while the exact
    installed tool collection, its reconciling per-tool breakdown, and the displaced baseline
    definition accumulate only once per distinct session. An absent session or definition
@@ -680,8 +678,8 @@ Acceptance:
 
 ## REQ-SCRIPT-001 — HPATCH/2 script grammar
 
-HPATCH/2 replaces HPATCH/1. There are no compatibility aliases. Outside a heredoc body,
-blank lines are ignored and every other physical line begins exactly one command:
+Outside a heredoc body, blank lines are ignored and every other physical line begins exactly
+one command:
 
 ```text
 in PATH
@@ -765,8 +763,7 @@ commands are invalid.
 
 Acceptance:
 
-1. Every accepted nonblank command is one of the six public commands; `type-`, `type+`,
-   `tsel`, `rsel`, `copy`, `cut`, `paste`, `del`, and script-level `commit` are syntax errors.
+1. Every accepted nonblank command is one of the six public commands.
 2. Line, range, anchored text, and unanchored text targets parse without a separate selection command, and inline
    replacement values remain distinguishable from a text target's quoted literal.
 3. Anchored and unanchored text targets accept JSON-escaped LF and exact multiline or
@@ -794,7 +791,7 @@ denote a different target from the retained command. Recovery
 has no operation keyword and cannot change operations, values, heredoc bodies, command count or
 order, or file context. Target parsing and script rebuilding preserve the public target literal's
 exact decoded bytes, including escaped LF, and enforce the same empty, CR, and control
-exclusions. There are no compatibility aliases, sentinel lines, or `accept` operation.
+exclusions.
 
 The router owns recovery grammar, parsing, handle resolution, ancestry, worktree isolation,
 dispatch, replay, diagnostics, and reevaluation. Every command handle resolves against the latest
@@ -842,11 +839,10 @@ Acceptance:
 7. Ordinary mutation-leading hpatch scripts are never detected as recovery.
 8. Per-attempt telemetry remains individual, while persistent metrics count every chain payload and one
    final or failed comparator.
-9. Removed `target`, `drop`, operation, value, value-row, and structural forms are syntax errors, not compatibility paths.
-10. One payload can correct multiple distinct command targets atomically without changing any other command field.
-11. A target correction can retarget an anchored or unanchored mutation to exact multiline
+9. One payload can correct multiple distinct command targets atomically without changing any other command field.
+10. A target correction can retarget an anchored or unanchored mutation to exact multiline
     text with escaped LF; rebuilding preserves the target bytes and public control exclusions.
-12. A target correction that denotes the retained target rejects before root reevaluation,
+11. A target correction that denotes the retained target rejects before root reevaluation,
     including an explicit default occurrence count, an equivalent quoted escape spelling, or a
     range whose two endpoints are the retained single row; the retained baseline and handles remain usable.
 
@@ -932,8 +928,7 @@ still stop at their authoritative boundary.
 
 Resolution produces one nonempty baseline span for a line or range and one or more
 nonempty spans for a text target. A mutation over multiple spans validates and registers
-all of them or none. There is no persistent selection, cursor, clipboard, shadow buffer,
-generation, or resume state.
+all of them or none.
 
 Acceptance:
 
@@ -981,8 +976,8 @@ Content movement requires emitting the destination content; `mv` moves whole fil
 
 Acceptance:
 
-1. Replacement, before insertion, after insertion, and deletion produce the specified
-   result directly from their targets without a selection command.
+1. Replacement, deletion, insertion before a line or text destination, and EOF append
+   produce the specified result directly from their targets or destination.
 2. Multi-match text mutation applies the same action to every requested match or none.
 3. Disjoint edits are script-order independent except for deliberate insertions at the
    same boundary, which retain script order.
@@ -1271,8 +1266,7 @@ Persistent guidance teaches this workflow:
 
 Acceptance:
 
-1. A model can choose and encode every HPATCH/2 operation from the persistent guidance without learning
-   HPATCH/1 state concepts.
+1. A model can choose and encode every HPATCH/2 operation from the persistent guidance.
 2. The installed prompt contains the central guidance exactly once and omits the pinned stock
    apply_patch, rg, and exec_command instructions.
 3. A configured legacy or marked customized prompt retains content before and after the owned

hooks_test.go

@@ -370,8 +370,8 @@ func TestErrorAndOutcomeHooksReceiveAttemptMetadata(t *testing.T) {
 	}
 
 	evaluatedScript := "new note.txt\ntype \"ok\"\n"
-	recoveryPayload := "C2:abcd target 2:bbbb"
-	delta := "C2:abcd target: 1:aaaa -> 2:bbbb"
+	recoveryPayload := "C2:abcd 2:bbbb"
+	delta := "C2:abcd: 1:aaaa -> 2:bbbb"
 	recoveryMetadata := AttemptMetadata{
 		SessionID:       "session-1",
 		CorrelationID:   "chain-1",

internal/router/dashboard_test.go

@@ -7,9 +7,9 @@ import (
 	"testing"
 )
 
-func TestDashboardGainStateHasNoRemovedBlockTableReference(t *testing.T) {
+func TestDashboardGainStateHasNoBlockTableReference(t *testing.T) {
 	if strings.Contains(string(dashboardHTML), "blocks:blocks.tbody") {
-		t.Fatal("dashboard gain state references the removed block selector table")
+		t.Fatal("dashboard gain state references an unsupported block table")
 	}
 }
 

internal/router/hpatch_exact_evidence_test.go

@@ -120,7 +120,7 @@ func TestHPatchExactEvidenceMalformedRecoveryIsRouterRejected(t *testing.T) {
 	directory := t.TempDir()
 	t.Setenv(hpatchExactEvidenceEnvironment, directory)
 	transform, _, _, _ := newHPatchTestTransform(t, testTranslator(t, new(int)))
-	payload := "C1:ffff drop\n"
+	payload := "C1:ffff not-a-target\n"
 	history, err := transform.translateRecovery("call-malformed", payload, nil)
 	if err != nil {
 		t.Fatal(err)

internal/router/hpatch_proxy_test.go

@@ -407,22 +407,6 @@ func TestHPatchPrepareRequestExposesEditToolsAndShell(t *testing.T) {
 	if _, exists := request.fields["instructions"]; exists {
 		t.Fatalf("prepareRequest added instructions: %s", request.fields["instructions"])
 	}
-	for _, obsoleteGuidance := range []string{
-		"Repairing a rejected script:",
-		"INDEX: COMMAND",
-		`INDEX.ROW: "VALUE"`,
-		": accept",
-	} {
-		if strings.Contains(exposed, obsoleteGuidance) {
-			t.Fatalf("standalone hpatch description includes obsolete recovery guidance %q: %q", obsoleteGuidance, exposed)
-		}
-	}
-	if strings.Contains(exposed, "type <<PATCH replacement or insertion consumes") {
-		t.Fatalf("standalone hpatch description retains obsolete indexed recovery framing: %q", exposed)
-	}
-	if strings.Contains(exposed, "workspace_id") {
-		t.Fatalf("standalone hpatch description retains workspace selection: %q", exposed)
-	}
 	if string(topTools[0]["future"]) != "true" {
 		t.Fatalf("unrelated top-level tool changed: %#v", topTools[0])
 	}
@@ -2067,7 +2051,7 @@ func TestHPatchHistoryDoesNotCrossWorkspacesSharingSessionIdentity(t *testing.T)
 		t.Fatalf("cross-workspace replay restored input %q", input)
 	}
 
-	history, err := second.translateRecovery("call-recovery", "C1:ffff drop", nil)
+	history, err := second.translateRecovery("call-recovery", "C1:ffff not-a-target", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -2450,7 +2434,7 @@ func TestHPatchNonEvaluatorFailureDoesNotBecomeRecoveryBaseline(t *testing.T) {
 	if first.evaluatorRejected || strings.Contains(first.translationError, "Use hpatch without `in`") {
 		t.Fatalf("non-evaluator failure exposed recovery guidance: %+v", first)
 	}
-	second, err := transform.translateRecovery("call-2", "C1:ffff drop", nil)
+	second, err := transform.translateRecovery("call-2", "C1:ffff not-a-target", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -2475,7 +2459,7 @@ func TestHPatchUnevaluatedRecoveryRunsOutcomeHookOnce(t *testing.T) {
 		t,
 		newManagedHPatchProxyWithDataDirectory(t, newInProcessHPatchTranslator(dataDirectory), dataDirectory),
 	)
-	payload := "C1:ffff drop"
+	payload := "C1:ffff not-a-target"
 	history, err := transform.translateRecovery("call-recovery", payload, nil)
 	if err != nil {
 		t.Fatal(err)

internal/router/hpatch_recovery_protocol_test.go

@@ -107,17 +107,16 @@ func TestRecoverScriptRetargetsMultilineLiteral(t *testing.T) {
 	}
 }
 
-func TestRecoverScriptRejectsNonTargetDuplicateStaleAndRemovedForms(t *testing.T) {
+func TestRecoverScriptRejectsNonTargetDuplicateStaleAndMalformedPayloads(t *testing.T) {
 	script := "in file.go\n" + `type 1:aaaa "bad"` + "\n"
 	commands := recoveryCommands(script)
 	handle := commands[1].handle
 	for _, payload := range []string{
 		commands[0].handle + " 2:bbbb",
 		"C2:ffff 2:bbbb",
 		handle + " 2:bbbb\n" + handle + " 3:cccc",
-		handle + " target 2:bbbb",
-		handle + ` value "fixed"`,
-		handle + " drop",
+		handle + " not-a-target",
+		handle + " 2:bbbb trailing",
 		handle + "  2:bbbb",
 		handle + "\t2:bbbb",
 		handle + ` 2:bbbb  "literal"`,