forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/workflow/stages.js

@@ -15,7 +15,6 @@ const STAGE_IDS = Object.freeze([
 	'validate',
 	'ship',
 	'review',
-	'premerge',
 	'verify',
 ]);
 
@@ -25,7 +24,6 @@ const STAGE_LABELS = Object.freeze({
 	validate: 'Validate',
 	ship: 'Ship',
 	review: 'Review',
-	premerge: 'Premerge',
 	verify: 'Verify',
 });
 
@@ -35,14 +33,13 @@ const STAGE_COMMANDS = Object.freeze({
 	validate: '/validate',
 	ship: '/ship',
 	review: '/review',
-	premerge: '/premerge',
 	verify: '/verify',
 });
 
 const WORKFLOW_STAGE_MATRIX = Object.freeze({
-	critical: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'premerge', 'verify']),
-	standard: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'premerge']),
-	refactor: Object.freeze(['plan', 'dev', 'validate', 'ship', 'premerge']),
+	critical: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'verify']),
+	standard: Object.freeze(['plan', 'dev', 'validate', 'ship', 'review']),
+	refactor: Object.freeze(['plan', 'dev', 'validate', 'ship']),
 	simple: Object.freeze(['dev', 'validate', 'ship']),
 	hotfix: Object.freeze(['dev', 'validate', 'ship']),
 	// Docs-only work intentionally reuses /verify as a pre-ship content check to
@@ -51,6 +48,18 @@ const WORKFLOW_STAGE_MATRIX = Object.freeze({
 	docs: Object.freeze(['verify', 'ship']),
 });
 
+// Pre-merge is a task-type gate/checkpoint embedded inside existing stages
+// (the doc-completion + PR-handoff checks that run before merge), not a
+// standalone universal workflow stage. It is keyed with a hyphen ('pre-merge')
+// so it never re-enters the stage model. `enabledFor` lists the classifications
+// that run the gate; `embeddedIn` names the stages where it fires.
+const WORKFLOW_GATES = Object.freeze({
+	'pre-merge': Object.freeze({
+		embeddedIn: Object.freeze(['ship', 'review']),
+		enabledFor: Object.freeze(['critical', 'standard', 'refactor']),
+	}),
+});
+
 const WORKFLOW_TERMINAL_STAGES = Object.freeze(Object.entries(WORKFLOW_STAGE_MATRIX).reduce((accumulator, [classification, path]) => {
 	accumulator[classification] = path.at(-1);
 	return accumulator;
@@ -77,6 +86,19 @@ function getWorkflowPath(classification) {
 	return normalized ? WORKFLOW_STAGE_MATRIX[normalized] : Object.freeze([]);
 }
 
+function getGatesForClassification(classification) {
+	const normalized = normalizeClassification(classification);
+	if (!normalized) {
+		return Object.freeze([]);
+	}
+
+	return Object.freeze(
+		Object.entries(WORKFLOW_GATES)
+			.filter(([, gate]) => gate.enabledFor.includes(normalized))
+			.map(([gateId]) => gateId),
+	);
+}
+
 function getStageWorkflow(stageId, classification) {
 	const normalizedStage = normalizeStageId(stageId);
 	const normalizedClassification = normalizeClassification(classification);
@@ -186,6 +208,7 @@ module.exports = {
 	STAGE_LABELS,
 	STAGE_COMMANDS,
 	WORKFLOW_STAGE_MATRIX,
+	WORKFLOW_GATES,
 	WORKFLOW_TERMINAL_STAGES,
 	STAGE_TRANSITIONS,
 	STAGE_MODEL,
@@ -193,6 +216,7 @@ module.exports = {
 	normalizeStageId,
 	isCanonicalStageId,
 	getWorkflowPath,
+	getGatesForClassification,
 	getStageWorkflow,
 	getAllowedTransitions,
 	canTransition,

package/lib/workflow/state-manager.js

@@ -105,7 +105,7 @@ function readBeadsIssue(issueId, options = {}) {
 
   try {
     const { projectRoot, ...execOptions } = options;
-    const raw = secureExecFileSync('bd', ['show', issueId, '--json'], {
+    const raw = secureExecFileSync('forge', ['issue', 'show', issueId, '--json'], {
       encoding: 'utf8',
       cwd: projectRoot,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -139,30 +139,19 @@ function readWorkflowStateFromBeads(issueId, options = {}) {
     }
   }
 
-  let comments = options.comments;
-  if (!comments) {
-    try {
-      const issue = readBeadsIssue(issueId, { projectRoot: options.projectRoot });
-      const state = extractWorkflowStateFromIssue(issue);
-      if (state) {
-        return state;
-      }
-    } catch (_error) {
-      // Fall through to comments-list fallback.
+  if (options.comments) {
+    const state = extractWorkflowStateFromComments(options.comments);
+    if (state) {
+      return state;
     }
   }
 
-  comments = comments || secureExecFileSync('bd', ['comments', 'list', issueId], {
-    encoding: 'utf8',
-    cwd: options.projectRoot,
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }).trim();
-
-  if (!comments) {
-    return null;
-  }
-
-  return extractWorkflowStateFromComments(comments);
+  // `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, projectRoot) {

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,7 +1,7 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.10",
-  "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",
@@ -13,15 +13,21 @@
   "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": "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 --output test-results/benchmark-results.json --profile-dir test-results/benchmark-profiles",
@@ -29,8 +35,8 @@
     "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 --randomize",
-    "test:rerun": "bun test --rerun-each 2",
+    "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": {
@@ -42,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",
@@ -61,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"
@@ -83,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));
+}