forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/recap.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const {
+  buildIssueRecap,
+  formatOrientationText,
+} = require('../orientation');
+const { recordContextLoaded } = require('../grounding/context-events');
+
+const usage = 'Usage: forge recap <issue> [--budget N] [--json]';
+
+// Options that consume the following token as their value. The issue-id scan
+// must skip these values so `forge recap --budget 220 <issue>` is not misread.
+const OPTIONS_WITH_VALUES = new Set(['--budget']);
+
+function readOption(args, name, fallback) {
+  const equals = args.find(arg => arg.startsWith(`${name}=`));
+  if (equals) return equals.slice(name.length + 1);
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('-')) return args[index + 1];
+  return fallback;
+}
+
+function readIssueArg(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (OPTIONS_WITH_VALUES.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith('-')) continue;
+    return arg;
+  }
+  return null;
+}
+
+// `forge recap <issue>` summarizes a single issue from the deterministic
+// orientation source assembly — it is issue-scoped, not a project-wide recap.
+async function handler(args, _flags, projectRoot, opts = {}) {
+  const issueId = readIssueArg(args);
+  if (!issueId) {
+    // Use `error` (not `output`) so the CLI dispatcher prints the usage line
+    // once via console.error instead of also appending a redundant bare
+    // "Command failed" (see bin/forge.js registry dispatch).
+    return { success: false, error: usage };
+  }
+
+  const budget = readOption(args, '--budget', undefined);
+  const recap = buildIssueRecap(projectRoot, issueId, { budgetTokens: budget });
+
+  // Grounding (gate.read_first): a successful recap IS the load-the-doc action,
+  // so append a `context.loaded` event that unblocks a later `forge claim <id>`.
+  // Best-effort and awaited so the event is durable before the CLI process exits;
+  // a bookkeeping failure never fails the recap render.
+  const deps = (opts.kernelBroker && opts.kernelDriver)
+    ? { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver }
+    : undefined;
+  try {
+    await recordContextLoaded(projectRoot, {
+      issueId, cmd: 'recap', budget, session: opts.session, env: opts.env, deps, now: opts.now,
+    });
+  } catch { /* best-effort: never fail a recap on grounding bookkeeping */ }
+
+  return {
+    success: true,
+    output: args.includes('--json') ? `${JSON.stringify(recap, null, 2)}\n` : formatOrientationText(recap),
+  };
+}
+
+module.exports = {
+  name: 'recap',
+  description: 'Summarize a single issue from deterministic orientation source files',
+  usage,
+  handler,
+};

package/lib/commands/recommend.js

@@ -23,7 +23,6 @@ const STAGE_NAMES = {
   validate: 'Validate',
   ship: 'Ship',
   review: 'Review',
-  premerge: 'Premerge',
 };
 
 /**

package/lib/commands/release.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const {
+  SUPPORTED_TARGET,
+  buildReadinessReport,
+  renderReadinessReport,
+  writeAuditArtifact,
+} = require('../release-readiness');
+const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
+const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
+
+// `forge release <id>` releases a claimed issue; `forge release check` runs the
+// release-readiness gate. The two share the top-level verb, so this command
+// dispatches `check` to the gate and routes everything else through the shared
+// issue dispatch (resolve backend → runIssueOperation('release') → normalize). The
+// Beads backend has no release op and returns the Kernel-only contract error.
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit';
+
+async function runReleaseIssue(args, projectRoot, opts = {}) {
+  const resolved = withResolvedIssueBackend(projectRoot, opts);
+  const runIssueOperation = resolved.runIssueOperation || defaultRunIssueOperation;
+  const normalizedArgs = normalizeArgs(args);
+  const result = await runIssueOperation('release', normalizedArgs, projectRoot,
+    { ...resolved, kernelBroker: resolved.kernelBroker });
+  return normalizeIssueResult(result, 'release', { json: normalizedArgs.includes('--json') });
+}
+
+function readOption(args, name, fallback) {
+  const equals = args.find(arg => arg.startsWith(`${name}=`));
+  if (equals) {
+    return equals.slice(name.length + 1);
+  }
+
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('-')) {
+    return args[index + 1];
+  }
+
+  return fallback;
+}
+
+function parseReleaseArgs(args = []) {
+  const subcommand = args.find((arg, index) => {
+    if (arg.startsWith('-')) {
+      return false;
+    }
+    const previous = args[index - 1];
+    return previous !== '--target';
+  });
+
+  return {
+    subcommand,
+    target: readOption(args, '--target', SUPPORTED_TARGET),
+    json: args.includes('--json'),
+  };
+}
+
+async function handler(args, _flags, projectRoot, opts = {}) {
+  const parsed = parseReleaseArgs(args);
+
+  if (parsed.subcommand === 'regen-audit') {
+    // forge release regen-audit — rewrite the D20 kill-list from a live re-scan.
+    // The staleness gate (lib/release-readiness d20 check) points here so a
+    // Beads-removal PR that shifts the census is a one-command fix, not a
+    // hand-edit that red-fails CI until it matches byte-for-byte.
+    const { path: artifact } = writeAuditArtifact(projectRoot);
+    return {
+      success: true,
+      output: `Regenerated ${artifact}. Commit it to clear the d20 staleness gate.\n`,
+    };
+  }
+
+  if (parsed.subcommand !== 'check') {
+    // forge release <id> — release a claimed issue via the shared issue dispatch.
+    return runReleaseIssue(args, projectRoot, opts);
+  }
+
+  const report = buildReadinessReport(projectRoot, { target: parsed.target });
+  const output = parsed.json
+    ? `${JSON.stringify(report, null, 2)}\n`
+    : renderReadinessReport(report);
+  const error = parsed.json
+    ? `Forge release readiness check failed for ${report.target}`
+    : output;
+
+  return {
+    success: report.success,
+    report,
+    output,
+    error: report.success ? undefined : error,
+  };
+}
+
+module.exports = {
+  name: 'release',
+  description: 'Release a claimed issue, or run Forge release readiness gates (forge release check)',
+  usage,
+  flags: {
+    '--target <version>': 'Release target to check',
+    '--json': 'Emit the readiness report as JSON',
+  },
+  handler,
+  parseReleaseArgs,
+};

package/lib/commands/remember.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const memoryRouter = require('../memory/router');
+const { stripGlobalFlags } = require('../global-flags');
+
+const usage =
+  'Usage: forge remember <note> [--kind <type>] [--session-summary] [--tag <label>]... ' +
+  '[--what <text>] [--why <text>] [--where <text>] [--learned <text>] [--json]';
+
+// Structured note fields (kernel issue 8cc1db4d). Each is optional and, when present, is
+// folded into the stored note body as a labeled line so it stays FTS-searchable. Order is
+// fixed for a stable, readable render.
+const STRUCTURED_FIELDS = [
+  ['--what', 'What'],
+  ['--why', 'Why'],
+  ['--where', 'Where'],
+  ['--learned', 'Learned'],
+];
+
+// A note's type is stored as a reserved `type:<value>` tag — cheap, additive, and filterable
+// by recall/search WITHOUT a store-schema change (a missing type is fine). The CLI flag is
+// `--kind` (NOT `--type`): `--type` is a reserved GLOBAL flag that bin/forge.js hard-validates
+// against workflow classifications (critical|standard|…), so it can never carry a note type.
+const TYPE_TAG_PREFIX = 'type:';
+
+/**
+ * Split positional note words from `--kind`, `--tag <label>`, the structured field flags,
+ * and `--json`. Global flags (e.g. `-p <dir>`) are stripped first so they never leak into the
+ * stored note content (kernel issue c1e090ff); `--kind` is NOT a global flag, so it survives
+ * the strip and is parsed here.
+ *
+ * @param {string[]} rawArgs - Raw command arguments.
+ * @returns {{ note: string, tags: string[], type: (string|undefined), fields: object, json: boolean }}
+ */
+function parseArgs(rawArgs) {
+  const args = stripGlobalFlags(rawArgs);
+  const fieldFlags = new Map(STRUCTURED_FIELDS.map(([flag, label]) => [flag, label]));
+  const words = [];
+  const tags = [];
+  const fields = {};
+  let type;
+  let json = false;
+
+  // Consume `--flag value` / `--flag=value`, guarding against swallowing the next flag.
+  const takeValue = (index) => {
+    const arg = args[index];
+    const eq = arg.indexOf('=');
+    if (eq >= 0) return { value: arg.slice(eq + 1), consumed: 0 };
+    const next = args[index + 1];
+    if (next && !next.startsWith('--')) return { value: next, consumed: 1 };
+    return { value: undefined, consumed: 0 };
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const bare = arg.startsWith('--') ? arg.split('=', 1)[0] : arg;
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--session-summary') {
+      // Memorable one-flag alias for `--kind session-summary` — the explicit capture-on-exit
+      // path an agent calls (via `forge memory add --session-summary` / `forge remember`) to
+      // persist a structured session summary with the same --what/--why/--learned fields.
+      type = 'session-summary';
+    } else if (bare === '--kind') {
+      const { value, consumed } = takeValue(index);
+      if (value) type = value.trim();
+      index += consumed;
+    } else if (bare === '--tag') {
+      const { value, consumed } = takeValue(index);
+      if (value) tags.push(value);
+      index += consumed;
+    } else if (fieldFlags.has(bare)) {
+      const { value, consumed } = takeValue(index);
+      if (value) fields[fieldFlags.get(bare)] = value.trim();
+      index += consumed;
+    } else {
+      words.push(arg);
+    }
+  }
+
+  return { note: words.join(' ').trim(), tags, type, fields, json };
+}
+
+/**
+ * Compose the stored note body from the positional note plus any structured fields. Fields
+ * are appended as labeled lines under the note so recall renders them readably and they stay
+ * searchable. Returns the empty string only when nothing at all was provided.
+ */
+function composeBody(note, fields) {
+  const lines = STRUCTURED_FIELDS
+    .map(([, label]) => (fields[label] ? `${label}: ${fields[label]}` : null))
+    .filter(Boolean);
+  return [note, ...lines].filter(Boolean).join('\n');
+}
+
+async function handler(args, _flags, projectRoot) {
+  const { note, tags, type, fields, json } = parseArgs(args);
+  const body = composeBody(note, fields);
+
+  if (!body) {
+    return {
+      success: false,
+      error: `No note provided.\n${usage}`,
+    };
+  }
+
+  // The type rides as a reserved tag so it is stored and filterable without a schema change.
+  const allTags = type ? [...tags, `${TYPE_TAG_PREFIX}${type}`] : tags;
+  const entry = memoryRouter.append(projectRoot, body, { tags: allTags });
+
+  if (json) {
+    const payload = type ? { ...entry, type } : entry;
+    return { success: true, output: `${JSON.stringify(payload, null, 2)}\n` };
+  }
+
+  const userTags = entry.tags.filter(tag => !tag.startsWith(TYPE_TAG_PREFIX));
+  const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
+  const typePrefix = type ? `(${type}) ` : '';
+  return {
+    success: true,
+    output: `Remembered: ${typePrefix}${entry.note}${tagSuffix}`,
+  };
+}
+
+module.exports = {
+  name: 'remember',
+  description: 'Persist a project-memory note to the kernel-backed memory store',
+  usage,
+  flags: {
+    '--kind': 'Type the note (decision|bugfix|gotcha|...) — filterable by recall (--type is reserved)',
+    '--session-summary': 'Alias for --kind session-summary — capture a session summary on exit',
+    '--tag': 'Attach a search label (repeatable)',
+    '--what': 'Structured field: what happened/changed',
+    '--why': 'Structured field: why',
+    '--where': 'Structured field: where (file/area)',
+    '--learned': 'Structured field: what was learned',
+    '--json': 'Emit machine-readable JSON output',
+  },
+  handler,
+};

package/lib/commands/role.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * `forge role <role> --use <skill> [--ideology <name>]`
+ *
+ * Thin SWAP verb over the sparse config writer: binds a role to a skill and/or
+ * ideology by writing `roles.<role>.skill` / `roles.<role>.ideology` in
+ * `.forge/config.yaml`. `forge options roles --json` reflects the binding
+ * through the shipped resolver (`applyRoleConfig`).
+ *
+ * Write-time validation errors BEFORE anything is written:
+ *  - unknown role (not in the KNOWN closed set ROLE_IDS)
+ *  - unresolvable skill (no SKILL.md under `.skills/ > skills/`)
+ *
+ * The skill name is OPEN-WORLD (a bring-your-own skill is fine) — it is checked
+ * for existence/trust, never against the closed PLAN_SUBSKILL enum.
+ */
+
+const { setConfigOverride, resolveSkill } = require('../config-writer');
+const { ROLE_IDS } = require('../core/runtime-graph');
+
+function usage() {
+  return 'Usage: forge role <role> --use <skill> [--ideology <name>]';
+}
+
+function parseArgs(args) {
+  const parsed = { role: args[0], skill: undefined, ideology: undefined };
+  for (let i = 1; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--use' || token === '--skill') {
+      if (i + 1 >= args.length) {
+        return { error: `${token} requires a value.` };
+      }
+      parsed.skill = args[i + 1];
+      i += 1;
+    } else if (token === '--ideology') {
+      if (i + 1 >= args.length) {
+        return { error: `${token} requires a value.` };
+      }
+      parsed.ideology = args[i + 1];
+      i += 1;
+    } else {
+      return { error: `Unknown argument '${token}'.` };
+    }
+  }
+  return { parsed };
+}
+
+async function handler(args, _flags, projectRoot = process.cwd()) {
+  const { parsed, error } = parseArgs(args);
+  if (error) {
+    return { success: false, error: `${error}\n${usage()}` };
+  }
+  if (!parsed.role) {
+    return { success: false, error: usage() };
+  }
+  if (!ROLE_IDS.has(parsed.role)) {
+    return {
+      success: false,
+      error: `Unknown role '${parsed.role}'. Known roles: ${[...ROLE_IDS].join(', ')}`,
+    };
+  }
+  if (parsed.skill === undefined && parsed.ideology === undefined) {
+    return { success: false, error: `Nothing to set — pass --use and/or --ideology.\n${usage()}` };
+  }
+  if (parsed.skill !== undefined) {
+    if (typeof parsed.skill !== 'string' || parsed.skill === '') {
+      return { success: false, error: `--use requires a skill name.\n${usage()}` };
+    }
+    if (!resolveSkill(projectRoot, parsed.skill)) {
+      return {
+        success: false,
+        error: `Unknown skill '${parsed.skill}' — no SKILL.md found under .skills/ or skills/.`,
+      };
+    }
+  }
+  if (parsed.ideology !== undefined && (typeof parsed.ideology !== 'string' || parsed.ideology === '')) {
+    return { success: false, error: `--ideology requires a name.\n${usage()}` };
+  }
+
+  const writes = [];
+  if (parsed.skill !== undefined) {
+    setConfigOverride(projectRoot, ['roles', parsed.role, 'skill'], parsed.skill);
+    writes.push(`roles.${parsed.role}.skill=${parsed.skill}`);
+  }
+  if (parsed.ideology !== undefined) {
+    setConfigOverride(projectRoot, ['roles', parsed.role, 'ideology'], parsed.ideology);
+    writes.push(`roles.${parsed.role}.ideology=${parsed.ideology}`);
+  }
+
+  return { success: true, output: `Updated ${writes.join(', ')}` };
+}
+
+module.exports = {
+  name: 'role',
+  description: 'Bind a role to a skill/ideology in .forge/config.yaml',
+  usage: usage(),
+  handler,
+};