hive-lite 0.1.0 → 0.1.1

package/README.md

@@ -301,6 +301,7 @@ 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.
+An initialized repo with zero configured areas is `needs_mapping`, not `healthy`; it still needs `$hive-lite-map-maintainer` bootstrap work before real requirements can be routed safely.
 
 ```bash
 node bin/hive.js map health

package/docs/cli-semantics.md

@@ -352,6 +352,7 @@ node bin/hive.js map health --json
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `healthy` | No critical/warning findings. | Map can support edit-ready areas. |
+| `needs_mapping` | Map files are valid, but no areas are configured. | Bootstrap focused areas before starting requirements. |
 | `needs_attention` | Map has warnings. | Refresh or repair if relevant to the next requirement. |
 | `unsafe_for_edit_context` | Map has critical findings. | Repair map before relying on edit context. |
 | `invalid_map` | Map YAML/schema is missing or invalid. | Fix map files before using Hive Lite. |

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

@@ -30,18 +30,30 @@ hive-lite skills doctor --agent <codex|claude|gemini>
 hive-lite skills install --agent <codex|claude|gemini>
 ```
 
-## Boundaries
+## Authority Boundary
 
-- Only edit:
+This skill has lifecycle-scoped authority.
+
+Bootstrap / repair exception:
+
+- If Hive Lite is not initialized, partially initialized, or explicitly being initialized, this skill may run the approved bootstrap command, normally `hive-lite init`.
+- Preserve setup side effects produced by the bootstrap command, including `.hive/config.yaml`, `.hive/map/*.yaml`, Hive Lite runtime/evidence directories, and `.gitignore` entries for those runtime/evidence directories.
+- These bootstrap side effects are authorized setup artifacts. Do not delete, revert, or "clean up" them merely because they are outside `.hive/map/`.
+- Do not hand-edit setup files as ordinary map maintenance. If setup files are missing or inconsistent after bootstrap, report a setup/repair condition or rerun an approved bootstrap/repair command when the task allows it.
+
+Normal map-maintenance mode:
+
+- After Hive Lite is initialized, directly edit only:
   - `.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`.
+- You may read `.hive/config.yaml`, `.gitignore`, and runtime metadata as needed, but must not directly modify them during normal map maintenance.
+- Do not edit application source, tests, docs, generated artifacts, or non-map project files.
 - 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.
+- Durable setup and map changes require human awareness. Summarize setup effects separately from map edits 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
@@ -98,6 +110,7 @@ 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.
+Preserve all setup artifacts created by `hive-lite init`; do not remove `.hive/config.yaml` or Hive Lite `.gitignore` entries as part of cleanup.
 
 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.
 
@@ -106,7 +119,7 @@ If the target directory is not a git repo or Hive Lite init fails, stop and repo
 Run:
 
 ```bash
-hive-lite map verify
+hive-lite map verify --json
 ```
 
 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.
@@ -149,7 +162,7 @@ Read [repair-rules.md](references/repair-rules.md). Keep edits narrow:
 Always run:
 
 ```bash
-hive-lite map verify
+hive-lite map verify --json
 hive-lite map health --json
 ```
 
@@ -181,6 +194,10 @@ Map maintenance complete.
 Mode:
 - <bootstrap|refresh|intent_repair|continuous_delta|recovery>
 
+Hive Lite setup:
+- <initialized with hive-lite init / no setup changes / setup repair needed>
+- Setup artifacts preserved: <.hive/config.yaml, .gitignore runtime rules, runtime directories, or none>
+
 Changed map files:
 - <file or none>
 
@@ -188,7 +205,7 @@ Changed areas/profiles:
 - <area/profile id and concise change>
 
 Verification:
-- hive-lite map verify: <ok/fail>
+- hive-lite map verify --json: <ok/fail>
 - hive-lite map health: <healthy/needs_attention/...>
 - focused find rerun, if applicable: <edit_context/discovery_context/needs_map>
 

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

@@ -19,12 +19,12 @@ 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.
+Preserve setup artifacts created by `hive-lite init`, including `.hive/config.yaml`, Hive Lite runtime/evidence directories, and `.gitignore` runtime/evidence rules. 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.
+- `map verify --json` reports `ok`.
+- `map health --json` has no critical findings for the first useful areas.
 - A sample `find` can produce `edit_context`.
 
 ## refresh

package/docs/skills/hive-lite-start-prompt/SKILL.md

@@ -33,8 +33,9 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 ## Boundaries
 
-- Do not edit application source, tests, docs, `.gitignore`, generated artifacts, `.hive/context`, `.hive/changes`, or `.hive/deltas`.
+- Do not directly edit application source, tests, docs, `.gitignore`, generated artifacts, `.hive/context`, `.hive/changes`, or `.hive/deltas`.
 - Only edit these Project Map files when map repair is needed: `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, `.hive/map/validation.yaml`.
+- Bootstrap exception: when Hive Lite map files are missing, this skill may run `hive-lite init` and must preserve setup artifacts created by that command, including `.hive/config.yaml`, runtime/evidence directories, and Hive Lite `.gitignore` entries. Do not delete or revert those artifacts merely because they are outside `.hive/map/`.
 - Do not run `hive check`, `hive validate`, `hive accept`, commits, formatters, or app tests for the new requirement. Those belong after the coding agent changes code.
 - During preflight, you may help finish or isolate pre-existing work only after explicit user confirmation.
 - Never discard changes with destructive commands such as `git reset --hard`, `git checkout --`, or forced branch switches.
@@ -72,7 +73,7 @@ If `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, or
 hive-lite init
 ```
 
-Do this automatically; do not ask the user whether to initialize Hive Lite. Initialization is setup work, not the requested product change.
+Do this automatically; do not ask the user whether to initialize Hive Lite. Initialization is setup work, not the requested product change. Preserve all setup artifacts created by `hive-lite init`; do not remove `.hive/config.yaml` or Hive Lite `.gitignore` entries as cleanup.
 
 Run:
 
@@ -93,7 +94,7 @@ After any preflight action, rerun `hive-lite status --json`; continue only when
 Run:
 
 ```bash
-hive-lite map verify
+hive-lite map verify --json
 ```
 
 If YAML is invalid or required map files are missing, repair only `.hive/map/*.yaml` if the fix is obvious. Otherwise stop and report the blocker.
@@ -182,7 +183,7 @@ Repair principles:
 After each repair, run:
 
 ```bash
-hive-lite map verify
+hive-lite map verify --json
 hive-lite map health --area <area_id> --json
 hive-lite find "<findIntent>" --json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/src/cli.js

@@ -43,6 +43,14 @@ function parseArgs(args) {
   return { positional, flags };
 }
 
+function isHelpArg(arg) {
+  return arg === 'help' || arg === '--help' || arg === '-h';
+}
+
+function isHelpFlag(arg) {
+  return arg === '--help' || arg === '-h';
+}
+
 function printHelp() {
   console.log(`
 Hive Lite - local Project Map + Change Control
@@ -719,7 +727,12 @@ function printSkillsMutation(result) {
 
 async function main(argv) {
   const [command, subcommand, subsubcommand, ...rest] = argv;
-  if (!command || command === 'help' || command === '--help' || command === '-h') {
+  if (!command || isHelpArg(command)) {
+    printHelp();
+    return;
+  }
+
+  if (subcommand === 'help' || isHelpFlag(subcommand) || isHelpFlag(subsubcommand) || rest.some(isHelpFlag)) {
     printHelp();
     return;
   }

package/src/lib/health.js

@@ -877,6 +877,7 @@ function summarize(result, areas, findings) {
   };
   let status = 'healthy';
   if (result.invalidMap) status = 'invalid_map';
+  else if (result.emptyMap) status = 'needs_mapping';
   else if (counts.critical > 0) status = 'unsafe_for_edit_context';
   else if (counts.warnings > 0) status = 'needs_attention';
   return {
@@ -912,6 +913,16 @@ function evaluateMapHealth(root, options = {}) {
   }
 
   const allAreas = Array.isArray(areasDoc.areas) ? areasDoc.areas : [];
+  if (allAreas.length === 0) {
+    addFinding(findings, {
+      severity: 'critical',
+      code: 'NO_AREAS_CONFIGURED',
+      field: 'areas',
+      message: 'Project Map has no areas configured.',
+      impact: 'Hive Lite cannot safely route requirements until at least one focused area is mapped.',
+      fix: 'Use hive-lite-map-maintainer to bootstrap focused Project Map areas.',
+    });
+  }
   const selectedAreas = options.area ? allAreas.filter((area) => area.id === options.area) : allAreas;
   if (options.area && selectedAreas.length === 0) {
     addFinding(findings, {
@@ -951,7 +962,7 @@ function evaluateMapHealth(root, options = {}) {
     validateRisk(area, findings);
   }
 
-  const base = { invalidMap, findings };
+  const base = { invalidMap, emptyMap: allAreas.length === 0, findings };
   const summarized = summarize(base, selectedAreas, findings);
   const areas = selectedAreas.map((area) => {
     const areaFindings = findings.filter((finding) => finding.areaId === area.id);

package/src/lib/next.js

@@ -105,7 +105,7 @@ function mapMaintainerPrompt(mode) {
   if (mode === 'bootstrap') {
     return [
       '$hive-lite-map-maintainer',
-      '这个项目第一次使用 Hive Lite，请初始化并建立第一版 3-8 个高价值 areas。',
+      '这个项目第一次使用 Hive Lite，请初始化并建立第一版 3-8 个高价值 areas。保留 hive-lite init 创建的 setup 产物，例如 .hive/config.yaml 和 .gitignore runtime 规则；初始化后只直接编辑 .hive/map/*.yaml。',
     ].join('\n');
   }
   if (mode === 'delta') {