ce-proof: SKILL.md must instruct agents to capture ownerSecret and delete docs at end of session

[muse-josht]

Summary

ce-proof's SKILL.md instructs the agent to upload markdown to Proof and operate on it (presence, comments, suggestions, edits) using the returned accessToken. It does not instruct the agent to capture or persist the ownerSecret from the create response — and the ownerSecret is the only credential that authorizes deletion of the doc afterward. As a result, agent-uploaded Proof docs accumulate as orphaned, undeletable artifacts in proofeditor.ai after a session ends.

A second related gap: there is no editor-side primitive to remove comment/suggestion marks. Emptying the markdown via rewrite.apply or block edits does not scrub marks — their quote (original anchored text) and text (author commentary) fields persist intact, readable to anyone with the accessToken. So even attempting cleanup via the editor token leaves an information surface behind.

Evidence

In a session on 2026-05-28 (using ce-brainstorm → ce-plan → ce-work for a documentation PR), the agent uploaded four Proof docs for HITL review using inline curl calls patterned on SKILL.md's "Workflow: Create and Share a New Document" example. Only one of the four docs had its ownerSecret captured (by accident, via an early jq extraction). After the session:

• The one doc with the captured ownerSecret could be cleanly deleted: DELETE /api/documents/<slug> returned {success: true, shareState: "DELETED"}.
• The other three returned 403 {"error":"Not authorized to delete document"} for every header form attempted (x-share-token, Authorization: Bearer, etc.) — because the accessToken grants editor / commenter / viewer role but never owner, and the SDK explicitly disables agent-OAuth (isOAuthConfigured returns false in EveryInc/proof-sdk's server/hosted-auth.ts).
• The user manually emptied the three docs by editing them down to nothing in the UI via the editor URL. Two of the three were clean afterward (no marks remained). The third (aq7naotv in this session) retained 11 comment marks with their full quote and text content including internal email addresses, Slack handles, paused PR URLs, and internal Sentry tag signatures — recoverable via GET /api/agent/<slug>/state from anyone with the URL.

What the skill should say

1. Capture ownerSecret at create time (currently silent)

The example response in plugins/compound-engineering/skills/ce-proof/SKILL.md shows ownerSecret: "yyy" in the JSON but never tells the agent to extract or store it. The "Workflow: Create and Share a New Document" example only extracts tokenUrl, slug, and accessToken. Most agents will copy this pattern verbatim and drop the ownerSecret on the floor.

Recommended fix: update the create-and-share workflow to extract all three fields and persist ownerSecret for the session. Add an explicit step like:

SLUG=$(echo "$RESPONSE" | jq -r '.slug')
TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')
OWNER_SECRET=$(echo "$RESPONSE" | jq -r '.ownerSecret')   # required for cleanup

Cross-reference EveryInc/proof-sdk/AGENT_CONTRACT.md step 2 ("Persist ownerSecret securely") in the skill body so the contract is visible to the agent.

2. Document the DELETE endpoint and require cleanup (currently absent)

SKILL.md has no DELETE example anywhere. Add a "Cleanup" or "End of Session" section:

curl -X DELETE "https://www.proofeditor.ai/api/documents/$SLUG" \
  -H "Authorization: Bearer $OWNER_SECRET"

And establish a default lifecycle: upload → review → sync back → DELETE, all in one workflow. The agent should not leave docs lingering after a session ends unless the user explicitly asks for the doc to stay.

3. Recommend the user-creates-then-shares default (preferred over agent-uploads)

The cleanest fix is to invert the default flow: when HITL review is needed, the agent asks the user to create the Proof doc in the UI (signed in via their account, which makes them the OAuth-bound owner) and paste the share link back. The agent then operates with editor-role from the URL ?token=, never holds an ownerSecret, and lifecycle is fully under the user's control via the Proof UI.

Recommended posture in SKILL.md:

• Default: user creates → user shares link → agent operates with accessToken → user deletes from UI when done.
• Fallback (when agent must create — e.g., the doc needs to exist before the user is in the loop): capture ownerSecret, persist for the session, DELETE before session end.

4. Warn about the marks-survive-content-deletion behavior

Even when an agent has lost the ownerSecret and tries to clean up via the editor token, emptying the markdown does not scrub the comment marks. The SDK does not expose comment.delete to editor-role tokens; supported comment ops are only add, reply, resolve, unresolve. rewrite.apply succeeds but doesn't remove marks either. The only remaining path is contacting Proof support to hard-delete by slug.

The skill should warn the agent up front so it doesn't promise the user "I'll empty it" as a working cleanup path.

Source references

• EveryInc/proof-sdk — AGENT_CONTRACT.md (token semantics, minimal flow), server/routes.ts (canOwnerMutate, getExplicitShareSecret, DELETE handler at L1787, supported comment ops), server/hosted-auth.ts (OAuth-not-available rationale)
• Current ce-proof SKILL.md content lacks ownerSecret capture instruction, lacks any DELETE example, lacks a cleanup section.

Suggested labels

skill:ce-proof, documentation, security (low-grade — bounded by URL distribution but a real leak vector).

---

Filed at the user's request after a real session hit this gap.