@harness-engineering/cli 1.8.0 → 1.8.1

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -398,7 +398,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### Example: 3-Phase Security Scanner
 
-**User invokes:** `/harness:autopilot docs/specs/2026-03-19-security-scanner.md`
+**User invokes:** `/harness:autopilot docs/changes/security-scanner/proposal.md`
 
 **INIT:**
 
@@ -407,7 +407,7 @@ Read spec — found 3 phases:
   Phase 1: Core Scanner (complexity: low)
   Phase 2: Rule Engine (complexity: high)
   Phase 3: CLI Integration (complexity: low)
-Created .harness/sessions/specs--2026-03-19-security-scanner/autopilot-state.json. Starting Phase 1.
+Created .harness/sessions/changes--security-scanner--proposal/autopilot-state.json. Starting Phase 1.
 ```
 
 **Phase 1 — ASSESS:**

package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md

@@ -108,9 +108,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
 
 2. **Run soundness review.** After all sections are reviewed and the spec is drafted, invoke `harness-soundness-review --mode spec` against the draft. Do not proceed to write the spec to `docs/` until the soundness review converges with no remaining issues.
 
-3. **Write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
-
-   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
+3. **Write the spec to `docs/`.** Write proposals to `docs/changes/<feature>/proposal.md`. This keeps change proposals organized by feature in a consistent location.
 
 4. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
 
@@ -216,7 +214,7 @@ Converge on a recommendation that addresses all concerns before presenting the d
 
 - **`harness validate`** — Run after writing the spec to `docs/`. Verifies project health and that the new spec file is properly placed.
 - **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
-- **Spec location** — Specs go to `docs/` (or `docs/specs/` if the project uses that convention). Follow existing naming patterns.
+- **Spec location** — Specs go to `docs/changes/<feature>/proposal.md`. Follow existing naming patterns.
 - **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
 - **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-planning. Uses confirmed transition (waits for user approval).
 
@@ -247,7 +245,7 @@ These patterns make requirements testable and unambiguous. Apply them when the o
 
 ```
 Read AGENTS.md — project is a TypeScript monorepo with React frontend and Express backend.
-Read existing docs/ — no prior notification specs. Found docs/specs/2026-01-15-user-auth.md as naming example.
+Read existing docs/ — no prior notification specs. Found docs/changes/user-auth/proposal.md as naming example.
 Checked src/services/ — no notification code exists. Found email utility in src/utils/email.ts.
 Scope assessment: single subsystem (notifications), estimated 1 week. Proceed.
 ```
@@ -293,10 +291,10 @@ Human: "Agreed, approach 2."
 **VALIDATE:**
 
 ```
-Wrote docs/specs/2026-03-14-notification-system.md
+Wrote docs/changes/notification-system/proposal.md
 Sections: Overview, Decisions, Technical Design, Success Criteria, Implementation Order
 harness validate — passes
-"Spec written to docs/specs/2026-03-14-notification-system.md. Ready for sign-off?"
+"Spec written to docs/changes/notification-system/proposal.md. Ready for sign-off?"
 Human: "Approved."
 ```
 

package/dist/agents/skills/claude-code/harness-code-review/SKILL.md

@@ -196,7 +196,7 @@ Gather context in this order until the ratio is met:
 
 1. **Files directly imported/referenced by changed files** — read the modules the changed code calls or depends on.
 2. **Corresponding test files** — find tests for changed code. If tests are missing, note this as a finding.
-3. **Spec/design docs mentioning changed components** — search `docs/specs/`, `docs/design-docs/`, `docs/plans/`.
+3. **Spec/design docs mentioning changed components** — search `docs/changes/`, `docs/design-docs/`, `docs/plans/`.
 4. **Type definitions used by changed code** — read interfaces, types, schemas consumed or produced.
 5. **Recent commits touching the same files** — see Commit History below.
 
@@ -224,7 +224,7 @@ grep -n "import\|require\|from " <changed-file>
 find . -name "*<module-name>*test*" -o -name "*<module-name>*spec*"
 
 # 4. Search for spec/design references
-grep -rl "<component-name>" docs/specs/ docs/design-docs/ docs/plans/
+grep -rl "<component-name>" docs/changes/ docs/design-docs/ docs/plans/
 
 # 5. Find type definitions
 grep -rn "interface\|type\|schema" <changed-file> | head -20

package/dist/agents/skills/claude-code/harness-planning/SKILL.md

@@ -208,7 +208,7 @@ When presenting the task breakdown, use progress markers:
 # Plan: <Feature Name>
 
 **Date:** YYYY-MM-DD
-**Spec:** docs/specs/<spec-file>.md (if applicable)
+**Spec:** docs/changes/<feature>/proposal.md (if applicable)
 **Estimated tasks:** N
 **Estimated time:** N minutes
 
@@ -286,7 +286,7 @@ When planning changes to existing functionality (not greenfield), express requir
 
 This is not mandatory for greenfield features. Only apply when modifying existing documented behavior.
 
-When `docs/specs/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
+When `docs/changes/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
 
 ## Success Criteria
 

package/dist/agents/skills/claude-code/harness-roadmap/SKILL.md

@@ -29,7 +29,6 @@ If the human has not seen and approved the milestone groupings and feature list,
 1. Check if `docs/roadmap.md` already exists.
    - If it exists: warn the human. "A roadmap already exists. Overwriting will replace it. Continue? (y/n)" Wait for confirmation before proceeding. If declined, stop.
 2. Scan for specs:
-   - `docs/specs/*.md`
    - `docs/changes/*/proposal.md`
    - Record each spec's title, status (if detectable from frontmatter or content), and file path.
 3. Scan for plans:
@@ -68,11 +67,11 @@ Unmatched plans: N (flag for review)
 
    ## Current Work
    - Feature A (in-progress) -- spec: docs/changes/feature-a/proposal.md
-   - Feature B (in-progress) -- spec: docs/specs/feature-b.md
+   - Feature B (in-progress) -- spec: docs/changes/feature-b/proposal.md
 
    ## Backlog
    - Feature C (planned) -- spec: docs/changes/feature-c/proposal.md
-   - Feature D (backlog) -- spec: docs/specs/feature-d.md
+   - Feature D (backlog) -- spec: docs/changes/feature-d/proposal.md
    ```
 
 2. Offer choices:
@@ -405,7 +404,7 @@ Choice?
 
 ## Success Criteria
 
-1. `--create` discovers all specs (`docs/specs/*.md`, `docs/changes/*/proposal.md`) and plans (`docs/plans/*.md`)
+1. `--create` discovers all specs (`docs/changes/*/proposal.md`) and plans (`docs/plans/*.md`)
 2. `--create` proposes groupings and waits for human confirmation before writing
 3. `--create` produces a valid `docs/roadmap.md` that round-trips through `parseRoadmap`/`serializeRoadmap`
 4. `--add` collects all fields interactively (milestone, status, spec, summary, blockers, plan)
@@ -452,7 +451,7 @@ Proposed Roadmap Structure:
 - Update Checker (in-progress) -- spec: docs/changes/update-checker/proposal.md
 
 ## Backlog
-- Design System (backlog) -- spec: docs/specs/design-system.md
+- Design System (backlog) -- spec: docs/changes/design-system/proposal.md
 
 Options:
   (A) Accept this structure

package/dist/agents/skills/gemini-cli/add-harness-component/SKILL.md

@@ -0,0 +1,192 @@
+# 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/skills/gemini-cli/add-harness-component/skill.yaml

@@ -0,0 +1,32 @@
+name: add-harness-component
+version: "1.0.0"
+description: Add a component to an existing harness project
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+cli:
+  command: harness skill run add-harness-component
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: add-harness-component
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on:
+  - initialize-harness-project

package/dist/agents/skills/gemini-cli/align-documentation/SKILL.md

@@ -0,0 +1,213 @@
+# Align Documentation
+
+> Sync documentation with code after implementation changes. Keep AGENTS.md, API docs, and architecture docs accurate by mapping code changes to their documentation impact.
+
+## When to Use
+
+- After completing a feature implementation (post-merge or post-commit)
+- After fixing a bug that changes observable behavior
+- After a refactoring that renames, moves, or restructures code
+- When detect-doc-drift reports findings that need fixing
+- When `on_post_feature` or `on_post_merge` triggers fire
+- NOT during active development — wait until the code is stable
+- NOT for creating documentation for a brand-new project (use validate-context-engineering for initial setup)
+- NOT for fixing code — this skill only changes documentation
+
+## Process
+
+### Phase 1: Detect — Identify What Changed
+
+1. **Run `git diff` against the appropriate baseline.** Choose the baseline based on context:
+   - After a feature: diff against the branch point (`git diff main...HEAD`)
+   - After a bug fix: diff against the commit before the fix
+   - After a refactoring: diff against the commit before refactoring started
+   - Periodic sync: diff against the last documentation sync commit
+
+2. **Extract the list of changed files.** For each changed file, note:
+   - File path (current and previous if renamed/moved)
+   - Nature of change (added, modified, deleted, renamed)
+   - Changed exports (new, removed, renamed, signature changed)
+   - Changed behavior (different return values, new error types, new side effects)
+
+3. **Run `harness check-docs`** to identify any documentation that already has broken references due to the changes.
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — find `documents` edges pointing to nodes changed in this diff
+- `get_impact` — auto-suggest which docs need updating after code changes
+
+Replaces manual doc-to-code correlation. 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
+  - Read `pipeline.driftFindings` to know which fixes to apply (pre-classified by safety)
+  - If `pipeline.fixBatch` is set, apply only those specific fixes rather than running full detection
+  - Write applied fixes as `DocFix[]` back to `pipeline.fixesApplied`
+  - This enables the convergence loop to track fix verification status
+- 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: Map — Connect Code Changes to Documentation
+
+For each changed file, identify all documentation that references it:
+
+**AGENTS.md sections:**
+
+- Knowledge map entries that reference the file path
+- Architecture descriptions that mention the module
+- Constraint documentation that references the file's layer or patterns
+- Onboarding guides that walk through the file
+
+**API documentation:**
+
+- JSDoc/TSDoc comments in the changed files themselves
+- Generated API doc pages that pull from the changed files
+- README examples that demonstrate the changed functions
+- Tutorial or guide pages that use the changed code
+
+**Architecture documentation:**
+
+- Diagrams that include the changed module
+- Data flow descriptions that reference the changed functions
+- Layer descriptions that list the changed file
+- Dependency documentation that references the changed imports
+
+**Inline code comments:**
+
+- Comments in OTHER files that reference the changed file or function
+- TODO comments that reference the changed behavior
+- Workaround comments that may no longer apply after the change
+
+### Phase 3: Generate — Draft Documentation Updates
+
+For each affected documentation location:
+
+1. **Draft the specific text change.** Show the old text and the new text. Keep the existing style and tone — documentation updates should be invisible in terms of voice.
+
+2. **Preserve context.** When updating a section, do not just change the specific reference — read the surrounding paragraph and ensure it still makes sense. A renamed function may require updating the explanatory text around it, not just the function name.
+
+3. **Handle deletions carefully.** When code is deleted, do not just delete the documentation reference. Consider whether the section should be removed entirely, replaced with information about the replacement, or noted as deprecated.
+
+4. **Add new sections when needed.** If a new module was added, draft a complete documentation section following the existing AGENTS.md structure and style.
+
+### Phase 4: Validate — Verify Documentation Accuracy
+
+1. **Run `harness check-docs`** to verify all links and references resolve correctly after the updates.
+
+2. **Cross-check each update against the actual code.** Read the updated documentation and verify every claim by looking at the code. Documentation that is wrong is worse than documentation that is missing.
+
+3. **Verify no orphaned references remain.** Search documentation files for any remaining references to old names, old paths, or deleted features.
+
+4. **Run `harness fix-drift`** to catch any remaining simple drift issues that manual review missed.
+
+### 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.
+
+5. **Commit the documentation update.** Use a commit message that references the original change: "docs: update AGENTS.md for notification service refactoring" or "docs: sync API docs after auth module rename."
+
+## What to Update
+
+### AGENTS.md Knowledge Map
+
+- File paths and module names (renamed or moved files)
+- Module purpose descriptions (changed responsibilities)
+- Constraint descriptions (new or changed rules)
+- Relationship descriptions (new or changed dependencies)
+- Gotcha sections (resolved gotchas, new gotchas)
+
+### Inline Code Comments
+
+- Function/class doc comments in the changed files (JSDoc, TSDoc)
+- Comments in other files that reference the changed code
+- TODO comments that reference completed or changed work
+- Workaround comments for issues that may now be resolved
+
+### Documentation Pages (docs/)
+
+- API reference pages that describe changed functions
+- Architecture pages that diagram changed modules
+- Tutorial and guide pages that demonstrate changed code
+- Getting-started guides if entry points changed
+- Changelog entries for user-facing changes
+
+## Harness Integration
+
+- **`harness check-docs`** — Run before and after updates. Identifies broken references and validates that all documentation links resolve.
+- **`harness fix-drift`** — Auto-fix simple drift issues (broken file paths, renamed references) after manual review confirms correctness.
+- **`harness fix-drift --json`** — Machine-readable output for tracking what was auto-fixed.
+- **`harness validate`** — Run after documentation changes to verify overall project health is maintained.
+
+## Success Criteria
+
+- `harness check-docs` passes with zero errors after documentation updates
+- Every code change from the diff has been mapped to its documentation impact
+- All file paths in documentation match current file locations
+- All function/class names in documentation match current code
+- All behavioral descriptions in documentation match current implementation
+- Documentation updates are committed with clear references to the triggering code change
+- No orphaned references to old names, paths, or deleted features remain
+
+## Examples
+
+### Example: Syncing docs after a module rename
+
+**Code change:** `src/services/mailer.ts` renamed to `src/services/email-service.ts`. Functions `sendMail()` and `formatMailBody()` renamed to `sendEmail()` and `formatEmailBody()`.
+
+**Documentation impact map:**
+
+```
+AGENTS.md:34      — "mailer.ts handles email delivery" → update path and description
+AGENTS.md:78      — "Use sendMail() for all outbound email" → update function name
+docs/api.md:156   — sendMail() API reference → update name and import path
+docs/arch.md:45   — architecture diagram lists "mailer" → update to "email-service"
+src/controllers/user-controller.ts:12 — comment "// delegates to mailer" → update
+```
+
+**Updates applied:**
+
+- AGENTS.md: updated two sections with new file path and function names
+- docs/api.md: updated function reference and import example
+- docs/arch.md: updated module name in architecture description
+- src/controllers/user-controller.ts: updated inline comment
+
+**Validation:** `harness check-docs` passes. All references resolve. Commit: "docs: sync documentation after mailer rename to email-service"
+
+### Example: Syncing docs after adding error handling
+
+**Code change:** `createUser()` in `src/services/user-service.ts` now throws `ValidationError` instead of returning `null` on invalid input.
+
+**Documentation impact map:**
+
+```
+docs/api.md:89    — "Returns null if validation fails" → update to describe thrown error
+AGENTS.md:52      — No mention of error handling → add note about ValidationError
+src/services/user-service.ts:15 — JSDoc @returns tag → update, add @throws tag
+```
+
+**Updates applied:**
+
+- docs/api.md: replaced "returns null" with "throws ValidationError" and added example
+- AGENTS.md: added note about error handling pattern in user-service section
+- JSDoc: updated @returns, added @throws ValidationError
+
+**Validation:** `harness check-docs` passes. Commit: "docs: update documentation for createUser error handling change"
+
+## Escalation
+
+- **When you cannot determine what documentation is affected:** Run `harness check-docs` for automated detection. For manual analysis, search all `.md` files and code comments for the old name/path. If the change is large, use detect-doc-drift first to get a complete inventory.
+- **When documentation is in an external system (wiki, Confluence):** Document the needed change and flag it for manual update. Include the specific text that needs changing and the correct replacement.
+- **When the code change is so large that documentation needs a rewrite:** Break the documentation update into sections. Update one section at a time, validating after each. Do not attempt a full rewrite in one pass.
+- **When you disagree with the existing documentation style:** Follow the existing style. Documentation alignment is about accuracy, not style improvement. Style changes should be a separate, deliberate effort.

package/dist/agents/skills/gemini-cli/align-documentation/skill.yaml

@@ -0,0 +1,31 @@
+name: align-documentation
+version: "1.0.0"
+description: Auto-fix documentation drift issues
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+cli:
+  command: harness skill run align-documentation
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: align-documentation
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on:
+  - detect-doc-drift