warded: nudge the agent (pull-freshness / land-on-main / re-read-thread) when it runs git pull or git branch #300

New issue

Closed

opened 2026-06-25 03:59:57 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-06-25 03:59:57 +00:00

Member

Problem

Headless ward agent runs sometimes lose the thread mid-run and waste time: working off stale state, branching when they should be landing on main, or forgetting context that was in the issue body/thread. The new "how it felt" retros (ward#281) make this legible after the fact, but there's no in-run nudge that catches it while it's happening.

Idea (from Kai): inject a short reminder at the moment the agent runs git pull or git branch - the natural points where an agent is reorienting around branch/sync state - so the guidance lands exactly when it's relevant rather than buried in the seed prompt.

Scope of the reminder

Trigger: a git invocation whose subcommand is pull or branch (any form: git pull, git branch ..., git -C x branch).

Content (three nudges, kept short):

Pull-before-work freshness - confirm you're on fresh main before branching/working, so you don't build on stale state.
Land-on-main flow - the carry ends by merging to main, pushing to canonical Forgejo, and closing the issue with the closes #N trailer. Don't strand work on a side branch or skip the push.
Re-read the issue thread - re-read the issue body + comment thread for context you may have dropped mid-run.

Explicitly out of scope: container-gotcha reminders (cred store perms, missing trufflehog/kdlfmt). Those are real provisioning bugs to fix (see ward#288 + the image-republish follow-up), not things to paper over with a reminder.

Mechanism (all-harness)

Decision: the reminder must fire for every headless harness (claude, codex, goose), not just claude. The existing ward hook pre-tool-use surface is registered only into claude's .claude/settings.json (install_hooks.go, matcher Bash -> ward hook pre-tool-use), so it's claude-only.

The only command-execution chokepoint all harnesses share is the git binary itself. So the faithful all-harness implementation is a thin git wrapper placed ahead of real git on the container PATH (provisioned in container_bootstrap.go): for pull/branch it prints the reminder to stderr (lands in the agent's command output), then execs the real git unchanged. Idempotent, no behavior change to git, fails open if the wrapper errors.

Open design question for the implementer: whether to also route the claude path through the existing ward hook pre-tool-use for a richer (structured additionalContext) nudge, or keep a single git-wrapper path for uniformity. Lean uniform unless there's a reason not to.

Acceptance

A headless run on any harness that runs git pull or git branch sees the three-nudge reminder in that command's output.
Real git behavior is unchanged (exit code, stdout, args passthrough).
Covered by a table test on the wrapper's subcommand detection (pull/branch vs push/commit/status).
docs/FEATURES.md + a short walkthrough updated per the trifecta rule.

## Problem Headless `ward agent` runs sometimes lose the thread mid-run and waste time: working off stale state, branching when they should be landing on `main`, or forgetting context that was in the issue body/thread. The new "how it felt" retros (ward#281) make this legible after the fact, but there's no in-run nudge that catches it while it's happening. Idea (from Kai): inject a short reminder **at the moment the agent runs `git pull` or `git branch`** - the natural points where an agent is reorienting around branch/sync state - so the guidance lands exactly when it's relevant rather than buried in the seed prompt. ## Scope of the reminder Trigger: a `git` invocation whose subcommand is `pull` or `branch` (any form: `git pull`, `git branch ...`, `git -C x branch`). Content (three nudges, kept short): - **Pull-before-work freshness** - confirm you're on fresh `main` before branching/working, so you don't build on stale state. - **Land-on-main flow** - the carry ends by merging to `main`, pushing to canonical Forgejo, and closing the issue with the `closes #N` trailer. Don't strand work on a side branch or skip the push. - **Re-read the issue thread** - re-read the issue body + comment thread for context you may have dropped mid-run. Explicitly **out of scope**: container-gotcha reminders (cred store perms, missing trufflehog/kdlfmt). Those are real provisioning bugs to fix (see ward#288 + the image-republish follow-up), not things to paper over with a reminder. ## Mechanism (all-harness) Decision: the reminder must fire for **every** headless harness (claude, codex, goose), not just claude. The existing `ward hook pre-tool-use` surface is registered only into claude's `.claude/settings.json` (`install_hooks.go`, matcher `Bash` -> `ward hook pre-tool-use`), so it's claude-only. The only command-execution chokepoint **all** harnesses share is the `git` binary itself. So the faithful all-harness implementation is a thin `git` wrapper placed ahead of real git on the container `PATH` (provisioned in `container_bootstrap.go`): for `pull`/`branch` it prints the reminder to stderr (lands in the agent's command output), then `exec`s the real git unchanged. Idempotent, no behavior change to git, fails open if the wrapper errors. Open design question for the implementer: whether to *also* route the claude path through the existing `ward hook pre-tool-use` for a richer (structured `additionalContext`) nudge, or keep a single git-wrapper path for uniformity. Lean uniform unless there's a reason not to. ## Acceptance - A headless run on any harness that runs `git pull` or `git branch` sees the three-nudge reminder in that command's output. - Real git behavior is unchanged (exit code, stdout, args passthrough). - Covered by a table test on the wrapper's subcommand detection (`pull`/`branch` vs `push`/`commit`/`status`). - `docs/FEATURES.md` + a short walkthrough updated per the trifecta rule.