forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/reset.js

@@ -1,29 +1,33 @@
 const fs = require('node:fs');
 const path = require('node:path');
+const { listCanonicalSkills } = require('./skills-sync');
+const { getPackageRoot } = require('./package-root');
+
+/**
+ * Package root that ships the canonical `skills/` source. Used to determine
+ * which skill directories Forge itself installed (so user/third-party skills
+ * sharing a skills dir are not removed during reset).
+ */
+const FORGE_PACKAGE_ROOT = path.resolve(__dirname, '..');
 
 /**
  * Known forge-created file patterns.
  * Used to distinguish forge files from user-created files.
  */
-const FORGE_COMMANDS = [
-  '.claude/commands/plan.md',
-  '.claude/commands/dev.md',
-  '.claude/commands/validate.md',
-  '.claude/commands/ship.md',
-  '.claude/commands/review.md',
-  '.claude/commands/premerge.md',
-  '.claude/commands/verify.md',
-  '.claude/commands/status.md',
-  '.claude/commands/preflight.md',
+const FORGE_SKILL_DIRS = [
+  '.agents/skills',
+  '.claude/skills',
+  '.cursor/skills',
+  '.codex/skills',
 ];
 
 const FORGE_RULES = [
   '.claude/rules/workflow.md',
-  '.claude/rules/greptile-review-process.md',
+  '.claude/rules/review-process.md',
 ];
 
 const FORGE_SCRIPTS = [
-  '.claude/scripts/greptile-resolve.sh',
+  '.claude/scripts/review-resolve.sh',
   '.claude/scripts/validate.sh',
 ];
 
@@ -39,11 +43,7 @@ const FORGE_DOCS = [
 
 const FORGE_AGENT_DIRS = [
   '.cursor',
-  '.cline',
-  '.roo',
   '.codex',
-  '.kilocode',
-  '.opencode',
 ];
 
 const FORGE_SYNC_SCRIPTS_DIR = 'scripts/github-beads-sync';
@@ -68,7 +68,7 @@ const FORGE_SYNC_SCRIPTS_DIR = 'scripts/github-beads-sync';
 function getForgeFiles(projectRoot) {
   const result = {
     config: [],
-    commands: [],
+    skillDirs: [],
     rules: [],
     scripts: [],
     docs: [],
@@ -82,30 +82,11 @@ function getForgeFiles(projectRoot) {
     result.config.push('.forge');
   }
 
-  // Known forge commands (static list)
-  for (const f of FORGE_COMMANDS) {
-    if (fs.existsSync(path.join(projectRoot, f))) {
-      result.commands.push(f);
-    }
-  }
-
-  // Dynamic discovery: scan the package's .claude/commands/ directory to find
-  // any commands that setup may have copied but aren't in the static list.
-  // Only files that exist in both the package source AND the project are included.
-  const packageCommandsDir = path.join(__dirname, '..', '.claude', 'commands');
-  try {
-    const packageEntries = fs.readdirSync(packageCommandsDir);
-    for (const entry of packageEntries) {
-      if (entry.endsWith('.md')) {
-        const relPath = `.claude/commands/${entry}`;
-        if (!result.commands.includes(relPath) &&
-            fs.existsSync(path.join(projectRoot, relPath))) {
-          result.commands.push(relPath);
-        }
-      }
+  // Known forge skill directories
+  for (const dir of FORGE_SKILL_DIRS) {
+    if (fs.existsSync(path.join(projectRoot, dir))) {
+      result.skillDirs.push(dir);
     }
-  } catch (_error) {
-    // Package commands directory read failed, skip
   }
 
   // Known forge rules
@@ -184,10 +165,10 @@ function resetSoft(projectRoot, { force = false } = {}) {
 
   // Record what was preserved
   const inventory = getForgeFiles(projectRoot);
-  for (const f of [...inventory.commands, ...inventory.rules, ...inventory.scripts]) {
+  for (const f of [...inventory.rules, ...inventory.scripts]) {
     preserved.push(f);
   }
-  for (const dir of inventory.agentDirs) {
+  for (const dir of [...inventory.skillDirs, ...inventory.agentDirs]) {
     preserved.push(dir);
   }
 
@@ -203,11 +184,16 @@ function resetSoft(projectRoot, { force = false } = {}) {
  * @param {{ force?: boolean }} options
  * @returns {{ removed: string[], preserved: string[] }}
  */
-function resetHard(projectRoot, { force = false } = {}) {
+function resetHard(projectRoot, { force = false, sourceRoot } = {}) {
   if (!force) {
     throw new Error('Hard reset requires --force flag. This will remove ALL forge files.');
   }
 
+  // Resolve the package/asset root AFTER the force guard so an unforced reset
+  // never triggers extraction work or fails with an asset-resolution error
+  // instead of the intended safety message.
+  const resolvedSourceRoot = sourceRoot ?? getPackageRoot(FORGE_PACKAGE_ROOT);
+
   const removed = [];
   const preserved = [];
   const inventory = getForgeFiles(projectRoot);
@@ -223,7 +209,6 @@ function resetHard(projectRoot, { force = false } = {}) {
 
   // Remove individual forge files
   const allFiles = [
-    ...inventory.commands,
     ...inventory.rules,
     ...inventory.scripts,
     ...inventory.docs,
@@ -260,6 +245,35 @@ function resetHard(projectRoot, { force = false } = {}) {
     }
   }
 
+  // Remove Forge-managed skill directories ONLY.
+  // Shared skills dirs (e.g. .claude/skills) can also hold user/third-party
+  // skills. Scope removal to the canonical Forge skill set so user work is
+  // preserved; the surrounding dir is removed only if nothing else remains.
+  const forgeSkillNames = new Set(
+    listCanonicalSkills(resolvedSourceRoot).map((s) => s.name)
+  );
+  for (const dir of inventory.skillDirs) {
+    const skillsRoot = path.join(projectRoot, dir);
+    if (!fs.existsSync(skillsRoot)) continue;
+
+    for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (!forgeSkillNames.has(entry.name)) continue;
+      fs.rmSync(path.join(skillsRoot, entry.name), { recursive: true, force: true });
+      removed.push([dir, entry.name].join('/'));
+    }
+
+    // Drop the now-empty skills dir, but keep it if user/third-party skills remain.
+    try {
+      if (fs.readdirSync(skillsRoot).length === 0) {
+        fs.rmSync(skillsRoot, { recursive: true, force: true });
+        removed.push(dir);
+      }
+    } catch (_error) {
+      // Directory read failed, skip
+    }
+  }
+
   // Remove agent directories
   for (const dir of inventory.agentDirs) {
     const fullPath = path.join(projectRoot, dir);
@@ -300,7 +314,7 @@ module.exports = {
   resetSoft,
   resetHard,
   reinstall,
-  FORGE_COMMANDS,
+  FORGE_SKILL_DIRS,
   FORGE_RULES,
   FORGE_SCRIPTS,
   FORGE_DOCS,

package/lib/review-adapter.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const REQUIRED_REVIEW_ADAPTER_METHODS = [
+  'fetchThreads',
+  'parse',
+  'reply',
+  'resolve',
+  'score',
+];
+
+class ReviewAdapter {
+  constructor(options = {}) {
+    this.id = options.id || 'review-adapter';
+    this.kind = options.kind || 'review';
+    this.name = options.name || this.id;
+    this.version = options.version || '0.1.0';
+  }
+
+  async fetchThreads() {
+    throw new Error(`${this.id}.fetchThreads is not implemented`);
+  }
+
+  parse() {
+    throw new Error(`${this.id}.parse is not implemented`);
+  }
+
+  async reply() {
+    throw new Error(`${this.id}.reply is not implemented`);
+  }
+
+  async resolve() {
+    throw new Error(`${this.id}.resolve is not implemented`);
+  }
+
+  score() {
+    throw new Error(`${this.id}.score is not implemented`);
+  }
+}
+
+function validateReviewAdapter(adapter) {
+  const errors = [];
+
+  if (!adapter || typeof adapter !== 'object') {
+    return { valid: false, errors: ['adapter must be an object'] };
+  }
+
+  if (!adapter.id || typeof adapter.id !== 'string') {
+    errors.push('id must be a non-empty string');
+  }
+
+  if (adapter.kind !== 'review') {
+    errors.push('kind must be "review"');
+  }
+
+  for (const method of REQUIRED_REVIEW_ADAPTER_METHODS) {
+    if (typeof adapter[method] !== 'function') {
+      errors.push(`${method} must be a function`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  ReviewAdapter,
+  REQUIRED_REVIEW_ADAPTER_METHODS,
+  validateReviewAdapter,
+};

package/lib/rules-sync.js

@@ -0,0 +1,260 @@
+'use strict';
+
+/**
+ * Canonical rule source → Cursor native rule renderer.
+ *
+ * Forge policy rules (workflow, TDD, security, documentation) have ONE canonical
+ * source in `rules/<name>.md`. Each canonical file is a THIN POINTER: a short
+ * frontmatter (`description`, `globs`, `alwaysApply`) plus a few lines that point
+ * at `AGENTS.md` and the relevant stage skill. The full policy bodies are NOT
+ * duplicated here — they live in `AGENTS.md` and `skills/<stage>/SKILL.md`.
+ *
+ * Only ONE harness has a first-class native rule surface, so only one renderer
+ * exists:
+ *
+ *   - Cursor : `.cursor/rules/<name>.mdc`  (MDC frontmatter + pointer body)
+ *
+ * Claude, Codex, and Hermes receive this same policy through their INSTRUCTION
+ * projection (`CLAUDE.md` → `AGENTS.md`, `AGENTS.md`, `forge orient`) — adding
+ * always-on `.claude/rules/*.md` files would triple-deliver the same policy into
+ * every session as pure token bloat. See `lib/harness-capability-matrix.js`
+ * (the `rules` row) and `docs/reference/AGENT_SKILL_PARITY.md`.
+ *
+ * The generated `.cursor/rules/*.mdc` files are NOT committed — they are produced
+ * at `forge setup` from the canonical source (like the gitignored, setup-populated
+ * skill dirs). The structural drift gate regenerates them into a temp dir and
+ * asserts the render is deterministic and well-formed, rather than committing a
+ * mirror. Never hand-edit a generated `.mdc` — edit `rules/<name>.md`.
+ *
+ * Dependency-free (no YAML/markdown deps) so it runs under `bun test` and the
+ * release gates without pulling `@forge/*` workspaces.
+ *
+ * @module rules-sync
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Canonical rule source directory (relative to a repo/package root). */
+const CANONICAL_RULES_DIR = 'rules';
+
+/** Cursor native rule surface (relative to a project root). */
+const CURSOR_RULES_DIR = '.cursor/rules';
+
+/** Canonical rule name → Cursor `.mdc` filename. */
+const CURSOR_RULE_FILES = {
+  workflow: 'forge-workflow.mdc',
+  tdd: 'tdd-enforcement.mdc',
+  security: 'security-scanning.mdc',
+  documentation: 'documentation.mdc',
+  'kernel-tracking': 'kernel-tracking.mdc',
+};
+
+const CANONICAL_RULE_NAMES = Object.keys(CURSOR_RULE_FILES);
+
+const GENERATED_NOTE =
+  'Generated by Forge from the canonical rules/ source. Do not edit — edit ' +
+  'rules/<name>.md and re-run `forge setup` (or the rules renderer).';
+
+// Stable substring stamped into every generated rule file. Used to distinguish a
+// Forge-managed generated `.mdc` (safe to refresh on upgrade) from a user-authored
+// rule (must never be clobbered).
+const GENERATED_RULE_MARKER = 'Generated by Forge from the canonical rules/ source';
+
+/**
+ * Parse the minimal YAML frontmatter Forge authors in canonical rule files.
+ * Only flat `key: value` pairs are supported (values kept as raw strings so
+ * arrays/booleans round-trip verbatim into the rendered output).
+ *
+ * @param {string} raw
+ * @returns {{ meta: Record<string,string>, body: string }}
+ */
+function parseFrontmatter(raw) {
+  const norm = String(raw).replace(/\r\n/g, '\n');
+  if (!norm.startsWith('---\n')) {
+    return { meta: {}, body: norm };
+  }
+  const end = norm.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return { meta: {}, body: norm };
+  }
+  const block = norm.slice(4, end);
+  const body = norm.slice(end + 5);
+  const meta = {};
+  for (const line of block.split('\n')) {
+    const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (m) meta[m[1]] = m[2].trim();
+  }
+  return { meta, body };
+}
+
+/** Body with leading blank lines removed and a single trailing newline. */
+function normalizeBody(body) {
+  return body.replace(/^\n+/, '').replace(/\s+$/, '') + '\n';
+}
+
+/**
+ * Read one canonical rule from disk into a render-ready descriptor.
+ *
+ * @param {string} sourceRoot - Repo/package root containing `rules/`.
+ * @param {string} name - Canonical rule name (stem of `rules/<name>.md`).
+ * @returns {{ name, description, globs, alwaysApply, body }}
+ */
+function readCanonicalRule(sourceRoot, name) {
+  const filePath = path.join(sourceRoot, CANONICAL_RULES_DIR, `${name}.md`);
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(raw);
+  return {
+    name,
+    description: meta.description || '""',
+    globs: meta.globs || '[]',
+    alwaysApply: meta.alwaysApply || 'false',
+    body: normalizeBody(body),
+  };
+}
+
+/**
+ * List all canonical rules (in stable CURSOR_RULE_FILES order).
+ *
+ * @param {string} sourceRoot - Repo/package root containing `rules/`.
+ * @param {{ only?: Iterable<string> }} [options]
+ * @returns {Array<ReturnType<typeof readCanonicalRule>>}
+ */
+function listCanonicalRules(sourceRoot, options = {}) {
+  const only = options.only ? new Set(options.only) : null;
+  return CANONICAL_RULE_NAMES
+    .filter((name) => !only || only.has(name))
+    .map((name) => readCanonicalRule(sourceRoot, name));
+}
+
+/** Render the Cursor native rule (`.mdc` — MDC frontmatter + pointer body). */
+function renderCursorRule(rule) {
+  const frontmatter = [
+    '---',
+    `description: ${rule.description}`,
+    `globs: ${rule.globs}`,
+    `alwaysApply: ${rule.alwaysApply}`,
+    '---',
+    '',
+    `<!-- ${GENERATED_NOTE} -->`,
+    '',
+    '',
+  ].join('\n');
+  return frontmatter + rule.body;
+}
+
+/**
+ * Render every canonical rule to Cursor `.mdc` content, keyed by output filename.
+ * Pure with respect to the target filesystem (only reads canonical `rules/`),
+ * so callers can diff two renders to prove determinism.
+ *
+ * @param {string} sourceRoot - Root containing canonical `rules/`.
+ * @param {{ only?: Iterable<string> }} [options]
+ * @returns {Record<string, string>} filename → rendered content
+ */
+function renderCursorRuleMap(sourceRoot, options = {}) {
+  const map = {};
+  for (const rule of listCanonicalRules(sourceRoot, options)) {
+    map[CURSOR_RULE_FILES[rule.name]] = renderCursorRule(rule);
+  }
+  return map;
+}
+
+/**
+ * Render canonical rules into a project's Cursor rule directory.
+ *
+ * @param {object} params
+ * @param {string} params.sourceRoot - Root containing canonical `rules/`.
+ * @param {string} params.targetRoot - Project root to write native rules under.
+ * @param {'cursor'} [params.harness='cursor'] - Only Cursor has a native rule surface.
+ * @param {boolean} [params.overwrite=false] - Overwrite existing files.
+ * @param {Iterable<string>} [params.only] - Restrict to these canonical names.
+ * @returns {{ written: string[], skipped: string[] }}
+ */
+function renderRulesForHarness({ sourceRoot, targetRoot, harness = 'cursor', overwrite = false, only }) {
+  if (harness !== 'cursor') {
+    throw new Error(
+      `No native rule surface for harness "${harness}"; Claude/Codex/Hermes ` +
+      'receive rule policy through their AGENTS.md instruction projection.',
+    );
+  }
+  const outDir = path.join(targetRoot, CURSOR_RULES_DIR);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const map = renderCursorRuleMap(sourceRoot, { only });
+  const written = [];
+  const skipped = [];
+  for (const [file, content] of Object.entries(map)) {
+    const outPath = path.join(outDir, file);
+    if (!overwrite && fs.existsSync(outPath)) {
+      // Refresh Forge-managed generated files even without --overwrite so an
+      // UPGRADE (`forge setup` on an existing project) picks up canonical changes
+      // and a stale drifted rule cannot survive forever. A user-authored rule
+      // (no generated marker) is respected and left untouched.
+      const existing = fs.readFileSync(outPath, 'utf-8');
+      if (!existing.includes(GENERATED_RULE_MARKER)) {
+        skipped.push(file);
+        continue;
+      }
+    }
+    fs.writeFileSync(outPath, content, 'utf-8');
+    written.push(file);
+  }
+  return { written, skipped };
+}
+
+/**
+ * Structural drift gate for rules: regenerate into a temp dir and assert the
+ * render is deterministic and well-formed. No committed mirror is compared —
+ * the canonical `rules/` source is the only tracked artifact, and Cursor rules
+ * are setup-populated (like the gitignored skill dirs).
+ *
+ * @param {object} params
+ * @param {string} params.sourceRoot - Root containing canonical `rules/`.
+ * @returns {{ ok: boolean, issues: object[], files: string[] }}
+ */
+function checkRulesRenderDeterminism({ sourceRoot }) {
+  const issues = [];
+  const first = renderCursorRuleMap(sourceRoot);
+  const second = renderCursorRuleMap(sourceRoot);
+  const files = Object.keys(first);
+
+  for (const file of files) {
+    if (first[file] !== second[file]) {
+      issues.push({ file, status: 'non-deterministic' });
+      continue;
+    }
+    const content = first[file];
+    if (!content.startsWith('---\n')) {
+      issues.push({ file, status: 'missing-frontmatter' });
+    }
+    if (!content.includes('description:')) {
+      issues.push({ file, status: 'missing-description' });
+    }
+  }
+
+  // Every canonical rule must map to exactly one Cursor output file.
+  for (const name of CANONICAL_RULE_NAMES) {
+    if (!files.includes(CURSOR_RULE_FILES[name])) {
+      issues.push({ file: CURSOR_RULE_FILES[name], status: 'unrendered-canonical' });
+    }
+  }
+
+  return { ok: issues.length === 0, issues, files };
+}
+
+module.exports = {
+  CANONICAL_RULES_DIR,
+  CURSOR_RULES_DIR,
+  CURSOR_RULE_FILES,
+  CANONICAL_RULE_NAMES,
+  GENERATED_NOTE,
+  GENERATED_RULE_MARKER,
+  parseFrontmatter,
+  listCanonicalRules,
+  readCanonicalRule,
+  renderCursorRule,
+  renderCursorRuleMap,
+  renderRulesForHarness,
+  checkRulesRenderDeterminism,
+};