forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/workflow/state-manager.js

@@ -9,34 +9,152 @@ const { getWorkflowPath, WORKFLOW_CLASSIFICATIONS, normalizeStageId } = require(
 
 const WORKFLOW_STATE_FILENAME = '.forge-state.json';
 
+function parseRelaxedWorkflowStatePayload(payload = '') {
+  const currentStage = String(payload).match(/currentStage:([a-z]+)/)?.[1];
+  if (!currentStage) {
+    return null;
+  }
+
+  const completedStages = (String(payload).match(/completedStages:\[([^\]]*)\]/)?.[1] || '')
+    .split(',')
+    .map(stage => stage.trim())
+    .filter(Boolean);
+  const skippedStages = (String(payload).match(/skippedStages:\[([^\]]*)\]/)?.[1] || '')
+    .split(',')
+    .map(stage => stage.trim())
+    .filter(Boolean);
+  const classification = String(payload).match(/classification:([a-z]+)/)?.[1] || 'standard';
+  const reason = String(payload).match(/reason:([^,}\]]+)/)?.[1]?.trim() || 'legacy-comment';
+
+  return readWorkflowState(JSON.stringify({
+    currentStage,
+    completedStages,
+    skippedStages,
+    workflowDecisions: {
+      classification,
+      reason,
+      userOverride: false,
+      overrides: [],
+    },
+    parallelTracks: [],
+  }));
+}
+
 function extractWorkflowStateFromComments(comments = '') {
-  const matches = String(comments).match(/^WorkflowState:\s*(\{.*\})$/gm);
+  const matches = String(comments)
+    .split(/\r?\n/)
+    .filter(line => line.startsWith('WorkflowState:'));
   if (!matches || matches.length === 0) {
     return null;
   }
 
-  const latest = matches.at(-1).replace(/^WorkflowState:\s*/, '');
-  return readWorkflowState(latest);
+  for (const match of [...matches].reverse()) {
+    const payload = match.replace(/^WorkflowState:\s*/, '');
+    try {
+      return readWorkflowState(payload);
+    } catch (_strictError) {
+      try {
+        const relaxedState = parseRelaxedWorkflowStatePayload(payload);
+        if (relaxedState) {
+          return relaxedState;
+        }
+      } catch (_relaxedError) {
+        // Continue to any earlier payloads.
+      }
+    }
+  }
+
+  return null;
 }
 
-function readWorkflowStateFromBeads(issueId, options = {}) {
+function extractWorkflowStateFromIssue(issue = {}) {
+  if (!issue || typeof issue !== 'object') {
+    return null;
+  }
+
+  if (typeof issue.comments === 'string') {
+    return extractWorkflowStateFromComments(issue.comments);
+  }
+
+  if (!Array.isArray(issue.comments) || issue.comments.length === 0) {
+    return null;
+  }
+
+  const mergedComments = issue.comments
+    .map(comment => {
+      if (typeof comment === 'string') {
+        return comment;
+      }
+
+      return comment && typeof comment === 'object' ? comment.text || '' : '';
+    })
+    .filter(Boolean)
+    .join('\n');
+
+  if (!mergedComments) {
+    return null;
+  }
+
+  return extractWorkflowStateFromComments(mergedComments);
+}
+
+function readBeadsIssue(issueId, options = {}) {
   if (!issueId) {
     return null;
   }
 
-  const comments = options.comments || secureExecFileSync('bd', ['comments', 'list', issueId], {
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }).trim();
+  try {
+    const { projectRoot, ...execOptions } = options;
+    const raw = secureExecFileSync('forge', ['issue', 'show', issueId, '--json'], {
+      encoding: 'utf8',
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...execOptions,
+    }).trim();
+
+    if (!raw) {
+      return null;
+    }
+
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      return parsed[0] || null;
+    }
+
+    return parsed;
+  } catch (_error) {
+    return null;
+  }
+}
 
-  if (!comments) {
+function readWorkflowStateFromBeads(issueId, options = {}) {
+  if (!issueId) {
     return null;
   }
 
-  return extractWorkflowStateFromComments(comments);
+  if (options.issue) {
+    const state = extractWorkflowStateFromIssue(options.issue);
+    if (state) {
+      return state;
+    }
+  }
+
+  if (options.comments) {
+    const state = extractWorkflowStateFromComments(options.comments);
+    if (state) {
+      return state;
+    }
+  }
+
+  // `forge issue show --json` returns the issue together with its full comment
+  // history, so a single read covers both the structured issue and the raw
+  // comment text carrying the serialized WorkflowState marker. No separate
+  // comment-list read is required.
+  const issue = readBeadsIssue(issueId, { projectRoot: options.projectRoot });
+  return extractWorkflowStateFromIssue(issue);
 }
 
-function loadStateFromBeads(options) {
+function loadStateFromBeads(options, projectRoot) {
   if (options.comments) {
     const state = extractWorkflowStateFromComments(options.comments);
     if (state) {
@@ -44,8 +162,19 @@ function loadStateFromBeads(options) {
     }
   }
 
+  if (options.issue) {
+    const state = extractWorkflowStateFromIssue(options.issue);
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
   if (options.issueId) {
-    const state = readWorkflowStateFromBeads(options.issueId, { comments: options.comments });
+    const state = readWorkflowStateFromBeads(options.issueId, {
+      comments: options.comments,
+      issue: options.issue,
+      projectRoot,
+    });
     if (state) {
       return { state, source: 'beads' };
     }
@@ -56,10 +185,24 @@ function loadStateFromBeads(options) {
 
 function loadState(projectRoot, options = {}) {
   if (!projectRoot) {
-    const beadsResult = loadStateFromBeads(options);
+    const beadsResult = loadStateFromBeads(options, null);
     return beadsResult || { state: null, source: null };
   }
 
+  if (options.preferBeads && (options.comments || options.issue || options.issueId)) {
+    try {
+      const beadsResult = loadStateFromBeads(options, projectRoot);
+      if (beadsResult) {
+        return beadsResult;
+      }
+    } catch (error) {
+      if (typeof options.onBeadsError === 'function') {
+        options.onBeadsError(error);
+      }
+      // Fall through to the on-disk state file when Beads cannot be read.
+    }
+  }
+
   const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
   if (fs.existsSync(statePath)) {
     try {
@@ -70,7 +213,7 @@ function loadState(projectRoot, options = {}) {
     }
   }
 
-  const beadsResult = loadStateFromBeads(options);
+  const beadsResult = loadStateFromBeads(options, projectRoot);
   if (beadsResult) {
     return beadsResult;
   }
@@ -185,8 +328,10 @@ function transitionStage(projectRoot, toStage, options = {}) {
 module.exports = {
   WORKFLOW_STATE_FILENAME,
   extractWorkflowStateFromComments,
+  extractWorkflowStateFromIssue,
   initializeState,
   loadState,
+  readBeadsIssue,
   readWorkflowStateFromBeads,
   saveState,
   transitionStage,

package/lib/workflow/state.js

@@ -5,7 +5,7 @@ const {
   STAGE_IDS,
   STAGE_MODEL,
   getWorkflowPath,
-  normalizeStageId,
+  normalizeStageId: normalizeCanonicalStageId,
 } = require('./stages.js');
 
 const WORKFLOW_STATE_SCHEMA_VERSION = 2;
@@ -19,6 +19,28 @@ const LEGACY_STANDARD_WORKFLOW_PATH = Object.freeze([
   'premerge',
   'verify',
 ]);
+
+// Stages that the canonical model no longer recognizes but that legacy
+// schemaVersion 1 standard workflows persisted (e.g. pre-merge, retired as a
+// standalone stage and re-homed as a task-type gate). We still accept these ids
+// when normalizing legacy state so historical .forge-state.json files survive a
+// read/write round-trip. The workflow-path membership checks below remain the
+// real guard: a non-legacy classification whose path omits the stage still
+// rejects it, so accepting the id here never leaks retired stages into current
+// flows.
+const LEGACY_STAGE_IDS = Object.freeze(
+  LEGACY_STANDARD_WORKFLOW_PATH.filter(stage => !normalizeCanonicalStageId(stage))
+);
+
+function normalizeStageId(stage) {
+  const canonical = normalizeCanonicalStageId(stage);
+  if (canonical) {
+    return canonical;
+  }
+
+  const value = typeof stage === 'string' ? stage.trim() : '';
+  return LEGACY_STAGE_IDS.includes(value) ? value : null;
+}
 const LEGACY_WORKFLOW_STATE_OPTIONS = Object.freeze({
   allowLegacyDefaultClassification: true,
   allowLegacyStandardVerify: true,

package/lib/workflow-profiles.js

@@ -9,10 +9,17 @@
 /**
  * Internal workflow profiles aligned with AGENTS.md specification
  */
+// `stages` lists ONLY the numbered workflow stages (aligned with the canonical stage
+// model in lib/workflow/stages.js). `/status` is a utility — an always-available
+// status/shepherd command, not a stage in any workflow — so it lives under
+// `utilities`, never inside `stages`.
+const UTILITIES = ['/status'];
+
 const PROFILES = {
   critical: {
     name: 'Critical (Maximum Rigor)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
+    stages: ['/plan', '/dev', '/validate', '/ship', '/review', '/verify'],
+    utilities: UTILITIES,
     tdd: 'strict',
     research: 'required',
     description: 'Security, auth, payments, data integrity, breaking changes',
@@ -21,7 +28,8 @@ const PROFILES = {
 
   standard: {
     name: 'Standard (Full Workflow)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
+    stages: ['/plan', '/dev', '/validate', '/ship', '/review'],
+    utilities: UTILITIES,
     tdd: 'required',
     research: 'optional',
     description: 'Most features and non-critical enhancements'
@@ -29,7 +37,8 @@ const PROFILES = {
 
   simple: {
     name: 'Simple (Streamlined)',
-    stages: ['/dev', '/validate', '/ship', '/premerge'],
+    stages: ['/dev', '/validate', '/ship'],
+    utilities: UTILITIES,
     tdd: 'recommended',
     research: 'skip',
     description: 'UI tweaks, small improvements, minor fixes'
@@ -38,6 +47,7 @@ const PROFILES = {
   hotfix: {
     name: 'Hotfix (Emergency)',
     stages: ['/dev', '/validate', '/ship'],
+    utilities: UTILITIES,
     tdd: 'required',  // Must reproduce bug
     research: 'skip',
     description: 'Production bugs, urgent fixes',
@@ -46,7 +56,8 @@ const PROFILES = {
 
   docs: {
     name: 'Docs (Documentation Only)',
-    stages: ['/verify', '/ship', '/premerge'],
+    stages: ['/verify', '/ship'],
+    utilities: UTILITIES,
     tdd: 'no',
     research: 'no',
     description: 'Documentation updates, README changes'
@@ -54,7 +65,8 @@ const PROFILES = {
 
   refactor: {
     name: 'Refactor (Behavior-Preserving)',
-    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
+    stages: ['/plan', '/dev', '/validate', '/ship'],
+    utilities: UTILITIES,
     tdd: 'strict',  // Must preserve behavior
     research: 'optional',
     description: 'Code cleanup, optimization, behavior-preserving improvements'

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.9",
-  "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
+  "version": "0.1.0-beta.2",
+  "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
     "forge": "bin/forge.js",
+    "forge-workflow": "bin/forge.js",
     "forge-preflight": "bin/forge-preflight.js"
   },
   "workspaces": [
@@ -12,18 +13,31 @@
   "scripts": {
     "test": "bun test --timeout 15000",
     "test:setup": "bash test-env/automation/setup-fixtures.sh",
-    "test:all": "bun run test:setup && bun test",
-    "test:coverage": "c8 --check-coverage bun test",
+    "test:all": "bun run test:setup && bun test --timeout 15000",
+    "test:coverage": "c8 --check-coverage bun test --timeout 15000",
+    "test:ci:shard": "node scripts/test-ci-shard.js",
     "typecheck": "echo 'No TypeScript in project - skipping type check'",
+    "gen:manifest": "node scripts/gen-command-manifest.js",
+    "gen:manifest:check": "node scripts/gen-command-manifest.js --check",
+    "prebuild": "node scripts/gen-command-manifest.js",
     "lint": "eslint . --max-warnings 0",
-    "check": "bash scripts/validate.sh",
+    "check": "node scripts/validate.js",
     "prepare": "lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
     "setup": "node ./bin/forge.js setup",
     "help": "node ./bin/forge.js --help",
+    "gen:assets": "bun scripts/gen-embedded-assets.mjs",
+    "build:binary": "bun scripts/gen-embedded-assets.mjs && bun build --compile --define FORGE_COMPILED=true ./bin/forge.js --outfile forge-bin",
+    "parity:binary": "bun scripts/parity-check.mjs",
     "validate:yaml": "find . \\( -name '*.yml' -o -name '*.yaml' \\) | grep -v node_modules | while IFS= read -r file; do echo \"Checking $file...\" && bun x js-yaml \"$file\" > /dev/null || exit 1; done",
     "test:mutation": "npx stryker run",
-    "test:benchmark": "node scripts/benchmark.js",
-    "test:dashboard": "node scripts/test-dashboard.js"
+    "test:benchmark": "node scripts/benchmark.js --output test-results/benchmark-results.json --profile-dir test-results/benchmark-profiles",
+    "test:benchmark:full": "node scripts/benchmark.js --output test-results/benchmark-full-results.json --profile-dir test-results/benchmark-full-profiles --group full-suite --group validate",
+    "test:full:parallel": "node scripts/test-full-suite.js",
+    "test:dashboard": "node scripts/test-dashboard.js",
+    "test:profile": "node scripts/test-profile.js --input-dir test-results --output test-results/test-profile.json --label local",
+    "test:randomized": "bun test --timeout 15000 --randomize",
+    "test:rerun": "bun test --timeout 15000 --rerun-each 2",
+    "agentic:sync": "node scripts/sync-agentic-workflow.js"
   },
   "peerDependencies": {
     "lefthook": "^1.0.0"
@@ -34,17 +48,18 @@
     }
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.4.1",
-    "@commitlint/config-conventional": "^20.4.1",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "@stryker-mutator/core": "^9.6.0",
     "c8": "^11.0.0",
     "eslint": "^10.0.2",
+    "eslint-plugin-sonarjs": "^4.1.0",
     "globals": "^17.3.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.1.0",
     "lefthook": "^2.1.4",
-    "yaml": "^2.8.3"
+    "typescript": "5.4.5"
   },
   "keywords": [
     "ai",
@@ -53,17 +68,15 @@
     "agents-md",
     "claude-code",
     "cursor",
-    "kilo-code",
-    "opencode",
-    "copilot",
-    "cline",
-    "roo-code",
     "codex",
     "development",
     "testing"
   ],
   "author": "Harsha Nandak",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.16.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/harshanandak/forge.git"
@@ -75,47 +88,44 @@
   "files": [
     "bin/",
     "lib/",
+    "rules/",
     "skills/",
-    ".claude/commands/",
     ".claude/rules/",
     ".claude/scripts/",
     ".claude/skills/",
     ".cursor/",
     "!.cursor/node_modules/",
-    ".cline/",
-    "!.cline/node_modules/",
-    ".roo/",
-    "!.roo/node_modules/",
-    ".codex/",
-    "!.codex/node_modules/",
-    ".kilocode/",
-    "!.kilocode/node_modules/",
-    ".opencode/",
-    "!.opencode/node_modules/",
     "scripts/",
-    ".github/prompts/",
+    "!scripts/github-beads-sync/",
+    "!scripts/github-beads-sync.config.json",
+    "!scripts/**/*.test.js",
     ".github/PLUGIN_TEMPLATE.json",
-    ".github/workflows/github-to-beads.yml",
-    ".github/workflows/beads-to-github.yml",
     ".forge/hooks/",
+    ".forge/protected-paths.yaml",
+    "CHANGELOG.md",
+    "QUICKSTART.md",
     "docs/*.md",
+    "docs/architecture/**/*.md",
+    "docs/guides/*.md",
+    "docs/reference/*.md",
+    "docs/forge/*.md",
     "install.sh",
     "lefthook.yml",
     "AGENTS.md",
     "CLAUDE.md",
-    ".mcp.json.example",
-    ".cursorrules",
-    "opencode.json"
+    ".mcp.json.example"
   ],
   "dependencies": {
-    "@babel/parser": "^7.29.2",
-    "fastest-levenshtein": "^1.0.16"
+    "@babel/parser": "^8.0.0",
+    "fastest-levenshtein": "^1.0.16",
+    "yaml": "^2.8.3"
   },
   "overrides": {
     "eslint": "^10.0.2",
+    "fast-uri": "^3.1.2",
     "flatted": "3.4.2",
     "minimatch": "10.2.4",
-    "brace-expansion": "5.0.5",
+    "brace-expansion": "5.0.6",
     "lodash": "4.18.1"
   },
   "c8": {

package/rules/documentation.md

@@ -0,0 +1,19 @@
+---
+description: "Progressive documentation standards"
+alwaysApply: false
+globs: []
+---
+
+# Documentation Standards
+
+Thin pointer — progressive documentation is part of every stage; the authoritative
+guidance lives in `AGENTS.md` and the `ship`/`verify` skills. Do not duplicate it here.
+
+Update documentation as you go, not at the end:
+
+- **/plan** — record design intent, rationale, and alternatives in the plan doc.
+- **/dev** — comment the *why* for non-obvious logic; keep JSDoc/TSDoc current.
+- **/ship** — update README/CHANGELOG for user-facing or breaking changes.
+- **/verify** — cross-check docs, validate examples, fix broken internal links.
+
+Keep terminology consistent, link to code, and remove stale docs promptly.

package/rules/kernel-tracking.md

@@ -0,0 +1,26 @@
+---
+description: "Always: file every issue, idea, bug, and decision to the Forge Kernel"
+alwaysApply: true
+globs: []
+---
+
+# Kernel Tracking (nothing discussed goes missing)
+
+**NON-NEGOTIABLE.** Anything raised in a session — a bug, an idea, a design
+decision, a follow-up, a TODO, a risk you noticed in passing — MUST become a
+Forge Kernel issue **immediately**, before it can be forgotten. This is a
+structural rule, not a judgment call.
+
+- Found or discussed something trackable? Run `forge issue create` right then —
+  do not wait for "later" or the end of the session.
+- Triage it: set a type and link it to its epic/parent so it is discoverable.
+- Deferring work? File the follow-up issue and reference it — never leave scope
+  cuts unfiled.
+- The Kernel is the single source of truth. Do NOT use TodoWrite, markdown TODO
+  lists, or memory notes as a substitute for a filed issue.
+
+This rule is a **thin pointer** — the authoritative workflow contract lives in
+`AGENTS.md` (see "Forge Issue Tracker") and the stage skills in
+`skills/<stage>/SKILL.md`. It is default-on and governed by the
+`rail.kernel_tracking` runtime rail (`forge gate disable rail.kernel_tracking`
+to turn it off). Do not duplicate policy here.

package/rules/security.md

@@ -0,0 +1,22 @@
+---
+description: "OWASP Top 10 security checks"
+alwaysApply: false
+globs: []
+---
+
+# Security Scanning Guidelines
+
+Thin pointer — full security analysis is documented in the plan design doc
+(OWASP Top 10 pass during `/plan`) and enforced in the `validate` skill. Do not
+duplicate the checklist here.
+
+For every feature, analyze the **OWASP Top 10 (2021)**: broken access control,
+cryptographic failures, injection (SQL/XSS/command), insecure design, security
+misconfiguration, vulnerable components, auth failures, integrity failures,
+logging/monitoring gaps, and SSRF.
+
+- Parameterize queries; sanitize output; validate all inputs.
+- Never store secrets or keys in code; reference env vars.
+- Run dependency audits (`npm audit`) and add security test cases.
+
+Load the `validate` skill and see `AGENTS.md` for the enforced gates.

package/rules/tdd.md

@@ -0,0 +1,20 @@
+---
+description: "TDD patterns and enforcement"
+alwaysApply: false
+globs: ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]
+---
+
+# TDD Enforcement
+
+Thin pointer — the full TDD procedure lives in the `dev` skill
+(`skills/dev/SKILL.md`) and `AGENTS.md`. Do not duplicate it here.
+
+**RED → GREEN → REFACTOR** is mandatory. No implementation without a failing
+test first:
+
+- **RED** — write the failing test first; run it and see it fail for the right reason.
+- **GREEN** — write the minimal code to pass; nothing beyond the test's scope.
+- **REFACTOR** — clean up while keeping tests green; commit each phase.
+
+Test behavior, not implementation. Cover edge cases, errors, and OWASP-relevant
+inputs. Load the `dev` skill for the enforced HARD-GATE loop and decision gate.

package/rules/workflow.md

@@ -0,0 +1,27 @@
+---
+description: "When working with Forge workflow commands"
+alwaysApply: true
+globs: []
+---
+
+# Forge TDD Workflow Template
+
+TDD-first workflow. This rule is a **thin pointer** — the authoritative contract
+lives in `AGENTS.md`, and each stage's detailed steps live in its skill
+(`skills/<stage>/SKILL.md`). Do not duplicate policy here.
+
+Stages: `/plan` → `/dev` → `/validate` → `/ship` → `/review` → `/verify`
+(pre-merge gate before merge). `/status` and `/shepherd` are utilities, not stages.
+
+- `/plan` — design intent → research → branch + worktree + task list
+- `/dev` — subagent-driven TDD per task (RED → GREEN → REFACTOR)
+- `/validate` — type check, lint, tests, security (HARD-GATE on exit)
+- `/ship` — push and open a PR referencing the design doc
+- `/review` — resolve ALL PR feedback (CI, Greptile, SonarCloud)
+- `/verify` — post-merge health check on the default branch
+
+> **Pre-merge gate** (not a numbered stage): finish docs on the branch, confirm CI
+> is green, hand off the PR. Embedded in `/ship` and `/review`, not a command.
+
+Load the matching stage skill for the full procedure. Default stack: `bun` test
+runner, Git conventional commits, OWASP-aware. See `AGENTS.md` for the rest.

package/scripts/auto-backing-issue.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pre-push auto-file rail (kernel issue a4b8f56f).
+ *
+ * Ensures the branch being pushed has a backing Kernel issue so a RAW `git push`
+ * (NOT routed through `forge push`, which wires the same rail) still auto-files
+ * started work — "nothing goes missing". BEST-EFFORT + NON-BLOCKING: a hook must
+ * never block a push on tracking, so `run()` swallows every error and the CLI entry
+ * ALWAYS exits 0. Idempotent via ensureBackingIssue (deduped by branch), so it never
+ * duplicates an issue `forge worktree`/`forge push` already filed.
+ */
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+/**
+ * @param {object} [deps] - injection seam for tests:
+ *   { getBranch, ensureBackingIssue, buildDeps, projectRoot, existsSync }
+ * @returns {Promise<object|null>} the backing-issue descriptor, or null when skipped.
+ */
+async function run(deps = {}) {
+  try {
+    const projectRoot = deps.projectRoot || process.cwd();
+    const existsSync = deps.existsSync || fs.existsSync;
+    const getBranch = deps.getBranch || (() => execFileSync('git', ['branch', '--show-current'], { encoding: 'utf8' }).trim());
+    const branch = getBranch();
+    if (!branch) return null;
+    if (!existsSync(path.join(projectRoot, '.git'))) return null;
+
+    const ensure = deps.ensureBackingIssue || require('../lib/kernel/backing-issue').ensureBackingIssue;
+    const buildDeps = deps.buildDeps || (root => require('../lib/kernel/cli-broker-factory').buildMigratedKernelIssueDeps({ projectRoot: root }));
+    const { kernelDriver, kernelBroker } = await buildDeps(projectRoot);
+    return await ensure({ branch, projectRoot, driver: kernelDriver, broker: kernelBroker });
+  } catch {
+    // Non-blocking: tracking must never break a push.
+    return null;
+  }
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  run().finally(() => process.exit(0));
+}