@nerviq/cli 1.11.0 → 1.13.0

package/src/techniques/hygiene.js

@@ -0,0 +1,294 @@
+/**
+ * Hygiene technique fragments.
+ * Generated mechanically from the legacy techniques.js monolith during HR-09.
+ */
+
+const {
+  hasFrontendSignals,
+  hasProjectFile,
+  readProjectFiles,
+  isGoProject,
+  containsEmbeddedSecret,
+} = require('./shared');
+
+module.exports = {
+  gitIgnoreClaudeTracked: {
+      id: 976,
+      name: '.claude/ tracked in git',
+      check: (ctx) => {
+        if (!ctx.fileContent('.gitignore')) return true; // no gitignore = ok
+        const lines = ctx.fileContent('.gitignore')
+          .split(/\r?\n/)
+          .map(line => line.trim())
+          .filter(line => line && !line.startsWith('#'));
+        const ignoresClaudeDir = lines.some(line => /^(\/|\*\*\/)?\.claude\/?$/.test(line));
+        const unignoresClaudeDir = lines.some(line => /^!(\/)?\.claude(\/|\*\*)?$/.test(line));
+        return !ignoresClaudeDir || unignoresClaudeDir;
+      },
+      impact: 'high',
+      rating: 4,
+      category: 'git',
+      fix: 'Remove .claude/ from .gitignore (keep .claude/settings.local.json ignored).',
+      template: null
+    },
+
+  gitIgnoreEnv: {
+      id: 917,
+      name: '.gitignore blocks .env files',
+      check: (ctx) => {
+        const gitignore = ctx.fileContent('.gitignore') || '';
+        return gitignore.includes('.env');
+      },
+      impact: 'critical',
+      rating: 5,
+      category: 'git',
+      fix: 'Add .env to .gitignore to prevent leaking secrets.',
+      template: null
+    },
+
+  gitIgnoreNodeModules: {
+      id: 91701,
+      name: '.gitignore blocks node_modules',
+      check: (ctx) => {
+        const hasNodeSignals = ctx.files.includes('package.json') ||
+          ctx.files.includes('tsconfig.json') ||
+          ctx.files.some(f => /package-lock\.json|pnpm-lock\.yaml|yarn\.lock|next\.config|vite\.config/i.test(f));
+        if (!hasNodeSignals) return null;
+        const gitignore = ctx.fileContent('.gitignore') || '';
+        return gitignore.includes('node_modules');
+      },
+      impact: 'high',
+      rating: 4,
+      category: 'git',
+      fix: 'Add node_modules/ to .gitignore.',
+      template: null
+    },
+
+  noSecretsInClaude: {
+      id: 1039,
+      name: 'CLAUDE.md has no embedded secrets',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return !containsEmbeddedSecret(md);
+      },
+      impact: 'critical',
+      rating: 5,
+      category: 'git',
+      fix: 'Remove hardcoded secrets, tokens, private keys, and connection strings from CLAUDE.md. Use environment variables or external secret stores instead.',
+      template: null
+    },
+
+  readme: {
+      id: 416,
+      name: 'Has README.md',
+      check: (ctx) => ctx.files.some(f => /^readme\.md$/i.test(f)),
+      impact: 'high',
+      rating: 4,
+      category: 'hygiene',
+      fix: 'Add a README.md with project overview, setup instructions, and usage.',
+      template: null
+    },
+
+  changelog: {
+      id: 417,
+      name: 'Has CHANGELOG.md',
+      check: (ctx) => ctx.files.some(f => /^changelog\.md$/i.test(f)),
+      impact: 'low',
+      rating: 3,
+      category: 'hygiene',
+      fix: 'Add a CHANGELOG.md to track notable changes across versions.',
+      template: null
+    },
+
+  contributing: {
+      id: 418,
+      name: 'Has CONTRIBUTING.md',
+      check: (ctx) => ctx.files.some(f => /^contributing\.md$/i.test(f)),
+      impact: 'low',
+      rating: 3,
+      category: 'hygiene',
+      fix: 'Add a CONTRIBUTING.md with contribution guidelines and code standards.',
+      template: null
+    },
+
+  license: {
+      id: 434,
+      name: 'Has LICENSE file',
+      check: (ctx) => ctx.files.some(f => /^license/i.test(f)),
+      impact: 'low',
+      rating: 3,
+      category: 'hygiene',
+      fix: 'Add a LICENSE file to clarify usage rights.',
+      template: null
+    },
+
+  editorconfig: {
+      id: 5001,
+      name: 'Has .editorconfig',
+      check: (ctx) => ctx.files.includes('.editorconfig'),
+      impact: 'low',
+      rating: 3,
+      category: 'hygiene',
+      fix: 'Add .editorconfig for consistent formatting across editors and Claude.',
+      template: null
+    },
+
+  nvmrc: {
+      id: 5002,
+      name: 'Node version pinned',
+      check: (ctx) => {
+        const hasNodeSignals = ctx.files.includes('package.json') ||
+          ctx.files.includes('tsconfig.json') ||
+          ctx.files.some(f => /package-lock\.json|pnpm-lock\.yaml|yarn\.lock|next\.config|vite\.config/i.test(f));
+        if (!hasNodeSignals) return null;
+        if (ctx.files.includes('.nvmrc') || ctx.files.includes('.node-version')) return true;
+        const pkg = ctx.jsonFile('package.json');
+        return !!(pkg && pkg.engines && pkg.engines.node);
+      },
+      impact: 'low',
+      rating: 3,
+      category: 'hygiene',
+      fix: 'Add .nvmrc, .node-version, or engines.node in package.json to pin Node version.',
+      template: null
+    },
+
+  gitAttributionDecision: {
+      id: 2015,
+      name: 'Git attribution configured',
+      check: (ctx) => {
+        const shared = ctx.jsonFile('.claude/settings.json') || {};
+        const local = ctx.jsonFile('.claude/settings.local.json') || {};
+        return shared.attribution !== undefined || local.attribution !== undefined ||
+               shared.includeCoAuthoredBy !== undefined || local.includeCoAuthoredBy !== undefined;
+      },
+      impact: 'low', rating: 3, category: 'git',
+      fix: 'Decide on git attribution: set attribution.commit or includeCoAuthoredBy in settings.',
+      template: null
+    },
+
+  gitIgnoreClaudeLocal: {
+      id: 2028,
+      name: '.gitignore excludes settings.local.json',
+      check: (ctx) => {
+        const gitignore = ctx.fileContent('.gitignore') || '';
+        return /settings\.local\.json|settings\.local/i.test(gitignore);
+      },
+      impact: 'medium', rating: 4, category: 'git',
+      fix: 'Add .claude/settings.local.json to .gitignore. Personal overrides should not be committed.',
+      template: null
+    },
+
+  envExampleExists: {
+      id: 2029,
+      name: '.env.example or .env.template exists',
+      check: (ctx) => {
+        return !!(ctx.fileContent('.env.example') || ctx.fileContent('.env.template') || ctx.fileContent('.env.sample'));
+      },
+      impact: 'low', rating: 3, category: 'hygiene',
+      fix: 'Add .env.example so new developers know which environment variables are needed.',
+      template: null
+    },
+
+  packageJsonHasScripts: {
+      id: 2030,
+      name: 'package.json has dev/test/build scripts',
+      check: (ctx) => {
+        const pkg = ctx.jsonFile('package.json');
+        if (!pkg) return null;
+        const scripts = pkg.scripts || {};
+        const has = (k) => !!scripts[k];
+        return has('test') || has('dev') || has('build') || has('start');
+      },
+      impact: 'medium', rating: 3, category: 'hygiene',
+      fix: 'Add scripts to package.json (test, dev, build). Claude uses these for verification.',
+      template: null
+    },
+
+  gitignoreClaudeLocal: {
+      id: 2036,
+      name: 'CLAUDE.local.md in .gitignore',
+      check: (ctx) => {
+        const gitignore = ctx.fileContent('.gitignore') || '';
+        return /CLAUDE\.local\.md/i.test(gitignore);
+      },
+      impact: 'medium',
+      rating: 3,
+      category: 'git',
+      fix: 'Add CLAUDE.local.md to .gitignore — it contains personal overrides that should not be committed.',
+      template: null
+    },
+
+  readmeQuality: {
+      id: 130151,
+      name: 'README has installation, usage, and contributing sections',
+      check: (ctx) => {
+        const readme = ctx.fileContent('README.md') || '';
+        if (!readme) return false;
+        return /install/i.test(readme) && /usage/i.test(readme) && /contribut/i.test(readme);
+      },
+      impact: 'medium',
+      category: 'docs-quality',
+      fix: 'Ensure README.md includes installation, usage, and contributing sections for developer onboarding.',
+      confidence: 0.7,
+    },
+
+  contributingGuide: {
+      id: 130152,
+      name: 'CONTRIBUTING.md exists',
+      check: (ctx) => ctx.files.some(f => /^contributing\.md$/i.test(f)),
+      impact: 'low',
+      category: 'docs-quality',
+      fix: 'Add CONTRIBUTING.md with contribution guidelines, code standards, and PR process.',
+      confidence: 0.7,
+    },
+
+  apiDocsGenerated: {
+      id: 130153,
+      name: 'API documentation generator configured',
+      check: (ctx) => {
+        const pkg = ctx.fileContent('package.json') || '';
+        if (/typedoc|jsdoc|apidoc|compodoc/i.test(pkg)) return true;
+        const py = readProjectFiles(ctx, /(^|\/)pyproject\.toml$/i) + readProjectFiles(ctx, /(^|\/)requirements[^/]*\.txt$/i);
+        if (/sphinx|pdoc|mkdocstrings/i.test(py)) return true;
+        if (isGoProject(ctx) && hasProjectFile(ctx, /(^|\/)doc\.go$/i)) return true;
+        return false;
+      },
+      impact: 'low',
+      category: 'docs-quality',
+      fix: 'Add an API documentation generator (typedoc, jsdoc, sphinx, godoc) for auto-generated docs.',
+      confidence: 0.7,
+    },
+
+  storybookConfigured: {
+      id: 130154,
+      name: 'Storybook configured for component docs',
+      check: (ctx) => {
+        if (!hasFrontendSignals(ctx)) return null;
+        return ctx.hasDir('.storybook') || hasProjectFile(ctx, /(^|\/)\.storybook\//i);
+      },
+      impact: 'low',
+      category: 'docs-quality',
+      fix: 'Add Storybook (.storybook/) for interactive component documentation and visual testing.',
+      confidence: 0.7,
+    },
+
+  codeOfConduct: {
+      id: 130155,
+      name: 'CODE_OF_CONDUCT.md exists',
+      check: (ctx) => ctx.files.some(f => /^code.of.conduct\.md$/i.test(f)),
+      impact: 'low',
+      category: 'docs-quality',
+      fix: 'Add CODE_OF_CONDUCT.md to set community standards and expectations.',
+      confidence: 0.7,
+    },
+
+  licenseDeclared: {
+      id: 130156,
+      name: 'LICENSE file exists',
+      check: (ctx) => ctx.files.some(f => /^license/i.test(f)),
+      impact: 'low',
+      category: 'docs-quality',
+      fix: 'Add a LICENSE file to clarify usage rights and legal terms.',
+      confidence: 0.7,
+    },
+};

package/src/techniques/instructions.js

@@ -0,0 +1,243 @@
+/**
+ * Instructions technique fragments.
+ * Generated mechanically from the legacy techniques.js monolith during HR-09.
+ */
+
+const {
+  path,
+  getClaudeHookContents,
+} = require('./shared');
+
+module.exports = {
+  claudeMd: {
+      id: 1,
+      name: 'CLAUDE.md project instructions',
+      check: (ctx) => ctx.files.includes('CLAUDE.md') || ctx.files.includes('.claude/CLAUDE.md'),
+      impact: 'critical',
+      rating: 5,
+      category: 'memory',
+      fix: 'Create CLAUDE.md with project-specific instructions, build commands, and coding conventions.',
+      template: 'claude-md'
+    },
+
+  mermaidArchitecture: {
+      id: 51,
+      name: 'Mermaid architecture diagram',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return md.includes('mermaid') || md.includes('graph ') || md.includes('flowchart ');
+      },
+      impact: 'high',
+      rating: 5,
+      category: 'memory',
+      fix: 'Add a Mermaid diagram to CLAUDE.md showing project architecture. Saves 73% tokens vs prose.',
+      template: 'mermaid'
+    },
+
+  pathRules: {
+      id: 3,
+      name: 'Path-specific rules',
+      check: (ctx) => ctx.hasDir('.claude/rules') && ctx.dirFiles('.claude/rules').length > 0,
+      impact: 'medium',
+      rating: 4,
+      category: 'memory',
+      fix: 'Add rules for different file types (frontend vs backend conventions).',
+      template: 'rules'
+    },
+
+  importSyntax: {
+      id: 763,
+      name: 'CLAUDE.md uses @path imports for modularity',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        // Current syntax is @path/to/file (no "import" keyword)
+        return /@\S+\.(md|txt|json|yml|yaml|toml)/i.test(md) || /@\w+\//.test(md);
+      },
+      impact: 'medium',
+      rating: 4,
+      category: 'memory',
+      fix: 'Use @path syntax in CLAUDE.md to split instructions into focused modules (e.g. @docs/coding-style.md). You can also use .claude/rules/ for path-specific rules.',
+      template: null
+    },
+
+  underlines200: {
+      id: 681,
+      name: 'CLAUDE.md under 200 lines (concise)',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return md.split('\n').length <= 200;
+      },
+      impact: 'medium',
+      rating: 4,
+      category: 'memory',
+      fix: 'Keep CLAUDE.md under 200 lines. Use @import or .claude/rules/ to split large instructions.',
+      template: null
+    },
+
+  xmlTags: {
+      id: 96,
+      name: 'XML tags for structured prompts',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        // Give credit for XML tags OR well-structured markdown with clear sections
+        const hasXml = md.includes('<constraints') || md.includes('<rules') ||
+          md.includes('<validation') || md.includes('<instructions');
+        const hasStructuredMd = (md.includes('## Rules') || md.includes('## Constraints') ||
+          md.includes('## Do not') || md.includes('## Never') || md.includes('## Important')) &&
+          md.split('\n').length > 20;
+        return hasXml || hasStructuredMd;
+      },
+      impact: 'medium',
+      rating: 4,
+      category: 'prompting',
+      fix: 'Add clear rules sections to CLAUDE.md. XML tags (<constraints>) are optional but improve clarity.',
+      template: null
+    },
+
+  fewShotExamples: {
+      id: 9,
+      name: 'CLAUDE.md contains code examples',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return (md.match(/```/g) || []).length >= 2;
+      },
+      impact: 'high',
+      rating: 5,
+      category: 'prompting',
+      fix: 'Add code examples (few-shot) in CLAUDE.md to show preferred patterns and conventions.',
+      template: null
+    },
+
+  roleDefinition: {
+      id: 10,
+      name: 'CLAUDE.md defines a role or persona',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /^you are a |^your role is|^act as a |persona:|behave as a /im.test(md);
+      },
+      impact: 'medium',
+      rating: 4,
+      category: 'prompting',
+      fix: 'Define a role or persona in CLAUDE.md (e.g. "You are a senior backend engineer...").',
+      template: null
+    },
+
+  constraintBlocks: {
+      id: 9601,
+      name: 'XML constraint blocks in CLAUDE.md',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /<constraints|<rules|<requirements|<boundaries/i.test(md);
+      },
+      impact: 'high',
+      rating: 5,
+      category: 'prompting',
+      fix: 'Wrap critical rules in <constraints> XML blocks for 40% better adherence.',
+      template: null
+    },
+
+  claudeLocalMd: {
+      id: 2002,
+      name: 'CLAUDE.local.md for personal overrides',
+      check: (ctx) => {
+        // CLAUDE.local.md is for personal, non-committed overrides
+        return ctx.files.includes('CLAUDE.local.md') || ctx.files.includes('.claude/CLAUDE.local.md');
+      },
+      impact: 'low',
+      rating: 2,
+      category: 'memory',
+      fix: 'Create CLAUDE.local.md for personal preferences that should not be committed (add to .gitignore).',
+      template: null
+    },
+
+  autoMemoryAwareness: {
+      id: 2012,
+      name: 'Auto-memory or memory management mentioned',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /auto.?memory|memory.*manage|remember|persistent.*context/i.test(md);
+      },
+      impact: 'low', rating: 3, category: 'memory',
+      fix: 'Claude Code supports auto-memory for cross-session learning. Mention your memory strategy if relevant.',
+      template: null
+    },
+
+  negativeInstructions: {
+      id: 2019,
+      name: 'CLAUDE.md includes "do not" instructions',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /do not|don't|never|avoid|must not/i.test(md);
+      },
+      impact: 'medium', rating: 4, category: 'prompting',
+      fix: 'Add explicit "do not" rules to CLAUDE.md. Negative constraints reduce common mistakes.',
+      template: null
+    },
+
+  outputStyleGuidance: {
+      id: 2020,
+      name: 'CLAUDE.md includes output or style guidance',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /coding style|naming convention|code style|style guide|formatting rules|\bprefer\b.*\b(single|double|tabs|spaces|camel|snake|kebab|named|default|const|let|arrow|function)\b/i.test(md);
+      },
+      impact: 'medium', rating: 3, category: 'prompting',
+      fix: 'Add coding style and naming conventions to CLAUDE.md so Claude matches your project patterns.',
+      template: null
+    },
+
+  projectDescriptionInClaudeMd: {
+      id: 2022,
+      name: 'CLAUDE.md describes what the project does',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /what.*does|overview|purpose|about|description|project.*is/i.test(md) && md.length > 100;
+      },
+      impact: 'high', rating: 4, category: 'memory',
+      fix: 'Start CLAUDE.md with a clear project description. Claude needs to know what your project does.',
+      template: null
+    },
+
+  directoryStructureInClaudeMd: {
+      id: 2023,
+      name: 'CLAUDE.md documents directory structure',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        return /src\/|app\/|lib\/|structure|director|folder/i.test(md);
+      },
+      impact: 'medium', rating: 4, category: 'memory',
+      fix: 'Document your directory structure in CLAUDE.md so Claude navigates your codebase efficiently.',
+      template: null
+    },
+
+  hookExitCodesDefined: {
+      id: 110003,
+      name: 'Hook scripts handle exit codes correctly',
+      check: (ctx) => {
+        const hookContents = getClaudeHookContents(ctx);
+        if (hookContents.length === 0) return null;
+        return hookContents.some(content => /process\.exit|exit\s+[012]|sys\.exit|return\s+[012]/i.test(content));
+      },
+      impact: 'low', rating: 3, category: 'governance',
+      fix: 'Hooks should use explicit exit codes: 0=success, 1=warning, 2=block. See Claude Code docs.',
+      template: null,
+      confidence: 0.7,
+    },
+
+  loopSafetyBoundaries: {
+      id: 110004,
+      name: 'Loop safety boundaries configured',
+      check: (ctx) => {
+        const md = ctx.claudeMdContent() || '';
+        const settings = ctx.fileContent('.claude/settings.json') || '';
+        const hookContents = getClaudeHookContents(ctx).join('\n');
+        const loopSafetyConfig = [md, settings, hookContents].filter(Boolean).join('\n');
+  
+        return /max[-_ ]?turns|maxTurns|max[-_ ]?tokens|maxTokens|loop(?:[-_ ]?(?:limit|limits|safety|guard|budget|boundary|boundaries))|iteration(?:[-_ ]?(?:limit|limits|guard|budget|cap|caps|count|max(?:imum)?))/i.test(loopSafetyConfig);
+      },
+      impact: 'medium', rating: 4, category: 'governance',
+      fix: 'Document loop safety limits such as maxTurns, maxTokens, or iteration caps in CLAUDE.md, settings, or hook guards.',
+      template: null,
+      confidence: 0.8,
+    },
+};