@harness-engineering/cli 1.0.1 → 1.1.0

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

@@ -0,0 +1,182 @@
+# 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.
+
+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/claude-code/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/claude-code/align-documentation/SKILL.md

@@ -0,0 +1,181 @@
+# 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.
+
+### 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.
+
+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/claude-code/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

package/dist/agents/skills/claude-code/check-mechanical-constraints/SKILL.md

@@ -0,0 +1,191 @@
+# Check Mechanical Constraints
+
+> Run all mechanical constraint checks: linter rules, boundary schemas, and forbidden imports. These are automated, enforceable rules — if it can be checked by a machine, it must be.
+
+## When to Use
+
+- Before every commit (ideally via pre-commit hook)
+- Before submitting a pull request for review
+- After any code generation or automated refactoring
+- When `on_pre_commit` or `on_validate` triggers fire
+- After resolving merge conflicts (constraints may have been silently violated)
+- NOT as a substitute for code review — mechanical constraints catch structural issues, not logic errors
+- NOT when only editing non-code files (docs, config) unless those files have their own schema constraints
+
+## Process
+
+### Phase 1: Run All Checks
+
+1. **Run `harness validate`** to check project-wide constraints: file structure, naming conventions, required files, and configuration validity.
+
+2. **Run `harness linter validate`** to check all linter rules: code style, import restrictions, forbidden patterns, and boundary schemas.
+
+3. **Run `harness check-deps`** to check architectural layer boundaries. This is included here because dependency violations are mechanical — they can be detected purely from import statements and the constraint config.
+
+4. **Capture all output.** Combine results from all three commands into a single violation list for triage.
+
+### Phase 2: Categorize Violations by Severity
+
+Organize violations into three tiers:
+
+**Tier 1 — Errors (must fix before commit):**
+
+- Forbidden imports (importing banned modules)
+- Layer boundary violations (importing across architectural boundaries)
+- Schema violations (config files that do not match required schema)
+- Missing required files (every package must have index.ts, etc.)
+
+**Tier 2 — Warnings (must fix before merge):**
+
+- Naming convention violations (wrong casing, wrong prefix)
+- Import ordering issues
+- Unused exports detected by linter
+- Documentation file references that do not resolve
+
+**Tier 3 — Info (fix when convenient):**
+
+- Style suggestions (formatting that does not affect behavior)
+- Complexity warnings (functions exceeding thresholds)
+- Minor inconsistencies with project conventions
+
+### Phase 3: Auto-Fix Where Safe
+
+Some violations can be fixed automatically without risk:
+
+- **Import ordering** — reorder imports to match the configured convention. This never changes behavior.
+- **Formatting** — apply the project's formatter (prettier, etc.). Pure whitespace and style changes.
+- **Simple forbidden imports** — when a forbidden import has a known replacement (e.g., `import lodash` to `import lodash-es`), apply the substitution.
+- **Missing trailing commas, semicolons** — mechanical formatting fixes.
+
+**Rules for auto-fix:**
+
+- ONLY auto-fix violations that cannot change runtime behavior
+- Run the test suite after auto-fixing to confirm nothing broke
+- Present the auto-fix diff to the user for awareness (do not silently change code)
+- If unsure whether a fix is safe, do NOT auto-fix — report it for manual resolution
+
+### Phase 4: Report Remaining Violations
+
+For each violation that was not auto-fixed, report:
+
+1. **File and line number** — exact location of the violation
+2. **Rule name** — which constraint was violated
+3. **What it protects against** — why this rule exists (see reference below)
+4. **How to fix** — specific guidance for resolving this type of violation
+5. **Severity tier** — whether it blocks commit, merge, or is informational
+
+## What Each Constraint Type Protects Against
+
+### Forbidden Imports
+
+**Protects against:** Implementation detail leakage and unwanted coupling. When a library is forbidden in a layer, it is because using it there would create a dependency that makes the layer harder to test, replace, or maintain. Example: forbidding `fs` in the UI layer ensures UI code never directly accesses the filesystem.
+
+### Layer Boundaries
+
+**Protects against:** Architectural erosion. Without enforced boundaries, codebases gradually become a tangle where everything depends on everything. Layer boundaries ensure changes in one area do not ripple unpredictably through the whole system.
+
+### Boundary Schemas
+
+**Protects against:** Configuration drift and invalid state. When config files must match a schema, you catch invalid configurations at lint time rather than at runtime. This prevents deployment failures and hard-to-debug runtime errors.
+
+### Naming Conventions
+
+**Protects against:** Cognitive overhead and inconsistency. Consistent naming means developers (human and AI) can predict file locations, function names, and module structure without searching. It also ensures automated tools that rely on naming patterns continue to work.
+
+### Required File Rules
+
+**Protects against:** Incomplete modules. When every package must have an `index.ts` or every component must have a test file, you ensure that the project structure remains complete and navigable.
+
+### Import Ordering
+
+**Protects against:** Merge conflicts and readability issues. Consistent import ordering reduces git conflicts when multiple developers add imports to the same file. It also makes imports scannable at a glance.
+
+## Harness Integration
+
+- **`harness validate`** — Project-wide structural validation. Checks file structure, naming conventions, required files, and configuration schemas.
+- **`harness validate --json`** — Machine-readable output for parsing and categorization.
+- **`harness linter validate`** — Runs all configured linter rules. Checks code patterns, import restrictions, and style conventions.
+- **`harness check-deps`** — Architectural boundary enforcement. Checks all imports against the layer model.
+- **`harness check-deps --json`** — Machine-readable dependency check output.
+
+## Success Criteria
+
+- All three commands (`harness validate`, `harness linter validate`, `harness check-deps`) pass with zero errors
+- All Tier 1 violations are resolved before any commit
+- All Tier 2 violations are resolved before any merge to main
+- Auto-fixed changes are verified by running the test suite
+- No violations are suppressed without explicit team approval and a documented reason
+
+## Examples
+
+### Example: Forbidden import detected
+
+**Violation:**
+
+```
+ERROR [forbidden-import] src/components/Dashboard.tsx:3
+  Import 'pg' is forbidden in layer 'ui'
+  Rule: ui layer must not import database drivers
+```
+
+**What it protects against:** The UI layer importing a PostgreSQL driver means UI code could execute raw SQL queries, bypassing the service and repository layers entirely. This breaks testability (tests need a real database) and security (SQL injection risk from UI layer).
+
+**Fix:** Remove the direct database call. Add the needed query to the appropriate repository, expose it through the service layer, and call the service from the UI component.
+
+### Example: Auto-fixable import ordering
+
+**Violation:**
+
+```
+WARNING [import-order] src/services/auth-service.ts:1-8
+  Imports are not in the configured order
+  Expected: builtin -> external -> internal -> relative
+  Found: relative -> external -> builtin
+```
+
+**Auto-fix applied:**
+
+```typescript
+// BEFORE
+import { hashPassword } from './utils';
+import bcrypt from 'bcrypt';
+import { createHash } from 'crypto';
+
+// AFTER (auto-fixed)
+import { createHash } from 'crypto';
+import bcrypt from 'bcrypt';
+import { hashPassword } from './utils';
+```
+
+Tests re-run: all passing. No behavioral change.
+
+### Example: Schema violation in config
+
+**Violation:**
+
+```
+ERROR [schema-violation] harness.config.json:24
+  Property 'layers[2].allowedImports' must be an array of strings
+  Found: number (42)
+  Schema: harness-config-schema.json#/properties/layers/items/properties/allowedImports
+```
+
+**What it protects against:** An invalid config means `harness check-deps` will either crash or silently skip validation. The layer constraints would not be enforced, allowing violations to slip through undetected.
+
+**Fix:** Correct the config value to be a valid string array: `"allowedImports": ["@shared/types", "@shared/utils"]`.
+
+## Gates
+
+These are hard stops. Mechanical constraints are non-negotiable.
+
+- **No commits with Tier 1 violations.** Errors must be resolved before the code is committed. No exceptions.
+- **No merges with Tier 2 violations.** Warnings must be resolved before merging to the main branch.
+- **No suppressing rules without documentation.** If a rule must be disabled for a specific line or file, the suppression comment must explain WHY (not just disable the rule).
+- **No auto-fix without test verification.** Every auto-fix must be followed by a test run to confirm no behavioral change.
+
+## Escalation
+
+- **When a rule seems wrong for the project:** Rules are configured in `harness.config.json` and linter configs. If a rule does not fit, propose a config change with justification. Do not disable the rule inline.
+- **When a violation cannot be fixed without a larger refactor:** Document the violation, create a task for the refactor, and get team approval for a temporary inline suppression with a TODO linking to the task.
+- **When auto-fix produces unexpected changes:** Undo the auto-fix, report the issue, and fix manually. Auto-fix tools are not infallible.
+- **When multiple constraints conflict:** The stricter constraint wins. If `harness validate` says a file is required but `harness linter validate` says its contents violate a rule, fix the contents to satisfy both. Escalate if truly irreconcilable.

package/dist/agents/skills/claude-code/check-mechanical-constraints/skill.yaml

@@ -0,0 +1,32 @@
+name: check-mechanical-constraints
+version: "1.0.0"
+description: Run all mechanical constraint checks (context validation + architecture)
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run check-mechanical-constraints
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: check-mechanical-constraints
+    path: string
+type: rigid
+state:
+  persistent: false
+  files: []
+depends_on:
+  - validate-context-engineering
+  - enforce-architecture