@illicomedia/skills-mcp-server 1.1.0 → 1.1.1

package/dist/audit.d.ts

@@ -19,5 +19,6 @@ export interface AuditReport {
 }
 /**
  * Checks that the files and scripts expected by Fredo QA Skills are present in a project.
+ * Context-aware across stacks (Rust, Go, Python, C/C++, Java, PHP, Node.js) and project types.
  */
 export declare function runComplianceAudit(projectPath: string): AuditReport;

package/dist/audit.js

@@ -2,13 +2,40 @@
 // SPDX-License-Identifier: MIT
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-const AUDIT_SCOPE = 'File-presence checks only: gates are not executed and file contents are not validated. A full pass means the expected files exist, not that the project is compliant.';
+const AUDIT_SCOPE = 'Fast preflight sanity check: verifies presence of scaffolding, agent directives, and baseline hygiene. Gates are not executed and compilers are not run.';
 /**
  * Checks that the files and scripts expected by Fredo QA Skills are present in a project.
+ * Context-aware across stacks (Rust, Go, Python, C/C++, Java, PHP, Node.js) and project types.
  */
 export function runComplianceAudit(projectPath) {
     const resolvedPath = path.resolve(projectPath);
+    const parentPath = path.dirname(resolvedPath);
     const results = [];
+    const fileExists = (rel) => fs.existsSync(path.join(resolvedPath, rel));
+    const parentFileExists = (rel) => resolvedPath !== parentPath && fs.existsSync(path.join(parentPath, rel));
+    const hasDir = (rel) => {
+        try {
+            const p = path.join(resolvedPath, rel);
+            return fs.existsSync(p) && fs.statSync(p).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    };
+    // Stack detection
+    const isRust = fileExists('Cargo.toml');
+    const isGo = fileExists('go.mod');
+    const isNode = fileExists('package.json');
+    const isPython = fileExists('pyproject.toml') ||
+        fileExists('requirements.txt') ||
+        fileExists('setup.py') ||
+        fileExists('Pipfile');
+    const hasMakefile = fileExists('Makefile') || fileExists('justfile') || fileExists('scripts/qa.sh');
+    const isWebProject = hasDir('public') ||
+        fileExists('index.html') ||
+        fileExists('src/index.html') ||
+        hasDir('dist') ||
+        hasDir('www');
     // Check 1: AGENTS.md policy presence
     const agentsMd = path.join(resolvedPath, 'AGENTS.md');
     const hasAgentsMd = fs.existsSync(agentsMd);
@@ -21,80 +48,484 @@ export function runComplianceAudit(projectPath) {
             ? 'AGENTS.md file present (content not evaluated).'
             : 'AGENTS.md not found. Coding agents have no repository-level QA instructions.',
     });
-    // Check 2: .qa-exceptions governance
+    // Check 2: .qa-exceptions.yaml governance (passes when file exists and unexpired, or project is clean without exceptions)
     const exceptionsFile = path.join(resolvedPath, '.qa-exceptions.yaml');
     const hasExceptions = fs.existsSync(exceptionsFile);
+    let exceptionsPassed = true;
+    let exceptionsSeverity = hasExceptions ? 'warning' : 'info';
+    let exceptionsDetails = 'No .qa-exceptions.yaml required (clean state: 0 exceptions, or handled natively in compiler/linter config).';
+    if (hasExceptions) {
+        try {
+            const content = fs.readFileSync(exceptionsFile, 'utf-8');
+            const dateMatches = content.matchAll(/(?:expires_at|expires):\s*["']?([0-9]{4}-[0-9]{2}-[0-9]{2})["']?/g);
+            const expiredList = [];
+            const now = Date.now();
+            for (const match of dateMatches) {
+                const expDate = Date.parse(match[1]);
+                if (!Number.isNaN(expDate) && expDate < now) {
+                    expiredList.push(match[1]);
+                }
+            }
+            if (expiredList.length > 0) {
+                exceptionsPassed = false;
+                exceptionsSeverity = 'blocker';
+                exceptionsDetails = `Exception register contains ${expiredList.length} expired entry(ies) (expired on ${expiredList.join(', ')}). Expired entries fail closed per qa-core.`;
+            }
+            else {
+                exceptionsDetails =
+                    'Exception register file present (all declared expiration dates are active).';
+            }
+        }
+        catch {
+            exceptionsDetails = 'Exception register file present (schema and expiry not checked).';
+        }
+    }
     results.push({
         category: 'governance',
         name: '.qa-exceptions.yaml present',
-        passed: hasExceptions,
+        passed: exceptionsPassed,
+        severity: exceptionsSeverity,
+        details: exceptionsDetails,
+    });
+    // Check 3: Root LICENSE file presence (Legal Governance)
+    const hasLicense = fileExists('LICENSE') ||
+        fileExists('LICENSE.md') ||
+        fileExists('LICENSE.txt') ||
+        fileExists('LICENCE') ||
+        fileExists('LICENCE.md') ||
+        fileExists('COPYING') ||
+        fileExists('COPYING.md') ||
+        fileExists('COPYING.txt') ||
+        parentFileExists('LICENSE') ||
+        parentFileExists('LICENSE.md') ||
+        parentFileExists('COPYING');
+    results.push({
+        category: 'governance',
+        name: 'LICENSE file present',
+        passed: hasLicense,
         severity: 'warning',
-        details: hasExceptions
-            ? 'Exception register file present (schema and expiry not checked).'
-            : 'No .qa-exceptions.yaml found. Deviations from quality gates should be tracked there.',
+        details: hasLicense
+            ? 'LICENSE file present in project root (license terms not evaluated).'
+            : 'No LICENSE, LICENSE.md, or COPYING file found in project root.',
     });
-    // Check 3: RFC 9116 security.txt
+    // Check 4: Vulnerability disclosure policy (RFC 9116 security.txt for web, SECURITY.md for offline CLI/libraries)
     const secTxtPublic = path.join(resolvedPath, 'public', '.well-known', 'security.txt');
     const secTxtDist = path.join(resolvedPath, 'dist', '.well-known', 'security.txt');
     const secTxtRoot = path.join(resolvedPath, '.well-known', 'security.txt');
-    const hasSecTxt = fs.existsSync(secTxtPublic) || fs.existsSync(secTxtDist) || fs.existsSync(secTxtRoot);
+    const hasSecTxt = fs.existsSync(secTxtPublic) ||
+        fs.existsSync(secTxtDist) ||
+        fs.existsSync(secTxtRoot) ||
+        fileExists('website/public/.well-known/security.txt') ||
+        fileExists('website/dist/.well-known/security.txt') ||
+        fileExists('apps/web/public/.well-known/security.txt') ||
+        fileExists('client/public/.well-known/security.txt');
+    const hasSecurityMd = fileExists('SECURITY.md') || fileExists('.github/SECURITY.md');
+    const secCheckName = isWebProject
+        ? 'security.txt present'
+        : hasSecTxt
+            ? 'security.txt present'
+            : 'SECURITY.md present';
+    const secPassed = hasSecTxt || (!isWebProject && hasSecurityMd);
+    let secDetails = 'No security policy found.';
+    if (hasSecTxt) {
+        secDetails =
+            'security.txt file present in a .well-known/ directory (RFC 9116 fields not checked).';
+    }
+    else if (hasSecurityMd) {
+        secDetails =
+            'SECURITY.md file present (standard vulnerability disclosure policy for offline/CLI repositories).';
+    }
+    else if (isWebProject) {
+        secDetails = 'No security.txt found in public/, dist/, or root .well-known/ directories.';
+    }
+    else {
+        secDetails = 'No SECURITY.md found in repository root.';
+    }
     results.push({
         category: 'security',
-        name: 'security.txt present',
-        passed: hasSecTxt,
-        severity: 'blocker',
-        details: hasSecTxt
-            ? 'security.txt file present in a .well-known/ directory (RFC 9116 fields not checked).'
-            : 'No security.txt found in public/, dist/, or root .well-known/ directories.',
+        name: secCheckName,
+        passed: secPassed,
+        severity: isWebProject ? 'blocker' : 'warning',
+        details: secDetails,
     });
-    // Check 4: Safe gitignore configuration
+    // Check 5: Safe gitignore configuration for .env
     const gitignore = path.join(resolvedPath, '.gitignore');
     const hasGitignore = fs.existsSync(gitignore);
-    let ignoresEnv = false;
+    let gitignoreContent = '';
     if (hasGitignore) {
-        const gitignoreContent = fs.readFileSync(gitignore, 'utf-8');
-        ignoresEnv = gitignoreContent.includes('.env');
+        try {
+            gitignoreContent = fs.readFileSync(gitignore, 'utf-8');
+        }
+        catch { }
+    }
+    else if (parentFileExists('.gitignore')) {
+        try {
+            gitignoreContent = fs.readFileSync(path.join(parentPath, '.gitignore'), 'utf-8');
+        }
+        catch { }
+    }
+    const hasEnvFiles = fileExists('.env') ||
+        fileExists('.env.local') ||
+        fileExists('.env.prod') ||
+        fileExists('.env.example');
+    const ignoresEnv = gitignoreContent.includes('.env');
+    const envPassed = ignoresEnv;
+    let envSeverity = 'warning';
+    let envDetails = '';
+    if (hasEnvFiles || isWebProject) {
+        envSeverity = 'blocker';
+        envDetails = ignoresEnv
+            ? '.gitignore contains the text ".env" (ignore rules and other secret files not evaluated).'
+            : '.gitignore missing or does not mention .env (also ignore private keys and credentials).';
+    }
+    else {
+        // Offline / CLI binary or non-web project without env files:
+        envSeverity = 'warning';
+        envDetails = ignoresEnv
+            ? '.gitignore contains the text ".env".'
+            : '.gitignore does not mention .env (recommended practice even for offline projects to prevent accidental secret commits).';
     }
     results.push({
         category: 'security',
         name: '.gitignore mentions .env',
-        passed: hasGitignore && ignoresEnv,
-        severity: 'blocker',
-        details: hasGitignore && ignoresEnv
-            ? '.gitignore contains the text ".env" (ignore rules and other secret files not evaluated).'
-            : '.gitignore missing or does not mention .env (also ignore private keys and credentials).',
+        passed: envPassed,
+        severity: envSeverity,
+        details: envDetails,
     });
-    // Check 5: QA scripts in package.json
-    const pkgJsonPath = path.join(resolvedPath, 'package.json');
+    // Check 6: Private key and secret hygiene in .gitignore
+    const keyIgnoreRegex = /(?:\*\.(?:pem|key|p12|pkcs12)|id_rsa|id_ed25519|\.aws)/;
+    const ignoresKeys = keyIgnoreRegex.test(gitignoreContent);
+    let hasRawKeyFile = false;
+    try {
+        const rootEntries = fs.readdirSync(resolvedPath);
+        for (const entry of rootEntries) {
+            if ((entry.endsWith('.pem') ||
+                entry.endsWith('.key') ||
+                entry.endsWith('.p12') ||
+                entry.endsWith('.pkcs12') ||
+                entry === 'id_rsa' ||
+                entry === 'id_ed25519') &&
+                !ignoresKeys) {
+                hasRawKeyFile = true;
+                break;
+            }
+        }
+    }
+    catch { }
+    let keyPassed = true;
+    let keySeverity = 'warning';
+    let keyDetails = '';
+    if (hasRawKeyFile) {
+        keyPassed = false;
+        keySeverity = 'blocker';
+        keyDetails = 'Raw private key or certificate file detected in workspace root.';
+    }
+    else if (ignoresKeys) {
+        keyPassed = true;
+        keySeverity = 'warning';
+        keyDetails = '.gitignore contains rules for private key and credential files.';
+    }
+    else if (isWebProject || hasEnvFiles || isNode) {
+        keyPassed = false;
+        keySeverity = 'warning';
+        keyDetails =
+            '.gitignore does not contain explicit rules ignoring private key files (*.pem, *.key, *.p12).';
+    }
+    else {
+        keyPassed = true;
+        keySeverity = 'info';
+        keyDetails =
+            'No private keys detected; explicit key ignore rules recommended for multi-contributor repositories.';
+    }
+    results.push({
+        category: 'security',
+        name: 'private key and secret hygiene in .gitignore',
+        passed: keyPassed,
+        severity: keySeverity,
+        details: keyDetails,
+    });
+    // Check 7: Canonical QA scripts / quality gates
     let hasQaStandard = false;
-    let hasTypeCheck = false;
-    if (fs.existsSync(pkgJsonPath)) {
+    let qaStandardDetails = '';
+    let qaCheckName = 'qa:starter or qa:standard script declared';
+    if (isNode) {
+        const pkgJsonPath = path.join(resolvedPath, 'package.json');
         try {
             const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
-            hasQaStandard = Boolean(pkg.scripts?.['qa:standard'] || pkg.scripts?.['qa:starter']);
-            hasTypeCheck = Boolean(pkg.scripts?.['type-check'] || pkg.scripts?.['tsc']);
+            hasQaStandard = Boolean(pkg.scripts?.['qa:standard'] ||
+                pkg.scripts?.['qa:starter'] ||
+                pkg.scripts?.['test']);
         }
         catch {
             // Ignored
         }
+        qaStandardDetails = hasQaStandard
+            ? 'package.json declares qa:starter or qa:standard (script not executed).'
+            : 'No qa:starter / qa:standard script in package.json.';
+    }
+    else if (isRust) {
+        hasQaStandard = true;
+        qaCheckName = 'qa:starter / cargo quality gates declared';
+        qaStandardDetails =
+            'Rust project detected (Cargo.toml). Canonical QA available via cargo test and cargo clippy.';
+    }
+    else if (isGo) {
+        hasQaStandard = true;
+        qaCheckName = 'qa:starter / go quality gates declared';
+        qaStandardDetails =
+            'Go project detected (go.mod). Canonical QA available via go test and golangci-lint.';
+    }
+    else if (isPython) {
+        hasQaStandard = fileExists('pyproject.toml') || fileExists('tox.ini') || hasMakefile;
+        qaCheckName = 'qa:starter / python quality gates declared';
+        qaStandardDetails = hasQaStandard
+            ? 'Python project detected. QA configured via pyproject.toml / test runner.'
+            : 'No test runner or pyproject.toml found for Python project.';
+    }
+    else if (hasMakefile) {
+        hasQaStandard = true;
+        qaCheckName = 'qa:starter / makefile quality gates declared';
+        qaStandardDetails = 'Makefile / scripts/qa.sh detected for canonical quality gate execution.';
+    }
+    else {
+        hasQaStandard = false;
+        qaStandardDetails = 'No qa:starter / qa:standard script in package.json.';
     }
     results.push({
         category: 'quality',
-        name: 'qa:starter or qa:standard script declared',
+        name: qaCheckName,
         passed: hasQaStandard,
         severity: 'blocker',
-        details: hasQaStandard
-            ? 'package.json declares qa:starter or qa:standard (script not executed).'
-            : 'No qa:starter / qa:standard script in package.json.',
+        details: qaStandardDetails,
     });
+    // Check 8: Static typing / static analysis / compiler checks
+    let hasTypeCheck = false;
+    let typeCheckDetails = '';
+    let typeCheckName = 'type-check script declared';
+    if (isNode) {
+        const pkgJsonPath = path.join(resolvedPath, 'package.json');
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+            hasTypeCheck = Boolean(pkg.scripts?.['type-check'] ||
+                pkg.scripts?.['tsc'] ||
+                pkg.scripts?.['check'] ||
+                fileExists('tsconfig.json'));
+        }
+        catch {
+            // Ignored
+        }
+        typeCheckDetails = hasTypeCheck
+            ? 'package.json declares a type-check script (script not executed).'
+            : 'No type-check or tsc script in package.json.';
+    }
+    else if (isRust) {
+        hasTypeCheck = true;
+        typeCheckName = 'compile-time type safety & borrow checking (rustc)';
+        typeCheckDetails = 'Rust compiler enforces compile-time type safety and borrow checking.';
+    }
+    else if (isGo) {
+        hasTypeCheck = true;
+        typeCheckName = 'compile-time type safety (go build)';
+        typeCheckDetails = 'Go compiler enforces compile-time type safety.';
+    }
+    else if (isPython) {
+        hasTypeCheck = fileExists('mypy.ini') || fileExists('pyproject.toml');
+        typeCheckName = 'static typing / type-check configured';
+        typeCheckDetails = hasTypeCheck
+            ? 'Python type checking or linter configuration detected.'
+            : 'No mypy.ini or type checking configuration detected.';
+    }
+    else {
+        hasTypeCheck = hasQaStandard;
+        typeCheckDetails = hasTypeCheck
+            ? 'Static analysis provided by build system.'
+            : 'No type-check or tsc script in package.json.';
+    }
     results.push({
         category: 'quality',
-        name: 'type-check script declared',
+        name: typeCheckName,
         passed: hasTypeCheck,
         severity: 'blocker',
-        details: hasTypeCheck
-            ? 'package.json declares a type-check script (script not executed).'
-            : 'No type-check or tsc script in package.json.',
+        details: typeCheckDetails,
+    });
+    // Check 9: Automated test suite declared
+    let hasTestSuite = false;
+    let testSuiteDetails = '';
+    if (isNode) {
+        const pkgJsonPath = path.join(resolvedPath, 'package.json');
+        let hasTestScript = false;
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+            hasTestScript = Boolean(pkg.scripts?.test ||
+                pkg.scripts?.['test:unit'] ||
+                pkg.scripts?.['test:all'] ||
+                pkg.scripts?.['test:e2e'] ||
+                pkg.scripts?.['test:run']);
+        }
+        catch { }
+        const hasTestConfigFile = fileExists('vitest.config.ts') ||
+            fileExists('vitest.config.js') ||
+            fileExists('vitest.config.mjs') ||
+            fileExists('jest.config.js') ||
+            fileExists('jest.config.ts') ||
+            fileExists('playwright.config.ts');
+        hasTestSuite = hasTestScript || hasTestConfigFile || hasDir('tests') || hasDir('test');
+        testSuiteDetails = hasTestSuite
+            ? 'package.json declares test script or test runner configuration (tests not executed).'
+            : 'No test runner script or test config declared in package.json.';
+    }
+    else if (isRust) {
+        hasTestSuite = true;
+        testSuiteDetails =
+            'Rust test framework declared via cargo test / Cargo.toml (tests not executed).';
+    }
+    else if (isGo) {
+        hasTestSuite = true;
+        testSuiteDetails = 'Go test framework declared via go test / go.mod (tests not executed).';
+    }
+    else if (isPython) {
+        hasTestSuite =
+            fileExists('pytest.ini') ||
+                fileExists('tox.ini') ||
+                fileExists('setup.cfg') ||
+                hasDir('tests') ||
+                hasDir('test');
+        testSuiteDetails = hasTestSuite
+            ? 'Python test runner configuration or tests/ directory detected (tests not executed).'
+            : 'No pytest.ini, tox.ini, or tests/ directory found for Python project.';
+    }
+    else if (fileExists('composer.json')) {
+        hasTestSuite =
+            fileExists('phpunit.xml') ||
+                fileExists('phpunit.xml.dist') ||
+                fileExists('pest.php') ||
+                hasDir('tests');
+        testSuiteDetails = hasTestSuite
+            ? 'PHPUnit or Pest test configuration detected (tests not executed).'
+            : 'No phpunit.xml or tests/ directory found for PHP project.';
+    }
+    else {
+        hasTestSuite =
+            hasDir('tests') ||
+                hasDir('test') ||
+                fileExists('scripts/test.sh') ||
+                (hasMakefile &&
+                    fileExists('Makefile') &&
+                    fs.readFileSync(path.join(resolvedPath, 'Makefile'), 'utf-8').includes('test:'));
+        testSuiteDetails = hasTestSuite
+            ? 'Test suite configuration or tests/ directory detected (tests not executed).'
+            : 'No automated test runner script or tests/ directory detected.';
+    }
+    results.push({
+        category: 'quality',
+        name: 'automated test suite declared',
+        passed: hasTestSuite,
+        severity: 'blocker',
+        details: testSuiteDetails,
+    });
+    // Check 10: Dependency lockfile presence
+    let hasLockfile = false;
+    let lockfileDetails = '';
+    let lockfileSeverity = 'warning';
+    const hasManifest = isNode || isRust || isGo || isPython || fileExists('composer.json') || fileExists('pom.xml');
+    if (isNode) {
+        hasLockfile =
+            fileExists('pnpm-lock.yaml') ||
+                fileExists('package-lock.json') ||
+                fileExists('yarn.lock') ||
+                fileExists('bun.lockb') ||
+                parentFileExists('pnpm-lock.yaml') ||
+                parentFileExists('package-lock.json');
+        lockfileDetails = hasLockfile
+            ? 'Dependency lockfile present for reproducible dependency resolution.'
+            : 'Node package.json detected without committed lockfile (pnpm-lock.yaml, package-lock.json).';
+    }
+    else if (isRust) {
+        hasLockfile = fileExists('Cargo.lock');
+        lockfileDetails = hasLockfile
+            ? 'Cargo.lock present for reproducible dependency resolution.'
+            : 'Cargo.lock missing. Binaries and end-user artifacts should commit Cargo.lock.';
+    }
+    else if (isGo) {
+        hasLockfile = fileExists('go.sum');
+        lockfileDetails = hasLockfile
+            ? 'go.sum present for reproducible dependency resolution.'
+            : 'go.sum missing for Go module dependency resolution.';
+    }
+    else if (isPython) {
+        hasLockfile =
+            fileExists('poetry.lock') ||
+                fileExists('Pipfile.lock') ||
+                fileExists('uv.lock') ||
+                fileExists('pdm.lock') ||
+                fileExists('requirements.lock');
+        lockfileDetails = hasLockfile
+            ? 'Python dependency lockfile present for reproducible dependency resolution.'
+            : 'No Python dependency lockfile found (poetry.lock, uv.lock, Pipfile.lock).';
+    }
+    else if (fileExists('composer.json')) {
+        hasLockfile = fileExists('composer.lock');
+        lockfileDetails = hasLockfile
+            ? 'composer.lock present for reproducible dependency resolution.'
+            : 'composer.lock missing for PHP Composer project.';
+    }
+    else {
+        hasLockfile = true;
+        lockfileSeverity = 'info';
+        lockfileDetails = 'No dependency manifest detected; lockfile requirement not applicable.';
+    }
+    results.push({
+        category: 'supply-chain',
+        name: 'dependency lockfile present',
+        passed: hasLockfile,
+        severity: lockfileSeverity,
+        details: lockfileDetails,
+    });
+    // Check 11: Continuous integration workflow definition
+    const checkCiDir = (dirRel) => {
+        try {
+            const dirPath = path.join(resolvedPath, dirRel);
+            if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+                return false;
+            const files = fs.readdirSync(dirPath);
+            return files.some((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        }
+        catch {
+            return false;
+        }
+    };
+    const checkParentCiDir = (dirRel) => {
+        try {
+            if (resolvedPath === parentPath)
+                return false;
+            const dirPath = path.join(parentPath, dirRel);
+            if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+                return false;
+            const files = fs.readdirSync(dirPath);
+            return files.some((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasCiWorkflow = checkCiDir('.github/workflows') ||
+        checkParentCiDir('.github/workflows') ||
+        fileExists('.gitlab-ci.yml') ||
+        fileExists('.circleci/config.yml') ||
+        fileExists('azure-pipelines.yml') ||
+        fileExists('bitbucket-pipelines.yml') ||
+        fileExists('Jenkinsfile') ||
+        fileExists('.travis.yml') ||
+        fileExists('.woodpecker.yml') ||
+        fileExists('.drone.yml');
+    results.push({
+        category: 'devops',
+        name: 'CI workflow definition present',
+        passed: hasCiWorkflow,
+        severity: 'warning',
+        details: hasCiWorkflow
+            ? 'CI workflow definition file present (workflow execution not evaluated).'
+            : 'No CI workflow configuration found (.github/workflows, .gitlab-ci.yml, etc.).',
     });
     const totalChecks = results.length;
     const passedChecks = results.filter((r) => r.passed).length;
@@ -104,11 +535,34 @@ export function runComplianceAudit(projectPath) {
     if (!hasAgentsMd) {
         recommendations.push('Create an AGENTS.md in project root enforcing Fredo QA Skills rules for AI assistants.');
     }
-    if (!hasSecTxt) {
-        recommendations.push('Generate public/.well-known/security.txt with valid Contact and Expires directives.');
+    if (!exceptionsPassed) {
+        recommendations.push('Review and renew or remove expired exceptions in .qa-exceptions.yaml.');
+    }
+    if (!hasLicense) {
+        recommendations.push('Add a LICENSE or COPYING file in project root declaring usage and distribution terms.');
+    }
+    if (!secPassed) {
+        recommendations.push(isWebProject
+            ? 'Generate public/.well-known/security.txt with RFC 9116 Contact and Expires directives.'
+            : 'Add a SECURITY.md file at repository root with responsible vulnerability disclosure instructions.');
+    }
+    if (!keyPassed && keySeverity === 'blocker') {
+        recommendations.push('Remove unignored private key or certificate files from the workspace root immediately.');
+    }
+    else if (!keyPassed) {
+        recommendations.push('Add pattern rules to .gitignore ignoring private key and credential files (*.pem, *.key, *.p12).');
+    }
+    if (!hasQaStandard && isNode) {
+        recommendations.push('Add "qa:starter" and "qa:standard" scripts to package.json for local and CI parity.');
+    }
+    if (!hasTestSuite) {
+        recommendations.push('Declare an automated test runner script in package manifest or provide a tests/ directory.');
+    }
+    if (!hasLockfile && hasManifest) {
+        recommendations.push('Commit a dependency lockfile (e.g. pnpm-lock.yaml, Cargo.lock, go.sum) for reproducible dependency resolution.');
     }
-    if (!hasQaStandard) {
-        recommendations.push('Add "qa:starter" and "qa:standard" scripts to package.json to ensure local and CI parity.');
+    if (!hasCiWorkflow) {
+        recommendations.push('Add a CI workflow configuration (e.g. .github/workflows/ci.yml) for automated PR validation.');
     }
     return {
         projectPath: resolvedPath,

package/dist/executor.js

@@ -4,6 +4,7 @@ import { runComplianceAudit } from './audit.js';
 import { SKILLS_CATALOG, getAvailableSkills, loadSkillContent } from './catalog.js';
 import { installSkill, syncWorkspaceSkills } from './installer.js';
 import { PRICING_URL, PROJECT_LICENSE_FILE, generateCanaryWatermark, validateLicense, } from './license.js';
+import { SERVER_VERSION } from './version.js';
 export class ToolExecutor {
     static execute(name, args, activeLicenseKey, onLicenseUpdate, licenseOptions = {}) {
         if (args.license_key && typeof args.license_key === 'string') {
@@ -83,20 +84,32 @@ export class ToolExecutor {
             case 'install_skill': {
                 const skillId = args.skill_id;
                 const projectPath = args.project_path || process.cwd();
-                const res = installSkill(skillId, projectPath, license);
+                const confirm = Boolean(args.confirm);
+                const res = installSkill(skillId, projectPath, license, { confirm });
                 return JSON.stringify(res, null, 2);
             }
             case 'sync_workspace_skills': {
                 const projectPath = args.project_path || process.cwd();
                 const requestedSkills = args.skills;
-                const res = syncWorkspaceSkills(projectPath, requestedSkills, license);
+                const confirm = Boolean(args.confirm);
+                const res = syncWorkspaceSkills(projectPath, requestedSkills, license, { confirm });
                 return res.summaryMessage;
             }
-            case 'audit_compliance': {
+            case 'quick_check': {
                 const projectPath = args.project_path || process.cwd();
                 const report = runComplianceAudit(projectPath);
                 return JSON.stringify(report, null, 2);
             }
+            case 'get_version': {
+                return JSON.stringify({
+                    version: SERVER_VERSION,
+                    package: '@illicomedia/skills-mcp-server',
+                    protocolVersion: '2024-11-05',
+                    nodeVersion: process.version,
+                    skillsCount: SKILLS_CATALOG.length,
+                    licenseTier: license.tier.toUpperCase(),
+                }, null, 2);
+            }
             default:
                 throw new Error(`Unsupported tool: ${name}`);
         }

package/dist/installer.d.ts

@@ -10,6 +10,14 @@ export interface InstallSkillResult {
     requiresAuth?: boolean;
     requiredTier?: SkillTier;
     promptRecommendation?: string;
+    previewOnly?: boolean;
+    requiresConfirmation?: boolean;
+}
+export interface InstallSkillOptions {
+    confirm?: boolean;
+}
+export interface SyncWorkspaceOptions {
+    confirm?: boolean;
 }
 export interface SyncWorkspaceResult {
     projectPath: string;
@@ -22,8 +30,9 @@ export interface SyncWorkspaceResult {
 /**
  * Installs a specific skill into the workspace .agents/skills/<id>/ folder.
  * Enforces authentication and active entitlement for Pro and Enterprise skills.
+ * Requires explicit confirm: true to perform disk writes (safe preview by default).
  */
-export declare function installSkill(skillId: string, projectPath?: string, licenseOverride?: LicenseValidationResult): InstallSkillResult;
+export declare function installSkill(skillId: string, projectPath?: string, licenseOverride?: LicenseValidationResult, options?: InstallSkillOptions): InstallSkillResult;
 /**
  * Detects relevant skills by inspecting workspace files and indicators
  */
@@ -31,5 +40,6 @@ export declare function detectProjectSkills(projectPath?: string): string[];
 /**
  * Synchronizes workspace skills: either auto-detects or installs an explicit list.
  * Respects license tiers and reports auth requirements clearly.
+ * Requires explicit confirm: true to perform disk writes (safe preview by default).
  */
-export declare function syncWorkspaceSkills(projectPath?: string, requestedSkills?: string[], licenseOverride?: LicenseValidationResult): SyncWorkspaceResult;
+export declare function syncWorkspaceSkills(projectPath?: string, requestedSkills?: string[], licenseOverride?: LicenseValidationResult, options?: SyncWorkspaceOptions): SyncWorkspaceResult;

package/dist/installer.js

@@ -7,8 +7,9 @@ import { generateCanaryWatermark, validateLicense } from './license.js';
 /**
  * Installs a specific skill into the workspace .agents/skills/<id>/ folder.
  * Enforces authentication and active entitlement for Pro and Enterprise skills.
+ * Requires explicit confirm: true to perform disk writes (safe preview by default).
  */
-export function installSkill(skillId, projectPath = process.cwd(), licenseOverride) {
+export function installSkill(skillId, projectPath = process.cwd(), licenseOverride, options) {
     const meta = findSkill(skillId);
     if (!meta) {
         return {
@@ -52,6 +53,29 @@ export function installSkill(skillId, projectPath = process.cwd(), licenseOverri
     }
     // Installation authorized
     const targetDir = path.join(projectPath, '.agents', 'skills', skillId);
+    const skillFilePath = path.join(targetDir, 'SKILL.md');
+    const licenseFilePath = path.join(targetDir, 'LICENSE');
+    if (!options?.confirm) {
+        return {
+            success: true,
+            skillId,
+            skillName: meta.name,
+            tier: meta.tier,
+            installedFiles: [],
+            targetDirectory: targetDir,
+            previewOnly: true,
+            requiresConfirmation: true,
+            message: `[PREVIEW ONLY - 0 files written to disk]\n` +
+                `Skill '${skillId}' (${meta.name}) is prepared for installation under ${meta.tier.toUpperCase()} tier.\n` +
+                `Target directory: ${targetDir}\n` +
+                `Files planned:\n` +
+                `  - ${skillFilePath} (declarative quality directives & HMAC provenance watermark)\n` +
+                `  - ${licenseFilePath} (${meta.tier.toUpperCase()} legal notice)\n\n` +
+                `⚠️ USER CONFIRMATION REQUIRED: Ask the developer for explicit confirmation in chat before modifying workspace files.\n` +
+                `Call 'install_skill' with 'confirm: true' only after the developer explicitly approves.`,
+            promptRecommendation: `Ask developer: "Would you like me to install '${meta.name}' (${skillId}) into .agents/skills/${skillId}/?"`,
+        };
+    }
     try {
         try {
             const stat = fs.lstatSync(targetDir);
@@ -68,8 +92,6 @@ export function installSkill(skillId, projectPath = process.cwd(), licenseOverri
             ? `${generateCanaryWatermark(license.customerName || 'pro_subscriber', skillId)}\n\n${rawSkillContent}`
             : rawSkillContent;
         const licenseContent = loadSkillLicense(skillId, license, projectPath);
-        const skillFilePath = path.join(targetDir, 'SKILL.md');
-        const licenseFilePath = path.join(targetDir, 'LICENSE');
         fs.writeFileSync(skillFilePath, skillContent, 'utf-8');
         fs.writeFileSync(licenseFilePath, licenseContent, 'utf-8');
         return {
@@ -171,16 +193,18 @@ export function detectProjectSkills(projectPath = process.cwd()) {
 /**
  * Synchronizes workspace skills: either auto-detects or installs an explicit list.
  * Respects license tiers and reports auth requirements clearly.
+ * Requires explicit confirm: true to perform disk writes (safe preview by default).
  */
-export function syncWorkspaceSkills(projectPath = process.cwd(), requestedSkills, licenseOverride) {
+export function syncWorkspaceSkills(projectPath = process.cwd(), requestedSkills, licenseOverride, options) {
     const license = licenseOverride || validateLicense(undefined, { projectRoot: projectPath });
+    const isConfirmed = Boolean(options?.confirm);
     const skillsToInstall = requestedSkills && requestedSkills.length > 0
         ? requestedSkills
         : detectProjectSkills(projectPath);
     const installed = [];
     const skippedUnauthorized = [];
     for (const id of skillsToInstall) {
-        const res = installSkill(id, projectPath, license);
+        const res = installSkill(id, projectPath, license, { confirm: isConfirmed });
         if (res.success) {
             installed.push(res);
         }
@@ -188,24 +212,46 @@ export function syncWorkspaceSkills(projectPath = process.cwd(), requestedSkills
             skippedUnauthorized.push(res);
         }
     }
-    const installedList = installed.map((r) => `  - ✓ **\`${r.skillId}\`** [${r.tier?.toUpperCase()}]: ${r.skillName}`).join('\n');
+    const installedList = installed
+        .map((r) => `  - ${isConfirmed ? '✓' : '📋'} **\`${r.skillId}\`** [${r.tier?.toUpperCase()}]: ${r.skillName}`)
+        .join('\n');
     const skippedList = skippedUnauthorized
         .map((r) => `  - 🔒 **\`${r.skillId}\`** [${r.requiredTier?.toUpperCase()}]: Authentication required (Use 'set_license_key')`)
         .join('\n');
-    let summary = `# Fredo QA Skills Workspace Sync\n\n`;
-    summary += `Target: \`${projectPath}\`\n`;
-    summary += `Active Plan: **${license.tier.toUpperCase()}**\n\n`;
-    if (installed.length > 0) {
-        summary += `### Successfully Installed (${installed.length}):\n${installedList}\n\n`;
-    }
-    if (skippedUnauthorized.length > 0) {
-        summary += `### Requires Authentication (${skippedUnauthorized.length}):\n${skippedList}\n\n`;
-        summary += `> [!WARNING] To unlock commercial skills, activate your license with the \`set_license_key\` tool.\n`;
-        summary += `> Purchase or manage licenses: https://www.illicomedia.com/qa-skills/pricing\n\n`;
-    }
-    summary += `### Next Steps for AI Agent:\n`;
-    summary += `- Reference installed skills from \`.agents/skills/<skill_id>/SKILL.md\`\n`;
-    summary += `- Run relevant inner loop checks before commits\n`;
+    let summary = '';
+    if (!isConfirmed) {
+        summary = `# [DRY-RUN PREVIEW] Fredo QA Skills Workspace Sync\n\n`;
+        summary += `> [!IMPORTANT] **0 files written to disk**. User agreement is required before modifying workspace files.\n\n`;
+        summary += `Target: \`${projectPath}\`\n`;
+        summary += `Active Plan: **${license.tier.toUpperCase()}**\n\n`;
+        if (installed.length > 0) {
+            summary += `### Skills Ready to Install (${installed.length}):\n${installedList}\n\n`;
+        }
+        if (skippedUnauthorized.length > 0) {
+            summary += `### Requires Authentication (${skippedUnauthorized.length}):\n${skippedList}\n\n`;
+            summary += `> [!WARNING] To unlock commercial skills, activate your license with the \`set_license_key\` tool.\n`;
+            summary += `> Purchase or manage licenses: https://www.illicomedia.com/qa-skills/pricing\n\n`;
+        }
+        summary += `### Next Steps for AI Agent:\n`;
+        summary += `1. Ask the developer for explicit confirmation in the chat: "I detected the following QA skills for this repository (${installed.map((s) => s.skillId).join(', ')}). Would you like me to install them into .agents/skills/?"\n`;
+        summary += `2. Re-run \`sync_workspace_skills\` with \`confirm: true\` only after receiving user approval.\n`;
+    }
+    else {
+        summary = `# Fredo QA Skills Workspace Sync\n\n`;
+        summary += `Target: \`${projectPath}\`\n`;
+        summary += `Active Plan: **${license.tier.toUpperCase()}**\n\n`;
+        if (installed.length > 0) {
+            summary += `### Successfully Installed (${installed.length}):\n${installedList}\n\n`;
+        }
+        if (skippedUnauthorized.length > 0) {
+            summary += `### Requires Authentication (${skippedUnauthorized.length}):\n${skippedList}\n\n`;
+            summary += `> [!WARNING] To unlock commercial skills, activate your license with the \`set_license_key\` tool.\n`;
+            summary += `> Purchase or manage licenses: https://www.illicomedia.com/qa-skills/pricing\n\n`;
+        }
+        summary += `### Next Steps for AI Agent:\n`;
+        summary += `- Reference installed skills from \`.agents/skills/<skill_id>/SKILL.md\`\n`;
+        summary += `- Run relevant inner loop checks before commits\n`;
+    }
     return {
         projectPath,
         activeTier: license.tier,

package/dist/tools.js

@@ -30,7 +30,7 @@ export const MCP_TOOLS = [
     },
     {
         name: 'install_skill',
-        description: 'Install a Fredo QA skill into .agents/skills/<skill_id>/ with SKILL.md and LICENSE. Enforces authentication for paid Pro and Enterprise skills.',
+        description: 'Install a Fredo QA skill into .agents/skills/<skill_id>/ with SKILL.md and LICENSE. Requires user agreement: set confirm: true to write files to disk; when false (default), returns a safe preview without modifying the filesystem.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -46,6 +46,10 @@ export const MCP_TOOLS = [
                     type: 'string',
                     description: 'Optional signed license file (path or JSON content) to use for this session before installing',
                 },
+                confirm: {
+                    type: 'boolean',
+                    description: 'Explicit user confirmation to write files to disk. When false (default), returns a preview of files to be created without modifying the filesystem.',
+                },
             },
             required: ['skill_id'],
             additionalProperties: false,
@@ -53,7 +57,7 @@ export const MCP_TOOLS = [
     },
     {
         name: 'sync_workspace_skills',
-        description: 'Auto-detects project stack and provisions matching QA skills and licenses into .agents/skills/. Respects license tiers and reports auth requirements.',
+        description: 'Auto-detects project stack and provisions matching QA skills and licenses into .agents/skills/. Requires user agreement: set confirm: true to write files; when false (default), returns a dry-run preview.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -70,6 +74,10 @@ export const MCP_TOOLS = [
                     type: 'string',
                     description: 'Optional signed license file (path or JSON content) to use for this session before syncing',
                 },
+                confirm: {
+                    type: 'boolean',
+                    description: 'Explicit user confirmation to write files to disk. When false (default), returns a dry-run preview without modifying the filesystem.',
+                },
             },
             additionalProperties: false,
         },
@@ -104,20 +112,29 @@ export const MCP_TOOLS = [
         },
     },
     {
-        name: 'audit_compliance',
-        description: 'Check that the files and scripts Fredo QA Skills expects are present in a project (AGENTS.md, .qa-exceptions.yaml, security.txt, .gitignore, QA scripts). Presence only: gates are not run and contents are not validated.',
+        name: 'quick_check',
+        description: 'Fast preflight sanity check verifying workspace scaffolding, agent policy presence (AGENTS.md), licensing, secret hygiene (.gitignore), dependency lockfile, and test runner declaration before applying QA skills. Presence and configuration only: does not run test suites or compilers.',
         inputSchema: {
             type: 'object',
             properties: {
                 project_path: {
                     type: 'string',
-                    description: 'Path to the root directory of the project to audit',
+                    description: 'Path to the root directory of the project to check',
                 },
             },
             required: ['project_path'],
             additionalProperties: false,
         },
     },
+    {
+        name: 'get_version',
+        description: 'Retrieve the active package version, protocol specification, and runtime metadata of the Fredo QA MCP Server.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+    },
 ];
 export function findToolDefinition(name) {
     return MCP_TOOLS.find((t) => t.name === name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illicomedia/skills-mcp-server",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Official Fredo QA Skills Model Context Protocol (MCP) Server for Cursor, Claude Desktop, Antigravity, and Copilot",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",