@entelligentsia/forgecli 0.7.10 → 0.8.4

package/skills/refresh-kb-links/SKILL.md

@@ -1,217 +0,0 @@
----
-name: refresh-kb-links
-description: Refresh Forge KB and workflow links in agent instruction files (CLAUDE.md, AGENTS.md, etc.)
----
-
-# forge:refresh-kb-links
-
-Scan every coding-agent instruction file in the project and ensure each has
-up-to-date links to the Forge knowledge base and generated workflow entry points.
-This skill is invoked by `/forge:refresh-kb-links` or conversationally via `/forge:ask`.
-
-## Setup
-
-Read the Forge config to determine the KB root path:
-
-```sh
-KB_PATH: !`node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}"`
-```
-
-## Known Agent Instruction Files
-
-Detect which of these files exist in the project root:
-
-| File | Coding tool |
-|------|------------|
-| `CLAUDE.md` | Claude Code |
-| `AGENTS.md` | OpenAI Codex / generic |
-| `AGENT.md` | generic |
-| `.github/copilot-instructions.md` | GitHub Copilot |
-| `.cursorrules` | Cursor (legacy) |
-| `.cursor/rules/*.mdc` | Cursor (current) |
-| `GEMINI.md` | Google Gemini |
-
-For each file found, check whether it already contains managed Forge sections.
-
-## Managed Section Markers
-
-Each file may have two independent managed sections:
-
-### KB links section
-
-Open marker (prefix match — tolerates minor text variations):
-```
-<!-- forge-kb-links
-```
-
-Close marker (exact):
-```
-<!-- /forge-kb-links -->
-```
-
-### Workflow links section
-
-Open marker (prefix match):
-```
-<!-- forge-workflow-links
-```
-
-Close marker (exact):
-```
-<!-- /forge-workflow-links -->
-```
-
-## Content Rules
-
-### KB section content
-
-Only include rows for files that actually exist on disk:
-
-- `{KB_PATH}/MASTER_INDEX.md` → "All sprints, tasks, bugs, and features"
-- `{KB_PATH}/architecture/INDEX.md` → "Stack, processes, database, routing, deployment"
-- `{KB_PATH}/business-domain/INDEX.md` → "Entity model and domain concepts"
-
-```markdown
-<!-- forge-kb-links: managed by Forge — do not edit manually -->
-## Forge Knowledge Base
-
-| Index | Contents |
-|-------|----------|
-| [MASTER_INDEX]({KB_PATH}/MASTER_INDEX.md) | All sprints, tasks, bugs, and features |
-| [Architecture]({KB_PATH}/architecture/INDEX.md) | Stack, processes, database, routing, deployment |
-| [Business Domain]({KB_PATH}/business-domain/INDEX.md) | Entity model and domain concepts |
-
-Personas live in `.forge/personas/`.
-<!-- /forge-kb-links -->
-```
-
-### Workflow section content
-
-Only include rows for workflow files that actually exist on disk. Check each:
-
-- `.forge/workflows/plan_task.md` → "Research codebase → implementation plan"
-- `.forge/workflows/implement_plan.md` → "Execute approved plan → code changes"
-- `.forge/workflows/fix_bug.md` → "Triage → fix → verify"
-- `.forge/workflows/orchestrate_task.md` → "Full task pipeline (plan → implement → review → commit)"
-- `.forge/workflows/run_sprint.md` → "Full sprint orchestration"
-- `.forge/workflows/architect_sprint_plan.md` → "Sprint planning and task decomposition"
-- `.forge/workflows/architect_sprint_intake.md` → "Sprint intake and requirements elicitation"
-
-```markdown
-<!-- forge-workflow-links: managed by Forge — do not edit manually -->
-## Forge Workflows
-
-| Workflow | Purpose |
-|----------|---------|
-| [Plan](.forge/workflows/plan_task.md) | Research codebase → implementation plan |
-| [Implement](.forge/workflows/implement_plan.md) | Execute approved plan → code changes |
-| [Fix bug](.forge/workflows/fix_bug.md) | Triage → fix → verify |
-| [Run task](.forge/workflows/orchestrate_task.md) | Full task pipeline (plan → implement → review → commit) |
-| [Run sprint](.forge/workflows/run_sprint.md) | Full sprint orchestration |
-<!-- /forge-workflow-links -->
-```
-
-(Only include rows where the referenced `.forge/workflows/` file exists on disk.)
-
-## KB Integrity Check
-
-Before scanning agent instruction files, verify that the knowledge graph itself is complete.
-The collate tool generates INDEX.md files at every node of the graph; if they are missing,
-links in MASTER_INDEX.md are broken and agents navigate to dead ends.
-
-Check the following, using `KB_PATH` as the root:
-
-1. **Sprint INDEX files** — for every directory under `{KB_PATH}/sprints/`, check that
-   `{KB_PATH}/sprints/{sprint-dir}/INDEX.md` exists.
-
-2. **Task INDEX files** — for every subdirectory under `{KB_PATH}/sprints/{sprint-dir}/`
-   that looks like a task folder (contains at least one `.md` file), check that its
-   `INDEX.md` exists.
-
-3. **Bug INDEX files** — for every directory under `{KB_PATH}/bugs/`, check that
-   `{KB_PATH}/bugs/{bug-dir}/INDEX.md` exists.
-
-If any INDEX files are missing, prepend this warning to the output (before the agent-file
-approval prompt):
-
-```
-⚠️  KB knowledge graph has broken links — INDEX.md files are missing:
-
-  △ {KB_PATH}/sprints/PROJ-S01/INDEX.md         — missing
-  △ {KB_PATH}/sprints/PROJ-S01/PROJ-S01-T01/INDEX.md — missing
-  △ {KB_PATH}/bugs/PROJ-B01-some-bug/INDEX.md   — missing
-
-Run collate to regenerate them:
-  node "$FORGE_ROOT/tools/collate.cjs"
-```
-
-If all INDEX files are present (or there are no sprint/task/bug folders yet), skip this
-block entirely. Do not warn when the KB is intact.
-
-## Staleness Check
-
-For each detected agent instruction file, check both sections:
-
-1. If the section marker is absent → section is **missing**
-2. If the section markers are present → extract the current content between them.
-   Compare current content vs. the content you would write (with current KB_PATH
-   and only existing files). If they differ → section is **stale**. If identical → **current**.
-
-## Approval Prompt
-
-After scanning all files, present a single consolidated approval prompt:
-
-```
-🏮 forge:refresh-kb-links — KB & Workflow Visibility
-
-Forge has generated a knowledge base and SDLC workflows for this project. Without links
-to these in your agent instruction files, every new conversation starts blind — no KB
-context, no workflow playbook.
-
-Found agent instruction files:
-  〇 CLAUDE.md        — no Forge KB links, no workflow links
-  〇 AGENTS.md        — no Forge KB links, no workflow links
-
-Add ## Forge Knowledge Base and ## Forge Workflows sections to each? [Y/n]
-(or choose individually: [c])
-```
-
-Adapt the status lines to reflect the actual state:
-- `〇 {filename}        — no Forge KB links, no workflow links` (both missing)
-- `〇 {filename}        — KB links stale` (KB section present but stale)
-- `〇 {filename}        — workflow links stale` (workflow section present but stale)
-- `〇 {filename}        — KB links stale, workflow links stale` (both stale)
-- `〇 {filename}        — links current, no changes needed` (both present and current — skip)
-
-**If all detected files already have current links:** output:
-
-```
-🏮 forge:refresh-kb-links — all KB and workflow links are current. No changes needed.
-```
-
-And return without prompting.
-
-## Writing Sections
-
-On approval ([Y] or per-file confirm):
-
-- **Missing section:** append the section to the end of the file.
-- **Stale section:** replace content between the open and close markers with fresh content.
-  Preserve everything outside the markers exactly.
-
-Write the `{KB_PATH}` substitution with the actual resolved path value (not the literal
-string `{KB_PATH}`). The resulting markdown should have real paths like `engineering/MASTER_INDEX.md`
-or `ai-docs/MASTER_INDEX.md`.
-
-## Idempotency
-
-On a second run where all links are already current, output the "all links current" message
-and return immediately. Do not re-write unchanged sections.
-
-## Rename Instructions
-
-If the user later renames the KB folder:
-
-1. Rename the folder on disk.
-2. Run: `node "$FORGE_ROOT/tools/manage-config.cjs" set paths.engineering <new-name>`
-3. Re-run `forge:refresh-kb-links` to refresh the links in all agent instruction files.

package/skills/store-custodian/SKILL.md

@@ -1,163 +0,0 @@
----
-name: store-custodian
-description: "Sole authorized gateway for reading and writing the Forge JSON store (.forge/store/). Use whenever a workflow needs to write sprints, tasks, bugs, features, or events — or read/list/validate/transition them. All store mutations MUST go through store-cli.cjs, never by writing files directly."
-allowed-tools:
-  - Bash
----
-
-# forge:store-custodian
-
-The Store Custodian is the **sole authorized gateway** for the probabilistic
-layer (LLM-driven workflows and commands) to read and modify the JSON store at
-`.forge/store/`. All store mutations must go through `store-cli.cjs`.
-
-**Hard rule: never fall back to writing store files directly.** If the CLI
-fails, read the error, fix the data, and retry. If it persists after retries,
-report the error to the user and stop.
-
-## FORGE_ROOT Resolution
-
-Before invoking any store-cli command, resolve the plugin root path:
-
-```sh
-FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
-```
-
-This reads the `paths.forgeRoot` field from the project config, which is set
-during `/forge:init` and refreshed by `/forge:update`. Do NOT hardcode the
-plugin install path.
-
-## Invocation
-
-All commands follow this pattern:
-
-```
-node "$FORGE_ROOT/tools/store-cli.cjs" <command> <args>
-```
-
-Exit codes: **0** on success, **1** on failure (validation error, illegal
-transition, entity not found, etc.).
-
-## Invocation Patterns
-
-### Write / Read / Mutate
-
-| Intent | Command |
-|--------|---------|
-| Write a sprint | `node "$FORGE_ROOT/tools/store-cli.cjs" write sprint '{...}'` |
-| Write a task | `node "$FORGE_ROOT/tools/store-cli.cjs" write task '{...}'` |
-| Write a bug | `node "$FORGE_ROOT/tools/store-cli.cjs" write bug '{...}'` |
-| Write a feature | `node "$FORGE_ROOT/tools/store-cli.cjs" write feature '{...}'` |
-| Read a task | `node "$FORGE_ROOT/tools/store-cli.cjs" read task FORGE-S01-T01` |
-| Read a task (raw JSON) | `node "$FORGE_ROOT/tools/store-cli.cjs" read task FORGE-S01-T01 --json` |
-| Update task status | `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task FORGE-S01-T01 status implemented` |
-| Update bug status | `node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug BUG-001 status triaged` |
-| Emit an event | `node "$FORGE_ROOT/tools/store-cli.cjs" emit FORGE-S01 '{...event-json...}'` |
-| Write a sidecar | `node "$FORGE_ROOT/tools/store-cli.cjs" emit FORGE-S01 '{...sidecar-json...}' --sidecar` |
-| Merge a sidecar | `node "$FORGE_ROOT/tools/store-cli.cjs" merge-sidecar FORGE-S01 20260415T141523Z_T01_plan_plan-task` |
-| Validate before write | `node "$FORGE_ROOT/tools/store-cli.cjs" validate task '{...}'` |
-| List entities | `node "$FORGE_ROOT/tools/store-cli.cjs" list task status=planned` |
-| List all sprints | `node "$FORGE_ROOT/tools/store-cli.cjs" list sprint` |
-| Delete an entity | `node "$FORGE_ROOT/tools/store-cli.cjs" delete task FORGE-S01-T01` |
-| Purge sprint events | `node "$FORGE_ROOT/tools/store-cli.cjs" purge-events FORGE-S01` |
-| Write collation state | `node "$FORGE_ROOT/tools/store-cli.cjs" write-collation-state '{...}'` |
-| Force a transition | `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task T01 status committed --force` |
-
-### Query
-
-Use the query engine to find entities by intent, sprint, or keyword — without manual KB navigation.
-
-| Intent | Command |
-|--------|---------|
-| Query by natural language | `node "$FORGE_ROOT/tools/store-cli.cjs" nlp "open bugs in S12"` |
-| Query sprint tasks/bugs | `node "$FORGE_ROOT/tools/store-cli.cjs" query --sprint S12` |
-| Query specific bug | `node "$FORGE_ROOT/tools/store-cli.cjs" query --bug {PREFIX}-BUG-047` |
-| Query specific task | `node "$FORGE_ROOT/tools/store-cli.cjs" query --task {PREFIX}-S12-T03` |
-| Keyword search | `node "$FORGE_ROOT/tools/store-cli.cjs" query --keyword auth` |
-| Project schema / grammar | `node "$FORGE_ROOT/tools/store-cli.cjs" schema` |
-| Query (strict mode, no NLP) | `node "$FORGE_ROOT/tools/store-cli.cjs" query --mode strict --sprint S12` |
-
-Query returns structured JSON: entity IDs, titles, statuses, relationships, fileRefs, INDEX.md excerpts.
-See `forge:store-query-nlp` for full output schema and confidence signals.
-See `forge:store-query-grammar` for NLP token vocabulary.
-
-## Entity Types
-
-| Entity | ID Field | Directory |
-|--------|----------|-----------|
-| sprint | `sprintId` | `.forge/store/sprints/` |
-| task | `taskId` | `.forge/store/tasks/` |
-| bug | `bugId` | `.forge/store/bugs/` |
-| event | `eventId` | `.forge/store/events/{sprintId}/` |
-| feature | `id` | `.forge/store/features/` |
-
-## Error Handling
-
-On exit code 1:
-1. Read stderr for the validation error message.
-2. Fix the data that caused the error (missing required fields, illegal
-   transition, invalid JSON, etc.).
-3. Retry the command (max 2 retries).
-4. If the command still fails after retries, report the validation error to
-   the user and stop. Do NOT fall back to writing store files directly.
-
-## Commands Reference
-
-### `write <entity> '<json>'`
-
-Write a full entity record. Validates against the schema before writing.
-Rejects on validation error (exit 1 + per-field stderr messages). No partial
-write on failure.
-
-### `read <entity> <id> [--json]`
-
-Read an entity record. Pretty-printed by default. `--json` outputs raw JSON for
-parsing.
-
-### `list <entity> [key=value ...]`
-
-List entities with optional key=value filter pairs. Numeric values are
-auto-parsed. Outputs JSON array.
-
-### `delete <entity> <id>`
-
-Delete an entity record. No validation needed.
-
-### `update-status <entity> <id> <field> <value> [--force]`
-
-Atomic status/enum field update with transition check. Reads the current
-record, verifies the transition is legal, applies the update, and writes back.
-Use `--force` to bypass the transition check (emits a warning on stderr).
-
-### `emit <sprintId> '<json>' [--sidecar]`
-
-Write an event record. With `--sidecar`, writes a `_{eventId}_usage.json`
-ephemeral sidecar file instead of a canonical event. Sidecars require only an
-`eventId` field; they are merged into the canonical event later.
-
-### `merge-sidecar <sprintId> <eventId>`
-
-Merge sidecar token fields into the canonical event, then delete the sidecar.
-Fails if either file is missing.
-
-### `purge-events <sprintId>`
-
-Delete all event files for a sprint.
-
-### `write-collation-state '<json>'`
-
-Write COLLATION_STATE.json to the store root. Delegates to the store facade.
-
-### `validate <entity> '<json>'`
-
-Validate a record against the schema without writing. Reports errors on
-stderr, exits 1 on failure, exits 0 on success with `{"ok":true,"valid":true}`.
-
-## Flags
-
-| Flag | Applies to | Effect |
-|------|-----------|--------|
-| `--dry-run` | All write commands | Validate and preview without writing |
-| `--force` | `update-status` | Bypass transition check (warns on stderr) |
-| `--json` | `read` | Output raw JSON (no pretty-print) |
-| `--sidecar` | `emit` | Write as sidecar file (ephemeral, `_-prefixed`) |

package/skills/store-query-grammar/SKILL.md

@@ -1,145 +0,0 @@
----
-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):
-
-```sh
-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:
-
-```json
-"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

package/skills/store-query-nlp/SKILL.md

@@ -1,110 +0,0 @@
----
-name: store-query-nlp
-description: "Query the Forge store using natural language. Use when you need to find tasks, bugs, sprints, or features by intent — e.g. 'open bugs in S12', 'blocked tasks', 'tasks implementing the auth feature', 'how many bugs are critical'. Returns structured JSON with entity IDs, titles, statuses, relationships, file refs, and INDEX.md excerpts."
-allowed-tools:
-  - Bash
----
-
-# 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:
-
-```sh
-FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
-```
-
-## Invocation
-
-```sh
-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
-
-```json
-{
-  "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
-
-```sh
-# 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:
-
-```sh
-node "$FORGE_ROOT/tools/store-cli.cjs" list bug
-# Then scan titles manually
-```
-
-Or read `engineering/MASTER_INDEX.md` directly.