@indigoai-us/hq-cli 5.201.4 → 5.202.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.202.0] — 2026-09-26
+
+### Added
+
+- Behind the off-by-default checkpoint.ontology.company-brief flag, the checkpoint ontology plan writes company-brief.md from the local entities, signals and source index, with no model call; recent signals are dated through their source.
+
 ## [5.201.4] — 2026-09-25
 
 ### Fixed

package/dist/commands/core-ontology.js

@@ -44,6 +44,11 @@ function requireRunDir(runDir) {
 export const registryFlagReader = (flagKey, company) => readLanesRegistryFlag(flagKey, {
     company: company.cloudUid ? { slug: company.slug, uid: company.cloudUid } : null,
 });
+function companyBriefSuffix(brief) {
+    if (!brief)
+        return "";
+    return `; company brief ${brief.status}${brief.reason ? ` (${brief.reason})` : ""}`;
+}
 export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
     const runDir = requireRunDir(runDirOption);
     const outcome = await planOntologyRun({
@@ -53,11 +58,13 @@ export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
         readFlag: deps.readFlag ?? registryFlagReader,
         now: deps.now?.(),
     });
-    if (outcome.status === "skipped")
-        return `ontology: skipped (${outcome.reason})`;
+    if (outcome.status === "skipped") {
+        return `ontology: skipped (${outcome.reason})${companyBriefSuffix(outcome.companyBrief)}`;
+    }
     const { plan } = outcome;
     return (`ontology: planned ${plan.inputs.length} input(s), ~${plan.budget.planned_tokens} tokens, ` +
-        `${plan.pending_after_run} left for later runs; plan at ${outcome.planPath}`);
+        `${plan.pending_after_run} left for later runs; plan at ${outcome.planPath}` +
+        companyBriefSuffix(outcome.companyBrief));
 }
 export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
     const runDir = requireRunDir(runDirOption);
@@ -70,7 +77,8 @@ export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
         return `ontology: ${report.status.replaceAll("_", " ")}; nothing written`;
     return (`ontology: ${report.created.length} created, ${report.updated.length} updated, ` +
         `${report.matched} matched, ${report.rejected.length} rejected, ${report.deferred.length} deferred, ` +
-        `${report.suspect_duplicates.length} suspect duplicate(s), ${report.write_errors.length} write error(s)`);
+        `${report.suspect_duplicates.length} suspect duplicate(s), ${report.write_errors.length} write error(s)` +
+        companyBriefSuffix(report.company_brief));
 }
 function fail(error) {
     if (error instanceof OntologyUsageError || error instanceof ApplyError || error instanceof WriteBoundsError) {

package/dist/lib/checkpoint-ontology/apply.d.ts

@@ -5,6 +5,7 @@
  * sections 4.3, 5 and 14). The model output is untrusted input: a malformed
  * candidate is rejected and counted, never repaired.
  */
+import { type CompanyBriefResult } from "./company-brief.js";
 import { type WritableEntityType } from "./identity.js";
 import { type EntityIndex } from "./tree.js";
 export declare const CAPS: {
@@ -73,6 +74,8 @@ export interface ApplyReport {
         path: string;
         reason: string;
     }>;
+    /** Present only when the plan ran the company brief and this apply created or updated entities. */
+    company_brief?: CompanyBriefResult;
     duration_ms: number;
 }
 export interface ApplyOptions {

package/dist/lib/checkpoint-ontology/apply.js

@@ -8,6 +8,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writeCompanyBrief } from "./company-brief.js";
 import { entitiesRoot, resolveOntologyCompany, safeWriteFile } from "./company.js";
 import { appendBackRefs, parseEntityFile, patchEntityFile, previewSignalContent, renderNewEntity, validateEntityFrontmatter, } from "./entity-file.js";
 import { canonicalizeName, entityId, isRejectedName, isWritableEntityType, normalizeEntityName, squash, toSlug, } from "./identity.js";
@@ -438,6 +439,10 @@ export function applyOntologyRun(options) {
             report.updated.push(rel);
     }
     commitLedger(options.hqRoot, company, plan, inputs, blocked, report);
+    // The plan rendered the brief before these entity writes; render it again so it matches them.
+    if (plan.company_brief && report.created.length + report.updated.length > 0) {
+        report.company_brief = writeCompanyBrief(options.hqRoot, company, options.now ?? new Date());
+    }
     return finish();
 }
 let signalRefIndex = null;

package/dist/lib/checkpoint-ontology/company-brief.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Deterministic `company-brief.md` for one company.
+ *
+ * The cloud gardener used to write this file. The checkpoint renders the same
+ * shape from the local ontology with no model call. Signal dates come from
+ * `sources/_index`, because signal files have no `created_at`.
+ */
+import { type OntologyCompany } from "./company.js";
+export declare const COMPANY_BRIEF_FILE = "company-brief.md";
+export interface CompanyBriefResult {
+    status: "written" | "unchanged" | "skipped" | "failed";
+    /** Set for skipped and failed. */
+    reason?: string;
+}
+/** `null` when fewer than three valid person, project, company, or concept entities exist. */
+export declare function renderCompanyBrief(company: OntologyCompany, now: Date): string | null;
+export declare function writeCompanyBrief(hqRoot: string, company: OntologyCompany, now: Date): CompanyBriefResult;
+//# sourceMappingURL=company-brief.d.ts.map

package/dist/lib/checkpoint-ontology/company-brief.js

@@ -0,0 +1,337 @@
+/**
+ * Deterministic `company-brief.md` for one company.
+ *
+ * The cloud gardener used to write this file. The checkpoint renders the same
+ * shape from the local ontology with no model call. Signal dates come from
+ * `sources/_index`, because signal files have no `created_at`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { safeWriteFile, WriteBoundsError } from "./company.js";
+import { parseEntityFile, validateEntityFrontmatter } from "./entity-file.js";
+export const COMPANY_BRIEF_FILE = "company-brief.md";
+const SIGNAL_TYPES = [
+    { dir: "decision", heading: "Decisions" },
+    { dir: "risk", heading: "Risks" },
+    { dir: "question", heading: "Questions" },
+];
+const ENTITY_TYPES = [
+    { dir: "person", heading: "People" },
+    { dir: "project", heading: "Projects" },
+    { dir: "company", heading: "Companies" },
+    { dir: "concept", heading: "Concepts" },
+];
+const CHANNELS = [
+    { id: "meeting", label: "Meeting" },
+    { id: "email", label: "Email" },
+    { id: "slack", label: "Slack" },
+    { id: "slack-dm", label: "Slack DM" },
+    { id: "linear", label: "Linear" },
+    { id: "notion", label: "Notion" },
+];
+const NO_SOURCES = "<!-- source channels: no sources/_index entries in last 7d -->";
+const SIGNAL_PREVIEW_MAX = 160;
+const SIGNAL_TOP = 5;
+const ENTITY_TOP = 8;
+/** Cloud budget: `floor(2000 * 0.4)` reserved tokens, minus the source block. */
+const SIGNAL_TOKEN_RESERVE = Math.floor(2000 * 0.4);
+const MIN_ENTITIES = 3;
+function byCodeUnit(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+function tokenCount(text) {
+    return Math.ceil(text.length / 4);
+}
+/** UTC dates `now`, `now − 1 day`, … from the epoch day, not the local calendar. */
+function windowDates(now) {
+    const day = Math.floor(now.getTime() / 86_400_000);
+    const dates = [];
+    for (let i = 0; i < 7; i += 1)
+        dates.push(new Date((day - i) * 86_400_000).toISOString().slice(0, 10));
+    return dates;
+}
+/**
+ * `false` when `dir` does not exist. Throws when it resolves outside the company:
+ * a symlinked directory would otherwise copy another company's files into this brief.
+ */
+function readableInside(companyDir, dir) {
+    let real;
+    try {
+        real = fs.realpathSync(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    const relative = path.relative(fs.realpathSync(companyDir), real);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new WriteBoundsError(`${path.relative(companyDir, dir)} resolves outside the company`);
+    }
+    return true;
+}
+function listDirectMd(companyDir, dir) {
+    if (!readableInside(companyDir, dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const names = [];
+    for (const entry of entries) {
+        // Files only. A directory whose name starts with `@` or `_` is never entered.
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        names.push(entry.name);
+    }
+    names.sort(byCodeUnit);
+    return names;
+}
+/** `null` when the file is missing, unparsable, or not a JSON array. */
+function readIndexArray(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+function indexKey(entry) {
+    const keys = entry.keys;
+    const markdown = keys && typeof keys === "object" && !Array.isArray(keys)
+        ? keys.markdown
+        : undefined;
+    if (typeof markdown === "string" && markdown.length > 0)
+        return markdown;
+    const sourceRef = entry.source_ref;
+    const fallback = sourceRef && typeof sourceRef === "object" && !Array.isArray(sourceRef)
+        ? sourceRef.key
+        : undefined;
+    return typeof fallback === "string" && fallback.length > 0 ? fallback : null;
+}
+function mapChannel(value) {
+    if (value === "meeting" || value === "meetings")
+        return "meeting";
+    if (value === "email" || value === "slack" || value === "slack-dm" || value === "linear" || value === "notion") {
+        return value;
+    }
+    return null;
+}
+function loadSources(companyDir, now) {
+    const times = new Map();
+    const counts = new Map();
+    const dir = path.join(companyDir, "sources", "_index");
+    // Regular files only: a symlinked index file could point at another company's index.
+    const names = readableInside(companyDir, dir)
+        ? fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => entry.name)
+            .sort(byCodeUnit)
+        : [];
+    const windowFiles = new Set(windowDates(now).map((date) => `${date}.json`));
+    for (const name of names) {
+        const entries = readIndexArray(path.join(dir, name));
+        if (!entries)
+            continue;
+        const inWindow = windowFiles.has(name);
+        for (const entry of entries) {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const record = entry;
+            const key = indexKey(record);
+            if (key && typeof record.written_at === "string")
+                times.set(key, record.written_at);
+            if (!inWindow)
+                continue;
+            const channel = mapChannel(record.channel);
+            if (channel)
+                counts.set(channel, (counts.get(channel) ?? 0) + 1);
+        }
+    }
+    return { times, counts };
+}
+function loadSignals(companyDir, times) {
+    const items = [];
+    for (const type of SIGNAL_TYPES) {
+        const dir = path.join(companyDir, "signals", type.dir);
+        for (const name of listDirectMd(companyDir, dir)) {
+            const parsed = parseEntityFile(fs.readFileSync(path.join(dir, name), "utf8"));
+            if (!parsed)
+                continue;
+            const content = parsed.frontmatter.canonical_content;
+            if (typeof content !== "string" || content.length === 0)
+                continue;
+            const sourceRef = parsed.frontmatter.source_ref;
+            const time = typeof sourceRef === "string" ? times.get(sourceRef) ?? null : null;
+            items.push({ type: type.dir, rel: `signals/${type.dir}/${name}`, content, time });
+        }
+    }
+    return items;
+}
+function compareSignals(a, b) {
+    if (a.time !== null && b.time !== null) {
+        if (a.time !== b.time)
+            return a.time < b.time ? 1 : -1;
+    }
+    else if (a.time !== b.time) {
+        return a.time === null ? 1 : -1;
+    }
+    if (a.rel !== b.rel)
+        return a.rel < b.rel ? 1 : -1;
+    return 0;
+}
+function previewContent(content) {
+    const collapsed = content.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= SIGNAL_PREVIEW_MAX)
+        return collapsed;
+    return `${collapsed.slice(0, SIGNAL_PREVIEW_MAX).trimEnd()}…`;
+}
+function renderSignalBlock(items) {
+    const sections = [];
+    for (const type of SIGNAL_TYPES) {
+        const rows = items.filter((item) => item.type === type.dir);
+        if (rows.length === 0)
+            continue;
+        const lines = rows.map((item) => {
+            const base = `- [${previewContent(item.content)}](${item.rel})`;
+            return item.time ? `${base} _(${item.time.slice(0, 10)})_` : base;
+        });
+        sections.push(`### ${type.heading}\n${lines.join("\n")}`);
+    }
+    if (sections.length === 0)
+        return null;
+    return ["## Recent Signals", ...sections].join("\n\n").trimEnd();
+}
+function confidenceOf(frontmatter) {
+    const value = frontmatter.confidence;
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : 0;
+}
+function compareEntities(a, b) {
+    if (a.score !== b.score)
+        return b.score - a.score;
+    if (a.name !== b.name)
+        return a.name < b.name ? -1 : 1;
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    return 0;
+}
+function loadEntities(companyDir) {
+    let total = 0;
+    const groups = [];
+    for (const type of ENTITY_TYPES) {
+        const dir = path.join(companyDir, "ontology", "entities", type.dir);
+        const items = [];
+        for (const name of listDirectMd(companyDir, dir)) {
+            const parsed = parseEntityFile(fs.readFileSync(path.join(dir, name), "utf8"));
+            if (!parsed)
+                continue;
+            const valid = validateEntityFrontmatter(parsed.frontmatter);
+            if (typeof valid === "string")
+                continue;
+            items.push({
+                file: name,
+                name: valid.canonical_name,
+                signalCount: valid.signal_count,
+                score: valid.signal_count * confidenceOf(parsed.frontmatter),
+            });
+        }
+        total += items.length;
+        items.sort(compareEntities);
+        groups.push({
+            heading: type.heading,
+            lines: items.slice(0, ENTITY_TOP).map((item) => `- [${item.name}](ontology/entities/${type.dir}/${item.file}) (${item.signalCount} signals)`),
+        });
+    }
+    return { total, groups };
+}
+function renderEntityBlock(slug, groups) {
+    const parts = [
+        `# ${slug} company brief`,
+        "_Rendered by hq core checkpoint from the local ontology._",
+        "## Key Entities",
+    ];
+    for (const group of groups) {
+        if (group.lines.length === 0)
+            continue;
+        parts.push(`### ${group.heading}\n${group.lines.join("\n")}`);
+    }
+    return parts.join("\n\n");
+}
+function renderSourceBlock(counts) {
+    const total = CHANNELS.reduce((sum, channel) => sum + (counts.get(channel.id) ?? 0), 0);
+    if (total === 0)
+        return NO_SOURCES;
+    const rows = CHANNELS.map((channel) => `| ${channel.label} | ${counts.get(channel.id) ?? 0} |`);
+    return ["## Source Channels", "", "_Last 7 days_", "", "| Channel | Count |", "| --- | ---: |", ...rows].join("\n");
+}
+function fitSignals(ranked, budget) {
+    const kept = ranked.slice();
+    while (kept.length > 0) {
+        const block = renderSignalBlock(kept);
+        if (block === null || tokenCount(block) <= budget)
+            break;
+        kept.pop();
+    }
+    return kept;
+}
+/** `null` when fewer than three valid person, project, company, or concept entities exist. */
+export function renderCompanyBrief(company, now) {
+    const entities = loadEntities(company.dir);
+    if (entities.total < MIN_ENTITIES)
+        return null;
+    const sources = loadSources(company.dir, now);
+    const signals = loadSignals(company.dir, sources.times);
+    const ranked = [];
+    for (const type of SIGNAL_TYPES) {
+        ranked.push(...signals.filter((item) => item.type === type.dir).sort(compareSignals).slice(0, SIGNAL_TOP));
+    }
+    const sourceBlock = renderSourceBlock(sources.counts);
+    const budget = Math.max(0, SIGNAL_TOKEN_RESERVE - tokenCount(sourceBlock));
+    const signalBlock = renderSignalBlock(fitSignals(ranked, budget));
+    const blocks = [renderEntityBlock(company.slug, entities.groups)];
+    if (signalBlock)
+        blocks.push(signalBlock);
+    blocks.push(sourceBlock);
+    return `${blocks.join("\n\n")}\n`;
+}
+export function writeCompanyBrief(hqRoot, company, now) {
+    try {
+        const content = renderCompanyBrief(company, now);
+        if (content === null)
+            return { status: "skipped", reason: "fewer than 3 entities" };
+        const target = path.join(company.dir, COMPANY_BRIEF_FILE);
+        let existing = null;
+        try {
+            // Never follow a symlinked brief for the equality check; safeWriteFile rejects it below.
+            if (!fs.lstatSync(target).isSymbolicLink())
+                existing = fs.readFileSync(target);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (existing && existing.equals(Buffer.from(content, "utf8")))
+            return { status: "unchanged" };
+        safeWriteFile(hqRoot, [company.dir], target, content);
+        return { status: "written" };
+    }
+    catch (error) {
+        const failed = error;
+        return { status: "failed", reason: `${failed.name}: ${failed.message}` };
+    }
+}
+//# sourceMappingURL=company-brief.js.map

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -7,9 +7,11 @@
  * backend model to read. The model only fills a candidates file; everything
  * that affects identity, scope and cost stays in code.
  */
+import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 export declare const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
+export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -66,6 +68,11 @@ export interface OntologyPlan {
     first_run: boolean;
     boundary: string | null;
     shared_inputs: boolean;
+    /** Present only when `checkpoint.ontology.company-brief` was on for this plan. */
+    company_brief?: {
+        status: CompanyBriefResult["status"];
+        reason?: string;
+    };
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;
@@ -98,10 +105,12 @@ export interface PlanOptions {
 export type PlanOutcome = {
     status: "skipped";
     reason: string;
+    companyBrief?: CompanyBriefResult;
 } | {
     status: "planned";
     plan: OntologyPlan;
     planPath: string;
+    companyBrief?: CompanyBriefResult;
 };
 export declare function ledgerPath(hqRoot: string, company: OntologyCompany): string;
 export declare function readLedger(hqRoot: string, company: OntologyCompany): Ledger | null;

package/dist/lib/checkpoint-ontology/plan.js

@@ -10,10 +10,12 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
 export const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
+export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -173,6 +175,10 @@ export async function planOntologyRun(options) {
     if (!(await options.readFlag(ONTOLOGY_FLAG, company)))
         return { status: "skipped", reason: "flag off" };
     const sharedInputs = await options.readFlag(SHARED_INPUTS_FLAG, company);
+    // Before the ledger, so a nothing-changed plan still records the brief.
+    const companyBrief = (await options.readFlag(COMPANY_BRIEF_FLAG, company))
+        ? writeCompanyBrief(hqRoot, company, options.now ?? new Date())
+        : undefined;
     const touched = sessionTouched(hqRoot, company, payload.files);
     const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched, sharedInputs);
     const pending = Object.entries(ledger.entries)
@@ -214,7 +220,8 @@ export async function planOntologyRun(options) {
     }
     writeLedger(hqRoot, company, ledger);
     if (inputs.length === 0) {
-        return { status: "skipped", reason: pending.length > 0 ? "over budget" : "nothing changed" };
+        const reason = pending.length > 0 ? "over budget" : "nothing changed";
+        return companyBrief ? { status: "skipped", reason, companyBrief } : { status: "skipped", reason };
     }
     // Session content is scoped to the session's user (design section 6, D2).
     // v1 records the existing entities it names as links in the report and
@@ -243,6 +250,13 @@ export async function planOntologyRun(options) {
         first_run: firstRun,
         boundary: ledger.boundary,
         shared_inputs: sharedInputs,
+        ...(companyBrief
+            ? {
+                company_brief: companyBrief.reason
+                    ? { status: companyBrief.status, reason: companyBrief.reason }
+                    : { status: companyBrief.status },
+            }
+            : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,
@@ -258,7 +272,7 @@ export async function planOntologyRun(options) {
     fs.mkdirSync(runDir, { recursive: true });
     const planPath = path.join(runDir, PLAN_FILE);
     fs.writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
-    return { status: "planned", plan, planPath };
+    return companyBrief ? { status: "planned", plan, planPath, companyBrief } : { status: "planned", plan, planPath };
 }
 const SESSION_TEXT_MAX_BYTES = 8_000;
 /** The session summary, decisions and learnings from the payload, capped. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.201.4",
+  "version": "5.202.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {