@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/forge-payload/meta/tool-specs/generation-manifest.spec.md

@@ -0,0 +1,139 @@
+# Tool Spec: generation-manifest
+
+## Purpose
+
+Track and verify the integrity of Forge-generated files via content hashes.
+Distinguishes between files that are pristine (unchanged since generation) and
+files that have been manually modified. Used by regeneration, migration, and
+health checks to avoid silently overwriting user edits.
+
+## Manifest file
+
+Stored at `.forge/generation-manifest.json`. Committed to version control so
+the whole team shares the same baseline. Structure:
+
+```json
+{
+  "files": {
+    ".forge/workflows/plan_task.md": {
+      "hash": "sha256:a3f9...",
+      "generatedAt": "2026-04-06T10:00:00.000Z",
+      "generatedByVersion": "0.5.0"
+    }
+  }
+}
+```
+
+## Inputs
+
+- `.forge/generation-manifest.json` — the manifest file (read/write)
+- CLI arguments — subcommand and target path
+
+## Outputs
+
+- Modified `.forge/generation-manifest.json` in-place (write subcommands)
+- Printed status or tables to stdout (read subcommands)
+- Exit codes (see per-subcommand below)
+
+## CLI Interface
+
+```
+generation-manifest record <path>
+```
+Hash the file at `<path>` and store/update its entry in the manifest.
+Records `hash`, `generatedAt` (ISO timestamp), and `generatedByVersion`
+(read from `.forge/config.json → version`, or `"unknown"`).
+Exit 0 on success.
+
+```
+generation-manifest record-all
+```
+Re-hash every file currently listed in the manifest. Skips missing files
+with a `△ Missing` note. Prints a summary line on completion.
+Exit 0 always (missing files are not an error).
+
+```
+generation-manifest check <path>
+```
+Compare the current content hash of `<path>` against the stored hash.
+
+| Exit code | Meaning |
+|-----------|---------|
+| 0 | Pristine — content matches the stored hash |
+| 1 | Modified — content has changed since it was recorded |
+| 2 | Untracked — file is not in the manifest |
+| 3 | File not found on disk |
+
+Output one status line to stdout regardless of exit code.
+
+```
+generation-manifest list [--modified]
+```
+Print a markdown pipe table of all tracked files with columns
+`Status | File | Version | Date`.
+With `--modified`: only show modified and missing files.
+If all files are pristine, print `〇 All tracked files are pristine.`
+
+```
+generation-manifest status
+```
+Print a compact summary: total tracked count, and counts per status
+(pristine / modified / missing). No table.
+
+```
+generation-manifest remove <path>
+```
+Remove a file from the manifest without touching the file itself.
+Exit 1 if the file is not tracked.
+
+## Hash algorithm
+
+SHA-256 of normalised content:
+1. Normalise line endings to LF (`\r\n` → `\n`)
+2. Strip trailing whitespace from each line
+3. Hash the resulting UTF-8 string
+4. Prefix the hex digest with `"sha256:"`
+
+This prevents false positives from editor-inserted trailing spaces or
+CRLF/LF differences across platforms.
+
+## What to track
+
+Record hashes for files that Forge generates and might overwrite on
+regeneration, but that users may legitimately customise:
+
+| Category | Pattern |
+|----------|---------|
+| Workflows | `.forge/workflows/*.md` |
+| Templates | `.forge/templates/*.md` |
+| Generated commands | `.claude/commands/{forge-generated}.md` |
+
+Do NOT track:
+- Knowledge base files (`engineering/architecture/`, `stack-checklist.md`) — expected to evolve via writeback
+- Collated views (`MASTER_INDEX.md`, `TIMESHEET.md`) — rebuilt from the store
+- Store JSON files (`.forge/store/`) — data, not generated artifacts
+
+## Status symbols
+
+| Symbol | Meaning |
+|--------|---------|
+| 〇 | Pristine — matches stored hash |
+| △ | Modified — diverged from stored hash |
+| × | Missing — file not found on disk |
+
+## Error handling
+
+- Wrap entry point in `process.on('uncaughtException')` — all errors print to
+  stderr prefixed with `×` and exit 1. No unhandled exceptions or stack traces.
+- If `.forge/generation-manifest.json` is missing, treat it as an empty manifest
+  (no files tracked) — do not error.
+- If `.forge/generation-manifest.json` contains invalid JSON, exit 1 with a
+  parse error message.
+- Write atomically: temp file + rename. Never leave a partial write.
+
+## Formatting rules
+
+- `list` output: markdown pipe table, status column shows `{symbol} {status}`
+- `check` output: one line to stdout: `{symbol} {relpath}: {status-description}`
+- `status` output: one line per non-zero count, prefixed with symbol
+- Success messages prefixed with `〇`; warnings with `△`; errors with `×`

package/dist/forge-payload/meta/tool-specs/manage-config.spec.md

@@ -0,0 +1,143 @@
+# Tool Spec: manage-config
+
+## Purpose
+
+Read and write `.forge/config.json` safely. Deterministic — no AI needed.
+Preserves key order, indentation, and all fields not explicitly modified.
+
+## Inputs
+
+- `.forge/config.json` — the config file to read or modify
+- CLI arguments — subcommand and options (see CLI Interface)
+
+## Outputs
+
+- Modified `.forge/config.json` in-place (write subcommands)
+- Printed values or reports to stdout (read subcommands)
+- Exit 0 on success, 1 on validation error, 2 on usage error
+
+## CLI Interface
+
+### Read subcommands
+
+```
+<tool> manage-config get <key.path>
+```
+Print the value at the dot-notation path (e.g., `project.prefix`,
+`pipelines.measure-conversion`). Exit 1 if the path does not exist.
+
+```
+<tool> manage-config list-pipelines
+```
+Print a table of all pipeline names, their descriptions, and phase counts.
+If no `pipelines` key exists, print `── No pipelines configured.` and exit 0.
+
+```
+<tool> manage-config pipeline get <name>
+```
+Print the full detail of a named pipeline as a markdown phase table with
+columns `# | Role | Command | Workflow | Model | maxIter`.
+Exit 1 with `× Pipeline '{name}' not found` if the name does not exist.
+
+### Write subcommands
+
+```
+<tool> manage-config pipeline add <name> --description <text> --phases <json>
+```
+Add or replace a named pipeline. `--phases` accepts a JSON array string of
+phase objects, each with `command` and `role` (required), and optionally
+`model`, `maxIterations`, `on_revision`, and `workflow`.
+
+```
+<tool> manage-config pipeline remove <name>
+```
+Remove a named pipeline. Exit 1 if the name does not exist.
+
+```
+<tool> manage-config set <key.path> <json-value>
+```
+Set an arbitrary dot-notation path to a JSON value. Creates intermediate
+objects as needed. Intended for first-party Forge tooling only — not
+advertised in user-facing help.
+
+## Validation Rules
+
+Applied before any write. Exit 1 and print a clear error if any rule fails.
+
+### Pipeline phases
+- Each phase must have `command` (non-empty string) and `role` (string).
+- `role` must be one of: `plan`, `review-plan`, `implement`, `review-code`,
+  `approve`, `commit`.
+- `maxIterations` must be a positive integer when present.
+- `workflow` (optional string) — path to a custom workflow file. When present,
+  the orchestrator invokes this file directly instead of the built-in workflow
+  for the command name. Used for custom phase commands in `engineering/commands/`.
+- At least one phase is required per pipeline.
+
+### Pipeline name
+- Must be a non-empty string containing only `[a-z0-9_-]`.
+- The name `default` is valid and overrides the hardcoded default pipeline.
+
+### File integrity
+- If `.forge/config.json` is not valid JSON, exit 1 with a parse error.
+  Never overwrite a corrupt file.
+
+## Algorithm
+
+### Read path (`get`)
+1. Read and parse `.forge/config.json`.
+2. Traverse the dot-notation path.
+3. Print the value as JSON (pretty-printed if object/array, bare if scalar).
+
+### Write path (`pipeline add`)
+1. Read and parse `.forge/config.json`. Fail fast on parse error.
+2. Run validation rules against the incoming phases. Fail fast on error.
+3. Ensure `config.pipelines` key exists (create empty object if absent).
+4. Merge the new pipeline entry under `config.pipelines[name]`.
+5. Serialise back to JSON with the same indentation as the source file
+   (detect indent from the first indented line; default to 2 spaces).
+6. Write atomically: write to a temp file alongside `config.json`, then
+   rename over the original. Never leave a partial write.
+
+### Write path (`pipeline remove`)
+1. Read and parse `.forge/config.json`.
+2. Check `config.pipelines[name]` exists; exit 1 if not.
+3. Delete the key.
+4. If `config.pipelines` is now empty, remove the `pipelines` key entirely.
+5. Serialise and write atomically (same indent detection as above).
+
+## Error Handling
+
+- Wrap the entire entry point in a top-level exception handler.
+- On unexpected errors (file I/O failures, JSON parse errors, unhandled
+  exceptions), print a clear one-line message to stderr and exit 1.
+- Never let the tool crash with an unhandled exception or stack trace visible
+  to the caller — all errors are caught and reported cleanly.
+- Python pattern:
+  ```python
+  if __name__ == "__main__":
+      try:
+          sys.exit(main())
+      except Exception as e:
+          print(f"Error: {e}", file=sys.stderr)
+          sys.exit(1)
+  ```
+- JS/TS pattern:
+  ```js
+  process.on('uncaughtException', (e) => {
+      process.stderr.write(`Error: ${e.message}\n`);
+      process.exit(1);
+  });
+  ```
+
+## Formatting Rules
+
+- Preserve the original indentation of the file.
+- Do not reorder top-level keys.
+- Do not add or remove trailing newlines beyond what was present.
+- `list-pipelines` output: markdown pipe table with columns
+  `Name | Description | Phases`. Print `(none)` when description is absent.
+- `pipeline get` output: optional description line prefixed with `──`, then
+  a markdown pipe table with columns `# | Role | Command | Workflow | Model | maxIter`.
+  Print `(built-in)` when `workflow` is absent; `—` when `maxIterations` is absent.
+- Success messages prefixed with `〇`; errors prefixed with `×`; neutral info with `──`.

package/dist/forge-payload/meta/tool-specs/seed-store.spec.md

@@ -0,0 +1,91 @@
+# Tool Spec: seed-store
+
+## Purpose
+
+Bootstrap the JSON store from an existing `engineering/` directory structure.
+Used when a project already has sprint/task artifacts but no JSON store.
+
+## Inputs
+
+- `.forge/config.json` — project prefix, paths
+- `engineering/sprints/` — existing sprint directories
+- `engineering/bugs/` — existing bug directories
+
+## Outputs
+
+- `.forge/store/sprints/*.json` — one per discovered sprint
+- `.forge/store/tasks/*.json` — one per discovered task
+- `.forge/store/bugs/*.json` — one per discovered bug
+
+## CLI Interface
+
+```
+<tool> seed-store              # scan and create
+<tool> seed-store --dry-run    # preview what would be created
+```
+
+Exit 0 on success, 1 on error.
+
+## Output Field Schema
+
+All JSON files use **camelCase** field names to match `validate-store`.
+
+**Sprint** (`.forge/store/sprints/<ID>.json`):
+```json
+{ "sprintId": "PREFIX-S01", "title": "...", "status": "active" }
+```
+
+**Task** (`.forge/store/tasks/<ID>.json`):
+```json
+{ "taskId": "PREFIX-S01-1", "sprintId": "PREFIX-S01", "title": "...", "status": "planned" }
+```
+
+**Bug** (`.forge/store/bugs/<ID>.json`):
+```json
+{ "bugId": "PREFIX-B01", "title": "...", "severity": "medium", "status": "reported" }
+```
+
+Status defaults: sprint → `"active"`, task → `"planned"`, bug → `"reported"`.
+Infer a better status from artifact presence when possible (e.g. PROGRESS.md
+with "committed" → `"committed"`).
+
+## Error Handling
+
+- Wrap the entire entry point in a top-level exception handler.
+- On unexpected errors (missing config, unreadable directories, unhandled
+  exceptions), print a clear one-line message to stderr and exit 1.
+- Never let the tool crash with an unhandled exception or stack trace visible
+  to the caller — all errors are caught and reported cleanly.
+- Python pattern:
+  ```python
+  if __name__ == "__main__":
+      try:
+          sys.exit(main())
+      except Exception as e:
+          print(f"Error: {e}", file=sys.stderr)
+          sys.exit(1)
+  ```
+- JS/TS pattern:
+  ```js
+  process.on('uncaughtException', (e) => {
+      process.stderr.write(`Error: ${e.message}\n`);
+      process.exit(1);
+  });
+  ```
+
+## Algorithm
+
+1. Read `.forge/config.json` for prefix and paths
+2. Scan `engineering/sprints/` for sprint directories (pattern: S{NN})
+3. For each sprint directory:
+   a. Create sprint JSON using the camelCase schema above
+   b. Scan for task directories (pattern: T{NN})
+   c. For each task directory:
+      - Read PLAN.md, PROGRESS.md if they exist
+      - Extract title, status from artifact content
+      - Create task JSON using the camelCase schema above
+4. Scan `engineering/bugs/` for bug directories
+5. For each bug directory:
+   a. Read available artifacts
+   b. Create bug JSON using the camelCase schema above
+6. Report: N sprints, N tasks, N bugs seeded

package/dist/forge-payload/meta/tool-specs/store-cli.spec.md

@@ -0,0 +1,328 @@
+# Tool Spec: store-cli
+
+## Purpose
+
+Deterministic store custodian CLI — the sole authorized gateway for the
+probabilistic layer to read and write the JSON store at `.forge/store/`.
+Wraps `store.cjs` facade, enforces schema validation on every write, and
+enforces status transition rules on `update-status`. Deterministic — no AI
+needed.
+
+## Inputs
+
+- `.forge/config.json` — paths (specifically `paths.forgeRoot` for schema resolution)
+- `.forge/schemas/*.schema.json` — canonical JSON Schema files (primary source)
+- `forge/schemas/*.schema.json` — in-tree source schemas (fallback for dogfooding)
+- CLI arguments — command, entity type, JSON payload, flags
+
+## Outputs
+
+- Entity records written to `.forge/store/` (via `store.cjs` facade)
+- Event records written to `.forge/store/events/{sprintId}/`
+- Sidecar files written to `.forge/store/events/{sprintId}/_{eventId}_usage.json`
+- `COLLATION_STATE.json` written to `.forge/store/`
+- JSON results to stdout on success
+- Per-field error messages to stderr on failure
+- Exit 0 on success, 1 on failure
+
+## CLI Interface
+
+```
+<tool> store-cli write <entity> '<json>'                     Write a full entity record
+<tool> store-cli read <entity> <id> [--json]                 Read an entity record
+<tool> store-cli list <entity> [key=value ...]               List entities with optional filter
+<tool> store-cli delete <entity> <id>                        Delete an entity record
+<tool> store-cli update-status <entity> <id> <field> <value> [--force]
+                                                             Update status/enum field with transition check
+<tool> store-cli emit <sprintId> '<json>' [--sidecar]       Write an event (or sidecar)
+<tool> store-cli merge-sidecar <sprintId> <eventId>          Merge sidecar into canonical event
+<tool> store-cli purge-events <sprintId>                     Delete all events for a sprint
+<tool> store-cli write-collation-state '<json>'              Write COLLATION_STATE.json
+<tool> store-cli validate <entity> '<json>'                  Validate against schema without writing
+<tool> store-cli nlp '<intent>'                              Query store by natural language intent (NLP)
+<tool> store-cli query [--sprint|--task|--bug|--feature <id>] [--status <s>]
+                       [--keyword <term>] [--type <entity>] [flags]
+                                                             Query store by exact flags or intent
+<tool> store-cli query --mode strict|nlp|off [flags]        Explicit mode control (strict=exact flags only)
+<tool> store-cli schema                                      Dump entity schemas, status enums, NLP grammar
+```
+
+Entity types: `sprint`, `task`, `bug`, `event`, `feature`
+
+Flags:
+- `--dry-run` — validate and preview without writing (applies to all write commands)
+- `--force` — bypass transition check on `update-status` (emits warning)
+- `--json` — output raw JSON on `read` (no pretty-print)
+- `--sidecar` — write as sidecar file on `emit` (ephemeral, `_`-prefixed)
+- `--sprint <id>` — filter query by sprint ID (e.g. `S12`)
+- `--task <id>` — query a specific task by ID
+- `--bug <id>` — query a specific bug by ID
+- `--feature <id>` — query a specific feature by ID
+- `--status <value>` — filter query by status value
+- `--keyword <term>` — keyword search on entity titles
+- `--type <entity>` — restrict `--keyword` to `sprints|tasks|bugs|features`
+- `--with-blockers` — follow `blockedBy` FK on tasks
+- `--with-blocked-tasks` — follow `blocksTask` FK on bugs
+- `--with-sprint` — follow `sprintId` FK on results
+- `--with-feature` — follow `featureId` FK on results
+- `--no-excerpts` — omit INDEX.md excerpts from results
+- `--mode strict|nlp|off` — engine mode (`strict`/`off` = exact flags only; `nlp` = intent parse)
+
+Exit codes: 0 on success, 1 on failure.
+
+## Entity Types
+
+| Entity | ID Field | Required Fields (minimal) | Store Path |
+|--------|----------|---------------------------|------------|
+| sprint | `sprintId` | `sprintId`, `title`, `status`, `taskIds`, `createdAt` | `.forge/store/sprints/{sprintId}.json` |
+| task | `taskId` | `taskId`, `sprintId`, `title`, `status`, `path` | `.forge/store/tasks/{taskId}.json` |
+| bug | `bugId` | `bugId`, `title`, `severity`, `status`, `path`, `reportedAt` | `.forge/store/bugs/{bugId}.json` |
+| event | `eventId` | `eventId`, `taskId`, `sprintId`, `role`, `action`, `phase`, `iteration`, `startTimestamp`, `endTimestamp`, `durationMinutes`, `model` | `.forge/store/events/{sprintId}/{eventId}.json` |
+| feature | `id` | `id`, `title`, `status`, `created_at` | `.forge/store/features/{id}.json` |
+
+Note: `feature` uses `id` (not `feature_id`) as its primary key. The
+`feature_id` field on sprint/task is a foreign key pointing to `feature.id`.
+
+Nullable fields (accepted as `null` without error): `sprintId`, `taskId`,
+`endTimestamp`, `durationMinutes`, `feature_id`, `description`, `completedAt`,
+`resolvedAt`.
+
+## Schema Validation
+
+The CLI validates every write payload against the canonical JSON Schema before
+writing. Schemas are loaded from:
+
+1. `.forge/schemas/{type}.schema.json` (project-installed, primary)
+2. `forge/schemas/{type}.schema.json` (in-tree source, for dogfooding)
+3. Minimal built-in fallback (required fields only, with stderr warning)
+
+Validation rules:
+- All `required` fields must be present and non-null (except nullable fields)
+- Field types must match schema declarations (including multi-type)
+- Enum values must be in the declared set
+- `additionalProperties: false` — reject records with undeclared fields
+- `minimum` constraints enforced for numeric fields
+
+On validation failure: exit 1, one error per line on stderr (prefixed with
+field name), no partial write.
+
+## Status Transitions
+
+The `update-status` command enforces legal state transitions. Illegal
+transitions are rejected (exit 1 with `"Illegal transition: ..."` on stderr).
+Use `--force` to bypass (emits warning).
+
+### Task
+
+```
+draft -> planned -> plan-approved -> implementing -> implemented
+      -> review-approved -> approved -> committed
+
+Failed states (enterable from any non-terminal state):
+  plan-revision-required, code-revision-required, blocked, escalated, abandoned
+
+Terminal states (no transitions out):
+  committed, abandoned
+```
+
+### Sprint
+
+```
+planning -> active -> completed -> retrospective-done
+
+Failed states:
+  blocked, partially-completed, abandoned
+
+Terminal states:
+  retrospective-done, abandoned
+```
+
+### Bug
+
+```
+reported -> triaged -> in-progress -> fixed
+
+Terminal state:
+  fixed
+```
+
+The architect-approve verdict for bugs travels through
+`bug.summaries.approve.verdict` (read by `read-verdict.cjs §
+BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Earlier revisions of this
+spec listed `approved` and `verified` between `fixed` and the terminal;
+they were removed because no workflow phase wrote them and their presence
+in the enum invited LLM-translated task workflows to attempt
+`update-status bug ... approved` — the trap that produced FORGE-BUG-002.
+
+### Feature
+
+```
+draft -> active -> shipped / retired
+
+Terminal states:
+  shipped, retired
+```
+
+## Sidecar Pattern
+
+Events support a sidecar mechanism for passing out-of-band data from subagents
+back to the orchestrator.
+
+### `emit --sidecar`
+
+Writes a `_{eventId}_usage.json` ephemeral file alongside the canonical event.
+Sidecar files require only an `eventId` field at minimum. Accepted fields:
+
+| Field | Notes |
+|-------|-------|
+| `eventId` | Required — matches the canonical event |
+| `inputTokens` | Token count |
+| `outputTokens` | Token count |
+| `cacheReadTokens` | Cache hit tokens |
+| `cacheWriteTokens` | Cache miss tokens (alias: `cacheCreationTokens`) |
+| `estimatedCostUSD` | Cost estimate (alias: `cost`) |
+| `model` | Full model identifier |
+| `durationMinutes` | Decimal minutes |
+| `startTimestamp` | ISO 8601 |
+| `endTimestamp` | ISO 8601 |
+| `tokenSource` | `reported` or `estimated` |
+
+Alias mapping at merge time: `cacheCreationTokens` -> `cacheWriteTokens`,
+`cost` -> `estimatedCostUSD`.
+
+### `merge-sidecar`
+
+Reads the sidecar, merges token fields into the canonical event via
+`store.writeEvent()`, and deletes the sidecar file. Fails if either file is
+missing.
+
+## Error Handling
+
+- Wrap the entire entry point in a top-level exception handler.
+- On unexpected errors (missing store files, bad JSON, unhandled exceptions),
+  print a clear one-line message to stderr and exit 1.
+- Never let the tool crash with an unhandled exception or stack trace visible
+  to the caller — all errors are caught and reported cleanly.
+- JS/TS pattern:
+  ```js
+  process.on('uncaughtException', (e) => {
+      process.stderr.write(`Error: ${e.message}\n`);
+      process.exit(1);
+  });
+  ```
+
+## Algorithm
+
+### `write`
+1. Parse entity type and JSON payload from CLI args.
+2. Validate entity type is one of: sprint, task, bug, event, feature.
+3. Parse JSON payload (exit 1 on parse error).
+4. Validate payload against schema for the entity type.
+5. If `--dry-run`, report what would be written and exit 0.
+6. Write entity via `store.write{Entity}()` facade.
+
+### `read`
+1. Parse entity type and ID from CLI args.
+2. For events, scan sprint directories to locate the event file.
+3. Output the record (pretty-print or `--json` raw).
+4. Exit 1 if entity not found.
+
+### `list`
+1. Parse entity type and optional key=value filter pairs.
+2. List entities via `store.list{Entities}()` with filter.
+3. Output JSON array.
+
+### `update-status`
+1. Read the current record via `store.get{Entity}()`.
+2. Check that `current[field] -> new` is a legal transition.
+3. If `--force`, bypass with warning on stderr.
+4. Apply the update and write back via `store.write{Entity}()`.
+5. Output JSON result with `from`/`to` fields.
+
+### `emit`
+1. Parse sprintId and JSON payload.
+2. If `--sidecar`: write `_{eventId}_usage.json` file directly.
+3. If canonical: validate against event schema, write via `store.writeEvent()`.
+4. Output JSON result.
+
+### `merge-sidecar`
+1. Read sidecar file. Read canonical event file.
+2. Merge token fields from sidecar into event (with alias resolution).
+3. Write updated event via `store.writeEvent()`.
+4. Delete sidecar file.
+
+### `validate`
+1. Parse entity type and JSON payload.
+2. Validate against schema (same logic as `write`).
+3. Exit 1 on errors (no write), exit 0 with `{"ok":true,"valid":true}`.
+
+### `nlp '<intent>'`
+1. Spawn `store-query.cjs nlp` with the intent string.
+2. Output JSON to stdout: `{query, path, traversalTrace, results, relatedFileRefs, meta}`.
+3. `results[]` contains: `{id, title, status, type, relationships, fileRefs, excerpt}`.
+
+### `query [flags|intent]`
+1. If exact entity flags present (`--sprint/--task/--bug/--feature`), run exact-args path.
+2. If `--keyword` present, run keyword search path.
+3. If intent string present (no flags), run NLP path.
+4. `--mode strict|off` rejects intent strings; `--mode nlp` forces NLP path.
+5. Returns same JSON structure as `nlp`.
+
+### `schema`
+1. Load project config (prefix, paths).
+2. Return entity schemas, status/severity enums, FK relationships, and NLP grammar vocabulary.
+3. Output: `{project, entities, entitySynonyms, statusSynonyms, grammar}`.
+
+## Query Output Schema
+
+```json
+{
+  "query": "<input string>",
+  "path": "exact | keyword | intent-nlp",
+  "traversalTrace": ["<step descriptions>"],
+  "results": [
+    {
+      "id": "<entity ID>",
+      "title": "<entity title>",
+      "status": "<current status>",
+      "type": "task | bug | sprint | feature",
+      "relationships": {
+        "sprintId": "<sprint ID>",
+        "featureId": "<feature ID>",
+        "blockedBy": ["<bug IDs>"],
+        "blocksTask": ["<task IDs>"]
+      },
+      "fileRefs": {
+        "json": "<store JSON path>",
+        "md": "<INDEX.md path>"
+      },
+      "storeRef": "<store JSON path>",
+      "indexRef": "<INDEX.md path>",
+      "excerpt": "<first 4 sentences from INDEX.md, or null>"
+    }
+  ],
+  "relatedFileRefs": ["<all md and json paths>"],
+  "totalMatched": 7,
+  "returned": 3,
+  "limit": 3,
+  "sort": "desc",
+  "meta": {
+    "mode": "auto | strict | nlp | off",
+    "engineVersion": "1.0.0",
+    "totalTimeMs": 42
+  }
+}
+```
+
+Count mode response (when intent contains `how many`, `count of`, etc.):
+
+```json
+{
+  "query": "how many open bugs",
+  "path": "intent-nlp",
+  "traversalTrace": ["..."],
+  "count": 7,
+  "results": [],
+  "totalMatched": 7
+}
+```