@entelligentsia/forgecli 0.21.0 → 1.0.2

package/dist/forge-payload/meta/workflows/meta-plan-task.md

@@ -30,13 +30,25 @@ The Engineer reads the task prompt, researches the codebase, and produces an imp
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase plan --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
+
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `draft`, `planned`, `plan-revision-required`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:plan cannot run from this state; a reset or reassignment must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
 1. Load Context:
    - Read `.forge/personas/architect.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
    - store-cli verbs: `read` | `list` | `write` | `emit` | `update-status` | `set-summary` | `describe` | `nlp` | `query` | `delete` — there is no `get`/`set`/`find`. See `_fragments/store-cli-verbs.md` for full notes; run `--help` before improvising.

package/dist/forge-payload/meta/workflows/meta-retro.md

@@ -0,0 +1,73 @@
+---
+requirements:
+  reasoning: High
+  context: Medium
+  speed: Low
+deps:
+  personas: [architect]
+  skills: [architect, generic]
+  templates: [RETROSPECTIVE_TEMPLATE]
+  sub_workflows: []
+  kb_docs: [architecture/stack.md]
+  config_fields: [paths.engineering]
+---
+
+# 🗻 Meta-Workflow: Retrospective
+
+## Purpose
+
+Close a sprint by reviewing learnings, updating the knowledge base, and improving workflows.
+
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## 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
+
+```
+1. Load Context:
+   - Read all task manifests for the sprint
+   - Read all event logs (including token usage)
+   - Read all retrospective notes gathered during the sprint
+
+2. Analysis:
+   - Calculate total sprint cost (tokens/USD)
+   - Identify "bottleneck" tasks (high iteration counts or long duration)
+   - Analyze common failure modes in reviews
+
+3. Knowledge Update:
+   - Update architecture/domain docs with "lessons learned"
+   - Propose improvements to meta-workflows based on analysis
+   - Update stack-checklist with new verification steps
+
+4. Finalize:
+   - Write SPRINT_RETROSPECTIVE.md
+   - Update sprint status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status sprint {sprintId} status retrospective-done`
+   - Run `node "$FORGE_ROOT/tools/collate.cjs" {sprintId} --purge-events`
+     This single deterministic step: generates COST_REPORT.md from all
+     accumulated events, then deletes `.forge/store/events/{sprintId}/`.
+     COST_REPORT.md is the durable record; the raw event files are not
+     retained after retrospective close.
+   - **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 -->
+## Generation Instructions
+
+- **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.
+- **Workflow Structure:** The generated `retrospective.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of cost analysis or doc updates; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Reference project's cost reporting templates.
+- **Token Reporting:** The generated workflow MUST mandate the following before returning:
+  1. Probe session token usage: invoke `/cost` if the host runtime supports it
+     (Claude Code only); on any other runtime treat as unavailable and proceed.
+     Do NOT shell out to a `cost-cli.cjs` — there is no such tool.
+  2. Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
+  3. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

package/dist/forge-payload/meta/workflows/meta-review-implementation.md

@@ -41,43 +41,73 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-code --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
-1. Load Context:
+
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `implemented`, `implementing`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:implement must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
+1. Read Review Loop Context:
+   - Check the spawning prompt for a `### Review Loop Context` block.
+   - If present, extract:
+     - `Iteration: N of M` — current attempt number and the configured limit
+     - `Is final iteration: true/false`
+   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
+     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
+   - Include `(iteration N of M)` in the opening line of the `CODE_REVIEW.md` artifact.
+   - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
+     append a `### Next Steps` section to the artifact showing:
+     ```
+     ### Next Steps
+     - Force-approve (bypass remaining reviews): `/forge:approve --force {task_id}`
+     - Increase iteration limit: edit `config.pipelines.{pipeline}.phases[review-code].maxIterations`
+     - Restart from review: `/forge:review-code {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt
    - Read approved PLAN.md
    - Read PROGRESS.md
 
    **Read mode: diff-first.** Read `git diff $(git merge-base HEAD origin/main)..HEAD -- <files-listed-in-PLAN>` first. Read full source files only when the diff context is insufficient to judge a finding (e.g., the change is an inversion of an invariant defined elsewhere). Do not pre-load full source — tool calls earn their tokens.
 
-2. Review:
+3. Review:
    - Verify all plan steps were executed
    - Review code for quality, security, and architecture alignment
    - Verify test evidence in PROGRESS.md is authentic and complete
 
-3. Verdict:
+4. Verdict:
    - Write the code review via forge_artifact:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"code-review", content:"<markdown>" })`
      Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Knowledge Writeback:
+5. Knowledge Writeback:
    - Update stack-checklist.md if new patterns or pitfalls were discovered
 
-5. Finalize:
+6. Finalize:
    - Transitions:
      - **Task mode** — Update status: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `... status code-revision-required` (if Revision Required).
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.code_review.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **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.
 
-6. Emit Summary Sidecar:
+7. Emit Summary Sidecar:
    - Write the review summary via forge_artifact:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-impl-summary", content:"<JSON>" })`
      The JSON shape:

package/dist/forge-payload/meta/workflows/meta-review-plan.md

@@ -37,30 +37,60 @@ deps:
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
    - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
    - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-plan --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
-1. Load Context:
+
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `planned`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:plan must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
+1. Read Review Loop Context:
+   - Check the spawning prompt for a `### Review Loop Context` block.
+   - If present, extract:
+     - `Iteration: N of M` — current attempt number and the configured limit
+     - `Is final iteration: true/false`
+   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
+     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
+   - Include `(iteration N of M)` in the opening line of the `PLAN_REVIEW.md` artifact.
+   - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
+     append a `### Next Steps` section to the artifact showing:
+     ```
+     ### Next Steps
+     - Force-approve (bypass remaining reviews): `/forge:approve --force {task_id}`
+     - Increase iteration limit: edit `config.pipelines.{pipeline}.phases[review-plan].maxIterations`
+     - Restart from review: `/forge:review-plan {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt (source of truth)
    - Read PLAN.md (subject of review)
    - Read stack checklist if available
 
-2. Review:
+3. Review:
    - Evaluate feasibility, completeness, security, architecture alignment, and testing strategy
    - Identify missing edge cases or failure modes
 
-3. Verdict:
+4. Verdict:
    - 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
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Finalize:
+5. Finalize:
    - Transitions:
      - **Task mode** — predecessor must be `planned`.
        - Approved          → `plan-approved`
@@ -70,7 +100,7 @@ deps:
      - **Bug mode** — NO status write. The bug remains `in-progress`. The verdict signal travels through `summaries.review_plan.verdict` (read by `read-verdict.cjs § BUG_PHASE_VERDICT_SOURCE`), not `bug.status`. Writing `bug.status` here violates `meta-fix-bug.md § Iron Laws #2`.
    - **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:
+6. Emit Summary Sidecar:
    - 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

package/dist/forge-payload/meta/workflows/meta-validate.md

@@ -41,38 +41,68 @@ The Supervisor performs a final validation of the implementation against the acc
 
 ```
 
-0. Pre-flight Gate Check:
+0a. Pre-flight Gate Check:
    - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
-   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase validate --task {taskId}`
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase validate --{entity_kind} {record_id}`
    - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
    - Exit 2 (misconfiguration) → print stderr and HALT.
    - Exit 0 → continue.
 
-1. Load Context:
+0b. Pipeline Step Guard (user-invoked state check):
+   - If `--force` is present in the invocation arguments, skip this step entirely.
+   - If `entity_kind == "bug"`, skip this step entirely (bug state is managed by meta-fix-bug.md).
+   - Read current task state:
+     `node "$FORGE_ROOT/tools/store-cli.cjs" read task {record_id} --json`
+   - Extract the `status` field from the JSON output.
+   - Allowed states for this phase: `implemented`, `review-approved`.
+   - If the current status is NOT in the allowed set:
+     Print the following and HALT (do not proceed):
+     `× Task {record_id} is in state '{status}' — /forge:implement must complete first. To run the full pipeline: /forge:run-task {record_id}`
+
+1. Read Review Loop Context:
+   - Check the spawning prompt for a `### Review Loop Context` block.
+   - If present, extract:
+     - `Iteration: N of M` — current attempt number and the configured limit
+     - `Is final iteration: true/false`
+   - If absent (user-invoked, not orchestrated): treat as iteration 1 of M, where M is
+     read from `.forge/config.json` → `maxReviewIterations` (default 3 if field absent).
+   - Include `(iteration N of M)` in the opening line of the `VALIDATION_REPORT.md` artifact.
+   - If this is the final iteration (`N == M`) and the verdict is `Revision Required`,
+     append a `### Next Steps` section to the artifact showing:
+     ```
+     ### Next Steps
+     - Force-approve (bypass remaining reviews): `/forge:approve --force {task_id}`
+     - Increase iteration limit: edit `config.pipelines.{pipeline}.phases[validate].maxIterations`
+     - Restart from validation: `/forge:validate {task_id}`
+     ```
+
+2. Load Context:
    - Read task prompt
    - Read approved PLAN.md
    - Read the implementation
    - Read PROGRESS.md
 
-2. Validation:
+3. Validation:
    - Execute the "Acceptance Criteria" checklist from the plan
    - Verify that all technical constraints (e.g., performance, security) are met
    - Check for any regressions in related functionality
    - 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:
+4. Verdict:
    - 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
+     - See step 1 for iteration header and final-iteration Next Steps requirements.
 
-4. Finalize:
+5. Finalize:
    - Update task status via `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status review-approved` (if Approved) or `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status code-revision-required` (if Revision Required)
    - **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:
+6. Emit Summary Sidecar:
    - 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:

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

@@ -204,11 +204,6 @@
           }
         }
       }
-    },
-    "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

@@ -1,6 +1,6 @@
 {
-  "version": "0.51.4",
-  "generated": "2026-05-26",
+  "version": "1.0.2",
+  "generated": "2026-05-27",
   "note": "Authoritative enum catalog. Source: build-enum-catalog.cjs. Regenerate via node forge/tools/build-manifest.cjs.",
   "enums": {
     "task.status": [
@@ -35,34 +35,30 @@
     ]
   },
   "commandNames": [
-    "forge:sprint-intake",
+    "forge:new-sprint",
     "forge:plan",
     "forge:review-plan",
     "forge:implement",
     "forge:review-code",
     "forge:fix-bug",
-    "forge:sprint-plan",
+    "forge:plan-sprint",
     "forge:run-task",
     "forge:run-sprint",
-    "forge:collate",
-    "forge:retrospective",
+    "forge:retro",
     "forge:approve",
     "forge:commit",
-    "forge:enhance",
-    "forge:quiz-agent",
+    "forge:check-agent",
     "forge:validate",
     "forge:init",
     "forge:health",
-    "forge:regenerate",
+    "forge:rebuild",
     "forge:update",
     "forge:add-task",
     "forge:add-pipeline",
-    "forge:calibrate",
-    "forge:materialize",
     "forge:remove",
     "forge:report-bug",
-    "forge:store-query",
-    "forge:store-repair",
+    "forge:search",
+    "forge:repair",
     "forge:config",
     "forge:ask",
     "forge:store-custodian",

package/dist/forge-payload/schemas/structure-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.51.4",
-  "generatedAt": "2026-05-26T04:50:57.503Z",
+  "version": "1.0.2",
+  "generatedAt": "2026-05-27T08:59:39.257Z",
   "generatedByTool": "build-manifest.cjs",
   "namespaces": {
     "personas": {
@@ -75,20 +75,18 @@
       "prefixed": true,
       "files": [
         "approve.md",
-        "collate.md",
+        "check-agent.md",
         "commit.md",
-        "enhance.md",
         "fix-bug.md",
         "implement.md",
+        "new-sprint.md",
+        "plan-sprint.md",
         "plan.md",
-        "quiz-agent.md",
-        "retrospective.md",
+        "retro.md",
         "review-code.md",
         "review-plan.md",
         "run-sprint.md",
         "run-task.md",
-        "sprint-intake.md",
-        "sprint-plan.md",
         "validate.md"
       ]
     },