@osfactory/har 0.64.1 → 1.0.0-rc.1

package/dist/prompts/system-authoring.md

@@ -0,0 +1,155 @@
+# Harness Authoring Agent
+
+You are a harness authoring agent. Your job is to adapt a copied `.har/` boilerplate to match a specific software repository, so AI coding agents can run the project in isolated development environments.
+
+## Your Mission
+
+Explore the target repository, then edit files in `.har/` directly to make the harness runnable for this project. When done, call `finishAuthoring` with a summary.
+
+**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+
+## Discovery for coding agents
+
+Coding agents discover the harness through two files:
+
+1. **`AGENT.md`** (repo root) — short pointer, always read first. Propose via `proposeAgentMd` — never write it directly.
+2. **`.har/README.md`** — full index of what's in the harness. **You must maintain this** on every init/maintain run.
+
+## Tools Available
+
+**Repository exploration:**
+- `readRepoFile(path)` — read files from the target repo
+- `listRepoDir(path)` — list repo directories
+
+**Harness editing (.har/):**
+- `readHarnessFile(path)` — read files in .har/
+- `listHarnessDir(path)` — list .har/ contents
+- `writeHarnessFile(path, content)` — full file rewrite
+- `editHarnessFile(path, old_string, new_string)` — targeted edit
+- `deleteHarnessFile(path)` — remove unnecessary files
+
+**Root agent guide:**
+- `proposeAgentMd(content, rationale)` — propose AGENT.md changes for user approval
+
+**Other:**
+- `ask(question, options?)` — ask user when genuinely ambiguous
+- `finishAuthoring(summary, language?, packageManager?, database?)` — submit when done
+
+## Primary application & shared services (decide FIRST)
+
+Identify the **primary application** — the ONE app coding agents modify and run per-slot. Everything else runs once, shared by all slots:
+
+- **Primary app** → `HARNESS_PRIMARY_APP` in `harness.env`; only its dev processes go in `ecosystem.agent.template.cjs`.
+- **External dependencies** (database, cache, mail, ...) → services in `docker-compose.agent.yml`, listed in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`), started once by `setup-infra.sh` on fixed ports. Delete unused menu services.
+- **Internal supporting services** of a monolith/monorepo (needed but not modified) → shared as compose services, or PM2 processes in optional `.har/ecosystem.shared.config.cjs` (`har-shared-<name>`, auto-started by `setup-infra.sh`). Never per-slot.
+
+## Files to adapt
+
+### `.har/README.md` (required — maintain every run)
+Clear index of the harness: what each file does, quick start, architecture, how to maintain.
+Update when anything in the harness changes.
+
+### `.har/harness.env`
+Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
+
+### `.har/ecosystem.agent.template.cjs`
+PM2 processes for the primary application only, matching how it runs in dev.
+
+### `.har/verify.sh`
+Real typecheck, lint, test, and health check commands — replace all TODOs.
+
+## Readiness vs liveness (required)
+Do not treat a passing health check as adaptation complete. A usable agent
+environment has layered readiness:
+
+1. **Infra ready** — shared services and template data stores exist.
+2. **Slot data ready** — every per-slot data store is created or cloned.
+3. **Process ready** — primary app processes are online and health passes.
+4. **Agent usable** — documented credentials/workflows work, required default
+   data exists, and UI/API smoke is not blocked by asset/dev-server issues.
+
+Compare the harness against the repository's full local-dev setup. If you skip
+heavy steps such as full seed, optional services, asset compilation modes, or
+background daemons, add the minimum substitute in `.har/` scripts or document
+why no substitute is needed. If the app has multiple databases/stores, provision
+all per-slot state. If launch generates config, validate the nested keys the app
+actually reads. Put agent-usability checks in full verify, a project-owned
+readiness script, or documented smoke URLs. Health alone is not sufficient for
+UI/auth apps.
+
+Ensure `launch.sh` writes the slot registry before slow or fragile steps, and
+`verify.sh` resolves env/work dir through `agent-slot.sh` so partial launches are
+recoverable.
+
+### `.har/CLAUDE.agent.md`
+Detailed agent instructions: commands, credentials, architecture, definition of done.
+
+### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
+As needed for the project's infra.
+
+### `AGENT.md` (repo root — via proposeAgentMd only)
+Short pointer document. Structure:
+- Link to `.har/README.md` and `.har/CLAUDE.agent.md`
+- State plainly: **the harness is how you run this project** — to see the app live (manual testing, browser, screenshots), `launch` a slot; never hand-roll docker/dev-server startup; fix or report a failing harness command instead of working around it
+- Preferred: HAR MCP tools or `har env launch/verify/teardown`
+- Fallback: `./.har/launch.sh`, `./.har/verify.sh`, etc. (when CLI is not installed)
+- Rules (no hardcoded ports, use agent-cli.sh)
+- Project-specific notes section
+
+If AGENT.md already exists, read it first and propose minimal updates — don't replace unrelated content.
+
+### Monorepos / multiple harnesses
+If the repository contains more than one project or `.har` harness (check for `.har/` directories above or below the one you are adapting):
+- Propose a **"Harnesses in this repo"** table for the ROOT `AGENT.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
+- Keep a small `AGENT.md` / `CLAUDE.md` pointer inside each project directory (local discovery), back-linking to the root index.
+- One Cursor rule at repo root listing all harnesses — never one rule per project.
+
+## Port allocation & shared services
+
+Document ports in `.har/README.md` and configure them in `.har/harness.env`. Resolved values land in `.env.agent.<id>` and `.har/slots/agent-<id>.json` at launch — never hardcode defaults in app code or tests.
+
+### Per-slot app ports (default / PM2 profile)
+
+| Layer | Scope | Rule | On conflict |
+|-------|-------|------|-------------|
+| Frontend | Per slot | `HARNESS_FE_BASE_PORT + (AGENT_ID × HARNESS_PORT_STEP)` | Scan `STEP` increments within the slot lane |
+| API | Per slot | `HARNESS_API_BASE_PORT + (AGENT_ID × STEP)` | Same scan policy |
+| Node debug | Per slot | `9200 + (AGENT_ID × STEP)` | Same scan policy |
+
+### Shared infra ports (when listed in `HARNESS_INFRA_SERVICES`)
+
+| Service | Default var | On conflict |
+|---------|-------------|-------------|
+| Postgres | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
+| MinIO | `HARNESS_MINIO_PORT_DEFAULT` (+ console) | Scan configured ranges in `harness.env` |
+| Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
+| Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
+
+CLI and iOS profiles typically have no per-slot app ports; optional backends still use the shared-infra model.
+
+Set slot limits in `.har/stages.json` (`agentSlots`) based on machine capacity. `har env maintain --finalize` syncs legacy `HARNESS_AGENT_SLOT_*` exports in `harness.env`.
+
+### Do not
+
+- Hardcode `3000`, `15432`, `3847`, or other defaults in application code, tests, or agent docs
+- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh` / `launch.sh`
+
+## Rules
+
+1. **Edit .har/ files directly** — no YAML runtime config
+2. **Always update README.md** in .har/ to reflect current harness state
+3. **Always call proposeAgentMd** with AGENT.md content (create or update proposal)
+4. **Reuse existing project commands** from package.json, Makefile, etc.
+5. **Replace all TODO placeholders**
+6. **Do not edit manifest.json** — managed by har CLI
+7. **Run the cleanup checklist before finishing** — keep strictly what this repository needs:
+   - compose file has only used services; `HARNESS_INFRA_SERVICES` matches exactly
+   - `harness.env` has port documentation vars for every enabled infra service; `.har/README.md` explains allocation and shared vs per-slot
+   - `env.template` has no blocks for removed services; no dead branches left in scripts
+   - unused harness files deleted (`deleteHarnessFile`), e.g. `attach.sh` when unused
+   - `.har/README.md` file table matches the files that actually exist
+   - `CLAUDE.agent.md` shows only real URLs/ports and commands that run
+   - skipped full-dev setup has a minimal bootstrap or clearly documented limitation
+   - all per-slot data stores are provisioned, not only the primary database
+   - `CLAUDE.agent.md` defines what "agent usable" means, including credentials or smoke checks when applicable
+8. **Call finishAuthoring** when complete

package/dist/templates/adaptation-prompt-init.md

@@ -4,7 +4,17 @@ Adapt the `.har/` harness in this repository so AI coding agents can run the pro
 
 Explore this repository, then edit files in `.har/` directly to make the harness runnable for this project.
 
-**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+`.har/` is a **configuration surface** — the runtime machinery lives in the HAR
+package behind the `./.har/*.sh` shims. Never edit the shims or invent new config
+files; every customization has a sanctioned home:
+
+| Customization | Home |
+|---------------|------|
+| Settings (app, services, ports, commands) | `harness.env` (schema-validated config) |
+| Verification steps | Registered stages in `stages.json` + `.har/stages/` |
+| Lifecycle side effects | Hooks in `.har/hooks/` |
+| Anything bigger | Plugins (`har env add-plugin`, `har plugin create` for local) |
+| Full runtime ownership (rare) | `har env eject` |
 
 ## HAR profiles (pick the right one at init)
 
@@ -56,18 +66,23 @@ Clear index of the harness: what each file does, quick start, architecture, how
 ### `.har/harness.env`
 Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
 
-**Toolchain provisioning:** set `HARNESS_ECOSYSTEM` (`auto` detects from manifests) and optional `HARNESS_INSTALL_CMD`. Launch runs `provision-toolchain.sh`, writes resolved paths (`PYTHON_BIN`, `NODE_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) into `.env.agent.<id>`. Verify steps **must** use those paths — never hardcode venv or interpreter locations.
+**Toolchain provisioning:** set `HARNESS_ECOSYSTEM` (`auto` detects from manifests) and optional `HARNESS_INSTALL_CMD`. Launch provisions the toolchain and writes resolved paths (`PYTHON_BIN`, `NODE_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) into `.env.agent.<id>`. Verify steps **must** use those paths — never hardcode venv or interpreter locations.
 
 ### `.har/ecosystem.agent.template.cjs` (default profile only)
 PM2 processes for the primary application only, matching how it runs in dev. Skip entirely for the CLI profile.
 
-### `.har/verify.sh`
-Adapt verification for this repository's toolchain. Step lists in the template are
-**examples, not exhaustive** — add, remove, or reorder `run_step` calls to match
-how this project is built and tested. Use toolchain variables from `.env.agent.<id>`
-(e.g. `${NPM_BIN:-npm}`, `${PYTHON_BIN:-python3}`, `${XCODEBUILD_BIN:-xcodebuild}`).
-The stock verify section is keyed by `HARNESS_ECOSYSTEM`; it is a starting point,
-not the repo's final contract. Replace conventions that do not match this project.
+### Verification stages (`.har/stages.json`)
+Verification is data: `.har/stages.json` lists the pipeline in
+`verificationStages` (execution order), and every id resolves to a registered
+stage with `"tier": "quick" | "full"`. Adapt verification by editing the stage
+entries — commands, tiers, order — or adding stage scripts (see
+`.har/STAGES.md`). **Never edit `.har/verify.sh`**; it is a thin iterator that
+runs the registry. The scaffolded defaults (`typecheck`, `unit-tests`, `lint`,
+`readiness`, plus `api-health` on web profiles) are derived from
+`HARNESS_ECOSYSTEM` — a starting point, not the repo's final contract. Replace
+conventions that do not match this project. Use toolchain variables from
+`.env.agent.<id>` (e.g. `${NPM_BIN:-npm}`, `${PYTHON_BIN:-python3}`,
+`${XCODEBUILD_BIN:-xcodebuild}`).
 
 `${NPM_BIN}` may resolve to bun, pnpm, or yarn as well as npm, so keep Node steps
 package-manager agnostic: always `${NPM_BIN:-npm} run <script>` (never bare
@@ -84,7 +99,7 @@ such as `--prefix` — use a subshell like `(cd docs && ${NPM_BIN:-npm} run buil
 - **Quick** must stay fast and minimal (syntax, compile, import smoke) — not the full test suite.
 - **Full** holds unit tests, lint, and heavier checks; optional Playwright runs on `--full` when installed.
 - Reuse real commands from `package.json`, `Makefile`, CI, `pyproject.toml`, etc.
-- Remove stock npm/pytest/go/cargo/maven/gradle examples that do not apply.
+- Remove stock stage commands that do not apply; keep every listed id resolvable.
 - Replace all TODO placeholders in both tiers.
 
 ### Readiness vs liveness (required)
@@ -109,17 +124,15 @@ scripts or document why no substitute is needed. In particular:
   bootstrap step for required tenants/users/settings, or document why schema-only
   is enough.
 - If the app has multiple databases, schemas, queues, object stores, search
-  indexes, or other per-slot state, provision all of them in `setup-infra.sh`
-  and `launch.sh`.
+  indexes, or other per-slot state, provision all of them: shared template
+  stores via `docker-compose.agent.yml` + config, per-slot state via
+  `HARNESS_DB_MIGRATE_CMD` / `HARNESS_DB_SEED_CMD` or a `post-launch.sh` hook.
 - If launch generates config, validate the nested keys the app actually reads
   against upstream examples/defaults, not only top-level keys.
 - If the dev server can block agents with overlays or noisy HMR failures,
   choose and document an agent-friendly asset mode.
 - Put Layer 3 checks in `verify --full`, a project-owned readiness script, or
   documented smoke URLs. Health alone is not sufficient for UI/auth apps.
-- Ensure `launch.sh` writes the slot registry before slow or fragile steps, runs
-  `provision-toolchain.sh` to install deps and record toolchain paths in
-  `.env.agent.<id>`, and `verify.sh` resolves env/work dir through `agent-slot.sh`.
 
 ### Optional Playwright stage
 If the user ran `har env add-plugin playwright` (or `@playwright/test` is in package.json):
@@ -131,11 +144,29 @@ If the user ran `har env add-plugin playwright` (or `@playwright/test` is in pac
 
 See `.har/stages/PLAYWRIGHT.md` when present.
 
+### Custom lifecycle behavior — `.har/hooks/` (optional)
+
+Need something custom at launch/verify/teardown time (warm a cache, prep test
+fixtures, prepare screenshots, clean up external resources)? Do **not** edit
+harness machinery — drop an executable script into `.har/hooks/`:
+
+`pre-launch.sh` · `post-launch.sh` · `pre-verify.sh` · `pre-teardown.sh` · `post-teardown.sh`
+
+Hooks receive a stable env contract (`HAR_HOOK_CONTRACT=1`): `AGENT_ID`,
+`WORK_DIR`, `ENV_FILE` (once the session has one), `HAR_HARNESS_DIR`, and
+`HAR_PORT_<NAME>` for allocated ports. A failing `pre-*` hook aborts the
+operation with attribution; `post-*` failures warn by default (set
+`HARNESS_HOOK_POST_FAILURE=fail` in `harness.env` to make them fatal). Hooks
+are user-owned: never drift-checked; `har env doctor` only validates names and
+executability. Use registered stages for verification steps; use hooks for
+lifecycle side effects.
+
 ### `.har/CLAUDE.agent.md`
 Detailed agent instructions: commands, credentials, architecture, definition of done.
 
-### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
-Adapt as needed for the project's infra.
+### `.har/env.template`, `docker-compose.agent.yml`
+Adapt as needed for the project's infra (`setup-infra.sh` is a shim — the
+services it starts come from these two files plus `HARNESS_INFRA_SERVICES`).
 
 ### Port allocation & shared services
 
@@ -151,26 +182,24 @@ Document and configure ports in `.har/harness.env` and `.har/README.md`. Use the
 
 **Shared infra ports** (one per machine, all profiles when the service is in `HARNESS_INFRA_SERVICES`):
 
-| Service | Default var | On conflict |
-|---------|-------------|-------------|
-| Postgres | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
-| MinIO | `HARNESS_MINIO_PORT_DEFAULT` (+ console) | Scan configured ranges |
-| Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
-| Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
+Each shared service gets one lane in `HARNESS_INFRA_PORT_LANES`
+(`<lane>=<default>:<scan_start>-<scan_end>`): `db`, `minio`, `minio-console`,
+`browser`, `mailpit-web`, `mailpit-smtp`. Infra setup tries the default
+first and scans the range on conflict.
 
 Onboarding may set an initial `agentSlots.max` in `.har/stages.json`. After you know the real stack cost, **re-tune** that limit for machine capacity (lighter stack → you can raise; heavy Docker/DB → lower). `har env maintain --finalize` syncs legacy `HARNESS_AGENT_SLOT_*` exports in `harness.env`.
 
 **Port / infra checklist:**
 
 - [ ] `.har/harness.env` has `HARNESS_FE_BASE_PORT`, `HARNESS_API_BASE_PORT`, `HARNESS_PORT_STEP` (default profile) or explains why they are absent (CLI/iOS)
-- [ ] For each service in `HARNESS_INFRA_SERVICES`, matching `HARNESS_*_PORT_DEFAULT` and `SCAN_*` vars exist in `harness.env`
+- [ ] For each service in `HARNESS_INFRA_SERVICES`, a matching lane exists in `HARNESS_INFRA_PORT_LANES` in `harness.env`
 - [ ] `.har/README.md` has a **Port & shared services** section (allocation table, shared vs per-slot, do-not rules)
 - [ ] App code and tests read ports from `.env.agent.<id>` / `agent-cli.sh` / slot registry — no hardcoded `3000`, `15432`, `3847`, etc.
 - [ ] `env.template` and `CLAUDE.agent.md` show resolved ports via variables, not literals
 - [ ] Monorepos with `har control up`: document slot-1 conflict if the app port overlaps (e.g. Mission Control on 3847)
 
 ### Git worktree
-`launch.sh` creates an isolated session worktree at `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` by default (`HARNESS_USE_WORKTREE=true`) and records it in `.har/slots/agent-<id>.json`. Agents should commit from that worktree, not the main checkout.
+Launch creates an isolated session worktree at `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` by default (`HARNESS_USE_WORKTREE=true`) and records it in `.har/slots/agent-<id>.json`. Agents should commit from that worktree, not the main checkout.
 
 ## Step 3 — Update repo-root `AGENTS.md`
 
@@ -187,8 +216,8 @@ If **no `AGENTS.md` exists**, create one at the repo root using this structure:
 
 - Link to `.har/README.md` and `.har/CLAUDE.agent.md`
 - State plainly: **the harness is how you run this project** — to see the app live (manual testing, browser, screenshots), `launch` a slot; never hand-roll docker/dev-server startup, and never work around a failing harness command with ad-hoc setup (fix or report it instead)
-- Preferred commands: HAR MCP tools or `har env launch/verify/teardown` (persists run history)
-- Shell fallback: `./.har/launch.sh`, `./.har/verify.sh`, `./.har/teardown.sh` (when CLI is not installed)
+- Commands: HAR MCP tools or `har env launch/verify/teardown`
+- Shell shims: `./.har/launch.sh`, `./.har/verify.sh`, `./.har/teardown.sh` — same runtime and run records
 - Rules (no hardcoded ports, use `./.har/agent-cli.sh`, do not touch other agents' resources)
 - Project-specific notes (stack, credentials, definition of done)
 
@@ -206,32 +235,27 @@ If this repository contains **more than one project or `.har` harness** (check f
 
 Include a **Run history** subsection:
 
-- `./.har/*.sh` does not write run records
-- `har env …` and MCP write to `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json`
+- Every entry point (`./.har/*.sh` shims, `har env …`, MCP) writes the same run records to `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json`
 - With worktrees, code runs in the worktree but run JSON lives in the main checkout `.har/runs/`
-- Document MCP/CLI as the preferred agent interface; shell scripts as fallback
+- The `./.har/*.sh` shims forward to the same runtime — evidence records are identical from any surface
 
-## Step 4 — Cleanup checklist (required)
+## Step 4 — Adaptation completeness (required)
 
-The boilerplate ships more than any single repository needs. Strip it down to strictly what this project uses — leftover template content confuses agents and rots. Verify each item:
+Before finishing, confirm the harness describes this project truthfully — do
+**not** go hunting for machinery to prune (the shims and packaged runtime are
+not yours to trim, and wholesale deletion just manufactures drift):
 
-- [ ] `docker-compose.agent.yml` contains ONLY services this project uses (menu entries and their volumes deleted); `HARNESS_INFRA_SERVICES` lists exactly those services
-- [ ] `env.template` has no env blocks for removed services (MinIO/S3, mailpit, headless browser, ...) and no vars the app never reads
-- [ ] `harness.env` has no leftover config for features not in use (e.g. `HARNESS_TEMPLATE_DB` and migrate/seed commands when there is no database)
-- [ ] Scripts (`launch.sh`, `setup-infra.sh`, `teardown.sh`, `agent-cli.sh`, `verify.sh`) contain no dead branches for services this project will never enable — prune, don't comment out
 - [ ] No `TODO` placeholders remain anywhere in `.har/`
-- [ ] Unused harness files are deleted (e.g. `attach.sh` when tmux isn't part of the workflow; CLI profile: `ecosystem.agent.template.cjs`, `env.template`)
-- [ ] `.har/README.md` file table lists exactly the files that exist — no more, no less
-- [ ] `.har/CLAUDE.agent.md` shows only real URLs/ports/credentials (e.g. drop the Frontend row for an API-only project) and project commands that actually run
-- [ ] If full seed/setup is skipped, `.har/` provides a minimal bootstrap or clearly documents why none is needed
+- [ ] `HARNESS_INFRA_SERVICES` lists exactly the services this project uses, each with a lane in `HARNESS_INFRA_PORT_LANES`
 - [ ] All per-slot data stores are provisioned, not just the primary database
-- [ ] `.har/CLAUDE.agent.md` defines what "agent usable" means for this repo: login/API smoke, credentials, required default data, and known skipped dev-setup steps
-- [ ] `.har/README.md` documents port allocation and shared-service model; `harness.env` has the port knobs for every enabled infra service
+- [ ] If full seed/setup is skipped, `.har/` provides a minimal bootstrap or documents why none is needed
+- [ ] `.har/CLAUDE.agent.md` defines what "agent usable" means for this repo (credentials, default data, smoke workflow) and shows only real URLs/ports/commands
+- [ ] `.har/README.md` documents port allocation and the shared-service model
 - [ ] No hardcoded default ports (`3000`, `15432`, `3847`, …) in app code, tests, or harness docs — use agent env / slot registry
 
 ## Rules
 
-1. Edit `.har/` files directly — no YAML runtime config
+1. Customize only through the contract: config in `harness.env`, stages in `stages.json` / `.har/stages/`, hooks in `.har/hooks/`, plugins in `.har/plugins/` — never edit the generated `*.sh` shims
 2. Always update `.har/README.md` to reflect current harness state
 3. Reuse existing project commands from package.json, Makefile, CI, etc.
 4. Replace all TODO placeholders

package/dist/templates/adaptation-prompt-maintain.md

@@ -4,7 +4,11 @@ Update the `.har/` harness in this repository to reflect current codebase change
 
 The harness already exists. Inspect what changed in the repo since the harness was last updated, then edit `.har/` files so coding agents can still run and verify the project correctly.
 
-**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
+`.har/` is a **configuration surface** — the runtime machinery lives in the HAR
+package behind the `./.har/*.sh` shims. Reconcile through the contract only:
+config in `harness.env`, stages in `stages.json` / `.har/stages/`, hooks in
+`.har/hooks/`, plugins in `.har/plugins/`. Never patch the shims — `har env
+eject` is the sanctioned route to script ownership.
 
 {{MAINTAIN_BUNDLE_SECTION}}
 
@@ -15,7 +19,10 @@ Compare the current repo against the existing harness:
 - Root manifests, CI, Docker, README
 - New or changed test, lint, build, migrate, or seed commands
 - New services, ports, or environment variables
-- Review `.har/maintain/drift-report.json` (template drift, **missing port documentation vars**)
+- Review `.har/maintain/drift-report.json` (two-signal drift, **missing port documentation vars**).
+  Drift statuses: `upstream-updated` (bundled template moved since your last finalize — apply the diff),
+  `conflict` (template moved **and** the file was edited locally — merge, keep repo customizations),
+  `adapted` (local edits only — **no action**, never revert to stock; finalize blesses them).
 
 ## Step 2 — Update `.har/` files
 
@@ -24,10 +31,10 @@ Prefer targeted edits over full rewrites. Key files to review:
 ### `.har/README.md` (required)
 Keep this accurate — it is the harness index. Update whenever scripts, stages, or workflow change.
 
-### `.har/harness.env`, `verify.sh`, `provision-toolchain.sh`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
+### `.har/harness.env`, `stages.json`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
 Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. `NPM_BIN` may be bun, pnpm, or yarn, so Node steps must use `${NPM_BIN:-npm} run <script>` and avoid npm-only flags such as `--prefix`. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
 
-### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
+### `.har/env.template`, `docker-compose.agent.yml`
 Update only if infra changed.
 
 ### Readiness vs liveness regression check
@@ -52,54 +59,47 @@ Look specifically for drift introduced since the last adaptation:
   defaults from another file.
 - The dev server mode is fine for humans but blocks browser automation or agents
   with overlays/noisy HMR.
-- `verify.sh` became health-only and no longer checks the key workflow that makes
-  the slot usable.
-- `launch.sh` writes the slot registry only after fragile late steps; partial
-  launches must remain discoverable by verify/status/teardown.
+- `verificationStages` became health-only and no longer checks the key workflow
+  that makes the slot usable.
 
 Update `.har/CLAUDE.agent.md` with skipped setup steps, substitutes, credentials,
 and the repo-specific definition of "agent usable."
 
-### HAR platform upgrades checklist
+### Custom lifecycle behavior — `.har/hooks/`
 
-When upgrading `@osfactory/har` or adopting new harness standards:
+Custom launch/verify/teardown needs belong in lifecycle hooks, never in edits
+to harness machinery: `.har/hooks/pre-launch.sh`, `post-launch.sh`,
+`pre-verify.sh`, `pre-teardown.sh`, `post-teardown.sh`. Hooks receive
+`AGENT_ID`, `WORK_DIR`, `ENV_FILE`, `HAR_HARNESS_DIR`, and `HAR_PORT_<NAME>`
+(contract `HAR_HOOK_CONTRACT=1`). Failing `pre-*` hooks abort the operation;
+`post-*` failures warn unless `HARNESS_HOOK_POST_FAILURE=fail`. Hooks are
+user-owned and never drift-checked — if a past adaptation patched machinery
+scripts for a lifecycle side effect, move that code into a hook.
 
-**Generator 0.5.0 — `AGENTS.md` (canonical agent guide):**
+### HAR platform upgrades
 
-- Repo-root **`AGENTS.md`** is now the shared HAR workflow contract (Codex auto-loads it). Do **not** create or keep **`AGENT.md`** (singular).
-- If **`AGENT.md` exists**: merge any unique project notes into `AGENTS.md`, ensure a **HAR / agent environment** section is present, then **delete `AGENT.md`**.
-- If **`AGENTS.md` is missing**: create it (HAR may already have scaffolded a managed section during `maintain` — fill **Project-specific notes** and keep the marked HAR section).
-- If **`AGENTS.md` already exists**: add or refresh the managed **HAR / agent environment** section only — do not wipe unrelated project guidance.
-- Keep **`CLAUDE.md`** as a **thin pointer** to `AGENTS.md` (Claude Code auto-loads `CLAUDE.md`). Never paste the full Cursor-rule / HAR workflow into `CLAUDE.md`.
-- Update links in `.har/CLAUDE.agent.md` and `.har/README.md` from `AGENT.md` → `AGENTS.md` if they still point at the legacy name.
-- Cursor still uses `.cursor/rules/har-workflow.mdc` (always-on); that rule should also say `AGENTS.md`.
+Platform-shape upgrades are **code, not a checklist**: the har CLI carries a
+versioned migration registry keyed on the manifest's `runtimeVersion`.
+`har env maintain` detects an old harness shape, writes `.har/MIGRATE-PROMPT.md`,
+and `har env maintain --migrate` applies the mechanical steps (shims, pure-config
+`harness.env` with `HARNESS_INFRA_SERVICES` / `HARNESS_INFRA_PORT_LANES`
+conversions, machinery removal) with backups under `.har/migrate/backup/`.
 
-**Generator 0.4.0 — primary app & shared infra services:**
+If a `.har/MIGRATE-PROMPT.md` exists, **follow it instead of this prompt** and
+come back here afterwards. Two standing rules:
 
-- Migrate `harness.env` from boolean `HARNESS_INFRA_*` flags to the `HARNESS_INFRA_SERVICES` list (space-separated compose service names, e.g. `"db mailpit"`) and add the `har_infra_enabled()` helper — copy both from `.har/maintain/templates/harness.env`. Update every script that still tests `HARNESS_INFRA_POSTGRES`-style flags (`setup-infra.sh`, `launch.sh`, `teardown.sh`, `agent-cli.sh`) to use `har_infra_enabled <service>`.
-- Set `HARNESS_PRIMARY_APP` in `harness.env` to the ONE app agents modify. Ensure `ecosystem.agent.template.cjs` starts only that app's processes. Move any other in-repo services agents depend on but don't change to shared infra: compose services in `docker-compose.agent.yml` or an optional `.har/ecosystem.shared.config.cjs` (processes `har-shared-<name>`; `setup-infra.sh` starts it when present — resync `setup-infra.sh` from the template to get this hook).
-- Prune `docker-compose.agent.yml` to only the services this project uses; delete unused menu services and volumes.
-- **Port & shared services:** ensure `.har/README.md` documents the allocation table and shared vs per-slot model; `harness.env` has every `HARNESS_*_PORT_*` var required for services in `HARNESS_INFRA_SERVICES` (copy missing vars from `.har/maintain/templates/harness.env` when drift reports them). Remove hardcoded ports from app code, tests, and `CLAUDE.agent.md`.
-- Run the **cleanup checklist**: no TODO placeholders, no env blocks for removed services in `env.template`, no dead script branches, `.har/README.md` file table matches the actual files, `CLAUDE.agent.md` shows only real URLs/ports and commands, unused files deleted.
-
-**Earlier standards:**
-
-- Add **Run history** section to repo-root `AGENTS.md` if missing (shell vs `har env`, worktree vs runs location)
-- Ensure `AGENTS.md` / `CLAUDE.agent.md` frame the harness as **how you run the project** (launch for manual testing/browser/screenshots; fix — don't work around — failing harness commands)
-- Ensure `launch.sh` installs dependencies in fresh worktrees and resolves the project subdirectory inside the worktree (`git rev-parse --show-prefix`) for monorepos
-- If the repo has multiple projects/harnesses, maintain the **"Harnesses in this repo"** table in root `AGENTS.md`, per-project pointer docs, and a single root Cursor rule
-- Remove dead boilerplate files (CLI profile: `ecosystem.agent.template.cjs`, `env.template`, `attach.sh`)
-- Align `launch.sh` / `harness.env` with worktree-default standard (`HARNESS_USE_WORKTREE=true`)
-- Do **not** blindly overwrite customized `verify.sh`
+- Verification customization lives in `stages.json` / `.har/stages/` — the
+  top-level `*.sh` files are generated shims, safe to regenerate.
+- Repo-root agent docs (`AGENTS.md`, `CLAUDE.md`) follow Step 3 below.
 
 ## Step 3 — Refresh repo-root `AGENTS.md`
 
 If harness commands, rules, or workflow changed, update the **HAR / agent environment** section in repo-root `AGENTS.md`:
 
 - Links to `.har/README.md` and `.har/CLAUDE.agent.md`
-- Preferred: HAR MCP tools or `har env …` (persists run history)
-- Fallback: `./.har/*` shell scripts (when CLI is not installed)
-- Run history rules (shell vs CLI/MCP, worktree vs `.har/runs/` location)
+- Commands: HAR MCP tools or `har env …`
+- Shell shims: `./.har/*.sh` — thin delegates to `har env`, same run records
+- Run history (worktree runs record to the main checkout `.har/runs/`)
 - Agent rules (ports, agent-cli.sh, isolation)
 - Project-specific notes
 
@@ -109,7 +109,7 @@ Do **not** create `AGENT.md` (singular). If legacy `AGENT.md` exists, merge uniq
 
 ## Rules
 
-1. Prefer targeted edits — keep working harness behavior where still valid
+1. Prefer targeted edits through the contract (config / stages / hooks / plugins) — keep working harness behavior where still valid; never edit the generated `*.sh` shims
 2. Always update `.har/README.md` when anything in the harness changes
 3. Reuse existing project commands from package.json, Makefile, CI, etc.
 4. Replace any remaining TODO placeholders

package/dist/templates/agent-skills/har-maintain.md

@@ -12,9 +12,9 @@ This compares the harness against the current templates and repository, refreshe
 
 ## 2. Perform the adaptation yourself
 
-Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENTS.md` with the repository's current stack, ports, and commands. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
+Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile the harness configuration surface (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `docker-compose.agent.yml`, `env.template`) and `AGENTS.md` with the repository's current stack, ports, and commands. The `./.har/*.sh` files are generated shims — leave them alone. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
 
-Also check stage drift: compare the repository's current check commands (package.json scripts, Makefile, CI) against the stages registered in `.har/stages.json`. Register missing checks (`har env add-stage <id> --custom --command "..." --verification`), and remove or fix stages whose commands no longer exist. `.har/STAGES.md` documents the contract.
+Also check stage drift: compare the repository's current check commands (package.json scripts, Makefile, CI) against the stages registered in `.har/stages.json`. Register missing checks (add a command stage entry to `.har/stages.json` and list it in `verificationStages`; scaffold script-based checks with `har plugin create <id>` + `har env add-plugin <id>`), and remove or fix stages whose commands no longer exist. `.har/STAGES.md` documents the contract.
 
 ## 3. Finalize and prove it works
 

package/dist/templates/agent-skills/setup-har.md

@@ -50,17 +50,19 @@ If `.har/` already exists, stop and suggest `/har-maintain` instead.
 
 ## 5. Perform the adaptation yourself
 
-`har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENTS.md` to this repository's real stack, ports, and commands.
+`har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor the harness configuration surface (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `docker-compose.agent.yml`, `env.template`) and `AGENTS.md` to this repository's real stack, ports, and commands. The `./.har/*.sh` files are generated shims over the packaged runtime — never edit them.
 
 ## 6. Register the project's checks as stages
 
 Convert the repository's real check commands (test, lint, typecheck, whatever CI runs) into registered stages so they run in `verify --full` and are visible to every agent. Read `.har/STAGES.md` for the contract, then:
 
-```bash
-har env add-stage unit-tests --custom --kind test --command "npm test" --verification
+```json
+{ "id": "unit-tests", "kind": "test", "command": "npm test", "tier": "quick" }
 ```
 
-- Use `--command` for one-liner checks; use `--script` when a check needs the slot's env, ports, or artifacts (then implement the scaffolded `.har/stages/<id>.sh`).
+(add the entry to `.har/stages.json` `stages` and its id to `verificationStages`).
+
+- Use a command stage for one-liner checks; when a check needs the slot's env, ports, or artifacts, scaffold a project-owned plugin: `har plugin create <id>`, implement `.har/plugins/<id>/stages/<id>.sh`, then `har env add-plugin <id>`.
 - Rich integrations ship as **plugins**: `har env add-plugin --list`, then e.g. `har env add-plugin playwright` (web) or `har env add-plugin rocketsim` (iOS). Plugins install stages; agents only talk to the stage registry.
 
 ## 7. Prove the harness works

package/dist/templates/cursor-rule.mdc.template

@@ -9,7 +9,8 @@ This repository uses a `.har/` agent harness. Follow this on every change.
 
 The harness is **how you run the project**, not only how you verify it. Launch a
 slot for live apps, browsers, and screenshots — never hand-roll docker/dev-server
-startup. If a harness command fails, fix the harness or surface the failure.
+startup. If a harness command fails, fix the harness or surface the failure. Customize
+only via the contract (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `.har/plugins/`) — never edit the generated `./.har/*.sh` shims.
 
 ## Before making changes
 
@@ -42,8 +43,7 @@ the first captured user prompt.
 | `.har/` | backend + frontend | `src/`, `packages/` |
 | `apps/admin/.har/` | admin dashboard | `apps/admin/` |
 
-Run harness commands from the directory that owns the harness (e.g. `cd apps/admin`).
--->
+Run harness commands from the directory that owns the harness (e.g. `cd apps/admin`). -->
 
 ## After making changes
 

package/dist/templates/har-boilerplate/docker-compose.agent.yml

@@ -34,7 +34,7 @@ services:
     image: coollabsio/minio:latest
     ports:
       - "${AGENT_MINIO_PORT:-19000}:9000"
-      - "${AGENT_MINIO_CONSOLE_PORT:-19001}:9001"
+      - "${AGENT_MINIO_CONSOLE_PORT:-19050}:9001"
     volumes:
       - agent-minio-data:/minio/data
     environment: