@coresource/hz 0.21.3 → 0.21.5

package/README.md

@@ -0,0 +1,103 @@
+# hz
+
+`hz` is the **reactive local planner** for cloud launches. Planning happens in a continuous reactive loop that supports investigation, targeted clarification, native plan editing, and explicit finalization — all while keeping local state authoritative until the user approves.
+
+## Core commands
+
+### `hz plan`
+
+`hz plan "<task>" --repo <path>` starts or resumes a local planning session in a deterministic launch bucket:
+
+- **Fresh runs** enter the reactive planner loop, show live progress during turns, and create mutable planner state.
+- **Interrupted sessions** resume from the exact working state (open items, diagnostics, investigation findings) rather than regenerating approximations.
+- **Approval** is required to finalize: this produces `mission-draft.json`, `plan-history.json`, finalized `plannerPlan` (embedded inside `mission-draft.json`), and infrastructure artifacts.
+- **Superseding revisions** rotate history and clear stale downstream state before execution continues.
+
+### `hz mission run`
+
+`hz mission run "<task>" --repo <path>` uses the **same normalized request identity** as `hz plan`:
+
+- Resumes partial planning if no finalized draft exists.
+- Reuses finalized local drafts without replanning or mutating mission-draft/plan-history.
+- Continues into upload, mission creation, and monitoring after finalization.
+
+Both commands avoid retired `/plan/*` routes in the normal planning flow.
+
+## Local artifacts
+
+Planning state is stored under `~/.hz/cloud-launches/<request-id>/`:
+
+| Artifact | Purpose |
+|----------|---------|
+| `request.json` | Normalized request identity and launch bootstrap metadata |
+| `planner-state.json` | Mutable planner state: milestones, work items, assertions, dependencies, clarification items, diagnostics, investigation findings |
+| `mission-draft.json` | Finalized mission snapshot (created only on approval) |
+| `plan-history.json` | Finalized revision history and supersession lineage |
+| `infrastructure/` | Generated deployables, TDD skills, and idempotent init scripts |
+
+Resume, reuse, and supersession all hang off deterministic launch identity derived from normalized task text plus sorted, deduped absolute repo paths.
+
+## Auth and environment
+
+Planning uses the existing CLI auth surface:
+
+- `HZ_API_KEY`, or
+- `hz auth login` (stores auth in `~/.hz/config.json`)
+
+An explicitly empty `HZ_API_KEY` is treated as an error.
+
+## Optional remote sync (finalized-only)
+
+If both of these are set, `hz plan` will sync the finalized local plan after approval:
+
+- `HZ_STATE_STORE_URL`
+- `HZ_STATE_STORE_MISSION_ID` (target mission-scoped store identifier)
+
+Optional overrides:
+
+- `HZ_STATE_STORE_TOKEN` (otherwise `HZ_API_KEY` is reused)
+- `HZ_STATE_STORE_STEP_ID`
+- `HZ_STATE_STORE_WORKER_SESSION_ID`
+
+Rules:
+
+- Sync runs **only after** local finalization.
+- Sync uses mission-scoped `/missions/{missionId}/plan` routes with optimistic versioning.
+- Read-back is verified after PUT.
+- Retries are bounded.
+- Sync failures warn, but the local draft remains authoritative and retryable later.
+- Retired `/plan/*` routes are not used in normal flow.
+
+## Build and test
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+Built-binary sanity checks:
+
+```bash
+node dist/hz.mjs plan --help
+node dist/hz.mjs mission run --help
+```
+
+## Architecture invariants
+
+1. **Local state is authoritative until explicit finalization.**
+2. **Working state and finalized artifacts are separate surfaces** — downstream consumers only see finalized outputs.
+3. **Reactive editing preserves stable IDs** for unchanged entities across edits and superseding revisions.
+4. **Blocking diagnostics prevent finalization.**
+5. **Normal planning flow makes zero requests under `/plan/`.**
+6. **`hz plan` and `hz mission run` agree on request identity, resume, and reuse semantics.**
+7. **Remote sync is finalized-only** — the mission-planner store is a finalized snapshot + step-state store, not a live remote planner.
+
+## Notes for developers
+
+- Planner decisions and validation outcomes are persisted so interruptions are recoverable and inspectable.
+- Mutable planner state is distinct from bootstrap state (`request.json`) and finalized artifacts (`mission-draft.json`).
+- Review-only planner state (e.g., `planningReview`) is excluded from downstream mission payloads and remote sync.
+- Step-state sync uses version-aware rebasing when the same worker session spans superseding syncs.
+- The deployed mission-store verification path uses a dedicated mission ID; retired routes currently return 404/405 (functionally equivalent to the ideal 410 Gone contract).