@deftai/directive 0.58.0 → 0.60.0

package/dist/dispatch.js

@@ -2,9 +2,15 @@
  * Unified `directive <verb> [args]` dispatcher (#1828 s0).
  * Routes to ported command modules in packages/cli and packages/core.
  */
-import { execFileSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, readSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { engineInfo } from "@deftai/directive-core";
+import { parseInitArgv, runInitDepositCli, userConfigDir, } from "@deftai/directive-core/init-deposit";
+import { appendAuditLog, disclosureLine, projectDefinitionPath, resolvePolicy, resolveWipCap, setPolicy, } from "@deftai/directive-core/policy";
+import { defaultWhich } from "@deftai/directive-core/scm";
+import { KNOWN_SUBAGENT_BACKEND_IDS, probeSubagentBackends, resolveSwarmSubagentBackend, } from "@deftai/directive-core/swarm";
 const HANDLER_KEYS = [
     "run",
     "main",
@@ -28,6 +34,12 @@ export const CLI_MODULE_VERBS = [
     "codebase-projection-registry",
     "codebase-provider",
     "doctor",
+    "install-upgrade",
+    "install-uninstall",
+    "migrate-preflight",
+    "changelog-check",
+    "change-init",
+    "commit-lint",
     "parity",
     "policy",
     "pr-closing-keywords",
@@ -43,6 +55,7 @@ export const CLI_MODULE_VERBS = [
     "release-publish",
     "release-rollback",
     "scope-lifecycle",
+    "session-start",
     "slice",
     "subagent-monitor",
     "toolchain-check",
@@ -117,6 +130,7 @@ export const CORE_MODULE_VERBS = [
     "pack-migrate-patterns",
     "pack-migrate-swarm-spec",
     "policy-set",
+    "setup-ghx",
     "scope-undo",
     "scope-demote",
     "scope-decompose",
@@ -160,7 +174,9 @@ export const VERB_ALIASES = {
     "triage:accept": "triage-actions",
     "triage:status": "triage-actions",
     "agents:refresh": "agents-refresh",
-    "session:start": "framework-commands",
+    "migrate:preflight": "migrate-preflight",
+    upgrade: "install-upgrade",
+    "session:start": "session-start",
     "toolchain:check": "toolchain-check",
     "ts:check-lane": "ts-check-lane",
     "spec:validate": "spec-validate",
@@ -169,6 +185,7 @@ export const VERB_ALIASES = {
     "project:render": "project-render",
     doctor: "doctor",
     build: "framework-commands",
+    "setup:ghx": "setup-ghx",
 };
 /** CLI modules living under verify-source-cli/ or content-validate-cli/ subdirs. */
 const SUBDIR_CLI_STEMS = {
@@ -324,23 +341,1542 @@ function parseCodeStructureArgs(argv) {
     }
     return { projectRoot, paths, json, strict };
 }
-function loadPythonScriptHandler(scriptName) {
-    return (argv) => {
-        const deftRoot = resolveDeftRoot();
-        try {
-            execFileSync("uv", ["--project", deftRoot, "run", "python", join(deftRoot, "scripts", scriptName), ...argv], {
-                cwd: deftRoot,
-                encoding: "utf8",
-                env: { ...process.env, PYTHONUTF8: "1", DEFT_CACHE_DISABLE: "1" },
-                stdio: "inherit",
-            });
+// ===========================================================================
+// Native pack-migrate handlers (#2022 Phase 1).
+//
+// Port of scripts/pack_migrate_{skills,rules,strategies,patterns,swarm_spec}.py
+// to native TypeScript so the pack-render surface no longer shells into bundled
+// Python. Output parity with the Python scripts is exact, including the
+// json.dumps(..., indent=2, ensure_ascii=True) + "\n" serialization, document
+// scanning order, and per-entry field ordering.
+// ===========================================================================
+const PACK_VERSION = "0.1";
+const DEFAULT_SKILL_VERSION = "0.1";
+const SHOULD_NOT_GLYPH = "\u2249";
+const MUST_NOT_GLYPH = "\u2297";
+/** Serialize like Python json.dumps(value, indent=2, ensure_ascii=True) + "\n". */
+function dumpsAsciiJson(value) {
+    const base = JSON.stringify(value, null, 2);
+    let out = "";
+    for (let i = 0; i < base.length; i += 1) {
+        const code = base.charCodeAt(i);
+        // ensure_ascii escapes every code unit outside the printable ASCII range
+        // (0x20-0x7e). JSON.stringify has already escaped control chars (< 0x20)
+        // and the structural quote/backslash, so only chars > 0x7e remain literal.
+        if (code > 0x7e) {
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            out += base.charAt(i);
+        }
+    }
+    return `${out}\n`;
+}
+/** Strip leading/trailing chars in `chars` (Python str.strip(chars)); whitespace when omitted. */
+function pyStrip(value, chars) {
+    if (chars === undefined) {
+        return value.replace(/^\s+/, "").replace(/\s+$/, "");
+    }
+    let start = 0;
+    let end = value.length;
+    while (start < end && chars.includes(value.charAt(start)))
+        start += 1;
+    while (end > start && chars.includes(value.charAt(end - 1)))
+        end -= 1;
+    return value.slice(start, end);
+}
+// Python str.splitlines() universal newlines: \n \r \r\n \v \f \x1c \x1d \x1e \x85 \u2028 \u2029.
+// Built from code points (as \uXXXX escape text) so no literal control characters land in the source.
+const LINE_BOUNDARY_CLASS = [0x0a, 0x0d, 0x0b, 0x0c, 0x1c, 0x1d, 0x1e, 0x85, 0x2028, 0x2029]
+    .map((code) => `\\u${code.toString(16).padStart(4, "0")}`)
+    .join("");
+const LINE_BOUNDARY_RE = new RegExp(`\\r\\n|[${LINE_BOUNDARY_CLASS}]`);
+/** Mirror Python str.splitlines(): split on universal line boundaries, dropping one terminal break. */
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const parts = text.split(LINE_BOUNDARY_RE);
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+/** Repo-relative POSIX path of `to` measured from `from`. */
+function relPosix(from, to) {
+    return relative(from, to).split(/[\\/]/).join("/");
+}
+/** Python Path.stem -- filename minus its final suffix. */
+function stemOf(filePath) {
+    const base = basename(filePath);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+/** Slugify a doc stem: lowercase, runs of non-alnum -> '-', trimmed of '-'. */
+function slugify(stem) {
+    return pyStrip(stem.toLowerCase().replace(/[^a-z0-9]+/g, "-"), "-");
+}
+function isFileSafe(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirSafe(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Sorted SKILL.md paths one directory below skillsDir (Python skills_dir glob of the SKILL.md docs). */
+function globSkillMd(skillsDir) {
+    const out = [];
+    let names;
+    try {
+        names = readdirSync(skillsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of names) {
+        const dir = join(skillsDir, name);
+        if (!isDirSafe(dir))
+            continue;
+        const candidate = join(dir, "SKILL.md");
+        if (isFileSafe(candidate))
+            out.push(candidate);
+    }
+    out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return out;
+}
+/** Sorted full paths of `<dir>/*.md` (Python dir.glob("*.md")). */
+function globMd(dir) {
+    const out = [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of names) {
+        if (!name.endsWith(".md"))
+            continue;
+        const candidate = join(dir, name);
+        if (isFileSafe(candidate))
+            out.push(candidate);
+    }
+    out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return out;
+}
+const H1_RE = /^#\s+(.+?)\s*$/;
+const CHROME_PREFIXES = [
+    "legend ",
+    "legend(",
+    "**legend",
+    `**${"\u26a0\ufe0f"}`,
+    "**see also",
+    "<!--",
+];
+function isChrome(line) {
+    const low = line.replace(/^\s+/, "").toLowerCase();
+    if (CHROME_PREFIXES.some((prefix) => low.startsWith(prefix)))
+        return true;
+    const stripped = line.trim();
+    return stripped.length > 0 && [...stripped].every((ch) => ch === "-" || ch === "=");
+}
+/** Index a line array with a defined fallback (`i` is always in range at call sites). */
+function lineAt(lines, i) {
+    return lines[i] ?? "";
+}
+function extractTitle(md) {
+    for (const line of splitLines(md)) {
+        const match = H1_RE.exec(line);
+        if (match)
+            return (match[1] ?? "").trim();
+    }
+    return "";
+}
+function extractDescription(md) {
+    const lines = splitLines(md);
+    const n = lines.length;
+    let i = 0;
+    while (i < n && !H1_RE.test(lineAt(lines, i)))
+        i += 1;
+    if (i < n)
+        i += 1;
+    while (i < n && (lineAt(lines, i).trim() === "" || isChrome(lineAt(lines, i))))
+        i += 1;
+    const block = [];
+    while (i < n &&
+        lineAt(lines, i).trim() !== "" &&
+        !lineAt(lines, i).replace(/^\s+/, "").startsWith("#")) {
+        let stripped = lineAt(lines, i).trim();
+        if (stripped.startsWith(">"))
+            stripped = stripped.replace(/^>+/, "").trim();
+        if (stripped)
+            block.push(stripped);
+        i += 1;
+    }
+    return block.join(" ");
+}
+const REDIRECT_MARKERS = [
+    "legacy alias",
+    "superseded",
+    "has been renamed",
+    "has moved",
+    "deprecated",
+];
+function isRedirectStub(md) {
+    const lines = splitLines(md);
+    const n = lines.length;
+    let i = 0;
+    while (i < n && !H1_RE.test(lineAt(lines, i)))
+        i += 1;
+    if (i < n)
+        i += 1;
+    while (i < n && (lineAt(lines, i).trim() === "" || isChrome(lineAt(lines, i))))
+        i += 1;
+    if (i >= n || !lineAt(lines, i).replace(/^\s+/, "").startsWith(">"))
+        return false;
+    const block = [];
+    while (i < n && lineAt(lines, i).replace(/^\s+/, "").startsWith(">")) {
+        block.push(lineAt(lines, i).replace(/^\s+/, "").replace(/^>+/, "").trim());
+        i += 1;
+    }
+    const quote = block.join(" ").toLowerCase();
+    return REDIRECT_MARKERS.some((marker) => quote.includes(marker));
+}
+const BANNER_OPEN = "<!-- AUTO-GENERATED by task packs:render";
+function stripLeadingBanner(body) {
+    const lines = body.split("\n");
+    const n = lines.length;
+    let i = 0;
+    while (i < n && lineAt(lines, i).trim() === "")
+        i += 1;
+    if (i < n && lineAt(lines, i).startsWith(BANNER_OPEN)) {
+        while (i < n && lineAt(lines, i).replace(/^\s+/, "").startsWith("<!--"))
+            i += 1;
+        while (i < n && lineAt(lines, i).trim() === "")
+            i += 1;
+    }
+    return lines.slice(i).join("\n");
+}
+const FRONTMATTER_RE = /^---\n([\s\S]*?\n)---\n?([\s\S]*)$/;
+function splitFrontmatter(text) {
+    if (!text.startsWith("---\n"))
+        return [null, text];
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match)
+        return [null, text];
+    return [match[1] ?? "", match[2] ?? ""];
+}
+function foldBlock(blockLines) {
+    const paragraphs = [];
+    let current = [];
+    for (const line of blockLines) {
+        if (line.trim() === "") {
+            if (current.length) {
+                paragraphs.push(current.join(" "));
+                current = [];
+            }
+        }
+        else {
+            current.push(line.trim());
+        }
+    }
+    if (current.length)
+        paragraphs.push(current.join(" "));
+    return paragraphs.join("\n");
+}
+const KEY_RE = /^([A-Za-z_][\w-]*):(.*)$/;
+const BLOCK_INDICATORS = new Set([">", ">-", ">+", "|", "|-", "|+"]);
+function isIndented(line) {
+    return line.startsWith(" ") || line.startsWith("\t");
+}
+function parseFrontmatterFields(frontmatter) {
+    const lines = frontmatter.split("\n");
+    const fields = {};
+    const n = lines.length;
+    let i = 0;
+    while (i < n) {
+        const line = lineAt(lines, i);
+        const match = KEY_RE.exec(line);
+        if (!match || isIndented(line)) {
+            i += 1;
+            continue;
+        }
+        const key = match[1] ?? "";
+        const value = (match[2] ?? "").trim();
+        if (BLOCK_INDICATORS.has(value)) {
+            const block = [];
+            i += 1;
+            while (i < n) {
+                const nxt = lineAt(lines, i);
+                if (nxt.trim() === "") {
+                    block.push("");
+                    i += 1;
+                    continue;
+                }
+                if (isIndented(nxt)) {
+                    block.push(nxt);
+                    i += 1;
+                    continue;
+                }
+                break;
+            }
+            fields[key] = foldBlock(block);
+            continue;
+        }
+        if (value === "" || value.startsWith("- ")) {
+            i += 1;
+            while (i < n &&
+                (lineAt(lines, i).replace(/^\s+/, "").startsWith("- ") || isIndented(lineAt(lines, i)))) {
+                i += 1;
+            }
+            if (!(key in fields))
+                fields[key] = "";
+            continue;
+        }
+        fields[key] = pyStrip(pyStrip(value, '"'), "'");
+        i += 1;
+    }
+    return fields;
+}
+function extractExtraFrontmatter(frontmatter) {
+    const lines = frontmatter.split("\n");
+    const extra = [];
+    const n = lines.length;
+    let i = 0;
+    while (i < n) {
+        const line = lineAt(lines, i);
+        const match = KEY_RE.exec(line);
+        if (!match || isIndented(line)) {
+            i += 1;
+            continue;
+        }
+        const key = match[1] ?? "";
+        const value = (match[2] ?? "").trim();
+        const block = [line];
+        i += 1;
+        if (BLOCK_INDICATORS.has(value)) {
+            while (i < n && (lineAt(lines, i).trim() === "" || isIndented(lineAt(lines, i)))) {
+                block.push(lineAt(lines, i));
+                i += 1;
+            }
+        }
+        else if (value === "" || value.startsWith("- ")) {
+            while (i < n &&
+                (lineAt(lines, i).replace(/^\s+/, "").startsWith("- ") || isIndented(lineAt(lines, i)))) {
+                block.push(lineAt(lines, i));
+                i += 1;
+            }
+        }
+        if (key !== "name" && key !== "description")
+            extra.push(...block);
+    }
+    while (extra.length && (extra[extra.length - 1] ?? "").trim() === "")
+        extra.pop();
+    return extra.length ? extra.join("\n") : null;
+}
+const ROUTING_HEADING = "## Skill Routing";
+const ROUTING_PATH_RE = /`(?:content\/)?(skills\/[^`]+\/SKILL\.md)`/;
+const ARROW_SPLIT_RE = /\u2192|->/;
+function parseRouting(agentsMd) {
+    const mapping = new Map();
+    const start = agentsMd.indexOf(ROUTING_HEADING);
+    if (start === -1)
+        return mapping;
+    const rest = agentsMd.slice(start + ROUTING_HEADING.length);
+    const end = rest.indexOf("\n## ");
+    const section = end !== -1 ? rest.slice(0, end) : rest;
+    for (const raw of splitLines(section)) {
+        const line = raw.trim();
+        if (!line.startsWith("- "))
+            continue;
+        const pathMatch = ROUTING_PATH_RE.exec(line);
+        if (!pathMatch)
+            continue;
+        const path = pathMatch[1] ?? "";
+        const head = line.split(ARROW_SPLIT_RE)[0] ?? "";
+        const keywords = (head.match(/"[^"]+"/g) ?? []).map((quoted) => quoted.slice(1, -1));
+        let bucket = mapping.get(path);
+        if (!bucket) {
+            bucket = [];
+            mapping.set(path, bucket);
+        }
+        for (const keyword of keywords) {
+            if (!bucket.includes(keyword))
+                bucket.push(keyword);
+        }
+    }
+    return mapping;
+}
+function buildSkillEntry(skillMd, skillsDir, routing, captureBody) {
+    const text = readFileSync(skillMd, "utf8");
+    const [frontmatter, body] = splitFrontmatter(text);
+    if (frontmatter === null)
+        return null;
+    const fields = parseFrontmatterFields(frontmatter);
+    const name = (fields.name ?? "").trim();
+    if (!name)
+        return null;
+    const relPath = relPosix(dirname(resolve(skillsDir)), resolve(skillMd));
+    const triggers = routing.get(relPath) ?? [];
+    const version = (fields.version ?? "").trim() || DEFAULT_SKILL_VERSION;
+    return {
+        id: name,
+        description: (fields.description ?? "").trim(),
+        triggers,
+        path: relPath,
+        version,
+        body: captureBody ? stripLeadingBanner(body) : null,
+        frontmatter_extra: extractExtraFrontmatter(frontmatter),
+    };
+}
+function buildSkillsPack(skillsDir, agentsMd, proofSkill) {
+    const routing = parseRouting(readFileSync(agentsMd, "utf8"));
+    const captureAll = proofSkill === null;
+    const proofPath = proofSkill !== null ? `skills/${proofSkill}/SKILL.md` : null;
+    const base = dirname(resolve(skillsDir));
+    const skills = [];
+    for (const skillMd of globSkillMd(skillsDir)) {
+        const relPath = relPosix(base, resolve(skillMd));
+        const entry = buildSkillEntry(skillMd, skillsDir, routing, captureAll || relPath === proofPath);
+        if (entry !== null)
+            skills.push(entry);
+    }
+    return {
+        pack: "skills-pack-0.1",
+        version: PACK_VERSION,
+        generated_from: "skills/*/SKILL.md + AGENTS.md (Skill Routing)",
+        skills,
+    };
+}
+const GLYPH_TIER = {
+    "!": "MUST",
+    "~": "SHOULD",
+    [SHOULD_NOT_GLYPH]: "SHOULD_NOT",
+    [MUST_NOT_GLYPH]: "MUST_NOT",
+    "?": "MAY",
+};
+const MARKER_RE = new RegExp(`^\\s*(?:-\\s+)?([!~?${SHOULD_NOT_GLYPH}${MUST_NOT_GLYPH}])\\s+(\\S.*)$`);
+const PROSE_TIERS = [
+    ["MUST NOT", "MUST_NOT"],
+    ["SHOULD NOT", "SHOULD_NOT"],
+    ["MUST", "MUST"],
+    ["SHOULD", "SHOULD"],
+    ["MAY", "MAY"],
+];
+function proseTier(text) {
+    for (const [keyword, tier] of PROSE_TIERS) {
+        const pattern = new RegExp(`\\b${keyword.replace(/ /g, "[ ]")}\\b`);
+        if (pattern.test(text))
+            return tier;
+    }
+    return null;
+}
+function parseRules(md, domain) {
+    const rules = [];
+    let seq = 0;
+    for (const raw of splitLines(md)) {
+        const line = raw.replace(/\s+$/, "");
+        let tier = null;
+        let text = "";
+        const marker = MARKER_RE.exec(line);
+        if (marker) {
+            tier = GLYPH_TIER[marker[1] ?? ""] ?? null;
+            text = (marker[2] ?? "").trim();
+        }
+        else {
+            const stripped = line.trim();
+            if (!stripped.startsWith("- "))
+                continue;
+            text = stripped.slice(2).trim();
+            tier = text ? proseTier(text) : null;
+        }
+        if (tier === null || text === "")
+            continue;
+        seq += 1;
+        rules.push({ id: `${domain}-${String(seq).padStart(3, "0")}`, tier, domain, text });
+    }
+    return rules;
+}
+const MANAGED_SECTION_RE = /<!--\s*deft:managed-section[\s\S]*?<!--\s*\/deft:managed-section\s*-->/g;
+function stripManagedSection(md) {
+    return md.replace(MANAGED_SECTION_RE, "");
+}
+function buildRulesPack(codingDir, extraSources) {
+    const base = dirname(resolve(codingDir));
+    const rules = [];
+    for (const md of globMd(codingDir)) {
+        const relPath = relPosix(base, resolve(md));
+        const domain = slugify(stemOf(md));
+        const text = readFileSync(md, "utf8");
+        const docRules = parseRules(text, domain);
+        docRules.forEach((rule, idx) => {
+            rule.path = relPath;
+            rule.body = idx === 0 ? stripLeadingBanner(text) : null;
+            rules.push(rule);
+        });
+    }
+    for (const src of extraSources) {
+        if (!isFileSafe(src))
+            continue;
+        const candidate = relPosix(base, resolve(src));
+        const relPath = candidate.startsWith("..") || isAbsolute(candidate) ? basename(src) : candidate;
+        const domain = slugify(stemOf(src));
+        let text = readFileSync(src, "utf8");
+        if (basename(src) === "AGENTS.md")
+            text = stripManagedSection(text);
+        for (const rule of parseRules(text, domain)) {
+            rule.path = relPath;
+            rule.body = null;
+            rules.push(rule);
+        }
+    }
+    return {
+        pack: "rules-pack-0.1",
+        version: PACK_VERSION,
+        generated_from: "coding/*.md + AGENTS.md + main.md (marker-prefixed RFC2119 directives; " +
+            "AGENTS.md managed-section excluded; coding bodies rendered, " +
+            "AGENTS.md/main.md metadata-only)",
+        rules,
+    };
+}
+function buildMdEntry(md, dir, captureBody) {
+    const relPath = relPosix(dirname(resolve(dir)), resolve(md));
+    const stemSlug = slugify(stemOf(md));
+    const text = readFileSync(md, "utf8");
+    return {
+        id: stemSlug,
+        title: extractTitle(text),
+        description: extractDescription(text),
+        triggers: stemSlug ? [stemSlug] : [],
+        path: relPath,
+        body: captureBody ? stripLeadingBanner(text) : null,
+    };
+}
+function buildStrategiesPack(strategiesDir, proofStrategy) {
+    const base = dirname(resolve(strategiesDir));
+    const captureAll = proofStrategy === null;
+    const strategies = [];
+    for (const md of globMd(strategiesDir)) {
+        const relPath = relPosix(base, resolve(md));
+        const captureBody = captureAll
+            ? !isRedirectStub(readFileSync(md, "utf8"))
+            : relPath === proofStrategy;
+        strategies.push(buildMdEntry(md, strategiesDir, captureBody));
+    }
+    return {
+        pack: "strategies-pack-0.1",
+        version: PACK_VERSION,
+        generated_from: "strategies/*.md",
+        strategies,
+    };
+}
+function buildPatternsPack(patternsDir, proofPattern) {
+    const base = dirname(resolve(patternsDir));
+    const patterns = [];
+    for (const md of globMd(patternsDir)) {
+        const relPath = relPosix(base, resolve(md));
+        patterns.push(buildMdEntry(md, patternsDir, relPath === proofPattern));
+    }
+    return {
+        pack: "patterns-pack-0.1",
+        version: PACK_VERSION,
+        generated_from: "patterns/*.md",
+        patterns,
+    };
+}
+function buildSwarmSpecPack(swarmDir, proofEntry) {
+    const base = dirname(resolve(swarmDir));
+    const entries = [];
+    for (const md of globMd(swarmDir)) {
+        const relPath = relPosix(base, resolve(md));
+        entries.push(buildMdEntry(md, swarmDir, relPath === proofEntry));
+    }
+    return {
+        pack: "swarm-spec-pack-0.1",
+        version: PACK_VERSION,
+        generated_from: "swarm/*.md",
+        entries,
+    };
+}
+function writePack(out, pack) {
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, dumpsAsciiJson(pack), "utf8");
+}
+/** Resolve the shippable content root: <root>/content when present, else <root> (#1875). */
+function resolveContentRoot() {
+    const root = resolveDeftRoot();
+    const candidate = join(root, "content");
+    return isDirSafe(candidate) ? candidate : root;
+}
+/**
+ * Minimal argparse-compatible option reader supporting `--flag value` and
+ * `--flag=value`. `listFlags` accumulate repeats; all flags take a value.
+ */
+function parsePackArgs(argv, valueFlags, listFlags = []) {
+    const values = {};
+    const lists = {};
+    const known = new Set([...valueFlags, ...listFlags]);
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        let flag = arg;
+        let inlineValue;
+        if (arg.startsWith("--") && arg.includes("=")) {
+            const eq = arg.indexOf("=");
+            flag = arg.slice(0, eq);
+            inlineValue = arg.slice(eq + 1);
+        }
+        if (!known.has(flag)) {
+            return { values, lists, error: `unrecognized argument: ${arg}` };
+        }
+        let value = inlineValue;
+        if (value === undefined) {
+            i += 1;
+            value = argv[i];
+        }
+        if (value === undefined) {
+            return { values, lists, error: `argument ${flag}: expected one argument` };
+        }
+        if (listFlags.includes(flag)) {
+            const bucket = lists[flag] ?? [];
+            bucket.push(value);
+            lists[flag] = bucket;
+        }
+        else {
+            values[flag] = value;
+        }
+    }
+    return { values, lists };
+}
+function runPackMigrateSkills(argv, io) {
+    const contentRoot = resolveContentRoot();
+    const parsed = parsePackArgs(argv, ["--skills-dir", "--agents-md", "--proof-skill", "--out"]);
+    if (parsed.error !== undefined) {
+        io.writeErr(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const skillsDir = parsed.values["--skills-dir"] ?? join(contentRoot, "skills");
+    const agentsMd = parsed.values["--agents-md"] ?? join(resolveDeftRoot(), "AGENTS.md");
+    const proofSkill = parsed.values["--proof-skill"] ?? null;
+    const out = parsed.values["--out"] ?? join(contentRoot, "packs", "skills", "skills-pack-0.1.json");
+    if (!isDirSafe(skillsDir)) {
+        io.writeErr(`error: skills directory not found: ${skillsDir}\n`);
+        return 1;
+    }
+    if (!isFileSafe(agentsMd)) {
+        io.writeErr(`error: AGENTS.md not found: ${agentsMd}\n`);
+        return 1;
+    }
+    const pack = buildSkillsPack(skillsDir, agentsMd, proofSkill);
+    if (pack.skills.length === 0) {
+        io.writeErr(`error: no skills with frontmatter discovered under ${skillsDir}\n`);
+        return 1;
+    }
+    writePack(out, pack);
+    const bodied = pack.skills.filter((s) => s.body !== null).length;
+    io.writeOut(`Migrated ${pack.skills.length} skills (${bodied} with body) -> ${out}\n`);
+    return 0;
+}
+function runPackMigrateRules(argv, io) {
+    const contentRoot = resolveContentRoot();
+    const deftRoot = resolveDeftRoot();
+    const parsed = parsePackArgs(argv, ["--coding-dir", "--out"], ["--extra-source"]);
+    if (parsed.error !== undefined) {
+        io.writeErr(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const codingDir = parsed.values["--coding-dir"] ?? join(contentRoot, "coding");
+    const extraSources = parsed.lists["--extra-source"] ?? [
+        join(deftRoot, "AGENTS.md"),
+        join(deftRoot, "main.md"),
+    ];
+    const out = parsed.values["--out"] ?? join(contentRoot, "packs", "rules", "rules-pack-0.1.json");
+    if (!isDirSafe(codingDir)) {
+        io.writeErr(`error: coding directory not found: ${codingDir}\n`);
+        return 1;
+    }
+    const pack = buildRulesPack(codingDir, extraSources);
+    if (pack.rules.length === 0) {
+        io.writeErr(`error: no directives discovered under ${codingDir}\n`);
+        return 1;
+    }
+    writePack(out, pack);
+    const bodied = pack.rules.filter((r) => r.body != null).length;
+    io.writeOut(`Migrated ${pack.rules.length} rules (${bodied} with body) -> ${out}\n`);
+    return 0;
+}
+function runPackMigrateStrategies(argv, io) {
+    const contentRoot = resolveContentRoot();
+    const parsed = parsePackArgs(argv, ["--strategies-dir", "--proof-strategy", "--out"]);
+    if (parsed.error !== undefined) {
+        io.writeErr(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const strategiesDir = parsed.values["--strategies-dir"] ?? join(contentRoot, "strategies");
+    const proofStrategy = parsed.values["--proof-strategy"] ?? null;
+    const out = parsed.values["--out"] ?? join(contentRoot, "packs", "strategies", "strategies-pack-0.1.json");
+    if (!isDirSafe(strategiesDir)) {
+        io.writeErr(`error: strategies directory not found: ${strategiesDir}\n`);
+        return 1;
+    }
+    const pack = buildStrategiesPack(strategiesDir, proofStrategy);
+    if (pack.strategies.length === 0) {
+        io.writeErr(`error: no strategies discovered under ${strategiesDir}\n`);
+        return 1;
+    }
+    writePack(out, pack);
+    const bodied = pack.strategies.filter((s) => s.body !== null).length;
+    io.writeOut(`Migrated ${pack.strategies.length} strategies (${bodied} with body) -> ${out}\n`);
+    return 0;
+}
+function runPackMigratePatterns(argv, io) {
+    const contentRoot = resolveContentRoot();
+    const parsed = parsePackArgs(argv, ["--patterns-dir", "--proof-pattern", "--out"]);
+    if (parsed.error !== undefined) {
+        io.writeErr(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const patternsDir = parsed.values["--patterns-dir"] ?? join(contentRoot, "patterns");
+    const proofPattern = parsed.values["--proof-pattern"] ?? "patterns/multi-agent.md";
+    const out = parsed.values["--out"] ?? join(contentRoot, "packs", "patterns", "patterns-pack-0.1.json");
+    if (!isDirSafe(patternsDir)) {
+        io.writeErr(`error: patterns directory not found: ${patternsDir}\n`);
+        return 1;
+    }
+    const pack = buildPatternsPack(patternsDir, proofPattern);
+    if (pack.patterns.length === 0) {
+        io.writeErr(`error: no patterns discovered under ${patternsDir}\n`);
+        return 1;
+    }
+    writePack(out, pack);
+    const bodied = pack.patterns.filter((p) => p.body !== null).length;
+    io.writeOut(`Migrated ${pack.patterns.length} patterns (${bodied} with body) -> ${out}\n`);
+    return 0;
+}
+function runPackMigrateSwarmSpec(argv, io) {
+    const contentRoot = resolveContentRoot();
+    const parsed = parsePackArgs(argv, ["--swarm-dir", "--proof-entry", "--out"]);
+    if (parsed.error !== undefined) {
+        io.writeErr(`error: ${parsed.error}\n`);
+        return 2;
+    }
+    const swarmDir = parsed.values["--swarm-dir"] ?? join(contentRoot, "swarm");
+    const proofEntry = parsed.values["--proof-entry"] ?? "swarm/swarm.md";
+    const out = parsed.values["--out"] ?? join(contentRoot, "packs", "swarm-spec", "swarm-spec-pack-0.1.json");
+    if (!isDirSafe(swarmDir)) {
+        io.writeErr(`error: swarm directory not found: ${swarmDir}\n`);
+        return 1;
+    }
+    const pack = buildSwarmSpecPack(swarmDir, proofEntry);
+    if (pack.entries.length === 0) {
+        io.writeErr(`error: no swarm-spec docs discovered under ${swarmDir}\n`);
+        return 1;
+    }
+    writePack(out, pack);
+    const bodied = pack.entries.filter((e) => e.body !== null).length;
+    io.writeOut(`Migrated ${pack.entries.length} swarm-spec entries (${bodied} with body) -> ${out}\n`);
+    return 0;
+}
+// ===========================================================================
+// Native setup:ghx handler (#2022 Phase 1).
+//
+// Port of scripts/setup_ghx.py to native TypeScript: consent-gated ghx proxy
+// installer with three-state exit (0 ok / 1 install failure / 2 config error).
+// ===========================================================================
+/** Pinned ghx version — keep in lockstep with .github/workflows/ci.yml env.GHX_VERSION. */
+export const GHX_VERSION = "v1.5.1";
+export const INSTALL_PS1_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_VERSION}/install.ps1`;
+export const INSTALL_SH_URL = `https://raw.githubusercontent.com/brunoborges/ghx/${GHX_VERSION}/install.sh`;
+function parseSetupGhxArgs(argv) {
+    let yes = false;
+    let check = false;
+    for (const arg of argv) {
+        if (arg === "--yes") {
+            yes = true;
+        }
+        else if (arg === "--check") {
+            check = true;
+        }
+        else {
+            return { yes, check, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return { yes, check };
+}
+export function ghxPresent(whichFn = defaultWhich) {
+    return whichFn("ghx") !== null;
+}
+export function detectSetupGhxHost() {
+    if (process.platform === "win32")
+        return "windows";
+    if (process.platform === "darwin")
+        return "darwin";
+    if (process.platform === "linux")
+        return "linux";
+    return process.platform;
+}
+function readConsentLineFromStdin() {
+    const buf = Buffer.alloc(256);
+    try {
+        const n = readSync(0, buf, 0, 256, null);
+        if (n === null || n <= 0)
+            return "";
+        return buf.toString("utf8", 0, n);
+    }
+    catch {
+        return "";
+    }
+}
+export function promptSetupGhxConsent(io, readLine = readConsentLineFromStdin) {
+    io.writeOut("\n[setup_ghx] ghx is the recommended GitHub CLI cache proxy for deft " +
+        "maintainers (prevents rate-limiting in multi-agent swarms; speeds up " +
+        "scm:* calls). Consumer projects only require gh.\n");
+    io.writeOut(`[setup_ghx] Upstream: https://github.com/brunoborges/ghx (${GHX_VERSION})\n`);
+    io.writeOut("[setup_ghx] Install ghx via the upstream installer? [y/N]: ");
+    const answer = readLine().trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+}
+export function buildSetupGhxInstallCommand(host, whichFn = defaultWhich) {
+    if (host === "windows") {
+        const psBin = whichFn("pwsh") ?? whichFn("powershell") ?? "powershell";
+        return [
+            psBin,
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            `irm ${INSTALL_PS1_URL} | iex`,
+        ];
+    }
+    if (host === "darwin" || host === "linux") {
+        return ["bash", "-c", `curl -fsSL ${INSTALL_SH_URL} | bash`];
+    }
+    throw new Error(`no upstream ghx installer available for host '${host}'; ` +
+        "see https://github.com/brunoborges/ghx#install for manual options");
+}
+export function installSetupGhx(host, whichFn = defaultWhich, runner = spawnSync) {
+    const cmd = buildSetupGhxInstallCommand(host, whichFn);
+    const proc = runner(cmd[0] ?? "", cmd.slice(1), {
+        env: { ...process.env, GHX_VERSION },
+        stdio: "inherit",
+    });
+    return proc.status ?? 1;
+}
+/** Native `setup:ghx` handler (replaces scripts/setup_ghx.py shell-out, #2022 Phase 1). */
+export function runSetupGhx(argv, io, deps = {}) {
+    const args = parseSetupGhxArgs(argv);
+    if (args.error !== undefined) {
+        io.writeErr(`setup-ghx: ${args.error}\n`);
+        return 2;
+    }
+    if (args.yes && args.check) {
+        io.writeErr("[setup_ghx] error: --yes and --check are mutually exclusive.\n");
+        return 2;
+    }
+    const whichFn = deps.whichFn ?? defaultWhich;
+    if (ghxPresent(whichFn)) {
+        io.writeOut("[setup_ghx] ghx already on PATH -- skipping install.\n");
+        return 0;
+    }
+    if (args.check) {
+        if (whichFn("gh") !== null) {
+            io.writeOut("[setup_ghx] gh is on PATH but ghx is not; ghx is the recommended GitHub CLI " +
+                "cache proxy. Install with `directive setup:ghx` (or `task setup:ghx`). Refs #884.\n");
+        }
+        else {
+            io.writeOut("[setup_ghx] ghx not on PATH; recommended for speed -- run `directive setup:ghx` " +
+                "to opt in. Consumer projects only require gh. Refs #884.\n");
+        }
+        return 0;
+    }
+    let consent;
+    if (args.yes) {
+        consent = true;
+        io.writeOut("[setup_ghx] --yes provided; skipping interactive consent prompt.\n");
+    }
+    else {
+        const skip = (process.env.DEFT_SETUP_GHX_SKIP ?? "").trim();
+        if (skip === "1" || skip.toLowerCase() === "true" || skip.toLowerCase() === "yes") {
+            io.writeOut("[setup_ghx] DEFT_SETUP_GHX_SKIP set; skipping ghx install. Refs #884.\n");
             return 0;
         }
-        catch (err) {
-            const e = err;
-            return typeof e.status === "number" ? e.status : 1;
+        const readLine = deps.readConsentLine ?? readConsentLineFromStdin;
+        consent = promptSetupGhxConsent(io, readLine);
+    }
+    if (!consent) {
+        io.writeOut("[setup_ghx] Skipping ghx install. ghx is recommended for speed for maintainers and " +
+            "swarm runs; consumer projects only require gh " +
+            "(see https://github.com/brunoborges/ghx, #884).\n");
+        return 0;
+    }
+    const host = detectSetupGhxHost();
+    const runInstall = deps.runInstall ?? ((h) => installSetupGhx(h, whichFn));
+    try {
+        const rc = runInstall(host);
+        if (rc !== 0) {
+            io.writeErr(`[setup_ghx] error: upstream installer exited ${rc}. ` +
+                "See https://github.com/brunoborges/ghx#install for manual options.\n");
+            return 1;
+        }
+        io.writeOut("[setup_ghx] ghx installed. Open a fresh shell so the updated PATH takes effect, " +
+            "then re-run `task setup` to verify.\n");
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        io.writeErr(`[setup_ghx] error: ${message}\n`);
+        return 1;
+    }
+}
+// ===========================================================================
+// Native directive bootstrap launcher (#2022 Phase 4).
+//
+// Thin operator entry: deposit-if-absent, carry phase intent + deliberate
+// re-entry signal, then hand off to deft-directive-setup (agent-driven).
+// ===========================================================================
+export const SETUP_SKILL_REL_PATH = ".deft/core/skills/deft-directive-setup/SKILL.md";
+function bootstrapPhaseLabel(phase) {
+    if (phase === 1)
+        return "user";
+    if (phase === 2)
+        return "project";
+    return "spec";
+}
+function resolveBootstrapUserMdPath() {
+    const override = process.env.DEFT_USER_PATH?.trim();
+    if (override)
+        return resolve(override);
+    return join(userConfigDir(), "USER.md");
+}
+function defaultBootstrapDeps() {
+    return {
+        deftCorePresent: (projectRoot) => isDirSafe(join(resolve(projectRoot), ".deft", "core")),
+        userMdPresent: () => isFileSafe(resolveBootstrapUserMdPath()),
+        projectDefPresent: (projectRoot) => isFileSafe(projectDefinitionPath(projectRoot)),
+        runInitDeposit: async (projectRoot, io) => {
+            const initArgs = parseInitArgv(["--yes", "--repo-root", projectRoot, "--json"], []);
+            return runInitDepositCli({
+                ...initArgs,
+                writeOut: io.writeOut,
+                writeErr: io.writeErr,
+            });
+        },
+    };
+}
+/** Parse `directive bootstrap` argv (#2022 Phase 4). */
+export function parseDirectiveBootstrapArgs(argv) {
+    let projectRoot = ".";
+    let jumpProject = false;
+    let strategy = null;
+    let reconfigure = false;
+    let force = false;
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project") {
+            jumpProject = true;
+        }
+        else if (arg === "--reconfigure") {
+            reconfigure = true;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    projectRoot,
+                    jumpProject,
+                    strategy,
+                    reconfigure,
+                    force,
+                    json,
+                    error: "argument --project-root: expected one argument",
+                };
+            }
+            projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--strategy") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    projectRoot,
+                    jumpProject,
+                    strategy,
+                    reconfigure,
+                    force,
+                    json,
+                    error: "argument --strategy: expected one argument",
+                };
+            }
+            strategy = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--strategy=")) {
+            strategy = arg.slice("--strategy=".length);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return {
+                projectRoot,
+                jumpProject,
+                strategy,
+                reconfigure,
+                force,
+                json,
+                error: "__help__",
+            };
+        }
+        else {
+            return {
+                projectRoot,
+                jumpProject,
+                strategy,
+                reconfigure,
+                force,
+                json,
+                error: `unrecognized argument: ${arg}`,
+            };
+        }
+    }
+    return {
+        projectRoot: resolve(projectRoot),
+        jumpProject,
+        strategy,
+        reconfigure,
+        force,
+        json,
+    };
+}
+/** Resolve phase intent and deliberate re-entry signal from parsed args + on-disk state. */
+export function resolveDirectiveBootstrapPlan(args, deps) {
+    let phase;
+    if (args.jumpProject) {
+        phase = 2;
+    }
+    else if (args.strategy !== null) {
+        phase = 3;
+    }
+    else if (!deps.userMdPresent(args.projectRoot)) {
+        phase = 1;
+    }
+    else if (!deps.projectDefPresent(args.projectRoot)) {
+        phase = 2;
+    }
+    else {
+        phase = 3;
+    }
+    let reEntry = "none";
+    if (args.force) {
+        reEntry = "force";
+    }
+    else if (args.reconfigure) {
+        reEntry = "reconfigure";
+    }
+    else {
+        const artifactExists = phase === 1
+            ? deps.userMdPresent(args.projectRoot)
+            : phase === 2
+                ? deps.projectDefPresent(args.projectRoot)
+                : deps.projectDefPresent(args.projectRoot);
+        if (artifactExists) {
+            reEntry = "prompt";
+        }
+    }
+    return {
+        phase,
+        phaseLabel: bootstrapPhaseLabel(phase),
+        reEntry,
+        strategy: args.strategy,
+    };
+}
+function printDirectiveBootstrapHelp(io) {
+    io.writeOut("Usage: directive bootstrap [--project-root <path>] [--project] [--strategy <name>] [--reconfigure] [--force] [--json]\n\n" +
+        "Deposit the framework when absent, then hand off to deft-directive-setup.\n\n" +
+        "  --project       Jump to Phase 2 (project configuration)\n" +
+        "  --strategy      Jump to Phase 3 (scope vBRIEF / spec interview)\n" +
+        "  --reconfigure   Deliberate re-entry — agent should reconfigure existing artifacts\n" +
+        "  --force         Skip reconfigure-or-keep prompt; overwrite allowed\n" +
+        "  --json          Emit structured handoff JSON on stdout\n");
+}
+function emitBootstrapHandoff(handoff, io, json) {
+    if (json) {
+        io.writeOut(`${JSON.stringify(handoff, null, 2)}\n`);
+        return;
+    }
+    io.writeOut("[directive bootstrap] Setup launcher — hand off to deft-directive-setup\n\n");
+    io.writeOut(`project_root: ${handoff.project_root}\n`);
+    io.writeOut(`deposited: ${handoff.deposited}\n`);
+    io.writeOut(`phase: ${handoff.phase} (${handoff.phase_label})\n`);
+    io.writeOut(`re_entry: ${handoff.re_entry}\n`);
+    if (handoff.strategy !== null) {
+        io.writeOut(`strategy: ${handoff.strategy}\n`);
+    }
+    io.writeOut(`\nNext: Read and follow ${handoff.skill_path}\n`);
+}
+/** Native `directive bootstrap` handler (#2022 Phase 4). */
+export async function runDirectiveBootstrap(argv, io, deps = {}) {
+    const merged = { ...defaultBootstrapDeps(), ...deps };
+    const args = parseDirectiveBootstrapArgs(argv);
+    if (args.error === "__help__") {
+        printDirectiveBootstrapHelp(io);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        io.writeErr(`directive bootstrap: ${args.error}\n`);
+        return 2;
+    }
+    const plan = resolveDirectiveBootstrapPlan(args, merged);
+    let deposited = false;
+    if (!merged.deftCorePresent(args.projectRoot)) {
+        const initCode = await merged.runInitDeposit(args.projectRoot, io);
+        if (initCode !== 0) {
+            return initCode;
+        }
+        deposited = true;
+    }
+    const handoff = {
+        handoff: "deft-directive-setup",
+        skill_path: SETUP_SKILL_REL_PATH,
+        project_root: args.projectRoot,
+        deposited,
+        phase: plan.phase,
+        phase_label: plan.phaseLabel,
+        re_entry: plan.reEntry,
+        strategy: plan.strategy,
+    };
+    emitBootstrapHandoff(handoff, io, args.json);
+    return 0;
+}
+// ===========================================================================
+// Native policy-set handler (#2022 Phase 1).
+//
+// Port of scripts/policy_set.py to native TypeScript so the typed-policy write
+// path (enforce-branches / allow-direct-commits / wip-cap / subagent-backend)
+// and the subagent-backends probe surface no longer shell into bundled Python.
+// Behaviour parity with the Python script is preserved: the audit row appended
+// to meta/policy-changes.log, the json.dumps(..., indent=2, ensure_ascii=False)
+// + "\n" serialization, the disclosure text, and the exit codes
+// (0 success / 1 refusal / 2 config-or-parse error).
+// ===========================================================================
+const POLICY_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- enabling direct commits to the default " +
+    "branch turns OFF the deft branch-protection policy.\n" +
+    "  \u2022 Pre-commit + pre-push hooks will no longer block default-branch " +
+    "commits.\n" +
+    "  \u2022 verify:branch will pass on the default branch.\n" +
+    "  \u2022 The CI sanity check (head_ref != base_ref) is still independent and " +
+    "will continue to flag master->master PRs.\n" +
+    "  \u2022 This change is reversible: run `task policy:enforce-branches` to " +
+    "re-enable the gate.\n" +
+    "  \u2022 The change is recorded to meta/policy-changes.log for auditability.";
+const POLICY_WIP_CAP_DISCLOSURE = "\u26a0 Capability-cost disclosure -- changing plan.policy.wipCap " +
+    "alters the refusal threshold on task scope:promote (#1124 / D4 of #1119).\n" +
+    "  \u2022 Raising the cap lets more vBRIEFs sit in pending/+active/ " +
+    "before promotion is refused.\n" +
+    "  \u2022 Lowering the cap may put the project over cap immediately; " +
+    "use `task scope:demote` / `task scope:demote --batch --older-than-days 30` " +
+    "to drain.\n" +
+    "  \u2022 cap=0 freezes promotion entirely (useful for code-freeze " +
+    "windows; restore by setting a positive value).\n" +
+    "  \u2022 This change is reversible and recorded to " +
+    "meta/policy-changes.log for auditability.";
+const POLICY_SET_COMMANDS = [
+    "enforce-branches",
+    "allow-direct-commits",
+    "wip-cap",
+    "subagent-backend",
+    "subagent-backends",
+];
+/** Flags each subcommand accepts (mirrors the policy_set.py argparse subparsers). */
+const POLICY_SET_ALLOWED_FLAGS = {
+    "enforce-branches": new Set(["--actor", "--note", "--project-root"]),
+    "allow-direct-commits": new Set(["--confirm", "--actor", "--note", "--project-root"]),
+    "wip-cap": new Set(["--set", "--confirm", "--actor", "--note", "--project-root"]),
+    "subagent-backend": new Set(["--set", "--actor", "--note", "--project-root"]),
+    "subagent-backends": new Set(["--format", "--project-root"]),
+};
+/** Custom error so write helpers can distinguish a missing file from a config fault. */
+class PolicySetError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.name = "PolicySetError";
+        this.kind = kind;
+    }
+}
+/** Python repr() for the audit-trail `previous=` field (None / 'str' / int / bool). */
+function pyRepr(value) {
+    if (value === undefined || value === null)
+        return "None";
+    if (typeof value === "string")
+        return `'${value}'`;
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    return String(value);
+}
+/** Strip newlines so an audit note stays a single log line (mirrors policy_set.py). */
+function sanitizeNote(note) {
+    return note.replace(/\n/g, " ").replace(/\r/g, " ");
+}
+function defaultPolicySetActor(cmd) {
+    switch (cmd) {
+        case "enforce-branches":
+            return "task policy:enforce-branches";
+        case "allow-direct-commits":
+            return "task policy:allow-direct-commits";
+        case "wip-cap":
+            return "task policy:wip-cap";
+        case "subagent-backend":
+            return "task policy:subagent-backend";
+        case "subagent-backends":
+            return "task policy:subagent-backends";
+    }
+}
+/** Mirror Python `Path(...).expanduser()` for a leading `~` / `~/` segment. */
+function expandUser(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+function policySetError(message) {
+    return {
+        cmd: "enforce-branches",
+        confirm: false,
+        actor: "",
+        note: "",
+        projectRoot: ".",
+        format: "text",
+        error: message,
+    };
+}
+/** Parse `policy-set <cmd> [flags]` (mirrors the policy_set.py argparse surface). */
+function parsePolicySetArgs(argv) {
+    const cmd = argv[0];
+    if (cmd === undefined) {
+        return policySetError("the following arguments are required: cmd");
+    }
+    if (!POLICY_SET_COMMANDS.includes(cmd)) {
+        return policySetError(`argument cmd: invalid choice: '${cmd}'`);
+    }
+    const command = cmd;
+    const allowed = POLICY_SET_ALLOWED_FLAGS[command];
+    const args = {
+        cmd: command,
+        confirm: false,
+        actor: defaultPolicySetActor(command),
+        note: "",
+        projectRoot: ".",
+        format: "text",
+    };
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i += 1) {
+        const token = rest[i];
+        if (token === undefined)
+            continue;
+        let flag = token;
+        let inlineValue;
+        if (token.startsWith("--") && token.includes("=")) {
+            const eq = token.indexOf("=");
+            flag = token.slice(0, eq);
+            inlineValue = token.slice(eq + 1);
+        }
+        if (!allowed.has(flag)) {
+            return policySetError(`unrecognized arguments: ${token}`);
+        }
+        const takeValue = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            i += 1;
+            return rest[i];
+        };
+        if (flag === "--confirm") {
+            args.confirm = true;
+            continue;
+        }
+        const value = takeValue();
+        if (value === undefined) {
+            return policySetError(`argument ${flag}: expected one argument`);
+        }
+        if (flag === "--actor") {
+            args.actor = value;
         }
+        else if (flag === "--note") {
+            args.note = value;
+        }
+        else if (flag === "--project-root") {
+            args.projectRoot = expandUser(value);
+        }
+        else if (flag === "--format") {
+            if (value !== "text" && value !== "json") {
+                return policySetError(`argument --format: invalid choice: '${value}'`);
+            }
+            args.format = value;
+        }
+        else if (flag === "--set") {
+            if (command === "wip-cap") {
+                // Python int() strips surrounding whitespace, so "--set ' 5'" parsed
+                // cleanly; trim before the integer check to preserve that contract.
+                const capText = value.trim();
+                if (!/^[+-]?\d+$/.test(capText)) {
+                    return policySetError(`argument --set: invalid int value: '${value}'`);
+                }
+                args.cap = Number.parseInt(capText, 10);
+            }
+            else {
+                // subagent-backend --set <choice>
+                if (!KNOWN_SUBAGENT_BACKEND_IDS.has(value)) {
+                    const choices = [...KNOWN_SUBAGENT_BACKEND_IDS].sort().join(", ");
+                    return policySetError(`argument --set: invalid choice: '${value}' (choose from ${choices})`);
+                }
+                args.backendId = value;
+            }
+        }
+    }
+    if (command === "wip-cap" && args.cap === undefined) {
+        return policySetError("the following arguments are required: --set");
+    }
+    if (command === "subagent-backend" && args.backendId === undefined) {
+        return policySetError("the following arguments are required: --set");
+    }
+    return args;
+}
+/** Load PROJECT-DEFINITION for an in-place typed-field write (mirrors the .setdefault chain). */
+function loadProjectDefinitionForWrite(projectRoot) {
+    const path = projectDefinitionPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new PolicySetError(`PROJECT-DEFINITION not found at ${path}`, "not-found");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new PolicySetError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`, "config");
+    }
+    // JSON.parse can yield a non-object top level (null / array / scalar) without
+    // throwing; reject it before the .plan/.policy property chain dereferences it.
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new PolicySetError(`PROJECT-DEFINITION at ${path} is not a JSON object`, "config");
+    }
+    const data = parsed;
+    let plan = data.plan;
+    if (plan === undefined) {
+        plan = {};
+        data.plan = plan;
+    }
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        throw new PolicySetError("PROJECT-DEFINITION 'plan' is not an object", "config");
+    }
+    const planObj = plan;
+    let policy = planObj.policy;
+    if (policy === undefined) {
+        policy = {};
+        planObj.policy = policy;
+    }
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        throw new PolicySetError("plan.policy is not an object", "config");
+    }
+    return { path, data, policyBlock: policy };
+}
+/** Write plan.policy.wipCap in place + append the audit row (mirrors set_wip_cap). */
+function writeWipCap(projectRoot, cap, actor, note) {
+    const { path, data, policyBlock } = loadProjectDefinitionForWrite(projectRoot);
+    const previous = policyBlock.wipCap;
+    policyBlock.wipCap = cap;
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    const changed = previous !== cap;
+    const parts = [`actor=${actor}`, `wipCap=${cap}`, `previous=${pyRepr(previous)}`];
+    if (note)
+        parts.push(`note=${sanitizeNote(note)}`);
+    const auditEntry = parts.join(" ");
+    appendAuditLog(projectRoot, auditEntry);
+    return { changed, auditEntry };
+}
+/** Write plan.policy.swarmSubagentBackend in place + append the audit row. */
+function writeSubagentBackend(projectRoot, backendId, actor, note) {
+    const { path, data, policyBlock } = loadProjectDefinitionForWrite(projectRoot);
+    const previous = policyBlock.swarmSubagentBackend;
+    policyBlock.swarmSubagentBackend = backendId;
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    const changed = previous !== backendId;
+    const parts = [
+        `actor=${actor}`,
+        `swarmSubagentBackend=${backendId}`,
+        `previous=${pyRepr(previous)}`,
+    ];
+    if (note)
+        parts.push(`note=${sanitizeNote(note)}`);
+    const auditEntry = parts.join(" ");
+    appendAuditLog(projectRoot, auditEntry);
+    return { changed, auditEntry };
+}
+/** Serialise the probe output for `subagent-backends --format json`. */
+function subagentBackendsToJson(backends) {
+    const payload = {
+        backends: backends.map((entry) => ({
+            id: entry.backend_id,
+            display_name: entry.display_name,
+            roles: [...entry.roles],
+            available: entry.available,
+        })),
     };
+    return JSON.stringify(payload, null, 2);
+}
+/** Map a write-path error to its fail-closed message + exit code (mirrors the except blocks). */
+function reportPolicyWriteError(err, io) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof PolicySetError && err.kind === "not-found") {
+        io.writeErr(`\u274c ${message}\n`);
+        io.writeErr("  Recovery: run `task setup` to generate vbrief/PROJECT-DEFINITION.vbrief.json.\n");
+        return 2;
+    }
+    io.writeErr(`\u274c Config error: ${message}\n`);
+    return 2;
+}
+function applyBranchPolicy(args, io) {
+    let target;
+    if (args.cmd === "enforce-branches") {
+        target = false;
+    }
+    else {
+        if (!args.confirm) {
+            io.writeOut(`${POLICY_CAPABILITY_COST_DISCLOSURE}\n`);
+            io.writeOut("\n");
+            io.writeOut("Re-run with --confirm to apply: task policy:allow-direct-commits -- --confirm\n");
+            return 1;
+        }
+        target = true;
+    }
+    let result;
+    try {
+        result = setPolicy(args.projectRoot, {
+            allowDirectCommits: target,
+            actor: args.actor,
+            note: args.note,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("PROJECT-DEFINITION not found")) {
+            io.writeErr(`\u274c ${message}\n`);
+            io.writeErr("  Recovery: run `task setup` to generate vbrief/PROJECT-DEFINITION.vbrief.json.\n");
+            return 2;
+        }
+        io.writeErr(`\u274c Config error: ${message}\n`);
+        return 2;
+    }
+    const state = target ? "OFF" : "ON";
+    io.writeOut(`\u2713 plan.policy.allowDirectCommitsToMaster=${target ? "true" : "false"} ` +
+        `(branch-protection ${state}).\n`);
+    if (result.changed) {
+        io.writeOut(`  audit: meta/policy-changes.log :: ${result.auditEntry}\n`);
+    }
+    else {
+        io.writeOut("  no-op: value already matched (audit entry still appended for trail).\n");
+    }
+    io.writeOut(`${disclosureLine(resolvePolicy(args.projectRoot))}\n`);
+    return 0;
+}
+function applyWipCap(args, io) {
+    const cap = args.cap ?? 0;
+    if (cap < 0) {
+        io.writeErr(`\u274c --set must be >= 0; got ${cap}.\n`);
+        return 1;
+    }
+    if (!args.confirm) {
+        io.writeOut(`${POLICY_WIP_CAP_DISCLOSURE}\n`);
+        io.writeOut("\n");
+        io.writeOut(`Re-run with --confirm to apply: task policy:wip-cap -- --set ${cap} --confirm\n`);
+        return 1;
+    }
+    let res;
+    try {
+        res = writeWipCap(args.projectRoot, cap, args.actor, args.note);
+    }
+    catch (err) {
+        return reportPolicyWriteError(err, io);
+    }
+    io.writeOut(`\u2713 plan.policy.wipCap=${cap}.\n`);
+    if (res.changed) {
+        io.writeOut(`  audit: meta/policy-changes.log :: ${res.auditEntry}\n`);
+    }
+    else {
+        io.writeOut("  no-op: value already matched (audit entry still appended for trail).\n");
+    }
+    const result = resolveWipCap(args.projectRoot);
+    io.writeOut(`[deft policy] plan.policy.wipCap=${result.cap} (source: ${result.source}).\n`);
+    return 0;
+}
+function applySubagentBackend(args, io) {
+    const backendId = args.backendId ?? "";
+    let res;
+    try {
+        res = writeSubagentBackend(args.projectRoot, backendId, args.actor, args.note);
+    }
+    catch (err) {
+        return reportPolicyWriteError(err, io);
+    }
+    io.writeOut(`\u2713 plan.policy.swarmSubagentBackend=${backendId}.\n`);
+    if (res.changed) {
+        io.writeOut(`  audit: meta/policy-changes.log :: ${res.auditEntry}\n`);
+    }
+    else {
+        io.writeOut("  no-op: value already matched (audit entry still appended for trail).\n");
+    }
+    const result = resolveSwarmSubagentBackend(args.projectRoot);
+    io.writeOut(`[deft policy] plan.policy.swarmSubagentBackend=${pyRepr(result.backend_id)} ` +
+        `(source: ${result.source}).\n`);
+    return 0;
+}
+function applySubagentBackends(args, io) {
+    const entries = probeSubagentBackends();
+    if (args.format === "json") {
+        io.writeOut(`${subagentBackendsToJson(entries)}\n`);
+        return 0;
+    }
+    for (const entry of entries) {
+        const roles = entry.roles.join(", ");
+        const avail = entry.available ? "available" : "unavailable";
+        io.writeOut(`${entry.backend_id}\t${entry.display_name}\troles=[${roles}]\t${avail}\n`);
+    }
+    return 0;
+}
+/** Native `policy-set` dispatcher (replaces the policy_set.py shell-out, #2022 Phase 1). */
+export function runPolicySet(argv, io) {
+    const args = parsePolicySetArgs(argv);
+    if (args.error !== undefined) {
+        io.writeErr(`policy-set: ${args.error}\n`);
+        return 2;
+    }
+    switch (args.cmd) {
+        case "enforce-branches":
+        case "allow-direct-commits":
+            return applyBranchPolicy(args, io);
+        case "wip-cap":
+            return applyWipCap(args, io);
+        case "subagent-backend":
+            return applySubagentBackend(args, io);
+        case "subagent-backends":
+            return applySubagentBackends(args, io);
+    }
 }
 async function loadCoreModuleHandler(verb, io) {
     switch (verb) {
@@ -449,17 +1985,19 @@ async function loadCoreModuleHandler(verb, io) {
             };
         }
         case "pack-migrate-skills":
-            return loadPythonScriptHandler("pack_migrate_skills.py");
+            return (argv) => runPackMigrateSkills(argv, io);
         case "pack-migrate-rules":
-            return loadPythonScriptHandler("pack_migrate_rules.py");
+            return (argv) => runPackMigrateRules(argv, io);
         case "pack-migrate-strategies":
-            return loadPythonScriptHandler("pack_migrate_strategies.py");
+            return (argv) => runPackMigrateStrategies(argv, io);
         case "pack-migrate-patterns":
-            return loadPythonScriptHandler("pack_migrate_patterns.py");
+            return (argv) => runPackMigratePatterns(argv, io);
         case "pack-migrate-swarm-spec":
-            return loadPythonScriptHandler("pack_migrate_swarm_spec.py");
+            return (argv) => runPackMigrateSwarmSpec(argv, io);
         case "policy-set":
-            return loadPythonScriptHandler("policy_set.py");
+            return (argv) => runPolicySet(argv, io);
+        case "setup-ghx":
+            return (argv) => runSetupGhx(argv, io);
         case "scope-undo": {
             const { undoMain } = await import("@deftai/directive-core/dist/scope/main.js");
             return undoMain;