Merge pull request 'docs: add .cards — project philosophy and design rationale' (#154) from docs/project-cards into main

.cards/deterministic-engine-uncertain-agent.md

@@ -0,0 +1,16 @@
+---
+title: "Deterministic Engine, Uncertain Agent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - process-discipline-from-software-engineering
+  - session-isolation-as-cognitive-reset
+---
+
+uwf 的架构将确定性和不确定性严格分层。
+
+Engine 层（moderator 纯查表、CAS 不可变、每步原子化）是刚性的——流程骨架本身不能成为另一个不可靠的环节。LLM 的不确定性被严格约束在 agent session 内部。
+
+这个选择意味着：调度逻辑完全可预测、可调试、可审计。出问题时你知道问题一定在某个 session 的产出里，不在流程逻辑里。

.cards/dissipative-structure-token-for-entropy.md

@@ -0,0 +1,16 @@
+---
+title: "Dissipative Structure — Token for Entropy Reduction"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - process-discipline-from-software-engineering
+  - session-isolation-as-cognitive-reset
+---
+
+uwf 本质上是一种耗散结构：通过消耗能量（token）实现熵减。
+
+一个 AI session 做长了会漂移、会累积错误、会失去焦点。把一件事拆成多个有明确边界的 session，让它们从不同角度相互校验，比一个 session 从头做到尾更可靠。多花的 token 就是耗散的能量，换来的是更低的交付熵——更可预测、更高质量的产出。
+
+这与人类工程实践中引入 review、测试、灰度等流程的逻辑一致：都是在用额外成本换系统可靠性。

.cards/process-discipline-from-software-engineering.md

@@ -0,0 +1,20 @@
+---
+title: "Process Discipline from Software Engineering"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern, decision]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - role-is-not-agent
+  - dissipative-structure-token-for-entropy
+  - deterministic-engine-uncertain-agent
+---
+
+uwf 的发心是将人类软件工程的流程纪律应用到 AI agent 上。
+
+人类早已验证：个体不可靠，但流程可以让不可靠的个体组成可靠的系统。Code review 不是因为不信任程序员，而是**写代码和审代码是两种认知模式**，一个人很难同时做好。测试、灰度、回滚——每一层都是在用额外成本换确定性。
+
+uwf 把这套搬过来：planner 和 reviewer 可以是同一个 agent，但流程迫使它在不同 session 里切换视角，形成自我制衡。用 role 和 role 之间的流转关系，**把做一件事的步骤固定下来**。
+
+PR #148 vs #142 是直接证据——不是换了更强的 agent，是同样的 agent，换了协作结构。

.cards/role-is-not-agent.md

@@ -0,0 +1,16 @@
+---
+title: "Role Is Not Agent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - process-discipline-from-software-engineering
+---
+
+在 uwf 体系里，role ≠ agent。一个 thread 跑的过程中，所有 role 往往由**同一个 agent** 扮演。
+
+Role 对应的是 agent 的 **session**——为了解决一个问题，需要多个 session 从不同角度观察和行动、相互制衡。角色可以在流程中多次重入，重入时**复用**同一个 session（保持角色内记忆连续），隔离发生在角色之间，不是每一步。
+
+这个区分决定了 uwf 的设计不是在做"任务分发给不同 agent"，而是在做**一个 agent 的多视角自我协作**。

.cards/session-isolation-as-cognitive-reset.md

@@ -0,0 +1,17 @@
+---
+title: "Session Isolation as Cognitive Reset"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision, pattern]
+category: "architecture"
+links:
+  - role-is-not-agent
+  - dissipative-structure-token-for-entropy
+  - process-discipline-from-software-engineering
+---
+
+uwf 的核心机制不是"多 agent 协调"，而是**用 session 隔离实现视角切换**。
+
+同一个 agent 以不同 role 进入时，得到的是全新的认知上下文——没有惯性、没有确认偏误。CAS 链传递工作成果，但认知状态是重置的。Role 定义（goal、procedure、output schema）塑造每个 session 的关注点和行为边界。
+
+这解释了为什么 stateless 单步设计这么重要：engine 确保每次角色切换都是一个干净的 session 入口。