magnus919_agent-skills/neckbeard/references/progress-and-finality.md

# Progress and Finality

How to judge whether work is advancing, when to keep going, when a bounded
check of an asynchronous dependency is justified, and when to stop or
escalate. One rule governs every section: **decide on semantic state — never
on elapsed time, iteration counts, timestamps, request IDs, or how many times
the same state has been observed.**

## Semantic progress, not iteration count

Progress means the world changed in a way that moves an acceptance criterion
forward: a changed artifact, a confirmed or falsified hypothesis, a new stage,
a changed dependency state, or a new output cursor from an asynchronous
system. An advancing timestamp, a fresh request ID, a poll counter, or the
continued existence of a process is *volatile churn* — it is not progress and
must never be recorded as evidence of progress.

Judge churn by content, not by source. A heartbeat whose only change is its
timestamp is churn. But a heartbeat that carries an advancing payload — a new
phase or step, a processed-item count, a new output cursor — is reporting
semantic state: record that payload in the declared semantic state, and it
counts as progress. The timestamp itself stays out of the fingerprint either
way.

The failure mode this page prevents is not "too many turns." It is repeated
observation of an unchanged semantic state while the declared stage action
remains untaken.

## The dependency contract

When a stage hands off to an asynchronous system, record — in the change
contract and the evidence ledger — whether a dependency is required for the
next stage:

- **Accepted/finished output with no required dependency:** the next action is
  to advance or deliver, or to declare the run terminal-complete. A status
  poll before that action is never justified.
- **A pending or failed dependency explicitly required for the next stage:**
  a bounded check is justified once (see below). Required-or-not is part of
  the contract, not something to re-derive mid-run.

Treat `accepted`/`finished` as a stage output, not automatically as whole-run
completion. Terminality is declared only when the contract has no required
dependency left.

## Bounded checks

One infrastructure check per normalized state fingerprint. The fingerprint is
computed from: stage, deliverable state, dependency state, whether the
dependency is required, and the declared semantic state. Volatile fields —
timestamps, request IDs, raw poll counters — are excluded from the
fingerprint, so a timestamp-only heartbeat difference is unchanged state. An
advancing heartbeat payload (a new phase, step count, or output cursor)
belongs in the declared semantic state; when it advances, the fingerprint
changes and the new state receives its own check allowance.

- First observation of a fingerprint: one check is allowed.
- The fingerprint changes (pending → succeeded, or a new output cursor):
  continue; the new fingerprint gets its own check allowance.
- The fingerprint is unchanged: do not re-check. Change the mechanism or
  escalate. An identical re-poll is a finality failure even when the
  timestamp and request ID differ.

## Complex work

There is no arbitrary turn cap. Continue while each turn produces new
evidence or a changed semantic state and at least one acceptance criterion
remains unmet. Multi-turn diagnosis, design iteration, and long test loops
are productive work when the semantic state keeps changing; a turn-count
ceiling must never stop them.

## Active-process ledger

The evidence ledger stays canonical. When work is asynchronous — or an
escalation is being considered — extend the run's record with an
active-process entry:

| Field | Content |
|---|---|
| `id` | Stable identifier for the asynchronous hand-off. |
| `status` | Current normalized state. |
| `output` | Latest meaningful output or artifact reference. |
| `normalized_state` | Fingerprint inputs: stage, deliverable state, dependency state, dependency-required flag, semantic state. |
| `dependency_required` | Whether the dependency gates the next stage. |
| `next_action` | The declared stage action: `work`, `check`, `advance`, `deliver`, `complete`, `mechanism_change`, or `escalate`. |
| `expected_transition` | What the next *semantic* change would look like. |
| `checks_for_state` | How many checks this fingerprint has consumed. |
| `escalation_trigger` | The condition under which the next unchanged observation escalates. |

## Examples

**Accepted but not blocked.** The deliverable is accepted; a publish job is
pending, but nothing requires it before delivery. Correct: deliver or
complete now. Wrong: check the publish job first.

**Genuinely pending dependency.** The delivery stage requires a published
release. One check is spent; the next observation shows the dependency
succeeded with a new output cursor. Correct: proceed to delivery. If the
observation had been unchanged, the correct move is a mechanism change or
escalation — not a second check.

**Productive multi-step work.** Three turns on an in-progress deliverable,
each with a new hypothesis, benchmark, or artifact, ending in verification
and delivery. Correct at any length: every turn changed the semantic state.

**Identical re-poll (failure).** Two observations with identical semantic
state but different timestamps and request IDs, with a check on each, while
the delivery action stays untaken. This fails finality: the second check was
an identical re-poll; the response to the unchanged result should have been a
mechanism change or escalation.

## Non-portable examples excluded

Keep this contract harness-neutral. Do not express the rules in terms of
specific tool names, scheduler or cron identifiers, process IDs, platform API
names, or any vendor's polling semantics. Describe state, dependencies,
actions, and terminality; each harness maps them to its own mechanisms.