@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/core-ontology-native.js

@@ -0,0 +1,916 @@
+/** Native TypeScript implementation of the local ontology scaffold scripts. */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { resolveBundledAsset } from "../utils/hq-roots.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
+import { runKnowledgePrefs } from "./core-knowledge-prefs.js";
+const FLAG = "core-native-ontology";
+const ASSET = "core/scripts/";
+const SIGNAL_TYPES = ["decision", "commitment", "risk", "question", "action_item", "key_point", "participant_contribution", "summary"];
+const CANDIDATE_SIGNAL_TYPES = ["action_item", "commitment", "decision", "risk", "question", "key_point", "participant_contribution", "summary"];
+const ENTITY_TYPES = ["person", "project", "company", "concept"];
+const ok = (stdout = "") => ({ code: 0, stdout, stderr: "" });
+const err = (code, stderr, stdout = "") => ({ code, stdout, stderr });
+const shellSubstitution = (value) => value.replace(/\n+$/, "");
+const byteSort = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+function trLowercase(value) {
+    const locale = process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || "C";
+    const asciiLower = (text) => text.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32));
+    if (/^(?:C|POSIX)(?:$|[._@])/i.test(locale))
+        return asciiLower(value);
+    const localeName = locale.split(/[.@]/, 1)[0].replaceAll("_", "-");
+    if (!/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(localeName))
+        return asciiLower(value);
+    return value.toLocaleLowerCase(localeName);
+}
+function writeResult(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exitCode = result.code;
+}
+/** Fast-entry adapter; family gating and shell fallback happen before import. */
+export function runOntologyNativeFast(args, _stdin, cwd, hqRoot, commandName) {
+    const operands = [...args];
+    const root = commandName === "source-yaml-validate" ? cwd : hqRoot ?? cwd;
+    let result;
+    if (commandName === "audience-grant")
+        result = audienceGrant(operands, root);
+    else if (commandName === "brief")
+        result = briefCommand(operands, root);
+    else if (commandName === "candidate")
+        result = candidateCommand(operands, root);
+    else if (commandName === "garden")
+        result = gardenCommand(operands, root);
+    else if (commandName === "source-worklist")
+        result = worklistCommand(operands, root);
+    else
+        result = sourceYamlValidate(operands[0]);
+    writeResult(result);
+    return result.code;
+}
+function runHq(args, output = "capture") {
+    const executable = process.env.HQ_BIN || "hq";
+    const result = spawnSync(executable, args, {
+        cwd: process.cwd(),
+        env: process.env,
+        encoding: "utf8",
+        stdio: output === "ignore" ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "ignore"],
+    });
+    return { status: result.status, stdout: typeof result.stdout === "string" ? result.stdout : "" };
+}
+function awkField(file, field, stripComment) {
+    if (!fs.existsSync(file))
+        return "";
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    const prefix = `${field}:`;
+    const line = lines.find((entry) => entry.startsWith(prefix));
+    if (line === undefined)
+        return "";
+    let value = line.slice(prefix.length).replace(/^[\t\n\v\f\r ]+/, "");
+    if (stripComment)
+        value = value.replace(/[\t\n\v\f\r ]+#.*$/, "");
+    return value.replace(/^["']|["']$/g, "");
+}
+function normalizeAudience(value) {
+    const entries = value.split(",")
+        .map((item) => item.replace(/^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g, ""))
+        .filter((item) => item !== "")
+        .map((item) => item.includes("@") ? item.toLowerCase() : item);
+    return [...new Set(entries)].sort(byteSort).join(",");
+}
+function audienceKey(value) {
+    const audience = shellSubstitution(value.replace(/^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/gm, ""));
+    if (!audience)
+        return err(2, "ontology-candidate: empty audience\n");
+    if (audience.toLowerCase() === "company")
+        return ok("company\n");
+    const key = createHash("sha256").update(normalizeAudience(audience)).digest("hex").slice(0, 16);
+    return ok(`${key}\n`);
+}
+export function sourceYamlValidate(file) {
+    if (!file)
+        return err(2, "usage: source-yaml-validate.sh <source.yaml>\n");
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        return err(2, `source-yaml-validate: no such file ${file}\n`);
+    }
+    let violations = 0;
+    let stdout = "";
+    const bad = (message) => { stdout += `${file}: ${message}\n`; violations += 1; };
+    const values = {};
+    for (const key of ["channel", "kind", "arrives", "pull_command", "audience_rule", "processor", "run", "schedule"]) {
+        values[key] = awkField(file, key, true);
+    }
+    const channel = values.channel;
+    const kind = values.kind;
+    const arrives = values.arrives;
+    const pull = values.pull_command;
+    const audience = values.audience_rule;
+    const processor = values.processor;
+    const run = values.run;
+    const schedule = values.schedule;
+    const folder = path.basename(path.dirname(file));
+    const oneOf = (name, value, allowed) => {
+        if (!` ${allowed} `.includes(` ${value} `))
+            bad(`${name} must be one of: ${allowed} (got '${value || "<missing>"}')`);
+    };
+    if (!channel)
+        bad("channel is required");
+    if (channel && channel !== folder)
+        bad(`channel '${channel}' must equal its folder name '${folder}'`);
+    oneOf("kind", kind, "meeting email slack doc custom");
+    oneOf("arrives", arrives, "drop pull cloud");
+    if (arrives === "pull" && !pull)
+        bad("pull_command is required when arrives: pull");
+    if (!audience)
+        bad("audience_rule is required (attendees|thread|channel|company|explicit); it is never defaulted");
+    else
+        oneOf("audience_rule", audience, "attendees thread channel company explicit");
+    if (!processor)
+        bad("processor is required (<worker>/<skill>)");
+    else if (!/^[a-z0-9-]+\/[a-z0-9-]+$/.test(processor))
+        bad(`processor must look like <worker>/<skill> (got '${processor}')`);
+    oneOf("run", run, "local cloud");
+    if (!schedule)
+        bad("schedule is required (cron or on-close)");
+    else if (schedule !== "on-close" && schedule.trim().split(/[\t\n\v\f\r ]+/).length !== 5) {
+        bad(`schedule must be a 5-field cron or on-close (got '${schedule}')`);
+    }
+    if (violations === 0)
+        stdout = `${file}: ok\n`;
+    return { code: violations === 0 ? 0 : 1, stdout, stderr: "" };
+}
+export function candidateCommand(args, root) {
+    const command = args[0] ?? "";
+    if (command === "key")
+        return audienceKey(args[1] ?? "");
+    if (command !== "write")
+        return err(2, "ontology-candidate: usage: ontology-candidate.sh write|key ...\n");
+    const values = { company: "", kind: "", type: "", audience: "", sourceRef: "", body: "", bodyFile: "", createdBy: process.env.HQ_USER_EMAIL ?? "" };
+    const aliases = {
+        "--company": "company", "--kind": "kind", "--type": "type", "--audience": "audience",
+        "--source-ref": "sourceRef", "--body": "body", "--body-file": "bodyFile", "--created-by": "createdBy",
+    };
+    for (let index = 1; index < args.length; index += 1) {
+        const name = args[index];
+        if (!(name in aliases))
+            return err(2, `ontology-candidate: unknown flag ${name}\n`);
+        if (index + 1 >= args.length) {
+            const lines = {
+                "--company": 50, "--kind": 51, "--type": 52, "--audience": 53,
+                "--source-ref": 54, "--body": 55, "--body-file": 56, "--created-by": 57,
+            };
+            return err(1, `${resolveBundledAsset(`${ASSET}ontology-candidate.sh`)}: line ${lines[name]}: $2: unbound variable\n`);
+        }
+        values[aliases[name]] = args[++index];
+    }
+    const { company, kind, type, audience, sourceRef } = values;
+    if (!company || !kind || !type || !audience || !sourceRef)
+        return err(2, "ontology-candidate: missing required flag\n");
+    let body = values.body;
+    if (values.bodyFile) {
+        if (!fs.existsSync(values.bodyFile) || !fs.statSync(values.bodyFile).isFile()) {
+            return err(2, `ontology-candidate: no body file ${values.bodyFile}\n`);
+        }
+        body = shellSubstitution(fs.readFileSync(values.bodyFile, "utf8"));
+    }
+    body = body.replace(/\n/g, " ").replace(/[\t\n\v\f\r ]+/g, " ").replace(/^ | $/g, "");
+    if (!body)
+        return err(2, "ontology-candidate: empty body\n");
+    let store;
+    let preference;
+    if (kind === "signal") {
+        store = "signals";
+        preference = "signals_capture";
+    }
+    else if (kind === "entity") {
+        store = "ontology";
+        preference = "ontology_capture";
+    }
+    else
+        return err(2, "ontology-candidate: kind must be signal or entity\n");
+    const allowed = kind === "signal" ? CANDIDATE_SIGNAL_TYPES : ENTITY_TYPES;
+    if (!allowed.includes(type))
+        return err(2, `ontology-candidate: unknown ${kind} type '${type}' (allowed: ${allowed.join(" ")})\n`);
+    const enabled = runKnowledgePrefs(["get", company, preference], root);
+    if (enabled.code !== 0)
+        return err(2, enabled.stderr);
+    if (shellSubstitution(enabled.stdout) !== "true")
+        return ok(`disabled for ${company} (${preference}=false)\n`);
+    const keyResult = audienceKey(audience);
+    if (keyResult.code !== 0)
+        return keyResult;
+    const key = shellSubstitution(keyResult.stdout);
+    const normalizedBody = trLowercase(body);
+    const id = createHash("sha256").update(`${kind}\n${type}\n${key}\n${normalizedBody}`).digest("hex");
+    const candidates = path.join(root, "companies", company, store, "_candidates");
+    if (fileNamedExists(candidates, `${id}.md`))
+        return ok(`exists ${id}\n`);
+    const day = new Date().toISOString().slice(0, 10);
+    const directory = path.join(candidates, day);
+    fs.mkdirSync(directory, { recursive: true });
+    const lines = ["---", `kind: ${kind}`, `type: ${type}`, `audience_key: ${key}`];
+    if (key !== "company")
+        lines.push(`audience: [${normalizeAudience(audience).replaceAll(",", ", ")}]`);
+    lines.push(`source_ref: "${sourceRef}"`);
+    if (values.createdBy)
+        lines.push(`created_by: ${values.createdBy}`);
+    lines.push(`created_at: ${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}`, "---", body);
+    const destination = path.join(directory, `${id}.md`);
+    fs.writeFileSync(`${destination}.tmp`, `${lines.join("\n")}\n`);
+    fs.renameSync(`${destination}.tmp`, destination);
+    return ok(`wrote ${store}/_candidates/${day}/${id}.md\n`);
+}
+function fileNamedExists(directory, name) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const current = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (fileNamedExists(current, name))
+                return true;
+        }
+        else if (entry.name === name)
+            return true;
+    }
+    return false;
+}
+function frontmatter(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const match = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const output = { _body: (match ? match[2] : text).trim() };
+    if (match) {
+        for (const line of match[1].split("\n")) {
+            const item = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+            if (item)
+                output[item[1]] = item[2].trim().replace(/^"(.*)"$/, "$1");
+        }
+    }
+    return output;
+}
+function walk(directory, predicate) {
+    if (!fs.existsSync(directory))
+        return [];
+    const output = [];
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!entry.name.startsWith("_"))
+                output.push(...walk(file, predicate));
+        }
+        else if (predicate(file))
+            output.push(file);
+    }
+    return output;
+}
+export function briefCommand(args, defaultRoot) {
+    let company;
+    let root;
+    let days = 14;
+    let top = 10;
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index];
+        if (key === "--company")
+            company = args[++index];
+        else if (key === "--hq-root")
+            root = args[++index];
+        else if (key === "--days")
+            days = Number(args[++index]);
+        else if (key === "--top")
+            top = Number(args[++index]);
+        else if (key === "--json")
+            json = true;
+        else
+            return err(2, `ontology-brief: unknown flag ${key}\n`);
+    }
+    if (!company)
+        return err(2, "usage: ontology-brief.mjs --company <co> [--days N] [--top N] [--json]\n");
+    const hqRoot = root || process.env.HQ_ROOT || defaultRoot;
+    const companyDir = path.join(hqRoot, "companies", company);
+    if (!fs.existsSync(companyDir))
+        return err(2, `ontology-brief: no company ${company}\n`);
+    const entities = walk(path.join(companyDir, "ontology", "entities"), (file) => file.endsWith(".md")).map(frontmatter);
+    const cutoff = Date.now() - days * 86400e3;
+    const signals = walk(path.join(companyDir, "signals"), (file) => file.endsWith(".md") && !file.includes(`${path.sep}_`))
+        .map((file) => ({ ...frontmatter(file), _scope: file.includes(`${path.sep}signals${path.sep}@`) ? "scoped" : "company" }))
+        .filter((signal) => SIGNAL_TYPES.includes(signal.type ?? ""));
+    const recent = signals.filter((signal) => !signal.created_at || Date.parse(signal.created_at) >= cutoff)
+        .sort((left, right) => (right.created_at ?? "").localeCompare(left.created_at ?? ""));
+    const facts = new Map();
+    for (const file of walk(path.join(companyDir, "ontology", "facts"), (item) => item.endsWith(".md"))) {
+        const document = frontmatter(file);
+        const scope = file.includes(`${path.sep}@company${path.sep}`) ? "company" : "scoped";
+        const slug = document.entity || path.basename(file, ".md");
+        for (const line of document._body.split("\n").filter((item) => item.startsWith("- "))) {
+            if (!facts.has(slug))
+                facts.set(slug, []);
+            facts.get(slug).push({ scope, line: line.slice(2) });
+        }
+    }
+    const hot = entities.map((entity) => ({ ...entity, _facts: facts.get(entity.slug ?? "") ?? [] }))
+        .sort((left, right) => (right._facts.length - left._facts.length) || ((Number(right.signal_count) || 0) - (Number(left.signal_count) || 0)))
+        .slice(0, top);
+    if (json) {
+        return ok(`${JSON.stringify({
+            company, entities: entities.length, signals: signals.length,
+            recent: recent.slice(0, top * 2).map((signal) => ({ type: signal.type, scope: signal._scope, text: signal.canonical_content || signal._body })),
+            hot: hot.map((entity) => ({ name: entity.canonical_name, type: entity.type, facts: entity._facts })),
+        })}\n`);
+    }
+    if (!entities.length && !signals.length)
+        return ok(`# ${company} — no local ontology yet\n\nNothing under ontology/ or signals/ that you can see.\n`);
+    const output = [`# ${company} — company brief (local)`, "", `${entities.length} entities · ${signals.length} signals you can see · last ${days} days`, "", "## Recent Signals"];
+    for (const type of SIGNAL_TYPES) {
+        const rows = recent.filter((signal) => signal.type === type).slice(0, 5);
+        if (!rows.length)
+            continue;
+        output.push("", `### ${type.replace("_", " ")}`);
+        for (const signal of rows)
+            output.push(`- ${signal.canonical_content || signal._body} _(${signal._scope})_`);
+    }
+    output.push("", "## Entities");
+    for (const entity of hot) {
+        output.push("", `### ${entity.canonical_name} — ${entity.type}`);
+        if (!entity._facts.length)
+            output.push("- no facts you can see");
+        for (const fact of entity._facts.slice(0, 6))
+            output.push(`- ${fact.line} _(${fact.scope})_`);
+    }
+    return ok(`${output.join("\n")}\n`);
+}
+const STOPWORDS = new Set([
+    "for", "calls", "call", "context", "summary", "reason", "the", "a", "an", "and",
+    "or", "this", "that", "it", "we", "they", "you", "i", "notes", "meeting", "update",
+    "question", "decision", "risk", "todo", "none", "n/a", "unknown",
+]);
+function readGardenDoc(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const match = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { fm: {}, body: text.trim() };
+    const fm = {};
+    for (const line of match[1].split("\n")) {
+        const item = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+        if (!item)
+            continue;
+        let value = item[2].trim();
+        if (value.startsWith("[") && value.endsWith("]")) {
+            value = value.slice(1, -1).split(",").map((part) => part.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+        }
+        else
+            value = value.replace(/^["']|["']$/g, "");
+        fm[item[1]] = value;
+    }
+    return { fm, body: match[2].trim() };
+}
+function writeGardenDoc(file, fm, body, dryRun) {
+    if (dryRun)
+        return;
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(fm)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        lines.push(`${key}: ${Array.isArray(value) ? `[${value.join(", ")}]` : value}`);
+    }
+    lines.push("---", body, "");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(`${file}.tmp`, lines.join("\n"));
+    fs.renameSync(`${file}.tmp`, file);
+}
+const slugify = (value) => value.toLowerCase().normalize("NFKD").replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+const isoNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+function listCandidates(directory) {
+    if (!fs.existsSync(directory))
+        return [];
+    const output = [];
+    for (const name of fs.readdirSync(directory).sort()) {
+        if (name === "_done")
+            continue;
+        const current = path.join(directory, name);
+        if (!fs.statSync(current).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(current).sort()) {
+            if (file.endsWith(".md"))
+                output.push(path.join(current, file));
+        }
+    }
+    return output;
+}
+export function gardenCommand(args, defaultRoot) {
+    let company;
+    let root;
+    let dryRun = false;
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index];
+        if (key === "--company")
+            company = args[++index];
+        else if (key === "--hq-root")
+            root = args[++index];
+        else if (key === "--dry-run")
+            dryRun = true;
+        else if (key === "--json")
+            json = true;
+        else
+            return err(2, `ontology-garden: unknown flag ${key}\n`);
+    }
+    if (!company)
+        return err(2, "usage: ontology-garden.mjs --company <co> [--hq-root <p>] [--dry-run] [--json]\n");
+    const hqRoot = root || process.env.HQ_ROOT || defaultRoot;
+    const companyDir = path.join(hqRoot, "companies", company);
+    if (!fs.existsSync(companyDir))
+        return err(2, `ontology-garden: no company ${company}\n`);
+    const ontology = path.join(companyDir, "ontology");
+    const signals = path.join(companyDir, "signals");
+    const report = { company, entities_created: 0, entities_updated: 0, signals_promoted: 0, facts_written: 0, rejected: 0, candidates_processed: 0, dry_run: dryRun };
+    const rejected = [];
+    const moves = [];
+    const entities = new Map();
+    const nameIndex = new Map();
+    const entityDirectory = path.join(ontology, "entities");
+    if (fs.existsSync(entityDirectory)) {
+        for (const type of fs.readdirSync(entityDirectory)) {
+            const typeDirectory = path.join(entityDirectory, type);
+            if (!fs.statSync(typeDirectory).isDirectory())
+                continue;
+            for (const name of fs.readdirSync(typeDirectory)) {
+                if (!name.endsWith(".md"))
+                    continue;
+                const file = path.join(typeDirectory, name);
+                const { fm } = readGardenDoc(file);
+                const slug = String(fm.slug || name.replace(/\.md$/, ""));
+                const aliases = Array.isArray(fm.aliases) ? fm.aliases : [];
+                const names = [fm.canonical_name, ...aliases].filter((value) => typeof value === "string" && value.length > 0);
+                entities.set(slug, { type: String(fm.type || type), file, fm, names });
+                for (const item of names)
+                    nameIndex.set(item.toLowerCase(), slug);
+            }
+        }
+    }
+    for (const file of listCandidates(path.join(ontology, "_candidates"))) {
+        const { fm, body } = readGardenDoc(file);
+        const name = body.split("\n")[0].trim();
+        const type = String(fm.type ?? "");
+        const reject = (reason) => {
+            rejected.push({ at: isoNow(), name, type, reason, candidate: path.relative(companyDir, file) });
+            report.rejected += 1;
+        };
+        if (!ENTITY_TYPES.includes(type))
+            reject("unknown-type");
+        else if (!name || STOPWORDS.has(name.toLowerCase()) || name.length < 2)
+            reject("stopword");
+        else {
+            const slug = slugify(name);
+            const held = nameIndex.get(name.toLowerCase());
+            const existing = entities.get(held || slug);
+            if (existing && existing.type !== type)
+                reject(`type-conflict:${existing.type}`);
+            else if (existing) {
+                const aliases = new Set(Array.isArray(existing.fm.aliases) ? existing.fm.aliases : []);
+                if (name !== existing.fm.canonical_name && !aliases.has(name)) {
+                    aliases.add(name);
+                    existing.fm.aliases = [...aliases];
+                    existing.fm.last_updated = isoNow();
+                    writeGardenDoc(existing.file, existing.fm, "", dryRun);
+                    report.entities_updated += 1;
+                    nameIndex.set(name.toLowerCase(), held || slug);
+                }
+            }
+            else {
+                const entityFile = path.join(ontology, "entities", type, `${slug}.md`);
+                const entityFm = {
+                    type, canonical_name: name, slug, aliases: [], signal_count: 0,
+                    first_seen: String(fm.created_at || isoNow()), last_updated: isoNow(), enriched_by: "ontology-worker",
+                };
+                writeGardenDoc(entityFile, entityFm, "", dryRun);
+                entities.set(slug, { type, file: entityFile, fm: entityFm, names: [name] });
+                nameIndex.set(name.toLowerCase(), slug);
+                report.entities_created += 1;
+            }
+        }
+        moves.push(file);
+        report.candidates_processed += 1;
+    }
+    const index = [];
+    for (const file of listCandidates(path.join(signals, "_candidates"))) {
+        const { fm, body } = readGardenDoc(file);
+        const type = String(fm.type ?? "");
+        const key = String(fm.audience_key ?? "");
+        moves.push(file);
+        report.candidates_processed += 1;
+        if (!SIGNAL_TYPES.includes(type) || !key || !body) {
+            rejected.push({ at: isoNow(), type, reason: !key ? "missing-audience" : "invalid", candidate: path.relative(companyDir, file) });
+            report.rejected += 1;
+            continue;
+        }
+        if (key !== "company" && !(Array.isArray(fm.audience) && fm.audience.length > 0)) {
+            rejected.push({ at: isoNow(), type, reason: "scoped-without-principals", candidate: path.relative(companyDir, file) });
+            report.rejected += 1;
+            continue;
+        }
+        const id = path.basename(file, ".md");
+        const scopeDirectory = key === "company" ? signals : path.join(signals, `@${key}`);
+        const outputFile = path.join(scopeDirectory, type, `${id}.md`);
+        if (!fs.existsSync(outputFile)) {
+            writeGardenDoc(outputFile, {
+                signal_id: id, type, canonical_content: JSON.stringify(body.split("\n")[0]), audience_key: key,
+                source_ref: JSON.stringify(fm.source_ref || ""), created_at: String(fm.created_at || isoNow()),
+            }, body, dryRun);
+            report.signals_promoted += 1;
+            index.push({ signal_id: id, type, audience_key: key, path: path.relative(companyDir, outputFile) });
+            if (key !== "company") {
+                const audienceFile = path.join(scopeDirectory, "_audience.yaml");
+                if (!fs.existsSync(audienceFile) && !dryRun) {
+                    fs.mkdirSync(scopeDirectory, { recursive: true });
+                    fs.writeFileSync(audienceFile, `audience_key: ${key}\nprincipals: [${fm.audience.join(", ")}]\n`);
+                }
+            }
+            const lower = body.toLowerCase();
+            const hit = new Set();
+            for (const [name, slug] of nameIndex) {
+                if (name.length < 3)
+                    continue;
+                const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                const expression = new RegExp(`(^|[^\\p{L}\\p{N}])${escaped}($|[^\\p{L}\\p{N}])`, "u");
+                if (expression.test(lower))
+                    hit.add(slug);
+            }
+            for (const slug of hit) {
+                const entity = entities.get(slug);
+                const factFile = path.join(ontology, "facts", `@${key}`, entity.type, `${slug}.md`);
+                const line = `- [${type}] ${body.split("\n")[0]} (signal ${id.slice(0, 12)})`;
+                const previous = fs.existsSync(factFile)
+                    ? readGardenDoc(factFile)
+                    : { fm: { entity: slug, type: entity.type, audience_key: key }, body: "" };
+                if (!previous.body.includes(`signal ${id.slice(0, 12)}`)) {
+                    writeGardenDoc(factFile, previous.fm, [previous.body, line].filter(Boolean).join("\n"), dryRun);
+                    report.facts_written += 1;
+                }
+                if (key === "company") {
+                    entity.fm.signal_count = String((parseInt(String(entity.fm.signal_count || "0"), 10) || 0) + 1);
+                    entity.fm.last_updated = isoNow();
+                    writeGardenDoc(entity.file, entity.fm, "", dryRun);
+                }
+            }
+        }
+    }
+    if (!dryRun) {
+        if (index.length) {
+            const file = path.join(signals, "_index", `${new Date().toISOString().slice(0, 10)}.json`);
+            const previous = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : [];
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, `${JSON.stringify([...previous, ...index], null, 2)}\n`);
+        }
+        if (rejected.length) {
+            const file = path.join(ontology, "_rejected", `${new Date().toISOString().slice(0, 10)}.jsonl`);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.appendFileSync(file, `${rejected.map((item) => JSON.stringify(item)).join("\n")}\n`);
+        }
+        for (const file of moves) {
+            const relative = path.relative(path.dirname(path.dirname(file)), file);
+            const destination = path.join(path.dirname(path.dirname(file)), "_done", relative);
+            fs.mkdirSync(path.dirname(destination), { recursive: true });
+            fs.renameSync(file, destination);
+        }
+        if (report.candidates_processed > 0) {
+            fs.mkdirSync(ontology, { recursive: true });
+            fs.writeFileSync(path.join(ontology, ".last-run"), `${Date.now()}\n`);
+        }
+    }
+    return ok(json
+        ? `${JSON.stringify(report)}\n`
+        : `garden ${company}: +${report.entities_created} entities, ~${report.entities_updated} updated, +${report.signals_promoted} signals, +${report.facts_written} facts, ${report.rejected} rejected, ${report.candidates_processed} candidates${dryRun ? " (dry run)" : ""}\n`);
+}
+export function audienceGrant(args, root) {
+    let company = "";
+    let dryRun = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index];
+        if (key === "--company") {
+            if (index + 1 >= args.length)
+                return err(1, `${resolveBundledAsset(`${ASSET}ontology-audience-grant.sh`)}: line 26: $2: unbound variable\n`);
+            company = args[++index];
+        }
+        else if (key === "--dry-run")
+            dryRun = true;
+        else
+            return err(2, `unknown flag ${key}\n`);
+    }
+    if (!company)
+        return err(2, "usage: ontology-audience-grant.sh --company <co> [--dry-run]\n");
+    const companyDir = path.join(root, "companies", company);
+    if (!fs.existsSync(companyDir) || !fs.statSync(companyDir).isDirectory())
+        return err(2, `no company ${company}\n`);
+    let cloud = false;
+    const companyYaml = path.join(companyDir, "company.yaml");
+    if (fs.existsSync(companyYaml))
+        cloud = /^cloud:[\t\v\f\r ]*true/m.test(fs.readFileSync(companyYaml, "utf8"));
+    const manifest = path.join(root, "companies", "manifest.yaml");
+    if (!cloud && fs.existsSync(manifest)) {
+        let inCompany = false;
+        for (const line of fs.readFileSync(manifest, "utf8").split("\n")) {
+            if (/^ {2}[^ #][^:]*:/.test(line))
+                inCompany = line.trim().split(/[\t ]/)[0] === `${company}:`;
+            if (inCompany && /^ {4}cloud_uid:[\t\v\f\r ]*[^\t\n\v\f\r ]/.test(line))
+                cloud = true;
+        }
+    }
+    if (!cloud)
+        return ok("local-only, no grants\n");
+    const membersRun = runHq(["members", "--company", company, "list"]);
+    const memberLines = membersRun.stdout.split("\n").slice(1).map((line) => line.trim().split(/[\t ]+/)[0]?.toLowerCase() ?? "");
+    const members = shellSubstitution(memberLines.join("\n"));
+    if (!members)
+        return err(3, `could not list members of ${company}\n`);
+    let granted = 0;
+    let skipped = 0;
+    let failed = 0;
+    let stdout = "";
+    let stderr = "";
+    const grant = (folder, who) => {
+        const prefix = `${folder.replace(/\/$/, "")}/*`;
+        if (dryRun) {
+            stdout += `would grant read ${prefix} -> ${who}\n`;
+            return;
+        }
+        runHq(["files", "--company", company, "share", prefix, "--with", who, "--permission", "read"], "ignore");
+        const acl = runHq(["files", "--company", company, "acl", prefix, "--json"]);
+        let confirmed = false;
+        if (acl.status === 0) {
+            try {
+                const payload = JSON.parse(acl.stdout);
+                confirmed = (payload.direct ?? []).some((value) => {
+                    if (!value || typeof value !== "object")
+                        return false;
+                    const row = value;
+                    return ((row.granteeId === who) || (who === "@all" && row.granteeType === "company-wide"))
+                        && ["read", "write", "admin"].includes(String(row.permission));
+                });
+            }
+            catch (parseError) {
+                // jq -e returns failure without a diagnostic on malformed JSON here.
+                void parseError;
+            }
+        }
+        if (confirmed) {
+            granted += 1;
+            stdout += `granted read ${prefix} -> ${who}\n`;
+        }
+        else {
+            failed += 1;
+            stderr += `READBACK FAILED: ${prefix} -> ${who}\n`;
+        }
+    };
+    const signalDir = path.join(companyDir, "signals");
+    const audienceFiles = fs.existsSync(signalDir)
+        ? fs.readdirSync(signalDir).filter((name) => /^@/.test(name)).sort(byteSort)
+            .map((name) => path.join(signalDir, name, "_audience.yaml")).filter((file) => fs.existsSync(file))
+        : [];
+    for (const audienceFile of audienceFiles) {
+        const key = path.basename(path.dirname(audienceFile)).slice(1);
+        const text = fs.readFileSync(audienceFile, "utf8");
+        const match = text.match(/^principals:[\t ]*\[(.*)\]$/m);
+        const principals = match
+            ? match[1].split(",").map((item) => item.replace(/^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g, ""))
+                .map((item) => item.includes("@") ? item.toLowerCase() : item).filter(Boolean)
+            : [];
+        const prefixes = [`signals/@${key}/`];
+        if (fs.existsSync(path.join(companyDir, "ontology", "facts", `@${key}`)))
+            prefixes.push(`ontology/facts/@${key}/`);
+        const sources = path.join(companyDir, "sources");
+        if (fs.existsSync(sources)) {
+            for (const channel of fs.readdirSync(sources).sort(byteSort)) {
+                if (fs.existsSync(path.join(sources, channel, `@${key}`)))
+                    prefixes.push(`sources/${channel}/@${key}/`);
+            }
+        }
+        for (const who of principals) {
+            if (!/^prs_|^agt_/.test(who) && !members.split("\n").includes(who)) {
+                stderr += `skip ${who} (not a member of ${company})\n`;
+                skipped += 1;
+                continue;
+            }
+            for (const prefix of prefixes)
+                grant(prefix, who);
+        }
+    }
+    if (fs.existsSync(path.join(companyDir, "ontology", "facts", "@company")))
+        grant("ontology/facts/@company/", "@all");
+    for (const type of ["action_item", "commitment", "decision", "risk", "question", "key_point", "participant_contribution", "summary"]) {
+        if (fs.existsSync(path.join(signalDir, type)))
+            grant(`signals/${type}/`, "@all");
+    }
+    stdout += `audience grants for ${company}: ${granted} granted, ${skipped} skipped, ${failed} failed\n`;
+    return { code: failed === 0 ? 0 : 3, stdout, stderr };
+}
+function itemList(file, field) {
+    if (!fs.existsSync(file))
+        return [];
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    let frontmatterLines = 0;
+    let inList = false;
+    const output = [];
+    for (const line of lines) {
+        if (line === "---") {
+            frontmatterLines += 1;
+            if (frontmatterLines === 2)
+                break;
+            continue;
+        }
+        if (frontmatterLines !== 1)
+            continue;
+        if (line.startsWith(`${field}:`)) {
+            let value = line.slice(field.length + 1).replace(/^[\t ]+/, "");
+            if (value.startsWith("[")) {
+                value = value.replaceAll("[", "").replaceAll("]", "").replaceAll('"', "").replaceAll("'", "");
+                for (const item of value.split(",")) {
+                    const trimmed = item.replace(/^[\t ]+|[\t ]+$/g, "");
+                    if (trimmed)
+                        output.push(trimmed);
+                }
+                break;
+            }
+            inList = true;
+            continue;
+        }
+        if (inList && /^[\t ]*-[\t ]+/.test(line)) {
+            output.push(line.replace(/^[\t ]*-[\t ]+/, "").replace(/["']/g, ""));
+            continue;
+        }
+        if (inList)
+            break;
+    }
+    return output;
+}
+export function worklistCommand(args, root) {
+    let company = "";
+    let channel = "";
+    let limit = "50";
+    let force = false;
+    let doneItem = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const key = args[index];
+        if (key === "--company" || key === "--channel" || key === "--limit" || key === "--mark-done") {
+            if (index + 1 >= args.length) {
+                const line = key === "--mark-done" ? 30 : 29;
+                return err(1, `${resolveBundledAsset(`${ASSET}ontology-source-worklist.sh`)}: line ${line}: $2: unbound variable\n`);
+            }
+            const value = args[++index];
+            if (key === "--company")
+                company = value;
+            else if (key === "--channel")
+                channel = value;
+            else if (key === "--limit")
+                limit = value;
+            else
+                doneItem = value;
+        }
+        else if (key === "--force")
+            force = true;
+        else
+            return err(2, `unknown flag ${key}\n`);
+    }
+    if (!company || !channel)
+        return err(2, "usage: ontology-source-worklist.sh --company <co> --channel <ch> [--limit N] [--force] [--mark-done <file>]\n");
+    const directory = path.join(root, "companies", company, "sources", channel);
+    const sourceFile = path.join(directory, "source.yaml");
+    const validation = sourceYamlValidate(sourceFile);
+    if (validation.code !== 0)
+        return err(2, `${validation.stderr}${validation.stdout}${validation.stderr}`);
+    const ledger = path.join(directory, ".processed");
+    if (doneItem) {
+        fs.appendFileSync(ledger, `${path.basename(doneItem)}\n`);
+        return ok();
+    }
+    const run = awkField(sourceFile, "run", false);
+    const rule = awkField(sourceFile, "audience_rule", false);
+    if (run === "cloud" && !force)
+        return err(4, "assigned to cloud agent (run: cloud); pass --force to run locally\n");
+    const processed = fs.existsSync(ledger) ? fs.readFileSync(ledger, "utf8").split("\n") : [];
+    const entries = fs.existsSync(directory)
+        ? fs.readdirSync(directory).filter((name) => name.endsWith(".md") && !name.startsWith("."))
+            .filter((name) => { try {
+            return fs.statSync(path.join(directory, name)).isFile();
+        }
+        catch {
+            return false;
+        } })
+            .sort(byteSort)
+        : [];
+    const output = [];
+    let count = 0;
+    for (const name of entries) {
+        if (processed.includes(name))
+            continue;
+        if (/^[+-]?\d+$/.test(limit) && count >= Number(limit))
+            break;
+        if (!/^[+-]?\d+$/.test(limit)) {
+            process.stderr.write(`${resolveBundledAsset(`${ASSET}ontology-source-worklist.sh`)}: line 61: [: ${limit}: integer expression expected\n`);
+        }
+        count += 1;
+        const file = path.join(directory, name);
+        const relative = `sources/${channel}/${name}`;
+        let audience;
+        if (rule === "company")
+            audience = "company";
+        else if (rule === "explicit")
+            audience = itemList(file, "audience").join(",");
+        else {
+            audience = itemList(file, "audience").join(",");
+            if (!audience)
+                audience = itemList(file, "attendees").filter((value) => /@|^(prs|agt)_/.test(value)).join(",");
+            if (!audience) {
+                const acl = runHq(["files", "--company", company, "acl", relative, "--json"]);
+                try {
+                    const payload = JSON.parse(acl.stdout);
+                    const principals = (payload.direct ?? []).filter((value) => {
+                        if (!value || typeof value !== "object")
+                            return false;
+                        const row = value;
+                        return ["person", "email", "agent"].includes(String(row.granteeType))
+                            && ["read", "write", "admin"].includes(String(row.permission));
+                    }).map((value) => String(value.granteeId ?? "")).sort(byteSort);
+                    audience = [...new Set(principals)].join(",");
+                }
+                catch (parseError) {
+                    // jq emits no stdout or stderr for malformed ACL JSON in this pipeline.
+                    void parseError;
+                }
+            }
+        }
+        if (!audience) {
+            output.push(`${JSON.stringify({ file: relative, skip: "no-audience" })}\n`);
+            continue;
+        }
+        const key = shellSubstitution(audienceKey(audience).stdout);
+        output.push(`${JSON.stringify({ file: relative, audience_key: key, audience: audience.split(",") })}\n`);
+    }
+    return ok(output.join(""));
+}
+export function registerCoreOntologyNativeCommands(ontology, rootFor) {
+    const entries = [
+        { name: "audience-grant", summary: "Grant scoped ontology audiences and verify each grant", asset: "ontology-audience-grant.sh", root: "live", run: audienceGrant },
+        { name: "brief", summary: "Render the local ontology company brief", asset: "ontology-brief.mjs", root: "live", run: (args, root) => briefCommand(args, root) },
+        { name: "candidate", summary: "Write a deterministic ontology candidate", asset: "ontology-candidate.sh", root: "live", run: candidateCommand },
+        { name: "garden", summary: "Promote local ontology candidates", asset: "ontology-garden.mjs", root: "live", run: (args, root) => gardenCommand(args, root) },
+        { name: "source-worklist", summary: "List unprocessed source items and their audience", asset: "ontology-source-worklist.sh", root: "live", run: worklistCommand },
+        { name: "source-yaml-validate", summary: "Validate a source.yaml file", asset: "source-yaml-validate.sh", root: "cwd", run: (args) => sourceYamlValidate(args[0]) },
+    ];
+    const rawArgv = process.argv.slice(2);
+    const coreIndex = rawArgv.indexOf("core");
+    const ontologyIndex = rawArgv.indexOf("ontology", coreIndex + 1);
+    const requestedLeaf = rawArgv[ontologyIndex + 1];
+    const leafIndex = ontologyIndex + 1;
+    const rootArgIndex = rawArgv.indexOf("--hq-root", leafIndex + 1);
+    const rootArgValue = rootArgIndex >= 0 ? rawArgv[rootArgIndex + 1] : undefined;
+    if (entries.some((entry) => entry.name === requestedLeaf) && rootArgIndex >= 0
+        && (!rootArgValue || rootArgValue.startsWith("-"))) {
+        // `core --hq-root <path>` is a required parent option. Once one of these
+        // script commands has started, the same spelling belongs to the script's
+        // own argv and may intentionally have no value. Let the leaf reproduce the
+        // old script's parser instead of Commander rejecting it first.
+        const rootOption = ontology.parent?.options.find((option) => option.long === "--hq-root");
+        if (rootOption) {
+            rootOption.required = false;
+            rootOption.optional = true;
+        }
+    }
+    for (const entry of entries) {
+        const command = ontology.command(entry.name)
+            .description(entry.summary)
+            .enablePositionalOptions()
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument("[args...]", "arguments accepted for shell ABI compatibility")
+            .action(async (args = [], _options, commandContext) => {
+            const argv = process.argv.slice(2);
+            const coreIndex = argv.indexOf("core");
+            const ontologyIndex = argv.indexOf("ontology", coreIndex + 1);
+            const commandIndex = argv.indexOf(entry.name, ontologyIndex + 1);
+            const forwarded = commandIndex >= 0 ? argv.slice(commandIndex + 1)
+                : commandContext.args.length > 0 ? commandContext.args : args;
+            const liveRoot = entry.root === "live" ? rootFor() : process.cwd();
+            const { resolveProcessFlagGate } = await import("../lib/flag-registry.js");
+            if (!resolveProcessFlagGate(FLAG, { fallback: false }, () => false)) {
+                const result = runBundledScript({
+                    asset: `${ASSET}${entry.asset}`,
+                    args: forwarded,
+                    cwd: process.cwd(),
+                    ...(entry.root === "live" ? { hqRoot: liveRoot } : {}),
+                });
+                if (result.code !== 0)
+                    process.exitCode = result.code;
+                return;
+            }
+            writeResult(entry.run(forwarded, entry.root === "live" ? liveRoot : process.cwd()));
+        });
+        describeCoreCommand(command, { execution: "native", asset: `${ASSET}${entry.asset}`, root: entry.root });
+    }
+}
+//# sourceMappingURL=core-ontology-native.js.map