@aiwg/cli 2026.10.11 → 2026.10.12

package/dist/src/gates/floors.js

@@ -1,6 +1,6 @@
+import { GATE_RANK } from './lattice.js';
 import { validateGateDocument } from './schema.js';
 import { splitPackId } from './registry.js';
-const OUTCOME_RANK = { PROMOTE: 0, HOLD: 1, ROLLBACK: 2 };
 const OUTCOMES = ['PROMOTE', 'HOLD', 'ROLLBACK'];
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
@@ -22,7 +22,7 @@ export const INTEGRITY_CEILING_FLOOR_PACK_VERSION = '1.0.0';
 export function projectCeilingSatisfied(declared, configured) {
     if (configured === undefined)
         return true;
-    return OUTCOME_RANK[declared ?? 'PROMOTE'] >= OUTCOME_RANK[configured];
+    return GATE_RANK[declared ?? 'PROMOTE'] >= GATE_RANK[configured];
 }
 /**
  * Resolves the effective project floors: the configured entries, verbatim.
@@ -64,7 +64,7 @@ export function assertCeilingDefaults(ceilings) {
             continue;
         if (!starValid)
             throw new Error(`gates.ceilings: per-study ceilings require the project-wide '*' default ceiling`);
-        if (OUTCOME_RANK[ceiling] < OUTCOME_RANK[star]) {
+        if (GATE_RANK[ceiling] < GATE_RANK[star]) {
             throw new Error(`gates.ceilings.${study}: must tighten the project default ceiling ${String(star)}, not loosen it`);
         }
     }
@@ -124,7 +124,7 @@ export function validateGatesConfig(gates) {
                 for (const [study, ceiling] of Object.entries(gates.ceilings)) {
                     if (study !== '*' && typeof ceiling === 'string'
                         && OUTCOMES.includes(ceiling)
-                        && OUTCOME_RANK[ceiling] < OUTCOME_RANK[star]) {
+                        && GATE_RANK[ceiling] < GATE_RANK[star]) {
                         errors.push(`gates.ceilings.${study}: must tighten the project default ceiling ${star}, not loosen it`);
                     }
                 }

package/dist/src/gates/index.js

@@ -1,17 +1,17 @@
 /**
  * Gates capability phase 1 core (epic #2824): declarative gate packs, a pure deterministic
- * evaluator and digest-bound reports. Experimental and default-off: nothing in the
- * decision runtime imports this module, so existing behavior is unchanged.
+ * evaluator and digest-bound reports. Decision consumers share its outcome lattice.
  */
 export { GATES_API_VERSION, qualifyGateParameter } from './types.js';
 export { GateSchemaError, validateGateDocument } from './schema.js';
 export { GateRegistryError, GATE_NAMESPACES, splitPackId, validateResolvedPack, resolveThresholdDefault, assertGateTightens, applyGateExtends, composeGatePack, resolveGateBinding, expandFloorPacks, enforceProjectFloors, authoredGatePacksOf, gateProvidersOf, GateRegistry, } from './registry.js';
 export { INTEGRITY_CEILING_FLOOR_PACK_ID, INTEGRITY_CEILING_FLOOR_PACK_VERSION, assertCeilingDefaults, projectCeilingSatisfied, resolveProjectFloors, validateGatesConfig, } from './floors.js';
 export { GateEvaluationError, maxOutcome, gateStatusOutcome, sealUpstream, sealGateHoldout, evaluateGates, } from './evaluate.js';
-export { validateGateReport } from './report.js';
+export { assertGateReportDecision, validateGateReport } from './report.js';
 export { createCoreProviderRegistry, evidenceProvider, pairedProvider, proportionProvider, scalarProvider, screeningProvider } from './providers/index.js';
 export { MetricProviderRegistry } from './providers/index.js';
 export { GATE_PACKS_DIR, GATE_PACK_MAX_BYTES, isGatePackFile, listGatePackFiles, readBundleGatePacksDeclaration, loadGatePackFile, originForPackDir, registerBundleGatePacks, resolveGatePacksDir, discoverShippedGatePacks, } from './discovery.js';
 export { buildGatesRegistry, validateGateFile, loadHoldoutFile, loadUpstreamFile, evaluateGatesFromFiles, installedAiwgRoot, listGatePacks, loadProjectFloorsForEvaluate, showGatePack, packsReferencedByRule, } from './driver.js';
 export { GateProviderError, computeProviderCodeDigest, deriveIsolatedSeed, loadGateBundleProviders, invokeBundleProvider, providerBindingPin, runIsolatedProvider, runIsolatedProviderSync, sealProviderSection, snapshotProviderDir, isLoaderIssuedProvider, isolationLaunchPlan, isolationSandboxStatus, parseIsolatedFrame, probeIsolationSandbox, isBundleProvidersEnabled, GATE_PROVIDER_MAX_FILE_BYTES, GATE_PROVIDER_MAX_FILES, GATE_PROVIDER_MAX_TOTAL_BYTES, GATE_PROVIDER_DEFAULT_TIMEOUT_MS, GATE_PROVIDER_MAX_TIMEOUT_MS, GATE_PROVIDER_DEFAULT_MAX_RECORDS, GATE_PROVIDER_MAX_OUTPUT_BYTES, } from './providers/loader.js';
+export { GATE_RANK, ceilingDecision, assertDecisionCeiling, GateDecisionUpgradeError } from './lattice.js';
 //# sourceMappingURL=index.js.map

package/dist/src/gates/lattice.js

@@ -0,0 +1,26 @@
+export const GATE_RANK = Object.freeze({ PROMOTE: 0, HOLD: 1, ROLLBACK: 2 });
+/** The strictest outcome wins; an empty set has no restriction. */
+export function maxOutcome(...outcomes) {
+    return outcomes.reduce((worst, outcome) => GATE_RANK[outcome] > GATE_RANK[worst] ? outcome : worst, 'PROMOTE');
+}
+export function ceilingDecision(decision, ...ceilings) {
+    return maxOutcome(decision, ...ceilings);
+}
+export class GateDecisionUpgradeError extends Error {
+    code = 'report-upgrades-component';
+    decision;
+    component;
+    constructor(decision, component) {
+        super(`Report decision differs from components: cannot upgrade ${component} to ${decision} (report-upgrades-component)`);
+        this.name = 'GateDecisionUpgradeError';
+        this.decision = decision;
+        this.component = component;
+    }
+}
+/** Validate a carried verdict independently of its digest or reproducibility checks. */
+export function assertDecisionCeiling(decision, ...components) {
+    const component = maxOutcome(...components);
+    if (GATE_RANK[decision] < GATE_RANK[component])
+        throw new GateDecisionUpgradeError(decision, component);
+}
+//# sourceMappingURL=lattice.js.map

package/dist/src/gates/registry.js

@@ -1,3 +1,4 @@
+import { ceilingDecision } from './lattice.js';
 import { canonicalJson } from '../security/artifact-trust.js';
 import { artifactDigest } from '../decision/validate.js';
 import { validateGateDocument } from './schema.js';
@@ -428,7 +429,7 @@ export function assertGateTightens(parent, child, params) {
     else if (minimumAfter < minimumBefore) {
         fail(`gate ${child.id} may only raise minimumN`);
     }
-    if (parent.onFail === 'ROLLBACK' && child.onFail !== 'ROLLBACK') {
+    if (ceilingDecision(child.onFail, parent.onFail) !== child.onFail) {
         fail(`gate ${child.id} may not demote onFail ROLLBACK -> HOLD`);
     }
     // Insufficient evidence always holds: ROLLBACK needs an observed blocking

package/dist/src/gates/report.js

@@ -1,6 +1,7 @@
+import { assertDecisionCeiling, GateDecisionUpgradeError } from './lattice.js';
 import { canonicalJson } from '../security/artifact-trust.js';
 import { artifactDigest } from '../decision/validate.js';
-import { evaluateGates, maxOutcome } from './evaluate.js';
+import { evaluateGates } from './evaluate.js';
 import { validateGateDocument } from './schema.js';
 /**
  * Validates a gate report against its trusted inputs. The report is re-derived
@@ -85,12 +86,14 @@ export function validateGateReport(report, input) {
     }
     if (expected.decision !== parsed.decision)
         reasons.push('report-decision-mismatch');
-    const components = [
-        ...parsed.gateEvidence.map(entry => entry.outcome),
-        parsed.ceilings.packOutcome, parsed.ceilings.upstreamCeiling, parsed.ceilings.bindingCeiling,
-    ];
-    if (maxOutcome(parsed.decision, maxOutcome(...components)) !== parsed.decision) {
-        reasons.push('report-upgrades-component');
+    try {
+        assertGateReportDecision(parsed);
+        assertDecisionCeiling(parsed.decision, input.upstream?.metadata.release_gate.decision ?? 'PROMOTE', input.binding.spec.ceiling ?? 'PROMOTE');
+    }
+    catch (error) {
+        if (!(error instanceof GateDecisionUpgradeError))
+            throw error;
+        return { valid: false, reasons: [...reasons, error.code], error };
     }
     return { valid: reasons.length === 0, reasons };
 }
@@ -99,4 +102,13 @@ function stripDigest(report) {
     void _dropped;
     return fields;
 }
+/** Validate carried component ceilings even when no trusted replay context is available. */
+export function assertGateReportDecision(report) {
+    const components = [
+        ...report.gateEvidence.map(entry => entry.outcome),
+        report.ceilings.packOutcome, report.ceilings.upstreamCeiling, report.ceilings.bindingCeiling,
+        report.upstream?.decision ?? 'PROMOTE',
+    ];
+    assertDecisionCeiling(report.decision, ...components);
+}
 //# sourceMappingURL=report.js.map

package/dist/src/issues/audit-cli.js

@@ -0,0 +1,120 @@
+// Wire issue-audit into the existing skill executor and configured tracker/label routing.
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { resolveIssueLabels } from '../config/aiwg-config.js';
+import { projectAiwgWritePath } from '../config/project-artifacts.js';
+import { resolveTrackerAuthority, chooseTrackerAccess } from '../tracker/capability-protocol.js';
+import { readConfig, readGitRemoteUrls } from '../tracker/project-inputs.js';
+import { cliForgeTransport, httpForgeTransport, forgeEndpointFromRemote } from '../tracker/forge-http.js';
+import { createForgeAuditTracker } from '../tracker/issue-pages.js';
+import { resolveToken } from './live.js';
+import { localIssueRoot } from './local.js';
+import { createLocalAuditTracker } from './audit-local.js';
+import { runIssueAudit, renderIssueAudit, needsAuditContent } from './audit.js';
+import { AuditStop, auditDigest, parseAuditFilter } from './audit-contract.js';
+export async function main(args, cwd = process.cwd(), dependencies = {}) {
+    const output = dependencies.output ?? console.log;
+    let format = 'markdown';
+    try {
+        const { values: v } = parseArgs({ args, strict: true, options: {
+                filter: { type: 'string' }, guidance: { type: 'string' }, provider: { type: 'string' },
+                checkpoint: { type: 'string' }, 'page-size': { type: 'string' }, 'max-items': { type: 'string' }, 'max-pages': { type: 'string' },
+                'max-bytes': { type: 'string' }, 'max-context-bytes': { type: 'string' },
+                select: { type: 'string' }, format: { type: 'string' }, 'all-open': { type: 'boolean' },
+                'dry-run': { type: 'boolean' }, apply: { type: 'boolean' }, interactive: { type: 'boolean' }, help: { type: 'boolean' },
+            } });
+        format = v.format ?? 'markdown';
+        if (!['json', 'markdown'].includes(format))
+            throw new AuditStop('format-invalid');
+        if (v.help) {
+            output('aiwg run skill issue-audit -- [--filter "status:open label:bug"] [--guidance TEXT] [--provider local|gitea|github]\n'
+                + '  [--checkpoint PATH] [--page-size 25] [--max-items 250] [--max-pages 100] [--max-bytes 65536]\n'
+                + '  [--max-context-bytes 262144] [--select ID,ID] [--format json|markdown]\n'
+                + 'Rerun the same scope/checkpoint to resume. Execution is read-only; cleanup decisions use the instructional workflow.');
+            return 0;
+        }
+        if (v.apply || v.interactive)
+            throw new AuditStop('use-instructional-workflow-for-interactive-or-apply');
+        const number = (name, fallback) => {
+            const value = Number(v[name] ?? fallback);
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new AuditStop(`invalid-${name}`);
+            return value;
+        };
+        const pageSize = number('page-size', 25);
+        const maxItems = number('max-items', 250);
+        const maxPages = number('max-pages', 100);
+        const maxBytes = number('max-bytes', 65_536);
+        const maxContextBytes = number('max-context-bytes', 262_144);
+        if (pageSize > 100)
+            throw new AuditStop('invalid-page-size');
+        const config = dependencies.config === undefined ? await readConfig(cwd) : dependencies.config;
+        const authority = resolveTrackerAuthority(config, dependencies.remoteUrls ?? await readGitRemoteUrls(cwd));
+        const provider = v.provider ?? authority.provider;
+        if (provider !== 'local' && provider !== 'gitea' && provider !== 'github')
+            throw new AuditStop('tracker-provider-unresolved');
+        const taxonomy = resolveIssueLabels(config?.issues, provider);
+        if (taxonomy.diagnostics.some(d => d.severity === 'error'))
+            throw new AuditStop('label-taxonomy-invalid');
+        const filter = v.filter ?? 'status:open';
+        const parsedFilter = parseAuditFilter(filter);
+        const nativeFilter = [`status:${parsedFilter.status}`, ...parsedFilter.labels.map(role => `label:${JSON.stringify(taxonomy.labels[role]?.resolved_name ?? role)}`)].join(' ');
+        const selection = v.select === undefined ? null : new Set(v.select.split(',').map(s => s.trim()).filter(Boolean));
+        const checkpoint = v.checkpoint ? resolve(cwd, v.checkpoint) : projectAiwgWritePath(cwd, 'working', 'issue-audit', 'checkpoint.json');
+        const env = dependencies.env ?? process.env;
+        let tracker = dependencies.tracker;
+        if (!tracker) {
+            if (provider === 'local')
+                tracker = createLocalAuditTracker(localIssueRoot(cwd));
+            else {
+                const endpoint = forgeEndpointFromRemote(provider, authority.issueTrackerUrl);
+                if (!endpoint)
+                    throw new AuditStop('tracker-repository-unresolved');
+                const token = resolveToken(provider, env);
+                const access = chooseTrackerAccess({ ...authority, provider }, [
+                    { kind: 'http-api', provider, remoteName: authority.issueTrackerRemote, available: !!token, authenticated: !!token },
+                    { kind: 'cli', provider, remoteName: authority.issueTrackerRemote, available: provider === 'github', cli: 'gh' },
+                ]);
+                const transport = access.kind === 'http-api' && token
+                    ? httpForgeTransport({ provider, apiBaseUrl: endpoint.apiBaseUrl, token, maxResponseBytes: maxBytes })
+                    : access.kind === 'cli' ? cliForgeTransport({ provider, hostname: endpoint.host, maxResponseBytes: maxBytes }) : null;
+                if (!transport)
+                    throw new AuditStop('tracker-no-access-route');
+                tracker = createForgeAuditTracker(provider, endpoint.repository, transport, `${provider}:${endpoint.apiBaseUrl}:${endpoint.repository}:${config?.remotes?.tracker_actor?.login ?? ''}`);
+            }
+        }
+        const nativeTracker = tracker;
+        const semanticTracker = { ...nativeTracker,
+            async listMetadata(options) {
+                const page = await nativeTracker.listMetadata(options);
+                return { ...page, items: page.items.map(i => ({ ...i, labels: [...i.labels,
+                            ...Object.values(taxonomy.labels).filter(l => i.labels.includes(l.resolved_name)).map(l => l.role)] })) };
+            },
+        };
+        const controller = new AbortController();
+        const interrupt = () => controller.abort();
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', interrupt);
+        try {
+            const report = await runIssueAudit(semanticTracker, { checkpoint, pageSize, maxItems, maxPages, maxBytes, maxContextBytes,
+                filter: nativeFilter, guidance: v.guidance, signal: controller.signal,
+                policyKey: auditDigest([selection ? [...selection].sort() : null, taxonomy.labels]),
+                select: i => selection ? selection.has(i.id) : needsAuditContent(i) });
+            output(format === 'json' ? JSON.stringify({ ...report, scope: { provider, filter }, diagnostics: taxonomy.diagnostics })
+                : `${renderIssueAudit(report)}${taxonomy.diagnostics.map(d => `\n${d.severity}: ${d.message}`).join('')}`);
+            return report.coverage.incomplete ? 2 : 0;
+        }
+        finally {
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', interrupt);
+        }
+    }
+    catch (error) {
+        const reason = error instanceof AuditStop ? error.reason : 'audit-error';
+        output(format === 'json' ? JSON.stringify({ mode: 'read-only', coverage: {
+                totalSeen: 0, totalHydrated: 0, totalCompleted: 0, incomplete: true, reason
+            } }) : `# Issue Audit\n\nCoverage: INCOMPLETE (${reason})`);
+        return 2;
+    }
+}
+//# sourceMappingURL=audit-cli.js.map

package/dist/src/issues/audit-contract.js

@@ -0,0 +1,64 @@
+// Shared bounded retrieval and checkpoint envelope for issue-audit backends.
+import { createHash } from 'node:crypto';
+export class AuditStop extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+export const auditBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+export const auditDigest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function boundedPageSize(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 100)
+        throw new AuditStop('invalid-page-size');
+    return value;
+}
+export function encodeAuditCursor(value) {
+    return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+export function decodeAuditCursor(cursor) {
+    try {
+        if (!/^[A-Za-z0-9_-]{1,8192}$/.test(cursor))
+            throw new Error();
+        return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new AuditStop('cursor-invalidated');
+    }
+}
+/** Reject unsupported filters rather than quietly broadening audit coverage. */
+export function parseAuditFilter(expression) {
+    const result = { status: 'open', labels: [] };
+    const tokens = /(?:^|\s+)(status|label):("(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+)/gy;
+    let position = 0;
+    const input = expression.trim();
+    while (position < input.length) {
+        const match = tokens.exec(input);
+        if (!match)
+            throw new AuditStop('filter-invalid');
+        let value = match[2];
+        if (value.startsWith('"')) {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                throw new AuditStop('filter-invalid');
+            }
+        }
+        else if (value.startsWith("'"))
+            value = value.slice(1, -1);
+        if (!value)
+            throw new AuditStop('filter-invalid');
+        if (match[1] === 'status') {
+            if (!['open', 'closed', 'all'].includes(value))
+                throw new AuditStop('filter-invalid');
+            result.status = value;
+        }
+        else
+            result.labels.push(value);
+        position = tokens.lastIndex;
+    }
+    return result;
+}
+//# sourceMappingURL=audit-contract.js.map

package/dist/src/issues/audit-local.js

@@ -0,0 +1,82 @@
+// Adapt the existing local issue index and selective issue reads to the audit envelope.
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { LocalIssueProviderCore } from './local.js';
+import { AuditStop, auditDigest, auditBytes, boundedPageSize, decodeAuditCursor, encodeAuditCursor, parseAuditFilter } from './audit-contract.js';
+export function createLocalAuditTracker(root) {
+    const provider = new LocalIssueProviderCore(root);
+    const identity = `local:${root}`;
+    return {
+        identity,
+        async listMetadata(options) {
+            options.signal?.throwIfAborted();
+            const size = boundedPageSize(options.pageSize);
+            const filter = parseAuditFilter(options.filter);
+            // Hash metadata only. Any changed index invalidates an offset cursor, avoiding silent omissions.
+            const fingerprint = auditDigest(await readFile(join(root, 'index/issues.index.json'), 'utf8'));
+            const scope = auditDigest([identity, size, filter]);
+            const cursor = options.cursor ? decodeAuditCursor(options.cursor) : null;
+            if (options.cursor && (!cursor || typeof cursor !== 'object'))
+                throw new AuditStop('cursor-invalidated');
+            if (cursor && (cursor.scope !== scope || typeof cursor.offset !== 'string' || !/^\d+$/.test(cursor.offset))) {
+                throw new AuditStop('cursor-invalidated');
+            }
+            if (cursor && cursor.fingerprint !== fingerprint)
+                throw new AuditStop('tracker-changed');
+            const result = await provider.listIssues({ limit: size, cursor: cursor?.offset,
+                filter: { status: filter.status === 'all' ? undefined : filter.status, labels: filter.labels } });
+            if (auditDigest(await readFile(join(root, 'index/issues.index.json'), 'utf8')) !== fingerprint)
+                throw new AuditStop('tracker-changed');
+            const items = result.issues.map(i => ({ id: i.id, title: i.title, status: i.status,
+                labels: [...i.labels, i.type, i.priority], updatedAt: i.updated_at }));
+            const bytes = auditBytes(items);
+            if (bytes > options.maxBytes)
+                throw new AuditStop('byte-budget');
+            return { items, bytes, complete: !result.nextCursor,
+                nextCursor: result.nextCursor ? encodeAuditCursor({ scope, fingerprint, offset: result.nextCursor }) : null };
+        },
+        async hydrate(issue, options) {
+            options.signal?.throwIfAborted();
+            if (!/^[A-Z][A-Z0-9]*-\d+$/.test(issue.id))
+                throw new AuditStop('invalid-issue-id');
+            // Preflight the selected files before the existing reader loads any bodies.
+            let bytes = 0;
+            const account = async (file) => {
+                const size = await stat(file).then(s => s.size).catch((error) => {
+                    if (error.code === 'ENOENT')
+                        return 0;
+                    throw error;
+                });
+                bytes += size;
+                if (bytes > options.maxBytes)
+                    throw new AuditStop('byte-budget');
+            };
+            await account(join(root, 'items', `${issue.id}.md`));
+            const eventsPath = join(root, 'events', `${issue.id}.jsonl`);
+            await account(eventsPath);
+            const events = await readFile(eventsPath, 'utf8').catch((error) => {
+                if (error.code === 'ENOENT')
+                    return '';
+                throw error;
+            });
+            for (const line of events.split(/\r?\n/).filter(Boolean)) {
+                const event = JSON.parse(line);
+                if (!event.body_path)
+                    continue;
+                const file = resolve(root, event.body_path);
+                if (!file.startsWith(resolve(root) + sep))
+                    throw new AuditStop('invalid-comment-path');
+                await account(file);
+            }
+            const record = await provider.getIssue(issue.id, { body: true, comments: 'all' });
+            if (record.fields.updated_at !== issue.updatedAt)
+                throw new AuditStop('tracker-changed');
+            const content = { body: record.body, comments: record.events.filter(e => e.type === 'comment').map(e => e.body ?? '') };
+            bytes = Math.max(bytes, auditBytes(content));
+            if (bytes > options.maxBytes)
+                throw new AuditStop('byte-budget');
+            return { ...content, bytes };
+        },
+    };
+}
+//# sourceMappingURL=audit-local.js.map

package/dist/src/issues/audit.js

@@ -0,0 +1,220 @@
+// Execute bounded audit batches with atomic, content-minimized item checkpoints.
+import { readFile } from 'node:fs/promises';
+import { atomicConfigWrite } from '../config/worker-write.js';
+import { acquireDirectoryLock, DirectoryLockContentionError } from '../artifacts/prebuilt-build-lock.js';
+import { ForgeReadError } from '../tracker/forge-http.js';
+import { AuditStop, auditDigest, auditBytes, boundedPageSize, parseAuditFilter, } from './audit-contract.js';
+export const needsAuditContent = (issue) => /\b(epic|deferred|duplicate|superseded|fixed)\b/i.test(`${issue.title} ${issue.labels.join(' ')}`);
+/** Deterministic triage candidates; deeper semantic conclusions belong to the auditor. */
+export function auditFinding(issue, content) {
+    const text = `${issue.title} ${issue.labels.join(' ')}`;
+    const references = content && /(?:#\d+|[A-Z][A-Z0-9]*-\d+)/.test(`${content.body}\n${content.comments.join('\n')}`);
+    if (/\b(blocker|critical|P[01])\b/i.test(text))
+        return { id: issue.id, category: 'High Priority', recommendation: 'Review blocker for address-issues' };
+    if (/\bepic\b/i.test(text))
+        return { id: issue.id, category: 'Epic Hygiene', recommendation: references
+                ? 'Check linked child status and acceptance against current issues' : 'Add child issue references before checking epic completion' };
+    if (/\b(duplicate|overlap)\b/i.test(text))
+        return { id: issue.id, category: 'Duplicate / Relationship Candidates', recommendation: references
+                ? 'Verify overlap with referenced issues before recommending cleanup' : 'Identify a related issue before recommending duplicate cleanup' };
+    if (/\b(deferred|superseded|fixed)\b/i.test(text))
+        return { id: issue.id, category: 'Cleanup Candidates', recommendation: content && !/\b\d{4}-\d{2}-\d{2}\b/.test(`${content.body}\n${content.comments.join('\n')}`)
+                ? 'Add a follow-up date and verify the cleanup decision' : 'Verify cleanup decision and follow-up date' };
+    return { id: issue.id, category: 'Next Actions', recommendation: content && !content.body.trim()
+            ? 'Add issue context and acceptance criteria' : 'Review priority and scope before address-issues' };
+}
+async function loadCheckpoint(file, scope) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return { version: 1, scope, cursor: null, pending: [], pageComplete: false, finished: false,
+            completed: [], findings: [], totalSeen: 0, totalHydrated: 0 };
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new AuditStop('checkpoint-invalid');
+    }
+    if (!value || value.version !== 1 || value.scope !== scope || !Array.isArray(value.completed)
+        || !Array.isArray(value.pending) || !Array.isArray(value.findings)
+        || typeof value.finished !== 'boolean' || typeof value.pageComplete !== 'boolean'
+        || !(value.cursor === null || typeof value.cursor === 'string')
+        || !Number.isSafeInteger(value.totalSeen) || value.totalSeen < 0
+        || !Number.isSafeInteger(value.totalHydrated) || value.totalHydrated < 0
+        || value.totalHydrated > value.completed.length || value.totalSeen < value.completed.length
+        || new Set(value.completed).size !== value.completed.length
+        || value.completed.some(id => typeof id !== 'string')
+        || value.pending.some(i => !i || typeof i.id !== 'string' || typeof i.title !== 'string'
+            || typeof i.status !== 'string' || typeof i.updatedAt !== 'string' || !Array.isArray(i.labels)
+            || i.labels.some(l => typeof l !== 'string') || value.completed.includes(i.id))
+        || new Set(value.pending.map(i => i.id)).size !== value.pending.length
+        || value.totalSeen !== value.completed.length + value.pending.length
+        || (value.finished && (value.pending.length > 0 || !value.pageComplete || value.cursor !== null))
+        || value.findings.length !== value.completed.length
+        || value.findings.some((f, i) => !f || f.id !== value.completed[i] || typeof f.recommendation !== 'string')) {
+        throw new AuditStop(value?.scope !== scope ? 'checkpoint-scope-mismatch' : 'checkpoint-invalid');
+    }
+    return value;
+}
+export async function runIssueAudit(tracker, options) {
+    const pageSize = boundedPageSize(options.pageSize ?? 25);
+    const maxItems = options.maxItems ?? 250;
+    const maxPages = options.maxPages ?? 100;
+    const maxBytes = options.maxBytes ?? 65_536;
+    const maxContext = options.maxContextBytes ?? 262_144;
+    for (const bound of [maxItems, maxPages, maxBytes, maxContext]) {
+        if (!Number.isSafeInteger(bound) || bound < 1)
+            throw new AuditStop('invalid-budget');
+    }
+    const filter = options.filter ?? 'status:open';
+    const guidance = options.guidance ?? '';
+    parseAuditFilter(filter);
+    if ((options.select || options.analyze) && !options.policyKey)
+        throw new AuditStop('policy-key-required');
+    const scope = auditDigest([tracker.identity, filter, guidance, pageSize, options.policyKey ?? 'metadata-triage-v1']);
+    let release;
+    try {
+        release = await acquireDirectoryLock(`${options.checkpoint}.lock`, { timeoutMs: 0, reclaimDeadOwner: true });
+    }
+    catch (error) {
+        if (error instanceof DirectoryLockContentionError)
+            throw new AuditStop('checkpoint-busy');
+        throw error;
+    }
+    try {
+        return await execute();
+    }
+    finally {
+        await release();
+    }
+    async function execute() {
+        let state = await loadCheckpoint(options.checkpoint, scope);
+        let durable = structuredClone(state);
+        const save = async () => {
+            try {
+                await atomicConfigWrite(options.checkpoint, `${JSON.stringify(state)}\n`);
+            }
+            catch {
+                throw new AuditStop('checkpoint-write-error');
+            }
+            durable = structuredClone(state);
+        };
+        const completed = new Set(state.completed);
+        const batches = [];
+        const visited = new Set();
+        let contextBytes = 0;
+        let processed = 0;
+        let reason = null;
+        let batch = { items: 0, bytes: 0 };
+        await save();
+        try {
+            while (!state.finished) {
+                if (options.signal?.aborted)
+                    throw new AuditStop('interrupted');
+                if (processed >= maxItems)
+                    throw new AuditStop('item-budget');
+                if (!state.pending.length) {
+                    if (batches.length >= maxPages)
+                        throw new AuditStop('page-budget');
+                    if (visited.has(state.cursor))
+                        throw new AuditStop('cursor-invalidated');
+                    if (contextBytes >= maxContext)
+                        throw new AuditStop('context-budget');
+                    const available = Math.min(maxBytes, maxContext - contextBytes);
+                    const page = await tracker.listMetadata({ cursor: state.cursor, pageSize, maxBytes: available, filter, signal: options.signal })
+                        .catch(error => { if (error instanceof AuditStop && error.reason === 'byte-budget' && available < maxBytes)
+                        throw new AuditStop('context-budget'); throw error; });
+                    if (page.items.length > pageSize || page.bytes > maxBytes)
+                        throw new AuditStop('byte-budget');
+                    if (page.bytes > maxContext - contextBytes)
+                        throw new AuditStop('context-budget');
+                    if (page.nextCursor !== null && page.nextCursor === state.cursor)
+                        throw new AuditStop('cursor-invalidated');
+                    if (!page.complete && page.nextCursor === null)
+                        throw new AuditStop('pagination-incomplete');
+                    const unique = new Map(page.items.filter(i => !completed.has(i.id)).map(i => [i.id, i]));
+                    visited.add(state.cursor);
+                    state.pending = [...unique.values()];
+                    state.totalSeen += state.pending.length;
+                    state.cursor = page.nextCursor;
+                    state.pageComplete = page.complete;
+                    batch = { items: 0, bytes: page.bytes };
+                    batches.push(batch);
+                    contextBytes += page.bytes;
+                    state.finished = !state.pending.length && state.pageComplete;
+                    await save();
+                    if (!state.pending.length)
+                        continue;
+                }
+                else if (!batches.length) {
+                    batch = { items: 0, bytes: auditBytes(state.pending) };
+                    if (batch.bytes > maxBytes)
+                        throw new AuditStop('byte-budget');
+                    contextBytes += batch.bytes;
+                    batches.push(batch);
+                }
+                const issue = state.pending[0];
+                const metadataBytes = auditBytes(issue);
+                if (contextBytes + metadataBytes > maxContext)
+                    throw new AuditStop('context-budget');
+                let content;
+                if ((options.select ?? needsAuditContent)(issue)) {
+                    const remaining = Math.min(maxBytes - batch.bytes, maxContext - contextBytes - metadataBytes);
+                    if (remaining < 1)
+                        throw new AuditStop(batch.bytes >= maxBytes ? 'byte-budget' : 'context-budget');
+                    content = await tracker.hydrate(issue, { maxBytes: remaining, signal: options.signal })
+                        .catch(error => { if (error instanceof AuditStop && error.reason === 'byte-budget' && remaining < maxBytes - batch.bytes)
+                        throw new AuditStop('context-budget'); throw error; });
+                    if (content.bytes > remaining)
+                        throw new AuditStop('byte-budget');
+                }
+                const finding = (options.analyze ?? auditFinding)(issue, content);
+                if (finding.id !== issue.id)
+                    throw new AuditStop('finding-id-mismatch');
+                state.completed.push(issue.id);
+                completed.add(issue.id);
+                state.findings.push(finding);
+                state.totalHydrated += Number(!!content);
+                state.pending.shift();
+                state.finished = !state.pending.length && state.pageComplete;
+                batch.items++;
+                batch.bytes += content?.bytes ?? 0;
+                contextBytes += metadataBytes + (content?.bytes ?? 0);
+                processed++;
+                await save();
+                options.afterItem?.(issue.id);
+            }
+        }
+        catch (error) {
+            state = durable;
+            reason = options.signal?.aborted ? 'interrupted' : error instanceof AuditStop ? error.reason
+                : error instanceof ForgeReadError ? (error.code === 'oversized' ? 'byte-budget' : `tracker-${error.code}`) : 'tracker-error';
+        }
+        return { mode: 'read-only', guidance,
+            coverage: { totalSeen: state.totalSeen, totalHydrated: state.totalHydrated, totalCompleted: state.completed.length,
+                incomplete: reason !== null || !state.finished, reason },
+            continuation: { checkpoint: options.checkpoint, cursor: state.cursor, pending: state.pending.length },
+            batches, findings: state.findings };
+    }
+}
+export function renderIssueAudit(report) {
+    const { coverage: c } = report;
+    const lines = ['# Issue Audit', '', 'Mode: read-only', `Guidance: ${report.guidance || 'none'}`, '',
+        `Coverage: ${c.incomplete ? `INCOMPLETE (${c.reason ?? 'unfinished'})` : 'complete'}`,
+        `Total seen: ${c.totalSeen}; hydrated: ${c.totalHydrated}; completed: ${c.totalCompleted}`, '', '## Findings'];
+    for (const category of ['High Priority', 'Cleanup Candidates', 'Epic Hygiene', 'Duplicate / Relationship Candidates', 'Next Actions']) {
+        lines.push('', `### ${category}`);
+        for (const finding of report.findings.filter(f => f.category === category))
+            lines.push(`- ${finding.id} — ${finding.recommendation}`);
+    }
+    if (c.incomplete)
+        lines.push('', `Resume with checkpoint: ${report.continuation.checkpoint}`);
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=audit.js.map