hive-lite 0.1.0

package/docs/skills/hive-lite-finish/references/safety.md

@@ -0,0 +1,95 @@
+# Safety Rules
+
+Use this reference before running any command that changes evidence, git state, or acceptance state.
+
+## Safe Agent Actions
+
+These can run without asking once the user has asked this skill to finish a change:
+
+```bash
+hive-lite status --json
+hive-lite check --context <ctx_id> --json
+hive-lite check <chg_id> --json
+```
+
+Reading `.hive/context/*.json`, `.hive/context/*.md`, `.hive/changes/*/change.json`, and validation logs is also safe.
+
+## Usually Safe Validation
+
+You may run `hive-lite validate <chg_id> --json` automatically when the configured command looks like a read-only build/check/test/typecheck/lint command.
+
+Examples usually safe:
+
+```text
+npm test
+npm run test
+npm run build
+npm run typecheck
+pnpm test
+bun run typecheck
+node scripts/*check*
+```
+
+Ask first if the command may be slow, needs services, or has side effects.
+
+## Ask First
+
+Always ask before running commands involving:
+
+```text
+commit
+stash
+worktree add
+accept
+accept-risk
+reviewed accept
+manual validation
+map delta apply
+```
+
+Manual validation is ask-first because the human must actually verify the product behavior.
+
+## Never Do Automatically
+
+Do not run these without explicit user request and confirmation:
+
+```text
+git reset
+git checkout --
+git clean
+rm -rf
+git push
+git merge
+deploy
+release
+kubectl
+terraform apply
+db migrate
+drop
+docker compose down
+```
+
+## Human-Only Decisions
+
+The human must decide:
+
+- manual UI/product verification passed or failed,
+- review reason,
+- accept-risk reason,
+- commit message,
+- whether to accept and commit,
+- whether to discard/stash/isolate dirty work.
+
+The skill may suggest wording, but the human must confirm it.
+
+## Hard Stops
+
+Stop immediately when Hive reports:
+
+- scope violation,
+- required validation failed,
+- blocked verdict,
+- changed files outside the intended context,
+- evidence policy says blocked.
+
+Do not continue to accept or commit from a hard stop.

package/docs/skills/hive-lite-finish/references/verdicts.md

@@ -0,0 +1,123 @@
+# Evidence Verdict Handling
+
+Use `evidencePolicy.verdict` from `hive-lite check --json` as the main finish-state driver.
+
+## acceptable
+
+Meaning: evidence is sufficient.
+
+Say:
+
+```text
+Evidence is sufficient:
+- scope is clean
+- required validation/manual evidence is satisfied
+```
+
+Then ask whether to accept and commit. Suggest a commit message, but wait for confirmation.
+
+## needs_validation
+
+Meaning: required automatic validation has not run.
+
+Action:
+
+1. Inspect `validation.plan`.
+2. Run safe validation automatically, or ask first if it looks risky.
+3. Rerun `hive-lite check <chg_id> --json`.
+
+Say:
+
+```text
+The change is not ready yet because automatic validation has not run.
+I can run the configured validation now.
+```
+
+## needs_manual_verification
+
+Meaning: this change is directly manually verifiable, but no manual evidence note has been recorded.
+
+Action:
+
+1. Ask the human to verify the product behavior.
+2. Give concrete checks.
+3. Wait for confirmation.
+4. Record manual evidence with `hive-lite validate --manual ...`.
+5. Rerun check.
+
+Do not say or imply that you personally verified the UI.
+
+Example prompt:
+
+```text
+Automatic validation passed. This is a UI behavior change, so I need your confirmation.
+
+Please open Dashboard and confirm:
+- the Action Inbox layout matches the requested hierarchy;
+- no obvious layout break is visible;
+- existing actions/status labels remain visible.
+
+Reply "passed" with any note, or describe what failed.
+```
+
+If the human describes a failure, do not accept. Failed manual evidence is optional, not the default. Usually the best next step is to give the coding agent a bounded repair prompt using the same Context Packet and the human's failure observation, then rerun `hive-lite check --context <ctx_id>` after edits.
+
+## needs_review_reason
+
+Meaning: Hive needs a human review reason before accepting. This often happens for review-gated scope, unknown verification policy, or internal behavior without focused evidence.
+
+Action:
+
+1. Explain why a reason is needed.
+2. Offer to draft a reason.
+3. Wait for human approval.
+4. Accept only after approval.
+
+Example:
+
+```text
+Hive needs a review reason because this touched review-gated scope.
+Suggested reason:
+"Reviewed the changed file; it is limited to the intended Action Inbox layout and validation passed."
+
+Do you approve this reason for accept?
+```
+
+## evidence_insufficient
+
+Meaning: evidence is not strong enough for normal accept.
+
+Action:
+
+Offer options:
+
+```text
+1. Ask the coding agent to add focused automated verification.
+2. Accept with a reviewed reason if the human believes evidence is sufficient.
+3. Accept risk if the human knowingly accepts insufficient evidence.
+4. Stop.
+```
+
+Prefer focused verification when practical. Do not force tests for low-value process compliance.
+
+## blocked
+
+Meaning: do not accept.
+
+Common reasons:
+
+- scope violation,
+- validation failed,
+- validation/CI weakened,
+- high-risk blocker.
+
+Action:
+
+Stop and explain blockers. Do not validate further unless it helps debugging, and do not accept/commit.
+
+Say:
+
+```text
+This change is blocked and cannot be accepted.
+Next options are to send it back to the coding agent, fix the map/scope if the map is wrong, or stop.
+```

package/docs/skills/hive-lite-map-maintainer/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: hive-lite-map-maintainer
+description: Use this skill when maintaining a Hive Lite Project Map instead of implementing product code. It handles first-time map bootstrap, existing-map refresh after drift, intent-triggered map repair from find/context gaps, map health cleanup, and map delta review/apply workflows while editing only `.hive/map/*.yaml`.
+---
+
+# Hive Lite Map Maintainer
+
+## Purpose
+
+Maintain `.hive/map/*.yaml` so Hive Lite can produce high-quality Context Packets and Evidence Policy decisions.
+
+This skill is for map work only. It may inspect the repo and edit Project Map YAML, but it must not implement product/application changes.
+
+## References
+
+- Read [lifecycle.md](references/lifecycle.md) to choose the right map maintenance mode.
+- Read [repair-rules.md](references/repair-rules.md) before editing Project Map YAML.
+
+## Skill Handoffs
+
+Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-finish` automatically. When map maintenance is complete, output the next skill prompt the user should run, then stop.
+
+- For coding work after map repair: output a `$hive-lite-start-prompt` handoff.
+- For finishing a code change: do not continue here; use `$hive-lite-finish`.
+
+If the target handoff skill is unavailable in the active agent CLI, tell the user to install or sync Hive Lite skills for their agent first. Hive Lite cannot detect the running agent by itself; use the user's agent target such as `codex`, `claude`, or `gemini`:
+
+```bash
+hive-lite skills doctor --agent <codex|claude|gemini>
+hive-lite skills install --agent <codex|claude|gemini>
+```
+
+## Boundaries
+
+- Only edit:
+  - `.hive/map/project.yaml`
+  - `.hive/map/areas.yaml`
+  - `.hive/map/rules.yaml`
+  - `.hive/map/validation.yaml`
+- Do not edit application source, tests, docs, generated artifacts, `.hive/context`, `.hive/changes`, or `.hive/deltas`.
+- Do not run `hive check`, `hive validate`, `hive accept`, app formatters, app tests, commits, pushes, merges, deploys, or destructive git commands.
+- Do not call an LLM API from Hive Lite. Use Hive Lite CLI facts plus repo inspection.
+- Do not turn the map into a wiki. Only add information that improves `find` or `check`.
+- Durable map changes require human awareness. If you changed map files, summarize exactly what changed and tell the user to run/approve commit separately.
+- Apply Map Delta Candidates only when the user explicitly asked for or confirmed that action. Otherwise list/summarize them and stop.
+
+## Find The CLI
+
+Run Hive Lite from the target repo root. Prefer the package command:
+
+```bash
+hive-lite <args>
+```
+
+If `hive-lite` is not available, try an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. If it is still unclear, ask for the Hive Lite CLI path.
+
+In examples below, replace `hive-lite` with the resolved command.
+
+## Workflow
+
+### 0. Git Precondition
+
+Run:
+
+```bash
+hive-lite status --json
+```
+
+If it reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init`, do not create `.hive/map`, and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
+
+### 1. Establish Mode
+
+Read [lifecycle.md](references/lifecycle.md), then classify the task as one of:
+
+- `bootstrap`: old/existing project is using Hive Lite for the first time.
+- `refresh`: `.hive/map/*.yaml` exists but may be stale after architecture or repo changes.
+- `intent_repair`: `find` or a start-prompt flow produced `needs_map`, `discovery_context`, broad scope, missing entrypoints, missing validation, or weak evidence policy.
+- `continuous_delta`: accepted Hive Lite changes produced Map Delta Candidates.
+- `recovery`: map files are missing, invalid YAML, or structurally broken.
+
+If the user provided a specific requirement, context id, or find output, prefer `intent_repair`.
+
+### 2. Ensure Map Exists
+
+Before any mode-specific work, check whether the target repo has the required Hive Lite map files:
+
+```text
+.hive/map/project.yaml
+.hive/map/areas.yaml
+.hive/map/rules.yaml
+.hive/map/validation.yaml
+```
+
+If any required map file is missing, run:
+
+```bash
+hive-lite init
+```
+
+This is setup work. Do it automatically; do not ask the user whether to initialize Hive Lite. Then continue with bootstrap or recovery.
+
+If the target directory is not a git repo or Hive Lite init fails, stop and report the blocker instead of inventing map files manually.
+
+### 3. Verify Current Map
+
+Run:
+
+```bash
+hive-lite map verify
+```
+
+If YAML is invalid, fix only `.hive/map/*.yaml` if the repair is obvious. If not obvious, stop with the exact file and parser error.
+
+### 4. Gather Facts
+
+Use the minimal facts needed for the selected mode:
+
+```bash
+hive-lite map health --json
+hive-lite map health --area <area_id> --json
+hive-lite map prompt --focus "<topic>" --max-areas 8
+hive-lite map prompt --from-find <ctx_id>
+hive-lite map delta list
+```
+
+Also inspect repo evidence with deterministic commands such as:
+
+```bash
+rg --files
+rg "<term>"
+```
+
+Do not infer paths or validation commands without checking files or scripts.
+
+### 5. Edit The Map
+
+Read [repair-rules.md](references/repair-rules.md). Keep edits narrow:
+
+- Add or repair focused product/work areas.
+- Replace generic one-part areas with dot-separated area ids when needed.
+- Add exact `scope.writable_direct` files.
+- Move broad patterns to `scope.writable_broad_fallback` with `requires_review: true`.
+- Add entrypoint `role`, `source`, and `confidence`.
+- Add minimal `verification` policy for finish-phase Evidence Policy.
+- Add validation metadata only from confirmed scripts or explicit manual profiles.
+
+### 6. Verify The Repair
+
+Always run:
+
+```bash
+hive-lite map verify
+hive-lite map health --json
+```
+
+For focused repairs, also run:
+
+```bash
+hive-lite map health --area <area_id> --json
+```
+
+For intent-triggered repairs, rerun the original find:
+
+```bash
+hive-lite find "<findIntent>" --json
+```
+
+The repair is successful when:
+
+- `map verify` is ok.
+- The affected area has no critical health findings.
+- Intent-triggered repair now produces `edit_context`, narrow direct writable files, configured validation, and no map-gap warnings.
+
+### 7. Return A Map Maintenance Summary
+
+Return:
+
+```text
+Map maintenance complete.
+
+Mode:
+- <bootstrap|refresh|intent_repair|continuous_delta|recovery>
+
+Changed map files:
+- <file or none>
+
+Changed areas/profiles:
+- <area/profile id and concise change>
+
+Verification:
+- hive-lite map verify: <ok/fail>
+- hive-lite map health: <healthy/needs_attention/...>
+- focused find rerun, if applicable: <edit_context/discovery_context/needs_map>
+
+Remaining TODO:
+- <uncertain path/profile/risk item or none>
+
+Next:
+- For coding work: run `$hive-lite-start-prompt` again with the original requirement or context.
+- For changed map files: commit them separately before starting a new requirement.
+```
+
+Do not include a coding agent prompt. This skill only maintains the Project Map.

package/docs/skills/hive-lite-map-maintainer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hive Lite Map Maintainer"
+  short_description: "Maintain Hive Lite Project Maps"
+  default_prompt: "Use $hive-lite-map-maintainer to refresh or repair the Hive Lite Project Map without changing product code."
+
+policy:
+  allow_implicit_invocation: true

package/docs/skills/hive-lite-map-maintainer/references/lifecycle.md

@@ -0,0 +1,114 @@
+# Hive Lite Map Lifecycle
+
+Choose one mode before editing the map.
+
+## bootstrap
+
+Use when an existing project is adopting Hive Lite for the first time.
+
+Goal:
+
+- Create the first 3-8 high-value product/work areas.
+- Make `find` and `check` usable quickly.
+- Do not map the whole project.
+
+Suggested flow:
+
+```bash
+hive-lite init
+hive-lite map prompt --focus "highest value product and workflow areas" --max-areas 8
+```
+
+Then inspect repo files and edit `.hive/map/*.yaml` directly.
+
+Success:
+
+- `map verify` passes.
+- `map health` has no critical findings for the first useful areas.
+- A sample `find` can produce `edit_context`.
+
+## refresh
+
+Use when `.hive/map/*.yaml` already exists but may be stale because architecture, paths, scripts, or validation changed outside normal Hive Lite maintenance.
+
+Goal:
+
+- Preserve existing useful areas.
+- Repair stale paths, missing roles, broad writable scopes, missing validation metadata, and weak verification policy.
+- Do not redesign the whole map unless it is structurally wrong.
+
+Suggested flow:
+
+```bash
+hive-lite map health --json
+hive-lite map health --area <area_id> --json
+```
+
+Prioritize critical findings, then warnings that affect `find` or `check`.
+
+## intent_repair
+
+Use when a real requirement hits a map gap during start:
+
+- `find.mode` is `needs_map` or `discovery_context`.
+- `find` selected a generic/broad area.
+- warnings include `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
+- `map health --area <selected>` shows critical findings.
+
+Goal:
+
+- Repair only the area needed for this intent.
+- Rerun `find` until it produces an edit-ready Context Packet.
+- Do not implement the product requirement.
+
+Suggested flow:
+
+```bash
+hive-lite map prompt --from-find <ctx_id>
+hive-lite map verify
+hive-lite map health --area <area_id> --json
+hive-lite find "<findIntent>" --json
+```
+
+Success:
+
+- rerun `find` returns `mode: edit_context`.
+- direct writable scope is narrow.
+- validation plan exists.
+- review-gated scope is present only as conditional/fallback boundary.
+
+## continuous_delta
+
+Use when accepted Hive Lite changes produce Map Delta Candidates.
+
+Goal:
+
+- Review durable lessons from real accepted changes.
+- Apply only map deltas that improve future `find/check`.
+
+Suggested flow:
+
+```bash
+hive-lite map delta list
+hive-lite map delta apply <delta_id>
+```
+
+Only apply a delta when the user explicitly asks or confirms. Reject stale or low-value deltas if the CLI supports it.
+
+## recovery
+
+Use when map files are missing, invalid YAML, or structurally broken.
+
+Goal:
+
+- Restore valid Project Map files.
+- Avoid broad semantic rewrites.
+
+Suggested flow:
+
+```bash
+hive-lite init
+hive-lite map verify
+```
+
+If invalid YAML cannot be repaired safely, stop and report the exact error.