@deftai/directive-core 0.92.0 → 0.94.0

package/dist/vbrief-reconcile/umbrellas.js

@@ -1,15 +1,18 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
-import { createIssueComment, editIssueCommentBody, GitHubBodyError, } from "../intake/github-body.js";
+import { createIssueComment, editIssueBody, editIssueCommentBody, fetchIssueBody, GitHubBodyError, } from "../intake/github-body.js";
+import { fetchIssueStates, IssueState } from "../intake/reconcile-issues.js";
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
-import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
+import { extractIssueRef, parseGithubIssueUri } from "../triage/reconcile/parse-uri.js";
 import { isRepoMutationAllowed } from "./repo-guard.js";
 export const OPEN_FOLDERS = ["proposed", "pending", "active"];
 export const CLOSED_FOLDERS = ["completed", "cancelled"];
 export const LIFECYCLE_FOLDERS = [...OPEN_FOLDERS, ...CLOSED_FOLDERS];
 export const CHILD_REF_TYPE = "x-xbrief/plan";
+/** Synthetic lifecycle folder for issue-only children with no local xBRIEF (#1649). */
+export const UNKNOWN_FOLDER = "unknown";
 const SCM_SOURCE = "github-issue";
 const HEADER_RE = /^## Current shape \(as of pass-(\d+)\)/m;
 // ReDoS-hardened (#1782 s4 / CodeQL js/polynomial-redos): the original
@@ -23,6 +26,12 @@ const HISTORY_RE = /^Child-count history:\s*(\S.*|)$/m;
 const LAST_UPDATED_RE = /^Last updated:\s*(\S.*|)$/m;
 const LAST_PASS_TYPE_RE = /^Last pass type:\s*(\S.*|)$/m;
 const HISTORY_TOKEN_RE = /^\s*pass-(\d+):\s*(\d+)\s*$/;
+/**
+ * Issue-body checklist line with a `#N` child ref (#1649).
+ * Captures leading marker, checkbox state, and the remainder after `]`.
+ * Linear-time: no nested quantifiers on overlapping classes.
+ */
+const CHECKLIST_ISSUE_LINE_RE = /^([ \t]*[-*+][ \t]+)\[([ xX])\]([ \t]*#[0-9]+\b.*)$/;
 const READING_ORDER = "1. Read the umbrella issue body.\n" +
     "2. Read this current-shape comment.\n" +
     "3. Read the amendment comments in chronological order for the full audit trail.";
@@ -52,12 +61,14 @@ export function childFromData(data, folder, fallbackId) {
         : {};
     const rawDeps = swarm.depends_on;
     const dependsOn = Array.isArray(rawDeps) ? rawDeps.map((d) => String(d)) : [];
+    const [, issueNumber] = extractIssueRef(data);
     return {
         story_id: String(plan.id ?? fallbackId),
         title: String(plan.title ?? plan.id ?? fallbackId),
         kind: String(metadata.kind ?? "story"),
         folder,
         depends_on: dependsOn,
+        issue_number: issueNumber,
     };
 }
 export function buildChildIndex(vbriefDir) {
@@ -80,7 +91,22 @@ export function buildChildIndex(vbriefDir) {
     }
     return index;
 }
-export function computeChildren(epicData, index) {
+/** Index children by forge issue number for github-issue ref resolution (#1649). */
+export function indexChildrenByIssueNumber(index) {
+    const byIssue = new Map();
+    for (const child of Object.values(index)) {
+        if (typeof child.issue_number === "number" && !byIssue.has(child.issue_number)) {
+            byIssue.set(child.issue_number, child);
+        }
+    }
+    return byIssue;
+}
+/**
+ * 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 function computeChildren(epicData, index, options = {}) {
     const plan = typeof epicData.plan === "object" && epicData.plan !== null && !Array.isArray(epicData.plan)
         ? epicData.plan
         : {};
@@ -89,21 +115,102 @@ export function computeChildren(epicData, index) {
     const seen = new Set();
     if (!Array.isArray(refs))
         return children;
+    const byIssue = indexChildrenByIssueNumber(index);
+    const epicIssue = options.epicIssueNumber ?? null;
     for (const ref of refs) {
         if (typeof ref !== "object" || ref === null || Array.isArray(ref))
             continue;
         const rec = ref;
-        if (!referenceTypeMatches(String(rec.type ?? ""), "plan"))
-            continue;
-        const name = basename(String(rec.uri ?? ""));
-        const child = index[name];
-        if (!child || seen.has(child.story_id))
+        const refType = String(rec.type ?? "");
+        if (referenceTypeMatches(refType, "plan")) {
+            const name = basename(String(rec.uri ?? ""));
+            const child = index[name];
+            if (!child || seen.has(child.story_id))
+                continue;
+            seen.add(child.story_id);
+            children.push(child);
             continue;
-        seen.add(child.story_id);
-        children.push(child);
+        }
+        if (referenceTypeMatches(refType, "github-issue")) {
+            const [, number] = parseGithubIssueUri(rec.uri);
+            if (number === null)
+                continue;
+            if (epicIssue !== null && number === epicIssue)
+                continue;
+            const fromIndex = byIssue.get(number);
+            if (fromIndex) {
+                if (seen.has(fromIndex.story_id))
+                    continue;
+                seen.add(fromIndex.story_id);
+                children.push(fromIndex);
+                continue;
+            }
+            // Synthetic child: hand-filed / issue:emit epic with issue-only child links.
+            const syntheticId = `#${number}`;
+            if (seen.has(syntheticId))
+                continue;
+            seen.add(syntheticId);
+            const title = typeof rec.title === "string" && rec.title.trim().length > 0
+                ? rec.title.trim()
+                : syntheticId;
+            children.push({
+                story_id: syntheticId,
+                title,
+                kind: "story",
+                folder: UNKNOWN_FOLDER,
+                depends_on: [],
+                issue_number: number,
+            });
+        }
     }
     return children;
 }
+/**
+ * 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 function isChildOpen(child, forgeStates) {
+    if (typeof child.issue_number === "number" &&
+        forgeStates != null &&
+        forgeStates.has(child.issue_number)) {
+        return forgeStates.get(child.issue_number) === "open";
+    }
+    if (CLOSED_FOLDERS.includes(child.folder))
+        return false;
+    // proposed/pending/active/unknown (and any unexpected folder) → open
+    return true;
+}
+/**
+ * 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 function reconcileBodyChecklist(body, closedIssueNumbers, knownIssueNumbers) {
+    if (knownIssueNumbers.size === 0)
+        return { body, changed: false };
+    const lines = body.split("\n");
+    let changed = false;
+    const out = lines.map((line) => {
+        const match = CHECKLIST_ISSUE_LINE_RE.exec(line);
+        if (!match)
+            return line;
+        const issueMatch = /#(\d+)\b/.exec(match[3] ?? "");
+        if (!issueMatch?.[1])
+            return line;
+        const issueNum = Number(issueMatch[1]);
+        if (!knownIssueNumbers.has(issueNum))
+            return line;
+        const wantChecked = closedIssueNumbers.has(issueNum);
+        const isChecked = (match[2] ?? " ").toLowerCase() === "x";
+        if (isChecked === wantChecked)
+            return line;
+        changed = true;
+        const marker = wantChecked ? "x" : " ";
+        return `${match[1]}[${marker}]${match[3]}`;
+    });
+    return { body: out.join("\n"), changed };
+}
 export function computeWaves(children) {
     const ids = new Set(children.map((c) => c.story_id));
     const deps = {};
@@ -249,18 +356,92 @@ export class ScmUmbrellaClient {
             throw new UmbrellaScmError(`create comment #${issueNumber} (${repo}) failed: ${message}`);
         }
     }
+    fetchIssueStates(repo, issueNumbers) {
+        const result = new Map();
+        if (issueNumbers.length === 0)
+            return result;
+        const states = fetchIssueStates(repo, new Set(issueNumbers));
+        if (states === null) {
+            throw new UmbrellaScmError(`fetch issue states (${repo}) failed`);
+        }
+        for (const [num, state] of states) {
+            if (!(state instanceof IssueState))
+                continue;
+            const value = state.value.toUpperCase();
+            if (value === "OPEN")
+                result.set(num, "open");
+            else if (value === "CLOSED")
+                result.set(num, "closed");
+            // NOT_FOUND / other → omit so folder fallback applies
+        }
+        return result;
+    }
+    fetchIssueBody(repo, issueNumber) {
+        try {
+            return fetchIssueBody(repo, issueNumber);
+        }
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`fetch issue body #${issueNumber} (${repo}) failed: ${message}`);
+        }
+    }
+    editIssueBody(repo, issueNumber, body) {
+        try {
+            editIssueBody(repo, issueNumber, { body });
+        }
+        catch (exc) {
+            const message = exc instanceof GitHubBodyError ? exc.message : String(exc);
+            throw new UmbrellaScmError(`edit issue body #${issueNumber} (${repo}) failed: ${message}`);
+        }
+    }
 }
-function planShape(epicData, index) {
-    const children = computeChildren(epicData, index);
+function planShape(epicData, index, options = {}) {
+    const children = computeChildren(epicData, index, {
+        epicIssueNumber: options.epicIssueNumber,
+    });
     const openChildren = children
-        .filter((c) => OPEN_FOLDERS.includes(c.folder))
+        .filter((c) => isChildOpen(c, options.forgeStates))
         .sort((a, b) => a.story_id.localeCompare(b.story_id));
     const closedChildren = children
-        .filter((c) => !OPEN_FOLDERS.includes(c.folder))
+        .filter((c) => !isChildOpen(c, options.forgeStates))
         .sort((a, b) => a.story_id.localeCompare(b.story_id));
     const waves = computeWaves(children);
     return [openChildren, closedChildren, waves];
 }
+function resolveForgeStates(client, repo, children) {
+    if (typeof client.fetchIssueStates !== "function")
+        return null;
+    const numbers = children
+        .map((c) => c.issue_number)
+        .filter((n) => typeof n === "number");
+    if (numbers.length === 0)
+        return null;
+    return client.fetchIssueStates(repo, numbers);
+}
+function reconcileChecklistForEpic(client, repo, issueNumber, closedChildren, allChildren, dryRun) {
+    if (typeof client.fetchIssueBody !== "function" || typeof client.editIssueBody !== "function") {
+        return "skipped";
+    }
+    const known = new Set();
+    for (const c of allChildren) {
+        if (typeof c.issue_number === "number")
+            known.add(c.issue_number);
+    }
+    if (known.size === 0)
+        return "skipped";
+    const closed = new Set();
+    for (const c of closedChildren) {
+        if (typeof c.issue_number === "number")
+            closed.add(c.issue_number);
+    }
+    const currentBody = client.fetchIssueBody(repo, issueNumber);
+    const { body: nextBody, changed } = reconcileBodyChecklist(currentBody, closed, known);
+    if (!changed)
+        return "unchanged";
+    if (!dryRun)
+        client.editIssueBody(repo, issueNumber, nextBody);
+    return "edited";
+}
 function reconcileOneEpic(epicData, index, options) {
     const mutateGate = isRepoMutationAllowed(options.repo, options.projectRoot, {
         allowCrossRepo: options.allowCrossRepo,
@@ -270,10 +451,28 @@ function reconcileOneEpic(epicData, index, options) {
     if (!mutateGate.allowed) {
         throw new Error(mutateGate.reason ?? `refusing cross-repo mutation on ${options.repo}`);
     }
-    const [openChildren, closedChildren, waves] = planShape(epicData, index);
-    const total = openChildren.length + closedChildren.length;
+    // Resolve children once without forge state to know which issue numbers to fetch.
+    const childrenProbe = computeChildren(epicData, index, {
+        epicIssueNumber: options.number,
+    });
+    const forgeStates = resolveForgeStates(options.client, options.repo, childrenProbe);
+    const [openChildren, closedChildren, waves] = planShape(epicData, index, {
+        epicIssueNumber: options.number,
+        forgeStates,
+    });
+    const allChildren = [...openChildren, ...closedChildren];
+    const total = allChildren.length;
     const comments = options.client.fetchComments(options.repo, options.number);
     const existing = comments.find((c) => hasCurrentShape(c.body));
+    let checklistAction = "skipped";
+    try {
+        checklistAction = reconcileChecklistForEpic(options.client, options.repo, options.number, closedChildren, allChildren, options.dryRun);
+    }
+    catch (exc) {
+        // Checklist is best-effort relative to comment path: surface as throw so
+        // callers see the failure (body drift is the #1649 user-visible bug).
+        throw new UmbrellaScmError(exc instanceof Error ? exc.message : `checklist reconcile failed: ${String(exc)}`);
+    }
     if (!existing) {
         const body = renderBody({
             passN: 1,
@@ -293,6 +492,7 @@ function reconcileOneEpic(epicData, index, options) {
             action: "created",
             pass_n: 1,
             body,
+            checklist_action: checklistAction,
         };
     }
     const parsed = parseCurrentShape(existing.body);
@@ -308,13 +508,16 @@ function reconcileOneEpic(epicData, index, options) {
         history: parsed.history.length > 0 ? parsed.history : [[prevPass, total]],
     });
     if (candidate === existing.body) {
+        // Comment unchanged; still report edited when checklist flipped (#1649).
+        const action = checklistAction === "edited" ? "edited" : "unchanged";
         return {
             story_id: options.storyId,
             repo: options.repo,
             issue_number: options.number,
-            action: "unchanged",
+            action,
             pass_n: prevPass,
             body: candidate,
+            checklist_action: checklistAction,
         };
     }
     const passN = prevPass + 1;
@@ -336,6 +539,7 @@ function reconcileOneEpic(epicData, index, options) {
         action: "edited",
         pass_n: passN,
         body,
+        checklist_action: checklistAction,
     };
 }
 export function nowIso(date = new Date()) {
@@ -441,13 +645,19 @@ export function reconcileUmbrellas(projectRoot, options = {}) {
     }
     return [outcome.errors.length > 0 ? 1 : 0, outcome];
 }
+function formatChecklistSuffix(action) {
+    if (action === undefined || action === "skipped")
+        return "";
+    return `; checklist=${action}`;
+}
 export function renderUmbrellasReport(outcome) {
     const lines = ["vBRIEF reconcile umbrellas", ""];
     const suffix = outcome.dry_run ? " (dry-run)" : "";
     lines.push(`Changed${suffix}:`);
     if (outcome.changed.length > 0) {
         for (const c of outcome.changed) {
-            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: ${c.action} -> pass-${c.pass_n}`);
+            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: ${c.action} -> pass-${c.pass_n}` +
+                formatChecklistSuffix(c.checklist_action));
         }
     }
     else {
@@ -457,7 +667,8 @@ export function renderUmbrellasReport(outcome) {
     lines.push("Unchanged:");
     if (outcome.unchanged.length > 0) {
         for (const c of outcome.unchanged) {
-            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: pass-${c.pass_n}`);
+            lines.push(`- #${c.issue_number} (${c.repo}) [${c.story_id}]: pass-${c.pass_n}` +
+                formatChecklistSuffix(c.checklist_action));
         }
     }
     else {
@@ -484,6 +695,7 @@ export function umbrellasOutcomeToJson(outcome) {
         issue_number: c.issue_number,
         action: c.action,
         pass_n: c.pass_n,
+        checklist_action: c.checklist_action ?? "skipped",
     });
     return {
         changed: outcome.changed.map(toChange),

package/dist/vbrief-validate/plan-hooks.d.ts

@@ -8,6 +8,10 @@ export declare function validateTriageRankingLabelsOnPlan(plan: unknown, filepat
 export declare function validateRuntimeAuthorityOnPlan(plan: unknown, filepath: string): string[];
 /** vbrief_validate hook: validate ``plan.policy.hostHooks`` (#2752). */
 export declare function validateHostHooksOnPlan(plan: unknown, filepath: string): string[];
+/** vbrief_validate hook: validate ``plan.policy.hostSlashCommands`` (#3054). */
+export declare function validateHostSlashCommandsOnPlan(plan: unknown, filepath: string): string[];
+/** vbrief_validate hook: validate ``plan.policy.openClawProductCommands`` (#3064). */
+export declare function validateOpenClawProductCommandsOnPlan(plan: unknown, filepath: string): string[];
 /** vbrief_validate hook: validate ``plan.policy.stalenessTickler`` (#2489). */
 export declare function validateStalenessTicklerOnPlan(plan: unknown, filepath: string): string[];
 /** Run all PROJECT-DEFINITION policy hooks (mirrors lazy-import block in Python). */

package/dist/vbrief-validate/plan-hooks.js

@@ -1,7 +1,9 @@
 import { validateHostHooks } from "../policy/host-hooks.js";
+import { validateHostSlashCommands } from "../policy/host-slash-commands.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { validateRuntimeAuthority } from "../policy/runtime-authority.js";
 import { validateStalenessTickler } from "../policy/staleness-tickler.js";
+import { validateOpenClawProductCommands } from "../slash/openclaw-deposit.js";
 import { validateTriageAutoClassifyOnPlan, validateTriageHoldMarkersOnPlan, } from "../triage/classify/index.js";
 import { validateRankingLabels } from "../triage/queue/ranking-labels.js";
 import { pyStrRepr, pythonTypeName } from "../triage/scope/python-repr.js";
@@ -140,6 +142,42 @@ export function validateHostHooksOnPlan(plan, filepath) {
     }
     return out;
 }
+/** vbrief_validate hook: validate ``plan.policy.hostSlashCommands`` (#3054). */
+export function validateHostSlashCommandsOnPlan(plan, filepath) {
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const policy = readPlanPolicy(plan);
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return [];
+    }
+    if (!("hostSlashCommands" in policy)) {
+        return [];
+    }
+    const out = [];
+    for (const err of validateHostSlashCommands(policy.hostSlashCommands)) {
+        out.push(`${filepath}: ${err} (#3054)`);
+    }
+    return out;
+}
+/** vbrief_validate hook: validate ``plan.policy.openClawProductCommands`` (#3064). */
+export function validateOpenClawProductCommandsOnPlan(plan, filepath) {
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return [];
+    }
+    const policy = readPlanPolicy(plan);
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return [];
+    }
+    if (!("openClawProductCommands" in policy)) {
+        return [];
+    }
+    const out = [];
+    for (const err of validateOpenClawProductCommands(policy.openClawProductCommands)) {
+        out.push(`${filepath}: ${err} (#3064)`);
+    }
+    return out;
+}
 /** vbrief_validate hook: validate ``plan.policy.stalenessTickler`` (#2489). */
 export function validateStalenessTicklerOnPlan(plan, filepath) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
@@ -216,6 +254,18 @@ export function runProjectDefinitionHooks(plan, filepath) {
     catch {
         /* hook must not break validation */
     }
+    try {
+        errors.push(...validateHostSlashCommandsOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
+    try {
+        errors.push(...validateOpenClawProductCommandsOnPlan(plan, filepath));
+    }
+    catch {
+        /* hook must not break validation */
+    }
     return errors;
 }
 //# sourceMappingURL=plan-hooks.js.map

package/dist/xbrief/create.d.ts

@@ -0,0 +1,36 @@
+/**
+ * xbrief:create — write a dense xBRIEF artifact at --out (#3057).
+ *
+ * Required: --format (json|md|both), --out
+ * Optional: --style, --title, --id, --status, --description, --force, --project-root
+ *
+ * Does NOT move lifecycle folders. Not scope:promote / activate / complete.
+ */
+import { type XbriefCliResult, type XbriefFormat, type XbriefStyle } from "./types.js";
+export declare const CREATE_USAGE: string;
+export interface CreateOptions {
+    format: XbriefFormat;
+    out: string;
+    style: XbriefStyle;
+    title?: string;
+    id?: string;
+    status?: string;
+    description?: string;
+    fromJson?: string;
+    force?: boolean;
+    projectRoot: string;
+    sizeCapBytes?: number;
+    cwd?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+}
+/** Parse create CLI argv into options (or error string). */
+export declare function parseCreateArgv(argv: readonly string[]): CreateOptions | {
+    error: string;
+};
+/** Core create implementation (testable). */
+export declare function createXbrief(options: CreateOptions): XbriefCliResult;
+/** CLI entry for dispatch wrapper. */
+export declare function runXbriefCreateCli(argv: string[]): XbriefCliResult;
+//# sourceMappingURL=create.d.ts.map