@entelligentsia/forgecli 0.19.0 → 0.20.3

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

@@ -0,0 +1,215 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Entelligentsia/agentic-skills/forge/config.schema.json",
+  "title": "ForgeConfig",
+  "description": "Schema for .forge/config.json — the per-project Forge configuration file. Canonical single-source schema (FORGE-S25-T12 reconciled sdlc-config.schema.json into this file and deleted the sibling). Generated by /forge:init and refreshed by /forge:update.",
+  "type": "object",
+  "required": ["version", "project", "paths"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Config schema version (e.g. '1.0'). Used for migration support."
+    },
+    "project": {
+      "type": "object",
+      "required": ["prefix", "name"],
+      "properties": {
+        "prefix": {
+          "type": "string",
+          "description": "Short prefix for task/sprint/bug IDs (e.g. ACME)"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable project name"
+        },
+        "description": {
+          "type": "string",
+          "description": "One-line project description"
+        }
+      }
+    },
+    "stack": {
+      "type": "object",
+      "description": "Detected/declared project technology stack. Optional fields nullable because not every project ships e.g. a frontend or task queue.",
+      "properties": {
+        "languages": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Primary languages detected"
+        },
+        "framework":         { "type": ["string", "null"], "description": "Primary backend framework" },
+        "frontendFramework": { "type": ["string", "null"], "description": "Frontend framework if detected" },
+        "database":          { "type": ["string", "null"], "description": "Primary database" },
+        "taskQueue":         { "type": ["string", "null"], "description": "Task queue if detected (celery, sidekiq, etc.)" },
+        "containerisation":  { "type": ["string", "null"], "description": "Container tooling if detected" }
+      }
+    },
+    "commands": {
+      "type": "object",
+      "description": "Resolved project tooling commands. Workflows reference these via {COMMAND_TEST} / {LINT_COMMAND} placeholders.",
+      "properties": {
+        "test":          { "type": "string" },
+        "build":         { "type": "string" },
+        "lint":          { "type": "string" },
+        "syntaxCheck": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "migrate":       { "type": "string" },
+        "migrateCheck":  { "type": "string" }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "required": ["engineering", "store", "forgeRoot"],
+      "properties": {
+        "engineering":     { "type": "string", "default": "engineering" },
+        "store":           { "type": "string", "default": ".forge/store" },
+        "workflows":       { "type": "string", "default": ".forge/workflows" },
+        "commands":        { "type": "string", "default": ".claude/commands" },
+        "templates":       { "type": "string", "default": ".forge/templates" },
+        "customCommands":  { "type": "string", "default": "engineering/commands", "description": "Directory for project-specific custom pipeline phase commands. Files here are workflow scripts invoked directly by the orchestrator via the phase workflow field." },
+        "forgeRoot":       { "type": "string", "description": "Absolute path to the installed Forge plugin root. Set at init time and refreshed by /forge:update. Used by generated workflows to invoke Forge tools without requiring $CLAUDE_PLUGIN_ROOT in subagent contexts." },
+        "forgeRef":        { "type": "string", "description": "Pinned Forge plugin reference (tag or commit) the project was generated against." }
+      }
+    },
+    "pipeline": {
+      "type": "object",
+      "description": "Optional pipeline customisation for the default pipeline",
+      "properties": {
+        "skipPhases": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "maxReviewIterations": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3
+        },
+        "includeTokenDataInBugReports": {
+          "type": "boolean",
+          "description": "If set, silently opt in (true) or out (false) of appending sprint token usage data to Forge bug reports. When absent, the user is prompted at report time."
+        }
+      }
+    },
+    "pipelines": {
+      "type": "object",
+      "description": "Named pipeline definitions. Each key is a pipeline name that tasks can reference via their `pipeline` field. The `default` pipeline is used when a task has no `pipeline` field. Projects define custom pipelines to route tasks to specialized agent commands.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["phases"],
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of when to use this pipeline"
+          },
+          "phases": {
+            "type": "array",
+            "description": "Ordered list of pipeline phases. Each phase maps to a slash command.",
+            "items": {
+              "type": "object",
+              "required": ["command", "role"],
+              "properties": {
+                "command": {
+                  "type": "string",
+                  "description": "Slash command name (without /) to invoke for this phase"
+                },
+                "role": {
+                  "type": "string",
+                  "enum": ["plan", "review-plan", "implement", "review-code", "validate", "approve", "commit"],
+                  "description": "Semantic role of this phase in the pipeline lifecycle"
+                },
+                "model": {
+                  "type": "string",
+                  "description": "Optional model override for this phase"
+                },
+                "maxIterations": {
+                  "type": "integer",
+                  "description": "Max revision loop iterations for review phases",
+                  "default": 3
+                },
+                "on_revision": {
+                  "type": "string",
+                  "description": "Command name of the phase to re-invoke on 'Revision Required'. Defaults to the nearest preceding non-review phase if omitted."
+                },
+                "workflow": {
+                  "type": "string",
+                  "description": "Optional path to a workflow file. When set, the orchestrator reads and follows this file directly instead of deriving the workflow from the command name. Use for custom phase commands in engineering/commands/."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "installedSkills": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Marketplace skill names installed during forge:init or recommended by forge:health. Used to wire skill invocations into generated personas and workflows.",
+      "examples": ["vue-best-practices", "stripe-integration", "claude-api"]
+    },
+    "sprint": {
+      "type": "object",
+      "description": "Optional sprint execution configuration",
+      "properties": {
+        "execution": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["sequential", "wave-parallel", "full-parallel"],
+              "default": "sequential"
+            },
+            "maxConcurrentAgents": {
+              "type": "integer",
+              "default": 3
+            }
+          }
+        }
+      }
+    },
+    "calibrationBaseline": {
+      "type": "object",
+      "description": "Calibration baseline written by /forge:init after skill generation. Records the state at calibration time so /forge:calibrate can detect drift.",
+      "properties": {
+        "lastCalibrated":   { "type": "string", "description": "ISO date (YYYY-MM-DD) of the last calibration run" },
+        "version":          { "type": "string", "description": "Plugin version string at calibration time (e.g. 0.9.3)" },
+        "masterIndexHash":  { "type": "string", "description": "SHA-256 hex digest of the semantic content of engineering/MASTER_INDEX.md at calibration time" },
+        "sprintsCovered":   { "type": "array", "items": { "type": "string" }, "description": "Sprint IDs whose tasks and outcomes were included in the calibration baseline" }
+      }
+    },
+    "calibrationHistory": {
+      "type": "array",
+      "description": "Audit trail of calibration runs. Each entry records the drift categories detected and the patches applied.",
+      "items": {
+        "type": "object",
+        "required": ["date", "version", "categories", "patches"],
+        "additionalProperties": false,
+        "properties": {
+          "date":       { "type": "string", "description": "ISO date (YYYY-MM-DD) of this calibration run" },
+          "version":    { "type": "string", "description": "Plugin version at calibration time" },
+          "categories": { "type": "array", "items": { "type": "string" }, "description": "Drift categories detected: technical, business, retrospective, acceptance-criteria" },
+          "patches": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["target", "type", "applied"],
+              "additionalProperties": false,
+              "properties": {
+                "target":  { "type": "string", "description": "Regeneration target (e.g. personas:engineer, skills:supervisor-skills)" },
+                "type":    { "type": "string", "enum": ["regenerate"], "description": "Patch type (currently only 'regenerate' is supported)" },
+                "applied": { "type": "boolean", "description": "Whether this patch was applied (true if approved and succeeded, false if skipped or failed)" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["full", "fast"],
+      "description": "Init mode. 'fast' means scaffolding was generated by /forge:init --fast (stubs present, heavy artifacts deferred to first use). 'full' means all artifacts are generated. Absent on pre-0.12 projects — treated as 'full' by all readers. Flipped to 'full' by /forge:regenerate (default) or /forge:materialize --all."
+    }
+  },
+  "additionalProperties": false
+}

package/dist/forge-payload/schemas/enum-catalog.json

@@ -0,0 +1,71 @@
+{
+  "version": "0.51.1",
+  "generated": "2026-05-23",
+  "note": "Authoritative enum catalog. Source: build-enum-catalog.cjs. Regenerate via node forge/tools/build-manifest.cjs.",
+  "enums": {
+    "task.status": [
+      "draft",
+      "planned",
+      "plan-approved",
+      "implementing",
+      "implemented",
+      "review-approved",
+      "approved",
+      "committed",
+      "plan-revision-required",
+      "code-revision-required",
+      "blocked",
+      "escalated",
+      "abandoned"
+    ],
+    "sprint.status": [
+      "planning",
+      "active",
+      "completed",
+      "retrospective-done",
+      "blocked",
+      "partially-completed",
+      "abandoned"
+    ],
+    "bug.status": [
+      "reported",
+      "triaged",
+      "in-progress",
+      "fixed"
+    ]
+  },
+  "commandNames": [
+    "forge:sprint-intake",
+    "forge:plan",
+    "forge:review-plan",
+    "forge:implement",
+    "forge:review-code",
+    "forge:fix-bug",
+    "forge:sprint-plan",
+    "forge:run-task",
+    "forge:run-sprint",
+    "forge:collate",
+    "forge:retrospective",
+    "forge:approve",
+    "forge:commit",
+    "forge:enhance",
+    "forge:quiz-agent",
+    "forge:validate",
+    "forge:init",
+    "forge:health",
+    "forge:regenerate",
+    "forge:update",
+    "forge:add-task",
+    "forge:add-pipeline",
+    "forge:calibrate",
+    "forge:materialize",
+    "forge:remove",
+    "forge:report-bug",
+    "forge:store-query",
+    "forge:store-repair",
+    "forge:config",
+    "forge:ask",
+    "forge:store-custodian",
+    "forge:refresh-kb-links"
+  ]
+}

package/dist/forge-payload/schemas/event-sidecar.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/event-sidecar.schema.json",
+  "title": "Event Sidecar",
+  "description": "Subset of event schema — token/cost/duration fields written by agents before canonical merge. All fields other than eventId are optional; presence enforcement happens on the canonical event, not the sidecar.",
+  "type": "object",
+  "required": ["eventId"],
+  "additionalProperties": false,
+  "properties": {
+    "eventId":          { "type": "string", "minLength": 1 },
+    "inputTokens":      { "type": "integer", "minimum": 0 },
+    "outputTokens":     { "type": "integer", "minimum": 0 },
+    "cacheReadTokens":  { "type": "integer", "minimum": 0 },
+    "cacheWriteTokens": { "type": "integer", "minimum": 0 },
+    "model":            { "type": "string",  "maxLength": 120 },
+    "provider":         { "type": "string",  "maxLength": 60 },
+    "durationMinutes":  { "type": "number",  "minimum": 0 },
+    "startTimestamp":   { "type": "string",  "format": "date-time" },
+    "endTimestamp":     { "type": "string",  "format": "date-time" },
+    "tokenSource":      { "type": "string",  "enum": ["reported", "estimated"] }
+  }
+}

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

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/event.schema.json",
+  "title": "Event",
+  "type": "object",
+  "required": [
+    "eventId", "sprintId", "role", "action",
+    "startTimestamp", "endTimestamp", "durationMinutes", "model", "provider"
+  ],
+  "properties": {
+    "eventId":         { "type": "string" },
+    "taskId":          { "type": "string" },
+    "bugId":          { "type": "string" },
+    "sprintId":        { "type": "string" },
+    "role":            { "type": "string" },
+    "action":          { "type": "string" },
+    "phase":           { "type": "string" },
+    "iteration":       { "type": "integer", "minimum": 1 },
+    "startTimestamp":  { "type": "string", "format": "date-time" },
+    "endTimestamp":    { "type": "string", "format": "date-time" },
+    "durationMinutes": { "type": "number", "minimum": 0 },
+    "model":           { "type": "string" },
+    "provider":        { "type": "string", "maxLength": 60 },
+    "verdict":            { "type": "string" },
+    "notes":              { "type": "string" },
+    "inputTokens":        { "type": "integer", "minimum": 0 },
+    "outputTokens":       { "type": "integer", "minimum": 0 },
+    "cacheReadTokens":    { "type": "integer", "minimum": 0 },
+    "cacheWriteTokens":   { "type": "integer", "minimum": 0 },
+    "tokenSource":        { "type": "string",  "enum": ["reported", "estimated"] },
+
+    "resolution": {
+      "type": "object",
+      "properties": {
+        "status":      { "type": "string", "enum": ["open", "resolved", "wontfix", "deferred"] },
+        "resolvedBy":  { "type": "string" },
+        "resolvedAt":  { "type": "string", "format": "date-time" },
+        "proposalRef": { "type": "string" },
+        "bugRef":       { "type": "string" }
+      },
+      "required": ["status"],
+      "additionalProperties": false
+    },
+
+    "type":     {
+      "type": "string",
+      "enum": [
+        "friction",
+        "task-planned",
+        "plan-complete",
+        "plan-approved",
+        "task-implemented",
+        "review-passed",
+        "review-failed",
+        "task-approved",
+        "task-validated",
+        "task-committed",
+        "sprint-complete",
+        "sprint-halted",
+        "bug-fixed",
+
+        "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
+        "fix-implemented", "fix-code-review-passed", "fix-code-review-failed",
+        "fix-approved", "bug-committed",
+
+        "skill_usage"
+      ]
+    },
+    "workflow": { "type": "string" },
+    "persona":  { "type": "string" },
+    "issue":    { "type": "string" },
+    "subkind":  {
+      "type": "string",
+      "pattern": "^(skill_unused|skill_failed|skill_missing|skill_stale|skill_redundant|x_[a-z_]+)$"
+    },
+    "evidence": {
+      "type": "object",
+      "properties": {
+        "trajectory_excerpt": { "type": "string" },
+        "tool_errors":        { "type": "array", "items": { "type": "string" } },
+        "retrieval_score":    { "type": "number", "minimum": 0, "maximum": 1 },
+        "skillId":            { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+
+    "taskCount":            { "type": "integer", "minimum": 0 },
+    "completedTaskIds":     { "type": "array", "items": { "type": "string" } },
+    "pausedAfterTaskIndex": { "type": "integer", "minimum": 0 },
+    "haltedAtTaskIndex":    { "type": "integer", "minimum": 0 },
+    "haltedAtTaskId":       { "type": "string" },
+    "lastError":            { "type": "string" },
+    "waveCount":            { "type": "integer", "minimum": 1 },
+    "maxConcurrency":       { "type": "integer", "minimum": 1 },
+
+    "skillId":                { "type": "string", "minLength": 1 },
+    "retrieved":              { "type": "boolean" },
+    "used":                   { "type": "boolean" },
+    "tool_call_success_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+    "retrieval_score":        { "type": "number", "minimum": 0, "maximum": 1 }
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if":   { "properties": { "type": { "const": "friction" } }, "required": ["type"] },
+      "then": { "required": ["workflow", "persona", "issue"] }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "task-planned", "plan-complete", "plan-approved",
+              "task-implemented", "review-passed", "review-failed",
+              "task-approved", "task-validated", "task-committed"
+            ]
+          }
+        },
+        "required": ["type"]
+      },
+      "then": { "required": ["taskId", "phase", "iteration"] }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
+              "fix-implemented", "fix-code-review-passed", "fix-code-review-failed",
+              "fix-approved", "bug-committed", "bug-fixed"
+            ]
+          }
+        },
+        "required": ["type"]
+      },
+      "then": { "required": ["bugId", "phase", "iteration"] }
+    },
+    {
+      "if": { "properties": { "type": { "const": "sprint-complete" } }, "required": ["type"] },
+      "then": {
+        "required": [
+          "eventId", "sprintId", "role", "action",
+          "startTimestamp", "endTimestamp", "durationMinutes",
+          "model", "provider",
+          "taskCount", "completedTaskIds", "verdict"
+        ],
+        "properties": {
+          "taskCount":            { "type": "integer", "minimum": 0 },
+          "completedTaskIds":     { "type": "array", "items": { "type": "string" } },
+          "verdict":              { "type": "string", "enum": ["complete", "partial"] },
+          "pausedAfterTaskIndex": { "type": "integer", "minimum": 0 },
+          "waveCount":            { "type": "integer", "minimum": 1 },
+          "maxConcurrency":       { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "sprint-halted" } }, "required": ["type"] },
+      "then": {
+        "required": [
+          "eventId", "sprintId", "role", "action",
+          "startTimestamp", "endTimestamp", "durationMinutes",
+          "model", "provider",
+          "haltedAtTaskIndex", "haltedAtTaskId", "lastError"
+        ],
+        "properties": {
+          "haltedAtTaskIndex": { "type": "integer", "minimum": 0 },
+          "haltedAtTaskId":    { "type": "string" },
+          "lastError":         { "type": "string" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "type": { "const": "skill_usage" } }, "required": ["type"] },
+      "then": {
+        "required": [
+          "eventId", "sprintId", "taskId",
+          "skillId", "retrieved", "used",
+          "tool_call_success_rate", "retrieval_score"
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/feature.schema.json",
+  "title": "Feature",
+  "type": "object",
+  "required": ["id", "title", "status", "created_at"],
+  "properties": {
+    "id": { "type": "string" },
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "shipped", "retired"]
+    },
+    "requirements": { "type": "array", "items": { "type": "string" } },
+    "sprints":      { "type": "array", "items": { "type": "string" } },
+    "tasks":        { "type": "array", "items": { "type": "string" } },
+    "created_at":   { "type": "string", "format": "date-time" },
+    "updated_at":   { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/dist/forge-payload/schemas/progress-entry.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/progress-entry.schema.json",
+  "title": "Progress Entry",
+  "description": "One line of progress.log, parsed from pipe-delimited fields: timestamp|agentName|bannerKey|status|detail",
+  "type": "object",
+  "required": ["timestamp", "agentName", "bannerKey", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "timestamp": { "type": "string", "format": "date-time" },
+    "agentName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" },
+    "bannerKey": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.:-]{0,127}$" },
+    "status":    { "type": "string", "enum": ["start", "progress", "done", "error"] },
+    "detail":    { "type": "string", "maxLength": 500 }
+  }
+}