@deftai/directive-core 0.81.0 → 0.82.0

package/dist/content-contracts/skills/helpers.d.ts

@@ -8,6 +8,7 @@ export declare function repoPath(...segments: string[]): string;
  * first (SOURCE layout), then fall back to the repo root so root-resident
  * harness entries (AGENTS.md) and the flattened consumer layout still resolve.
  */
+export declare function resolveContentPathFromRoot(projectRoot: string, relPath: string): string;
 export declare function resolveRepoPath(relPath: string): string;
 export declare function readRepoFile(relPath: string): string;
 export declare function repoFileExists(relPath: string): boolean;
@@ -15,7 +16,12 @@ export declare function readSkill(relPath: string): string;
 export declare function readAgentsMd(): string;
 /** Slice the first `## Returning Sessions` section body out of AGENTS.md. */
 export declare function returningSessionsSection(): string;
+export declare function listSkillMdFilesFromRoot(projectRoot: string): string[];
 export declare function listSkillMdFiles(): string[];
+export declare function listSkillMdEntriesFromRoot(projectRoot: string): ReadonlyArray<{
+    path: string;
+    text: string;
+}>;
 export declare const RFC2119_LEGEND = "!=MUST, ~=SHOULD";
 export declare const PLATFORM_DETECTION_HEADING = "## Platform Detection";
 export declare const USER_MD_GATE_HEADING = "## USER.md Gate";

package/dist/content-contracts/skills/helpers.js

@@ -13,12 +13,15 @@ export function repoPath(...segments) {
  * first (SOURCE layout), then fall back to the repo root so root-resident
  * harness entries (AGENTS.md) and the flattened consumer layout still resolve.
  */
-export function resolveRepoPath(relPath) {
-    const underContent = join(REPO_ROOT, "content", relPath);
+export function resolveContentPathFromRoot(projectRoot, relPath) {
+    const underContent = join(projectRoot, "content", relPath);
     if (existsSync(underContent)) {
         return underContent;
     }
-    return repoPath(relPath);
+    return join(projectRoot, relPath);
+}
+export function resolveRepoPath(relPath) {
+    return resolveContentPathFromRoot(REPO_ROOT, relPath);
 }
 export function readRepoFile(relPath) {
     return readFileSync(resolveRepoPath(relPath), "utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -43,6 +46,26 @@ export function returningSessionsSection() {
     const nextHeading = rest.indexOf("\n## ");
     return nextHeading === -1 ? rest : rest.slice(0, nextHeading);
 }
+function skillsDirFromRoot(projectRoot) {
+    const resolved = resolveContentPathFromRoot(projectRoot, "skills");
+    return existsSync(resolved) ? resolved : null;
+}
+export function listSkillMdFilesFromRoot(projectRoot) {
+    const skillsDir = skillsDirFromRoot(projectRoot);
+    if (skillsDir === null) {
+        return [];
+    }
+    const results = [];
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            const skillMd = join(skillsDir, entry.name, "SKILL.md");
+            if (existsSync(skillMd)) {
+                results.push(join("skills", entry.name, "SKILL.md"));
+            }
+        }
+    }
+    return results.sort();
+}
 export function listSkillMdFiles() {
     const skillsDir = resolveRepoPath("skills");
     const results = [];
@@ -56,6 +79,27 @@ export function listSkillMdFiles() {
     }
     return results.sort();
 }
+export function listSkillMdEntriesFromRoot(projectRoot) {
+    const skillsDir = skillsDirFromRoot(projectRoot);
+    if (skillsDir === null) {
+        return [];
+    }
+    const entries = [];
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const skillMd = join(skillsDir, entry.name, "SKILL.md");
+        if (!existsSync(skillMd)) {
+            continue;
+        }
+        entries.push({
+            path: join("skills", entry.name, "SKILL.md"),
+            text: readFileSync(skillMd, "utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n"),
+        });
+    }
+    return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
 export const RFC2119_LEGEND = "!=MUST, ~=SHOULD";
 export const PLATFORM_DETECTION_HEADING = "## Platform Detection";
 export const USER_MD_GATE_HEADING = "## USER.md Gate";

package/dist/content-contracts/skills/skill-external-fetch-gate.d.ts

@@ -0,0 +1,18 @@
+/** Skill-validation gate: external fetch must not pair with execute/install without mitigation (#1532 / #1936). */
+export type ExternalFetchViolation = {
+    skillPath: string;
+    detail: string;
+};
+/** Strip YAML frontmatter and HTML comment banners before scanning skill prose. */
+export declare function skillProse(raw: string): string;
+export declare function hasExternalFetchSignal(prose: string): boolean;
+export declare function hasRiskyExternalFetchPattern(prose: string): boolean;
+export declare function hasExecuteFromExternalSignal(prose: string): boolean;
+export declare function hasUntrustedFetchMitigation(prose: string): boolean;
+export declare function analyzeSkillExternalFetch(skillPath: string, rawText: string): ExternalFetchViolation | null;
+/** Collect violations across skill entries (used by verify-source gate + tests). */
+export declare function collectExternalFetchViolations(entries: ReadonlyArray<{
+    path: string;
+    text: string;
+}>): ExternalFetchViolation[];
+//# sourceMappingURL=skill-external-fetch-gate.d.ts.map

package/dist/content-contracts/skills/skill-external-fetch-gate.js

@@ -0,0 +1,81 @@
+/** Skill-validation gate: external fetch must not pair with execute/install without mitigation (#1532 / #1936). */
+const EXTERNAL_FETCH_RE = /\b(fetch(?:ing)?(?:\s+\w+){0,6}\s+(?:the\s+)?(?:url|content|article|related\s+urls?|http|https|web\s+page)|fetch\s+and\s+read|webfetch|mcp.*fetch)/i;
+const EXECUTE_FROM_EXTERNAL_RE = /\b(download|install|run|execute)\b.{0,40}\b(?:found|inside|within|in)\b.{0,40}\b(?:fetched|external|url|content|page|article)\b|\bfollow\b.{0,40}\b(?:instructions?|commands?)\b.{0,40}\b(?:download|install|run|execute)\b|\bexecute\b.{0,40}\b(?:commands?|scripts?|instructions?)\b.{0,40}\b(?:found|inside|within)\b/i;
+const FETCH_THEN_EXECUTE_RE = /\bfetch\b.{0,120}\b(?:then|and)\b.{0,60}\b(?:run|execute|install|download)\b/i;
+const RUN_FETCHED_ARTIFACT_RE = /\b(?:run|execute|install)\b.{0,40}\b(?:downloaded|fetched)\b/i;
+const FETCHED_ARTIFACT_RE = /\b(?:downloaded|fetched)\b.{0,40}\b(?:script|binary|executable|tool|installer|package|file)\b/i;
+const FOLLOW_RELATED_URLS_RE = /\bfetch(?:ing)?\s+related\s+urls?\b/i;
+const SECURITY_CONTEXT_HEADING = /## Security context/i;
+const UNTRUSTED_DOCTRINE_RE = /untrusted\s+(?:external\s+)?(?:content|data)/i;
+const FORBID_EXTERNAL_EXECUTE_RE = /⊗[\s\S]{0,200}\b(?:download|install|execute|run)\b[\s\S]{0,200}\b(?:external|fetched|externally|found inside)\b/i;
+/** Strip HTML comment blocks; repeat until stable for CodeQL multi-char sanitization. */
+function stripHtmlComments(text) {
+    let body = text;
+    let prev = "";
+    while (prev !== body) {
+        prev = body;
+        body = body.replace(/<!--[\s\S]*?-->/g, "");
+    }
+    return body;
+}
+/** Strip YAML frontmatter and HTML comment banners before scanning skill prose. */
+export function skillProse(raw) {
+    let body = raw.replace(/\r\n/g, "\n");
+    if (body.startsWith("---")) {
+        const end = body.indexOf("\n---", 3);
+        if (end !== -1) {
+            body = body.slice(end + 4);
+        }
+    }
+    return stripHtmlComments(body);
+}
+export function hasExternalFetchSignal(prose) {
+    return EXTERNAL_FETCH_RE.test(prose);
+}
+export function hasRiskyExternalFetchPattern(prose) {
+    if (!hasExternalFetchSignal(prose)) {
+        return false;
+    }
+    return (hasExecuteFromExternalSignal(prose) ||
+        FOLLOW_RELATED_URLS_RE.test(prose) ||
+        /\bfetch\b.{0,40}\bfollow\b/i.test(prose));
+}
+export function hasExecuteFromExternalSignal(prose) {
+    return (EXECUTE_FROM_EXTERNAL_RE.test(prose) ||
+        FETCH_THEN_EXECUTE_RE.test(prose) ||
+        RUN_FETCHED_ARTIFACT_RE.test(prose) ||
+        FETCHED_ARTIFACT_RE.test(prose));
+}
+export function hasUntrustedFetchMitigation(prose) {
+    return (SECURITY_CONTEXT_HEADING.test(prose) &&
+        UNTRUSTED_DOCTRINE_RE.test(prose) &&
+        FORBID_EXTERNAL_EXECUTE_RE.test(prose));
+}
+export function analyzeSkillExternalFetch(skillPath, rawText) {
+    const prose = skillProse(rawText);
+    if (!hasExternalFetchSignal(prose)) {
+        return null;
+    }
+    if (!hasRiskyExternalFetchPattern(prose)) {
+        return null;
+    }
+    if (hasUntrustedFetchMitigation(prose)) {
+        return null;
+    }
+    return {
+        skillPath,
+        detail: "external fetch or follow-through language without Security context untrusted-data / forbid-execute mitigation (#1936)",
+    };
+}
+/** Collect violations across skill entries (used by verify-source gate + tests). */
+export function collectExternalFetchViolations(entries) {
+    const violations = [];
+    for (const { path, text } of entries) {
+        const finding = analyzeSkillExternalFetch(path, text);
+        if (finding !== null) {
+            violations.push(finding);
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=skill-external-fetch-gate.js.map

package/dist/eval/crud-telemetry.d.ts

@@ -54,6 +54,8 @@ export declare class InstrumentedVbriefCrud {
     update(path: string, content: string, options?: {
         trustedWrite?: boolean;
     }): CrudResult;
+    /** Record update metrics without persisting (caller owns validated atomic write). */
+    recordTrustedUpdate(path: string, content: string): void;
     delete(path: string): CrudResult;
     private recordMetric;
 }

package/dist/eval/crud-telemetry.js

@@ -248,6 +248,36 @@ export class InstrumentedVbriefCrud {
         writeFileSync(path, content, "utf8");
         return { ok: true };
     }
+    /** Record update metrics without persisting (caller owns validated atomic write). */
+    recordTrustedUpdate(path, content) {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const message = sanitizeInlineMessage(err instanceof Error ? err.message : String(err));
+            this.recordMetric({
+                operation: "update",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: invalid JSON -- ${message}`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return;
+        }
+        const assessment = assessDocument(path, parsed);
+        this.recordMetric({
+            operation: "update",
+            path,
+            schemaValid: assessment.schemaValid,
+            schemaErrors: assessment.schemaErrors,
+            inventedKeys: assessment.inventedKeys,
+            byteDiffMinimality: null,
+            byteDiffChangedRatio: null,
+        });
+    }
     delete(path) {
         if (!existsSync(path)) {
             this.recordMetric({

package/dist/intake/github-body-cli.js

@@ -17,6 +17,8 @@ function parseArgs(argv) {
             out.pr = Number.parseInt(argv[++i], 10);
         else if (arg === "--body-file")
             out.bodyFile = argv[++i];
+        else if (arg === "--out-file")
+            out.outFile = argv[++i];
     }
     return out;
 }

package/dist/intake/github-body.d.ts

@@ -9,6 +9,8 @@ export type RunGhApiFn = (args: readonly string[], options?: {
 /** Resolve the live GitHub CLI used for writes and mutation read-back. */
 export declare function resolveLiveGh(): string;
 export declare function readBody(bodyFile: string, stdinText?: string | null): string;
+/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607). */
+export declare function verifyBodyPostcondition(intended: string, live: string): void;
 export declare function createIssue(repo: string, options: {
     title: string;
     body: string;
@@ -35,6 +37,14 @@ export declare function editPrBody(repo: string, pr: number, options: {
     binary?: string | null;
     runFn?: RunGhApiFn;
 }): Record<string, unknown>;
+export declare function fetchIssueBody(repo: string, issue: number, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): string;
+export declare function writeIssueBodyToFile(repo: string, issue: number, outFile: string, options?: {
+    binary?: string | null;
+    runFn?: RunGhApiFn;
+}): string;
 export interface GitHubBodyCliArgs {
     command: string;
     repo?: string;
@@ -43,6 +53,7 @@ export interface GitHubBodyCliArgs {
     comment?: number;
     pr?: number;
     bodyFile?: string;
+    outFile?: string;
 }
 export declare function githubBodyMain(args: GitHubBodyCliArgs): number;
 //# sourceMappingURL=github-body.d.ts.map

package/dist/intake/github-body.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { defaultWhich } from "../scm/binary.js";
 import { call } from "../scm/call.js";
 export const DEFAULT_TIMEOUT_SECONDS = 60;
@@ -73,14 +73,62 @@ function requireIntField(obj, field) {
     }
     return value;
 }
+function requireStringField(obj, field) {
+    const value = obj[field];
+    if (typeof value !== "string") {
+        throw new GitHubBodyError(`response did not include string field ${JSON.stringify(field)}`);
+    }
+    return value;
+}
+function countNewlines(text) {
+    let count = 0;
+    for (const ch of text) {
+        if (ch === "\n")
+            count += 1;
+    }
+    return count;
+}
+function normalizeNewlines(text) {
+    return text.replace(/\r\n/g, "\n");
+}
+/** Fail closed when live read-back body is flattened or mojibaked vs intended payload (#2607). */
+export function verifyBodyPostcondition(intended, live) {
+    if (intended === live) {
+        return;
+    }
+    if (normalizeNewlines(intended) === normalizeNewlines(live)) {
+        return;
+    }
+    const diagnoses = [];
+    if (live.includes("\uFFFD") && !intended.includes("\uFFFD")) {
+        diagnoses.push("live body contains U+FFFD replacement character not present in intended payload");
+    }
+    const intendedNl = countNewlines(intended);
+    const liveNl = countNewlines(live);
+    if (intendedNl > 0 && liveNl < intendedNl) {
+        diagnoses.push(`newline count mismatch (intended ${intendedNl}, live ${liveNl})`);
+    }
+    if (intended.includes("\n") && intended.replace(/\n/g, " ") === live) {
+        diagnoses.push("live body looks like intended newlines were collapsed to spaces (PowerShell string[] join)");
+    }
+    if (diagnoses.length > 0) {
+        throw new GitHubBodyError(`body postcondition failed: ${diagnoses.join("; ")}`);
+    }
+    throw new GitHubBodyError(`body postcondition failed: re-fetched body does not match intended payload (length intended=${intended.length}, live=${live.length})`);
+}
 function mutateWithReadback(mutationEndpoint, method, payload, readbackEndpoint, options = {}) {
+    const intendedBody = typeof payload.body === "string" ? payload.body : undefined;
     const mutation = runGhApiJson([mutationEndpoint, "--method", method, "--input", "-"], {
         inputText: jsonInput(payload),
         binary: options.binary,
         runFn: options.runFn,
     });
     const endpoint = typeof readbackEndpoint === "function" ? readbackEndpoint(mutation) : readbackEndpoint;
-    return runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
+    const readback = runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
+    if (intendedBody !== undefined) {
+        verifyBodyPostcondition(intendedBody, requireStringField(readback, "body"));
+    }
+    return readback;
 }
 export function createIssue(repo, options) {
     const [owner, name] = splitRepo(repo);
@@ -116,32 +164,55 @@ export function editPrBody(repo, pr, options) {
         runFn: options.runFn,
     });
 }
+export function fetchIssueBody(repo, issue, options = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/issues/${issue}`;
+    const response = runGhApiJson([endpoint], { binary: options.binary, runFn: options.runFn });
+    return requireStringField(response, "body");
+}
+export function writeIssueBodyToFile(repo, issue, outFile, options = {}) {
+    const body = fetchIssueBody(repo, issue, options);
+    writeFileSync(outFile, body, { encoding: "utf8" });
+    return body;
+}
 export function githubBodyMain(args) {
     try {
-        const body = readBody(args.bodyFile ?? "-");
-        let result;
         switch (args.command) {
-            case "issue-create":
-                result = createIssue(args.repo, { title: args.title, body });
-                break;
-            case "issue-edit":
-                result = editIssueBody(args.repo, args.issue, { body });
-                break;
-            case "comment-create":
-                result = createIssueComment(args.repo, args.issue, { body });
-                break;
-            case "comment-edit":
-                result = editIssueCommentBody(args.repo, args.comment, { body });
-                break;
-            case "pr-edit":
-                result = editPrBody(args.repo, args.pr, { body });
-                break;
-            default:
-                process.stderr.write(`error: unknown command ${JSON.stringify(args.command)}\n`);
-                return 1;
+            case "issue-fetch": {
+                if (args.repo === undefined || args.issue === undefined || args.outFile === undefined) {
+                    process.stderr.write("error: issue-fetch requires --repo, --issue, and --out-file\n");
+                    return 1;
+                }
+                writeIssueBodyToFile(args.repo, args.issue, args.outFile);
+                return 0;
+            }
+            default: {
+                const body = readBody(args.bodyFile ?? "-");
+                let result;
+                switch (args.command) {
+                    case "issue-create":
+                        result = createIssue(args.repo, { title: args.title, body });
+                        break;
+                    case "issue-edit":
+                        result = editIssueBody(args.repo, args.issue, { body });
+                        break;
+                    case "comment-create":
+                        result = createIssueComment(args.repo, args.issue, { body });
+                        break;
+                    case "comment-edit":
+                        result = editIssueCommentBody(args.repo, args.comment, { body });
+                        break;
+                    case "pr-edit":
+                        result = editPrBody(args.repo, args.pr, { body });
+                        break;
+                    default:
+                        process.stderr.write(`error: unknown command ${JSON.stringify(args.command)}\n`);
+                        return 1;
+                }
+                process.stdout.write(`${JSON.stringify(result)}\n`);
+                return 0;
+            }
         }
-        process.stdout.write(`${JSON.stringify(result)}\n`);
-        return 0;
     }
     catch (exc) {
         process.stderr.write(`error: ${String(exc)}\n`);

package/dist/integration-e2e/helpers.js

@@ -98,7 +98,7 @@ export function createConsumerProject(parent) {
 export function writeScopeVbrief(projectRoot, folder, filename, status = "proposed") {
     const target = join(projectRoot, "xbrief", folder, filename);
     writeFileSync(target, `${JSON.stringify({
-        vBRIEFInfo: { version: "0.5" },
+        xBRIEFInfo: { version: "0.8" },
         plan: {
             title: "Consumer fixture scope",
             status,

package/dist/issue-sync/sync-from-xbrief.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { createIssueComment } from "../intake/github-body.js";
 import { provenanceIssueNumber, repoSlugFromUrl } from "../intake/issue-ingest.js";
 import { extractReferencesFromVbrief, GITHUB_ISSUE_REF_TYPES, parseIssueNumber, } from "../intake/reconcile-issues.js";
@@ -192,9 +193,11 @@ export function syncFromXbrief(options) {
     writeOut(`issue:sync-from-xbrief: posted comment to ${origin.repo}#${origin.number} (id: ${commentResult.id}).`);
     const writeFingerprint = options.writeFingerprint ??
         ((targetPath, stamped) => {
+            assertWriteTargetSafe(projectRoot, targetPath);
             writeFileSync(targetPath, `${JSON.stringify(stamped, null, 2)}\n`, "utf8");
         });
     try {
+        assertWriteTargetSafe(projectRoot, absPath);
         writeFingerprint(absPath, stampIssueSyncFingerprint(data, origin));
     }
     catch (exc) {

package/dist/orphan-active/evaluate.d.ts

@@ -0,0 +1,25 @@
+import type { RunGhFn } from "../pr-protected-issues/types.js";
+export type OutputStream = "stdout" | "stderr" | "none";
+export interface OrphanActiveBrief {
+    readonly path: string;
+    readonly reason: string;
+}
+export interface EvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+    readonly orphans: readonly OrphanActiveBrief[];
+}
+export interface EvaluateOptions {
+    readonly quiet?: boolean;
+    readonly repo?: string | null;
+    readonly runGh?: RunGhFn;
+    readonly skipGh?: boolean;
+}
+/**
+ * Pure evaluator for orphaned active/running xBRIEF detection (#2321).
+ * Fails when active/ briefs with plan.status==running reference only closed
+ * issues and/or a merged PR — the stop-at:pr-open orphan signature.
+ */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
+//# sourceMappingURL=evaluate.d.ts.map