@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/core-policy.js

@@ -0,0 +1,1018 @@
+/** Native ports of policy-age-report.sh, policy-retire.sh, and
+ * read-policy-frontmatter.sh. Runtime policy edits stay rooted at the caller's
+ * live HQ tree; frontmatter extraction stays rooted at cwd. */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { policyValidatorDiagnostic } from '../lib/policy-validator.js';
+import { resolveLiveRoot, resolveBundledAsset } from '../utils/hq-roots.js';
+import { runBundledScript } from '../utils/run-bundled-script.js';
+import { describeCoreCommand } from './core-command-catalog.js';
+import { runPolicyFrontmatter as runPolicyFrontmatterImpl } from './core-policy-frontmatter.js';
+const POLICY_AGE_REPORT_ASSET = 'core/scripts/policy-age-report.sh';
+const POLICY_RETIRE_ASSET = 'core/scripts/policy-retire.sh';
+const POLICY_FRONTMATTER_ASSET = 'core/scripts/read-policy-frontmatter.sh';
+const AGE_HELP = [
+    '# hq-core: public',
+    '# policy-age-report.sh — measure policy usage and flag retirement candidates',
+    '# (2026-09-07).',
+    '#',
+    "# Why: nothing retired a policy. About 85% of one install's 1,251 personal",
+    '# policies were machine-written, and the only "usage" signal was that the',
+    '# loader printed them — which, above the host\'s output ceiling, meant nothing.',
+    '# This report gives the fade-out its inputs. It does NOT delete anything; it',
+    '# names candidates with the evidence, for a human (or /learn --retire) to act on.',
+    '#',
+    '# Signals per policy (from workspace/orchestrator/policy-trigger-state/*.txt,',
+    '# one ledger per session, and the policy files themselves):',
+    '#   fired          number of sessions whose ledger recorded the slug (emitted)',
+    '#   retrieved      number of sessions that pulled the full text (record-policy-retrieval.sh)',
+    '#   last_fired     newest ledger mtime that contains the slug (UTC date)',
+    '#   age_days       days since frontmatter `created:` (or file mtime)',
+    '#   stale_refs     backtick-quoted HQ-relative paths in the Rule text that no',
+    '#                  longer exist on disk (an inaccuracy proxy). Only core/,',
+    '#                  .claude/, companies/<co>/ paths are judged; lines that talk',
+    '#                  about a path being deleted/removed/legacy are not dependencies;',
+    '#                  a same-stem sibling (foo.sh -> foo.mjs) counts as renamed.',
+    '#   single_incident frontmatter source is a one-off (user-correction,',
+    '#                  session-learning, back-pressure-failure) AND version == 1',
+    '#',
+    '# Candidate classes (--candidates):',
+    '#   never-fired    fired == 0 and age_days >= --min-age (default 30)',
+    '#   dormant        fired > 0 but last_fired older than --dormant-days (default 90)',
+    '#   stale-refs     stale_refs > 0 (rule points at something that is gone)',
+    '#   single-incident-old   single_incident, age_days >= --incident-days (default 60), and fired <= 1',
+    '#',
+    '# Usage:',
+].join('\n') + '\n';
+const RETIRE_HELP = [
+    '# hq-core: public',
+    '# policy-retire.sh — retire (or restore) a policy without deleting it (2026-09-07).',
+    '#',
+    '# Why: nothing retired policies, so the corpus only grew. Retirement is a',
+    '# frontmatter state, not a deletion: the file stays where it is (history,',
+    '# grep-ability, restore), and every consumer skips `status: retired` — the',
+    '# trigger loader, the company-bind digest, the age report.',
+    '#',
+    '# Usage:',
+    '#   policy-retire.sh <slug-or-path> --reason "<why>" [--by <who>]',
+    '#   policy-retire.sh <slug-or-path> --restore',
+    '#   policy-retire.sh --from-report <age-report.json> --class <never-fired|dormant|stale-refs|single-incident-old> --reason "<why>" [--yes]',
+    '#   policy-retire.sh --auto [--dir <policies-dir>]... [--classes a,b] [--report-dir <dir>] [--dry-run]',
+    '#',
+    '# --auto is the human-ON-the-loop mode (2026-09-07): it runs the age report,',
+    '# retires every candidate with a per-policy reason, and writes a dated report',
+    '# (default workspace/reports/policy-retirement-<date>.md) so a wrong call can',
+    '# be found and reversed with --restore. Nobody approves in advance. Classes and',
+    '# reasons:',
+    '#   never-fired          never emitted in any session ledger, older than 30 days',
+    '#   dormant              last emitted more than 90 days ago',
+].join('\n') + '\n';
+function policyResult(code, stdout = '', stderr = '') {
+    return { code, stdout: Buffer.from(stdout), stderr: Buffer.from(stderr) };
+}
+function expectedFsMiss(error) {
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR' || code === 'EACCES' || code === 'ELOOP';
+}
+function fileText(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        // These shell reads are all redirected or guarded, so missing and denied
+        // files contribute no text. Surface I/O and programming failures.
+        if (expectedFsMiss(error))
+            return undefined;
+        throw error;
+    }
+}
+function listFiles(directory) {
+    try {
+        return fs.readdirSync(directory).sort();
+    }
+    catch (error) {
+        // The legacy find/glob paths tolerate absent and inaccessible directories.
+        if (expectedFsMiss(error))
+            return [];
+        throw error;
+    }
+}
+function statMtimeSeconds(filePath) {
+    try {
+        return Math.floor(fs.statSync(filePath).mtimeMs / 1000);
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return undefined;
+        throw error;
+    }
+}
+function isFile(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return false;
+        throw error;
+    }
+}
+function isSymlink(filePath) {
+    try {
+        return fs.lstatSync(filePath).isSymbolicLink();
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return false;
+        throw error;
+    }
+}
+function dirExists(directory) {
+    try {
+        return fs.statSync(directory).isDirectory();
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return false;
+        throw error;
+    }
+}
+function frontmatterScalar(file, key) {
+    const body = fileText(file);
+    if (body === undefined)
+        return '';
+    const lines = body.split('\n');
+    let depth = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (index === 0 && !line.startsWith('---'))
+            return '';
+        if (line.startsWith('---')) {
+            depth += 1;
+            if (depth === 2)
+                break;
+            continue;
+        }
+        if (depth !== 1)
+            continue;
+        const match = line.match(new RegExp(`^${key}:[ \\t]*(.*)$`));
+        if (!match)
+            continue;
+        let value = match[1] ?? '';
+        if (key === 'id')
+            value = value.replace(/^["']|["']$/g, '');
+        if (key === 'source' || key === 'created')
+            value = value.replaceAll('"', '');
+        if (key === 'created')
+            return value.slice(0, 10);
+        return value;
+    }
+    return '';
+}
+function ruleBody(file) {
+    const text = fileText(file) ?? '';
+    const lines = text.split('\n');
+    const body = [];
+    let inside = false;
+    for (const line of lines) {
+        if (line === '## Rule') {
+            inside = true;
+            continue;
+        }
+        if (inside && line.startsWith('## '))
+            break;
+        if (inside)
+            body.push(line);
+    }
+    return body.join('\n');
+}
+function extractRulePaths(file) {
+    const skipLine = /(deleted|removed|retired|deprecated|no longer|not exist|never (call|use|run|read)|do not (call|use|run|read)|must not|instead of|was renamed|old path|legacy)/i;
+    const paths = new Set();
+    for (const line of ruleBody(file).split('\n')) {
+        if (skipLine.test(line))
+            continue;
+        for (const match of line.matchAll(/`((?:core|personal|companies|repos|workspace|\.claude)\/[A-Za-z0-9_./-]+)`/g)) {
+            const reference = match[1];
+            const basename = path.posix.basename(reference);
+            if (/^(foo|bar|baz|example|placeholder|sample|your-|my-|x\.sh|dummy)/.test(basename))
+                continue;
+            if (/[{}*]/.test(reference))
+                continue;
+            paths.add(reference);
+        }
+    }
+    return [...paths].sort();
+}
+function shellReferenceStem(reference) {
+    const lastDot = reference.lastIndexOf('.');
+    return lastDot === -1 ? reference : reference.slice(0, lastDot);
+}
+function shellLsExtensionGlobHasMatch(root, stem) {
+    const patternPath = path.join(root, `${stem}.*`);
+    const directory = path.dirname(patternPath);
+    const basenamePattern = path.basename(patternPath);
+    const literalPrefix = basenamePattern.slice(0, -1);
+    let entries;
+    try {
+        entries = fs.readdirSync(directory);
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return false;
+        throw error;
+    }
+    // Bash 5.2 enables globskipdots by default, so `.*` only matches when the
+    // directory has an actual hidden entry. readdir omits `.` and `..`.
+    return entries.some((entry) => entry.startsWith(literalPrefix));
+}
+function refSummary(file, root) {
+    const refs = extractRulePaths(file);
+    const judged = refs.filter((reference) => {
+        if (!(reference.startsWith('core/') || reference.startsWith('.claude/') || reference.startsWith('companies/')))
+            return false;
+        if (reference.startsWith('.claude/state/') || reference.startsWith('.claude/worktrees/') || reference.startsWith('core/packages/'))
+            return false;
+        return true;
+    });
+    const stale = [];
+    const renamed = [];
+    for (const reference of refs) {
+        if (reference.startsWith('.claude/state/') || reference.startsWith('.claude/worktrees/') || reference.startsWith('core/packages/'))
+            continue;
+        if (!(reference.startsWith('core/') || reference.startsWith('.claude/'))) {
+            if (!reference.startsWith('companies/'))
+                continue;
+            const company = reference.slice('companies/'.length).split('/')[0];
+            if (!dirExists(path.join(root, 'companies', company)))
+                continue;
+        }
+        if (fs.existsSync(path.join(root, reference)))
+            continue;
+        const stem = shellReferenceStem(reference);
+        const hasSibling = shellLsExtensionGlobHasMatch(root, stem);
+        if (hasSibling)
+            renamed.push(reference);
+        else
+            stale.push(reference);
+    }
+    return { stale, renamed, judged: judged.length };
+}
+function epochFromDate(value) {
+    if (!value)
+        return 0;
+    const parsed = Date.parse(`${value}T00:00:00Z`);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== value)
+        return 0;
+    return Math.floor(parsed / 1000);
+}
+function countLedgerRows(directory, withMtime, recursive) {
+    const counts = new Map();
+    const newest = new Map();
+    let anyFiles = false;
+    let stderr = '';
+    const walk = (current) => {
+        for (const entry of listFiles(current)) {
+            const full = path.join(current, entry);
+            let stat;
+            try {
+                stat = fs.lstatSync(full);
+            }
+            catch (error) {
+                if (expectedFsMiss(error))
+                    continue;
+                throw error;
+            }
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory() && recursive) {
+                walk(full);
+                continue;
+            }
+            if (!stat.isFile() || !entry.endsWith('.txt'))
+                continue;
+            anyFiles = true;
+            let content;
+            try {
+                content = fs.readFileSync(full, 'utf8');
+            }
+            catch (error) {
+                const code = error.code;
+                if (withMtime && (code === 'EACCES' || code === 'EPERM')) {
+                    stderr += `awk: fatal: cannot open file \`${full}' for reading: Permission denied\n`;
+                    continue;
+                }
+                if (expectedFsMiss(error))
+                    continue;
+                throw error;
+            }
+            const mtime = Math.floor(stat.mtimeMs / 1000);
+            for (const line of content.split('\n')) {
+                const slug = line.trim().split(/[ \t\r\f\v]+/)[0];
+                if (!slug)
+                    continue;
+                counts.set(slug, (counts.get(slug) ?? 0) + 1);
+                if (withMtime)
+                    newest.set(slug, Math.max(newest.get(slug) ?? 0, mtime));
+            }
+        }
+    };
+    if (dirExists(directory))
+        walk(directory);
+    return { counts, newest, anyFiles, stderr };
+}
+function parseAgeOptions(args, scriptPath) {
+    const dirs = [];
+    let json = false;
+    let candidates = false;
+    let minAge = '30';
+    let dormantDays = '90';
+    let incidentDays = '60';
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === '--dir' || arg === '--min-age' || arg === '--dormant-days' || arg === '--incident-days') {
+            if (index + 1 >= args.length) {
+                const line = arg === '--dir' ? 41 : arg === '--min-age' ? 44 : arg === '--dormant-days' ? 45 : 46;
+                return { kind: 'error', result: policyResult(1, '', `${scriptPath}: line ${line}: $2: unbound variable\n`) };
+            }
+            const value = args[index + 1];
+            if (arg === '--dir')
+                dirs.push(value);
+            else if (arg === '--min-age')
+                minAge = value;
+            else if (arg === '--dormant-days')
+                dormantDays = value;
+            else
+                incidentDays = value;
+            index += 2;
+        }
+        else if (arg === '--json') {
+            json = true;
+            index += 1;
+        }
+        else if (arg === '--candidates') {
+            candidates = true;
+            index += 1;
+        }
+        else if (arg === '-h' || arg === '--help')
+            return { kind: 'help' };
+        else
+            return { kind: 'error', result: policyResult(2, '', `policy-age-report: unknown arg ${arg}\n`) };
+    }
+    return { kind: 'options', dirs, json, candidates, minAge, dormantDays, incidentDays };
+}
+const BASH_INTEGER_MIN = -(1n << 63n);
+const BASH_INTEGER_MAX = (1n << 63n) - 1n;
+function bashInteger(value) {
+    if (!/^[+-]?[0-9]+$/.test(value))
+        return undefined;
+    const parsed = BigInt(value);
+    return parsed < BASH_INTEGER_MIN || parsed > BASH_INTEGER_MAX ? undefined : parsed;
+}
+function bashTestGreaterOrEqual(left, right, scriptPath, line) {
+    const parsed = bashInteger(right);
+    if (parsed === undefined) {
+        return {
+            value: false,
+            stderr: `${scriptPath}: line ${line}: [: ${right}: integer expression expected\n`,
+        };
+    }
+    return { value: BigInt(left) >= parsed, stderr: '' };
+}
+export function runPolicyAgeReport(args, root, env = process.env, nowEpoch = Math.floor(Date.now() / 1000)) {
+    const parsed = parseAgeOptions(args, resolveBundledAsset(POLICY_AGE_REPORT_ASSET));
+    if (parsed.kind === 'help')
+        return policyResult(0, AGE_HELP);
+    if (parsed.kind === 'error')
+        return parsed.result;
+    let now = nowEpoch;
+    try {
+        if (env.HQ_POLICY_REPORT_NOW_EPOCH) {
+            const epoch = bashInteger(env.HQ_POLICY_REPORT_NOW_EPOCH);
+            if (epoch === undefined) {
+                const value = env.HQ_POLICY_REPORT_NOW_EPOCH;
+                if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+                    throw new Error(`${resolveBundledAsset(POLICY_AGE_REPORT_ASSET)}: line 96: ${value}: unbound variable`);
+                }
+                throw new Error(`${resolveBundledAsset(POLICY_AGE_REPORT_ASSET)}: line 96: ${value}: invalid arithmetic value`);
+            }
+            now = Number(epoch);
+        }
+    }
+    catch (error) {
+        return policyResult(1, '', `${String(error.message)}\n`);
+    }
+    const ledgerDir = env.HQ_POLICY_LEDGER_DIR || path.join(root, 'workspace/orchestrator/policy-trigger-state');
+    const retrievalDir = env.HQ_POLICY_RETRIEVAL_LEDGER_DIR || path.join(root, 'workspace/orchestrator/policy-retrieval-state');
+    const usage = countLedgerRows(ledgerDir, true, true);
+    const retrieval = countLedgerRows(retrievalDir, false, false);
+    const dirs = parsed.dirs.length > 0 ? parsed.dirs : [path.join(root, 'personal/policies'), path.join(root, 'core/policies')];
+    const rows = [];
+    let stderr = usage.stderr + retrieval.stderr;
+    for (const requestedDir of dirs) {
+        const directory = path.isAbsolute(requestedDir) ? requestedDir : path.join(root, requestedDir);
+        if (!dirExists(directory))
+            continue;
+        for (const basename of listFiles(directory)) {
+            if (!basename.endsWith('.md') || basename === 'README.md' || basename === 'example-policy.md' || basename.startsWith('_digest') || basename.includes(' ') || basename.includes('.conflict-') || basename.includes('.sync-conflict-'))
+                continue;
+            const file = path.join(directory, basename);
+            if (!isFile(file) || isSymlink(file))
+                continue;
+            const text = fileText(file);
+            if (text === undefined)
+                continue;
+            if (/^status: retired/m.test(text))
+                continue;
+            const id = frontmatterScalar(file, 'id') || basename.slice(0, -3);
+            const enforcement = frontmatterScalar(file, 'enforcement') || 'unset';
+            const source = frontmatterScalar(file, 'source');
+            const version = frontmatterScalar(file, 'version');
+            const createdEpoch = epochFromDate(frontmatterScalar(file, 'created')) || statMtimeSeconds(file) || 0;
+            const ageDays = Math.trunc((now - createdEpoch) / 86400);
+            const fired = usage.counts.get(id) ?? 0;
+            const lastEpoch = usage.newest.get(id);
+            const lastFired = lastEpoch === undefined ? null : new Date(lastEpoch * 1000).toISOString().slice(0, 10);
+            const lastAge = lastEpoch === undefined ? -1 : Math.trunc((now - lastEpoch) / 86400);
+            const retrieved = retrieval.counts.get(id) ?? 0;
+            const refs = refSummary(file, root);
+            const singleIncident = ['user-correction', 'session-learning', 'back-pressure-failure'].includes(source) && (version || '1') === '1';
+            const classes = [];
+            if (fired === 0) {
+                const comparison = bashTestGreaterOrEqual(ageDays, parsed.minAge, resolveBundledAsset(POLICY_AGE_REPORT_ASSET), 130);
+                stderr += comparison.stderr;
+                if (comparison.value && usage.anyFiles)
+                    classes.push('never-fired');
+            }
+            if (fired > 0) {
+                const comparison = bashTestGreaterOrEqual(lastAge, parsed.dormantDays, resolveBundledAsset(POLICY_AGE_REPORT_ASSET), 131);
+                stderr += comparison.stderr;
+                if (comparison.value)
+                    classes.push('dormant');
+            }
+            if (refs.stale.length > 0)
+                classes.push('stale-refs');
+            if (refs.renamed.length > 0)
+                classes.push('renamed-refs');
+            if (singleIncident) {
+                const comparison = bashTestGreaterOrEqual(ageDays, parsed.incidentDays, resolveBundledAsset(POLICY_AGE_REPORT_ASSET), 135);
+                stderr += comparison.stderr;
+                if (comparison.value && fired <= 1)
+                    classes.push('single-incident-old');
+            }
+            let displayPath = file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+            if (!path.isAbsolute(file) && !file.startsWith(`${root}/`))
+                displayPath = file;
+            rows.push({
+                id,
+                path: displayPath,
+                enforcement,
+                age_days: ageDays,
+                fired,
+                last_fired: lastFired,
+                stale_refs: refs.stale,
+                single_incident: singleIncident,
+                candidate_classes: classes,
+                retrieved,
+                refs_judged: refs.judged,
+                renamed_refs: refs.renamed,
+            });
+        }
+    }
+    if (parsed.json) {
+        const selected = parsed.candidates ? rows.filter((row) => row.candidate_classes.length > 0) : rows;
+        return policyResult(0, `${JSON.stringify(selected)}\n`, stderr);
+    }
+    const never = rows.filter((row) => row.fired === 0).length;
+    const staleTotal = rows.filter((row) => row.stale_refs.length > 0).length;
+    const candidateCount = rows.filter((row) => row.candidate_classes.length > 0).length;
+    let stdout = `policy-age-report: ${rows.length} policies, ${never} never fired, ${staleTotal} with stale references, ${candidateCount} retirement candidates (min-age ${parsed.minAge}d, dormant ${parsed.dormantDays}d, incident ${parsed.incidentDays}d)\n`;
+    if (!parsed.candidates)
+        stdout += '  (add --candidates to list them, --json for machine-readable rows)\n';
+    else {
+        const lines = rows.filter((row) => row.candidate_classes.length > 0).map((row) => `  ${row.candidate_classes.join(',').padEnd(14)} ${row.id.padEnd(60)} fired=${String(row.fired).padEnd(4)} last=${(row.last_fired ?? '-').padEnd(10)} age=${String(row.age_days).padEnd(4)}d ${row.stale_refs.length > 0 ? `stale:${row.stale_refs.join(',')}` : ''}`);
+        stdout += `${lines.sort().map((line) => `${line}\n`).join('')}`;
+    }
+    return policyResult(0, stdout, stderr);
+}
+export function runPolicyFrontmatter(args, cwd) {
+    return runPolicyFrontmatterImpl(args, cwd);
+}
+function parseRetireOptions(args, scriptPath, env) {
+    const value = {
+        auto: false,
+        dryRun: false,
+        dirs: [],
+        reportDir: '',
+        classes: '',
+        reason: '',
+        by: env.HQ_SESSION_ID || env.USER || 'unknown',
+        restore: false,
+        report: '',
+        className: '',
+        yes: false,
+        target: '',
+    };
+    const optionsWithValues = new Map([
+        ['--dir', 'dirs'],
+        ['--report-dir', 'reportDir'],
+        ['--classes', 'classes'],
+        ['--reason', 'reason'],
+        ['--by', 'by'],
+        ['--from-report', 'report'],
+        ['--class', 'className'],
+    ]);
+    for (let index = 0; index < args.length;) {
+        const arg = args[index];
+        if (arg === '--auto') {
+            value.auto = true;
+            index += 1;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            value.dryRun = true;
+            index += 1;
+            continue;
+        }
+        if (arg === '--restore') {
+            value.restore = true;
+            index += 1;
+            continue;
+        }
+        if (arg === '--yes') {
+            value.yes = true;
+            index += 1;
+            continue;
+        }
+        if (arg === '-h' || arg === '--help')
+            return { kind: 'help' };
+        const key = optionsWithValues.get(arg);
+        if (key !== undefined) {
+            if (index + 1 >= args.length) {
+                const lineByOption = {
+                    '--dir': 44,
+                    '--report-dir': 45,
+                    '--classes': 46,
+                    '--reason': 47,
+                    '--by': 48,
+                    '--from-report': 50,
+                    '--class': 51,
+                };
+                return { kind: 'error', result: policyResult(1, '', `${scriptPath}: line ${lineByOption[arg]}: $2: unbound variable\n`) };
+            }
+            const next = args[index + 1];
+            if (key === 'dirs')
+                value.dirs.push(next);
+            else
+                value[key] = next;
+            index += 2;
+            continue;
+        }
+        if (arg.startsWith('-'))
+            return { kind: 'error', result: policyResult(2, '', `policy-retire: unknown arg ${arg}\n`) };
+        value.target = arg;
+        index += 1;
+    }
+    return { kind: 'options', value };
+}
+function firstLine(content) {
+    const end = content.indexOf(0x0a);
+    if (end === -1)
+        return content.length > 0 ? content : undefined;
+    return content.subarray(0, end);
+}
+function awkRecords(content) {
+    const records = [];
+    let start = 0;
+    while (start < content.length) {
+        const end = content.indexOf(0x0a, start);
+        if (end === -1) {
+            records.push(content.subarray(start));
+            break;
+        }
+        records.push(content.subarray(start, end));
+        start = end + 1;
+    }
+    return records;
+}
+function rewriteStatus(content, status, reason, by, now) {
+    const output = [];
+    let depth = 0;
+    let done = false;
+    for (const record of awkRecords(content)) {
+        const line = record.toString('latin1');
+        if (/^---[ \t]*$/.test(line)) {
+            depth += 1;
+            if (depth === 2 && !done) {
+                if (status === 'retired') {
+                    output.push(Buffer.from(`status: retired\nretired_at: ${now.toISOString().replace(/\.\d{3}Z$/, 'Z')}\nretired_by: ${by}\nretired_reason: "${reason}"\n`));
+                }
+                done = true;
+            }
+            output.push(record, Buffer.from('\n'));
+            continue;
+        }
+        if (depth === 1 && /^(status|retired_at|retired_by|retired_reason):/.test(line))
+            continue;
+        output.push(record, Buffer.from('\n'));
+    }
+    return Buffer.concat(output);
+}
+function setPolicyStatus(filePath, status, reason, by, env, now, cwd = process.cwd()) {
+    const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+    let content;
+    try {
+        content = fs.readFileSync(resolvedPath);
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return { ok: false, error: `policy-retire: ${filePath} has no frontmatter\n` };
+        throw error;
+    }
+    if (!firstLine(content)?.toString('latin1').startsWith('---')) {
+        return { ok: false, error: `policy-retire: ${filePath} has no frontmatter\n` };
+    }
+    const diagnostic = policyValidatorDiagnostic(content.toString('utf8'), resolvedPath, env);
+    if (diagnostic !== undefined) {
+        // Bash command substitution in policy-retire.sh strips all trailing newlines
+        // from the validator output before printf adds its single final newline.
+        const trimmedDiagnostic = diagnostic.replace(/\n+$/, '');
+        return {
+            ok: false,
+            error: `policy-retire: refusing to write ${filePath}; canonical policy validation failed:\n${trimmedDiagnostic}\n`,
+        };
+    }
+    const tempPath = `${resolvedPath}.tmp`;
+    fs.writeFileSync(tempPath, rewriteStatus(content, status, reason, by, now), { mode: 0o666 });
+    fs.renameSync(tempPath, filePath);
+    return { ok: true };
+}
+function displayPolicyPath(filePath, root) {
+    return filePath.startsWith(`${root}/`) ? filePath.slice(root.length + 1) : filePath;
+}
+function resolvePolicyTarget(target, root, cwd) {
+    let found = isFile(path.isAbsolute(target) ? target : path.resolve(cwd, target))
+        ? (path.isAbsolute(target) ? target : target)
+        : undefined;
+    if (found === undefined) {
+        const dirs = [path.join(root, 'personal/policies'), path.join(root, 'core/policies')];
+        const companies = listFiles(path.join(root, 'companies')).map((name) => path.join(root, 'companies', name, 'policies'));
+        dirs.push(...companies);
+        for (const directory of dirs) {
+            if (isFile(path.join(directory, `${target}.md`))) {
+                found = path.join(directory, `${target}.md`);
+                break;
+            }
+            if (isFile(path.join(directory, target))) {
+                found = path.join(directory, target);
+                break;
+            }
+        }
+    }
+    if (found === undefined)
+        return undefined;
+    if (!isSymlink(path.isAbsolute(found) ? found : path.resolve(cwd, found)))
+        return found;
+    try {
+        return fs.realpathSync(path.isAbsolute(found) ? found : path.resolve(cwd, found));
+    }
+    catch (error) {
+        if (expectedFsMiss(error)) {
+            try {
+                return fs.readlinkSync(path.isAbsolute(found) ? found : path.resolve(cwd, found));
+            }
+            catch (readError) {
+                if (expectedFsMiss(readError))
+                    return undefined;
+                throw readError;
+            }
+        }
+        throw error;
+    }
+}
+function sessionCompanySlug(root, env) {
+    const valid = (candidate) => candidate !== '' && candidate !== '.' && candidate !== '..' && /^[A-Za-z0-9._-]+$/.test(candidate);
+    const candidates = ['HQ_SESSION_ID', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_SESSION_ID', 'CODEX_SESSION_ID', 'CODEX_THREAD_ID', 'GROK_SESSION_ID'];
+    let sessionId = '';
+    for (const variable of candidates) {
+        const value = (env[variable] ?? '').replace(/[\s\u00a0]+/g, '');
+        if (valid(value)) {
+            sessionId = value;
+            break;
+        }
+    }
+    if (!sessionId) {
+        const current = fileText(path.join(root, 'workspace/sessions/.current')) ?? '';
+        const value = current.replace(/[\s\u00a0]+/g, '');
+        if (valid(value))
+            sessionId = value;
+    }
+    if (!sessionId)
+        return '';
+    const metadata = fileText(path.join(root, 'workspace/sessions', sessionId, 'meta.yaml'));
+    if (metadata === undefined)
+        return '';
+    for (const line of metadata.split('\n')) {
+        if (line.trim().split(/[ \t]+/)[0] !== 'company_slug:')
+            continue;
+        return line.replace(/^[^:]+:[ \t]*/, '').replace(/^["]|["]$/g, '');
+    }
+    return '';
+}
+function resolveAutoDirs(options, root, env) {
+    if (options.dirs.length > 0)
+        return options.dirs;
+    const dirs = [path.join(root, 'personal/policies')];
+    const company = sessionCompanySlug(root, env);
+    if (company && company !== 'personal' && dirExists(path.join(root, 'companies', company, 'policies'))) {
+        dirs.push(path.join(root, 'companies', company, 'policies'));
+    }
+    return dirs;
+}
+function autoRetire(options, root, cwd, env, now) {
+    const dirs = resolveAutoDirs(options, root, env);
+    const ageArgs = dirs.flatMap((directory) => ['--dir', directory]).concat(['--json', '--candidates']);
+    const report = runPolicyAgeReport(ageArgs, root, env, Math.floor(now.getTime() / 1000));
+    const json = report.code === 0 ? report.stdout.toString('utf8') : '[]';
+    let candidates;
+    try {
+        candidates = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`policy-retire: in-process age report returned invalid JSON: ${String(error)}`);
+    }
+    const today = now.toISOString().slice(0, 10);
+    const reportDir = options.reportDir || path.join(root, 'workspace/reports');
+    const outputPath = path.join(reportDir, `policy-retirement-${today}.md`);
+    const tempPath = `${outputPath}.tmp`;
+    fs.mkdirSync(reportDir, { recursive: true });
+    let reportText = '';
+    if (!isFile(outputPath)) {
+        reportText += `# Automatic policy retirement — ${today}\n\nMode: human on the loop. Each policy below was retired by \`policy-retire.sh --auto\` with the reason shown.\nReverse any wrong call with \`bash core/scripts/policy-retire.sh <slug> --restore\` and fix the rule that produced it.\n\n`;
+    }
+    reportText += `## Run ${now.toISOString().slice(11, 19)}Z — dirs: ${dirs.join(' ')}\n\n`;
+    fs.writeFileSync(tempPath, reportText);
+    let retired = 0;
+    let failed = 0;
+    let needfix = 0;
+    let wouldRetire = 0;
+    let stdout = '';
+    let stderr = '';
+    for (const candidate of candidates) {
+        if (!candidate.path)
+            continue;
+        let file = path.join(root, candidate.path);
+        if (!isFile(file))
+            file = candidate.path;
+        if (!isFile(path.isAbsolute(file) ? file : path.resolve(cwd, file)))
+            continue;
+        const resolvedForRead = path.isAbsolute(file) ? file : path.resolve(cwd, file);
+        const text = fileText(resolvedForRead) ?? '';
+        if (/^status: retired/m.test(text))
+            continue;
+        let classes = candidate.candidate_classes.join(',');
+        if (options.classes) {
+            const keep = [];
+            for (const name of options.classes.replaceAll(',', ' ').split(/[ \t\n]+/).filter(Boolean)) {
+                if (classes.split(',').includes(name))
+                    keep.push(name);
+            }
+            classes = keep.join(',');
+            if (!classes)
+                continue;
+        }
+        let why = '';
+        if (classes.split(',').includes('renamed-refs')) {
+            reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): referenced file was renamed: ${candidate.renamed_refs.join(', ')}\n`;
+            needfix += 1;
+        }
+        if (classes.split(',').includes('stale-refs')) {
+            if (candidate.refs_judged > 0 && candidate.stale_refs.length === candidate.refs_judged) {
+                why = `every path the rule depends on is gone (${candidate.stale_refs.join(', ')})`;
+            }
+            else {
+                reportText += `- needs-fix (not retired) **${candidate.id}** (${candidate.path}): references gone: ${candidate.stale_refs.join(', ')}\n`;
+                needfix += 1;
+            }
+        }
+        if (classes.split(',').includes('never-fired'))
+            why = `${why ? `${why}; ` : ''}never emitted in any session ledger over ${candidate.age_days} days`;
+        if (classes.split(',').includes('dormant'))
+            why = `${why ? `${why}; ` : ''}last emitted ${candidate.last_fired ?? 'never'}, more than the dormant window ago`;
+        if (classes.split(',').includes('single-incident-old'))
+            why = `${why ? `${why}; ` : ''}one-off correction, ${candidate.age_days} days old, fired ${candidate.fired}x`;
+        if (!why)
+            continue;
+        if (options.dryRun) {
+            stdout += `would retire: ${candidate.id} — ${why}\n`;
+            wouldRetire += 1;
+            continue;
+        }
+        const updated = setPolicyStatus(resolvedForRead, 'retired', `auto: ${why}`, options.by, env, now);
+        if (updated.ok) {
+            stdout += `retired: ${candidate.id} — ${why}\n`;
+            reportText += `- **${candidate.id}** (${candidate.path}): ${why}\n`;
+            retired += 1;
+        }
+        else {
+            stderr += updated.error;
+            stderr += `failed: ${candidate.id} (${candidate.path}); policy was not retired\n`;
+            reportText += `- failed (not retired) **${candidate.id}** (${candidate.path}): canonical policy validation failed\n`;
+            failed += 1;
+        }
+    }
+    if (options.dryRun) {
+        fs.rmSync(tempPath, { force: true });
+        stdout += `policy-retire --auto: ${wouldRetire} of ${candidates.length} candidates would be retired (dry run)\n`;
+    }
+    else if (retired > 0 || failed > 0 || needfix > 0) {
+        fs.appendFileSync(outputPath, fs.readFileSync(tempPath));
+        fs.rmSync(tempPath, { force: true });
+        stdout += `policy-retire --auto: ${retired} retired, ${failed} failed, ${needfix} need a fix; report ${displayPolicyPath(outputPath, root)}\n`;
+    }
+    else {
+        fs.rmSync(tempPath, { force: true });
+        stdout += 'policy-retire --auto: nothing to retire\n';
+    }
+    return policyResult(failed > 0 ? 1 : 0, stdout, stderr);
+}
+function fromReport(options, root, cwd, env, now) {
+    if (!options.className || !options.reason)
+        return policyResult(2, '', '--from-report needs --class and --reason\n');
+    const reportPath = path.isAbsolute(options.report) ? options.report : path.resolve(cwd, options.report);
+    let reportText;
+    try {
+        reportText = fs.readFileSync(reportPath, 'utf8');
+    }
+    catch (error) {
+        if (expectedFsMiss(error))
+            return policyResult(2, '', `cannot read ${options.report}\n`);
+        throw error;
+    }
+    let report;
+    try {
+        report = JSON.parse(reportText);
+    }
+    catch {
+        return policyResult(2, '', `policy-retire: invalid JSON report ${options.report}\n`);
+    }
+    const rows = Array.isArray(report)
+        ? report
+        : report !== null && typeof report === 'object'
+            ? Object.values(report)
+            : [];
+    let retired = 0;
+    let failed = 0;
+    let selected = 0;
+    let stdout = '';
+    let stderr = report === null
+        ? `jq: error (at ${reportPath}:0): Cannot iterate over null (null)\n`
+        : '';
+    for (const value of rows) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const row = value;
+        const candidateClasses = row.candidate_classes;
+        const matchesClass = Array.isArray(candidateClasses)
+            ? candidateClasses.includes(options.className)
+            : typeof candidateClasses === 'string' && candidateClasses.includes(options.className);
+        const reportPath = typeof row.path === 'string' ? row.path : '';
+        if (!matchesClass || !reportPath)
+            continue;
+        const file = path.join(root, reportPath);
+        if (!isFile(file))
+            continue;
+        if (/^status: retired/m.test(fileText(file) ?? ''))
+            continue;
+        selected += 1;
+        const reportId = typeof row.id === 'string' ? row.id : String(row.id ?? 'null');
+        if (!options.yes) {
+            stdout += `would retire: ${reportId} (${reportPath})\n`;
+            continue;
+        }
+        const updated = setPolicyStatus(file, 'retired', `${options.reason} [${options.className}]`, options.by, env, now, cwd);
+        if (updated.ok) {
+            retired += 1;
+            stdout += `retired: ${reportId} (${reportPath})\n`;
+        }
+        else {
+            failed += 1;
+            stderr += `${updated.error}failed: ${reportId} (${reportPath}); policy was not retired\n`;
+        }
+    }
+    if (options.yes) {
+        stdout += `policy-retire: ${retired} retired [${options.className}]; ${failed} failed\n`;
+        if (failed > 0)
+            return policyResult(1, stdout, stderr);
+    }
+    else
+        stdout += `policy-retire: ${selected} would be retired [${options.className}] (add --yes)\n`;
+    return policyResult(0, stdout, stderr);
+}
+export function runPolicyRetire(args, root, cwd, env = process.env, now = new Date()) {
+    const parsed = parseRetireOptions(args, resolveBundledAsset(POLICY_RETIRE_ASSET), env);
+    if (parsed.kind === 'help')
+        return policyResult(0, RETIRE_HELP);
+    if (parsed.kind === 'error')
+        return parsed.result;
+    const options = parsed.value;
+    if (options.auto)
+        return autoRetire(options, root, cwd, env, now);
+    if (options.report)
+        return fromReport(options, root, cwd, env, now);
+    if (!options.target)
+        return policyResult(2, RETIRE_HELP);
+    const file = resolvePolicyTarget(options.target, root, cwd);
+    if (file === undefined)
+        return policyResult(3, '', `policy-retire: no policy found for '${options.target}'\n`);
+    if (options.restore) {
+        const updated = setPolicyStatus(file, 'active', '', options.by, env, now, cwd);
+        if (!updated.ok)
+            return policyResult(1, '', updated.error);
+        return policyResult(0, `policy-retire: restored ${displayPolicyPath(file, root)}\n`);
+    }
+    if (!options.reason)
+        return policyResult(2, '', 'policy-retire: --reason is required\n');
+    const updated = setPolicyStatus(file, 'retired', options.reason, options.by, env, now, cwd);
+    if (!updated.ok)
+        return policyResult(1, '', updated.error);
+    return policyResult(0, `policy-retire: retired ${displayPolicyPath(file, root)} — ${options.reason}\n`);
+}
+function writeResult(result) {
+    if (result.stdout.length > 0)
+        process.stdout.write(result.stdout);
+    if (result.stderr.length > 0)
+        process.stderr.write(result.stderr);
+    if (result.code !== 0)
+        process.exitCode = result.code;
+}
+/** Fast-entry adapter; family gating and shell fallback happen before import. */
+export function runPolicyFast(args, _stdin, cwd, hqRoot, commandName) {
+    let result;
+    if (commandName === "frontmatter") {
+        result = runPolicyFrontmatter(args, cwd);
+    }
+    else {
+        const root = hqRoot ?? resolveLiveRoot();
+        result = commandName === "age-report"
+            ? runPolicyAgeReport(args, root)
+            : runPolicyRetire(args, root, cwd);
+    }
+    writeResult(result);
+    return result.code;
+}
+export function registerCorePolicyCommand(core) {
+    const group = core.command('policy').description('Policy maintenance commands');
+    const register = (name, asset, summary, rootKind) => {
+        const command = group
+            .command(name)
+            .description(summary)
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument('[args...]', 'arguments passed through to the scaffold command');
+        describeCoreCommand(command, { execution: 'native', asset, root: rootKind });
+        return command;
+    };
+    const ageReport = register('age-report', POLICY_AGE_REPORT_ASSET, 'Report policy usage and retirement candidates', 'live');
+    ageReport.action(async (args = [], _options, command) => {
+        const operands = command.args.length > 0 ? command.args : args;
+        const { coreNativePolicyEnabled } = await import('./core-native-policy-flag.js');
+        if (!await coreNativePolicyEnabled()) {
+            const root = resolveLiveRoot({ hqRoot: core.opts().hqRoot });
+            const result = runBundledScript({ asset: POLICY_AGE_REPORT_ASSET, args: operands, cwd: process.cwd(), hqRoot: root });
+            if (result.code !== 0)
+                process.exitCode = result.code;
+            return;
+        }
+        const root = resolveLiveRoot({ hqRoot: core.opts().hqRoot });
+        writeResult(runPolicyAgeReport(operands, root));
+    });
+    const retire = register('retire', POLICY_RETIRE_ASSET, 'Retire or restore a policy', 'live');
+    retire.action(async (args = [], _options, command) => {
+        const operands = command.args.length > 0 ? command.args : args;
+        const { coreNativePolicyEnabled } = await import('./core-native-policy-flag.js');
+        if (!await coreNativePolicyEnabled()) {
+            const root = resolveLiveRoot({ hqRoot: core.opts().hqRoot });
+            const result = runBundledScript({ asset: POLICY_RETIRE_ASSET, args: operands, cwd: process.cwd(), hqRoot: root });
+            if (result.code !== 0)
+                process.exitCode = result.code;
+            return;
+        }
+        const root = resolveLiveRoot({ hqRoot: core.opts().hqRoot });
+        writeResult(runPolicyRetire(operands, root, process.cwd()));
+    });
+    const frontmatter = register('frontmatter', POLICY_FRONTMATTER_ASSET, 'Extract policy frontmatter', 'cwd');
+    frontmatter.action(async (args = [], _options, command) => {
+        const operands = command.args.length > 0 ? command.args : args;
+        const { coreNativePolicyEnabled } = await import('./core-native-policy-flag.js');
+        if (!await coreNativePolicyEnabled()) {
+            const result = runBundledScript({ asset: POLICY_FRONTMATTER_ASSET, args: operands, cwd: process.cwd() });
+            if (result.code !== 0)
+                process.exitCode = result.code;
+            return;
+        }
+        writeResult(runPolicyFrontmatter(operands, process.cwd()));
+    });
+}
+//# sourceMappingURL=core-policy.js.map