@deftai/directive-core 0.102.0 → 0.104.0

package/dist/vbrief-reconcile/index.js

@@ -1,6 +1,7 @@
 export { depResolved, graphOutcomeToJson, RESOLVED_FOLDERS, reconcileGraph, renderGraphReport, } from "./graph.js";
 export { computeDesiredLabels, labelsOutcomeToJson, MANAGED_LABELS, reconcileLabels, renderLabelsReport, SCAN_FOLDERS, ScmLabelClient, ScmLabelError, } from "./labels.js";
 export { cmdVbriefReconcile, run, usage } from "./main.js";
+export { briefUpdatedOf, compareOriginFreshness, evaluateOriginFreshness, extractGithubIssueOrigin, extractGithubIssueOrigins, fetchGithubIssueUpdatedAt, formatOriginStaleMessage, ORIGIN_FRESHNESS_REMEDIATION, } from "./origin-freshness.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from "./parity-scenarios.js";
 export { pyRepr } from "./py-repr.js";
 export { buildSpecTaskIndex, detectStatusMarker, folderFromStatus, formatReconciliationMarkdown, hasDisagreement, loadOverrides, normalizeTaskId, OVERRIDES_FILENAME, parseOverridesYaml, reconcileScopeItems, writeReconciliationReport, } from "./reconciliation.js";

package/dist/vbrief-reconcile/origin-freshness.d.ts

@@ -0,0 +1,44 @@
+import { type CallOptions, type CompletedProcess } from "../scm/call.js";
+export declare const ORIGIN_FRESHNESS_REMEDIATION = "Re-read the issue body and comments (#2143), then either refresh the brief or record intentional divergence and bump xBRIEFInfo.updated. Do not auto-write origin text onto the brief (#309 D12).";
+export type OriginFreshnessKind = "no-origin" | "current" | "stale" | "uncomparable";
+export interface GithubIssueOrigin {
+    readonly owner: string;
+    readonly repo: string;
+    readonly number: number;
+    readonly uri: string;
+    readonly type: string;
+}
+export type FetchOriginUpdatedAt = (origin: GithubIssueOrigin) => {
+    updatedAt: string;
+} | {
+    error: string;
+};
+export interface EvaluateOriginFreshnessOptions {
+    readonly fetchOriginUpdatedAt?: FetchOriginUpdatedAt;
+    readonly cwd?: string;
+    readonly skip?: boolean;
+}
+export type OriginFreshnessResult = {
+    readonly ok: true;
+    readonly kind: OriginFreshnessKind;
+} | {
+    readonly ok: false;
+    readonly kind: OriginFreshnessKind;
+    readonly message: string;
+};
+export type ScmCallFn = (source: string, verb: string, args: readonly string[] | null, options?: CallOptions) => CompletedProcess;
+export declare function briefUpdatedOf(payload: Record<string, unknown>): string | null;
+export declare function extractGithubIssueOrigins(payload: Record<string, unknown>): GithubIssueOrigin[];
+export declare function extractGithubIssueOrigin(payload: Record<string, unknown>): GithubIssueOrigin | null;
+export declare function compareOriginFreshness(briefUpdated: string | null, originUpdatedAt: string | null): OriginFreshnessKind;
+export declare function formatOriginStaleMessage(origin: GithubIssueOrigin, originUpdatedAt: string, briefUpdated: string | null): string;
+export declare function fetchGithubIssueUpdatedAt(origin: GithubIssueOrigin, options?: {
+    scmCall?: ScmCallFn;
+    cwd?: string;
+}): {
+    updatedAt: string;
+} | {
+    error: string;
+};
+export declare function evaluateOriginFreshness(payload: Record<string, unknown>, options?: EvaluateOriginFreshnessOptions): OriginFreshnessResult;
+//# sourceMappingURL=origin-freshness.d.ts.map

package/dist/vbrief-reconcile/origin-freshness.js

@@ -0,0 +1,221 @@
+import { extractReferencesFromVbrief, GITHUB_ISSUE_REF_TYPES, parseIssueNumber, } from "../intake/reconcile-issues.js";
+import { call } from "../scm/call.js";
+const ISSUE_URL_PATTERN = /https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)/g;
+const ISSUE_API_URL_PATTERN = /https:\/\/api\.github\.com\/repos\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)/g;
+export const ORIGIN_FRESHNESS_REMEDIATION = "Re-read the issue body and comments (#2143), then either refresh the brief or record intentional divergence and bump xBRIEFInfo.updated. Do not auto-write origin text onto the brief (#309 D12).";
+export function briefUpdatedOf(payload) {
+    const info = payload.xBRIEFInfo;
+    if (info !== null && typeof info === "object" && !Array.isArray(info)) {
+        const updated = info.updated;
+        if (typeof updated === "string" && updated.trim().length > 0) {
+            return updated.trim();
+        }
+    }
+    const plan = payload.plan;
+    if (plan !== null && typeof plan === "object" && !Array.isArray(plan)) {
+        const updated = plan.updated;
+        if (typeof updated === "string" && updated.trim().length > 0) {
+            return updated.trim();
+        }
+    }
+    return null;
+}
+export function extractGithubIssueOrigins(payload) {
+    const origins = [];
+    const seen = new Set();
+    const add = (origin) => {
+        const key = `${origin.owner}/${origin.repo}#${origin.number}`;
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        origins.push(origin);
+    };
+    for (const rec of extractReferencesFromVbrief(payload)) {
+        const type = String(rec.type ?? "");
+        if (!GITHUB_ISSUE_REF_TYPES.has(type)) {
+            continue;
+        }
+        const fromUri = originFromUri(rec);
+        let origin = fromUri !== null ? { ...fromUri, type } : null;
+        if (origin === null) {
+            const number = parseIssueNumber(rec);
+            if (number === null) {
+                continue;
+            }
+            origin = {
+                owner: "",
+                repo: "",
+                number,
+                uri: typeof rec.uri === "string" ? rec.uri : "",
+                type,
+            };
+        }
+        add(origin);
+    }
+    for (const text of textualOriginFields(payload)) {
+        for (const fromText of originsFromText(text)) {
+            add({ ...fromText, type: "x-xbrief/github-issue" });
+        }
+    }
+    return origins;
+}
+export function extractGithubIssueOrigin(payload) {
+    return extractGithubIssueOrigins(payload)[0] ?? null;
+}
+function originFromUri(ref) {
+    for (const key of ["uri", "url"]) {
+        const value = ref[key];
+        if (typeof value !== "string" || value.length === 0) {
+            continue;
+        }
+        const parsed = originFromText(value);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function originsFromText(text) {
+    const origins = [];
+    const seen = new Set();
+    for (const pattern of [ISSUE_URL_PATTERN, ISSUE_API_URL_PATTERN]) {
+        for (const match of text.matchAll(pattern)) {
+            if (!match[1] || !match[2] || !match[3]) {
+                continue;
+            }
+            const owner = match[1];
+            const repo = match[2];
+            const number = Number.parseInt(match[3], 10);
+            const key = `${owner}/${repo}#${number}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            origins.push({
+                owner,
+                repo,
+                number,
+                uri: `https://github.com/${owner}/${repo}/issues/${number}`,
+            });
+        }
+    }
+    return origins;
+}
+function originFromText(text) {
+    return originsFromText(text)[0] ?? null;
+}
+function textualOriginFields(payload) {
+    const texts = [];
+    const plan = payload.plan;
+    if (plan !== null && typeof plan === "object" && !Array.isArray(plan)) {
+        const narratives = plan.narratives;
+        if (narratives !== null && typeof narratives === "object" && !Array.isArray(narratives)) {
+            const origin = narratives.Origin;
+            if (typeof origin === "string" && origin.length > 0) {
+                texts.push(origin);
+            }
+        }
+    }
+    for (const key of ["xBRIEFInfo", "vBRIEFInfo"]) {
+        const info = payload[key];
+        if (info !== null && typeof info === "object" && !Array.isArray(info)) {
+            const description = info.description;
+            if (typeof description === "string" && description.length > 0) {
+                texts.push(description);
+            }
+        }
+    }
+    return texts;
+}
+export function compareOriginFreshness(briefUpdated, originUpdatedAt) {
+    if (originUpdatedAt === null || originUpdatedAt.trim().length === 0) {
+        return "uncomparable";
+    }
+    if (briefUpdated === null || briefUpdated.trim().length === 0) {
+        return "stale";
+    }
+    const briefMs = Date.parse(briefUpdated);
+    const originMs = Date.parse(originUpdatedAt);
+    if (Number.isNaN(briefMs) || Number.isNaN(originMs)) {
+        return "uncomparable";
+    }
+    return originMs > briefMs ? "stale" : "current";
+}
+export function formatOriginStaleMessage(origin, originUpdatedAt, briefUpdated) {
+    const slug = origin.owner.length > 0 ? `${origin.owner}/${origin.repo}` : "origin";
+    const briefStamp = briefUpdated ?? "(missing)";
+    return (`Origin GitHub issue #${origin.number} (${slug}) is newer than this xBRIEF ` +
+        `(origin updated_at=${originUpdatedAt}, brief updated=${briefStamp}). ` +
+        ORIGIN_FRESHNESS_REMEDIATION);
+}
+export function fetchGithubIssueUpdatedAt(origin, options = {}) {
+    if (origin.owner.length === 0 || origin.repo.length === 0) {
+        return { error: "origin reference is missing owner/repo in the GitHub issue URI" };
+    }
+    const scmCall = options.scmCall ?? call;
+    let result;
+    try {
+        result = scmCall("github-issue", "api", [`repos/${origin.owner}/${origin.repo}/issues/${origin.number}`], { timeout: 30, cwd: options.cwd });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: `gh CLI not available (${message})` };
+    }
+    if (result.returncode !== 0) {
+        const stderr = result.stderr.trim();
+        return { error: stderr.length > 0 ? stderr : `gh api exited ${result.returncode}` };
+    }
+    try {
+        const payload = JSON.parse(result.stdout);
+        const updatedAt = payload.updated_at;
+        if (typeof updatedAt !== "string" || updatedAt.trim().length === 0) {
+            return { error: "origin issue payload lacks updated_at" };
+        }
+        return { updatedAt: updatedAt.trim() };
+    }
+    catch {
+        return { error: "origin issue payload is not valid JSON" };
+    }
+}
+export function evaluateOriginFreshness(payload, options = {}) {
+    if (options.skip === true) {
+        return { ok: true, kind: "no-origin" };
+    }
+    const origins = extractGithubIssueOrigins(payload);
+    if (origins.length === 0) {
+        return { ok: true, kind: "no-origin" };
+    }
+    const fetch = options.fetchOriginUpdatedAt ??
+        ((next) => fetchGithubIssueUpdatedAt(next, { cwd: options.cwd }));
+    const briefUpdated = briefUpdatedOf(payload);
+    for (const origin of origins) {
+        const fetched = fetch(origin);
+        if ("error" in fetched) {
+            return {
+                ok: false,
+                kind: "uncomparable",
+                message: `Could not fetch origin GitHub issue #${origin.number} for freshness check: ${fetched.error}. ` +
+                    ORIGIN_FRESHNESS_REMEDIATION,
+            };
+        }
+        const kind = compareOriginFreshness(briefUpdated, fetched.updatedAt);
+        if (kind === "stale") {
+            return {
+                ok: false,
+                kind,
+                message: formatOriginStaleMessage(origin, fetched.updatedAt, briefUpdated),
+            };
+        }
+        if (kind === "uncomparable") {
+            return {
+                ok: false,
+                kind,
+                message: `Could not compare origin GitHub issue #${origin.number} updated_at=${fetched.updatedAt} ` +
+                    `to brief updated=${briefUpdated ?? "(missing)"}. ${ORIGIN_FRESHNESS_REMEDIATION}`,
+            };
+        }
+    }
+    return { ok: true, kind: "current" };
+}
+//# sourceMappingURL=origin-freshness.js.map

package/dist/verify-ac/evaluate.d.ts

@@ -27,6 +27,16 @@ export interface OracleIntegrityResultFields {
     readonly code: number;
     readonly message: string;
 }
+/** Stable prefix for product-oracle check ids emitted by verify:ac (#3322 / #3337). */
+export declare const VERIFY_AC_CHECK_ID_PREFIX = "verify:ac";
+/**
+ * Namespace product-oracle check_id per active scope (#3337).
+ *
+ * Same-session multi-active verify:ac must not pair fail/pass across briefs.
+ * Prefer plan.id or xBRIEF path as scopeKey; empty → global fallback `verify:ac`
+ * (unknown-scope single-brief / tests without a plan).
+ */
+export declare function verifyAcCheckId(scopeKey?: string | null): string;
 /** Test seam: isolate stdout-dest buffer across cases. */
 export declare function resetInProcessVerificationBuffer(): void;
 /**
@@ -34,12 +44,20 @@ export declare function resetInProcessVerificationBuffer(): void;
  * Fail-open: missing dest / write errors never change the AC result.
  * Stdout dest also appends to the same-process buffer so evaluate can
  * inspect this invocation without re-reading a file.
+ * check_id is namespaced per active scope when scopeKey is provided (#3337).
  */
 export declare function emitVerifyAcAttempts(options: {
     readonly projectRoot: string;
     readonly runs: readonly LiteralAcceptanceRunResult[];
     readonly env?: NodeJS.ProcessEnv;
     readonly sessionId?: string;
+    /**
+     * Active scope identity (plan.id or xBRIEF path stem). When set, check_id
+     * becomes `verify:ac/<scopeKey>` so multi-active sessions do not false-deny (#3337).
+     */
+    readonly scopeKey?: string | null;
+    /** Full check_id override (tests). Wins over scopeKey when non-empty. */
+    readonly checkId?: string | null;
     /** stdout seam (tests). */
     readonly writeStdout?: (line: string) => void;
 }): void;

package/dist/verify-ac/evaluate.js

@@ -16,7 +16,24 @@ function formatUnresolved(flag) {
     return (`check_id=${flag.check_id} fail method=${flag.failed_method} ` +
         `then pass method=${flag.passed_method} without independent re-derivation`);
 }
-const VERIFY_AC_CHECK_ID = "verify:ac";
+/** Stable prefix for product-oracle check ids emitted by verify:ac (#3322 / #3337). */
+export const VERIFY_AC_CHECK_ID_PREFIX = "verify:ac";
+/**
+ * Namespace product-oracle check_id per active scope (#3337).
+ *
+ * Same-session multi-active verify:ac must not pair fail/pass across briefs.
+ * Prefer plan.id or xBRIEF path as scopeKey; empty → global fallback `verify:ac`
+ * (unknown-scope single-brief / tests without a plan).
+ */
+export function verifyAcCheckId(scopeKey) {
+    const key = typeof scopeKey === "string" ? scopeKey.trim() : "";
+    if (key.length === 0) {
+        return VERIFY_AC_CHECK_ID_PREFIX;
+    }
+    // Keep pairing keys readable; strip control chars that would corrupt JSONL.
+    const safe = key.replace(/[\0\n\r]/g, "_");
+    return `${VERIFY_AC_CHECK_ID_PREFIX}/${safe}`;
+}
 /** Same-process verification JSONL when dest is stdout (`-`). */
 const inProcessVerificationLines = [];
 let inProcessStdoutSessionId;
@@ -36,6 +53,7 @@ function inProcessVerificationText() {
  * Fail-open: missing dest / write errors never change the AC result.
  * Stdout dest also appends to the same-process buffer so evaluate can
  * inspect this invocation without re-reading a file.
+ * check_id is namespaced per active scope when scopeKey is provided (#3337).
  */
 export function emitVerifyAcAttempts(options) {
     if (options.runs.length === 0) {
@@ -57,6 +75,10 @@ export function emitVerifyAcAttempts(options) {
                 sessionId = randomUUID();
             }
         }
+        const explicitCheck = typeof options.checkId === "string" && options.checkId.trim().length > 0
+            ? options.checkId.trim()
+            : null;
+        const checkId = explicitCheck ?? verifyAcCheckId(options.scopeKey);
         const emitter = new RunSummaryEmitter({
             projectRoot,
             sessionId,
@@ -65,7 +87,7 @@ export function emitVerifyAcAttempts(options) {
         });
         for (const run of options.runs) {
             const emitted = emitter.emitVerification({
-                check_id: VERIFY_AC_CHECK_ID,
+                check_id: checkId,
                 method_fingerprint: `${run.command}\0${run.cwd}`,
                 outcome: run.ok ? "pass" : "fail",
             });

package/dist/verify-ac/index.d.ts

@@ -5,6 +5,6 @@
  * by editing the comparison. Deterministic surface is the flagged event.
  */
 export { type AcceptanceClause, type AcceptanceClauseReading, type ClauseOutcome, type ClauseWalkReport, type ClauseWalkResult, deriveAcceptanceClauses, formatClauseWalkMessage, isScratchArtifactPath, readAcceptanceClauses, serializeAcceptanceClauses, stampDerivedClausesOnAcceptance, walkAcceptanceClauses, } from "./clauses.js";
-export { type EvaluateProductOracleIntegrityOptions, emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, type OracleIntegrityResultFields, type ProductOracleIntegrityVerdict, } from "./evaluate.js";
+export { type EvaluateProductOracleIntegrityOptions, emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, type OracleIntegrityResultFields, type ProductOracleIntegrityVerdict, VERIFY_AC_CHECK_ID_PREFIX, verifyAcCheckId, } from "./evaluate.js";
 export { type FlaggedMethodChangePass, flagPassAfterFailFromJsonl, flagPassAfterFailWithMethodChange, readVerificationAttempts, unresolvedMethodChangePasses, type VerificationAttempt, } from "./flag.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/verify-ac/index.js

@@ -5,6 +5,6 @@
  * by editing the comparison. Deterministic surface is the flagged event.
  */
 export { deriveAcceptanceClauses, formatClauseWalkMessage, isScratchArtifactPath, readAcceptanceClauses, serializeAcceptanceClauses, stampDerivedClausesOnAcceptance, walkAcceptanceClauses, } from "./clauses.js";
-export { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, } from "./evaluate.js";
+export { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, VERIFY_AC_CHECK_ID_PREFIX, verifyAcCheckId, } from "./evaluate.js";
 export { flagPassAfterFailFromJsonl, flagPassAfterFailWithMethodChange, readVerificationAttempts, unresolvedMethodChangePasses, } from "./flag.js";
 //# sourceMappingURL=index.js.map

package/dist/verify-source/index.d.ts

@@ -1,3 +1,4 @@
+export * from "../telemetry-coverage/index.js";
 export * from "./biome-config.js";
 export * from "./code-structure-validate.js";
 export * from "./contained-writes.js";

package/dist/verify-source/index.js

@@ -1,3 +1,4 @@
+export * from "../telemetry-coverage/index.js";
 export * from "./biome-config.js";
 export * from "./code-structure-validate.js";
 export * from "./contained-writes.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -382,8 +382,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.102.0",
-    "@deftai/directive-types": "^0.102.0",
+    "@deftai/directive-content": "^0.104.0",
+    "@deftai/directive-types": "^0.104.0",
     "archiver": "^8.0.0"
   },
   "scripts": {