dos-goal-gate

# dos-goal-gate — gate "I'm done" on a witness, not on self-report

> **A completion condition the agent checks against its own narration is the
> exact failure DOS exists to fix.** When an agent decides "the goal is met" by
> re-reading what it just wrote, the part deciding ground truth *is* the part
> being judged — that is **consistency, not grounding** (docs/138). This skill
> never decides done-ness by re-reading the transcript. It turns the goal into a
> set of checkable EFFECT claims, then wires the Stop decision so the agent
> cannot stop until a read-back whose **byte-author is not the agent** (git
> ancestry, an OS exit code, a fresh state read) corroborates each effect. The
> kernel decides; the skill narrates.

The shape is domain-free: **state the goal as effects → wire the Stop gate →
on each stop, witness every effect → stop only when all are corroborated.** The
*policy* (which plan grammar, which lanes, where state lives) is data read from
`dos doctor --json`, never literals this screenplay hardcodes.

**Why this is not just "ask the model if it's done."** A harness stop-condition
("keep going until X") is evaluated by a model reading the session — so a
confident, fluent narration of an X that the world does not corroborate ends the
work early (the silent fail of docs/177). The gate below replaces that judgment
with a verdict over evidence the agent did not write: a phase is done when *git*
says a commit backs it, not when the agent says it committed; a file exists when
a *fresh read* finds it, not when the agent says it wrote it.

## When to use this (and when not)

- **Use it** when a single agent self-paces toward a stated goal and you want its
  "done" to be unfalsifiable-by-narration — a `/loop` worker, a self-stopping
  task agent, or any run where the operator stated a completion condition.
- **Use `dos-witness-claim` instead** when many workers' results are folded at a
  `parallel()`/`pipeline()` barrier — that skill is the *fan-out fold* analogue;
  this one is the *single-agent self-stop* analogue. Same witness discipline,
  different site.
- **This is advisory (a PDP, not a PEP — docs/99).** It computes a Stop verdict
  and lets the runtime act on it via the user-owned hook seam. It blocks a *false*
  done; it never blocks a *true* one, and it never enforces beyond the Stop hook.

## Inputs

- The operator's **goal** — the completion condition in plain words ("the auth
  refactor is shipped and the suite is green", "the migration plan's phases are
  all landed"). Free prose is the *input*, never the *test*.
- Optionally, a **transcript path** for the running session (the Stop event
  carries it; you rarely pass it by hand).

## Step 0 — Discover the workspace layout (one call)

Run the doctor verb and read the result. **Every path / lane / exit-code below
comes from here, never a literal.**

```bash
dos doctor --workspace . --json
```

The fields this skill uses:

- `exit_codes.verify` — `{shipped, not_shipped, contract_error}`. Branch on these
  for a **git-phase** effect (Step 2a), never on parsing prose.
- `exit_codes."verify-result"` — `{healthy, unreadable, dead, contract_error}`
  (`dead=3`). Branch on these for the **terminal-state** witness when a transcript
  is in play.
- `paths.plans_glob` / `lanes` / `stamp` — the host's plan grammar, lane taxonomy,
  and ship-stamp convention, if a goal names a `(plan, phase)`.
- `git` — if `false`, the git-existence witness (Step 2a) has no history; every
  git-phase effect resolves `source="none"`. Say so; do not silently pass it.
- `runtime_hooks` — which runtimes already have a `dos hook …` Stop entry wired
  (so you know whether Step 1 still needs doing).

## Step 1 — Wire the Stop gate (once per workspace)

The gate is `dos hook stop`: a Stop / SubagentStop hook that refuses to let the
agent stop while a confidently-CLAIMED phase is NOT corroborated by git. Wire it
into the runtime's settings — idempotent, merged into any existing hooks, never
clobbering the operator's own:

```bash
dos init --with-hooks --workspace .      # Claude Code (the default runtime)
# cross-runtime: dos init --hooks <runtime> --workspace .   (preview with --dry-run)
```

This binds three hooks; the load-bearing one here is **Stop → `dos hook stop`**.
On every stop it extracts the `(plan, phase)` the agent claimed and refuses the
stop (feeding the verdict back as the next instruction) if git does not back it.
That refusal IS the grounded form of "keep working until the goal is met": the
work cannot end on the agent's word that a phase shipped.

> **Two Stop hooks, opposite triggers — do not conflate them.** `dos hook stop`
> blocks a *false done* (the agent claimed a phase, git disagrees). `dos hook
> marker` (docs/259) blocks a *premature give-up while a keep-alive budget is
> unspent*, then gets out of the way. A host may wire both; this skill is about
> the first. If your goal is "don't stop polling yet," that is `dos hook marker`,
> not this gate.

### Step 1a — How this composes with the harness `/goal` command

The Claude Code `/goal <condition>` command is itself a **session-scoped Stop
hook — but a *model-evaluated* one**: a fast model re-reads the session after each
turn and rules on whether the condition holds. That is precisely the
consistency-not-grounding shape this skill exists to fix — the judge is a model
reading the agent's own narration, with no witness the agent did not author.

You do **not** replace `/goal`; you wire `dos hook stop` (Step 1) **alongside**
it, and the harness combines them for you. Claude Code runs every matching Stop
hook in parallel and applies an **ANY-block** rule: *the stop is refused if **any**
hook blocks it* (a `{"decision":"block",…}` at exit 0, or exit 2). So with both
active, the agent may stop only when the `/goal` model-judge **AND** the grounded
git gate both allow it — a logical AND of "the narration reads done" and "ground
truth backs it." The grounded gate can only ever *add* a re