Skip to main content

Live Delivery Reconciliation

Use when reconciling live delivery status. Use this skill for questions such as “what is actively being worked on?”, “work status”, “is this PR ready?”, or after the user reports a merge. The goal is a current, evidence-backed operational picture—not a replay of remembered state or a list of queued cards.

Core distinction​

Classify every lane into exactly one operational category:

  1. Active writer — a live mutation-capable worker is tied to the issue/worktree, and current task-scoped repository mutation exists or the worker has just started with an explicit first-mutation checkpoint.
  2. Active verification — tests, build, install, review, or exact-head validation is running, but no code writer is active. Never count this toward a writer floor.
  3. Waiting for human action — merge, platform test, tenant comparison, credential, approval, or explicit waiver is required.
  4. Queued — claimable/todo work exists, but no live executing process owns it.
  5. Blocked or stale — a card/label says work exists, but runtime evidence is absent, contradictory, or dependency-blocked.
  6. Complete — merged/closed and reconciled; no further work may be appended to the finished branch or PR.

Do not collapse these categories into a vague “in progress.”

Truth hierarchy​

Use current evidence in this order:

  1. Live GitHub PR/issue state and exact head SHA.
  2. Live OS process identity, command, cwd/worktree, and parentage.
  3. Hermes-tracked background processes and subagents.
  4. Running verification commands tied to a worktree.
  5. Kanban task state and scheduler state.
  6. GitHub labels, comments, and remembered status.

Labels and queue cards are projections, not proof of execution. An in-progress label without a live owner is stale until proven otherwise. A todo or blocked card is not active work.

Workflow​

1. Re-read terminal events​

If the user says a PR merged, verify live state, mergedAt, merge commit, and current head context before discussing follow-on work. Mark the PR/branch terminal in your reasoning and identify stale human-action cards or labels for reconciliation.

2. Take a unified runtime census​

Check, in parallel where possible:

  • Hermes subagents.
  • Hermes-tracked background terminal jobs.
  • OS-level coding/review workers, including Claude, OpenCode, Codex, Terra, Sol, Reasonix, and Luna routes.
  • Child build/test/install processes whose cwd identifies a delivery worktree.
  • Relevant scheduler jobs and whether one is currently executing.
  • Kanban cards filtered to non-complete states.
  • GitHub open PRs plus issues labeled in-progress and ready.
  • Containers only when they can materially own or support the work being reported.

See references/github-and-runtime-probes.md for resilient probes and API fallbacks.

3. Correlate identity​

For each process, map:

  • PID and parent PID.
  • Worktree/cwd.
  • Issue or PR number from command/worktree/card metadata.
  • Route/model when available.
  • Whether it can mutate, only verify, or merely supervise.
  • Current repository mutation or immutable candidate SHA.

Do not count a supervisor, scheduler, gateway, compiler, npm ci, test runner, or reviewer as a writer.

4. Verify claimed activity​

Before calling a lane an active writer, require both:

  • A live writer process whose command and cwd match the lane.
  • Task-scoped mutation evidence, unless the process was launched moments ago and the report explicitly says it has not reached its first mutation.

Use git status --short, git diff --stat, branch, and HEAD. Remember that substantive work may be untracked; an empty git diff --stat does not mean an empty worktree. Inspect git status --short too.

5. Handle races caused by reconciliation​

A scheduler or supervisor may spawn workers while the census is running. If a manual scheduler fire reports “already running,” do not conclude nothing happened. Recheck OS processes and worktrees before the final answer. Report the final observed state, not the earlier snapshot.

6. Validate PR readiness​

Read live PR state, draft status, mergeability, head SHA, reviews/comments, and exact-head CI. Exact-head approvals expire on PR-head mutation; unrelated base movement does not invalidate head-bound evidence unless it introduces conflict, protection failure, or material overlap.

When GraphQL statusCheckRollup or REST check-runs is permission-restricted, query Actions runs by head_sha and verify each relevant run’s event, status, conclusion, and head SHA. Do not translate an empty legacy commit-status list into failed CI.

Partial-delivery readiness traps​

Resolve whether the user's number names an issue or a PR before discussing approval. An issue's ready label can mean claimable, not human-review-ready. For mapping/import/baseline work, execute the validator AND derive populated versus missing rows from the artifact: a passing bounded validator may intentionally allow incomplete rows. Compare that result against the complete issue acceptance contract.

Check authoritative execution-card reviews before claiming that no review evidence exists. Exact Terra/Sol approvals for an immutable bounded slice do not establish parent-issue completion or PR readiness; state both facts separately. Keep issue number, card ID, worktree, and candidate SHA joined when interpreting comments. A misfiled comment about a different issue's candidate is not a blocker for this issue.

Circular native-platform sequencing holds​

When a dependency-cleanup PR is held for native Windows acceptance while production driver replacement is held until that PR merges, identify the cycle explicitly. Preserve merge/release gates; use one serial reviewed stack or a fully gated combined successor to allow implementation without premature parent merge. A descendant artifact/test result does not certify the original parent SHA. Reconcile exact package/lock/database/fixture ownership and preserve old branches/review history; do not waive platform checks or restart a known-failing native install. Record the corrective next-action plan on the existing coordinator and verify readback, distinguishing handoff from actual launch and delivery.

7. Reconcile projections​

When authorized, correct stale in-progress labels, completed human-action cards, merged-PR cards, and dependency projections. After any external write, read back the exact target. If reconciliation is already running, avoid duplicate dispatch and verify its eventual observable effect.

For body-only PR updates, gh pr edit may fail because its GraphQL query touches deprecated Projects Classic fields even though the PR and authentication are valid. Fall back to PATCH /repos/{owner}/{repo}/pulls/{number} through gh api, then read the PR back from REST. Build multiline Markdown payloads with structured argument arrays or JSON serialization. Never interpolate Markdown containing backticks into an unquoted shell heredoc or eval: shell command substitution can execute text such as `npm test` before GitHub receives it.

Human test handoffs and repeated blockers​

Before giving copy-paste test instructions, verify the exact candidate's prerequisites on the target platform. If a known dependency prevents installation or packaging, give only the independently runnable test portion now; do not include the unavailable build commands in the immediate procedure, even under a conditional heading. State the prerequisite that will unlock the remaining instructions and withhold them until a viable candidate exists. A user repeating the same platform error needs delivery reconciliation, not another retry recipe.

For urgent “I need this working” questions, distinguish the user's immediate failure, the next internal verification prerequisite, remaining production integration, and any lack of an active owner. Read preserved untracked prototypes and their handoffs before saying implementation has not started. Prototype existence, reported Node tests, Electron verification, production adoption, and native installer acceptance are separate milestones. Attribute handoff results unless independently rerun; do not promote them to verified release evidence.

Do not stop at a status-only promise when authorized recovery is available: use the established controller/owner path, preserve productive workers, and verify any dispatch before claiming work resumed. If recovery is not performed, state that plainly rather than implying a running planner is fixing the blocker.

See references/platform-test-handoff-lessons.md for the motivating example and test-handoff checklist.

Completion audits of unfinished builds​

When the user asks a named reviewer to review an existing build/plan and says they need it implemented, treat the audit as an input to authorized delivery—not the completion of the request. Reconcile installed source, newer candidate branches, current owner identities, and external deployment receipts before accepting the old plan's status. Preserve active mutation owners; an isolated read-only audit may proceed without becoming a competing writer. Correct obsolete route/escalation policies in the revised plan against current user authority.

Give the existing durable completion owner an explicit audit-to-implementation handoff rather than creating another supervisor. Verify that handoff by reading back its exact configuration. Report audit launch, report completion, validated plan, implementation, deployment, and acceptance separately: a live process or configured continuation proves none of the later milestones. See references/completion-audit-handoff.md for the evidence and handoff checklist.

Audit-to-execution acceptance discipline​

For this user's “Implement the plan,” the deliverable is accepted work, not a manager prompt, coordination card, first green gate, or dispatched pass. Those are checkpoints. Keep the existing owner and continuation obligation, advance the next safe acceptance phase, and report any remaining work explicitly. If the owner exits into backoff, describe it as queued/backed off—not active implementation.

Before executing an advisory recovery plan, reconcile its candidate identities, latest review verdicts, and user-specific authority against current evidence. Equal line counts do not prove byte equivalence; an earlier approval does not erase a later changes-requested verdict. Missing override evidence in an audit packet is not permission to replace an explicit user role override or ask the user to approve it again. Suggested migration numbers must be derived from fresh main, not hardcoded from the audit.

A coordination card must cover the complete issue acceptance contract, including downstream wiring and full-baseline delivery—not only the preserved slices selected as dependencies. A writer-dispatch blockage does not necessarily block safe gate/review jobs; do not clear controller state or retry history to force progress. Verify the actual next job and its receipt independently of the manager's prose.

See references/preserved-candidate-recovery.md for evidence capture, plan corrections, and the demonstrated gate handoff pattern.

Owner-facing merge and decision handoff​

For this user's “what can I review and merge?” or “what is waiting on me?”, lead with two separate answers: open PRs available for review and PRs actually cleared to merge. Enumerate the fresh live list with links; explicitly say when none is merge-ready. Conflict-free GitHub state, green host-only CI, historical local approval, formal GitHub review, owner acceptance and native/security release acceptance are different evidence classes. An approved unpublished candidate is an agent-owned integration/publication obligation, not something the user can approve in GitHub. If author and reviewing user are the same account, distinguish an owner-acceptance comment from a formal independent approval.

Organize the owner list into: actionable decisions now, reviews requiring an agent-prepared exact-candidate packet, later native/live testing blocked on implementation, and intentionally deferred product choices. Describe the exact subject and prerequisite; never ask for a blanket source/fingerprint approval or tell the user to repeat a known-blocked install. Do not ask again for already-granted policy decisions. Missing human acceptance must not halt safe technical preparation, gates or review.

For complete benchmark delivery, report canonical source controls separately from retained historical rules, automated checks, manual availability and imported evidence. Passing generators or correcting false claims does not prove complete availability: a truthful remediation may remove a whole pillar. Verify current artifact schema keys before counting sections, and compare per-identity availability against the pinned source universe, not just totals. Use the latest bounded approval to preserve work, not to close the whole parent issue.

See references/merge-readiness-and-owner-decisions.md for the decision-packet and recovery-audit checklist.

Already-authorized local-build recovery​

When this user asks whether they must do anything to advance an already-approved build, distinguish owner-only gates from an absent execution owner. Do not repeatedly answer “nothing is waiting on you” while leaving recoverable agent-side work idle. Where the existing mandate includes dispatch/recovery, use its established owner path without requiring another approval; a reporting-only task must remain read-only unless recovery is authorized.

An hourly status job is not a delivery supervisor. Inspect its actual prompt/script before crediting it with continuation. A stale implementation_running field plus an absent recorded PID requires live worktree/process reconciliation, not repetition of the field. A worker restart is proven by a surviving exact-route child and a fresh task-scoped source/test change; parser and whitespace checks certify only that bounded checkpoint, not functional acceptance or durable supervision repair.

See references/local-build-stall-recovery.md for the observed recovery pattern, detector pitfalls, and evidence limits.

Review findings versus code-launch requests​

When asked what a named reviewer requested, read the latest applicable report and identify its reviewed artifact and round. Separate product-code findings from plan, evidence-schema, and review-admission findings. Report severity, concrete remediation, and any review-integrity qualification; a completed document review is not candidate approval.

For this user's subsequent “launch [model] to make the code changes,” explicitly check whether the live named-model process is planning-only. Do not present that process, a waiting handoff, or a verified board comment as the requested implementation launch. Preserve existing productive owners, resolve the current phase gate against actual user authority, and advance the first admissible implementation action. Do not silently waive an explicit gate, but do not invent a new approval requirement either. If code launch remains blocked, lead with “Code implementation has not launched” and name the exact unmet prerequisite; recorded authorization is only an intermediate checkpoint.

A manual cron run skipped as “already running” does not prove its transient prompt reached the executing owner. Persist the instruction on an established owner-consumed surface and verify readback, while distinguishing persistence from owner acknowledgment and actual execution. Recheck live phase/process evidence before final reporting.

See references/review-scope-and-launch-evidence.md for the evidence boundaries illustrated by the CIS plan-review handoff.

Local acceptance versus deployment readiness​

A missing worker can mean completed local acceptance, not a stalled build. Read the latest acceptance record and its referenced final review before interpreting older stall memories or historical REQUEST CHANGES reports. Match the reviewed SHA to live HEAD and clean status. A deliberately frozen task checkbox may lag an external exact-head acceptance artifact; report the discrepancy without mutating the approved candidate merely to update its checkbox.

Distinguish recorded passing gates from tests rerun during this status check. Owner-approved security exceptions are not remediation: report the raw audit failure and residual risk separately from the exception-policy result. Local acceptance, remote code publication, application deployment, host integration, and live-provider acceptance are separate milestones and authorizations.

See references/local-acceptance-evidence.md for the evidence reconciliation pattern.

Security decisions during asynchronous delivery​

A timed-out approval form grants nothing. If the user says “prompt me again,” reopen the same bounded decision rather than infer approval or restart unrelated discovery. Once answered, preserve the exact decision and conditions outside an immutable review worktree, then reconcile every owner-consumed brief/status/reporting surface. A saved decision plus a cron trigger does not prove an already-running reviewer consumed it. Check the actual retry brief: stale “awaiting owner approval” text can survive a successful supervisor tick. Correct that projection without claiming technical controls verified; if necessary obtain a bounded same-head SOL disposition incorporating the decision. Never ask the user to approve an already-granted identical scope again.

Keep code verdict, conditional security exception, local deployment, and remote/TLS acceptance separate. Continue safe remediation and isolated verification while an owner-only exception is unanswered. A narrow build-tool exception must not silently extend from disposable validation into retained publication workflows; explain exact advisories/graph, changed usage, residual risk, compensating controls and revalidation triggers.

Before handling a completion callback, reconcile both current scheduler state and exact-CWD OS children. A manager may already have launched the next writer/reviewer. Use the existing owner's dispatch path or an explicit shared exclusion before foreground launch; promptly editing status after launch is not collision prevention.

See references/docker-delivery-and-approval-handoffs.md for the Docker provenance gates, approval propagation failure, and owner-specific deployment boundary demonstrated in Research Hub.

Reporting format​

Lead with the operational answer.

  • Active writers: issue links, concrete task, route, and mutation checkpoint.
  • Active verification: issue/PR, exact candidate, gate currently running.
  • Waiting: only material human or external gates.
  • Queued/blocked: summarize only when needed to prevent a false impression that they are executing.

State discrepancies plainly, for example: “GitHub marks #140 in progress, but no live worker exists, so the label is stale.” Avoid dumping the entire backlog or every historical card.

Invariants​

  • Never infer “active” from labels, assignment, recent comments, or a started timestamp alone.
  • Never count validation activity as a mutation-capable writer.
  • Never cite remembered PR state without a same-turn live read.
  • Never append work to a merged PR branch.
  • Never report a declared total without deriving it from the current collected set.
  • Recheck after actions that can change the fleet before finalizing status.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/live-delivery-reconciliation/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/live-delivery-reconciliation/ · view source · Imported 2026-10-03. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-03.