@deftai/directive-core 0.93.0 → 0.95.0

package/dist/cache/fetch.js

@@ -1,7 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
-import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
+import { GhRestError, InvalidRepoError, restIssueView, runGhApi, splitRepo, } from "../scm/gh-rest.js";
+import { CURRENT_SHAPE_SIDECAR, isUmbrellaLikeIssue, parseCommentsFromGhStdout, RAW_ISSUE_COMMENTS_KEY, } from "../umbrella-current-shape/index.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
 import { CacheError, CacheFetchError } from "./errors.js";
 import { atomicWriteText } from "./io.js";
@@ -54,20 +55,130 @@ export const DEFAULT_RETRY_AFTER_FALLBACK_S = 60;
 export const PROGRESS_EVERY_N = 50;
 const RATE_LIMIT_RE = /(?:HTTP\s*429|API rate limit exceeded|rate limit exceeded)/i;
 const RETRY_AFTER_RE = /Retry-After:\s*(\d+)/i;
+/**
+ * Default REST fetch for an issue's comment thread (#1870).
+ * Returns raw REST comment objects (with id/body/html_url/author_association).
+ */
+export function restIssueComments(repo, issueNumber, options = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/issues/${issueNumber}/comments?per_page=100`;
+    const runner = options.runGhApiFn ?? runGhApi;
+    const result = runner(["--paginate", endpoint]);
+    if (result.returncode !== 0) {
+        throw new GhRestError({
+            stderr: result.stderr.trim(),
+            exitCode: result.returncode,
+            endpoint,
+            payload: null,
+            hint: "verify repo/issue number and gh auth; comments feed the #1152 current-shape surface",
+        });
+    }
+    try {
+        // Reuse the paginated-JSON parser so multi-page comment threads stay intact.
+        const mapped = parseCommentsFromGhStdout(result.stdout);
+        return mapped.map((c) => ({
+            id: c.id,
+            body: c.body,
+            html_url: c.htmlUrl,
+            updated_at: c.updatedAt,
+            author_association: c.authorAssociation,
+            user: { login: c.authorLogin },
+        }));
+    }
+    catch (exc) {
+        throw new GhRestError({
+            stderr: `non-JSON comments response: ${exc instanceof Error ? exc.message : String(exc)}`,
+            exitCode: 0,
+            endpoint,
+            payload: null,
+            hint: "REST comments endpoint returned non-JSON; check gh / ghx version",
+        });
+    }
+}
 let paginatedListerImpl = restIssueListPaginated;
 let sleepImpl = () => { };
 let progressWriterImpl = (line) => process.stderr.write(line);
 let progressFlusherImpl = () => { };
 let singleIssueFetcherImpl = restIssueView;
+let issueCommentsFetcherImpl = restIssueComments;
 export function setSingleIssueFetcher(fn) {
     singleIssueFetcherImpl = fn;
 }
+export function setIssueCommentsFetcher(fn) {
+    issueCommentsFetcherImpl = fn;
+}
 export function setPaginatedLister(fn) {
     paginatedListerImpl = fn;
 }
 export function setSleepFn(fn) {
     sleepImpl = fn;
 }
+/**
+ * Attach the issue comment thread onto a raw issue payload when the issue is
+ * umbrella/tracker-like (#1870). Non-umbrellas skip the extra REST call.
+ * Failures leave the payload unchanged so body-only cache still lands.
+ *
+ * When `force` is true, re-fetches even if a comments array is already present
+ * (closed-state refresh and shape backfill paths).
+ */
+export function enrichRawWithCommentsIfUmbrella(repo, raw, options = {}) {
+    if (!isUmbrellaLikeIssue(raw)) {
+        return raw;
+    }
+    if (options.force !== true && Array.isArray(raw[RAW_ISSUE_COMMENTS_KEY])) {
+        return raw;
+    }
+    const number = raw.number;
+    if (typeof number !== "number" || number <= 0) {
+        return raw;
+    }
+    const fetcher = options.fetchComments ?? issueCommentsFetcherImpl;
+    try {
+        const comments = fetcher(repo, number);
+        return { ...raw, [RAW_ISSUE_COMMENTS_KEY]: [...comments] };
+    }
+    catch {
+        // Soft-fail: cache body still useful; agents can live-fetch via umbrella:current-shape.
+        // Preserve a prior comments array when force-refresh fails so we do not
+        // drop a previously cached current-shape surface (#1870 Greptile P1).
+        if (Array.isArray(raw[RAW_ISSUE_COMMENTS_KEY])) {
+            return raw;
+        }
+        return raw;
+    }
+}
+/**
+ * True when an on-disk cache entry is umbrella-like but was written before
+ * #1870 comment enrichment (no `comments` key on raw.json). Used to override
+ * the TTL-fresh skip so body-only entries get one backfill pass.
+ */
+export function entryNeedsCurrentShapeBackfill(edir) {
+    const rawPath = join(edir, "raw.json");
+    if (!existsSync(rawPath)) {
+        return false;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(rawPath, "utf8"));
+        if (!isUmbrellaLikeIssue(raw)) {
+            return false;
+        }
+        // Missing comments key → never enriched. Empty array is "attempted".
+        if (!Object.hasOwn(raw, RAW_ISSUE_COMMENTS_KEY)) {
+            return true;
+        }
+        // Has comments but no sidecar while a shape should exist: rare mid-write
+        // race; treat missing sidecar + non-empty comments as needing rewrite.
+        if (Array.isArray(raw[RAW_ISSUE_COMMENTS_KEY]) &&
+            raw[RAW_ISSUE_COMMENTS_KEY].length > 0 &&
+            !existsSync(join(edir, CURRENT_SHAPE_SIDECAR))) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
 export function setProgressWriter(fn, flusher) {
     progressWriterImpl = fn;
     progressFlusherImpl = flusher ?? (() => { });
@@ -311,7 +422,7 @@ export function runFetchAll(options) {
     }
     for (let i = 0; i < issues.length; i += 1) {
         const processed = i + 1;
-        const raw = normaliseRestIssue(issues[i] ?? {});
+        let raw = normaliseRestIssue(issues[i] ?? {});
         const number = raw.number;
         if (typeof number !== "number" || number <= 0) {
             report.issuesFailed += 1;
@@ -324,12 +435,24 @@ export function runFetchAll(options) {
             const key = `${options.repo}/${number}`;
             const edir = entryDir(source, key, cacheRoot);
             const metaPath = join(edir, "meta.json");
-            const skipFresh = !options.force && isFreshFn(metaPath) && !contentDriftNumbers.has(number);
+            // #1870 Greptile P1: TTL-fresh must not skip body-only umbrella entries
+            // forever — comment enrichment is not part of the content-drift fingerprint.
+            const needsShapeBackfill = entryNeedsCurrentShapeBackfill(edir);
+            const skipFresh = !options.force &&
+                isFreshFn(metaPath) &&
+                !contentDriftNumbers.has(number) &&
+                !needsShapeBackfill;
             if (skipFresh) {
                 report.alreadyFresh += 1;
             }
             else {
                 try {
+                    // #1870: umbrella/tracker issues get comment threads so content.md
+                    // carries the canonical ## Current shape surface, not body alone.
+                    raw = enrichRawWithCommentsIfUmbrella(options.repo, raw, {
+                        fetchComments: options.fetchComments,
+                        force: needsShapeBackfill,
+                    });
                     doPutFn(key, raw);
                     report.issuesWritten += 1;
                 }
@@ -388,6 +511,7 @@ export function cacheFetchAll(options) {
         force: options.force,
         contentDriftNumbers: options.contentDriftNumbers,
         probeDriftFn: options.probeDriftFn,
+        fetchComments: options.fetchComments,
     });
 }
 export class StateRefreshReportImpl {
@@ -509,7 +633,10 @@ export function cacheRefreshClosed(options) {
         delayMs: options.delayMs ?? DEFAULT_DELAY_MS,
         fetchSingle: singleIssueFetcherImpl,
         doPut: (key, raw) => {
-            cachePut(options.source, key, raw, {
+            // #1870 Greptile P1: closed-state rewrite still enriches umbrella comments
+            // so current-shape.json is not deleted by a body-only single-issue put.
+            const enriched = enrichRawWithCommentsIfUmbrella(options.repo, raw, { force: true });
+            cachePut(options.source, key, enriched, {
                 ttlSeconds: options.ttlSeconds,
                 cacheRoot,
             });

package/dist/cache/operations.d.ts

@@ -4,6 +4,14 @@ import { SCANNER_VERSION } from "./scanner.js";
 import { type Clock } from "./time.js";
 import type { CacheGetOptions, CachePutOptions, GetResult, PutResult } from "./types.js";
 export { ProjectionContainmentError as CacheContainmentError };
+/**
+ * Render agent-facing content.md for a cache entry.
+ *
+ * For github-issue sources, appends the canonical `## Current shape` comment
+ * when the raw payload carries a comment thread with a maintainer-authored
+ * shape (#1870 / #1152). Body alone is never sufficient for umbrella planning.
+ */
+export declare function renderContent(source: string, raw: Record<string, unknown>): string;
 /** Write a cache entry (mirrors `cache.cache_put`). */
 export declare function cachePut(source: string, key: string, raw: Record<string, unknown>, options?: CachePutOptions): PutResult;
 /** Read a cache entry (mirrors `cache.cache_get`). */

package/dist/cache/operations.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { pyRepr } from "../scm/py-format.js";
+import { appendCurrentShapeSection, buildCurrentShapeSidecar, CURRENT_SHAPE_SIDECAR, } from "../umbrella-current-shape/index.js";
 import { ALLOWED_SOURCES, REPO_RE, SOURCE_TTL_SECONDS } from "./constants.js";
 import { CacheCapBreachedError, CacheError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
 import { appendAudit, atomicWriteText, fileSize, removeEntryDir, touchMtime } from "./io.js";
@@ -20,7 +21,14 @@ function assertWritableCachePath(cacheRoot, ...segments) {
     assertProjectionContained(projectDir, target);
     return target;
 }
-function renderContent(source, raw) {
+/**
+ * Render agent-facing content.md for a cache entry.
+ *
+ * For github-issue sources, appends the canonical `## Current shape` comment
+ * when the raw payload carries a comment thread with a maintainer-authored
+ * shape (#1870 / #1152). Body alone is never sufficient for umbrella planning.
+ */
+export function renderContent(source, raw) {
     if (source === "github-issue") {
         const number = raw.number;
         const title = raw.title ?? "";
@@ -28,7 +36,8 @@ function renderContent(source, raw) {
         if (typeof number !== "number") {
             throw new CacheError(`invalid github-issue raw payload: 'number' must be int (got ${typeof number})`);
         }
-        return `# #${number}: ${title}\n\n${body}`;
+        const base = `# #${number}: ${title}\n\n${body}`;
+        return appendCurrentShapeSection(base, raw);
     }
     throw new CacheError(`unknown source '${source}': v1 supports ${JSON.stringify([...ALLOWED_SOURCES].sort())}`);
 }
@@ -96,9 +105,20 @@ export function cachePut(source, key, raw, options = {}) {
     const edir = entryDir(source, key, cacheRoot);
     const rawText = pythonJsonDump(raw);
     const rawSize = Buffer.byteLength(rawText, "utf8");
+    // #1870 Greptile P2: account for current-shape sidecar bytes in cap + meta
+    // so usage does not underreport by the cumulative sidecar size.
+    const plannedSidecar = buildCurrentShapeSidecar(raw);
+    const plannedSidecarText = plannedSidecar !== null
+        ? `${pythonJsonDump({
+            ...plannedSidecar,
+            body: plannedSidecar.body,
+        })}\n`
+        : "";
+    const plannedSidecarBytes = Buffer.byteLength(plannedSidecarText, "utf8");
+    const entryPayloadBytes = rawSize + plannedSidecarBytes;
     const existingSize = existingEntrySize(edir);
     const isNewEntry = existingSize === null;
-    const incomingDelta = isNewEntry ? rawSize : rawSize - existingSize;
+    const incomingDelta = isNewEntry ? entryPayloadBytes : entryPayloadBytes - existingSize;
     const incomingEntries = isNewEntry ? 1 : 0;
     const enforceResult = enforceCaps(cacheRoot, {
         caps: options.caps ?? null,
@@ -132,14 +152,48 @@ export function cachePut(source, key, raw, options = {}) {
     // #3042: contain cache entry writes against project root (parent of cacheRoot).
     const projectRoot = dirname(resolve(cacheRoot));
     atomicWriteText(join(edir, "raw.json"), rawText, { projectRoot });
-    const authoritativeSize = fileSize(join(edir, "raw.json"));
+    const rawFileSize = fileSize(join(edir, "raw.json"));
     const rendered = renderContent(source, raw);
     const scanResult = scan(rendered, utcIso(clock, fetched));
     const contentPath = join(edir, "content.md");
+    const shapeSidecarPath = join(edir, CURRENT_SHAPE_SIDECAR);
     let contentWritten = false;
+    let sidecarBytesWritten = 0;
     if (scanResult.passed) {
         atomicWriteText(contentPath, scanResult.transformed_content, { projectRoot });
         contentWritten = true;
+        // #1870: persist the selected current-shape comment + permalink beside
+        // content.md so triage/gates can read it without re-parsing the markdown.
+        const sidecar = plannedSidecar;
+        if (sidecar !== null) {
+            // Quarantine-scan the sidecar body independently so a hard-fail on the
+            // full content.md transform cannot leave a credential-bearing sidecar.
+            const shapeScan = scan(sidecar.body, utcIso(clock, fetched));
+            if (shapeScan.passed) {
+                const sidecarText = `${pythonJsonDump({
+                    ...sidecar,
+                    body: shapeScan.transformed_content,
+                })}\n`;
+                atomicWriteText(shapeSidecarPath, sidecarText, { projectRoot });
+                sidecarBytesWritten = Buffer.byteLength(sidecarText, "utf8");
+            }
+            else if (existsSync(shapeSidecarPath)) {
+                try {
+                    unlinkSync(shapeSidecarPath);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        else if (existsSync(shapeSidecarPath)) {
+            try {
+                unlinkSync(shapeSidecarPath);
+            }
+            catch {
+                /* ignore */
+            }
+        }
     }
     else if (existsSync(contentPath)) {
         try {
@@ -148,7 +202,16 @@ export function cachePut(source, key, raw, options = {}) {
         catch {
             /* ignore */
         }
+        if (existsSync(shapeSidecarPath)) {
+            try {
+                unlinkSync(shapeSidecarPath);
+            }
+            catch {
+                /* ignore */
+            }
+        }
     }
+    const authoritativeSize = rawFileSize + sidecarBytesWritten;
     const meta = buildMeta({
         source,
         key,

package/dist/check/cached-orchestrator.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { lintShippedRegistry, resolveTaskContract, runWithCache, } from "../cache/task-cache/index.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "./consumer-gate-integrity.js";
 import { resolveCheckTarget } from "./context.js";
 import { checkGateId, checkGateSpawnArgs, gatesForCheckTarget } from "./gate-lists.js";
 function captureSpawn(taskBin, args, opts) {
@@ -29,6 +30,16 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
     const cwd = target === "check:framework-source" ? resolvedFramework : resolvedProject;
     const gates = gatesForCheckTarget(target);
     const codeVersion = readCorePackageVersion();
+    // #3070: fail loud with deposit-repair guidance when consumer check-graph
+    // includes (e.g. tasks/verify.yml for verify:orphan-active) are missing,
+    // instead of opaque go-task "Task does not exist" exit 200/201.
+    if (target === "check:consumer") {
+        const integrity = evaluateConsumerGateIntegrity(resolvedFramework);
+        if (!integrity.ok) {
+            process.stderr.write(formatConsumerGateIntegrityFailure(integrity));
+            return 2;
+        }
+    }
     const registryLint = lintShippedRegistry();
     if (!registryLint.ok) {
         for (const finding of registryLint.findings.filter((f) => f.kind === "under-declared-input")) {

package/dist/check/consumer-gate-integrity.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Consumer check-graph integrity (#3070).
+ *
+ * CONSUMER_CHECK_GATES lists Taskfile tasks that must resolve in a vendored
+ * deposit. When optional Taskfile includes silently omit `tasks/verify.yml`
+ * (etc.), go-task fails with opaque exit 200/201 ("Task does not exist").
+ *
+ * This module:
+ *  1. Maps each gate to its include namespace / root Taskfile surface
+ *  2. Proves shipped files define those tasks (static + runtime)
+ *  3. Emits a deposit-repair recovery message instead of opaque go-task errors
+ */
+import { type CheckGateSpec } from "./gate-lists.js";
+/** Include namespaces required by the consumer check graph (Taskfile includes). */
+export declare const CHECK_GRAPH_REQUIRED_NAMESPACES: readonly ["verify", "toolchain", "vbrief"];
+export type CheckGraphNamespace = (typeof CHECK_GRAPH_REQUIRED_NAMESPACES)[number];
+export declare const CONSUMER_GATE_INTEGRITY_RECOVERY: string;
+export interface ConsumerGateIntegrityFinding {
+    readonly gateId: string;
+    readonly kind: "missing-include-file" | "missing-task-definition" | "missing-root-taskfile";
+    readonly detail: string;
+    readonly expectedPath?: string;
+}
+export interface ConsumerGateIntegrityResult {
+    readonly ok: boolean;
+    readonly findings: readonly ConsumerGateIntegrityFinding[];
+    readonly recovery: string;
+}
+export interface ConsumerGateIntegritySeams {
+    readonly exists?: (path: string) => boolean;
+    readonly readText?: (path: string) => string | null;
+    /** Override gate list under test (defaults to CONSUMER_CHECK_GATES). */
+    readonly gates?: readonly CheckGateSpec[];
+}
+/** Namespace for a namespaced task (`verify:orphan-active` → `verify`); null for root tasks. */
+export declare function gateNamespace(gateId: string): string | null;
+/** Local task name inside an include (`verify:orphan-active` → `orphan-active`). */
+export declare function gateLocalName(gateId: string): string;
+/** Relative path of the include Taskfile for a namespace. */
+export declare function includeTaskfileRel(namespace: string): string;
+/**
+ * Namespaces that CONSUMER_CHECK_GATES require via `ns:task` form.
+ * Root-only gates (doctor, verify-strategy-output) do not add a namespace.
+ */
+export declare function requiredNamespacesForGates(gates?: readonly CheckGateSpec[]): readonly string[];
+/** True when `localName` is a top-level task key under a Taskfile `tasks:` section. */
+export declare function taskDefinedInTaskfileYaml(text: string, localName: string): boolean;
+/**
+ * Parse root Taskfile `includes:` entries: map namespace → { taskfile, optional }.
+ * Minimal line parser (avoids a YAML dependency); sufficient for go-task include shape.
+ */
+export declare function parseTaskfileIncludes(text: string): ReadonlyMap<string, {
+    readonly taskfile: string;
+    readonly optional: boolean;
+}>;
+/**
+ * Assert every consumer check gate resolves against `frameworkRoot` Taskfile + includes.
+ * When the root Taskfile is absent, returns ok with no findings (caller/spawn handles that).
+ */
+export declare function evaluateConsumerGateIntegrity(frameworkRoot: string, seams?: ConsumerGateIntegritySeams): ConsumerGateIntegrityResult;
+/** Format integrity failure for stderr (check orchestrator / doctor). */
+export declare function formatConsumerGateIntegrityFailure(result: ConsumerGateIntegrityResult): string;
+/**
+ * Namespaces that must not be `optional: true` on the root Taskfile when the
+ * check graph depends on them — silent omit is the #3070 failure mode.
+ */
+export declare function checkGraphOptionalIncludeViolations(rootTaskfileText: string, namespaces?: readonly string[]): readonly string[];
+//# sourceMappingURL=consumer-gate-integrity.d.ts.map