hive-lite 0.1.0 → 0.1.2

package/README.md

@@ -235,6 +235,8 @@ node bin/hive.js map-dump
 
 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.
 
+Inside a git repo, `status` and `next` report `hive_init_required` until the repo has been initialized with `hive-lite init`. Hive Lite skills should stop in this state and ask the human/operator to run init explicitly before start, finish, or map-maintenance workflows continue.
+
 Committed by default:
 
 ```text
@@ -264,6 +266,8 @@ node bin/hive.js next --json
 
 Typical `phaseGuess` values:
 
+- `repo_setup_required`: current directory is not inside a git repo
+- `hive_init_required`: run `hive-lite init` explicitly before using Hive Lite skills
 - `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`
@@ -287,6 +291,8 @@ node bin/hive.js status --json
 
 It classifies the current repo as:
 
+- `repo_setup_required`: not inside a git worktree
+- `hive_init_required`: git repo exists, but required Hive Lite setup files are missing
 - `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
@@ -301,6 +307,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

@@ -35,6 +35,7 @@ Human output explains the result. JSON output is a stable contract with fields s
 It reads:
 
 - git repo presence
+- Hive Lite initialization state
 - worktree state
 - latest Hive Change Record
 - Project Map health
@@ -51,6 +52,7 @@ Hive Lite cannot detect the currently running agent CLI. If the caller provides
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Current directory is not inside a git repo. | Stop. Switch to the correct repo root, or manually initialize git and create an initial commit before using Hive Lite. |
+| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Stop skill workflows. Run `hive-lite init` explicitly from the repo root, commit or preserve setup files, then rerun `next`. |
 | `skill_preflight` | The selected agent target is missing the operator skill needed for the next Hive Lite step. | Run the recommended `skills install` or `skills sync`, then rerun `next`. |
 | `preflight` | Worktree has unmanaged dirty changes. | Stop before starting new work. Commit, stash, use a separate worktree, or stop. |
 | `finish` | A Hive change is in progress, or was accepted without commit. | Use `$hive-lite-finish` to check, validate, record evidence, accept, or commit. |
@@ -101,6 +103,7 @@ node bin/hive.js status --json
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Not inside a git worktree. | Stop. Do not auto-run `git init`. |
+| `hive_init_required` | Inside a git worktree, but required Hive Lite setup files are missing. | Stop all skills. Run `hive-lite init` explicitly from the repo root. |
 | `clean` | Worktree is clean. | It is safe to start `find`. |
 | `unmanaged_dirty` | Dirty files are not tied to a Hive Change Record. | Stop and ask the human to commit, stash, use a worktree, or stop. |
 | `in_progress` | Dirty files belong to an unfinished Hive Change Record. | Continue finish flow: `check`, `validate`, manual evidence, or `accept`. |
@@ -352,6 +355,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-finish/SKILL.md

@@ -61,6 +61,8 @@ In command examples below, replace `hive-lite` with the resolved command.
 
 Run `hive-lite status --json` first. If it reports `hive.state = repo_setup_required`, stop immediately. Do not run check/validate/accept 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.
 
+If it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself, and do not run check/validate/accept. Tell the user to run `hive-lite init` from the repo root first. If they expected an existing Hive Lite change, they may be in the wrong directory.
+
 Find one of:
 
 - context id from the coding agent output, such as `ctx_xxx`,

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

@@ -1,6 +1,6 @@
 ---
 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`.
+description: Use this skill when maintaining a Hive Lite Project Map instead of implementing product code. It handles first map creation after explicit Hive Lite init, existing-map refresh after drift, intent-triggered map repair from find/context gaps, map health cleanup, and map delta review/apply workflows while directly editing only `.hive/map/*.yaml`.
 ---
 
 # Hive Lite Map Maintainer
@@ -30,18 +30,27 @@ hive-lite skills doctor --agent <codex|claude|gemini>
 hive-lite skills install --agent <codex|claude|gemini>
 ```
 
-## Boundaries
+## Authority Boundary
 
-- Only edit:
+Setup precondition:
+
+- This skill must not run `hive-lite init`.
+- If Hive Lite is not initialized or is partially initialized, stop immediately and tell the user to run `hive-lite init` from the target repo root, then rerun this skill.
+- Do not create `.hive/map` manually, do not edit `.hive/config.yaml`, and do not edit `.gitignore`.
+
+Map-maintenance authority:
+
+- 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 map changes require human awareness. Summarize 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
@@ -68,6 +77,31 @@ 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.
 
+If it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself. Tell the user:
+
+```text
+Hive Lite is not initialized in this repo yet.
+
+Please run this once from the repo root:
+  hive-lite init
+
+Then commit or otherwise preserve the setup files, and rerun:
+  $hive-lite-map-maintainer
+  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+```
+
+For older Hive Lite versions that do not report `hive.initialized`, check for required setup files before continuing:
+
+```text
+.hive/config.yaml
+.hive/map/project.yaml
+.hive/map/areas.yaml
+.hive/map/rules.yaml
+.hive/map/validation.yaml
+```
+
+If any are missing, stop with the same message. Do not run init automatically.
+
 ### 1. Establish Mode
 
 Read [lifecycle.md](references/lifecycle.md), then classify the task as one of:
@@ -91,22 +125,14 @@ Before any mode-specific work, check whether the target repo has the required Hi
 .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.
+If any required map file is missing, stop immediately and tell the user to run `hive-lite init` from the repo root. Do not create missing map files manually.
 
 ### 3. Verify Current Map
 
 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 +175,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 +207,10 @@ Map maintenance complete.
 Mode:
 - <bootstrap|refresh|intent_repair|continuous_delta|recovery>
 
+Hive Lite setup:
+- initialized: yes
+- setup changes made by this skill: none
+
 Changed map files:
 - <file or none>
 
@@ -188,7 +218,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

@@ -6,6 +6,11 @@ Choose one mode before editing the map.
 
 Use when an existing project is adopting Hive Lite for the first time.
 
+Precondition:
+
+- `hive-lite init` has already been run explicitly by the user/operator.
+- If Hive Lite setup files are missing, stop and tell the user to run `hive-lite init`; do not run it from this skill.
+
 Goal:
 
 - Create the first 3-8 high-value product/work areas.
@@ -15,16 +20,15 @@ Goal:
 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.
+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
@@ -97,7 +101,7 @@ Only apply a delta when the user explicitly asks or confirms. Reject stale or lo
 
 ## recovery
 
-Use when map files are missing, invalid YAML, or structurally broken.
+Use when initialized map files are invalid YAML or structurally broken. If required Hive Lite setup or map files are missing, stop and tell the user to run `hive-lite init` from the repo root.
 
 Goal:
 
@@ -107,8 +111,7 @@ Goal:
 Suggested flow:
 
 ```bash
-hive-lite init
-hive-lite map verify
+hive-lite map verify --json
 ```
 
 If invalid YAML cannot be repaired safely, stop and report the exact error.

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`.
+- Do not run `hive-lite init`. If Hive Lite is not initialized or is partially initialized, stop and tell the user to run `hive-lite init` from the repo root before using this skill.
 - 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.
@@ -66,21 +67,38 @@ Read [input-calibration.md](references/input-calibration.md). Produce:
 
 ### 2. Preflight The Worktree
 
-If `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, or `.hive/map/validation.yaml` is missing, run:
+Run:
 
 ```bash
-hive-lite init
+hive-lite status --json
 ```
 
-Do this automatically; do not ask the user whether to initialize Hive Lite. Initialization is setup work, not the requested product change.
+If status reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init` 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.
 
-Run:
+If status reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself. Tell the user:
 
-```bash
-hive-lite status --json
+```text
+Hive Lite is not initialized in this repo yet.
+
+Please run this once from the repo root:
+  hive-lite init
+
+After the setup files are committed or otherwise preserved, rerun:
+  $hive-lite-map-maintainer
+  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
 ```
 
-If status reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init` 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.
+For older Hive Lite versions that do not report `hive.initialized`, check whether these files exist before continuing:
+
+```text
+.hive/config.yaml
+.hive/map/project.yaml
+.hive/map/areas.yaml
+.hive/map/rules.yaml
+.hive/map/validation.yaml
+```
+
+If any are missing, stop with the same message. Do not run init automatically and do not create missing map files manually.
 
 If the command is unavailable in an older Hive Lite, fall back to `git status --porcelain`.
 
@@ -93,7 +111,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 +200,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/docs/skills/hive-lite-start-prompt/references/preflight.md

@@ -4,23 +4,24 @@ Use this reference when `hive-lite status --json` is not clean.
 
 The goal is to protect the Change Record boundary. A new Hive Lite requirement must start from a clean worktree.
 
-## After Automatic Init
+## Hive Lite Not Initialized
 
-If the worktree is dirty only because this skill just ran `hive-lite init`, explain that Hive Lite was initialized automatically and stop before starting the product requirement.
+If `hive-lite status --json` reports `hive.state = hive_init_required` or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` from this skill.
 
-Present options:
+Say:
 
 ```text
-Hive Lite has been initialized for this repo. The setup files need a git boundary before a product requirement can start.
+Hive Lite is not initialized in this repo yet.
 
-Options:
-1. Commit the Hive Lite setup files.
-2. Stash the setup files.
-3. Create a separate git worktree for the product requirement.
-4. Stop.
+Please run this once from the repo root:
+  hive-lite init
+
+After the setup files are committed or otherwise preserved, rerun:
+  $hive-lite-map-maintainer
+  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
 ```
 
-Do not ask whether to run init; init has already been performed. Do ask before committing, stashing, or creating a worktree.
+Do not continue to find/map repair/start prompt until Hive Lite setup exists.
 
 ## States
 
@@ -107,6 +108,7 @@ hive-lite accept <chg_id> --commit -m "<message>"
 ## Safety Rules
 
 - Do not continue to `find` while status is not clean.
+- Do not run `hive-lite init` from a skill.
 - Do not initialize git automatically.
 - Do not assume "new branch" cleans the worktree; dirty files usually follow branch switches.
 - Prefer commit, stash, or separate git worktree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",

package/src/cli.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const { version: packageVersion } = require('../package.json');
 const { requireGitRepo } = require('./lib/git');
 const { evaluateMapHealth } = require('./lib/health');
 const { createMapPrompt, initProject, loadProjectMap, suggestMap, verifyProjectMap } = require('./lib/map');
@@ -43,11 +44,28 @@ 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 isVersionArg(arg) {
+  return arg === 'version' || arg === '--version' || arg === '-v';
+}
+
+function printVersion() {
+  console.log(packageVersion);
+}
+
 function printHelp() {
   console.log(`
 Hive Lite - local Project Map + Change Control
 
 Usage:
+  hive-lite version
   hive-lite init
   hive-lite doctor
   hive-lite status [--json] [--all]
@@ -79,6 +97,16 @@ function currentCliCommandArgv() {
   return [process.execPath, path.resolve(process.argv[1])];
 }
 
+function requireHiveInitialized(cwd, commandName) {
+  const status = evaluateWorkspaceStatus(cwd);
+  if (status.hive.initialized === false) {
+    const missing = status.hive.missingSetupFiles && status.hive.missingSetupFiles.length > 0
+      ? ` Missing: ${status.hive.missingSetupFiles.join(', ')}.`
+      : '';
+    throw new Error(`${commandName} requires Hive Lite initialization. Run hive-lite init from the repo root first.${missing}`);
+  }
+}
+
 function printInit(result) {
   console.log('Hive Lite initialized.');
   console.log(`Repo: ${result.root}`);
@@ -523,6 +551,11 @@ function printWorkspaceStatus(result) {
   console.log(`Hive State: ${result.hive.state}`);
   console.log(`Can Start New Requirement: ${result.canStartNewRequirement ? 'yes' : 'no'}`);
   console.log(`Reason: ${result.hive.reason}`);
+  if (result.hive.initialized === false && result.hive.missingSetupFiles && result.hive.missingSetupFiles.length > 0) {
+    console.log('');
+    console.log('Missing Hive Lite Setup Files:');
+    for (const file of result.hive.missingSetupFiles) console.log(`  - ${file}`);
+  }
   if (result.hive.latestChange) {
     console.log('');
     console.log('Latest Change:');
@@ -719,7 +752,17 @@ 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 (isVersionArg(command)) {
+    printVersion();
+    return;
+  }
+
+  if (subcommand === 'help' || isHelpFlag(subcommand) || isHelpFlag(subsubcommand) || rest.some(isHelpFlag)) {
     printHelp();
     return;
   }
@@ -782,6 +825,7 @@ async function main(argv) {
     const intent = parsed.positional.join(' ').trim();
     if (!intent) throw new Error('find requires an intent string');
     const root = requireGitRepo(process.cwd(), 'hive-lite find');
+    requireHiveInitialized(root, 'hive-lite find');
     const result = createContextPacket(root, intent, {
       ...parsed.flags,
       cliCommandArgv: currentCliCommandArgv(),
@@ -795,7 +839,8 @@ async function main(argv) {
   }
 
   if (command === 'check') {
-    requireGitRepo(process.cwd(), 'hive-lite check');
+    const root = requireGitRepo(process.cwd(), 'hive-lite check');
+    requireHiveInitialized(root, 'hive-lite check');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     const changeId = parsed.positional[0] || null;
     const result = createOrUpdateChange(process.cwd(), {
@@ -808,7 +853,8 @@ async function main(argv) {
   }
 
   if (command === 'validate') {
-    requireGitRepo(process.cwd(), 'hive-lite validate');
+    const root = requireGitRepo(process.cwd(), 'hive-lite validate');
+    requireHiveInitialized(root, 'hive-lite validate');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     if (!parsed.flags.json && !parsed.flags.manual) {
       parsed.flags.onStart = (item) => {
@@ -824,7 +870,8 @@ async function main(argv) {
   }
 
   if (command === 'accept') {
-    requireGitRepo(process.cwd(), 'hive-lite accept');
+    const root = requireGitRepo(process.cwd(), 'hive-lite accept');
+    requireHiveInitialized(root, 'hive-lite accept');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     const result = acceptChange(process.cwd(), parsed.positional[0] || null, parsed.flags);
     if (parsed.flags.json) console.log(JSON.stringify(result, null, 2));
@@ -855,6 +902,7 @@ async function main(argv) {
       return;
     }
     if (subcommand === 'prompt') {
+      requireHiveInitialized(root, 'hive-lite map prompt');
       const parsed = parseArgs([subsubcommand, ...rest].filter((item) => item !== undefined));
       const result = createMapPrompt(root, parsed.flags);
       if (parsed.flags.json) console.log(JSON.stringify(result, null, 2));
@@ -863,10 +911,12 @@ async function main(argv) {
     }
     if (subcommand === 'delta') {
       if (subsubcommand === 'list') {
+        requireHiveInitialized(root, 'hive-lite map delta list');
         printDeltas(allDeltas(root));
         return;
       }
       if (subsubcommand === 'apply') {
+        requireHiveInitialized(root, 'hive-lite map delta apply');
         const parsed = parseArgs(rest);
         const id = parsed.positional[0];
         if (!id) throw new Error('map delta apply requires a delta id');
@@ -877,6 +927,7 @@ async function main(argv) {
         return;
       }
       if (subsubcommand === 'reject') {
+        requireHiveInitialized(root, 'hive-lite map delta reject');
         const parsed = parseArgs(rest);
         const id = parsed.positional[0];
         if (!id) throw new Error('map delta reject requires a delta id');

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。请建立第一版 Project Map，不要改应用代码。',
     ].join('\n');
   }
   if (mode === 'delta') {
@@ -177,11 +177,13 @@ function evaluateNextAction(cwd, options = {}) {
   const root = repoRoot(cwd);
   const workspace = evaluateWorkspaceStatus(root);
   const repoSetupRequired = workspace.hive.state === 'repo_setup_required';
-  const mapHealth = repoSetupRequired
+  const hiveInitRequired = workspace.hive.state === 'hive_init_required';
+  const setupRequired = repoSetupRequired || hiveInitRequired;
+  const mapHealth = setupRequired
     ? { status: 'not_checked', critical: 0, warnings: 0, info: 0, areasChecked: 0, topFindings: [] }
     : mapHealthSummary(root);
-  const latestChange = repoSetupRequired ? null : latestChangeSummary(root);
-  const deltas = repoSetupRequired ? [] : pendingDeltas(root);
+  const latestChange = setupRequired ? null : latestChangeSummary(root);
+  const deltas = setupRequired ? [] : pendingDeltas(root);
   const warnings = [];
   const secondaryActions = [];
 
@@ -222,6 +224,16 @@ function evaluateNextAction(cwd, options = {}) {
     });
     summaryForHuman = '当前目录不是 git repo。Hive Lite 不能安全开始；请切到正确的 repo 根目录，或你自己先完成 git 初始化和初始提交。';
     summaryForAgent = 'No git repository detected. Stop. Do not run find/check/accept or initialize git automatically.';
+  } else if (workspace.hive.state === 'hive_init_required') {
+    phaseGuess = 'hive_init_required';
+    primaryAction = action({
+      kind: 'run_hive_init',
+      label: 'Run hive-lite init',
+      command: 'hive-lite init',
+      explanation: 'This git repository has not been initialized for Hive Lite. Run init explicitly before using Hive Lite skills.',
+    });
+    summaryForHuman = '当前项目还没有初始化 Hive Lite。请先在项目根目录运行 hive-lite init，然后提交 setup/map 文件，再用 hive-lite-map-maintainer 建立 Project Map。';
+    summaryForAgent = 'Hive Lite is not initialized. Stop all skill workflows and tell the human to run hive-lite init first.';
   } else if (!workspace.canStartNewRequirement) {
     if (workspace.hive.state === 'in_progress') {
       phaseGuess = 'finish';

package/src/lib/status.js

@@ -6,6 +6,14 @@ const { latestChangeId, loadChange } = require('./change');
 const { exists, readJson } = require('./fsx');
 const { hiveDir } = require('./map');
 
+const REQUIRED_HIVE_SETUP_FILES = [
+  '.hive/config.yaml',
+  '.hive/map/project.yaml',
+  '.hive/map/areas.yaml',
+  '.hive/map/rules.yaml',
+  '.hive/map/validation.yaml',
+];
+
 function sha256(value) {
   return createHash('sha256').update(value || '').digest('hex');
 }
@@ -204,6 +212,10 @@ function action(kind, label, command, description) {
   return { kind, label, command, description };
 }
 
+function missingHiveSetupFiles(root) {
+  return REQUIRED_HIVE_SETUP_FILES.filter((file) => !exists(path.join(root, file)));
+}
+
 function actionsFor(state, latestId, diffMatches) {
   if (state === 'repo_setup_required') {
     return [
@@ -212,6 +224,12 @@ function actionsFor(state, latestId, diffMatches) {
       action('manual_git_setup', 'Set up git manually', null, 'If this is a new project, review .gitignore, initialize git, and create an initial commit yourself before running Hive Lite.'),
     ];
   }
+  if (state === 'hive_init_required') {
+    return [
+      action('run_hive_init', 'Run Hive Lite init', 'hive-lite init', 'Initialize Hive Lite setup files before using Hive Lite skills.'),
+      action('stop', 'Stop', null, 'Do not run start, finish, or map-maintainer skills until Hive Lite has been initialized.'),
+    ];
+  }
   if (state === 'clean') {
     return [
       action('start_requirement', 'Start a Hive Lite requirement', 'hive-lite find "<intent>" --json', 'The worktree is clean enough to generate a new Context Packet.'),
@@ -281,6 +299,8 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
   const root = repoRoot(cwd);
   const files = changedFiles(root);
   const dirty = files.length > 0;
+  const missingSetupFiles = missingHiveSetupFiles(root);
+  const initialized = missingSetupFiles.length === 0;
   const currentDiff = dirty ? diffFromHead(root) : '';
   const currentDiffHash = dirty ? diffHash(currentDiff) : null;
   const latest = latestChange(root);
@@ -292,7 +312,10 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
     ? 'Working tree has dirty files that are not known to be an accepted or in-progress Hive change.'
     : 'Working tree is clean.';
 
-  if (dirty && latest.change) {
+  if (!initialized) {
+    state = 'hive_init_required';
+    reason = 'Hive Lite is not initialized in this git repository. Run hive-lite init before using Hive Lite skills.';
+  } else if (dirty && latest.change) {
     if (accepted(latest.change) && !committed(latest.change) && diffMatches) {
       state = 'accepted_uncommitted';
       reason = 'The dirty diff matches the latest accepted Hive change, but no commit was created.';
@@ -330,6 +353,8 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
     hive: {
       state,
       reason,
+      initialized,
+      missingSetupFiles,
       latestChange: latestSummary,
     },
     canStartNewRequirement: state === 'clean',