@entelligentsia/forgecli 1.0.21 → 1.0.36

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

@@ -1,4 +1,71 @@
 {
+  "1.2.21": {
+    "version": "1.3.0",
+    "date": "2026-06-07",
+    "notes": "CLI-first bootstrap: /forge:init now dispatches workflow('wfl:init') — the dynamic JS driver added in S31-T04. init.md command wrapper hoists interactive prompts (KB folder, CLAUDE.md offer, marketplace-skills offer). Phase-1 and Phase-4 rulebooks annotated with orchestrator-owned step markers. sdlc-init.md reduced to a spec pointer. New base-pack/commands/init.md project-local wrapper authored. No change to installed projects (init.md is a plugin command, not a materialized base-pack command).",
+    "target": "commands:init,init:wfl-init,init:phases:phase-1-collect,init:phases:phase-4-register,init:sdlc-init,init:base-pack:commands:init",
+    "regenerate": [],
+    "breaking": false,
+    "manual": [
+      "No action required for existing initialized projects. New inits use the dynamic wfl:init driver. The Workflow tool is required; upgrade Claude Code if not available."
+    ]
+  },
+  "1.2.20": {
+    "version": "1.2.21",
+    "date": "2026-06-06",
+    "notes": "commit-task.cjs hardening from its first live firing (HELLO-BUG-002 transcript analysis, forge-engineering#40). (1) Gitignored staging paths are pre-filtered with git check-ignore and warn-skipped — previously one ignored path aborted the all-or-nothing git add and the agent retried the identical command. (2) A clean staging set is now a legitimate no-op SUCCESS: the tool seals the record's terminal status and returns {ok:true, committed:false, reason:nothing-to-commit} — a bug whose fix is already at HEAD ends fixed without improvised manual transitions. Result JSON gains an explicit committed flag. meta-commit.md: forge_commit named tool is the primary surface on forgecli (typed args — no shell-quoting of the commit message); bash form stays as the Claude Code fallback; no-op outcome documented as success.",
+    "target": "tools:commit-task,workflows:commit_task",
+    "regenerate": [
+      "tools",
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild tools workflows to refresh .forge/tools/commit-task.cjs and .forge/workflows/commit_task.md."
+    ]
+  },
+  "1.2.19": {
+    "version": "1.2.20",
+    "date": "2026-06-06",
+    "notes": "Deterministic commit choreography (forge-engineering#40). The commit phase was the most expensive phase of the pipeline (15-31% of run input tokens) because an LLM re-derived deterministic choreography turn-by-turn. New tools/commit-task.cjs owns the whole sequence — preflight gate, status precondition, staging-set derivation (record artifact dir + implementation file provenance), commit-boundary guard (aborts on a pre-populated index), git commit, terminal status transition (task→committed / bug→fixed) — with --dry-run, argv-array spawns, and operator-gated --force. The implement phase now records files_changed provenance in IMPLEMENTATION-SUMMARY.json (new optional PHASE_SUMMARY_SCHEMA key, max 100 paths) so commit never re-derives the change surface from git. meta-commit.md rewritten: agent inspects once (git diff --stat), crafts the message, calls the tool once; explicit no-summary contract (commit is not in VALID_SUMMARY_PHASES — the previous prompt commanded writing a SUMMARY that the schema rejects, sending agents on an unwinnable format hunt plus 3 write-verification retries); batched-inspection rule; commit-early/reset/redo loop forbidden.",
+    "target": "tools:commit-task,tools:store-cli,workflows:commit_task,workflows:implement_plan",
+    "regenerate": [
+      "tools",
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild tools workflows to vendor .forge/tools/commit-task.cjs and refresh .forge/workflows/commit_task.md + implement_plan.md. Until the rebuild, the regenerated commit workflow will reference a tool that is not yet vendored and will halt loudly (by design)."
+    ]
+  },
+  "1.2.18": {
+    "version": "1.2.19",
+    "date": "2026-06-06",
+    "notes": "Event-type discipline in the JS workflow drivers (forge-engineering#39 Phase 3). wfl-run-task.js and wfl-fix-bug.js now carry TASK_TYPE_TOKENS / BUG_TYPE_TOKENS maps (verbatim ports of _fragments/event-vocabulary.md) and inject explicit per-phase type guidance into the subagent emit instructions: start events MUST NOT carry a type field, complete events set the exact pass/fail token for the phase, and copying the action value (start/complete) into type is explicitly forbidden — that guess-leak was the source of the schema-rejected type:start/type:complete store residue. Also fixes wfl-run-task emitSkip(): the skip event emitted iteration 0, violating the schema's minimum of 1, so every pre-task skip event was silently rejected; now 1.",
+    "target": "workflows-js:wfl-run-task,workflows-js:wfl-fix-bug",
+    "regenerate": [
+      "workflows-js"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild to regenerate .claude/workflows/wfl-run-task.js and wfl-fix-bug.js from the base-pack. Prompt/instruction text + one literal fix — no schema or tool change."
+    ]
+  },
+  "1.2.17": {
+    "version": "1.2.18",
+    "date": "2026-06-06",
+    "notes": "Event-type vocabulary gets a spec owner (forge-engineering#39). New canonical fragment _fragments/event-vocabulary.md defines the phase→type token tables for task/bug/sprint events; schemas/event.schema.json now mirrors it: adds the bug-pipeline fail tokens fix-revision-requested (approve) and bug-commit-failed (commit) that forge-cli already emits (previously rejected by the enum — events and their token telemetry were silently dropped), adds bug-skipped (pre-loop skip; requires bugId, no phase/iteration), and retires bug-fixed (defined, emitted by nothing, zero store occurrences). The wfl-fix-bug.js base-pack driver's skip emit was triple-broken against the schema (underscore bug_skipped token, missing required eventId/model/provider, undeclared reason key) — now emits a valid bug-skipped event with the skip reason in notes and model/provider \"n/a\". meta-fix-bug.md and meta-orchestrate.md reference the vocabulary fragment; emitted tokens MUST come from its tables.",
+    "target": "schemas:event,fragments:event-vocabulary,fragments:event-emission-schema,workflows:fix_bug,workflows:orchestrate_task,workflows-js:wfl-fix-bug",
+    "regenerate": [
+      "schemas",
+      "workflows",
+      "workflows-js"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update, then /forge:rebuild schemas workflows to refresh .forge/schemas/event.schema.json, .forge/workflows/ (fix_bug.md, orchestrate_task.md, _fragments/), and the regenerated .claude/workflows/wfl-fix-bug.js. Projects with the legacy invalid store events (type start/complete/feature_implemented) can clear them via /forge:repair — strip the invalid type field (untyped events are valid)."
+    ]
+  },
   "1.2.16": {
     "version": "1.2.17",
     "date": "2026-06-04",
@@ -2857,5 +2924,79 @@
     ],
     "breaking": false,
     "manual": []
+  },
+  "1.3.0": {
+    "version": "1.4.0",
+    "date": "2026-06-07",
+    "notes": "Fixed /forge:* command namespace (CLI-first redesign). Project-prefix command namespaces (/acme:*, /hello:*) are retired: getCommandsSubdir() now returns 'forge' unconditionally, base-pack command templates carry literal /forge: headings ({{PREFIX}} removed), and substitute-placeholders materializes commands to .claude/commands/forge/. All command .md files (plugin commands/ + base-pack commands/) resolve FORGE_ROOT with a vendored fallback: ${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge} — full parity for plugin-less projects bootstrapped by '4ge init claude' where tools/schemas/hooks are vendored under .forge/. Rulebooks (generate-commands, phase-3-materialize, phase-1-collect, meta-migrate, migrate_structural) updated to the fixed namespace.",
+    "target": "tools:lib:paths,tools:substitute-placeholders,commands:*,init:base-pack:commands:*,init:generation:generate-commands,init:phases:phase-1-collect,init:phases:phase-3-materialize,meta:workflows:meta-migrate,init:base-pack:workflows:migrate_structural",
+    "regenerate": [
+      "commands"
+    ],
+    "breaking": true,
+    "manual": [
+      "Existing projects with prefix-namespaced commands (.claude/commands/<prefix>/): re-run materialization (or /forge:rebuild) to produce .claude/commands/forge/, then delete the old .claude/commands/<prefix>/ directory. The old commands keep working until removed but will not receive updates."
+    ]
+  },
+  "1.4.0": {
+    "version": "1.4.1",
+    "date": "2026-06-07",
+    "notes": "wfl-init.js Workflow-harness parse fix: the driver shipped wrapped in 'export default async function wflInit(args)' — the Workflow tool permits exactly one export (the meta literal) and evaluates the rest as an async function body, so every /forge:init dispatch failed at launch with \"SyntaxError: Unexpected keyword 'export'\". Body now runs at top level reading the global args. New regression test (wfl-drivers-parse.test.cjs) parses all four base-pack drivers exactly the way the harness does.",
+    "target": "init:base-pack:workflows-js:wfl-init",
+    "regenerate": [
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": [
+      "Projects bootstrapped with the broken driver: re-run '4ge init claude .' (idempotent repair overwrites .claude/workflows/wfl-init.js)."
+    ]
+  },
+  "1.4.1": {
+    "version": "1.4.2",
+    "date": "2026-06-07",
+    "notes": "wfl-init.js Workflow-API rewrite (forge#112): the driver mis-used the harness API four ways — phase(title, callback) callbacks were silently discarded so init ran 0 agents while reporting fabricated ok:true; parallel() received promises instead of thunks; agent() had model as first arg instead of opts.model; structured results lacked opts.schema. Phase bodies now run inline at top level, fan-outs use thunks, all agents use agent(prompt, {model, label, phase, schema}), and the report reflects real phase results. Rulebook reads use vendored .forge/init/... paths with direct-analysis fallback. Contract enforced by wfl-drivers-parse.test.cjs (phase-callback, thunk, arg-order, referenced-rulebook-exists gates).",
+    "target": "init:base-pack:workflows-js:wfl-init",
+    "regenerate": [
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": [
+      "Projects bootstrapped with the broken driver: re-run '4ge init claude .' (idempotent repair overwrites .claude/workflows/wfl-init.js)."
+    ]
+  },
+  "1.4.2": {
+    "version": "1.4.3",
+    "date": "2026-06-07",
+    "notes": "wfl-init.js verify-phase CLI alignment (forge#112 follow-up): the Phase 2 verify prompts invoked 'verify-phase.cjs --phase 2' bare, but the tool requires '--phase 2 --kb-path <path>' (exit 2 without it). Both Phase 2 invocations now pass --kb-path \"${kbFolder}\". New contract gates in wfl-drivers-parse.test.cjs assert every driver verify-phase invocation uses a supported phase (1-3) and that --phase 2 always carries --kb-path.",
+    "target": "init:base-pack:workflows-js:wfl-init",
+    "regenerate": [
+      "workflows"
+    ],
+    "breaking": false,
+    "manual": []
+  },
+  "1.4.3": {
+    "version": "1.4.4",
+    "date": "2026-06-07",
+    "notes": "First full CLI-first field-test gap fixes (config drift + manifest scope): (1) phase-1-collect.md no longer instructs the config-writer to derive paths.commands from the project prefix — it is ALWAYS '.claude/commands/forge' (the prefix-derived instruction survived the 1.4.0 namespace redesign and produced paths.commands='.claude/commands/git' -> check-structure 0/14). (2) generate-tools.md gains an explicit step writing paths.forgeRoot='.forge' — without it the register agent improvised an absolute npm-global payload path, which breaks on version upgrades and nvm switches. (3) build-manifest.cjs excludes 10 plugin-development tools from the tools namespace — the structure manifest describes instances, and expecting dev tools produced false 49/59 'missing tools' gaps in /forge:health.",
+    "target": "init:phases:phase-1-collect,init:generation:generate-tools,tools:build-manifest,schemas:structure-manifest",
+    "regenerate": [],
+    "breaking": false,
+    "manual": [
+      "Existing CLI-first projects with drifted config: run node .forge/tools/manage-config.cjs set paths.commands '\".claude/commands/forge\"' and set paths.forgeRoot '\".forge\"', then re-run '4ge init claude .' to refresh .forge/schemas/structure-manifest.json."
+    ]
+  },
+  "1.4.4": {
+    "version": "1.4.5",
+    "date": "2026-06-09",
+    "notes": "Collate-workflow KB-link refresh is orchestrator-owned under forge-cli. collator_agent.md (base-pack) + meta-collate.md (meta source) no longer instruct the collator subagent to invoke the forge:refresh-kb-links Skill tool: forge-cli subagents run via the Pi runtime, which has no Skill tool, so the instruction triggered a multi-call bash-probe loop before falling back. The Claude Code TUI standalone path still uses the Skill tool; under forge-cli the run-task orchestrator owns the KB refresh (runRefreshKbLinks) after the writeback phase. Prose-only change to the generated collate workflow.",
+    "target": "workflows:collator_agent,meta:meta-collate",
+    "regenerate": [
+      "workflows:collator_agent"
+    ],
+    "breaking": false,
+    "manual": [
+      "Run /forge:update (or /forge:rebuild) to regenerate the collate workflow (collator_agent.md) with the orchestrator-owned KB-refresh guidance."
+    ]
   }
 }

package/dist/forge-payload/commands/add-pipeline.md

@@ -10,7 +10,7 @@ description: Conversational pipeline manager — add, customize, view, or remove
 ## Setup
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Read project config values:

package/dist/forge-payload/commands/add-task.md

@@ -10,7 +10,7 @@ Add a task to an existing sprint without re-running the full sprint planner.
 ## Setup
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Read project config values:
@@ -256,8 +256,8 @@ Display a summary (substitute `{PREFIX}` with `PROJECT_PREFIX.toLowerCase()`):
    Pipeline:   {PIPELINE}
 
 ── Next steps:
-   1. Run /{PREFIX}:run-task {TASK_ID} to execute the full pipeline.
-   2. Or run /{PREFIX}:plan {TASK_ID} to plan it first.
+   1. Run /forge:run-task {TASK_ID} to execute the full pipeline.
+   2. Or run /forge:plan {TASK_ID} to plan it first.
 ```
 
 ---

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

@@ -10,7 +10,7 @@ Single conversational entry point for all Forge intent.
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 ## Open with oracle banner

package/dist/forge-payload/commands/check-agent.md

@@ -12,7 +12,7 @@ release engineering, significant refactors).
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 ## Arguments

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

@@ -11,7 +11,7 @@ commands (e.g. `paths.forgeRoot` is refreshed by `/forge:update`).
 ## Locate the Forge plugin
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Read `.forge/config.json`. If it does not exist, stop and emit:

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

@@ -32,7 +32,7 @@ Assess the health and currency of the project's SDLC knowledge base.
 
 First, resolve the plugin root and project root:
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Open the run with the oracle hero + subtitle:

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

@@ -13,7 +13,7 @@ AI software development lifecycle for the codebase in the current working direct
 Set `$FORGE_ROOT` to the plugin root provided by Claude Code:
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 `$FORGE_ROOT` is the directory containing `meta/`, `init/`, `hooks/`, and `commands/`.
@@ -136,13 +136,68 @@ Any other input (including 0, 5+, or non-numeric text) re-prompts with the same
 If a `$ARGUMENTS` phase number is provided (e.g. `3`), skip the pre-flight
 table and go straight to the specified phase.
 
-Read `$FORGE_ROOT/init/sdlc-init.md` — that document is your complete orchestration.
-Follow it exactly. It defines 4 phases:
+Before dispatching, gather the following values interactively:
 
-1. **Collect** — 5 parallel discovery prompts, KB folder prompt, `config.json`
-2. **Discover** — KB doc fan-out + inline `project-context.json` construction
-3. **Materialize** — `substitute-placeholders.cjs` + `build-overlay.cjs` smoke test
-4. **Register** — tools, versioning, manifest, cache, store seed, Tomoshibi, `.gitignore` update (unconditional), CLAUDE.md KB-link offer
+**KB Folder Prompt:**
+
+```
+What should your engineering knowledge base folder be named?
+  Default: engineering
+
+KB folder name [engineering]: ___
+```
+
+If the user provides a custom name, write it:
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" set paths.engineering "{name}"
+```
+Set `kbFolder` to the chosen name (default: `"engineering"`).
+
+**CLAUDE.md Offer:**
+
+```sh
+ls CLAUDE.md AGENTS.md CLAUDE.local.md .cursorrules 2>/dev/null
+```
+
+If NONE of those files exist, ask:
+```
+No CLAUDE.md / AGENTS.md found. Create a minimal CLAUDE.md with Forge KB links? [Y/n]: ___
+```
+Set `createClaudeMd = true` (default Y) or `false`.
+If any file exists, set `createClaudeMd = false` (skip silently).
+
+**Timestamp:** `isoTimestamp = new Date().toISOString()`
+
+Execute the workflow:
+
+```
+workflow('wfl:init', {
+  forgeRoot: FORGE_ROOT,
+  kbFolder,
+  startPhase,
+  createClaudeMd,
+  isoTimestamp,
+  rawArguments: $ARGUMENTS
+})
+```
+
+If the Workflow tool is unavailable, halt immediately with the following message:
+
+> The Workflow tool is required to run `/forge:init`. This Claude Code build does not
+> support the Workflow tool. Upgrade Claude Code and try again.
+>
+> (Alternatively, run `4ge init claude .` again to re-scaffold, then upgrade Claude Code.)
+
+Do NOT fall back to reading `sdlc-init.md` or any other document — Iron Law 5.
+
+**Post-workflow:** on `result.ok === true`, render closing banners (use `banners.cjs forge`
+and `--subtitle "灯 SDLC ready…"`), emit the welcome block, present the marketplace-skills
+offer from `result.skillMatches` (install accepted skills via `manage-config.cjs set
+installedSkills.{id} true`), invoke `forge:refresh-kb-links` via the Skill tool, and
+print the final report (KB doc count, workflow count, command count, accepted/skipped skills).
+
+On `result.ok === false`: surface `result.failure` as formatted JSON and offer
+`/forge:report-bug`.
 
 The current working directory is the target project. All generated artifacts go into
 `.forge/`, the configured KB folder (default: `engineering/`), and `.claude/commands/`

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

@@ -10,7 +10,7 @@ Re-run generation phases using the current state of the project. Use `--enrich`
 ## Locate the Forge plugin
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Read `.forge/config.json`. If it does not exist, stop and tell the user to run
@@ -18,7 +18,7 @@ Read `.forge/config.json`. If it does not exist, stop and tell the user to run
 
 Resolve tools from the plugin:
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 All tool invocations in this command use `node "$FORGE_ROOT/tools/<tool>.cjs"`.
@@ -709,7 +709,7 @@ When `$ARGUMENTS` contains `--enrich`, run the enhancement workflow instead of r
 This is the v1.0 replacement for the removed `/forge:enhance` command.
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 1. Check that `$FORGE_ROOT/meta/workflows/meta-enhance.md` exists. If absent:

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

@@ -21,7 +21,7 @@ nothing is deleted until you confirm explicitly.
 Read the configured KB path and project prefix from config:
 
 ```sh
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 KB_PATH: !`node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}"`
 PREFIX: !`node -e "try{console.log(require('./.forge/config.json').project.prefix.toLowerCase())}catch{console.log('')}"`
 ```

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

@@ -19,7 +19,7 @@ $ARGUMENTS
 
 1. Resolve the plugin root:
    ```
-   FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+   FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
    ```
 
 2. Run the four-phase repair workflow below. If `--dry-run` is in `$ARGUMENTS`,

package/dist/forge-payload/commands/report-bug.md

@@ -30,7 +30,7 @@ gh is not installed or not authenticated.
 Collect the following in parallel:
 
 ```
-forge_version:  !`cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/'`
+forge_version:  !`cat "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}/.claude-plugin/plugin.json" 2>/dev/null | grep '"version"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/'`
 node_version:   !`node --version 2>/dev/null || echo "N/A"`
 os_info:        !`uname -srm 2>/dev/null || echo "N/A"`
 forge_config:   !`cat ".forge/config.json" 2>/dev/null | head -30 || echo "No .forge/config.json found"`

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

@@ -12,7 +12,7 @@ Quick overview of the current sprint and task state.
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 ## Locate project config

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

@@ -12,7 +12,7 @@ project's generated artifacts.
 ## Locate plugin root
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 Detect install mode:
@@ -442,7 +442,7 @@ install changes the cache path (e.g. `…/cache/forge/forge/0.9.6/` →
 this command is stale.
 
 ```sh
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 If the re-derived `FORGE_ROOT` differs from the original value, print:
@@ -916,7 +916,7 @@ consolidated prompt. **Nothing is written without the user saying yes.**
 ### 5a — Locate tools
 
 ```
-FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT:-$(pwd)/.forge}"`
 ```
 
 All tools are invoked directly from the plugin:

package/dist/forge-payload/hooks/lib/common.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * hooks/lib/common.cjs — Shared primitives for Forge hooks
+ *
+ * Provides four canonical exports used across hook files:
+ *   - resolveForgePaths()       (H-1a) — read .forge/config.json and derive key paths
+ *   - readStdinJson(cb, stdin)  (H-1b) — async stdin → JSON parsing (callback pattern)
+ *   - formatHookOutput(name, p) (H-1c) — build hookSpecificOutput JSON envelope
+ *   - FORGE_COMMAND_PATTERNS    (H-1d) — canonical forge-command RegExp array
+ *
+ * IMPORTANT: This file is intentionally excluded from the forge-cli payload
+ * (build-payload.cjs copies only hooks/*.js, not hooks/lib/). Therefore:
+ *   - Only .cjs hooks (post-init.cjs, post-sprint.cjs) may require this file.
+ *   - .js hooks (triage-error.js, forge-permissions.js) retain inline copies
+ *     of the patterns they need. Those inline copies carry comments pointing
+ *     here as the canonical source. Keep both in sync when patterns change.
+ *
+ * Closes findings: H-1a, H-1b, H-1c, H-1d (FORGE-S25-T08)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// H-1a: resolveForgePaths
+// ---------------------------------------------------------------------------
+
+/**
+ * Read .forge/config.json from the current working directory and derive the
+ * key filesystem paths used by hooks.
+ *
+ * Merged from the two identical implementations in post-init.cjs and
+ * post-sprint.cjs. The post-init version included structureVersionsPath;
+ * this function always returns all fields — callers that don't need a field
+ * simply ignore it.
+ *
+ * @returns {{ forgeDir: string, eventsRoot: string, cacheDir: string,
+ *             forgeRoot: string|null, structureVersionsPath: string } | null}
+ *   Returns null if .forge/config.json is missing or unparseable.
+ */
+function resolveForgePaths() {
+  const cfgPath = path.join(process.cwd(), '.forge', 'config.json');
+  if (!fs.existsSync(cfgPath)) return null;
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); } catch (_) { return null; }
+  const forgeDir = path.dirname(cfgPath);
+  return {
+    forgeDir,
+    eventsRoot: path.join(forgeDir, 'store', 'events'),
+    structureVersionsPath: path.join(forgeDir, 'structure-versions.json'),
+    cacheDir: path.join(forgeDir, 'cache'),
+    forgeRoot: (cfg.paths && cfg.paths.forgeRoot) || null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// H-1b: readStdinJson
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all data from a readable stream (defaulting to process.stdin), parse
+ * as JSON, and invoke the callback with the result.
+ *
+ * Merges the async stdin reading pattern used by triage-error.js and
+ * forge-permissions.js. Note: .js hooks retain inline copies of this
+ * pattern to avoid a module-scope require on hooks/lib/ (forge-cli bundle
+ * gap — see file header). This function is provided for .cjs hook consumers
+ * and for future use when the .js extension is migrated in T14.
+ *
+ * @param {function(object|null): void} callback
+ *   Called with the parsed object, or null if input is empty or malformed.
+ * @param {NodeJS.ReadableStream} [stdin]
+ *   Readable stream to consume. Defaults to process.stdin.
+ */
+function readStdinJson(callback, stdin) {
+  const stream = stdin || process.stdin;
+  if (stream.setEncoding) stream.setEncoding('utf8');
+  let raw = '';
+  stream.on('data', chunk => { raw += chunk; });
+  stream.on('end', () => {
+    if (!raw) { callback(null); return; }
+    try {
+      callback(JSON.parse(raw));
+    } catch (_) {
+      callback(null);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// H-1c: formatHookOutput
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Claude Code hook stdout envelope as a JSON string.
+ *
+ * Claude Code hook protocol: hooks write a JSON object to stdout where the
+ * top-level key is `hookSpecificOutput` containing `hookEventName` plus any
+ * additional fields from payload.
+ *
+ * @param {string} hookEventName - e.g. 'PostToolUse', 'SessionStart'
+ * @param {object} payload - additional fields to include in hookSpecificOutput
+ * @returns {string} JSON string ready for process.stdout.write
+ */
+function formatHookOutput(hookEventName, payload) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName,
+      ...payload,
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// H-1d: FORGE_COMMAND_PATTERNS
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical array of RegExp patterns that identify forge-related commands.
+ *
+ * @catalogSync forge/schemas/enum-catalog.json#commandNames (FORGE-S25-T26)
+ *
+ * Build-time drift detection: forge/tools/__tests__/build-enum-catalog.test.cjs
+ * verifies that every `forge:*` entry in enum-catalog.json commandNames has at
+ * least one matching regex here. Run `node --test forge/tools/__tests__/*.test.cjs`
+ * to check. Drift will cause the drift-detection test to fail.
+ *
+ * Runtime: this array is the single source of truth for forge command recognition.
+ * hooks/triage-error.cjs and hooks/forge-permissions.cjs maintain inline copies
+ * of subsets; those files cannot require() this module due to the forge-cli bundle
+ * gap (build-payload.cjs bundles hooks/*.cjs but excludes hooks/lib/).
+ *
+ * When adding a new forge command: update this array, the inline copies in
+ * triage-error.cjs and forge-permissions.cjs, AND build-enum-catalog.cjs COMMAND_NAMES.
+ */
+const FORGE_COMMAND_PATTERNS = [
+  /manage-config/,
+  /\.forge\//,
+  /CLAUDE_PLUGIN_ROOT/,
+  /FORGE_ROOT/,
+  /MANAGE_CONFIG/,
+  /engineering\/tools\//,
+  /forge:init/,
+  /forge:health/,
+  /forge:rebuild/,
+  /forge:update/,
+  /forge:add-pipeline/,
+  /forge:add-task/,
+  /forge:plan/,
+  /forge:implement/,
+  /forge:approve/,
+  /forge:commit/,
+  /forge:review/,
+  /forge:new-sprint/,
+  /forge:plan-sprint/,
+  /forge:run-task/,
+  /forge:run-sprint/,
+  /forge:fix-bug/,
+  /forge:retro/,
+  /forge:check-agent/,
+  /forge:report-bug/,
+  // forge:enhance removed in v1.0 (T03) — absorbed into forge:rebuild --enrich
+  // forge:collate removed from user-facing surface in v1.0 (T03) — internal tool only
+  /forge:validate/,
+  // forge:calibrate removed in v1.0 (T03) — absorbed into forge:health --fix (T04)
+  // forge:materialize removed in v1.0 (T03) — fast-mode eliminated in T01
+  /forge:remove/,
+  /forge:search/,
+  /forge:repair/,
+  /forge:store-custodian/,
+  /forge:config/,
+  /forge:ask/,
+  /forge:refresh-kb-links/,
+  /store-cli\.cjs/,
+  /validate-store\.cjs/,
+];
+
+// ---------------------------------------------------------------------------
+// H-5b: logSwallowedError
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a diagnostic line to the swallowed-error log at
+ * `$dataDir/logs/forge-hooks.log`. If `dataDir` is falsy, falls back to
+ * `os.tmpdir()/forge-plugin-data/logs/forge-hooks.log`.
+ *
+ * Format per line:
+ *   <ISO-timestamp> [<tag>] <err.message>
+ *
+ * Invariants:
+ *   - Append-only. No log rotation. Users can `truncate -s 0` or `rm` the
+ *     file; it will be recreated on the next swallowed error.
+ *   - Hook code NEVER reads this log.
+ *   - Fully fail-open: if the log write itself fails, we exit silently.
+ *
+ * Closes finding: H-5b (FORGE-S25-T15)
+ *
+ * @param {string} tag - Short hook identifier (e.g. 'post-init', 'post-sprint').
+ * @param {Error|*} err - The caught error. Uses err.message if available.
+ * @param {string|null|undefined} dataDir - CLAUDE_PLUGIN_DATA directory.
+ */
+function logSwallowedError(tag, err, dataDir) {
+  try {
+    const baseDir = dataDir || path.join(os.tmpdir(), 'forge-plugin-data');
+    const logsDir = path.join(baseDir, 'logs');
+    fs.mkdirSync(logsDir, { recursive: true });
+    const logPath = path.join(logsDir, 'forge-hooks.log');
+    const msg = (err && err.message) ? err.message : String(err);
+    const line = `${new Date().toISOString()} [${tag}] ${msg}\n`;
+    fs.appendFileSync(logPath, line, 'utf8');
+  } catch (_) {
+    // Fully fail-open — never re-throw
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  resolveForgePaths,
+  readStdinJson,
+  formatHookOutput,
+  FORGE_COMMAND_PATTERNS,
+  logSwallowedError,
+};