Add GET /api/v1/plans/:id/snapshot endpoint for agents

[HamptonMakes]

Summary

Adds a single "oneshot" API endpoint that returns everything an agent needs to understand and act on a plan in one request, eliminating 3-4 separate API calls.

Endpoint: GET /api/v1/plans/:id/snapshot

Response shape

{
  "id": "...",
  "title": "...",
  "status": "considering",
  "current_content": "# Plan...",
  "current_revision": 3,
  "created_by": "Alice",
  "created_by_user": { "id": "...", "name": "Alice" },
  "tags": ["infra"],
  "comment_threads": [
    {
      "id": "...",
      "status": "pending",
      "anchor_text": "...",
      "anchor_occurrence": 0,
      "created_by": "Bob",
      "created_by_user": { "id": "...", "name": "Bob" },
      "comments": [
        {
          "id": "...",
          "author_type": "human",
          "author_id": "...",
          "body_markdown": "..."
        }
      ]
    }
  ],
  "references": [...],
  "collaborators": [
    { "id": "...", "user": { "id": "...", "name": "Carol" }, "role": "reviewer" }
  ]
}

Design decisions

• Backward compatible: created_by remains a string everywhere. New created_by_user field added as structured {id, name} object for agents that need to correlate users across sections.
• Efficient markdown parsing: anchor_occurrence is computed by stripping markdown once for all threads, not N times.
• N+1 prevention: Comments sorted in memory (sort_by) instead of .order() to leverage eager loading.
• Nil-safe user_json: Returns nil for missing users instead of crashing.
• author_id on comments: Agents can now correlate who wrote each comment.
• No versions array: Current content/revision is included; full version history available via existing GET /api/v1/plans/:id/versions.

Testing

• 3 new request specs (full response shape, auth required, 404 for missing plan)
• All 690 existing tests pass

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0c6b4b6e00

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Return fallback occurrence for unresolved anchors

For anchored threads that do not have anchor_start populated (e.g., legacy threads created before positional anchoring or records where resolution failed), compute_anchor_occurrence now returns nil immediately, so /snapshot emits anchor_occurrence: null. That regresses the existing fallback behavior in CommentThread#anchor_occurrence_index (which returns first occurrence 0 when position is missing) and can make agent-side anchor targeting non-deterministic for repeated anchor text. Please preserve the 0 fallback for anchored threads without positional data so snapshot consumers always get a usable index.

Useful? React with 👍 / 👎.

[HamptonMakes]

Re: Codex review on compute_anchor_occurrence fallback

Good catch — fixed in b546f06. Anchored threads without anchor_start now return anchor_occurrence: 0 (first occurrence) instead of nil, matching the existing CommentThread#anchor_occurrence_index fallback behavior.