feat(lint): add lint command implementation

Author: codeaholicguy

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

@@ -64,11 +64,12 @@ graph TD
     - `ai-devkit lint --feature <name>`
     - `ai-devkit lint --feature <name> --json`
 - Internal interfaces
-  - `runLint(options): Promise<number>`
-  - `checkBaseDocs(cwd): Promise<LintCheckResult[]>`
-  - `checkFeatureDocs(cwd, target): Promise<LintCheckResult[]>`
-  - `checkFeatureWorktree(cwd, target): Promise<LintCheckResult[]>`
-  - `renderLintOutput(summary, options): void`
+  - `runLintChecks(options, dependencies?): LintReport`
+  - `renderLintReport(report, options): void` (in `commands/lint`)
+  - `normalizeFeatureName(input): string`
+  - `isInsideGitWorkTreeSync(cwd): boolean`
+  - `localBranchExistsSync(cwd, branchName): boolean`
+  - `getWorktreePathsForBranchSync(cwd, branchName): string[]`
 - Request/response formats
   - Input: CLI flags and current working directory.
   - Output:
@@ -89,9 +90,10 @@ graph TD
   - JSON formatter for machine-readable mode.
 - Backend services/modules
   - `commands/lint` command entry.
-  - `services/lint` for composable checks.
-  - `utils/feature-name` normalization utility.
-  - `utils/git` helpers for worktree checks.
+  - `services/lint/lint.service.ts` for orchestration and business rules only.
+  - `services/lint/rules/*` for modular validation rules (base docs, feature docs, feature-name, git worktree).
+  - `util/git` sync helpers for git/worktree checks.
+  - `util/terminal-ui` for consistent terminal output formatting.
 - Database/storage layer
   - None.
 - Third-party integrations
@@ -122,6 +124,7 @@ graph TD
   - Single-responsibility check modules.
   - Deterministic output for CI and humans.
   - Collect-all-results reporting to surface all issues in one run.
+  - Avoid shell interpolation for git operations by using argument-based command execution.
 
 ## Non-Functional Requirements
 **How should the system perform?**

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

@@ -9,57 +9,86 @@ description: Technical implementation notes, patterns, and code guidelines
 ## Development Setup
 **How do we get started?**
 
-- Prerequisites and dependencies
-- Environment setup steps
-- Configuration needed
+- `npm install` at repository root.
+- CLI package local validation commands:
+  - `npm run lint` (from `packages/cli`)
+  - `nx run cli:test -- --runInBand lint.test.ts` (from repo root)
 
 ## Code Structure
 **How is the code organized?**
 
-- Directory structure
-- Module organization
-- Naming conventions
+- `packages/cli/src/cli.ts`
+  - Registers new `lint` command and options (`--feature`, `--json`).
+- `packages/cli/src/commands/lint.ts`
+  - Command entrypoint that runs checks, renders output, and sets process exit code.
+- `packages/cli/src/services/lint/lint.service.ts`
+  - Core lint orchestration and business logic only (no terminal rendering).
+- `packages/cli/src/services/lint/rules/`
+  - Rule modules split by concern (`base-docs`, `feature-name`, `feature-docs`, `git-worktree`).
+- `packages/cli/src/__tests__/services/lint/lint.test.ts`
+  - Unit coverage for normalization and check outcomes.
+- `packages/cli/src/__tests__/commands/lint.test.ts`
+  - Command-level coverage for orchestration and exit-code behavior.
 
 ## Implementation Notes
 **Key technical details to remember:**
 
 ### Core Features
-- Feature 1: Implementation approach
-- Feature 2: Implementation approach
-- Feature 3: Implementation approach
+- Base readiness checks validate `docs/ai/{requirements,design,planning,implementation,testing}/README.md`.
+- Feature mode normalizes `feature-<name>` and `<name>` into a shared `normalizedName`.
+- Feature names are validated as kebab-case before running feature-level checks.
+- Feature mode validates lifecycle docs:
+  - `docs/ai/{phase}/feature-<normalizedName>.md`
+- Git validation behavior:
+  - Missing git repository => required failure.
+  - Missing `feature-<name>` branch => required failure.
+  - Missing dedicated worktree for branch => warning only.
+- Reporter supports:
+  - human-readable checklist output
+  - JSON report output with summary and per-check metadata
 
 ### Patterns & Best Practices
-- Design patterns being used
-- Code style guidelines
-- Common utilities/helpers
+- `runLintChecks` accepts injected dependencies (`cwd`, `existsSync`, `execFileSync`) for testability.
+- 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.
 
 ## Integration Points
 **How do pieces connect?**
 
-- API integration details
-- Database connections
-- Third-party service setup
+- CLI wiring: Commander action in `packages/cli/src/cli.ts` calls `lintCommand`.
+- `lintCommand` delegates to `runLintChecks` then `renderLintReport`.
+- `lint.service` composes rule modules and uses `util/git` sync helpers to query `git rev-parse`, `git show-ref`, and `git worktree list --porcelain`.
+- `commands/lint` owns `renderLintReport` and uses `util/terminal-ui` for consistent user-facing output.
 
 ## Error Handling
 **How do we handle failures?**
 
-- Error handling strategy
-- Logging approach
-- Retry/fallback mechanisms
+- Git command failures are converted into deterministic lint results (miss or warn), not thrown errors.
+- Missing files are reported with explicit path and remediation guidance.
+- Output includes suggested fixes (for example `npx ai-devkit init`, `git worktree add ...`).
 
 ## Performance Considerations
 **How do we keep it fast?**
 
-- Optimization strategies
-- Caching approach
-- Query optimization
-- Resource management
+- Uses direct existence checks and small git commands only.
+- No recursive repository scans or network calls.
 
 ## Security Notes
 **What security measures are in place?**
 
-- Authentication/authorization
-- Input validation
-- Data encryption
-- Secrets management
+- Read-only filesystem and git metadata checks only.
+- No mutation of repository state.
+- Git commands use argument-based process execution (`execFileSync`) to avoid shell interpolation risks from user input.
 
+## Phase 6 Check Implementation
+
+- Design/requirements alignment: aligned for command surface, normalization, check categories, and exit behavior.
+- Deviations and gaps:
+  - Full CLI binary execution via `npm run dev -- lint ...` is currently blocked by unrelated pre-existing TypeScript errors in `src/commands/memory.ts`.
+
+## Phase 8 Code Review
+
+- Blocking issue found and resolved:
+  - `packages/cli/src/services/lint/lint.service.ts`: replaced shell-command interpolation with argument-based git execution and added feature-name validation.
+- Remaining non-blocking gap:
+  - Full CLI binary execution remains blocked by unrelated pre-existing TypeScript issues outside this feature.

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

@@ -9,36 +9,36 @@ description: Break down work into actionable tasks and estimate timeline
 ## Milestones
 **What are the major checkpoints?**
 
-- [ ] Milestone 1: Lint requirements/design approved
-- [ ] Milestone 2: `ai-devkit lint` base + feature checks implemented
-- [ ] Milestone 3: Tests, docs, and rollout complete
+- [x] Milestone 1: Lint requirements/design approved
+- [x] Milestone 2: `ai-devkit lint` base + feature checks implemented
+- [x] Milestone 3: Tests, docs, and rollout complete
 
 ## Task Breakdown
 **What specific work needs to be done?**
 
 ### Phase 1: Foundation
-- [ ] Task 1.1: Audit current CLI command registration and identify insertion point for `lint`
-- [ ] Task 1.2: Extract/reimplement `check-docs.sh` base and feature doc checks in TypeScript utilities
-- [ ] Task 1.3: Implement feature-name normalization utility (`foo` and `feature-foo` -> `foo`)
-- [ ] Task 1.4: Define shared lint result model and formatter (`ok/miss/warn`, remediation hints)
+- [x] Task 1.1: Audit current CLI command registration and identify insertion point for `lint`
+- [x] Task 1.2: Extract/reimplement `check-docs.sh` base and feature doc checks in TypeScript utilities
+- [x] Task 1.3: Implement feature-name normalization utility (`foo` and `feature-foo` -> `foo`)
+- [x] Task 1.4: Define shared lint result model and formatter (`ok/miss/warn`, remediation hints)
 
 ### Phase 2: Core Features
-- [ ] Task 2.1: Add `ai-devkit lint` command handler with base workspace checks
-- [ ] Task 2.2: Add `--feature <name>` mode with feature doc checks across all lifecycle phases
-- [ ] Task 2.3: Add git checks for `feature-<name>` branch/worktree presence and mapping
-- [ ] Task 2.4: Ensure proper exit codes and summary output for CI compatibility
+- [x] Task 2.1: Add `ai-devkit lint` command handler with base workspace checks
+- [x] Task 2.2: Add `--feature <name>` mode with feature doc checks across all lifecycle phases
+- [x] Task 2.3: Add git checks for `feature-<name>` branch/worktree presence and mapping
+- [x] Task 2.4: Ensure proper exit codes and summary output for CI compatibility
 
 ### Phase 3: Integration & Polish
-- [ ] Task 3.1: Update help text and README command documentation
-- [ ] Task 3.2: Decide whether to keep `skills/dev-lifecycle/scripts/check-docs.sh` as wrapper or migrate references to `ai-devkit lint`
-- [ ] Task 3.3: Add actionable remediation guidance in failures (`npx ai-devkit init`, worktree creation command)
-- [ ] Task 3.4: Validate behavior against existing lifecycle docs and feature naming conventions
+- [x] Task 3.1: Update help text and README command documentation
+- [x] Task 3.2: Decide whether to keep `skills/dev-lifecycle/scripts/check-docs.sh` as wrapper or migrate references to `ai-devkit lint`
+- [x] Task 3.3: Add actionable remediation guidance in failures (`npx ai-devkit init`, worktree creation command)
+- [x] Task 3.4: Validate behavior against existing lifecycle docs and feature naming conventions
 
 ### Phase 4: Validation
-- [ ] Task 4.1: Unit tests for base docs checks and feature docs checks
-- [ ] Task 4.2: Unit tests for feature normalization and git/worktree validation logic
-- [ ] Task 4.3: Integration tests for CLI exit codes and terminal output
-- [ ] Task 4.4: Manual verification on repositories with and without required docs/worktrees
+- [x] Task 4.1: Unit tests for base docs checks and feature docs checks
+- [x] Task 4.2: Unit tests for feature normalization and git/worktree validation logic
+- [x] Task 4.3: Integration tests for CLI exit codes and terminal output
+- [x] Task 4.4: Manual verification on repositories with and without required docs/worktrees
 
 ## Dependencies
 **What needs to happen in what order?**

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

@@ -9,73 +9,67 @@ description: Define testing approach, test cases, and quality assurance
 ## Test Coverage Goals
 **What level of testing do we aim for?**
 
-- Unit test coverage target (default: 100% of new/changed code)
-- Integration test scope (critical paths + error handling)
-- End-to-end test scenarios (key user journeys)
-- Alignment with requirements/design acceptance criteria
+- Unit target: 100% of new/changed lint utilities and feature normalization logic.
+- Integration target: CLI command invocation, rendered output categories, and exit code behavior.
+- Manual target: run lint flows on real workspace states (healthy and missing prerequisites).
 
 ## Unit Tests
 **What individual components need testing?**
 
-### Component/Module 1
-- [ ] Test case 1: [Description] (covers scenario / branch)
-- [ ] Test case 2: [Description] (covers edge case / error handling)
-- [ ] Additional coverage: [Description]
-
-### Component/Module 2
-- [ ] Test case 1: [Description]
-- [ ] Test case 2: [Description]
-- [ ] Additional coverage: [Description]
+### `packages/cli/src/services/lint/lint.service.ts` + `packages/cli/src/services/lint/rules/*`
+- [x] Feature name normalization accepts both `lint-command` and `feature-lint-command`.
+- [x] Invalid feature names fail fast as required failures before git checks run.
+- [x] Base docs missing case returns required failures and non-zero exit code.
+- [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.
 
 ## Integration Tests
 **How do we test component interactions?**
 
-- [ ] Integration scenario 1
-- [ ] Integration scenario 2
-- [ ] API endpoint tests
-- [ ] Integration scenario 3 (failure mode / rollback)
+- [x] Command-level test verifies `lintCommand` calls `runLintChecks` and `renderLintReport` with parsed options.
+- [x] Command-level test verifies `process.exitCode` is set from report exit code (`0` and `1` paths).
+- [x] Output rendering tests verify human-readable sections and `--json` serialization behavior.
 
 ## End-to-End Tests
 **What user flows need validation?**
 
-- [ ] User flow 1: [Description]
-- [ ] User flow 2: [Description]
-- [ ] Critical path testing
-- [ ] Regression of adjacent features
+- [x] Real workspace state (current repo) via utility execution: feature check passes with required checks satisfied.
+- [x] Missing docs scenario (temporary directory): required failures and non-zero exit code.
+- [x] Branch exists/no dedicated worktree scenario (temporary git repo): warning-only worktree result with zero exit code.
 
 ## Test Data
 **What data do we use for testing?**
 
-- Test fixtures and mocks
-- Seed data requirements
-- Test database setup
+- Dependency-injected stubs for `existsSync` and `execFileSync`.
+- Synthetic git command outputs for branch/worktree combinations.
 
 ## Test Reporting & Coverage
 **How do we verify and communicate test results?**
 
-- Coverage commands and thresholds (`npm run test -- --coverage`)
-- Coverage gaps (files/functions below 100% and rationale)
-- Links to test reports or dashboards
-- Manual testing outcomes and sign-off
+- Executed:
+  - `nx run cli:test -- --runInBand lint.test.ts` (pass, 2 suites / 9 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.
+  - Temporary directory with no docs: pass `false`, exit code `1`, required failures `5`.
+  - Temporary git repo with `feature-sample` branch but no dedicated worktree: pass `true`, exit code `0`, git warning present.
+- Current gap:
+  - Full CLI binary invocation (`npm run dev -- lint ...`) remains blocked by unrelated pre-existing TypeScript issues in `src/commands/memory.ts`.
 
 ## Manual Testing
 **What requires human validation?**
 
-- UI/UX testing checklist (include accessibility)
-- Browser/device compatibility
-- Smoke tests after deployment
+- Validate output readability and remediation commands in terminal.
+- Validate warning-only behavior when worktree is missing but branch exists.
+- Validate JSON consumers in CI pipelines that parse `--json` output.
 
 ## Performance Testing
 **How do we validate performance?**
 
-- Load testing scenarios
-- Stress testing approach
-- Performance benchmarks
+- Confirm command remains sub-second for standard repository size during manual verification.
 
 ## Bug Tracking
 **How do we manage issues?**
 
-- Issue tracking process
-- Bug severity levels
-- Regression testing strategy
-
+- Track unrelated pre-existing TypeScript issues in `src/commands/memory.ts` separately from this feature.