hive-lite 0.1.3 → 0.1.7

package/README.md

@@ -74,9 +74,9 @@ 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.
+When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`, `next` also checks whether the recommended Hive Lite operator skill is current in that target. If it is missing or stale, `next` recommends `skills sync` before the handoff.
 
-### Install Agent Skills
+### Sync Agent Skills
 
 Hive Lite ships four operator skills:
 
@@ -98,22 +98,22 @@ node bin/hive.js skills doctor --json
 
 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:
+Install or update skills in one step:
 
 ```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
+node bin/hive.js skills sync --agent codex
+node bin/hive.js skills sync --agent claude
+node bin/hive.js skills sync --agent gemini
+node bin/hive.js skills sync --agent all
 ```
 
-`install` creates missing skills but does not overwrite stale local copies unless `--force` is passed.
+`sync` installs missing skills and overwrites stale copies with the bundled version.
 
-Synchronize bundled skills over existing stale copies:
+`install` is still available for conservative installs that should not overwrite stale local copies unless `--force` is passed:
 
 ```bash
-node bin/hive.js skills sync --agent codex
-node bin/hive.js skills sync --agent all
+node bin/hive.js skills install --agent codex
+node bin/hive.js skills install --agent all
 ```
 
 Use `--dry-run` to preview writes. Use `--path <skills-dir>` for a custom target.
@@ -144,7 +144,7 @@ node bin/hive.js find "Update server API for Action Inbox hierarchy" --from-spli
 
 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.
+When Hive Lite is run from a source checkout, generated split notes may render the caller's current CLI invocation and include `hive-lite` as a package-alias fallback when available.
 
 ### Check And Validate A Change
 
@@ -236,7 +236,7 @@ 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` reports `hive_init_required` until the repo has been initialized with `hive-lite init`. `next` recommends `$hive-lite-bootstrap`, which is the first-time setup skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.
+Inside a git repo, `status` reports `hive_init_required` until required Hive Lite setup files exist. `status` and `next` recommend `$hive-lite-bootstrap`, which is the first-time setup and setup-repair skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.
 
 Committed by default:
 
@@ -268,7 +268,7 @@ node bin/hive.js next --json
 Typical `phaseGuess` values:
 
 - `repo_setup_required`: current directory is not inside a git repo
-- `hive_init_required`: use `$hive-lite-bootstrap` for first-time setup before product work
+- `hive_init_required`: use `$hive-lite-bootstrap` for first-time setup or setup repair before product work
 - `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`

package/docs/cli-semantics.md

@@ -45,15 +45,15 @@ It reads:
 By default, `status --json` and `next --json` filter split notes to reduce exploratory clutter. They show active unfinished split notes that already have accepted phase progress. If no active split exists, they show only the newest unstarted split note. `splitNoteSummary` reports how many split notes were hidden by this default policy. Use `status --all --json` to inspect every runtime split note.
 `splitNoteSummary.primaryRecentSplitNote` identifies the split note selected as primary from the visible notes. `splitNoteSummary.otherActiveSplitNotes` lists older active-progress split notes so an operator can tell whether additional historical split work exists.
 
-Hive Lite cannot detect the currently running agent CLI. If the caller provides `--agent <codex|claude|gemini|all>` or `--path <skills-dir>`, `next` treats the recommended Hive Lite operator skill as a precondition. When the selected target is missing that skill or has a stale copy, `phaseGuess` becomes `skill_preflight` and `primaryAction.kind` becomes `install_operator_skill`.
+Hive Lite cannot detect the currently running agent CLI. If the caller provides `--agent <codex|claude|gemini|all>` or `--path <skills-dir>`, `next` treats the recommended Hive Lite operator skill as a precondition. When the selected target is missing that skill or has a stale copy, `phaseGuess` becomes `skill_preflight` and `primaryAction.kind` becomes `sync_operator_skill`.
 
 ### `phaseGuess`
 
 | 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. | Use `$hive-lite-bootstrap` for first-time setup before product work. |
-| `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`. |
+| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Use `$hive-lite-bootstrap` for first-time setup or setup repair before product work. |
+| `skill_preflight` | The selected agent target is missing the operator skill needed for the next Hive Lite step, or has a stale copy. | Run the recommended `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. |
 | `map` | Project Map is missing, invalid, critical, or needs attention. | Use `$hive-lite-map-maintainer` to bootstrap, refresh, or repair the map. |
@@ -103,7 +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 ordinary start/finish/map-maintainer skills. Use `$hive-lite-bootstrap` for first-time setup, or run `hive-lite init` manually as the low-level fallback. |
+| `hive_init_required` | Inside a git worktree, but required Hive Lite setup files are missing. | Stop ordinary start/finish/map-maintainer skills. Use `$hive-lite-bootstrap` for first-time setup or setup repair. |
 | `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`. |
@@ -146,7 +146,7 @@ node bin/hive.js find "<phase.findIntent>" --from-split split_xxx --phase phase_
 `--from-split` + `--phase` constrains routing to the selected phase's primary area when the split note is available.
 If the split note or phase cannot be found, the result is not an edit permit and `phaseDependencyStatus.canStartNormally` is `false`.
 If `--area` disagrees with the recorded phase area, Hive Lite routes to the recorded phase area and reports a warning.
-Split-note markdown renders the current Hive Lite CLI invocation first, such as `node /path/to/bin/hive.js ...` when run from a source checkout, and includes `hive-lite ...` as a fallback for environments where the package alias is installed.
+Split-note markdown renders the current Hive Lite CLI invocation first when run from a source checkout, and includes `hive-lite ...` as a fallback for environments where the package alias is installed.
 
 ## `skills`
 
@@ -186,8 +186,8 @@ node bin/hive.js skills doctor --path ~/.codex/skills --json
 | Status | Meaning | What To Do |
 | --- | --- | --- |
 | `current` | Installed copy matches bundled copy. | Nothing needed. |
-| `missing` | Skill is not installed at the target path. | Run `skills install`. |
-| `stale` | Skill exists but differs from the bundled copy. | Run `skills sync` or `skills install --force` if you want to overwrite. |
+| `missing` | Skill is not installed at the target path. | Run `skills sync`. |
+| `stale` | Skill exists but differs from the bundled copy. | Run `skills sync`. |
 
 Install missing skills:
 

package/docs/skills/hive-lite-bootstrap/SKILL.md

@@ -1,30 +1,31 @@
 ---
 name: hive-lite-bootstrap
-description: Use this skill when a git repository is adopting Hive Lite for the first time. It checks first-time setup state, may run `hive-lite init`, builds the first Project Map without changing product code, verifies readiness, and prepares a user-approved commit for Hive Lite setup and map files before any product requirement starts.
+description: Use this skill when a git repository is adopting Hive Lite for the first time or has incomplete Hive Lite setup files. It checks setup state, may run `hive-lite init`, builds the first Project Map without changing product code, verifies readiness, and prepares a user-approved commit for Hive Lite setup and map files before any product requirement starts.
 ---
 
 # Hive Lite Bootstrap
 
 ## Purpose
 
-Onboard a git repository to Hive Lite for the first time:
+Onboard a git repository to Hive Lite for the first time, or repair incomplete required Hive Lite setup files before product work starts:
 
 ```text
-check repo -> run hive-lite init when needed -> build first Project Map -> verify -> commit setup/map after approval
+check repo -> run hive-lite init when needed -> build or repair first Project Map -> verify -> commit setup/map after approval
 ```
 
-This skill is the only Hive Lite operator skill that may run `hive-lite init`. Use it for first-time project setup, not for ordinary coding work.
+This skill is the only Hive Lite operator skill that may run `hive-lite init`. Use it for first-time project setup or incomplete setup repair, not for ordinary coding work or ordinary map health cleanup.
 
 ## Boundaries
 
 - Do not edit application source, tests, product docs, package files, secrets, CI, or generated artifacts.
-- You may run `hive-lite init` only when the target is already a git repo and the worktree was clean before init.
+- You may run `hive-lite init` only when the target is already a git repo and either the worktree was clean before first init, or the only dirty entries are Hive Lite setup/map artifacts involved in setup repair.
 - You may directly edit only:
   - `.hive/map/project.yaml`
   - `.hive/map/areas.yaml`
   - `.hive/map/rules.yaml`
   - `.hive/map/validation.yaml`
 - Preserve setup artifacts created by `hive-lite init`, including `.hive/config.yaml` and Hive Lite `.gitignore` runtime/evidence rules. Do not manually curate or remove them.
+- Do not use this skill to fix ordinary map health findings after required setup files exist. Use `$hive-lite-map-maintainer` for stale paths, scope, roles, validation, aliases, or other Project Map quality cleanup.
 - Do not start a product requirement, run `hive-lite find`, create a Change Record, accept risk, push, merge, deploy, or run app tests.
 - Commit only after explicit human approval, or when the user's request already explicitly asked you to commit the Hive Lite bootstrap.
 - If committing, include only Hive Lite setup/map files and the Hive Lite `.gitignore` change. Never include product-code changes.
@@ -37,7 +38,20 @@ Run Hive Lite from the target repo root. Prefer:
 hive-lite <args>
 ```
 
-If unavailable, use an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. Ask for the CLI path if it is not obvious.
+If `hive-lite` is not available, stop and tell the user:
+
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -54,17 +68,21 @@ Stop if the directory is not a git repo. Tell the user to switch to the repo roo
 
 Stop if `git status --short` shows pre-existing non-Hive changes. Ask the user to commit, stash, or use another worktree first. Do not run `hive-lite init` into a dirty product worktree.
 
+If `hive.state = hive_init_required` because required setup files are missing, this is a setup repair condition. Continue only when dirty entries are limited to Hive Lite setup/map artifacts.
+
+If `git status --short` shows a deleted tracked `.hive/map/*.yaml` file from an existing committed Project Map, stop and ask whether to restore that file from git before rebuilding anything. Do not silently replace a previously committed map file with a default empty file.
+
 If Hive Lite is already initialized, do not rerun init. Continue only if the user asked to build or repair the first Project Map; otherwise explain that setup already exists and recommend `$hive-lite-map-maintainer` or `$hive-lite-start-prompt`.
 
 ### 2. Initialize
 
-If status reports `hive.state = hive_init_required` or `hive.initialized = false`, run:
+If status reports `hive.state = hive_init_required` or `hive.initialized = false`, run this only for first-time setup, partial setup, or user-approved setup repair:
 
 ```bash
 hive-lite init
 ```
 
-Then continue in the same turn. Do not ask the user to commit yet; first build the initial Project Map.
+Then continue in the same turn. Do not ask the user to commit yet; first build or repair the initial Project Map.
 
 ### 3. Build First Map
 
@@ -133,7 +151,8 @@ Return:
 Hive Lite bootstrap complete.
 
 Setup:
-- hive-lite init: <run / already initialized>
+- mode: <first-time / setup repair / already initialized>
+- hive-lite init: <run / already initialized / not run>
 
 Project Map:
 - changed files: <files>
@@ -150,4 +169,3 @@ Commit:
 Next:
 - After the setup/map commit exists, start the first requirement with `$hive-lite-start-prompt`.
 ```
-

package/docs/skills/hive-lite-finish/SKILL.md

@@ -27,11 +27,12 @@ Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-map
 - Next phase after split accept: output a `$hive-lite-start-prompt` handoff.
 - Map repair or refresh needed during finish: output a `$hive-lite-map-maintainer` handoff; do not edit map files here.
 
-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`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Boundaries
@@ -51,9 +52,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 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>`. Ask for the CLI path if it is not obvious.
+If `hive-lite` is not available, stop and tell the user:
 
-In command examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -61,7 +73,7 @@ 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. Recommend `$hive-lite-bootstrap` for first-time setup. If the user expected an existing Hive Lite change, they may be in the wrong directory.
+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. Recommend `$hive-lite-bootstrap` for first-time setup or setup repair. If the user expected an existing Hive Lite change, they may be in the wrong directory or missing setup files.
 
 Find one of:
 

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

@@ -23,11 +23,12 @@ Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-fin
 - 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`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Authority Boundary
@@ -35,7 +36,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 Setup precondition:
 
 - This skill must not run `hive-lite init`.
-- If Hive Lite is not initialized or is partially initialized, stop immediately and recommend `$hive-lite-bootstrap` for first-time setup.
+- If Hive Lite setup is missing or incomplete, stop immediately and recommend `$hive-lite-bootstrap` for first-time setup or setup repair.
 - Do not create `.hive/map` manually, do not edit `.hive/config.yaml`, and do not edit `.gitignore`.
 
 Map-maintenance authority:
@@ -61,9 +62,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 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.
+If `hive-lite` is not available, stop and tell the user:
 
-In examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -80,17 +92,11 @@ If it reports `hive.state = repo_setup_required`, stop immediately. Do not run `
 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.
+Hive Lite setup is missing or incomplete in this repo.
 
 Recommended next step:
   $hive-lite-bootstrap
-  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
-
-If the bootstrap skill is not available, run `hive-lite init` from the repo root, then rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
-
-Do not commit immediately after init. Build the first Project Map first, then commit Hive Lite setup and map files together before starting the first product requirement.
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 ```
 
 For older Hive Lite versions that do not report `hive.initialized`, check for required setup files before continuing:
@@ -128,7 +134,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, stop immediately and recommend `$hive-lite-bootstrap`. Do not create missing map files manually.
+If any required map file is missing, stop immediately and recommend `$hive-lite-bootstrap` as a setup repair handoff. Do not create missing map files manually. If the repo already had a committed Project Map, tell the user that restoring the missing file from git is safer than silently rebuilding it from defaults.
 
 ### 3. Verify Current Map
 

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

@@ -56,7 +56,7 @@ 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`.
+- warnings include `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_DIRECT_NEW_FILE_SCOPE`, `DIRECT_ONLY_REFERENCE_PEERS`, `BROAD_FALLBACK_ONLY`, `TARGET_ENTITY_MISMATCH`, `MISSING_ARTIFACT_FAMILY_SCOPE`, `MISSING_REQUIRED_HOOK_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
 - `map health --area <selected>` shows critical findings.
 
 Goal:

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

@@ -55,6 +55,10 @@ Rules:
 
 - `readable` may be broad.
 - `writable_direct` should be exact existing files, usually 2-8 files.
+- Prefer `writable_existing` for exact update targets and `writable_create_patterns` for new file permissions when the repo has repeated artifact families.
+- For intents that create new peer files, use very small direct patterns that match only the expected family, such as `src/providers/*Provider.ts`; do not fall back to an entire source tree.
+- Existing peer files that are only copy/reference examples should stay readable/reference context, not selected Direct Writable for a new peer target.
+- Put peer examples under `readable_reference` and describe repeated families under `artifact_families` when possible.
 - Broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, and `**` must not be in `writable_direct`.
 - Every conditional/fallback item needs `reason` and `requires_review: true`.
 

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

@@ -24,18 +24,19 @@ Do not assume this skill can invoke another skill automatically. Handoffs are te
 - To map maintenance: output a `$hive-lite-map-maintainer` prompt and stop.
 - To finish work after coding: include `$hive-lite-finish` in the final instructions, but do not run finish actions here.
 
-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`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Boundaries
 
 - 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 recommend `$hive-lite-bootstrap` before using this skill.
+- Do not run `hive-lite init`. If Hive Lite setup is missing or incomplete, stop and recommend `$hive-lite-bootstrap` 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.
@@ -49,9 +50,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 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>`. Do not spend a long time searching the target repo; ask for the Hive Lite CLI path if it is not obvious.
+If `hive-lite` is not available, stop and tell the user:
 
-In command examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -78,11 +90,11 @@ If status reports `hive.state = repo_setup_required`, stop immediately. Do not r
 If status 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.
+Hive Lite setup is missing or incomplete in this repo.
 
 Recommended next step:
   $hive-lite-bootstrap
-  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 
 Do not start the product requirement yet. After bootstrap builds the first map, commit the Hive Lite setup and map files together, then rerun this start skill with the original requirement.
 ```
@@ -99,9 +111,9 @@ For older Hive Lite versions that do not report `hive.initialized`, check whethe
 
 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`.
+If `hive-lite status --json` is unavailable, stop and tell the user to update Hive Lite CLI and sync skills. Do not fall back to git-only status for normal pilot use.
 
-Continue only when `canStartNewRequirement` is true or fallback git status is clean. If not clean, read [preflight.md](references/preflight.md), present options, and stop immediately unless the user had already explicitly chosen an option before this step.
+Continue only when `canStartNewRequirement` is true. If not clean, read [preflight.md](references/preflight.md), present options, and stop immediately unless the user had already explicitly chosen an option before this step.
 
 After any preflight action, rerun `hive-lite status --json`; continue only when the target worktree is clean.
 
@@ -168,8 +180,9 @@ Accept the packet only when all are true:
 - `mode` is `edit_context`.
 - `area.id` is present.
 - `writableScope` contains at least one narrow direct file.
+- `writePlan.blockingWarnings` is empty when present.
 - `validationPlan` is not empty.
-- `warnings` has no map-gap warning such as `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
+- `warnings` has no map-gap warning such as `NO_CONFIDENT_AREA`, `MISSING_DIRECT_WRITABLE_SCOPE`, `MISSING_DIRECT_NEW_FILE_SCOPE`, `DIRECT_ONLY_REFERENCE_PEERS`, `BROAD_FALLBACK_ONLY`, `TARGET_ENTITY_MISMATCH`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
 - `hive-lite map health --area <areaId> --json` reports no critical findings.
 
 Review-gated conditional or broad fallback scope is allowed. Include it in the final prompt as a boundary, not as a failure.
@@ -188,7 +201,12 @@ Repair principles:
 
 - Prefer focused product/work area ids such as `dashboard.action_inbox`, not one-part ids such as `dashboard`.
 - Preserve unrelated areas exactly unless a change is needed for the reported map gap.
-- Use `scope.writable_direct` for exact files the coding agent may edit.
+- Use `scope.writable_direct` for exact files the coding agent may edit, or very small direct patterns when the intent needs new peer files such as a provider, proxy, adapter, connector, or plugin.
+- Prefer `scope.writable_existing` for exact update targets and `scope.writable_create_patterns` for narrow create permissions when the map needs operation-specific write capabilities.
+- Put copy sources and peer examples under `scope.readable_reference` when they should guide implementation but not be edited.
+- Use `artifact_families` to declare required create artifacts and hook files for repeated artifact families such as providers, adapters, connectors, endpoints, DTOs, tests, or migrations.
+- Treat Direct Writable as the selected intent-specific write target list, not the area's full writable maximum.
+- Keep peer examples, entrypoints, and similar existing files as reference context unless the current intent specifically requires editing them.
 - Put conditional files under `scope.writable_conditional` with `reason` and `requires_review: true`.
 - Put broad patterns only under `scope.writable_broad_fallback` with `reason` and `requires_review: true`.
 - Never put broad patterns such as `apps/*/src/**`, `packages/**`, `server/**`, or `**` in `writable_direct`.
@@ -258,6 +276,9 @@ Use this context packet as your source of truth. Edit only Direct Writable files
 Direct Writable:
 - <file>
 
+Reference Files:
+- <file and reason, only when useful; do not edit unless it is also Direct Writable>
+
 Review-Gated:
 - <conditional/broad item and reason>
 

package/docs/skills/hive-lite-start-prompt/references/preflight.md

@@ -11,11 +11,11 @@ If `hive-lite status --json` reports `hive.state = hive_init_required` or `hive.
 Say:
 
 ```text
-Hive Lite is not initialized in this repo yet.
+Hive Lite setup is missing or incomplete in this repo.
 
 Recommended next step:
   $hive-lite-bootstrap
-  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 
 After bootstrap builds the first map, commit the Hive Lite setup and map files together before starting the product requirement.
 ```
@@ -107,7 +107,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 this start skill; first-time setup belongs to `$hive-lite-bootstrap`.
+- Do not run `hive-lite init` from this start skill; first-time setup and setup repair belong to `$hive-lite-bootstrap`.
 - 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.3",
+  "version": "0.1.7",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/src/cli.js

@@ -103,7 +103,7 @@ function requireHiveInitialized(cwd, commandName) {
     const missing = status.hive.missingSetupFiles && status.hive.missingSetupFiles.length > 0
       ? ` Missing: ${status.hive.missingSetupFiles.join(', ')}.`
       : '';
-    throw new Error(`${commandName} requires Hive Lite initialization. Use $hive-lite-bootstrap first, or run hive-lite init from the repo root as the low-level fallback.${missing}`);
+    throw new Error(`${commandName} requires Hive Lite initialization. Use $hive-lite-bootstrap first.${missing}`);
   }
 }
 
@@ -230,6 +230,22 @@ function printContext(result) {
       console.log(`    risk: ${item.risk}`);
     }
   }
+  if (packet.writePlan && packet.writePlan.hypotheses && packet.writePlan.hypotheses.length > 0) {
+    console.log('');
+    console.log('Write Plan:');
+    for (const item of packet.writePlan.hypotheses) {
+      console.log(`  - ${item.action} ${item.artifactFamily}: ${item.operation}${item.targetIdentity ? ` for ${item.targetIdentity}` : ''}`);
+    }
+    if (packet.writePlan.blockingWarnings && packet.writePlan.blockingWarnings.length > 0) {
+      console.log('  blocking:');
+      for (const item of packet.writePlan.blockingWarnings) console.log(`    - ${item.code}: ${item.message}`);
+    }
+  }
+  if (packet.writePlan && packet.writePlan.referenceFiles && packet.writePlan.referenceFiles.length > 0) {
+    console.log('');
+    console.log('Reference Files:');
+    for (const file of packet.writePlan.referenceFiles) console.log(`  - ${file.path}\n    reason: ${file.reason}`);
+  }
   console.log('');
   console.log('Relevant Files:');
   if (packet.relevantFiles.length === 0) console.log('  - (none found)');
@@ -242,6 +258,14 @@ function printContext(result) {
     console.log('');
     console.log(`Scope Quality: ${packet.scope.quality}`);
     console.log('');
+    console.log('Writable Existing Scope:');
+    if (!packet.scope.writableExisting || packet.scope.writableExisting.length === 0) console.log('  - (none configured)');
+    for (const item of packet.scope.writableExisting || []) console.log(`  - ${patternDisplay(item)}`);
+    console.log('');
+    console.log('Writable Create Patterns:');
+    if (!packet.scope.writableCreatePatterns || packet.scope.writableCreatePatterns.length === 0) console.log('  - (none configured)');
+    for (const item of packet.scope.writableCreatePatterns || []) console.log(`  - ${patternDisplay(item)}`);
+    console.log('');
     console.log('Conditional Writable Scope:');
     if (packet.scope.writableConditional.length === 0) console.log('  - (none configured)');
     for (const item of packet.scope.writableConditional) console.log(`  - ${patternDisplay(item)}`);
@@ -363,6 +387,24 @@ function printCheck(root, result) {
     console.log('  broad fallback:');
     for (const item of change.scope.writableBroadFallback) console.log(`    - ${patternDisplay(item)}`);
   }
+  if (change.writePlanStatus) {
+    console.log('');
+    console.log('Write Plan:');
+    console.log(`  ${change.writePlanStatus.status}`);
+    if (change.writePlanStatus.contextMode) console.log(`  context mode: ${change.writePlanStatus.contextMode}`);
+    if (change.writePlanStatus.selectedWritableDirect && change.writePlanStatus.selectedWritableDirect.length > 0) {
+      console.log('  selected direct:');
+      for (const item of change.writePlanStatus.selectedWritableDirect) console.log(`    - ${item}`);
+    }
+    if (change.writePlanStatus.referenceOnlyTouched && change.writePlanStatus.referenceOnlyTouched.length > 0) {
+      console.log('  reference-only touched:');
+      for (const item of change.writePlanStatus.referenceOnlyTouched) console.log(`    - ${item.path}: ${item.reason || item.reference}`);
+    }
+    if (change.writePlanStatus.blockingReasons && change.writePlanStatus.blockingReasons.length > 0) {
+      console.log('  blockers:');
+      for (const reason of change.writePlanStatus.blockingReasons) console.log(`    - ${reason}`);
+    }
+  }
   console.log('');
   console.log('Validation:');
   console.log(`  ${change.validation.status}`);