Tighten scrub skill delivery contract (#3205)

to make the golem do things

Author: dlwh

.agents/skills/handle-gh-scrub/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: handle-gh-scrub
+description: Base execution contract for scheduled scrub runs in marin-community/marin.
+---
+
+# handle-gh-scrub
+
+Use this skill for scheduled scrub turns.
+
+## Workflow
+
+1. Read the requested `scrub-*` skill and apply it for this run.
+2. Decide whether useful progress is available now.
+3. If useful work exists, implement and validate it.
+4. Publish outcomes before ending the run:
+   - commit/push to a branch
+   - open/update a PR when code or docs changed
+5. If publish is blocked (token/permissions/infra), keep the run open and schedule follow-up.
+6. If no-op is correct, explicitly report inspected scope and why no change was justified.
+
+## Completion Contract
+
+- Do not end a run with uncommitted local changes.
+- `HARNESS_SCRUB_LOOP {"needs_followup_at":null}` is only valid when either:
+  - a visible artifact exists (commit/branch/PR), or
+  - a justified no-op outcome is recorded.
+- If work is partially done or blocked, set a future `needs_followup_at`.
+
+## Required Footer
+
+Your response must end with exactly one line in this format:
+
+```text
+HARNESS_SCRUB_LOOP {"needs_followup_at":null}
+```
+
+Rules:
+
+- Keep JSON valid and on one line.
+- Set `needs_followup_at = null` when the current scrub run is complete.
+- Use a future RFC 3339 timestamp (with timezone/offset) when this run needs another follow-up turn.

.agents/skills/scrub-docs-code-parity/SKILL.md

@@ -25,4 +25,7 @@ Use this skill on scheduled scrub turns for docs/code parity in `marin-community
 ## Output
 
 - Keep the final scrub response concise and action-focused.
+- Treat local-only edits as incomplete work. If you modify files, publish the result (commit/push and open or update a PR) before finishing this scrub run.
+- If publish is blocked (auth, permissions, CI infra, etc.), report the blocker and set a future `needs_followup_at` instead of ending the run.
+- If no material drift is found, explicitly report inspected scope and why no change was needed.
 - Always end with the required `HARNESS_SCRUB_LOOP` footer (provided by the base scrub contract).

.agents/skills/scrub-reflection-self-improvement/SKILL.md

@@ -33,4 +33,7 @@ Use this skill on scheduled scrub turns to identify and land high-leverage impro
 
 - Keep rationale explicit: observed gap, change made (or plan), and expected impact.
 - Prefer durable artifacts over transient notes: land guidance updates in `AGENTS.md` and/or recipe docs when that is the primary improvement.
+- Treat local-only edits as incomplete work. If you modify files, publish the result (commit/push and open or update a PR) before finishing this scrub run.
+- If publish is blocked (auth, permissions, CI infra, etc.), report the blocker and set a future `needs_followup_at` instead of ending the run.
+- If you choose no-op, include explicit inspected signals and why no justified improvement exists now.
 - Always end with the required `HARNESS_SCRUB_LOOP` footer (provided by the base scrub contract).