@entelligentsia/forgecli 0.15.0 → 0.19.0

package/dist/forge-payload/.base-pack/workflows/validate_task.md

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Validate Task
 ## Iron Laws
 
@@ -29,15 +30,7 @@ deps:
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -63,7 +56,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - When re-running the test suite, use the **resolved test command** from `commands.test` in `.forge/config.json` (i.e. `` `${commands.test}` ``, e.g. `.venv/bin/python -m pytest`). Template placeholder: {{TEST_COMMAND}}. Do NOT invoke bare `python` / `python3` — the project interpreter is rarely on `$PATH`.
 
 3. Verdict:
-   - Write VALIDATION_REPORT.md using the format:
+   - Write the validation report via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-report", content:"<markdown>" })`
+     The markdown content must use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: list the failed criteria and required fixes
      - If Approved: confirm the task is validated
@@ -73,7 +68,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
 5. Emit Summary Sidecar:
-   - Write `VALIDATION-SUMMARY.json` to the task directory with the following shape:
+   - Write the validation summary via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-summary", content:"<JSON>" })`
+     The JSON content must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what acceptance criteria were validated>",
@@ -92,4 +89,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 ```
 
 ## Friction Emit
-Emit `type:friction` `{workflow:validate, persona:qa-engineer, issue}` per `_fragments/friction-emit.md`.
+Emit `type:friction` `{workflow:validate, persona:qa-engineer, issue}` per `_fragments/friction-emit.md`.
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

package/dist/forge-payload/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "forge",
-  "version": "0.46.1",
-  "description": "Self-enhancing AI software development lifecycle \u2014 generates project-specific SDLC instances from meta-definitions",
+  "version": "0.51.3",
+  "description": "Self-enhancing AI software development lifecycle — generates project-specific SDLC instances from meta-definitions",
   "license": "MIT",
   "author": {
     "name": "Entelligentsia",
@@ -9,8 +9,8 @@
     "url": "https://github.com/Entelligentsia"
   },
   "repository": "https://github.com/Entelligentsia/forge",
-  "updateUrl": "https://raw.githubusercontent.com/Entelligentsia/forge/release/forge/.claude-plugin/plugin.json",
-  "migrationsUrl": "https://raw.githubusercontent.com/Entelligentsia/forge/release/forge/migrations.json",
+  "updateUrl": "https://raw.githubusercontent.com/Entelligentsia/forge/main/forge/.claude-plugin/plugin.json",
+  "migrationsUrl": "https://raw.githubusercontent.com/Entelligentsia/forge/main/forge/migrations.json",
   "keywords": [
     "sdlc",
     "ai-agents",
@@ -18,4 +18,4 @@
     "sprint-planning",
     "meta-generator"
   ]
-}
+}

package/dist/forge-payload/.schemas/_defs/phaseSummary.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/_defs/phaseSummary.schema.json",
+  "title": "PhaseSummary",
+  "description": "Shared shape for terse structured summaries of phase artifacts. Single-sourced under _defs/ and $ref'd from task.schema.json and bug.schema.json. Optional bug-only `route` field is permitted on every $ref site but only meaningful on the triage phase summary written by meta-fix-bug.md.",
+  "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" },
+    "route":       { "type": "string", "enum": ["A", "B"], "description": "Fix-bug pipeline route decision. Only set on the triage phase summary by meta-fix-bug.md. A = short-circuit (skip plan-fix + review-plan); B = full loop (default). Optional and meaningless on non-triage phases — see meta-fix-bug.md § Triage Judgement." }
+  },
+  "additionalProperties": false
+}

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

@@ -25,32 +25,16 @@
       "type": "object",
       "description": "Terse structured summaries of phase artifacts. Optional; full artifacts on disk remain authoritative.",
       "properties": {
-        "plan":           { "$ref": "#/$defs/phaseSummary" },
-        "triage":         { "$ref": "#/$defs/phaseSummary" },
-        "review_plan":    { "$ref": "#/$defs/phaseSummary" },
-        "implementation": { "$ref": "#/$defs/phaseSummary" },
-        "code_review":    { "$ref": "#/$defs/phaseSummary" },
-        "validation":     { "$ref": "#/$defs/phaseSummary" },
-        "approve":        { "$ref": "#/$defs/phaseSummary" }
+        "plan":           { "$ref": "_defs/phaseSummary.schema.json" },
+        "triage":         { "$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" },
+        "approve":        { "$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" },
-        "route":       { "type": "string", "enum": ["A", "B"], "description": "Fix-bug pipeline route decision. Only set on the triage phase summary by meta-fix-bug.md. A = short-circuit (skip plan-fix + review-plan); B = full loop (default). Optional and meaningless on non-triage phases — see meta-fix-bug.md § Triage Judgement." }
-      },
-      "additionalProperties": false
-    }
-  }
+  "additionalProperties": false
 }

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

@@ -1,83 +1,215 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "forge/config.schema.json",
+  "$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.",
+  "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')"
+      "description": "Config schema version (e.g. '1.0'). Used for migration support."
     },
     "project": {
       "type": "object",
       "required": ["prefix", "name"],
       "properties": {
-        "prefix": { "type": "string", "description": "Task ID prefix (e.g. FORGE)" },
-        "name": { "type": "string", "description": "Human-readable project name" },
-        "description": { "type": "string" }
+        "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" } },
-        "framework": { "type": ["string", "null"] },
-        "frontendFramework": { "type": ["string", "null"] },
-        "database": { "type": ["string", "null"] },
-        "taskQueue": { "type": ["string", "null"] },
-        "containerisation": { "type": ["string", "null"] }
+        "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" },
-        "lint": { "type": "string" },
-        "syntaxCheck": {}
+        "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" },
-        "store": { "type": "string" },
-        "workflows": { "type": "string" },
-        "commands": { "type": "string" },
-        "templates": { "type": "string" },
-        "customCommands": { "type": "string" },
-        "forgeRoot": { "type": "string" },
-        "forgeRef": { "type": "string" }
+        "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": {
-        "maxReviewIterations": { "type": "integer", "minimum": 1 }
+        "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": "Custom pipeline definitions keyed by pipeline name"
+      "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" }
+      "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" },
-        "version": { "type": "string" },
-        "masterIndexHash": { "type": "string" },
-        "sprintsCovered": { "type": "array", "items": { "type": "string" } }
+        "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"]
+      "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"
+  ]
+}