docs(routines): clarify deferred sweep trigger

Co-Authored-By: Paperclip <noreply@paperclip.ing>

doc/DATABASE.md

@@ -233,7 +233,7 @@ the reusable company-level slot, declarations record where `user_secret_ref`
 bindings are required, and the concrete value is selected later for the
 responsible user.
 
-Secret-aware env bindings are supported by agents, projects, and routines. Routine env lives in `routines.env`, is captured in `routine_revisions.snapshot`, and routine dispatches store `routine_runs.routine_revision_id` so runtime secret resolution uses the env snapshot that existed when the run was created. The same immutable snapshot supplies `lifecycle_policy`; `latest_success_wins` records supersession with `issues.superseded_by_issue_id`, `routine_runs.status = 'superseded'`, and `routine_runs.superseded_by_run_id`, except that an older instance with any transitively non-terminal `issues.parent_id` descendant is left unchanged and receives an idempotent `issue.supersession_deferred` activity entry with the superseding issue/run and live descendant issue ids. Routine secret refs bind with `target_type = 'routine'`, `target_id = routines.id`, and `config_path` values under `env.*`.
+Secret-aware env bindings are supported by agents, projects, and routines. Routine env lives in `routines.env`, is captured in `routine_revisions.snapshot`, and routine dispatches store `routine_runs.routine_revision_id` so runtime secret resolution uses the env snapshot that existed when the run was created. The same immutable snapshot supplies `lifecycle_policy`; `latest_success_wins` records supersession with `issues.superseded_by_issue_id`, `routine_runs.status = 'superseded'`, and `routine_runs.superseded_by_run_id`, except that an older instance with any transitively non-terminal `issues.parent_id` descendant is left unchanged and receives an idempotent `issue.supersession_deferred` activity entry with the superseding issue/run and live descendant issue ids. A later successful run repeats the sweep after the subtree clears; a descendant terminal transition does not run the sweep by itself. Routine secret refs bind with `target_type = 'routine'`, `target_id = routines.id`, and `config_path` values under `env.*`.
 
 For local/default installs, the active provider is `local_encrypted`:
 

doc/SPEC-implementation.md

@@ -457,7 +457,7 @@ The current implementation includes additional V1-control-plane tables beyond th
 
 - Issue structure and review: `issue_relations` for blockers, `labels`/`issue_labels`, `issue_thread_interactions`, `issue_approvals`, `issue_execution_decisions`, `issue_work_products`, `issue_inbox_archives`, `issue_read_states`, and issue reference mention indexes.
 - Execution and workspace control: `execution_workspaces`, `project_workspaces`, `workspace_runtime_services`, `workspace_operations`, `environments`, `environment_leases`, `agent_task_sessions`, `agent_runtime_state`, `agent_wakeup_requests`, heartbeat events, and watchdog decision tables.
-- Plugins and routines: `plugins`, plugin config/state/entities/jobs/logs/webhooks, plugin database namespaces/migrations, plugin company settings, `routines`, `routine_revisions`, `routine_triggers`, and `routine_runs`. Routine concurrency is a dispatch-time policy. Instance lifecycle is a separate, revision-snapshotted policy with safe default `independent`; opt-in `latest_success_wins` lets a newer successful execution cancel and link older visible non-terminal instances without making pause or archive destructive. An older instance with any transitively non-terminal `parent_id` descendant is skipped, leaving its issue and routine run unchanged, and records one `issue.supersession_deferred` activity entry per superseding run with the superseding issue/run ids and the live descendant issue ids.
+- Plugins and routines: `plugins`, plugin config/state/entities/jobs/logs/webhooks, plugin database namespaces/migrations, plugin company settings, `routines`, `routine_revisions`, `routine_triggers`, and `routine_runs`. Routine concurrency is a dispatch-time policy. Instance lifecycle is a separate, revision-snapshotted policy with safe default `independent`; opt-in `latest_success_wins` lets a newer successful execution cancel and link older visible non-terminal instances without making pause or archive destructive. An older instance with any transitively non-terminal `parent_id` descendant is skipped, leaving its issue and routine run unchanged, and records one `issue.supersession_deferred` activity entry per superseding run with the superseding issue/run ids and the live descendant issue ids. Each later successful run repeats the sweep, so a deferred instance becomes eligible after its subtree is terminal; descendant completion alone does not trigger a lifecycle mutation.
 - Access and operations: company memberships, instance roles, principal permission grants, invites, join requests, board API keys, CLI auth challenges, budget policies/incidents, feedback exports/votes, company skills, sidebar preferences, and company logos.
 
 Decision-desk triage uses company-scoped sidecars rather than adding queue fields to every attention source: