agentic-engineering-harness 0.4.16

package/policies/core/trust-boundary.rego

@@ -0,0 +1,17 @@
+package harness.trust_boundary
+
+# Input shape expected from the harness policy adapter:
+# {
+#   "changedFiles": [...],
+#   "frozenPatterns": [...],
+#   "workerRole": "implementation-worker"
+# }
+#
+# Pattern expansion is intentionally performed by the harness before OPA.
+
+default allow := true
+
+deny contains "implementation worker changed a frozen artifact" if {
+  input.workerRole == "implementation-worker"
+  count(input.frozenChangedFiles) > 0
+}

package/presets/agents/default.jsonc

@@ -0,0 +1,80 @@
+{
+  "version": 1,
+  "activeProfile": "balanced",
+  "skillRoots": [".harness/skills", ".agents/skills", ".opencode/skills"],
+  "runtimes": {
+    "codex": { "adapter": "codex", "paseoProvider": "codex", "command": "codex", "capabilities": { "nativeAgent": false, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true } },
+    "opencode": { "adapter": "opencode", "paseoProvider": "opencode", "command": "opencode", "capabilities": { "nativeAgent": true, "nativeAgentViaPaseo": false, "modelSelection": true, "variantSelection": true, "sessions": true, "structuredOutput": true } }
+  },
+  "models": {
+    "brain": { "runtime": "codex", "provider": "openai", "model": "gpt-5.6-luna", "variant": "max" },
+    "workhorse": { "runtime": "opencode", "provider": "opencode-go", "model": "deepseek-v4-flash" }
+  },
+  "agents": {
+    "lead": { "role": "orchestrator", "domains": ["*"], "description": "Own intent, decomposition, dependency ordering, risk decisions and final semantic acceptance. Delegate repository work to the narrowest specialist; do not perform implementation edits. Preserve sealed requirements and use human-on-exception only when the answer cannot be derived from repository evidence or normative artifacts.", "execution": { "model": "@brain" }, "skills": ["engineering-workflow", "lead-engineer", "verification-planning", "worktree-lifecycle"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }, "outputContract": "orchestrator" },
+    "planner": { "role": "planner", "domains": ["*"], "description": "Produce bounded delegation plans from requirements, changed areas, dependencies, findings and validation evidence. Remain read-only, identify parallelizable work, required reviewers and validation gates, and never silently change normative scope.", "execution": { "model": "@brain" }, "skills": ["routing-normalizer", "verification-planning", "acceptance-traceability"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }, "outputContract": "planner" },
+    "oracle": { "role": "escalation", "domains": ["*"], "description": "Diagnose persistent, ambiguous, cycling or cross-cutting failures using repository evidence and sealed requirements. Distinguish implementation defects from spec contradictions, missing product decisions and unavailable external resources. Do not edit files.", "execution": { "model": "@brain" }, "skills": ["recovery-classifier", "simplify"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "deny", "review": "allow", "validate": "allow", "gitWrite": "deny" }, "outputContract": "recovery" },
+    "explorer": { "role": "explorer", "domains": ["*"], "description": "Perform fast repository discovery: locate relevant files, symbols, tests, ownership boundaries and nearby patterns. Return evidence and paths rather than speculative redesigns. Remain read-only.", "execution": { "model": "@workhorse" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "delegate": "deny", "review": "deny", "validate": "deny", "gitWrite": "deny" } },
+    "librarian": { "role": "librarian", "domains": ["*"], "description": "Research authoritative documentation and project-local knowledge needed by another agent. Prefer primary sources and report exact constraints, versions and citations; do not modify repository files.", "execution": { "model": "@workhorse" }, "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "deny", "network": "allow", "delegate": "deny", "review": "deny", "validate": "deny", "gitWrite": "deny" } },
+    "designer": { "role": "reviewer", "domains": ["design", "ui", "ux", "frontend"], "description": "Review user-facing interface structure, interaction clarity, accessibility implications and consistency with the repository design system. Use browser evidence when useful, but do not mutate source or replace deterministic UI tests.", "execution": { "model": "@workhorse" }, "mcps": ["playwright", "context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "github-manager": { "role": "coordinator", "domains": ["github", "delivery", "repository"], "description": "Inspect GitHub issues, pull requests, actions and repository metadata and perform first-pass delivery triage. GitHub MCP access is intentionally read-only by default; deterministic Harness delivery code owns issue and branch writes.", "execution": { "model": "@workhorse" }, "skills": ["github-delivery-lifecycle", "worktree-lifecycle"], "mcps": ["github"], "permissions": { "read": "allow", "write": "deny", "shell": "deny", "network": "allow", "delegate": "deny", "review": "allow", "gitWrite": "deny" } },
+
+    "implementation-worker": { "role": "implementer", "domains": ["*"], "description": "Implement bounded tasks that do not require a narrower domain specialist. Make the smallest coherent change, preserve public contracts unless explicitly authorized, add focused tests and report concrete validation evidence.", "execution": { "model": "@workhorse" }, "skills": ["implementation-worker", "verification-planning"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "backend-implementer": { "role": "implementer", "domains": ["backend", "server", "services", "api"], "description": "Implement server-side behavior, domain/application services, API handlers and integration boundaries. Preserve architecture and API contracts, enforce authorization at the correct boundary, and add unit/integration coverage for changed behavior.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "frontend-implementer": { "role": "implementer", "domains": ["frontend", "web", "ui", "ux"], "description": "Implement web UI, routing, client state, forms and service integration while preserving accessibility, responsive behavior and existing design-system conventions. Add focused component or browser coverage where useful.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "data-implementer": { "role": "implementer", "domains": ["data", "database", "schema", "migration", "persistence"], "description": "Implement persistence, schema and migration changes with explicit compatibility and rollback awareness. Preserve data invariants, avoid destructive migration shortcuts and update repository/integration tests for changed persistence behavior.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "mobile-implementer": { "role": "implementer", "domains": ["mobile", "ios", "android", "react-native"], "description": "Implement mobile flows, platform integration, navigation, state and native-facing behavior while preserving platform conventions, offline/error behavior and shared API contracts. Add focused mobile tests where the stack supports them.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "test-implementer": { "role": "implementer", "domains": ["test", "tests", "testing", "e2e"], "description": "Create or repair tests that prove observable requirements rather than implementation trivia. Prefer deterministic fixtures, cover regressions and edge cases, and never weaken assertions merely to make a run pass.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning", "acceptance-traceability"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "docs-implementer": { "role": "implementer", "domains": ["docs", "documentation"], "description": "Update developer/user documentation to match implemented behavior, commands, configuration and operational constraints. Keep examples executable and avoid documenting behavior that is not present in code.", "execution": { "model": "@workhorse" }, "skills": ["prompt-drift-audit"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "ops-implementer": { "role": "implementer", "domains": ["ops", "devops", "ci", "cd", "docker", "deployment", "infrastructure", "delivery"], "description": "Implement CI/CD, container, build and operational configuration changes conservatively. Preserve reproducibility, least privilege and local developer workflows; validate commands/configuration rather than relying on textual inspection alone.", "execution": { "model": "@workhorse" }, "skills": ["github-delivery-lifecycle", "worktree-lifecycle", "verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "quality-implementer": { "role": "implementer", "domains": ["*"], "description": "Perform targeted remediation of normalized review findings. Resolve mandatory findings first, reduce aggregate quality debt without broadening scope, avoid churn on subjective low-value issues and preserve deterministic behavior.", "execution": { "model": "@workhorse" }, "skills": ["finding-dedup", "simplify"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+    "senior-implementer": { "role": "implementer", "domains": ["*"], "description": "Handle high-risk or persistent remediation that defeated cheaper workers. Re-evaluate local design assumptions against sealed requirements, make the smallest architecture-consistent correction and leave a clear validation trail.", "execution": { "model": "@brain" }, "skills": ["verification-planning", "simplify", "recovery-classifier"], "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "ask", "delegate": "deny", "gitWrite": "deny" }, "outputContract": "implementer" },
+
+    "code-quality-reviewer": { "role": "reviewer", "domains": ["*"], "description": "Review the diff for correctness, maintainability, unnecessary complexity, error handling and regression risk. Findings must be concrete, evidenced and actionable; avoid style-only noise already enforced by deterministic tooling.", "execution": { "model": "@workhorse" }, "skills": ["finding-dedup", "simplify"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "requirements-reviewer": { "role": "reviewer", "domains": ["requirements", "acceptance", "*"], "description": "Trace implemented behavior back to sealed requirements and acceptance criteria. Flag missing, partial or contradictory coverage and distinguish product ambiguity from ordinary implementation defects.", "execution": { "model": "@brain" }, "skills": ["acceptance-traceability"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "architecture-reviewer": { "role": "reviewer", "domains": ["architecture"], "description": "Review dependency direction, module boundaries, coupling, layering and architectural invariants. Use actual structural evidence; do not invent a redesign when the requested change is consistent with existing architecture.", "execution": { "model": "@brain" }, "skills": ["acceptance-traceability"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "security-reviewer": { "role": "reviewer", "domains": ["security", "authentication", "authorization", "auth"], "description": "Review trust boundaries, authentication/authorization, tenant or resource isolation, secrets, injection, unsafe deserialization and privilege changes. Prioritize exploitable evidence and concrete attack paths over speculative checklists.", "execution": { "model": "@brain" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "api-reviewer": { "role": "reviewer", "domains": ["api", "contract"], "description": "Review API compatibility, request/response semantics, validation, error models, versioning and contract drift. Flag undocumented breaking changes and mismatches between implementation, generated schemas and consumers.", "execution": { "model": "@workhorse" }, "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "backend-reviewer": { "role": "reviewer", "domains": ["backend", "server", "services"], "description": "Review server-side correctness, domain boundaries, transactions, concurrency, error handling and integration behavior. Require evidence tied to changed code and tests.", "execution": { "model": "@workhorse" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "frontend-reviewer": { "role": "reviewer", "domains": ["frontend", "web", "ui", "ux"], "description": "Review user-visible behavior, state consistency, loading/error paths, accessibility, routing and client/API integration. Prefer reproducible UI or browser evidence for behavioral findings.", "execution": { "model": "@workhorse" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "data-reviewer": { "role": "reviewer", "domains": ["data", "database", "schema", "migration", "persistence"], "description": "Review schema safety, migration ordering, data invariants, query behavior, indexing implications and transactional consistency. Treat irreversible/destructive migration risk explicitly.", "execution": { "model": "@workhorse" }, "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "mobile-reviewer": { "role": "reviewer", "domains": ["mobile", "ios", "android", "react-native"], "description": "Review mobile navigation, platform behavior, lifecycle/state, offline/error paths, accessibility and API integration. Account for platform-specific regressions rather than treating mobile as a web viewport.", "execution": { "model": "@workhorse" }, "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "test-reviewer": { "role": "reviewer", "domains": ["test", "tests", "testing", "e2e"], "description": "Review whether tests prove the intended behavior, catch the regression, cover meaningful edges and avoid brittle implementation coupling. Flag missing validation, vacuous assertions and false-positive test structure.", "execution": { "model": "@workhorse" }, "skills": ["acceptance-traceability", "verification-planning"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "validate": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "docs-reviewer": { "role": "reviewer", "domains": ["docs", "documentation"], "description": "Review documentation for factual consistency with the resulting code, commands and configuration. Flag stale examples, missing operational caveats and misleading migration guidance.", "execution": { "model": "@workhorse" }, "skills": ["prompt-drift-audit"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+    "ops-reviewer": { "role": "reviewer", "domains": ["ops", "devops", "ci", "cd", "docker", "deployment", "infrastructure", "delivery"], "description": "Review build, CI/CD, deployment and container changes for reproducibility, least privilege, secret handling, caching correctness and rollback/operability risk.", "execution": { "model": "@workhorse" }, "skills": ["github-delivery-lifecycle", "worktree-lifecycle"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "review": "allow", "gitWrite": "deny" }, "outputContract": "reviewer" },
+
+    "validator": { "role": "validator", "domains": ["*"], "description": "Execute or interpret deterministic project validation without modifying source. Report exact commands, exit codes and evidence; never convert a failed deterministic gate into a semantic pass.", "execution": { "model": "@workhorse" }, "skills": ["deterministic-validation", "verification-planning"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "deny", "validate": "allow", "gitWrite": "deny" }, "outputContract": "validator" },
+    "integration-validator": { "role": "validator", "domains": ["integration"], "description": "Validate the integrated change after implementation streams converge. Check cross-module/API/data interactions, disclose command evidence and identify the owning remediation agent for any actionable integration failure.", "execution": { "model": "@workhorse" }, "skills": ["acceptance-traceability", "finding-dedup", "prompt-drift-audit", "verification-planning"], "mcps": ["context7"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "validate": "allow", "review": "allow", "gitWrite": "deny" }, "outputContract": "validator" },
+    "e2e-validator": { "role": "validator", "domains": ["e2e", "browser", "journey"], "description": "Validate end-to-end behavior through the project's actual E2E tooling. Focus on observable user/system journeys, capture failing evidence and avoid substituting manual reasoning for runnable checks.", "execution": { "model": "@workhorse" }, "skills": ["verification-planning", "acceptance-traceability"], "mcps": ["playwright"], "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "validate": "allow", "review": "allow", "gitWrite": "deny" }, "outputContract": "validator" }
+  },
+  "profiles": {
+    "economy": { "description": "Use the workhorse aggressively; keep only control/escalation roles on the brain model.", "agents": { "*-reviewer": { "execution": { "model": "@workhorse" } }, "lead": { "execution": { "model": "@brain" } }, "planner": { "execution": { "model": "@brain" } }, "oracle": { "execution": { "model": "@brain" } }, "senior-implementer": { "execution": { "model": "@brain" } } } },
+    "balanced": { "description": "Use the workhorse for bounded work/review and the brain for planning, architecture, security, requirements and escalation.", "agents": { "*-reviewer": { "execution": { "model": "@workhorse" } }, "architecture-reviewer": { "execution": { "model": "@brain" } }, "security-reviewer": { "execution": { "model": "@brain" } }, "requirements-reviewer": { "execution": { "model": "@brain" } }, "lead": { "execution": { "model": "@brain" } }, "planner": { "execution": { "model": "@brain" } }, "oracle": { "execution": { "model": "@brain" } }, "senior-implementer": { "execution": { "model": "@brain" } } } },
+    "maximum-quality": { "description": "Run all semantic reviewers on the brain while bounded implementation remains on the workhorse until escalation is needed.", "agents": { "*-reviewer": { "execution": { "model": "@brain" } }, "designer": { "execution": { "model": "@brain" } }, "lead": { "execution": { "model": "@brain" } }, "planner": { "execution": { "model": "@brain" } }, "oracle": { "execution": { "model": "@brain" } }, "senior-implementer": { "execution": { "model": "@brain" } } } }
+  },
+  "routing": [
+    { "id": "backend", "priority": 60, "when": { "intent": "implement", "domains": ["backend", "server", "services"] }, "use": "backend-implementer", "reviewers": ["backend-reviewer"] },
+    { "id": "frontend", "priority": 60, "when": { "intent": "implement", "domains": ["frontend", "web", "ui", "ux"] }, "use": "frontend-implementer", "reviewers": ["frontend-reviewer"] },
+    { "id": "design-review", "priority": 48, "when": { "intent": "implement", "domains": ["ui", "ux", "design"] }, "reviewers": ["designer"] },
+    { "id": "data", "priority": 60, "when": { "intent": "implement", "domains": ["data", "database", "schema", "migration", "persistence"] }, "use": "data-implementer", "reviewers": ["data-reviewer"] },
+    { "id": "mobile", "priority": 60, "when": { "intent": "implement", "domains": ["mobile", "ios", "android", "react-native"] }, "use": "mobile-implementer", "reviewers": ["mobile-reviewer"] },
+    { "id": "tests", "priority": 60, "when": { "intent": "implement", "domains": ["test", "tests", "testing", "e2e"] }, "use": "test-implementer", "reviewers": ["test-reviewer"] },
+    { "id": "docs", "priority": 60, "when": { "intent": "implement", "domains": ["docs", "documentation"] }, "use": "docs-implementer", "reviewers": ["docs-reviewer"] },
+    { "id": "ops", "priority": 60, "when": { "intent": "implement", "domains": ["ops", "devops", "ci", "cd", "docker", "deployment", "infrastructure", "delivery"] }, "use": "ops-implementer", "reviewers": ["ops-reviewer"] },
+    { "id": "api-review", "priority": 45, "when": { "intent": "implement", "domains": ["api", "contract"] }, "reviewers": ["api-reviewer"] },
+    { "id": "security-review", "priority": 50, "when": { "intent": "implement", "domains": ["security", "authentication", "authorization", "auth"] }, "reviewers": ["security-reviewer"] },
+    { "id": "architecture-review", "priority": 40, "when": { "intent": "implement", "domains": ["architecture"] }, "reviewers": ["architecture-reviewer"] },
+    { "id": "high-risk-review", "priority": 35, "when": { "intent": "implement", "risk": "high" }, "reviewers": ["architecture-reviewer", "requirements-reviewer"] },
+    { "id": "default-implementation", "priority": 0, "when": { "intent": "implement" }, "use": "implementation-worker", "reviewers": ["code-quality-reviewer", "requirements-reviewer"], "validators": ["validator"] }
+  ],
+  "recovery": {
+    "PATCH_CONTEXT_MISMATCH": [{ "action": "same-agent" }, { "action": "agent", "agent": "quality-implementer" }, { "action": "lead" }],
+    "TOOL_FAILURE": [{ "action": "same-agent" }, { "action": "agent", "agent": "quality-implementer" }, { "action": "lead" }],
+    "MISSING_CONTEXT": [{ "action": "same-agent" }, { "action": "lead" }],
+    "WRONG_AGENT": [{ "action": "reroute" }, { "action": "lead" }],
+    "VALIDATION_FAILURE": [{ "action": "same-agent" }, { "action": "agent", "agent": "quality-implementer" }, { "action": "agent", "agent": "senior-implementer" }],
+    "REVIEW_FAILURE": [{ "action": "agent", "agent": "quality-implementer" }, { "action": "agent", "agent": "senior-implementer" }, { "action": "lead" }],
+    "AMBIGUOUS_OUTPUT": [{ "action": "same-agent" }, { "action": "lead" }],
+    "CONFLICTING_RESULTS": [{ "action": "agent", "agent": "oracle" }, { "action": "lead" }]
+  }
+}

package/presets/docker.yaml

@@ -0,0 +1,4 @@
+id: containers
+recommended:
+  localRuntime: podman-rootless
+  fallbackRuntime: docker-engine

package/presets/dotnet.yaml

@@ -0,0 +1,12 @@
+id: dotnet
+validation:
+  commands:
+    - id: dotnet-build
+      command: dotnet build --no-restore
+      required: true
+    - id: dotnet-test
+      command: dotnet test --no-build
+      required: true
+recommended:
+  acceptance: Reqnroll
+  integration: Testcontainers

package/presets/expo.yaml

@@ -0,0 +1,6 @@
+id: expo
+validation:
+  commands:
+    - id: expo-typecheck
+      command: pnpm typecheck
+      required: true

package/presets/generic.yaml

@@ -0,0 +1,3 @@
+id: generic
+validation:
+  commands: []

package/presets/nextjs.yaml

@@ -0,0 +1,8 @@
+id: nextjs
+validation:
+  commands:
+    - id: next-build
+      command: pnpm build
+      required: true
+recommended:
+  e2e: Playwright

package/presets/node.yaml

@@ -0,0 +1,6 @@
+id: node
+validation:
+  commands:
+    - id: npm-test
+      command: npm test
+      required: true

package/presets/pnpm.yaml

@@ -0,0 +1,6 @@
+id: pnpm
+validation:
+  commands:
+    - id: pnpm-test
+      command: pnpm test
+      required: true

package/presets/postgres.yaml

@@ -0,0 +1,4 @@
+id: postgres
+recommended:
+  integration: Testcontainers PostgreSQL
+  migrationGate: required

package/schemas/agent-output-planner.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"Planner output","type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","items":{"type":"object","required":["id","summary","agent","scope","dependencies","acceptance","risk"],"properties":{"id":{"type":"string"},"summary":{"type":"string"},"agent":{"type":"string"},"scope":{"type":"array","items":{"type":"string"}},"dependencies":{"type":"array","items":{"type":"string"}},"acceptance":{"type":"array","minItems":1,"items":{"type":"string"}},"risk":{"enum":["low","medium","high"]}}}}}}

package/schemas/agent-topology.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/JamesMorales04/agentic-engineering-harness/schemas/agent-topology.schema.json",
+  "title": "Agentic Engineering Harness Agent Topology Layer",
+  "type": "object",
+  "required": ["version"],
+  "anyOf": [
+    { "required": ["extends"] },
+    { "required": ["runtimes", "models", "agents"] }
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "extends": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "activeProfile": { "type": "string" },
+    "skillRoots": { "type": "array", "items": { "type": "string" } },
+    "runtimes": { "type": "object", "additionalProperties": { "type": "object" } },
+    "models": { "type": "object", "additionalProperties": { "type": "object" } },
+    "agents": { "type": "object", "additionalProperties": { "type": "object" } },
+    "profiles": { "type": "object" },
+    "routing": { "type": "array", "items": { "type": "object", "required": ["id", "when"] } },
+    "recovery": { "type": "object" },
+    "councils": { "type": "object" },
+    "remove": {
+      "type": "object",
+      "properties": {
+        "runtimes": { "type": "array", "items": { "type": "string" } },
+        "models": { "type": "array", "items": { "type": "string" } },
+        "agents": { "type": "array", "items": { "type": "string" } },
+        "profiles": { "type": "array", "items": { "type": "string" } },
+        "routing": { "type": "array", "items": { "type": "string" } },
+        "councils": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/project.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/JamesMorales04/agentic-engineering-harness/schemas/project.schema.json",
+  "title": "Agentic Engineering Harness project configuration",
+  "type": "object",
+  "required": ["version", "project"],
+  "properties": {
+    "version": { "const": 1 },
+    "project": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 } } },
+    "agents": { "type": "object", "properties": { "configPath": { "type": "string" }, "generatedPath": { "type": "string" }, "activeProfile": { "type": "string" }, "required": { "type": "boolean" }, "findingsDir": { "type": "string" } } },
+    "workflow": { "type": "object", "properties": {
+      "quick": { "type": "object", "properties": { "maxFiles": { "type": "integer", "minimum": 1 }, "disallowedDomains": { "type": "array", "items": { "type": "string" } } } },
+      "issueIntake": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "snapshotDir": { "type": "string" }, "verifyDriftOnRun": { "type": "boolean" }, "requireOpen": { "type": "boolean" }, "plannerAgent": { "type": "string", "minLength": 1 }, "autoHandoff": { "type": "boolean" } } },
+      "reviews": { "type": "object", "properties": {
+        "enabled": { "type": "boolean" }, "reviewQuick": { "type": "boolean" }, "leadAcceptance": { "type": "boolean" }, "leadAcceptanceQuick": { "type": "boolean" },
+        "maxRemediationRounds": { "type": "integer", "minimum": 0, "deprecated": true },
+        "blockingSeverities": { "type": "array", "deprecated": true, "items": { "enum": ["critical", "high", "medium", "low", "note"] } },
+        "quality": { "type": "object", "properties": { "severityPoints": { "$ref": "#/$defs/severityNumbers" } } },
+        "convergence": { "type": "object", "properties": { "minimumDebtPointImprovement": { "type": "integer", "minimum": 0 }, "stagnationWindow": { "type": "integer", "minimum": 1 }, "cycleDetection": { "type": "boolean" }, "regressionDetection": { "type": "boolean" } } },
+        "finalQualityGate": { "type": "object", "properties": { "maxBySeverity": { "$ref": "#/$defs/severityNumbers" }, "maxDebtPoints": { "type": "integer", "minimum": 0 } } },
+        "escalation": { "type": "object", "properties": { "criticalStartStage": { "type": "integer", "minimum": 0 }, "replanResumeStage": { "type": "integer", "minimum": 0 }, "stages": { "type": "array", "items": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 }, "action": { "enum": ["remediate", "diagnose", "replan"] }, "agent": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 } } } } } }
+      } }
+    } },
+    "orchestration": { "type": "object", "properties": { "provider": { "type": "string" }, "required": { "type": "boolean" }, "worker": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "maxRepairAttempts": { "type": "integer", "minimum": 0 }, "timeoutSeconds": { "type": "integer", "minimum": 1 }, "titlePrefix": { "type": "string" } } } } },
+    "toolchain": { "type": "object", "properties": { "configPath": { "type": "string" }, "lockPath": { "type": "string" }, "statePath": { "type": "string" }, "generatedMisePath": { "type": "string" } } },
+    "mcp": { "type": "object", "properties": { "servers": { "type": "object", "additionalProperties": { "type": "object", "required": ["type"], "properties": { "description": { "type": "string" }, "type": { "enum": ["local", "remote"] }, "command": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "url": { "type": "string", "format": "uri" }, "environment": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "oauth": { "type": "boolean" }, "enabled": { "type": "boolean" }, "timeoutMs": { "type": "integer", "minimum": 1 }, "codemode": { "type": "boolean" } } } } } },
+    "delivery": { "type": "object", "properties": {
+      "stateDir": { "type": "string" },
+      "github": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tokenEnv": { "type": "string", "minLength": 1 }, "repository": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "apiBaseUrl": { "type": "string", "format": "uri" }, "assignTokenOwner": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "branchPattern": { "type": "string", "minLength": 1 }, "finalizeOnAcceptance": { "type": "boolean" }, "pullRequestDraft": { "type": "boolean" } } },
+      "paseo": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "createWorkspace": { "type": "boolean" }, "autoUseWorkspace": { "type": "boolean" }, "worktreeSlugPattern": { "type": "string", "minLength": 1 } } }
+    } },
+    "memory": { "type": "object" }, "codeIntelligence": { "type": "object" }, "sdd": { "type": "object" }, "validation": { "type": "object" }, "security": { "type": "object" }, "telemetry": { "type": "object" }, "evals": { "type": "object" }, "provenance": { "type": "object" }
+  },
+  "$defs": { "severityNumbers": { "type": "object", "properties": { "critical": { "type": "integer", "minimum": 0 }, "high": { "type": "integer", "minimum": 0 }, "medium": { "type": "integer", "minimum": 0 }, "low": { "type": "integer", "minimum": 0 }, "note": { "type": "integer", "minimum": 0 } } } },
+  "additionalProperties": false
+}

package/schemas/quick-contract.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agentic Engineering Harness QuickContract",
+  "type": "object",
+  "required": ["version", "mode", "task", "quick", "scope", "routing", "constraints"],
+  "properties": {
+    "version": { "const": 1 },
+    "mode": { "const": "quick" },
+    "task": { "type": "object", "required": ["id", "title"], "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } } },
+    "quick": { "type": "object", "required": ["request", "acceptance", "triage"], "properties": { "request": { "type": "string", "minLength": 1 }, "acceptance": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "triage": { "type": "object" } } },
+    "scope": { "type": "object", "required": ["allowed"], "properties": { "allowed": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "forbidden": { "type": "array", "items": { "type": "string" } }, "frozen": { "type": "array", "items": { "type": "string" } } } },
+    "routing": { "type": "object" },
+    "constraints": { "type": "object", "properties": { "breakingApiChanges": { "const": false }, "newDependencies": { "const": false }, "schemaChanges": { "const": false } } },
+    "repair": { "type": "object" },
+    "verification": { "type": "object" }
+  }
+}

package/schemas/task-contract.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agentic Engineering Harness TaskContract",
+  "type": "object",
+  "required": ["version", "task"],
+  "properties": {
+    "version": { "const": 1 },
+    "mode": { "enum": ["spec", "quick"] },
+    "task": { "type": "object", "required": ["id", "title"], "properties": { "id": { "type": "string" }, "title": { "type": "string" } } },
+    "quick": { "type": "object", "properties": { "request": { "type": "string" }, "acceptance": { "type": "array", "items": { "type": "string" } }, "triage": { "type": "object" } } },
+    "source": { "type": "object", "properties": { "proposal": { "type": "string" }, "spec": { "type": "string" }, "design": { "type": "string" }, "tasks": { "type": "string" }, "acceptance": { "type": "string" }, "issue": { "type": "string" } } },
+    "issue": { "type": "object", "required": ["provider", "repository", "number", "url", "state", "fetchedAt", "updatedAt", "contentSha256", "snapshotPath"], "properties": { "provider": { "const": "github" }, "repository": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "number": { "type": "integer", "minimum": 1 }, "url": { "type": "string", "format": "uri" }, "state": { "type": "string" }, "fetchedAt": { "type": "string" }, "updatedAt": { "type": "string" }, "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "snapshotPath": { "type": "string" } } },
+    "git": { "type": "object", "properties": { "baseRef": { "type": "string" }, "originatingBranch": { "type": "string" } } },
+    "scope": { "type": "object" },
+    "routing": { "type": "object", "properties": { "intent": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "risk": { "enum": ["low", "medium", "high"] }, "agent": { "type": "string" }, "reviewers": { "type": "array", "items": { "type": "string" } }, "profile": { "type": "string" } } },
+    "requirements": { "type": "array" }, "constraints": { "type": "object" }, "impact": { "type": "object" }, "repair": { "type": "object" }, "verification": { "type": "object" }
+  }
+}

package/schemas/toolchain.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/JamesMorales04/agentic-engineering-harness/schemas/toolchain.schema.json",
+  "title": "Agentic Engineering Harness toolchain",
+  "type": "object",
+  "required": ["version", "manager", "tools"],
+  "properties": {
+    "version": { "const": 1 },
+    "manager": {
+      "type": "object",
+      "required": ["provider"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "generatedConfig": { "type": "string" },
+        "lockFile": { "type": "string" },
+        "stateFile": { "type": "string" },
+        "minimumVersion": { "type": "string" }
+      }
+    },
+    "strategy": {
+      "type": "object",
+      "properties": {
+        "validators": { "enum": ["local", "prefer-container"] },
+        "containerEngine": { "type": "string", "minLength": 1 }
+      }
+    },
+    "profiles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "extends": { "type": "array", "items": { "type": "string" } },
+          "tools": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["kind", "command"],
+        "properties": {
+          "kind": { "enum": ["system", "mise"] },
+          "command": { "type": "string", "minLength": 1 },
+          "source": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "minLength": 1 },
+          "required": { "type": "boolean" },
+          "dependsOn": { "type": "array", "items": { "type": "string" } },
+          "activateWhen": { "type": "array", "items": { "type": "string" } },
+          "container": {
+            "type": "object",
+            "required": ["image"],
+            "properties": {
+              "image": { "type": "string", "minLength": 1 },
+              "engine": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "projectDependencies": {
+      "type": "object",
+      "properties": {
+        "autoDetect": { "type": "boolean" },
+        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/validation-report.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.local/schemas/validation-report.schema.json",
+  "title": "Deterministic Validation Report",
+  "type": "object",
+  "required": ["version", "taskId", "status", "checks", "changedFiles"],
+  "properties": {
+    "version": { "const": 1 },
+    "taskId": { "type": "string" },
+    "status": { "enum": ["PASS", "FAIL"] },
+    "checks": { "type": "array" },
+    "changedFiles": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": true
+}

package/skills/acceptance-traceability/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: acceptance-traceability
+description: Trace sealed acceptance criteria to implementation and executable evidence.
+license: Apache-2.0
+---
+# Acceptance Traceability
+
+For every requirement/criterion, locate:
+1. implementation evidence,
+2. test/validator evidence,
+3. runtime or contract evidence when applicable.
+
+Classify each criterion as COVERED, PARTIALLY_COVERED, NOT_VALIDATED or NOT_COVERED. Cite files/commands rather than relying on summaries. A passing unrelated test does not satisfy traceability. Never rewrite the criterion from implementation behavior.

package/skills/deterministic-validation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: deterministic-validation
+purpose: Treat executable gates as authoritative over LLM self-assessment.
+---
+
+# Deterministic Validation
+
+Run `engineering-harness verify <TASK-ID>` after implementation.
+
+Interpretation:
+
+- Any `FAIL` blocks acceptance.
+- `WARN` requires lead-agent consideration but does not automatically block.
+- A worker's claim that tests pass is not evidence; the generated validation report is evidence.
+- Never weaken frozen validation artifacts to turn a failing result into PASS.

package/skills/engineering-workflow/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: engineering-workflow
+purpose: Turn a natural-language engineering request or existing GitHub issue into the correct Harness workflow while keeping the lead agent as semantic owner.
+---
+
+# Engineering Workflow
+
+You are the engineering lead entrypoint. The user may be operating from Paseo mobile and should not need to know Harness commands or manually provision engineering dependencies.
+
+## Entry protocol
+
+1. Identify the repository root and read `AGENTS.md`, `.harness/project.yaml`, `.harness/agents.source.jsonc`, `.harness/toolchain.yaml` when present, relevant architecture docs and current Git state.
+2. Establish environment readiness before delegation:
+   - run `aeh doctor` when the project has already been initialized;
+   - if doctor reports a reconciliable toolchain failure (missing/out-of-lock Codex, OpenCode, Paseo, Graphify, validator or managed project runtime), run `aeh setup` autonomously and then run `aeh doctor` again;
+   - do not ask the user to install each managed dependency manually;
+   - do not invoke sudo or silently install required host/system prerequisites. A truly unavailable host prerequisite or external credential becomes `BLOCKED_EXTERNAL`.
+3. Run `aeh agents check` before delegation. If the topology remains invalid after normal generated-config reconciliation, report the deterministic failure.
+4. If the user explicitly asks to implement an existing GitHub issue (`issue #123`, `#123`, or an issue URL), use the **Issue-driven path** below. Do not manually recreate the issue as a new SDD request first.
+5. Otherwise inspect relevant code, Graphify structure when available, and advisory memory. Git/specs/tests remain authoritative.
+6. Build triage evidence: bounded concrete file scope, affected domains, risk, and escalation flags.
+7. Run `aeh triage "<request>" --file ... --domain ... --risk ...`.
+8. Follow the Harness decision. Do not downgrade SPEC to QUICK manually.
+
+## Toolchain policy
+
+Treat `.harness/toolchain.yaml` as desired engineering capability configuration and `.harness/toolchain.lock.json` as its resolved executable state.
+
+- `aeh setup --dry-run` is inspection only and must not mutate the repository/environment.
+- ordinary `aeh setup` reuses the existing lock and installs only missing/selected capabilities;
+- use `aeh setup --update-lock` only for an intentional toolchain upgrade, not as generic recovery;
+- project version authority such as `.node-version`, `.nvmrc`, .NET `global.json` and explicit project tool overrides must be respected;
+- `.harness/toolchain.state.json` and generated wrappers are machine-local and must not be treated as normative Git content;
+- do not run package-manager installs with unfrozen semantics when a lockfile/frozen mode is available;
+- use OCI validator alternatives only when configured/preferred and the container engine is available; absence of Podman should fall back to managed local tooling when the tool definition permits it.
+
+## Issue-driven path
+
+For an existing GitHub issue, the issue is an **input source**, not mutable normative truth during execution.
+
+1. Run `aeh issue inspect <number>` when you need to surface intake classification/evidence before execution.
+2. Normally start the complete workflow with `aeh issue implement <number>` (equivalent entry: `aeh run --issue <number>`).
+3. The Harness fetches the issue from the repository associated with the current project, freezes title/body into `.harness/issues/GH-<number>.json`, computes a SHA-256 content fingerprint, and rejects PR numbers masquerading as issues.
+4. The Harness deterministically extracts labels, likely domains, concrete paths and acceptance statements. Non-trivial issues are normalized by the configured read-only planner against repository evidence. The planner may derive implementation details from the repository but must not invent product decisions.
+5. The normalized intake is deterministically materialized as either:
+   - a bounded QuickContract only when QUICK safety rules and concrete file scope are satisfied; or
+   - a complete SDD/TaskContract with requirement IDs, design/tasks and acceptance traceability.
+6. The generated TaskContract/SDD plus frozen issue snapshot are sealed. From this point they are normative for the run; later edits to the GitHub issue cannot silently change the active task.
+7. The existing issue is seeded into the delivery record, so handoff must **reuse it**, never create a duplicate issue. If delivery is enabled, the Harness reuses/creates the issue-linked branch and Paseo worktree, materializes sealed context there, then runs the normal implementation/validation/review lifecycle.
+8. Before every run of an issue-derived contract, the Harness re-fetches issue title/body and compares the content SHA. `ISSUE_DRIFT` blocks silent execution on changed requirements.
+9. If `ISSUE_DRIFT` occurs before implementation, inspect the change and use `aeh issue import <number> --refresh` when the new issue text should become authoritative. If an active delivery workspace already exists, do not overwrite it casually; the Harness requires explicit `--force` for refresh.
+10. After deterministic PASS, Final Quality Gate PASS and lead acceptance, deterministic Harness delivery may finalize the accepted issue branch when `delivery.github.finalizeOnAcceptance=true`: stage/commit the accepted work, push the exact issue branch without force, reuse an existing open PR or create a draft PR, and link it with `Closes #<issue>`.
+11. Agents never receive `gitWrite` merely to perform this finalization. Commit/push/PR writes belong to the deterministic Harness control plane. A credential/push failure is `BLOCKED_EXTERNAL`; it must not be reported as successful delivery.
+12. `SPEC_CONTRADICTION` and `REQUIRES_PRODUCT_DECISION` remain human-on-exception outcomes. Ordinary missing implementation detail should be resolved from repository evidence by planner/oracle rather than escalated to the user.
+
+## QUICK path
+
+Use QUICK only when the Harness returns QUICK.
+
+1. Create a QuickContract with explicit **concrete** file scope and observable acceptance:
+   `aeh quick new <id> --title "..." --request "..." --scope <paths...> --acceptance "..." --domain <domains...>`
+2. Wildcard/repository-wide scope such as `**`, `src/**` or `src/*.ts` is not a bounded QUICK scope and must escalate to SPEC.
+3. Run `aeh quick validate <id>`.
+4. Run `aeh run <id>` with the desired profile.
+5. Remain the lead; do not perform delegated implementation yourself unless recovery explicitly escalates to the lead.
+6. Inspect the final deterministic report. Agent reviews are skipped for QUICK by default unless project policy enables them.
+
+## SPEC path
+
+1. Run `aeh sdd new <id> --title "..."`.
+2. Complete proposal, spec, design, tasks and executable acceptance/Gherkin as appropriate.
+3. Ensure stable requirement IDs and validator traceability.
+4. Run `aeh sdd validate <id>`.
+5. Run `aeh run <id>` with the appropriate profile.
+6. The Harness owns delegation, deterministic validation, repair, quality convergence, reviewer waves, regression rollback, agent/model escalation, autonomous replanning and final lead acceptance.
+
+## Quality convergence
+
+Do not stop or ask the user because a remediation round count has been reached. Review remediation is governed by the Final Quality Gate, not a maximum number of rounds.
+
+Default quality weights use integer DebtPoints: critical=300, high=75, medium=24, low=3, note=1. Therefore three notes equal one low and DebtScore is DebtPoints/3. Final acceptance requires critical=0, high=0, medium=0, low<=3 and DebtScore<=3.
+
+When quality is improving, continue autonomously. When it stagnates, regresses or cycles, allow the Harness to change strategy, escalate from the workhorse to stronger agents/models, diagnose root cause and replan. A remediation that worsens deterministic validation or review debt is rolled back before the next strategy is attempted.
+
+## Human-on-exception
+
+Human intervention is the final exception path, not a routine review step. Request a human decision only when the Harness identifies one of these states:
+
+- `SPEC_CONTRADICTION`: authoritative requirements cannot all be satisfied.
+- `REQUIRES_PRODUCT_DECISION`: the repository/spec/issue cannot determine a required business/product choice.
+- `BLOCKED_EXTERNAL`: a required host prerequisite, credential, account permission, push permission or external resource is unavailable to the Harness/agents.
+- `ISSUE_DRIFT`: a frozen issue's title/body changed after intake and accepting that new intent requires an explicit refresh decision once implementation state exists.
+
+Missing managed toolchain components are not by themselves human exceptions: attempt `aeh setup` first. Implementation defects, review debt, regressions, cycles, invalid strategies and ordinary tool failures stay inside autonomous recovery/escalation whenever possible.
+
+## Triage escalation rules
+
+Treat architecture, authentication/authorization/security, tenant isolation, schema/migrations, public API compatibility, new dependencies, cross-module refactors, ambiguous requirements and medium/high risk as SPEC. A QuickContract must never be used to bypass these boundaries. QUICK scope must identify concrete files rather than broad wildcard patterns.
+
+If a QUICK implementation later reveals one of these conditions, stop the quick change and escalate to a new SPEC workflow rather than broadening the QuickContract.
+
+## Mobile/Paseo behavior
+
+When started as a Codex lead inside Paseo, remain the parent session. Use the Harness as the control layer and allow it to spawn routed OpenCode/Codex work through the configured transports. Before delegation, reconcile the toolchain autonomously when needed. For `implement issue #X`, prefer `aeh issue implement X`; that command owns intake, freeze, optional handoff/worktree, execution and configured accepted-delivery finalization. Surface only meaningful status, deterministic failures that cannot self-recover, permission requests, true human-on-exception states, final acceptance and resulting PR/delivery state to the user. Do not surface every remediation or provisioning step as a request for approval.
+
+## Self-modification
+
+If the repository being modified is the Harness itself or the task changes `.harness/agents.source.jsonc`, `.harness/toolchain.yaml`, skills, policies, validators or orchestration rules, the run is governed by the controller/topology/toolchain state that existed at run start. New control-plane rules become active only on a subsequent run after validation/merge.

package/skills/finding-dedup/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: finding-dedup
+description: Normalize and consolidate reviewer findings before remediation.
+license: Apache-2.0
+---
+# Finding Deduplication
+
+Represent findings with severity, category, location, evidence, impact, recommended fix and owning agent.
+
+Treat findings as likely duplicates when they target the same path, overlapping lines/behavior, category and remediation. Preserve the strongest evidence/severity and union useful context. Keep distinct findings separate when their root cause or fix differs.
+
+Do not discard a finding merely because another reviewer did not mention it.