@harness-engineering/cli 1.26.0 → 1.26.1

package/dist/agents/commands/codex/harness/detect-doc-drift/SKILL.md

@@ -1,191 +0,0 @@
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-
-# 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.
-
-### Graph-Enhanced Context (when available)
-
-When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate drift detection:
-
-- `query_graph` — find `documents` edges where the target code node has changed since the doc node was last updated
-
-When a graph is available, drift is simply stale edges: doc-to-code edges where the code side has been modified more recently than the doc side. This replaces regex pattern matching and catches semantic drift that text search misses. Fall back to file-based commands if no graph is available.
-
-### Pipeline Context (when orchestrated)
-
-When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
-
-- If `pipeline` field exists: read `DocPipelineContext` from it
-  - Use `pipeline.exclusions` to skip findings that were already addressed in a previous phase
-  - Write `DriftFinding[]` results back to `pipeline.driftFindings` in handoff.json
-  - This enables the orchestrator to track findings across phases and avoid double-counting
-- If `pipeline` field does not exist: behave exactly as today (standalone mode)
-
-No changes to the skill's interface or output format — the pipeline field is purely additive.
-
-### 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
-```
-
-## Rationalizations to Reject
-
-| Rationalization | Reality |
-| --- | --- |
-| "The docs are close enough -- a renamed function is obvious from context" | Renamed references in AGENTS.md cause AI agents to hallucinate about non-existent code. Precision matters. |
-| "We only changed internal code, so the docs do not need checking" | Internal API docs with wrong signatures waste developer debugging time. Changed-behavior-not-reflected drift is High priority. |
-| "There are too many findings to deal with right now, so skip the scan" | The escalation protocol exists for this case: focus on Critical and High items, create a tracking issue for the rest. |
-| "We can rely on code review to catch stale docs" | Code reviewers focus on code correctness, not documentation cross-references. harness check-docs catches what humans routinely miss. |
-
-## 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/commands/codex/harness/detect-doc-drift/agents/openai.yaml

@@ -1,3 +0,0 @@
-# Reserved for Phase B native integration
-name: detect-doc-drift
-version: "1.0.0"

package/dist/agents/commands/codex/harness/enforce-architecture/SKILL.md

@@ -1,289 +0,0 @@
-<!-- Generated by harness generate-slash-commands. Do not edit. -->
-
-# 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
-
-- **Design constraints** — when `design` config exists, also load design constraint rules:
-  - Token compliance — components must reference design tokens, not hardcoded values
-  - Accessibility compliance — color pairs must meet WCAG contrast ratios
-  - Anti-pattern enforcement — project-specific anti-patterns from `design-system/DESIGN.md`
-  - Platform binding — tokens must have appropriate platform bindings for enabled platforms
-
-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
-
-### Graph-Enhanced Context (when available)
-
-When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate violation detection:
-
-- `query_graph` — traverse `imports` edges against layer constraint nodes to find all violations in a single query
-- `get_relationships` — find all code dependent on a violation target to show the full scope of impact
-
-Graph queries show the complete violation scope (not just the first occurrence per file) and reveal transitive violations that single-file analysis misses. Fall back to file-based commands if no graph is available.
-
-### Phase 2: Run Dependency Checks
-
-1. **Run `harness check-deps`** to analyze all import statements against the constraint model. Capture the full JSON output.
-
-1b. **Optionally run `harness check-arch`** for comprehensive architecture analysis beyond dependency checking. This covers circular dependencies, complexity, coupling, module size, and dependency depth in addition to layer violations.
-
-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.
-   - **Design constraint violation** — a component uses hardcoded values instead of design tokens, or violates a declared anti-pattern. Severity depends on `design.strictness` in config. These violations surface as DESIGN-xxx codes:
-     - `DESIGN-001` [warn] — Hardcoded color/font/spacing instead of token reference
-     - `DESIGN-002` [warn] — Value matches a project anti-pattern
-     - `DESIGN-003` [error] — WCAG contrast ratio failure (error in strict mode)
-     - `DESIGN-004` [info] — Missing platform binding for enabled platform
-
-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 3.5: Apply Safe Architecture Fixes
-
-Some architecture violations can be auto-fixed. Apply these before surfacing remaining violations.
-
-**Import ordering violations:**
-
-1. Identify files where imports are not ordered according to the project's layer convention.
-2. Reorder imports: external packages first, then by layer (lowest to highest), then relative imports.
-3. Verify with lint + typecheck. This is a safe, mechanical fix.
-
-**Forbidden import replacement (with configured alternative):**
-
-1. Check `harness.config.json` for `forbiddenImports` entries that include an `alternative` field.
-2. For each violation where an alternative exists, replace the import path with the alternative.
-3. Verify with typecheck + test. This is "probably safe" -- present as a diff for approval in interactive mode, apply silently in CI mode.
-
-**Design token substitution (unambiguous mapping):**
-
-1. When a hardcoded value has exactly one matching design token, replace the literal with the token reference.
-2. Verify with typecheck + test.
-3. If the mapping is ambiguous (multiple candidate tokens), surface to user.
-
-**Never auto-fix these (always surface to user):**
-
-- Upward dependencies
-- Skip-layer dependencies
-- Circular dependencies
-- Forbidden imports without a configured alternative
-
-### Phase 3.6: Convergence Loop (Standalone)
-
-When running standalone (not through the orchestrator), apply a single-concern convergence loop:
-
-1. **Re-run detection.** After applying all safe/probably-safe fixes, run `harness check-deps` again.
-2. **Check if violation count decreased.** Compare the new count to the previous count.
-3. **If decreased: loop.** Fixing one violation can resolve others (e.g., replacing a forbidden import may eliminate a transitive skip-layer violation). Go back to Phase 2 with the new results.
-4. **If unchanged: stop.** Proceed to Phase 4 (Guide Resolution) for remaining violations.
-5. **Maximum iterations: 5.** To prevent infinite loops.
-
-**Verification gate:** After each fix batch, run:
-
-```
-pnpm lint && pnpm tsc --noEmit && pnpm test
-```
-
-If any command fails, revert the batch and reclassify those findings as unsafe.
-
-### 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:** Check `harness.config.json` for an `alternative` field. If present, this should have been auto-fixed in Phase 3.5. If not present, replace the forbidden import with the approved alternative or restructure the code.
-- **Design constraint violation:** Replace hardcoded values with token references from `design-system/tokens.json`. For anti-pattern violations, consult `design-system/DESIGN.md` for the project's aesthetic intent and approved alternatives. For contrast failures, use `harness-accessibility` to find compliant color pairs.
-
-## 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: "Hardcoded colors in components"
-
-A component uses `#3b82f6` directly instead of referencing `color.primary` from the design token system. Fix: import and reference the token. In Tailwind: use the token-mapped utility class. In CSS: use the custom property `var(--color-primary)`.
-
-### 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.
-- **`harness-design-system`** — Provides the design token source of truth (`tokens.json`) that constraints validate against.
-- **`harness-accessibility`** — Provides WCAG contrast validation used by DESIGN-003 constraints.
-- **Design constraint category** — Controlled by `design.strictness` in `harness.config.json`. Design violations surface alongside architectural violations in the same report.
-- **`harness check-arch`** — Architecture assertion framework. Runs all 7 metric collectors against baseline and thresholds. Use for comprehensive structural health checks beyond layer dependencies. Supports `--update-baseline` to capture current state and `--json` for machine-readable output.
-- **`harness check-arch --module <path>`** — Scoped architecture check for a single module. Use when validating a specific subsystem.
-
-## 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.
-
-## Evidence Requirements
-
-When this skill makes claims about existing code, architecture, or behavior,
-it MUST cite evidence using one of:
-
-1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
-2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
-   "existing bcrypt wrapper")
-3. **Test/command output:** Inline or referenced output from a test run or CLI command
-4. **Session evidence:** Write to the `evidence` session section via `manage_state`
-
-**Uncited claims:** Technical assertions without citations MUST be prefixed with
-`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
-
-## Red Flags
-
-### Universal
-
-These apply to ALL skills. If you catch yourself doing any of these, STOP.
-
-- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
-  reference. Belief is not evidence.
-- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
-  Search the codebase first. The project may already have a convention.
-- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
-  but do not expand scope beyond the stated task.
-
-### Domain-Specific
-
-- **"Auto-fixing this import to use the correct layer"** without verifying the replacement module exists — Stop. Verify the target exists and exports the needed symbol before rewriting an import.
-- **"This file is in a test directory, skipping violation"** — Stop. Test directories have architectural rules too. Check the constraint definition before assuming tests are exempt.
-- **"Removing this circular dependency by moving the import"** without tracing downstream effects — Stop. Moving imports can break consumers. Trace the dependency chain first.
-- **"This violation is from generated code, ignoring"** — Stop. Generated files can still violate architecture if the generator is misconfigured. Check the source template.
-
-## Rationalizations to Reject
-
-| Rationalization | Reality |
-| --- | --- |
-| "The violation is minor — just one import" | One violation sets a precedent. Enforce the constraint or document an explicit exception with rationale. |
-| "It works, so the architecture must be fine" | Working code with bad architecture is technical debt with compound interest. Correct function does not excuse structural violations. |
-| "This is a legacy module, different rules apply" | Legacy does not mean exempt. Either the constraint applies or it needs an explicit documented exception. |
-
-## 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/commands/codex/harness/enforce-architecture/agents/openai.yaml

@@ -1,3 +0,0 @@
-# Reserved for Phase B native integration
-name: enforce-architecture
-version: "1.0.0"