@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/codex/AGENTS.md

@@ -0,0 +1,39 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Skills
+
+This file bootstraps harness context for Codex CLI. Each skill is available as a structured workflow in the `harness/` directory.
+
+## Available Skills
+
+- **add-harness-component** — Add a component to an existing harness project
+- **cleanup-dead-code** — Detect and auto-fix dead code including dead exports, commented-out code, and orphaned dependencies
+- **detect-doc-drift** — Detect documentation that has drifted from code
+- **enforce-architecture** — Validate architectural layer boundaries, detect violations, and auto-fix import ordering and forbidden import replacement
+- **harness-architecture-advisor** — Interactive architecture advisor that surfaces trade-offs and helps humans choose
+- **harness-autopilot** — Autonomous phase execution loop — chains planning, execution, verification, and review, pausing only at human decision points
+- **harness-brainstorming** — Structured ideation and exploration with harness methodology
+- **harness-code-review** — Multi-phase code review pipeline with mechanical checks, graph-scoped context, and parallel review agents
+- **harness-codebase-cleanup** — Orchestrate dead code removal and architecture violation fixes with shared convergence loop
+- **harness-debugging** — Systematic debugging with harness validation and state tracking
+- **harness-dependency-health** — Analyze structural health of the codebase using graph metrics
+- **harness-docs-pipeline** — Orchestrator composing 4 documentation skills into a sequential pipeline with convergence-based remediation and qualitative health reporting
+- **harness-execution** — Execute a planned set of tasks with harness validation and state tracking
+- **harness-hotspot-detector** — Identify structural risk hotspots via co-change and churn analysis
+- **harness-impact-analysis** — Graph-based impact analysis — answers "if I change X, what breaks?"
+- **harness-integrity** — Unified integrity gate — chains verify (quick gate) with AI review into a single report
+- **harness-onboarding** — Onboard a new developer to a harness-managed project
+- **harness-perf** — Performance enforcement and benchmark management
+- **harness-planning** — Structured project planning with harness constraints and validation
+- **harness-refactoring** — Safe refactoring with validation before and after changes
+- **harness-release-readiness** — Audit npm release readiness, run maintenance checks, offer auto-fixes, track progress across sessions
+- **harness-roadmap** — Create and manage a unified project roadmap from existing specs and plans
+- **harness-security-scan** — Lightweight mechanical security scan for health checks
+- **harness-skill-authoring** — Create and maintain harness skills following the rich skill format
+- **harness-soundness-review** — Deep soundness analysis of specs and plans with auto-fix and convergence loop
+- **harness-supply-chain-audit** — 6-factor dependency risk evaluation for supply chain security
+- **harness-tdd** — Test-driven development integrated with harness validation
+- **harness-test-advisor** — Graph-based test selection — answers "what tests should I run?"
+- **harness-verification** — Comprehensive harness verification of project health and compliance
+- **harness-verify** — Binary pass/fail quick gate — runs test, lint, typecheck commands and returns structured result
+- **initialize-harness-project** — Scaffold a new harness-compliant project

package/dist/agents/commands/codex/harness/add-harness-component/SKILL.md

@@ -0,0 +1,195 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Add Harness Component
+
+> Add layers, documentation, components, or skills to an existing harness project with proper integration. Validate against existing constraints, wire into architecture, and verify the result.
+
+## When to Use
+
+- Adding a new layer to the project's architecture
+- Adding a new documentation file that harness should track
+- Adding a new component (module, service, package) that must be wired into existing layer boundaries
+- Adding a new skill to the project's skill library
+- When a plan calls for introducing a new architectural boundary or module
+- NOT when initializing a project from scratch (use initialize-harness-project)
+- NOT when modifying an existing component (use standard editing workflows)
+- NOT when removing components (manual process — removing requires careful dependency analysis)
+
+## Process
+
+### Phase 1: DETERMINE — Identify What to Add
+
+1. **Clarify the component type.** Ask if not obvious from context:
+   - **Layer:** A new architectural boundary (e.g., adding an "infrastructure" layer to a project that only has "business" and "data")
+   - **Document:** A documentation file that harness should track for drift detection (e.g., API docs, architecture decision records)
+   - **Component:** A code module, service, or package that lives within an existing layer
+   - **Skill:** A new harness skill definition for the project's workflow
+
+2. **Gather requirements.** For each type:
+   - **Layer:** Name, which directories belong to it, which layers it can import from, which layers can import from it
+   - **Document:** Path, what it documents, which code files it relates to
+   - **Component:** Name, which layer it belongs to, what it depends on, what will depend on it
+   - **Skill:** Name, purpose, type (rigid or flexible), triggers
+
+3. **Check prerequisites.** The project must already be initialized with harness. If `harness.yaml` does not exist, stop and run initialize-harness-project first.
+
+### Phase 2: VALIDATE — Check Against Existing Constraints
+
+1. **Read the current configuration.** Load `harness.yaml` and `AGENTS.md` to understand existing layers, constraints, and architecture.
+
+2. **Verify the new component does not conflict:**
+   - Does the layer name already exist?
+   - Does the component directory already exist?
+   - Would the new dependency relationships create circular imports?
+   - Does the component violate any existing forbidden-import rules?
+
+3. **If conflicts are found,** report them clearly: "Adding layer X would conflict with existing layer Y because [reason]. Options: [A] rename, [B] merge into existing layer, [C] restructure. Which do you prefer?"
+
+4. **Run `harness check-deps`** on the current state to establish a clean baseline. If it already fails, fix existing violations before adding new components.
+
+### Phase 3: ADD — Create the Component
+
+1. **Run `harness add` with appropriate arguments:**
+   - Layer: `harness add layer <name> --dirs <dir1,dir2> --imports <allowed-layers>`
+   - Document: `harness add doc <path> --tracks <related-code-paths>`
+   - Component: `harness add component <name> --layer <layer-name>`
+   - Skill: `harness add skill <name> --type <rigid|flexible>`
+
+2. **Review generated files and configuration changes.** `harness add` modifies `harness.yaml` and may generate template files. Check that the changes look correct.
+
+3. **Create the actual code or content.** `harness add` creates the configuration entry but not necessarily the implementation. Create the directories, files, and initial code as needed.
+
+### Phase 4: WIRE — Integrate into Architecture
+
+1. **Update imports and exports.** If the new component needs to be imported by existing code, add the imports. If existing code needs to be aware of the new layer, update barrel files or index modules.
+
+2. **Update `AGENTS.md`.** Add the new component to the architecture section. Document its purpose, boundaries, and relationships to other components. This keeps agent instructions accurate.
+
+3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.yaml` reflects the actual import graph.
+
+4. **For new skills:** Write the `skill.yaml` and `SKILL.md` files following the harness skill format. Use harness-skill-authoring for guidance on writing good skill content.
+
+### Phase 5: VERIFY — Confirm Integration
+
+1. **Run `harness validate`** to verify the full project configuration is still valid after the addition.
+
+2. **Run `harness check-deps`** to verify no dependency violations were introduced. The new component's imports must respect layer boundaries.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
+3. **If validation fails,** fix the issues before committing. Common causes:
+   - New layer not properly registered in `harness.yaml`
+   - Component placed in wrong directory for its declared layer
+   - Imports from forbidden layers
+   - `AGENTS.md` references outdated architecture
+
+4. **Commit the addition.** All new and modified files in a single atomic commit.
+
+## Harness Integration
+
+- **`harness add layer <name>`** — Register a new architectural layer with directory mappings and import rules.
+- **`harness add doc <path>`** — Register a documentation file for drift tracking.
+- **`harness add component <name> --layer <layer>`** — Register a new code component within an existing layer.
+- **`harness add skill <name> --type <type>`** — Scaffold a new skill definition.
+- **`harness validate`** — Verify project configuration after the addition.
+- **`harness check-deps`** — Verify dependency constraints are respected after the addition.
+
+## Success Criteria
+
+- The new component is properly registered in `harness.yaml`
+- The component's files exist in the correct directories for its declared layer
+- `AGENTS.md` is updated to reflect the new component
+- `harness validate` passes after the addition
+- `harness check-deps` passes after the addition (no new violations)
+- No circular dependencies were introduced
+- The addition is committed as a single atomic commit
+
+## Examples
+
+### Example: Adding a New Layer
+
+```
+Human: "We need an infrastructure layer for external API clients."
+
+DETERMINE: Adding a layer. Name: infrastructure. Dirs: src/infrastructure/.
+  Imports from: (none — infrastructure is a leaf layer, no internal dependencies).
+  Imported by: business layer (services call external APIs through infrastructure).
+
+VALIDATE:
+  Read harness.yaml — existing layers: presentation, business, data.
+  No conflict with "infrastructure" name.
+  Run: harness check-deps — passes (clean baseline).
+
+ADD:
+  harness add layer infrastructure --dirs src/infrastructure --imports none
+  mkdir -p src/infrastructure
+
+WIRE:
+  Update harness.yaml: allow business → infrastructure imports.
+  Update AGENTS.md: document infrastructure layer purpose and boundaries.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/infrastructure/
+  git commit -m "feat: add infrastructure layer for external API clients"
+```
+
+### Example: Adding a Document for Drift Tracking
+
+```
+Human: "Track our API specification for documentation drift."
+
+DETERMINE: Adding a document. Path: docs/api-spec.md.
+  Tracks: src/routes/, src/models/response.ts.
+
+ADD:
+  harness add doc docs/api-spec.md --tracks src/routes,src/models/response.ts
+
+WIRE:
+  Update AGENTS.md: note that docs/api-spec.md is tracked for drift.
+
+VERIFY:
+  harness validate  # Pass
+  git add harness.yaml AGENTS.md
+  git commit -m "feat: track API spec for documentation drift detection"
+```
+
+### Example: Adding a Component to an Existing Layer
+
+```
+Human: "Add a notification service to the business layer."
+
+DETERMINE: Adding a component. Name: notification-service. Layer: business.
+  Depends on: data layer (notification repository). Depended on by: presentation layer (routes).
+
+VALIDATE:
+  Read harness.yaml — business layer exists, maps to src/services/.
+  No existing notification-service directory.
+  business → data is an allowed import. Presentation → business is allowed.
+  Run: harness check-deps — passes.
+
+ADD:
+  harness add component notification-service --layer business
+  Create src/services/notification-service.ts
+  Create src/services/notification-service.test.ts
+
+WIRE:
+  Add export to src/services/index.ts (if barrel file exists).
+  Update AGENTS.md: add notification service to business layer component list.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/services/notification-service.*
+  git commit -m "feat: add notification service to business layer"
+```
+

package/dist/agents/commands/codex/harness/add-harness-component/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: add-harness-component
+version: "1.0.0"

package/dist/agents/commands/codex/harness/cleanup-dead-code/SKILL.md

@@ -0,0 +1,248 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Cleanup Dead Code
+
+> Entropy analysis and safe cleanup. Find unused exports, dead files, and pattern violations — then remove them without breaking anything.
+
+## When to Use
+
+- After a major refactoring or feature removal
+- When the codebase feels "heavy" — too many files, unclear what is used
+- As a periodic hygiene task (monthly or per-quarter)
+- When `on_entropy_check` triggers fire
+- After deleting a feature flag and its associated code paths
+- When `harness cleanup` reports growing entropy in the project health dashboard
+- NOT during active feature development — dead code cleanup is a separate, focused task
+- NOT when tests are failing — fix tests first, then clean up
+- NOT under time pressure — dead code removal requires careful verification
+
+## Process
+
+### Phase 1: Analyze — Run Entropy Report
+
+1. **Run `harness cleanup`** to generate a full entropy report. This analyzes:
+   - **Dead exports** — functions, classes, and constants that are exported but never imported anywhere
+   - **Unused files** — files that are not imported by any other file in the project
+   - **Pattern violations** — code that violates established project patterns (e.g., a service file without a corresponding test file)
+   - **Orphaned dependencies** — npm packages listed in package.json but never imported
+
+2. **Run `harness cleanup --type dead-code --json`** for machine-readable output focused specifically on unused code.
+
+3. **Review the report summary.** Note the total count and distribution. A few dead exports are normal; dozens suggest accumulated entropy from incomplete refactorings.
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate dead code detection:
+
+- `query_graph` — perform graph reachability analysis from entry point nodes to identify truly unreachable code
+- `get_relationships` — distinguish dynamic imports from genuinely unused code by checking edge types
+
+Graph reachability reduces false positives compared to static analysis alone, since it traces the full transitive import graph including re-exports. Fall back to file-based commands if no graph is available.
+
+### Phase 2: Categorize — Safe vs. Needs Review
+
+**Safe to auto-fix (remove without further analysis):**
+
+- Exports that are not imported anywhere AND not referenced in any config file
+- Files that are not imported anywhere AND have no side effects (no top-level execution)
+- Dead exports (non-public, zero importers) -- remove `export` keyword or delete entirely if zero internal callers
+- Commented-out code blocks -- delete commented block (dead by definition, code is in git history)
+- Orphaned npm dependencies -- remove from package.json (probably safe; needs install+test verification)
+- Unused local variables and imports within a file (linter can catch these)
+
+**Needs human review before removal:**
+
+- Exports that APPEAR unused but might be consumed dynamically (see "What NOT to Delete" below)
+- Files that appear unused but are entry points (CLI scripts, test fixtures, config files)
+- Code that is only used in specific build configurations or environments
+- Exports from a public package — external consumers may depend on them
+
+### Phase 3: Apply Safe Fixes
+
+For each item categorized as safe:
+
+1. **Remove the dead code.** Delete the export, function, file, or import.
+
+2. **Run `harness fix-drift`** to update any documentation references that pointed to the deleted code.
+
+3. **Run the full test suite.** All tests must pass. If any test fails:
+   - **STOP.** The code was not actually dead — something depends on it.
+   - **Undo the deletion immediately.**
+   - **Reclassify** the item as "needs human review" and investigate the hidden dependency.
+
+4. **Run `harness validate` and `harness check-deps`.** Both must pass.
+
+5. **Commit the cleanup.** Group related removals into logical commits (e.g., "remove unused shipping utilities" not "delete dead code").
+
+**New fix types:**
+
+- **Dead exports (non-public):** Use `detect_entropy` with `autoFix: true, fixTypes: ['dead-exports']`. The tool removes the `export` keyword. If the function/class has zero internal callers too, delete the entire declaration.
+- **Commented-out code:** Use `detect_entropy` with `autoFix: true, fixTypes: ['commented-code']`. The tool deletes commented-out code blocks. This is cosmetic and only needs lint verification.
+- **Orphaned dependencies:** Use `detect_entropy` with `autoFix: true, fixTypes: ['orphaned-deps']`. The tool removes the dep from package.json. **Must run `pnpm install && pnpm test` after** to verify nothing breaks.
+
+### Phase 3.5: Convergence Loop (Standalone)
+
+When running standalone (not through the orchestrator), apply a single-concern convergence loop:
+
+1. **Re-run detection.** After applying all safe fixes, run `harness cleanup --type dead-code` again.
+2. **Check if issue count decreased.** Compare the new count to the previous count.
+3. **If decreased: loop.** New dead code may have been exposed by the fixes (e.g., removing a dead export made a file fully unused). Go back to Phase 2 (Categorize) with the new report.
+4. **If unchanged: stop.** No more cascading fixes are possible. Proceed to Phase 4 (Report).
+5. **Maximum iterations: 5.** To prevent infinite loops, stop after 5 convergence cycles regardless.
+
+**Why convergence matters:** Removing dead code can create more dead code. For example:
+
+- Removing a dead export may make all remaining exports in a file dead, making the file itself dead.
+- Removing a dead file removes its imports, which may make other files' exports dead.
+- Removing an orphaned dep may cause lint warnings that reveal unused imports.
+
+### Phase 4: Report Remaining Items
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Dead code removal changes graph topology — skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
+For items that need human review, report:
+
+1. **What it is** — file path, export name, what it does
+2. **Why it appears dead** — no static imports found
+3. **Why it might not be dead** — dynamic import patterns, external consumers, test utilities
+4. **Recommended action** — delete with confidence, delete with caution, or keep
+
+## What NOT to Delete
+
+These patterns make code APPEAR dead when it is actually in use:
+
+### Dynamically imported modules
+
+```typescript
+// This import won't show up in static analysis
+const module = await import(`./plugins/${pluginName}`);
+```
+
+Files in a `plugins/` directory may appear unused but are loaded dynamically at runtime. Check for `import()` calls, `require()` with variables, and glob-based loading patterns.
+
+### Test utilities and fixtures
+
+```typescript
+// test-helpers.ts — only imported by test files
+export function createMockUser() { ... }
+```
+
+Test utility files may appear unused if the analysis excludes test files. Verify that `harness cleanup` includes test files in its import graph.
+
+### Type-only exports
+
+```typescript
+// Only used as a type, never as a value
+export interface UserConfig { ... }
+```
+
+Some analysis tools miss type-only imports (`import type { UserConfig }`). Verify before deleting any exported interface or type alias.
+
+### Package entry points
+
+```typescript
+// index.ts — re-exports for external consumers
+export { createClient } from './client';
+```
+
+The entry point of a package re-exports things for external consumers. These exports may have zero internal imports but are the public API.
+
+### Side-effect files
+
+```typescript
+// polyfills.ts — imported for side effects, not for exports
+import './polyfills';
+```
+
+Some files are imported for their side effects (polyfills, global registrations, CSS). They have no exports but are not dead.
+
+### Environment-specific code
+
+```typescript
+// Only used when FEATURE_FLAG_X is enabled
+if (process.env.FEATURE_FLAG_X) {
+  const handler = require('./experimental-handler');
+}
+```
+
+Code behind feature flags or environment checks may appear dead in the default configuration.
+
+## Harness Integration
+
+- **`harness cleanup`** — Full entropy analysis. Reports dead exports, unused files, pattern violations, and orphaned dependencies.
+- **`harness cleanup --type dead-code`** — Focused analysis on unused code specifically.
+- **`harness cleanup --type dead-code --json`** — Machine-readable output for automation.
+- **`harness fix-drift`** — Update documentation after removing dead code. Ensures deleted items are not still referenced in docs.
+- **`harness validate`** — Run after cleanup to verify project structure remains valid.
+- **`harness check-deps`** — Run after cleanup to verify no dependency violations were introduced.
+
+## Success Criteria
+
+- `harness cleanup` reports zero dead exports and zero unused files (or all remaining items are documented as intentional)
+- All tests pass after every deletion
+- `harness validate` and `harness check-deps` pass after cleanup
+- Documentation references to deleted code are updated or removed
+- No dynamically-imported, type-only, or side-effect code was accidentally deleted
+- Each cleanup commit is atomic and has a descriptive message explaining what was removed and why
+
+## Examples
+
+### Example: Removing unused utility functions
+
+**Entropy report:**
+
+```
+DEAD EXPORT: src/utils/string-helpers.ts
+  - capitalizeFirst() — 0 imports found
+  - truncateWithEllipsis() — 0 imports found
+  - slugify() — 3 imports found (ACTIVE, not dead)
+```
+
+**Action:** Remove `capitalizeFirst` and `truncateWithEllipsis` from the file. Keep `slugify`. Run tests — all pass. Commit: "remove unused capitalizeFirst and truncateWithEllipsis from string-helpers"
+
+### Example: Detecting a false positive
+
+**Entropy report:**
+
+```
+UNUSED FILE: src/plugins/markdown-renderer.ts
+  - 0 static imports found
+  - File contains: export default class MarkdownRenderer
+```
+
+**Investigation:** Check for dynamic imports:
+
+```typescript
+// src/plugins/index.ts
+const renderer = await import(`./${format}-renderer`);
+```
+
+**Result:** False positive. The file is loaded dynamically based on the `format` variable. Mark as intentional and add a comment in the file explaining the dynamic loading pattern.
+
+### Example: Orphaned npm dependency
+
+**Entropy report:**
+
+```
+ORPHANED DEPENDENCY: moment (package.json)
+  - 0 imports of 'moment' found in src/
+  - Last imported in commit abc123 (removed 3 months ago)
+```
+
+**Action:** Remove `moment` from package.json dependencies. Run `npm install` to update lockfile. Run tests — all pass. Commit: "remove unused moment dependency"
+
+## Escalation
+
+- **When removing code causes unexpected test failures:** The code has a hidden dependency. Undo the deletion, investigate the dependency chain, and document the finding. The code is not dead — it is just hard to trace.
+- **When the entropy report is very large (>50 items):** Do not attempt to clean everything at once. Pick the highest-confidence dead code (files with zero imports, no dynamic patterns) and clean those first. Schedule the rest across multiple sessions.
+- **When you are unsure if an export is used externally:** Check if the code is in a published package. If so, removing an export is a breaking change. Deprecate first, then remove in a major version.
+- **When dead code is tangled with live code in the same file:** Extract the live code first (using harness-refactoring), then delete the remaining dead code. Do not try to surgically remove dead code from a complex file in one step.
+

package/dist/agents/commands/codex/harness/cleanup-dead-code/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: cleanup-dead-code
+version: "1.0.0"

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

@@ -0,0 +1,182 @@
+<!-- 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
+```
+
+## 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.
+