@harness-engineering/cli 1.1.1 → 1.2.2

package/dist/agents/skills/gemini-cli/detect-doc-drift/SKILL.md

@@ -1,159 +0,0 @@
-# Detect Doc Drift
-
-> Detect documentation that has drifted from code. Find stale docs before they mislead developers and AI agents.
-
-## When to Use
-
-- After completing a feature, bug fix, or refactoring
-- During code review — check if the changed files have associated docs that need updating
-- As a periodic hygiene check (weekly or per-sprint)
-- When `on_post_feature` or `on_doc_check` triggers fire
-- When onboarding reveals confusion caused by outdated documentation
-- NOT during active development — wait until the code is stable before checking docs
-- NOT for writing new documentation from scratch (use align-documentation instead)
-
-## Process
-
-### Phase 1: Scan — Run Drift Detection
-
-1. **Run `harness check-docs`** to identify all documentation issues. Capture the full output.
-
-2. **Run `harness cleanup --type drift`** for a deeper analysis that cross-references code changes against documentation references.
-
-3. **Optionally, run `git diff` against a baseline** (last release, last sprint, etc.) to identify which code files changed. This helps prioritize — docs for recently changed files are most likely to be drifted.
-
-### Phase 2: Identify — Classify Drift Types
-
-Categorize each finding into one of these drift types:
-
-**Renamed but not updated:**
-A function, class, variable, or file was renamed in code, but documentation still references the old name. This is the most common type of drift.
-
-- Example: `calculateShipping()` was renamed to `computeShippingCost()`, but AGENTS.md and three inline comments still say `calculateShipping`.
-
-**New code with no docs:**
-A new module, function, or API was added but no documentation entry exists. This is not "drift" in the strict sense but a gap that grows into drift over time.
-
-- Example: `src/services/notification-service.ts` was added two sprints ago. It has 5 public exports. No AGENTS.md section, no doc page, no inline doc comments beyond basic JSDoc.
-
-**Deleted code still referenced:**
-A file, function, or feature was removed, but documentation still describes it as if it exists. This actively misleads readers.
-
-- Example: `src/utils/legacy-parser.ts` was deleted. The architecture doc still includes it in the data flow diagram. AGENTS.md still warns about its quirks.
-
-**Changed behavior not reflected:**
-A function's signature, return type, error handling, or side effects changed, but the documentation describes the old behavior.
-
-- Example: `createUser()` now throws `ValidationError` instead of returning `null` on invalid input. The API docs still say "returns null if validation fails."
-
-**Moved code with stale paths:**
-A file or module was moved to a different directory, but documentation references the old path.
-
-- Example: `src/helpers/format.ts` was moved to `src/utils/format.ts`. Three doc files and AGENTS.md reference the old path.
-
-### Phase 3: Prioritize — Rank by Impact
-
-Not all drift is equally harmful. Prioritize fixes:
-
-**Critical (fix immediately):**
-
-- Public API documentation that describes wrong behavior — external consumers will write broken code
-- AGENTS.md sections that reference deleted files — AI agents will hallucinate about non-existent code
-- README getting-started guides with wrong commands — new developers cannot onboard
-
-**High (fix before next release):**
-
-- Internal API docs with wrong signatures — developers waste time debugging
-- Architecture docs with stale diagrams — wrong mental models lead to wrong decisions
-- Frequently accessed docs with broken links — high-traffic pages with dead ends
-
-**Medium (fix in next sprint):**
-
-- Internal docs for stable code — low change rate means low confusion rate
-- Comments in rarely modified files — few people read them
-- Edge case documentation — affects few users
-
-**Low (fix when convenient):**
-
-- Stylistic inconsistencies in docs (capitalization, formatting)
-- Redundant documentation that says the same thing in multiple places
-- Historical notes that are outdated but clearly marked as historical
-
-### Phase 4: Report — Generate Actionable Output
-
-For each drift finding, provide:
-
-1. **File and line number** of the drifted documentation
-2. **The specific stale content** (quote the exact text that is wrong)
-3. **What changed in code** (the commit, file, and nature of the change)
-4. **Suggested fix** (the replacement text or action needed)
-5. **Priority tier** (Critical / High / Medium / Low)
-
-Group findings by documentation file so that fixes can be applied file-by-file.
-
-## Harness Integration
-
-- **`harness check-docs`** — Primary tool. Scans all documentation files for broken references, stale paths, and missing entries.
-- **`harness cleanup --type drift`** — Deeper analysis that cross-references git history with documentation references to detect semantic drift.
-- **`harness cleanup --type drift --json`** — Machine-readable output for automated pipelines.
-- **`harness fix-drift`** — Auto-fix simple drift issues after review (use align-documentation skill for applying fixes).
-
-## Success Criteria
-
-- `harness check-docs` reports zero errors
-- All file paths referenced in documentation resolve to existing files
-- All function/class names referenced in documentation match current code
-- All API documentation matches current function signatures and behavior
-- No documentation references deleted files, functions, or features
-- Drift findings are prioritized and assigned to the appropriate fix cycle
-
-## Examples
-
-### Example: Renamed function detected
-
-**Drift finding:**
-
-```
-DRIFT: Renamed reference detected
-  Doc: AGENTS.md:47
-  Stale text: "Use `calculateShipping()` to compute shipping costs"
-  Code change: calculateShipping renamed to computeShippingCost (commit a1b2c3d)
-  File: src/services/shipping.ts:24
-  Priority: High
-  Suggested fix: Replace `calculateShipping()` with `computeShippingCost()`
-```
-
-### Example: Deleted file still documented
-
-**Drift finding:**
-
-```
-DRIFT: Reference to deleted file
-  Doc: docs/architecture.md:112
-  Stale text: "The legacy parser (src/utils/legacy-parser.ts) handles XML input"
-  Code change: File deleted in commit d4e5f6g, functionality merged into unified-parser.ts
-  Priority: Critical
-  Suggested fix: Update section to reference unified-parser.ts, remove legacy parser description
-```
-
-### Example: New module with no documentation
-
-**Drift finding:**
-
-```
-GAP: Undocumented module
-  File: src/services/notification-service.ts
-  Created: commit h7i8j9k (3 weeks ago)
-  Public exports: NotificationService, NotificationType, sendNotification
-  Imported by: 4 modules
-  Documentation references: 0
-  Priority: High
-  Suggested fix: Add AGENTS.md section describing purpose, constraints, and public API
-```
-
-## Escalation
-
-- **When drift is extensive (>30 findings):** Do not try to fix everything. Focus on Critical and High priority items. Create a tracking issue for the remaining items and schedule them across sprints.
-- **When you cannot determine the correct replacement text:** The code change may have been complex. Check the commit message and PR description for context. If still unclear, flag the finding for the original author to resolve.
-- **When documentation is in a format you cannot parse:** Some docs may be in wiki pages, Confluence, or other external systems. Report the finding with a link and flag it for manual review.
-- **When drift reveals a deeper problem (code changed but nobody knew):** This suggests a process gap. Recommend adding `harness check-docs` to the CI pipeline or pre-merge hooks to catch drift at the source.

package/dist/agents/skills/gemini-cli/detect-doc-drift/skill.yaml

@@ -1,30 +0,0 @@
-name: detect-doc-drift
-version: "1.0.0"
-description: Detect documentation that has drifted from code
-cognitive_mode: diagnostic-investigator
-triggers:
-  - manual
-  - on_pr
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Glob
-cli:
-  command: harness skill run detect-doc-drift
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: detect-doc-drift
-    path: string
-type: flexible
-state:
-  persistent: false
-  files: []
-depends_on: []

package/dist/agents/skills/gemini-cli/enforce-architecture/SKILL.md

@@ -1,165 +0,0 @@
-# Enforce Architecture
-
-> Validate architectural layer boundaries and detect dependency violations. No code may violate layer constraints — this is a hard gate, not a suggestion.
-
-## When to Use
-
-- Before approving any pull request or merge
-- After writing new imports or module references
-- When adding a new module or package to the project
-- When `on_pre_commit` or `on_architecture_check` triggers fire
-- After refactoring that moves code between layers or modules
-- NOT when editing documentation, configuration, or non-code files
-- NOT when the violation is intentional and requires a constraint update (escalate instead)
-
-## Process
-
-### Phase 1: Load Constraints
-
-1. **Read `harness.config.json`** to understand the project's architectural constraints. The config defines:
-   - **Layers** — ordered list of architectural layers (e.g., `ui -> service -> repository -> domain`)
-   - **Dependency rules** — which layers may import from which (typically: layers may only import from layers below them)
-   - **Forbidden imports** — specific import paths that are never allowed in certain contexts
-   - **Boundary definitions** — which directories/packages belong to which layer
-
-2. **Understand the layer model.** In a typical layered architecture:
-   - Higher layers depend on lower layers (UI depends on Service, Service depends on Repository)
-   - Lower layers NEVER depend on higher layers (Repository must not import from UI)
-   - Same-layer imports may or may not be allowed depending on project config
-   - Cross-cutting concerns (logging, config) have their own rules
-
-### Phase 2: Run Dependency Checks
-
-1. **Run `harness check-deps`** to analyze all import statements against the constraint model. Capture the full JSON output.
-
-2. **Parse the results.** Each violation includes:
-   - The violating file and line number
-   - The forbidden import target
-   - The source layer and target layer
-   - The specific rule being violated
-
-### Phase 3: Analyze Violations
-
-For each violation, determine:
-
-1. **Which layers are involved.** Identify the source file's layer and the imported module's layer. Map them to the constraint model.
-
-2. **What rule is violated.** Common violation types:
-   - **Upward dependency** — a lower layer imports from a higher layer (e.g., repository importing from UI). This is the most serious type. It creates coupling that makes the lower layer untestable in isolation.
-   - **Skip-layer dependency** — a layer reaches past its immediate neighbor (e.g., UI importing directly from Repository, bypassing Service). This breaks encapsulation and makes the middle layer pointless.
-   - **Circular dependency** — two modules or layers depend on each other. This creates fragile coupling where changing either module risks breaking the other.
-   - **Forbidden import** — a specific import that is explicitly banned (e.g., importing a database driver outside the repository layer). This prevents implementation details from leaking.
-
-3. **Explain the impact.** For each violation, state:
-   - WHY the constraint exists (what architectural property it protects)
-   - WHAT would happen if the violation were allowed to persist
-   - HOW it affects testability, maintainability, and changeability
-
-### Phase 4: Guide Resolution
-
-For each violation, provide a specific fix:
-
-- **Upward dependency:** Introduce an interface or abstraction in the lower layer. The higher layer implements it; the lower layer depends only on the abstraction. Alternatively, use dependency injection.
-- **Skip-layer dependency:** Route the call through the intermediate layer. Add a method to the Service layer that delegates to the Repository, then have the UI call the Service.
-- **Circular dependency:** Break the cycle by extracting shared types into a common module that both can depend on, or restructure so the dependency flows in one direction only.
-- **Forbidden import:** Replace the forbidden import with the approved alternative. If no alternative exists, the feature may need to live in a different layer.
-
-## Common Violation Patterns
-
-### Pattern: "I just need one thing from that layer"
-
-A UI component imports a repository function directly because "it is just one query." Fix: add the query to the Service layer. The extra indirection is the architecture working correctly.
-
-### Pattern: "Shared types across layers"
-
-Two layers both need the same type definition. Fix: place shared types in the lowest layer that both depend on, or create a dedicated `types` or `shared` module at the bottom of the layer stack.
-
-### Pattern: "Test utilities importing production code from wrong layer"
-
-Test helpers import across layer boundaries for convenience. Fix: each layer's tests should only import from that layer and below. Test utilities should follow the same constraints as production code.
-
-### Pattern: "Circular dependency through re-exports"
-
-Module A re-exports from Module B, and Module B imports from Module A. The circular dependency is hidden by the re-export. Fix: identify the true dependency direction and remove the reverse path.
-
-## Harness Integration
-
-- **`harness check-deps`** — Primary tool. Analyzes all imports against the layer model defined in `harness.config.json`. Returns structured violation data including file, line, source layer, target layer, and rule violated.
-- **`harness check-deps --json`** — Machine-readable output for automated pipelines. Use this when parsing results programmatically.
-- **`harness validate`** — Includes dependency checking as part of full project validation. Use when you want a complete health check, not just architecture.
-
-## Success Criteria
-
-- `harness check-deps` reports zero violations
-- All imports flow downward through the layer stack (or follow explicitly configured exceptions)
-- No circular dependencies exist between modules or layers
-- No forbidden imports are present anywhere in the codebase
-- Every new module is assigned to the correct layer in the config
-- The layer model in `harness.config.json` accurately reflects the intended architecture
-
-## Examples
-
-### Example: Service layer importing from UI layer
-
-**Violation from `harness check-deps`:**
-
-```
-VIOLATION: Upward dependency
-  File: src/services/user-service.ts:12
-  Import: import { UserForm } from '../components/UserForm'
-  Source layer: service (level 2)
-  Target layer: ui (level 3)
-  Rule: service layer must not depend on ui layer
-```
-
-**Impact:** The UserService now depends on a React component. It cannot be used in a CLI tool, a background job, or tested without a DOM. The service layer should be framework-agnostic.
-
-**Resolution:**
-
-```typescript
-// BEFORE (violating)
-import { UserForm } from '../components/UserForm';
-const data = UserForm.defaultValues; // using UI defaults in service
-
-// AFTER (fixed)
-// Define the defaults where they belong — in the service layer
-const DEFAULT_USER_DATA: UserInput = { name: '', email: '' };
-```
-
-### Example: Circular dependency between modules
-
-**Violation from `harness check-deps`:**
-
-```
-VIOLATION: Circular dependency detected
-  Cycle: src/services/order-service.ts -> src/services/inventory-service.ts -> src/services/order-service.ts
-  order-service imports checkStock from inventory-service
-  inventory-service imports getOrderQuantity from order-service
-```
-
-**Resolution:** Extract the shared concern into a new module:
-
-```typescript
-// src/services/stock-calculator.ts (new, shared module)
-export function calculateRequiredStock(quantity: number, reserved: number): number {
-  return quantity - reserved;
-}
-```
-
-Both services import from `stock-calculator` instead of from each other. The cycle is broken.
-
-## Gates
-
-These are hard stops. Architecture violations are not warnings — they are errors.
-
-- **No code with layer violations may be approved or merged.** If `harness check-deps` reports violations, the code must be fixed before it proceeds.
-- **No new modules without layer assignment.** Every new directory or package must be mapped to a layer in `harness.config.json` before code is written in it.
-- **No "temporary" violations.** There is no TODO for architecture. Either the code respects the constraints or it does not ship.
-- **No suppressing violations without team approval.** If a violation needs to be allowed, the constraint in `harness.config.json` must be explicitly updated with a comment explaining why.
-
-## Escalation
-
-- **When a violation seems impossible to fix within the current architecture:** The architecture may need to evolve. Escalate to the human with a clear explanation of the constraint, the use case, and why they conflict. Propose options: update the constraint, restructure the code, or add a new layer.
-- **When `harness check-deps` reports false positives:** Verify the layer assignments in `harness.config.json` are correct. If a file is assigned to the wrong layer, fix the config. If the tool is genuinely wrong, report the issue.
-- **When fixing one violation creates another:** This usually indicates a deeper structural issue. Step back and look at the dependency graph as a whole rather than fixing violations one at a time.
-- **When the team wants to change the layer model:** This is a significant architectural decision. All existing code must be migrated to the new model. Plan this as a dedicated refactoring effort, not a side task.

package/dist/agents/skills/gemini-cli/enforce-architecture/skill.yaml

@@ -1,31 +0,0 @@
-name: enforce-architecture
-version: "1.0.0"
-description: Validate architectural layer boundaries and detect circular dependencies
-cognitive_mode: meticulous-verifier
-triggers:
-  - manual
-  - on_pr
-  - on_commit
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Glob
-cli:
-  command: harness skill run enforce-architecture
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: enforce-architecture
-    path: string
-type: rigid
-state:
-  persistent: false
-  files: []
-depends_on: []