@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/_lib/scan_scope.ts

@@ -0,0 +1,115 @@
+/**
+ * Scan-scope assertions — "a gate that read nothing did not pass".
+ *
+ * WHY THIS EXISTS (audit 2026-07-29, `agents/settings/contexts/gates-that-cannot-fail.md`):
+ * ADR-051 moved the source container and a later commit deleted `packages/`.
+ * Fourteen `lint_*`/`check_*` gates kept a hardcoded literal path, and every
+ * one of them treats a missing directory as "nothing to check" — so they exit 0
+ * and print a green checkmark while scanning zero files. Their own output said
+ * so (`0 file(s) scanned`, `0 name(s) checked`, `0 declarer(s)`); nothing ever
+ * asserted on the number.
+ *
+ * Two shapes cover the whole class:
+ *
+ * - **Corpus gates** walk a root and check N units → {@link assertScanned}.
+ *   Zero units is a failure unless the gate declares a justified `allowEmpty`.
+ * - **Watch-list gates** (diff-based, no corpus to count) name specific files
+ *   they guard → {@link assertWatchlistResolves}. A watch list that resolves to
+ *   nothing on disk means the guard is watching phantoms.
+ *
+ * Both throw {@link DeadScopeError}; callers map it to a non-zero exit. The
+ * point is that the failure is LOUD and names the root, so the next path
+ * migration cannot silently disarm a gate again.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Raised when a gate's scope is empty — it cannot have checked anything. */
+export class DeadScopeError extends Error {
+    readonly gate: string;
+
+    constructor(gate: string, message: string) {
+        super(message);
+        this.name = 'DeadScopeError';
+        this.gate = gate;
+    }
+}
+
+export interface ScannedOptions {
+    /** Gate name, for the error message (e.g. `lint_namespace`). */
+    gate: string;
+    /** How many units the gate actually examined. */
+    scanned: number;
+    /** Plural noun for the unit — `file(s)`, `name(s)`, `declarer(s)`. */
+    units: string;
+    /** The root(s) the gate walked, repo-relative, for the error message. */
+    roots: readonly string[];
+    /**
+     * Justification for legitimately scanning zero. Supply ONLY when an empty
+     * corpus is a real, expected state (an optional consumer surface that may
+     * genuinely be absent) — never to silence a moved root. The string is the
+     * reason and is printed, so it is reviewable in a diff.
+     */
+    allowEmpty?: string;
+}
+
+/**
+ * Assert a corpus gate examined at least one unit.
+ *
+ * @throws {DeadScopeError} when `scanned === 0` and no `allowEmpty` reason is given.
+ */
+export function assertScanned(opts: ScannedOptions): void {
+    if (opts.scanned > 0) {
+        return;
+    }
+    if (opts.allowEmpty !== undefined && opts.allowEmpty.trim() !== '') {
+        return;
+    }
+    const roots = opts.roots.length > 0 ? opts.roots.join(', ') : '(no root declared)';
+    throw new DeadScopeError(
+        opts.gate,
+        `${opts.gate}: scanned 0 ${opts.units} under ${roots} — the scan scope is ` +
+            'dead or the root moved. A gate that read nothing has not passed. ' +
+            'Repoint the root (prefer the shared resolver in _lib/agent_src.ts), ' +
+            'or declare a justified `allowEmpty` reason if an empty corpus is genuinely expected.',
+    );
+}
+
+export interface WatchlistOptions {
+    /** Gate name, for the error message. */
+    gate: string;
+    /** Repo-relative candidate paths the gate guards. */
+    candidates: readonly string[];
+    /** Absolute repo root the candidates resolve against. */
+    repoRoot: string;
+}
+
+/**
+ * Assert a watch-list gate's targets exist on disk, and return the ones that do.
+ *
+ * A diff-based guard has no corpus to count: it compares changed paths against
+ * a fixed list. If that list resolves to nothing, the guard reports "clean"
+ * forever — the exact shape of the `check_safety_floor_untouched` defect, which
+ * announced `4 rules guarded` while guarding none.
+ *
+ * @returns the subset of `candidates` that exist.
+ * @throws {DeadScopeError} when none of them exist.
+ */
+export function assertWatchlistResolves(opts: WatchlistOptions): string[] {
+    const resolved = opts.candidates.filter((rel) => {
+        try {
+            return fs.statSync(path.join(opts.repoRoot, rel)).isFile();
+        } catch {
+            return false;
+        }
+    });
+    if (resolved.length === 0) {
+        throw new DeadScopeError(
+            opts.gate,
+            `${opts.gate}: none of its ${opts.candidates.length} guarded path(s) exist ` +
+                `under ${opts.repoRoot} — the guard is watching phantoms and can never fire. ` +
+                `Checked: ${opts.candidates.join(', ')}`,
+        );
+    }
+    return resolved;
+}

package/src/scripts/_lib/user_global_memory_audit.ts

@@ -0,0 +1,187 @@
+/**
+ * The global user-memory audit render — Phase 4 of road-to-global-user-memory
+ * ("delete, revoke, audit"). Renders what the GLOBAL layer currently holds —
+ * `~/.event4u/agent-config/user/profile.md` and its `observations.jsonl`
+ * buffer — without requiring a human to open raw JSONL. This is the global
+ * layer only, not the merged effective profile `/agents user show` already
+ * renders (project-local `.agent-user.md` never leaves the project it lives
+ * in, so it has nothing to audit at this layer).
+ *
+ * Every free-text value that ever originated from a buffered observation or
+ * a profile field — `suggest`, `evidence`, `project_name`, a profile field's
+ * string value, a tombstone's `reason` — is routed through the SAME
+ * `knowledge_global_redaction.redaction_scan` gate the write path already
+ * runs (Phase 2's `evaluateCaptureGuards` /
+ * `evaluateContextCaptureGuards`) before it may appear in the rendered
+ * output. That gate's `project_path` category already flags absolute-path
+ * shapes (`/Users/`, `/home/`, `/opt/`, `/private/`, a configured
+ * `repo_root`) in free text, so a stray path mentioned inside an
+ * observation's own `suggest`/`evidence` text is caught the same way a
+ * credential or an email would be — this module never needs a second path
+ * detector. The only path-shaped strings this render ever emits verbatim
+ * are the two canonical, tool-owned storage locations (`profilePath`,
+ * `bufferPath`) it resolves itself — never a value that came from
+ * user-authored or agent-authored content. `context.project_path` (a raw
+ * project directory, one of the fields road-to-global-user-memory Phase 3
+ * flagged as a narrower-but-real metadata surface) is never read by this
+ * module at all — only `context.project_name` (already a basename) ever
+ * reaches the render, and it still passes the same scan.
+ *
+ * Pure, read-only. Never writes to `profile.md`, the buffer, or the
+ * revocation ledger.
+ */
+import { redaction_scan } from './knowledge_global_redaction.js';
+import {
+    getPath,
+    loadGlobalProfileLayer,
+    mergeUserProfileLayers,
+    resolveGlobalProfilePath,
+} from './agent_user_profile.js';
+import * as revocations from './user_global_revocations.js';
+import {
+    ALLOWED_OBSERVATION_FIELDS,
+    findPromotionCandidates,
+    readGlobalObservations,
+    resolveGlobalObservationsPath,
+} from './user_global_observations.js';
+import type { ObservationField } from './user_global_observations.js';
+import type * as user_global_paths from './user_global_paths.js';
+
+const REDACTED_MARKER = '[redacted]';
+
+/** `true` when `text` fails the write-path redaction gate — the sole criterion for masking a render value. */
+function _isClean(text: string): boolean {
+    return redaction_scan(text).length === 0;
+}
+
+/** Redact `text` if it fails the same gate the write path already runs; pass through unchanged otherwise. */
+function _safe(text: string): string {
+    return _isClean(text) ? text : REDACTED_MARKER;
+}
+
+/** Render a parsed profile leaf value (string, string[], or other scalar) as a redaction-checked display string. */
+function _renderFieldValue(value: unknown): string {
+    if (Array.isArray(value)) {
+        return _safe(value.map((v) => String(v)).join(', '));
+    }
+    return _safe(String(value));
+}
+
+export interface AuditProfileField {
+    readonly path: string;
+    readonly value: string;
+}
+
+export interface AuditBufferFieldCount {
+    readonly field: string;
+    readonly count: number;
+}
+
+export interface AuditPromotionCandidate {
+    readonly suggest: string;
+    readonly seenCount: number;
+    readonly projects: readonly string[];
+}
+
+export interface GlobalMemoryAuditRender {
+    readonly profilePath: string | null;
+    readonly profileExists: boolean;
+    readonly profileLastUpdated: string | undefined;
+    readonly profileFields: readonly AuditProfileField[];
+    readonly bufferPath: string | null;
+    readonly bufferEntryCount: number;
+    readonly bufferFieldCounts: readonly AuditBufferFieldCount[];
+    readonly promotionCandidates: readonly AuditPromotionCandidate[];
+    readonly revocationCount: number;
+    /** Pre-formatted, print-ready block — every value already passed the redaction gate above. */
+    readonly text: string;
+}
+
+/**
+ * Build the audit render for the global layer. `env` is honoured exactly
+ * like every other global-artefact reader (`$EVENT4U_CONFIG_HOME`, the
+ * legacy `~/.config/agent-config/` fallback) — tests MUST inject it rather
+ * than touch the real `~/.event4u/`.
+ */
+export function renderGlobalMemoryAudit(
+    options: { env?: user_global_paths.EnvMap | null } = {},
+): GlobalMemoryAuditRender {
+    const env = options.env ?? null;
+
+    const profileLayer = loadGlobalProfileLayer(env);
+    const merged = mergeUserProfileLayers(profileLayer, null);
+    const profilePath = resolveGlobalProfilePath(env);
+    const profileFields: AuditProfileField[] = Object.keys(merged.sources)
+        .sort()
+        .map((dottedPath) => ({
+            path: dottedPath,
+            value: _renderFieldValue(getPath(merged.profile, dottedPath.split('.'))),
+        }));
+    const profileLastUpdated =
+        typeof profileLayer?.data.last_updated === 'string' ? profileLayer.data.last_updated : undefined;
+
+    const bufferPath = resolveGlobalObservationsPath(env);
+    const { entries } = readGlobalObservations({ env });
+    const fieldCounts = new Map<ObservationField, number>();
+    for (const entry of entries) {
+        if ((ALLOWED_OBSERVATION_FIELDS as readonly string[]).includes(entry.field)) {
+            const field = entry.field as ObservationField;
+            fieldCounts.set(field, (fieldCounts.get(field) ?? 0) + 1);
+        }
+    }
+    const bufferFieldCounts: AuditBufferFieldCount[] = [...fieldCounts.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([field, count]) => ({ field, count }));
+
+    const promotionCandidates: AuditPromotionCandidate[] = findPromotionCandidates(entries).map((c) => ({
+        suggest: _safe(c.observation.suggest),
+        seenCount: c.seenCount,
+        projects: c.projects.map((p) => _safe(p)),
+    }));
+
+    const revocationCount = revocations.loadTombstones(env).length;
+
+    const lines: string[] = [];
+    lines.push('Global user-memory audit');
+    lines.push('');
+    lines.push(`Profile: ${profilePath ?? '(none — no observation has been accepted yet)'}`);
+    if (profileFields.length === 0) {
+        lines.push('  (no fields set)');
+    } else {
+        for (const field of profileFields) {
+            lines.push(`  ${field.path}: ${field.value}`);
+        }
+    }
+    if (profileLastUpdated !== undefined) {
+        lines.push(`  last_updated: ${profileLastUpdated}`);
+    }
+    lines.push('');
+    lines.push(`Buffer: ${bufferPath ?? '(none — no observation has been buffered yet)'} (${entries.length} entries)`);
+    if (bufferFieldCounts.length === 0) {
+        lines.push('  (empty)');
+    } else {
+        for (const fc of bufferFieldCounts) {
+            lines.push(`  ${fc.field}: ${fc.count}×`);
+        }
+    }
+    lines.push('');
+    lines.push(`Promotion candidates (seen_count ≥ 3): ${promotionCandidates.length}`);
+    for (const candidate of promotionCandidates) {
+        lines.push(`  "${candidate.suggest}" — seen in ${candidate.seenCount} projects (${candidate.projects.join(', ')})`);
+    }
+    lines.push('');
+    lines.push(`Revocation ledger: ${revocationCount} tombstone(s)`);
+
+    return {
+        profilePath,
+        profileExists: profileLayer !== null,
+        profileLastUpdated,
+        profileFields,
+        bufferPath,
+        bufferEntryCount: entries.length,
+        bufferFieldCounts,
+        promotionCandidates,
+        revocationCount,
+        text: lines.join('\n'),
+    };
+}