@deftai/directive-core 0.66.0 → 0.66.2

package/dist/doctor/paths.d.ts

@@ -2,6 +2,7 @@
 export declare function resolvePath(pathStr: string, cwd?: string): string;
 /** Best-effort version string (mirrors Python `_resolve_version`). */
 export declare function resolveVersion(frameworkRoot?: string): string;
+export declare function resolveFrameworkRootForProject(projectRoot: string, explicitRoot?: string | null): string;
 /** Return the deft framework repo root (the directory containing `main.md`). */
 export declare function resolveDefaultFrameworkRoot(): string;
 /** Directory containing doctor implementation (Python: scripts/). */

package/dist/doctor/paths.js

@@ -32,6 +32,61 @@ export function resolveVersion(frameworkRoot) {
     }
     return "dev";
 }
+/**
+ * Resolve the framework root for a CLI command running against `projectRoot`.
+ *
+ * Priority: explicit `--deft-root` / `--framework-root` → `DEFT_ROOT` env →
+ * maintainer source checkout at `projectRoot` (when `main.md` + framework markers
+ * are present, even if a dogfood `.deft/core` deposit also exists) → consumer
+ * deposit (`.deft/core`, legacy `deft/`) → maintainer checkout walk
+ * (`resolveDefaultFrameworkRoot`).
+ *
+ * Refs #2146 (npm global `deft` must not default to `node_modules/vbrief/schemas`).
+ */
+function isFrameworkSourceCheckoutAt(projectRoot) {
+    try {
+        if (!statSync(join(projectRoot, "main.md")).isFile()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    return DEFT_REPO_POSITIVE_MARKERS.every((marker) => {
+        try {
+            return statSync(join(projectRoot, marker)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function resolveFrameworkRootForProject(projectRoot, explicitRoot) {
+    const explicit = explicitRoot?.trim();
+    if (explicit) {
+        return resolve(explicit);
+    }
+    const envRoot = process.env.DEFT_ROOT?.trim();
+    if (envRoot) {
+        return resolve(envRoot);
+    }
+    const root = resolve(projectRoot);
+    if (isFrameworkSourceCheckoutAt(root)) {
+        return root;
+    }
+    for (const rel of [join(".deft", "core"), "deft"]) {
+        const candidate = join(root, rel);
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return resolveDefaultFrameworkRoot();
+}
 /** Return the deft framework repo root (the directory containing `main.md`). */
 export function resolveDefaultFrameworkRoot() {
     const envRoot = process.env.DEFT_ROOT?.trim();

package/dist/intake/issue-ingest.d.ts

@@ -1,6 +1,17 @@
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
+/** GitHub issue comment thread entry (REST `repos/.../issues/N/comments`). */
+export interface IssueComment {
+    readonly id?: number;
+    readonly body?: string;
+    readonly user?: {
+        readonly login?: string;
+    };
+    readonly created_at?: string;
+}
+/** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
+export declare const ISSUE_COMMENT_THREAD_KEY: "issueCommentThread";
 export declare function bodyControlCharacterLabels(body: string): string[];
 export declare function warnBodyControlCharacters(number: number, body: string): void;
 export declare function extractPlanItems(body: string): Record<string, string>[];
@@ -8,6 +19,9 @@ export declare function extractAcSectionItems(text: string): Record<string, stri
 export declare function extractCrossRefs(body: string, repoUrl: string, exclude?: ReadonlySet<number>): Record<string, string>[];
 export declare function provenanceIssueNumber(data: Record<string, unknown>): number | null;
 export declare function scanProvenanceRefs(vbriefDir: string): Map<number, string[]>;
+export declare function composeOverviewWithComments(body: string, comments: readonly IssueComment[]): string;
+export declare function issueCommentThread(issue: Record<string, unknown>): IssueComment[];
+export declare function issueCommentsAlreadyFetched(issue: Record<string, unknown>): boolean;
 export declare function buildIssueVbrief(issue: Record<string, unknown>, status: IngestStatus, repoUrl: string): [Record<string, unknown>, string];
 export declare function targetFilename(number: number, title: string): string;
 export interface FetchIssueOptions {
@@ -16,6 +30,10 @@ export interface FetchIssueOptions {
     readonly scmCall?: ScmCallFn;
 }
 export declare function fetchFromCache(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
+export declare function fetchIssueComments(repo: string, number: number, options?: FetchIssueOptions): IssueComment[];
+export declare function attachIssueCommentThread(issue: Record<string, unknown>, comments: readonly IssueComment[]): Record<string, unknown>;
+export declare function repoSlugFromUrl(repoUrl: string): string | null;
+export declare function enrichIssueWithComments(issue: Record<string, unknown>, repoUrl: string, options?: FetchIssueOptions): Record<string, unknown>;
 export declare function fetchSingleIssue(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
 export declare function fetchIssue(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
 export type IngestResult = "created" | "dryrun" | "duplicate";
@@ -25,6 +43,9 @@ export declare function ingestOne(issue: Record<string, unknown>, options: {
     repoUrl: string;
     dryRun?: boolean;
     existingRefs?: Map<number, string[]>;
+    scmCall?: ScmCallFn;
+    cwd?: string | null;
+    cacheRoot?: string | null;
 }): [IngestResult, string | null, string];
 export declare function ingestBulk(issues: Record<string, unknown>[], options: {
     vbriefDir: string;
@@ -32,6 +53,9 @@ export declare function ingestBulk(issues: Record<string, unknown>[], options: {
     repoUrl: string;
     label?: string | null;
     dryRun?: boolean;
+    scmCall?: ScmCallFn;
+    cwd?: string | null;
+    cacheRoot?: string | null;
 }): Record<string, string[] | number>;
 export declare function resolveRepoUrl(repo: string): string;
 export interface IssueIngestCliArgs {

package/dist/intake/issue-ingest.js

@@ -10,6 +10,8 @@ import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
+/** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
+export const ISSUE_COMMENT_THREAD_KEY = "issueCommentThread";
 const STATUS_MAP = {
     proposed: ["proposed", "proposed"],
     pending: ["pending", "pending"],
@@ -192,6 +194,42 @@ export function scanProvenanceRefs(vbriefDir) {
     }
     return issueToVbriefs;
 }
+export function composeOverviewWithComments(body, comments) {
+    if (comments.length === 0) {
+        return body;
+    }
+    const parts = [];
+    if (body.length > 0) {
+        parts.push(body);
+        parts.push("");
+        parts.push("---");
+        parts.push("");
+    }
+    parts.push("## Issue comment thread");
+    parts.push("");
+    parts.push("_The issue body is the original write-up; maintainer comments below may supersede it. Read the full thread before building a dispatch envelope (#2143)._");
+    parts.push("");
+    for (const comment of comments) {
+        const author = comment.user?.login ?? "unknown";
+        const when = comment.created_at ?? "";
+        const header = when.length > 0 ? `### Comment by @${author} (${when})` : `### Comment by @${author}`;
+        parts.push(header);
+        parts.push("");
+        parts.push(typeof comment.body === "string" ? comment.body : "");
+        parts.push("");
+    }
+    return parts.join("\n").trimEnd();
+}
+export function issueCommentThread(issue) {
+    const raw = issue[ISSUE_COMMENT_THREAD_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((entry) => entry !== null && typeof entry === "object");
+}
+export function issueCommentsAlreadyFetched(issue) {
+    return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
+}
 export function buildIssueVbrief(issue, status, repoUrl) {
     const number = Number(issue.number);
     const title = (typeof issue.title === "string" && issue.title.length > 0
@@ -201,6 +239,8 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         (repoUrl.length > 0 ? `${repoUrl}/issues/${number}` : "");
     const bodyRaw = issue.body;
     const bodyStr = typeof bodyRaw === "string" && bodyRaw.length > 0 ? bodyRaw : "";
+    const commentThread = issueCommentThread(issue);
+    const overviewSource = commentThread.length > 0 ? composeOverviewWithComments(bodyStr, commentThread) : bodyStr;
     const labelsRaw = issue.labels;
     const labelNames = [];
     if (Array.isArray(labelsRaw)) {
@@ -221,9 +261,9 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         Description: title,
         Origin: url.length > 0 ? `Ingested from ${url}` : `Ingested from issue #${number}`,
     };
-    if (bodyStr.length > 0) {
-        warnBodyControlCharacters(number, bodyStr);
-        narratives.Overview = bodyStr;
+    if (overviewSource.length > 0) {
+        warnBodyControlCharacters(number, overviewSource);
+        narratives.Overview = overviewSource;
     }
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
@@ -246,8 +286,8 @@ export function buildIssueVbrief(issue, status, repoUrl) {
                 title: `Issue #${number}: ${title}`,
             },
         ];
-        if (bodyStr.length > 0 && repoUrl.length > 0) {
-            references.push(...extractCrossRefs(bodyStr, repoUrl, new Set([number])));
+        if (overviewSource.length > 0 && repoUrl.length > 0) {
+            references.push(...extractCrossRefs(overviewSource, repoUrl, new Set([number])));
         }
         plan.references = references;
     }
@@ -284,6 +324,47 @@ export function fetchFromCache(repo, number, options = {}) {
         return null;
     }
 }
+export function fetchIssueComments(repo, number, options = {}) {
+    const scmCall = options.scmCall ?? call;
+    let result;
+    try {
+        result = scmCall("github-issue", "api", [`repos/${repo}/issues/${number}/comments`], {
+            timeout: 30,
+            cwd: options.cwd ?? undefined,
+        });
+    }
+    catch {
+        return [];
+    }
+    if (result.returncode !== 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function attachIssueCommentThread(issue, comments) {
+    return { ...issue, [ISSUE_COMMENT_THREAD_KEY]: [...comments] };
+}
+export function repoSlugFromUrl(repoUrl) {
+    const match = /github\.com\/([^/\s]+\/[^/\s]+)/.exec(repoUrl);
+    return match?.[1] ?? null;
+}
+export function enrichIssueWithComments(issue, repoUrl, options = {}) {
+    if (issueCommentsAlreadyFetched(issue)) {
+        return issue;
+    }
+    const repo = repoSlugFromUrl(repoUrl);
+    const number = Number(issue.number);
+    if (repo === null || !Number.isFinite(number)) {
+        return issue;
+    }
+    return attachIssueCommentThread(issue, fetchIssueComments(repo, number, options));
+}
 export function fetchSingleIssue(repo, number, options = {}) {
     const scmCall = options.scmCall ?? call;
     let result;
@@ -316,9 +397,15 @@ export function fetchSingleIssue(repo, number, options = {}) {
 export function fetchIssue(repo, number, options = {}) {
     const live = fetchSingleIssue(repo, number, options);
     if (live !== null) {
-        return live;
+        const comments = fetchIssueComments(repo, number, options);
+        return attachIssueCommentThread(live, comments);
     }
-    return fetchFromCache(repo, number, options);
+    const cached = fetchFromCache(repo, number, options);
+    if (cached === null) {
+        return null;
+    }
+    const comments = fetchIssueComments(repo, number, options);
+    return attachIssueCommentThread(cached, comments);
 }
 export function ingestOne(issue, options) {
     const number = Number(issue.number);
@@ -331,7 +418,12 @@ export function ingestOne(issue, options) {
             `#${number} already ingested at ${existing}`,
         ];
     }
-    const [vbrief, folder] = buildIssueVbrief(issue, options.status, options.repoUrl);
+    const enriched = enrichIssueWithComments(issue, options.repoUrl, {
+        scmCall: options.scmCall,
+        cwd: options.cwd,
+        cacheRoot: options.cacheRoot,
+    });
+    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl);
     const filename = targetFilename(number, String(issue.title ?? ""));
     const target = join(options.vbriefDir, folder, filename);
     if (options.dryRun) {
@@ -429,6 +521,7 @@ export function issueIngestMain(args) {
             repoUrl,
             label: args.label,
             dryRun: args.dryRun,
+            cwd: projectRoot,
         });
         const created = summary.created;
         const duplicate = summary.duplicate;
@@ -454,6 +547,7 @@ export function issueIngestMain(args) {
         status,
         repoUrl,
         dryRun: args.dryRun,
+        cwd: projectRoot,
     });
     process.stdout.write(`${msg}\n`);
     return result === "duplicate" ? 1 : 0;

package/dist/xbrief-migrate/drift-gate.js

@@ -38,6 +38,8 @@ import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIG
 export const LEGACY_REFERENCE_PREFIX = "x-vbrief/";
 /** Default allowlist: sanctioned data-plane trees that legitimately retain legacy tokens for back-compat. */
 export const BUILTIN_ALLOW_LIST = [
+    // Vendored npm deposit (#2146): C1 flatten maps content/vbrief/* -> .deft/core/vbrief/*.
+    ".deft/core/vbrief/**",
     // Shipped vBRIEF surface (#1875 C3) + conformance round-trip fixtures (#715).
     "content/vbrief/**",
     // Test fixtures exercising the legacy read path + pre-cutover migration (#2108 / #2110)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.66.0",
+  "version": "0.66.2",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -237,8 +237,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.66.0",
-    "@deftai/directive-types": "^0.66.0",
+    "@deftai/directive-content": "^0.66.2",
+    "@deftai/directive-types": "^0.66.2",
     "archiver": "^8.0.0"
   },
   "scripts": {