Add PUT /api/v1/plans/:id/content for full content replacement

[HamptonMakes]

Why

Agents are great at producing whole files, but the only existing edit path was the lease + semantic-operations dance, which agents (and humans!) get wrong constantly. The local agent skill already documented a PUT /content endpoint as if it existed — and Hampton's agent kept hitting 404s trying to use it. This makes the documented path real and promotes it to the recommended workflow.

What

• New PUT /api/v1/plans/:id/content — read plan, edit markdown locally, PUT it back. Server diffs against current revision, decomposes into ops (preserving comment anchors in unchanged regions via existing OT), creates a new immutable PlanVersion. Optimistic concurrency via base_revision (returns 409 on stale).
• Plans::DiffToOperations — line-level LCS diff → ordered replace_exact ops with cumulative-delta-aware _pre_resolved_ranges. Granularity chosen so anchors in unchanged regions survive intact.
• Plans::ReplaceContent — orchestrator service. Locks plan, normalizes CRLF→LF (so Windows/textarea content doesn't trigger wholesale rewrite), applies ops, marks anchors out-of-date, broadcasts.
• Disabled wrap_parameters on the API base controller — was silently nesting JSON body under params[:content].
• Fixed apply_replace_exact delta to be computed from the actual range slice (not from old_text.length) so mismatched caller-supplied old_text can't corrupt OT metadata. Also relaxed the old_text blank check when _pre_resolved_ranges is supplied (needed for pure-insertion hunks).
• Updated /agent-instructions doc to feature this as the primary edit path; lease + operations relegated to "Advanced".

Risk Assessment

Low — purely additive endpoint; existing lease+operations path is unchanged in semantics. The two apply_operations.rb modifications were reviewed for backward compatibility (existing tests pass, plus a delta-bug regression test). Comment-anchor invariants are covered by tests at the diff, service, and request layers.

References

• 765/765 specs pass (13 new tests across diff/replace/apply specs)
• Diff service has a 30-iteration random fuzz roundtrip plus targeted tests for: trailing-newline variants, unicode, repeated identical lines (LCS ambiguity), shared prefix/suffix, contiguous delete-then-insert, 100k-char single line, large files with many disjoint hunks
• Anchor preservation tested at three layers: DiffToOperations (via TransformRange), ReplaceContent (anchors before/inside/after change), and request spec (marks overlapping anchors out-of-date)
• Code review surfaced and fixed: CRLF normalization, delta-corruption attack surface via _pre_resolved_ranges, named RoundtripFailureError exception with controller rescue
• Agent thread: https://ampcode.com/threads/T-019dda2a-85b2-706b-b5f8-67601e9dcf58

Generated with Amp

[HamptonMakes]

@codex

[HamptonMakes]

@codex are you dead!?!

[chatgpt-codex-connector]

To use Codex here, create an environment for this repo.

[Copilot]

Pull request overview

Adds an agent-friendly “full content replacement” edit path for plans by introducing a new PUT /api/v1/plans/:id/content endpoint that diffs incoming markdown into OT-compatible replace_exact operations, applies them to generate positional metadata, and persists a new immutable PlanVersion with optimistic concurrency via base_revision.

Changes:

• Introduce PUT /api/v1/plans/:id/content plus request specs and updated agent instructions recommending this workflow.
• Add Plans::DiffToOperations (line-level LCS → ordered replace_exact ops with _pre_resolved_ranges) and Plans::ReplaceContent orchestrator (locking, CRLF→LF normalization, apply+roundtrip check, anchor handling, broadcast).
• Harden ApplyOperations#replace_exact delta computation to derive from the actual resolved range length (not caller-supplied old_text length) and relax old_text blank validation when _pre_resolved_ranges is provided.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
spec/services/plans/replace_content_spec.rb	Service-level coverage for version creation, no-op, stale revision, CRLF normalization, roundtrip safety, and anchor behavior.
spec/services/plans/diff_to_operations_spec.rb	Extensive roundtrip/property and edge-case coverage for diff→ops generation and OT compatibility.
spec/services/plans/apply_operations_spec.rb	Regression test ensuring delta is computed from resolved range slice length.
spec/requests/api/v1/content_spec.rb	Request-level coverage for endpoint behavior: create/no-op, validation, auth, concurrency, anchor out-of-date.
engine/config/routes.rb	Adds singular content resource under plans for update (PUT/PATCH).
engine/app/views/coplan/agent_instructions/show.text.erb	Documents the new recommended edit workflow and relegates lease+ops to “Advanced”.
engine/app/services/coplan/plans/replace_content.rb	New orchestrator implementing lock+diff+apply+version creation + anchor marking + broadcast.
engine/app/services/coplan/plans/diff_to_operations.rb	New diff service generating ordered replace_exact ops with _pre_resolved_ranges.
engine/app/services/coplan/plans/apply_operations.rb	Updates replace_exact validation and delta calculation to avoid metadata corruption.
engine/app/controllers/coplan/api/v1/content_controller.rb	New API controller implementing PUT /content behavior and error mapping.
engine/app/controllers/coplan/api/v1/base_controller.rb	Disables wrap_parameters to prevent JSON body auto-wrapping collisions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.