gloss-agent-check

name	gloss-agent-check
description	Review pending gloss candidate session files with the gloss-agent-check CLI - prepare the word-selection payload, decide each ambiguous Pāli word's dictionary sense, write the answers file, and apply it to produce agent-checked sessions for the built-in gloss data bank.

Gloss agent check — reviewing candidate session files

You are the reviewing agent in the gloss data-bank pipeline (docs/gloss-ai-word-selection.md §7): candidate session files generated by gloss-corpus-explore contain ambiguous Pāli words, each with a list of DPD dictionary senses. Your job is to pick the correct sense for every ambiguous occurrence, using the sentence context. Confirmed selections are shipped as built-in-agent-checked cache rows in the app's database.

Paths and environment

All commands run from the cli/ directory of this repo. The data-cache root defaults to ../../bootstrap-assets-resources/gloss-data-cache (override with --data-cache DIR). Folders under it:

folder	role
candidates/	generated, unreviewed input files (candidates-*.json)
agent-answers/	transient answers files you write (git-ignored)
agent-checked/	finished output sessions (committed)
human-checked/	sessions reviewed by a human in the Gloss UI

SIMSAPA_DIR must be set — the CLI opens the real databases (apply validates every selected uid against the dictionaries):

export SIMSAPA_DIR=/home/gambhiro/prods/apps/simsapa-ng-project/bootstrap-assets-resources/dist/simsapa

Procedure

Work one candidate file per apply cycle — bounded, verifiable increments. Never start a second file before the current one has applied successfully.

1. Find pending work:

   cargo run --release -- gloss-agent-check status
   

   Lists pending candidates, agent-checked files (with review counts), and human-checked files. Pick the first pending candidate.

2. Prepare the payload for that file:

   cargo run --release -- gloss-agent-check prepare \
       ../../bootstrap-assets-resources/gloss-data-cache/candidates/candidates-001.json \
       --out /path/to/scratchpad/candidates-001-payload.json
   

   The payload is {"task": "pali_word_selection", "items": [...]}. Each item carries word (the inflected surface form), context (the sentence window; <b>…</b> marks the target occurrence), source_uid (the sutta reference, e.g. sn56.11/pli/ms), and options. There are three item kinds, distinguished by the id suffix (docs/gloss-ai-word-selection.md):

   • Sense items (p<paragraph>w<word>): the options are candidate DPD dictionary senses — each has uid, word (the DPD lemma, e.g. ārāma 4), and a summary of the sense.
   • Break-down items (…d): the word is a compound/sandhi form with ≥ 2 possible deconstructions; each option's word is a break-down string (e.g. sādhu + iti) and its uid a pseudo-uid (d:0, d:1, …). Pick the break-down that fits the context.
   • Component items (…c<k>): the item's word is the compound and component_word names one of its component words; the options are DPD senses for that component. The item's deconstructions array lists the compound's break-downs as strings; a breakdowns array (when present) lists the break-down strings this component occurs in. Pick the sense the component has within the compound in this context, consistent with the break-down you selected for that compound (when it has a break-down item).

3. Decide every item using the context sentence, the source_uid (sutta-level knowledge, e.g. standard formulas), and the option summaries. Apply the selection guidance below.

Selection guidance

• Prefer the sense that fits the grammatical role of the word in the sentence (case, number, verb form; the summaries state part-of-speech).
• Standard formulaic openings and refrains (e.g. evaṁ me sutaṁ, ekaṁ samayaṁ, bhagavā etadavoca) have conventional senses — use them.
• When two senses are near-synonymous in the context, pick the lower-numbered / more general one and mark it confident.
• When the context window is genuinely insufficient, or the senses diverge in meaning and the context does not settle it, mark confidence: "review" with a one-line note explaining the doubt. Review entries are skipped by the import (never written as confirmed rows) and surface in status counts for human follow-up — flagging honestly is better than guessing.
• Copy the option's word lemma verbatim — including sense numbers and diacritics (ārāma 4, suta 1.3, √gam). A mistyped lemma fails validation; that is the safety net, do not defeat it by "fixing" spellings.

Hard rules

• One file per apply cycle. Finish (apply successfully) the current candidate before preparing the next.
• Never edit candidate or agent-checked JSON files directly. The answers file in agent-answers/ is your entire write surface; the CLI produces the agent-checked/ output. Hand-edited session files break the identical-by-construction guarantee of options, uids, and context hashes.
• Do not move files into human-checked/ — promotion from agent-checked to human-checked is a deliberate manual act by the user.
• Do not regenerate candidates or re-run the gloss lookup; the options baked into the candidate file are trusted as-is.