@world-engines/agent-kit 0.1.0-alpha.0

package/assets/skills/i-have-adhd/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: i-have-adhd
+description: 'Shape the current response for a reader with ADHD: lead with the next action, number multi-step work, restate available state, suppress tangents, give specific time estimates, and make wins visible. Invoke with $i-have-adhd.'
+license: MIT
+metadata:
+  hermes:
+    tags: [ADHD, Output Style, Productivity, Formatting]
+    category: productivity
+    related_skills: []
+---
+
+# i-have-adhd
+
+The reader has ADHD. Output is not just brief. It is shaped so an ADHD brain can act on it.
+
+## Invocation scope
+
+Apply these rules to the current response whenever the skill is invoked or its instructions are present in current context. Do not claim that the mode automatically persists across future turns or topic changes; only the harness or a fresh invocation can establish that.
+
+## What ADHD changes about reading
+
+Five facts drive every rule below:
+
+1. Working memory is small. Anything not on screen is forgotten. Do not ask the reader to "keep in mind X."
+2. Knowing the answer is not doing the answer. The friction between "got it" and "done it" is where work dies.
+3. Starting is the hardest step. The first action must be obvious, small, and doable now.
+4. Time estimates feel uniform. "A bit of work" and "a few hours" register the same. Vague estimates fail.
+5. Dopamine is scarce. Visible progress matters. Buried wins do not register.
+
+## Rules
+
+### 1. Lead with the next action
+
+The first line is something the reader can do. Not context. Not a plan. The action.
+
+Bad: "Let's think about this. Your auth flow has a few moving pieces..."
+Good: "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
+
+If the answer is a command, path, or snippet, it goes first. Prose comes after, if at all.
+
+### 2. Number multi-step tasks
+
+If the work takes more than one step, write a numbered list. Each step is one bounded action. No step contains "and then" twice.
+
+Use the fewest steps that still work. Cut any step the reader does not need, and fold trivial steps into the one before. A short path finished beats a complete path abandoned.
+
+Bad: "First open the file, find the function, swap it out, then run the tests."
+
+Good:
+```
+1. Open `src/auth.ts`
+2. Replace `verifyToken` (lines 42 to 58) with the snippet below
+3. Run `npm test -- auth.spec.ts`
+```
+
+### 3. End with one concrete next action
+
+If anything is left open, name ONE thing the reader can do in under two minutes. Even "open the file" counts.
+
+Bad: "Hope that helps. Let me know if you want to dig deeper."
+Good: "Next: run `npm test` and paste the first failing line."
+
+### 4. Suppress tangents
+
+If a second issue exists, finish the first, then offer the second as a separate question.
+
+Bad: "Here's the fix. By the way, your dependency is also stale, and your README is out of date, and..."
+Good: "Here's the fix. Separately: there is also a stale dependency. Want me to handle that next?"
+
+A question that comes up mid-work is not a tangent: answer it yourself if you can and fold the result in. If it still needs the reader, surface it once, at the end.
+
+### 5. Restate available state in this response
+
+The reader cannot hold "we are on step 3 of 5" between messages. Restate it.
+
+Bad: "Done. Ready for the next part?"
+Good: "Step 3 of 5 done: schema updated. Next: backfill the new column. Run the script?"
+
+If the harness has a task or plan tool, use it for multi-step work: one item per step, one in progress at a time. The checklist does the restating; do not also narrate the full plan as prose.
+
+### 6. Give specific time estimates
+
+Vague estimates fail. Ballpark in concrete units.
+
+Bad: "This will take some work."
+Good: "About 15 minutes if tests already cover this. An afternoon if not."
+
+### 7. Make completed work visible
+
+Show what now works, in concrete terms. Do not bury wins in a recap.
+
+Bad: "I've made some changes to the auth flow. Among other things..."
+Good: "Login now works with magic links. Try: `npm run dev`, open `/login`."
+
+### 8. Matter-of-fact tone for errors
+
+Never use "Uh oh," "Oh no," or "There seems to be a problem." State cause and fix.
+
+Bad: "Uh oh, the test is failing. There seems to be an issue..."
+Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request."
+
+### 9. Cap lists at 5 items
+
+If a list grows past five, split into "do now" vs "later," or "must" vs "nice to have." Five items ranked beats ten unranked.
+
+### 10. No preamble, no recap, no closing pleasantries
+
+Forbidden openers: "Great question," "Let me...", "I'll...", "Sure!", "Looking at your...", "To answer your question..."
+
+Forbidden recaps after a completed task: "I've now done X, Y, and Z, which means..."
+
+Forbidden closers: "Let me know if you need anything else," "Hope this helps," "Happy to clarify," "Feel free to ask."
+
+Start with the answer. End when the answer is done.
+
+## When to break the rules
+
+Override the defaults when:
+
+1. User asks to "explain" or "walk me through." Explain fully. Still no preamble, still no closer, but the body runs as long as the topic needs. Add headers so the reader can skim back.
+2. Destructive action ahead (`rm -rf`, force push, schema migration, dropping a table). Confirm before acting. Safety wins over brevity.
+3. Debug spiral. If the last three turns have been "still broken," stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question.
+4. Real ambiguity in the request. One short clarifying question beats guessing and rewriting.
+5. A rule fights the task. When a rule would delete the answer itself, the task wins; the shape stays. Example: "what are my options" gets 2 to 4 ranked options with one-line trade-offs, recommendation first, not one path. The options are the answer.
+6. A rule fights the harness. Inside an agent harness, the system prompt outranks this skill: announce a tool call when the harness requires it, do the work instead of asking "want me to," point time estimates at whoever executes the steps. Same principle as 5: the constraint wins, the shape stays.
+
+## Pre-send check
+
+Before sending, delete:
+
+1. The first sentence if it announces what you are about to do.
+2. The last sentence if it asks "anything else?" or recaps what just happened.
+3. Any "by the way" sidebar.
+4. Any hedging adverb adding no information ("perhaps," "might," "could possibly"). Keep a hedge that carries real uncertainty; deleting it manufactures confidence.
+5. Any idiom or figurative phrase ("circle back," "get the ball rolling," "on the same page"). Replace with the literal action.
+
+Then verify: if the reader reads only the first line and the last line, do they know (a) what to do next, and (b) what just happened?
+
+If yes, send.

package/assets/skills/i-have-adhd/SOURCE.md

@@ -0,0 +1,9 @@
+# 来源说明
+
+- 上游仓库：<https://github.com/ayghri/i-have-adhd>
+- 上游路径：`skills/i-have-adhd/SKILL.md`
+- 许可：MIT License。
+- 核验基准：2026-09-07 核验上游 `main` commit `58494af57962b2d7a996b4d419474380a299af5e`。
+- 随包保留的许可全文：[LICENSE.md](LICENSE.md)
+
+随包 instruction 对 harness 生效范围和 metadata 做了本地适配，不声称与当前上游逐字相同。

package/assets/skills/i-have-adhd/agents/gemini.toml

@@ -0,0 +1,24 @@
+# Gemini CLI custom command for i-have-adhd.
+# Install: copy to ~/.gemini/commands/i-have-adhd.toml, then type /i-have-adhd.
+# Self-contained so it works as a global command from any directory.
+
+description = "ADHD-friendly output: action-first, numbered steps, no preamble or closers."
+
+prompt = """
+For the rest of this session, shape every response for a reader with ADHD. The output is not just brief; it is shaped so an ADHD brain can act on it.
+
+1. Lead with the next action. The first line is a command, path, or snippet the reader can run, not context, not a plan.
+2. Number multi-step work. One bounded action per step; no step with two "and then"s.
+3. End with one concrete next action the reader can do in under two minutes.
+4. Suppress tangents. Finish the current issue first; fold self-resolved questions into the answer, surface still-open ones once at the end.
+5. Restate state every turn ("Step 3 of 5 done: schema updated. Next: backfill the column.").
+6. Give time estimates in concrete units (minutes, hours), never "a bit" or "some work".
+7. Make completed work visible in concrete terms ("Login works with magic links. Try: npm run dev").
+8. State errors matter-of-factly: cause, then fix. No "uh oh" or "there seems to be a problem".
+9. Cap lists at 5 items; split into now/later or must/nice-to-have if longer.
+10. No preamble, no recap, no closing pleasantries. Start with the answer; end when it is done.
+
+Break these rules only when: the reader asks you to "explain" or "walk through" (go as long as the topic needs, still no preamble/closer); a destructive action is ahead (confirm first; safety beats brevity); you are in a debug spiral (name the assumption that might be wrong, ask one diagnostic question); or the request is genuinely ambiguous (ask one short clarifying question); or the harness's own system prompt requires something these rules ban (the harness wins; keep the shape).
+
+{{args}}
+"""

package/assets/skills/i-have-adhd/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "I Have ADHD"
+  short_description: "Action-first output for ADHD readers"
+  default_prompt: "Use $i-have-adhd to make this response action-first and easy to execute."
+
+policy:
+  allow_implicit_invocation: true

package/assets/skills/improve-codebase-architecture/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/assets/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,44 @@
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/assets/skills/improve-codebase-architecture/LANGUAGE.md

@@ -0,0 +1,53 @@
+# Language
+
+Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+## Terms
+
+**Module**
+Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
+_Avoid_: unit, component, service.
+
+**Interface**
+Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+
+**Implementation**
+What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**
+Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(from Michael Feathers)_
+A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+_Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter**
+A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage**
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+**Locality**
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

package/assets/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: improve-codebase-architecture
+description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+license: MIT
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+## Glossary
+
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+
+- **Module** — anything with an interface and an implementation (function, class, package, slice).
+- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
+- **Implementation** — the code inside.
+- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth.
+- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+
+Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+
+- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.**
+- **One adapter = hypothetical seam. Two adapters = real seam.**
+
+This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+Read the project's domain glossary and any ADRs in the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
+
+**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Follow the repository's domain-doc rules in `docs/agents/domain.md`, and add the term to the configured `CONTEXT.md`. Create it lazily only when that contract permits.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. Follow the repository's ADR rules and location recorded in `docs/agents/domain.md`.
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

package/assets/skills/improve-codebase-architecture/SOURCE.md

@@ -0,0 +1,3 @@
+# 来源说明
+
+本技能是 `mattpocock/skills` 中 `skills/engineering/improve-codebase-architecture/` 的本地适配快照。统一来源、核验 commit 与 MIT 许可全文见 [setup-matt-pocock-skills/SOURCE.md](../setup-matt-pocock-skills/SOURCE.md) 和 [setup-matt-pocock-skills/LICENSE.md](../setup-matt-pocock-skills/LICENSE.md)。

package/assets/skills/lossless-document-authoring/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: lossless-document-authoring
+description: 将整本书或长文无损导入 WorldEngine，在无向量编辑态维护原文图，恢复既有抽取，或核验提审、D4F 审核、质量封分及原文证据。用于全文入库、checkpoint、review-ready 生命周期、图谱证据与字符守恒验证；普通 View 编码不使用。
+license: LicenseRef-WorldEngine-Project
+---
+
+# 无损长文创作
+
+保留完整 source authority，并把编辑态、提审产物、审核与发布明确分层。原文 bytes 和 `source_document` 是 authority；segments、nodes、edges、embedding、审核结果与答案都是派生层，不能用摘要替代原文。
+
+## 选择动作
+
+- 新来源或新 revision：先读取 `docs/authoring/development/cli.md` 和 `docs/authoring/development/authoring-workflows.md`，Windows 用 `.\worldengine.cmd --help` 读取当前合同。全新来源依据 manifest 的 `local_scenario_id` 与规范化项目相对路径稳定推导 CLI identity，不让作者理解内部参数；已有 identity 冲突且 readback 无法消歧时才问。首个 `ingest` 在 stdout 返回 `{ receipt, next }`；harness 处理 `next.request.structuredRequest.messages`，输出遵守其 `jsonSchema`，把项目内不超过 8 MiB 的 candidate JSON 交给 `accept`，循环 `next`，ready 后 `commit`。Host 不重打 raw bytes，只保存最终成书内容，不记录讨论或废案。
+- 外部原文路径：把绝对 `.txt/.md/.markdown` 路径直接交给 `ingest`；Host 单一入口以打开文件句柄复核 path/inode/大小/读取期变化，逐字节复制到 `.worldengine/imported-sources/<content-hash>.<ext>`，返回物理 `sourceStoragePath` 与稳定逻辑 `external-source/<path-hash>.<ext>`。最终 `world_source_document` 同时保留 logical path、storage path、raw bytes、长度和 SHA-256；content hash 不参与初始 source identity，外部原件不改写、不执行。多轮讨论可逐项确认人物、关系和取舍，但不会写 DB；只有明确成稿/生成/写入意图触发 `ingest`，并在每个最终 candidate 经 `accept` 后由显式 `commit` 一次性写入。
+- 聊天式渐进编辑：只使用 runtime 实际公开的 schema/read/apply/readback 更新同一中性作者源及 raw graph，不把原文摘要化，也不因每次编辑调用 embedding；内容变化按产品 source identity 形成新 revision。
+- 已中断或失败：`ingest status <operation-id>` 读取 checkpoint，再用 `ingest resume <operation-id>` 恢复；ready 时 resume 直接 commit，否则返回下一条 request。operation ID 复制自 Host 的回执；旧 provider journal 没有 adapter 时明确失败，不能静默迁移、清空 checkpoint 或伪造 candidate。
+- 向量准备与查书：`recall prepare [scope-id]` 只要求产品登录后的本机 `127.0.0.1:11450` 账户模型代理，并按账户余额结算；它不要求 ProjectAuthBroker。Agent Kit 不分发或要求配置 DeepSeek/OpenRouter provider key。独立本地向量准备、混合检索与多跳查询只消费当前 schema 已公开的接口与回执。
+- 提审与远端状态：只有当前 CLI help 明确列出相应 review 入口，且桌面为该 `project_id` 注入有效 ProjectAuthBroker capability 时才执行；不要把这项远端权限错误地设为本地 `recall prepare` 的前置条件。
+- 回答文档问题：先告诉用户 semantic 检索需要登录，`recall prepare [scope-id]` 按账户余额计费；准备当前 revision 后再 `ask <scope-id> <query>`。外部 harness 路径只收到 `candidates`、`graphPaths`、`pathOptions`、`evidence` 等证据 bundle，须自行基于证据回答；没有闭合证据就明确不可回答。
+- 导出供人或 LLM 审阅：`.\worldengine.cmd dump <document-id> <output-relative-dir>`，从已提交 document 的同源 readback 导出原始文本、当前已提交图与计数清单。输出必须是项目内尚不存在的新目录；dump 不调用模型、不需要凭据，也不代表审核完成。
+- 检查事实或关系：使用 exact-21 的 `world_search`、`world_get`、`world_traverse` 或当前 CLI 包装；修改只经 `world_apply`。不存在任意 Cypher/SQL 或额外公开 Tool。
+
+## 判定边界
+
+- `prepare` 只证明本地冻结完成；`submit` 返回 `pending_review` 只证明已提审。只有审核与质量封分的实际 readback 才能称 ready，review 仍不等于 publish。
+- `sourceCoverage.status=complete` 不等于已入图；`graphStatus=partial` 不能称完整图。新编辑态图完整时 embedding 仍可为 pending；只有 review-ready 才要求向量 provider/model/dimension/text identity 全部闭合。
+- D4F 审核必须消费冻结 artifact 的全部可理解业务字段及同源原文证据，不得用摘要、标签、抽样原文或可变 ScenarioRecord 替代。分块结果不自动证明跨块一致性。
+- `quality_factor`/`llm_bias_factor` 的 `0` 是合法审核结果，`1` 也可以表示没有严重质量问题；未知、缺失、拒绝或 provider 失败既不是 `0` 也不是 `1`，且不得封存静态系统分。编辑期估值、审核静态分与玩家/榜单混合分不得混标。
+- Trigger/GUI 的成功必须由真实工具/CAS 和已提交投影 readback 证明；界面通知、preview、旧内存数组或候选预筛都不是保存或触发成立的证据。
+- 生产 Trigger 当前只具备 `logical_seq` 与 `world_time` 时钟；`presentation_seq`/`real_time` 会在 production compile 被拒绝。simulation 可选四域只证明模拟器输入能力，不能冒充生产时间源。
+- Desktop 可展示本地结构分，但未取得正式审核回执时 quality factor 保持 `null`，不能用默认值封分。平台 tag 比较必须由已认证且已绑定 scenario 的正式 caller 提供；未绑定不推断基准。
+
+## 不变量
+
+- LLM 规划只引用稳定 unit ID 来组成 segments；抽取输出 node/edge，parents、aliases 与 evidence 保留在 metadata/provenance 中。
+- “path” 是图中的事实链，不是文件路径或相似结果列表；必须保留每条边的 `src`、`dst` 与关系方向，即使检索从入边或双向展开也不能倒置事实。每一跳都必须引用可读回的原文 evidence。
+- v4 的否定 edge 使用正向 canonical predicate，并显式保留 negation qualifier。展示、检索或冲突分析尚未真实读回正确否定语义时，不能把否定事实当作正向事实；也不能只靠谓词文字猜极性。
+- 相关内容不等于足以回答。缺少方向、实体消歧或任一跳 evidence 时返回证据不足，并指出缺口。
+- 原始 source bytes 100% 守恒是硬要求；语义文字短不直接证明原文字节丢失，原文完整复现也不证明图谱穷尽。语义质量须另看实体、边、断言及去重证据覆盖，不能用引用或 ID 膨胀充当理解量。
+- 原文 bytes、窗口覆盖、结构化抽取完整度、向量覆盖与质量审核是彼此独立的证据层；任何一层通过都不能替另一层背书。
+- 可上传、可提审、抽取完整与质量状态只以本项目当前 receipt/readback 和已安装版本公开的容量门为准。局部运输实验或未落地的 chunk transport 不能写成 production 可用能力，也不能越过实际容量/身份/回执门声称成功。
+- 坏 window 保留 checkpoint 与失败状态。已落盘的抽取或 embedding 可复用；未落盘的在途请求可能重试，不承诺远程请求绝对只执行一次。
+- 不读取、索取、打印、传递、比较或写入 provider key，也不读取/复制 `.env`；不得引导用户配置 DeepSeek/OpenRouter key。
+
+执行整本 ingest、resume、status、ask、dump 或 review 前，读取 [D4F 工作流](references/d4f-workflow.md)。CLI 参数以当前 `.\worldengine.cmd --help` 为准；Skill 不复制机械 schema、CAS 或 checkpoint transition。