@aiwg/cli 2026.9.7 → 2026.9.10

package/dist/src/lint/runner.js

@@ -7,6 +7,7 @@
  * @issue #810
  */
 import fs from 'fs';
+import { spawnSync } from 'child_process';
 import fsp from 'fs/promises';
 import path from 'path';
 import { glob } from 'glob';
@@ -29,6 +30,165 @@ function parseFrontmatter(content) {
     return result;
 }
 const DEFAULT_REFERENCE_PATTERN = '\\bREF-\\d{3,}\\b';
+/**
+ * Phrases that mark an identifier as deliberately absent (#2555). A mention
+ * next to one of these documents a gap rather than pointing at a document, so
+ * it is not an unresolved reference.
+ */
+export const DEFAULT_ABSENCE_MARKERS = [
+    '\\bunallocated\\b',
+    '\\bnot in corpus\\b',
+    '\\bskipped\\b',
+    '\\bretired\\b',
+    '\\bwithdrawn\\b',
+    '\\bdeliberately (?:absent|unallocated|skipped)\\b',
+    '\\bnever (?:allocated|assigned)\\b',
+    '\\bdeduplicat',
+];
+// Deliberately NOT markers: "does not exist", "missing", "no longer exists".
+// Those are how a broken reference is described, not how a corpus records an
+// intentional gap, and treating them as markers would suppress the finding this
+// check exists for.
+/**
+ * Verification targets — things the inducting agent could have checked.
+ *
+ * Requiring one of these is what separates "the agent skipped a cheap check"
+ * from "the paper's own claim is unverified". Only the first is a provenance
+ * gap; the second is legitimate analysis, and #2523 explicitly does not ask
+ * agents to stop declaring limitations. Validated against a 2,544-reference
+ * corpus, where grammar-only matching made ~45% of hits paper-claim prose
+ * ("scaling behavior above 7B is unverified", "Not confirmed (34% vs 51%)").
+ */
+/**
+ * Split a markdown line into clauses.
+ *
+ * Corpus prose keeps whole paragraphs, bullet bodies and changelog table rows on
+ * a single line, so "same line" is far too coarse a scope for relating an
+ * unperformed action to its target. Sentence and cell boundaries are the unit
+ * that actually corresponds to one statement.
+ */
+function splitClauses(line) {
+    return line
+        .split(/(?<=[.;:!?])\s+|\s+\u2014\s+|\s+--\s+|\|/g)
+        .map((c) => c.trim())
+        .filter(Boolean);
+}
+export const DEFAULT_VERIFICATION_TARGETS = [
+    'openreview',
+    '(?:acl )?anthology',
+    'proceedings',
+    'camera[- ]ready',
+    'published version',
+    '\\bPMLR\\b',
+    '\\bDBLP\\b',
+    '\\bOpenAlex\\b',
+    'semantic scholar',
+    '\\bpubpeer\\b',
+    '\\bunpaywall\\b',
+    'retraction|correction notice|expression of concern',
+    'citation (?:census|count)',
+    'influential citation',
+    '\\bPDF\\b',
+    'full[- ]text',
+    '\\be-?print\\b',
+    '(?:code|project|dataset|repository|repo)\\s+(?:page|url|link|release|availability)',
+    '\\bvenue\\b',
+    '\\bacceptance\\b',
+    'source[_ ]type',
+];
+/**
+ * Phrases that assert a check was not performed. Drawn from real induction
+ * output — each of these has appeared in a corpus reference doc (#2523).
+ * Only counted when a verification target appears on the same line.
+ */
+export const DEFAULT_UNCERTAINTY_PATTERNS = [
+    '(?:was|were|is|are) not (?:retrieved|run|performed|attempted|fetched|queried|checked|acquired|probed|verified|confirmed)',
+    'not (?:retrieved|run|performed|attempted|fetched|queried|checked|acquired|probed|verified|confirmed)\\b',
+    // Requires the action to be stated as unperformed. Without the trailing verb
+    // this matched bare "no search" in unrelated prose and scope statements like
+    // "no exhaustive census is claimed", neither of which is a skipped check.
+    'no (?:\\w+[ -]){0,4}(?:quer(?:y|ies)|search|census|fetch|check|lookup|probe)(?:es|s)?\\s+(?:was |were )?(?:performed|run|attempted|made|conducted|executed)',
+    '\\b(?:is|remains) unverified\\b',
+    '\\bunconfirmed\\b',
+    'rests on .{0,60} rather than an independent',
+];
+/**
+ * A dated outcome closes an uncertainty (#2523's "records an outcome with a
+ * date"). The vocabulary is deliberately wider than a verb+date pair: the
+ * retraction convention recommended alongside this rule writes
+ * `~~<limitation>~~ **Done YYYY-MM-DD (<what closed it>).**`, which no
+ * verb+date pattern matches, so a correctly dated retraction was rejected for
+ * its shape (#2556).
+ */
+export const DATED_OUTCOME_PATTERN = '(?:\\b(?:done|resolved|completed|closed|addressed|fixed|verified|retrieved|archived|queried|fetched|checked|probed|confirmed)\\b[^\\n]{0,60}?\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}[^\\n]{0,30}?\\b(?:done|resolved|completed|closed|addressed|fixed)\\b)';
+/**
+ * The closure half of {@link DATED_OUTCOME_PATTERN}. Only explicit closure
+ * verbs count outside a struck span: a date sitting anywhere near an action
+ * verb ("...was not retrieved at induction. Induction ran 2026-09-01.") is not
+ * an outcome, and treating it as one would discharge the very statements this
+ * rule exists to catch.
+ */
+export const CLOSURE_OUTCOME_PATTERN = '(?:\\b(?:done|resolved|completed|closed|addressed|fixed)\\b[^\\n]{0,60}?\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}[^\\n]{0,30}?\\b(?:done|resolved|completed|closed|addressed|fixed)\\b)';
+/**
+ * Spans struck through with `~~…~~` are, by the markup's own meaning, no longer
+ * asserted. When a dated outcome follows the span on the same line, the pair is
+ * a completed retraction however long the struck text is — the length of the
+ * struck span was the hidden variable behind #2556.
+ */
+function retractedWithDatedOutcome(line) {
+    const dated = new RegExp(DATED_OUTCOME_PATTERN, 'i');
+    const strikethrough = /~~([\s\S]*?)~~/g;
+    let match;
+    while ((match = strikethrough.exec(line)) !== null) {
+        if (dated.test(line.slice(match.index + match[0].length)))
+            return true;
+    }
+    return false;
+}
+/** Character offsets of every `~~…~~` span on a line. */
+function strikethroughSpans(line) {
+    const spans = [];
+    const strikethrough = /~~([\s\S]*?)~~/g;
+    let match;
+    while ((match = strikethrough.exec(line)) !== null) {
+        spans.push({ start: match.index, end: match.index + match[0].length });
+    }
+    return spans;
+}
+export const DEFAULT_OBSTACLE_PATTERNS = [
+    '\\bHTTP\\s?[45]\\d{2}\\b',
+    '\\b(?:401|403|404|429|451|503)\\b',
+    'paywall',
+    'closed[- ]access',
+    'requires? (?:a )?(?:credential|token|API key|subscription|login|account)',
+    '\\b(?:HF_TOKEN|API[_ ]KEY)\\b',
+    'rate[- ]limit',
+    'anti[- ]bot',
+    'cloudflare',
+    'captcha',
+    'endpoint unknown',
+    'no (?:known )?endpoint',
+    // Obstacle vocabulary observed in a real corpus: these are named obstacles,
+    // so the statement is already a real outcome rather than a silent skip.
+    'proof[- ]of[- ]work',
+    'challenge (?:artifact|page|response)',
+    'returned challenge',
+    '\\bgated\\b',
+    'did not render',
+    'green OA',
+    // Explicit scope declarations: saying what is deliberately not claimed is an
+    // outcome, unlike omitting the check and not saying so.
+    'is not (?:claimed|asserted)',
+    'NOT (?:recorded|asserted) as',
+    'evidence boundary',
+    'completion_evidence',
+    'status:\\s*(?:incomplete|blocked)',
+    '\\b(?:queried|fetched|checked|probed|confirmed|resolved)\\s+(?:on\\s+)?\\d{4}-\\d{2}-\\d{2}',
+    '\\bdeferred\\b.{0,40}\\b(?:because|since|due to)\\b',
+    // An explicit dated closure ("**Done 2026-09-12 (post-induction audit).**"),
+    // which the verb+date pattern above does not match (#2556).
+    CLOSURE_OUTCOME_PATTERN,
+];
 /**
  * Build a target-wide artifact ID index once per lint run.
  *
@@ -117,11 +277,19 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             const refPattern = check.referencePattern || DEFAULT_REFERENCE_PATTERN;
             const regex = new RegExp(refPattern, 'g');
             const lines = content.split('\n');
+            const absence = (check.absenceMarkers ?? DEFAULT_ABSENCE_MARKERS).map((p) => new RegExp(p, 'i'));
             for (let i = 0; i < lines.length; i++) {
                 let match;
                 while ((match = regex.exec(lines[i])) !== null) {
                     const refId = match[0];
                     const basePath = check.basePath || '.aiwg/research/findings';
+                    // A corpus documents its deliberate gaps ("REF-2464 remains
+                    // unallocated after deduplication"). Reading that sentence as a
+                    // dangling reference left only two ways to silence an error: delete
+                    // accurate documentation, or allocate a REF that is deliberately
+                    // absent (#2555).
+                    if (absence.some((re) => re.test(lines[i])))
+                        continue;
                     if (!referenceIndex.has(refId) && !resolvesFromBasePath(refId, targetDir, basePath)) {
                         diagnostics.push({
                             ruleId: '',
@@ -136,6 +304,59 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
             }
             break;
         }
+        case 'unregistered-uncertainty': {
+            // An uncertainty written only into prose is invisible to the verification
+            // contract: it was never a declared check, so it never surfaces as
+            // `incomplete` and the "never report skipped verification as success" rule
+            // is never violated. Flag the bare form; accept it once a specific
+            // obstacle is named or an outcome is recorded (#2523).
+            const uncertainty = (check.uncertaintyPatterns ?? DEFAULT_UNCERTAINTY_PATTERNS)
+                .map((p) => new RegExp(p, 'i'));
+            const targets = (check.verificationTargets ?? DEFAULT_VERIFICATION_TARGETS)
+                .map((p) => new RegExp(p, 'i'));
+            const obstacle = (check.obstaclePatterns ?? DEFAULT_OBSTACLE_PATTERNS)
+                .map((p) => new RegExp(p, 'i'));
+            const within = check.obstacleWithinLines ?? 2;
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                // Both conditions must hold in the SAME CLAUSE: an unperformed action
+                // AND something the agent could have acted on. Without the target, the
+                // match is as likely to be the paper's own limitation, which must stay
+                // untouched. Without clause scoping, a long markdown line relates two
+                // unrelated clauses — real corpus prose puts whole paragraphs and
+                // changelog tables on one line, which produced most false positives.
+                const clause = splitClauses(lines[i]).find((c) => uncertainty.some((re) => re.test(c)) && targets.some((re) => re.test(c)));
+                if (!clause)
+                    continue;
+                // A struck span followed by a dated outcome is a completed retraction,
+                // whatever its length. Clause scoping otherwise ends the window before
+                // the `**Done <date>**` that closes it, so the recommended convention
+                // failed for two-sentence struck text and passed for one (#2556).
+                const clauseAt = lines[i].indexOf(clause);
+                const struck = clauseAt >= 0 && strikethroughSpans(lines[i])
+                    .some((span) => clauseAt >= span.start && clauseAt < span.end);
+                if (struck && retractedWithDatedOutcome(lines[i]))
+                    continue;
+                // Look in the matching line and the following `within` lines: the
+                // obstacle normally sits in the same sentence or the next one.
+                const window = lines.slice(i, i + within + 1).join(' ');
+                if (obstacle.some((re) => re.test(window)))
+                    continue;
+                diagnostics.push({
+                    ruleId: '',
+                    ruleName: '',
+                    // Left unset so the rule's declared severity applies (see runRule).
+                    // This is a prose heuristic, so the shipped rule declares `warn`; an
+                    // operator can raise it to error once a corpus is clean.
+                    severity: undefined,
+                    file: filePath,
+                    line: i + 1,
+                    message: `Uncertainty stated without a named obstacle or recorded outcome: ${clause.trim().slice(0, 160)}`,
+                    fix: 'Resolve it if it costs about one request against a known endpoint, or name the specific obstacle (HTTP status, credential required, rate limited, paywalled) so it lands as incomplete/blocked rather than narrative. If the check has since been done, retract the statement with the dated form — `~~<original limitation>~~ **Done YYYY-MM-DD (<what closed it>).** <evidence>` — which closes it whatever the length of the struck text.',
+                });
+            }
+            break;
+        }
         case 'pattern-match': {
             if (!check.pattern)
                 break;
@@ -223,16 +444,44 @@ function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, re
     }
     return diagnostics;
 }
+/**
+ * Candidate paths a rule glob may be written against (#2555).
+ *
+ * `collectFiles` walks with `cwd: targetDir`, so files arrive target-relative
+ * (`REF-001.md`) while rule globs are written repo-relative
+ * (`documentation/references/**\/*.md`). Narrowing the target to the very
+ * directory a rule names therefore matched nothing, and the run reported PASS
+ * with every finding unreported. Matching against the target-relative path and
+ * each ancestor-prefixed form makes a glob resolve the same way wherever the
+ * walk is rooted.
+ */
+export function ruleMatchCandidates(file, targetDir) {
+    const normalizedFile = file.replace(/\\/g, '/');
+    const candidates = [normalizedFile];
+    const segments = path.resolve(targetDir).replace(/\\/g, '/').split('/').filter(Boolean);
+    let prefix = '';
+    for (let i = segments.length - 1; i >= 0 && segments.length - i <= 12; i -= 1) {
+        prefix = prefix ? `${segments[i]}/${prefix}` : `${segments[i]}/`;
+        candidates.push(`${prefix}${normalizedFile}`);
+    }
+    return candidates;
+}
+/** True when a rule's glob selects this file, wherever the walk was rooted. */
+export function ruleAppliesToFile(ruleGlob, file, targetDir) {
+    return ruleMatchCandidates(file, targetDir).some((candidate) => minimatch(candidate, ruleGlob));
+}
 /**
  * Run a single rule against all matching files in the target
  */
 async function runRule(rule, targetDir, allFiles, referenceIndex) {
     const diagnostics = [];
+    RULE_APPLIED.delete(rule.id);
     // Filter files matching the rule's glob
     const ruleGlob = rule.appliesTo.glob;
-    const matchingFiles = allFiles.filter(f => minimatch(f, ruleGlob));
+    const matchingFiles = allFiles.filter(f => ruleAppliesToFile(ruleGlob, f, targetDir));
     if (matchingFiles.length === 0)
         return diagnostics;
+    RULE_APPLIED.add(rule.id);
     // Handle id-unique check at the ruleset level
     const uniqueCheck = rule.checks.find(c => c.type === 'id-unique');
     if (uniqueCheck) {
@@ -278,10 +527,12 @@ async function runRule(rule, targetDir, allFiles, referenceIndex) {
     }
     return diagnostics;
 }
+/** Rule ids that selected at least one file in the current run (#2555). */
+const RULE_APPLIED = new Set();
 /**
  * Collect all files under a target directory
  */
-async function collectFiles(targetDir, recursive) {
+async function collectFiles(targetDir, recursive, respectGitignore = true) {
     const pattern = recursive ? '**/*' : '*';
     try {
         const files = await glob(pattern, {
@@ -289,12 +540,44 @@ async function collectFiles(targetDir, recursive) {
             nodir: true,
             dot: false,
         });
-        return files.filter(f => f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'));
+        const linted = files.filter(f => f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'));
+        return respectGitignore ? dropGitignored(targetDir, linted) : linted;
     }
     catch {
         return [];
     }
 }
+/**
+ * Drop files git ignores (#2555).
+ *
+ * Generated trees are regenerated, not authored: linting `indices/` reported an
+ * error in text that documents a deliberate gap. `git check-ignore` is asked
+ * once for the whole set so the semantics are git's own (negations, nested
+ * `.gitignore`, `core.excludesFile`) rather than a re-implementation. Outside a
+ * repository, or without git, every file is kept.
+ */
+function dropGitignored(targetDir, files) {
+    if (files.length === 0)
+        return files;
+    try {
+        const result = spawnSync('git', ['check-ignore', '--stdin'], {
+            cwd: targetDir,
+            input: `${files.join('\n')}\n`,
+            encoding: 'utf8',
+        });
+        // 0 = some paths ignored, 1 = none ignored, anything else = not a repo or
+        // git unavailable, in which case nothing is filtered.
+        if (result.error || (result.status !== 0 && result.status !== 1))
+            return files;
+        const ignored = new Set((result.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean));
+        if (ignored.size === 0)
+            return files;
+        return files.filter((file) => !ignored.has(file));
+    }
+    catch {
+        return files;
+    }
+}
 /**
  * Auto-detect which rulesets apply to a target path
  *
@@ -326,12 +609,17 @@ function autoDetectRulesets(target, available) {
  */
 export async function runLint(targetDir, rulesets, options = {}) {
     const recursive = options.recursive ?? true;
-    const allFiles = await collectFiles(targetDir, recursive);
+    const allFiles = await collectFiles(targetDir, recursive, options.respectGitignore ?? true);
     const referenceIndex = buildReferenceIndex(allFiles);
     const allDiagnostics = [];
+    const inapplicableRules = [];
+    let rulesSelected = 0;
     for (const ruleset of rulesets) {
         for (const rule of ruleset.rules) {
+            rulesSelected += 1;
             const diagnostics = await runRule(rule, targetDir, allFiles, referenceIndex);
+            if (!RULE_APPLIED.has(rule.id))
+                inapplicableRules.push(rule.id);
             allDiagnostics.push(...diagnostics);
         }
     }
@@ -356,6 +644,11 @@ export async function runLint(targetDir, rulesets, options = {}) {
             warnings,
             infos,
             passed,
+            // A run where no rule selected a file must never read the same as a clean
+            // run (#2555). Reporters surface this; callers can gate on it.
+            rulesSelected,
+            rulesApplied: rulesSelected - inapplicableRules.length,
+            inapplicableRules,
         },
         timestamp: new Date().toISOString(),
     };

package/dist/src/policy/authorization.js

@@ -113,7 +113,7 @@ export function evaluateAuthorization(model, request) {
 }
 export function validateAuthorization(model) {
     if (!model)
-        return [{ severity: 'warning', code: 'authorization-missing', message: 'No normalized authorization block; run steward permissions audit.' }];
+        return [{ severity: 'warning', code: 'authorization-missing', message: 'No normalized authorization block; default deny applies. Write one with `aiwg steward permissions migrate --apply`.' }];
     const out = [];
     if (model.version !== '1')
         out.push({ severity: 'error', code: 'version', message: `Unsupported authorization version: ${model.version}` });