hive-lite 0.1.0

package/README.md

@@ -0,0 +1,443 @@
+# Hive Lite
+
+Hive Lite is a local Project Map + Change Control CLI for coding agents.
+
+It deliberately starts small:
+
+- no server
+- no Dashboard
+- no Feature or Task objects
+- no agent runner
+- no embeddings
+- no SQLite
+
+The first loop is:
+
+```text
+intent -> hive-lite find -> Context Packet
+agent edits code outside Hive
+current diff -> hive-lite check -> Change Record
+validate -> accept -> optional Map Delta Candidate
+```
+
+## Commands
+
+For detailed CLI output meanings and "what to do next" tables, see [docs/cli-semantics.md](docs/cli-semantics.md).
+For a non-technical pilot-user workflow guide in Chinese, see [docs/user-pilot-guide.zh.md](docs/user-pilot-guide.zh.md).
+
+Examples below use `node bin/hive.js` from this repository. When installed as a package, use `hive-lite` instead.
+
+### Setup And Health
+
+Initialize Hive Lite in a git repo:
+
+```bash
+node bin/hive.js init
+```
+
+Creates durable map files under `.hive/map/` and runtime directories such as `.hive/context/` and `.hive/changes/`. This command requires an existing git repository.
+
+Check basic map file validity:
+
+```bash
+node bin/hive.js doctor
+node bin/hive.js map verify
+node bin/hive.js map verify --json
+```
+
+Inspect Project Map readiness for safe `find` / `check` behavior:
+
+```bash
+node bin/hive.js map health
+node bin/hive.js map health --area dashboard.action_inbox
+node bin/hive.js map health --json
+```
+
+### Current State And Next Action
+
+Inspect worktree state, latest Hive change, and recent split notes:
+
+```bash
+node bin/hive.js status
+node bin/hive.js status --json
+node bin/hive.js status --all --json
+```
+
+Ask Hive Lite what the operator should do next:
+
+```bash
+node bin/hive.js next
+node bin/hive.js next --json
+node bin/hive.js next --agent codex --json
+```
+
+`status` and `next` show actionable split notes by default: active split notes with accepted phase progress, or the newest unstarted split note when no active split exists. Use `status --all` to inspect every runtime split note. `next` may recommend start, finish, map maintenance, split continuation, dirty-worktree cleanup, or git repo setup. It does not run agents, commit, accept risk, or modify files.
+In JSON output, `splitNoteSummary.primaryRecentSplitNote` identifies the split note that `status`/`next` treat as primary, and `splitNoteSummary.otherActiveSplitNotes` lists older active split notes with accepted progress.
+
+When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`, `next` also checks whether the recommended Hive Lite operator skill is installed in that target. If it is missing or stale, `next` recommends installing/syncing skills before the handoff.
+
+### Install Agent Skills
+
+Hive Lite ships three operator skills:
+
+- `hive-lite-start-prompt`
+- `hive-lite-finish`
+- `hive-lite-map-maintainer`
+
+Check installed skill status:
+
+```bash
+node bin/hive.js skills doctor
+node bin/hive.js skills doctor --agent codex
+node bin/hive.js skills doctor --path ~/.codex/skills
+node bin/hive.js skills doctor --json
+```
+
+`skills doctor` does not detect which agent CLI is installed or currently running. It checks the selected skills directories: all known target paths by default, one or more paths with `--agent`, or a custom path with `--path`.
+
+Codex, Claude, and Gemini targets are global user-skill installs. `--agent codex` writes to `~/.codex/skills`, `--agent claude` writes to `~/.claude/skills`, and `--agent gemini` writes to `~/.gemini/skills`. They do not create or update repo-local `.codex/skills`, `.claude/skills`, or `.gemini/skills`. Use `--path <repo-local-skills-dir>` only when you intentionally want a custom repo-local copy that Hive Lite can inspect.
+
+Install missing skills:
+
+```bash
+node bin/hive.js skills install --agent codex
+node bin/hive.js skills install --agent claude
+node bin/hive.js skills install --agent gemini
+node bin/hive.js skills install --agent all
+```
+
+`install` creates missing skills but does not overwrite stale local copies unless `--force` is passed.
+
+Synchronize bundled skills over existing stale copies:
+
+```bash
+node bin/hive.js skills sync --agent codex
+node bin/hive.js skills sync --agent all
+```
+
+Use `--dry-run` to preview writes. Use `--path <skills-dir>` for a custom target.
+
+### Start A Requirement
+
+Generate a Context Packet from a user intent:
+
+```bash
+node bin/hive.js find "Dashboard Action Inbox content should align left" --explain
+node bin/hive.js find "Dashboard Action Inbox content should align left" --json
+node bin/hive.js find "Dashboard Action Inbox content should align left" --area dashboard.action_inbox
+node bin/hive.js find "Dashboard Action Inbox content should align left" --max-files 12
+```
+
+Possible modes:
+
+- `edit_context`: safe to hand the packet to a coding agent
+- `discovery_context`: useful for investigation, but not an edit permit
+- `needs_map`: Project Map does not support this intent yet
+- `needs_decomposition`: intent is too broad for one Context Packet / Change Record
+
+For decomposed work, continue a specific phase:
+
+```bash
+node bin/hive.js find "Update server API for Action Inbox hierarchy" --from-split split_xxx --phase phase_server_api --area server.action_inbox_api --json
+```
+
+When `--from-split` and `--phase` point to a recorded split phase, Hive Lite constrains routing to that phase's primary area. Generated split notes include `--area <primaryAreaId>` so copied commands stay narrowly scoped even if the original intent was broad.
+If the split note or phase cannot be found, Hive Lite does not treat the copied command as an edit permit. If `--area` disagrees with the recorded phase area, the recorded phase area wins and Hive Lite prints a warning.
+When Hive Lite is run from a source checkout with `node /path/to/bin/hive.js`, generated split notes render that Node command first and include `hive-lite` as a package-alias fallback when available.
+
+### Check And Validate A Change
+
+After a coding agent edits files, create or refresh a Change Record from the current diff:
+
+```bash
+node bin/hive.js check --context ctx_xxx
+node bin/hive.js check --context ctx_xxx --json
+node bin/hive.js check chg_xxx
+```
+
+Run the validation plan recorded on the Change Record:
+
+```bash
+node bin/hive.js validate chg_xxx
+node bin/hive.js validate chg_xxx --profile dashboard-build
+node bin/hive.js validate chg_xxx --cmd "npm test"
+```
+
+Record human/manual evidence:
+
+```bash
+node bin/hive.js validate chg_xxx \
+  --manual manual-verification \
+  --result passed \
+  --note "Opened the Dashboard and verified the Action Inbox layout."
+```
+
+Manual `--result` values are `passed`, `failed`, or `not_applicable`. Manual notes should say what was actually checked.
+
+### Accept A Change
+
+Accept after evidence is sufficient:
+
+```bash
+node bin/hive.js accept chg_xxx
+node bin/hive.js accept chg_xxx --commit -m "Left align Action Inbox content"
+```
+
+Accept with a human review reason when Hive Lite requires one:
+
+```bash
+node bin/hive.js accept chg_xxx --reviewed --reason "Reviewed internal behavior; automated validation passed."
+```
+
+Accept explicit risk only when the human knowingly accepts insufficient evidence:
+
+```bash
+node bin/hive.js accept chg_xxx --accept-risk --reason "No focused test exists yet; accepting low-risk isolated UI logic after review."
+```
+
+`blocked` changes cannot be accepted in the MVP.
+
+### Maintain The Project Map
+
+Generate a prompt for map bootstrap, refresh, or intent-triggered repair:
+
+```bash
+node bin/hive.js map health --area dashboard.action_inbox
+node bin/hive.js map prompt --focus "Dashboard Action Inbox" --from-find ctx_xxx
+node bin/hive.js map prompt --focus "Dashboard surfaces" --max-areas 8
+node bin/hive.js map prompt --from-find ctx_xxx --json
+```
+
+Inspect and apply durable map delta candidates produced by accepted changes:
+
+```bash
+node bin/hive.js map delta list
+node bin/hive.js map delta apply delta_xxx
+node bin/hive.js map delta reject delta_xxx --reason "One-off change; not durable map knowledge."
+```
+
+### Debug / Inspection
+
+Show a raw Change Record:
+
+```bash
+node bin/hive.js show-change chg_xxx
+node bin/hive.js show-change
+```
+
+Dump the loaded Project Map as JSON:
+
+```bash
+node bin/hive.js map-dump
+```
+
+## Local Data
+
+Hive Lite requires a git repository. If the current directory is not inside a git worktree, `status` and `next` will report `repo_setup_required`, and workflow commands such as `init`, `find`, `check`, `validate`, and `accept` stop. Hive Lite does not initialize git automatically; switch to the correct repo root or manually initialize git and create an initial commit first.
+
+Committed by default:
+
+```text
+.hive/config.yaml
+.hive/map/**
+```
+
+Ignored by default:
+
+```text
+.hive/context/**
+.hive/changes/**
+.hive/patches/**
+.hive/state/**
+```
+
+Do not blanket-ignore `.hive/`. If `.hive/map/*.yaml` is hidden by `.gitignore` or `.git/info/exclude`, map refreshes will not show up as normal git changes. Ignore only runtime evidence directories, not the durable Project Map.
+
+## Next Action
+
+`next` is a lightweight local state interpreter. It does not run an agent, change files, accept risk, commit, or manage a workflow. It reads git state plus Hive artifacts and suggests the next operator step:
+
+```bash
+node bin/hive.js next
+node bin/hive.js next --json
+```
+
+Typical `phaseGuess` values:
+
+- `preflight`: dirty worktree must be committed, stashed, isolated, or stopped before a new requirement
+- `finish`: an in-progress or accepted-uncommitted Hive change should be closed with `$hive-lite-finish`
+- `map`: Project Map needs bootstrap, refresh, or repair via `$hive-lite-map-maintainer`
+- `split_continue`: a recent split note has a ready remaining phase; continue through `$hive-lite-start-prompt`
+- `start`: safe to begin a new bounded requirement with `$hive-lite-start-prompt`
+
+This is the CLI layer that a future static report or companion UI should read first.
+
+## Core Objects
+
+### Worktree Boundary
+
+Hive Lite does not require a new branch for every requirement, but a new requirement should start from a clean working tree.
+
+Use `status` before generating a start prompt:
+
+```bash
+node bin/hive.js status
+node bin/hive.js status --json
+```
+
+It classifies the current repo as:
+
+- `clean`: safe to start a new `find`
+- `unmanaged_dirty`: dirty files are not tied to a Hive Change Record
+- `in_progress`: dirty files belong to an unfinished Hive Change Record
+- `accepted_uncommitted`: the latest Hive Change Record was accepted without a commit
+
+For non-clean states, commit, stash, or move to a separate git worktree before starting a new requirement. This keeps `check` tied to one clear dirty diff.
+
+### Project Map
+
+The durable context router under `.hive/map`.
+
+`map prompt` prints a copyable prompt for an external agent CLI. It does not call an LLM and does not write map files. Its job is to help draft 3-8 high-value areas from repo evidence, then a human reviews and edits `.hive/map/areas.yaml`.
+
+`map health` is a deterministic readiness check for the Project Map. It does not score the map or repair it. It checks whether areas have enough precise routing, writable scope, entrypoints, validation, verification policy, and boundaries for `find` to safely generate an `edit_context` and for `check` to explain evidence needs.
+
+```bash
+node bin/hive.js map health
+node bin/hive.js map health --area dashboard.action_inbox
+node bin/hive.js map health --json
+```
+
+When `find` reports a map gap, pass the generated context packet back into `map prompt`:
+
+```bash
+node bin/hive.js map prompt --from-find ctx_xxx
+```
+
+The prompt will include the intent, selected area, warnings, relevant files, scope quality, and current scope so an external agent can propose a narrow map repair.
+For `--from-find`, an editing-capable external agent is instructed to edit only `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, and `.hive/map/validation.yaml` directly, then summarize the map changes. If it cannot edit files, it should fall back to complete replacement YAML for the affected map files.
+
+Areas can use tiered scope:
+
+```yaml
+scope:
+  readable:
+    - apps/dashboard/src/**
+  writable_direct:
+    - apps/dashboard/src/components/ActionInbox.tsx
+  writable_conditional:
+    - pattern: apps/dashboard/src/stores/**
+      reason: only if grouping depends on store shape
+      requires_review: true
+  writable_broad_fallback:
+    - pattern: apps/dashboard/src/**
+      reason: fallback only
+      requires_review: true
+  forbidden:
+    - apps/dashboard/dist/**
+```
+
+`find` uses this to choose a packet mode: `edit_context`, `discovery_context`, `needs_map`, or `needs_decomposition`. `check` treats direct files as clean, while conditional or broad fallback matches require review.
+
+Areas should also give Hive Lite enough evidence-policy signal for the finish phase. Keep this small: roles and verification policy are not a code graph, they are just hints for whether a change is UI-visible, internal logic, CLI behavior, config, or unknown.
+
+Canonical entrypoint roles:
+
+```text
+page
+ui_component
+styles
+state_store
+grouping_logic
+data_transform
+api_contract
+schema_logic
+cli_behavior
+error_handling
+cache_logic
+config
+docs
+test
+unknown
+```
+
+Example:
+
+```yaml
+entrypoints:
+  - path: apps/dashboard/src/pages/InboxPage.vue
+    role: page
+    source: manual
+    confidence: high
+  - path: apps/dashboard/src/components/InboxItemCard.vue
+    role: ui_component
+    source: manual
+    confidence: high
+
+verification:
+  direct_manual_allowed: true
+  manual_profiles:
+    - manual-verification
+  focused_test_recommended_for_roles:
+    - grouping_logic
+    - data_transform
+    - error_handling
+  review_with_reason_allowed: true
+  risk_acceptance_allowed: false
+```
+
+Validation profiles can add lightweight metadata so `check` can describe what kind of evidence a command provides:
+
+```yaml
+profiles:
+  - id: dashboard-build
+    command: bun --cwd apps/dashboard build
+    evidence_type: build
+    covers_roles:
+      - page
+      - ui_component
+      - styles
+    safety: safe_auto
+```
+
+### Context Packet
+
+Generated by `find`. It tells an agent where to look, what it may edit, what not to touch, and how to validate.
+
+### Change Record
+
+Generated by `check`. It captures the working tree diff, scope result, validation state, evidence policy, deterministic risk, and next action.
+
+### Evidence Policy
+
+Hive Lite does not force every change to add tests. It asks whether evidence is sufficient for this change, or whether the human must record a reason.
+
+`check` adds an Evidence Policy section with verdicts such as:
+
+- `acceptable`: evidence is sufficient
+- `needs_validation`: required command validation has not run
+- `needs_manual_verification`: a directly verifiable change needs a manual evidence note
+- `needs_review_reason`: accept requires `--reviewed --reason "..."`
+- `evidence_insufficient`: add focused evidence when practical, or accept with an explicit reason/risk
+- `blocked`: scope violation, failed validation, or another blocker
+
+Manual evidence is recorded through `validate`:
+
+```bash
+node bin/hive.js validate chg_xxx \
+  --manual dashboard-action-inbox-visual \
+  --result passed \
+  --note "Opened Dashboard and confirmed the Action Inbox hierarchy."
+```
+
+For internal changes that are not directly manually verifiable, prefer focused automated evidence when practical. If a focused test is not worth the cost, accept with a reason:
+
+```bash
+node bin/hive.js accept chg_xxx \
+  --reviewed \
+  --reason "Reviewed grouping logic; typecheck passed and the change is isolated to direct writable files."
+```
+
+## MVP Cutline
+
+Hive Lite does not write code in MVP. It helps a coding agent start in the right place and helps a human decide whether the resulting diff is acceptable.

package/bin/hive.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+require('../src/cli').main(process.argv.slice(2)).catch((error) => {
+  console.error(`error: ${error.message}`);
+  process.exit(1);
+});