aiwg 2026.7.3 → 2026.7.5

package/README.md

@@ -13,6 +13,11 @@ npm i -g aiwg        # install globally
 aiwg use sdlc        # deploy SDLC framework
 ```
 
+Then ask your AI assistant to set up the project for AIWG. The agent-led setup
+conversation should establish remotes, issue storage, delivery behavior,
+signing policy, and provider choices; the assistant may call `aiwg setup project`
+as the underlying CLI helper.
+
 macOS users: if npm fails with `EACCES` under `/usr/local/lib/node_modules`,
 use the [macOS Install Guide](docs/getting-started/macos-install.md).
 Agents and stewards setting up AIWG end-to-end should use the
@@ -133,7 +138,8 @@ The user surface is the conversation with your AI tool. You install AIWG, deploy
 The CLI exists mostly for the agent to call under the hood. The commands a user typically runs by hand are a short list:
 
 - `aiwg use <framework>` — deploy AIWG to your project (one-time per framework, per project)
-- `aiwg wizard` — guided first-run setup
+- Project setup agent/skill — recommended guided setup conversation for repo, tracker, delivery, signing, and provider policy
+- `aiwg wizard` — guided first-run goal routing
 - `aiwg new <project>` — scaffold a new project
 - `aiwg status` — what's deployed and engaged in this workspace
 - `aiwg doctor` — health check

package/dist/src/artifacts/browser-export.js

@@ -65,6 +65,7 @@ function relationshipsForEntry(entry, graph, recordTypesByPath) {
             source_path: edge.path,
             target_path: edge.path,
             direction: prefix,
+            metadata: Object.fromEntries(Object.entries(edge).filter(([key]) => key !== "path" && key !== "type")),
         });
     };
     for (const edge of edges.upstream)
@@ -125,6 +126,20 @@ function recordTypeForEntry(entry, schemaVersion) {
             return "aiwg.memory.entry";
         case "issue":
             return "aiwg.issue";
+        case "source.file":
+            return "aiwg.source.file";
+        case "source.module":
+            return "aiwg.source.module";
+        case "source.package":
+            return "aiwg.source.package";
+        case "source.builtin":
+            return "aiwg.source.builtin";
+        case "source.asset":
+            return "aiwg.source.asset";
+        case "source.unresolved":
+            return "aiwg.source.unresolved";
+        case "source.entrypoint":
+            return "aiwg.source.entrypoint";
         default:
             if (pathText.includes("/research/references/") ||
                 /^ref[-_]/i.test(entry.name ?? entry.title))

package/dist/src/artifacts/cli.js

@@ -16,7 +16,7 @@
  * @source @src/cli/handlers/subcommands.ts
  * @tests @test/unit/artifacts/cli.test.ts
  */
-import { GRAPH_CONFIGS, loadUserGraphConfigs } from './types.js';
+import { GRAPH_CONFIGS, loadUserGraphConfigs, loadGlobalGraphConfigs } from './types.js';
 import { SUPPORTED_VIEWS } from './corpus-views/renderers.js';
 /** Parse --graph flag from args, returns undefined for "all graphs" */
 function parseGraphFlag(args) {
@@ -30,6 +30,7 @@ function parseGraphFlag(args) {
     const val = args[idx + 1];
     // Load user-defined graphs so validation is complete
     loadUserGraphConfigs(process.cwd());
+    loadGlobalGraphConfigs();
     if (val in GRAPH_CONFIGS)
         return val;
     // Corpus markdown views (#1490) are valid --graph targets for `index build`.
@@ -135,6 +136,9 @@ export async function main(args) {
         case 'sync':
             await handleSync(subcommandArgs);
             break;
+        case 'migrate-legacy':
+            await handleMigrateLegacy(subcommandArgs);
+            break;
         case 'deps':
             await handleDeps(subcommandArgs);
             break;
@@ -186,7 +190,7 @@ export async function main(args) {
             break;
         default:
             console.error(`Error: Unknown index subcommand '${subcommand}'`);
-            console.log('Available: build, query, discover, show, export, sync, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, watch');
+            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, watch');
             process.exit(1);
     }
 }
@@ -200,6 +204,7 @@ function printIndexUsage() {
     console.log('  show       Print the full text of a specific skill/agent/command/rule');
     console.log('  export     Export a browser-consumable index contract');
     console.log('  sync       Materialize the Fortemi Core static index cache');
+    console.log('  migrate-legacy  Move legacy root indexes into graph sidecar indexes');
     console.log('  deps       Show artifact dependency graph');
     console.log('  stats      Show index statistics');
     console.log('  status     Enumerate the index-graph registry (freshness + drift); alias: list');
@@ -211,7 +216,7 @@ function printIndexUsage() {
     console.log('  watch      Start a filesystem watcher for automatic incremental index updates');
     console.log('');
     console.log('Options:');
-    console.log('  --graph <name>  Target a specific graph (framework, project, codebase, or user-defined)');
+    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:');
@@ -225,6 +230,7 @@ function printIndexUsage() {
     console.log('  aiwg index show skill flow-deploy-to-production --json');
     console.log('  aiwg index show agent aiwg-steward');
     console.log('  aiwg index export --format fortemi --graph project --out aiwg-fortemi-index.json');
+    console.log('  aiwg index migrate-legacy --scope project --dry-run');
     console.log('  aiwg index query "authentication" --type use-case');
     console.log('  aiwg index query "security rules" --graph framework --json');
     console.log('  aiwg index query "mixture of experts" --fulltext --graph papers   # body text, BM25');
@@ -332,7 +338,7 @@ async function handleBuild(args) {
         console.log('  --scope <dir>    Limit scan to a specific subdirectory');
         console.log('  --graph <name>   Build a specific graph only (built-in or user-defined)');
         console.log('');
-        console.log('Built-in graph names: project, codebase, framework');
+        console.log('Built-in graph names: project, codebase, source, user, framework');
         console.log('User-defined graphs: configure under index.graphs in .aiwg/aiwg.config');
         console.log('');
         console.log('Default behavior (no --graph): builds all graphs with defaultBuild: true');
@@ -342,6 +348,8 @@ async function handleBuild(args) {
         console.log('  aiwg index build');
         console.log('  aiwg index build --force');
         console.log('  aiwg index build --graph codebase --force');
+        console.log('  aiwg index build --graph source --force');
+        console.log('  aiwg index build --graph user --force');
         console.log('  aiwg index build --graph references            # user-defined graph');
         console.log('  aiwg index build --scope documentation/references');
         console.log('  aiwg index build --all');
@@ -363,6 +371,7 @@ async function handleBuild(args) {
     }
     // Load user-defined graphs
     loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
     let jsonBuilt = false;
     if (graph) {
         // --graph X: build the JSON graph if X is one; otherwise X may be a
@@ -821,6 +830,83 @@ async function handleSync(args) {
         process.exit(1);
     }
 }
+/**
+ * Handle 'index migrate-legacy' command.
+ */
+async function handleMigrateLegacy(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('Usage: aiwg index migrate-legacy [--scope project|user|global | --all] [options]');
+        console.log('');
+        console.log('Migrates compatible legacy root index files into graph sidecar index');
+        console.log('directories. Project scope moves .aiwg/.index/*.json to');
+        console.log('.aiwg/.index/project/*.json and refreshes the Fortemi Core static');
+        console.log('cache. User/global scopes report or migrate their corresponding');
+        console.log('sidecar locations without modifying packaged/prebuilt AIWG indexes.');
+        console.log('');
+        console.log('Options:');
+        console.log('  --scope <name>         Scope to migrate: project, user, or global (default: project)');
+        console.log('  --all                  Migrate project, user, and global scopes');
+        console.log('  --dry-run              Print planned changes without writing files');
+        console.log('  --no-fortemi-sync      Do not refresh the project Fortemi Core static cache');
+        console.log('  --generated-at <iso>   Override generated timestamp for deterministic fixtures');
+        console.log('  --json                 Print the migration report as JSON');
+        console.log('');
+        console.log('Examples:');
+        console.log('  aiwg index migrate-legacy --scope project --dry-run');
+        console.log('  aiwg index migrate-legacy --all --json');
+        return;
+    }
+    const all = args.includes('--all');
+    const scopeValue = parseFlagValue(args, '--scope', 'Error: --scope requires project, user, or global');
+    if (all && scopeValue) {
+        console.error('Error: pass either --all or --scope, not both');
+        process.exit(1);
+    }
+    const allowedScopes = ['project', 'user', 'global'];
+    const scopes = all
+        ? [...allowedScopes]
+        : scopeValue
+            ? [scopeValue]
+            : ['project'];
+    const invalidScope = scopes.find((scope) => !allowedScopes.includes(scope));
+    if (invalidScope) {
+        console.error('Error: --scope must be project, user, or global');
+        process.exit(1);
+    }
+    const generatedAt = parseFlagValue(args, '--generated-at', 'Error: --generated-at requires an ISO timestamp value');
+    const { migrateLegacyIndex } = await import('./legacy-index-migration.js');
+    try {
+        const report = migrateLegacyIndex(process.cwd(), {
+            scopes: scopes,
+            dryRun: args.includes('--dry-run'),
+            syncFortemi: !args.includes('--no-fortemi-sync'),
+            generatedAt,
+        });
+        if (args.includes('--json')) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log(`Legacy index migration ${report.dryRun ? '(DRY RUN)' : 'complete'}`);
+        for (const result of report.results) {
+            const entries = result.entries === null ? 'unknown' : String(result.entries);
+            const detail = result.reason ? ` — ${result.reason}` : '';
+            console.log(`  ${result.scope}: ${result.status} (${entries} entries)${detail}`);
+            for (const file of result.files) {
+                console.log(`    ${file.name}: ${file.status}`);
+            }
+            if (result.fortemiCore) {
+                console.log(`    fortemi-core: ${result.fortemiCore.status} (${result.fortemiCore.itemCount} item(s)) → ${result.fortemiCore.exportPath}`);
+            }
+        }
+        if (report.reportPath) {
+            console.log(`  report: ${report.reportPath}`);
+        }
+    }
+    catch (err) {
+        console.error('Error: ' + (err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+}
 /**
  * Handle 'index deps' command
  *

package/dist/src/artifacts/fortemi-core-sync.js

@@ -1,9 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
+import { GRAPH_CONFIGS, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
 import { loadGraphIndexFile } from "./index-reader.js";
 function syncDir(cwd, graph) {
+    loadGlobalGraphConfigs();
+    const config = GRAPH_CONFIGS[graph];
+    if (graph === "framework" || config?.shared) {
+        const xdgData = process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? cwd, ".local", "share");
+        return path.join(xdgData, "aiwg", "index", "fortemi-core", graph);
+    }
     return path.join(cwd, ".aiwg", ".index", "fortemi-core", graph);
 }
 function findPackageRoot(startDir) {

package/dist/src/artifacts/index-builder.js

@@ -13,10 +13,29 @@ import fs from 'fs';
 import path from 'path';
 import { createHash } from 'crypto';
 import { load as loadYaml } from 'js-yaml';
-import { INDEX_VERSION, INDEX_DIR, PHASE_DIRECTORIES, GRAPH_CONFIGS, loadUserGraphConfigs } from './types.js';
+import { INDEX_VERSION, INDEX_DIR, PHASE_DIRECTORIES, GRAPH_CONFIGS, loadUserGraphConfigs, loadGlobalGraphConfigs } from './types.js';
 import { parseCitationSidecar, citationResultToEdges, buildRefToPathMap } from './citation-parser.js';
 import { writeIndexFile, resolveIndexDir, loadGraphIndexFile } from './index-reader.js';
 import { loadManifest, writeManifest, statMatches, makeEntry } from './checksum-manifest.js';
+function expandScanDir(cwd, scanDir) {
+    if (scanDir === '~')
+        return process.env.HOME ?? scanDir;
+    if (scanDir.startsWith('~/')) {
+        return path.join(process.env.HOME ?? '', scanDir.slice(2));
+    }
+    if (path.isAbsolute(scanDir))
+        return scanDir;
+    return path.join(cwd, scanDir);
+}
+function indexPathFor(cwd, fullPath) {
+    const rel = path.relative(cwd, fullPath);
+    if (!rel.startsWith('..') && !path.isAbsolute(rel))
+        return rel;
+    return fullPath;
+}
+function absoluteEntryPath(cwd, entryPath) {
+    return path.isAbsolute(entryPath) ? entryPath : path.join(cwd, entryPath);
+}
 /**
  * Parse YAML frontmatter from markdown content
  */
@@ -498,6 +517,7 @@ export async function buildIndex(cwd, options = {}) {
     const startTime = Date.now();
     // Ensure user-defined graphs are loaded
     loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
     // Determine scan directories based on graph type
     const graphConfig = graph ? GRAPH_CONFIGS[graph] : undefined;
     let scanDirs;
@@ -508,7 +528,7 @@ export async function buildIndex(cwd, options = {}) {
         fileExtensions = ['.md', '.yaml', '.json'];
     }
     else if (graphConfig) {
-        scanDirs = graphConfig.scanDirs.map(d => path.join(cwd, d));
+        scanDirs = graphConfig.scanDirs.map(d => expandScanDir(cwd, d));
         fileExtensions = graphConfig.extensions;
     }
     else {
@@ -548,6 +568,19 @@ export async function buildIndex(cwd, options = {}) {
     fs.mkdirSync(indexOutputDir, { recursive: true });
     // effectiveOutputCwd is used for backward-compat loadMetadataIndex calls
     const effectiveOutputCwd = outputDir ?? cwd;
+    if (graph === 'source') {
+        const { buildSourceGraphIndex } = await import('./source-graph.js');
+        await buildSourceGraphIndex({
+            cwd,
+            outputDir: indexOutputDir,
+            effectiveOutputCwd,
+            verbose,
+        });
+        const buildTimeMs = Date.now() - startTime;
+        console.log(`Source graph built in ${buildTimeMs}ms`);
+        console.log(`  Output: ${INDEX_DIR}/source/`);
+        return;
+    }
     // Load existing index for incremental updates
     const existingIndex = force ? null : loadGraphIndexFile(effectiveOutputCwd, 'metadata.json', graph);
     const existingEntries = existingIndex?.entries ?? {};
@@ -577,7 +610,7 @@ export async function buildIndex(cwd, options = {}) {
     let unchangedCount = 0;
     const useFilenameMetadata = graphConfig?.nodeStrategy === 'filename-metadata';
     for (const fullPath of files) {
-        const relativePath = path.relative(cwd, fullPath);
+        const relativePath = indexPathFor(cwd, fullPath);
         let entry;
         if (useFilenameMetadata) {
             // Filename-metadata strategy: derive metadata from filename, skip content read.
@@ -728,7 +761,7 @@ export async function buildIndex(cwd, options = {}) {
         // Build REF-XXX → path map from all entries with ref frontmatter
         const entryFrontmatter = new Map();
         for (const entryPath of Object.keys(entries)) {
-            const fullPath = path.join(cwd, entryPath);
+            const fullPath = absoluteEntryPath(cwd, entryPath);
             if (fs.existsSync(fullPath)) {
                 const content = fs.readFileSync(fullPath, 'utf-8');
                 const { data } = parseFrontmatter(content);
@@ -739,7 +772,7 @@ export async function buildIndex(cwd, options = {}) {
         // Parse each entry as a citation sidecar and extract edges
         let citationEdgeCount = 0;
         for (const entryPath of Object.keys(entries)) {
-            const fullPath = path.join(cwd, entryPath);
+            const fullPath = absoluteEntryPath(cwd, entryPath);
             if (!fs.existsSync(fullPath))
                 continue;
             const content = fs.readFileSync(fullPath, 'utf-8');
@@ -848,7 +881,7 @@ export async function buildIndex(cwd, options = {}) {
             console.log(`  Pruned ${manifestStats.pruned} stale manifest entries (files no longer on disk)`);
         }
     }
-    const displayDir = graph ? `${INDEX_DIR}/${graph}/` : `${INDEX_DIR}/`;
+    const displayDir = graph ? indexOutputDir : `${INDEX_DIR}/`;
     console.log(`  Output: ${displayDir}`);
 }
 //# sourceMappingURL=index-builder.js.map

package/dist/src/artifacts/index-status.js

@@ -18,7 +18,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, loadUserGraphConfigs, } from './types.js';
+import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, loadGlobalGraphConfigs, loadUserGraphConfigs, } from './types.js';
 import { getFortemiCoreSyncStatus, } from './fortemi-core-sync.js';
 function readBuiltMeta(indexDir) {
     try {
@@ -47,6 +47,7 @@ export function collectIndexStatus(cwd, nowMs) {
     // instead of letting malformed defs vanish (#1624).
     const warnings = [];
     loadUserGraphConfigs(cwd, warnings);
+    loadGlobalGraphConfigs(warnings);
     const now = nowMs ?? Date.now();
     const graphs = [];
     for (const [name, config] of Object.entries(GRAPH_CONFIGS)) {

package/dist/src/artifacts/legacy-index-migration.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { INDEX_VERSION, getGraphIndexDir } from './types.js';
+import { syncFortemiCoreIndex } from './fortemi-core-sync.js';
+const INDEX_FILES = ['metadata.json', 'tags.json', 'dependencies.json', 'stats.json'];
+function sha256File(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+function readJson(filePath) {
+    try {
+        return { value: JSON.parse(fs.readFileSync(filePath, 'utf-8')), reason: null };
+    }
+    catch (err) {
+        return {
+            value: null,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function resolveHome(options) {
+    return options.homeDir ?? process.env.AIWG_HOME ?? os.homedir();
+}
+function resolveXdgData(options) {
+    return options.xdgDataHome ?? process.env.XDG_DATA_HOME ?? path.join(resolveHome(options), '.local', 'share');
+}
+function scopePaths(cwd, scope, options) {
+    switch (scope) {
+        case 'project':
+            return {
+                sourceDir: path.join(cwd, '.aiwg', '.index'),
+                destinationDir: getGraphIndexDir(cwd, 'project'),
+                syncRoot: cwd,
+                graph: 'project',
+            };
+        case 'user': {
+            const home = resolveHome(options);
+            return {
+                sourceDir: path.join(home, '.aiwg', '.index'),
+                destinationDir: path.join(home, '.aiwg', '.index', 'user'),
+                syncRoot: null,
+                graph: 'user',
+            };
+        }
+        case 'global': {
+            const xdg = resolveXdgData(options);
+            return {
+                sourceDir: path.join(xdg, 'aiwg', 'index'),
+                destinationDir: path.join(xdg, 'aiwg', 'index', 'global'),
+                syncRoot: null,
+                graph: 'global',
+            };
+        }
+    }
+}
+function validateLegacyMetadata(sourceDir) {
+    const metadataPath = path.join(sourceDir, 'metadata.json');
+    if (!fs.existsSync(metadataPath)) {
+        return { index: null, reason: 'metadata.json not found' };
+    }
+    const parsed = readJson(metadataPath);
+    if (!parsed.value) {
+        return { index: null, reason: `metadata.json is unreadable: ${parsed.reason}` };
+    }
+    if (parsed.value.version !== INDEX_VERSION) {
+        return {
+            index: null,
+            reason: `metadata.json schema version ${String(parsed.value.version ?? 'missing')} is not compatible with ${INDEX_VERSION}`,
+        };
+    }
+    if (!parsed.value.entries || typeof parsed.value.entries !== 'object' || Array.isArray(parsed.value.entries)) {
+        return { index: null, reason: 'metadata.json entries must be an object' };
+    }
+    return { index: parsed.value, reason: null };
+}
+function migrateOneScope(cwd, scope, options) {
+    const { sourceDir, destinationDir, syncRoot, graph } = scopePaths(cwd, scope, options);
+    const baseResult = {
+        scope,
+        sourceDir,
+        destinationDir,
+        status: 'skipped',
+        files: [],
+        entries: null,
+        reason: null,
+        fortemiCore: null,
+    };
+    if (!fs.existsSync(sourceDir)) {
+        return { ...baseResult, reason: 'legacy index directory not found' };
+    }
+    if (path.resolve(sourceDir) === path.resolve(destinationDir)) {
+        return {
+            ...baseResult,
+            reason: 'source and destination are the same directory; no migration needed',
+        };
+    }
+    const validation = validateLegacyMetadata(sourceDir);
+    if (!validation.index) {
+        return {
+            ...baseResult,
+            status: 'needs-rebuild',
+            reason: validation.reason,
+        };
+    }
+    let changed = false;
+    let anyCreated = false;
+    for (const name of INDEX_FILES) {
+        const sourcePath = path.join(sourceDir, name);
+        const destinationPath = path.join(destinationDir, name);
+        if (!fs.existsSync(sourcePath)) {
+            baseResult.files.push({ name, status: 'skipped' });
+            continue;
+        }
+        const sourceHash = sha256File(sourcePath);
+        const destinationHash = sha256File(destinationPath);
+        const exists = destinationHash !== null;
+        const same = sourceHash !== null && sourceHash === destinationHash;
+        const status = same ? 'unchanged' : exists ? 'updated' : 'created';
+        baseResult.files.push({ name, status });
+        if (!same) {
+            changed = true;
+            if (!exists)
+                anyCreated = true;
+            if (!options.dryRun) {
+                fs.mkdirSync(destinationDir, { recursive: true });
+                fs.copyFileSync(sourcePath, destinationPath);
+            }
+        }
+    }
+    baseResult.entries = Object.keys(validation.index.entries).length;
+    baseResult.status = changed ? (anyCreated ? 'created' : 'updated') : 'unchanged';
+    if (!options.dryRun && options.syncFortemi !== false && syncRoot) {
+        const manifest = syncFortemiCoreIndex(syncRoot, {
+            graph,
+            generatedAt: options.generatedAt,
+        });
+        baseResult.fortemiCore = {
+            status: manifest.status,
+            exportPath: manifest.export_path,
+            itemCount: manifest.item_count,
+        };
+    }
+    return baseResult;
+}
+function defaultReportPath(cwd) {
+    return path.join(cwd, '.aiwg', '.index', 'migrations', 'legacy-index-migration.json');
+}
+export function migrateLegacyIndex(cwd, options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const scopes = options.scopes?.length ? options.scopes : ['project'];
+    const results = scopes.map((scope) => migrateOneScope(cwd, scope, { ...options, generatedAt }));
+    const report = {
+        schemaVersion: 'aiwg.legacy-index-migration.v1',
+        dryRun: options.dryRun === true,
+        generatedAt,
+        results,
+        reportPath: options.dryRun ? null : defaultReportPath(cwd),
+    };
+    if (!options.dryRun) {
+        const reportPath = defaultReportPath(cwd);
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+        fs.writeFileSync(reportPath, JSON.stringify(report, null, 2) + '\n', 'utf-8');
+    }
+    return report;
+}
+//# sourceMappingURL=legacy-index-migration.js.map