@entelligentsia/forgecli 1.0.10 → 1.0.14

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

@@ -55,8 +55,10 @@
         "task-approved",
         "task-validated",
         "task-committed",
+        "sprint-start",
         "sprint-complete",
         "sprint-halted",
+        "task-dispatch",
         "bug-fixed",
 
         "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
@@ -135,6 +137,20 @@
       },
       "then": { "required": ["bugId", "phase", "iteration"] }
     },
+    {
+      "if": { "properties": { "type": { "const": "sprint-start" } }, "required": ["type"] },
+      "then": {
+        "required": [
+          "eventId", "sprintId", "role", "action",
+          "startTimestamp", "endTimestamp", "durationMinutes",
+          "model", "provider",
+          "taskCount"
+        ],
+        "properties": {
+          "taskCount": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
     {
       "if": { "properties": { "type": { "const": "sprint-complete" } }, "required": ["type"] },
       "then": {

package/dist/forge-payload/.schemas/migrations.json

@@ -1,4 +1,240 @@
 {
+  "1.2.13": {
+    "version": "1.2.14",
+    "date": "2026-06-03",
+    "notes": "Correct the set-summary / set-bug-summary call signature in the review and triage workflows. meta-review-implementation.md, meta-review-plan.md, and meta-bug-triage.md documented a forge_store invocation with named entity/id/phase fields (forge_store({ command:'set-summary', entity:'task', id:'{taskId}', phase:'code_review' })) — but the forge_store tool schema accepts only { command, args[] }. Subagents handed the non-existent named form mis-built args, landing the record id in the phase slot; the phase-ownership guard rejected it ('expected summary key code_review'), summaries.code_review was never written, and the orchestrator halted the task as 'verdict missing'. All sites now use the canonical positional form forge_store({ command:'set-summary', args:['{taskId}', 'code_review'] }) with a one-line signature reminder; the _fragments/store-cli-verbs.md cheat-sheet documents the forge_store { command, args[] } shape and the 'id in both slots' failure. Also fixed a forge_store read call in meta-bug-triage.md that used the same invalid named form.",
+    "target": "workflows:review_code workflows:review_plan workflows:bug-triage",
+    "regenerate": [
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild workflows to refresh .forge/workflows/ (review_code.md, review_plan.md, triage.md, and the store-cli-verbs fragment) with the corrected set-summary signature. Prompt-text only — no tool or schema change."
+    ]
+  },
+  "1.2.12": {
+    "version": "1.2.13",
+    "date": "2026-06-03",
+    "notes": "Deterministic post-phase exit guard (FORGE-S26-T19). New parseOutputs() export in parse-gates.cjs handles ```outputs phase=X``` fence blocks with closed grammar (artifact + require directives; unknown throws). New postflight-gate.cjs evaluator runs post-phase; returns { phase, reasonCode, detail, remediation } with new output-missing and output-stub reasonCodes; no LLM in path. forge-cli run-task.ts now calls runPostflightGate() after runForgeSubagent returns and before FSM advance; on UNSATISFIED halts + calls existing runHaltAdvisor. wfl-run-task.js gets a #22 parity-seam comment. meta-plan-task.md and meta-implement.md: prose Tier-2 self-check replaced by declarative outputs blocks + thin pointer reminders.",
+    "target": "tools:parse-gates tools:postflight-gate",
+    "regenerate": ["workflows"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:rebuild to pick up updated meta-workflow changes (meta-plan-task.md, meta-implement.md now include declarative outputs blocks). postflight-gate.cjs is additive — no-op for workflows without outputs blocks."
+    ]
+  },
+  "1.2.11": {
+    "version": "1.2.12",
+    "date": "2026-06-03",
+    "notes": "Rebuild/republish bump — no functional source change from 1.2.11. Cut to ship a fresh plugin manifest + integrity hashes and a corresponding forge-cli 1.0.12 build/install. Carries the 1.2.11 halt-recovery-advisor payload (FORGE-S26-T18) unchanged.",
+    "target": "release:rebuild",
+    "regenerate": [],
+    "breaking": false,
+    "manual": []
+  },
+  "1.2.10": {
+    "version": "1.2.11",
+    "date": "2026-06-03",
+    "notes": "Halt-recovery advisor (FORGE-S26-T18). preflight-gate.cjs now emits structured JSON on stdout on gate failure: { phase, reasonCode, detail, remediation }. reasonCode values: artifact-missing, predecessor-verdict-missing, illegal-status, tool-error. Both LLM orchestrators (meta-orchestrate.md, meta-fix-bug.md) parse and render the structured failure instead of raw stderr. forge-cli run-task and fix-bug upgraded to runPreflightGateWithData() which returns structured failure alongside the PreflightResult enum; on halt, the CLI spawns a read-only halt-recovery advisor subagent on the advisorModel config slot (or getAvailable()[0] fallback). New optional advisorModel field added to forge-cli layered config (L1 global / L2 project). Post-phase self-check guards added to meta-plan-task.md and meta-implement.md (Tier 2) to prevent false complete events when a phase subagent silently fails to write its primary output.",
+    "target": "tools:preflight-gate",
+    "regenerate": ["workflows"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:rebuild to pick up updated meta-workflow changes (meta-orchestrate.md, meta-fix-bug.md, meta-plan-task.md, meta-implement.md). The structured JSON stdout from preflight-gate.cjs is additive — orchestrators that do not parse it still receive human-readable stderr and exit 1."
+    ]
+  },
+  "1.2.9": {
+    "version": "1.2.10",
+    "date": "2026-06-03",
+    "notes": "Fix incomplete .forge/tools/ vendored closure. generate-tools.md and rebuild.md copied tools via `*.cjs` globs only, silently skipping the two `.js` lib helpers (lib/result.js, lib/validate.js) and the top-level list-skills.js. Because store-cli.cjs does a top-level require('./lib/validate.js') and collate.cjs requires './lib/result.js', a freshly vendored .forge/tools/ left store-cli.cjs dead-on-arrival (ENOENT) and broke KB collation. Latent since the vendored-tools model landed; S29 made it fatal by moving tool execution off $FORGE_ROOT/tools/ onto the vendored copy. Both vendoring sites now copy `.cjs` and `.js` (find -maxdepth 1, excludes __tests__/) and record both in the generation manifest. New regression guard tools/__tests__/vendored-tools-closure.test.cjs ties the documented copy extensions to the actual require()-closure.",
+    "target": "tools:vendor-closure",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:rebuild tools to re-vendor .forge/tools/ with the complete closure. Existing projects vendored by v1.2.4–v1.2.9 are missing .forge/tools/lib/result.js, .forge/tools/lib/validate.js, and .forge/tools/list-skills.js — store-cli and KB collation are broken until this re-vendor runs."
+    ]
+  },
+  "1.2.8": {
+    "version": "1.2.9",
+    "date": "2026-06-03",
+    "notes": "Finish the FORGE_ROOT retirement in the workflow/persona layer (vendored-path scope). Remove the vestigial 'Resolve FORGE_ROOT (config.paths.forgeRoot)' preamble bullet from meta-approve/review-plan/review-implementation/validate/commit/plan-task/implement/bug-triage (the gate calls already use node .forge/tools/preflight-gate.cjs). Switch persona identity banners to node .forge/tools/banners.cjs <id> at the generator (build-base-pack.cjs identityBlock) and in the three base-pack-only personas (librarian/orchestrator/product-manager); drop the broken paths.forgeRoot resolution. meta-collate/collator now invoke node .forge/tools/collate.cjs directly. meta-migrate resolves the plugin root from CLAUDE_PLUGIN_ROOT (plugin-side reads of init/base-pack are not vendored). Stale paths.forgeRoot doc references removed from store-cli.spec.md, meta-enhance config_fields, and tool-discipline.md. paths.forgeRoot is intentionally retained as a maintained convenience field (written by check-update.cjs) for skills/commands that resolve the plugin root — those are out of scope for this entry.",
+    "target": "workflows:forge-root-residual-cleanup",
+    "regenerate": ["workflows", "personas"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:rebuild workflows personas to regenerate the updated workflow and persona files. The vendored banners/collate invocations require .forge/tools/ to be present — run /forge:rebuild tools first if it is absent (see the 1.2.7 migration)."
+    ]
+  },
+  "1.2.7": {
+    "version": "1.2.8",
+    "date": "2026-06-03",
+    "notes": "Remove all $FORGE_ROOT references from init/smoke-test.md. Switch tool exec check to node .forge/tools/validate-store.cjs, generation-manifest stamp to node .forge/tools/generation-manifest.cjs, version read to .forge/tools/.forge-tools-version, distribution detection to the distribution field in .forge-tools-version, and remove the forgeRoot field from update-check-cache.json stamp. Smoke-test runs only at init time — existing projects are not affected.",
+    "target": "init:smoke-test",
+    "regenerate": ["init"],
+    "breaking": false,
+    "manual": [
+      "Re-run /forge:init on new projects to pick up the updated smoke-test. Existing projects are unaffected — smoke-test runs only once at init time."
+    ]
+  },
+  "1.2.6": {
+    "version": "1.2.7",
+    "date": "2026-06-02",
+    "notes": "Remove paths.forgeRoot from config.schema.json required[] and properties. forge-preflight.cjs now resolves plugin root via forgeRef-based cache scan (mirrors manage-config.cjs Priority 2) instead of reading config.paths.forgeRoot. manage-config.cjs resolve-forge-root drops Priority 3 (forgeRoot fallback). generate-tools.md drops Step 1 (forgeRoot write). update.md removes forgeRoot refresh from Step 4 config section and fixes tools regenerate category to invoke /forge:rebuild tools instead of running schema refresh inline.",
+    "target": "config:forgeRoot",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:rebuild tools to re-vendor .forge/tools/ on existing projects. Projects that have never run /forge:rebuild tools will have .forge/tools/ absent until this step."
+    ]
+  },
+  "1.2.5": {
+    "version": "1.2.6",
+    "date": "2026-06-02",
+    "notes": "Add vendored-tools integrity and staleness check to /forge:health. Exports checkToolsVersion(projectRoot) from check-structure.cjs: reads .forge/tools/.forge-tools-version marker and paths.forgeRef from config, returns { present, vendoredVersion, activeVersion, stale, reason }. generate-tools.md Step 2c now writes .forge/tools/.forge-tools-version after the tool copy loop. rebuild.md tools category now re-writes the marker after re-copy. health.md gains step 8b (vendored tools presence + staleness check, emitting 〇/△/× with /forge:rebuild tools recommendation). Closes the integrity gap for existing projects that ran /forge:rebuild tools in v1.2.4 without the marker.",
+    "target": "tools:health",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild tools to write .forge/tools/.forge-tools-version. Until this runs, /forge:health will report 'stale (marker absent)' — non-breaking."
+    ]
+  },
+  "1.2.4": {
+    "version": "1.2.5",
+    "date": "2026-06-02",
+    "notes": "Rewrite all ~159 node \"$FORGE_ROOT/tools/X.cjs\" call-sites in meta/workflows/*.md, meta/workflows/_fragments/*.md, and wfl-*.js drivers to use the fixed project-relative form node .forge/tools/X.cjs. Delete the FORGE_ROOT export preamble from all three JS drivers (wfl-run-task.js, wfl-run-sprint.js, wfl-fix-bug.js). Tools are now vendored in .forge/tools/ (added in v1.2.4), so no subagent needs to resolve a plugin root path at runtime. Drift test guard updated: asserts no $FORGE_ROOT remains in any driver source. Existing projects must regenerate workflows and workflows-js to pick up the new paths.",
+    "target": "workflows:*",
+    "regenerate": ["workflows", "workflows-js"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then run /forge:rebuild tools (if not done in v1.2.4 step), then /forge:rebuild workflows and /forge:rebuild workflows-js. Tools must be vendored in .forge/tools/ before running the rewritten workflows."
+    ]
+  },
+  "1.2.3": {
+    "version": "1.2.4",
+    "date": "2026-06-02",
+    "notes": "Add tools vendor category: copy plugin tools/*.cjs + tools/lib/*.cjs into .forge/tools/ at init and rebuild, mirroring the existing schemas copy. Adds tools namespace to structure-manifest.json (via build-manifest.cjs TOOLS_FILES constant), Step 2b to generate-tools.md (init copy), and tools/tools:<filename> category to rebuild.md (verbatim re-copy from $FORGE_ROOT/tools/). check-structure.cjs validateManifest now maps the tools namespace to forgeRoot/tools/ with recursive lib/ enumeration. Foundation for FORGE-S29 call-site rewrite (T02+). No existing call-sites changed in this task.",
+    "target": "tools",
+    "regenerate": ["tools"],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild tools to materialise .forge/tools/."
+    ]
+  },
+  "1.2.2": {
+    "version": "1.2.3",
+    "date": "2026-06-02",
+    "notes": "Harden FORGE_ROOT / .forge/config.json resolution in the packaged JS workflow drivers. A friction trace of a real /fix-bug run showed phase subagents repeatedly probing ../.forge/config.json (the PARENT directory — 5 of 11 subagents) and one invoking `node \"$FORGE_ROOT/tools/preflight-gate.cjs\"` with an unexported $FORGE_ROOT that expands to '' → '/tools/preflight-gate.cjs' (Cannot find module). Root cause: the per-phase subagent prompt preamble said only 'Resolve FORGE_ROOT from .forge/config.json paths.forgeRoot' — no cwd anchor and no instruction to export $FORGE_ROOT, even though every subsequent command used $FORGE_ROOT as a shell variable. Replaced all ~23 preamble sites across wfl-run-task.js / wfl-run-sprint.js / wfl-fix-bug.js with a directive that (a) anchors the config to ./.forge/config.json in the current working directory ('never a parent directory'), (b) tells the agent to EXPORT FORGE_ROOT, and (c) STOPs if $FORGE_ROOT is empty or $FORGE_ROOT/tools is missing. Added a regression guard in workflows-js-drift.test.cjs. Prompt-text only — no orchestration-logic change.",
+    "target": "workflows-js:wfl-run-task",
+    "regenerate": [
+      "workflows-js:wfl-run-task",
+      "workflows-js:wfl-run-sprint",
+      "workflows-js:wfl-fix-bug"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild workflows-js to refresh .claude/workflows/wfl-*.js."
+    ]
+  },
+  "1.2.1": {
+    "version": "1.2.2",
+    "date": "2026-06-02",
+    "notes": "Fix three orchestration-logic edge-case bugs in the packaged JS workflow drivers (found by an adversarial review of the v1.2.1 packaged workflows). (S1) wfl-run-sprint.js re-dispatch passed { taskId, resumeFrom } but wfl:run-task parses only the task id, so resumeFrom was silently dropped — removed the misleading arg; the retry is a clean re-dispatch that resumes from store state. (S2) wfl-run-sprint.js treated a skipped child as non-terminal, so a legitimately `blocked` task (waiting on a dependency) was re-dispatched and then force-escalated; a skipped child is now terminal-acceptable. (F1) wfl-fix-bug.js had no null guard on the finalize dispatch — a skipped/errored finalize fell through and the run was reported bugStatus:'fixed', escalated:false even though collate + the finalize gate never ran; it now escalates on a null finalize while preserving bugStatus:'fixed'. Added text-contract regression guards in workflows-js-drift.test.cjs. Deferred (tracked for a follow-up): revision-counter/eventId attribution (wfl-run-task), count-bucket taxonomy + full-parallel dependency ordering (wfl-run-sprint), and two MINORs in wfl-fix-bug (phase('Pipeline') grouping, escalateBug bugId).",
+    "target": "workflows-js:wfl-run-sprint",
+    "regenerate": [
+      "workflows-js:wfl-run-sprint",
+      "workflows-js:wfl-fix-bug"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild workflows-js to refresh .claude/workflows/wfl-run-sprint.js and wfl-fix-bug.js."
+    ]
+  },
+  "1.2.0": {
+    "version": "1.2.1",
+    "date": "2026-06-02",
+    "notes": "Fix wfl-fix-bug.js invalid meta. The fix-bug JS driver declared its meta with `desc:` and `steps:` instead of `description:` and `phases:`, so the Workflow runtime rejected it ('meta.description must be a non-empty string') and the named-workflow registry silently skipped it — /forge:fix-bug (and any /<prefix>:fix-bug) could never launch wfl:fix-bug. This shipped latent since the driver was authored and was exposed by the v1.2.0 orchestration-prose retirement, which removed the fix_bug.md fallback. Renamed desc->description and steps->phases (adding the Resolve phase) to match wfl-run-task.js / wfl-run-sprint.js. Added a meta-contract regression guard (workflows-js-drift.test.cjs) that asserts every JS driver exposes name + non-empty description + phases.",
+    "target": "workflows-js:wfl-fix-bug",
+    "regenerate": [
+      "workflows-js:wfl-fix-bug"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update to receive the fix, then /forge:rebuild workflows-js to refresh .claude/workflows/wfl-fix-bug.js. /<prefix>:fix-bug will then launch wfl:fix-bug correctly."
+    ]
+  },
+  "1.1.2": {
+    "version": "1.2.0",
+    "date": "2026-06-02",
+    "notes": "Retire LLM orchestration prose. The deterministic JS drivers (.claude/workflows/wfl-run-task.js, wfl-run-sprint.js, wfl-fix-bug.js — category workflows-js) are now the only orchestration truth; /forge:run-task, /forge:run-sprint and /forge:fix-bug already dispatch to them via workflow(wfl:*). The prose orchestrators orchestrate_task.md, run_sprint.md and fix_bug.md are no longer built into the base-pack, no longer generated into .forge/workflows/, and no longer tested (the orchestrators-retired and orchestrator-base-pack-parity drift tests are removed; only the JS drivers are tested). meta-orchestrate.md and meta-fix-bug.md are kept in meta/ as reference specs only. build-base-pack and build-manifest drop the three workflow mappings; workflow-gen-plan.json goes 16->15; the rebuild orchestration-generation step and generate-orchestration.md rulebook are removed. The three retired prose files are added to /forge:update's delete-workflow scan so existing projects have the orphaned .forge/workflows/orchestrate_task.md, run_sprint.md and fix_bug.md removed (rebuild only regenerates and clears manifest entries; it does not delete files on disk).",
+    "target": "workflows-js:wfl-run-task",
+    "regenerate": [
+      "workflows",
+      "workflows-js"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update — it removes the retired orchestrate_task.md / run_sprint.md / fix_bug.md from .forge/workflows/ via its delete-workflow scan (prompts before deleting any you have hand-edited).",
+      "Orchestration now runs through .claude/workflows/wfl-*.js — no action needed for /forge:run-task, /forge:run-sprint, or /forge:fix-bug."
+    ]
+  },
+  "1.1.1": {
+    "version": "1.1.2",
+    "date": "2026-06-02",
+    "notes": "v1.1.2 — Fix collate.cjs resolveTaskDir: when a task store record's `path` field points at a file inside the task directory (e.g. .../FORGE-S22-T04/PLAN.md) rather than the directory itself, Case 1 returned basename('PLAN.md') instead of the task dir. Downstream, collate's existsSync(sprintDir/PLAN.md) check failed and the task's INDEX.md was silently never generated. Case 1 now verifies its candidate is a real directory on disk and otherwise falls through to the filesystem scan (which resolves the dir by taskId). Symptom: 18 task INDEX.md files across FORGE-S22/S23 were missing despite valid store records.",
+    "target": "tools:collate",
+    "regenerate": [
+      "tools:collate"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update to receive the fixed collate tool.",
+      "After update, run /forge:collate (or /forge:rebuild) to regenerate any task INDEX.md files that were skipped."
+    ]
+  },
+  "1.1.0": {
+    "version": "1.1.1",
+    "date": "2026-06-02",
+    "notes": "v1.1.1 — LOW-polish orchestration parity (FORGE-S28-T09). #19: emitSkip() agent helper emits a task-dispatch/action:skip event when the pre-task SKIP_STATUS guard fires, giving the event log a complete accounting of every task. #20: writeback step added to the hardcoded default pipeline prompt in wfl-run-task.js (orchestrate_task.md §3 full default: …approve → writeback → commit, writeback→update_implementation.md). #21: structural-limitation comment documents Progress-Monitor IPC as a host-layer concern (JS driver has no shell access, so the Pi/forge-cli TS layer must open the pipe). #22: BANNER_MAP constants added to both wfl-run-task.js and wfl-run-sprint.js; wfl-run-task phase-start log line now shows the persona label. #23: wfl-run-sprint.js adds an agent step to transition sprint status to 'active' before the wave loop begins, mirroring run_sprint.md Step 1. Also fixes pre-existing forge/package.json test regression (accidental 'dependencies' field removed; placeholder-coverage no-npm test passes).",
+    "target": "workflows-js:wfl-run-task",
+    "regenerate": [
+      "workflows-js:wfl-run-task",
+      "workflows-js:wfl-run-sprint"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update to receive the updated JS workflow orchestrators.",
+      "After update, run /forge:rebuild workflows-js to regenerate .claude/workflows/wfl-*.js in your project."
+    ]
+  },
+  "1.0.11": {
+    "version": "1.1.0",
+    "date": "2026-06-02",
+    "notes": "v1.1.0 — (1) New rebuild/update surface for the JS orchestration workflows: workflows-js is now a first-class /forge:rebuild category (verbatim copy of .claude/workflows/*.js from base-pack, no LLM/placeholder substitution) and a recognised /forge:update regenerate target; build-manifest.cjs declares a workflows-js namespace so /forge:health and check-structure cover .claude/workflows/*.js. Previously these files were materialised only at /forge:init and had no regeneration path. (2) Fix FORGE-BUG-041: wfl-run-task.js emitRetryEvent/mergeSidecar passed schema:{type:'string'} to agent(), an invalid StructuredOutput input_schema (Anthropic requires type:'object'); the subagent could never call StructuredOutput so the workflow threw after the nudge limit — every wfl:run-task task escalated immediately after its plan phase. Dropped the invalid schema option from both calls. With (1) in place, /forge:update now auto-delivers this fix via the workflows-js:wfl-run-task regenerate target.",
+    "target": "workflows-js:wfl-run-task",
+    "regenerate": [
+      "workflows-js:wfl-run-task"
+    ],
+    "breaking": false,
+    "manual": []
+  },
+  "1.0.10": {
+    "version": "1.0.11",
+    "date": "2026-05-31",
+    "notes": "v1.0.11 — Orchestration waste reduction (FORGE-S27 Track A, shipped tasks A1/A3/A4/NH1/NH2). New forge-preflight.cjs aggregates deterministic pre-dispatch glue into a single blob read, eliminating ~20 hand-run round-trips from the orchestrator preamble. New preflight-session.cjs SessionStart hook pre-warms the blob for run-task/fix-bug/run-sprint. banners.cjs gains --quiet flag; orchestrate_task loop uses it so verbose banner output does not accrete in the transcript. meta-orchestrate.md state-ledger compaction discipline: /compact retains the one-line [checkpoint] ledger and sheds raw tool output. meta-fix-bug.md: A1+A3 treatment ported (preflight cross-ref, --quiet flag, spurious cost bullet removed). token-forensics.cjs: message.id-dedup harness for correct through-model token accounting. A2 (context-pack/forge-compress port) remains escalated and is not included in this release.",
+    "target": "tools:forge-preflight",
+    "regenerate": [
+      "tools:forge-preflight",
+      "hooks:preflight-session",
+      "workflows:orchestrate_task",
+      "workflows:fix_bug",
+      "tools:banners",
+      "tools:token-forensics"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update to copy the updated tools and hooks into your project."
+    ]
+  },
   "1.0.9": {
     "version": "1.0.10",
     "date": "2026-05-31",

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

@@ -26,6 +26,7 @@ Assess the health and currency of the project's SDLC knowledge base.
 | **Concepts freshness** | `docs/concepts/*.md` pages older than `forge/meta/store-schema/` updates |
 | **Context pack freshness** | `source_hash` in `.forge/cache/context-pack.json` vs. current hash of `engineering/architecture/*.md` |
 | **Plugin integrity** | Plugin command and agent files modified since last release hash was recorded |
+| **Vendored tools** | `.forge/tools/` present, file set matches structure-manifest, and version marker matches active plugin version |
 
 ## How to run
 
@@ -116,6 +117,32 @@ cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/..."
    If the tool is absent (file not found), skip this check silently.
    Note: custom `paths.*` overrides in `.forge/config.json` are respected by
    check-structure.cjs. Projects using default paths will see no difference.
+8b. Check vendored tools integrity and staleness:
+   ```sh
+   node -e "
+   const { checkToolsVersion } = require('$FORGE_ROOT/tools/check-structure.cjs');
+   const result = checkToolsVersion('$PROJECT_ROOT');
+   console.log(JSON.stringify(result));
+   "
+   ```
+   Also read the structure-manifest to get the expected tools file count and count
+   how many are currently present in `.forge/tools/`:
+   ```sh
+   cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/check-structure.cjs" --path "$PROJECT_ROOT"
+   ```
+   (The tools namespace output from the above `check-structure.cjs` call in step 8 already
+   covers file presence/completeness — use that result here for the tools namespace row.)
+
+   Based on the `checkToolsVersion` result and the tools namespace from step 8:
+   - If `.forge/tools/` is absent or the tools namespace shows missing files:
+     > × Vendored tools — missing or incomplete (N/M files present) — run `/forge:rebuild tools`
+   - If `.forge/tools/` is present and files are complete, but `stale=true`:
+     - If `reason='marker-absent'`:
+       > △ Vendored tools — stale (version marker absent; active: <activeVersion>) — run `/forge:rebuild tools`
+     - If `reason='version-mismatch'`:
+       > △ Vendored tools — stale (vendored: <vendoredVersion>, active: <activeVersion>) — run `/forge:rebuild tools`
+   - If present, complete, and `stale=false`:
+     > 〇 Vendored tools — <N>/<M> files present, version <vendoredVersion>
 9. Check skill gaps: run `node "$FORGE_ROOT/tools/list-skills.js"` to get the live
    installed skill list from `~/.claude/plugins/installed_plugins.json` (source of
    truth — not the config, which can be stale). Read `$FORGE_ROOT/meta/skill-recommendations.md`,
@@ -199,6 +226,7 @@ After step 16, emit a pass/fail summary grid. One row per check category; substi
 | Store integrity                |   〇   |
 | Modified generated files       |   〇   |
 | Generated file structure       |   〇   |
+| Vendored tools                 |   〇   |
 | Plugin integrity               |   〇   |
 | Persona pack freshness         |   △   |
 | Context pack freshness         |   〇   |
@@ -221,6 +249,7 @@ After the summary grid, emit a "Recommended Actions" section only if one or more
 | Store integrity errors         | `/forge:repair`                                        |
 | Modified generated files       | `/forge:rebuild`                                             |
 | Missing generated files        | `/forge:update`                                              |
+| Vendored tools missing / stale | `/forge:rebuild tools`                                       |
 | Plugin integrity modified      | `/forge:update`                                              |
 | Persona pack missing / stale   | `/forge:rebuild`                                             |
 | Context pack missing / stale   | `/forge:rebuild`                                             |

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

@@ -84,6 +84,12 @@ with a colon delimiter (both forms are equivalent).
 /forge:rebuild workflows plan_task          # single workflow file only
 /forge:rebuild workflows:plan_task          # same — colon form (from migration entries)
 /forge:rebuild workflows sprint_plan        # single workflow file only
+/forge:rebuild workflows-js                  # .claude/workflows/ JS orchestration workflows (verbatim copy)
+/forge:rebuild workflows-js wfl-run-task     # single JS workflow file only
+/forge:rebuild workflows-js:wfl-run-task     # same — colon form (from migration entries)
+/forge:rebuild tools                        # .forge/tools/ verbatim re-copy from $FORGE_ROOT/tools/
+/forge:rebuild tools store-cli              # single tool file only (name with or without .cjs)
+/forge:rebuild tools:store-cli              # same — colon form (from migration entries)
 /forge:rebuild commands                     # .claude/commands/ slash command wrappers
 /forge:rebuild templates                    # document templates only
 /forge:rebuild templates PLAN_TEMPLATE      # single template file only
@@ -311,14 +317,14 @@ write, record hash.
      --kb "$(node "$FORGE_ROOT/tools/manage-config.cjs" get paths.engineering 2>/dev/null || echo engineering)" \
      --out .forge/init-context.md --json-out .forge/init-context.json
    ```
-2. Read `$FORGE_ROOT/init/workflow-gen-plan.json` (16-entry fan-out table).
+2. Read `$FORGE_ROOT/init/workflow-gen-plan.json` (15-entry fan-out table).
    Let `M_total` = the entry count.
 
 3. Render the workflows badge, then emit the count:
    ```sh
    node "$FORGE_ROOT/tools/banners.cjs" --badge ember
    ```
-   Then emit: `Generating workflows (<N> atomic + orchestration, parallel)...`
+   Then emit: `Generating workflows (<N> atomic, parallel)...`
 4. Check each file for manual modifications before any clearing:
    ```sh
    node "$FORGE_ROOT/tools/generation-manifest.cjs" check .forge/workflows/{filename}.md
@@ -334,27 +340,143 @@ write, record hash.
    `$FORGE_ROOT/init/generation/generate-workflows.md` as the per-subagent rulebook
    (same fan-out pattern as `/forge:init` Phase 7d). Spawn one per entry.
 7. Collect results. Retry failures once in a single Agent call.
-8. Spawn orchestration subagent:
-   ```
-   Read $FORGE_ROOT/init/generation/generate-orchestration.md and follow it.
-   FORGE_ROOT: {FORGE_ROOT}
-   Input: $FORGE_ROOT/meta/workflows/meta-orchestrate.md + .forge/workflows/
-   Output: .forge/workflows/orchestrate_task.md and .forge/workflows/run_sprint.md
-   ```
-9. **Replay user enhancements** (forge#107 / Approach A):
+
+   > **LLM orchestration retired.** `orchestrate_task` / `run_sprint` / `fix_bug`
+   > are no longer generated. The deterministic JS drivers in
+   > `.claude/workflows/wfl-*.js` (category `workflows-js`) are the only
+   > orchestration truth; `/forge:run-task`, `/forge:run-sprint`, and
+   > `/forge:fix-bug` dispatch to them via `workflow(wfl:*)`. The prose specs
+   > `meta-orchestrate.md` / `meta-fix-bug.md` remain in `meta/` as reference
+   > docs only — neither built into the base-pack nor regenerated here.
+
+8. **Replay user enhancements** (forge#107 / Approach A):
    ```sh
    node "$FORGE_ROOT/tools/manage-versions.cjs" replay --target workflows
    ```
    Walks snapshots; restores enhanced `workflows/<name>.md` files. Later
    snapshots win on collision.
-10. For each written file: record hash `node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/workflows/{filename}.md`
+9. For each written file: record hash `node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/workflows/{filename}.md`
     (this runs AFTER replay so the recorded hash reflects the restored content).
-11. Emit `  〇 workflows — <N> files written`.
+10. Emit `  〇 workflows — <N> files written`.
 
 **Do NOT touch:** `.claude/commands/`, `.forge/config.json`, or any knowledge base file.
 
 ---
 
+## Category: `workflows-js` — verbatim copy (full or single file)
+
+Re-materialise the JS orchestration workflows in `.claude/workflows/` from the
+plugin base-pack. Unlike the `workflows` category (LLM-generated `.forge/`
+markdown with placeholder substitution and KB enrichment), the
+`workflows-js` files are **deterministic verbatim copies** from
+`$FORGE_ROOT/init/base-pack/workflows-js/` — no LLM, no placeholder
+substitution, no enrichment. The output is byte-identical to the base-pack
+source (enforced by `workflows-js-drift.test.cjs`), so this category mirrors
+the `workflows:_fragments` copy pattern, not the generation pattern.
+
+Render a badge, then proceed:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --badge ember
+```
+
+**If a sub-target is provided** (e.g. `/forge:rebuild workflows-js wfl-run-task`
+or the colon form `workflows-js:wfl-run-task`), copy only the single file. The
+sub-target may be given with or without the `.js` extension; normalise to
+`<sub-target>.js`.
+
+1. Verify `$FORGE_ROOT/init/base-pack/workflows-js/<sub-target>.js` exists. If
+   not, list the available files and exit cleanly.
+2. Ensure `.claude/workflows/` exists (create if absent).
+3. Copy verbatim (no substitution) to `.claude/workflows/<sub-target>.js`.
+4. Record a manifest hash:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record .claude/workflows/<sub-target>.js
+   ```
+5. Emit `  〇 workflows-js:<sub-target> — copied`.
+
+**If no sub-target** — full copy, directory fan-out:
+
+1. Enumerate all `.js` files in `$FORGE_ROOT/init/base-pack/workflows-js/`.
+   Let `N` = the count.
+2. Emit: `Copying workflows-js (<N> files)...`
+3. Ensure `.claude/workflows/` exists (create if absent).
+4. For each file, copy verbatim to `.claude/workflows/<filename>`, then record
+   a manifest hash:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record .claude/workflows/<filename>
+   ```
+5. Emit `  〇 workflows-js — <N> files copied`.
+
+> **Note:** Only the base-pack-sourced JS workflows (`wfl-*.js`) are written.
+> Custom or project-specific files in `.claude/workflows/` are never
+> overwritten or deleted. Verify with `ls .claude/workflows/`.
+
+---
+
+## Category: `tools` — verbatim copy (full or single file)
+
+Re-materialise the vendored plugin tools in `.forge/tools/` from the installed
+plugin. Unlike workflow and persona categories (LLM-generated with placeholder
+substitution), tools files are **deterministic verbatim copies** from
+`$FORGE_ROOT/tools/` — no LLM, no substitution, no enrichment. The output is
+byte-identical to the plugin source.
+
+**If a sub-target is provided** (e.g. `/forge:rebuild tools store-cli`
+or the colon form `tools:store-cli`), copy only the single file. The sub-target
+may be given with or without the `.cjs` extension; normalise to `<sub-target>.cjs`.
+Sub-targets in the `lib/` namespace may be specified with the `lib/` prefix
+(e.g. `tools:lib/schema-loader` or `tools:lib/schema-loader.cjs`).
+
+**Single-file steps:**
+
+1. Resolve the source path: if the sub-target starts with `lib/`, look in
+   `$FORGE_ROOT/tools/lib/<name>.cjs`; otherwise look in `$FORGE_ROOT/tools/<name>.cjs`.
+   If the source does not exist, list the available files and exit cleanly.
+2. Ensure the target directory exists (`.forge/tools/` or `.forge/tools/lib/`).
+3. Copy verbatim to the resolved `.forge/tools/` path.
+4. Record a manifest hash:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/tools/<sub-target>.cjs
+   ```
+5. Emit `  〇 tools:<sub-target> — copied`.
+
+**If no sub-target** — full re-copy, directory fan-out:
+
+1. Enumerate all `*.cjs` **and `*.js`** files in `$FORGE_ROOT/tools/` (top-level
+   only, exclude `*.test.cjs`/`*.test.js`). Let `N_top` = the count.
+   Enumerate all `*.cjs` **and `*.js`** files in `$FORGE_ROOT/tools/lib/` (exclude
+   `*.test.cjs`/`*.test.js`). Let `N_lib` = the count.
+   Both extensions are required: e.g. `store-cli.cjs` loads `lib/validate.js` and
+   `collate.cjs` loads `lib/result.js`; a `.cjs`-only copy breaks them.
+2. Emit: `Copying tools (<N_top> tool files + <N_lib> lib files)...`
+3. Ensure `.forge/tools/` and `.forge/tools/lib/` exist (create if absent).
+4. For each top-level file, copy verbatim to `.forge/tools/<filename>`, then
+   record a manifest hash:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/tools/<filename>
+   ```
+5. For each lib file, copy verbatim to `.forge/tools/lib/<filename>`, then
+   record a manifest hash:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/tools/lib/<filename>
+   ```
+6. Write (or overwrite) the version marker so `/forge:health` can detect staleness:
+   ```sh
+   ACTIVE_VERSION=$(node -e "console.log(require('$FORGE_ROOT/.claude-plugin/plugin.json').version)")
+   node -e "
+   const fs = require('fs');
+   fs.writeFileSync('.forge/tools/.forge-tools-version', JSON.stringify({ version: '${ACTIVE_VERSION}' }) + '\n');
+   "
+   ```
+7. Emit `  〇 tools — <N_top + N_lib> files copied`.
+
+> **Note:** This is a full re-copy of the plugin tools at the installed
+> `$FORGE_ROOT` version. Use `/forge:rebuild tools` after `/forge:update` to
+> refresh `.forge/tools/` to the new plugin version.
+
+---
+
 ## Category: `commands` — full rebuild
 
 Re-generate `.claude/commands/` slash command wrappers from the current
@@ -549,7 +671,7 @@ are not yet represented in review checklist items.
 
 ## Default (no argument)
 
-Run all five categories respecting dependencies — with maximum parallelism:
+Run all categories respecting dependencies — with maximum parallelism:
 
 1. **Build brief** (once, synchronous):
    ```sh
@@ -572,8 +694,14 @@ Run all five categories respecting dependencies — with maximum parallelism:
    Spawn orchestration and commands subagents in a **SINGLE Agent tool message**.
    Wait for both.
 
-This runs in 4 serial steps instead of 5 sequential category passes, with all
-fan-outs parallelised within each step.
+5. **workflows-js** (deterministic verbatim copy — no LLM, independent):
+   Run the `workflows-js` category (full copy) as described above: copy every
+   `.js` file from `$FORGE_ROOT/init/base-pack/workflows-js/` into
+   `.claude/workflows/` and record manifest hashes. This step has no
+   dependencies and can run alongside step 4.
+
+This runs in a handful of serial steps instead of sequential per-category
+passes, with all fan-outs parallelised within each step.
 
 ## Flag: `--enrich`