docs: cover non-execution worktree lifecycle (WAT-1777)

Author: willblanchard

doc/experimental/issue-worktree-support.md

@@ -24,21 +24,32 @@ We are intentionally not shipping the UI for this yet. The runtime code remains
 
 ## Large-repo Worktree Lifecycle Policy
 
-Paperclip-owned issue and review worktrees are execution workspaces, not agent-owned scratch directories. The execution workspace record is the source of truth for:
+Paperclip-owned issue and review worktrees should be execution workspaces, not agent-owned scratch directories. For worktrees created through the execution workspace runtime, the execution workspace record is the source of truth for:
 
 - owner: the Paperclip company/project plus the issue linked through `sourceIssueId` and `issues.executionWorkspaceId`
 - linked work: the issue identifier, branch name, base ref, project workspace, and any PR link carried in the issue thread
 - creation and use time: `openedAt`, `createdAt`, and `lastUsedAt`
 - cleanup eligibility: `closedAt`, `cleanupEligibleAt`, `cleanupReason`, and workspace `status`
 - provider ownership: `providerType: "git_worktree"` plus `metadata.createdByRuntime: true` means Paperclip may remove the derived worktree after close-readiness passes
 
+Some existing large-repo worktrees were created by local agent workflows before execution workspace records covered every path. Examples include superpowers or agent-created worktrees under `/tmp` with names derived from issue branches. Those worktrees are still in scope for stale-worktree prevention, but they are not automatically safe to delete. Until they are adopted into execution workspace records or carry explicit Paperclip ownership metadata, they use a report-only lifecycle:
+
+- owner discovery: infer the repository from `git rev-parse --show-toplevel`, the branch or detached commit from `git status --branch --porcelain=v2`, and the creating workflow from path markers such as `/tmp`, `.paperclip/worktrees`, `paperclip/`, `wat-`, or adapter-specific worktree roots
+- linked work discovery: parse `WAT-\d+` or project issue keys from the branch name, worktree basename, PR branch, or recent commit subjects, then query matching Paperclip issues and PR links
+- active-work guardrail: if any inferred linked issue is non-terminal, the row remains active and report-only regardless of age
+- missing-link guardrail: if no issue or PR can be inferred, the row is reported as orphaned but not deleted
+- retention: clean, linked, terminal non-execution worktrees are stale after 24 hours; review-shaped worktrees are stale after 7 days; unknown-owner rows stay report-only until an operator records ownership or removes them manually
+- dirty-work guardrails: dirty tracked files, untracked files, unpushed commits, detached heads, unresolved merges, inaccessible git status, missing upstream/base refs, or running processes with `cwd` inside the worktree all block deletion
+- deletion policy: non-execution worktrees are never deleted by the automatic release/completion cleanup path. A later cleanup implementation may delete them only after adopting them into an execution workspace record or recording equivalent owner, issue, creation time, and Paperclip-created metadata.
+
 Retention defaults for large local worktrees:
 
 - active or linked to open issue: keep; report size and readiness only
 - clean, idle, Paperclip-created issue worktree: eligible for cleanup after 24 hours
 - in review: keep for 7 days unless a reviewer explicitly archives the workspace earlier
 - `cleanup_failed`: keep until an operator resolves the reported reason
 - shared/project-primary workspace: never delete the underlying project checkout; archive only the execution workspace record
+- non-execution Paperclip/agent worktree: report when stale by the windows above, but do not delete until ownership metadata is explicit
 
 Close and cleanup must use the execution workspace close-readiness report before deleting anything. The report includes linked open issues, runtime services, git dirty state, untracked files, ahead/behind counts, merge status, and planned cleanup actions. Destructive archive is blocked for isolated git worktrees when:
 
@@ -50,7 +61,7 @@ Close and cleanup must use the execution workspace close-readiness report before
 
 The lower-level cleanup helper also refuses to remove a git worktree when `git status --porcelain --untracked-files=all` is non-empty, so direct callers report dirty worktrees instead of deleting them. If a worktree is clean and Paperclip owns it, cleanup removes the git worktree and then attempts to delete the runtime-created branch with `git branch -d`; unmerged branches are reported and kept.
 
-Safe stale-worktree reporting should list, but not delete, candidate `/tmp` worktrees matching all of:
+Safe stale-worktree reporting should list, but not delete, execution-workspace candidate `/tmp` worktrees matching all of:
 
 - provider is `git_worktree`
 - workspace path resolves under `/tmp` or the platform temp directory
@@ -59,6 +70,8 @@ Safe stale-worktree reporting should list, but not delete, candidate `/tmp` work
 
 Each row should include workspace id, issue identifier, owner agent if known, path, branch, base ref, opened/last-used time, approximate path size, readiness state, blocking reasons, and planned actions. Deletion is only allowed by the archive/close path after readiness returns `ready` or `ready_with_warnings`; blocked rows remain report-only.
 
+The same stale report should also scan registered large-repo roots and platform temp worktree roots for non-execution git worktrees. These rows should include source `non_execution_git_worktree`, inferred repository, inferred issue or PR, owner agent if known, path, branch or detached commit, upstream/base ref, last filesystem activity, approximate path size, git cleanliness, ahead/unpushed status, active process hints, and why the row is report-only. They are stale signals for operators and future adoption work, not deletion candidates.
+
 Successful release/completion behavior: when a Paperclip-owned isolated worktree is closed, the server archives the execution workspace record, stops attached runtime services, runs configured cleanup/teardown commands, removes the clean git worktree, and records any cleanup warning in `cleanupReason`. If release/completion does not explicitly archive the workspace, the stale-worktree report is the follow-up mechanism that makes the retention breach visible before manual or scheduled archive.
 
 ## Hidden UI entrypoints