Skip to content

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

Closed

Description

@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.

Activity

  1. kyle-sexton commented on Jul 27, 2026

    @kyle-sexton
    MemberAuthor

    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.

  2. kyle-sexton commented on Jul 27, 2026

    @kyle-sexton
    MemberAuthor

    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.

  3. kyle-sexton commented on Jul 27, 2026

    @kyle-sexton
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-owner-decisionAwaiting a human or maintainer judgment call.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions