hive-lite 0.1.9 → 0.2.1

package/README.md

@@ -24,6 +24,7 @@ validate -> accept -> optional Map Delta Candidate
 
 For detailed CLI output meanings and "what to do next" tables, see [docs/cli-semantics.md](docs/cli-semantics.md).
 For a non-technical pilot-user workflow guide in Chinese, see [docs/user-pilot-guide.zh.md](docs/user-pilot-guide.zh.md).
+For using `$hive-lite-discovery` to turn vague ideas into Start Intent Handoffs, see [docs/hive-lite-discovery-usage.zh.md](docs/hive-lite-discovery-usage.zh.md).
 
 Examples below use `node bin/hive.js` from this repository. When installed as a package, use `hive-lite` instead.
 
@@ -78,9 +79,10 @@ When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`
 
 ### Sync Agent Skills
 
-Hive Lite ships four operator skills:
+Hive Lite ships five bundled skills for discovery and operator workflows:
 
 - `hive-lite-bootstrap`
+- `hive-lite-discovery`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`

package/docs/cli-semantics.md

@@ -133,10 +133,34 @@ node bin/hive.js find "Dashboard Action Inbox content should align left" --json
 - `mode`: whether the packet is editable, discovery-only, map-needing, or too broad
 - `area.id`: selected Project Map area
 - `writableScope`: direct writable files
+- `writePlan.selectedWritableCertificates`: structured proof for each selected direct write
 - `reviewGated`: conditional or broad fallback scope that requires review
 - `splitNote`: split artifact path when mode is `needs_decomposition`
 - `candidatePhaseSeeds`: phase seeds for large intents
 
+### Write Plan Safety
+
+`find` builds a write plan before it emits `edit_context`.
+
+Hard principles:
+
+- Relevant does not mean writable.
+- Entrypoint does not mean writable.
+- Peer example does not mean writable.
+- Broad fallback does not mean writable.
+- Create intent requires create capability.
+- Hook requirement requires hook capability.
+- Direct Writable is selected per intent, not copied from the whole area.
+- Unknown new files are blocked by default during `check`.
+
+Areas can declare `identity_aliases` so user-facing names, model names, or vendor nicknames resolve to the same peer identity during write-plan selection. This is useful for intents such as "image2" or "ChatGPT" that should map to OpenAI/OpenAI-like provider files without making old peer examples writable.
+
+Areas can also declare `peer_file_templates` for read-only candidate paths. Templates help explain what a new peer may need, but they do not grant write permission; create intents still need `writable_create_patterns` or an exact certified create path.
+
+`selectedWritableDirect` remains a compatibility path list. New Context Packets also include `writePlan.selectedWritableCertificates`, where each certificate records the path or pattern, operation, artifact, target identity, and map entry that certified the write. `check` uses these certificates when present, and falls back to legacy selected direct scope for older Context Packets.
+
+Warning codes that indicate map gaps or write-plan uncertainty include `MISSING_DIRECT_NEW_FILE_SCOPE`, `DIRECT_ONLY_REFERENCE_PEERS`, `BROAD_FALLBACK_ONLY`, `TARGET_ENTITY_MISMATCH`, `MISSING_ARTIFACT_FAMILY_SCOPE`, `MISSING_REQUIRED_HOOK_SCOPE`, `AMBIGUOUS_TARGET_IDENTITY`, `REFERENCE_DIRECT_ROLE_CONFLICT`, `DIRECT_SCOPE_OPERATION_UNSPECIFIED`, `UNKNOWN_NEW_FILE`, and `LOW_CONFIDENCE_INTENT_WRITE_PLAN`.
+
 When continuing a split phase, pass the recorded split and phase ids plus the phase primary area:
 
 ```bash
@@ -148,9 +172,35 @@ If the split note or phase cannot be found, the result is not an edit permit and
 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 when run from a source checkout, and includes `hive-lite ...` as a fallback for environments where the package alias is installed.
 
+## `intent`
+
+`intent` stores and checks Start Intent Handoff artifacts produced by `$hive-lite-discovery`.
+It is a deterministic artifact command, not a discovery chat surface and not an execution permit.
+
+Commands:
+
+```bash
+node bin/hive.js intent save --from <start-intent.md> --json
+node bin/hive.js intent save --stdin --json
+node bin/hive.js intent validate <intent_id_or_path> --json
+node bin/hive.js intent show <intent_id_or_path> --json
+```
+
+Saved handoffs are written under:
+
+```text
+.hive/state/intents/<intent_id>/start-intent.md
+.hive/state/intents/<intent_id>/start-intent.json
+```
+
+The validator requires `type: hive-lite.start-intent`, `version: 1`, `status: ready_for_hive`, a safe `intent_id`, and the minimal Markdown sections `Original Idea`, `Agreed Direction`, and `User-Confirmed Decisions`. `Blocking Questions` is optional, but if present for a ready handoff it must be `None`.
+It rejects execution-only content such as `Direct Writable`, final file scope, implementation plans, validation plans, files-to-modify sections, and direct instructions that an agent should edit specific files.
+`show --json` includes a derived `findIntent` for `$hive-lite-start-prompt`; it is target-oriented and derived from `Agreed Direction`.
+The human-readable `intent save` output recommends starting the operator runner with `hive-lite operator run --intent <intent_id>` and also prints the equivalent saved handoff path form.
+
 ## `skills`
 
-`skills` installs and checks the Hive Lite operator skills that teach agent CLIs how to drive Hive Lite.
+`skills` installs and checks bundled Hive Lite skills that teach agent CLIs how to drive discovery and operator workflows.
 
 Hive Lite does not detect which agent CLI is installed or currently running. `skills doctor` only checks the selected skills directories: all known target paths by default, explicit target paths with `--agent`, or a custom directory with `--path`.
 
@@ -159,6 +209,7 @@ Hive Lite does not detect which agent CLI is installed or currently running. `sk
 Bundled skills:
 
 - `hive-lite-bootstrap`
+- `hive-lite-discovery`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`
@@ -344,6 +395,7 @@ JSON output includes `status`, `mapDir`, `problems`, `errors`, and `warnings`. `
 ## `map health`
 
 `map health` checks whether the Project Map can support safe `find` and useful `check` evidence policy.
+It includes lightweight static lint for write capability coverage, such as reference files that also match update-capable writable scope, artifact families missing create patterns or hook coverage, create patterns without operation/artifact/intent metadata, and peer templates/examples without create capability.
 
 ```bash
 node bin/hive.js map health

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

@@ -30,6 +30,17 @@ This skill is the only Hive Lite operator skill that may run `hive-lite init`. U
 - 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.
 
+## Completion Contract
+
+End with exactly one clear outcome:
+
+- `bootstrap_complete`: Hive Lite setup exists, the first Project Map is verified, changed setup/map files are summarized, and the commit boundary is either created or explicitly waiting for approval.
+- `already_initialized`: setup already exists and ordinary work should continue through `$hive-lite-start-prompt` or `$hive-lite-map-maintainer`.
+- `needs_user_decision`: pre-existing dirty work, deleted committed map files, or commit approval requires a human choice.
+- `blocked`: the repo is not a git repository, the CLI is unavailable, or setup cannot be repaired safely.
+
+Do not start a product requirement from this skill.
+
 ## Find The CLI
 
 Run Hive Lite from the target repo root. Prefer:
@@ -53,6 +64,23 @@ 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.
 
+## Language Style
+
+Use Chinese for human-facing process guidance, warnings, and next-step instructions. Keep technical identifiers and structured Hive Lite labels in English, including file paths, commands, setup state names, validation profile ids, `Project Map`, `Change`, and `Commit`.
+
+## Context Gathering
+
+Gather only enough facts to create or repair the initial Hive Lite setup.
+
+Stop searching once these are known:
+
+- repo and worktree preflight state;
+- whether `hive-lite init` is needed and safe;
+- high-value initial areas, existing scripts, and key entrypoints needed for the first usable Project Map;
+- `map verify` and `map health` status after the map is built.
+
+Do not map the whole repository. Build 3-8 narrow areas that make near-term product requests routable.
+
 ## Workflow
 
 ### 1. Preflight

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

@@ -0,0 +1,149 @@
+---
+name: hive-lite-discovery
+description: Use this skill when a user wants to discuss and clarify a product/code requirement before coding. It behaves like a no-code requirements conversation, may inspect the repository read-only to compare the idea with the current project, asks follow-up questions when the requirement is unclear, saves a short Start Intent Handoff with `hive-lite intent save`, and stops before code execution, Project Map repair, or operator-run automation.
+---
+
+# Hive Lite Discovery
+
+## Purpose
+
+Turn a requirements conversation into a durable Start Intent Handoff that is ready for Hive Lite to search.
+
+Discovery makes an idea ready for Hive Lite. Start makes that intent ready for code.
+
+The mental model is simple: the user is saying, "do not write code yet; discuss this requirement with me." If the requirement is unclear, ask natural follow-up questions. If repo context would help, inspect it read-only. When the direction is clear enough, save the agreed result for the next skill.
+
+## Boundaries
+
+- This skill is pre-Hive and pre-operator.
+- Do not edit application code, tests, docs, `.hive/map/*.yaml`, `.gitignore`, generated artifacts, or runtime evidence.
+- Do not run `hive-lite find`, `check`, `validate`, `accept`, `operator run`, or coding-agent execution.
+- Do not produce `Direct Writable`, final file scope, an implementation plan, a validation plan, files to modify, or instructions that an agent should edit specific files.
+- Do not turn vague ideas into coding permission. The handoff is search-ready, not execution-ready.
+- Keep the handoff plain and short. Do not add sections merely to sound complete.
+- Optional non-goals, acceptance signals, unknowns, or hints are for unusual cases only; omit them by default.
+
+## Completion Contract
+
+End with exactly one clear outcome:
+
+- `ready_for_hive`: a valid Start Intent Handoff is saved, `intent_id` and artifact paths are reported, and the next terminal `hive-lite operator run --intent ...` command is shown.
+- `needs_user_decision`: one to three product questions are asked because the direction is not clear enough; no `ready_for_hive` handoff is saved.
+- `blocked`: CLI, repo, or artifact validation prevents saving; report the exact blocker and next action.
+
+Do not produce a coding prompt, implementation plan, or file-edit permission as a discovery outcome.
+
+## Context Gathering
+
+Gather only enough facts to make the idea ready for Hive Lite search.
+
+Stop searching once these are known:
+
+- the user-approved product direction;
+- confirmed product decisions versus open blocking questions;
+- whether the request is best understood as a bug, new capability, behavior change, or replacement of existing behavior;
+- only the minimal repo vocabulary or existing capability hints needed to phrase the direction in project terms;
+- whether the handoff can be saved as `status: ready_for_hive`.
+
+Do not inspect the repo to choose final files, architecture, validation commands, or Direct Writable scope. Those belong to `$hive-lite-start-prompt` and the Context Packet.
+
+## Workflow
+
+1. Understand the user's starting idea and preserve it as provenance.
+2. Inspect the repo read-only only when project vocabulary, current behavior, or the difference between the idea and the current project needs clarification. Prefer `rg` and `rg --files`; do not write files during exploration.
+3. Ask follow-up questions only when the answer affects the product direction. If product decisions remain unresolved, do not save a `ready_for_hive` handoff.
+4. Separate confirmed decisions from ideas that were merely discussed.
+5. Draft a short Start Intent Handoff using the required structure below.
+6. Save it with one of:
+
+```bash
+hive-lite intent save --from <draft-start-intent.md> --json
+hive-lite intent save --stdin --json
+```
+
+7. If the CLI reports errors, revise the draft only when the error is about this draft's content. Treat execution-only content errors as real scope violations, not formatting nits.
+   - If the CLI reports `MISSING_SECTION` for optional legacy sections such as `Non-Goals`, `Acceptance Signals`, `Unknowns For Hive Lite To Resolve`, `Pre-Hive Observations / Hints`, or `Blocking Questions`, the installed CLI is stale relative to this skill. Do not add those sections just to satisfy the old CLI. Stop and tell the user to update or reinstall Hive Lite CLI, then rerun discovery.
+8. Return the `intent_id`, `start-intent.md` path, and the next terminal command for `hive-lite operator run --intent`.
+
+## Required Handoff
+
+Use Markdown with YAML frontmatter:
+
+```md
+---
+type: hive-lite.start-intent
+version: 1
+status: ready_for_hive
+source: hive-lite-discovery
+intent_id: int_20260515_short_topic
+created_at: 2026-05-15T00:00:00+08:00
+---
+
+# Start Intent Handoff: <short title>
+
+## Original Idea
+
+<Preserve the user's starting point. This is provenance, not the final requirement.>
+
+## Agreed Direction
+
+<The user-approved product or behavior direction. Avoid exact implementation files or architecture.>
+
+## User-Confirmed Decisions
+
+- <Decision actually confirmed by the user.>
+
+```
+
+The sections above are enough for most handoffs. Add optional sections only when they remove real ambiguity:
+
+- `## Blocking Questions`: use only when the handoff is not ready; for `ready_for_hive`, omit it or set it to `None`.
+- `## Non-Goals`: use only for a user-confirmed scope boundary that would otherwise be easy to misunderstand.
+- `## Pre-Hive Observations / Hints`: use only for non-authoritative repo observations that materially help wording.
+- Avoid `## Acceptance Signals` and `## Unknowns For Hive Lite To Resolve` by default. They easily become noisy pseudo-specs.
+
+## Target-Only Routing Text
+
+`Agreed Direction` is used to derive the Hive Lite `findIntent`. Keep it target-only.
+
+- Put only the capability or behavior that should be searched next.
+- Do not name reference, existing, non-regression, or "do not replace" capabilities in `Agreed Direction`.
+- If the user mentions an existing capability only as context, keep that in `Original Idea`.
+- If an additive/non-replacement boundary is important, phrase it generically in `User-Confirmed Decisions`, such as `This is additive, not a replacement of existing LLM proxy capability`, without naming unrelated providers.
+- Before saving, mentally check whether `Agreed Direction` could match multiple providers, products, modules, or target identities. If yes, rewrite it around the intended target only.
+
+## Validation Rules
+
+- A `ready_for_hive` handoff must have no unresolved product questions. If `Blocking Questions` exists, it must be `None`.
+- Do not invent non-goals, acceptance criteria, codebase unknowns, or hints just to fill a template.
+- Put possible file paths only in `Pre-Hive Observations / Hints`, and phrase them as non-authoritative hints.
+- If the user asks for implementation planning, explain that `$hive-lite-start-prompt` and the Context Packet define execution boundaries after discovery.
+- If the requirement is already clear, save a short handoff without extra questions. Do not skip to `$hive-lite-start-prompt` unless the user explicitly asks to bypass discovery.
+
+## Final Output
+
+When the intent is saved, use this shape:
+
+~~~text
+Start Intent Handoff saved.
+
+Intent: <intent_id>
+Path: .hive/state/intents/<intent_id>/start-intent.md
+JSON: .hive/state/intents/<intent_id>/start-intent.json
+
+Next recommended step: run this in a real terminal from the target repo root, not in the agent chat:
+```bash
+cd <target repo root>
+hive-lite operator run --intent <intent_id>
+```
+
+Equivalent path form:
+```bash
+cd <target repo root>
+hive-lite operator run --intent .hive/state/intents/<intent_id>/start-intent.md
+```
+
+The discovery skill stops here. It does not run the operator command, start coding, or invoke another skill automatically.
+~~~
+
+Do not run the next skill or operator command yourself from this discovery skill.

package/docs/skills/hive-lite-discovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hive Lite Discovery"
+  short_description: "Clarify ideas into Hive Lite start intents"
+  default_prompt: "Use $hive-lite-discovery to clarify this vague idea and save a Start Intent Handoff."

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

@@ -22,7 +22,9 @@ Hive Lite is the factual evidence layer. This skill is the operator layer. The h
 
 ## Skill Handoffs
 
-Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-map-maintainer` automatically. If another skill is needed, output an explicit prompt for the user to run and stop.
+Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-map-maintainer` automatically. If another skill is needed, output an explicit prompt for the user to paste as a new skill invocation message and stop.
+
+Skill handoffs are not terminal commands. Do not run raw `hive-lite find/check/validate` commands as a substitute for a `$hive-lite-start-prompt`, `$hive-lite-finish`, or `$hive-lite-map-maintainer` handoff. If the human says "help me run the next skill" or similar, remind them to paste the provided `$...` block as a new message so the correct skill is loaded.
 
 - 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.
@@ -35,6 +37,18 @@ hive-lite --version
 hive-lite skills sync --agent all
 ```
 
+## Operator Runner Mode
+
+If the invocation includes `Step result path`, `Artifacts directory`, and `Step-result schema_version`, you are running under `hive-lite operator run`.
+
+- Treat natural-language output as human/debug text only; the runner reads `step-result.json`.
+- Write any repair, handoff, manual-review, or accept-summary artifact under the provided `Artifacts directory`, then write `step-result.json` to the exact `Step result path`.
+- Use `needs_human_action` with `manual_review_required` or `review_reason_required` when human evidence or review judgment is required.
+- Use `accept_ready` with `accept` only when Hive Lite evidence is acceptable and the remaining decision is human accept/commit confirmation.
+- Use `risk_acceptance_required` only when explicit human risk acceptance and a reason are required.
+- Use `blocked` with `revise_required` for scope violations, failed required validation, or repair-needed outcomes.
+- After writing the structured result, stop. Do not wait for human input inside the operator-agent session.
+
 ## Boundaries
 
 - Do not edit application code.
@@ -44,6 +58,18 @@ hive-lite skills sync --agent all
 - Do not ignore scope violations or failed required validation.
 - Agent summaries are not evidence. Evidence must come from Hive Lite diff/scope, validation logs, manual validation notes, review reasons, or accept records.
 
+## Completion Contract
+
+End with exactly one clear outcome:
+
+- `accepted` or `done`: the change was accepted through Hive Lite and the commit decision was completed or explicitly deferred.
+- `needs_human_action`: the human must perform manual verification, provide a review reason, or choose a risk path before the skill can proceed.
+- `accept_ready`: evidence is acceptable and the human/runner must decide whether to accept and commit.
+- `blocked`: scope, validation, map, or evidence problems prevent accept; provide the bounded repair prompt or map-maintainer handoff.
+- `failed`: only for an unexpected tool/runtime failure that prevents a normal blocked result.
+
+Do not present a change as finished unless Hive Lite check/validation/evidence state supports that conclusion.
+
 ## Find The CLI
 
 Run Hive Lite from the target repo root. Prefer the package command:
@@ -67,6 +93,19 @@ 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.
 
+## Context Gathering
+
+Gather only enough facts to decide the finish outcome.
+
+Stop searching once these are known:
+
+- target `ctx_id` or `chg_id`;
+- latest `hive-lite check --json` scope, validation, risk, and `evidencePolicy.verdict`;
+- validation command safety from [safety.md](references/safety.md), when validation is needed;
+- exact human evidence, review reason, or risk reason when the flow requires one.
+
+After any validation, manual evidence, review reason, or risk action, rerun `hive-lite check <chg_id> --json` before deciding the next outcome.
+
 ## Workflow
 
 ### 1. Identify The Change
@@ -138,10 +177,10 @@ After running validation or recording manual evidence, run `hive-lite check <chg
 
 If `accept` later returns `postAcceptHint.kind = split_remaining_phases`, explain ready and waiting phases to the human and recommend `postAcceptHint.suggestedNextPhase` when present.
 
-Do not assume this skill can invoke `$hive-lite-start-prompt` automatically. Instead, output a clear handoff prompt and stop:
+Do not assume this skill can invoke `$hive-lite-start-prompt` automatically. Instead, output a clear handoff prompt for the human to paste as a new message and stop:
 
 ```text
-To continue the next phase, run:
+To continue the next phase, paste this as a new message:
 
 $hive-lite-start-prompt
 Continue split <split_id> with phase <phase_id>.
@@ -149,7 +188,7 @@ Use this find intent:
 "<findIntent>"
 ```
 
-If the user explicitly asks you to continue in the same session, you may run the phase-specific `hive-lite find ... --from-split ... --phase ... --area <primaryAreaId> --json` command and summarize the result, but do not duplicate the full start-skill workflow unless the active agent environment has actually loaded `$hive-lite-start-prompt`.
+If the user asks you to continue the next phase in the same session, do not run the phase-specific `hive-lite find ...` command as a shortcut. Tell them to paste the `$hive-lite-start-prompt` block above as a new message so the start skill is definitely active.
 
 ### 4. Automatic Validation
 
@@ -287,7 +326,7 @@ Accepted and committed.
 - Split next phase: <handoff prompt or none>
 ```
 
-If `Map Delta Candidate` is not `none`, do not apply it from this skill. Explain that the accepted change suggests a possible Project Map improvement and output this handoff:
+If `Map Delta Candidate` is not `none`, do not apply it from this skill. Explain that the accepted change suggests a possible Project Map improvement and output this handoff for the human to paste as a new message:
 
 ```text
 $hive-lite-map-maintainer
@@ -307,4 +346,22 @@ If no commit was created because the user explicitly asked not to commit, warn t
 
 Do not dump raw JSON unless the user asks. Translate Hive Lite facts into plain language, then show exact commands only when asking for confirmation or reporting what ran.
 
+Use Chinese for human-facing process guidance, warnings, and instructions. Keep technical identifiers and structured Hive Lite labels in English. Do not translate labels such as `Change`, `Commit`, `Evidence`, `Validation`, `Review mode`, `Map Delta Candidate`, or `Worktree`; do not translate commands, file paths, context/change ids, validation profile ids, verdict names, risk levels, commit hashes, branch names, package names, or code symbols.
+
+For accepted-change summaries, keep the structured summary lines in English and localize only human reminders or operational notes. For example:
+
+```text
+Accepted and committed.
+
+- Change: chg_xxx
+- Commit: <sha> (<message>)
+- Evidence: .hive/changes/chg_xxx/evidence.json
+- Validation: mvn -q -DskipTests compile passed
+- Review mode: accepted with your review reason
+- Map Delta Candidate: none
+- Worktree: clean
+
+没有执行 push 或 deploy。
+```
+
 When you must stop for human input, stop cleanly with choices. Do not continue in the same response unless the user had already explicitly chosen an option.

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

@@ -54,6 +54,17 @@ Map-maintenance authority:
 - 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.
 
+## Completion Contract
+
+End with exactly one clear outcome:
+
+- `map_maintained`: `.hive/map/*.yaml` changes are summarized, `map verify` and relevant health/find checks are reported, and the next skill prompt or commit boundary is explicit.
+- `needs_user_decision`: a Map Delta Candidate, missing map restore, uncertain broad repair, or commit decision requires human confirmation.
+- `handoff_required`: setup repair, start-prompt rerun, or finish flow belongs to another skill; provide the exact handoff prompt and stop.
+- `blocked`: required map files, YAML validity, or repo state prevents safe maintenance; report the exact blocker and next action.
+
+Do not include a coding agent prompt or product-code implementation instructions.
+
 ## Find The CLI
 
 Run Hive Lite from the target repo root. Prefer the package command:
@@ -77,6 +88,23 @@ 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.
 
+## Language Style
+
+Use Chinese for human-facing process guidance, warnings, and next-step instructions. Keep technical identifiers and structured Hive Lite labels in English, including area ids, file paths, commands, validation profile ids, `Context Packet`, `Direct Writable`, `Review-Gated`, `Map Delta Candidate`, `Change`, and `Commit`.
+
+## Context Gathering
+
+Gather only enough facts to repair or refresh the Project Map safely.
+
+Stop searching once these are known:
+
+- maintenance mode from [lifecycle.md](references/lifecycle.md);
+- current map validity and affected area health;
+- exact existing paths, scripts, entrypoints, validation profiles, and risk/manual-verification hints needed for the map change;
+- whether an intent-triggered repair now produces `edit_context` without critical map-gap warnings.
+
+Prefer `rg --files`, `rg`, `hive-lite map health`, `hive-lite map prompt`, and focused `hive-lite find` reruns over broad architecture exploration. Mark uncertainty with TODO notes instead of continuing to search indefinitely.
+
 ## Workflow
 
 ### 0. Git Precondition

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_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`.
+- 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`, `AMBIGUOUS_TARGET_IDENTITY`, `REFERENCE_DIRECT_ROLE_CONFLICT`, `DIRECT_SCOPE_OPERATION_UNSPECIFIED`, `UNKNOWN_NEW_FILE`, `LOW_CONFIDENCE_INTENT_WRITE_PLAN`, `MISSING_ENTRYPOINT`, or `MISSING_VALIDATION`.
 - `map health --area <selected>` shows critical findings.
 
 Goal:

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

@@ -54,11 +54,18 @@ scope:
 Rules:
 
 - `readable` may be broad.
+- Relevant does not mean writable.
+- Entrypoint does not mean writable.
+- Peer example does not mean writable.
+- Broad fallback does not mean writable.
+- Direct Writable is selected per intent, not copied from the whole area.
 - `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.
+- Use `identity_aliases` when user-facing names, model names, or vendor nicknames should resolve to one canonical peer identity.
+- Use `peer_file_templates` only as read-only candidate path hints; create permissions still require `writable_create_patterns`.
 - 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`.