store-query-nlp

forge:store-query-nlp

Translate natural language intent into a structured Forge store query. Returns filtered, FK-resolved results with excerpts — replacing manual KB navigation.

When to use: anytime you need to find entities without knowing exact IDs, or want filtered/sorted results from a sprint/feature/status. Replaces reading MASTER_INDEX.md manually when a focused query is sufficient.

Setup

Resolve the plugin root path before any invocation:

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

Invocation

node "$FORGE_ROOT/tools/store-cli.cjs" nlp "<natural language query>"

Returns JSON to stdout. Exit 0 on success, 1 on error.

Example Queries

Intent	Example
Bugs in a sprint	"open bugs in S12"
Blocked tasks	"blocked tasks"
Tasks by status	"implementing tasks in S14"
Critical bugs	"critical bugs"
Tasks for a feature	"tasks for FEAT-003"
Sprint overview	"sprint S12"
Specific bug	"WI-BUG-047"
Specific task	"WI-S12-T03"
Latest sprint	"latest sprint"
Count query	"how many open bugs"
Blocking chain	"bugs blocking tasks in S12"

Output Structure

{
  "query": "open bugs in S12",
  "path": "intent-nlp",
  "traversalTrace": ["..."],
  "results": [
    {
      "id": "WI-BUG-047",
      "title": "...",
      "status": "in-progress",
      "type": "bug",
      "relationships": { "sprintId": "S12", "blocksTask": ["WI-S12-T03"] },
      "fileRefs": { "json": ".forge/store/bugs/WI-BUG-047.json", "md": "engineering/bugs/..." },
      "excerpt": "First few sentences from INDEX.md..."
    }
  ],
  "relatedFileRefs": ["..."],
  "meta": { "mode": "auto", "engineVersion": "1.0.0", "totalTimeMs": 42 }
}

Interpreting Results

• traversalTrace — explains the NLP parse path (entity detected, filters applied, FKs followed, confidence level)
• fileRefs.md — path to the INDEX.md for this entity; read it for full context
• fileRefs.json — path to the store JSON record; use with store-cli read for full data
• excerpt — first 4 sentences from the INDEX.md; often sufficient without a Read() call
• relatedFileRefs — flat list of all referenced files, ready for batch Read()
• meta.totalTimeMs — wall-clock query time; typical range 5–80ms

Confidence Signals

Check traversalTrace for confidence:

• plan confidence: high — all filters validated against schema enums/patterns
• plan confidence: low — one or more filters were stripped as invalid; results may be broader than expected
• overall confidence: low (required retry) — primary query returned 0 results; retried as keyword-only search

When confidence is low, verify results or fall back to reading MASTER_INDEX.md.

Mode Control

# Explicit NLP mode (default for nlp subcommand)
node "$FORGE_ROOT/tools/store-cli.cjs" nlp "open bugs in S12"

# Strict mode — exact flags only, no NLP (baseline comparison)
node "$FORGE_ROOT/tools/store-cli.cjs" query --mode strict --sprint S12 --status in-progress

Fallback

If the query returns 0 results or low confidence, fall back to:

node "$FORGE_ROOT/tools/store-cli.cjs" list bug
# Then scan titles manually

Or read engineering/MASTER_INDEX.md directly.