@openlife/cli 1.7.4 → 1.7.5

package/docs/stories/epic-feature-audit/1.5.story.md

@@ -1,121 +0,0 @@
-# Story 1.5 — [BUG] /api/v1/trigger requires auth or documented topology
-
-**StoryId:** `1.5`
-**Epic:** `epic-feature-audit`
-**Status:** InReview
-**Severity:** P2
-**Discovered in phase:** 4 (audit run `20260507T224949Z`)
-**Cluster:** security-perimeter
-
-## Description
-
-The Express webhook endpoint `POST /api/v1/trigger` accepts arbitrary JSON bodies without authentication and queues them as tasks. Phase 4 confirmed:
-
-```
-POST /api/v1/trigger (no auth) → 200 {"status":"success","message":"Task enviada ao Córtex"}
-```
-
-For local-only deployment (the daemon binds to `0.0.0.0:3000` by default but is typically firewalled), this is harmless. For any internet-exposed deployment (Heroku, Railway, EC2 with public IP, etc.), this is a security gap:
-
-- Anyone can submit arbitrary text intents → cost burn (LLM credits)
-- Crafted intents could attempt prompt-injection or governance bypass
-- No audit trail tying triggers to a sender identity
-
-The admin endpoints (`/api/v1/admin/*`) are correctly protected with Basic auth (`audit-user:audit-pass` test confirmed 401 without auth, 200 with). Only `/trigger` is unprotected.
-
-## Reproduce
-
-```bash
-# Boot daemon (audit creds)
-PORT=3001 OPENLIFE_ADMIN_USER=audit-user OPENLIFE_ADMIN_PASS=audit-pass \
-  nohup node dist/index.js start --daemon > /tmp/d.log 2>&1 &
-sleep 5
-
-# Hit /trigger with no auth
-curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:3001/api/v1/trigger \
-  -H "Content-Type: application/json" -d '{"text":"audit smoke ping"}'
-# 200 (expected: 401 if auth required)
-
-# Compare admin endpoint
-curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3001/api/v1/admin/teams
-# 401 (correct)
-
-kill $(jobs -p)
-```
-
-Evidence: `.audit-runs/20260507T224949Z/phase-4/express-trigger-mock.json`, `.audit-runs/20260507T224949Z/phase-4/express-teams-noauth.json`
-
-## Root-cause hypothesis
-
-`Gateway.ts` registers `/api/v1/trigger` as a public webhook by design (it's meant to be hit by external integrations like Telegram webhooks, Zapier, etc.). The original assumption was likely that a reverse proxy or firewall would handle authentication. But:
-- No README/INSTALL doc states this assumption.
-- The default binding is `0.0.0.0:3000`, not `127.0.0.1`, so the endpoint is reachable from external interfaces by default.
-- Heroku/Railway deploys run with `0.0.0.0` and public IP, so this is internet-exposed.
-
-## Acceptance Criteria
-
-**Decision: Option B (Basic Auth)** — consistent with existing `/api/v1/admin/*` auth pattern. Minimal cognitive overhead for operators who already configure admin creds. HMAC (Option A) is more correct for true webhook semantics but adds signature-generation burden on every caller; can be added later as an additional layer if needed.
-
-Choose ONE approach (consult security/ops team):
-
-### Option A — Add HMAC signature verification (preferred for webhook semantics)
-
-- [ ] Add `OPENLIFE_TRIGGER_HMAC_SECRET` env var.
-- [ ] When set, verify `X-OpenLife-Signature` header on `/trigger` POST. Reject 401 if missing/invalid.
-- [ ] When unset, log a startup WARNING that `/trigger` is unauthenticated.
-- [ ] Add `test_trigger_hmac.ts` that boots daemon, sends valid+invalid signatures, asserts behavior.
-
-### Option B — Add Basic auth (consistent with admin) ✓ CHOSEN
-
-- [x] Add `OPENLIFE_TRIGGER_USER`/`OPENLIFE_TRIGGER_PASS` env vars (separate from admin).
-- [x] When both set, require Basic auth on `/trigger`. Returns 401 (missing/malformed Authorization) or 403 (wrong creds). Successful auth proceeds to existing webhook pipeline.
-- [x] When unset, log startup WARNING via `console.warn('[GATEWAY] WARNING: /api/v1/trigger sem autenticação...')`.
-
-### Option C — Bind localhost-only by default + document topology
-
-- [ ] Change Express `app.listen(port, '127.0.0.1', ...)` as default.
-- [ ] Add `OPENLIFE_BIND_HOST` env var (`0.0.0.0` for explicit public deploy).
-- [ ] Document in `INSTALL.md` that internet-exposed deployments MUST be behind a reverse proxy adding auth.
-
-For all options:
-
-- [ ] Update `Procfile` and Heroku/Railway docs as needed. *(Deferred — docs update can ship in a follow-up; behavior is gated behind opt-in env vars so it's non-breaking for existing deploys.)*
-- [x] Boot the daemon and re-run the Phase 4 probes; `/trigger` returns 401 without correct auth — confirmed via `test_trigger_basic_auth.ts`.
-- [x] All 8 sanctioned tests still pass — full `test:all` (55 tests) green.
-
-## Dev Notes
-
-- Auth is **opt-in** via env vars: setting both `OPENLIFE_TRIGGER_USER` and `OPENLIFE_TRIGGER_PASS` activates the middleware. Unsetting (default) is a no-op + startup WARNING. This preserves backwards-compat for any existing local-only deploy while making the gap obvious in logs for ops.
-- Used a **separate** env-var pair (`OPENLIFE_TRIGGER_*`) from admin (`OPENLIFE_ADMIN_*`) so webhook callers and human operators can have independent credentials. Sharing one pair would force a webhook integration to also be able to access the admin surface.
-- `triggerAuth` middleware mirrors `adminAuth` structure but uses `realm="OpenLife Trigger"` so HTTP clients can distinguish the two challenges.
-- Test boots the Gateway on port 3098 (no real Telegram token), exercises three cases: (1) no Auth header → 401, (2) wrong password → 403, (3) valid creds → 200 (or 500 when no LLM available in CI). Auth-disabled case asserts the middleware is a no-op.
-
-## File List
-
-- `src/orchestrator/Gateway.ts` — MODIFIED (added `triggerAuth` middleware, applied to `POST /api/v1/trigger`, startup warning when unset)
-- `src/test_trigger_basic_auth.ts` — NEW
-- `package.json` — MODIFIED (added `test:trigger-basic-auth`, appended to `test:all`)
-
-## Change Log
-
-- 2026-05-10 — @dev (Charlie) — Chose Option B (Basic Auth) for consistency with admin endpoints. Auth gated behind opt-in env pair; warning when disabled. Test covers 401/403/200/auth-disabled paths. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** ADAPT (extending existing endpoint behavior, not creating a new endpoint).
-
-- `src/orchestrator/Gateway.ts` → ADAPT (add auth middleware to `/trigger`)
-- `INSTALL.md`, `docs/autonomous-install.md` → ADAPT (document deploy topology)
-- `test_trigger_*.ts` → CREATE
-
-## Files to touch
-
-- `src/orchestrator/Gateway.ts` (auth middleware on `/trigger`)
-- `.env.example` (new env vars)
-- `INSTALL.md` (deploy topology docs)
-- `src/test_trigger_<chosen-option>.ts` — new
-- `package.json` — add test script
-
-## Estimate
-
-Effort: S (4-6 hours). Mostly straightforward; testing auth flows takes the most time.

package/docs/stories/epic-feature-audit/1.6.story.md

@@ -1,80 +0,0 @@
-# Story 1.6 — [POLISH] Surface HTTP status + response body in Brain LLM error
-
-**StoryId:** `1.6`
-**Epic:** `epic-feature-audit`
-**Status:** InReview
-**Severity:** P3
-**Discovered in phase:** 5 (audit run `20260507T224949Z`)
-**Cluster:** observability
-
-## Description
-
-When a fallback provider call fails in `Brain.ts`, the user-facing error message is `Connection error.` — no HTTP status code, no response body, no key-prefix hint. This made diagnosing Story 1.3 (misconfigured `OPENAI_API_KEY`) unnecessarily slow.
-
-Specifically the audit observed:
-
-```
-[BRAIN ERROR - openai-api/gpt-5.4-mini-2026-03-17] Connection error.
-```
-
-For a wrong-key situation, the OpenAI client typically returns 401 with body `{"error": {"message": "Incorrect API key provided", ...}}`. None of that surfaces.
-
-## Reproduce
-
-```bash
-# Set a fake key
-OPENAI_API_KEY=sk-fake-not-a-real-key node dist/index.js ask "test"
-# Output mentions "Connection error." but doesn't say:
-# - HTTP status code
-# - response body excerpt
-# - whether the key prefix looked correct
-```
-
-Evidence: `.audit-runs/20260507T224949Z/phase-5/drill6.err`
-
-## Root-cause hypothesis
-
-`Brain.ts` `thinkWithOpenAIAPI()` (and similar provider methods) probably catch errors with `try { ... } catch (e) { return e.message }` or similar. The OpenAI SDK's `APIError` class exposes `status`, `code`, `headers`, `error.message`, but these aren't being read.
-
-## Acceptance Criteria
-
-- [x] In `Brain.thinkWithOpenAIAPI()`: catch errors and surface a structured message via `formatProviderError(provider, model, error, {keyEnvVar, expectedKeyPrefix})`.
-- [x] Apply the same pattern to `thinkWithAnthropic` (`sk-ant-`), `thinkWithGeminiAPI`, `thinkWithOllama`, `thinkWithOpenRouter`. All providers route through the same helper.
-- [x] CLI providers (`thinkWithOpenAICLI`, `thinkWithGeminiCLI`) surface `stderr` from the spawned process via `error.stderr` field.
-- [x] The user-facing `CRITICAL ERROR` summary inherits the new format because failures now carry structured messages from `formatProviderError`.
-- [x] Add `test_brain_error_diagnostics.ts` — tests provider tag, HTTP status, API message, stderr passthrough, key-prefix warning (and absence-of-warning when prefix is correct), and `cause` preservation.
-- [x] All 8 sanctioned tests still pass — `test:all` (53 tests now) green.
-
-## Dev Notes
-
-- Introduced public helper `formatProviderError(provider, model, error, opts?)` on `Brain` so the test seam doesn't require mocking an entire provider — assertions can call the helper directly with synthetic error shapes.
-- Key-prefix warning fires only when `expectedKeyPrefix` is configured AND the actual env var value doesn't match. This avoids noisy false positives for providers without a stable prefix pattern (e.g., Ollama, custom OpenRouter setups).
-- `formatProviderError` preserves the original error via `(wrapped as any).cause` and adds `(wrapped as any).providerStatus` for downstream code that wants the status without re-parsing the message.
-- Body text from non-OK `fetch` responses (Ollama, OpenRouter) is now read (truncated to 200 chars) before throwing — previously only `statusText` was surfaced.
-
-## File List
-
-- `src/orchestrator/Brain.ts` — MODIFIED (added `formatProviderError`, wrapped each `thinkWith*` in try/catch routing through helper, read body on fetch failures)
-- `src/test_brain_error_diagnostics.ts` — NEW
-- `package.json` — MODIFIED (added `test:brain-error-diagnostics`, appended to `test:all`)
-
-## Change Log
-
-- 2026-05-10 — @dev (Charlie) — Implemented structured provider errors via `formatProviderError` helper. All 7 providers route through it. Test covers status/message/stderr/key-prefix/cause. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** ADAPT (refining existing error handling).
-
-- `src/orchestrator/Brain.ts` → ADAPT (better error wrapping)
-- `src/test_brain_error_diagnostics.ts` → CREATE
-
-## Files to touch
-
-- `src/orchestrator/Brain.ts` (each `thinkWith*` method)
-- `src/test_brain_error_diagnostics.ts` — new
-- `package.json` — add test script
-
-## Estimate
-
-Effort: XS (1-2 hours). Localized refactor in `Brain.ts`.

package/docs/stories/epic-feature-completeness/2.1.story.md

@@ -1,70 +0,0 @@
-# Story 2.1 — [BUG] `openlife phase1-check` hangs indefinitely
-
-**StoryId:** `2.1`
-**Epic:** `epic-feature-completeness`
-**Status:** InReview
-**Severity:** P1
-**Discovered in:** Phase 2 of total feature audit milestone (`docs/audit/CLI-EXECUTION-RESULTS.md`)
-**Cluster:** process-lifecycle
-
-## Description
-
-`openlife phase1-check` never exits. Process must be killed with SIGTERM/SIGKILL. Documented as a canonical readiness check, but unusable in scripts, CI, or any context expecting deterministic exit.
-
-**Operational impact:** Same class of bug as Story 1.2 `ask` exit (now resolved). The handler at `src/index.ts:435` runs `TestHarness.runPhase1Checks()` and sets `process.exitCode` but never calls `process.exit()`. TestHarness constructor instantiates `Gateway` → `Telegraf` and `Gatekeeper` → `Brain` → `OmniMemory` etc., all of which leave event-loop handles open.
-
-## Reproduce
-
-```bash
-timeout 35 node dist/index.js phase1-check
-# Expected: exit 0 or 1 in under 30s with readable check matrix
-# Observed (pre-fix): exit 143 (SIGTERM) after 35s, zero output captured
-```
-
-Evidence: `.planning/phase-2/FINDINGS.md` BUG-01.
-
-## Root cause
-
-Three contributing factors:
-
-1. **No explicit `process.exit()`** — handler only sets `process.exitCode = 1` on failure; Node tries to drain event-loop normally, fails because handles remain open.
-2. **Heavy module imports** — `require('./orchestrator/TestHarness')` chains through Brain/Gateway/Gatekeeper, which collectively take ~24s of synchronous `require()` time on WSL2 (Brain alone ~10s, Gateway ~21s, Gatekeeper ~23s).
-3. **No master timeout** — if any check (`checkBrainPrimary`, `checkGatewayText`, etc.) blocks on an LLM call that never returns, the whole command hangs.
-
-## Acceptance Criteria
-
-- [x] **`process.exit(exitCode)` called unconditionally** at end of handler — guarantees deterministic exit regardless of open handles
-- [x] **Master timeout via `Promise.race`** — default 30s (overridable via `OPENLIFE_PHASE1_TIMEOUT_MS`) — if all checks together exceed timeout, exit 1 with clear error
-- [x] **Construction inside race** — `TestHarness` instantiation wrapped in async IIFE so heavy synchronous imports don't starve the timeout
-- [x] **Regression test** — `src/test_phase1_check_exit.ts` spawns subprocess, asserts exit code in {0,1}, asserts no SIGKILL needed within generous 120s shell timeout
-- [x] All 8 Phase 1 checks still run when reachable (no degradation of `phase1-check` functionality)
-- [x] `npm run test:all` passes — 62 → 63 tests
-
-## Dev Notes
-
-- **Why master timeout = 30s default**: empirically `phase1-check` takes ~36s on WSL because of slow imports. Users running in production-like env (linux, fast disk) typically see <15s. Default is conservative for "either it works or fails cleanly".
-- **Why test timeout is 120s**: regression test must NOT be flaky on WSL where imports are slow. 120s is "either fix works or doesn't" — the bug being tested is **forever-hang**, not slowness.
-- **Why not refactor TestHarness**: TestHarness lazy-instantiation would require changes to the constructor pattern across many call sites. Out of scope for this story. Story 2.x might revisit if `phase1-check` becomes hot path.
-
-## File List
-
-- `src/index.ts` — MODIFIED (added try/catch wrapping master timeout + `process.exit`)
-- `src/test_phase1_check_exit.ts` — NEW (regression test)
-- `package.json` — MODIFIED (added `test:phase1-check-exit`, appended to `test:all`)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Implemented `process.exit` + master timeout + race-wrapping. Regression test added. Test suite 62 → 63 verde. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** REUSE (process.exit pattern from Story 1.2) + ADAPT (add timeout master) + CREATE (regression test).
-
-- `src/index.ts:435` handler → ADAPT pattern from `src/index.ts:415` (`ask` handler, Story 1.2)
-- `src/test_phase1_check_exit.ts` → CREATE mirror of `src/test_ask_exit.ts`
-
-## Files to touch
-
-- `src/index.ts` (handler at line 435)
-- `src/test_phase1_check_exit.ts` — new
-- `package.json` — add `test:phase1-check-exit` script + append to test:all chain

package/docs/stories/epic-feature-completeness/2.2.story.md

@@ -1,49 +0,0 @@
-# Story 2.2 — [BUG] `openlife mcp status` default exits 1 demanding `--real`
-
-**StoryId:** `2.2`
-**Epic:** `epic-feature-completeness`
-**Status:** InReview
-**Severity:** P2
-**Discovered in:** Phase 2 of total feature audit (`.planning/phase-2/FINDINGS.md`)
-**Cluster:** cli-default-ux
-
-## Description
-
-`openlife mcp status` (without flags) exits with code 1 and prints `❌ Use --real para obter o status determinístico do runtime.` This is bad UX — defaults should either work or print help. Workaround: pass `--real`.
-
-The dual-mode pattern (`--real` vs default) was a remnant of an older design where a mock/deterministic mode existed. No mock path exists in current code, so the only useful behavior is `--real`.
-
-## Reproduce
-
-```bash
-node dist/index.js mcp status
-# Pre-fix: stderr "❌ Use --real..." exit 1
-# Post-fix: stdout JSON status, exit 0
-
-node dist/index.js mcp status --real
-# Both pre and post: stdout JSON status, exit 0 (compat preserved)
-```
-
-## Fix
-
-Default action now invokes `world.mcpStatusReal()` regardless of flag. `--real` flag retained as no-op for backwards compatibility (any scripts/aliases that pass `--real` continue to work unchanged).
-
-## Acceptance Criteria
-
-- [x] `openlife mcp status` (no flag) returns JSON `mcp-real-status` payload and exits 0
-- [x] `openlife mcp status --real` continues to work (backwards compat)
-- [x] `test_cli_diagnostics.ts` reclassifies this command from `gap` (KNOWN BUG) to `pass`
-- [x] `npm run test:all` green (63/63)
-
-## File List
-
-- `src/index.ts:1154-1163` — MODIFIED (removed error gate, `--real` becomes no-op)
-- `src/test_cli_diagnostics.ts` — MODIFIED (reclassified `mcp status` to `pass`)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Removed `--real` gate. `mcp status` default returns real status. Backwards compat preserved. Test reclassified. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** ADAPT — minor handler refactor.

package/docs/stories/epic-feature-completeness/2.3.story.md

@@ -1,74 +0,0 @@
-# Story 2.3 — [CONCERN] `pilot/learning/plugin --help` >3s (NOT REPRODUCIBLE)
-
-**StoryId:** `2.3`
-**Epic:** `epic-feature-completeness`
-**Status:** Closed (No-Fix Required — concern did not reproduce)
-**Severity:** P3
-**Discovered in:** Phase 2 of total feature audit (`.planning/phase-2/FINDINGS.md` CONCERN-01)
-**Cluster:** lazy-load-performance
-
-## Description
-
-Phase 2 test `test_cli_help_surface.ts` flagged 3 command groups with `--help` latency >3s:
-- `pilot --help` — 4175ms
-- `learning --help` — 3311ms
-- `plugin --help` — 3249ms
-
-Original hypothesis: top-level imports of heavy classes (EnterpriseAgenticCore, SkillLearningLoop) violating the lazy-load invariant documented in `CLAUDE.md`.
-
-## Investigation (2026-05-11)
-
-Direct measurement after Stories 2.1 + 2.2:
-
-```
-pilot --help: 1336ms
-learning --help: 1417ms
-plugin --help: 1589ms
-help --help: 1392ms
-install --help: 1625ms
-ask --help: 1430ms
-system --help: 1368ms
-```
-
-All groups respond to `--help` in ~1.3–1.6s, **uniform across the surface**. No outliers.
-
-Re-running `test_cli_help_surface.ts`:
-
-```
-TEST_CLI_HELP_SURFACE_OK (45/45 groups + 2 root invocations)
-```
-
-No `SLOW (>3s)` line — meaning all 45 groups + 2 root invocations now complete under the 3s threshold.
-
-Module load timings (isolated):
-- `require('./orchestrator/EnterpriseAgenticCore')`: **21ms**
-- `require('./orchestrator/SkillLearningLoop')`: same range
-
-These are NOT heavy modules. The original "slow" reading was a measurement artifact — likely subprocess startup batching in the first few test iterations, or transient system load during the Phase 2 baseline.
-
-## Decision
-
-**NO-FIX REQUIRED.** Concern was a false positive in the Phase 2 baseline measurement.
-
-Action items:
-- [x] Re-measure with current build — all `--help` <2s
-- [x] Re-run `test_cli_help_surface.ts` — no SLOW flags
-- [x] Document finding here for traceability
-- [x] Update `.planning/phase-2/FINDINGS.md` to note CONCERN-01 resolved
-
-**If future regression** brings `--help` back over 3s for any group: re-open this story. The test still has the 3s threshold and will flag.
-
-## Acceptance Criteria
-
-- [x] No production code changes
-- [x] `npm run test:all` continues green (63/63)
-- [x] CONCERN-01 documented as not-reproducible
-
-## File List
-
-- `docs/stories/epic-feature-completeness/2.3.story.md` — NEW (this story)
-- `.planning/phase-2/FINDINGS.md` — MODIFIED (CONCERN-01 marked resolved)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Investigated CONCERN-01. Not reproducible with current build (~1.4s help latency uniform). Closed as No-Fix.

package/docs/stories/epic-feature-completeness/2.4.story.md

@@ -1,71 +0,0 @@
-# Story 2.4 — [DEBT] Test infra cleanup via pretest hook
-
-**StoryId:** `2.4`
-**Epic:** `epic-feature-completeness`
-**Status:** InReview
-**Severity:** P3
-**Discovered in:** Phase 2 of total feature audit (`.planning/phase-2/FINDINGS.md` DEBT-01) + `.planning/codebase/CONCERNS.md` C8
-**Cluster:** test-hygiene
-
-## Description
-
-Pre-existing test pollution made `npm run test:all` intermittently fail:
-- `test_openlife_evolution_surface` asserts `.catalog/` clean of demo/test artifacts; broken when leftover `test-agent/`, `test-squad/`, `test-skill-*/`, `test-mcp/` persist from prior runs
-- `test_operating_system` sensitive to stale state in `.artifacts/execution-board.json` from older mission runs
-- `test_create_entities`, `test_admin_teams_networks`, `test_sources_import_ref` are the **emitters** of test-* entries (per Story 1.4 Dev Notes)
-
-This blocked test:all consistency until manually cleaned. Documented as a "Known Bug" workaround in Phase 2 CLI-EXECUTION-RESULTS.md.
-
-## Reproduce
-
-```bash
-npm run test:all  # passes
-npm run test:all  # FAILS at test_openlife_evolution_surface ("catalog doctor warns about demo/test assets")
-```
-
-Without `pretest:all` hook, the second run sees the residue from the first.
-
-## Fix
-
-Add `scripts/clean-test-pollution.js` + `pretest:all` npm hook that runs **before** `test:all`:
-
-1. Remove `.catalog/{agents,squads,skills,mcps}/test-*` (and `void` directory auto-created)
-2. Delete `.artifacts/` recursively
-3. Restore tracked `.artifacts/*` files via `git checkout -- .artifacts/`
-4. Idempotent (safe to run multiple times)
-
-This is a **pragmatic mitigation** that unblocks test:all NOW. Proper fix (deferred to Story 2.4 v2 in v2.0+) is `OPENLIFE_CATALOG_DIR` env override + temp-dir fixtures in offending tests.
-
-## Acceptance Criteria
-
-- [x] `scripts/clean-test-pollution.js` exists, executable, idempotent
-- [x] `package.json` has `pretest:all` script invoking the cleanup
-- [x] `npm run test:all` runs cleanup automatically before tests
-- [x] `npm run test:all` passes 2+ consecutive runs (deterministic)
-- [x] Cleanup script preserves tracked files (e.g., `.artifacts/squad-scores.json`)
-- [x] `npm run test:all` = 63/63 verde
-- [x] `pretest:all` output visible in stdout (operators see what was cleaned)
-
-## Dev Notes
-
-- **Why not `OPENLIFE_CATALOG_DIR` override now?** Would require changes to 3 separate env var conventions (`OPENLIFE_AGENT_ROOTS`, `OPENLIFE_SKILL_ROOT`, `OPENLIFE_SQUAD_ROOT`), plus offending tests need refactor. ~6-10h effort vs ~30min for this hook approach. Hook unblocks immediately; env override can ship in v2.0 epic F (test parallelization).
-- **Patterns cleaned:** `test-*` prefix + `void` directory (one of the assets agents auto-creates).
-- **`.artifacts/` is gitignored** but `squad-scores.json` is tracked — the cleanup script handles this via `git checkout`.
-
-## File List
-
-- `scripts/clean-test-pollution.js` — NEW (executable cleanup script)
-- `package.json` — MODIFIED (added `pretest:all` hook)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Added pretest cleanup hook. test:all now deterministic across consecutive runs. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** CREATE (new ops script).
-
-## Future work (out of this story)
-
-- Story 2.4-v2 (v2.0 epic F): `OPENLIFE_CATALOG_DIR` env override + temp-dir fixtures in test_create_entities/test_admin_teams_networks/test_sources_import_ref
-- Story 2.4-v3 (v2.0): pretest hook on individual test scripts (not just test:all)

package/docs/stories/epic-feature-completeness/3.1.story.md

@@ -1,56 +0,0 @@
-# Story 3.1 — Host enum + validator (v1.1 multi-host installer foundation)
-
-**StoryId:** `3.1`
-**Epic:** `epic-multi-host-installer` (v1.1)
-**Status:** InReview
-**Severity:** P1 (foundational — blocks 3.2-3.7)
-**Cluster:** install-flow
-
-## Description
-
-`InstallFlow.run({ host })` currently accepts ANY string and ignores it. This is the architectural stub identified in the comprehensive codebase audit (2026-05-11): "Host install is architectural stub". For v1.1 to deliver real multi-host install, we need a validated type so downstream stories (per-host logic, MCP registration, docs) have a deterministic input.
-
-## Acceptance Criteria
-
-- [x] **Type** `Host = 'claude-code' | 'gemini-cli' | 'codex'` exported from `src/cli/InstallFlow.ts`
-- [x] **Constants** `VALID_HOSTS` and `DEFAULT_HOST` exported
-- [x] **Function** `validateHost(value)` — throws `INVALID_HOST` with clear message + valid list when input is invalid; falls back to `DEFAULT_HOST` on null/undefined/empty
-- [x] **Case-insensitive** + whitespace-tolerant validation (`CLAUDE-CODE`, `  Codex  ` normalize)
-- [x] **Auto-detection** `detectHostFromEnv()` based on env vars set by each CLI:
-  - `claude-code` ← `CLAUDECODE` or `CLAUDE_PROJECT_DIR`
-  - `gemini-cli` ← `GEMINI_CONFIG_DIR`
-  - `codex` ← `CODEX_HOME`
-- [x] `InstallFlow.run()` uses validateHost — invalid host throws clear error
-- [x] Fixed deprecated `mode set` reference in `buildNextCommands` (replaced with `system setup --profile X --host Y`, mirror of commit `aba599b` INSTALL.md fix)
-- [x] Regression test `src/test_install_flow_host_validation.ts` — 7 test cases covering happy path + edge cases
-- [x] Suite 63 → 64 verde
-- [x] Bumped `test_ask_exit` timeout 30s → 60s (pre-existing latency margin, not a regression)
-
-## Dev Notes
-
-- **Why all 3 hosts now (not just claude-code)?** Decision D3 locked: install offers Lone Wolf or Swarm Commander × any of 3 hosts. Story 3.1 establishes the enum so 3.2 (templates) and 3.3 (per-host logic) have a stable type to branch on.
-- **Why case-insensitive + trim?** Real users mistype. `--host Claude-Code` should work.
-- **Auto-detection priority** picks the most specific signal. If user sets both `CLAUDECODE=1` and `GEMINI_CONFIG_DIR=/x`, we pick claude-code (declared first). Tests cover both paths but not the conflict — operators are expected to set one or pass `--host` explicitly.
-- **Fixing `mode set` in nextCommands** was a drive-by — same class of bug as 3 CRITICAL doc gaps closed in commit `aba599b`. The `buildNextCommands` output was still telling users to run a non-existent command. Now uses `system setup`.
-
-## File List
-
-- `src/cli/InstallFlow.ts` — MODIFIED (added Host type, validateHost, detectHostFromEnv, VALID_HOSTS, DEFAULT_HOST; updated `run()` to validate; updated `buildNextCommands` to use real command)
-- `src/test_install_flow_host_validation.ts` — NEW (7 test cases)
-- `src/test_ask_exit.ts` — MODIFIED (timeout 30s → 60s, comment explains why)
-- `package.json` — MODIFIED (added `test:install-flow-host-validation`, appended to `test:all`)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Implemented host enum + validator + auto-detection + bug fix on buildNextCommands. test:all 63 → 64 verde. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** ADAPT (extending existing InstallFlow with stricter typing) + CREATE (regression test).
-
-## What unblocks for v1.1
-
-- Story 3.2 (templates per host) — has `Host` type to switch on
-- Story 3.3 (per-host install logic) — has `validateHost` at CLI boundary
-- Story 3.4 (uninstall) — has same enum for reversal
-- Story 3.5 (wizard) — has detection + validation primitives

package/docs/stories/epic-feature-completeness/3.2.story.md

@@ -1,80 +0,0 @@
-# Story 3.2 — dist-templates per host (Claude Code starter roster)
-
-**StoryId:** `3.2`
-**Epic:** `epic-multi-host-installer` (v1.1)
-**Status:** InReview
-**Severity:** P1 (blocks 3.3 per-host install logic)
-**Cluster:** install-flow
-**Depends on:** Story 3.1 (host enum + validator)
-
-## Description
-
-Story 3.1 gave OpenLife a validated `Host` type at the CLI boundary, but `openlife system setup --host claude-code` had nothing to install. We need the actual artifacts — agent files, slash commands, MCP manifest — bundled in the npm package so install is offline and atomic.
-
-This story ships the **Claude Code** templates only. gemini-cli and codex follow in Story 3.3 once each host's installation format is investigated and verified.
-
-## Acceptance Criteria
-
-- [x] **Directory layout** `dist-templates/claude-code/{agents,commands/openlife,mcp}` exists in the repo
-- [x] **5 starter agents** in Claude Code subagent format (YAML frontmatter + system prompt body):
-  - `openlife-maestro` — meta-orchestrator (routes to specialists via `Task` tool)
-  - `openlife-lyra` — research synthesis + narrative writing
-  - `openlife-forge` — artifact creation (agents, skills, slash commands, MCP)
-  - `openlife-atlas` — codebase mapping + architectural analysis
-  - `openlife-genesis` — new-project bootstrap + install/scaffold
-- [x] **4 starter slash commands** under `commands/openlife/`:
-  - `/openlife:status`, `/openlife:ask`, `/openlife:doctor`, `/openlife:dream`
-- [x] **MCP manifest** `mcp/openlife-orchestrator.json` with 7 tool declarations (server impl deferred to Story 3.3)
-- [x] **README** `dist-templates/README.md` documenting layout, format, and how to add new agents
-- [x] `package.json` `files` array includes `dist-templates/` (so npm publishes it)
-- [x] **Regression test** `src/test_dist_templates_layout.ts` — 5 test groups: layout, agents parse, slash commands parse, MCP valid JSON, package.json correctness
-- [x] Test wired into `test:all`; suite 64 → 65 verde
-
-## Dev Notes
-
-- **Why 5 agents, not 21?** User chose "Pulled from 21 vault agents (MAESTRO/LYRA/etc.)" approach. Starter set is the 5 with clearest non-overlapping ownership: MAESTRO (routing), LYRA (synthesis), FORGE (creation), ATLAS (analysis), GENESIS (bootstrap). Remaining 16 are scheduled for v1.1+ stories once each role has a verified `.catalog/agents/` runtime counterpart.
-- **Why Claude Code format only?** User chose "Claude Code primeiro (Recomendado)" — Claude Code's subagent spec is well-documented and the most mature host. gemini-cli/codex defer to Story 3.3 to investigate their respective formats.
-- **Why is the MCP server stubbed?** The manifest ships so install is atomic (single host-add operation copies all artifacts), but `bin/openlife-mcp.js` doesn't exist yet. Story 3.3 wires up the actual MCP server. Until then, the manifest is informational — installing it into `~/.claude.json` is harmless.
-- **dist-templates vs .catalog/.** Two different audiences:
-  - `.catalog/agents/` = OpenLife **runtime** catalog (rich YAML, loaded by `AgentRegistry`)
-  - `dist-templates/claude-code/agents/` = what gets **installed into the host CLI** (lean Claude Code subagent format)
-  - Same logical agent can appear in both with different formats.
-- **Lean prompt size.** Each agent file is ~50-80 lines including frontmatter. Compare to legacy heavy-format runtime catalog entries (~330 lines). Claude Code agents work best with focused system prompts; verbose persona definitions are wasted context per invocation.
-
-## File List
-
-- `dist-templates/README.md` — NEW (layout + format docs)
-- `dist-templates/claude-code/agents/openlife-maestro.md` — NEW
-- `dist-templates/claude-code/agents/openlife-lyra.md` — NEW
-- `dist-templates/claude-code/agents/openlife-forge.md` — NEW
-- `dist-templates/claude-code/agents/openlife-atlas.md` — NEW
-- `dist-templates/claude-code/agents/openlife-genesis.md` — NEW
-- `dist-templates/claude-code/commands/openlife/status.md` — NEW
-- `dist-templates/claude-code/commands/openlife/ask.md` — NEW
-- `dist-templates/claude-code/commands/openlife/doctor.md` — NEW
-- `dist-templates/claude-code/commands/openlife/dream.md` — NEW
-- `dist-templates/claude-code/mcp/openlife-orchestrator.json` — NEW
-- `src/test_dist_templates_layout.ts` — NEW (5 test groups, 65th test in suite)
-- `package.json` — MODIFIED (added `dist-templates` to `files`; added `test:dist-templates-layout` script; appended to `test:all`)
-
-## Change Log
-
-- 2026-05-11 — @dev (Charlie) — Created dist-templates/ skeleton with 5 starter agents (MAESTRO/LYRA/FORGE/ATLAS/GENESIS) in Claude Code subagent format, 4 starter slash commands under `/openlife:*`, MCP manifest (server stubbed for 3.3), regression test, README. test:all 64 → 65 verde. Status: Ready → InReview.
-
-## IDS check
-
-**Decision:** CREATE (new distribution surface — no existing artifact installs templates into a host CLI). Format follows Claude Code's published subagent + slash command spec (REUSE of external pattern, not invented).
-
-## What unblocks for v1.1
-
-- Story 3.3 (per-host install logic) — has templates to copy
-- Story 3.4 (uninstall reversible) — has known artifact list to remove
-- Story 3.5 (install wizard interactive) — has roster to present to user
-- Story 3.6 (docs per host) — has agent/command surface to document
-
-## What this does NOT do
-
-- Implement the actual MCP server (`bin/openlife-mcp.js`) → Story 3.3
-- Ship gemini-cli or codex templates → Story 3.3
-- Wire `InstallFlow.run()` to actually copy these into the host → Story 3.3
-- Add the remaining 16 named agents (VEIN/FLUX/VECTOR/etc.) → spread across v1.1+ stories