store-query-grammar

name	store-query-grammar
description	Reference for the Forge NLP query grammar — entity synonyms, status synonyms, ordering tokens, FK phrases, and ID patterns. Use when constructing or debugging store-query-nlp queries, or to understand why a query returned unexpected results.
allowed-tools	["Bash"]

forge:store-query-grammar

NLP grammar reference for the Forge store query engine.

The query engine (store-cli.cjs nlp) uses a 5-stage deterministic rule-based parser — no LLM, no network. This skill documents the token vocabulary so you can construct precise queries and debug unexpected parse results.

Setup

Dump the live grammar for the current project (includes project-specific ID patterns):

FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
node "$FORGE_ROOT/tools/store-cli.cjs" schema

The schema command returns entity schemas, status enums, and the full grammar reference for the installed project prefix.

Parser Stages

Stage 1 — ID Patterns (highest priority)

Matched first; consumed tokens are excluded from later stages.

Pattern	Example	Resolves to
{PREFIX}-S##-T##	WI-S12-T03	task filter
{PREFIX}-BUG-###	WI-BUG-047	bug filter
FEAT-###	FEAT-003	feature filter
S##	S12	sprint filter
sprint N	sprint 12	sprint filter → S12

Stage 2 — Entity Detection

The parser identifies the primary entity type from synonyms. First match wins.

Entity	Synonyms
sprints	sprint, sprints, release, releases, iteration, iterations
tasks	task, tasks, item, items, work item, work items, todo, todos
bugs	bug, bugs, defect, defects, issue, issues, problem, problems
features	feature, features, epic, epics, capability, capabilities

Bigrams are matched before unigrams (e.g. work item → tasks).

Stage 3 — Status / Severity Filters

Maps natural-language status phrases to schema enum values per entity type.

Input phrase	tasks	bugs	sprints	features
open / active / in progress	implementing	in-progress	active	active
completed / done	committed	fixed	completed	shipped
fixed	—	fixed	—	—
planned / planning	planned	—	planning	—
implementing	implementing	—	—	—
implemented	implemented	—	—	—
committed	committed	—	—	—
draft	draft	—	—	draft
abandoned	abandoned	—	abandoned	—
retired	—	—	—	retired
shipped	—	—	—	shipped
triaged	—	triaged	—	—
reported	—	reported	—	—
blocked	blocked	—	—	—

Severity (bugs only, sets severity field not status):

Input	Severity
critical	critical
major	major
minor	minor

Stage 4 — FK Follow Phrases

Trigger FK traversal in the result set.

Phrase	FK followed
with sprint / sprint for / which sprint	sprintId
with feature / feature for	featureId
block / blocking / blocked	blocksTask (for bugs) or blockedBy (for tasks)

Stage 4b — Ordering and Limit Tokens

Token(s)	Effect
latest / newest / recent / most recent	sort desc, limit 1
oldest / earliest / first	sort asc, limit 1
last	sort desc, limit 1
top N / first N	sort desc/asc, limit N
last N	sort desc, limit N
how many / count of / number of / count	count mode (returns {count: N})

Stage 5 — Keyword Extraction

Remaining tokens (not consumed by stages 1–4, not in stop words, length > 1) become keyword match terms on the title field (word-boundary match).

Stop words include all entity synonyms plus: list, all, the, show, find, what, which, are, in, for, about, related, to, of, and, with, details, status, how, many, there, a, an, is, that, this, on, by, me, give, get, tell, please, can, do, does, did, was, were, been, being, have, has, had, will, would, could, should, may, might, blocking, blocked, block, severity, titles, title.

Debugging Queries

If a query returns unexpected results, use traversalTrace in the output:

"traversalTrace": [
  "intent parsed via NLP rules",
  "listed tasks with filter {\"status\":\"implementing\"}: 7 results",
  "sorted tasks desc",
  "limited to 3 (of 7)",
  "plan confidence: high"
]

Common debug patterns:

Symptom	Likely cause
0 results, retried	Status phrase didn't map to a valid enum for the detected entity type
confidence: low	Filter value stripped — check the status mapping table above
Wrong entity type	Entity synonym matched a stop word before the intended synonym
Keyword matching too broadly	Term is short (≤1 char) or in stop words; try a more specific term
Missing FK traversal	FK phrase not in stage 4 vocabulary; use --with-sprint / --with-feature flags instead

Query Composition Tips

• Put entity type first: "bugs in S12" not "S12 bugs" — entity is detected in order
• Use exact ID when known: "WI-BUG-047" is faster and more precise than "bug about auth"
• Count before listing: "how many open bugs" before "open bugs" for large stores
• Combine stages naturally: "critical open bugs in S12 blocking tasks" uses stages 1, 2, 3, 4 together