agentic-engineering-harness 0.4.16 → 0.6.0

package/docs/V0.5.1.md

@@ -0,0 +1,129 @@
+# v0.5.1 — Zero-friction Paseo entrypoint
+
+v0.5.1 makes `aeh start` the interactive product entrypoint for a Harness-enabled repository. After startup, the user can work from Paseo by writing normal engineering requests; repository-changing prompts are automatically routed through the Harness instead of requiring the user to invoke triage, QUICK, SPEC, SDD, TaskContracts, workers, validators or reviewers manually.
+
+## Start
+
+With AEH installed in the project:
+
+```bash
+aeh start
+```
+
+Equivalent package-manager invocations include:
+
+```bash
+npx aeh start
+npm exec aeh -- start
+```
+
+`npm aeh start` is not the canonical npm bin syntax. Use `npm exec aeh -- start` when invoking the locally installed package through npm.
+
+By default `aeh start`:
+
+1. loads `.harness/project.yaml` and the resolved agent topology;
+2. selects the configured interactive lead, normally `lead`/Codex;
+3. verifies that Paseo and the lead runtime are available;
+4. reconciles managed toolchain dependencies automatically when they are missing;
+5. starts `paseo daemon start --web-ui` only when the daemon is not already running;
+6. creates a persistent Paseo session for the project or reuses the compatible prior session;
+7. bootstraps that lead with the `engineering-workflow` invariant;
+8. waits until initialization reaches `AEH READY` before reporting the session ready.
+
+State is machine-local and gitignored under:
+
+```text
+.harness/paseo/lead-session.json
+.harness/paseo/lead-bootstrap.md
+```
+
+The command deliberately does not rewrite the user's global `~/.paseo/config.json`.
+
+## Prompt semantics
+
+Once the generated lead is open in Paseo, a normal prompt such as:
+
+```text
+Add rate limiting to the public authentication endpoints and cover it with tests.
+```
+
+is interpreted as:
+
+```text
+natural-language prompt
+        ↓
+repository inspection
+        ↓
+automatic triage evidence
+        ↓
+QUICK or SPEC
+        ↓
+QuickContract or SDD/TaskContract
+        ↓
+seal
+        ↓
+Harness execution
+        ↓
+planner DAG / worker waves
+        ↓
+deterministic validators + evidence
+        ↓
+review quality convergence
+        ↓
+lead semantic acceptance
+        ↓
+configured deterministic delivery
+```
+
+The parent Paseo lead must not implement a repository-changing prompt directly as a shortcut around this pipeline.
+
+Read-only questions may be answered directly when they do not mutate repository state. Existing GitHub issue requests enter the issue-driven path automatically. If a task initially appears QUICK but implementation reveals architecture, security, schema, public API, cross-module or otherwise unsafe scope, the lead escalates it to SPEC rather than widening the QuickContract.
+
+## Session reuse
+
+`aeh start` reuses `.harness/paseo/lead-session.json` when the previous session still exists and its bootstrap version, project root, selected lead, provider, model and title remain compatible.
+
+Create a clean lead explicitly with:
+
+```bash
+aeh start --new
+```
+
+Other startup controls:
+
+```bash
+aeh start --no-web-ui
+aeh start --no-setup
+aeh start --lead lead
+aeh start --title "AEH Lead"
+aeh start /path/to/repository
+```
+
+`--no-setup` disables automatic toolchain reconciliation. If Paseo or the selected lead runtime is unavailable in that mode, startup fails instead of silently falling back to a different agent/runtime.
+
+## Configuration
+
+New projects receive:
+
+```yaml
+orchestration:
+  provider: paseo
+  interactive:
+    autoSetup: true
+    webUi: true
+    leadAgent: lead
+    reuseSession: true
+    stateDir: .harness/paseo
+    title: AEH Lead
+```
+
+The lead is resolved from the active topology; the start implementation does not hard-code Codex. Projects can therefore replace the logical lead while preserving the same Harness entry semantics.
+
+## Defense in depth
+
+The automatic path is enforced at two conversational layers:
+
+- the persistent `aeh start` bootstrap makes the rule part of the Paseo lead conversation;
+- generated `AGENTS.md` independently states that repository-changing conversational prompts must enter `engineering-workflow`.
+
+The deterministic Harness remains the acceptance authority. Paseo and the lead decide how to interpret and route the prompt, but do not replace sealing, scope enforcement, validators, evidence, review convergence or final acceptance gates.

package/docs/V0.5.2.md

@@ -0,0 +1,180 @@
+# v0.5.2 — Harness-governed engineering audits
+
+v0.5.2 closes the read-only escape that existed in v0.5.1. A request no longer bypasses AEH merely because it does not mutate files. The interactive entrypoint now distinguishes a purely informational question from a read-only engineering operation.
+
+## Intent model
+
+Every conversational request is classified at the top level as:
+
+```text
+prompt
+  |
+  v
+engineering intent
+  |-- INFORMATIONAL -> direct answer, no mutation
+  |-- AUDIT         -> Harness read-only audit pipeline
+  `-- CHANGE        -> deterministic QUICK | SPEC triage
+```
+
+`AUDIT` is deliberately not a subtype of QUICK. A repository-wide review is valid audit scope even though it would be invalid QUICK scope, and it does not need artificial SDD artifacts merely to run a code review.
+
+Examples:
+
+```text
+"What does src/core/run.ts do?"
+  -> INFORMATIONAL
+
+"review the repo and validate the code for improvements"
+  -> AUDIT
+
+"find bugs and security risks"
+  -> AUDIT
+
+"review this module and fix every bug you find"
+  -> CHANGE -> QUICK | SPEC
+```
+
+The public classifier is:
+
+```bash
+aeh intent "review the repo and validate the code for improvements"
+```
+
+## Audit workflow
+
+Run an audit explicitly with:
+
+```bash
+aeh audit "review the repo and validate the code for improvements"
+```
+
+Optional hints include repeated `--file`, `--domain`, `--reviewer` and `--risk low|medium|high` values.
+
+The pipeline is:
+
+```text
+AUDIT request
+   |
+   v
+worktree checkpoint
+   |
+   v
+transient TaskContract + SHA-256 seal
+   |
+   v
+hard-frozen control plane
+   |
+   v
+configured deterministic validators
+   |
+   v
+failure classification
+   |
+   v
+read-only reviewer wave
+   |
+   v
+finding normalization + deduplication
+   |
+   v
+severity counts + DebtScore + Quality Gate evaluation
+   |
+   v
+AuditReport
+```
+
+Reviewer sessions are clamped to `write=deny`, `gitWrite=deny` and `delegate=deny`. The worktree is also checkpointed before the audit and rolled back afterward, so an accidental tracked mutation by a reviewer or tool does not survive. Any dirty paths that existed before the audit are restored to their exact prior contents.
+
+The transient contract and seal make the audit compatible with the same direct, Paseo and supported Podman execution boundaries used elsewhere in AEH.
+
+## Deterministic failures are evidence
+
+The lead must not silently reinterpret a failing validator as harmless environment noise. Audit reports classify failed checks when possible as:
+
+```text
+ASSERTION_FAILURE
+ENVIRONMENT_FAILURE
+SANDBOX_DENIAL
+MISSING_DEPENDENCY
+TOOL_FAILURE
+```
+
+For example:
+
+```text
+spawnSync git EPERM: operation not permitted
+  -> SANDBOX_DENIAL
+```
+
+That classification does not pretend the affected test passed. The audit remains `DEGRADED` and `productionSafe=false` when a deterministic failure prevents establishing correctness.
+
+## AuditReport
+
+Reports are machine-readable local artifacts:
+
+```text
+.harness/audits/<auditId>.json
+.harness/audits/latest.json
+```
+
+An AuditReport contains:
+
+- frozen controller SHA;
+- audited commit/base ref and pre-existing dirty paths;
+- deterministic checks plus failure classes;
+- reviewer sessions;
+- normalized/deduplicated findings;
+- severity counts;
+- integer DebtPoints and displayed DebtScore;
+- Final Quality Gate evaluation;
+- conservative `productionSafe` status;
+- any paths restored by the read-only rollback boundary.
+
+Audit artifacts are generated state and are gitignored by `aeh init`.
+
+## Audit to remediation
+
+AUDIT itself does not edit files or auto-remediate. If the user later says:
+
+```text
+fix these
+fix all findings
+implement the audit recommendations
+```
+
+the persistent lead reads `.harness/audits/latest.json` and the referenced report, reuses the normalized findings as evidence for a new `CHANGE`, and performs normal deterministic change triage.
+
+```text
+AuditReport
+    |
+    v
+new CHANGE request
+    |
+    v
+QUICK | SPEC
+    |
+    v
+sealed implementation workflow
+```
+
+The audit result does not override safety policy. Security, architecture, schema, public API, cross-module or otherwise unsafe findings still force SPEC when normal change triage requires it.
+
+## Paseo behavior
+
+`aeh start` now writes bootstrap version 2. Existing v0.5.1 lead sessions are intentionally incompatible and are recreated/replaced on the next start so the old broad read-only bypass cannot persist.
+
+The standing interactive invariant is now:
+
+> Every engineering operation must enter through the Harness, whether read-only or mutating. Only purely informational questions may bypass AEH.
+
+Consequently this prompt:
+
+```text
+review the repo and validate the code for improvements
+```
+
+must route to `aeh audit`; the lead must not answer that it skipped AEH because the work is read-only.
+
+## Control-plane freeze
+
+Self-hosted AEH snapshots now explicitly include `src/audit` and `src/paseo` in the controller trust boundary. Audit policy and the interactive routing code therefore cannot modify themselves and take effect inside the same active audit/run; changes govern only a later invocation after validation.

package/docs/V0.5.md

@@ -0,0 +1,116 @@
+# v0.5 — Architecture Close, Scale and Organization Governance
+
+v0.5 closes the original single-host architecture and adds the first scale/governance layer. The deterministic Harness remains the only acceptance authority: planner/reviewer/remote-worker output is evidence or proposed change, never an acceptance decision.
+
+## v0.4.17 — Control-Plane Snapshot & Hard Freeze
+
+Every run materializes `.harness/controller/<task>/files` plus a manifest containing per-file SHA-256, a composite SHA-256, AEH version and controller Git SHA when available. The snapshot includes project config, agent topology, generated topology, toolchain source/lock, policy directories, schemas and skills. When AEH modifies itself, controller source modules are frozen as well.
+
+Agent skill text is loaded from the snapshot. OPA reads policies through the frozen policy root. If live controller files change during the run, the run records controller drift but continues to use the old snapshot. The changed controller becomes eligible only on the next run.
+
+## v0.4.18 — Executable Multi-Worker Planner Waves
+
+SPEC tasks with planning enabled are decomposed by the configured planner into a typed task DAG. The plan is rejected unless task IDs/dependencies/agents/scopes are valid and every TaskContract requirement is assigned to at least one implementation task.
+
+Each local delegation executes in its own detached Git worktree. Accepted earlier-wave patches are materialized first, the frozen task/controller context is copied, and a baseline commit is created. The worker returns a binary patch. Within each wave the coordinator checks every patch before applying any patch, then applies all accepted patches and runs a deterministic barrier. Only a PASS barrier unlocks the next wave.
+
+Graphify is conservative scheduling evidence: scope overlap, shared structural nodes, communities, graph distance and high-centrality nodes can serialize tasks. Graphify cannot override the explicit dependency DAG or redefine desired architecture.
+
+## v0.4.19 — Requirement Evidence Graph
+
+`.harness/evidence/<task>.json` records nodes for requirements, planner tasks, changed files, deterministic checks, review findings, agent sessions, commit and pull request. Requirement coverage requires both:
+
+1. a task assigned to the requirement that produced a concrete changed file; and
+2. PASS results for all validators declared by the requirement.
+
+When `evidence.requireComplete=true`, incomplete coverage is a deterministic failure and enters the normal autonomous remediation/escalation lifecycle.
+
+## v0.4.20 — Worker Sandbox Hardening
+
+Podman remains optional globally but can be required by policy or task risk. Supported OpenCode sandbox runs default to a read-only container root, rootless user namespace, `cap-drop=ALL`, no-new-privileges, PID limits, ephemeral HOME and tmpfs. Network is denied when project policy or the logical agent denies network. CPU/RAM/tmpfs and immutable image digests are configurable. Only explicitly allowlisted environment/credential variables cross the boundary; SSH agents, host sockets and credentials are not projected implicitly.
+
+Both the logical-agent prompt path and the legacy Podman worker executor use the hardened policy.
+
+## Scale and organization governance
+
+### Distributed workers
+
+The distributed protocol has filesystem and HTTP queue transports. Jobs are leased with expiry/reclaim semantics. A remote worker clones the frozen base ref, materializes accepted prior-wave patches, executes one delegated task and returns a binary patch plus session metadata. The coordinator rechecks scope and patch applicability and runs all deterministic barriers.
+
+Remote workers are deliberately **untrusted patch producers**. They do not become validation or normative authorities. Git credentials remain on worker nodes and are not serialized into jobs.
+
+Commands:
+
+```bash
+aeh worker serve . --port 8787 --host 0.0.0.0
+aeh worker run . --worker-id node-01
+```
+
+For remote HTTP workers set `distributed.provider: http`, `distributed.endpoint` and optionally `distributed.tokenEnv` on worker/coordinator configs as appropriate.
+
+### Organization policy bundles
+
+Organization bundles contain `bundle.json`, file hashes, optional inheritance and policy directories. Sources may be local or remote and can pin the manifest SHA-256. Optional Cosign blob verification can require a configured public key and signature. Resolved bundles are cached under `.harness/policy-bundles` and frozen into the active controller snapshot before execution.
+
+```bash
+aeh policy sync
+```
+
+### Statistical eval dashboards
+
+Repeated evals compute pass-rate Wilson intervals plus mean/median/standard deviation/confidence intervals for score, duration, tokens, cost, repairs and human interventions.
+
+```bash
+aeh eval repeat EVAL-001 --variant balanced --runs 10
+aeh eval dashboard EVAL-001
+```
+
+### Native structured runtime adapters and resume
+
+The agent contract layer exposes JSON Schemas in addition to Zod schemas. Runtimes that support native output schemas receive them; Zod remains the final parser/validator. Codex and OpenCode direct sessions expose resume/session primitives, while Paseo sessions resume through `send/wait/logs`. Ephemeral Podman sessions intentionally do not pretend they can resume host sessions without an explicit persisted session volume.
+
+### MCP benchmark and packs
+
+The MCP benchmark records a baseline serialized-config token estimate, local/remote reachability latency, permission-surface heuristic and stale-data risk. This is intentionally not yet a claim about exact runtime tool-schema tokens; runtime-native introspection is the next benchmark refinement.
+
+```bash
+aeh mcp benchmark
+```
+
+Default named packs remain least-privilege: research, browser and GitHub read-only are enabled as catalog groupings; observability stays opt-in.
+
+## Default execution flow
+
+```text
+Intent / GitHub Issue
+        ↓
+Toolchain doctor/setup
+        ↓
+QUICK or SPEC
+        ↓
+Seal normative task inputs
+        ↓
+Resolve org policies + topology
+        ↓
+Freeze control plane
+        ↓
+Planner DAG
+        ↓
+Isolated local/remote worker waves
+        ↓
+Deterministic barriers
+        ↓
+Requirement evidence gate
+        ↓
+Reviewer quality convergence
+        ↓
+Regression rollback / model escalation / replan as needed
+        ↓
+Final quality gate + lead acceptance
+        ↓
+Deterministic delivery
+        ↓
+Final evidence graph + controller drift record
+```
+
+The user remains human-on-exception: product decisions, contradictory normative requirements and genuinely unavailable external resources are escalation states; implementation defects, review debt, worker failures and strategy churn remain autonomous recovery concerns.

package/docs/V0.6.md

@@ -0,0 +1,148 @@
+# v0.6 — Orchestration & Context Architecture
+
+v0.6 changes the interactive model from a persistent lead that personally performs setup, discovery and specification authoring into a thin semantic orchestrator backed by bounded agents and durable Harness state.
+
+## Thin lead
+
+The interactive lead owns user intent, high-level routing, true ambiguity and final semantic acceptance. It delegates operational work:
+
+```text
+User
+  |
+  v
+AEH Lead
+  |-- explorer              repository discovery
+  |-- environment-manager   doctor/setup/Paseo recovery
+  |-- planner               decomposition + triage evidence
+  |-- spec-manager          OpenSpec authoring
+  `-- AEH                  implementation/validation/review/delivery
+```
+
+The lead should receive compact structured outcomes instead of retaining raw shell logs, full source files or long environment-repair transcripts.
+
+## Paseo-native orchestration first
+
+When the current Paseo agent exposes its orchestration tools, the lead prefers `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity` and lifecycle controls, and uses `/paseo-handoff` for responsibility transfer. `/paseo-committee` and `/paseo-advisor` may provide advisory reasoning but never override deterministic AEH gates.
+
+AEH still contains a CLI-based Paseo adapter because an external Node control-plane process cannot invoke tools local to the conversational agent. That adapter is now a compatibility fallback rather than the lead's normal orchestration mechanism.
+
+The fallback negotiates the installed Paseo surface at runtime with `paseo --version` and help output. It does not assume `--quiet`, JSON output or daemon JSON support. This specifically avoids the failure mode where an older Paseo such as 0.3.1 rejects a flag expected by a newer CLI.
+
+Recoverable daemon states such as stale PID, unreachable daemon or connection refused are stopped/restarted and verified before lead/worker launch.
+
+## Fresh lead sessions
+
+`aeh start` now creates a fresh lead by default:
+
+```bash
+aeh start
+```
+
+Explicit reuse is:
+
+```bash
+aeh start --resume
+```
+
+This prevents a new invocation from inheriting stale conversational assumptions, obsolete bootstrap instructions or unnecessary historical context. Durable Git/TaskContract/seal/run/audit/delivery state remains reusable even when the conversation is fresh.
+
+## Context pressure and automatic lead rotation
+
+Default policy:
+
+```text
+<70%     normal
+70-80%   PRESSURE: stop exploratory work and increase delegation
+>=80%    HANDOFF_REQUIRED: write handoff and rotate to a fresh lead
+>=90%    HARD_HANDOFF: no further engineering work in the old lead
+```
+
+The public check is:
+
+```bash
+aeh context guard --agent "$PASEO_AGENT_ID"
+```
+
+When Paseo exposes a usable context ratio and the guard runs inside a managed Paseo lead, AEH writes:
+
+```text
+.harness/paseo/handoffs/lead-<timestamp>.json
+```
+
+and automatically creates a fresh lead. The artifact records prior/new lead IDs, context usage, branch, latest run/audit/delivery references, and an optional semantic brief. The fresh lead is bootstrapped from this deterministic artifact and its referenced sealed state. Normal compaction-and-continue is not the preferred path once the handoff threshold is crossed.
+
+If the installed Paseo version does not expose a stable context ratio, AEH returns `UNKNOWN`; it does not fabricate token usage. Fresh-on-start and delegation-first behavior still reduce accumulation.
+
+## OpenSpec as SPEC authoring backend
+
+For non-QUICK changes, the lead no longer writes proposal/spec/design/tasks itself. `spec-manager` owns SPEC authoring with OpenSpec.
+
+```text
+CHANGE
+  |
+  v
+SPEC
+  |
+  v
+spec-manager
+  |
+  |-- aeh spec prepare
+  |-- openspec status / instructions
+  |-- proposal/specs/design/tasks
+  |-- openspec validate --strict
+  `-- aeh spec compile
+          |
+          v
+      AEH proposal/spec/design/tasks/Gherkin
+      + TaskContract
+      + stable requirement IDs
+      + validator traceability
+          |
+          v
+         seal
+```
+
+Commands:
+
+```bash
+aeh spec prepare READABILITY-001 --title "Improve readability"
+aeh spec compile READABILITY-001 --title "Improve readability"
+aeh sdd validate READABILITY-001
+aeh seal READABILITY-001
+aeh run READABILITY-001
+```
+
+OpenSpec is an **authoring source before freeze**. The compiled native AEH SDD/TaskContract and seal remain normative during implementation. OpenSpec apply commands do not replace AEH's worker, validation, review-convergence or delivery lifecycle.
+
+The compiler records `authoring.provider=openspec`, change name and SHA-256 provenance. It maps OpenSpec `### Requirement:` / `#### Scenario:` content into stable AEH requirement IDs and Gherkin acceptance. Refactor/tooling changes without a delta spec receive an explicit behavior-preservation requirement.
+
+A requirement validator may not be invented. AEH uses configured deterministic validators first, otherwise derives a project test/typecheck/build command from known project metadata. If it cannot establish executable requirement evidence, SPEC compilation fails instead of emitting a phantom validator.
+
+## Built-in orchestration preset
+
+New projects extend:
+
+```jsonc
+{
+  "extends": ["aeh:orchestration"]
+}
+```
+
+This extends `aeh:default`, makes lead/planner delegation-first, and adds:
+
+- `environment-manager`;
+- `spec-manager`.
+
+OpenSpec is included in the declarative toolchain and automatically selected when `sdd.authoring.provider: openspec` is active.
+
+## Trust boundary
+
+The authority order remains unchanged:
+
+1. user intent / true product decisions;
+2. sealed compiled AEH SDD + TaskContract;
+3. deterministic validators/evidence;
+4. quality/review gates;
+5. LLM summaries and advisory tools.
+
+Paseo skills improve communication and lifecycle control; they do not become gate authority. OpenSpec improves specification authoring; it does not become mutable execution truth after the AEH seal.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.4.16",
-  "description": "OSS-first engineering harness for deterministic, spec-driven and issue-driven multi-agent software delivery.",
+  "version": "0.6.0",
+  "description": "OSS-first engineering harness for deterministic, spec-driven, issue-driven, audit-governed and orchestration-first multi-agent software delivery.",
   "type": "module",
   "bin": { "engineering-harness": "./dist/entry.js", "aeh": "./dist/entry.js" },
   "files": ["dist", "templates", "presets", "policies", "schemas", "skills", "docs"],
@@ -14,5 +14,5 @@
   "bugs": { "url": "https://github.com/JamesMorales04/agentic-engineering-harness/issues" },
   "publishConfig": { "access": "public" },
   "license": "Apache-2.0",
-  "keywords": ["ai-agents", "codex", "opencode", "paseo", "sdd", "github-issues", "issue-driven-development", "quick-contract", "gherkin", "agent-routing", "agent-presets", "mcp", "github-delivery", "worktrees", "multi-model", "quality-convergence", "toolchain", "mise", "bootstrap", "human-on-exception", "deterministic-validation", "engineering-harness", "slsa", "opentelemetry"]
+  "keywords": ["ai-agents", "codex", "opencode", "paseo", "openspec", "sdd", "audit", "code-review", "github-issues", "issue-driven-development", "quick-contract", "gherkin", "agent-routing", "agent-presets", "orchestration", "context-handoff", "mcp", "github-delivery", "worktrees", "multi-model", "multi-worker", "distributed-workers", "quality-convergence", "evidence-graph", "policy-bundles", "sandbox", "toolchain", "mise", "bootstrap", "human-on-exception", "deterministic-validation", "engineering-harness", "slsa", "opentelemetry"]
 }

package/presets/agents/orchestration.jsonc

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "extends": ["aeh:default"],
+  "agents": {
+    "lead": {
+      "description": "Own user intent, semantic decisions, exception handling and final acceptance. Operate as a thin orchestrator: delegate repository discovery, environment repair, specification authoring, planning, implementation and review. Prefer Paseo native/MCP orchestration tools and handoff skills over direct shell orchestration. Do not author SDD/OpenSpec artifacts or debug tooling interactively when a specialist can own that bounded operation.",
+      "skills": ["engineering-workflow", "lead-engineer", "paseo-orchestration", "verification-planning", "worktree-lifecycle"],
+      "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }
+    },
+    "planner": {
+      "description": "Produce a read-only delegation DAG and triage evidence. Use explorer/Graphify evidence supplied to you; do not implement, author specifications, repair the environment, or run broad validation. Return bounded scope, dependencies, risks, reviewers and validators to the lead/Harness.",
+      "permissions": { "read": "allow", "write": "deny", "shell": "deny", "network": "deny", "delegate": "allow", "review": "allow", "validate": "deny", "gitWrite": "deny" }
+    },
+    "environment-manager": {
+      "role": "coordinator",
+      "domains": ["environment", "toolchain", "paseo", "build-system"],
+      "description": "Own deterministic environment readiness and recovery delegated by the lead. Run AEH setup/doctor/agents checks, diagnose package-manager and Paseo daemon/provider failures, and return a compact structured outcome. Never implement product code or change normative requirements.",
+      "execution": { "model": "@workhorse" },
+      "skills": ["paseo-orchestration", "recovery-classifier"],
+      "permissions": { "read": "allow", "write": "deny", "shell": "allow", "network": "ask", "delegate": "deny", "review": "deny", "validate": "allow", "gitWrite": "deny" },
+      "outputContract": "recovery"
+    },
+    "spec-manager": {
+      "role": "planner",
+      "domains": ["requirements", "specification", "sdd", "openspec"],
+      "description": "Own SPEC authoring only. Use OpenSpec to create/iterate proposal, delta specs, design and tasks from the user's intent plus repository/planner evidence. Validate OpenSpec strictly, then compile it through AEH into traceable TaskContract/Gherkin artifacts. Do not implement code, run broad validation, perform GitHub delivery or redefine user intent silently.",
+      "execution": { "model": "@brain" },
+      "skills": ["openspec-authoring", "acceptance-traceability", "verification-planning"],
+      "permissions": { "read": "allow", "write": "allow", "shell": "allow", "network": "deny", "delegate": "allow", "review": "deny", "validate": "deny", "gitWrite": "deny" },
+      "outputContract": "planner"
+    }
+  },
+  "routing": [
+    { "id": "environment-readiness", "priority": 100, "when": { "intent": ["environment", "toolchain", "recover-environment"] }, "use": "environment-manager" },
+    { "id": "spec-authoring", "priority": 100, "when": { "intent": ["spec-authoring", "openspec"] }, "use": "spec-manager" }
+  ]
+}