docs(execution-semantics): §9.1/§10/§11 stalled-at-dispatch + adapter-staleness gaps (GRO-2055) #17

2026-06-02T02:45:13Z

Flea Flicker commented

2026-06-02 02:45:13 +00:00

First-time contributor

GRO-2055 Phase 1 — land execution-semantics.md patch

Applies the ready-to-apply patch in GRO-2055#document-phase1-patch to farhoodlabs/paperclip:dev.

Source plan: GRO-2053 (CEO-approved 2026-06-02).

Section-number drift (important)

The plan was written against an older revision of the document. Every section from "Crash and Restart Recovery" onward had shifted +1. The exact phrase the plan attributes to "§8.1" lives in the current §9.1. This PR applies the edits to the current sections, not the plan's numbers:

Plan reference	Current document section
§8.1 (Contract B)	§9.1 — Stranded assigned `todo`
§9, step 3	§10 — Startup and Periodic Reconciliation, step 3
§10 (Contract A)	§11 — Silent Active-Run Watchdog

Edits applied (3, verbatim)

§9.1 — Add stalled-at-dispatch recovery clause for issues with no prior linked run (Contract B). Updates the recovery rule and the closing dispatch-recovery note.
§10 step 3 — Make explicit that stalled-at-dispatch detection does not require a prior linked run. Extends the stranded-work closing sentence to cover the never-dispatched case.
§11 — Insert ### Adapter heartbeat staleness (pre-run) subsection extending the watchdog contract to adapter-level heartbeat staleness that predates any linked run (Contract A). Default 15 min threshold, bounded to one open recovery action per adapter per window.

Invariants preserved

Productive work continues — both contracts fire only on genuinely stalled states.
Only real blockers stop work — adapter stalls surface as explicit, owned recovery actions.
No infinite loops — Contract A: ≤1 recovery action per adapter per staleness window. Contract B: one dispatch wake, then bounded escalation to blocked + recovery action.

Acceptance

3 edits applied verbatim; only doc/execution-semantics.md changed.
PR open against farhoodlabs/paperclip:dev.
Body links GRO-2055 + GRO-2053 and notes the plan→doc section-number drift.

Co-author

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

## GRO-2055 Phase 1 — land execution-semantics.md patch Applies the **ready-to-apply patch** in [GRO-2055#document-phase1-patch](/GRO/issues/GRO-2055#document-phase1-patch) to `farhoodlabs/paperclip:dev`. **Source plan:** [GRO-2053](/GRO/issues/GRO-2053#document-plan) (CEO-approved 2026-06-02). ### Section-number drift (important) The plan was written against an older revision of the document. Every section from "Crash and Restart Recovery" onward had shifted **+1**. The exact phrase the plan attributes to "§8.1" lives in the **current §9.1**. This PR applies the edits to the **current** sections, not the plan's numbers: | Plan reference | Current document section | |---|---| | §8.1 (Contract B) | §9.1 — Stranded assigned `todo` | | §9, step 3 | §10 — Startup and Periodic Reconciliation, step 3 | | §10 (Contract A) | §11 — Silent Active-Run Watchdog | ### Edits applied (3, verbatim) 1. **§9.1** — Add stalled-at-dispatch recovery clause for issues with **no prior linked run** (Contract B). Updates the recovery rule and the closing dispatch-recovery note. 2. **§10 step 3** — Make explicit that stalled-at-dispatch detection does not require a prior linked run. Extends the stranded-work closing sentence to cover the never-dispatched case. 3. **§11** — Insert `### Adapter heartbeat staleness (pre-run)` subsection extending the watchdog contract to adapter-level heartbeat staleness that predates any linked run (Contract A). Default 15 min threshold, bounded to one open recovery action per adapter per window. ### Invariants preserved - Productive work continues — both contracts fire only on genuinely stalled states. - Only real blockers stop work — adapter stalls surface as explicit, owned recovery actions. - No infinite loops — Contract A: ≤1 recovery action per adapter per staleness window. Contract B: one dispatch wake, then bounded escalation to `blocked` + recovery action. ### Acceptance - [x] 3 edits applied verbatim; only `doc/execution-semantics.md` changed. - [x] PR open against `farhoodlabs/paperclip:dev`. - [x] Body links GRO-2055 + GRO-2053 and notes the plan→doc section-number drift. ### Co-author Co-Authored-By: Paperclip <noreply@paperclip.ing>

Flea Flicker added 1 commit 2026-06-02 02:45:13 +00:00

docs(execution-semantics): §9.1/§10/§11 stalled-at-dispatch + adapter-staleness gaps (GRO-2055) 607c57edab

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

Flea Flicker commented

2026-06-02 02:45:54 +00:00

First-time contributor

@cpfarhood — ready for review. This is a cross-repo PR from gb_flea/paperclip:docs/exec-semantics-gro2055 → farhoodlabs/paperclip:dev. Per GRO-2057, merge ownership is the platform maintainer (sole writer to farhoodlabs/paperclip); please merge. PR body links GRO-2055 and GRO-2053 and notes the plan→doc section-number drift.

@cpfarhood — ready for review. This is a cross-repo PR from `gb_flea/paperclip:docs/exec-semantics-gro2055` → `farhoodlabs/paperclip:dev`. Per [GRO-2057](/GRO/issues/GRO-2057), merge ownership is the platform maintainer (sole writer to `farhoodlabs/paperclip`); please merge. PR body links [GRO-2055](/GRO/issues/GRO-2055) and [GRO-2053](/GRO/issues/GRO-2053) and notes the plan→doc section-number drift.

Chris Farhood closed this pull request

2026-06-02 10:45:16 +00:00

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: farhoodlabs/paperclip#17

Allow edits from maintainers