@entelligentsia/forgecli 1.0.14 → 1.0.21

package/dist/extensions/forgecli/store/store-error-remediation.js

@@ -0,0 +1,307 @@
+// Store-error remediation — forge-cli#24
+// Moved from lib/store-error-remediation.ts to root by FORGE-S25-T22 (S-7: single-file lib/ dir).
+//
+// Shared remediation-hint surface for store validation errors.
+// Consumed by:
+//   - health-check.ts (per-error row in store-integrity output)
+//   - hooks/write-guard.ts (block-message body for schema violations)
+//   - hook-dispatcher.ts (store-cli intercept block messages)
+//   - store-validator.ts (structured result for hook callers)
+//
+// Error sources:
+//   1. validate.js (in-process via write-guard) — produces error strings like:
+//        "status: value "verified" not in [reported, triaged, in-progress, fixed]"
+//        "taskId: missing required field"
+//        "xyz: undeclared field"
+//   2. store-cli.cjs validate (subprocess via store-validator.ts) — same format,
+//      piped through stderr.
+//   3. validate-store.cjs --dry-run (subprocess via health-check.ts) — lines like:
+//        "ERROR  FORGE-S18-T02: status: value "verified" not in [reported, triaged, ...]"
+//        "WARN   FORGE-S18-T02: ..."
+//
+// This module parses those formats and returns a one-line user-facing hint
+// plus an optional copy-pasteable store-cli command.
+// ── Entity-type inference from entity name / ID ────────────────────────────────
+/** Map entity type to the corresponding schema's status enum values. */
+const STATUS_ENUMS = {
+    task: [
+        "draft",
+        "planned",
+        "plan-approved",
+        "implementing",
+        "implemented",
+        "review-approved",
+        "approved",
+        "committed",
+        "plan-revision-required",
+        "code-revision-required",
+        "blocked",
+        "escalated",
+        "abandoned",
+    ],
+    sprint: ["planning", "active", "completed", "retrospective-done", "partially-completed", "blocked", "abandoned"],
+    bug: ["reported", "triaged", "in-progress", "fixed"],
+    feature: ["proposed", "accepted", "in-progress", "delivered", "declined"],
+    event: [], // no status field
+};
+/** Known entity types that support write via store-cli. */
+const ENTITY_TYPES = new Set(["task", "sprint", "bug", "feature", "event"]);
+/**
+ * Infer the entity type from an entity name/ID string.
+ * Returns "task" as default if no match.
+ */
+export function inferEntityType(entity) {
+    const lower = entity.toLowerCase();
+    // Bug patterns: BUG-015, FORGE-BUG-015, bug-031
+    if (/\bbug/i.test(entity))
+        return "bug";
+    // Sprint patterns: S18 (standalone), sprint-01 — but NOT inside task IDs like FORGE-S18-T02
+    if (/^[A-Z]+-S\d+$/i.test(entity) || /\bsprint/i.test(entity))
+        return "sprint";
+    // Feature patterns: FORGE-F01
+    if (/\bf\d+\b/i.test(entity) || lower.includes("feat"))
+        return "feature";
+    // Event patterns
+    if (lower.includes("event"))
+        return "event";
+    // Task IDs: FORGE-S18-T02, PROJECT-T01
+    if (/\bt\d+\b/i.test(entity))
+        return "task";
+    // Default
+    return "task";
+}
+const STATUS_REMEDIATION = {
+    hint: "Set status to one of the legal values for this entity type.",
+    command: (entityType, entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <legal-value>`,
+};
+const REQUIRED_FIELD_REMEDIATION = {
+    hint: "Add the missing field with a valid value. Use the template command to see the canonical shape.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+};
+const UNDECLARED_FIELD_REMEDIATION = {
+    hint: "Remove the undeclared field, or check the schema for the correct property name.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const TYPE_MISMATCH_REMEDIATION = {
+    hint: "Use the correct type for this field. Use the describe command to see the expected type.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const PATTERN_REMEDIATION = {
+    hint: "The value must match the expected pattern (e.g. a date-time or ID format).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const DATE_TIME_REMEDIATION = {
+    hint: "Use an ISO 8601 date-time string (e.g. 2026-05-21T12:00:00Z).",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+const LENGTH_REMEDIATION = {
+    hint: "Adjust the value length to satisfy the schema constraint.",
+    command: (entityType, _entityId) => `node "$FORGE_ROOT/tools/store-cli.cjs" describe ${entityType}`,
+};
+/**
+ * Parse a single validation error line from validate.js / store-cli.
+ *
+ * Examples:
+ *   'status: value "verified" not in [reported, triaged, in-progress, fixed]'
+ *   'taskId: missing required field'
+ *   'xyz: undeclared field'
+ *   'sprintId: expected string, got number'
+ *   'title: value length 0 is below minLength 1'
+ *   'createdAt: value "today" is not a valid date-time'
+ *   'prefix: value "AB" does not match pattern ^[A-Z]+-[A-Z]$'
+ */
+export function parseValidationError(line) {
+    // Enum violation: 'field: value "X" not in [a, b, c]'
+    const enumMatch = line.match(/^(\w+):\s+value\s+"([^"]+)"\s+not in \[([^\]]+)\]/);
+    if (enumMatch) {
+        return {
+            field: enumMatch[1],
+            errorKind: "enum",
+            observed: enumMatch[2],
+            enumValues: enumMatch[3].split(",").map((s) => s.trim()),
+        };
+    }
+    // Required field: 'field: missing required field'
+    if (/\bmissing required field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "required" };
+    }
+    // Undeclared field: 'xyz: undeclared field'
+    if (/\bundeclared field\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "undeclared" };
+    }
+    // Type mismatch: 'field: expected string, got number'
+    const typeMatch = line.match(/^(\w+):\s+expected\s+\S+,?\s+got\s+\S+/);
+    if (typeMatch) {
+        return { field: typeMatch[1], errorKind: "type" };
+    }
+    // Date-time format: 'field: value "..." is not a valid date-time'
+    if (/\bis not a valid date-time\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "datetime" };
+    }
+    // Pattern mismatch: 'field: value "..." does not match pattern ...'
+    if (/\bdoes not match pattern\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "pattern" };
+    }
+    // Length violations
+    if (/\blength\b.*\b(exceeds|below)\b/.test(line) || /\b(exceeds|below)\b.*\blength\b/.test(line)) {
+        const fieldMatch = line.match(/^(\w+):/);
+        return { field: fieldMatch?.[1] ?? "unknown", errorKind: "length" };
+    }
+    // Generic: capture leading field name if present
+    const genericMatch = line.match(/^(\w+):/);
+    return { field: genericMatch?.[1] ?? "unknown", errorKind: "other" };
+}
+// ── Public API ──────────────────────────────────────────────────────────────────
+/**
+ * Given a single validation error line (from validate.js or store-cli),
+ * return a user-facing remediation hint and optional copy-pasteable command.
+ *
+ * @param errorLine  A single error line from validate.js / store-cli output.
+ * @param entityType  The entity type (task, sprint, bug, feature, event).
+ * @param entityId   The entity ID (e.g. "FORGE-S18-T02") — used for commands.
+ * @returns          RemediationResult with hint and command.
+ */
+export function remediateError(errorLine, entityType, entityId) {
+    const parsed = parseValidationError(errorLine);
+    switch (parsed.errorKind) {
+        case "enum": {
+            const legalValues = STATUS_ENUMS[entityType] ?? parsed.enumValues ?? [];
+            const isStatusField = parsed.field === "status" || parsed.field.toLowerCase().includes("status");
+            if (isStatusField && legalValues.length > 0) {
+                return {
+                    hint: `"${parsed.observed}" is not a legal ${entityType} status. Legal values: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" update-status ${entityType} ${entityId} status <${legalValues.join("|")}>`,
+                };
+            }
+            if (legalValues.length > 0) {
+                return {
+                    hint: `Invalid value for "${parsed.field}". Allowed: ${legalValues.join(", ")}.`,
+                    command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+                };
+            }
+            return {
+                hint: STATUS_REMEDIATION.hint,
+                command: STATUS_REMEDIATION.command(entityType, entityId),
+            };
+        }
+        case "required":
+            return {
+                hint: REQUIRED_FIELD_REMEDIATION.hint,
+                command: REQUIRED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "undeclared":
+            return {
+                hint: UNDECLARED_FIELD_REMEDIATION.hint,
+                command: UNDECLARED_FIELD_REMEDIATION.command(entityType, entityId),
+            };
+        case "type":
+            return {
+                hint: TYPE_MISMATCH_REMEDIATION.hint,
+                command: TYPE_MISMATCH_REMEDIATION.command(entityType, entityId),
+            };
+        case "datetime":
+            return {
+                hint: DATE_TIME_REMEDIATION.hint,
+                command: DATE_TIME_REMEDIATION.command(entityType, entityId),
+            };
+        case "pattern":
+            return {
+                hint: PATTERN_REMEDIATION.hint,
+                command: PATTERN_REMEDIATION.command(entityType, entityId),
+            };
+        case "length":
+            return {
+                hint: LENGTH_REMEDIATION.hint,
+                command: LENGTH_REMEDIATION.command(entityType, entityId),
+            };
+        case "other":
+        default:
+            return {
+                hint: "Check the schema for the expected shape.",
+                command: `node "$FORGE_ROOT/tools/store-cli.cjs" template ${entityType}`,
+            };
+    }
+}
+/**
+ * Parse a multi-line validation output (e.g. from store-cli validate or
+ * validate-store --dry-run) into individual error lines and return
+ * remediation for each.
+ *
+ * @param output    Raw multi-line output from validation tool.
+ * @param entityType Override entity type (inferred from output if not provided).
+ * @returns         Array of { errorLine, remediation } objects.
+ */
+export function remediateValidationOutput(output, entityType) {
+    const lines = output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    const results = [];
+    for (const line of lines) {
+        // Strip "ERROR" / "WARN" prefix from validate-store --dry-run output
+        const cleaned = line.replace(/^(ERROR|WARN)\s+/, "");
+        if (!cleaned)
+            continue;
+        // Extract entity ID from lines like "FORGE-S18-T02: status: ..."
+        const entityIdMatch = cleaned.match(/^([A-Z]+-S?\d+-T?\d+|[A-Z]+-BUG-\d+|[A-Z]+-F\d+):/);
+        const entityId = entityIdMatch?.[1] ?? "unknown";
+        // If entity type not overridden, try to infer
+        const inferredType = entityType ?? inferEntityType(entityId);
+        // Skip non-error lines (hint lines from validate.js, blank lines, etc.)
+        if (cleaned.startsWith("(") || cleaned.startsWith("hint:") || cleaned.startsWith("#")) {
+            continue;
+        }
+        // Skip lines that are just an entity name without an error field
+        // (the real error is on the same line after the entity prefix)
+        const errorPart = entityIdMatch ? cleaned.slice(entityIdMatch[0].length).trim() : cleaned;
+        if (!errorPart || errorPart.length < 3)
+            continue;
+        results.push({
+            errorLine: cleaned,
+            remediation: remediateError(errorPart, inferredType, entityId),
+        });
+    }
+    return results;
+}
+/**
+ * Format a block message for a write-guard violation, appending remediation hints.
+ * Used by hook-dispatcher.ts for store-cli intercept blocks.
+ *
+ * @param rawReason  The raw reason string from validateStoreCLIPayload or checkWriteGuard.
+ * @param entityType  The entity type if known.
+ * @param entityId   The entity ID if known.
+ * @returns          Enhanced reason string with remediation hints appended.
+ */
+export function enhanceBlockMessage(rawReason, entityType, entityId) {
+    // Parse the raw reason into lines and try to add remediation to each error line.
+    const lines = rawReason.split("\n");
+    const enhanced = [];
+    for (const line of lines) {
+        // Strip leading list markers and bullet points
+        const stripped = line.replace(/^\s*[-•]\s*/, "").trim();
+        // Check if this line contains a recognizable validation error pattern
+        const parsed = parseValidationError(stripped);
+        // Also match lines that contain validation error patterns not caught by parseValidationError
+        const hasKnownError = parsed.errorKind !== "other" ||
+            /\bmissing required\b|\bnot in \[|\bundeclared\b|\bexpected\b.*\bgot\b/.test(stripped);
+        if (hasKnownError) {
+            const type = entityType ?? "task";
+            const id = entityId ?? "unknown";
+            const remediation = remediateError(stripped, type, id);
+            enhanced.push(line);
+            enhanced.push(`  💡 ${remediation.hint}`);
+            if (remediation.command) {
+                enhanced.push(`  → ${remediation.command}`);
+            }
+        }
+        else {
+            enhanced.push(line);
+        }
+    }
+    return enhanced.join("\n");
+}
+//# sourceMappingURL=store-error-remediation.js.map

package/dist/extensions/forgecli/store/store-error-remediation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-error-remediation.js","sourceRoot":"","sources":["../../../../src/extensions/forgecli/store/store-error-remediation.ts"],"names":[],"mappings":"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"}

package/dist/extensions/forgecli/store/store-resolver.d.ts

@@ -0,0 +1,56 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+export declare const ENTITY_TYPES: Set<string>;
+export declare const ID_PATTERNS: {
+    task: RegExp;
+    sprint: RegExp;
+    bug: RegExp;
+    feature: RegExp;
+    bareTask: RegExp;
+    idFragment: RegExp;
+};
+export type ResolverHit = {
+    dir: string;
+} | {
+    item: any;
+};
+export interface ResolveOptions {
+    entityTypes?: Set<string>;
+    ctx?: ExtensionCommandContext;
+    statusLabel?: string;
+}
+export declare function isDebug(): boolean;
+export declare function resolveToolDir(forgeRoot: string): string;
+export declare function runStoreCli(toolDir: string, argv: string[], cwd: string): Promise<any>;
+/**
+ * Try store-cli's native --task-suffix / --sprint-suffix flags. Returns:
+ *   - results array on success
+ *   - null if the flag is unsupported (older store-cli) — caller should fall back
+ */
+export declare function suffixMatch(toolDir: string, cwd: string, kind: "task" | "sprint", suffix: string): Promise<any[] | null>;
+/**
+ * Resolution cascade:
+ *   1. @path        → use the path directly as artifact directory
+ *   2. Canonical ID → store-cli query --task/--bug/--feature/--sprint
+ *   3. ID suffix    → --task-suffix / --sprint-suffix (one call) with loop fallback
+ *   4. Keyword      → store-cli query --keyword (title substring)
+ *   5. NLP fallback → store-cli nlp "<query>"
+ */
+export declare function resolveEntityRef(arg: string, toolDir: string, cwd: string, opts?: ResolveOptions): Promise<ResolverHit | null>;
+export interface ResolveToCanonicalIdOptions {
+    /** Which entity types to search. Defaults to a single-element set matching `kind`. */
+    entityTypes?: Set<string>;
+    /** Command label used in error messages (e.g. "forge:run-task"). */
+    commandLabel?: string;
+}
+/**
+ * Resolve a raw user arg to a canonical entity ID string.
+ *
+ * 1. If the arg is already a canonical ID that resolves directly → return it.
+ * 2. If the arg is an unprefixed ID (e.g. "S22-T03") → suffix-match or
+ *    prefix-normalize to the canonical form → return it.
+ * 3. If the arg is ambiguous → prompt the user (or hard-fail in non-interactive).
+ * 4. If the arg cannot be resolved → emit an actionable error and return null.
+ */
+export declare function resolveToCanonicalId(arg: string, toolDir: string, cwd: string, kind: "task" | "sprint" | "bug" | "feature", opts: ResolveToCanonicalIdOptions & {
+    ctx?: ExtensionCommandContext;
+}): Promise<string | null>;

package/dist/extensions/forgecli/store/store-resolver.js

@@ -0,0 +1,263 @@
+// store-resolver.ts — Shared store-cli resolver for `@path` / canonical ID /
+// ID-suffix / keyword / NLP cascade. Used by /forge:read, /forge:run-task,
+// /forge:run-sprint, /forge:fix-bug, and (eventually) /forge:plan,
+// /forge:implement ports. Co-locates the spawn helper, regex constants, and
+// the multi-result picker so future ports do not drift from the canonical
+// cascade.
+import * as path from "node:path";
+import { execFileAsync } from "../lib/exec-helpers.js";
+import { isDirectory } from "../lib/shared-fs-utils.js";
+export const ENTITY_TYPES = new Set(["task", "sprint", "bug", "feature"]);
+export const ID_PATTERNS = {
+    task: /^([A-Z0-9]+-)?S\d+-T\d+$/i,
+    sprint: /^([A-Z0-9]+-)?S\d+$/i,
+    bug: /^([A-Z0-9]+-)?B\d+$/i,
+    feature: /^([A-Z0-9]+-)?F\d+$/i,
+    bareTask: /^T\d+$/i,
+    idFragment: /^(S|B|F|T)\d+(-T\d+)?$/i,
+};
+export function isDebug() {
+    return process.env.FORGE_DEBUG === "1";
+}
+export function resolveToolDir(forgeRoot) {
+    const nested = path.join(forgeRoot, "tools");
+    return isDirectory(nested) ? nested : forgeRoot;
+}
+export async function runStoreCli(toolDir, argv, cwd) {
+    const toolPath = path.join(toolDir, "store-cli.cjs");
+    const timeout = argv[0] === "nlp" ? 30_000 : 10_000;
+    const result = await execFileAsync("node", [toolPath, ...argv], {
+        cwd,
+        encoding: "utf8",
+        timeout,
+    });
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error(`store-cli returned non-JSON for argv=${JSON.stringify(argv)}: ${result.stdout.slice(0, 200)}`);
+    }
+}
+function filterEntities(rs, entityTypes) {
+    return rs.filter((r) => entityTypes.has(r.type));
+}
+async function pickFromResults(items, arg, ctx, statusLabel) {
+    if (items.length === 1)
+        return { item: items[0] };
+    ctx.ui.setStatus(statusLabel, undefined);
+    const nonInteractive = process.env.FORGE_YES === "1" || process.env.FORGE_NON_INTERACTIVE === "1";
+    if (nonInteractive) {
+        ctx.ui.notify(`Multiple records match "${arg}" — refusing to pick in non-interactive mode`, "error");
+        return null;
+    }
+    const options = items.map((t, i) => `[${i}] ${t.id} (${t.type}): ${t.title}`);
+    const selection = await ctx.ui.select(`Multiple records found for "${arg}". Select one:`, options);
+    if (!selection)
+        return null;
+    const idx = parseInt(selection.match(/^\[(\d+)\]/)?.[1] ?? "-1", 10);
+    if (idx < 0 || idx >= items.length)
+        return null;
+    return { item: items[idx] };
+}
+/**
+ * Try store-cli's native --task-suffix / --sprint-suffix flags. Returns:
+ *   - results array on success
+ *   - null if the flag is unsupported (older store-cli) — caller should fall back
+ */
+export async function suffixMatch(toolDir, cwd, kind, suffix) {
+    const flag = kind === "task" ? "--task-suffix" : "--sprint-suffix";
+    try {
+        const r = await runStoreCli(toolDir, ["query", flag, suffix], cwd);
+        if (r && Array.isArray(r.results) && r.path === "suffix")
+            return r.results;
+        // store-cli ran but didn't take the suffix path → treat as unsupported.
+        return null;
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] suffix flag failed: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Resolution cascade:
+ *   1. @path        → use the path directly as artifact directory
+ *   2. Canonical ID → store-cli query --task/--bug/--feature/--sprint
+ *   3. ID suffix    → --task-suffix / --sprint-suffix (one call) with loop fallback
+ *   4. Keyword      → store-cli query --keyword (title substring)
+ *   5. NLP fallback → store-cli nlp "<query>"
+ */
+export async function resolveEntityRef(arg, toolDir, cwd, opts = {}) {
+    const ctx = opts.ctx;
+    const statusLabel = opts.statusLabel ?? "forge:resolve";
+    const entityTypes = opts.entityTypes ?? ENTITY_TYPES;
+    const setStatus = (msg) => ctx?.ui.setStatus(statusLabel, msg);
+    const pick = (items) => ctx ? pickFromResults(items, arg, ctx, statusLabel) : Promise.resolve({ item: items[0] });
+    // ── 1. @path ──────────────────────────────────────────────────────────────
+    if (arg.startsWith("@")) {
+        const rawPath = arg.slice(1).trim();
+        const resolved = path.isAbsolute(rawPath) ? rawPath : path.join(cwd, rawPath);
+        return { dir: resolved };
+    }
+    // ── 2. Canonical structured ID ────────────────────────────────────────────
+    const isCanonical = /^[A-Z0-9]+-/i.test(arg) &&
+        (ID_PATTERNS.task.test(arg) ||
+            ID_PATTERNS.bug.test(arg) ||
+            ID_PATTERNS.feature.test(arg) ||
+            ID_PATTERNS.sprint.test(arg));
+    let structuredResult = null;
+    try {
+        if (ID_PATTERNS.task.test(arg)) {
+            setStatus(`Looking up task ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--task", arg], cwd);
+        }
+        else if (ID_PATTERNS.bug.test(arg)) {
+            setStatus(`Looking up bug ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--bug", arg], cwd);
+        }
+        else if (ID_PATTERNS.feature.test(arg)) {
+            setStatus(`Looking up feature ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--feature", arg], cwd);
+        }
+        else if (ID_PATTERNS.sprint.test(arg)) {
+            setStatus(`Looking up sprint ${arg}…`);
+            structuredResult = await runStoreCli(toolDir, ["query", "--sprint", arg], cwd);
+        }
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] structured query failed: ${err.message}`);
+    }
+    if (structuredResult?.results?.length > 0) {
+        return pick(structuredResult.results);
+    }
+    if (isCanonical) {
+        setStatus(undefined);
+        ctx?.ui.notify(`No record found for canonical ID "${arg}"`, "warning");
+        return null;
+    }
+    // ── 3. ID suffix matching ─────────────────────────────────────────────────
+    const looksLikeIdFragment = ID_PATTERNS.idFragment.test(arg);
+    if (looksLikeIdFragment) {
+        setStatus(`Searching for ID suffix "${arg}"…`);
+        try {
+            const suffix = arg.toUpperCase();
+            // Sprint-shaped fragment (e.g. "S01"): native sprint-suffix first,
+            // fall back to list-and-filter.
+            if (ID_PATTERNS.sprint.test(arg) && !ID_PATTERNS.task.test(arg)) {
+                const fast = await suffixMatch(toolDir, cwd, "sprint", suffix);
+                if (fast && fast.length > 0)
+                    return pick(fast);
+                if (fast === null) {
+                    const r = await runStoreCli(toolDir, ["query", "--list-sprints"], cwd);
+                    const matched = (r?.results ?? []).filter((s) => s.id?.toUpperCase().endsWith(`-${suffix}`) || s.id?.toUpperCase() === suffix);
+                    if (matched.length > 0) {
+                        const canonical = [];
+                        for (const s of matched) {
+                            try {
+                                const rr = await runStoreCli(toolDir, ["query", "--sprint", s.id], cwd);
+                                canonical.push(...(rr?.results ?? []));
+                            }
+                            catch (err) {
+                                if (isDebug())
+                                    console.error(`[forge:resolver] sprint lookup failed for ${s.id}: ${err.message}`);
+                            }
+                        }
+                        if (canonical.length > 0)
+                            return pick(canonical);
+                    }
+                }
+            }
+            // Task-shaped fragment (e.g. "T01" or "S01-T01"): native task-suffix
+            // first; fall back to N sprint × Tnn loop.
+            if (ID_PATTERNS.task.test(arg) || ID_PATTERNS.bareTask.test(arg)) {
+                const tPart = ID_PATTERNS.bareTask.test(arg) ? suffix : suffix.split("-")[1];
+                const fast = await suffixMatch(toolDir, cwd, "task", tPart);
+                if (fast && fast.length > 0)
+                    return pick(fast);
+                if (fast === null) {
+                    const r = await runStoreCli(toolDir, ["query", "--list-sprints"], cwd);
+                    for (const s of r?.results ?? []) {
+                        try {
+                            const taskId = `${s.id}-${tPart}`;
+                            const rr = await runStoreCli(toolDir, ["query", "--task", taskId], cwd);
+                            if (rr?.results?.length > 0)
+                                return pick(rr.results);
+                        }
+                        catch (err) {
+                            if (isDebug())
+                                console.error(`[forge:resolver] task lookup failed for ${s.id}-${tPart}: ${err.message}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (isDebug())
+                console.error(`[forge:resolver] suffix search failed: ${err.message}`);
+        }
+    }
+    // ── 4. Keyword search ─────────────────────────────────────────────────────
+    setStatus(`Keyword search: "${arg}"…`);
+    let keywordResult = null;
+    try {
+        keywordResult = await runStoreCli(toolDir, ["query", "--keyword", arg], cwd);
+    }
+    catch (err) {
+        if (isDebug())
+            console.error(`[forge:resolver] keyword search failed: ${err.message}`);
+    }
+    if (keywordResult?.results?.length > 0) {
+        return pick(filterEntities(keywordResult.results, entityTypes));
+    }
+    // ── 5. NLP fallback ───────────────────────────────────────────────────────
+    setStatus(`Searching Forge store: "${arg}"…`);
+    const nlpResult = await runStoreCli(toolDir, ["nlp", arg], cwd);
+    const items = filterEntities(nlpResult.results || [], entityTypes);
+    if (items.length === 0) {
+        setStatus(undefined);
+        ctx?.ui.notify(`No records found matching "${arg}"`, "warning");
+        return null;
+    }
+    return pick(items);
+}
+/**
+ * Resolve a raw user arg to a canonical entity ID string.
+ *
+ * 1. If the arg is already a canonical ID that resolves directly → return it.
+ * 2. If the arg is an unprefixed ID (e.g. "S22-T03") → suffix-match or
+ *    prefix-normalize to the canonical form → return it.
+ * 3. If the arg is ambiguous → prompt the user (or hard-fail in non-interactive).
+ * 4. If the arg cannot be resolved → emit an actionable error and return null.
+ */
+export async function resolveToCanonicalId(arg, toolDir, cwd, kind, opts) {
+    const { ctx, entityTypes = new Set([kind]), commandLabel = `forge:${kind}` } = opts;
+    const resolved = await resolveEntityRef(arg, toolDir, cwd, {
+        entityTypes,
+        ctx,
+        statusLabel: `${commandLabel}: resolving`,
+    });
+    if (!resolved) {
+        ctx?.ui.notify(`× ${commandLabel} — could not resolve "${arg}". ` +
+            `No matching ${kind} found. ` +
+            `Try a canonical ID like <PREFIX>-S<N>-T<N> or use /forge:read for search.`, "error");
+        return null;
+    }
+    if ("dir" in resolved) {
+        // @path resolution — not a task/sprint/bug ID pattern.
+        ctx?.ui.notify(`× ${commandLabel} — "${arg}" resolved to a directory path, not a ${kind} ID. ` +
+            `Provide a canonical ${kind} ID instead.`, "error");
+        return null;
+    }
+    const canonicalId = resolved.item?.id;
+    if (!canonicalId || typeof canonicalId !== "string") {
+        ctx?.ui.notify(`× ${commandLabel} — resolved "${arg}" but record has no canonical ID.`, "error");
+        return null;
+    }
+    // If the canonical ID differs from the raw arg, notify the user.
+    if (canonicalId !== arg) {
+        ctx?.ui.notify(`ℹ ${commandLabel} — resolved "${arg}" → ${canonicalId}`, "info");
+    }
+    return canonicalId;
+}
+//# sourceMappingURL=store-resolver.js.map