forge-workflow 0.1.0-beta.2 → 0.1.0-beta.4

package/lib/commands/recall.js

@@ -4,22 +4,34 @@ const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 const { fenceUntrusted } = require('../untrusted-content');
 
-const usage = 'Usage: forge recall [query] [--limit N] [--all] [--json]';
+const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+
+// Reserved tag prefix that `remember --kind` writes (kernel issue 8cc1db4d). A `--kind`
+// filter keeps only notes carrying this tag; the prefix is stripped when surfacing the
+// derived `type` field so a note's user tags stay clean. The filter FLAG is `--kind` (NOT
+// `--type`): `--type` is a reserved GLOBAL flag hard-validated to workflow classifications.
+const TYPE_TAG_PREFIX = 'type:';
+
+// When a `--kind` filter is active the tag filter runs in the command layer (the store is
+// not reimplemented), so scan a generous window of recent notes before filtering rather than
+// the small default page — otherwise the type match could fall outside the default limit.
+const TYPE_FILTER_SCAN = 1000;
 
 /**
- * Separate the optional positional query from `--limit N` and `--json`.
- * Global flags (e.g. `-p <dir>`, `--all`) are stripped first so they never
- * corrupt the search query (kernel issue c1e090ff). `--all` is a GLOBAL boolean
- * flag, so the handler reads it from its `flags` argument (or the raw args on a
- * direct call) — not from this parsed query.
+ * Separate the optional positional query from `--kind <type>`, `--limit N`, and `--json`.
+ * Global flags (e.g. `-p <dir>`, `--all`) are stripped first so they never corrupt the
+ * search query (kernel issue c1e090ff). `--all` is a GLOBAL boolean flag, so the handler
+ * reads it from its `flags` argument (or the raw args on a direct call) — not from here.
+ * `--kind` is NOT a global flag, so it survives the strip and is parsed here.
  *
  * @param {string[]} rawArgs - Raw command arguments.
- * @returns {{ query: string, limit: (number|undefined), json: boolean }}
+ * @returns {{ query: string, limit: (number|undefined), type: (string|undefined), json: boolean }}
  */
 function parseArgs(rawArgs) {
   const args = stripGlobalFlags(rawArgs);
   const words = [];
   let limit;
+  let type;
   let json = false;
 
   for (let index = 0; index < args.length; index += 1) {
@@ -37,18 +49,43 @@ function parseArgs(rawArgs) {
       if (Number.isInteger(value) && value > 0) {
         limit = value;
       }
+    } else if (arg === '--kind') {
+      const value = args[index + 1];
+      if (value && !value.startsWith('--')) {
+        type = value.trim();
+        index += 1;
+      }
+    } else if (arg.startsWith('--kind=')) {
+      type = arg.slice('--kind='.length).trim();
     } else {
       words.push(arg);
     }
   }
 
-  return { query: words.join(' ').trim(), limit, json };
+  return { query: words.join(' ').trim(), limit, type, json };
+}
+
+// Derive a note's `type` from its reserved `type:` tag (undefined when untyped), so any
+// surface — JSON and text — can show and filter by kind without exposing the tag encoding.
+function typeOf(entry) {
+  const tag = (entry.tags || []).find(t => t.startsWith(TYPE_TAG_PREFIX));
+  return tag ? tag.slice(TYPE_TAG_PREFIX.length) : undefined;
+}
+
+function withType(entry) {
+  const type = typeOf(entry);
+  return type ? { ...entry, type } : entry;
 }
 
 function formatEntry(entry) {
   const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
   const prefix = date ? `${date}  ` : '';
-  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  // The reserved `type:` tag renders as a leading `(kind)` marker, not as a raw tag, so the
+  // displayed tags stay the user's own labels.
+  const type = typeOf(entry);
+  const userTags = (entry.tags || []).filter(t => !t.startsWith(TYPE_TAG_PREFIX));
+  const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
+  const typeMarker = type ? `(${type}) ` : '';
   // Machine/insights records are LABELED with their source so they are never mistaken for a
   // plain human note; human `remember` notes render clean.
   const marker = entry.machine && entry.sourceAgent ? `(${entry.sourceAgent}) ` : '';
@@ -56,16 +93,33 @@ function formatEntry(entry) {
   // so the human/agent-facing render is provenance-fenced. The `--json` path above
   // keeps the raw note so programmatic consumers/parsers are unaffected.
   const note = fenceUntrusted(entry.note, { source: 'memory' });
-  return `- ${prefix}${marker}${note}${tagSuffix}`;
+  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
 }
 
 async function handler(args, flags, projectRoot) {
-  const { query, limit, json } = parseArgs(args);
+  const { query, limit, type, json } = parseArgs(args);
   // `--all` is a GLOBAL boolean flag: in production bin/forge.js strips it from
   // args and sets flags.all; on a direct handler call it may still be in args.
   const all = Boolean(flags && flags.all) || args.includes('--all');
 
-  const { notes, total, capped, scope } = memoryRouter.recall(projectRoot, { query, limit, all });
+  // A `--type` filter scans a generous recent window, then keeps only matching notes — the
+  // read stays entirely in the existing store (no schema change). `--limit` is re-applied
+  // AFTER filtering so it caps the typed result set, not the pre-filter scan.
+  const recallLimit = type ? Math.max(limit ?? 0, TYPE_FILTER_SCAN) : limit;
+  const result = memoryRouter.recall(projectRoot, { query, limit: recallLimit, all });
+  let notes = result.notes.map(withType);
+  let { total, capped } = result;
+  const { scope } = result;
+  if (type) {
+    notes = notes.filter(entry => entry.type === type);
+    total = notes.length;
+    if (limit && notes.length > limit) {
+      notes = notes.slice(0, limit);
+      capped = true;
+    } else {
+      capped = false;
+    }
+  }
 
   if (json) {
     // Object (not a bare array) so programmatic consumers see the total and whether the
@@ -108,6 +162,7 @@ module.exports = {
   description: 'Retrieve project-memory notes from the kernel-backed memory store',
   usage,
   flags: {
+    '--kind': 'Filter to notes of a type (decision|bugfix|gotcha|...); --type is reserved',
     '--limit': 'Cap the number of notes returned',
     '--all': 'Include machine/insights records in the no-query listing (query already searches all)',
     '--json': 'Emit machine-readable JSON output',

package/lib/commands/recap.js

@@ -4,6 +4,7 @@ const {
   buildIssueRecap,
   formatOrientationText,
 } = require('../orientation');
+const { recordContextLoaded } = require('../grounding/context-events');
 
 const usage = 'Usage: forge recap <issue> [--budget N] [--json]';
 
@@ -35,7 +36,7 @@ function readIssueArg(args) {
 
 // `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) {
+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
@@ -44,9 +45,22 @@ async function handler(args, _flags, projectRoot) {
     return { success: false, error: usage };
   }
 
-  const recap = buildIssueRecap(projectRoot, issueId, {
-    budgetTokens: readOption(args, '--budget', undefined),
-  });
+  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),

package/lib/commands/release.js

@@ -4,6 +4,7 @@ const {
   SUPPORTED_TARGET,
   buildReadinessReport,
   renderReadinessReport,
+  writeAuditArtifact,
 } = require('../release-readiness');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
@@ -11,9 +12,8 @@ const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = requir
 // `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]';
+// issue dispatch (resolve backend → runIssueOperation('release') → normalize).
+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);
@@ -57,6 +57,18 @@ function parseReleaseArgs(args = []) {
 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);

package/lib/commands/remember.js

@@ -3,62 +3,122 @@
 const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 
-const usage = 'Usage: forge remember <note> [--tag <label>]... [--json]';
+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 `--tag <label>` pairs and the `--json` flag.
- * Global flags (e.g. `-p <dir>`) are stripped first so they never leak into
- * the stored note content (kernel issue c1e090ff).
+ * 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[], json: boolean }}
+ * @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 === '--tag') {
-      const value = args[index + 1];
-      if (value && !value.startsWith('--')) {
-        tags.push(value);
-        index += 1;
-      }
-    } else if (arg.startsWith('--tag=')) {
-      tags.push(arg.slice('--tag='.length));
+    } 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, json };
+  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, json } = parseArgs(args);
+  const { note, tags, type, fields, json } = parseArgs(args);
+  const body = composeBody(note, fields);
 
-  if (!note) {
+  if (!body) {
     return {
       success: false,
       error: `No note provided.\n${usage}`,
     };
   }
 
-  const entry = memoryRouter.append(projectRoot, note, { tags });
+  // 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) {
-    return { success: true, output: `${JSON.stringify(entry, null, 2)}\n` };
+    const payload = type ? { ...entry, type } : entry;
+    return { success: true, output: `${JSON.stringify(payload, null, 2)}\n` };
   }
 
-  const tagSuffix = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : '';
+  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: ${entry.note}${tagSuffix}`,
+    output: `Remembered: ${typePrefix}${entry.note}${tagSuffix}`,
   };
 }
 
@@ -67,7 +127,13 @@ module.exports = {
   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/serve.js

@@ -240,7 +240,7 @@ async function routeMutation(verb, args, projectRoot, deps = {}) {
 function defaultGenerate(projectRoot, dashboardDir) {
   return new Promise((resolve, reject) => {
     const script = path.join(dashboardDir, 'generate-snapshot.mjs');
-    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore' });
+    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore', windowsHide: true });
     const timer = setTimeout(() => { child.kill(); reject(new Error('snapshot generation timed out')); }, GEN_TIMEOUT_MS);
     child.on('error', (err) => { clearTimeout(timer); reject(err); });
     child.on('exit', (code) => {
@@ -441,7 +441,10 @@ function browserOpener() {
 function openBrowser(url) {
   try {
     const { file, args } = browserOpener();
-    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore' });
+    // windowsHide keeps this detached opener from flashing a console window on
+    // Windows (Node defaults windowsHide to false); background/detached spawns
+    // must stay silent (issue 931e7924).
+    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore', windowsHide: true });
     // spawn() failures (e.g. the opener binary is missing) surface ASYNChronously
     // as an 'error' event, NOT via the try/catch — an unhandled one would crash
     // `forge serve`. Opening a browser is best-effort; swallow it (URL is printed).