@entelligentsia/forgecli 1.0.3 → 1.0.14

package/dist/forge-payload/tools/check-structure.cjs

@@ -132,9 +132,17 @@ function validateManifest(manifest, forgeRoot) {
     fragments: path.join(basePackDir, 'workflows', '_fragments'),
     templates: path.join(basePackDir, 'templates'),
     commands:  path.join(basePackDir, 'commands'),
+    'workflows-js': path.join(basePackDir, 'workflows-js'),
+    // tools: not base-pack-sourced — source is forgeRoot/tools/ (verbatim vendor).
+    // Uses recursive enumeration to include lib/*.cjs with the lib/ prefix.
+    tools: path.join(forgeRoot, 'tools'),
     // schemas: not base-pack-sourced — source is forgeRoot/schemas/
   };
 
+  // Namespaces that require recursive enumeration (files may include path prefixes
+  // like lib/*.cjs). The walker returns relative paths with forward slashes.
+  const recursiveNs = new Set(['tools']);
+
   const manifestOnly = [];  // Files in manifest but not in base-pack
   const basePackOnly = [];   // Files in base-pack but not in manifest
 
@@ -147,14 +155,31 @@ function validateManifest(manifest, forgeRoot) {
 
     const manifestFiles = new Set(ns.files || []);
 
-    // Read base-pack source directory
+    // Read base-pack source directory (flat or recursive depending on namespace)
     let basePackFiles = [];
     try {
-      basePackFiles = fs.readdirSync(sourceDir).filter(f => {
-        // Only include regular files, skip subdirectories (like _fragments under workflows)
-        const stat = fs.statSync(path.join(sourceDir, f));
-        return stat.isFile();
-      });
+      if (recursiveNs.has(nsKey)) {
+        // Recursive walk: enumerate all files, returning paths relative to sourceDir
+        // (with forward-slash separators). Excludes *.test.cjs files.
+        const walkDir = (dir, prefix) => {
+          const entries = fs.readdirSync(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+              walkDir(path.join(dir, entry.name), relPath);
+            } else if (entry.isFile() && !entry.name.endsWith('.test.cjs')) {
+              basePackFiles.push(relPath);
+            }
+          }
+        };
+        walkDir(sourceDir, '');
+      } else {
+        basePackFiles = fs.readdirSync(sourceDir).filter(f => {
+          // Only include regular files, skip subdirectories (like _fragments under workflows)
+          const stat = fs.statSync(path.join(sourceDir, f));
+          return stat.isFile();
+        });
+      }
     } catch {
       // Directory doesn't exist — all manifest files are manifestOnly
       for (const f of manifestFiles) {
@@ -183,9 +208,65 @@ function validateManifest(manifest, forgeRoot) {
   return { manifestOnly, basePackOnly };
 }
 
+// Checks whether the vendored .forge/tools/ directory is present, and whether
+// the version marker (.forge/tools/.forge-tools-version) matches the active
+// plugin version from .forge/config.json (paths.forgeRef).
+//
+// Returns:
+//   { present, vendoredVersion, activeVersion, stale, reason }
+//
+//   present        — true if .forge/tools/ directory exists
+//   vendoredVersion — version string from .forge-tools-version (or null)
+//   activeVersion   — version string from paths.forgeRef in config (or null)
+//   stale          — true when: dir absent=false; marker absent=true; versions differ=true
+//   reason         — 'ok' | 'missing' | 'marker-absent' | 'version-mismatch'
+function checkToolsVersion(projectRoot) {
+  const toolsDir = path.join(projectRoot, '.forge', 'tools');
+  const markerFile = path.join(toolsDir, '.forge-tools-version');
+  const configFile = path.join(projectRoot, '.forge', 'config.json');
+
+  // Dir absent → not stale (just missing)
+  if (!fs.existsSync(toolsDir)) {
+    return { present: false, vendoredVersion: null, activeVersion: null, stale: false, reason: 'missing' };
+  }
+
+  // Read active version from config
+  let activeVersion = null;
+  if (fs.existsSync(configFile)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+      activeVersion = (cfg && cfg.paths && cfg.paths.forgeRef) ? cfg.paths.forgeRef : null;
+    } catch {
+      // unparseable — leave activeVersion null
+    }
+  }
+
+  // Marker absent → stale
+  if (!fs.existsSync(markerFile)) {
+    return { present: true, vendoredVersion: null, activeVersion, stale: true, reason: 'marker-absent' };
+  }
+
+  // Read vendored version from marker
+  let vendoredVersion = null;
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerFile, 'utf8'));
+    vendoredVersion = (marker && marker.version) ? marker.version : null;
+  } catch {
+    // unparseable marker → treat as marker-absent
+    return { present: true, vendoredVersion: null, activeVersion, stale: true, reason: 'marker-absent' };
+  }
+
+  // Version mismatch → stale
+  if (activeVersion && vendoredVersion && vendoredVersion !== activeVersion) {
+    return { present: true, vendoredVersion, activeVersion, stale: true, reason: 'version-mismatch' };
+  }
+
+  return { present: true, vendoredVersion, activeVersion, stale: false, reason: 'ok' };
+}
+
 // ── Exports ────────────────────────────────────────────────────────────────────
 
-module.exports = { checkNamespaces, validateManifest };
+module.exports = { checkNamespaces, validateManifest, checkToolsVersion };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────
 

package/dist/forge-payload/tools/collate.cjs

@@ -108,9 +108,23 @@ function resolveTaskDir(task, sprintDirPath, engPath) {
   const normalizedTaskPath = task.path ? task.path.replace(/\\/g, '/').replace(/\/$/, '') : null;
   const normalizedEngPath  = engPath   ? engPath.replace(/\\/g, '/').replace(/\/$/, '')  : '';
 
-  // Case 1: path is under the engineering root — it IS the task directory
+  // Case 1: path is under the engineering root — it IS (or is a file inside)
+  // the task directory. Some store records carry task.path pointing at a file
+  // inside the task dir (e.g. .../FORGE-S22-T04/PLAN.md) rather than the dir
+  // itself; in that case basename(path) is the filename, not the dir. Only
+  // trust Case 1 when its candidate resolves to a real directory on disk —
+  // otherwise fall through to the filesystem scan, which resolves by taskId.
   if (normalizedTaskPath && normalizedEngPath && normalizedTaskPath.startsWith(normalizedEngPath + '/')) {
-    return resultOk(path.basename(normalizedTaskPath));
+    const candidate = path.basename(normalizedTaskPath);
+    // Can't verify against disk — preserve legacy behaviour and trust the path.
+    if (!sprintDirPath) return resultOk(candidate);
+    const candidatePath = path.join(sprintDirPath, candidate);
+    // Trust Case 1 only when the candidate is a real directory. If it's a file
+    // (task.path pointed at a doc inside the dir) or absent, fall through to the
+    // filesystem scan below, which resolves the dir by taskId.
+    if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory()) {
+      return resultOk(candidate);
+    }
   }
 
   // Case 2 (and fallback for case 1 missing): filesystem scan

package/dist/forge-payload/tools/lib/artifact-kinds.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+// ── Canonical artifact-kind registry ─────────────────────────────────────────
+//
+// Single source of truth for artifact filenames, bug-mode filename overrides,
+// and the phase→kind mapping. Extracted from artifact.cjs per ADR
+// `doc/decisions/artifact-resolution-abstraction.md` (Phase 1) so that
+// artifact.cjs, store-cli.cjs (set-summary / set-bug-summary), and the
+// forge-cli `forge_artifact` surface all consume ONE catalog instead of
+// maintaining parallel copies.
+//
+// Renaming an artifact file is a one-line edit here.
+
+const ARTIFACT_CATALOG = {
+  'plan':                   { filename: 'PLAN.md',                    type: 'md' },
+  'plan-review':            { filename: 'PLAN_REVIEW.md',             type: 'md' },
+  'progress':               { filename: 'PROGRESS.md',                type: 'md' },
+  'code-review':            { filename: 'CODE_REVIEW.md',             type: 'md' },
+  'validation-report':      { filename: 'VALIDATION_REPORT.md',       type: 'md' },
+  'architect-approval':     { filename: 'ARCHITECT_APPROVAL.md',      type: 'md' },
+  'triage':                 { filename: 'TRIAGE.md',                  type: 'md' },
+  'bug-report':             { filename: 'BUG_REPORT.md',              type: 'md' },
+  'index':                  { filename: 'INDEX.md',                   type: 'md' },
+  'task-prompt':            { filename: 'TASK_PROMPT.md',             type: 'md' },
+  'sprint-requirements':    { filename: 'SPRINT_REQUIREMENTS.md',     type: 'md' },
+  'sprint-completion-review': { filename: 'SPRINT_COMPLETION_REVIEW.md', type: 'md' },
+  'cost-report':            { filename: 'COST_REPORT.md',             type: 'md' },
+  'timesheet':              { filename: 'TIMESHEET.md',               type: 'md' },
+  'plan-summary':           { filename: 'PLAN-SUMMARY.json',          type: 'json' },
+  'review-plan-summary':    { filename: 'REVIEW-PLAN-SUMMARY.json',   type: 'json' },
+  'implementation-summary': { filename: 'IMPLEMENTATION-SUMMARY.json', type: 'json' },
+  'review-code-summary':    { filename: 'REVIEW-CODE-SUMMARY.json',   type: 'json' },
+  'review-impl-summary':    { filename: 'REVIEW-IMPL-SUMMARY.json',   type: 'json' },
+  'validation-summary':     { filename: 'VALIDATION-SUMMARY.json',    type: 'json' },
+  'approve-summary':        { filename: 'APPROVE-SUMMARY.json',       type: 'json' },
+  'commit-summary':         { filename: 'COMMIT-SUMMARY.json',        type: 'json' },
+  'triage-summary':         { filename: 'TRIAGE-SUMMARY.json',        type: 'json' },
+  'writeback-summary':      { filename: 'WRITEBACK-SUMMARY.json',     type: 'json' },
+  'collation-summary':      { filename: 'COLLATION-SUMMARY.json',     type: 'json' },
+};
+
+// Per-entity filename overrides. Bug-mode plans and plan-summaries use the
+// BUG_FIX_PLAN prefix to match the long-standing forge convention and the
+// preflight-gate.cjs expectations for review-plan in bug mode. Without this
+// override, plan-fix (routed via plan_task.md post FORGE-BUG-040) writes
+// PLAN.md and review-plan preflight then fails "artifact missing:
+// BUG_FIX_PLAN.md" — see FORGE-BUG-041.
+const ARTIFACT_FILENAME_OVERRIDES = {
+  bug: {
+    'plan':         'BUG_FIX_PLAN.md',
+    'plan-summary': 'BUG-FIX-PLAN-SUMMARY.json',
+  },
+};
+
+// Phase → artifact-kind. Phases use underscore spellings (mirror of
+// store-helpers VALID_SUMMARY_PHASES); kinds use the hyphenated catalog keys.
+// This is the mapping set-summary / set-bug-summary use to self-resolve the
+// sidecar JSON file from a record's path, so callers never hand-build paths.
+const PHASE_TO_KIND = {
+  'plan':           'plan-summary',
+  'review_plan':    'review-plan-summary',
+  'implementation': 'implementation-summary',
+  'code_review':    'review-code-summary',
+  'validation':     'validation-summary',
+  'triage':         'triage-summary',
+  'approve':        'approve-summary',
+};
+
+function resolveArtifactFilename(entity, artifactName) {
+  const override = ARTIFACT_FILENAME_OVERRIDES[entity];
+  if (override && override[artifactName]) return override[artifactName];
+  const entry = ARTIFACT_CATALOG[artifactName];
+  if (!entry) throw new Error(`unknown artifact kind: ${artifactName}`);
+  return entry.filename;
+}
+
+// Resolve the phase-summary sidecar filename for an entity. Applies the
+// phase→kind map, then the per-entity filename override (so a bug's "plan"
+// summary becomes BUG-FIX-PLAN-SUMMARY.json).
+function resolveSummaryFilename(entity, phase) {
+  const kind = PHASE_TO_KIND[phase];
+  if (!kind) throw new Error(`unknown phase: ${phase}`);
+  return resolveArtifactFilename(entity, kind);
+}
+
+const ARTIFACT_NAMES = Object.keys(ARTIFACT_CATALOG).sort();
+
+module.exports = {
+  ARTIFACT_CATALOG,
+  ARTIFACT_FILENAME_OVERRIDES,
+  ARTIFACT_NAMES,
+  PHASE_TO_KIND,
+  resolveArtifactFilename,
+  resolveSummaryFilename,
+};

package/dist/forge-payload/tools/lib/store-nlp.cjs

@@ -99,6 +99,12 @@ function parseIntentNLP(intent) {
   outer:
   for (let i = 0; i < words.length; i++) {
     if (consumed.has(i)) continue;
+    // "with <entity>" (and "<entity> for") are FK-follow directives handled in
+    // Stage 4 — they must NOT be treated as the primary entity. Otherwise an
+    // explicit anchored ID (e.g. "WI-S19-T04 with sprint with feature") loses
+    // its entity to the follow-word, its filter is stripped as invalid, and the
+    // query degrades into a full-store scan.
+    if (i > 0 && words[i - 1] === 'with') continue;
     const w = words[i];
     if (i + 1 < words.length) {
       const bigram = w + ' ' + words[i + 1];

package/dist/forge-payload/tools/lib/store-query-exec.cjs

@@ -5,6 +5,14 @@ const path = require('path');
 const { extractExcerpt, loadForgeConfig, findIndexPath } = require('./store-facade.cjs');
 const { extractKeywordsFromIntent } = require('./store-nlp.cjs');
 
+// Default safety cap for NLP listings without an explicit limit. Prevents an
+// unbounded query from dumping the entire store into an LLM's context (a single
+// uncapped query consumed ~28% of a plan run's input tokens — see
+// doc/plans/store-query-nlp-response-shape-improvement.md). Callers that need
+// everything use the exact `--sprint`/`--task` flag paths (which bypass this) or
+// pass an explicit limit.
+const DEFAULT_NLP_LIMIT = 25;
+
 function escapeRe(s) {
   return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -128,7 +136,7 @@ function executeQuery(plan, store, cfg) {
   const trace = [];
   const traverse = plan.traverse || plan;
   const singMap = { bug: 'bugs', task: 'tasks', sprint: 'sprints', feature: 'features' };
-  const primary = singMap[traverse.primary] || traverse.primary || 'tasks';
+  let primary = singMap[traverse.primary] || traverse.primary || 'tasks';
   let filter = { ...(traverse.filter || {}) };
   const follow = traverse.follow || [];
   const kwMatch = traverse.keywordMatch || {};
@@ -138,6 +146,7 @@ function executeQuery(plan, store, cfg) {
 
   // Validate + strip invalid filters
   const validation = validatePlan(plan);
+  const stripped = {};
   if (validation.warnings.length > 0) {
     const validators = buildFieldValidators();
     const fields = validators[primary];
@@ -145,14 +154,17 @@ function executeQuery(plan, store, cfg) {
       for (const key of Object.keys(filter)) {
         if (!fields[key]) {
           trace.push(`stripped invalid filter key: ${key}`);
+          stripped[key] = filter[key];
           delete filter[key];
         } else {
           const spec = fields[key];
           if (spec instanceof RegExp && !spec.test(String(filter[key]))) {
             trace.push(`stripped filter ${key}="${filter[key]}" (value mismatch)`);
+            stripped[key] = filter[key];
             delete filter[key];
           } else if (Array.isArray(spec) && !spec.includes(String(filter[key]))) {
             trace.push(`stripped filter ${key}="${filter[key]}" (not in enum)`);
+            stripped[key] = filter[key];
             delete filter[key];
           }
         }
@@ -160,6 +172,21 @@ function executeQuery(plan, store, cfg) {
     }
   }
 
+  // Re-route on a stripped record-anchoring ID: an explicit taskId/bugId that
+  // was stripped because `primary` disagreed means the caller named a specific
+  // record. Honour it (re-route primary + restore the filter) instead of
+  // degrading into a full-collection scan. This is the engine-layer floor that
+  // backs up the parser fix in store-nlp.cjs.
+  const ID_ROUTE = { taskId: 'tasks', bugId: 'bugs' };
+  for (const idKey of Object.keys(ID_ROUTE)) {
+    if (stripped[idKey] !== undefined && primary !== ID_ROUTE[idKey]) {
+      trace.push(`re-routed primary ${primary} → ${ID_ROUTE[idKey]} (anchored ${idKey}="${stripped[idKey]}")`);
+      primary = ID_ROUTE[idKey];
+      filter[idKey] = stripped[idKey];
+      break;
+    }
+  }
+
   // List primary entities
   let entities;
   switch (primary) {
@@ -201,10 +228,16 @@ function executeQuery(plan, store, cfg) {
     return { query: cfg.query || '', path: 'intent-nlp', traversalTrace: trace, count: totalMatched, results: [], relatedFileRefs: [], totalMatched };
   }
 
-  // Limit
-  if (traverse.limit && entities.length > traverse.limit) {
-    trace.push(`limited to ${traverse.limit} (of ${totalMatched})`);
-    entities = entities.slice(0, traverse.limit);
+  // Limit — honour an explicit limit; otherwise apply a default safety cap so an
+  // unbounded NLP listing never dumps the whole collection into the model's
+  // context. `truncated` + `totalMatched` let the caller detect and, if needed,
+  // re-query with an explicit limit or the exact-flag path.
+  const effectiveLimit = traverse.limit || DEFAULT_NLP_LIMIT;
+  let truncated = false;
+  if (entities.length > effectiveLimit) {
+    trace.push(`limited to ${effectiveLimit} (of ${totalMatched})${traverse.limit ? '' : ' [default cap]'}`);
+    entities = entities.slice(0, effectiveLimit);
+    truncated = true;
   }
 
   // Build results + follow FKs
@@ -263,6 +296,7 @@ function executeQuery(plan, store, cfg) {
     results:        allResults,
     totalMatched,
     returned:       allResults.length,
+    truncated,
     limit:          traverse.limit || null,
     sort:           traverse.sort || null,
     relatedFileRefs: [...new Set(relatedFiles)],

package/dist/forge-payload/tools/lib/suggest.cjs

@@ -90,7 +90,8 @@ const DRIFT_MAP = {
   'task-completed': ['task-committed'],
   'implemented':    ['implementing'],
   'set':            ['set-summary'],
-  'start':          ['startTimestamp']
+  'start':          ['startTimestamp'],
+  'create':         ['write']
 };
 
 // ---------------------------------------------------------------------------

package/dist/forge-payload/tools/manage-config.cjs

@@ -418,7 +418,7 @@ if (subcmd === 'resolve-forge-root') {
 
   const { config } = readConfig();
   const forgeRef = getByPath(config, 'paths.forgeRef');
-  const forgeRoot = getByPath(config, 'paths.forgeRoot');
+  // Note: paths.forgeRoot read removed in FORGE-S29-T03 (Priority 3 deprecated).
 
   // Priority 2: Scan cache/marketplace directories by forgeRef
   if (forgeRef && typeof forgeRef === 'string') {
@@ -442,14 +442,12 @@ if (subcmd === 'resolve-forge-root') {
     }
   }
 
-  // Priority 3: Fallback to paths.forgeRoot (deprecated but still read)
-  if (forgeRoot && typeof forgeRoot === 'string') {
-    console.log(forgeRoot);
-    process.exit(0);
-  }
+  // Priority 3 (paths.forgeRoot fallback) removed — FORGE-S29-T03.
+  // paths.forgeRoot is deprecated and no longer used as a resolution fallback.
+  // Relying on it masks misconfigured projects and blocks the FORGE_ROOT retirement.
 
   // No resolution possible
-  console.error('× Cannot resolve Forge plugin root: no CLAUDE_PLUGIN_ROOT env var, no forgeRef cache match, and no forgeRoot in config.');
+  console.error('× Cannot resolve Forge plugin root: no CLAUDE_PLUGIN_ROOT env var and no forgeRef cache match. Run /forge:update to refresh.');
   process.exit(1);
 }
 

package/dist/forge-payload/tools/parse-gates.cjs

@@ -154,4 +154,76 @@ function parseAfter(rest, lineNo) {
   return { phase: m[1], verdict };
 }
 
-module.exports = { parseGates };
+// parseOutputs — same fence-scan logic as parseGates but for ```outputs phase=X blocks.
+// Closed grammar: only `artifact` and `require` directives are allowed.
+// Unknown directives throw (parity with parseGates).
+const OUTPUTS_FENCE_OPEN = /^```outputs\s+phase=([A-Za-z0-9_-]+)\s*$/;
+
+function parseOutputs(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return {};
+  const lines = markdown.split('\n');
+  const result = {};
+  let currentPhase = null;
+  let inFence = false;
+  let fenceStartLine = -1;
+  let fenceBuffer = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    if (!inFence) {
+      const m = line.match(OUTPUTS_FENCE_OPEN);
+      if (m) {
+        currentPhase = m[1];
+        if (result[currentPhase]) {
+          throw new Error(
+            `parse-gates: line ${lineNo}: duplicate outputs block for phase "${currentPhase}"`,
+          );
+        }
+        inFence = true;
+        fenceStartLine = lineNo;
+        fenceBuffer = [];
+      }
+      continue;
+    }
+    // Inside an outputs fence
+    if (FENCE_CLOSE.test(line)) {
+      result[currentPhase] = parseOutputsBlock(fenceBuffer, fenceStartLine);
+      inFence = false;
+      currentPhase = null;
+      fenceBuffer = [];
+      continue;
+    }
+    fenceBuffer.push({ text: line, lineNo });
+  }
+  if (inFence) {
+    throw new Error(`parse-gates: unterminated \`\`\`outputs fence opened at line ${fenceStartLine}`);
+  }
+  return result;
+}
+
+function parseOutputsBlock(bufferedLines, _fenceStartLine) {
+  const spec = { artifacts: [], require: [] };
+  for (const { text, lineNo } of bufferedLines) {
+    const trimmed = text.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const firstSpace = trimmed.search(/\s/);
+    if (firstSpace < 0) {
+      throw new Error(`parse-gates: line ${lineNo}: malformed directive "${trimmed}"`);
+    }
+    const directive = trimmed.slice(0, firstSpace);
+    const rest = trimmed.slice(firstSpace + 1).trim();
+    switch (directive) {
+      case 'artifact':
+        spec.artifacts.push(parseArtifact(rest, lineNo));
+        break;
+      case 'require':
+        spec.require.push(parsePredicate(rest, lineNo));
+        break;
+      default:
+        throw new Error(`parse-gates: line ${lineNo}: unknown directive "${directive}"`);
+    }
+  }
+  return spec;
+}
+
+module.exports = { parseGates, parseOutputs };