✨ feat: align syntax, intent clauses, and hole reports

.gitignore

@@ -23,3 +23,7 @@
 lcov.info
 *.profraw
 *.profdata
+
+# Local agent state
+.pi-lens/
+.spark/

ROADMAP.md

@@ -0,0 +1,122 @@
+# Spore Roadmap
+
+This is a living document in the **Spore implementation repository**. It
+describes what Spore intends to build, organized by system area.
+
+Design rationale and normative semantics live in the sibling
+[`spore-evolution`](../spore-evolution) repository. The vision states design
+principles, SEP-0000 owns review questions and process mechanics, and each
+section below links to the concrete SEPs that define _how_ and _why_.
+
+## Compiler core (`sporec`)
+
+Design basis: [SEP-0006](../spore-evolution/seps/SEP-0006-compiler-architecture.md)
+
+- Cranelift code generation behind a stable TypedHIR boundary
+- Incremental compilation keyed by signature, intent, property, realization,
+  evidence, and dependency provenance
+- End-to-end pipeline: Source -> Lex -> Parse -> Resolve -> TypeCheck -> Verify
+  -> Codegen -> Cranelift IR -> native
+
+## Signature, intent, and properties
+
+Design basis: [SEP-0001](../spore-evolution/seps/SEP-0001-core-syntax.md),
+[SEP-0006](../spore-evolution/seps/SEP-0006-compiler-architecture.md)
+
+- Base Signature parsing and canonicalization
+- Intent Signature parsing for `uses`, `budget`, and `properties`
+- Internal Claim construction from source properties
+- EvidenceRecord generation and storage
+
+## Hole system
+
+Design basis: [SEP-0005](../spore-evolution/seps/SEP-0005-hole-system.md)
+
+- Stabilize HoleReport protocol around typed absence
+- Project capability, budget, and property context into every report
+- Multi-hole atomic fill with cross-hole consistency checking
+- Agent fill-and-verify loop: propose -> validate -> review if flagged
+
+## Type system
+
+Design basis: [SEP-0002](../spore-evolution/seps/SEP-0002-type-system.md)
+
+- Inline generic bounds in type parameter lists
+- L0 refinement type enforcement for decidable predicates
+- L1 abstract interpretation propagation for value flow analysis
+- Type evidence emitted through the compiler evidence layer
+
+## Effect and capability system
+
+Design basis: [SEP-0003](../spore-evolution/seps/SEP-0003-effect-system.md)
+
+- Runtime effect handler dispatch
+- Capability-surface filtering for hole reports
+- Reference CLI platform: console, filesystem, network connect/listen,
+  environment, process spawning, clock, random, and exit
+- Reference web platform: HTTP server, request/response
+
+## Budget model
+
+Design basis: [SEP-0004 realization-shape budgets](../spore-evolution/seps/SEP-0004-cost-analysis.md)
+
+- Quantitative realization-shape constraints
+- Built-in budget fields for branches, nesting, recursion, parallelism, calls,
+  effects, and holes
+- Budget evidence emitted per checked realization
+
+## Concurrency
+
+Design basis: [SEP-0007](../spore-evolution/seps/SEP-0007-concurrency-model.md)
+
+- Runtime execution of structured concurrency primitives (`spawn`, `await`,
+  `parallel_scope`)
+- Compiler-enforced task lifetimes
+- Cancellation propagation
+- Budget-aware fan-out and nesting checks
+- Channel boundary checks
+
+## Module and package system
+
+Design basis: [SEP-0008](../spore-evolution/seps/SEP-0008-module-package-system.md)
+
+- Content-addressed package store
+- `spore.toml` plus generated lock data
+- Package discovery, search, and documentation generation
+- Provenance hashes for signatures, intents, properties, realizations, evidence,
+  and dependencies
+
+## Diagnostics and developer experience
+
+Design basis: [SEP-0006](../spore-evolution/seps/SEP-0006-compiler-architecture.md)
+
+- LSP server with completions, diagnostics, go-to-definition, hole integration
+- `spore watch` with real-time incremental diagnostics
+- `spore watch --json` NDJSON events for IDE and Agent consumption
+
+## Standard library
+
+Design basis: [SEP-0009](../spore-evolution/seps/SEP-0009-standard-library.md)
+
+- `spore.list`, `spore.map`, `spore.set`, `spore.str`, `spore.math`, `spore.ref`
+- Standard library properties for core operations
+- All further libraries as third-party packages
+
+## Self-hosting
+
+Design basis: [SEP-0006](../spore-evolution/seps/SEP-0006-compiler-architecture.md)
+
+- Partial self-hosting: parser, type checker, budget checker, and evidence
+  builder rewritten in Spore
+- Performance target: compiled output within 2x of equivalent Rust for compute-bound code
+- Formal language specification beyond design docs
+- Stability policy for signatures, holes, and evidence protocols
+
+## Long-term explorations
+
+These are not committed but may influence future design:
+
+- Distributed effect delegation with cryptographic attestation
+- Optional formal verification mode for safety-critical paths
+- Visual hole explorer for interactive dependency graph navigation
+- Cross-platform compilation: WASM, embedded, GPU via effect-gated backends

SPARK.md

@@ -23,7 +23,7 @@ Spore（孢子）从一个类比出发：一粒孢子携带完整蓝图，在适
 
 Spore 是一门编译型、通用目的的编程语言，目标是让**签名成为唯一的规范来源**。
 
-- 一个函数签名同时承载输入/输出类型、错误集、effect 声明、计算代价预算和 spec 断言——不需要在别处重复表达。
+- 一个函数签名同时承载输入/输出类型、错误集、effect 声明、实现形态预算和 properties——不需要在别处重复表达。
 - 带 hole 的程序合法编译，编译器为每个 hole 输出自包含的上下文报告，使"部分完成"成为正常的工作状态而非错误。
 - 编译器输出同时面向人和机器：同一份 Diagnostic IR 投影为终端文本、JSON 和 LSP 事件。
 - 模块以内容 hash 标识，无版本号，无钻石依赖冲突。
@@ -32,27 +32,27 @@ Spore 是一门编译型、通用目的的编程语言，目标是让**签名成
 
 - 希望在编码前先固化意图的开发者——先写签名与类型，再逐步实现。
 - 使用 AI Agent 辅助编程的团队——Agent 通过 HoleReport 获取精确上下文，完成结构化填洞。
-- 对副作用和计算代价敏感的场景——effect 和 cost 在签名层面显式声明并编译期验证。
+- 对副作用和实现形态敏感的场景——effect 和 budget 在签名层面显式声明并编译期验证。
 
 ## 核心原则
 
-1. **签名是重力中心** — 输入/输出、错误集、effect、代价预算、spec 全部在签名声明，函数体可以为空。
+1. **签名是重力中心** — 输入/输出、错误集、effect、预算、properties 全部在签名声明，函数体可以为空。
 2. **Hole 是协作点而非错误** — 带 hole 的程序编译成功；hole 是人、Agent、团队之间结构化协作的接口。
 3. **先架构后细节** — 自顶向下：先定签名与类型，编译器验证骨架，再按依赖顺序填洞。
 4. **编译器是文档助手** — 所有输出同时提供人类可读文本与机器可读 JSON，共享同一份 Diagnostic IR。
-5. **显式的 effect 与代价** — 每个副作用必须声明，每个计算代价可被编译期验证。从签名就能完整评估一个函数的影响。
+5. **显式的 effect 与预算** — 每个副作用必须声明，实现形态约束可被编译期验证。从签名就能完整评估一个函数的影响。
 6. **内容寻址取代版本号** — 签名 hash 决定接口兼容性，实现 hash 决定缓存，无 semver，无钻石依赖冲突。
 
 ## 能力地图（方向性）
 
-- **函数签名即规范**：`where` / `uses` / `cost` / `spec` 四个子句覆盖约束、effect、代价和行为断言。
-- **Hole 系统**：`?name` 语法；编译器按依赖图排序推荐填洞顺序；HoleReport 包含类型、可见绑定、可用 effect、代价预算、候选函数。
+- **函数签名即规范**：inline bounds / `uses` / `budget` / `properties` 覆盖类型约束、effect、预算和行为断言。
+- **Hole 系统**：`?name` 语法；编译器按依赖图排序推荐填洞顺序；HoleReport 包含类型、可见绑定、可用 effect、预算上下文、候选函数。
 - **Effect 系统**：内置 atomic effect（Console / FileRead / NetConnect 等）+ 自定义 effect 接口 + 聚合别名；`handle ... with ...` 词法作用域 handler。
-- **代价模型**：四维向量 `[compute, alloc, io, parallel]`；编译期抽象解释验证 ≤ 声明上界。
+- **预算模型**：命名的实现形态约束（分支、嵌套、递归、并行度、调用、effect、hole）；编译期按源码形态验证。
 - **内容寻址模块**：双 hash（sig hash / impl hash）驱动增量编译与缓存；禁止循环依赖。
 - **Platform 系统**：语言级概念，以普通包形态提供全部 IO effect handler；应用代码保持纯净；Platform 是唯一 FFI 表面。
 - **结构化并发**：`Spawn` 作为 effect，无 async/await 着色；`Channel[T]` 消息传递，无共享可变状态。
-- **双格式诊断**：Diagnostic IR 投影为默认文本 / `--json` / LSP adapter；统一错误码族（E / W / C / K / H / M）。
+- **双格式诊断**：Diagnostic IR 投影为默认文本 / `--json` / LSP adapter；统一错误码族（E / W / F / B / H / P / M）。
 - **编译器工具链**：`sporec`（无状态编译器）+ `spore`（有状态 Codebase Manager：依赖、lock、缓存、watch）。
 
 ## 成功信号
@@ -64,7 +64,8 @@ Spore 是一门编译型、通用目的的编程语言，目标是让**签名成
 
 ## 生态关系
 
-- **SEP 规范**：详细语义存放于 `spore-evolution/seps/`（SEP-0001 ~ SEP-0009），SPARK.md 只保留方向性描述。
+- **SEP 规范**：详细语义存放于 [`../spore-evolution/seps/`](../spore-evolution/seps/)（SEP-0001 ~ SEP-0009），SPARK.md 只保留方向性描述。
+- **实现路线**：[`ROADMAP.md`](ROADMAP.md) 跟踪编译器、工具链与标准库的实现计划，并链接对应 SEP。
 - **Backend**：Cranelift 为主（纯 Rust、快编译、原生 WASM）；LLVM 作为未来可选高性能后端。
 - **实现语言**：Rust（edition 2024，MSRV 1.95）；自举路线为纯计算组件逐步用 Spore 重写。
 
@@ -74,28 +75,28 @@ Spore 是一门编译型、通用目的的编程语言，目标是让**签名成
 - **HKT** — 用 generics + traits + 关联类型 + GAT 覆盖，不引入 higher-kinded types。
 - **Async/await 着色** — 并发通过 `Spawn` effect 建模，不设专门的 async 语法。
 - **自定义操作符** — 管道 `|>` 是唯一特殊操作符。
-- **Comptime** — const generics + 细化类型 + 代价模型已足够，不引入编译期求值宏。
+- **Comptime** — const generics + 细化类型 + 预算模型已足够，不引入编译期求值宏。
 - **独立 MIR** — 无 borrow checker，不需要 CFG 级中间表示。
 - **Semver** — 内容寻址 hash 取代语义版本号。
 - **循环依赖** — 模块图必须无环。
 
 ## 已考虑的替代方案 & 理由
 
-| 方向 | 替代方案 | 选择 & 理由 |
-|---|---|---|
-| 版本管理 | Semver | 内容 hash 消除版本兼容猜测；不同 hash 直接共存，钻石依赖不冲突 |
-| 泛型表达力 | HKT | 实际需求由 GAT + 关联类型覆盖；HKT 引入的类型层复杂度与"签名可读"原则冲突 |
-| 中间表示 | 独立 MIR（CFG-based） | 无 borrow checker，hash + 依赖图已覆盖增量缓存，额外 IR 无收益 |
-| 并发模型 | Async/await | effect 系统天然统一同步与异步；着色问题在 Spore 不存在 |
-| Effect handler | 可恢复 continuation | 先实现 one-shot non-resumable handler，降低运行时复杂度 |
-| 循环引用 | 允许并做拓扑延迟 | Elm 证明了禁止循环依赖带来的架构清晰度；编译器可更自由地并行与缓存 |
+| 方向           | 替代方案              | 选择 & 理由                                                               |
+| -------------- | --------------------- | ------------------------------------------------------------------------- |
+| 版本管理       | Semver                | 内容 hash 消除版本兼容猜测；不同 hash 直接共存，钻石依赖不冲突            |
+| 泛型表达力     | HKT                   | 实际需求由 GAT + 关联类型覆盖；HKT 引入的类型层复杂度与"签名可读"原则冲突 |
+| 中间表示       | 独立 MIR（CFG-based） | 无 borrow checker，hash + 依赖图已覆盖增量缓存，额外 IR 无收益            |
+| 并发模型       | Async/await           | effect 系统天然统一同步与异步；着色问题在 Spore 不存在                    |
+| Effect handler | 可恢复 continuation   | 先实现 one-shot non-resumable handler，降低运行时复杂度                   |
+| 循环引用       | 允许并做拓扑延迟      | Elm 证明了禁止循环依赖带来的架构清晰度；编译器可更自由地并行与缓存        |
 
 ## 开放问题
 
-- Cranelift backend 当前只覆盖单模块纯标量程序；`HostValue` / ADT / `Option` / `Result` 的数据布局何时冻结？
-- `foreign fn` 与 effect lowering 需等 Platform host model 泛化后再推进——如何界定 skeleton 阶段边界？
+- Cranelift backend 当前只覆盖单模块纯标量程序；`HostValue` / ADT / `Option` / outcome 的数据布局何时冻结？
+- `@foreign` 导入边界与 effect lowering 需等 Platform host model 泛化后再推进——如何界定 skeleton 阶段边界？
 - 细化类型 L1 层（抽象解释传播）的工程化路径尚未确定。
-- `with_cost_limit` 等运行时代价收敛机制暂未进入表面语法。
+- 运行时资源收敛机制暂未进入表面语法；当前预算只约束源码实现形态。
 
 ## 修订记录