@rmyndharis/aimhooman 0.1.0

package/src/scan.mjs

@@ -0,0 +1,325 @@
+import {
+    loadRules,
+    loadRulesWithDiagnostics,
+    actionFor,
+    matchesPath,
+    matchesContent,
+    MAX_LOCAL_MATCH_INPUT,
+} from './rules.mjs';
+import { normalizeGitPath } from './git-path.mjs';
+
+const DECISION_RANK = { allow: 0, review: 1, block: 2 };
+const CATEGORY_RANK = new Map([['secret', 2], ['policy-config', 1]]);
+
+// Engine evaluates paths, messages, and content against a rule set under a
+// profile, honoring local allow/deny overrides.
+export class Engine {
+    constructor(profile, rules) {
+        this.profile = profile;
+        this.rules = rules;
+        this.allowPaths = new Set();
+        this.allowRules = new Set();
+        this.allowSecretPaths = new Set();
+        this.denyPaths = new Set();
+        this.denyRules = new Set();
+        this.scopedAllow = [];
+        this.skipped = {};
+    }
+
+    // setOverrides keeps path and rule scopes separate. String entries remain
+    // accepted for the small public Engine API and are inferred from known IDs.
+    setOverrides(allow, deny, scopedAllow = []) {
+        const allowed = this.#splitOverrides(allow);
+        const denied = this.#splitOverrides(deny);
+        this.allowPaths = allowed.paths;
+        this.allowRules = allowed.rules;
+        this.allowSecretPaths = allowed.secretPaths;
+        this.denyPaths = denied.paths;
+        this.denyRules = denied.rules;
+        this.scopedAllow = scopedAllow.filter((entry) => (
+            entry
+            && typeof entry.target === 'string'
+            && typeof entry.ruleId === 'string'
+            && typeof entry.transition === 'string'
+            && (typeof entry.newObjectId === 'string' || entry.newObjectId === null)
+            && (entry.newMode === '100644' || entry.newMode === '100755' || entry.newMode === null)
+        ));
+    }
+
+    // decide applies overrides to one rule. The caller reduces every resolved
+    // match, so a rule-level allow cannot hide a different matching rule.
+    decide(base, target, rule, context = {}) {
+        if (this.denyPaths.has(target) || this.denyRules.has(rule.id)) return 'block';
+        if (context.transientAllowRules?.has(rule.id)) return 'allow';
+        if (this.scopedAllow.some((entry) => (
+            entry.target === target
+            && entry.ruleId === rule.id
+            && entry.transition === context.transition
+            && entry.newObjectId === context.objectId
+            && entry.newMode === context.mode
+        ))) return 'allow';
+        // A rule-level allow cannot bypass the secret-category guard that the
+        // path-level allow below enforces: secret rules require an explicit
+        // --scope secret-path override on a specific path, never a blanket rule allow.
+        if (this.allowRules.has(rule.id) && rule.category !== 'secret') return 'allow';
+        // A --scope secret-path allow is the explicit override for secret-category
+        // rules only; it must not also suppress a non-secret rule that happens to
+        // match the same path (principle of least privilege).
+        if (this.allowSecretPaths.has(target) && rule.category === 'secret') return 'allow';
+        if (this.allowPaths.has(target) && rule.category !== 'secret') return 'allow';
+        return base;
+    }
+
+    #splitOverrides(entries) {
+        const result = { paths: new Set(), rules: new Set(), secretPaths: new Set() };
+        for (const entry of entries || []) {
+            const target = typeof entry === 'string' ? entry : entry?.target;
+            if (!target) continue;
+            const scope = typeof entry === 'string'
+                ? (this.lookup(target) ? 'rule' : 'path')
+                : (entry.scope ?? (this.lookup(target) ? 'rule' : 'path'));
+            if (scope === 'rule') result.rules.add(target);
+            else if (scope === 'secret-path') result.secretPaths.add(target);
+            else if (scope === 'path') result.paths.add(target);
+        }
+        return result;
+    }
+
+    lookup(id) {
+        return this.rules.find((r) => r.id === id) || null;
+    }
+
+    checkPaths(paths, context = {}) {
+        const out = [];
+        const seen = new Set();
+        for (const raw of paths || []) {
+            const p = normalize(raw);
+            if (!p || seen.has(p)) continue;
+            seen.add(p);
+            const result = this.#evaluate('path', p, undefined, context);
+            if (result) out.push(finding(result, { path: p }));
+            else if (this.denyPaths.has(p)) out.push(pathDenyFinding(p));
+        }
+        return out;
+    }
+
+    checkMessage(text) {
+        const out = [];
+        for (const record of lineRecords(String(text ?? ''))) {
+            this.#markLocalInputSkip('message', '', record.text);
+            const result = this.#evaluate('message', '', record.text);
+            if (result) out.push(finding(result, { line: record.line, text: record.text }));
+        }
+        return out;
+    }
+
+    checkContent(path, content, options = {}) {
+        const out = [];
+        const p = normalize(path);
+        const categories = Array.isArray(options.categories)
+            ? new Set(options.categories)
+            : null;
+        for (const record of lineRecords(String(content))) {
+            this.#markLocalInputSkip('code', p, record.text, categories);
+            const result = this.#evaluate('code', p, record.text, { categories });
+            if (result) out.push(finding(result, { path: p, line: record.line, text: record.text }));
+        }
+        return out;
+    }
+
+    // Repair is deliberately narrower than detection: only clean-profile block
+    // findings backed by validated whole-line metadata may remove bytes.
+    fixMessage(text) {
+        const value = String(text ?? '');
+        if (this.profile !== 'clean') return { cleaned: value, removed: [] };
+        const candidates = this.checkMessage(value).filter((f) => (
+            f.decision === 'block' && f.autofix === 'remove-whole-line'
+        ));
+        if (!candidates.length) return { cleaned: value, removed: [] };
+        const records = lineRecords(value);
+        const terminatedLines = new Set(records
+            .filter((record) => record.end > record.start && value[record.end - 1] === '\n')
+            .map((record) => record.line));
+        const removed = candidates.filter((finding) => terminatedLines.has(finding.line));
+        if (!removed.length) return { cleaned: value, removed: [] };
+        const drop = new Set(removed.map((f) => f.line));
+        const ranges = [];
+        for (const record of records.filter((candidate) => drop.has(candidate.line))) {
+            const previous = ranges.at(-1);
+            if (previous && record.start <= previous.end) previous.end = Math.max(previous.end, record.end);
+            else ranges.push({ start: record.start, end: record.end });
+        }
+        let cleaned = '';
+        let cursor = 0;
+        for (const range of ranges) {
+            cleaned += value.slice(cursor, range.start);
+            cursor = range.end;
+        }
+        cleaned += value.slice(cursor);
+        return { cleaned, removed };
+    }
+
+    takeSkipped() {
+        const skipped = this.skipped;
+        this.skipped = {};
+        return skipped;
+    }
+
+    #markLocalInputSkip(kind, target, text, categories = null) {
+        if (text.length <= MAX_LOCAL_MATCH_INPUT) return;
+        const applicable = this.rules.some((rule) => {
+            if (rule.source !== 'local' || rule.kind !== kind) return false;
+            if (categories && !categories.has(rule.category)) return false;
+            if (kind !== 'code') return true;
+            const candidate = rule.pathCaseInsensitive ? target.toLowerCase() : target;
+            if (rule.pathRes.length && !rule.pathRes.some((regexp) => regexp.test(candidate))) return false;
+            return !rule.exceptRes.some((regexp) => regexp.test(candidate));
+        });
+        if (applicable) this.skipped['local-input-limit'] = (this.skipped['local-input-limit'] || 0) + 1;
+    }
+
+    #evaluate(kind, target, text, context = {}) {
+        const matches = [];
+        for (const rule of this.rules) {
+            if (rule.kind !== kind) continue;
+            if (context.excludedRuleIds?.has(rule.id)) continue;
+            if (context.categories && !context.categories.has(rule.category)) continue;
+            const matched = kind === 'path'
+                ? matchesPath(rule, target)
+                : matchesContent(rule, text, kind === 'code' ? target : undefined);
+            if (!matched) continue;
+            matches.push({
+                rule,
+                decision: this.decide(actionFor(rule, this.profile), target, rule, context),
+            });
+        }
+        if (!matches.length) return null;
+
+        matches.sort(compareMatch);
+        const decision = matches.reduce((current, match) => (
+            DECISION_RANK[match.decision] > DECISION_RANK[current] ? match.decision : current
+        ), 'allow');
+        if (decision === 'allow') return null;
+
+        const primary = matches.find((match) => match.decision === decision);
+        const autofix = matches.some((match) => (
+            match.decision === 'block' && match.rule.autofix === 'remove-whole-line'
+        )) ? 'remove-whole-line' : undefined;
+        return { matches, primary, decision, autofix };
+    }
+}
+
+function compareMatch(left, right) {
+    const decision = DECISION_RANK[right.decision] - DECISION_RANK[left.decision];
+    if (decision) return decision;
+    const category = (CATEGORY_RANK.get(right.rule.category) || 0) - (CATEGORY_RANK.get(left.rule.category) || 0);
+    if (category) return category;
+    const source = Number(right.rule.source !== 'local') - Number(left.rule.source !== 'local');
+    if (source) return source;
+    return compareText(left.rule.id, right.rule.id);
+}
+
+function finding(result, extra) {
+    const rule = result.primary.rule;
+    const matchedRules = [...result.matches]
+        .sort((left, right) => compareText(left.rule.id, right.rule.id))
+        .map((match) => ({
+            ruleId: match.rule.id,
+            ruleVersion: match.rule.version ?? null,
+            kind: match.rule.kind,
+            category: match.rule.category,
+            provider: match.rule.provider,
+            confidence: match.rule.confidence ?? null,
+            decision: match.decision,
+            reason: match.rule.reason,
+            remediation: match.rule.remediation || [],
+            source: match.rule.source || 'builtin',
+        }));
+    const out = {
+        ruleId: rule.id,
+        ruleVersion: rule.version ?? null,
+        matchedRuleIds: matchedRules.map((match) => match.ruleId),
+        matchedRules,
+        kind: rule.kind,
+        category: rule.category,
+        provider: rule.provider,
+        confidence: rule.confidence ?? null,
+        decision: result.decision,
+        reason: rule.reason,
+        remediation: rule.remediation || [],
+        source: rule.source || 'builtin',
+        ...extra,
+    };
+    if (result.autofix) out.autofix = result.autofix;
+    return out;
+}
+
+function pathDenyFinding(path) {
+    return {
+        ruleId: 'override.path-deny',
+        ruleVersion: 1,
+        matchedRuleIds: ['override.path-deny'],
+        matchedRules: [{
+            ruleId: 'override.path-deny',
+            ruleVersion: 1,
+            kind: 'path',
+            category: 'local-override',
+            provider: 'aimhooman',
+            confidence: 'high',
+            decision: 'block',
+            reason: 'A local deny override blocks this path.',
+            remediation: ['Remove the deny override before committing this path.'],
+            source: 'local',
+        }],
+        kind: 'path',
+        category: 'local-override',
+        provider: 'aimhooman',
+        confidence: 'high',
+        decision: 'block',
+        reason: 'A local deny override blocks this path.',
+        remediation: ['Remove the deny override before committing this path.'],
+        source: 'local',
+        path,
+    };
+}
+
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function lineRecords(value) {
+    const records = [];
+    let start = 0;
+    let line = 1;
+    while (start < value.length) {
+        const newline = value.indexOf('\n', start);
+        const end = newline < 0 ? value.length : newline + 1;
+        let textEnd = newline < 0 ? value.length : newline;
+        if (textEnd > start && value[textEnd - 1] === '\r') textEnd -= 1;
+        records.push({ start, end, line, text: value.slice(start, textEnd) });
+        start = end;
+        line += 1;
+    }
+    if (value.length === 0 || value.endsWith('\n')) {
+        records.push({ start: value.length, end: value.length, line, text: '' });
+    }
+    return records;
+}
+
+function normalize(p) {
+    return normalizeGitPath(p);
+}
+
+// newEngine builds an engine for a profile with the embedded rule packs loaded.
+// When stateDir is given, local rule packs from <stateDir>/rules/*.json are
+// appended after the core packs.
+export function newEngine(profile, stateDir) {
+    return new Engine(profile, loadRules(stateDir));
+}
+
+// Diagnostic constructor lets hook/CLI callers choose profile-specific handling
+// for malformed local packs while always retaining validated built-in rules.
+export function newEngineWithDiagnostics(profile, stateDir) {
+    const { rules, errors } = loadRulesWithDiagnostics(stateDir);
+    return { engine: new Engine(profile, rules), errors };
+}

package/src/state.mjs

@@ -0,0 +1,360 @@
+import {
+    lstatSync,
+    mkdirSync,
+    readFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
+import { normalizeGitPath } from './git-path.mjs';
+
+// Per-repository state, stored in the common Git dir (never the worktree).
+
+const PROFILES = new Set(['clean', 'strict', 'compliance']);
+const OVERRIDE_SCOPES = new Set([
+    'path', 'rule', 'secret-path', 'reviewed-instruction', 'reviewed-policy-file', 'policy-migration',
+]);
+const OVERRIDE_FIELDS = new Set([
+    'target', 'scope', 'reason', 'actor', 'at', 'head', 'transition', 'oldObjectId', 'newObjectId', 'newMode',
+]);
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+const REVIEWED_MODE = /^(?:100644|100755)$/;
+const RFC3339_DATE_TIME = new RegExp(
+    '^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])'
+    + 't(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?'
+    + '(?:z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$',
+    'i',
+);
+
+export class ProjectPolicyError extends Error {
+    constructor(file, detail, cause) {
+        super(`project policy "${file}": ${detail}`);
+        this.name = 'ProjectPolicyError';
+        this.file = file;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class LocalConfigError extends Error {
+    constructor(file, detail, cause) {
+        super(`local config "${file}": ${detail}`);
+        this.name = 'LocalConfigError';
+        this.file = file;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class LocalOverridesError extends Error {
+    constructor(file, detail, cause) {
+        super(`local overrides "${file}": ${detail}`);
+        this.name = 'LocalOverridesError';
+        this.file = file;
+        if (cause) this.cause = cause;
+    }
+}
+
+export function loadProjectPolicy(root) {
+    if (!root) return null;
+    const file = join(root, '.aimhooman.json');
+    let stat;
+    try {
+        stat = lstatSync(file);
+    } catch (error) {
+        if (error?.code === 'ENOENT') return null;
+        throw new ProjectPolicyError(file, `cannot inspect file: ${error.message}`, error);
+    }
+    if (!stat.isFile()) {
+        throw new ProjectPolicyError(file, 'must be a regular file, not a symlink or special file');
+    }
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    } catch (error) {
+        throw new ProjectPolicyError(file, `cannot read file: ${error.message}`, error);
+    }
+    return parseProjectPolicy(text, file);
+}
+
+// Strip a single leading UTF-8 BOM: Node's utf8 decoder keeps it, and
+// JSON.parse rejects it with a misleading "invalid JSON" syntax error.
+function stripBom(text) {
+    return typeof text === 'string' && text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+}
+
+export function parseProjectPolicy(text, file = '.aimhooman.json') {
+    let policy;
+    try {
+        policy = JSON.parse(stripBom(text));
+    } catch (error) {
+        throw new ProjectPolicyError(file, `invalid JSON: ${error.message}`, error);
+    }
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+        throw new ProjectPolicyError(file, 'root must be a JSON object');
+    }
+    const unknown = Object.keys(policy).filter((key) => !['schema_version', 'profile'].includes(key));
+    if (unknown.length) {
+        throw new ProjectPolicyError(file, `unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+    }
+    if (policy.schema_version !== 1) {
+        throw new ProjectPolicyError(file, 'schema_version must be 1');
+    }
+    if (!PROFILES.has(policy.profile)) {
+        throw new ProjectPolicyError(file, 'profile must be clean, strict, or compliance');
+    }
+    return { schemaVersion: 1, profile: policy.profile, file };
+}
+
+export function loadConfig(stateDir, root) {
+    const project = loadProjectPolicy(root);
+    if (project) return { profile: project.profile, source: 'project', file: project.file };
+    const file = join(stateDir, 'config.json');
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    } catch (error) {
+        if (error?.code === 'ENOENT') return { profile: 'clean', source: 'default' };
+        throw new LocalConfigError(file, `cannot read file: ${error.message}`, error);
+    }
+    let config;
+    try {
+        config = JSON.parse(stripBom(text));
+    } catch (error) {
+        throw new LocalConfigError(file, `invalid JSON: ${error.message}`, error);
+    }
+    const normalized = normalizeLocalConfig(config, file);
+    return { profile: normalized.profile, source: 'local', file };
+}
+
+export function saveConfig(stateDir, config) {
+    const file = join(stateDir, 'config.json');
+    const normalized = normalizeLocalConfig(config, file);
+    atomicWriteJson(file, { schema_version: 1, profile: normalized.profile });
+}
+
+function normalizeLocalConfig(config, file) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new LocalConfigError(file, 'root must be a JSON object');
+    }
+    const unknown = Object.keys(config).filter((key) => !['schema_version', 'profile'].includes(key));
+    if (unknown.length) {
+        throw new LocalConfigError(file, `unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+    }
+    // Unversioned files written by pre-release builds remain readable. Every
+    // subsequent save writes schema_version=1, while unknown/future versions
+    // fail closed instead of being interpreted under the wrong contract.
+    if (config.schema_version !== undefined && config.schema_version !== 1) {
+        throw new LocalConfigError(file, 'schema_version must be 1');
+    }
+    if (!PROFILES.has(config.profile)) {
+        throw new LocalConfigError(file, 'profile must be clean, strict, or compliance');
+    }
+    return { profile: config.profile };
+}
+
+export function loadOverrides(stateDir) {
+    const file = join(stateDir, 'overrides.json');
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    } catch (error) {
+        if (error?.code === 'ENOENT') return { allow: [], deny: [] };
+        throw new LocalOverridesError(file, `cannot read file: ${error.message}`, error);
+    }
+    return parseOverrides(text, file);
+}
+
+export function saveOverrides(stateDir, overrides) {
+    const file = join(stateDir, 'overrides.json');
+    const normalized = normalizeOverrides(overrides, file);
+    atomicWriteJson(file, { schema_version: 1, ...normalized });
+}
+
+export function normalizeOverrideTarget(target) {
+    if (typeof target !== 'string') return '';
+    return normalizeGitPath(target);
+}
+
+function parseOverrides(text, file) {
+    let value;
+    try {
+        value = JSON.parse(stripBom(text));
+    } catch (error) {
+        throw new LocalOverridesError(file, `invalid JSON: ${error.message}`, error);
+    }
+    return normalizeOverrides(value, file);
+}
+
+function normalizeOverrides(value, file) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new LocalOverridesError(file, 'root must be a JSON object');
+    }
+    const unknown = Object.keys(value).filter((key) => !['schema_version', 'allow', 'deny'].includes(key));
+    if (unknown.length) {
+        throw new LocalOverridesError(file, `unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+    }
+    // Older local files had no schema_version. Reads keep that compatibility;
+    // saveOverrides always rewrites the canonical versioned form.
+    if (value.schema_version !== undefined && value.schema_version !== 1) {
+        throw new LocalOverridesError(file, 'schema_version must be 1');
+    }
+    return {
+        allow: overrideEntries(value.allow, 'allow', file),
+        deny: overrideEntries(value.deny, 'deny', file),
+    };
+}
+
+function overrideEntries(value, key, file) {
+    if (value === undefined) return [];
+    if (!Array.isArray(value)) {
+        throw new LocalOverridesError(file, `${key} must be an array`);
+    }
+    return value.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new LocalOverridesError(file, `${key}[${index}] must be an object`);
+        }
+        const unknown = Object.keys(entry).filter((field) => !OVERRIDE_FIELDS.has(field));
+        if (unknown.length) {
+            throw new LocalOverridesError(
+                file,
+                `${key}[${index}] has unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`,
+            );
+        }
+        const target = normalizeOverrideTarget(entry.target);
+        if (!target) {
+            throw new LocalOverridesError(file, `${key}[${index}].target must be a non-empty string`);
+        }
+        const scope = entry.scope;
+        if (scope !== undefined && !OVERRIDE_SCOPES.has(scope)) {
+            throw new LocalOverridesError(file, `${key}[${index}].scope is unsupported`);
+        }
+        if (key === 'deny' && scope !== undefined && !['path', 'rule'].includes(scope)) {
+            throw new LocalOverridesError(file, `${key}[${index}].scope ${scope} is only valid for allow entries`);
+        }
+        for (const field of ['reason', 'actor', 'at', 'transition']) {
+            if (entry[field] !== undefined && typeof entry[field] !== 'string') {
+                throw new LocalOverridesError(file, `${key}[${index}].${field} must be a string`);
+            }
+        }
+        if (entry.at !== undefined && !isRfc3339DateTime(entry.at)) {
+            throw new LocalOverridesError(file, `${key}[${index}].at must be an RFC3339 date-time`);
+        }
+        for (const field of ['head', 'oldObjectId']) {
+            if (entry[field] !== undefined && !OBJECT_ID.test(entry[field])) {
+                throw new LocalOverridesError(file, `${key}[${index}].${field} must be a full Git object ID`);
+            }
+        }
+        if (entry.newObjectId !== undefined && entry.newObjectId !== null && !OBJECT_ID.test(entry.newObjectId)) {
+            throw new LocalOverridesError(file, `${key}[${index}].newObjectId must be a full Git object ID or null`);
+        }
+        if (entry.newMode !== undefined && entry.newMode !== null && !REVIEWED_MODE.test(entry.newMode)) {
+            throw new LocalOverridesError(file, `${key}[${index}].newMode must be a regular-file Git mode or null`);
+        }
+        validateOverrideBinding(entry, key, index, file);
+        // Entries written before scoped overrides did not carry a scope. Keep
+        // that distinction so the engine can infer rule IDs from its catalog;
+        // treating every legacy entry as a path changes existing policy.
+        const normalized = { ...entry, target };
+        for (const field of ['head', 'oldObjectId', 'newObjectId']) {
+            if (typeof normalized[field] === 'string') normalized[field] = normalized[field].toLowerCase();
+        }
+        if (normalized.transition !== 'staged' && typeof normalized.transition === 'string') {
+            normalized.transition = normalized.transition.toLowerCase();
+        }
+        return normalized;
+    });
+}
+
+function isRfc3339DateTime(value) {
+    if (!RFC3339_DATE_TIME.test(value) || !Number.isFinite(Date.parse(value))) return false;
+    const date = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+    if (!date) return false;
+    const year = Number(date[1]);
+    const month = Number(date[2]);
+    const day = Number(date[3]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return day <= daysInMonth[month - 1];
+}
+
+function validateOverrideBinding(entry, key, index, file) {
+    const label = `${key}[${index}]`;
+    const scope = entry.scope;
+    const has = (field) => Object.prototype.hasOwnProperty.call(entry, field);
+    const reviewFields = ['head', 'transition', 'oldObjectId', 'newObjectId', 'newMode'];
+
+    if (scope === 'reviewed-instruction' || scope === 'reviewed-policy-file') {
+        for (const field of ['head', 'transition', 'newObjectId', 'newMode']) {
+            if (!has(field)) {
+                throw new LocalOverridesError(file, `${label}.${field} is required for ${scope}`);
+            }
+        }
+        if (entry.transition !== 'staged' && !OBJECT_ID.test(entry.transition)) {
+            throw new LocalOverridesError(
+                file,
+                `${label}.transition must be "staged" or a full Git object ID for ${scope}`,
+            );
+        }
+        if (entry.newObjectId !== null && !OBJECT_ID.test(entry.newObjectId || '')) {
+            throw new LocalOverridesError(
+                file,
+                `${label}.newObjectId must be a full Git blob ID or null for ${scope}`,
+            );
+        }
+        if ((entry.newObjectId === null) !== (entry.newMode === null)) {
+            throw new LocalOverridesError(
+                file,
+                `${label}.newObjectId and .newMode must both describe a blob or both be null for ${scope}`,
+            );
+        }
+        for (const field of ['oldObjectId']) {
+            if (has(field)) {
+                throw new LocalOverridesError(file, `${label}.${field} is only valid for policy-migration`);
+            }
+        }
+        return;
+    }
+
+    if (scope === 'policy-migration') {
+        if (key !== 'allow') {
+            throw new LocalOverridesError(file, `${label}.scope policy-migration is only valid for allow entries`);
+        }
+        if (normalizeOverrideTarget(entry.target) !== '.aimhooman.json') {
+            throw new LocalOverridesError(file, `${label}.target must be .aimhooman.json for policy-migration`);
+        }
+        for (const field of ['head', 'transition', 'oldObjectId', 'newObjectId', 'newMode']) {
+            if (!has(field)) {
+                throw new LocalOverridesError(file, `${label}.${field} is required for policy-migration`);
+            }
+        }
+        if (entry.transition !== 'staged' && !OBJECT_ID.test(entry.transition)) {
+            throw new LocalOverridesError(
+                file,
+                `${label}.transition must be "staged" or a full Git object ID`,
+            );
+        }
+        if ((entry.newObjectId === null) !== (entry.newMode === null)) {
+            throw new LocalOverridesError(
+                file,
+                `${label}.newObjectId and .newMode must both describe a blob or both be null for policy-migration`,
+            );
+        }
+        return;
+    }
+
+    for (const field of reviewFields) {
+        if (has(field)) {
+            throw new LocalOverridesError(file, `${label}.${field} requires a review-bound scope`);
+        }
+    }
+}
+
+function atomicWriteJson(file, value) {
+    let text;
+    try {
+        text = JSON.stringify(value, null, 2) + '\n';
+    } catch (error) {
+        throw new TypeError(`cannot serialize "${file}": ${error.message}`, { cause: error });
+    }
+
+    mkdirSync(dirname(file), { recursive: true });
+    atomicWrite(file, text);
+}