agentic-qe 3.15.5 → 3.15.7

package/dist/cli/commands/security.js

@@ -8,17 +8,57 @@ import chalk from 'chalk';
 import { discoverSecurityFiles } from '../../domains/security-compliance/scan-discovery.js';
 import { FilePath } from '../../shared/value-objects/index.js';
 import { writeOutput, toJSON, toSARIF, securityToMarkdown } from '../utils/ci-output.js';
+import { runDependencyAdvisoryScan } from '../../domains/security-compliance/dependency-advisory-engine.js';
+import { resolve as resolvePath } from 'node:path';
+/** Name of the CLI check for the OSV dependency advisory scan (#1049). */
+export const DEPENDENCY_CHECK = 'Dependency advisories';
+/** #1049: dependency advisories could not be checked; the dependency result is UNMEASURED (same code as coverage/quality). */
+export const EXIT_DEPENDENCIES_UNMEASURED = 3;
+/**
+ * `aqe security` exit contract:
+ * 0 = every requested check completed, no medium+ findings
+ * 1 = high/critical findings, non-compliance, or a non-dependency check incomplete/failed
+ * 2 = medium findings only, every requested check complete
+ * 3 = dependency advisories could not be checked (failed or partial OSV lookup) and
+ *     there are no high/critical findings, non-compliance or other incomplete checks:
+ *     UNMEASURED, never a clean exit (#1049). Medium findings plus an incomplete
+ *     dependency scan also exit 3: the result is unmeasured, not a medium-only verdict.
+ */
+export function securityExitCode(result) {
+    const checks = result.checks ?? [];
+    const highOrCritical = result.vulnerabilities.some(v => v.severity === 'high' || v.severity === 'critical');
+    const nonCompliant = result.compliance?.compliant === false;
+    if (result.status !== 'complete' || nonCompliant) {
+        const dependencyUnmeasured = checks.some(check => check.name === DEPENDENCY_CHECK && check.status !== 'complete');
+        const otherIncomplete = checks.some(check => check.name !== DEPENDENCY_CHECK && check.status !== 'complete');
+        if (dependencyUnmeasured && !otherIncomplete && !nonCompliant && !highOrCritical)
+            return EXIT_DEPENDENCIES_UNMEASURED;
+        return 1;
+    }
+    if (highOrCritical)
+        return 1;
+    if (result.vulnerabilities.some(v => v.severity === 'medium'))
+        return 2;
+    return 0;
+}
 export function createSecurityCommand(context, cleanupAndExit, ensureInitialized) {
     const securityCmd = new Command('security')
         .description('Security scanning and URL validation')
         .option('--sast', 'Run SAST scan')
         .option('--dast', 'Run DAST scan')
+        .option('--dependencies', 'Check package.json dependencies against OSV advisories (sends package names and versions to the OSV API)')
         .option('--compliance <frameworks>', 'Check compliance (gdpr,hipaa,soc2)', '')
         .option('--url-validate <url>', 'Validate a URL for security threats and PII exposure')
         .option('--no-pii', 'Disable PII scanning when using --url-validate')
         .option('-t, --target <path>', 'Target directory to scan', '.')
         .option('-F, --format <format>', 'Output format (text|json|sarif|markdown)', 'text')
         .option('-o, --output <path>', 'Write output to file')
+        .addHelpText('after', `
+Exit codes:
+  0  every requested check completed; no medium or higher findings
+  1  high/critical findings, non-compliance, or a check failed / is incomplete
+  2  medium findings only
+  ${EXIT_DEPENDENCIES_UNMEASURED}  UNMEASURED: dependency advisories could not be checked (OSV unreachable, rate limited, or partial)`)
         .action(async (options) => {
         if (!await ensureInitialized())
             return;
@@ -86,13 +126,13 @@ export function createSecurityCommand(context, cleanupAndExit, ensureInitialized
             return; // Don't fall through to SAST/DAST path
         }
         const format = options.format;
-        const runSAST = options.sast || (!options.dast && !options.compliance);
+        const runSAST = options.sast || (!options.dast && !options.compliance && !options.dependencies);
         const frameworks = options.compliance
             ? options.compliance.split(',').map((value) => value.trim()).filter(Boolean)
             : [];
         const scanResult = {
             vulnerabilities: [], target: options.target,
-            scanType: [runSAST && 'SAST', options.dast && 'DAST', frameworks.length > 0 && 'Compliance'].filter(Boolean).join('+'),
+            scanType: [runSAST && 'SAST', options.dast && 'DAST', options.dependencies && 'Dependencies', frameworks.length > 0 && 'Compliance'].filter(Boolean).join('+'),
             checks: [], status: 'not-run',
         };
         const checks = scanResult.checks;
@@ -133,6 +173,18 @@ export function createSecurityCommand(context, cleanupAndExit, ensureInitialized
                         checks.push({ name: 'Source discovery', status: discovery.status, reason: 'Requested source discovery did not complete; inspect discovery issues.' });
                     }
                 }
+                if (options.dependencies) {
+                    // #1049: a failed or partial OSV lookup is reported, never a clean dependency scan.
+                    const outcome = await runDependencyAdvisoryScan({ scanPackageJson: (manifest) => securityAPI.runDependencyScan(manifest) }, resolvePath(options.target));
+                    scanResult.dependencyScan = outcome.report;
+                    scanResult.vulnerabilities.push(...outcome.vulnerabilities.map(formatVulnerability));
+                    const status = outcome.report.status;
+                    checks.push({
+                        name: DEPENDENCY_CHECK,
+                        status: status === 'complete' ? 'complete' : status === 'incomplete' ? 'partial' : status === 'failed' ? 'failed' : 'not-run',
+                        ...(status !== 'complete' ? { reason: outcome.report.message } : {}),
+                    });
+                }
                 if (frameworks.length > 0) {
                     const issues = [];
                     let compliant = true;
@@ -189,13 +241,7 @@ export function createSecurityCommand(context, cleanupAndExit, ensureInitialized
             return cleanupAndExit(1);
         }
         // Incomplete execution never has a clean exit, even if it found no vulnerabilities.
-        if (scanResult.status !== 'complete' || scanResult.compliance?.compliant === false)
-            return cleanupAndExit(1);
-        if (scanResult.vulnerabilities.some(v => v.severity === 'high' || v.severity === 'critical'))
-            return cleanupAndExit(1);
-        if (scanResult.vulnerabilities.some(v => v.severity === 'medium'))
-            return cleanupAndExit(2);
-        return cleanupAndExit(0);
+        return cleanupAndExit(securityExitCode(scanResult));
     });
     return securityCmd;
 }
@@ -227,6 +273,7 @@ function formatVulnerability(value) {
             severity: value.severity, type: value.title || value.category,
             file: value.location.file, line: value.location.line ?? 1,
             message: value.description,
+            ...(value.cveId ? { cveId: value.cveId } : {}),
         };
     }
     return value;
@@ -265,6 +312,26 @@ function printSecurityResult(result) {
         ...(result.evidence?.files.filter(file => file.status !== 'analyzed' && file.status !== 'excluded').map(file => `${file.path}: ${file.status}${file.reason ? ` (${file.reason})` : ''}`) ?? []),
         ...(result.discovery?.issues.map(issue => `${issue.path}: ${issue.reason}`) ?? []),
     ];
+    if (result.dependencyScan && result.dependencyScan.status !== 'complete') {
+        const unchecked = result.dependencyScan.uncheckedPackages;
+        console.log(chalk.yellow(`  ${result.dependencyScan.message}`));
+        for (const pkg of unchecked.slice(0, 10)) {
+            const where = `${pkg.member ? `${pkg.member}: ` : ''}${pkg.name}@${pkg.version}${pkg.lockedVersion ? ` (lockfile ${pkg.lockedVersion})` : ''}`;
+            console.log(chalk.yellow(`    not checked: ${where} (${pkg.reason})`));
+        }
+        if (unchecked.length > 10)
+            console.log(chalk.yellow(`    ... and ${unchecked.length - 10} more unchecked package(s)`));
+    }
+    else if (result.dependencyScan) {
+        console.log(`  ${result.dependencyScan.message}`);
+    }
+    if (result.dependencyScan?.localPackages.length) {
+        const local = result.dependencyScan.localPackages;
+        console.log(`  Local packages (not OSV subjects, excluded): ${local.slice(0, 10).map(p => `${p.member ? `${p.member}: ` : ''}${p.name}`).join(', ')}${local.length > 10 ? ` ... and ${local.length - 10} more` : ''}`);
+    }
+    for (const problem of result.dependencyScan?.resolutionErrors ?? []) {
+        console.log(chalk.yellow(`    incomplete: ${problem}`));
+    }
     for (const limitation of limitations.slice(0, 10))
         console.log(chalk.yellow(`  ${limitation}`));
     if (limitations.length > 10)

package/dist/cli/commands/test.js

@@ -7,7 +7,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { filterTestFilesForFramework, walkSourceFiles } from '../utils/file-discovery.js';
 import { writeOutput, toJSON, toJUnit, testRunToMarkdown } from '../utils/ci-output.js';
-import { writeQualityEvidence } from '../../domains/quality-assessment/quality-evidence.js';
+import { writeTestRunEvidence } from '../../domains/quality-assessment/quality-evidence.js';
 import { validateBehaviorExamples } from '../../domains/test-generation/services/behavior-example-validation.js';
 import { findProjectRoot } from '../../kernel/project-root.js';
 import { writeGeneratedTestFile } from '../utils/generated-test-writer.js';
@@ -192,12 +192,11 @@ export function createTestCommand(context, cleanupAndExit, ensureInitialized) {
                         duration: run.duration,
                         measuredAt: new Date().toISOString(),
                     }, { namespace: 'test-execution', persist: true });
-                    await writeQualityEvidence(context.kernel.memory, {
-                        testsPassing: total > 0 ? (run.passed / total) * 100 : 0,
-                    }, {
-                        measuredAt: new Date().toISOString(),
-                        source: 'aqe test execute',
-                    });
+                    // #1027 NB1: the shared run-scoped writer (same as test_execute_parallel),
+                    // stamped with this run's id so it pairs with the run's own coverage.
+                    await writeTestRunEvidence(context.kernel.memory, {
+                        runId: run.runId, passed: run.passed, failed: run.failed, skipped: run.skipped,
+                    }, { source: 'aqe test execute' });
                     if (format === 'json') {
                         writeOutput(toJSON(run), options.output);
                     }

package/dist/cli/commands/workflow.js

@@ -227,13 +227,17 @@ export function createWorkflowCommand(context, cleanupAndExit, ensureInitialized
                     console.log(chalk.gray('  No scheduled workflows\n'));
                 }
                 else {
+                    // #991: entries loaded from a hand-edited or legacy file may lack
+                    // fields; show "(missing)" rather than "undefined".
+                    const show = (value) => value === undefined || value === null || value === '' ? '(missing)' : String(value);
                     for (const sched of scheduled) {
                         const statusIcon = sched.enabled ? chalk.green('*') : chalk.gray('o');
-                        console.log(`  ${statusIcon} ${chalk.white(sched.workflowId)}`);
-                        console.log(chalk.gray(`     ID: ${sched.id}`));
-                        console.log(chalk.gray(`     Schedule: ${sched.schedule} (${sched.scheduleDescription})`));
-                        console.log(chalk.gray(`     File: ${sched.pipelinePath}`));
-                        console.log(chalk.gray(`     Next run: ${sched.nextRun}`));
+                        console.log(`  ${statusIcon} ${chalk.white(show(sched.workflowId))}`);
+                        console.log(chalk.gray(`     ID: ${show(sched.id)}`));
+                        const description = sched.scheduleDescription ? ` (${sched.scheduleDescription})` : '';
+                        console.log(chalk.gray(`     Schedule: ${show(sched.schedule)}${description}`));
+                        console.log(chalk.gray(`     File: ${show(sched.pipelinePath)}`));
+                        console.log(chalk.gray(`     Next run: ${show(sched.nextRun)}`));
                         if (sched.lastRun) {
                             console.log(chalk.gray(`     Last run: ${sched.lastRun}`));
                         }

package/dist/cli/handlers/init-guard.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `aqe init` guard for shared directories (#1006, review of #1026 N3).
+ *
+ * Initializing in the OS temp dir or a system dir wrote `<tmp>/.agentic-qe`
+ * and `.mcp.json` there, but every later command resolves such a dir to a
+ * private scratch root, so the initialized store was never used. Refusing
+ * with a clear next step is less surprising than initializing a hidden root.
+ *
+ * @module cli/handlers/init-guard
+ */
+/** The explicit root is also the destination for all init-generated files. */
+export declare function initProjectRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Error message when `projectRoot` must not be initialized, otherwise null.
+ *
+ * An explicit root (`AQE_PROJECT_ROOT`) is refused only when it is a hard-stop
+ * directory (OS temp dir, `/`, `/home`, ...), or a sticky world-writable
+ * directory WITHOUT `.git`. This mirrors `findProjectRoot`, which keeps a
+ * sticky (mode 1777) directory that is itself a repo root as its own root, so
+ * the explicit root stays the escape hatch for such a repository. A derived
+ * root (the cwd) keeps the stricter rule: any shared directory is refused.
+ */
+export declare function sharedRootInitError(projectRoot: string, explicit: boolean): string | null;
+/** Error message when the selected root must not be initialized, otherwise null. */
+export declare function sharedDirInitError(cwd: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Error message when an explicit `AQE_PROJECT_ROOT` is not an existing
+ * directory, otherwise null. A typo must not silently create and initialize a
+ * new project somewhere else. Must run before anything creates the root (the
+ * CLI's token bootstrap does `mkdir -p <root>/.agentic-qe` at startup).
+ */
+export declare function explicitRootError(cwd?: string, env?: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=init-guard.d.ts.map

package/dist/cli/handlers/init-guard.js

@@ -0,0 +1,66 @@
+/**
+ * `aqe init` guard for shared directories (#1006, review of #1026 N3).
+ *
+ * Initializing in the OS temp dir or a system dir wrote `<tmp>/.agentic-qe`
+ * and `.mcp.json` there, but every later command resolves such a dir to a
+ * private scratch root, so the initialized store was never used. Refusing
+ * with a clear next step is less surprising than initializing a hidden root.
+ *
+ * @module cli/handlers/init-guard
+ */
+import { isHardStopDir, isSharedSystemDir, isStickyWorldWritable } from '../../kernel/shared-dirs.js';
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** The explicit root is also the destination for all init-generated files. */
+export function initProjectRoot(cwd = process.cwd(), env = process.env) {
+    return resolve(cwd, env.AQE_PROJECT_ROOT || '.');
+}
+/**
+ * Error message when `projectRoot` must not be initialized, otherwise null.
+ *
+ * An explicit root (`AQE_PROJECT_ROOT`) is refused only when it is a hard-stop
+ * directory (OS temp dir, `/`, `/home`, ...), or a sticky world-writable
+ * directory WITHOUT `.git`. This mirrors `findProjectRoot`, which keeps a
+ * sticky (mode 1777) directory that is itself a repo root as its own root, so
+ * the explicit root stays the escape hatch for such a repository. A derived
+ * root (the cwd) keeps the stricter rule: any shared directory is refused.
+ */
+export function sharedRootInitError(projectRoot, explicit) {
+    const shared = explicit
+        ? isHardStopDir(projectRoot)
+            || (isStickyWorldWritable(projectRoot) && !existsSync(join(projectRoot, '.git')))
+        : isSharedSystemDir(projectRoot);
+    if (!shared)
+        return null;
+    return (`Refusing to initialize in "${projectRoot}": it is a shared temp/system directory, ` +
+        'so a store here would be shared by every unrelated project below it and ' +
+        'later commands would not use it. Create a project directory first ' +
+        '(mkdir my-project && cd my-project) or set AQE_PROJECT_ROOT to a project directory.');
+}
+/** Error message when the selected root must not be initialized, otherwise null. */
+export function sharedDirInitError(cwd, env = process.env) {
+    return sharedRootInitError(initProjectRoot(cwd, env), Boolean(env.AQE_PROJECT_ROOT));
+}
+/**
+ * Error message when an explicit `AQE_PROJECT_ROOT` is not an existing
+ * directory, otherwise null. A typo must not silently create and initialize a
+ * new project somewhere else. Must run before anything creates the root (the
+ * CLI's token bootstrap does `mkdir -p <root>/.agentic-qe` at startup).
+ */
+export function explicitRootError(cwd = process.cwd(), env = process.env) {
+    if (!env.AQE_PROJECT_ROOT)
+        return null;
+    const root = initProjectRoot(cwd, env);
+    let isDir = false;
+    try {
+        isDir = statSync(root).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (isDir)
+        return null;
+    return (`AQE_PROJECT_ROOT "${root}" is not an existing directory. ` +
+        'Create it first (mkdir -p) or correct the path; aqe init does not create the project root.');
+}
+//# sourceMappingURL=init-guard.js.map

package/dist/cli/handlers/init-handler.d.ts

@@ -80,6 +80,9 @@ export interface InitJsonOutput {
                 error?: string;
             };
         };
+        /** #1017: pre-3.15.6 test-named skill files removed / kept by init. */
+        retiredAssetsRemoved?: string[];
+        retiredAssetsKept?: string[];
     };
     totalDurationMs: number;
     timestamp: string;

package/dist/cli/handlers/init-handler.js

@@ -9,6 +9,7 @@ import { createRequire } from 'node:module';
 import { ALL_DOMAINS } from '../../shared/types/index.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
 import { resolveInitFlags } from './init-flags.js';
+import { initProjectRoot, sharedRootInitError } from './init-guard.js';
 // ============================================================================
 // Init Handler
 // ============================================================================
@@ -88,6 +89,15 @@ export class InitHandler {
             });
         }
         try {
+            const projectRoot = initProjectRoot();
+            // #1006 (review of #1026 N3): never initialize a store in a shared
+            // temp/system dir; later commands would resolve elsewhere and ignore it.
+            const sharedDirError = sharedRootInitError(projectRoot, Boolean(process.env.AQE_PROJECT_ROOT));
+            if (sharedDirError) {
+                console.error(chalk.red(`\n  ${sharedDirError}\n`));
+                await this.cleanupAndExit(1);
+                return;
+            }
             // Expand --with-all-platforms into individual flags
             if (options.withAllPlatforms) {
                 options.withCopilot = true;
@@ -108,11 +118,11 @@ export class InitHandler {
                 console.log(chalk.blue('\n  Agentic QE v3 Initialization\n'));
                 // Use modular orchestrator for --auto or --modular
                 if (options.auto || options.modular || options.browserEngine) {
-                    await this.runModularInit(options, context);
+                    await this.runModularInit(options, context, projectRoot);
                     return;
                 }
                 // Legacy wizard mode using InitOrchestrator
-                await this.runLegacyWizard(options, context);
+                await this.runLegacyWizard(options, context, projectRoot);
                 return;
             }
             // Platform provisioning (--with-opencode, --with-n8n, --with-<editor>, ...)
@@ -135,7 +145,7 @@ export class InitHandler {
             const noStatusLineRequested = flags.noStatusLine;
             if (options.browserEngine || options.modular || platformRequested || databaseFree || noClaudeRequested || noStatusLineRequested) {
                 console.log(chalk.blue('\n  Agentic QE v3 Initialization\n'));
-                await this.runModularInit(options, context);
+                await this.runModularInit(options, context, projectRoot);
                 return;
             }
             // Standard init without wizard
@@ -146,7 +156,7 @@ export class InitHandler {
             await this.cleanupAndExit(1);
         }
     }
-    async runModularInit(options, _context) {
+    async runModularInit(options, _context, projectRoot) {
         const isJsonMode = options.json === true;
         // #931/#935: commander maps --no-<name> to options.<name> === false.
         const flags = resolveInitFlags(options);
@@ -176,7 +186,7 @@ export class InitHandler {
         }
         const { createModularInitOrchestrator } = await import('../../init/orchestrator.js');
         const orchestrator = createModularInitOrchestrator({
-            projectRoot: process.cwd(),
+            projectRoot,
             autoMode: options.auto,
             upgrade: options.upgrade,
             minimal: options.minimal,
@@ -247,7 +257,7 @@ export class InitHandler {
             try {
                 const { setupClaudeFlowIntegration } = await import('../commands/claude-flow-setup.js');
                 cfResult = await setupClaudeFlowIntegration({
-                    projectRoot: process.cwd(),
+                    projectRoot,
                     force: options.withClaudeFlow,
                 });
                 if (cfResult.available) {
@@ -304,11 +314,11 @@ export class InitHandler {
         }
         await this.cleanupAndExit(0);
     }
-    async runLegacyWizard(options, _context) {
+    async runLegacyWizard(options, _context, projectRoot) {
         const flags = resolveInitFlags(options);
         const { InitOrchestrator } = await import('../../init/init-wizard.js');
         const orchestratorOptions = {
-            projectRoot: process.cwd(),
+            projectRoot,
             autoMode: options.auto,
             minimal: options.minimal,
             browserEngine: options.browserEngine,
@@ -446,62 +456,62 @@ export class InitHandler {
         }
     }
     getHelp() {
-        return `
-Initialize the AQE v3 system with various configuration options.
-
-Usage:
-  aqe init [options]
-
-Options:
-  -d, --domains <domains>    Comma-separated list of domains to enable (default: all)
-  -m, --max-agents <number>  Maximum concurrent agents (default: 15)
-  --memory <backend>         Memory backend: sqlite, agentdb, or hybrid (default: hybrid)
-  --lazy                     Enable lazy loading of domains
-  --wizard                   Run interactive setup wizard
-  --auto                     Auto-configure based on project analysis
-  -u, --upgrade              Upgrade existing installation (overwrite skills, agents, validation)
-  --minimal                  Minimal configuration (skip optional features)
-  --skip-patterns            Skip loading pre-trained patterns
+        return `
+Initialize the AQE v3 system with various configuration options.
+
+Usage:
+  aqe init [options]
+
+Options:
+  -d, --domains <domains>    Comma-separated list of domains to enable (default: all)
+  -m, --max-agents <number>  Maximum concurrent agents (default: 15)
+  --memory <backend>         Memory backend: sqlite, agentdb, or hybrid (default: hybrid)
+  --lazy                     Enable lazy loading of domains
+  --wizard                   Run interactive setup wizard
+  --auto                     Auto-configure based on project analysis
+  -u, --upgrade              Upgrade existing installation (overwrite skills, agents, validation)
+  --minimal                  Minimal configuration (skip optional features)
+  --skip-patterns            Skip loading pre-trained patterns
   --browser-engine          Install optional Vibium and browser payload
   --no-browser-engine       Skip browser setup (default)
-  --with-n8n                 Install n8n workflow testing agents and skills
+  --with-n8n                 Install n8n workflow testing agents and skills
   --with-opencode            Include OpenCode agent/skill provisioning
   --with-codex               Include OpenAI Codex hooks, instructions, skills, and MCP
   --codex-guidance <mode>    Codex AGENTS.md guidance: full, compact, or none
   --with-ruflo               Opt into Ruflo guidance and lifecycle hooks for Codex
-  --auto-migrate             Automatically migrate from v2 if detected
-  --with-claude-flow         Force Claude Flow integration setup
-  --skip-claude-flow         Skip Claude Flow integration
-  --no-mcp                   Skip MCP server config (MCP is enabled by default)
-  --with-mcp                 Add the .mcp.json entry even if the agentic-qe-fleet plugin is enabled
-                             (--no-mcp and --with-mcp cannot be combined)
-  --no-governance            Skip governance configuration (ADR-058)
-  --modular                  Use new modular init system
-
-MCP Server:
-  MCP server configuration is ENABLED BY DEFAULT. It writes .mcp.json
-  at the project root so Claude Code auto-discovers the AQE MCP server.
-  Use --no-mcp to skip if you only want CLI commands.
-  If the agentic-qe-fleet Claude Code plugin is enabled (user, project or
-  local settings), init skips the entry because the plugin already provides
-  the AQE MCP server. Use --with-mcp to add the project entry anyway.
-
-Governance:
-  Governance is ENABLED BY DEFAULT. It installs .claude/guidance/ with:
-  - constitution.md: 7 unbreakable QE invariants
-  - shards/*.shard.md: 12 domain-specific governance rules
-
-  Use --no-governance to skip, or set GOVERNANCE_*=false env vars for
-  fine-grained control over individual gates (ContinueGate, MemoryWriteGate, etc.)
-
+  --auto-migrate             Automatically migrate from v2 if detected
+  --with-claude-flow         Force Claude Flow integration setup
+  --skip-claude-flow         Skip Claude Flow integration
+  --no-mcp                   Skip MCP server config (MCP is enabled by default)
+  --with-mcp                 Add the .mcp.json entry even if the agentic-qe-fleet plugin is enabled
+                             (--no-mcp and --with-mcp cannot be combined)
+  --no-governance            Skip governance configuration (ADR-058)
+  --modular                  Use new modular init system
+
+MCP Server:
+  MCP server configuration is ENABLED BY DEFAULT. It writes .mcp.json
+  at the project root so Claude Code auto-discovers the AQE MCP server.
+  Use --no-mcp to skip if you only want CLI commands.
+  If the agentic-qe-fleet Claude Code plugin is enabled (user, project or
+  local settings), init skips the entry because the plugin already provides
+  the AQE MCP server. Use --with-mcp to add the project entry anyway.
+
+Governance:
+  Governance is ENABLED BY DEFAULT. It installs .claude/guidance/ with:
+  - constitution.md: 7 unbreakable QE invariants
+  - shards/*.shard.md: 12 domain-specific governance rules
+
+  Use --no-governance to skip, or set GOVERNANCE_*=false env vars for
+  fine-grained control over individual gates (ContinueGate, MemoryWriteGate, etc.)
+
 Examples:
   aqe init --auto            # Auto-configure based on project (keeps existing skills)
   aqe init --auto --with-codex --with-ruflo
                              # Codex plus optional Ruflo coordination
-  aqe init --auto --upgrade  # Auto-configure AND update all skills/agents
-  aqe init --upgrade         # Upgrade existing installation
-  aqe init --wizard          # Run interactive wizard
-  aqe init --domains test-generation,coverage-analysis
+  aqe init --auto --upgrade  # Auto-configure AND update all skills/agents
+  aqe init --upgrade         # Upgrade existing installation
+  aqe init --wizard          # Run interactive wizard
+  aqe init --domains test-generation,coverage-analysis
 `;
     }
 }

package/dist/cli/handlers/interfaces.js

@@ -5,6 +5,7 @@
  * Part of the CLI modularization refactoring.
  */
 import chalk from 'chalk';
+import { isAqeManagedDir } from '../../shared/aqe-managed-dirs.js';
 // ============================================================================
 // Helper Functions for Handlers
 // ============================================================================
@@ -66,7 +67,7 @@ export function getColorForPercent(percent) {
 export async function walkDirectory(dir, options = {}) {
     const fs = await import('fs');
     const path = await import('path');
-    const { extensions = ['.ts'], exclude = ['node_modules', 'dist'], maxDepth = 4, includeTests = false, } = options;
+    const { extensions = ['.ts'], exclude = ['node_modules', 'dist', '.git'], maxDepth = 4, includeTests = false, } = options;
     const walkDir = (currentDir, depth) => {
         if (depth > maxDepth)
             return [];
@@ -81,6 +82,9 @@ export async function walkDirectory(dir, options = {}) {
         for (const item of items) {
             if (exclude.includes(item))
                 continue;
+            // #999: AQE state/assets (.agentic-qe anywhere; .claude at the root or next to .agentic-qe)
+            if (isAqeManagedDir(currentDir, item, depth === 0))
+                continue;
             if (!includeTests && (item === 'tests' || item.includes('.test.') || item.includes('.spec.')))
                 continue;
             const fullPath = path.join(currentDir, item);

package/dist/cli/index.js

@@ -417,6 +417,17 @@ async function main() {
     const commandArgs = process.argv.slice(2).filter(arg => arg !== '--');
     const learningSnapshot = commandArgs[0] === 'learning'
         && (commandArgs[1] === 'backup' || commandArgs[1] === 'restore');
+    // `aqe init` must not create a mistyped AQE_PROJECT_ROOT: the token bootstrap
+    // below does `mkdir -p <root>/.agentic-qe`, so the check has to run first.
+    if (commandArgs[0] === 'init') {
+        const { explicitRootError } = await import('./handlers/init-guard.js');
+        const rootError = explicitRootError();
+        if (rootError) {
+            console.error(chalk.red(`\n  ${rootError}\n`));
+            await cleanupAndExit(1);
+            return;
+        }
+    }
     if (!learningSnapshot) {
         const { bootstrapTokenTracking } = await import('../init/token-bootstrap.js');
         await bootstrapTokenTracking({

package/dist/cli/scheduler/persistent-scheduler.d.ts

@@ -123,9 +123,11 @@ export declare class PersistentScheduler {
         due: number;
     }>;
     /**
-     * Load schedules without acquiring lock (for use within locked context)
+     * Load schedules for a locked read-modify-write. A genuinely unparseable
+     * file is backed up (not removed) first, so the write that follows cannot
+     * silently replace it with fewer schedules.
      */
-    private loadSchedulesUnsafe;
+    private loadForWrite;
     /**
      * Parse schedules file content with validation
      * Security: Checks file size before parsing to prevent DoS
@@ -139,6 +141,8 @@ export declare class PersistentScheduler {
      * Handle corrupt schedules file by backing up and creating new
      */
     private handleCorruptFile;
+    /** Copy an unparseable schedules file to `.corrupt.<ts>` (left in place). */
+    private backupCorruptFile;
     /**
      * Execute a function with file locking for safe concurrent access
      */