agentic-engineering-harness 0.6.0 → 0.6.2

package/docs/PASEO.md

@@ -1,35 +1,68 @@
 # Paseo Integration
 
-Paseo is AEH's default interactive orchestration surface. In v0.6 the design intentionally separates **agent-local orchestration** from the **external deterministic Harness adapter**.
+Paseo is AEH's default interactive orchestration surface. The integration separates **Paseo communication/session lifecycle** from **AEH deterministic workflow ownership**.
+
+## SDK-first control plane
+
+AEH uses Paseo's published TypeScript client package, `@getpaseo/client`, as the primary control surface for agent creation, follow-up turns, status lookup and directory queries. Paseo currently documents that package as public but **not yet a stable public SDK**, so AEH deliberately resolves the copy bundled with the active `@getpaseo/cli` installation first instead of independently selecting a client version.
+
+The resolver supports normal PATH installations and mise-managed npm tools. In particular, mise may expose a shim through `command -v`; AEH also asks `mise which paseo` for the real binary and `mise where npm:@getpaseo/cli` for the synthetic npm installation root, then resolves `@getpaseo/client` from that package tree. A direct project-level SDK import is retained only as a compatibility fallback.
+
+The CLI remains responsible for daemon bootstrap/recovery and is retained as a compatibility fallback when the SDK cannot be resolved or connected:
+
+```text
+AEH
+├── daemon/bootstrap/recovery -> Paseo CLI
+└── normal agent lifecycle    -> @getpaseo/client bundled with active CLI
+```
+
+Set `AEH_PASEO_FORCE_CLI=1` only when the compatibility path is deliberately required. `PASEO_DAEMON_URL` overrides the default SDK endpoint `ws://127.0.0.1:6767/ws`; `PASEO_DAEMON_PASSWORD` supplies daemon authentication when configured.
+
+A system-prompt-only idle agent is an SDK-only invariant. If the SDK is unavailable, AEH refuses to degrade that lead creation into a CLI user turn because doing so would expose the bootstrap as conversational input.
 
 ## Conversational lead
 
-When the lead is running inside Paseo and Paseo exposes its orchestration tools, prefer the native/MCP control surface:
+`aeh start` creates the lead as an idle Paseo agent. The AEH bootstrap is passed through the SDK's `systemPrompt`; it is no longer sent as the first user message and there is no synthetic `AEH READY` turn.
 
-- create a bounded agent;
-- send follow-up prompts;
-- inspect agent status/activity;
-- cancel/archive/update agent lifecycle;
-- use `/paseo` for the current tool reference;
-- use `/paseo-handoff` when responsibility moves to a fresh agent.
+The bootstrap is intentionally thin. `AGENTS.md`, `.harness/skills/engineering-workflow/SKILL.md`, and the resolved AEH agent topology are authoritative for roles, charters, permissions and delegation. This avoids duplicating a role map inside every Paseo conversation and prevents prompt/configuration drift.
 
-This keeps the lead as an orchestrator and avoids filling its context with hand-written shell control loops. Committee/advisor skills are advisory reasoning only; deterministic AEH validation remains authoritative.
+When the lead is running inside Paseo and Paseo exposes its orchestration tools, it may still use the native/MCP conversational surface and `/paseo-handoff`. Deterministic Harness-owned work, however, is created externally by AEH through the SDK.
 
-## External AEH fallback
+## Independent AEH agents
 
-AEH itself is an external Node control-plane process and cannot assume access to tools injected only into an agent conversation. Therefore it retains a CLI adapter for deterministic launches, waits, logs and repair prompts.
+AEH-managed workers are created without the Paseo SDK `parent` option. A worker may be placed in a delivery workspace, but workspace placement does not establish parentage. This makes each worker a top-level Paseo agent rather than a child whose lifecycle belongs to the current lead conversation.
 
-The adapter no longer hard-codes a specific Paseo CLI surface. Before launch it probes:
+Workflow ownership is represented by labels instead:
 
 ```text
-paseo --version
-paseo run --help
-paseo daemon status --help
+aeh.project=<project>
+aeh.kind=lead|worker
+aeh.role=<logical-agent>
+aeh.task=<task-id>        # workers
+aeh.profile=<profile>     # when selected
+aeh.generation=<n>        # leads
 ```
 
-and conditionally uses JSON/quiet/background flags only when supported. This permits older Paseo installations to fail with a precise capability error rather than because AEH blindly passed a newer flag.
+The shared Paseo runtime exposes list/inspect primitives over those labels. This lets AEH determine which logical agent is active for a task without scraping assistant prose or relying on parent/child nesting. The same labels survive lead context rotation, so a fresh lead can correlate existing workers with durable AEH run state.
+
+### Observe active agents
+
+Use the top-level AEH command to inspect the live Paseo directory. The project label is applied automatically; filters are additive:
+
+```bash
+aeh paseo agents
+aeh paseo agents --status working
+aeh paseo agents --kind worker --role backend-implementer
+aeh paseo agents --task TASK-123 --json
+```
+
+The tabular view reports status, logical role, task, kind, stable Paseo agent ID and title. `--json` returns the same normalized fields plus the complete AEH label set. This is the preferred way to answer which AEH agent is currently working without depending on Paseo parent/subagent nesting.
+
+## Runtime consolidation
+
+Lead startup, `PaseoWorkerExecutor`, and generic `agentPrompt` execution all use the same managed Paseo runtime. That runtime owns SDK-first create/run/probe/list behavior and the CLI fallback. Individual worker paths should not add new hand-written `paseo run/send/wait/logs` loops.
 
-Recognized stale/unreachable daemon states are recovered by stop/start + readiness verification before launching a lead/worker.
+Structured output is passed through the SDK `outputSchema` field. The compatibility CLI path continues to negotiate `--output-schema` and background capabilities dynamically.
 
 ## Session policy
 
@@ -42,7 +75,7 @@ orchestration:
 ```
 
 ```bash
-aeh start          # fresh lead
+aeh start          # fresh idle lead
 aeh start --resume # explicit compatible reuse
 ```
 
@@ -52,10 +85,10 @@ Workspaces and durable AEH state remain reusable even though normal conversation
 
 Default pressure policy is 70/80/90 percent. `aeh context guard` consumes a context ratio only when Paseo exposes a usable field; AEH does not guess.
 
-At the handoff threshold it writes a deterministic `.harness/paseo/handoffs/*.json` artifact. From a managed Paseo lead it also creates the replacement lead automatically and bootstraps it from the handoff artifact and referenced sealed/run/audit/delivery state. The old lead stops engineering work rather than compacting and continuing normally.
+At the handoff threshold it writes a deterministic `.harness/paseo/handoffs/*.json` artifact. From a managed Paseo lead it also creates the replacement lead automatically and bootstraps it from the handoff artifact and referenced sealed/run/audit/delivery state. Workers remain independent top-level agents associated through AEH labels and durable task/run state rather than lead parentage.
 
 ## Trust boundary
 
-Paseo owns communication/process/session lifecycle. It is not normative engineering truth. AEH TaskContracts, seals, deterministic reports, evidence graphs and quality gates continue to decide acceptance.
+Paseo owns communication, process and session lifecycle. It is not normative engineering truth. AEH TaskContracts, seals, deterministic reports, evidence graphs and quality gates continue to decide acceptance.
 
 For stronger direct process isolation configure Podman sandboxing where appropriate; Paseo orchestration and worker sandboxing remain separate policy axes.

package/docs/PUBLISHING.md

@@ -2,41 +2,62 @@
 
 The package name is `agentic-engineering-harness` and the public CLI commands are `aeh` and `engineering-harness`.
 
-The repository is prepared for npm Trusted Publishing through GitHub Actions OIDC. No long-lived npm publish token is stored in the repository workflow.
+`package.json` is the single source of truth for the AEH version. Runtime CLI version output imports that package metadata; source files and CI must not maintain separate hard-coded version strings.
 
 ## Preflight
 
-Before any publication:
+Every release candidate must pass:
 
 ```bash
 npm run release:check
 ```
 
-This must pass typecheck, tests, build and `npm pack --dry-run`.
+This runs typecheck, the complete test suite, build and `npm pack --dry-run`.
 
-Check whether the desired package name already exists:
+## Automatic releases from `main`
 
-```bash
-npm view agentic-engineering-harness version
+`.github/workflows/publish.yml` is the single npm publishing workflow. A push to `main` starts an idempotent release pipeline unless the repository variable below is set:
+
+```text
+AEH_AUTO_PUBLISH=false
 ```
 
-An npm `E404` means the name is not currently published. If another owner controls the name, choose a scoped package name before publishing rather than changing package identity after adoption.
+The workflow performs the following steps:
 
-## One-time first publication
+1. installs dependencies with `npm ci`;
+2. checks whether the current `package.json` version is already present on npm;
+3. if the current version is unpublished, it publishes that exact version first;
+4. otherwise it derives the next semantic version from commits since the latest `v*` tag:
+   - a breaking Conventional Commit (`type!:` or `BREAKING CHANGE:`) -> major;
+   - `feat:` -> minor;
+   - every other change -> patch;
+5. synchronizes `package.json` and `package-lock.json` with `npm version --no-git-tag-version`;
+6. runs `npm run release:check` on the exact candidate;
+7. commits the version metadata as `chore(release): vX.Y.Z [skip ci]` and creates the matching Git tag;
+8. publishes the package to npm with provenance;
+9. creates the GitHub Release for the tag.
 
-npm Trusted Publisher configuration requires an npm package to exist first. The first release therefore needs one deliberate maintainer-authenticated publish.
+The release commit/tag is pushed with GitHub's repository token. GitHub does not recursively trigger ordinary push workflows for pushes created with that `GITHUB_TOKEN`, so the version commit does not create an infinite publish loop.
 
-From a clean checkout of the exact release commit:
+The repository must allow the workflow identity to write the release metadata commit/tag. If branch rules forbid direct writes to `main`, grant the GitHub Actions identity the appropriate bypass/write permission or set `AEH_AUTO_PUBLISH=false` until the repository rule is adjusted. Source validation remains independent of publication.
 
-```bash
-npm login
-npm run release:check
-npm publish --access public
+## Manual release control
+
+`publish-npm` also supports `workflow_dispatch`. The `bump` input can be:
+
+```text
+auto     # Conventional Commit-derived bump
+current  # publish current version only if it is not already published
+patch
+minor
+major
 ```
 
-Complete the npm account's required 2FA/interactive authentication. Do not create a persistent automation token solely for this bootstrap.
+Manual dispatch is useful for retrying an external npm/OIDC failure or deliberately overriding the automatic bump classification. A `current` retry is also able to recreate a missing GitHub Release when the npm version and matching Git tag already exist; it will not fabricate a missing tag for an already-published package.
 
-After the first package exists, open the package settings on npmjs.com and configure a Trusted Publisher with:
+## npm authentication
+
+The preferred steady-state path is npm Trusted Publishing with GitHub Actions OIDC. Configure the npm package Trusted Publisher with:
 
 ```text
 Provider: GitHub Actions
@@ -46,39 +67,21 @@ Workflow filename: publish.yml
 Allowed action: npm publish
 ```
 
-The workflow file lives at `.github/workflows/publish.yml`; npm expects only the filename in the Trusted Publisher configuration.
-
-For the strongest steady-state posture, after the OIDC flow has been proven once, disallow traditional publish tokens for the package and retain 2FA on the maintainer account.
+The workflow grants `id-token: write`, which is required for OIDC. Modern npm clients can exchange the GitHub OIDC identity for short-lived publish authorization, avoiding a long-lived npm write token.
 
-## Steady-state release
+For bootstrap or compatibility, the workflow also accepts an optional GitHub Actions secret named `NPM_TOKEN`. If present, it is exported only for the `npm publish` step. Once Trusted Publishing is verified, prefer removing the long-lived token.
 
-1. Change `package.json` to the intended semantic version.
-2. Ensure the CLI dispatcher reports the same version.
-3. Merge only after CI `release:check` passes.
-4. Create/publish a GitHub Release tagged exactly:
+If the package has never been published and npm does not permit Trusted Publisher configuration before first publication, perform one maintainer-authenticated bootstrap publish, then configure the Trusted Publisher above. The automatic workflow will subsequently see that version as published and continue normal semantic versioning.
 
-```text
-v<package.json version>
-```
-
-For example:
-
-```text
-v0.4.16
-```
+## Version policy
 
-5. The `publish-npm` workflow will:
-   - check out the release commit;
-   - use Node 24 on a GitHub-hosted runner;
-   - verify that the release tag exactly matches `package.json`;
-   - run `npm run release:check` again;
-   - execute `npm publish` using npm Trusted Publishing/OIDC.
+The repository currently starts this release line at `0.6.1`. After that, normal merges do not require a human to edit the version manually. The release workflow owns the release metadata bump.
 
-If the tag/version check fails, no publish is attempted.
+If a PR intentionally changes the package version to a version that is not yet on npm, that repository version wins: the next `main` publication ships it before any further automatic increment. This makes explicit release corrections and recovery deterministic.
 
 ## What enters the npm tarball
 
-The `files` allowlist in `package.json` publishes only:
+The `files` allowlist in `package.json` publishes:
 
 ```text
 dist/
@@ -92,7 +95,7 @@ docs/
 
 plus npm-required package metadata such as `package.json`, README and LICENSE.
 
-This is why CI runs `npm pack --dry-run`: bootstrap templates, default agents, skills and toolchain schemas are runtime assets for `aeh init`, not merely repository documentation.
+Packaged `skills/` and core `policies/` are runtime control-plane assets. `aeh init`, `aeh setup`, and `aeh start` reconcile those package assets into the consumer repository's `.harness` directory. `.harness/managed-assets.json` is versioned project state: it records hashes so missing or untouched files can be restored/upgraded, retired untouched assets can be removed, and project-local modifications remain protected as overrides.
 
 ## Consumer installation
 
@@ -103,8 +106,14 @@ npm install --save-dev agentic-engineering-harness
 npm exec aeh -- init --setup
 ```
 
-AEH should not be imported into the product runtime merely to use the engineering workflow.
+After the repository has been initialized, a normal:
+
+```bash
+npm exec aeh -- start
+```
+
+reconciles managed Harness assets before loading the agent topology and starting Paseo.
 
 ## Failure policy
 
-Publication is a delivery operation, not an engineering-quality gate. A registry/OIDC/permission failure must not cause the source commit to be rewritten or force-pushed. Fix the external publishing configuration and re-run/recreate the release process as appropriate while preserving the already-validated source commit.
+A registry/OIDC/permission failure is an external delivery failure, not a reason to rewrite validated engineering history. The release workflow is retry-safe: if the version commit/tag exists but npm publication failed, a manual rerun with `current` will attempt the same unpublished version rather than incrementing it again. If npm publication succeeded but GitHub Release creation failed, a `current` rerun can repair the release from the existing matching tag.

package/package.json

@@ -1,18 +1,93 @@
 {
   "name": "agentic-engineering-harness",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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"],
-  "scripts": { "build": "tsc -p tsconfig.json", "dev": "tsx src/entry.ts", "test": "vitest run", "test:watch": "vitest", "typecheck": "tsc -p tsconfig.json --noEmit", "check": "npm run typecheck && npm test && npm run build", "release:check": "npm run check && npm pack --dry-run" },
-  "engines": { "node": ">=22" },
-  "dependencies": { "@opentelemetry/api": "^1.9.0", "commander": "^14.0.1", "minimatch": "^10.0.3", "yaml": "^2.8.1", "zod": "^4.0.17" },
-  "devDependencies": { "@types/node": "^24.2.1", "tsx": "^4.20.3", "typescript": "^5.9.2", "vitest": "^3.2.4" },
-  "repository": { "type": "git", "url": "git+https://github.com/JamesMorales04/agentic-engineering-harness.git" },
+  "bin": {
+    "engineering-harness": "./dist/entry.js",
+    "aeh": "./dist/entry.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "presets",
+    "policies",
+    "schemas",
+    "skills",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/entry.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "npm run typecheck && npm test && npm run build",
+    "release:check": "npm run check && npm pack --dry-run",
+    "release:resolve": "node scripts/release-version.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "commander": "^14.0.1",
+    "minimatch": "^10.0.3",
+    "yaml": "^2.8.1",
+    "zod": "^4.0.17"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JamesMorales04/agentic-engineering-harness.git"
+  },
   "homepage": "https://github.com/JamesMorales04/agentic-engineering-harness#readme",
-  "bugs": { "url": "https://github.com/JamesMorales04/agentic-engineering-harness/issues" },
-  "publishConfig": { "access": "public" },
+  "bugs": {
+    "url": "https://github.com/JamesMorales04/agentic-engineering-harness/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "Apache-2.0",
-  "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"]
+  "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"
+  ]
 }