@entelligentsia/forgecli 0.21.0 → 1.0.2

package/dist/forge-payload/commands/remove.md

@@ -13,7 +13,7 @@ nothing is deleted until you confirm explicitly.
 | Location | Contents | Safe to remove? |
 |---|---|---|
 | `.forge/` | Config, workflows, templates, task/sprint/bug store | Yes — regeneratable via `/forge:init` |
-| `.claude/commands/` | Generated slash commands (sprint-plan, run-task, etc.) | Yes — regeneratable via `/forge:init` |
+| `.claude/commands/` | Generated slash commands (plan-sprint, run-task, etc.) | Yes — regeneratable via `/forge:init` |
 | `{KB_PATH}/` | Knowledge base, sprint history, bug history, tools | **Caution** — represents accumulated project learning |
 
 ## Step 1 — Inventory what exists
@@ -90,8 +90,8 @@ Summarise exactly what will be deleted, then ask:
 ```
 About to delete:
   ✗ .forge/
-  ✗ .claude/commands/{PREFIX}/sprint-intake.md
-  ✗ .claude/commands/{PREFIX}/sprint-plan.md
+  ✗ .claude/commands/{PREFIX}/new-sprint.md
+  ✗ .claude/commands/{PREFIX}/plan-sprint.md
   ✗ .claude/commands/{PREFIX}/run-task.md
   ✗ .claude/commands/{PREFIX}/run-sprint.md
   ✗ .claude/commands/{PREFIX}/plan.md
@@ -101,8 +101,7 @@ About to delete:
   ✗ .claude/commands/{PREFIX}/fix-bug.md
   ✗ .claude/commands/{PREFIX}/approve.md
   ✗ .claude/commands/{PREFIX}/commit.md
-  ✗ .claude/commands/{PREFIX}/collate.md
-  ✗ .claude/commands/{PREFIX}/retrospective.md
+  ✗ .claude/commands/{PREFIX}/retro.md
   [✗ {KB_PATH}/]   ← only if option 3 confirmed
 
 Type "confirm" to proceed, or anything else to cancel.
@@ -122,8 +121,8 @@ rm -rf .forge/
 **Option 2 (standard):**
 ```bash
 rm -rf .forge/
-rm -f ".claude/commands/${PREFIX}/sprint-intake.md" \
-      ".claude/commands/${PREFIX}/sprint-plan.md" \
+rm -f ".claude/commands/${PREFIX}/new-sprint.md" \
+      ".claude/commands/${PREFIX}/plan-sprint.md" \
       ".claude/commands/${PREFIX}/run-task.md" \
       ".claude/commands/${PREFIX}/run-sprint.md" \
       ".claude/commands/${PREFIX}/plan.md" \
@@ -133,16 +132,15 @@ rm -f ".claude/commands/${PREFIX}/sprint-intake.md" \
       ".claude/commands/${PREFIX}/fix-bug.md" \
       ".claude/commands/${PREFIX}/approve.md" \
       ".claude/commands/${PREFIX}/commit.md" \
-      ".claude/commands/${PREFIX}/collate.md" \
-      ".claude/commands/${PREFIX}/retrospective.md"
+      ".claude/commands/${PREFIX}/retro.md"
 rmdir ".claude/commands/${PREFIX}" 2>/dev/null || true
 ```
 
 **Option 3 (full):**
 ```bash
 rm -rf .forge/ "{KB_PATH}/"
-rm -f ".claude/commands/${PREFIX}/sprint-intake.md" \
-      ".claude/commands/${PREFIX}/sprint-plan.md" \
+rm -f ".claude/commands/${PREFIX}/new-sprint.md" \
+      ".claude/commands/${PREFIX}/plan-sprint.md" \
       ".claude/commands/${PREFIX}/run-task.md" \
       ".claude/commands/${PREFIX}/run-sprint.md" \
       ".claude/commands/${PREFIX}/plan.md" \
@@ -152,8 +150,7 @@ rm -f ".claude/commands/${PREFIX}/sprint-intake.md" \
       ".claude/commands/${PREFIX}/fix-bug.md" \
       ".claude/commands/${PREFIX}/approve.md" \
       ".claude/commands/${PREFIX}/commit.md" \
-      ".claude/commands/${PREFIX}/collate.md" \
-      ".claude/commands/${PREFIX}/retrospective.md"
+      ".claude/commands/${PREFIX}/retro.md"
 rmdir ".claude/commands/${PREFIX}" 2>/dev/null || true
 ```
 

package/dist/forge-payload/commands/repair.md

@@ -0,0 +1,187 @@
+---
+name: repair
+description: Diagnose and repair corrupted store records. Use when validate-store reports errors or store data seems wrong.
+---
+
+# /forge:repair
+
+Diagnose and repair corruption in the Forge JSON store.
+
+## Arguments
+
+$ARGUMENTS
+
+| Argument | Purpose |
+|----------|---------|
+| `--dry-run` | Show what would be repaired without making any changes |
+
+## How to Run
+
+1. Resolve the plugin root:
+   ```
+   FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+   ```
+
+2. Run the four-phase repair workflow below. If `--dry-run` is in `$ARGUMENTS`,
+   preview all changes without writing — skip Phase 2 writes and Phase 3
+   writes, and skip Phase 4 verification since nothing changed.
+
+## Phase 1: Diagnosis
+
+Run the deterministic validator in JSON mode:
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run --json
+```
+
+Parse the JSON output. Categorize each error by its `category` field:
+
+| Category | Example | Deterministic fix? |
+|----------|---------|--------------------|
+| `missing-required` | `"sprintId": null` on a sprint | Yes — backfill |
+| `type-mismatch` | `"iteration": "1"` instead of `1` | Yes — coerce |
+| `invalid-enum` | `"status": "in-progress"` on a bug | No — needs judgment |
+| `undeclared-field` | `"priority": "high"` on a task | No — needs judgment |
+| `orphaned-fk` | `taskId` pointing to deleted task in event | No — needs judgment |
+| `filename-mismatch` | Event filename != eventId | Yes — rename |
+| `minimum-violation` | `"iteration": 0` | Yes — coerce |
+| `orphan-directory` | Sprint dir with no sprint record | No — needs judgment |
+| `stale-path` | `path` pointing to nonexistent dir | No — needs judgment |
+
+## Phase 2: Auto-Fix
+
+Run the deterministic validator with `--fix`:
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --fix --json
+```
+
+For dry-run, preview without writing:
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --fix --dry-run --json
+```
+
+Report each fix to the user (entity, field, what was backfilled or nullified).
+
+## Phase 3: LLM-Judgment Fixes
+
+For each remaining error from Phase 1 that was not auto-fixed, apply LLM judgment:
+
+1. **Read the corrupted record**:
+   ```sh
+   node "$FORGE_ROOT/tools/store-cli.cjs" read <entity> <id> --json
+   ```
+
+2. **Determine the correct value** based on schema definitions, store context, and
+   the judgment rules below.
+
+3. **Present the proposed fix** to the user with:
+   - Entity ID and field affected
+   - Current (corrupted) value
+   - Proposed (corrected) value
+   - Reasoning
+
+   If the user declines, skip the fix and note it in the report.
+
+4. **Apply the fix** using the appropriate command:
+
+   | Corruption Pattern | Repair Action | Command |
+   |-------------------|---------------|---------|
+   | Invalid enum value | Map to nearest valid enum | `store-cli.cjs update-status <entity> <id> <field> <value> [--force]` |
+   | Undeclared field | Remove the field by rewriting | `store-cli.cjs write <entity> '<fixed-json>'` |
+   | Type mismatch | Coerce to correct type and rewrite | `store-cli.cjs write <entity> '<fixed-json>'` |
+   | Orphaned FK | Nullify or remap to existing entity | `store-cli.cjs write <entity> '<fixed-json>'` |
+   | Dangling sprint.taskIds | Remove taskIds referencing non-existent tasks | `store-cli.cjs write sprint '<fixed-json>'` |
+   | Illegal status transition | Force-correct to valid state | `store-cli.cjs update-status <entity> <id> status <value> --force` |
+   | Stale COLLATION_STATE | Regenerate via collate | `node "$FORGE_ROOT/tools/collate.cjs"` |
+
+### Judgment Rules: Invalid Enum Values
+
+Map common misspellings and variant forms to canonical values:
+
+| Entity | Field | Common Misspellings | Canonical Values |
+|--------|-------|--------------------|------------------|
+| Sprint | status | "in-progress" | active |
+| Sprint | status | "done", "finished" | completed |
+| Task | status | "in-progress" | implementing |
+| Task | status | "in-review", "review" | review-approved |
+| Task | status | "done", "finished" | committed |
+| Bug | severity | "high", "critical" | critical |
+| Bug | severity | "medium" | major |
+| Bug | severity | "low" | minor |
+| Bug | status | "open" | reported |
+| Bug | status | "working" | in-progress |
+| Feature | status | "complete", "done" | shipped |
+
+When no reasonable mapping exists, ask the user to choose from valid values.
+
+### Judgment Rules: Orphaned References
+
+- **Event.taskId → deleted task**: If the event's sprintId is valid, nullify the
+  taskId. If the sprint also doesn't exist, ask the user whether to delete the
+  event or create a stub sprint.
+- **Sprint.taskIds containing deleted task IDs**: Remove the deleted IDs from the
+  array and rewrite the sprint.
+- **Undeclared fields**: Remove the field and rewrite. Mention the removed data in
+  the report so the user can decide whether to add it to the schema.
+
+### Hard Rules
+
+1. **Never fall back to direct file writes.** All repairs go through
+   `store-cli.cjs`. If it rejects a write, fix the data and retry (max 2).
+2. **Never delete data without confirmation.** Ask the user before deleting any
+   record.
+3. **Never skip Phase 4 verification.** Always re-run validate-store after
+   repairs.
+4. **Preserve data priority.** Prefer corrections that retain more original data.
+   Mapping "in-progress" → "implementing" is better than resetting to "draft".
+
+## Phase 4: Verification
+
+Re-run the validator to confirm the store is clean:
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run --json
+```
+
+If `"ok": true`, report success. If errors remain, report them as unresolved
+with suggestions for next steps.
+
+## Repair Report
+
+After all phases, output a structured report:
+
+```
+# Store Repair Report
+
+## Phase 1: Diagnosis
+- Errors found: N
+- Warnings found: M
+- Categories: {breakdown by category}
+
+## Phase 2: Auto-Fix
+- Fixes applied: N
+- Details: {list of each fix}
+
+## Phase 3: LLM-Judgment Fixes
+- Fixes proposed: N
+- Fixes applied: M (with user approval)
+- Fixes skipped: K (user declined)
+- Details: {list of each proposed change with reasoning}
+
+## Phase 4: Verification
+- Errors remaining: N
+- Warnings remaining: M
+- Status: PASS / FAIL
+
+## Unresolved Issues
+{List of issues that could not be automatically resolved, with suggestions}
+```
+
+## On Error
+
+If `validate-store.cjs` crashes or returns unexpected output, report the error
+and suggest running `/forge:report-bug` if it appears to be a Forge bug. Do NOT
+attempt to continue repairs after an unexpected error in a deterministic tool —
+the store state is unknown and further writes could cause additional corruption.

package/dist/forge-payload/commands/search.md

@@ -0,0 +1,73 @@
+---
+name: search
+description: Query the Forge store by natural language or exact flags. Use for finding tasks, bugs, sprints, or features without manually reading the knowledge base.
+allowed-tools:
+  - Bash
+---
+
+# /forge:search
+
+Query the Forge JSON store by intent, sprint, entity ID, or keyword.
+
+## Locate plugin root
+
+```
+FORGE_ROOT: !`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`
+```
+
+## Dispatch
+
+If `$ARGUMENTS` starts with `--` (flags), run exact query:
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" query $ARGUMENTS
+```
+
+Otherwise run NLP intent query:
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" nlp "$ARGUMENTS"
+```
+
+If `$ARGUMENTS` is empty, print usage:
+
+```
+Usage: /forge:search <intent or flags>
+
+Examples:
+  /forge:search open bugs in S12
+  /forge:search WI-BUG-047
+  /forge:search --sprint S12 --status in-progress
+  /forge:search --keyword auth
+  /forge:search schema
+```
+
+## Output
+
+Results are printed as JSON. Key fields:
+
+| Field | Meaning |
+|-------|---------|
+| `results[].id` | Entity ID |
+| `results[].title` | Entity title |
+| `results[].status` | Current status |
+| `results[].type` | `task`, `bug`, `sprint`, or `feature` |
+| `results[].relationships` | FK IDs (sprintId, featureId, blockedBy, etc.) |
+| `results[].fileRefs.md` | Path to INDEX.md for this entity |
+| `results[].excerpt` | First 4 sentences from INDEX.md |
+| `traversalTrace` | NLP parse steps and confidence |
+| `meta.totalTimeMs` | Query wall-clock time |
+
+## Schema reference
+
+To see the project's entity schemas and NLP grammar vocabulary:
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" schema
+```
+
+## Skills
+
+- `forge:store-query-nlp` — NLP intent reference and output schema
+- `forge:store-query-grammar` — Token vocabulary for constructing queries
+- `forge:store-custodian` — Write/mutate operations (separate from query)

package/dist/forge-payload/commands/status.md

@@ -0,0 +1,105 @@
+---
+name: status
+description: Sprint and task summary — shows current sprint name, task status counts, and recent activity
+allowed-tools:
+  - Bash
+---
+
+# /forge:status
+
+Quick overview of the current sprint and task state.
+
+## Locate plugin root
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Locate project config
+
+Check whether `.forge/config.json` exists in the current working directory.
+If it does not exist, output:
+
+```
+× forge:status — not inside a Forge project. Run /forge:init first.
+```
+
+and stop.
+
+## Gather sprint data
+
+Run:
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" query --list-sprints --no-excerpts
+```
+
+Parse the JSON output. Filter `results` to entries where `status == "active"`.
+Sort by `id` descending (most recent sprint first). If no active sprints are found, output:
+
+```
+forge:status — No active sprint found.
+Run /forge:init to initialise a project, or check your store with /forge:search --list-sprints.
+```
+
+and stop.
+
+Use the first (most recent) active sprint as the current sprint.
+
+## Gather task data
+
+Run:
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" query --sprint <SPRINT_ID> --no-excerpts
+```
+
+From the JSON output, collect all results where `type == "task"`.
+
+## Format and output
+
+Print a markdown status report in this format:
+
+```
+## Sprint: <SPRINT_ID> — <sprint.title> (<sprint.status>)
+
+### Tasks (<total> total)
+  <status1>: <count>  |  <status2>: <count>  |  ...
+
+### Recent Activity
+  - <TASK_ID>: <task.title truncated to 60 chars> → <task.status>
+  ...
+
+### Next: /forge:run-task <NEXT_TASK_ID>
+```
+
+**Task counts:** Group tasks by status. Show only status buckets with count > 0, separated by `  |  `. Omit zero-count buckets.
+
+**Recent Activity:** Show up to 5 tasks sorted by taskId descending (highest T-number first). Each line:
+`  - <task.id>: <title> → <status>`
+
+**Next action:** Find the first task (sorted by taskId ascending) that has status `implementing` or `planned`. Suggest `/forge:run-task <TASK_ID>`. If all tasks are committed or abandoned, output `### Next: Sprint complete — run /forge:retro`.
+
+**Multiple active sprints:** If more than one active sprint exists, add a note after the report:
+```
+  Note: <N> other active sprint(s) found. Showing most recent (<SPRINT_ID>).
+```
+
+## Arguments
+
+$ARGUMENTS
+
+| Argument | Purpose |
+|----------|---------|
+| `--sprint <ID>` | Show status for a specific sprint instead of the most recent active one |
+
+If `--sprint <ID>` is in `$ARGUMENTS`, use that sprint ID directly (skip the list-sprints step and active-filter). If the sprint is not found, output:
+```
+× forge:status — sprint <ID> not found. Run /forge:search --list-sprints to see available sprints.
+```
+
+## On error
+
+If any step above fails unexpectedly, describe what went wrong and ask:
+
+> "This looks like a Forge bug. Would you like to file a report to help improve it? Run `/forge:report-bug` — I'll pre-fill the report from this conversation."

package/dist/forge-payload/commands/store-query.md

@@ -1,73 +1,6 @@
 ---
 name: store-query
-description: Query the Forge store by natural language or exact flags. Use for finding tasks, bugs, sprints, or features without manually reading the knowledge base.
-allowed-tools:
-  - Bash
+description: Renamed in v1.0 — use /forge:search
 ---
 
-# /forge:store-query
-
-Query the Forge JSON store by intent, sprint, entity ID, or keyword.
-
-## Locate plugin root
-
-```
-FORGE_ROOT: !`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`
-```
-
-## Dispatch
-
-If `$ARGUMENTS` starts with `--` (flags), run exact query:
-
-```sh
-node "$FORGE_ROOT/tools/store-cli.cjs" query $ARGUMENTS
-```
-
-Otherwise run NLP intent query:
-
-```sh
-node "$FORGE_ROOT/tools/store-cli.cjs" nlp "$ARGUMENTS"
-```
-
-If `$ARGUMENTS` is empty, print usage:
-
-```
-Usage: /forge:store-query <intent or flags>
-
-Examples:
-  /forge:store-query open bugs in S12
-  /forge:store-query WI-BUG-047
-  /forge:store-query --sprint S12 --status in-progress
-  /forge:store-query --keyword auth
-  /forge:store-query schema
-```
-
-## Output
-
-Results are printed as JSON. Key fields:
-
-| Field | Meaning |
-|-------|---------|
-| `results[].id` | Entity ID |
-| `results[].title` | Entity title |
-| `results[].status` | Current status |
-| `results[].type` | `task`, `bug`, `sprint`, or `feature` |
-| `results[].relationships` | FK IDs (sprintId, featureId, blockedBy, etc.) |
-| `results[].fileRefs.md` | Path to INDEX.md for this entity |
-| `results[].excerpt` | First 4 sentences from INDEX.md |
-| `traversalTrace` | NLP parse steps and confidence |
-| `meta.totalTimeMs` | Query wall-clock time |
-
-## Schema reference
-
-To see the project's entity schemas and NLP grammar vocabulary:
-
-```sh
-node "$FORGE_ROOT/tools/store-cli.cjs" schema
-```
-
-## Skills
-
-- `forge:store-query-nlp` — NLP intent reference and output schema
-- `forge:store-query-grammar` — Token vocabulary for constructing queries
-- `forge:store-custodian` — Write/mutate operations (separate from query)
+× /forge:store-query was renamed to /forge:search in v1.0.