@deftai/directive-core 0.93.0 → 0.94.0

package/dist/review-monitor/l4-owner.js

@@ -0,0 +1,262 @@
+/**
+ * Owner Continuity / L4 owner gate (#3090).
+ *
+ * Exit 0 only when a fresh sticky review-owner lease exists on the PR,
+ * or the caller asserts `review_cycle: done` after Step 6.
+ * Freeform started/pending/initiated values are rejected.
+ * skipped / n/a / parent-retained are process evidence only — they do NOT
+ * satisfy this machine gate when --pr is required (lease-or-done).
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveRepo } from "../triage/queue/repo.js";
+import { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY } from "./constants.js";
+import { fetchActiveMonitorFromGithub } from "./record.js";
+export const L4_OWNER_HELP = "usage: task verify:l4-owner -- --pr <N> [options]\n" +
+    "\n" +
+    "Owner Continuity / L4 owner gate (#3090): after drive-to:merge-ready /\n" +
+    "babysit / shepherd claims, exit 0 only when a sticky GitHub review-owner\n" +
+    "lease is fresh on the PR, or the caller asserts --review-cycle done\n" +
+    "(Step 6 fail-closed all-of on HEAD). Freeform started/pending/initiated\n" +
+    "are rejected. skipped / n/a / parent-retained do NOT satisfy this machine\n" +
+    "gate (process A/B/C still applies). Silent hold exits 1.\n" +
+    "\n" +
+    "options:\n" +
+    "  -h, --help                 Show this help and exit 0\n" +
+    "  --pr N                     Pull request number (required unless --help)\n" +
+    "  --repo OWNER/REPO          Repository (optional; inferred from origin)\n" +
+    "  --head-sha SHA             Expected HEAD SHA (optional freshness check)\n" +
+    "  --project-root PATH        Project root (default: cwd)\n" +
+    "  --review-cycle VALUE       done | in_progress:<pr>#<ref> | skipped:<reason> | n/a\n" +
+    "  --json                     Emit structured JSON on stdout\n" +
+    "\n" +
+    "exit codes:\n" +
+    "  0  READY       Fresh sticky lease, or --review-cycle done\n" +
+    "  1  NOT READY   Silent hold / illegal evidence / lease missing\n" +
+    "  2  CONFIG      Usage / path / GitHub fetch error\n";
+const FORBIDDEN_FREEFORM = new Set(["started", "pending", "initiated", "start", "in_progress"]);
+export function parseReviewCycleEvidence(raw) {
+    if (raw === null || raw === undefined || raw.trim() === "") {
+        return { ok: true, value: null };
+    }
+    const value = raw.trim();
+    const lower = value.toLowerCase();
+    if (FORBIDDEN_FREEFORM.has(lower)) {
+        return {
+            ok: false,
+            reason: `illegal freeform review_cycle value '${value}' (#3090); ` +
+                "use done | in_progress:<pr>#<ref> | skipped:<reason> | n/a",
+        };
+    }
+    if (value === "done" || value === "n/a") {
+        return { ok: true, value };
+    }
+    if (value.startsWith("in_progress:")) {
+        const rest = value.slice("in_progress:".length);
+        if (!rest.includes("#") || rest.endsWith("#") || rest.startsWith("#")) {
+            return {
+                ok: false,
+                reason: "in_progress requires form in_progress:<pr>#<monitor_or_lease_ref> (#3090)",
+            };
+        }
+        const prPart = rest.slice(0, rest.indexOf("#"));
+        if (!/^\d+$/.test(prPart) || Number(prPart) <= 0) {
+            return {
+                ok: false,
+                reason: "in_progress:<pr> must be a positive integer PR number (#3090)",
+            };
+        }
+        return { ok: true, value: value };
+    }
+    if (value.startsWith("skipped:")) {
+        const rest = value.slice("skipped:".length).trim();
+        if (rest.length === 0) {
+            return { ok: false, reason: "skipped requires a non-empty reason (#3090)" };
+        }
+        return { ok: true, value: value };
+    }
+    return {
+        ok: false,
+        reason: `unknown review_cycle value '${value}' (#3090); ` +
+            "use done | in_progress:<pr>#<ref> | skipped:<reason> | n/a",
+    };
+}
+/** Parse in_progress:<pr>#<ref> into parts; null if not that form. */
+export function parseInProgressEvidence(value) {
+    if (!value.startsWith("in_progress:")) {
+        return null;
+    }
+    const rest = value.slice("in_progress:".length);
+    const hash = rest.indexOf("#");
+    if (hash <= 0) {
+        return null;
+    }
+    const prPart = rest.slice(0, hash);
+    const ref = rest.slice(hash + 1);
+    if (!/^\d+$/.test(prPart) || ref.length === 0) {
+        return null;
+    }
+    return { pr: Number(prPart), ref };
+}
+function oneLine(value) {
+    return value.replace(/\r?\n/g, " ");
+}
+export function evaluateL4OwnerGate(args) {
+    const projectRoot = resolve(args.projectRoot);
+    let isDir = false;
+    try {
+        isDir = existsSync(projectRoot) && statSync(projectRoot).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: `verify_l4_owner: --project-root is not a directory: ${oneLine(projectRoot)}`,
+            monitorRecord: null,
+            reviewCycle: null,
+            path: "config",
+        };
+    }
+    const parsed = parseReviewCycleEvidence(args.reviewCycle);
+    if (!parsed.ok) {
+        return {
+            exitCode: EXIT_NOT_READY,
+            message: `verify_l4_owner: ${oneLine(parsed.reason)}`,
+            monitorRecord: null,
+            reviewCycle: null,
+            path: "illegal",
+        };
+    }
+    // Machine gate is lease-or-done only (#3090). skipped/n/a are handoff enum values
+    // but must not green-light ownership of an open PR without lease or Step 6 done.
+    if (parsed.value === "n/a" || parsed.value?.startsWith("skipped:")) {
+        return {
+            exitCode: EXIT_NOT_READY,
+            message: `verify_l4_owner: review_cycle=${oneLine(parsed.value)} does not satisfy the machine ` +
+                `gate for PR #${args.pr} (#3090). Exit 0 requires a fresh sticky lease or --review-cycle done.`,
+            monitorRecord: null,
+            reviewCycle: parsed.value,
+            path: "none",
+        };
+    }
+    if (parsed.value === "done") {
+        return {
+            exitCode: EXIT_READY,
+            message: `verify_l4_owner: review_cycle=done asserted for PR #${args.pr} (#3090). ` +
+                "Caller MUST have satisfied Step 6 fail-closed all-of on HEAD before this claim.",
+            monitorRecord: null,
+            reviewCycle: "done",
+            path: "done",
+        };
+    }
+    // Validate in_progress PR binding when evidence is present (before lease fetch).
+    if (parsed.value?.startsWith("in_progress:")) {
+        const parts = parseInProgressEvidence(parsed.value);
+        if (parts === null) {
+            return {
+                exitCode: EXIT_NOT_READY,
+                message: `verify_l4_owner: malformed in_progress evidence ${oneLine(parsed.value)} (#3090).`,
+                monitorRecord: null,
+                reviewCycle: parsed.value,
+                path: "illegal",
+            };
+        }
+        if (parts.pr !== args.pr) {
+            return {
+                exitCode: EXIT_NOT_READY,
+                message: `verify_l4_owner: review_cycle PR #${parts.pr} does not match --pr ${args.pr} (#3090). ` +
+                    "Ownership evidence must bind to the target PR.",
+                monitorRecord: null,
+                reviewCycle: parsed.value,
+                path: "none",
+            };
+        }
+    }
+    const repo = resolveRepo(args.repo ?? null, projectRoot);
+    if (repo === null) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: "verify_l4_owner: could not resolve owner/repo — pass --repo OWNER/REPO or run inside a git repo with origin",
+            monitorRecord: null,
+            reviewCycle: parsed.value,
+            path: "config",
+        };
+    }
+    const now = args.now ?? new Date();
+    const githubMonitor = fetchActiveMonitorFromGithub(repo, args.pr, {
+        now,
+        headSha: args.headSha ?? null,
+        seams: args.seams,
+    });
+    if (githubMonitor !== null && typeof githubMonitor === "object" && "error" in githubMonitor) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: `verify_l4_owner: ${oneLine(githubMonitor.error)}`,
+            monitorRecord: null,
+            reviewCycle: parsed.value,
+            path: "config",
+        };
+    }
+    if (githubMonitor !== null) {
+        const ref = parsed.value ??
+            `in_progress:${args.pr}#${githubMonitor.monitor_agent_id}`;
+        return {
+            exitCode: EXIT_READY,
+            message: `verify_l4_owner: active GitHub review-owner lease for PR #${args.pr} ` +
+                `(monitor_agent_id=${oneLine(githubMonitor.monitor_agent_id)}, owner=${oneLine(githubMonitor.owner)}) ` +
+                "— review_cycle path=lease (#3090).",
+            monitorRecord: githubMonitor,
+            reviewCycle: ref,
+            path: "lease",
+        };
+    }
+    // parent-retained is process path B — machine gate cannot verify it (lease-or-done only).
+    if (parsed.value?.startsWith("in_progress:")) {
+        const parts = parseInProgressEvidence(parsed.value);
+        if (parts?.ref === "parent-retained") {
+            return {
+                exitCode: EXIT_NOT_READY,
+                message: `verify_l4_owner: parent-retained for PR #${args.pr} is process path B only (#3090). ` +
+                    "Machine gate requires a sticky <!-- deft:review-owner --> lease or --review-cycle done. " +
+                    "Keep parent dual-source poll/fix; do not emit L4 status:pass as terminal.",
+                monitorRecord: null,
+                reviewCycle: parsed.value,
+                path: "none",
+            };
+        }
+        return {
+            exitCode: EXIT_NOT_READY,
+            message: `verify_l4_owner: review_cycle=${oneLine(parsed.value)} claims in_progress but no sticky ` +
+                `<!-- deft:review-owner --> lease found for PR #${args.pr} (#3090 / #2797).\n` +
+                "  Register: deft review-monitor:register --pr <N> --monitor-agent-id <id> --platform-primitive …",
+            monitorRecord: null,
+            reviewCycle: parsed.value,
+            path: "none",
+        };
+    }
+    return {
+        exitCode: EXIT_NOT_READY,
+        message: `verify_l4_owner: silent hold on PR #${args.pr} — no fresh sticky lease and no ` +
+            "review_cycle=done (#3090 Owner Continuity Gate).\n" +
+            "  Same turn MUST end in A (monitor+lease), B (parent-retained + next dual-source action),\n" +
+            "  or C (explicit BLOCKED/FAILED finish). Check-run SUCCESS alone is not CLEAN.",
+        monitorRecord: null,
+        reviewCycle: null,
+        path: "none",
+    };
+}
+export function l4OwnerResultToJson(result) {
+    return {
+        exit_code: result.exitCode,
+        message: result.message,
+        monitor_agent_id: result.monitorRecord?.monitor_agent_id ?? null,
+        monitor_owner: result.monitorRecord?.owner ?? null,
+        monitor_record: result.monitorRecord,
+        path: result.path,
+        ready: result.exitCode === EXIT_READY,
+        review_cycle: result.reviewCycle,
+    };
+}
+//# sourceMappingURL=l4-owner.js.map

package/dist/tool-events/classify.js

@@ -212,6 +212,7 @@ const VERIFY_TASK_VERBS = new Set([
     "verify:forward-coverage",
     "verify:story-ready",
     "verify:review-monitor",
+    "verify:l4-owner",
     "pr:watch",
     "pr:merge-ready",
     "coverage:hotspots",

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 {