@deftai/directive-core 0.92.0 → 0.94.0

package/dist/triage/welcome/writers.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { containedWrite } from "../../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
@@ -32,21 +33,29 @@ export function appendAuditEntry(projectRoot, entry) {
     });
     return logPath;
 }
-function atomicWrite(_projectRoot, path, data) {
-    const dir = dirname(path);
-    mkdirSync(dir, { recursive: true });
+/**
+ * Atomically write PROJECT-DEFINITION JSON under projectRoot containment (#3077).
+ * Containment root is projectRoot (not dirname(path)) so a force-added `xbrief/`
+ * directory symlink fails closed before temp+rename — same class as #3042.
+ */
+function atomicWrite(projectRoot, path, data) {
+    const root = resolve(projectRoot);
+    const targetAbs = resolve(path);
+    // Refuse leaf/parent symlinks and out-of-root targets before temp+rename.
+    assertWriteTargetSafe(root, targetAbs);
+    const dir = dirname(targetAbs);
     const payload = `${JSON.stringify(data, null, 2)}\n`;
     const tmpName = `.${Date.now()}.tmp`;
     const tmp = join(dir, tmpName);
     try {
-        // #2980 wave D: temp payload write uses containedWrite under the parent dir.
+        // #2980 wave D / #3077: product write routes through containedWrite under projectRoot.
         containedWrite({
-            root: resolve(dir),
-            target: tmpName,
+            root,
+            target: tmp,
             data: payload,
             mode: "create",
         });
-        renameSync(tmp, path);
+        renameSync(tmp, targetAbs);
     }
     catch (err) {
         try {

package/dist/umbrella-current-shape/index.d.ts

@@ -66,6 +66,51 @@ export interface RunCurrentShapeOptions {
     readonly writeOut?: (text: string) => void;
     readonly writeErr?: (text: string) => void;
 }
+/**
+ * Map a GitHub REST issue-comment object (or an already-normalized row) onto
+ * the internal `IssueComment` shape. Used by `umbrella:current-shape`, the
+ * triage cache put path, and `issue:ingest` so all three share one selector.
+ */
+export declare function mapIssueCommentEntry(entry: unknown): IssueComment | null;
+/**
+ * Labels that mark an issue as umbrella/tracker-like for cache comment enrichment
+ * (#1870). Mirrors `TRACKER_LABELS` in scope/open-umbrella-warning.ts.
+ */
+export declare const UMBRELLA_TRACKER_LABELS: ReadonlySet<string>;
+/**
+ * Key under which `cache:fetch-all` / `cache:put` stash the issue comment thread
+ * on the raw.json payload so `content.md` and `issue:ingest` can surface the
+ * canonical current-shape comment without a second live fetch (#1870).
+ */
+export declare const RAW_ISSUE_COMMENTS_KEY: "comments";
+/** Sidecar filename next to content.md carrying the selected current-shape payload. */
+export declare const CURRENT_SHAPE_SIDECAR: "current-shape.json";
+export interface CurrentShapeSidecar {
+    readonly commentId: number;
+    readonly htmlUrl: string;
+    readonly pass: number;
+    readonly authorLogin: string;
+    readonly authorAssociation: string;
+    readonly body: string;
+}
+/** True when labels or sub-issue summary mark the issue as umbrella/tracker-like. */
+export declare function isUmbrellaLikeIssue(raw: Record<string, unknown>): boolean;
+/** Normalize a raw issue payload's comment array (REST or pre-mapped). */
+export declare function commentsFromRawPayload(raw: Record<string, unknown>): IssueComment[];
+/**
+ * Count maintainer-authored `## Current shape` comments (for the !=1 lint).
+ * Non-maintainer forgeries are excluded (#2307).
+ */
+export declare function countMaintainerCurrentShapeComments(comments: readonly IssueComment[]): number;
+/** Markdown section appended to cache content.md when a canonical shape exists. */
+export declare function formatCurrentShapeSection(selected: CurrentShapeComment): string;
+/**
+ * Append the canonical current-shape comment (if any) to a rendered cache body.
+ * Returns the input unchanged when no maintainer-authored current-shape exists.
+ */
+export declare function appendCurrentShapeSection(baseContent: string, raw: Record<string, unknown>): string;
+/** Build the current-shape.json sidecar payload, or null when none is selectable. */
+export declare function buildCurrentShapeSidecar(raw: Record<string, unknown>): CurrentShapeSidecar | null;
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
 export declare function parseCommentsFromGhStdout(stdout: string): IssueComment[];
 export declare function extractPassFromBody(body: string): number | null;

package/dist/umbrella-current-shape/index.js

@@ -44,24 +44,178 @@ export const REQUIRED_SECTIONS = [
     "readingOrder",
 ];
 export const OPTIONAL_SECTIONS = ["openQuestions"];
-function mapCommentEntry(entry) {
+/**
+ * Map a GitHub REST issue-comment object (or an already-normalized row) onto
+ * the internal `IssueComment` shape. Used by `umbrella:current-shape`, the
+ * triage cache put path, and `issue:ingest` so all three share one selector.
+ */
+export function mapIssueCommentEntry(entry) {
     if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
         return null;
     }
     const rec = entry;
-    if (typeof rec.id !== "number" || typeof rec.body !== "string") {
+    // Accept either GitHub REST field names or the already-mapped camelCase shape.
+    const id = typeof rec.id === "number" ? rec.id : null;
+    const body = typeof rec.body === "string" ? rec.body : null;
+    if (id === null || body === null) {
         return null;
     }
     const user = typeof rec.user === "object" && rec.user !== null
         ? rec.user
         : null;
+    const htmlUrl = typeof rec.html_url === "string"
+        ? rec.html_url
+        : typeof rec.htmlUrl === "string"
+            ? rec.htmlUrl
+            : "";
+    const updatedAt = typeof rec.updated_at === "string"
+        ? rec.updated_at
+        : typeof rec.updatedAt === "string"
+            ? rec.updatedAt
+            : "";
+    const authorLogin = user !== null && typeof user.login === "string"
+        ? user.login
+        : typeof rec.authorLogin === "string"
+            ? rec.authorLogin
+            : "";
+    const authorAssociation = typeof rec.author_association === "string"
+        ? rec.author_association
+        : typeof rec.authorAssociation === "string"
+            ? rec.authorAssociation
+            : "";
+    return {
+        id,
+        body,
+        htmlUrl,
+        updatedAt,
+        authorLogin,
+        authorAssociation,
+    };
+}
+/** @deprecated Prefer `mapIssueCommentEntry` — kept as a private alias for call sites. */
+function mapCommentEntry(entry) {
+    return mapIssueCommentEntry(entry);
+}
+/**
+ * Labels that mark an issue as umbrella/tracker-like for cache comment enrichment
+ * (#1870). Mirrors `TRACKER_LABELS` in scope/open-umbrella-warning.ts.
+ */
+export const UMBRELLA_TRACKER_LABELS = new Set([
+    "epic",
+    "meta",
+    "tracker",
+    "type:tracker",
+    "status:tracker",
+]);
+/**
+ * Key under which `cache:fetch-all` / `cache:put` stash the issue comment thread
+ * on the raw.json payload so `content.md` and `issue:ingest` can surface the
+ * canonical current-shape comment without a second live fetch (#1870).
+ */
+export const RAW_ISSUE_COMMENTS_KEY = "comments";
+/** Sidecar filename next to content.md carrying the selected current-shape payload. */
+export const CURRENT_SHAPE_SIDECAR = "current-shape.json";
+/** True when labels or sub-issue summary mark the issue as umbrella/tracker-like. */
+export function isUmbrellaLikeIssue(raw) {
+    const labelsRaw = raw.labels;
+    if (Array.isArray(labelsRaw)) {
+        for (const label of labelsRaw) {
+            let name = "";
+            if (typeof label === "string") {
+                name = label;
+            }
+            else if (label !== null && typeof label === "object" && !Array.isArray(label)) {
+                const n = label.name;
+                if (typeof n === "string")
+                    name = n;
+            }
+            if (name.length > 0 && UMBRELLA_TRACKER_LABELS.has(name.toLowerCase())) {
+                return true;
+            }
+        }
+    }
+    const summary = raw.sub_issues_summary;
+    if (summary !== null && typeof summary === "object" && !Array.isArray(summary)) {
+        const total = summary.total;
+        if (typeof total === "number" && Number.isFinite(total) && total > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Normalize a raw issue payload's comment array (REST or pre-mapped). */
+export function commentsFromRawPayload(raw) {
+    const rawComments = raw[RAW_ISSUE_COMMENTS_KEY];
+    if (!Array.isArray(rawComments)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of rawComments) {
+        const mapped = mapIssueCommentEntry(entry);
+        if (mapped !== null) {
+            out.push(mapped);
+        }
+    }
+    return out;
+}
+/**
+ * Count maintainer-authored `## Current shape` comments (for the !=1 lint).
+ * Non-maintainer forgeries are excluded (#2307).
+ */
+export function countMaintainerCurrentShapeComments(comments) {
+    let count = 0;
+    for (const comment of comments) {
+        if (!isMaintainerAuthored(comment.authorAssociation)) {
+            continue;
+        }
+        if (extractPassFromBody(comment.body) !== null) {
+            count += 1;
+        }
+    }
+    return count;
+}
+/** Markdown section appended to cache content.md when a canonical shape exists. */
+export function formatCurrentShapeSection(selected) {
+    const permalink = selected.htmlUrl.length > 0 ? selected.htmlUrl : `comment id ${selected.id}`;
+    const author = selected.authorLogin.length > 0 ? `@${selected.authorLogin}` : "maintainer";
+    return [
+        "",
+        "---",
+        "",
+        "## Canonical current shape (#1152 / #1870)",
+        "",
+        `_Authoritative planning surface — prefer this over the issue body (stale by design). ` +
+            `Source: [${permalink}](${permalink}) · pass-${selected.pass} · ${author}. ` +
+            `Deterministic read path: \`task umbrella:current-shape <N>\`._`,
+        "",
+        selected.body.trimEnd(),
+        "",
+    ].join("\n");
+}
+/**
+ * Append the canonical current-shape comment (if any) to a rendered cache body.
+ * Returns the input unchanged when no maintainer-authored current-shape exists.
+ */
+export function appendCurrentShapeSection(baseContent, raw) {
+    const selected = selectCurrentShapeComment(commentsFromRawPayload(raw));
+    if (selected === null) {
+        return baseContent;
+    }
+    return `${baseContent.trimEnd()}\n${formatCurrentShapeSection(selected)}`;
+}
+/** Build the current-shape.json sidecar payload, or null when none is selectable. */
+export function buildCurrentShapeSidecar(raw) {
+    const selected = selectCurrentShapeComment(commentsFromRawPayload(raw));
+    if (selected === null) {
+        return null;
+    }
     return {
-        id: rec.id,
-        body: rec.body,
-        htmlUrl: typeof rec.html_url === "string" ? rec.html_url : "",
-        updatedAt: typeof rec.updated_at === "string" ? rec.updated_at : "",
-        authorLogin: user !== null && typeof user.login === "string" ? user.login : "",
-        authorAssociation: typeof rec.author_association === "string" ? rec.author_association : "",
+        commentId: selected.id,
+        htmlUrl: selected.htmlUrl,
+        pass: selected.pass,
+        authorLogin: selected.authorLogin,
+        authorAssociation: selected.authorAssociation,
+        body: selected.body,
     };
 }
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */

package/dist/vbrief-reconcile/index.d.ts

@@ -5,6 +5,6 @@ export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from
 export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";
 export { allScopeIds, asStrList, candidateDepGraph, candidateFromPath, markCycles, } from "./swarm-deps.js";
-export type { Candidate, Child, ConflictEntry, LabelChange, LabelClient, ReconciledItem, ReconcileGraphOutcome, ReconcileLabelsOutcome, ReconcileUmbrellasOutcome, ReconciliationReport, SpecTaskEntry, UmbrellaChange, UmbrellaClient, } from "./types.js";
-export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, umbrellasOutcomeToJson, } from "./umbrellas.js";
+export type { Candidate, Child, ConflictEntry, ForgeIssueState, LabelChange, LabelClient, ReconciledItem, ReconcileGraphOutcome, ReconcileLabelsOutcome, ReconcileUmbrellasOutcome, ReconciliationReport, SpecTaskEntry, UmbrellaChange, UmbrellaClient, } from "./types.js";
+export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/vbrief-reconcile/index.js

@@ -5,5 +5,5 @@ export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from
 export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";
 export { allScopeIds, asStrList, candidateDepGraph, candidateFromPath, markCycles, } from "./swarm-deps.js";
-export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, umbrellasOutcomeToJson, } from "./umbrellas.js";
+export { buildChildIndex, CHILD_REF_TYPE, CLOSED_FOLDERS, childFromData, classifyPassType, computeChildren, computeWaves, indexChildrenByIssueNumber, isChildOpen, LIFECYCLE_FOLDERS, nowIso, OPEN_FOLDERS, parseCurrentShape, reconcileBodyChecklist, reconcileUmbrellas, renderBody, renderUmbrellasReport, ScmUmbrellaClient, UmbrellaScmError, UNKNOWN_FOLDER, umbrellasOutcomeToJson, } from "./umbrellas.js";
 //# sourceMappingURL=index.js.map

package/dist/vbrief-reconcile/types.d.ts

@@ -94,7 +94,10 @@ export interface Child {
     readonly kind: string;
     readonly folder: string;
     readonly depends_on: string[];
+    /** Linked forge issue number when known (#1649). */
+    readonly issue_number?: number | null;
 }
+export type ForgeIssueState = "open" | "closed";
 export interface UmbrellaChange {
     readonly story_id: string;
     readonly repo: string;
@@ -102,6 +105,11 @@ export interface UmbrellaChange {
     readonly action: "created" | "edited" | "unchanged";
     readonly pass_n: number;
     readonly body: string;
+    /**
+     * Issue-body checkbox reconcile (#1649): `edited` when checkboxes flipped,
+     * `unchanged` when already correct, `skipped` when body APIs unavailable.
+     */
+    readonly checklist_action?: "edited" | "unchanged" | "skipped";
 }
 export interface ReconcileUmbrellasOutcome {
     changed: UmbrellaChange[];
@@ -124,5 +132,11 @@ export interface UmbrellaClient {
     }>;
     editComment(repo: string, commentId: number, body: string): void;
     createComment(repo: string, issueNumber: number, body: string): number | null;
+    /** Optional: forge open/closed for child issues (#1649). Folder fallback when absent. */
+    fetchIssueStates?(repo: string, issueNumbers: readonly number[]): ReadonlyMap<number, ForgeIssueState>;
+    /** Optional: umbrella issue body for checklist reconcile (#1649). */
+    fetchIssueBody?(repo: string, issueNumber: number): string;
+    /** Optional: write reconciled checklist body (#1649). */
+    editIssueBody?(repo: string, issueNumber: number, body: string): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/vbrief-reconcile/umbrellas.d.ts

@@ -1,14 +1,40 @@
-import type { Child, ReconcileUmbrellasOutcome, UmbrellaClient } from "./types.js";
+import type { Child, ForgeIssueState, ReconcileUmbrellasOutcome, UmbrellaClient } from "./types.js";
 export declare const OPEN_FOLDERS: readonly ["proposed", "pending", "active"];
 export declare const CLOSED_FOLDERS: readonly ["completed", "cancelled"];
 export declare const LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
 export declare const CHILD_REF_TYPE = "x-xbrief/plan";
+/** Synthetic lifecycle folder for issue-only children with no local xBRIEF (#1649). */
+export declare const UNKNOWN_FOLDER: "unknown";
 export declare class UmbrellaScmError extends Error {
     name: string;
 }
 export declare function childFromData(data: Record<string, unknown>, folder: string, fallbackId: string): Child;
 export declare function buildChildIndex(vbriefDir: string): Record<string, Child>;
-export declare function computeChildren(epicData: Record<string, unknown>, index: Record<string, Child>): Child[];
+/** Index children by forge issue number for github-issue ref resolution (#1649). */
+export declare function indexChildrenByIssueNumber(index: Record<string, Child>): Map<number, Child>;
+/**
+ * Resolve epic children from plan refs AND github-issue refs (#1649 defect 2).
+ * The epic's own github-issue ref is skipped when `epicIssueNumber` is provided.
+ * Issue-only children (no local xBRIEF) are synthesized with folder `unknown`.
+ */
+export declare function computeChildren(epicData: Record<string, unknown>, index: Record<string, Child>, options?: {
+    epicIssueNumber?: number | null;
+}): Child[];
+/**
+ * Whether a child counts as open for current-shape + checklist (#1649 defect 3).
+ * Prefer forge issue state when present; fall back to lifecycle folder.
+ * `unknown` (issue-only, no local xBRIEF) counts open without forge confirmation.
+ */
+export declare function isChildOpen(child: Child, forgeStates?: ReadonlyMap<number, ForgeIssueState> | null): boolean;
+/**
+ * Reconcile umbrella issue-body checkboxes `- [ ] #N` / `- [x] #N` to child state (#1649).
+ * Only lines that mention a known child issue number are rewritten; other checkboxes untouched.
+ * Idempotent: returns `changed: false` when already correct.
+ */
+export declare function reconcileBodyChecklist(body: string, closedIssueNumbers: ReadonlySet<number>, knownIssueNumbers: ReadonlySet<number>): {
+    body: string;
+    changed: boolean;
+};
 export declare function computeWaves(children: readonly Child[]): string[][];
 export declare function renderBody(options: {
     passN: number;
@@ -34,6 +60,9 @@ export declare class ScmUmbrellaClient implements UmbrellaClient {
     }>;
     editComment(repo: string, commentId: number, body: string): void;
     createComment(repo: string, issueNumber: number, body: string): number | null;
+    fetchIssueStates(repo: string, issueNumbers: readonly number[]): ReadonlyMap<number, ForgeIssueState>;
+    fetchIssueBody(repo: string, issueNumber: number): string;
+    editIssueBody(repo: string, issueNumber: number, body: string): void;
 }
 export declare function nowIso(date?: Date): string;
 export interface ReconcileUmbrellasOptions {