@entelligentsia/forgecli 0.3.0 → 0.7.6

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

@@ -0,0 +1,174 @@
+---
+name: remove
+description: Use when you want to remove Forge from the current project, with options for what to keep
+---
+
+# /forge:remove
+
+Remove Forge artifacts from the current project. This command is interactive —
+nothing is deleted until you confirm explicitly.
+
+## What Forge puts in a project
+
+| 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` |
+| `{KB_PATH}/` | Knowledge base, sprint history, bug history, tools | **Caution** — represents accumulated project learning |
+
+## Step 1 — Inventory what exists
+
+Read the configured KB path and project prefix from config:
+
+```sh
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+KB_PATH: !`node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}"`
+PREFIX: !`node -e "try{console.log(require('./.forge/config.json').project.prefix.toLowerCase())}catch{console.log('')}"`
+```
+
+If `PREFIX` is empty or `.forge/config.json` is unreadable, fall back to scanning both
+`.claude/commands/` and all immediate subdirectories for the 13 known filenames and remove
+whatever is found. Log a warning: `△ Could not read project prefix from config — scanning for commands in all locations.`
+
+Check which Forge directories are present:
+
+```
+exists: !`[ -d ".forge" ] && echo "YES" || echo "NO"`
+exists: !`[ -d "{KB_PATH}" ] && echo "YES" || echo "NO"`
+exists: !`[ -d ".claude/commands" ] && echo "YES" || echo "NO"`
+```
+
+Report to the user exactly what was found before proceeding (use the actual KB path value, e.g. `engineering/` or `ai-docs/`).
+
+## Step 2 — Present options
+
+Show the user these options:
+
+```
+Forge removal options:
+
+  [1] Minimal — remove .forge/ only
+      Removes config, workflows, templates, and the task/sprint/bug store.
+      Leaves {KB_PATH}/ and .claude/commands/ intact.
+      Use this to reset Forge config while keeping your knowledge base.
+
+  [2] Standard — remove .forge/ and generated commands
+      Removes .forge/ and the Forge-generated commands in .claude/commands/.
+      Leaves {KB_PATH}/ intact.
+      Recommended for most removals — your knowledge base survives.
+
+  [3] Full — remove everything
+      Removes .forge/, generated commands, AND {KB_PATH}/.
+      Your knowledge base, sprint history, and bug history will be lost.
+      This cannot be undone.
+
+Which option? (1 / 2 / 3)
+```
+
+Wait for the user's choice before proceeding.
+
+## Step 3 — Confirm KB folder removal (option 3 only)
+
+If the user chose option 3, ask explicitly (using the actual KB_PATH value):
+
+```
+{KB_PATH}/ contains your accumulated knowledge base — architecture docs,
+entity model, stack checklist, sprint history, and bug history. This represents
+real learning that took sprints to build.
+
+Are you sure you want to delete it?
+Type "delete {KB_PATH}" to confirm, or anything else to keep it and use option 2 instead.
+```
+
+If they do not type exactly `delete {KB_PATH}` (with the actual path, e.g. `delete engineering`
+or `delete ai-docs`), downgrade to option 2 and inform them.
+
+## Step 4 — Final confirmation
+
+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}/run-task.md
+  ✗ .claude/commands/{PREFIX}/run-sprint.md
+  ✗ .claude/commands/{PREFIX}/plan.md
+  ✗ .claude/commands/{PREFIX}/review-plan.md
+  ✗ .claude/commands/{PREFIX}/implement.md
+  ✗ .claude/commands/{PREFIX}/review-code.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
+  [✗ {KB_PATH}/]   ← only if option 3 confirmed
+
+Type "confirm" to proceed, or anything else to cancel.
+```
+
+Only proceed if the user types exactly `confirm`.
+
+## Step 5 — Execute
+
+Remove only the confirmed items. Use targeted commands — never `rm -rf .`:
+
+**Option 1 (minimal):**
+```bash
+rm -rf .forge/
+```
+
+**Option 2 (standard):**
+```bash
+rm -rf .forge/
+rm -f ".claude/commands/${PREFIX}/sprint-intake.md" \
+      ".claude/commands/${PREFIX}/sprint-plan.md" \
+      ".claude/commands/${PREFIX}/run-task.md" \
+      ".claude/commands/${PREFIX}/run-sprint.md" \
+      ".claude/commands/${PREFIX}/plan.md" \
+      ".claude/commands/${PREFIX}/review-plan.md" \
+      ".claude/commands/${PREFIX}/implement.md" \
+      ".claude/commands/${PREFIX}/review-code.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"
+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" \
+      ".claude/commands/${PREFIX}/run-task.md" \
+      ".claude/commands/${PREFIX}/run-sprint.md" \
+      ".claude/commands/${PREFIX}/plan.md" \
+      ".claude/commands/${PREFIX}/review-plan.md" \
+      ".claude/commands/${PREFIX}/implement.md" \
+      ".claude/commands/${PREFIX}/review-code.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"
+rmdir ".claude/commands/${PREFIX}" 2>/dev/null || true
+```
+
+After removal, verify the directories are gone and report what was removed.
+
+## Step 6 — Close
+
+Confirm completion and remind the user:
+
+- To reinstall Forge in this project: `/forge:init`
+- The plugin itself is unaffected — only project artifacts were removed
+- To uninstall the plugin entirely: `/plugin uninstall forge`
+
+## 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/report-bug.md

@@ -0,0 +1,191 @@
+---
+name: report-bug
+description: Use when you encounter a bug in Forge itself and want to file it as a GitHub issue in the Entelligentsia/forge repository
+---
+
+# /forge:report-bug
+
+File a bug report against Forge itself (not your project). This command
+gathers context automatically, lets you describe what went wrong, shows
+a draft, and files the issue to `Entelligentsia/forge` via `gh`.
+
+## Step 1 — Check prerequisites
+
+Verify `gh` is available and authenticated:
+
+```
+gh_check: !`gh auth status 2>&1 | head -3`
+```
+
+If `gh` is not installed or not authenticated, stop and tell the user:
+
+```
+gh is not installed or not authenticated.
+  Install:      https://cli.github.com
+  Authenticate: gh auth login
+```
+
+## Step 2 — Gather automatic context
+
+Collect the following in parallel:
+
+```
+forge_version:  !`cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/'`
+node_version:   !`node --version 2>/dev/null || echo "N/A"`
+os_info:        !`uname -srm 2>/dev/null || echo "N/A"`
+forge_config:   !`cat ".forge/config.json" 2>/dev/null | head -30 || echo "No .forge/config.json found"`
+```
+
+Extract from `forge_config` (if present): `language`, `framework`, and a
+1-line project description. If the config is absent, note that Forge was not
+yet initialised in this project.
+
+## Step 2b — Token data opt-in
+
+1. **Detect a relevant sprint.** Read `.forge/config.json` to confirm the store
+   path (default `.forge/store`). Then read the sprint store JSONs from
+   `.forge/store/sprints/` to find the sprint with `status: "active"` or
+   `status: "in-progress"`. If multiple match, use the one with the most recent
+   `updatedAt` date. Check whether a `COST_REPORT.md` file exists under
+   `engineering/sprints/<sprint-dir>/COST_REPORT.md` for that sprint. If no
+   sprint qualifies or no `COST_REPORT.md` is found, skip all remaining steps
+   in Step 2b (silent — do not print anything to the user).
+
+2. **Check config override.** Read `forge_config` (already loaded in Step 2).
+   If `pipeline.includeTokenDataInBugReports` is a boolean:
+   - `true`  → set `include_token_data = true`, skip the prompt
+   - `false` → set `include_token_data = false`, skip the prompt
+
+3. **Prompt the user** (only when a `COST_REPORT.md` was found and no config
+   override is set):
+   ```
+   Include token usage data from the relevant sprint in this report?
+   (Helps the Forge team diagnose efficiency issues) [Y/n]
+   ```
+   Treat empty input / Enter as **Y**. Set `include_token_data` accordingly.
+
+4. **Capture the cost data.** If `include_token_data = true`, read the content
+   of the detected `COST_REPORT.md` file. Store it as `cost_report_content`.
+
+## Step 3 — Interview the user
+
+**If this command was invoked immediately after a Forge error** (i.e., the recent conversation contains an error from a Forge command), extract the answers from that context automatically:
+- Which command failed → from the conversation
+- What happened → from the error output
+- Expected behaviour → infer from the command's purpose
+- Reproduction steps → from the conversation
+- Severity → infer from impact (blocked = HIGH, partial failure = MEDIUM, cosmetic = LOW)
+
+Skip to Step 4 directly with the pre-filled answers.
+
+**Otherwise**, ask the following questions in one message (the user may answer all at once):
+
+```
+To file a Forge bug report, please answer:
+
+1. Which command or phase triggered this?
+   (e.g. /forge:init Phase 3, /forge:health, generate-tools.md, etc.)
+
+2. What happened? (actual behaviour)
+
+3. What did you expect to happen?
+
+4. Steps to reproduce — paste any relevant error messages or output.
+
+5. Severity: HIGH / MEDIUM / LOW
+   HIGH   = blocks init or a core workflow entirely
+   MEDIUM = incorrect output, missing functionality, confusing behaviour
+   LOW    = cosmetic, wording, minor inconvenience
+```
+
+Wait for the user's response before continuing.
+
+## Step 4 — Draft the issue
+
+Compose the issue title and body using the information collected.
+
+**Title format:** `<command/file>: <one-line summary> [<SEVERITY>]`
+Example: `generate-tools.md: Node.js tool generation fails on ESM projects [HIGH]`
+
+**Body template:**
+
+```markdown
+## Summary
+
+<one sentence description from the user>
+
+---
+
+## Bug — <title>
+
+**Forge command / file:** <which command or phase>
+
+<user's description of what happened>
+
+<paste any error output from the user, in a code block>
+
+**Expected behaviour:** <what the user expected>
+
+**Steps to reproduce:**
+<user's reproduction steps, formatted as a numbered list>
+
+**Suggested fix:** <leave blank or add if the user mentioned one>
+
+---
+
+## Environment
+
+- Plugin version: <forge_version>
+- Claude Code model: <current model — claude-sonnet-4-6 or as known>
+- Project stack: <language + framework from .forge/config.json, or "Forge not initialised">
+- Node.js: <node_version>
+- OS: <os_info>
+```
+
+If `include_token_data = true`, append the following block immediately after
+the `## Environment` section (leave it out entirely when `include_token_data`
+is false or was never set):
+
+```markdown
+<details>
+<summary>Token Usage Data</summary>
+
+{cost_report_content}
+
+</details>
+```
+
+## Step 5 — Show draft and confirm
+
+Print the full draft (title + body) to the user and ask:
+
+```
+Draft issue ready. File to Entelligentsia/forge? [Y/n]
+Or type "edit" to revise before filing.
+```
+
+If the user says **edit**: ask what to change, update the draft, and show it again.
+
+If the user says **no** or anything other than Y/y/edit: cancel and inform the user they can copy the draft above and file manually at https://github.com/Entelligentsia/forge/issues/new
+
+## Step 6 — File the issue
+
+Run:
+
+```sh
+gh issue create --repo Entelligentsia/forge --title "TITLE" --body "BODY"
+```
+
+Substitute `TITLE` and `BODY` with the collected values. Pass title and body via variables or a heredoc to avoid shell escaping issues.
+The `gh` output will include the new issue URL.
+
+Report the URL to the user:
+
+```
+Bug filed: https://github.com/Entelligentsia/forge/issues/<N>
+Thank you — this helps improve Forge for everyone.
+```
+
+## Arguments
+
+$ARGUMENTS

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

@@ -0,0 +1,73 @@
+---
+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
+---
+
+# /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)

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

@@ -0,0 +1,187 @@
+---
+name: store-repair
+description: Diagnose and repair corrupted store records. Use when validate-store reports errors or store data seems wrong.
+---
+
+# /forge:store: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/update-tools.md

@@ -0,0 +1,56 @@
+---
+name: update-tools
+description: Use when you want to refresh .forge/schemas/ to match the currently installed Forge plugin version
+---
+
+# /forge:update-tools
+
+Refresh the JSON schemas in `.forge/schemas/` from the installed Forge plugin.
+
+Forge tools (`collate.cjs`, `manage-config.cjs`, etc.) ship with the plugin and
+are invoked directly from `$FORGE_ROOT/tools/` — they are not copied to the project.
+This command only manages schemas.
+
+## Locate the plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Steps
+
+### 1 — Copy schemas
+
+Copy all JSON Schema files from `$FORGE_ROOT/schemas/` to `.forge/schemas/`.
+Create `.forge/schemas/` if it does not exist.
+
+```sh
+mkdir -p .forge/schemas
+cp "$FORGE_ROOT/schemas/"*.schema.json .forge/schemas/
+```
+
+### 2 — Record hashes
+
+Record each copied schema file in the generation manifest so health checks
+can detect modifications:
+
+```sh
+for f in .forge/schemas/*.schema.json; do
+  node "$FORGE_ROOT/tools/generation-manifest.cjs" record "$f"
+done
+```
+
+### 3 — Verify
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+```
+
+Print `〇 Schemas updated and store validation passed.` on success.
+Print `× Validation failed — {output}` on non-zero exit.
+
+## 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."