@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/artifacts/citation-parser.js

@@ -22,6 +22,7 @@
  * @tests @test/unit/artifacts/citation-parser.test.ts
  */
 import { parseFrontmatter } from './index-builder.js';
+import { CITATION_HEADER_ALIASES, CITATION_SECTION_ALIASES } from './citation-table-schema.js';
 /**
  * Match a single node identifier (REF-* or PROF-*) anywhere in a string.
  * Used by `extractRefsFromTable` to pull every ID out of a table cell.
@@ -33,31 +34,71 @@ const NODE_ID_PATTERN = /(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)/g;
  * frontmatter `ref` values.
  */
 const NODE_ID_FULL = /^(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)$/;
-/** Explicit column aliases used by historical citation-sidecar variants. */
-const CITATION_REF_COLUMNS = [
-    'Inducted REF',
-    'REF',
-    'Corpus REF',
-    'In-corpus REF',
-];
-/**
- * Preserve the corpus snapshot's legacy edge semantics: every node ID on a
- * pipe-delimited line inside an outgoing/incoming section is a declaration.
- * Explicit column parsing remains the primary path, while this compatibility
- * scan covers malformed rows and prose continuations that historical corpus
- * snapshots already count.
- */
-function extractSectionNodeIds(section) {
-    const refs = [];
-    for (const line of section.split('\n')) {
-        if (!line.includes('|'))
-            continue;
-        NODE_ID_PATTERN.lastIndex = 0;
-        const matches = line.match(NODE_ID_PATTERN);
-        if (matches)
-            refs.push(...matches);
+/** An unnamed resolution cell must contain only one REF, optionally decorated. */
+function standaloneRef(value) {
+    let text = value.trim();
+    const link = text.match(/^\[([^\]]+)\]\([^\s]+(?:\s+"[^"\n]*")?\)$/);
+    if (link)
+        text = link[1].trim();
+    const code = text.match(/^`([^`]+)`$/);
+    if (code)
+        text = code[1].trim();
+    return /^REF-\d+[a-z]?$/.test(text) ? text : null;
+}
+/** Resolution aliases are shared by every registered bibliographic form. */
+const CITATION_REF_COLUMNS = CITATION_HEADER_ALIASES.ref;
+const HEADER_ROLES = new Map(Object.entries(CITATION_HEADER_ALIASES).flatMap(([role, aliases]) => aliases.map(alias => [alias, role])));
+function normalizeCell(value) {
+    return value.toLowerCase().replace(/[`*_]/g, '').replace(/\s+/g, ' ').trim();
+}
+/** Direction belongs to the heading, never to a mention in its section body. */
+function citationDirection(heading) {
+    const text = normalizeCell(heading.replace(/[ \t]+#+[ \t]*$/, ''));
+    const segment = text.split(/[/—:(]/, 1)[0].trim();
+    // Keep the corpus's Incoming/Outgoing descriptions, with a word boundary
+    // so unrelated words such as "Incomingish" cannot declare citations.
+    if (/^incoming(?:\s|$)/.test(segment))
+        return 'incoming';
+    if (/^outgoing(?:\s|$)/.test(segment))
+        return 'outgoing';
+    for (const direction of ['incoming', 'outgoing']) {
+        if (CITATION_SECTION_ALIASES[direction].some(alias => text === alias
+            || (text.startsWith(alias) && /^\s*[/—:(]/.test(text.slice(alias.length)))))
+            return direction;
     }
-    return [...new Set(refs)];
+    return null;
+}
+/** Explicitly non-bibliographic or uncertain declarations must not assert citations. */
+function isNonCitation(value) {
+    const text = normalizeCell(value);
+    // An explicit disavowal wins even when the description also says "cites".
+    if (/\b(?:topical|thematic|non[- ]citations?|methodological cousin|unverified)\b/.test(text)
+        || /\bnot (?:(?:a|an) )?(?:(?:verified|formal|directly) )?(?:citations?|cites?|cited|verified)\b/.test(text)
+        || /\bno (?:formal |verified )?citations?\b/.test(text)
+        || /\b(?:if|unless|provided that|assuming)\s+(?:ref-\d+|prof-[pofg]-|present\b)/.test(text)
+        || /\bconditional (?:on|upon)\b/.test(text)
+        || /^(?:conditional|related)(?:\s+only)?\s*(?:[(:;—-]|$)/.test(text))
+        return true;
+    // "Cites X in Related Work", "cites-related-version", and citations to a
+    // paper named "Conditional Memory" describe real citations, not qualifiers.
+    if (/\b(?:cites?|cited|citing)\b/.test(text))
+        return false;
+    return /\brelated\b/.test(text);
+}
+/** Table/section declarations, rather than incidental mentions in audit prose. */
+function isNonCitationContext(value) {
+    // Candidate-specific audit prose does not disavow the surrounding tables.
+    // Keep whole-table declarations separate from notes about particular REFs.
+    const text = value.replace(/<!--[\s\S]*?-->/g, '').toLowerCase().replace(/[`*_]/g, '').split('\n')
+        .filter(line => !/\b(?:search results|external .*?candidates?|historical records)\b/.test(line))
+        .filter(line => !/(?:ref-\d+|prof-[pofg]-)/.test(line)
+        || /\b(?:rows|tables?|relationships?|connections?) (?:below|are|only)\b/.test(line))
+        .join('\n');
+    return /(?:^|\n)\s*(?:related|topical|thematic) works[^\n]*\b(?:do|does) not (?:directly )?cite\b/.test(text)
+        || /\b(?:no (?:formal|verified) citations?|not (?:(?:asserted|verified) )?citation (?:edges?|rows?)|relationship notes|related corpus nodes)\b/.test(text)
+        || /\bno citations\s*(?:[.!;]|$)/.test(text)
+        || /\b(?:topical|thematic|related|conditional|non-citation) (?:relationships?|connections?|only)\b/.test(text)
+        || /(?:^|\n)\s*(?:topical|thematic|related|conditional|non-citation)(?:\s+(?:relationships?|connections?|notes|rows|only))?\s*(?:$|\n)/.test(text);
 }
 /**
  * Test whether a string is a valid sidecar node identifier.
@@ -73,75 +114,102 @@ export function isNodeId(value) {
  * Extract node identifiers from a markdown table column.
  *
  * Scans table rows for a column matching `columnName` (case-insensitive)
- * and extracts node IDs (REF-* or PROF-*), skipping empty/dash values.
+ * and extracts node IDs (REF-* or PROF-*) only from that cell. Malformed
+ * tables/rows and explicit non-citation qualifiers are skipped.
  *
  * @param tableText - Markdown table text (header + separator + rows)
  * @param columnName - Column header to extract from (e.g., "Inducted REF")
  * @returns Array of node identifiers found
  */
 export function extractRefsFromTable(tableText, columnName) {
-    const aliases = (Array.isArray(columnName) ? columnName : [columnName])
-        .map(name => name.trim().toLowerCase());
-    const tableBlocks = [];
-    let currentBlock = [];
-    for (const line of tableText.split('\n')) {
-        if (line.trim().startsWith('|')) {
-            currentBlock.push(line);
-        }
-        else if (currentBlock.length > 0) {
-            tableBlocks.push(currentBlock);
-            currentBlock = [];
-        }
-    }
-    if (currentBlock.length > 0)
-        tableBlocks.push(currentBlock);
-    const parseRow = (line) => {
-        let row = line.trim();
-        if (row.startsWith('|'))
-            row = row.slice(1);
-        if (row.endsWith('|'))
-            row = row.slice(0, -1);
-        return row.split('|').map(cell => cell.trim());
-    };
+    return extractTableRefs(tableText, columnName, false);
+}
+function extractTableRefs(tableText, columnName, bibliographicOnly) {
+    const aliases = (typeof columnName === 'string' ? [columnName] : columnName)
+        .map(normalizeCell);
+    const parseRow = (line) => line.trim().replace(/^\|/, '').replace(/\|$/, '').split(/(?<!\\)\|/)
+        .map(cell => cell.replace(/\\\|/g, '|').trim());
+    const lines = tableText.split('\n');
+    const headings = [];
+    let preamble = [];
     const refs = [];
-    for (const lines of tableBlocks) {
-        const headerCells = parseRow(lines[0]);
-        const colIndex = headerCells.findIndex(header => {
-            const normalized = header.toLowerCase().replace(/[`*_]/g, '').trim();
-            return aliases.some(alias => normalized === alias ||
-                normalized.startsWith(`${alias} /`) ||
-                normalized.startsWith(`${alias} (`));
-        });
-        if (lines.length < 3 || colIndex === -1) {
-            // Legacy sidecars sometimes have headerless continuation rows or a
-            // generic table whose rows were extended with a final REF cell. The
-            // corpus snapshot has always treated every in-section table REF as an
-            // outgoing/incoming declaration, so retain that compatibility fallback.
-            const dataLines = lines.length >= 3 ? lines.slice(2) : lines;
-            for (const line of dataLines) {
-                NODE_ID_PATTERN.lastIndex = 0;
-                const refMatches = line.match(NODE_ID_PATTERN);
-                if (refMatches)
-                    refs.push(...refMatches);
-            }
+    for (let i = 0; i < lines.length; i++) {
+        const heading = lines[i].match(/^ {0,3}(#{1,6})[ \t]+(.+)/);
+        if (heading) {
+            // A parent section's declaration also governs its nested tables.
+            const parent = headings[headings.length - 1];
+            if (parent && parent.level < heading[1].length)
+                parent.text += `\n${preamble.join('\n')}`;
+            while (headings.length && headings[headings.length - 1].level >= heading[1].length)
+                headings.pop();
+            headings.push({ level: heading[1].length, text: heading[2] });
+            preamble = [];
+            continue;
+        }
+        if (!lines[i].trim().startsWith('|')) {
+            preamble.push(lines[i]);
             continue;
         }
-        // Skip this table's header and separator, preserving all interior cells.
-        for (let i = 2; i < lines.length; i++) {
-            const cells = parseRow(lines[i]);
-            if (colIndex >= cells.length)
+        const table = [];
+        while (i < lines.length && lines[i].trim().startsWith('|'))
+            table.push(lines[i++]);
+        i--;
+        const context = [...headings.map(h => h.text), ...preamble];
+        preamble = [];
+        // A trailing note can explicitly disavow the preceding table's citations.
+        const following = [];
+        for (let j = i + 1; j < lines.length && !/^\s*[#|]/.test(lines[j]); j++)
+            following.push(lines[j]);
+        if (/^\s*note\b/im.test(following.join('\n')))
+            context.push(...following);
+        if (isNonCitationContext(context.join('\n')) || table.length < 3)
+            continue;
+        const headers = parseRow(table[0]).map(normalizeCell);
+        if (headers.some(isNonCitation))
+            continue;
+        const separator = parseRow(table[1]);
+        if (separator.length !== headers.length || !separator.every(cell => /^:?-{3,}:?$/.test(cell)))
+            continue;
+        const roles = headers.map(header => HEADER_ROLES.get(header));
+        // Incoming/Outgoing declares the direction; the named resolution header
+        // identifies the target when present. Otherwise whole-cell REF IDs
+        // resolve rows. Additional metadata and column order do not change
+        // those semantics. Multiple resolution columns are ambiguous.
+        if (bibliographicOnly && roles.filter(role => role === 'ref').length > 1)
+            continue;
+        // For graph extraction the headers register exactly one resolution
+        // column when present. The generic column helper still honors its explicit alias order.
+        const colIndex = bibliographicOnly
+            ? roles.indexOf('ref')
+            : aliases.map(alias => headers.indexOf(alias)).find(index => index !== -1) ?? -1;
+        if (colIndex === -1 && !bibliographicOnly)
+            continue;
+        for (const line of table.slice(2)) {
+            const cells = parseRow(line);
+            // Extra/missing cells have no unambiguous column semantics. Never guess.
+            if (cells.length !== headers.length)
+                continue;
+            // A resolution explicitly labelled as context/adjacency does not map
+            // the printed entry to that node (corpus Formal References variants).
+            if (colIndex !== -1
+                && /\b(?:REF-\d+[a-z]?|PROF-[POFG]-[a-z0-9-]+)\s+(?:(?:family )?context|adjacent)\b/i.test(normalizeCell(cells[colIndex])))
                 continue;
-            // Historical rows may expand the named REF cell into an issue/REF pair
-            // or append placeholder cells without extending the header. Scan from
-            // the named column through the remainder of the row; columns before the
-            // alias (title/authors/year) remain excluded.
-            const value = cells.slice(colIndex).join(' | ');
-            if (!value || value === '—' || value === '-' || value === '–')
+            // A condition can also qualify the printed title, as in the downstream
+            // "Learning is Forgetting (if REF-828 in 6-benchmark suite)" row.
+            if (cells.some(cell => /\b(?:if|unless|provided that|assuming)\s+[`*_[\s]*(?:REF-\d+|PROF-[POFG]-)/i.test(cell)))
                 continue;
-            NODE_ID_PATTERN.lastIndex = 0;
-            const refMatches = value.match(NODE_ID_PATTERN);
-            if (refMatches)
-                refs.push(...refMatches);
+            const qualifiers = cells.filter((_, index) => (bibliographicOnly && colIndex === -1) || index === colIndex
+                || ['notes', 'evidence', 'context', 'kind', 'relationship', 'status'].includes(roles[index] ?? '')
+                || (!bibliographicOnly && !['#', 'title', 'work', 'authors', 'year', 'doi/url', 'doi', 'url'].includes(headers[index])));
+            if (qualifiers.some(isNonCitation))
+                continue;
+            // Without a named resolution column, only whole-cell REF IDs resolve.
+            // Named columns always take precedence over incidental IDs elsewhere.
+            const matches = colIndex === -1
+                ? cells.map(standaloneRef).filter((ref) => ref !== null)
+                : cells[colIndex].match(NODE_ID_PATTERN);
+            if (matches)
+                refs.push(...matches);
         }
     }
     return [...new Set(refs)];
@@ -149,6 +217,12 @@ export function extractRefsFromTable(tableText, columnName) {
 /**
  * Parse a citation sidecar markdown file into structured edges.
  *
+ * Tables in recognized directional or reference sections declare citations through a unique
+ * registered resolution column, or whole-cell REF IDs when no such column
+ * exists, independent of other metadata columns.
+ * Topical, related, conditional and explicitly non-citation declarations are
+ * skipped; they do not produce citation edges or new relationship types.
+ *
  * @param content - Full markdown content of the sidecar file
  * @returns Parse result with ref ID and edge arrays, or null if not a valid sidecar
  */
@@ -158,22 +232,29 @@ export function parseCitationSidecar(content) {
     const ref = typeof data.ref === 'string' ? data.ref : null;
     if (!ref || !NODE_ID_FULL.test(ref))
         return null;
-    // Split body into sections by ## headings
-    const sections = body.split(/^## /m).filter(Boolean);
+    // ATX level-two headings allow indentation, tabs and closing hashes.
+    const sectionHeading = /^ {0,3}##[ \t]+([^\r\n]+)/m;
+    const sections = body.split(/(?=^ {0,3}##[ \t]+)/m).filter(Boolean);
+    const preamble = sectionHeading.test(sections[0] ?? '') ? '' : sections[0] ?? '';
+    if (isNonCitationContext(preamble.replace(/^#+ .*$/gm, '')))
+        return { ref, cites: [], citedBy: [] };
     let cites = [];
     let citedBy = [];
     for (const section of sections) {
-        const sectionLower = section.toLowerCase();
-        if (sectionLower.startsWith('outgoing')) {
-            cites.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
-            cites.push(...extractSectionNodeIds(section));
+        const heading = section.match(sectionHeading);
+        const direction = heading ? citationDirection(heading[1]) : null;
+        if (direction === 'outgoing') {
+            cites.push(...extractTableRefs(section, CITATION_REF_COLUMNS, true));
         }
-        else if (sectionLower.startsWith('incoming')) {
-            citedBy.push(...extractRefsFromTable(section, CITATION_REF_COLUMNS));
-            citedBy.push(...extractSectionNodeIds(section));
+        else if (direction === 'incoming') {
+            citedBy.push(...extractTableRefs(section, CITATION_REF_COLUMNS, true));
         }
     }
-    return { ref, cites: [...new Set(cites)], citedBy: [...new Set(citedBy)] };
+    return {
+        ref,
+        cites: [...new Set(cites)].filter(target => target !== ref),
+        citedBy: [...new Set(citedBy)].filter(source => source !== ref),
+    };
 }
 /**
  * Convert a CitationParseResult into TypedEdge arrays for the dependency graph.

package/dist/src/artifacts/citation-table-schema.js

@@ -0,0 +1,59 @@
+/**
+ * Registered column aliases for citation-sidecar edge extraction.
+ *
+ * Based on the research-papers corpus table contract
+ * (scripts/corpus/citation-sidecar.schema.json, schemaVersion 1). A unique
+ * resolution header identifies the target cell in Incoming/Outgoing tables.
+ * Without one, a whole-cell REF ID can resolve a row.
+ * Other columns supply metadata or explicit qualifiers that disavow citations;
+ * they do not need to follow an enumerated table shape.
+ */
+/** Direction names used as whole headings or before /, —, :, or (. */
+export const CITATION_SECTION_ALIASES = {
+    incoming: ['cited-by', 'cited by', 'papers that cite this work', 'sources that cite this work', 'works that cite this work'],
+    outgoing: [
+        'cites', 'references', 'papers this work cites', 'sources this work cites', 'works this work cites',
+        'formal / high-value references extracted',
+        'formal / high-value references and benchmarks extracted',
+        'formal references extracted from the card',
+        'formal references extracted from the addendum / parent card',
+        'high-value references and benchmarks',
+        'foundational external citations',
+    ],
+};
+export const CITATION_HEADER_ALIASES = {
+    ordinal: ['#', 'bibliography #', 'label', 'row', 'original label', '# (arxiv)'],
+    title: [
+        'title', 'citing work', 'cited work', 'citation', 'citation (extracted)', 'title / source',
+        'title / work', 'title / source bibliographic entry', 'citation as printed (normalized whitespace)',
+        'citation as printed or faithfully transcribed', 'cited source / concept',
+        'mentioned work / cluster', 'work cited / discussed', 'source', 'artifact', 'title / referent',
+        'work / cluster', 'source-reported reference', 'title / source label', 'title / target', 'entry',
+        'reference', 'reference (as printed, cvpr 2026 camera-ready)', 'reference (as printed, arxiv v2)',
+    ],
+    authors: [
+        'authors', 'authors / publisher', 'organization', 'party', 'authors / project', 'author(s)',
+        'authors / attributed entity', 'authors (as printed)', 'author or owner', 'authors / org',
+    ],
+    year: ['year'],
+    locator: [
+        'doi/url', 'doi / url', 'url', 'identifier', 'venue / doi / url', 'doi/url/venue', 'venue / url',
+        'doi/url or venue', 'venue / id', 'venue / identifier', 'identifier / url', 'venue / doi',
+    ],
+    ref: [
+        'inducted ref', 'corpus node', 'corpus ref', 'in-corpus ref', 'ref', 'citing ref', 'ref / issue',
+        'in-corpus ref / issue', 'corpus id',
+    ],
+    context: ['context', 'where it appears'],
+    notes: ['notes', 'note', 'rationale', 'why the guarded matcher missed it'],
+    evidence: [
+        'source evidence', 'in-text evidence', 'provenance', 'evidence', 'basis', 'verification',
+        'confirmed by',
+    ],
+    'their-row': ['their row', '[ref]', 'row in its sidecar'],
+    venue: ['venue'],
+    kind: ['kind', 'type', 'nature'],
+    relationship: ['relationship', 'relation', 'relationship (conceptual, not citation-grounded)'],
+    status: ['mapping status', 'status', 'mapping'],
+};
+//# sourceMappingURL=citation-table-schema.js.map

package/dist/src/artifacts/cli.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { GRAPH_CONFIGS, OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadUserGraphConfigs, loadGlobalGraphConfigs, orderedGraphEntries, } from './types.js';
+import { resolveIndexWorkers } from './index-preparation.js';
 import { SUPPORTED_VIEWS } from './corpus-views/renderers.js';
 import { parseResourceSelector, readVerifiedRegularFile, } from '../resources/web-release.js';
 import { findPackageRoot } from '../cli/find-package-root.js';
@@ -213,6 +214,15 @@ export async function main(args) {
         process.exit(0);
     }
     switch (subcommand) {
+        case 'refresh': {
+            if (subcommandArgs.includes('--help') || subcommandArgs.includes('-h')) {
+                printIndexUsage();
+                break;
+            }
+            const { runIndexRefresh } = await import('./index-refresh.js');
+            await runIndexRefresh(subcommandArgs);
+            break;
+        }
         case 'build':
             await handleBuild(subcommandArgs);
             break;
@@ -288,15 +298,16 @@ export async function main(args) {
             break;
         default:
             console.error(`Error: Unknown index subcommand '${subcommand}'`);
-            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, eval-discovery, watch');
+            console.log('Available: build, refresh, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, eval-discovery, watch');
             process.exit(1);
     }
 }
-function printIndexUsage() {
+export function printIndexUsage() {
     console.log('Usage: aiwg index <subcommand> [options]');
     console.log('');
     console.log('Available subcommands:');
     console.log('  build      Build/rebuild the artifact index');
+    console.log('  refresh    Safely refresh graphs, caches, sessions, runtime, models, and local issues');
     console.log('  query      Search artifacts by keyword, type, phase, tags');
     console.log('  discover   Capability search across operational asset types (#1214)');
     console.log('  show       Print the full text of a specific operational asset');
@@ -315,12 +326,23 @@ function printIndexUsage() {
     console.log('  watch      Start a filesystem watcher for automatic incremental index updates');
     console.log('');
     console.log('Options:');
+    console.log('  build [--force] [--verbose] [--all] [--scope <dir>] [--graph <name>]');
+    console.log('  refresh [--full] [--workspace <path>]... [--root <dir>]...');
+    console.log('          [--only graphs|sessions|caches|runtime|models|issues] [--dry-run] [--json] [--lock-wait-ms <n>]');
+    console.log('          [--max-record-bytes <n>] [--max-source-bytes <n>]');
+    console.log('  Session import defaults: 67108864 bytes per record, 1073741824 bytes (1 GiB) per source; source 0 is unlimited.');
+    console.log('  --exclude <id-or-glob> (repeatable): skip session IDs or absolute path globs; adds to sessions.import.exclude and AIWG_SESSIONS_IMPORT_EXCLUDE (comma-separated).');
+    console.log('  Import limits: CLI flag > AIWG_SESSIONS_IMPORT_MAX_RECORD_BYTES / AIWG_SESSIONS_IMPORT_MAX_SOURCE_BYTES > workspace config > default.');
+    console.log('  build/refresh --index-workers <n>: preparation processes (0 = serial); flag > AIWG_INDEX_WORKERS > automatic CPU/memory limits.');
+    console.log('  sync [--backend fortemi-core] [--graph <name> | --all] [--repo <name>]');
+    console.log('       [--privacy private|sanitized|public] [--generated-at <iso>] [--json]');
     console.log('  --graph <name>  Target a specific graph (framework, project, codebase, source, user, or user-defined)');
     console.log('  --all           Build all known graphs (including user-defined)');
     console.log('');
     console.log('Examples:');
     console.log('  aiwg index build');
     console.log('  aiwg index build --all');
+    console.log('  aiwg index refresh --root ~/dev --json');
     console.log('  aiwg index build --graph codebase --force');
     console.log('  aiwg index discover "create intake"');
     console.log('  aiwg index discover "deploy production" --limit 5 --json');
@@ -483,10 +505,13 @@ async function handleBuild(args) {
         console.log('Usage: aiwg index build [options]');
         console.log('');
         console.log('Options:');
+        console.log('  --index-workers <n> Preparation processes (0 = serial); overrides AIWG_INDEX_WORKERS');
         console.log('  --force          Full rebuild (ignore checksums, re-index everything)');
         console.log('  --verbose        Show detailed progress during indexing');
         console.log('  --all            Build all known graphs (including user-defined)');
         console.log('  --scope <dir>    Limit scan to a specific subdirectory');
+        console.log('  --include-ignored Include gitignored sources (runtime directories stay excluded)');
+        console.log('  Source discovery skips symlinks and .aiwg/{working,sessions,scratch,tmp,temp,cache,.index,.cache,.storage-cache}/.');
         console.log('  --graph <name>   Build a specific graph only (built-in or user-defined)');
         console.log('');
         console.log('Built-in graph names: project, codebase, source, user, framework');
@@ -508,6 +533,15 @@ async function handleBuild(args) {
         console.log('  aiwg index sync --all');
         return;
     }
+    let workers;
+    try {
+        workers = resolveIndexWorkers(parseFlagValue(args, '--index-workers', 'Error: --index-workers requires a value'));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+        return;
+    }
     // Dynamic import to keep the CLI router lightweight
     const { buildIndex } = await import('./index-builder.js');
     const cwd = process.cwd();
@@ -516,6 +550,7 @@ async function handleBuild(args) {
     const force = args.includes('--force');
     const verbose = args.includes('--verbose');
     const all = args.includes('--all');
+    const includeIgnored = args.includes('--include-ignored');
     const graph = parseGraphFlag(args);
     let scope;
     const scopeIdx = args.indexOf('--scope');
@@ -531,7 +566,7 @@ async function handleBuild(args) {
         // --graph X: build the JSON graph if X is one; otherwise X may be a
         // research-corpus markdown view, rendered below.
         if (graph in GRAPH_CONFIGS) {
-            await buildIndex(cwd, { force, verbose, scope, graph, explicit: true });
+            await buildIndex(cwd, { force, verbose, scope, includeIgnored, workers, graph, explicit: true });
             jsonBuilt = true;
             builtGraphs.add(graph);
         }
@@ -539,7 +574,7 @@ async function handleBuild(args) {
     else if (all) {
         // Build all known graphs — user asked for everything, but don't hard-error on missing dirs
         for (const [name] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
-            await buildIndex(cwd, { force, verbose, graph: name, explicit: false });
+            await buildIndex(cwd, { force, verbose, includeIgnored, workers, graph: name, explicit: false });
             builtGraphs.add(name);
         }
         jsonBuilt = true;
@@ -548,7 +583,7 @@ async function handleBuild(args) {
         // Default: build graphs with defaultBuild=true; skip gracefully if their dirs don't exist
         for (const [name, config] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
             if (config.defaultBuild) {
-                await buildIndex(cwd, { force, verbose, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
+                await buildIndex(cwd, { force, verbose, includeIgnored, workers, scope: name === Object.keys(GRAPH_CONFIGS)[0] ? scope : undefined, graph: name, explicit: false });
                 builtGraphs.add(name);
             }
         }
@@ -589,18 +624,18 @@ async function syncFortemiCoreCachesAfterBuild(cwd, graphs, verbose) {
     const { syncFortemiCoreIndex } = await import('./fortemi-core-sync.js');
     const { loadGraphIndexFile } = await import('./index-reader.js');
     for (const graph of graphs) {
-        // Some default-build graphs skip cleanly when their scan roots are absent.
-        // Only materialize a cache when this build left an actual source index.
-        if (!loadGraphIndexFile(cwd, 'metadata.json', graph))
-            continue;
         try {
+            // Some auto-selected graphs skip cleanly when their scan roots are absent.
+            if (!loadGraphIndexFile(cwd, 'metadata.json', graph))
+                continue;
             const manifest = syncFortemiCoreIndex(cwd, { graph });
             if (verbose) {
                 console.log(`Fortemi Core ${graph} sync: ${manifest.status}, ${manifest.item_count} item(s) → ${manifest.export_path}`);
             }
         }
         catch (err) {
-            console.error(`Warning: Fortemi Core ${graph} sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+            console.error(`Error: Fortemi Core ${graph} sync failed: ${err instanceof Error ? err.message : String(err)}`);
             console.error(`Run \`aiwg index sync --graph ${graph}\` before using Fortemi-backed commands for '${graph}' artifacts.`);
         }
     }
@@ -1099,19 +1134,30 @@ async function handleSync(args) {
         if (all) {
             const { loadGraphIndexFile } = await import('./index-reader.js');
             const manifests = [];
+            const failures = [];
             for (const [name] of orderedGraphEntries(Object.entries(GRAPH_CONFIGS))) {
-                if (!loadGraphIndexFile(cwd, 'metadata.json', name))
-                    continue;
-                manifests.push(syncFortemiCoreIndex(cwd, { ...options, graph: name }));
+                try {
+                    if (!loadGraphIndexFile(cwd, 'metadata.json', name))
+                        continue;
+                    manifests.push(syncFortemiCoreIndex(cwd, { ...options, graph: name }));
+                }
+                catch (err) {
+                    failures.push({ graph: name, status: 'failed', error: err instanceof Error ? err.message : String(err) });
+                }
             }
+            if (failures.length)
+                process.exitCode = 1;
             if (json) {
-                console.log(JSON.stringify({ manifests }, null, 2));
+                console.log(JSON.stringify({ manifests, failures }, null, 2));
                 return;
             }
-            console.log(`Fortemi Core sync: ${manifests.length} graph(s)`);
+            console.log(`Fortemi Core sync: ${manifests.length} graph(s) succeeded, ${failures.length} failed`);
             for (const manifest of manifests) {
                 console.log(`  ${manifest.graph}: ${manifest.status}, ${manifest.item_count} item(s) → ${manifest.export_path}`);
             }
+            for (const failure of failures) {
+                console.error(`  ${failure.graph}: failed — ${failure.error}`);
+            }
             return;
         }
         const manifest = syncFortemiCoreIndex(cwd, {
@@ -1480,7 +1526,7 @@ async function handleDiscover(args) {
  * artifact by type and name.
  *
  * Shape (#1218):
- *   aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core]
+ *   aiwg show <type> <name> [--json] [--first] [--bound-rule-bodies] [--graph <name>] [--backend local|fortemi-core]
  *
  * Type is positional (not a flag) so the verb reads as
  * "show <kind> <name>". `<type>` is one of the operational show types.
@@ -1504,8 +1550,8 @@ async function handleShow(args) {
     }
     const HELP_TEXT = [
         '',
-        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
-        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
+        'Usage: aiwg show <type> <name> [--json] [--first] [--bound-rule-bodies] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
+        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--bound-rule-bodies] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
         '       aiwg index show <type> <name> ...',
         '',
         `Types: ${OPERATIONAL_SHOW_TYPES.join(' | ')}`,
@@ -1521,6 +1567,10 @@ async function handleShow(args) {
         '  aiwg show command discover',
         '  aiwg show skill intake-wizard --resource-source web --aiwg-version stable',
         '',
+        'Bound rules: summaries and show pointers are appended for bound skills, agents, and flows.',
+        'Fetch and follow every required_rule_checks entry before starting governed work; summaries do not replace full rules.',
+        'Use --bound-rule-bodies to include their full text (JSON: bound_rules[].content).',
+        '',
         'Tip: use `aiwg discover "<phrase>" --json` first to find the stable id.',
     ].join('\n');
     if (positional.length === 0) {
@@ -1584,6 +1634,7 @@ async function handleShow(args) {
         : webReleaseOptionsFromEnvironment();
     const params = {
         name,
+        boundRuleBodies: flags.includes('--bound-rule-bodies'),
         typeFilter: type ? [type] : undefined,
         json,
         first,

package/dist/src/artifacts/corpus-tools/snapshot.js

@@ -238,7 +238,7 @@ export function computeSnapshot(root, options = {}) {
         if (r.year)
             years.push(r.year);
         inc(sourceTypes, r.sourceType || 'other');
-        const grade = r.radar?.gradeCurrent?.trim().toUpperCase();
+        const grade = r.grade?.trim().toUpperCase();
         if (!grade)
             grades.Missing++;
         else if (CONTROLLED_GRADES.includes(grade))

package/dist/src/artifacts/corpus-tools/vision-extract.js

@@ -60,6 +60,7 @@ const codexAdapter = {
                 // function's own documented default (see extractPages() below).
                 timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000),
                 encoding: 'utf8',
+                killSignal: 'SIGKILL',
             });
             if (r.status === 0 && fs.existsSync(tmp)) {
                 const text = fs.readFileSync(tmp, 'utf8');
@@ -174,6 +175,7 @@ function commandAdapter(template) {
                 const r = spawnSync('sh', ['-c', cmd, 'aiwg-vision', imagePath, promptFile, out], {
                     timeout: positiveTimeoutMs(ctx.timeoutSec * 1000, 240_000), encoding: 'utf8',
                     env: { ...process.env, AIWG_VISION_IMAGE: imagePath, AIWG_VISION_PROMPT_FILE: promptFile, AIWG_VISION_OUT: out },
+                    killSignal: 'SIGKILL',
                 });
                 let text;
                 if (fs.existsSync(out))