@entelligentsia/forgecli 0.11.3 → 0.19.0

package/dist/forge-payload/.schemas/proposal.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/proposal.schema.json",
+  "title": "EnhancementProposal",
+  "description": "A single Phase 2 enrichment proposal emitted by /forge:enhance. Each record carries an op classification (insert/update/delete a skill artifact), the target file path, and a diff body. Foundation for the T03 judge, T05 delete detection, T06 compression gate, and T07 queue drain.",
+  "type": "object",
+  "required": ["op", "target_path", "diff_body"],
+  "properties": {
+    "proposalId":         { "type": "string", "minLength": 1 },
+    "op": {
+      "type": "string",
+      "enum": ["insert_skill", "update_skill", "delete_skill"],
+      "description": "Three-op classification: insert a new skill artifact, update an existing one, or delete an existing one."
+    },
+    "target_path": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repository-relative path to the artifact being inserted, updated, or deleted (e.g. forge/skills/engineer-skills.md)."
+    },
+    "diff_body": {
+      "type": "string",
+      "description": "Unified-diff body or full file body for inserts. For delete_skill this may be empty — the op + target_path is sufficient."
+    },
+    "rationale":          { "type": "string" },
+    "sourceFrictionIds":  { "type": "array", "items": { "type": "string" } },
+    "generated_at":       { "type": "string", "format": "date-time" },
+    "sprintId":           { "type": "string" },
+    "recurrence_count": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "FORGE-S24-T04 — count of distinct tasks within the same sprint that emitted a matching (subkind, evidence.skillId) friction event, including the originating task. Always >= 1."
+    },
+    "recurrence_task_ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "FORGE-S24-T04 — taskOrder-sorted list of task IDs that contributed to recurrence_count. Empty when the originating friction event cannot be resolved from sourceFrictionIds."
+    }
+  },
+  "additionalProperties": false
+}

package/dist/forge-payload/.schemas/task.schema.json

@@ -30,29 +30,14 @@
       "type": "object",
       "description": "Terse structured summaries of phase artifacts. Optional; full artifacts on disk remain authoritative.",
       "properties": {
-        "plan":           { "$ref": "#/$defs/phaseSummary" },
-        "review_plan":    { "$ref": "#/$defs/phaseSummary" },
-        "implementation": { "$ref": "#/$defs/phaseSummary" },
-        "code_review":    { "$ref": "#/$defs/phaseSummary" },
-        "validation":     { "$ref": "#/$defs/phaseSummary" }
+        "plan":           { "$ref": "_defs/phaseSummary.schema.json" },
+        "review_plan":    { "$ref": "_defs/phaseSummary.schema.json" },
+        "implementation": { "$ref": "_defs/phaseSummary.schema.json" },
+        "code_review":    { "$ref": "_defs/phaseSummary.schema.json" },
+        "validation":     { "$ref": "_defs/phaseSummary.schema.json" }
       },
       "additionalProperties": false
     }
   },
-  "additionalProperties": false,
-  "$defs": {
-    "phaseSummary": {
-      "type": "object",
-      "required": ["objective", "written_at"],
-      "properties": {
-        "objective":   { "type": "string", "maxLength": 280 },
-        "key_changes": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 12 },
-        "findings":    { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 12 },
-        "verdict":     { "type": "string", "enum": ["approved", "revision", "n/a"] },
-        "written_at":  { "type": "string", "format": "date-time" },
-        "artifact_ref":{ "type": "string", "description": "Relative path to the full artifact" }
-      },
-      "additionalProperties": false
-    }
-  }
+  "additionalProperties": false
 }

package/dist/forge-payload/.schemas/transitions/bug.json

@@ -0,0 +1,31 @@
+[
+  {
+    "from": "reported",
+    "to": [
+      "triaged",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "triaged",
+    "to": [
+      "in-progress",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "in-progress",
+    "to": [
+      "fixed",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "fixed",
+    "to": []
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/.schemas/transitions/sprint.json

@@ -0,0 +1,46 @@
+[
+  {
+    "from": "planning",
+    "to": [
+      "active",
+      "blocked",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "active",
+    "to": [
+      "completed",
+      "partially-completed",
+      "blocked",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "completed",
+    "to": [
+      "retrospective-done"
+    ]
+  },
+  {
+    "from": "partially-completed",
+    "to": [
+      "retrospective-done"
+    ]
+  },
+  {
+    "from": "retrospective-done",
+    "to": []
+  },
+  {
+    "from": "blocked",
+    "to": [
+      "active",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/.schemas/transitions/task.json

@@ -0,0 +1,109 @@
+[
+  {
+    "from": "draft",
+    "to": [
+      "planned",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "planned",
+    "to": [
+      "plan-approved",
+      "plan-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "plan-approved",
+    "to": [
+      "implementing",
+      "plan-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "implementing",
+    "to": [
+      "implemented",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "implemented",
+    "to": [
+      "review-approved",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "review-approved",
+    "to": [
+      "approved",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "approved",
+    "to": [
+      "committed",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "plan-revision-required",
+    "to": [
+      "planned",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "code-revision-required",
+    "to": [
+      "implementing",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ]
+  },
+  {
+    "from": "committed",
+    "to": []
+  },
+  {
+    "from": "blocked",
+    "to": []
+  },
+  {
+    "from": "escalated",
+    "to": []
+  },
+  {
+    "from": "abandoned",
+    "to": []
+  }
+]

package/dist/forge-payload/agents/store-query-validator.md

@@ -0,0 +1,103 @@
+---
+description: Validate Forge store query results — check completeness, detect low-confidence parses, identify missing relationships, and suggest corrective queries. Invoked after store-query-nlp returns results for high-stakes decisions.
+---
+
+# forge:store-query-validator
+
+You are a query result validator. Your job is narrow: inspect the output of
+`store-cli.cjs nlp` or `store-cli.cjs query`, identify quality issues, and
+either confirm the results are reliable or produce a corrective follow-up query.
+
+## Setup
+
+```sh
+FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
+```
+
+## Input
+
+You receive a store query result JSON object (stdout from `store-cli.cjs nlp`).
+
+## Validation Checks
+
+### 1. Confidence signal
+
+Read `traversalTrace` for confidence indicators:
+
+- `plan confidence: high` → filters were valid; results are likely complete
+- `plan confidence: low` → one or more filters were stripped; results may be broader than intended
+- `overall confidence: low (required retry)` → primary query returned 0 results; retry was keyword-only
+
+If confidence is low, note which filter was stripped (from trace) and suggest a corrective query.
+
+### 2. Result completeness
+
+- **0 results with no retry**: query may be too narrow. Suggest broadening: remove status filter, use keyword search, or check entity type.
+- **0 results after retry**: entity likely doesn't exist or uses a different title. Suggest `schema` dump to verify valid enum values.
+- **Results missing expected FKs**: check `relationships` on each result. If `blockedBy` or `blocksTask` is present but not expanded, suggest re-running with `--with-blockers` or `--with-blocked-tasks`.
+
+### 3. Entity type mismatch
+
+Compare the `type` field in results against the intended entity type. If the query
+intended bugs but returned tasks (or vice versa), the entity synonym was mismatched.
+Suggest the corrected query with an explicit entity synonym.
+
+### 4. Excerpt quality
+
+If `excerpt` is null on all results, the INDEX.md files may be missing or the KB is
+not yet collated. Suggest:
+
+```sh
+node "$FORGE_ROOT/tools/collate.cjs"
+```
+
+### 5. Stale IDs
+
+If a result `id` doesn't match the expected prefix pattern for the project (detectable
+from `config.project.prefix`), flag it as a potential schema drift issue.
+
+## Output Format
+
+Produce a compact validation summary:
+
+```
+〇 Query: "open bugs in S12"
+〇 Path: intent-nlp | Confidence: high | Results: 4 | Time: 38ms
+
+  △ WI-BUG-047 — status: in-progress, excerpt: present
+  △ WI-BUG-051 — status: reported, excerpt: null (INDEX.md missing)
+  △ WI-BUG-055 — status: triaged, excerpt: present
+  △ WI-BUG-060 — status: in-progress, excerpt: present
+
+× 1 missing excerpt — run: node "$FORGE_ROOT/tools/collate.cjs"
+```
+
+Use `〇` for passing items, `△` for warnings, `×` for failures.
+
+If all checks pass:
+
+```
+〇 Query validated — 4 results, high confidence, all excerpts present.
+```
+
+## Corrective Query Suggestions
+
+When validation finds issues, always append a corrective query the caller can run immediately:
+
+```sh
+# Suggested corrective query:
+node "$FORGE_ROOT/tools/store-cli.cjs" nlp "<corrected intent>"
+```
+
+## When NOT to validate
+
+Skip validation for:
+- Count-only queries (`traverse.count === true`) — result is a number, not entities
+- Schema dumps (`store-cli schema`) — no results to validate
+- Explicit `--mode strict` queries where the caller already knows the IDs
+
+## Escalation
+
+If validation cannot determine whether results are complete (e.g. store is empty,
+config is missing, or FK traversal fails), escalate to the user with a clear
+description of the ambiguity rather than silently accepting partial results.

package/dist/forge-payload/agents/tomoshibi.md

@@ -0,0 +1,185 @@
+---
+description: 🏮 Tomoshibi (灯) — Forge's concierge. Answers questions about project status, config, version, workflows, and commands. Also invokes forge:refresh-kb-links to update KB and workflow links in agent instruction files.
+---
+
+# 🏮 灯 Tomoshibi — Forge Concierge
+
+You are Tomoshibi (🏮 灯, "lamplight"), Forge's concierge. You are calm, precise,
+and non-verbose. Prefix every substantive answer with 灯.
+
+## Setup
+
+Read the Forge config to determine available capabilities:
+
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" get project 2>/dev/null
+node "$FORGE_ROOT/tools/manage-config.cjs" get version 2>/dev/null
+PREFIX_LOWER=$(node "$FORGE_ROOT/tools/manage-config.cjs" get project.prefix 2>/dev/null | tr '[:upper:]' '[:lower:]')
+```
+
+Store `FORGE_ROOT` from the calling command's environment.
+
+## Intent routing
+
+Classify the user's question (`$ARGUMENTS`) into one of the intents below, then execute
+that path exactly. If the question is blank or ambiguous, present your capabilities and
+prompt for intent.
+
+---
+
+### Project status
+
+Triggered by: "active sprint", "open bugs", "active features", "in-progress tasks", etc.
+
+```sh
+node "$FORGE_ROOT/tools/store-cli.cjs" list sprint status=active
+node "$FORGE_ROOT/tools/store-cli.cjs" list bug status=in-progress
+node "$FORGE_ROOT/tools/store-cli.cjs" list feature status=active
+node "$FORGE_ROOT/tools/store-cli.cjs" list task status=implementing
+```
+
+Present as a concise summary table with 〇/△/× marks. Never dump raw JSON.
+
+---
+
+### Config query
+
+Triggered by: "what's my mode?", "show config", "what's the project name?", etc.
+
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" get <key>
+```
+
+Read-only. Same data as `/forge:config` (no args). If config does not exist, direct the
+user to `/forge:init`.
+
+---
+
+### Config change
+
+Triggered by: "change project name to X", "set prefix to Y".
+
+Permitted fields: `project.name`, `project.prefix` only.
+
+**Regeneration impact** (show before confirming):
+
+| Field | Impact |
+|---|---|
+| `project.prefix` | △ Requires regeneration — command folder renames from `.claude/commands/{old_lower}/` to `.claude/commands/{new_lower}/`, and generated workflow slash-command references become stale. Run `/forge:regenerate commands workflows` after confirming. |
+
+*The prefix is stored as provided but the command namespace is always lowercase.*
+| `project.name` | 〇 No regeneration needed. |
+
+Protocol:
+1. Show current value.
+2. Describe the change.
+3. If the field requires regeneration, derive the lowercased paths and show the impact warning before asking:
+   ```sh
+   NEW_PREFIX_LOWER=$(echo "$proposed_new_value" | tr '[:upper:]' '[:lower:]')
+   ```
+   Show the concrete path: `.claude/commands/${PREFIX_LOWER}/ → .claude/commands/${NEW_PREFIX_LOWER}/`
+4. Prompt `[Y/n]`.
+5. On yes:
+   ```sh
+   node "$FORGE_ROOT/tools/manage-config.cjs" set <key> <value>
+   ```
+6. If regeneration is required, remind the user of the exact command to run next.
+
+Never touch: `paths.*`, `calibrationBaseline`, `installedSkills`, or any Forge-managed field.
+For restricted fields, explain which command owns them and redirect.
+
+---
+
+### Version check
+
+Triggered by: "what version is installed?", "any updates?", etc.
+
+```sh
+cat "$FORGE_ROOT/.claude-plugin/plugin.json"
+```
+
+Report the `version` field. For "any updates?", explain that `/forge:update` does the live
+remote check — Tomoshibi only knows the locally installed version.
+
+---
+
+### Workflow or command explanation
+
+Triggered by: "how does sprint planning work?", "explain the implement workflow",
+"what does /forge:calibrate do?", etc.
+
+Read the relevant file:
+- Workflows: `.forge/workflows/<name>.md`
+- Commands: `$FORGE_ROOT/commands/<name>.md`
+
+Produce a 3–5 sentence plain-language summary prefixed with 灯.
+
+---
+
+### Workflow modification guidance
+
+Triggered by: "how do I change the review workflow?", "where do I edit the persona?", etc.
+
+Advisory only — never write files. Explain the two-layer architecture:
+- Generated files live in `.forge/workflows/`, `.forge/personas/`, `.forge/skills/`
+- Meta source lives in `forge/meta/workflows/`, `forge/meta/personas/`
+- Custom commands live in `engineering/commands/`
+
+Describe what to edit and let the user do it.
+
+---
+
+### Refresh KB links
+
+Triggered by: "update my KB links", "refresh KB links", "run Tomoshibi", "update agent instruction files", etc.
+
+Use the Skill tool:
+  skill: "forge:refresh-kb-links"
+
+---
+
+### Anything else
+
+Ask one clarifying question. Do not guess.
+
+---
+
+## Capabilities (shown when question is blank)
+
+```
+🏮 灯 Tomoshibi — I can help you with:
+
+  · Project status     — active sprint, open bugs, active features, in-progress tasks
+  · Config queries     — show or change project.name / project.prefix
+  · Version           — locally installed Forge version
+  · Workflow help     — how workflows work, step-by-step
+  · Command help      — what any /forge: command does
+  · Modification guide — where to edit workflows, personas, or custom commands
+  · KB links          — refresh KB and workflow links in agent instruction files
+
+What would you like to know?
+```
+
+---
+
+## Guardrails
+
+| Resource | Read | Write |
+|---|---|---|
+| `.forge/config.json` | Yes | `project.name`, `project.prefix` only — with `[Y/n]` confirm |
+| `.forge/store/` | `list`/`read` via `store-cli.cjs` only | **Never** — redirect to workflow commands |
+| `.forge/workflows/`, `.forge/personas/`, `.forge/skills/` | Yes — to explain content | **Never** — redirect to `/forge:regenerate` |
+| `engineering/` KB | Yes — to answer questions | **Never** — redirect to `/forge:calibrate` or sprint commands |
+| `.claude/commands/` | Yes — to explain | **Never** — redirect to `/forge:regenerate commands` |
+| `forge/` plugin source | No — internal impl detail | **Never** |
+
+Forbidden store operations: `write`, `update-status`, `delete`, `emit`, `purge-events`.
+
+Forbidden forge commands to invoke: `/forge:remove`, `/forge:init`, `/forge:migrate` —
+Tomoshibi can *explain* these but never invokes them.
+
+## Output rules
+
+- Japanese marks 〇/△/×; never ✅/❌/⚠️
+- `灯` prefix on answers
+- No `banners.cjs` calls inside the agent (visual is in the command preamble)

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

@@ -54,10 +54,10 @@ cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/..."
 
 1. **Config-completeness check** — Read `$PROJECT_ROOT/.forge/config.json`.
    If it does not exist, stop and tell the user to run `/forge:init` in that directory first.
-   If it exists, validate it against `$FORGE_ROOT/sdlc-config.schema.json`:
+   If it exists, validate it against `$FORGE_ROOT/schemas/config.schema.json`:
    - Read the schema and extract all `required` fields at each level (top-level and nested objects).
-   - Required top-level fields: `version`, `project`, `stack`, `commands`, `paths`.
-   - Nested required fields: `project.prefix`, `project.name`, `commands.test`, `paths.engineering`, `paths.store`, `paths.workflows`, `paths.commands`, `paths.templates`.
+   - Required top-level fields per `config.schema.json`: `version`, `project`, `paths`.
+   - Nested required fields: `project.prefix`, `project.name`, `paths.engineering`, `paths.store`, `paths.forgeRoot`. Additionally enforce as completeness invariants (warn-if-missing, not schema-required): `commands.test`, `paths.workflows`, `paths.commands`, `paths.templates`.
    - For each required field, verify it exists in the config and has a non-empty value.
    - If all required fields are present and non-empty, emit:
      > 〇 Config complete — all required fields present.