@entelligentsia/forgecli 0.15.0 → 0.20.0

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

@@ -20,8 +20,10 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Review Plan
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Evaluate the plan against what the task actually requires, not against what the plan claims to deliver. Plans routinely understate complexity, omit edge cases, or skip security steps. Your job is adversarial review, not approval.
@@ -30,15 +32,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
 
@@ -61,7 +55,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Identify missing edge cases or failure modes
 
 3. Verdict:
-   - Write PLAN_REVIEW.md using the format:
+   - Write the plan review via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan-review", content:"<markdown>" })
+     Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
@@ -77,7 +72,8 @@ 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 `REVIEW-PLAN-SUMMARY.json` to the record's directory with the following shape:
+   - Write the review-plan summary via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-plan-summary", content:"<JSON>" })
+     The JSON must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -89,20 +85,13 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      ```
    - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} review_plan \
-       engineering/sprints/{sprint}/{task}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-summary", entity:"task", id:"{record_id}", phase:"review_plan" })
      ```
      Or (bug mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} review_plan \
-       engineering/bugs/{bugDir}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-bug-summary", entity:"bug", id:"{record_id}", phase:"review_plan" })
      ```
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
-## Generation Notes
-
-- Enforce `**Verdict:** [Approved | Revision Required]` format exactly — orchestrator branches on this.
-- **Markers (required by `/forge:run-task` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `.forge/personas/supervisor.md` persona path. Missing any → kickoff shim refuses to dispatch.
-- Token Reporting: `_fragments/finalize.md` — wire via `file_ref:`.
-- Event Emission: "complete" event MUST include the `eventId` passed by the orchestrator.
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -12,7 +12,14 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Retrospective
+## Iron Laws
+
+- Never mutate JSON records during retrospective; the store is the source of truth and retrospective flows downstream from it. Retrospective operations read store data and write markdown views only.
+- Read `.forge/personas/architect.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
 ## Algorithm
 
 ```
@@ -42,4 +49,6 @@ deps:
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) 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.
      (tombstone — written after the purge; the only event in the directory
      going forward)
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [commands.test, paths.engineering]
 ---
 
+
 # Update Implementation
 ## 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
 
@@ -59,4 +52,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 4. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status implemented`
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) 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.
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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

@@ -20,6 +20,7 @@ deps:
   config_fields: [paths.engineering]
 ---
 
+
 # Update Plan
 ## 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
 
@@ -59,4 +52,6 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 4. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status planned`
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) 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.
-```
+```
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->

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"
+  ]
+}