hive-lite 0.1.1 → 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

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`. |

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
@@ -32,18 +32,15 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 ## Authority Boundary
 
-This skill has lifecycle-scoped authority.
+Setup precondition:
 
-Bootstrap / repair exception:
+- 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`.
 
-- 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.
+Map-maintenance authority:
 
-Normal map-maintenance mode:
-
-- After Hive Lite is initialized, directly edit only:
+- Directly edit only:
   - `.hive/map/project.yaml`
   - `.hive/map/areas.yaml`
   - `.hive/map/rules.yaml`
@@ -53,7 +50,7 @@ Normal map-maintenance mode:
 - 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 setup and map changes require human awareness. Summarize setup effects separately from map edits 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
@@ -80,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:
@@ -103,16 +125,7 @@ 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.
-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.
+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
 
@@ -195,8 +208,8 @@ 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>
+- initialized: yes
+- setup changes made by this skill: none
 
 Changed map files:
 - <file or none>

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,11 +20,10 @@ Goal:
 Suggested flow:
 
 ```bash
-hive-lite init
 hive-lite map prompt --focus "highest value product and workflow areas" --max-areas 8
 ```
 
-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.
+Inspect repo files and edit `.hive/map/*.yaml` directly.
 
 Success:
 
@@ -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

@@ -35,7 +35,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 - 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-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.
@@ -67,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. Preserve all setup artifacts created by `hive-lite init`; do not remove `.hive/config.yaml` or Hive Lite `.gitignore` entries as cleanup.
+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`.
 

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.1",
+  "version": "0.1.2",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

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');
@@ -51,11 +52,20 @@ 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]
@@ -87,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}`);
@@ -531,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:');
@@ -732,6 +757,11 @@ async function main(argv) {
     return;
   }
 
+  if (isVersionArg(command)) {
+    printVersion();
+    return;
+  }
+
   if (subcommand === 'help' || isHelpFlag(subcommand) || isHelpFlag(subsubcommand) || rest.some(isHelpFlag)) {
     printHelp();
     return;
@@ -795,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(),
@@ -808,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(), {
@@ -821,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) => {
@@ -837,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));
@@ -868,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));
@@ -876,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');
@@ -890,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/next.js

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