agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/analytics/usageStats.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { resolveProfileDirOverride, resolveXdgDataHome } from "../core/envPaths.js";
+import { expanduser } from "../core/paths.js";
+import { tiersDirForCorpusPath, assessTiers, iterBoundedRecords, readTierCorpusMetadata } from "./extractCorpus/index.js";
 export const EXIT_STATUSES = new Set(["complete", "flagged", "stuck", "waiting"]);
 export const TRIGGER_SLASH = "slash";
 export const TRIGGER_NATURAL = "natural";
-const MARKER_RE = /─{2,}\s+(\S)\s+([a-z]+era)\s+·\s+([a-z]+(?:\s+\d+)?)\s+─{2,}/g;
+const MARKER_RE = /─{2,}\s+(\S)\s+(status|vision|discuss|research|plan|build|optimize|audit|document|profile|design|orchestrate)\s+·\s+([a-z]+(?:\s+\d+)?)\s+─{2,}/g;
 function newInvocation(init) {
     return {
         skill: init.skill,
@@ -18,6 +21,9 @@ function newInvocation(init) {
         exit_timestamp: init.exit_timestamp ?? null,
         trigger: init.trigger ?? TRIGGER_NATURAL,
         project_id: init.project_id ?? "",
+        source_class: init.source_class ?? "active_runtime",
+        source_product: init.source_product ?? "unknown",
+        active_runtime: init.active_runtime ?? true,
     };
 }
 export function findMarkers(text) {
@@ -101,7 +107,7 @@ export function pairInvocations(turns) {
     for (const turn of turns) {
         const sid = String(turn.source_id ?? "");
         const ts = String(turn.timestamp ?? "");
-        const text = (isMapping(turn.data) ? turn.data.content : "") || "";
+        const text = ((isMapping(turn.data) ? turn.data.content : "") || ""); // cast: corpus record content from JSON.parse IO boundary
         for (const marker of findMarkers(text)) {
             if (marker.kind === "intro") {
                 if (!pending.has(marker.skill))
@@ -113,6 +119,9 @@ export function pairInvocations(turns) {
                     intro_source_id: sid,
                     intro_timestamp: ts,
                     completed: false,
+                    source_class: String(turn.source_class ?? "active_runtime"),
+                    source_product: String(turn.source_product ?? turn.runtime ?? "unknown"),
+                    active_runtime: turn.active_runtime !== false && turn.source_class !== "historical_import",
                 }));
             }
             else {
@@ -150,12 +159,13 @@ function stableSort(items, key) {
     })
         .map(([item]) => item);
 }
-const CLAUDE_CODE_XML_RE = /<command-name>\s*\/[A-Za-z0-9._:-]+\s*<\/command-name>/;
+// Retained only to classify command markup in consent-gated historical imports.
+const HISTORICAL_COMMAND_XML_RE = /<command-name>\s*\/[A-Za-z0-9._:-]+\s*<\/command-name>/;
 const BARE_SLASH_RE = /^\s*\/[A-Za-z0-9._:-]+(?:\s|$)/m;
 export function classifyTrigger(userTurnText) {
     if (!userTurnText)
         return TRIGGER_NATURAL;
-    if (CLAUDE_CODE_XML_RE.test(userTurnText))
+    if (HISTORICAL_COMMAND_XML_RE.test(userTurnText))
         return TRIGGER_SLASH;
     if (BARE_SLASH_RE.test(userTurnText))
         return TRIGGER_SLASH;
@@ -226,13 +236,70 @@ function accumulate(bucket, inv) {
     bucket[inv.completed ? "completed" : "incomplete"] += 1;
     bucket[inv.trigger === TRIGGER_SLASH ? "trigger_slash" : "trigger_natural"] += 1;
 }
-export function analyzeCorpus(corpus, projectFilter = null) {
-    const rawRecords = isMapping(corpus) ? (corpus.records ?? []) : [];
-    const records = filterRecordsByProject(rawRecords, projectFilter);
-    const userTurnsByConv = userTurnsByConversation(records);
-    const grouped = groupByConversation(records);
+function activeAnalyticsRecord(record) {
+    if (record.active_runtime === false || record.source_class === "historical_import")
+        return false;
+    return record.runtime !== "claude" && record.runtime !== "claude-code";
+}
+export function analyzeCorpus(corpus, projectFilter = null, sourceView = "active") {
+    const rawRecords = (isMapping(corpus) ? (corpus.records ?? []) : []); // cast: corpus records from JSON.parse IO boundary
+    return analyzeRecords(rawRecords, projectFilter, sourceView);
+}
+/**
+ * Single-pass analysis over a record iterable. Bounded consumers feed the
+ * tiered shard iterator here so non-conversation records (instruction documents,
+ * project config signals, tool calls) are counted for provenance and discarded
+ * rather than materialized; only conversation turns are retained as the analysis
+ * working set. Mirrors `analyzeCorpus` exactly when given the full record array.
+ */
+export function analyzeRecords(records, projectFilter = null, sourceView = "active") {
+    const provenanceCounts = new Map();
+    const userTurnsByConv = new Map();
+    const assistantByConv = new Map();
+    for (const record of records) {
+        if (!isMapping(record))
+            continue;
+        const isActive = activeAnalyticsRecord(record);
+        if (sourceView === "active" && !isActive)
+            continue;
+        if (projectFilter !== null) {
+            const pid = record.project_id ?? "";
+            if (!(typeof pid === "string" && projectMatch(pid, projectFilter)))
+                continue;
+        }
+        const sourceClass = String(record.source_class ?? (isActive ? "active_runtime" : "historical_import"));
+        const sourceProduct = String(record.source_product ?? record.runtime ?? "unknown");
+        const activeRuntime = isActive;
+        const key = `${sourceClass}\0${sourceProduct}\0${activeRuntime}`;
+        const current = provenanceCounts.get(key) ?? { source_class: sourceClass, source_product: sourceProduct, active_runtime: activeRuntime, records: 0 };
+        current.records += 1;
+        provenanceCounts.set(key, current);
+        if (record.source_kind !== "conversation_turn")
+            continue;
+        const data = record.data;
+        if (!isMapping(data))
+            continue;
+        const ckey = conversationKey(record);
+        if (ckey === null)
+            continue;
+        const actor = data.actor;
+        if (actor === "user") {
+            if (!userTurnsByConv.has(ckey))
+                userTurnsByConv.set(ckey, []);
+            userTurnsByConv.get(ckey).push(record);
+        }
+        else if (actor === "assistant") {
+            if (!assistantByConv.has(ckey))
+                assistantByConv.set(ckey, []);
+            assistantByConv.get(ckey).push(record);
+        }
+    }
+    for (const items of userTurnsByConv.values())
+        stableSortByTimestamp(items);
+    for (const items of assistantByConv.values())
+        stableSortByTimestamp(items);
     const invocations = [];
-    for (const [sid, turns] of grouped) {
+    for (const [sid, turns] of assistantByConv) {
         const tsToProject = new Map();
         for (const t of turns) {
             tsToProject.set(String(t.timestamp ?? ""), String(t.project_id ?? ""));
@@ -243,7 +310,7 @@ export function analyzeCorpus(corpus, projectFilter = null) {
             let precedingText = "";
             if (preceding !== null) {
                 const data = isMapping(preceding.data) ? preceding.data : {};
-                precedingText = data.content || "";
+                precedingText = (data.content || ""); // cast: corpus record content from JSON.parse IO boundary
             }
             inv.trigger = classifyTrigger(precedingText);
             invocations.push(inv);
@@ -264,34 +331,40 @@ export function analyzeCorpus(corpus, projectFilter = null) {
             accumulate(perProject[inv.project_id][inv.skill], inv);
         }
     }
-    return { invocations: sorted, skills, project_filter: projectFilter, per_project: perProject };
+    return {
+        invocations: sorted,
+        skills,
+        project_filter: projectFilter,
+        per_project: perProject,
+        source_view: sourceView,
+        source_provenance: [...provenanceCounts.values()].sort((a, b) => `${a.source_class}:${a.source_product}`.localeCompare(`${b.source_class}:${b.source_product}`)),
+    };
 }
 // --- Paths -----------------------------------------------------------------
-export const CORPUS_GUIDANCE = "Provide --corpus <path> to an existing corpus.json.";
+export const CORPUS_GUIDANCE = "Publish bounded tiers with `agentera stats refresh --consent local-history`; `--corpus PATH` points at a legacy corpus.json whose sibling `tiers/` is preferred when published.";
 function homeDir(env) {
     return env.HOME ?? os.homedir();
 }
 export function defaultUsageDir(env = process.env, platform = process.platform) {
     const override = env.AGENTERA_USAGE_DIR;
     if (override)
-        return override;
-    const profileraOverride = env.PROFILERA_PROFILE_DIR;
-    if (profileraOverride)
-        return profileraOverride;
+        return expanduser(override);
+    const profileOverride = resolveProfileDirOverride(env);
+    if (profileOverride)
+        return expanduser(profileOverride);
     const home = homeDir(env);
     if (platform === "darwin")
         return path.join(home, "Library", "Application Support", "agentera");
     if (platform === "win32") {
         const appdata = env.APPDATA ?? path.join(home, "AppData", "Roaming");
-        return path.join(appdata, "agentera");
+        return path.join(expanduser(appdata), "agentera");
     }
-    const xdg = env.XDG_DATA_HOME ?? path.join(home, ".local", "share");
-    return path.join(xdg, "agentera");
+    return path.join(resolveXdgDataHome(env, home), "agentera");
 }
 export function defaultCorpusPath(env = process.env, platform = process.platform) {
-    const profileraOverride = env.PROFILERA_PROFILE_DIR;
-    if (profileraOverride)
-        return path.join(profileraOverride, "intermediate", "corpus.json");
+    const profileOverride = resolveProfileDirOverride(env);
+    if (profileOverride)
+        return path.join(expanduser(profileOverride), "intermediate", "corpus.json");
     const home = homeDir(env);
     let base;
     if (platform === "darwin") {
@@ -299,11 +372,10 @@ export function defaultCorpusPath(env = process.env, platform = process.platform
     }
     else if (platform === "win32") {
         const appdata = env.APPDATA ?? path.join(home, "AppData", "Roaming");
-        base = path.join(appdata, "agentera");
+        base = path.join(expanduser(appdata), "agentera");
     }
     else {
-        const xdg = env.XDG_DATA_HOME ?? path.join(home, ".local", "share");
-        base = path.join(xdg, "agentera");
+        base = path.join(resolveXdgDataHome(env, home), "agentera");
     }
     return path.join(base, "intermediate", "corpus.json");
 }
@@ -319,7 +391,7 @@ export function corpusTooLargeReason(corpusPath) {
         const size = fs.statSync(corpusPath).size;
         if (size <= MAX_CORPUS_READ_BYTES)
             return null;
-        return `corpus is too large to load (${size} bytes; max ${MAX_CORPUS_READ_BYTES}). Rebuild with agentera report refresh --consent local-history or pass --corpus PATH to a smaller extract.`;
+        return `corpus is too large to load (${size} bytes; max ${MAX_CORPUS_READ_BYTES}). Refresh bounded tiers with agentera stats refresh --consent local-history, or pass --corpus PATH to a smaller legacy extract (its sibling tiers/ is preferred when published).`;
     }
     catch {
         return null;
@@ -340,18 +412,20 @@ export function loadCorpusOrRaise(corpusPath) {
     catch (exc) {
         throw new CorpusUnavailable(`corpus is not readable JSON: ${exc.message}`);
     }
-    const records = isMapping(corpus) ? (corpus.records ?? []) : [];
+    const records = (isMapping(corpus) ? (corpus.records ?? []) : []); // cast: corpus records from JSON.parse IO boundary
     const hasTurn = Array.isArray(records) && records.some((r) => isMapping(r) && r.source_kind === "conversation_turn");
     if (!hasTurn) {
         throw new CorpusUnavailable(`corpus at ${corpusPath} contains no conversation_turn records. ${CORPUS_GUIDANCE}`);
     }
-    return corpus;
+    return corpus; // cast: corpus from JSON.parse IO boundary
 }
 export function buildJsonPayload(analysis, opts) {
     return {
         generated_at: opts.generatedAt,
         extracted_at: opts.extractedAt,
         project_filter: analysis.project_filter,
+        source_view: analysis.source_view,
+        source_provenance: analysis.source_provenance,
         skills: analysis.skills,
         per_project: analysis.per_project,
         invocations: analysis.invocations.map((inv) => ({ ...inv })),
@@ -381,7 +455,10 @@ export function renderMarkdown(analysis, opts) {
     const scope = analysis.project_filter || "all projects";
     const extractedLine = opts.extractedAt || "unknown (corpus omitted extracted_at)";
     const lines = [];
-    lines.push("# Suite Usage", "", `- Generated: ${opts.generatedAt}`, `- Corpus extracted: ${extractedLine}`, `- Scope: ${scope}`, "");
+    lines.push("# Suite Usage", "", `- Generated: ${opts.generatedAt}`, `- Corpus extracted: ${extractedLine}`, `- Scope: ${scope}`, `- Sources: ${analysis.source_view}`, "");
+    if (analysis.source_view === "all") {
+        lines.push("## Source provenance", "", "| Source class | Source product | Active runtime | Records |", "| --- | --- | --- | --- |", ...analysis.source_provenance.map((item) => `| ${item.source_class} | ${item.source_product} | ${item.active_runtime ? "yes" : "no"} | ${item.records} |`), "");
+    }
     if (Object.keys(analysis.skills).length === 0) {
         lines.push("No skill invocations found in the corpus for this scope.", "");
         return lines.join("\n");
@@ -468,6 +545,7 @@ export function usageMain(argv, io = {}) {
     let corpus = null;
     let project = null;
     let emitJson = false;
+    let sourceView = "active";
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--corpus")
@@ -480,23 +558,61 @@ export function usageMain(argv, io = {}) {
             project = a.slice("--project=".length);
         else if (a === "--json")
             emitJson = true;
+        else if (a === "--sources" || a.startsWith("--sources=")) {
+            const value = a === "--sources" ? argv[++i] : a.slice("--sources=".length);
+            if (value !== "active" && value !== "all") {
+                err(`usage_stats: unsupported --sources '${value}'; choose active or all`);
+                return 2;
+            }
+            sourceView = value;
+        }
     }
     const corpusPath = corpus ?? defaultCorpusPath(env, platform);
-    let corpusData;
-    try {
-        corpusData = loadCorpusOrRaise(corpusPath);
-    }
-    catch (e) {
-        if (e instanceof CorpusUnavailable) {
-            err(String(e.message));
+    // Bounded tier path: analyze real-scale evidence by streaming one bounded
+    // shard at a time instead of materializing the monolithic corpus envelope.
+    // Falls back to the legacy corpus.json read only when no tiers were published
+    // (legacy state) so existing small-envelope consumers keep working.
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    let analysis;
+    let extractedAt = null;
+    if (assessment.analyzable) {
+        const records = iterBoundedRecords(tiersDir);
+        if (records === null) {
+            err(tierUnavailableMessage(assessment, corpusPath));
             return 2;
         }
-        throw e;
+        analysis = analyzeRecords(records, project, sourceView);
+        const metadata = readTierCorpusMetadata(tiersDir);
+        extractedAt = metadata?.extracted_at ?? null;
+    }
+    else if (assessment.state === "corrupt" || assessment.state === "oversized") {
+        // Tier-level failure: the published tier is unreadable or a shard exceeds the
+        // reader cap. Project actionable recovery from the authority contract rather
+        // than silently falling back to the corpus envelope.
+        err(tierUnavailableMessage(assessment, corpusPath));
+        return 2;
+    }
+    else {
+        // Legacy or missing: delegate to the corpus-envelope reader, which preserves
+        // the existing too-large / not-found degradation and message contract.
+        let corpusData;
+        try {
+            corpusData = loadCorpusOrRaise(corpusPath);
+        }
+        catch (e) {
+            if (e instanceof CorpusUnavailable) {
+                err(String(e.message));
+                return 2;
+            }
+            throw e;
+        }
+        analysis = analyzeCorpus(corpusData, project, sourceView);
+        const md = corpusData.metadata;
+        extractedAt =
+            md && typeof md === "object" && !Array.isArray(md) ? (md.extracted_at ?? null) : null;
     }
-    const analysis = analyzeCorpus(corpusData, project);
     const generatedAt = nowIso();
-    const md = corpusData.metadata;
-    const extractedAt = md && typeof md === "object" && !Array.isArray(md) ? (md.extracted_at ?? null) : null;
     if (emitJson) {
         out(renderJson(analysis, { generatedAt, extractedAt }));
         return 0;
@@ -506,4 +622,15 @@ export function usageMain(argv, io = {}) {
     out(renderStdoutSummary(analysis, { generatedAt, extractedAt, reportPath: outPath }));
     return 0;
 }
-//# sourceMappingURL=usageStats.js.map
+/** Compose the degrade message for a non-analyzable tier state. */
+function tierUnavailableMessage(assessment, corpusPath) {
+    const recovery = assessment.recovery;
+    const where = `tiers at ${assessment.tiersDir}${corpusPath ? ` (corpus=${corpusPath})` : ""}`;
+    if (assessment.state === "oversized") {
+        return `evidence tier is oversized at ${assessment.artifact ?? where}. ${recovery ?? ""}`.trim();
+    }
+    if (assessment.state === "corrupt") {
+        return `evidence tier is unreadable at ${where}. ${recovery ?? ""}`.trim();
+    }
+    return `evidence tier is ${assessment.state} at ${where}. ${recovery ?? ""}`.trim();
+}

package/dist/audit/terminologyDrift.js

@@ -0,0 +1,281 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { isSafeProjectSourcePath } from "../registries/glossaryEntryContract.js";
+import { unicodeCaselessExact } from "../registries/glossaryTermIdentity.js";
+import { containsGlossaryTerm } from "../registries/glossaryTermOccurrence.js";
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Deterministic variant ordering only; never use this key for term identity. */
+function variantSortKey(term) {
+    return term.toLowerCase();
+}
+function orderedEvidence(evidence) {
+    return [...evidence].sort((left, right) => compareText(left.source_path, right.source_path)
+        || left.line - right.line
+        || compareText(left.source_record_sha256, right.source_record_sha256));
+}
+function evidenceIdentity(item) {
+    return `${item.source_path}:${item.line}`;
+}
+function proposalWithoutDigest(proposal) {
+    const { proposal_digest: _digest, ...finding } = proposal;
+    return {
+        ...finding,
+        canonical_evidence: orderedEvidence(finding.canonical_evidence),
+        variants: finding.variants
+            .map((variant) => ({ ...variant, evidence: orderedEvidence(variant.evidence) }))
+            .sort((left, right) => compareText(variantSortKey(left.term), variantSortKey(right.term))
+            || compareText(left.term, right.term)),
+    };
+}
+export function canonicalTerminologyJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalTerminologyJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => compareText(left, right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalTerminologyJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Digest one complete finding while ignoring semantically irrelevant array order. */
+export function terminologyProposalDigest(proposal) {
+    return crypto
+        .createHash("sha256")
+        .update(canonicalTerminologyJson(proposalWithoutDigest(proposal)))
+        .digest("hex");
+}
+function canonicalProposal(seed) {
+    const ordered = seed.terms
+        .map((term) => ({ term: term.term, evidence: orderedEvidence(term.evidence) }))
+        .sort((left, right) => right.evidence.length - left.evidence.length || compareText(left.term, right.term));
+    const [canonical, ...variants] = ordered;
+    const finding = {
+        family: "terminology_drift",
+        concept: seed.concept,
+        proposed_canonical_term: canonical.term,
+        canonical_evidence: canonical.evidence,
+        variants: variants.sort((left, right) => compareText(variantSortKey(left.term), variantSortKey(right.term))
+            || compareText(left.term, right.term)),
+        severity: seed.confidence < 70 ? "info" : seed.severity,
+        confidence: seed.confidence,
+        ...(seed.personal_divergence ? { personal_divergence: seed.personal_divergence } : {}),
+    };
+    return { ...finding, proposal_digest: terminologyProposalDigest(finding) };
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactFields(value, allowed) {
+    return Object.keys(value).every((field) => allowed.includes(field));
+}
+function proposalEvidence(value, label, violations) {
+    if (!mapping(value) || !exactFields(value, ["source_path", "line", "source_record_sha256"])) {
+        violations.push(`${label} must contain only source_path, line, and source_record_sha256`);
+        return null;
+    }
+    if (!isSafeProjectSourcePath(value.source_path)
+        || !Number.isInteger(value.line)
+        || Number(value.line) < 1
+        || typeof value.source_record_sha256 !== "string"
+        || !/^[a-f0-9]{64}$/.test(value.source_record_sha256)) {
+        violations.push(`${label} must identify one safe project-relative source line with a lowercase SHA-256`);
+        return null;
+    }
+    return value;
+}
+/** Validate and normalize the complete finding shape that Audit itself can emit. */
+export function validateTerminologyProposal(value) {
+    const violations = [];
+    const fields = ["family", "concept", "proposed_canonical_term", "canonical_evidence", "variants", "severity", "confidence", "personal_divergence", "proposal_digest"];
+    if (!mapping(value) || !exactFields(value, fields)) {
+        return { proposal: null, violations: ["proposal must be one complete terminology_drift finding with no undeclared fields"] };
+    }
+    if (value.family !== "terminology_drift")
+        violations.push("proposal family must be terminology_drift");
+    if (typeof value.concept !== "string" || value.concept.trim() === "")
+        violations.push("proposal concept must be non-empty");
+    if (typeof value.proposed_canonical_term !== "string" || value.proposed_canonical_term.trim() === "")
+        violations.push("proposed canonical term must be non-empty");
+    if (!["critical", "warning", "info"].includes(String(value.severity)))
+        violations.push("proposal severity is invalid");
+    const minimumConfidence = confidenceFloor();
+    if (!Number.isInteger(value.confidence) || Number(value.confidence) < minimumConfidence || Number(value.confidence) > 100) {
+        violations.push(`proposal confidence must be an integer from ${minimumConfidence} through 100`);
+    }
+    if (Number.isInteger(value.confidence) && Number(value.confidence) < 70 && value.severity !== "info") {
+        violations.push("confidence below 70 requires info severity");
+    }
+    if (typeof value.proposal_digest !== "string" || !/^[a-f0-9]{64}$/.test(value.proposal_digest))
+        violations.push("proposal_digest must be a lowercase SHA-256");
+    const terms = [];
+    const readTerm = (term, records, label) => {
+        if (typeof term !== "string" || term.trim() === "") {
+            violations.push(`${label} term must be non-empty`);
+            return;
+        }
+        if (!Array.isArray(records) || records.length === 0) {
+            violations.push(`${label} evidence must be non-empty`);
+            return;
+        }
+        const parsed = records
+            .map((record, index) => proposalEvidence(record, `${label}[${index}]`, violations))
+            .filter((record) => record !== null);
+        if (new Set(parsed.map(evidenceIdentity)).size !== parsed.length) {
+            violations.push(`${label} identities must be distinct`);
+        }
+        terms.push({ term, evidence: parsed });
+    };
+    readTerm(value.proposed_canonical_term, value.canonical_evidence, "canonical_evidence");
+    if (!Array.isArray(value.variants) || value.variants.length === 0) {
+        violations.push("proposal variants must be non-empty");
+    }
+    else {
+        value.variants.forEach((variant, index) => {
+            if (!mapping(variant) || !exactFields(variant, ["term", "evidence"])) {
+                violations.push(`variants[${index}] must contain only term and evidence`);
+                return;
+            }
+            readTerm(variant.term, variant.evidence, `variants[${index}].evidence`);
+        });
+    }
+    if (terms.some((term, index) => terms.slice(0, index).some((candidate) => unicodeCaselessExact(candidate.term, term.term)))) {
+        violations.push("proposal term identities must be Unicode caseless-exact unique");
+    }
+    let divergence;
+    if (value.personal_divergence !== undefined) {
+        if (!mapping(value.personal_divergence)
+            || !exactFields(value.personal_divergence, ["personal_term", "project_term"])
+            || typeof value.personal_divergence.personal_term !== "string"
+            || value.personal_divergence.personal_term.trim() === ""
+            || value.personal_divergence.project_term !== value.proposed_canonical_term)
+            violations.push("personal_divergence must bind a non-empty personal term to the proposed project term");
+        else
+            divergence = value.personal_divergence;
+    }
+    if (violations.length > 0 || terms.length < 2)
+        return { proposal: null, violations };
+    const expected = canonicalProposal({
+        family: "terminology_drift",
+        concept: value.concept,
+        terms,
+        severity: value.severity,
+        confidence: value.confidence,
+        ...(divergence ? { personal_divergence: divergence } : {}),
+    });
+    if (expected.proposed_canonical_term !== value.proposed_canonical_term)
+        violations.push("proposed canonical term is not the best-supported term under the Audit tie-break");
+    if (canonicalTerminologyJson(proposalWithoutDigest(expected)) !== canonicalTerminologyJson(proposalWithoutDigest(value))) {
+        violations.push("proposal shape or ordering is not the canonical Audit output");
+    }
+    if (expected.proposal_digest !== value.proposal_digest)
+        violations.push("proposal_digest does not match the canonical Audit output");
+    return { proposal: violations.length === 0 ? expected : null, violations };
+}
+function confidenceFloor() {
+    const protocol = loadYamlMappingFile(path.join(resolveSourceRoot(), "skills", "agentera", "protocol.yaml"));
+    const scale = protocol.CONFIDENCE_SCALE;
+    const range = scale?.["3"]?.range;
+    if (!Array.isArray(range) || !Number.isInteger(range[0])) {
+        throw new Error("protocol CONFIDENCE_SCALE CS3 lower bound is unavailable");
+    }
+    return Number(range[0]);
+}
+function verifiedEvidence(projectRoot, term, evidence) {
+    const root = fs.realpathSync(projectRoot);
+    const verified = [];
+    const identities = new Set();
+    for (const item of evidence) {
+        if (!Number.isInteger(item.line) || item.line < 1 || !isSafeProjectSourcePath(item.source_path))
+            return null;
+        const pathname = path.resolve(root, item.source_path);
+        if (pathname !== root && !pathname.startsWith(`${root}${path.sep}`))
+            return null;
+        let realPath;
+        try {
+            realPath = fs.realpathSync(pathname);
+        }
+        catch {
+            return null;
+        }
+        if (!realPath.startsWith(`${root}${path.sep}`) || !fs.statSync(realPath).isFile())
+            return null;
+        const line = fs.readFileSync(realPath, "utf8").split(/\r?\n/)[item.line - 1];
+        if (line === undefined || !containsGlossaryTerm(line, term))
+            return null;
+        const sourcePath = path.relative(root, realPath).split(path.sep).join(path.posix.sep);
+        const identity = `${sourcePath}:${item.line}`;
+        if (identities.has(identity))
+            continue;
+        identities.add(identity);
+        verified.push({
+            source_path: sourcePath,
+            line: item.line,
+            source_record_sha256: crypto.createHash("sha256").update(line).digest("hex"),
+        });
+    }
+    return verified.length > 0 ? verified : null;
+}
+/** Generate findings from assessed concepts without writing project or personal state. */
+export function assessTerminologyDrift(input) {
+    const minimumConfidence = confidenceFloor();
+    const findings = [];
+    for (const concept of input.concepts) {
+        if (concept.confidence < minimumConfidence ||
+            concept.confidence > 100 ||
+            !Number.isInteger(concept.confidence) ||
+            input.deliberateDecisionConcepts.has(concept.concept) ||
+            input.trackedIssueConcepts.has(concept.concept))
+            continue;
+        const consolidated = [];
+        let invalidEvidence = false;
+        for (const candidate of concept.terms) {
+            const term = candidate.term.trim();
+            const evidence = term ? verifiedEvidence(input.projectRoot, term, candidate.evidence) : null;
+            if (!evidence) {
+                invalidEvidence = true;
+                break;
+            }
+            const group = consolidated.find((item) => unicodeCaselessExact(item.term, term)) ?? { term, evidence: new Map() };
+            for (const item of evidence)
+                group.evidence.set(`${item.source_path}:${item.line}`, item);
+            if (!consolidated.includes(group))
+                consolidated.push(group);
+        }
+        if (invalidEvidence || consolidated.length < 2)
+            continue;
+        const terms = consolidated.map((term) => ({
+            term: term.term,
+            evidence: orderedEvidence([...term.evidence.values()]),
+        }));
+        const seed = {
+            family: "terminology_drift",
+            concept: concept.concept,
+            terms,
+            severity: concept.severity,
+            confidence: concept.confidence,
+        };
+        let finding = canonicalProposal(seed);
+        const personalTerm = input.personalTerms?.get(concept.concept)?.trim();
+        if (personalTerm && !unicodeCaselessExact(personalTerm, finding.proposed_canonical_term)) {
+            finding = canonicalProposal({
+                ...seed,
+                personal_divergence: {
+                    personal_term: personalTerm,
+                    project_term: finding.proposed_canonical_term,
+                },
+            });
+        }
+        const validated = validateTerminologyProposal(finding);
+        if (!validated.proposal)
+            throw new Error(`Audit produced an invalid terminology proposal: ${validated.violations.join("; ")}`);
+        findings.push(validated.proposal);
+    }
+    return findings;
+}

package/dist/bin/agentera.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { main } from "../cli/dispatch.js";
-process.exit(main(process.argv));
-//# sourceMappingURL=agentera.js.map
+// Assigning exitCode lets Node drain piped stdout/stderr before the process
+// terminates. Calling process.exit() here truncates large command payloads.
+process.exitCode = main(process.argv);