refactor(lint): split rules and keep service business-only

Author: codeaholicguy

docs/ai/design/feature-lint-command.md

@@ -20,7 +20,7 @@ graph TD
   BaseCheck --> FS[(File System)]
   FeatureCheck --> FS
   GitCheck --> Git[(Git metadata)]
-  LintService --> Reporter[Terminal and JSON reporter]
+  CLI --> Reporter[Terminal and JSON reporter]
 ```
 
 - Key components and responsibilities
@@ -29,7 +29,7 @@ graph TD
   - Base docs checker: validate required phase template files (`docs/ai/*/README.md`).
   - Feature docs checker: validate `docs/ai/{phase}/feature-<name>.md` across lifecycle phases.
   - Git/worktree checker: evaluate feature branch/worktree convention used by `dev-lifecycle` Phase 1 prerequisite.
-  - Reporter: consistent output rows (`[OK]`, `[MISS]`, `[WARN]`) and final summary with exit code.
+  - Reporter (command-owned): consistent output rows (`[OK]`, `[MISS]`, `[WARN]`) and final summary with exit code.
 - Technology stack choices and rationale
   - TypeScript within existing CLI package for shared UX and testability.
   - Extract shell script checks into reusable TS utilities to avoid behavior drift.

docs/ai/implementation/feature-lint-command.md

@@ -43,12 +43,13 @@ description: Technical implementation notes, patterns, and code guidelines
   - Missing git repository => required failure.
   - Missing `feature-<name>` branch => required failure.
   - Missing dedicated worktree for branch => warning only.
-- Reporter supports:
+- Command rendering supports:
   - human-readable checklist output
   - JSON report output with summary and per-check metadata
 
 ### Patterns & Best Practices
 - `runLintChecks` accepts injected dependencies (`cwd`, `existsSync`, `execFileSync`) for testability.
+- Shared phase-doc rule helper keeps base/feature doc checks consistent while avoiding duplication.
 - Check results use a normalized shape (`LintCheckResult`) so rendering and JSON use one source of truth.
 - Required failures drive exit code; warnings are advisory only.
 

docs/ai/testing/feature-lint-command.md

@@ -23,6 +23,7 @@ description: Define testing approach, test cases, and quality assurance
 - [x] Branch exists + no dedicated worktree returns pass with warning.
 - [x] Missing feature branch returns required failure.
 - [x] Non-git directory in feature mode returns required failure.
+- [x] Rule-level suites cover base-docs, feature-name, and git-worktree rule behavior directly.
 
 ## Integration Tests
 **How do we test component interactions?**
@@ -48,7 +49,7 @@ description: Define testing approach, test cases, and quality assurance
 **How do we verify and communicate test results?**
 
 - Executed:
-  - `nx run cli:test -- --runInBand lint.test.ts` (pass, 2 suites / 9 tests)
+  - `nx run cli:test -- --runInBand lint.test.ts` (pass, 5 suites / 16 tests)
   - `npm run lint` in `packages/cli` (pass with pre-existing repo warnings unrelated to lint command)
 - Manual verification runs:
   - Current repo + `feature=lint-command`: pass `true`, exit code `0`, zero required failures.

packages/cli/README.md

@@ -49,6 +49,15 @@ ai-devkit init --template ./ai-devkit.init.yaml
 # Add a development phase
 ai-devkit phase requirements
 
+# Validate workspace docs readiness
+ai-devkit lint
+
+# Validate a feature's docs and git branch/worktree conventions
+ai-devkit lint --feature lint-command
+
+# Emit machine-readable output for CI
+ai-devkit lint --feature lint-command --json
+
 # Install a skill
 ai-devkit skill add <skill-registry> <skill-name>
 

packages/cli/src/__tests__/services/lint/lint.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from '@jest/globals';
 import { normalizeFeatureName, runLintChecks } from '../../../services/lint/lint.service';
 
-describe('lint utilities', () => {
+describe('lint service', () => {
   it('normalizes feature names with optional feature- prefix', () => {
     expect(normalizeFeatureName('lint-command')).toBe('lint-command');
     expect(normalizeFeatureName('feature-lint-command')).toBe('lint-command');

packages/cli/src/__tests__/services/lint/rules/base-docs.rule.lint.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from '@jest/globals';
+import { runBaseDocsRules } from '../../../../services/lint/rules/base-docs.rule';
+import { LintDependencies } from '../../../../services/lint/types';
+
+describe('base docs rule', () => {
+  it('returns ok checks when all base docs exist', () => {
+    const deps: LintDependencies = {
+      cwd: () => '/repo',
+      existsSync: () => true,
+      execFileSync: () => ''
+    };
+
+    const checks = runBaseDocsRules('/repo', deps);
+
+    expect(checks).toHaveLength(5);
+    expect(checks.every(check => check.level === 'ok')).toBe(true);
+  });
+
+  it('returns missing checks when base docs do not exist', () => {
+    const deps: LintDependencies = {
+      cwd: () => '/repo',
+      existsSync: () => false,
+      execFileSync: () => ''
+    };
+
+    const checks = runBaseDocsRules('/repo', deps);
+
+    expect(checks).toHaveLength(5);
+    expect(checks.every(check => check.level === 'miss')).toBe(true);
+    expect(checks[0].fix).toBe('Run: npx ai-devkit init');
+  });
+});

packages/cli/src/__tests__/services/lint/rules/feature-name.rule.lint.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from '@jest/globals';
+import { normalizeFeatureName, validateFeatureNameRule } from '../../../../services/lint/rules/feature-name.rule';
+
+describe('feature name rule', () => {
+  it('normalizes optional feature- prefix', () => {
+    expect(normalizeFeatureName('feature-lint-command')).toBe('lint-command');
+    expect(normalizeFeatureName('lint-command')).toBe('lint-command');
+  });
+
+  it('returns no validation check for valid names', () => {
+    const result = validateFeatureNameRule('feature-lint-command');
+
+    expect(result.check).toBeUndefined();
+    expect(result.target.branchName).toBe('feature-lint-command');
+  });
+
+  it('returns missing check for invalid names', () => {
+    const result = validateFeatureNameRule('lint command');
+
+    expect(result.check?.id).toBe('feature-name');
+    expect(result.check?.level).toBe('miss');
+  });
+});

packages/cli/src/__tests__/services/lint/rules/git-worktree.rule.lint.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from '@jest/globals';
+import { runGitWorktreeRules } from '../../../../services/lint/rules/git-worktree.rule';
+import { LintDependencies } from '../../../../services/lint/types';
+
+describe('git worktree rule', () => {
+  it('returns required failure when not in git repo', () => {
+    const deps: LintDependencies = {
+      cwd: () => '/repo',
+      existsSync: () => true,
+      execFileSync: (_file: string, args: readonly string[]) => {
+        if (args[0] === 'rev-parse') {
+          throw new Error('not git');
+        }
+        return '';
+      }
+    };
+
+    const checks = runGitWorktreeRules('/repo', 'feature-sample', deps);
+
+    expect(checks).toHaveLength(1);
+    expect(checks[0].id).toBe('git-repo');
+    expect(checks[0].required).toBe(true);
+  });
+
+  it('returns warning when branch exists and dedicated worktree is missing', () => {
+    const deps: LintDependencies = {
+      cwd: () => '/repo',
+      existsSync: () => true,
+      execFileSync: (_file: string, args: readonly string[]) => {
+        const cmd = args.join(' ');
+        if (cmd.startsWith('rev-parse')) {
+          return 'true\n';
+        }
+        if (cmd.startsWith('show-ref')) {
+          return '';
+        }
+        if (cmd.startsWith('worktree list --porcelain')) {
+          return 'worktree /repo\nbranch refs/heads/main\n\n';
+        }
+        return '';
+      }
+    };
+
+    const checks = runGitWorktreeRules('/repo', 'feature-sample', deps);
+
+    expect(checks[0].id).toBe('git-branch');
+    expect(checks[1].id).toBe('git-worktree');
+    expect(checks[1].level).toBe('warn');
+  });
+});

packages/cli/src/commands/lint.ts

@@ -13,18 +13,24 @@ export function renderLintReport(report: LintReport, options: LintOptions = {}):
     return;
   }
 
-  printCategory('base-docs', report);
+  const sections: Array<{ title: string; category: LintCheckResult['category'] }> = [
+    { title: '=== Base Structure ===', category: 'base-docs' }
+  ];
 
   if (report.feature) {
-    ui.text('');
-    ui.text(`=== Feature: ${report.feature.normalizedName} ===`);
-    printRows(report.checks.filter(check => check.category === 'feature-docs'));
-
-    ui.text('');
-    ui.text(`=== Git: ${report.feature.branchName} ===`);
-    printRows(report.checks.filter(check => check.category === 'git-worktree'));
+    sections.push(
+      { title: `=== Feature: ${report.feature.normalizedName} ===`, category: 'feature-docs' },
+      { title: `=== Git: ${report.feature.branchName} ===`, category: 'git-worktree' }
+    );
   }
 
+  sections.forEach((section, index) => {
+    if (index > 0) {
+      ui.text('');
+    }
+    printSection(section.title, section.category, report);
+  });
+
   ui.text('');
   if (report.pass) {
     ui.text('All checks passed.');
@@ -37,11 +43,8 @@ export function renderLintReport(report: LintReport, options: LintOptions = {}):
   }
 }
 
-function printCategory(category: LintCheckResult['category'], report: LintReport): void {
-  if (category === 'base-docs') {
-    ui.text('=== Base Structure ===');
-  }
-
+function printSection(title: string, category: LintCheckResult['category'], report: LintReport): void {
+  ui.text(title);
   printRows(report.checks.filter(check => check.category === category));
 }
 

packages/cli/src/services/lint/lint.service.ts

@@ -4,7 +4,7 @@ import { runBaseDocsRules } from './rules/base-docs.rule';
 import { runFeatureDocsRules } from './rules/feature-docs.rule';
 import { validateFeatureNameRule, normalizeFeatureName } from './rules/feature-name.rule';
 import { runGitWorktreeRules } from './rules/git-worktree.rule';
-import { LintCheckResult, LintDependencies, LintOptions, LintReport } from './types';
+import { FeatureTarget, LintCheckResult, LintDependencies, LintOptions, LintReport } from './types';
 
 const defaultDependencies: LintDependencies = {
   cwd: () => process.cwd(),
@@ -34,7 +34,16 @@ export function runLintChecks(
     return finalizeReport(cwd, checks);
   }
 
-  const featureValidation = validateFeatureNameRule(options.feature);
+  return runFeatureChecks(cwd, checks, options.feature, deps);
+}
+
+function runFeatureChecks(
+  cwd: string,
+  checks: LintCheckResult[],
+  rawFeature: string,
+  deps: LintDependencies
+): LintReport {
+  const featureValidation = validateFeatureNameRule(rawFeature);
   if (featureValidation.check) {
     checks.push(featureValidation.check);
     return finalizeReport(cwd, checks, featureValidation.target);
@@ -49,7 +58,7 @@ export function runLintChecks(
 function finalizeReport(
   cwd: string,
   checks: LintCheckResult[],
-  feature?: { raw: string; normalizedName: string; branchName: string }
+  feature?: FeatureTarget
 ): LintReport {
   const summary = checks.reduce(
     (acc, check) => {