Document task watchdog proof obligations

doc/TASK-WATCHDOG.md

@@ -9,6 +9,7 @@
   - [From the API](#from-the-api)
 - [How a scan works](#how-a-scan-works)
 - [What the watchdog agent does](#what-the-watchdog-agent-does)
+  - [Proof obligations and outcomes](#proof-obligations-and-outcomes)
   - [Writing custom instructions](#writing-custom-instructions)
 - [Scope enforcement](#scope-enforcement)
 - [Origin and badges](#origin-and-badges)
@@ -89,7 +90,7 @@ For each active watchdog the tick:
 3. **Computes a stop fingerprint.** A SHA-256 hash over the stopped leaves' identifiers, statuses, blockers, pending interactions, and the current watchdog configuration. The configuration is part of the fingerprint, so changing the agent or instructions invalidates the previously reviewed state.
 4. **Compares against `lastReviewedFingerprint`.** Match → suppress (the watchdog already saw this exact stopped state). New → proceed.
 5. **Ensures a review task exists.** Creates (or reopens) one child issue with `originKind = 'task_watchdog'` and `originId = watchedIssueId`. Idempotent per watchdog — only one review task is ever live at a time.
-6. **Wakes the watchdog agent.** Sends a wake with `wakeReason = task_watchdog_stopped_subtree`, the stop fingerprint, the leaf summaries, the default mandate, and any custom instructions. The idempotency key is `(watchdogId, stopFingerprint)`, so retries cannot stack duplicate wakes.
+6. **Wakes the watchdog agent.** Sends a wake with `wakeReason = task_watchdog_stopped_subtree`, the stop fingerprint, the leaf summaries, the default mandate, and any custom instructions. The wake idempotency key is `(watchdogId, stopFingerprint)`, so retries cannot stack duplicate wakes for the same stopped state.
 
 When the subtree changes between scans (someone restarts work, adds a blocker, or accepts an interaction) the stop fingerprint changes too, and the watchdog will be woken again for the new state — even if the previous run already disposed of an earlier fingerprint.
 
@@ -113,6 +114,26 @@ The mandate also enforces safety constraints that custom instructions **cannot o
 
 The formal authority contract (the full list of allowed and disallowed mutations, and the eligibility test for accepting plan confirmations) is in [`doc/SPEC-implementation.md`](SPEC-implementation.md) §9.9.
 
+### Proof obligations and outcomes
+
+Each stopped leaf creates a proof obligation: the watchdog must either verify the stopped disposition against bounded evidence or restore a valid path that will move the work forward. A proof obligation is not satisfied by a prose-only comment such as "looks blocked" or "seems done." The durable issue state must answer what happens next.
+
+The proof-obligation fingerprint is a stable hash over the leaf id, the leaf's stopped status, the stopped disposition being verified, the relevant evidence anchors, and any waiting primitive the watchdog depends on. Paperclip should treat watchdog proof handling as idempotent for `(watchdogId, stopFingerprint, proofObligationFingerprint)`. A retry or duplicate watchdog wake for the same obligation must reuse the recorded result instead of creating duplicate follow-up issues, duplicate blockers, or repeated monitor loops.
+
+Allowed proof outcomes:
+
+| Outcome       | Meaning                                                                 | Required durable state                                                                 |
+| ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| **Accepted**  | The stopped state is legitimate.                                        | Terminal, blocked, review, interaction, approval, owner, or monitor path is already valid; the watchdog records bounded evidence. |
+| **Restored**  | The stopped state was wrong or incomplete, and the watchdog moved work. | The leaf is reopened, reassigned, unblocked, given a child follow-up, given a monitor, or has an eligible plan confirmation resolved. |
+| **Deferred**  | Verification needs another bounded actor or check.                      | A first-class blocker, pending interaction/approval, human owner, typed reviewer, follow-up issue, or one-shot monitor names the owner and next action. |
+| **Failed**    | The watchdog could not safely verify or restore the obligation.         | The reusable watchdog issue is `blocked` or `in_review` with the real blocker, escalation owner, and safe next action. |
+| **Dismissed** | The obligation is a false positive for this watchdog pass.              | The reusable watchdog issue records why no source mutation is needed and the reviewed fingerprint can be suppressed. |
+
+Real verification blockers must be first-class. If the watchdog needs QA, CTO review, board approval, an external service result, or another team before it can decide, it must express that wait as a blocker, interaction, approval, owner/reviewer assignment, follow-up issue, or bounded one-shot monitor. A comment may explain the evidence, but the comment is not the waiting path.
+
+Use one-shot monitors only when the current assignee owns a future check against an async service. A monitor is not recurring uptime monitoring; when it fires, the assignee must decide the next outcome and explicitly re-arm it if another bounded check is still appropriate. Use `blocked` with a named external owner/action when Paperclip does not own the check.
+
 ### Writing custom instructions
 
 Custom instructions are most useful when they tell the watchdog what evidence to look at and what shortcuts to refuse. Examples:
@@ -165,6 +186,7 @@ It is **not** the right tool for:
 
 - monitoring a single running process for silence — that is the silent active-run watchdog, automatic, no configuration
 - liveness recovery on stalled agent-owned issues without an explicit recovery surface — that is automatic too
+- ongoing external uptime monitoring or periodic health checks — use a routine, service monitor, or external monitor; a task watchdog performs one stopped-subtree verification pass per fingerprint
 - board-level approvals or anything security-sensitive — the watchdog cannot resolve those
 - replacing a human reviewer on a typed execution-policy stage — the watchdog cannot bypass typed participants
 

doc/execution-semantics.md

@@ -557,6 +557,35 @@ The watchdog should verify stopped leaves against comments, documents, work prod
 
 When work should continue, the watchdog restores a live path inside the watched subtree: reopen or reassign stuck work, create follow-up issues, repair blockers, set a monitor, or resolve an eligible plan confirmation. When the stopped state is legitimate, the watchdog records why and leaves the subtree with a valid terminal, waiting, blocked, review, or explicit recovery path.
 
+### Proof-obligation contract
+
+Each stopped leaf in a task-watchdog evaluation is a proof obligation. The watchdog must prove one of two things from bounded evidence:
+
+- the stopped disposition is legitimate and already has a valid terminal, waiting, review, blocked, owner, interaction, approval, monitor, or recovery path
+- the stopped disposition is wrong or incomplete, and the watchdog has restored or routed a valid next action inside its authority
+
+A prose-only comment is never enough to satisfy a proof obligation. Comments and reusable-watchdog issue notes can explain evidence, but real verification blockers must become first-class blockers, pending interactions or approvals, human owners, typed reviewers, follow-up issues, explicit recovery actions, or bounded one-shot monitors.
+
+The proof-obligation fingerprint is a stable identifier for the leaf-level obligation being reviewed. It must include at least the watchdog id, stopped leaf issue id, stopped leaf disposition, relevant evidence anchors, and the waiting or recovery primitive the watchdog depends on. Watchdog proof handling is idempotent for:
+
+```
+(watchdogId, stopFingerprint, proofObligationFingerprint)
+```
+
+A repeated wake or retry for the same tuple must reuse the existing obligation result. It must not create duplicate child issues, duplicate blockers, duplicate interactions, or an unbounded monitor loop.
+
+Allowed proof-obligation outcomes:
+
+- **Accepted**: the stopped state is legitimate. The watchdog records bounded evidence and leaves the source subtree on a valid terminal or waiting path.
+- **Restored**: the stopped state was wrong or incomplete. The watchdog reopens, reassigns, unblocks, creates in-subtree follow-up work, resolves an eligible plan confirmation, or sets a bounded monitor so work can continue.
+- **Deferred**: the watchdog found a real verification dependency. The dependency is represented by a first-class blocker, interaction, approval, human owner, typed reviewer, follow-up issue, recovery action, or one-shot monitor with owner and next action.
+- **Failed**: the watchdog cannot safely verify or restore the obligation. The reusable watchdog issue remains `blocked` or `in_review` with the real blocker, escalation owner, and next safe action.
+- **Dismissed**: the obligation is a false positive for this watchdog pass. The reusable watchdog issue records why no source mutation is needed, and the reviewed fingerprint may suppress future wakes for the same stopped state.
+
+Deferred is not a parking lot for uncertainty. It is valid only when the deferred dependency itself has a live or waiting path under §8. If the watchdog cannot name that path, the outcome is Failed and must escalate or block with a named owner/action.
+
+One-shot monitors are allowed only for bounded future checks owned by the current assignee, such as waiting for CI, an external review service, or a provider job. They are not recurring uptime monitoring. When a monitor fires, the assignee must decide the next proof outcome or explicitly re-arm a new bounded monitor; Paperclip must not loop indefinitely on the same proof obligation.
+
 ### Eligible interaction decisions
 
 A task watchdog may resolve only eligible `request_confirmation` plan confirmations. Eligibility is defined in `doc/SPEC-implementation.md` and must be checked by the server at decision time. The critical constraints are:
@@ -576,6 +605,7 @@ The watchdog's reviewed fingerprint should update only after the watchdog issue
 - `in_review` with a real reviewer, approval, interaction, user owner, monitor, or recovery path
 - `blocked` with first-class blockers or a named external owner/action
 - a watchdog mutation that restores live work, where the subsequent source-subtree mutation naturally changes the stop fingerprint
+- a dismissed false-positive proof obligation that records why no source mutation or further review is needed
 
 If the watchdog moved work forward, Paperclip should not mark the old fingerprint as permanently acceptable just because the watchdog issue completed. The next scan should observe the changed subtree state and either suppress because work is live or compute a new stopped fingerprint later.