feat: establish workspace resolution boundary

.gitignore

@@ -9,6 +9,7 @@ coverage/
 .codex/
 .echopath/
 .opendomain/
+/opendomain/generated/
 /AGENTS.md
 /openspec/
 .npmrc

CONTRIBUTING.md

@@ -42,7 +42,8 @@ Keep the layers separate:
 - Run `npm run opendomain -- validate`.
 - Add or update tests for parser, validator, CLI, or index behavior changes.
 - Update docs when commands, formats, or workflow expectations change.
-- Do not commit generated `.opendomain/` indexes.
+- Do not treat `opendomain/generated/` or legacy `.opendomain/index.json`
+  as authoritative domain knowledge.
 
 ## Planning Artifacts
 

README.md

@@ -47,7 +47,8 @@ This workspace now includes the first MVP slices:
 - OpenSpec `affects_domain` grounding
 - Domain Candidate boundary checks
 - Semantic Retrieval Index as a derived read-first view
-- OpenDomain dogfooding under `domain/`
+- Deterministic workspace resolution with canonical `opendomain/` sources
+- OpenDomain dogfooding under `opendomain/`
 
 The source of truth remains Markdown with YAML front matter stored in Git.
 
@@ -60,7 +61,7 @@ Install the CLI from npm:
 ```bash
 npm install -g @echopath-labs/opendomain
 opendomain init
-opendomain validate domain
+opendomain validate
 ```
 
 Or try it from a source checkout:
@@ -71,15 +72,20 @@ Common commands:
 npm run opendomain -- help
 npm run opendomain -- init
 npm run opendomain -- validate
-npm run opendomain -- prepare examples/erp/openspec/changes/order-cancellation/spec.md
-npm run opendomain -- prepare --integration openspec examples/erp/openspec/changes/order-cancellation/spec.md
+npm run prepare:demo
 npm run opendomain -- candidate list examples/erp
 npm run opendomain -- candidate show candidate-0001-order-lifecycle examples/erp
 npm run opendomain -- index build examples/erp --out /tmp/erp-index.json
 npm run opendomain -- index query sales.order --index /tmp/erp-index.json
 npm test
 ```
 
+Commands without a source path resolve the current project's canonical
+`opendomain/` workspace. During `0.x`, a legacy `domain/` workspace remains
+readable when the canonical root is absent. If both exist, `opendomain/` wins
+with a warning; the roots are never merged. Pass a file or directory explicitly
+when validating a fixture or external corpus such as `examples/erp`.
+
 ## Project Status
 
 OpenDomain is early alpha. The current repository is ready for public iteration,
@@ -111,7 +117,7 @@ License: MIT.
 │   ├── grounding-protocol.md
 │   ├── candidate-workflow.md
 │   └── decisions/
-├── domain/
+├── opendomain/
 │   └── README.md
 ├── examples/
 │   └── erp/
@@ -146,11 +152,11 @@ See [docs/semantic-retrieval-index.md](docs/semantic-retrieval-index.md).
 
 ## Dogfooding
 
-OpenDomain now models part of its own product semantics under `domain/`.
+OpenDomain now models part of its own product semantics under `opendomain/`.
 
 ```bash
-npm run opendomain -- validate domain
-npm run opendomain -- prepare domain/openspec/changes/self-model-maintenance/spec.md
+npm run opendomain -- validate
+npm run opendomain -- prepare examples/self-model/openspec/changes/self-model-maintenance/spec.md
 ```
 
 See [docs/dogfooding-self-model.md](docs/dogfooding-self-model.md).
@@ -159,7 +165,7 @@ See [docs/dogfooding-self-model.md](docs/dogfooding-self-model.md).
 
 Use this rule when preserving planning:
 
-- `domain/`: long-lived OpenDomain semantics
-- `domain/candidates/`: proposed or inferred semantics
+- `opendomain/`: long-lived OpenDomain semantics
+- `opendomain/candidates/`: proposed or inferred semantics
 - a project's optional `openspec/changes/`: future delivery work
 - `docs/`: narrative explanation and product guidance

README.zh-CN.md

@@ -103,6 +103,7 @@ OpenDomain 适合：
 - OpenSpec `affects_domain` grounding；
 - Candidate 边界检查；
 - Semantic Retrieval Index，作为派生的 read-first 检索视图；
+- 以 canonical `opendomain/` 为入口的确定性工作区解析；
 - ERP Order Cancellation 示例；
 - OpenDomain 自己的 self-model dogfooding。
 
@@ -130,7 +131,7 @@ OpenDomain 的 npm 包名是 `@echopath-labs/opendomain`，CLI 命令是 `opendo
 ```bash
 npm install -g @echopath-labs/opendomain
 opendomain init
-opendomain validate domain
+opendomain validate
 ```
 
 也可以从源码运行。
@@ -175,7 +176,7 @@ npm run opendomain -- validate examples/erp
 为一个 Feature 准备 Codex grounding：
 
 ```bash
-npm run opendomain -- prepare examples/erp/openspec/changes/order-cancellation/spec.md
+npm run prepare:demo
 ```
 
 构建并查询 Semantic Retrieval Index：
@@ -189,10 +190,10 @@ npm run opendomain -- index query sales.order --index /tmp/erp-index.json
 
 ### 1. 写长期业务语义
 
-把长期成立的业务知识写入 `domain/` 或 `examples/<name>/domain/`：
+把长期成立的业务知识写入项目根目录的 `opendomain/`：
 
 ```text
-domain/
+opendomain/
   contexts/
   concepts/
   rules/
@@ -201,6 +202,14 @@ domain/
   candidates/
 ```
 
+不传 source path 时，CLI 会从当前项目根目录解析工作区：
+
+- 优先使用 canonical `opendomain/`；
+- 在 `0.x` 期间，只有 `domain/` 时会兼容读取并给出迁移提示；
+- 两个根目录同时存在时只读取 `opendomain/`，发出 warning，不合并语料；
+- 默认只读取六类语义目录，不扫描 `examples/`、`generated/` 或 integration 配置；
+- 验证示例、fixture 或外部语料时，需要显式传入文件或目录。
+
 例如 `sales.order` 应该说明 Order 在 Sales context 中是什么意思，它不是什么，它受哪些规则和生命周期约束，以及证据是什么。
 
 ### 2. 用 OpenSpec 引用 OpenDomain
@@ -259,7 +268,7 @@ extracted_by: codex
 extracted_at: 2026-07-07
 evidence:
   - type: spec
-    location: examples/erp/domain/lifecycles/sales.order-lifecycle.md
+    location: examples/erp/opendomain/lifecycles/sales.order-lifecycle.md
     summary: Accepted lifecycle does not include Closed state.
     confidence: medium
 possible_conflicts:
@@ -342,7 +351,7 @@ OpenDomain 目前是 early alpha。
 - 内部项目记忆；
 - 未经授权的业务文档或代码片段。
 
-如果你要在公司内部使用 OpenDomain，建议在私有仓库维护项目自己的 `domain/` 文件。
+如果你要在公司内部使用 OpenDomain，建议在私有仓库维护项目自己的 `opendomain/` 文件。
 
 ## 贡献
 

ROADMAP.md

@@ -11,7 +11,7 @@ human maintainers.
 - OpenSpec `affects_domain` grounding
 - Domain Candidate boundary checks
 - Semantic Retrieval Index as a derived read-first view
-- OpenDomain self-model dogfooding under `domain/`
+- OpenDomain self-model dogfooding under `opendomain/`
 
 ## Near-Term Work
 

docs/OPEN_DOMAIN_DEVELOPMENT_GUIDE.md

@@ -592,7 +592,7 @@ Codex 在 Greenfield 开发时，可采用以下结构作为初始建议。
 │   ├── architecture.md
 │   └── decisions/
 │       └── ADR-0001-git-native-markdown-first.md
-├── domain/
+├── opendomain/
 │   ├── contexts/
 │   │   └── sales.md
 │   ├── concepts/
@@ -1104,7 +1104,7 @@ OpenDomain CLI 应该简单、确定、适合 CI。
 
 ```bash
 opendomain validate
-opendomain validate domain/concepts/sales.order.md
+opendomain validate opendomain/concepts/sales.order.md
 opendomain graph export --format json
 opendomain candidate validate
 opendomain ids list
@@ -1439,10 +1439,10 @@ Create:
 - schemas/rule.schema.json
 - schemas/lifecycle.schema.json
 - schemas/candidate.schema.json
-- examples/erp/domain/concepts/sales.order.md
-- examples/erp/domain/rules/sales.confirmed-order-cannot-be-deleted.md
-- examples/erp/domain/lifecycles/sales.order-lifecycle.md
-- examples/erp/domain/candidates/candidate-0001-order-lifecycle.md
+- examples/erp/opendomain/concepts/sales.order.md
+- examples/erp/opendomain/rules/sales.confirmed-order-cannot-be-deleted.md
+- examples/erp/opendomain/lifecycles/sales.order-lifecycle.md
+- examples/erp/opendomain/candidates/candidate-0001-order-lifecycle.md
 
 Keep schemas minimal but valid.
 Make examples human-readable and machine-parseable.

docs/architecture.md

@@ -24,13 +24,19 @@ Derived graph, index, search, MCP, or export views
 
 The source of truth is the set of OpenDomain files in Git:
 
-- `domain/` for project domain knowledge
+- `opendomain/` for canonical project domain knowledge
 - `examples/` for illustrative fixtures
 - `schemas/` for machine validation
 
 Derived views are not authoritative. A graph export, search index, embedding
 index, generated docs site, or MCP resource must be rebuildable from Git files.
 
+Commands without an explicit source target resolve only the current project's
+canonical `opendomain/` semantic directories. During `0.x`, legacy `domain/`
+remains a warning-producing fallback when the canonical root is absent. Dual
+roots are never merged. Explicit targets are available for examples, fixtures,
+and external corpora.
+
 The first derived retrieval view is documented in
 `docs/semantic-retrieval-index.md`.
 

docs/decisions/ADR-0007-non-destructive-workspace-migration.md

@@ -6,7 +6,7 @@ Accepted
 
 ## Context
 
-OpenDomain alpha releases use `domain/` for semantic sources and
+Earlier OpenDomain alpha releases used `domain/` for semantic sources and
 `.opendomain/index.json` for a generated index. Moving to canonical
 `opendomain/` must not make existing knowledge disappear or let tooling delete
 or overwrite user files.
@@ -17,15 +17,17 @@ Throughout `0.x`, OpenDomain falls back to legacy `domain/` when canonical
 `opendomain/` is absent. If both roots exist, canonical `opendomain/` wins with
 an explicit warning.
 
-`opendomain migrate workspace` copies and validates source files and Candidates
-without overwriting targets, deleting legacy content, changing Git state, or
-editing ignore rules. Legacy generated indexes are rebuilt rather than copied.
-Legacy discovery may only be removed in `1.0` with documented migration
-guidance.
+The current version provides discovery fallback only; it does not expose an
+automatic migration command. If a migration command is introduced later, it
+must copy and validate source files and Candidates without overwriting targets,
+deleting legacy content, changing Git state, or editing ignore rules. Legacy
+generated indexes must be rebuilt rather than copied. Legacy discovery may only
+be removed in `1.0` with documented migration guidance.
 
 ## Consequences
 
 - Existing alpha users retain access to their business model.
 - Migration remains reversible because legacy files are preserved.
 - Dual roots are deterministic but produce a visible warning.
 - The CLI carries a legacy discovery path until `1.0`.
+- Maintainers perform the current source move manually and review the Git diff.

docs/dogfooding-self-model.md

@@ -3,16 +3,16 @@
 OpenDomain should use its own format to model its own long-lived product
 semantics.
 
-This is the first real `domain/` model in the repository. The ERP files under
-`examples/` remain examples; the OpenDomain self model under `domain/` is actual
-project knowledge.
+This is the first real `opendomain/` model in the repository. The ERP files under
+`examples/` remain examples; the OpenDomain self model under `opendomain/` is
+actual project knowledge.
 
 ## Boundary
 
 Use the repository layers this way:
 
-- `domain/`: long-lived OpenDomain product semantics
-- `domain/candidates/`: proposed OpenDomain semantics awaiting human review
+- `opendomain/`: long-lived OpenDomain product semantics
+- `opendomain/candidates/`: proposed OpenDomain semantics awaiting human review
 - a maintainer's private `openspec/changes/`: change intent, design, tasks, and acceptance
 - `docs/`: PRD, architecture, and development guidance
 - `examples/`: external example domains
@@ -54,8 +54,8 @@ Proposed self-model Candidate:
 
 Use this split when preserving planning output:
 
-- Put stable OpenDomain semantics in `domain/`.
-- Put uncertain inferred semantics in `domain/candidates/`.
+- Put stable OpenDomain semantics in `opendomain/`.
+- Put uncertain inferred semantics in `opendomain/candidates/`.
 - Put delivery plans in a private planning workspace such as `openspec/changes/`.
 - Put explanatory narrative in `docs/`.
 
@@ -79,7 +79,7 @@ This is now accepted self-model knowledge through:
 Before changing OpenDomain's own domain semantics, run:
 
 ```bash
-npm run opendomain -- prepare domain/openspec/changes/self-model-maintenance/spec.md
+npm run opendomain -- prepare examples/self-model/openspec/changes/self-model-maintenance/spec.md
 ```
 
 This returns the accepted OpenDomain files to read first and the Candidate
@@ -90,7 +90,7 @@ boundary for the proposed Semantic Retrieval Index.
 Validate real OpenDomain self-model files:
 
 ```bash
-npm run opendomain -- validate domain
+npm run opendomain -- validate
 ```
 
 Run all tests:

docs/getting-started.md

@@ -4,7 +4,7 @@
 
 目标是在 10 分钟内完成三件事：
 
-1. 初始化 `domain/` 目录。
+1. 初始化 canonical `opendomain/` 目录。
 2. 验证生成的 OpenDomain 文件。
 3. 明确第一条真实业务知识应该如何进入模型。
 
@@ -33,7 +33,7 @@ opendomain init
 `opendomain init` 会创建：
 
 ```text
-domain/
+opendomain/
   README.md
   contexts/
     example.md
@@ -52,7 +52,7 @@ AGENTS.md
 ## 3. 验证生成结果
 
 ```bash
-opendomain validate domain
+opendomain validate
 ```
 
 通过验证只说明文件格式和引用关系成立，不代表这些 starter 内容已经是你的真实业务知识。
@@ -97,7 +97,7 @@ ERP 示例展示了：
 - Agent 本轮工作记录；
 - 只从代码或数据库里猜出来、还没人确认的业务知识。
 
-如果你不确定，就先写入 `domain/candidates/`。
+如果你不确定，就先写入 `opendomain/candidates/`。
 
 可以用 CLI 浏览和记录 Candidate 审查结果：
 

docs/grounding-protocol.md

@@ -35,7 +35,7 @@ metadata 会继续输出，但 consumer 不应依赖它们作为 Grounding Proto
 protocol_version: "1.0"
 source:
   type: openspec
-  path: examples/erp/openspec/changes/order-cancellation/spec.md
+  path: openspec/changes/order-cancellation/spec.md
 intent:
   id: spec.order-cancellation
   name: Order cancellation
@@ -68,11 +68,13 @@ Grounding Request 只引用 OpenDomain ID，不复制业务定义，也不代表
 使用 JSON 输出：
 
 ```bash
-npm run opendomain -- prepare \
-  examples/erp/openspec/changes/order-cancellation/spec.md \
-  --json
+cd examples/erp
+opendomain prepare openspec/changes/order-cancellation/spec.md --json
 ```
 
+`prepare` resolves accepted OpenDomain sources from the current project
+workspace, so it must run from the project that owns the Feature spec.
+
 ## Semantic Closure
 
 Grounding Request 中的 `affects_domain` 是 declared roots。OpenDomain 使用

docs/mvp-grounding-demo.md

@@ -50,7 +50,7 @@ npm run opendomain -- validate examples/erp
 Prepare the Codex grounding pack for the feature:
 
 ```bash
-npm run opendomain -- prepare examples/erp/openspec/changes/order-cancellation/spec.md
+npm run prepare:demo
 ```
 
 Validate with machine-readable output:
@@ -62,7 +62,8 @@ npm run opendomain -- validate examples/erp --json
 Prepare with machine-readable output:
 
 ```bash
-npm run opendomain -- prepare examples/erp/openspec/changes/order-cancellation/spec.md --json
+cd examples/erp
+node ../../bin/opendomain.mjs prepare openspec/changes/order-cancellation/spec.md --json
 ```
 
 List known IDs: