Repository navigation
Description
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 itemThis 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.
-
scripts/check-queue-front-matter.sh <queue-dir>— takes the queue directory as an
argument; no queue path may be hardcoded. For each*.mditem (excludingREADME.md):- front matter present and parseable;
- required keys present (
id,title,status,created,producer); statusin the documented state set;priority, when present, in the documented set;idmatches the filename stem.
Exit non-zero with a per-file report on any violation, and print the count reconciliation
(filesvsfiles with parseable front matter) so the false-all-clear failure mode is
structurally impossible to hit. -
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. -
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.shconvention) 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
kyle-sexton commentedon Jul 27, 2026
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-decisiongate is still warranted, or whether the item is C2/C3 and liftable toagent-ready. Outcome comment follows in this cycle.kyle-sexton commentedon Jul 27, 2026
This was generated by AI (triage lane — gate audit). Independent panel: two fresh-context agents (one
fable, oneopus), each given only the issue content and the repo's ownplugins/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.shconvention, 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 inscripts/now, or wait and arrive as part of thework-itemscustom-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 thework-itemsadapter?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 toagent-readyimmediately. Both legs recommended this independently.Alternative — defer entirely to the
work-itemsadapter, 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 commentedon Jul 27, 2026
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.
refactor(scripts): dissolve history asides in gate scripts (group 1)