@entelligentsia/forgecli 1.0.2 → 1.0.10

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

@@ -14,37 +14,26 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
 const { findProjectRoot } = require('./lib/project-root.cjs');
 
 // ── Artifact catalog ─────────────────────────────────────────────────────────
-
-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' },
-  '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' },
-};
-
-const ARTIFACT_NAMES = Object.keys(ARTIFACT_CATALOG).sort();
+//
+// The catalog, bug-mode overrides, and filename resolution now live in the
+// canonical registry at lib/artifact-kinds.cjs (ADR artifact-resolution Phase 1),
+// consumed here and by store-cli.cjs so there is ONE source of truth.
+const {
+  ARTIFACT_CATALOG,
+  ARTIFACT_FILENAME_OVERRIDES,
+  ARTIFACT_NAMES,
+  resolveArtifactFilename,
+} = require('./lib/artifact-kinds.cjs');
+
+// The provider seam (ArtifactStore/FsArtifactImpl) and entity-dir resolution
+// live in artifact-store.cjs (ADR Phase 3). This CLI is a thin layer over the
+// facade: it owns arg parsing, @-file expansion, JSON validation, and display;
+// all filesystem access goes through the provider.
+const artifactStore = require('./artifact-store.cjs');
+const { ArtifactStore, FsArtifactImpl, resolveEntityDir } = artifactStore;
 
 // ── Summary JSON validation ──────────────────────────────────────────────────
 
@@ -66,66 +55,6 @@ function validateSummaryJson(content) {
   return null;
 }
 
-// ── Entity path resolution ───────────────────────────────────────────────────
-
-/** Read a store record via store-cli and return its `path` field, or null on failure. */
-function readStorePath(entity, entityId, toolDir, projectRoot) {
-  const cliPath = path.join(toolDir, 'store-cli.cjs');
-  try {
-    const result = execFileSync('node', [cliPath, 'read', entity, entityId, '--json'], {
-      cwd: projectRoot,
-      encoding: 'utf8',
-      timeout: 10_000,
-    });
-    const record = JSON.parse(result);
-    if (typeof record.path === 'string' && record.path.length > 0) {
-      // Defensive: if the path ends with a file extension, the store record
-      // was written with a filename (e.g. "…/PROGRESS.md") instead of the
-      // directory. Strip the trailing filename to get the entity directory.
-      const p = record.path;
-      if (/\.(md|json)$/i.test(p)) return path.dirname(p);
-      return p;
-    }
-  } catch (_) {
-    // Store unavailable or record not found — fall through.
-  }
-  return null;
-}
-
-/**
- * Resolve entity directory using the store record's `path` field when available,
- * falling back to ID-only construction.
- */
-function resolveEntityDir(entity, entityId, engineeringPath, toolDir, projectRoot) {
-  switch (entity) {
-    case 'bug': {
-      const storePath = readStorePath('bug', entityId, toolDir, projectRoot);
-      if (storePath) return storePath;
-      return path.join(engineeringPath, 'bugs', entityId);
-    }
-    case 'sprint': {
-      const storePath = readStorePath('sprint', entityId, toolDir, projectRoot);
-      if (storePath) return storePath;
-      return path.join(engineeringPath, 'sprints', entityId);
-    }
-    case 'task': {
-      const storePath = readStorePath('task', entityId, toolDir, projectRoot);
-      if (storePath) return storePath;
-      // Fallback: derive from sprint prefix + sprint record path.
-      const match = entityId.match(/^(.+-S\d+)-T\d+$/);
-      if (!match) return null;
-      const sprintId = match[1];
-      const sprintPath = readStorePath('sprint', sprintId, toolDir, projectRoot);
-      if (sprintPath) {
-        return path.join(sprintPath, entityId);
-      }
-      return path.join(engineeringPath, 'sprints', sprintId, entityId);
-    }
-    default:
-      return null;
-  }
-}
-
 // ── CLI ───────────────────────────────────────────────────────────────────────
 
 if (require.main === module) {
@@ -141,6 +70,9 @@ if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
     '  read <entity> <entityId> <artifact>         Read artifact content',
     '  write <entity> <entityId> <artifact> <content|@file>',
     '                                              Write artifact (content or @/path/to/file)',
+    '  exists <entity> <entityId> <artifact>       Exit 0 if present, 2 if absent',
+    '  url <entity> <entityId> <artifact>          Print the backend URL (file:// for fs)',
+    '  delete <entity> <entityId> <artifact>       Delete an artifact',
     '',
     'Entities: task, bug, sprint',
     `Known artifacts: ${ARTIFACT_NAMES.join(', ')}`,
@@ -189,6 +121,14 @@ if (!entityDir) {
 
 const absDir = path.resolve(projectRoot, entityDir);
 
+// Provider instance — all filesystem access for read/write/exists/url/delete
+// goes through the facade (ADR Phase 3). Wired with the already-resolved dir so
+// the CLI and the provider agree on location without a second store read.
+const store = new ArtifactStore(new FsArtifactImpl({
+  projectRoot, engineeringPath, toolDir,
+  resolveDir: () => entityDir,
+}));
+
 // ── list ────────────────────────────────────────────────────────────────────
 
 if (subcmd === 'list') {
@@ -200,7 +140,13 @@ if (subcmd === 'list') {
   const known = [];
   const other = [];
   for (const f of files) {
-    const catalogEntry = Object.entries(ARTIFACT_CATALOG).find(([, v]) => v.filename === f);
+    // Recognise the per-entity overrides as well, so e.g. BUG_FIX_PLAN.md
+    // surfaces as the `plan` artifact in bug-mode listings.
+    const overrideEntry = ARTIFACT_FILENAME_OVERRIDES[entity]
+      ? Object.entries(ARTIFACT_FILENAME_OVERRIDES[entity]).find(([, fn]) => fn === f)
+      : undefined;
+    const catalogEntry = overrideEntry
+      || Object.entries(ARTIFACT_CATALOG).find(([, v]) => v.filename === f);
     if (catalogEntry) {
       known.push(`  ${catalogEntry[0]} → ${f}`);
     } else {
@@ -233,16 +179,42 @@ if (!catalogEntry) {
   process.exit(1);
 }
 
-const filePath = path.join(absDir, catalogEntry.filename);
+const resolvedFilename = resolveArtifactFilename(entity, artifactName);
+const displayPath = path.join(entityDir, resolvedFilename);
+const handle = { entity, entityId, kind: artifactName };
 
 // ── read ─────────────────────────────────────────────────────────────────────
 
 if (subcmd === 'read') {
-  if (!fs.existsSync(filePath)) {
-    process.stderr.write(`Artifact not found: ${path.join(entityDir, catalogEntry.filename)}\n`);
+  if (!store.exists(handle)) {
+    process.stderr.write(`Artifact not found: ${displayPath}\n`);
     process.exit(2);
   }
-  process.stdout.write(fs.readFileSync(filePath, 'utf8'));
+  process.stdout.write(store.read(handle));
+  process.exit(0);
+}
+
+// ── exists ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'exists') {
+  // Boolean check: always exit 0 with a "true"/"false" token so callers
+  // (including the forge-cli subprocess surface) never treat absence as an error.
+  process.stdout.write(store.exists(handle) ? 'true\n' : 'false\n');
+  process.exit(0);
+}
+
+// ── url ────────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'url') {
+  process.stdout.write(store.url(handle) + '\n');
+  process.exit(0);
+}
+
+// ── delete ─────────────────────────────────────────────────────────────────────
+
+if (subcmd === 'delete') {
+  const removed = store.delete(handle);
+  process.stdout.write(removed ? `Deleted ${displayPath}\n` : `Nothing to delete: ${displayPath}\n`);
   process.exit(0);
 }
 
@@ -272,22 +244,19 @@ if (subcmd === 'write') {
     const validationError = validateSummaryJson(content);
     if (validationError) {
       process.stderr.write(
-        `Summary validation failed for ${catalogEntry.filename}: ${validationError}. ` +
+        `Summary validation failed for ${resolvedFilename}: ${validationError}. ` +
         `Required fields: ${SUMMARY_REQUIRED.join(', ')}.\n`
       );
       process.exit(1);
     }
   }
 
-  fs.mkdirSync(absDir, { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(
-    `Wrote ${Buffer.byteLength(content, 'utf8')} bytes to ${path.join(entityDir, catalogEntry.filename)}\n`
-  );
+  const res = store.write(handle, content);
+  process.stdout.write(`Wrote ${res.bytes} bytes to ${displayPath}\n`);
   process.exit(0);
 }
 
-process.stderr.write(`Unknown subcommand: ${subcmd}. Valid: list, read, write\n`);
+process.stderr.write(`Unknown subcommand: ${subcmd}. Valid: list, read, write, exists, url, delete\n`);
 process.exit(1);
 
 } // end if (require.main === module)

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/preflight-gate.cjs

@@ -113,7 +113,49 @@ function describePredicate(pred) {
   return `${pred.field} ${pred.op} ${pred.value}`;
 }
 
-module.exports = { preflight, resolveTaskArtifactDir, resolveSprintArtifactDir };
+module.exports = { preflight, resolveTaskArtifactDir, resolveSprintArtifactDir, deriveSprintTaskFromArtifactPath };
+
+// Derive {sprint} and {task} substitutions directly from a task's artifact path
+// (task.path) when that path is a directory under `<engineeringRoot>/sprints/`.
+//
+// task.path is the authoritative artifact location — it is where the plan /
+// implement phases actually write PLAN.md, REVIEW.md, etc. Splitting it tolerates
+// ANY nesting depth and ANY on-disk naming, so a single rule covers both the
+// modern 2-level layout (`sprints/<sprint>/<task>/`) and legacy 3-level layouts
+// (`sprints/<sprint>/tasks/<task>/`) whose on-disk sprint dir name need not equal
+// sprintId (e.g. sprintId "S19" → dir "sprint_19_platform_ux_improvements"). The
+// directory-scan resolution (resolveSprintArtifactDir + resolveTaskArtifactDir)
+// cannot express the `tasks/` nesting, which is what broke review-plan preflight
+// for heterogeneous-layout projects (walkinto.in S19/S32/S33).
+//
+//   {task}   = the last path segment (the artifact directory name)
+//   {sprint} = everything between `sprints/` and that last segment, joined by "/"
+//
+// File-vs-dir guard: if task.path ends in a filename (has an extension), the
+// artifact directory is its PARENT — strip the filename first. This prevents the
+// bogus `.../TASK_PROMPT.md/PLAN.md` (ENOTDIR) seen when a project stores
+// task.path as a file inside the artifact dir.
+//
+// Returns null when the path is absent, or not under `<engineeringRoot>/sprints/`
+// (e.g. a forge/ source-file path — see regression S12-T06), or resolves to
+// fewer than 2 directory segments. In every null case the caller falls back to
+// the directory-scan resolution, preserving prior behaviour.
+function deriveSprintTaskFromArtifactPath(taskPath, engineeringRoot) {
+  if (!taskPath) return null;
+  let norm = String(taskPath).replace(/\\/g, '/').replace(/\/+$/, '');
+  // File-vs-dir guard — drop a trailing filename so we split on the dir.
+  if (/\.[a-zA-Z0-9]+$/.test(norm)) {
+    norm = norm.replace(/\/[^/]*$/, '');
+  }
+  const er = String(engineeringRoot || 'engineering').replace(/\/+$/, '');
+  const prefix = er + '/sprints/';
+  if (!norm.startsWith(prefix)) return null;
+  const segs = norm.slice(prefix.length).split('/').filter(Boolean);
+  if (segs.length < 2) return null;
+  const task = segs[segs.length - 1];
+  const sprint = segs.slice(0, -1).join('/');
+  return { sprint, task };
+}
 
 // CLI shim: `node preflight-gate.cjs --phase <name> --task <taskId> [--bug <bugId>] [--workflow <name>]`
 // exit codes: 0 ok, 1 gate(s) failed, 2 invalid args / missing definitions
@@ -246,10 +288,18 @@ if (require.main === module) {
   // name is used both as the {sprint} substitution and as the directory in
   // which resolveTaskArtifactDir scans for task subdirectories.
   const sprintId = taskRecord ? taskRecord.sprintId : undefined;
-  const resolvedSprintDir = sprintId
-    ? (resolveSprintArtifactDir(sprintId, engineeringRoot) || sprintId)
-    : undefined;
-  const taskArtifactDir = resolveTaskArtifactDir(taskRecord, engineeringRoot, undefined, resolvedSprintDir);
+  // Primary resolution: derive {sprint}/{task} straight from task.path (the
+  // authoritative artifact directory). This honours arbitrary layout nesting —
+  // including legacy 3-level `sprints/<sprint>/tasks/<task>/` trees the
+  // directory-scan resolution below cannot express. Falls back to the scan when
+  // task.path is not an artifact dir under sprints/ (e.g. a forge/ source file).
+  const derived = taskRecord ? deriveSprintTaskFromArtifactPath(taskRecord.path, engineeringRoot) : null;
+  const resolvedSprintDir = derived
+    ? derived.sprint
+    : (sprintId ? (resolveSprintArtifactDir(sprintId, engineeringRoot) || sprintId) : undefined);
+  const taskArtifactDir = derived
+    ? derived.task
+    : resolveTaskArtifactDir(taskRecord, engineeringRoot, undefined, resolvedSprintDir);
   // Fallback: if task.path points to a file (e.g., TASK_PROMPT.md) we want
   // the *directory* segment, not the filename. Without this, a project that
   // stores task.path as the prompt file would propagate "TASK_PROMPT.md" as

package/dist/forge-payload/tools/store-cli.cjs

@@ -55,6 +55,7 @@ const { validateRecord, NULLABLE_FIELDS } = require('./lib/validate.js');
 
 // FORGE-S22-T03: suggestion engine for "Did you mean?" on validation/transition errors
 const { suggest, suggestEntityType, formatSuggestion } = require('./lib/suggest.cjs');
+const { resolveSummaryFilename, PHASE_TO_KIND } = require('./lib/artifact-kinds.cjs');
 
 // Valid phase keys for summaries (dot-delimited → underscore in JSON key)
 const VALID_SUMMARY_PHASES = new Set(['plan', 'review_plan', 'implementation', 'code_review', 'validation', 'triage', 'approve']);
@@ -432,8 +433,8 @@ Commands:
   progress-clear <sprintOrBugId>              Clear (truncate) the progress log
   write-collation-state '<json>'             Write COLLATION_STATE.json
   validate <entity> '<json>'                  Validate against schema without writing
-  set-summary <taskId> <phase> <jsonFile>     Set a phase summary on a task record
-  set-bug-summary <bugId> <phase> <jsonFile>  Set a phase summary on a bug record
+  set-summary <taskId> <phase> [<jsonFile>]     Set a phase summary on a task record (sidecar auto-resolved from record.path when jsonFile omitted)
+  set-bug-summary <bugId> <phase> [<jsonFile>]  Set a phase summary on a bug record (sidecar auto-resolved from record.path when jsonFile omitted)
   describe <entity>                           Print the JSON Schema for an entity
   template <entity>                           Print a canonical sample record (required fields populated)
 
@@ -1289,9 +1290,50 @@ function _setSummaryOnEntity(entityKind, entityId, phase, summaryFilePath) {
     process.exit(1);
   }
 
+  // Load entity first — its `path` is the authoritative artifact directory and
+  // is needed both to self-resolve the sidecar (when no file arg is given) and
+  // to merge the summary below.
+  const record = entityKind === 'task' ? store.getTask(entityId) : store.getBug(entityId);
+  if (!record) {
+    console.error(`${entityKind} not found: ${entityId}`);
+    process.exit(1);
+  }
+
+  // ADR artifact-resolution Phase 1: when the caller omits the JSON file, derive
+  // the sidecar from record.path + the canonical phase→filename map. The agent
+  // never hand-builds the path (kills the Class-1 failures + the arity bug).
+  let selfResolved = false;
+  if (!summaryFilePath) {
+    if (typeof record.path !== 'string' || record.path.length === 0) {
+      console.error(`Cannot self-resolve summary sidecar: ${entityKind} ${entityId} has no "path". Pass an explicit <jsonFile>.`);
+      process.exit(1);
+    }
+    // record.path is the entity directory; defensively strip a trailing filename.
+    const dir = /\.(md|json)$/i.test(record.path) ? path.dirname(record.path) : record.path;
+    summaryFilePath = path.join(dir, resolveSummaryFilename(entityKind, phase));
+    selfResolved = true;
+  }
+
   // Read and validate summary JSON
   if (!fs.existsSync(summaryFilePath)) {
-    console.error(`Summary file not found: ${summaryFilePath}`);
+    // v1.0.10: self-resolve looks for the CANONICAL filename. If an agent wrote a
+    // non-canonical sidecar (e.g. VALIDATE-SUMMARY.json via the Write tool instead
+    // of forge_artifact's VALIDATION-SUMMARY.json), surface the near-name file so
+    // the error is fixable in one step rather than a silent dead-end.
+    let hint = '';
+    if (selfResolved) {
+      try {
+        const dir = path.dirname(summaryFilePath);
+        const expected = path.basename(summaryFilePath);
+        const nearby = fs.readdirSync(dir).filter((f) => f !== expected && f.endsWith('.json') && /summary/i.test(f));
+        if (nearby.length > 0) {
+          const kind = PHASE_TO_KIND[phase];
+          hint = ` (expected ${expected}; found ${nearby.join(', ')} in the same dir — write the sidecar via ` +
+            `forge_artifact artifact:"${kind}", or rename it to ${expected})`;
+        }
+      } catch (_) { /* dir unreadable — fall back to the plain message */ }
+    }
+    console.error(`Summary file not found: ${summaryFilePath}${hint}`);
     process.exit(1);
   }
 
@@ -1309,14 +1351,7 @@ function _setSummaryOnEntity(entityKind, entityId, phase, summaryFilePath) {
     process.exit(1);
   }
 
-  // Load entity
-  const record = entityKind === 'task' ? store.getTask(entityId) : store.getBug(entityId);
-  if (!record) {
-    console.error(`${entityKind} not found: ${entityId}`);
-    process.exit(1);
-  }
-
-  // Merge summary
+  // Merge summary (record was loaded above for path resolution)
   if (!record.summaries) record.summaries = {};
   record.summaries[phase] = summary;
 
@@ -1394,8 +1429,8 @@ function cmdSetSummary() {
   const phase       = args[2];
   const summaryFile = args[3];
 
-  if (!taskId || !phase || !summaryFile) {
-    console.error('Usage: store-cli.cjs set-summary <taskId> <phase> <jsonFile>');
+  if (!taskId || !phase) {
+    console.error('Usage: store-cli.cjs set-summary <taskId> <phase> [<jsonFile>]');
     process.exit(1);
   }
 
@@ -1407,8 +1442,8 @@ function cmdSetBugSummary() {
   const phase       = args[2];
   const summaryFile = args[3];
 
-  if (!bugId || !phase || !summaryFile) {
-    console.error('Usage: store-cli.cjs set-bug-summary <bugId> <phase> <jsonFile>');
+  if (!bugId || !phase) {
+    console.error('Usage: store-cli.cjs set-bug-summary <bugId> <phase> [<jsonFile>]');
     process.exit(1);
   }