handoff-queue: consumer-side front-matter validator (a status grep reports a false all-clear on a malformed item)

[kyle-sexton]

Problem

The cross-terminal handoff queue this repo consumes (a file-based markdown queue outside the repo,
one item per file with YAML front matter) has no front-matter validation on the consumer side.
Items arrive off-schema routinely, and one specific failure mode is actively dangerous:

A grep '^status:' reconciliation reports a false all-clear. An item deposited with no front
matter at all is invisible to a status grep, so the queue reads as fully drained while unprocessed
work sits in it. This produced a live false all-clear during a drain session — the queue was
declared empty with an unprocessed item present.

Observed rates in one batch: 3 of 7 newly-deposited items were malformed — two with no front
matter whatsoever, one with off-schema values (status: open, which is not in the documented state
set unclaimed | claimed | in-progress | blocked | done).

The interim rule (already in force, undocumented in this repo)

Reconcile the queue by file count, never by status grep:

n=$(ls 2026*.md | wc -l)
s=$(grep -l '^status:' 2026*.md | wc -l)
# any gap between n and s is an unprocessed malformed item

This rule currently lives only in session handoff notes. It is load-bearing and has no tracked home.

Proposal (needs a decision)

A consumer-side front-matter validator, plus a tracked home for the reconciliation rule.

1. scripts/check-queue-front-matter.sh <queue-dir> — takes the queue directory as an
   argument; no queue path may be hardcoded. For each *.md item (excluding README.md):

   • front matter present and parseable;
   • required keys present (id, title, status, created, producer);
   • status in the documented state set;
   • priority, when present, in the documented set;
   • id matches the filename stem.

   Exit non-zero with a per-file report on any violation, and print the count reconciliation
   (files vs files with parseable front matter) so the false-all-clear failure mode is
   structurally impossible to hit.

2. Run it at claim time in the consumer flow — the point where an agent decides "is there work?"
   — and treat a validation failure as "write conforming front matter first, then claim," not as a
   reason to skip the item.

3. Document the count-based reconciliation rule wherever the consumer flow is described.

Constraints this must respect

• Consumer side only. The write-time fix belongs to the queue producer, which is a separate
  project in a different identity domain; this repo cannot reach it and must not try. This issue
  scopes strictly to detection and repair on the consuming side.
• Repo-agnostic (CLAUDE.md): the queue directory is a parameter, never a baked-in path. The
  script must work against any directory following the queue's documented schema.
• Not a CI gate. The queue lives outside the repository, so no CI job can see it. This is an
  operator/agent-invoked utility, and its own test file (scripts/*.test.sh convention) is what CI
  actually exercises.

Open question for the maintainer

Is scripts/ the right home, or should this graduate with the queue itself into a work-items
custom adapter? The queue's own README already names that graduation path ("when concurrent
multi-agent claiming becomes a hard requirement, graduate the whole store to a work-items custom
adapter"). If the adapter is coming anyway, a throwaway script in scripts/ may be the wrong
investment — but the false-all-clear is live today and the adapter is not scheduled.

Related

• Deferred from the queue-drain batch that closed at 27/27 done; recorded as an unstarted next
  step in that batch's handoff, with no issue filed until now.

[kyle-sexton]

This was generated by AI (triage lane — gate-audit claim). Claiming this item for one gate-audit cycle: an independent panel re-classifies whether the needs-human / status: needs-decision gate is still warranted, or whether the item is C2/C3 and liftable to agent-ready. Outcome comment follows in this cycle.

[kyle-sexton]

This was generated by AI (triage lane — gate audit). Independent panel: two fresh-context agents (one fable, one opus), each given only the issue content and the repo's own plugins/autonomy/reference/guardrails/work-classes.md, plus the triage lane's own read. This lane never executes work items, authors fixes, or merges.

Gate audit: GATE UPHELD — one unanswered maintainer question, blocking the first line of code

Panel: 2-of-2 STAYS-GATED, both C3. Lane read concurs.

The validator itself is well specified — argument-not-hardcoded queue dir, required keys (id, title, status, created, producer), documented state set, id-matches-filename-stem, non-zero exit with count reconciliation, scripts/*.test.sh convention, explicitly not a CI gate. Implementation is not the problem.

What holds the gate is the issue's own ## Open question for the maintainer: does this live in scripts/ now, or wait and arrive as part of the work-items custom-adapter graduation the queue's README already names? Two defensible answers, no decision recorded — and the answer determines whether the first line should be written at all.

This is the narrowest gate in the batch: one sentence from the maintainer converts it into a clean C3 lift.

Decision required

Does the front-matter validator land now as scripts/check-queue-front-matter.sh, or wait for the work-items adapter?

RECOMMENDED — build it now in scripts/. The false all-clear (a status grep reporting clean on a malformed item) is a live failure mode today, the adapter is unscheduled, the script is cheap, and its validation logic can migrate into the adapter later rather than being thrown away. The count-reconciliation rule is load-bearing and currently has no tracked home. Record this decision on the issue and it can flip to agent-ready immediately. Both legs recommended this independently.

Alternative — defer entirely to the work-items adapter, avoiding throwaway investment and accepting the live false-all-clear in the interim. Reasonable only if the adapter is about to be scheduled.

[kyle-sexton]

This was generated by AI (triage lane — claim release). Gate-audit cycle complete for this item; the triage claim posted earlier this cycle is released. No lease is held — another instance or lane may pick this up immediately. The outcome comment above this one carries the classification and either the lift rationale or the decision summary.