@entelligentsia/forgecli 1.0.20 → 1.0.25

package/dist/forge-payload/meta/store-schema/event.schema.md

@@ -10,6 +10,13 @@
 
 Example: `20260415T141523000Z_ACME-S02-T03_engineer_implement`
 
+## Type Vocabulary
+
+The optional `type` field, when present, must come from the canonical
+phase→type tables in `meta/workflows/_fragments/event-vocabulary.md`
+(task / bug / sprint / friction / skill_usage families). The schema enum in
+`schemas/event.schema.json` mirrors that fragment.
+
 ## Fields
 
 | Field | Type | Required | Description |

package/dist/forge-payload/meta/workflows/_fragments/event-emission-schema.md

@@ -4,6 +4,10 @@
      orchestrator stitches runtime telemetry + judgement into the canonical
      event and emits it. Referenced by meta-orchestrate.md and meta-fix-bug.md.
 
+     Companion: _fragments/event-vocabulary.md owns the `type` token
+     vocabulary (phase→type tables for task/bug/sprint events). This fragment
+     owns WHO emits; that one owns WHAT token.
+
      PLAN-11 / SLICE-2 (2026-05-14): the LLM no longer hand-builds event JSON.
      Runtime facts (model, provider, eventId, timestamps, iteration, tokens)
      are owned by the orchestrator, never the subagent. The subagent only

package/dist/forge-payload/meta/workflows/_fragments/event-vocabulary.md

@@ -0,0 +1,88 @@
+# Fragment: Event Type Vocabulary
+
+<!-- Canonical phase→type vocabulary for store events (forge-engineering#39).
+     This fragment OWNS the `type` token vocabulary; `schemas/event.schema.json`
+     mirrors it. Any vocabulary change lands here first, then in the schema enum
+     (test-first via tools/__tests__/event-schema-variants.test.cjs), then in
+     emitters (forge-cli orchestrators, wfl JS drivers, meta workflows).
+
+     Companion: _fragments/event-emission-schema.md owns WHO emits (orchestrator
+     vs subagent field ownership). This fragment owns WHAT token each phase emits.
+
+     Invariant: every token emitted by any surface MUST appear in the schema
+     enum, and every enum token MUST have a named emitter below. Dead tokens are
+     removed (bug-fixed was retired by forge-engineering#39 — defined, never
+     emitted by anything). -->
+
+## Rules
+
+1. **Emitted tokens ⊆ schema enum.** An emitter never invents a token. If a new
+   phase outcome needs a token, add it here + the schema enum first.
+2. **`type` is optional** on events. An untyped event is valid (task-pipeline
+   events from forge-cli run-task are currently untyped). When a `type` IS set,
+   it must come from the tables below.
+3. **Kebab-case for lifecycle tokens.** Underscore names are reserved for the
+   `friction` and `skill_usage` event families.
+4. **Conditional fields.** Typed events trigger schema conditionals — see the
+   "Requires" column. Driver-emitted skip events have no model/provider; emit
+   the literal `"n/a"` for both (never guess a model string — see
+   `_fragments/event-emission-schema.md` §Why no example record here).
+5. **Skip reasons ride in `notes`.** `reason` is not a declared event property
+   (`additionalProperties: false` rejects it).
+
+## Task pipeline (orchestrate_task / run-task / wfl:run-task)
+
+| Phase | Pass token | Fail token | Requires |
+|---|---|---|---|
+| plan | `task-planned` | `task-planned` | taskId, phase, iteration |
+| review-plan | `plan-approved` | `review-failed` | taskId, phase, iteration |
+| implement | `task-implemented` | `task-implemented` | taskId, phase, iteration |
+| review-code | `review-passed` | `review-failed` | taskId, phase, iteration |
+| validate | `task-validated` | `review-failed` | taskId, phase, iteration |
+| approve | `task-approved` | `review-failed` | taskId, phase, iteration |
+| commit | `task-committed` | `task-committed` | taskId, phase, iteration |
+
+`plan-complete` is a legacy alias accepted by the enum for plan-phase events;
+new emitters use `task-planned`.
+
+## Bug pipeline (fix_bug / fix-bug / wfl:fix-bug)
+
+| Phase | Pass token | Fail token | Requires |
+|---|---|---|---|
+| pre-loop skip | `bug-skipped` | — | bugId (no phase/iteration; model/provider `"n/a"`) |
+| triage | `bug-triaged` | `bug-triaged` | bugId, phase, iteration |
+| plan-fix | `fix-planned` | `fix-planned` | bugId, phase, iteration |
+| review-plan | `fix-review-passed` | `fix-review-failed` | bugId, phase, iteration |
+| implement | `fix-implemented` | `fix-implemented` | bugId, phase, iteration |
+| review-code | `fix-code-review-passed` | `fix-code-review-failed` | bugId, phase, iteration |
+| approve | `fix-approved` | `fix-revision-requested` | bugId, phase, iteration |
+| commit | `bug-committed` | `bug-commit-failed` | bugId, phase, iteration |
+
+Non-review phases emit their single token regardless of outcome (the verdict
+field carries the judgement); review phases (review-plan, review-code, approve)
+select pass/fail on `verdict == "revision"`.
+
+## Sprint grain (run_sprint / run-sprint / wfl:run-sprint)
+
+| Moment | Token | Requires |
+|---|---|---|
+| before wave loop | `sprint-start` | sprintId (taskCount optional) |
+| before each task dispatch | `task-dispatch` | taskId (convention; phase/iteration carried but not schema-enforced) |
+| sprint finished | `sprint-complete` | taskCount, completedTaskIds, verdict |
+| sprint aborted | `sprint-halted` | haltedAtTaskIndex, haltedAtTaskId, lastError |
+
+## Other families
+
+| Token | Emitter | Spec |
+|---|---|---|
+| `friction` | any persona, drained by orchestrator | `_fragments/friction-emit.md` |
+| `skill_usage` | forge-cli skill-curation telemetry | `event.schema.json` skill_usage conditional |
+
+## Out of scope (known follow-ups)
+
+- **Feature events** have no lifecycle tokens; feature-related events are
+  emitted untyped. Defining a feature vocabulary is a future change to this
+  fragment + the enum.
+- **Task-pipeline typed emission in forge-cli** — run-task currently emits
+  untyped events (valid under Rule 2); adopting the task table above is
+  forward work tracked in forge-engineering#39 step 3.

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

@@ -32,6 +32,8 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 - Commit only the artifacts produced for this task; do not sweep unrelated working-tree changes into the commit. The commit boundary mirrors the task boundary.
 - Read `.forge/personas/engineer.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/tools/store-cli.cjs`). Never edit `.forge/store/*.json` directly.
+- **Never run `git add`/`git commit`/`git reset` yourself** — `commit-task.cjs` owns staging, boundary checks, committing, and the terminal transition (#40). Your judgement input is the message.
+- **Commit writes NO summary** (`commit` ∉ `VALID_SUMMARY_PHASES` — any `set-summary` is rejected); the tool's terminal `update-status` is this phase's only store write.
 
 ## Store-Write Verification
 
@@ -41,55 +43,56 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 ```
 
-0a. Pre-flight Gate Check:
-   - **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/tools/preflight-gate.cjs --phase commit --{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/tools/store-cli.cjs read task {record_id} --json`
-   - Extract the `status` field from the JSON output.
-   - Allowed states for this phase: `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:approve must complete first. To run the full pipeline: /forge:run-task {record_id}`
-
-1. Load Context:
-   - Read the record manifest (task or bug, per entity_kind).
-   - Read ARCHITECT_APPROVAL.md by kind — never construct the path:
-     `forge_artifact({ command:"read", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval" })`
-
-2. Staging:
-   - Stage all record-related artifacts and the code changes:
-     - Task mode: PLAN.md, PROGRESS.md, REVIEW files, ARCHITECT_APPROVAL.md, and the implementation diff under the task directory plus modified source files.
-     - Bug mode: BUG_FIX_PLAN.md (Path B only — absent on Path A), TRIAGE.md, PROGRESS.md, REVIEW files, ARCHITECT_APPROVAL.md, the regression test, and the implementation diff.
-   - Verify no unrelated files are staged.
-
-3. Commit:
-   - Create a commit with a message following project conventions.
-   - Include the record ID in the commit message: task ID for task mode, bug ID for bug mode.
-   - Append a `Co-authored-by:` trailer crediting the AI assistant that actually ran the session. Resolve the identity from the host runtime: on Claude Code use `Co-authored-by: Claude <noreply@anthropic.com>`; on pi / Ollama / any other runtime use `Co-authored-by: {modelId} <noreply@{provider}.ai>` derived from the session's `provider` and `modelId` (e.g. `Co-authored-by: glm-5.1:cloud <noreply@ollama.ai>`); if neither is resolvable, omit the trailer rather than guess. Do NOT hardcode `Claude Opus 4.6 <noreply@anthropic.com>` — that literal is rejected as a regression of forge#82 (commits authored under the wrong model).
-   - Let git's configured `user.name` / `user.email` own the commit author; never pass `--author` to override it.
-
-4. Store Finalization:
-   - Transitions:
-     - **Task mode** — `approved → committed` (terminal): `node .forge/tools/store-cli.cjs update-status task {taskId} status committed`
-     - **Bug mode** — `in-progress → fixed` (terminal): `node .forge/tools/store-cli.cjs update-status bug {bugId} status fixed`. This is the ONLY phase in the bug pipeline that writes `bug.status` post-triage (see `meta-fix-bug.md § Iron Laws #2`). Do NOT write `approved` or `verified` — those values are vestigial enum members slated for removal.
-
-5. Finalize:
-   - **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.
+0. Entity-mode resolution:
+   - Read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`.
+
+1. Inspect ONCE (message material only — #40 batched-inspection rule):
+   - One `git diff --stat`; at most ONE combined `git diff` if the message needs detail.
+     Never per-file diffs, never repeated `git status` — each extra turn re-pays full context.
+   - Staging is NOT your decision — the tool derives it from the store record.
+
+2. Craft the commit message:
+   - Follow project conventions; include the record ID ({taskId} / {bugId}) in the subject.
+   - `Co-authored-by:` trailer from the host runtime: Claude Code →
+     `Co-authored-by: Claude <noreply@anthropic.com>`; pi / Ollama / other →
+     `Co-authored-by: {modelId} <noreply@{provider}.ai>` from the session's `provider` and
+     `modelId`; if unresolvable, omit rather than guess. Never hardcode
+     `Claude Opus 4.6 <noreply@anthropic.com>` (forge#82 regression).
+   - Git's configured `user.name`/`user.email` own authorship; never `--author`.
+
+3. Commit via the tool — ONE call:
+   - If the `forge_commit` named tool is available (forgecli): call it —
+     `forge_commit({ entity:"{entity_kind}", id:"{record_id}", message:"<message>", trailer:"<line>" })`.
+     Never pass the message through a bash string when the typed tool exists.
+   - Otherwise (Claude Code): `node .forge/tools/commit-task.cjs --{entity_kind} {record_id} --message "<message>" [--trailer "<Co-authored-by line>"]`
+   - The tool owns the choreography: preflight gate (`preflight-gate.cjs --phase commit`
+     internally), status precondition (task `approved` / bug `in-progress` — wrong-state runs
+     halt with `× {record_id} is in state '{status}' …; /forge:approve must complete first`),
+     staging (artifact dir + `summaries.implementation.files_changed` provenance),
+     commit-boundary guard (aborts on a pre-staged index), `git commit`, terminal transition
+     (task → `committed`; bug → `fixed`, the ONLY post-triage `bug.status` write).
+   - On `no files_changed provenance` warning: ONE `git status --porcelain`, then re-run the
+     tool with `--also <path>` per source file. Never manual `git add`.
+   - Success → JSON with `ok:true`. `committed:true` carries `sha` + `staged`;
+     `committed:false, reason:"nothing-to-commit"` is ALSO success (fix already at HEAD /
+     staging set clean — the tool still sealed the record's terminal status). Do not
+     "fix" a no-op by staging things yourself.
+   - Failure (exit 1 / ok:false) → print stderr and HALT — no manual staging, no
+     `git reset`, no `--force` retry (operator-gated). Tool file missing → HALT;
+     instruct `/forge:update` + `/forge:rebuild tools`.
+   - NEVER commit before the tool reports `ok: true` — the premature-commit/reset/redo loop
+     is forbidden.
+
+4. Finalize:
+   - No summary, no `set-summary` (see Iron Laws). **Do NOT emit a phase event yourself** —
+     the orchestrator owns event emission. Return the tool's JSON result as your phase output.
 ```
 
 <!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `commit_task.md` must follow the strict "Algorithm" block format.
-- **Context Isolation:** Forbid inline execution of commit operations; use the `Agent` tool for sub-tasks.
+- **Tool Ownership:** All git operations route through `commit-task.cjs` (forge-engineering#40) — the generated workflow must never instruct manual `git add`/`git commit`/`git reset`.
 - **Project Specifics:**
   - Embed project's commit message conventions.
 - **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.

package/dist/forge-payload/meta/workflows/meta-fix-bug.md

@@ -148,7 +148,9 @@ Differences are confined to the **triage** step and the **path branch**.
    - Detect execution cluster from ANTHROPIC_DEFAULT_*_MODEL env vars.
    - Clear progress log: store-cli progress-clear bugs
    - Read bug record. If status ∈ {blocked, escalated, fixed, abandoned}:
-     skip the run, emit a single `bug_skipped` event, return.
+     skip the run, emit a single `bug-skipped` event (token + payload shape per
+     `_fragments/event-vocabulary.md` § Bug pipeline: requires `bugId`, no
+     phase/iteration; model/provider `"n/a"`; skip reason in `notes`), return.
 
 2. Triage:
    - Locate or create the bug record (MANDATORY — do this before anything else):
@@ -503,7 +505,10 @@ After each subagent returns: `✓` for completed/approved, `↻` for revision re
 <!-- See _fragments/event-emission-schema.md for canonical contract -->
 > See `_fragments/event-emission-schema.md` for the actor split (subagent
 > writes judgement-only SUMMARY; orchestrator composes the canonical event
-> from runtime telemetry + SUMMARY and emits it).
+> from runtime telemetry + SUMMARY and emits it), and
+> `_fragments/event-vocabulary.md` § Bug pipeline for the canonical
+> phase→`type` token table (pass/fail tokens per phase, `bug-skipped`
+> pre-loop skip shape). Emitted tokens MUST come from that table.
 
 The orchestrator is the only actor that calls `store-cli emit` for phase
 events. All bug-phase events use `sprintId="bugs"` (the reserved virtual

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

@@ -87,13 +87,13 @@ The Engineer implements the approved plan: write code, run tests, verify, and do
          `node .forge/tools/store-cli.cjs update-status task {taskId} status implementing`
          `node .forge/tools/store-cli.cjs update-status task {taskId} status implemented`
      - **Bug mode** — NO status write. The bug remains `in-progress` until the commit phase transitions it to `fixed`. 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.
+   - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry plus the SUMMARY you write next. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (Plan 11 / Slice 2). Write the SUMMARY and return.
 
 7. Emit Summary Sidecar:
    - Write `IMPLEMENTATION-SUMMARY.json` via `forge_artifact`:
      `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"implementation-summary", content:"<JSON>" })`
-     JSON shape: `{"objective":"<one sentence>", "key_changes":["<up to 12 bullets>"], "verdict":"n/a", "written_at":"<ISO 8601>", "artifact_ref":"PROGRESS.md"}`
-     The tool validates required fields automatically — fix and retry if it rejects.
+     JSON shape: `{"objective":"<one sentence>", "key_changes":["<up to 12 bullets>"], "files_changed":["<path>"], "verdict":"n/a", "written_at":"<ISO 8601>", "artifact_ref":"PROGRESS.md"}`
+   - `files_changed`: every repo path this phase changed (one `git status --porcelain`); `commit-task.cjs` stages from it.
    - Then link sidecar to store (task mode):
      `forge_store({ command:"set-summary", args:["{taskId}", "implementation"] })`
      Or (bug mode):

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

@@ -950,7 +950,10 @@ is a violation of the Iron Laws.
 <!-- See _fragments/event-emission-schema.md for canonical contract -->
 > See `_fragments/event-emission-schema.md` for the actor split (subagent
 > writes judgement-only SUMMARY; orchestrator composes the canonical event
-> from runtime telemetry + SUMMARY and emits it).
+> from runtime telemetry + SUMMARY and emits it), and
+> `_fragments/event-vocabulary.md` § Task pipeline / § Sprint grain for the
+> canonical phase→`type` token tables. When setting `type` on a phase or
+> sprint event, the token MUST come from those tables.
 
 The **orchestrator** is the only actor that calls `store-cli emit` for phase
 events. Phase subagents write `{PHASE}-SUMMARY.json` and return. After each

package/dist/forge-payload/schemas/enum-catalog.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.2.13",
-  "generated": "2026-06-03",
+  "version": "1.2.21",
+  "generated": "2026-06-06",
   "note": "Authoritative enum catalog. Source: build-enum-catalog.cjs. Regenerate via node forge/tools/build-manifest.cjs.",
   "enums": {
     "task.status": [

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

@@ -59,11 +59,11 @@
         "sprint-complete",
         "sprint-halted",
         "task-dispatch",
-        "bug-fixed",
 
         "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
         "fix-implemented", "fix-code-review-passed", "fix-code-review-failed",
-        "fix-approved", "bug-committed",
+        "fix-approved", "fix-revision-requested", "bug-committed",
+        "bug-commit-failed", "bug-skipped",
 
         "skill_usage"
       ]
@@ -129,7 +129,8 @@
             "enum": [
               "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
               "fix-implemented", "fix-code-review-passed", "fix-code-review-failed",
-              "fix-approved", "bug-committed", "bug-fixed"
+              "fix-approved", "fix-revision-requested", "bug-committed",
+              "bug-commit-failed"
             ]
           }
         },
@@ -137,6 +138,10 @@
       },
       "then": { "required": ["bugId", "phase", "iteration"] }
     },
+    {
+      "if": { "properties": { "type": { "const": "bug-skipped" } }, "required": ["type"] },
+      "then": { "required": ["bugId"] }
+    },
     {
       "if": { "properties": { "type": { "const": "sprint-start" } }, "required": ["type"] },
       "then": {

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

@@ -1,6 +1,6 @@
 {
-  "version": "1.2.13",
-  "generatedAt": "2026-06-03T05:20:45.625Z",
+  "version": "1.2.21",
+  "generatedAt": "2026-06-06T15:46:43.003Z",
   "generatedByTool": "build-manifest.cjs",
   "namespaces": {
     "personas": {
@@ -94,6 +94,7 @@
       "files": [
         "context-injection.md",
         "event-emission-schema.md",
+        "event-vocabulary.md",
         "finalize.md",
         "friction-emit.md",
         "generation-instructions.md",
@@ -151,6 +152,7 @@
         "check-no-skipped-tests.cjs",
         "check-structure.cjs",
         "collate.cjs",
+        "commit-task.cjs",
         "compression-gate.cjs",
         "delete-candidate-detector.cjs",
         "estimate-usage.cjs",

package/dist/forge-payload/tools/commit-task.cjs

@@ -0,0 +1,218 @@
+'use strict';
+
+// commit-task.cjs — deterministic commit choreography (forge-engineering#40).
+//
+// The commit phase was the most expensive phase of the SDLC pipeline
+// (15–31% of run input tokens across instrumented runs) because an LLM
+// re-derived deterministic choreography turn-by-turn: gate, state check,
+// staging-set discovery, boundary verification, commit, terminal status
+// transition. This tool owns the whole sequence; the agent supplies only the
+// commit message (the single judgement-worthy step).
+//
+// Staging-set derivation (the commit boundary mirrors the task boundary):
+//   1. record.path — the task/bug artifact directory (always staged)
+//   2. record.summaries.implementation.files_changed — provenance recorded
+//      by the implement phase (PHASE_SUMMARY_SCHEMA.files_changed)
+//   3. --also <path> extras (each validated to stay inside the project root)
+//
+// Usage:
+//   node commit-task.cjs --task <id> | --bug <id>
+//        --message <msg>      commit subject/body (required unless --dry-run)
+//        [--trailer <line>]   optional Co-authored-by trailer
+//        [--also <path>]      extra path to stage (repeatable)
+//        [--skip-gate]        skip preflight-gate (orchestrator already ran it)
+//        [--force]            bypass the status precondition
+//        [--dry-run]          print the staging plan as JSON; no writes
+//
+// Exit codes: 0 ok | 1 failure (message on stderr).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { findProjectRoot } = require('./lib/project-root.cjs');
+
+const ALLOWED_STATUS = { task: 'approved', bug: 'in-progress' };
+const TERMINAL_STATUS = { task: 'committed', bug: 'fixed' };
+
+function fail(msg) {
+  console.error(`commit-task: ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const opts = { also: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--task': opts.entityKind = 'task'; opts.recordId = argv[++i]; break;
+      case '--bug': opts.entityKind = 'bug'; opts.recordId = argv[++i]; break;
+      case '--message': opts.message = argv[++i]; break;
+      case '--trailer': opts.trailer = argv[++i]; break;
+      case '--also': opts.also.push(argv[++i]); break;
+      case '--skip-gate': opts.skipGate = true; break;
+      case '--force': opts.force = true; break;
+      case '--dry-run': opts.dryRun = true; break;
+      default: fail(`unknown argument: ${a}`);
+    }
+  }
+  if (!opts.entityKind || !opts.recordId) {
+    fail('usage: commit-task.cjs --task <id> | --bug <id> --message <msg> [--trailer <line>] [--also <path>]... [--skip-gate] [--force] [--dry-run]');
+  }
+  if (!opts.dryRun && (!opts.message || !opts.message.trim())) {
+    fail('--message is required (the commit message is the only input the agent supplies)');
+  }
+  return opts;
+}
+
+function git(root, args, { allowFail = false } = {}) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  if (r.status !== 0 && !allowFail) {
+    fail(`git ${args.join(' ')} failed: ${(r.stderr || r.stdout || '').trim()}`);
+  }
+  return r;
+}
+
+// Resolve a repo-relative path and reject anything escaping the project root.
+function insideRoot(root, p) {
+  const abs = path.resolve(root, p);
+  const rel = path.relative(root, abs);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = findProjectRoot();
+  if (!root) fail('no .forge/config.json found above the current directory');
+
+  // 1. Record read (store facade — never raw .forge/store writes).
+  const store = require('./store.cjs');
+  const record = opts.entityKind === 'task' ? store.getTask(opts.recordId) : store.getBug(opts.recordId);
+  if (!record) fail(`${opts.entityKind} ${opts.recordId} not found in the store`);
+
+  // 2. Status precondition (deterministic version of the Pipeline Step Guard).
+  const allowed = ALLOWED_STATUS[opts.entityKind];
+  if (record.status !== allowed && !opts.force) {
+    const hint = opts.entityKind === 'task' ? "; /forge:approve must complete first" : '';
+    fail(`× ${opts.recordId} is in state '${record.status}' — commit requires '${allowed}'${hint}. Use --force to bypass (operator-gated, user-invoked re-runs only).`);
+  }
+
+  // 3. Preflight gate (skippable when the orchestrator already ran it).
+  if (!opts.skipGate) {
+    const gate = spawnSync(process.execPath,
+      [path.join(__dirname, 'preflight-gate.cjs'), '--phase', 'commit', `--${opts.entityKind}`, opts.recordId],
+      { cwd: root, encoding: 'utf8' });
+    if (gate.status !== 0) {
+      fail(`preflight gate failed (exit ${gate.status}):\n${(gate.stderr || gate.stdout || '').trim()}`);
+    }
+  }
+
+  // 4. Staging set: artifact dir + implementation provenance + --also extras.
+  const stage = [];
+  const warnings = [];
+  if (record.path) {
+    const rel = insideRoot(root, record.path);
+    if (rel && fs.existsSync(path.join(root, rel))) stage.push(rel);
+    else warnings.push(`artifact dir missing on disk: ${record.path}`);
+  }
+  const provenance = record.summaries?.implementation?.files_changed;
+  if (Array.isArray(provenance) && provenance.length > 0) {
+    for (const p of provenance) {
+      const rel = insideRoot(root, p);
+      if (rel === null) { warnings.push(`provenance path outside the project root, skipped: ${p}`); continue; }
+      if (!fs.existsSync(path.join(root, rel))) {
+        // Deleted files are legitimate changes — git add stages deletions of
+        // tracked paths; only warn when git knows nothing about the path.
+        const known = git(root, ['ls-files', '--error-unmatch', '--', rel], { allowFail: true });
+        if (known.status !== 0) { warnings.push(`provenance path not found (skipped): ${p}`); continue; }
+      }
+      stage.push(rel);
+    }
+  } else {
+    warnings.push('no files_changed provenance in summaries.implementation — staging the artifact dir only. Pass source files via --also if the task changed code.');
+  }
+  for (const p of opts.also) {
+    const rel = insideRoot(root, p);
+    if (rel === null) fail(`--also path outside the project root: ${p}`);
+    stage.push(rel);
+  }
+  let stageSet = [...new Set(stage)];
+  if (stageSet.length === 0) fail('nothing to stage — no artifact dir, no provenance, no --also paths');
+
+  // Pre-filter gitignored paths (live-run finding, forge-engineering#40):
+  // `git add` of the whole set is all-or-nothing — one ignored path aborts
+  // everything. check-ignore each path; warn-skip the ignored ones.
+  const ignored = [];
+  for (const rel of stageSet) {
+    const ci = git(root, ['check-ignore', '-q', '--', rel], { allowFail: true });
+    if (ci.status === 0) ignored.push(rel);
+  }
+  if (ignored.length > 0) {
+    warnings.push(`gitignored path(s) skipped from the staging set: ${ignored.join(', ')} — track them or stage explicitly with git add -f outside this tool.`);
+    stageSet = stageSet.filter((p) => !ignored.includes(p));
+  }
+
+  for (const w of warnings) console.error(`commit-task: warning: ${w}`);
+
+  if (opts.dryRun) {
+    process.stdout.write(JSON.stringify({ dryRun: true, entityKind: opts.entityKind, recordId: opts.recordId, stage: stageSet }, null, 2) + '\n');
+    return;
+  }
+
+  // 5. Commit-boundary guard: a pre-populated index means someone else's
+  //    changes would be swept into this commit. Abort loudly (Iron Law:
+  //    the commit boundary mirrors the task boundary).
+  const preStaged = git(root, ['diff', '--cached', '--name-only']).stdout.trim();
+  if (preStaged) {
+    fail(`index already has staged changes — refusing to sweep them into the ${opts.recordId} commit:\n${preStaged}\nUnstage them (git reset) or commit them separately, then re-run.`);
+  }
+
+  // 6. Terminal status transition helper — through store-cli (single source
+  //    of truth for transition legality — never reimplemented here).
+  const target = TERMINAL_STATUS[opts.entityKind];
+  const transition = (context) => {
+    const updArgs = [path.join(__dirname, 'store-cli.cjs'), 'update-status', opts.entityKind, opts.recordId, 'status', target];
+    if (opts.force) updArgs.push('--force'); // --force bypasses the transition map too (user-invoked re-runs)
+    const upd = spawnSync(process.execPath, updArgs, { cwd: root, encoding: 'utf8' });
+    if (upd.status !== 0) {
+      fail(`${context} but status transition to '${target}' failed:\n${(upd.stderr || upd.stdout || '').trim()}`);
+    }
+  };
+
+  // 7. Stage exactly the derived set. A clean staging set is a legitimate
+  //    terminal state (e.g. a bug whose fix is already at HEAD): no commit,
+  //    but the record is still sealed (live-run finding, forge-engineering#40).
+  const noop = (why) => {
+    console.error(`commit-task: ${why} — nothing to commit; sealing the record without a commit.`);
+    transition('no-op commit');
+    process.stdout.write(JSON.stringify(
+      { ok: true, committed: false, reason: 'nothing-to-commit', skippedIgnored: ignored, status: target }, null, 2) + '\n');
+  };
+  if (stageSet.length === 0) {
+    noop('entire staging set is gitignored');
+    return;
+  }
+  git(root, ['add', '--', ...stageSet]);
+  const staged = git(root, ['diff', '--cached', '--name-only']).stdout.trim().split('\n').filter(Boolean);
+  if (staged.length === 0) {
+    noop('working tree already clean for the staging set');
+    return;
+  }
+
+  // 8. Commit. Message comes from the agent; the optional trailer is appended
+  //    after a blank line per git convention.
+  const message = opts.trailer ? `${opts.message.trim()}\n\n${opts.trailer.trim()}\n` : `${opts.message.trim()}\n`;
+  git(root, ['commit', '-m', message]);
+  const sha = git(root, ['rev-parse', 'HEAD']).stdout.trim();
+
+  transition(`commit ${sha} created`);
+
+  process.stdout.write(JSON.stringify({ ok: true, committed: true, sha, staged, status: target }, null, 2) + '\n');
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`commit-task: ${err.message}`);
+  process.exit(1);
+}

package/dist/forge-payload/tools/store-cli.cjs

@@ -77,7 +77,12 @@ const PHASE_SUMMARY_SCHEMA = {
     verdict:     { type: 'string', enum: ['approved', 'revision', 'n/a'] },
     written_at:  { type: 'string' },
     artifact_ref:{ type: 'string' },
-    route:       { type: 'string', enum: ['A', 'B'] }
+    route:       { type: 'string', enum: ['A', 'B'] },
+    // forge-engineering#40: implement-phase file provenance. The implement
+    // workflow records the repo-relative paths it created/modified;
+    // commit-task.cjs derives its staging set from this list instead of the
+    // LLM re-deriving the change surface from git each run.
+    files_changed: { type: 'array', items: { type: 'string', maxLength: 300 }, maxItems: 100 }
   },
   additionalProperties: false
 };

package/node_modules/@mariozechner/clipboard/package.json

@@ -42,6 +42,7 @@
     "version": "napi version"
   },
   "optionalDependencies": {
-    "@mariozechner/clipboard-linux-x64-gnu": "0.3.9"
+    "@mariozechner/clipboard-linux-x64-gnu": "0.3.9",
+    "@mariozechner/clipboard-linux-x64-musl": "0.3.9"
   }
 }

package/node_modules/@mariozechner/clipboard-linux-x64-musl/README.md

@@ -0,0 +1,3 @@
+# `@mariozechner/clipboard-linux-x64-musl`
+
+This is the **x86_64-unknown-linux-musl** binary for `@mariozechner/clipboard`

package/node_modules/@mariozechner/clipboard-linux-x64-musl/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mariozechner/clipboard-linux-x64-musl",
+  "version": "0.3.9",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "clipboard.linux-x64-musl.node",
+  "files": [
+    "clipboard.linux-x64-musl.node"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">= 10"
+  },
+  "libc": [
+    "musl"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/badlogic/clipboard.git"
+  }
+}