feat: add declarative Profile Runtime v1

.github/workflows/ci.yml

@@ -29,3 +29,6 @@ jobs:
 
       - name: Validate OpenDomain
         run: npm run opendomain -- validate
+
+      - name: Run installed-package smoke
+        run: npm run smoke:package

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+- Add repository-local declarative Integration Profile v1 for structured
+  planning sources beyond the built-in OpenSpec adapter.
+- Add safe file and bundle Source Units, Native Mapping, strict Sidecar Domain
+  Declaration, and deterministic explicit or automatic adapter selection.
+- Add `opendomain integrations list`, `opendomain integrations validate`, and
+  `opendomain prepare --profile <id>`.
+- Add Profile-aware initialization, ERP examples, package installation smoke
+  coverage, and complete usage documentation.
+
 ## 0.1.0-alpha.5 - 2026-07-23
 
 - Harden YAML front matter parsing with deterministic YAML 1.2 policy checks

README.md

@@ -45,6 +45,10 @@ This workspace now includes the first MVP slices:
 - CLI commands for project init, validation, ID listing, reference checks,
   grounding, indexing, and demo
 - OpenSpec `affects_domain` grounding
+- Declarative repository-local Integration Profiles for structured non-OpenSpec
+  sources, with Native Mapping and Sidecar Domain Declaration
+- Deterministic file or bundle Source Units and explicit or automatic Profile
+  selection
 - Domain Candidate boundary checks
 - Semantic Retrieval Index as a derived read-first view
 - Deterministic workspace resolution with canonical `opendomain/` sources
@@ -73,6 +77,8 @@ npm run opendomain -- help
 npm run opendomain -- init
 npm run opendomain -- validate
 npm run prepare:demo
+npm run opendomain -- integrations validate
+npm run opendomain -- integrations list
 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
@@ -96,6 +102,7 @@ Useful entry points:
 - [Getting started](docs/getting-started.md)
 - [Usage guide](docs/usage.md)
 - [Grounding Protocol v1](docs/grounding-protocol.md)
+- [Integration Profile guide](docs/integration-profiles.md)
 - [Roadmap](ROADMAP.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
@@ -115,9 +122,11 @@ License: MIT.
 │   ├── glossary.md
 │   ├── architecture.md
 │   ├── grounding-protocol.md
+│   ├── integration-profiles.md
 │   ├── candidate-workflow.md
 │   └── decisions/
 ├── opendomain/
+│   ├── integrations/profiles/
 │   └── README.md
 ├── examples/
 │   └── erp/

README.zh-CN.md

@@ -99,8 +99,12 @@ OpenDomain 适合：
 - Bounded Context、Domain Concept、Business Rule、Lifecycle、Domain Event、Domain Candidate；
 - 安全 parser 和 Draft 2020-12 Runtime Schema 校验；
 - 在 Semantic Closure、index 和 grounding 前执行安全语料门禁；
-- CLI 命令：init、validate、ids list、refs check、prepare、index、demo；
+- CLI 命令：init、validate、ids list、refs check、prepare、integrations、
+  index、demo；
 - OpenSpec `affects_domain` grounding；
+- 面向结构化非 OpenSpec 来源的 repository-local 声明式 Integration Profile；
+- Native Mapping、Sidecar Domain Declaration，以及确定性的 file / bundle
+  Source Unit；
 - Candidate 边界检查；
 - Semantic Retrieval Index，作为派生的 read-first 检索视图；
 - 以 canonical `opendomain/` 为入口的确定性工作区解析；
@@ -200,6 +204,8 @@ opendomain/
   lifecycles/
   events/
   candidates/
+  integrations/
+    profiles/
 ```
 
 不传 source path 时，CLI 会从当前项目根目录解析工作区：
@@ -244,6 +250,20 @@ OpenSpec 描述这次变更，OpenDomain 描述长期语义。
 npm run opendomain -- prepare <feature-spec-or-dir>
 ```
 
+对于其他结构化规划格式，可以在
+`opendomain/integrations/profiles/` 中声明 repository-local Profile：
+
+```bash
+npm run opendomain -- integrations validate
+npm run opendomain -- integrations list
+npm run opendomain -- prepare --profile <profile-id> <structured-file-or-bundle>
+```
+
+未显式选择时，只有一个 built-in adapter 或 Profile 匹配才会继续；多重匹配会
+失败，不按优先级猜测。Profile 只归一化来源中明确存在的 intent 和 OpenDomain
+ID，不扫描正文、不推断 ID，也不创建或提升 Candidate。完整说明见
+[Integration Profile 使用指南](docs/integration-profiles.md)。
+
 输出会告诉 Codex：
 
 - `Read first`：先读哪些 accepted source files；
@@ -293,6 +313,9 @@ Candidate 不是 accepted truth。它只是待人类审查的提案。
 | 输出 JSON 验证结果 | `npm run opendomain -- validate examples/erp --json` |
 | 为 Feature 准备 grounding | `npm run opendomain -- prepare <feature-spec-or-dir>` |
 | 显式使用 OpenSpec integration | `npm run opendomain -- prepare --integration openspec <feature-spec-or-dir>` |
+| 列出 integration | `npm run opendomain -- integrations list` |
+| 验证 Integration Profile | `npm run opendomain -- integrations validate` |
+| 显式使用本地 Profile | `npm run opendomain -- prepare --profile <profile-id> <source-unit>` |
 | 列出 Candidate | `npm run opendomain -- candidate list examples/erp` |
 | 查看 Candidate | `npm run opendomain -- candidate show <candidate-id> examples/erp` |
 | 记录 Candidate review | `npm run opendomain -- candidate review <candidate-id> --decision rejected --reviewed-by <name> --reason <text> examples/erp` |
@@ -313,6 +336,7 @@ Candidate 不是 accepted truth。它只是待人类审查的提案。
 - [MVP PRD](docs/product-prd.md)
 - [架构说明](docs/architecture.md)
 - [Grounding Protocol v1](docs/grounding-protocol.md)
+- [Integration Profile 使用指南](docs/integration-profiles.md)
 - [Candidate 工作流](docs/candidate-workflow.md)
 - [Semantic Retrieval Index](docs/semantic-retrieval-index.md)
 - [MVP Grounding Demo](docs/mvp-grounding-demo.md)
@@ -332,6 +356,7 @@ OpenDomain 目前是 early alpha。
 - 运行 ERP 示例；
 - 验证 OpenDomain 文件格式；
 - 为 OpenSpec Feature 生成 grounding pack；
+- 用声明式 Profile 为其他结构化规划来源生成 grounding pack；
 - 用 index 生成 read-first plan；
 - 在本仓库中 dogfood OpenDomain 自身模型。
 

ROADMAP.md

@@ -7,24 +7,28 @@ human maintainers.
 
 - Markdown + YAML front matter source files
 - Parser and validator
-- CLI validation, ID listing, reference checks, grounding, and demo commands
+- CLI initialization, validation, Candidate review, indexing, grounding, and
+  integration inspection commands
 - OpenSpec `affects_domain` grounding
+- Declarative Integration Profile v1 with file and bundle Source Units, Native
+  Mapping, and Sidecar Domain Declaration
 - Domain Candidate boundary checks
 - Semantic Retrieval Index as a derived read-first view
+- Deterministic canonical and legacy workspace resolution
 - OpenDomain self-model dogfooding under `opendomain/`
 
 ## Near-Term Work
 
-1. Candidate review commands
-   - `opendomain candidate list`
-   - `opendomain candidate show <id>`
-   - stale Candidate review support
-
-2. Codex grounding CI
+1. Codex grounding CI
    - check `affects_domain` references
    - check grounding report shape
    - keep CI honest about what it can and cannot prove
 
+2. Integration consumer conformance
+   - validate Profile-generated Grounding Requests across external tools
+   - define EchoPath handoff and recovery consumption without protocol coupling
+   - add tool-specific examples only after the generic Profile contract holds
+
 3. OpenSpec archive and long-term recall
    - preserve change history
    - connect archived changes to current OpenDomain IDs

docs/architecture.md

@@ -15,7 +15,9 @@ CLI
   ↓
 Candidate workflow
   ↓
-OpenSpec reference checks
+Built-in adapters + declarative Integration Profile Runtime
+  ↓
+Grounding Request v1
   ↓
 Derived graph, index, search, MCP, or export views
 ```
@@ -37,6 +39,11 @@ 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.
 
+Repository-local Integration Profiles live under
+`opendomain/integrations/profiles/`. They are versioned configuration beside
+the semantic source, not accepted domain knowledge and not part of the default
+semantic corpus.
+
 The first derived retrieval view is documented in
 `docs/semantic-retrieval-index.md`.
 
@@ -78,6 +85,8 @@ OpenDomain optimizes for a stable Codex reading path:
 ```text
 OpenSpec affects_domain or code path hint
   ↓
+Built-in adapter or declarative Integration Profile
+  ↓
 Versioned Grounding Request
   ↓
 Shared Semantic Closure
@@ -95,9 +104,11 @@ It does not mean moving accepted facts into an index. Indexes and other derived
 views help Codex find files; OpenDomain Markdown files still decide truth.
 
 Grounding Protocol v1 defines the stable request-to-pack contract. Profile
-Runtime remains an optional format-normalization layer, and external consumers
-must not add tool-specific fields to the stable protocol. See
-`docs/grounding-protocol.md`.
+Runtime is the replaceable format-normalization layer: it resolves one bounded
+file or directory Source Unit and transports explicit structured intent and
+OpenDomain IDs. It does not infer, define, review, or promote domain knowledge.
+External consumers must not add tool-specific fields to the stable protocol.
+See `docs/grounding-protocol.md` and `docs/integration-profiles.md`.
 
 ## Planning Layers
 
@@ -145,9 +156,10 @@ promote proposed knowledge to accepted knowledge.
 
 Accepted knowledge requires evidence and human review metadata.
 
-## OpenSpec Integration
+## Integration Boundary
 
-OpenSpec may reference OpenDomain IDs through fields such as:
+The built-in OpenSpec adapter may reference OpenDomain IDs through fields such
+as:
 
 ```yaml
 affects_domain:
@@ -164,3 +176,9 @@ should explain what the business world means over time.
 
 OpenSpec should reference OpenDomain through IDs. It should not copy concept,
 rule, lifecycle, or event definitions into feature specs.
+
+Other planning tools may use repository-local declarative Profiles. Native
+Mapping reads explicit fields owned by the external format. Sidecar Mapping
+associates one strict Domain Declaration with a bounded directory Source Unit.
+Both produce the same Grounding Request v1 and neither changes accepted
+OpenDomain knowledge.

docs/getting-started.md

@@ -44,6 +44,9 @@ opendomain/
   events/
   candidates/
     candidate-0001-first-domain-model.md
+  integrations/
+    profiles/
+      README.md
 AGENTS.md
 ```
 
@@ -77,6 +80,7 @@ ERP 示例展示了：
 - accepted domain event；
 - proposed Domain Candidate；
 - OpenSpec `affects_domain` 如何引用 OpenDomain ID。
+- repository-local Integration Profile 如何映射非 OpenSpec 结构化来源。
 
 ## 5. 写第一条真实 Domain Concept
 
@@ -142,6 +146,18 @@ opendomain prepare --integration openspec <feature-spec-or-dir>
 
 Codex 应先读取输出中 `Read first` 列出的 accepted source files，并把 `Candidate boundaries` 视为 proposed knowledge。
 
+如果项目使用其他结构化规划格式，可以先查看和验证本地 Integration Profile：
+
+```bash
+opendomain integrations list
+opendomain integrations validate
+opendomain prepare --profile <profile-id> <structured-file-or-bundle>
+```
+
+Profile 位于 `opendomain/integrations/profiles/`，只把显式结构化字段归一化成
+Grounding Request，不从正文推断业务语义。参见
+[Integration Profile 使用指南](integration-profiles.md)。
+
 ## 7. 基本原则
 
 - OpenDomain 记录长期业务语义。

docs/grounding-protocol.md

@@ -16,6 +16,9 @@ OpenSpec / Spec Kit / other structured source
 Profile Runtime 负责格式适配，不属于稳定协议。Grounding Pack 也不是 source of
 truth；accepted OpenDomain Markdown 文件仍然决定业务语义。
 
+Profile 格式、Source Unit、Native Mapping 与 Sidecar Declaration 见
+[Integration Profile 使用指南](integration-profiles.md)。
+
 ## Version
 
 当前协议版本：