@entelligentsia/forgecli 0.7.10 → 0.9.0

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.